@spec aggregate?(String.t()) :: boolean()

True when a select field is an aggregate: count(), col.sum(), alias:col.sum()::cast, alias:col->>key::int.sum()::cast. A bare name() is an aggregate only when name is a known aggregate function; otherwise it is an empty-projection embed. An <operand>.fn() form is always an aggregate.

@spec embed?(String.t()) :: boolean()

True when a select field references an embedding: it has a top-level ( not preceded by a . aggregate marker, i.e. name(...) / alias:name(...) / name!hint(...).

@spec logic_prefix(String.t()) :: {boolean(), :and | :or, String.t()} | nil

Match a logic-group prefix: and(/or(/not.and(/not.or(.

Returns {negate?, :and | :or, "(...)"} when member begins with and(/or(/not.and(/not.or( (whitespace allowed before the () and ends in ); otherwise nil. The returned group keeps its surrounding parens.

@spec parse_embed_parts(String.t()) :: {:ok, String.t(), String.t()} | :error

Split an embed term into its name!hint... head and inner sub-select.

Returns {:ok, head_string, inner_string} where head is the name!hint... text and inner is everything between the first ( and the final ) (kept opaque). Returns :error when the string is not a well-formed embed term.

@spec parse_filter_expr(String.t(), String.t()) :: {:ok, map()} | :error

Parse a column filter — col_raw (which may carry a json path) plus the [not.]op[.modifier].value tail — into a filter node.

Returns {:ok, %{column:, json_path:, op:, modifier:, negate:, value:}} or :error.

@spec parse_json_path(String.t()) ::
  {:ok, {String.t(), [{:arrow | :arrow_text, String.t()}]}} | :error

Parse a json-path column reference (col, col->a->>b, col->0, col->>-3).

Returns {:ok, {base_col, [{:arrow | :arrow_text, key}]}} or :error.

@spec parse_order_term(String.t()) :: {:ok, map()} | {:error, term()}

Parse one order term: a column order <col>[->json][.asc|.desc][.nullsfirst|.nullslast] or a related order <rel>(<col>[->json])[.mods] (ordering by a to-one embedded resource).

Returns {:ok, term} (column or related order map) or {:error, {:order_parse, ...}}.

@spec parse_request(String.t()) :: {:ok, map()} | {:error, term()}

Parse a full request query string into a structured query plan.

Returns {:ok, plan} where plan is a map with keys :select, :filters, :order, :limit, :offset, or {:error, reason}.

select/order items and column filters are returned as data; the executor resolves them against the relation's columns and renders SQL.

@spec parse_scalar_select(String.t()) ::
  {:ok, map()} | {:error, {:select_parse, String.t()}}

Parse a scalar select field [alias:]col[::cast][->json] into a :field node.

Returns {:ok, %{kind: :field, ...}} or {:error, {:select_parse, field}}.

@spec peel_agg_cast(String.t()) :: {String.t() | nil, String.t()}

Peel a trailing )::cast off an aggregate term (the regex ^(.*\))::([A-Za-z0-9_ ]+)$).

Returns {cast, rest} — the trimmed cast and the rest (ending in )) — or {nil, original} when there is no trailing )::cast.

@spec split_agg_call(String.t()) :: {:ok, String.t(), String.t()} | :error

Split the trailing aggregate call off a select field.

Returns {:ok, operand, fun} where operand is everything before the . that introduces the call — "" for the field-less count() form — and fun is the aggregate name. :error when the string does not end in an empty call <fun>().

The operand is kept opaque here because PostgREST parses it as a full field reference (pField plus an optional ::cast), so it may carry a json path and a cast: jsonb_col->>key::integer.sum().

@spec split_key(String.t()) :: [String.t()]

Split a .-delimited query-string key into its segments, treating a quoted field name as atomic ("a.dotted.column" is one segment, tasks.name is two).

@spec split_op_value(String.t()) ::
  {:ok, String.t(), String.t() | nil, String.t()} | :error

Split a filter's op[.modifier].value tail.

Returns {:ok, op, modifier, value} or :error. modifier is nil unless a (any)/(all)/(lang) quantifier is present.

@spec valid_identifier?(String.t()) :: boolean()

True when col is a valid PostgREST unquoted identifier ([A-Za-z_][A-Za-z0-9_ -]*).