turbine-orm 0.34.0 → 0.36.0

package/dist/query/aggregates.d.ts

@@ -0,0 +1,74 @@
+/**
+ * turbine-orm: aggregate / groupBy compilation (extracted from builder.ts)
+ *
+ * buildAggregate + buildGroupBy and their helpers (HAVING clauses, groupBy
+ * ordering, DISTINCT-ON sources, JSON-path aggregate targets). All functions
+ * take a {@link BuilderCtx} first argument; WHERE compilation is reused from
+ * where.ts (via `whereMod`), and the shared orderBy / row-parse primitives
+ * stay class-resident, reached through the ctx. See builder.ts for the thin
+ * delegating methods (buildGroupBy / buildAggregate).
+ */
+import type { DeferredQuery } from './deferred.js';
+import type { AggregateArgs, AggregateResult, GroupByArgs, GroupByOrderBy, HavingClause, HavingFilter } from './types.js';
+import type { BuilderCtx } from './where.js';
+export declare function buildGroupBy<T extends object>(qi: BuilderCtx, args: GroupByArgs<T>): DeferredQuery<Record<string, unknown>[]>;
+/**
+ * Compile a groupBy `orderBy` into an ORDER BY body. Unlike findMany ORDER BY
+ * ({@link buildOrderBy}, which validates keys against the table's physical
+ * columns), groupBy ordering targets the columns the RESULT actually
+ * contains: plain by-fields, JSON group-key aliases, and requested aggregates
+ * (`_count` / `_sum` / `_avg` / `_min` / `_max`). Each key re-emits the exact
+ * SELECT expression that produced it (`byOrderExprs` / `aggOrderExprs`),
+ * mirroring how HAVING re-emits aggregate expressions, so no dialect ever has
+ * to accept a SELECT-alias reference in ORDER BY, and any already-bound
+ * JSON-path placeholder is reused verbatim (ORDER BY is the last clause, so
+ * no `$n` renumbering). An aggregate key that was not requested, or an unknown
+ * by-key, throws {@link ValidationError} E003 listing the valid keys.
+ */
+export declare function buildGroupByOrderBy(qi: BuilderCtx, orderBy: GroupByOrderBy, byOrderExprs: Map<string, string>, aggOrderExprs: Map<string, string>): string;
+/**
+ * Validate a JSON-path target (group key or aggregate target) in groupBy:
+ * the field must resolve to a real json/jsonb column and the path must be a
+ * non-empty array of keys/indexes. Returns the resolved snake_case column.
+ */
+export declare function resolveJsonPathTarget(qi: BuilderCtx, context: string, field: string, path: (string | number)[]): string;
+/**
+ * Build the `distinctOn` row source for groupBy (PostgreSQL only: other
+ * engines throw {@link UnsupportedFeatureError} E017):
+ *
+ * ```sql
+ * (SELECT DISTINCT ON ("c1") * FROM "table"<WHERE> ORDER BY "c1", <orderBy>) AS "table"
+ * ```
+ *
+ * The wrapper is aliased as the table name so every outer expression (group
+ * keys, aggregates, HAVING, ORDER BY) is byte-identical to the plain path.
+ * `distinctOn.orderBy` is required (it decides which row survives) and
+ * supports plain columns, {@link OrderBySpec} nulls, and JSON-path specs;
+ * JSON paths push their text[] param here, after the WHERE params.
+ */
+export declare function buildDistinctOnSource<T extends object>(qi: BuilderCtx, distinctOn: NonNullable<GroupByArgs<T>['distinctOn']>, whereSql: string, params: unknown[]): string;
+/**
+ * Build the SQL fragments for a {@link HavingClause}.
+ *
+ * Each aggregate expression (`COUNT(*)`, `SUM("col")`, etc.) is constructed
+ * from a **schema-validated, quoted** column identifier: `qi.toColumn()`
+ * throws {@link ValidationError} for unknown fields and `qi.q()` quotes via
+ * the dialect, so no unvalidated identifier ever reaches the SQL string. Every
+ * comparison value is pushed onto the shared `params` array and referenced by
+ * a `$N` placeholder via {@link buildHavingNumericClauses} — there is no string
+ * interpolation of user values.
+ *
+ * `jsonAggExprs` (from {@link buildGroupBy}) maps `alias:aggKey` to the
+ * exact aggregate expression a JSON-path aggregate emitted in SELECT
+ * (including its already-bound path placeholder), so HAVING on a JSON-path
+ * aggregate alias reuses the same expression instead of resolving the alias
+ * as a column.
+ */
+export declare function buildHavingClauses<T extends object>(qi: BuilderCtx, having: HavingClause<T>, params: unknown[], jsonAggExprs?: Map<string, string>): string[];
+/**
+ * Convert a single having filter into one or more parameterized SQL
+ * comparisons against the given aggregate expression. A bare number is
+ * shorthand for equality. Unknown operator keys throw {@link ValidationError}.
+ */
+export declare function buildHavingNumericClauses(qi: BuilderCtx, expr: string, filter: HavingFilter, params: unknown[]): string[];
+export declare function buildAggregate<T extends object>(qi: BuilderCtx, args: AggregateArgs<T>): DeferredQuery<AggregateResult<T>>;