turbine-orm 0.49.0 → 0.50.0

package/dist/cjs/query/aggregates.d.ts

@@ -0,0 +1,92 @@
+/**
+ * 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 { TableMetadata } from '../schema.js';
+import type { DeferredQuery } from './deferred.js';
+import type { AggregateArgs, AggregateResult, GroupByArgs, GroupByOrderBy, HavingClause, HavingFilter } from './types.js';
+import type { BuilderCtx } from './where.js';
+/**
+ * Enforce the PII contract on the aggregate surface. A PII-tagged
+ * (`defineSchema` `pii: true`) column is excluded from every default
+ * projection, and a value-returning aggregate is a projection by another name:
+ * `groupBy({ by: ['email'] })` emits one row per distinct plaintext email, and
+ * `_min`/`_max` return a stored cell verbatim. Both therefore REQUIRE the same
+ * `includePii: true` opt-in reads use.
+ *
+ * Deliberately NOT gated: `_count` (a count, never a value), `_sum` / `_avg`
+ * (a computed total across many rows, not a stored cell), and `where` /
+ * `orderBy` / `having` on PII columns (they return no values at all). Untagged
+ * schemas short-circuit on the `pii` lookup, so their SQL is byte-identical.
+ *
+ * Shared with the PowQL aggregate paths (src/powql.ts) so every engine applies
+ * one policy.
+ */
+export declare function assertAggregatePiiOptIn(table: string, meta: TableMetadata | undefined, field: string, column: string, usage: string, includePii: boolean | undefined): void;
+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 | 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>>;

package/dist/cjs/query/aggregates.js

@@ -54,6 +54,7 @@ exports.buildAggregate = buildAggregate;
 const errors_js_1 = require("../errors.js");
 const schema_js_1 = require("../schema.js");
 const filters_js_1 = require("./filters.js");
+const utils_js_1 = require("./utils.js");
 const whereMod = __importStar(require("./where.js"));
 /**
  * Enforce the PII contract on the aggregate surface. A PII-tagged
@@ -275,8 +276,8 @@ function buildGroupBy(qi, args) {
     // no `$n` renumbering. `offset` without a deterministic `orderBy` yields an
     // arbitrary window (same caveat as findMany).
     if (args.limit !== undefined || args.offset !== undefined) {
-        const limitPh = args.limit !== undefined ? qi.paginationRef(args.limit, params) : undefined;
-        const offsetPh = args.offset !== undefined ? qi.paginationRef(args.offset, params) : undefined;
+        const limitPh = args.limit !== undefined ? qi.paginationRef(args.limit, params, 'limit') : undefined;
+        const offsetPh = args.offset !== undefined ? qi.paginationRef(args.offset, params, 'skip/offset') : undefined;
         sql += qi.buildPagination(limitPh, offsetPh, args.orderBy !== undefined);
     }
     return {
@@ -556,7 +557,10 @@ function buildHavingClauses(qi, having, params, jsonAggExprs) {
         for (const [aggKey, filter] of Object.entries(value)) {
             if (filter === undefined)
                 continue;
-            const fn = aggFnByKey[aggKey];
+            // ownLookup, not a bare index: an inherited Object.prototype member
+            // ("constructor", "toString", …) would otherwise resolve to a truthy
+            // builtin and be spliced into the HAVING clause as its source text.
+            const fn = (0, utils_js_1.ownLookup)(aggFnByKey, aggKey);
             if (!fn) {
                 throw new errors_js_1.ValidationError(`[turbine] Unknown aggregate "${aggKey}" in having for field "${key}" on table "${qi.table}". ` +
                     `Supported: ${Object.keys(aggFnByKey).join(', ')}.`);

package/dist/cjs/query/batched-loader.d.ts

@@ -0,0 +1,193 @@
+/**
+ * turbine-orm — Batched relation loader (the `relationLoadStrategy: 'batched'` path)
+ *
+ * ## Why this exists
+ *
+ * Turbine's default `with`-clause strategy resolves nested relations in ONE SQL
+ * statement using correlated `json_agg(json_build_object(...))` subqueries — one
+ * probe per parent row (see `buildRelationSubquery` in builder.ts). That is the
+ * right default: a single round-trip, and when the child FK columns are indexed
+ * each probe is an index seek. But it degrades in two situations:
+ *
+ *   1. **Missing FK index** — a correlated probe per parent row becomes
+ *      N-parents × full-table-scan. A batched-loader ORM pays that missing index
+ *      only ONCE (a single `WHERE fk = ANY($1)` seq-scan), which is why schemas
+ *      migrated from those ORMs often lack the index the json_agg path needs.
+ *   2. **Huge unpaginated result sets** — the JSON wire format
+ *      (`json_build_object` per row, re-serialized inside `json_agg`) is heavy to
+ *      encode/decode compared with flat rows.
+ *
+ * This module implements the alternative, opt-in strategy: run the base query
+ * WITHOUT relation subqueries, collect the parent keys, then issue ONE flat
+ * follow-up query per relation (`SELECT ... FROM child WHERE fk = ANY($1)`),
+ * and stitch the children onto the parents in memory. D relation levels cost D
+ * extra round-trips instead of one, but each is a single indexed lookup over a
+ * key set, and rows come back flat.
+ *
+ * ## Design constraints (see CLAUDE.md)
+ *
+ *   - **Same executor / connection path.** Every follow-up query runs through the
+ *     caller's own executor ({@link RelationLoadContext.exec}) and child query
+ *     interfaces built on the caller's pool. Inside a `$transaction` that pool is
+ *     the pinned-connection `txPool`, so batched loads join the transaction — no
+ *     separate pool checkout per query.
+ *   - **Identical output shape.** The stitched result is byte-for-byte the same
+ *     shape the join strategy produces: relation arrays for hasMany/manyToMany
+ *     (`[]` when empty), single-or-null for hasOne/belongsTo, with the same
+ *     camelCase keys and Date coercion — because the child rows are parsed by the
+ *     very same `parseRow`/`buildFindMany` machinery via a child QueryInterface.
+ *   - **Stitch keys never leak.** To stitch, the follow-up query must select the
+ *     FK/PK it joins on even when the caller's `select`/`omit` excluded it; the
+ *     loader adds those columns for the query and strips them from the returned
+ *     entities afterwards ({@link includeKeysForBatching}).
+ *
+ * PowDB (powql.ts) has its own batched loaders for the same reasons — this is the
+ * clean Postgres/SQL implementation, deliberately NOT shared with PowQL.
+ *
+ * @module
+ */
+import type pg from 'pg';
+import { type RelationDef, type SchemaMetadata, type TableMetadata } from '../schema.js';
+import type { ReselectExecutor } from './builder.js';
+import type { SkipGlobalFilters, WithClause, WithCount } from './types.js';
+/**
+ * A DeferredQuery, minimally typed for what the loader consumes. Kept local to
+ * avoid a value import of builder.ts (which imports this module).
+ */
+interface Deferred {
+    sql: string;
+    params: unknown[];
+    preparedName?: string;
+    transform: (result: pg.QueryResult) => unknown;
+}
+/**
+ * The read surface the loader needs from a child QueryInterface: build (but do
+ * not execute) a flat findMany. The loader runs the built SQL through
+ * {@link RelationLoadContext.exec}, so execution stays on the caller's connection.
+ */
+export interface BatchedChildReader {
+    buildFindMany(args: Record<string, unknown>): Deferred;
+}
+/**
+ * Everything the loader needs from the owning QueryInterface, passed as closures
+ * so this module never imports builder.ts at runtime (it is imported BY it).
+ */
+export interface RelationLoadContext {
+    /** Metadata of the table whose rows are the current `parents`. */
+    parentMeta: TableMetadata;
+    schema: SchemaMetadata;
+    /** Build a child reader for `table`, bound to the caller's pool (tx-safe). */
+    makeChild: (table: string) => BatchedChildReader;
+    /** Run raw SQL through the caller's executor (same timeout/instrumentation path). */
+    exec: ReselectExecutor;
+    /** Quote an identifier via the active dialect. */
+    quote: (name: string) => string;
+    /** Build an `IN`/`ANY` predicate via the active dialect (PG: `expr = ANY($n)`). */
+    buildInClause: (expr: string, paramRef: string, negated: boolean) => string;
+    /** The single bound value for an `IN` list (PG: the array as-is). */
+    inClauseParam: (values: unknown[]) => unknown;
+    /** Placeholder for a 1-indexed parameter position (PG: `$n`). */
+    paramPlaceholder: (index: number) => string;
+    /**
+     * The query's `skipGlobalFilters` opt-out, threaded onto every child
+     * `buildFindMany` so relation row loads honor (or skip) the target table's
+     * global filter exactly as the join strategy would.
+     */
+    skipGlobalFilters?: SkipGlobalFilters;
+    /**
+     * The query's `includePii` opt-in, threaded onto every child `buildFindMany`
+     * so a batched relation load excludes (or includes) PII-tagged columns exactly
+     * as the join strategy does at every nested level. Default `false`.
+     */
+    includePii?: boolean;
+    /**
+     * Render `table`'s global filter against `alias` for a raw follow-up query
+     * (the batched `_count`), numbering its `$n` placeholders AFTER
+     * `precedingParams` already-bound params. Returns `null` when no filter
+     * applies. Provided by the owning QueryInterface so this module needs no
+     * filter machinery of its own.
+     */
+    tableGlobalFilter?: (table: string, alias: string, precedingParams: number) => {
+        clause: string;
+        params: unknown[];
+    } | null;
+}
+/**
+ * The default projection of `meta` expressed in FIELD names: which fields the
+ * default (no `select`/`omit`) projection hides, and which it returns. Today the
+ * only hidden class is PII-tagged columns, and only when `includePii` is off.
+ *
+ * Returns `undefined` for the overwhelmingly common untagged case, so callers
+ * keep the `select: undefined, omit: undefined` fast path and the emitted SQL
+ * stays byte-identical.
+ */
+export declare function defaultProjectionFields(meta: TableMetadata, includePii: boolean | undefined): {
+    hidden: ReadonlySet<string>;
+    visible: string[];
+} | undefined;
+/**
+ * Adjust a `select`/`omit` pair so that `fields` are guaranteed present in the
+ * query result, returning the adjusted projection plus the list of fields that
+ * were added ONLY for stitching and must be stripped from the final entities.
+ *
+ * Used both for the base query (parent keys) and each follow-up query (child
+ * keys) so a caller's `select: { title: true }` on a relation still stitches even
+ * though the FK was not requested — and the FK never appears in the output.
+ */
+export declare function includeKeysForBatching(select: Record<string, boolean> | undefined, omit: Record<string, boolean> | undefined, fields: string[], 
+/**
+ * The default projection for this table when it is NOT `select`/`omit`-driven:
+ * `hidden` are fields the default projection leaves out (today: PII-tagged
+ * columns without `includePii`), `visible` is everything it does return.
+ *
+ * Without this, a correlation key that is itself PII-tagged is absent from
+ * every row, the loader sees no keys, and it silently hands back empty
+ * relation arrays. Passing it turns that case into an explicit select that
+ * re-adds only the key, which is then stripped like any other stitch-only
+ * field, so no PII value ever reaches the caller.
+ */
+defaultProjection?: {
+    hidden: ReadonlySet<string>;
+    visible: string[];
+}): {
+    select?: Record<string, boolean>;
+    omit?: Record<string, boolean>;
+    strip: string[];
+};
+/** Delete stitch-only key fields from each row (no-op when `fields` is empty). */
+export declare function stripFields(rows: Record<string, unknown>[], fields: string[]): void;
+/**
+ * The set of parent FIELD names a batched load of `withClause` needs present on
+ * each parent row in order to stitch (the local key of every requested relation).
+ * The caller adds these to the base query and strips the added ones afterwards.
+ */
+export declare function neededParentKeyFields(parentMeta: TableMetadata, withClause: WithClause): string[];
+/**
+ * Resolve the set of to-many relations a `_count` spec selects. `true` counts
+ * every to-many relation (hasMany + manyToMany) of the table; the record form
+ * counts only the enabled names. Shared by the join builder and the batched
+ * loader so both count the exact same relations.
+ *
+ * Errors: E005 ({@link RelationError}) for an unknown relation name, E003
+ * ({@link ValidationError}) when a named relation is to-one.
+ */
+export declare function resolveCountRelations(parentMeta: TableMetadata, countSpec: WithCount): RelationDef[];
+/**
+ * Reject pick-row relation ordering anywhere inside a `with` tree's orderBy —
+ * strategy parity with the join path, which throws this exact E003 at SQL
+ * build time (`pickOrderNestedError` in builder.ts). Without this guard the
+ * loaders would forward `options.orderBy` as the child reader's TOP-LEVEL
+ * findMany orderBy, where the pick shape compiles fine — so the same query
+ * would execute on 'batched' but throw on 'join'. Walks the whole tree up
+ * front so acceptance never depends on which levels have rows — the batched
+ * runners in builder.ts call this BEFORE the base query (a zero-row base
+ * result must still reject, exactly like the join strategy's build-time throw).
+ */
+export declare function rejectNestedPickOrder(withClause: WithClause): void;
+/**
+ * Load every relation in `withClause` for `parents` and attach it onto each row
+ * in place. Mirrors the join strategy's output shape exactly. Recurses for nested
+ * `with` by re-running itself against the freshly-loaded child rows.
+ */
+export declare function loadRelationsBatched(ctx: RelationLoadContext, parents: Record<string, unknown>[], withClause: WithClause, timeout?: number, depth?: number, path?: string[]): Promise<void>;
+export {};