diff --git a/lib/plausible/stats/comparisons.ex b/lib/plausible/stats/comparisons.ex index 05f8eb677..158882eaf 100644 --- a/lib/plausible/stats/comparisons.ex +++ b/lib/plausible/stats/comparisons.ex @@ -9,23 +9,42 @@ defmodule Plausible.Stats.Comparisons do alias Plausible.Stats - @modes ~w(previous_period year_over_year) + @modes ~w(previous_period year_over_year custom) @disallowed_periods ~w(realtime all) @type mode() :: String.t() | nil + @typep option() :: {:from, String.t()} | {:to, String.t()} | {:now, NaiveDateTime.t()} - @spec compare( - Plausible.Site.t(), - Stats.Query.t(), - mode(), - NaiveDateTime.t() | nil - ) :: {:ok, Stats.Query.t()} | {:error, :not_supported} - def compare( - %Plausible.Site{} = site, - %Stats.Query{} = source_query, - mode, - now \\ nil - ) do + @spec compare(Plausible.Site.t(), Stats.Query.t(), mode(), [option()]) :: + {:ok, Stats.Query.t()} | {:error, :not_supported} + @doc """ + Generates a comparison query based on the source query and comparison mode. + + The mode parameter specifies the type of comparison and can be one of the + following: + + * `"previous_period"` - shifts back the query by the same number of days the + source query has. + + * `"year_over_year"` - shifts back the query by 1 year. + + * `"custom"` - compares the query using a custom start date defined in + `opts`. The end date of the comparison query is inferred using the same + numbers of days the original query had. For example, if the graph displays + data for seven days, and the user selects a custom comparison starting on + May 7th, the end date would be automatically set to May 13th. + + The comparison query returned by the function has its end date restricted to + the current day. This can be overriden by the `now` option, described below. + + ## Options + + * `:now` - a `NaiveDateTime` struct with the current date and time. This is + optional and used for testing purposes. + + * `:from` - a ISO-8601 date string used when mode is `"custom"`. + + """ def compare(%Plausible.Site{} = site, %Stats.Query{} = source_query, mode, opts \\ []) do if valid_mode?(source_query, mode) do opts = Keyword.put_new(opts, :now, Timex.now(site.timezone)) @@ -58,6 +77,15 @@ defmodule Plausible.Stats.Comparisons do %Stats.Query{source_query | date_range: range} end + defp do_compare(source_query, "custom", opts) do + from = opts |> Keyword.fetch!(:from) |> Date.from_iso8601!() + + diff_in_days = Date.diff(source_query.date_range.last, source_query.date_range.first) + to = from |> Date.add(diff_in_days) |> earliest(opts[:now]) + + %Stats.Query{source_query | date_range: Date.range(from, to)} + end + defp earliest(a, b) do if Date.compare(a, b) in [:eq, :lt], do: a, else: b end diff --git a/lib/plausible_web/controllers/api/stats_controller.ex b/lib/plausible_web/controllers/api/stats_controller.ex index 26fefc22e..9df33a165 100644 --- a/lib/plausible_web/controllers/api/stats_controller.ex +++ b/lib/plausible_web/controllers/api/stats_controller.ex @@ -115,7 +115,9 @@ defmodule PlausibleWeb.Api.StatsController do full_intervals = build_full_intervals(query, labels) comparison_result = - case Comparisons.compare(site, query, params["comparison"]) do + case Comparisons.compare(site, query, params["comparison"], + from: params["comparison_from"] + ) do {:ok, comparison_query} -> Stats.timeseries(site, comparison_query, [selected_metric]) {:error, :not_supported} -> nil end @@ -175,9 +177,11 @@ defmodule PlausibleWeb.Api.StatsController do with :ok <- validate_params(params) do comparison_mode = params["comparison"] || "previous_period" + comparison_opts = [from: params["comparison_from"]] + query = Query.from(site, params) |> Filters.add_prefix() - {top_stats, sample_percent} = fetch_top_stats(site, query, comparison_mode) + {top_stats, sample_percent} = fetch_top_stats(site, query, comparison_mode, comparison_opts) json(conn, %{ top_stats: top_stats, @@ -245,7 +249,8 @@ defmodule PlausibleWeb.Api.StatsController do defp fetch_top_stats( site, %Query{period: "realtime", filters: %{"event:goal" => _goal}} = query, - _comparison_mode + _comparison_mode, + _comparison_opts ) do query_30m = %Query{query | period: "30m"} @@ -272,7 +277,12 @@ defmodule PlausibleWeb.Api.StatsController do {stats, 100} end - defp fetch_top_stats(site, %Query{period: "realtime"} = query, _comparison_mode) do + defp fetch_top_stats( + site, + %Query{period: "realtime"} = query, + _comparison_mode, + _comparison_opts + ) do query_30m = %Query{query | period: "30m"} %{ @@ -298,11 +308,16 @@ defmodule PlausibleWeb.Api.StatsController do {stats, 100} end - defp fetch_top_stats(site, %Query{filters: %{"event:goal" => _goal}} = query, comparison_mode) do + defp fetch_top_stats( + site, + %Query{filters: %{"event:goal" => _goal}} = query, + comparison_mode, + comparison_opts + ) do total_q = Query.remove_event_filters(query, [:goal, :props]) {prev_converted_visitors, prev_completions} = - case Stats.Comparisons.compare(site, query, comparison_mode) do + case Stats.Comparisons.compare(site, query, comparison_mode, comparison_opts) do {:ok, prev_query} -> %{visitors: %{value: prev_converted_visitors}, events: %{value: prev_completions}} = Stats.aggregate(site, prev_query, [:visitors, :events]) @@ -362,7 +377,7 @@ defmodule PlausibleWeb.Api.StatsController do {stats, 100} end - defp fetch_top_stats(site, query, comparison_mode) do + defp fetch_top_stats(site, query, comparison_mode, comparison_opts) do metrics = if query.filters["event:page"] do [ @@ -389,7 +404,7 @@ defmodule PlausibleWeb.Api.StatsController do current_results = Stats.aggregate(site, query, metrics) prev_results = - case Stats.Comparisons.compare(site, query, comparison_mode) do + case Stats.Comparisons.compare(site, query, comparison_mode, comparison_opts) do {:ok, prev_results_query} -> Stats.aggregate(site, prev_results_query, metrics) {:error, :not_supported} -> nil end diff --git a/test/plausible/stats/comparisons_test.exs b/test/plausible/stats/comparisons_test.exs index 3074937dd..858225a0e 100644 --- a/test/plausible/stats/comparisons_test.exs +++ b/test/plausible/stats/comparisons_test.exs @@ -24,6 +24,17 @@ defmodule Plausible.Stats.ComparisonsTest do assert comparison.date_range.first == ~D[2023-02-28] assert comparison.date_range.last == ~D[2023-02-28] end + + test "limits the comparison query to current day when mode is custom" do + site = build(:site) + query = Query.from(site, %{"period" => "month", "date" => "2023-03-25"}) + now = ~N[2023-03-25 14:00:00] + + {:ok, comparison} = Comparisons.compare(site, query, "custom", from: "2023-03-23", now: now) + + assert comparison.date_range.first == ~D[2023-03-23] + assert comparison.date_range.last == ~D[2023-03-25] + end end describe "with period set to previous month" do @@ -59,6 +70,16 @@ defmodule Plausible.Stats.ComparisonsTest do assert comparison.date_range.first == ~D[2019-02-01] assert comparison.date_range.last == ~D[2019-03-01] end + + test "infers the end date from source query length when mode is custom" do + site = build(:site) + query = Query.from(site, %{"period" => "month", "date" => "2023-03-01"}) + + {:ok, comparison} = Comparisons.compare(site, query, "custom", from: "2023-04-02") + + assert comparison.date_range.first == ~D[2023-04-02] + assert comparison.date_range.last == ~D[2023-05-01] + end end describe "with period set to year to date" do @@ -105,6 +126,16 @@ defmodule Plausible.Stats.ComparisonsTest do assert comparison.date_range.first == ~D[2021-01-01] assert comparison.date_range.last == ~D[2021-12-31] end + + test "infers the end date from source query length when mode is custom" do + site = build(:site) + query = Query.from(site, %{"period" => "year", "date" => "2022-03-02"}) + + {:ok, comparison} = Comparisons.compare(site, query, "custom", from: "2019-01-01") + + assert comparison.date_range.first == ~D[2019-01-01] + assert comparison.date_range.last == ~D[2019-12-30] + end end describe "with period set to custom" do