feat: support aggregation function helpers (#22)

Author: zoedsoupe

lib/supabase/postgrest/query_builder.ex

@@ -182,4 +182,39 @@ defmodule Supabase.PostgREST.QueryBuilder do
     |> Request.with_headers(%{"prefer" => prefer})
     |> Request.with_body(data)
   end
+
+  # aggregation helpers
+
+  defguardp is_column(c) when is_binary(c) or is_atom(c)
+
+  @aggregators [:sum, :avg, :min, :max, :count]
+
+  for agg <- @aggregators do
+    @doc """
+    Hleper function to apply aggregation of #{agg} function to a specified
+    column name. This should be used on `select/3`.
+
+    ## Parameters
+    - `column`: The `Supabase.Fetcher.Request` to use.
+    - `opts.as`: If specifying more than one aggregate function for the same column, you may need to rename it, so you can pass an optional `:as` value for it.
+
+    ## Examples
+        iex> alias Supabase.PostgREST, as: Q
+        iex> Q.select(builder, [Q.avg("amount")])
+
+        iex> alias Supabase.PostgREST, as: Q
+        iex> Q.select(builder, [Q.avg("amount", as: "avg_amount"), Q.sum("amount", as: "total_amount")])
+
+    ## See also
+    - PostgREST official docs about aggregation functions: https://docs.postgrest.org/en/stable/references/api/aggregate_functions.html
+    """
+    @impl true
+    def unquote(agg)(column, opts \\ []) when is_column(column) do
+      if as = Keyword.get(opts, :as) do
+        "#{as}:#{column}.#{to_string(unquote(agg))}()"
+      else
+        "#{column}.#{to_string(unquote(agg))}()"
+      end
+    end
+  end
 end

lib/supabase/postgrest/query_builder/behaviour.ex

@@ -3,6 +3,8 @@ defmodule Supabase.PostgREST.QueryBuilder.Behaviour do
 
   alias Supabase.Fetcher.Request
 
+  @type column :: String.t() | atom
+  @type agg_opt :: {:as, column}
   @type options :: [count: :exact, returning: boolean | :representation]
   @type insert_options :: [count: :exact, returning: boolean | :representation, on_conflict: any]
 
@@ -16,4 +18,11 @@ defmodule Supabase.PostgREST.QueryBuilder.Behaviour do
   @callback delete(Request.t(), options) :: Request.t()
   @callback update(Request.t(), map) :: Request.t()
   @callback update(Request.t(), map, options) :: Request.t()
+
+  # aggregate functions helpers
+  @callback sum(column, list(agg_opt)) :: String.t()
+  @callback max(column, list(agg_opt)) :: String.t()
+  @callback min(column, list(agg_opt)) :: String.t()
+  @callback avg(column, list(agg_opt)) :: String.t()
+  @callback count(column, list(agg_opt)) :: String.t()
 end

test/supabase/postgrest/query_builder_test.exs

@@ -260,4 +260,27 @@ defmodule Supabase.PostgREST.QueryBuilderTest do
       assert is_list(body)
     end
   end
+
+  describe "select with aggregations" do
+    test "it should support single column with aggregation", %{request: req} do
+      result = QueryBuilder.select(req, [QueryBuilder.sum("amount")])
+      assert {"select", "amount.sum()"} = List.keyfind(result.query, "select", 0)
+    end
+
+    test "it should support multiple different column with aggregation", %{request: req} do
+      result = QueryBuilder.select(req, [QueryBuilder.sum("amount"), QueryBuilder.avg("sales")])
+      assert {"select", "amount.sum(),sales.avg()"} = List.keyfind(result.query, "select", 0)
+    end
+
+    test "it should support multiple column with aggregation", %{request: req} do
+      result =
+        QueryBuilder.select(req, [
+          QueryBuilder.sum("amount", as: "total_amount"),
+          QueryBuilder.avg("amount", as: "avg_amount")
+        ])
+
+      assert {"select", "total_amount:amount.sum(),avg_amount:amount.avg()"} =
+               List.keyfind(result.query, "select", 0)
+    end
+  end
 end