turbine-orm 0.49.0 → 0.50.0

package/dist/query/deferred.d.ts

@@ -155,6 +155,45 @@ export interface QueryInterfaceOptions {
      * byte-identical to before. SQL engines only (PowDB keeps its own defaults).
      */
     stableRelationOrder?: boolean;
+    /**
+     * When `true`, a `findMany` that paginates (`limit` / `take` / `offset`) but
+     * declares no `orderBy` is ordered by the table's primary key ascending
+     * (every column of a composite PK, in declaration order), making its pages
+     * deterministic. An explicit `orderBy` always wins, PK-less tables are left
+     * alone, and `distinct` / `cursor` shapes are skipped.
+     *
+     * Default `false` in core: an unordered `LIMIT` is non-deterministic, but
+     * adding an `ORDER BY` to SQL that existing applications already emit changes
+     * both the rows a page returns and the plan the engine picks, so the fix is
+     * opt-in until a major. `turbine-orm/prisma-compat` defaults it ON, since
+     * matching Prisma's semantics is that layer's contract. When off, the emitted
+     * SQL is byte-identical to before.
+     */
+    implicitPkOrdering?: boolean;
+    /**
+     * Parent-row ceiling for the `relationLoadStrategy: 'auto'` to-one rule: a
+     * to-one relation stays in the single-statement join when the query's `limit`
+     * bounds the parent set at or under this many rows, and loads batched when the
+     * query is unbounded or bounded above it (a correlated to-one subquery is
+     * re-evaluated per parent row regardless of indexing). Defaults to
+     * `AUTO_TO_ONE_JOIN_MAX_ROWS` (1000); `0` sends every unbounded-or-limited
+     * to-one relation batched. Ignored under an explicit `'join'` / `'batched'`.
+     */
+    autoToOneJoinMaxRows?: number;
+    /**
+     * Round-trip time to the database, in milliseconds, used to DERIVE the
+     * `relationLoadStrategy: 'auto'` to-one threshold instead of guessing a row
+     * count. Prefer this over `autoToOneJoinMaxRows`: the break-even between the
+     * single-statement join and the batched follow-up is
+     * `roundTripMs / AUTO_JOIN_PENALTY_MS_PER_ROW`, and measurement shows the
+     * per-row penalty is a constant of the plan while the break-even moves ~17x
+     * between a loopback link and a 2.7ms one. Set it to what `ping` says (a
+     * Unix socket is ~0.05, same-region managed Postgres ~0.5-2, cross-region
+     * ~30-60). Defaults to `AUTO_ASSUMED_ROUND_TRIP_MS` (0.7ms, same-region),
+     * which reproduces the historical 1000-row threshold exactly. Overridden by
+     * an explicit `autoToOneJoinMaxRows`; only consulted under `'auto'`.
+     */
+    autoRoundTripMs?: number;
     /**
      * How nested-relation subqueries encode each row's JSON: `'object'` (default,
      * `json_build_object`) or `'positional'` (`json_build_array`, key-less — see

package/dist/query/index.d.ts

@@ -11,4 +11,4 @@ export { postgresDialect } from '../dialect.js';
 export type { SqlCacheEntry } from './utils.js';
 export { buildCorrelation, escapeLike, escSingleQuote, fnv1a64Hex, LRUCache, OPERATOR_KEYS, quoteIdent, sqlToPreparedName, } from './utils.js';
 export type { DeferredQuery, MiddlewareFn, QueryEvent, QueryEventListener, QueryInterfaceOptions, ReselectExecutor, } from './builder.js';
-export { QueryInterface } from './builder.js';
+export { AUTO_ASSUMED_ROUND_TRIP_MS, AUTO_JOIN_PENALTY_MS_PER_ROW, AUTO_TO_ONE_JOIN_MAX_ROWS, AUTO_TO_ONE_JOIN_ROWS_MAX, AUTO_TO_ONE_JOIN_ROWS_MIN, QueryInterface, } from './builder.js';

package/dist/query/index.js

@@ -7,4 +7,4 @@
  */
 export { postgresDialect } from '../dialect.js';
 export { buildCorrelation, escapeLike, escSingleQuote, fnv1a64Hex, LRUCache, OPERATOR_KEYS, quoteIdent, sqlToPreparedName, } from './utils.js';
-export { QueryInterface } from './builder.js';
+export { AUTO_ASSUMED_ROUND_TRIP_MS, AUTO_JOIN_PENALTY_MS_PER_ROW, AUTO_TO_ONE_JOIN_MAX_ROWS, AUTO_TO_ONE_JOIN_ROWS_MAX, AUTO_TO_ONE_JOIN_ROWS_MIN, QueryInterface, } from './builder.js';

package/dist/query/relations.d.ts

@@ -49,7 +49,7 @@ export declare function withFingerprint(qi: BuilderCtx, withClause: WithClause |
  * Collect params from a `with` clause tree. Mirrors buildSelectWithRelations +
  * buildRelationSubquery param-push order.
  */
-export declare function collectWithParams(qi: BuilderCtx, withClause: WithClause, params: unknown[], table?: string): void;
+export declare function collectWithParams(qi: BuilderCtx, withClause: WithClause, params: unknown[], table?: string, flattenPlan?: FlattenPlan | null): void;
 /**
  * Collect params from a single relation subquery. Mirrors buildRelationSubquery.
  */
@@ -229,8 +229,19 @@ export declare function collectManyToManyTargetGlobalFilter(qi: BuilderCtx, relD
  */
 export declare function collectRelationCountParams(qi: BuilderCtx, relDef: RelationDef, params: unknown[]): void;
 export declare function getCamelDateFields(qi: BuilderCtx, table: string, meta: TableMetadata): Set<string>;
-/** Parse a row that may contain JSON nested relation columns */
-export declare function parseNestedRow(qi: BuilderCtx, row: Record<string, unknown>, table: string): Record<string, unknown>;
+/**
+ * Parse a row that may contain JSON nested relation columns.
+ *
+ * `fromJson` says where THIS row's own scalar columns came from. A root row
+ * (join, batched, flatten) is read straight off the driver, so `false`; a row
+ * decoded out of a `json_agg`/`json_build_object` column is `true` and gets
+ * its divergent scalars decoded back to the driver's representation first (see
+ * the JSON-wire section above). Recursion into a relation column is always
+ * `true`, which is exactly right on every strategy: `batched` and `flatten`
+ * hand this function driver rows, but any relation still nested INSIDE one of
+ * those rows arrived as a correlated JSON subquery.
+ */
+export declare function parseNestedRow(qi: BuilderCtx, row: Record<string, unknown>, table: string, fromJson?: boolean): Record<string, unknown>;
 /**
  * Resolve the emitted column list for a relation, honoring `select` / `omit`.
  * Shared by {@link buildRelationSubquery} (json order) and
@@ -262,7 +273,7 @@ export declare function buildRelationShape(qi: BuilderCtx, relDef: RelationDef,
  * positional arrays into the object form first (shapes built once, not per
  * row), then delegates to parseNestedRow for date/snake-camel coercion.
  */
-export declare function makeNestedParser(qi: BuilderCtx, withClause: WithClause, includePii?: boolean): (row: Record<string, unknown>) => Record<string, unknown>;
+export declare function makeNestedParser(qi: BuilderCtx, withClause: WithClause, includePii?: boolean, flattenPlan?: FlattenPlan | null): (row: Record<string, unknown>) => Record<string, unknown>;
 /**
  * Return a shallow copy of a top-level row with each relation column decoded
  * from its positional array(s) into the object representation. Only relation
@@ -279,6 +290,160 @@ export declare function decodePositionalRelations(qi: BuilderCtx, row: Record<st
 export declare function decodePositionalValue(qi: BuilderCtx, raw: unknown, shape: RelationShape): unknown;
 /** Map one positional array back to a keyed object using the shape's key order. */
 export declare function decodePositionalObject(qi: BuilderCtx, arr: unknown, shape: RelationShape): unknown;
+/** One relation `'flatten'` declined, with the reason, for the dev warning. */
+export interface FlattenReject {
+    /** Dotted path from the root table's `with`, e.g. `order.customer`. */
+    relation: string;
+    reason: string;
+}
+/**
+ * One entry in a flattened relation's nested `with`, in
+ * `sortedEntries(spec.with)` order. `'flat'` is another LEFT JOIN; `'json'` is
+ * a correlated subquery projected as a single JSON column, exactly as the
+ * default strategy would have emitted it (with the join alias as its parent
+ * reference). Ordering is preserved so the assembled object's key order matches
+ * the join strategy's byte for byte.
+ */
+export interface FlattenSlot {
+    relName: string;
+    kind: 'flat' | 'json';
+}
+/** A single to-one relation compiled as a LEFT JOIN plus a prefixed projection. */
+export interface FlattenNode {
+    relName: string;
+    relDef: RelationDef;
+    spec: true | WithOptions;
+    targetTable: string;
+    targetMeta: TableMetadata;
+    /** Output-name prefix, and the derived-table alias for a top-level node (`f0`). */
+    alias: string;
+    /** Alias of the real target table inside the derived table (`f0s`). */
+    srcAlias: string;
+    /** Target-side correlation columns (provably unique — see {@link provableUniqueTargetKey}). */
+    keyColumns: string[];
+    /**
+     * Match discriminator. A top-level node projects the constant `1` (its
+     * derived-table row exists only when the target matched, and the outer LEFT
+     * JOIN null-extends it otherwise); a nested node projects the predicate
+     * `(src.key IS NOT NULL)`. Either way the discriminator carries no cell
+     * VALUE, so a PII-tagged key column never leaves the database merely because
+     * a discriminator was needed: no PII column enters the wire, the projection
+     * or the assembled object unless the caller selected it or passed
+     * `includePii`. Without it, "the join matched nothing" would be
+     * indistinguishable from "the row exists and every projected column is NULL".
+     */
+    discAlias: string;
+    /** `[snake_case column, output alias]` for every projected column. */
+    cols: [column: string, sqlAlias: string][];
+    /** Nested `with` entries in emission order. */
+    slots: FlattenSlot[];
+    /** Nested flattened relations, keyed by relation name (the `'flat'` slots). */
+    children: Record<string, FlattenNode>;
+    /** Output alias of each `'json'` slot's correlated subquery column. */
+    jsonAliases: Record<string, string>;
+    /**
+     * Top-level nodes only: the correlation columns re-exposed by the derived
+     * table (`f0__$c0`, ...) so the OUTER join condition can reference them
+     * without the real column names entering the outer scope. Never surfaced to
+     * the caller.
+     */
+    corrAliases: string[];
+    /** Nesting depth, matching {@link buildRelationSubquery}'s depth accounting. */
+    depth: number;
+    /** Breadcrumb trail for {@link CircularRelationError} parity. */
+    path: string[];
+}
+/**
+ * The compiled `'flatten'` plan for one `with` clause: which top-level
+ * relations become LEFT JOINs, and a signature that keys the SQL template
+ * cache. Relations absent from `nodes` compile exactly as they do today.
+ */
+export interface FlattenPlan {
+    nodes: Record<string, FlattenNode>;
+    /** Every SELECT-list alias the plan introduces (flat rows carry them all). */
+    aliases: string[];
+    /** Structural signature for the `fl=` SQL-cache-key segment. */
+    signature: string;
+}
+/**
+ * The target-side correlation columns of a to-one relation, but ONLY when the
+ * schema PROVES they are unique on the target table. This is the row-
+ * multiplication guard: a LEFT JOIN over a non-unique key silently duplicates
+ * parent rows, which would change results rather than just the plan.
+ *
+ * Proof sources, all exact set matches (a unique index on `(a, b)` does NOT
+ * make `a` unique):
+ *   - the target's primary key,
+ *   - a declared unique constraint (`uniqueColumns`),
+ *   - a full, non-expression UNIQUE index. Partial unique indexes are refused
+ *     (they only constrain the rows matching their predicate) and PowDB
+ *     doc-field expression indexes are refused (they index a JSON path, not the
+ *     raw column).
+ *
+ * Returns `null` for to-many / manyToMany relations and for anything it cannot
+ * prove, which routes the relation back to the correlated subquery.
+ *
+ * NULLs need no special handling: a unique constraint permits repeated NULLs,
+ * but `target.key = parent.fk` never matches a NULL key, so a null-keyed target
+ * row can never join.
+ */
+export declare function provableUniqueTargetKey(relDef: RelationDef, targetMeta: TableMetadata): string[] | null;
+/**
+ * Compile the `'flatten'` plan for a top-level `with` clause, or return `null`
+ * when nothing in it is eligible (in which case the caller emits exactly the SQL
+ * it emits today, down to the cache key).
+ *
+ * The plan is a pure function of the schema, the `with` clause shape and
+ * `includePii` — never of any bound value — so the build path, the cache-hit
+ * param-collect path and the row assembler can each recompute it and agree.
+ */
+export declare function planFlattenWith(qi: BuilderCtx, table: string, withClause: WithClause, includePii?: boolean): FlattenPlan | null;
+/**
+ * Emit one TOP-LEVEL flattened relation: a derived table holding its whole
+ * to-one subtree, joined to the parent on the re-exposed correlation columns,
+ * plus the pass-through projection of every name that subtree contributes.
+ *
+ * ```sql
+ *  LEFT JOIN (
+ *    SELECT 1 AS "f0__$k", f0s."id" AS "f0__$c0",
+ *           f0s."id" AS "f0__id", f0s."name" AS "f0__name",
+ *           (f1s."id" IS NOT NULL) AS "f1__$k", f1s."code" AS "f1__code"
+ *    FROM "orgs" f0s
+ *    LEFT JOIN "regions" f1s ON f1s."id" = f0s."region_id"
+ *    WHERE f0s."deleted" = $1
+ *  ) f0 ON f0."f0__$c0" = "users"."org_id"
+ * ```
+ *
+ * See the derived-table note above for why the join cannot expose the target's
+ * real column names.
+ */
+export declare function emitFlattenNode(qi: BuilderCtx, node: FlattenNode, parentRef: string, params: unknown[], joinSink: string[], selectSink: string[], aliasCounter: {
+    n: number;
+}, includePii?: boolean): void;
+/** Param-collect mirror of {@link emitFlattenNode}. */
+export declare function collectFlattenNodeParams(qi: BuilderCtx, node: FlattenNode, params: unknown[]): void;
+/**
+ * Rebuild one flattened relation's object from a flat row.
+ *
+ * Returns `null` when the discriminator is NULL (the LEFT JOIN matched
+ * nothing), which is the ONLY signal that distinguishes "no related row" from
+ * "a related row whose every projected column is NULL".
+ *
+ * The sub-row is keyed by the target's raw snake_case column names and handed
+ * to {@link parseNestedRow}, so the flattened object goes through the very same
+ * camelCase mapping, Date coercion and nested-JSON parsing the join strategy's
+ * `json_build_object` output does. Nested flattened relations are assigned
+ * after the parse, over placeholder keys inserted in slot order, so the
+ * assembled object's key order matches the join strategy's exactly.
+ */
+export declare function assembleFlattenNode(qi: BuilderCtx, row: Record<string, unknown>, node: FlattenNode): Record<string, unknown> | null;
+/**
+ * Row parser for a `'flatten'` plan: strip the prefixed join columns out of the
+ * flat row (inserting a placeholder at the position each relation's block
+ * started, so key order is preserved), parse the remainder exactly as the join
+ * strategy does, then assemble each flattened relation.
+ */
+export declare function makeFlattenParser(qi: BuilderCtx, plan: FlattenPlan): (row: Record<string, unknown>) => Record<string, unknown>;
 /**
  * Build a SELECT clause that includes both base columns and nested relation subqueries.
  *
@@ -320,7 +485,10 @@ export declare function decodePositionalObject(qi: BuilderCtx, arr: unknown, sha
  * @returns A complete SELECT clause string (without the `SELECT` keyword) containing
  *          base columns and relation subqueries.
  */
-export declare function buildSelectWithRelations(qi: BuilderCtx, table: string, withClause: WithClause, params: unknown[], columnsList?: string[] | null, depth?: number, path?: string[], includePii?: boolean): string;
+export declare function buildSelectWithRelations(qi: BuilderCtx, table: string, withClause: WithClause, params: unknown[], columnsList?: string[] | null, depth?: number, path?: string[], includePii?: boolean, flatten?: {
+    plan: FlattenPlan;
+    joinSink: string[];
+}): string;
 /**
  * Generate a correlated subquery that returns JSON for a single relation.
  *