turbine-orm 0.49.0 → 0.50.0

package/dist/query/builder.d.ts

@@ -13,6 +13,71 @@
 import type pg from 'pg';
 import type { SchemaMetadata } from '../schema.js';
 import type { AggregateArgs, AggregateResult, CountArgs, CreateArgs, CreateManyArgs, DeleteArgs, DeleteManyArgs, FindManyArgs, FindManyStreamArgs, FindUniqueArgs, GroupByArgs, GroupByResult, QueryResult, TypedWithClause, UpdateArgs, UpdateManyArgs, UpsertArgs, WithClause } from './types.js';
+/**
+ * Marginal cost of keeping a to-one relation on the JOIN plan, per parent row.
+ *
+ * A to-one relation compiled into the join plan is a CORRELATED subquery: the
+ * engine re-evaluates it once per parent row, so the join plan costs roughly
+ * `AUTO_JOIN_PENALTY_MS_PER_ROW * parentRows` more CPU than one flat follow-up
+ * query, no matter how well indexed the correlation column is. The batched plan
+ * pays that back as a second statement, i.e. one extra round trip.
+ *
+ * Break-even is therefore, to a first approximation:
+ *
+ *     parentRows = roundTripMs / AUTO_JOIN_PENALTY_MS_PER_ROW
+ *
+ * Measured (PostgreSQL 17, hasOne over a UNIQUE FK, 10K-row parent table,
+ * median of 15 reps per point) at two very different link speeds:
+ *
+ *   link                RTT      penalty/row   break-even   observed crossover
+ *   ─────────────────── ──────── ───────────── ──────────── ──────────────────
+ *   loopback TCP        0.118ms  0.000711ms    ~166-236     between 200 and 400
+ *   +1ms/direction      2.683ms  0.000717ms    ~3744-3993   between 3000 and 5000
+ *
+ * The two things that matters most in that table: the per-row penalty is
+ * essentially IDENTICAL across the two links (it is a property of the plan, not
+ * the wire), while the break-even moved by 17x. So the break-even is a function
+ * of the deployment's round-trip time and NOTHING ELSE that is knowable at plan
+ * time. That is why this is expressed as a per-row cost and a round-trip time
+ * rather than as a hard-coded row count: a row count tuned on a Unix socket is
+ * off by ~20x for a cross-region deployment, and vice versa. Concretely, the
+ * previously shipped flat `1000` was simultaneously too HIGH on loopback
+ * (up to 1.44x slower than the better plan just under the cliff) and too LOW
+ * over a 2.7ms link (1.26x slower just above it).
+ */
+export declare const AUTO_JOIN_PENALTY_MS_PER_ROW = 0.0007;
+/**
+ * Round-trip time assumed before this process has observed a real one, chosen
+ * as a typical same-region managed-Postgres latency (app and database in one
+ * region over TCP). It is stated as a LATENCY rather than a row count so the
+ * assumption is visible and re-derivable: at
+ * {@link AUTO_JOIN_PENALTY_MS_PER_ROW} it yields exactly the 1000-row default
+ * this heuristic has always shipped, so an unmeasured process behaves exactly
+ * as before.
+ */
+export declare const AUTO_ASSUMED_ROUND_TRIP_MS = 0.7;
+/**
+ * Default parent-row ceiling under which `'auto'` keeps a to-one relation on
+ * the single-statement join plan: {@link AUTO_ASSUMED_ROUND_TRIP_MS} divided by
+ * {@link AUTO_JOIN_PENALTY_MS_PER_ROW}. Used until the process has measured its
+ * own round-trip time, and whenever measurement is unavailable.
+ */
+export declare const AUTO_TO_ONE_JOIN_MAX_ROWS: number;
+/**
+ * Clamps on the MEASURED threshold (an explicit `autoToOneJoinMaxRows` is an
+ * instruction, not an estimate, and bypasses both).
+ *
+ * The lower clamp matters: on a very fast link the formula can drop the
+ * threshold to a few dozen rows, and the sweep shows the join plan winning by
+ * up to 1.83x on a handful of parent rows, where the second statement's fixed
+ * cost dwarfs everything. Holding the floor at 100 rows keeps those small
+ * queries on the join plan; the cost of doing so, in the band where batched has
+ * just started to win, is under 1.2x. The upper clamp is a sanity bound for a
+ * pathological latency reading (a 70ms measurement would otherwise ask for
+ * 100K rows).
+ */
+export declare const AUTO_TO_ONE_JOIN_ROWS_MIN = 100;
+export declare const AUTO_TO_ONE_JOIN_ROWS_MAX = 100000;
 export type { DeferredQuery, MiddlewareFn, QueryEvent, QueryEventListener, QueryInterfaceOptions, ReselectExecutor, } from './deferred.js';
 import type { DeferredQuery, MiddlewareFn, QueryInterfaceOptions } from './deferred.js';
 export declare class QueryInterface<T extends object, R extends object = {}> {
@@ -57,6 +122,23 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
     private readonly relationLoadStrategy;
     /** Client-level default for {@link applyStableRelationOrder} (off unless configured). */
     private readonly stableRelationOrder;
+    /**
+     * Client-level opt-in: apply an implicit primary-key ascending `ORDER BY` to a
+     * `findMany` that paginates (`limit`/`take`/`offset`) but declares no
+     * `orderBy`. OFF by default in core, see {@link applyImplicitPkOrdering}.
+     */
+    private readonly implicitPkOrdering;
+    /**
+     * Explicitly configured parent-row ceiling for the `'auto'` to-one rule, or
+     * `undefined` to derive it from the observed round-trip time. See
+     * {@link autoToOneThreshold}.
+     */
+    private readonly autoToOneJoinMaxRowsOption;
+    /**
+     * Deployment round-trip time in milliseconds, from which the to-one threshold
+     * is derived. See {@link autoToOneThreshold}.
+     */
+    private readonly autoRoundTripMs;
     /** Nested-relation JSON encoding: 'object' (default) or 'positional'. */
     private readonly jsonEncoding;
     /**
@@ -169,11 +251,23 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      * ROWS ONLY`. No params are pushed, so the collect path is unaffected.
      */
     private limitOneClause;
+    /**
+     * Coerce a LIMIT/OFFSET argument and validate it as a non-negative safe
+     * integer. Numeric strings (`'5'`) coerce; everything else (`NaN`, a
+     * non-numeric string, a negative, a fractional or out-of-safe-range number)
+     * throws {@link ValidationError} (E003) naming the argument and the table.
+     *
+     * This runs on EVERY pagination path, parameterized as well as inlined: a
+     * bound `NaN` serializes as SQL NULL, and Postgres reads `LIMIT NULL` as
+     * "no limit", so an unvalidated value silently turns a paginated query into
+     * a full-table read (and a bad OFFSET silently disappears).
+     */
+    private paginationValue;
     /**
      * Validate a LIMIT/OFFSET value as a non-negative integer and return it as an
      * inline SQL literal. Used only on `dialect.inlineLimitOffset` engines (MySQL).
      * The input is always a Turbine-controlled pagination value, never a raw user
-     * string — and this guard guarantees the output is `String` of a validated
+     * string, and this guard guarantees the output is `String` of a validated
      * integer, so inlining cannot inject SQL.
      */
     private limitOffsetLiteral;
@@ -216,6 +310,97 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      * nothing stable to order by, so both are left untouched.
      */
     private applyStableRelationOrder;
+    /**
+     * The primary key of this table as an ascending `orderBy`, in DECLARATION
+     * order (a composite PK orders on every column), or `undefined` for a PK-less
+     * table. Field names are the camelCase accessor names, so the emitted SQL goes
+     * through the normal column mapping.
+     */
+    private pkOrderBy;
+    /**
+     * The field names a `cursor` actually seeks on (its own keys with a defined
+     * value), in the canonical sorted order the cursor conditions are built in.
+     * Empty for a missing cursor or one whose every value is `undefined` (which
+     * emits no seek condition at all, so it does not paginate).
+     */
+    private cursorFields;
+    /**
+     * The ascending ordering implied by a `cursor`, or `undefined` when the shape
+     * is too ambiguous to order safely.
+     *
+     * A cursor seek emits `col > $n` per field (`<` when the orderBy says desc),
+     * so the ONLY ordering coherent with it is on the cursor's own field: ordering
+     * a seek on column X by column Y walks the table in an order the seek does not
+     * follow, which skips and repeats rows just as badly as no order at all. That
+     * is why this orders on the cursor field rather than blindly on the primary
+     * key when the two differ.
+     *
+     * Returns `undefined` (warn, inject nothing) for two shapes:
+     *  - a MULTI-field cursor. `a > $1 AND b > $2` is a conjunction, not a proper
+     *    composite keyset seek (`(a, b) > ($1, $2)`), so no single ORDER BY makes
+     *    it correct. Injecting `(a asc, b asc)` would dress a broken seek up as a
+     *    sound one.
+     *  - a field that does not resolve to a real column. Column validation belongs
+     *    to the normal build path, which raises a precise error; synthesizing an
+     *    ORDER BY on it here would only change which error the caller sees.
+     */
+    private cursorOrderBy;
+    /**
+     * Whether a findMany paginates (`limit` / `take` / `offset` / `cursor`) but
+     * declares no ordering, which makes the returned page NON-DETERMINISTIC:
+     * Postgres is free to return different rows for the same unordered `LIMIT`
+     * once the heap changes underneath it, so a row can appear on two pages or on
+     * none.
+     *
+     * `cursor` counts, and is the worst case rather than an exception: a keyset
+     * seek with no ORDER BY is exactly this bug (`WHERE id > $1 LIMIT $2` walks
+     * the heap in whatever order the plan happens to produce). An empty orderBy
+     * (`[]`, or an object whose every value is `undefined`) counts as absent,
+     * because it emits no ordering.
+     *
+     * `distinct` is still excluded: that path re-orders in an outer wrapper around
+     * a `DISTINCT ON` whose ordering picks the representative row, so an implicit
+     * key would change which rows come back, not just their order.
+     */
+    private isUnorderedPage;
+    /**
+     * Opt-in (`implicitPkOrdering`) primary-key ascending ordering for a paginating
+     * findMany that declares no `orderBy`, making its pages deterministic.
+     *
+     * OFF by default in CORE, deliberately: turning it on would add an `ORDER BY`
+     * to SQL that existing applications already emit, changing both the rows a
+     * given page returns and the plan the engine picks. That is a breaking change
+     * in everything but the type signature, so it waits for a major. The
+     * `turbine-orm/prisma-compat` layer defaults it ON instead, because reproducing
+     * Prisma's semantics is that layer's whole contract.
+     *
+     * An explicit `orderBy` always wins, a PK-less table is left alone (nothing
+     * stable to order by), and a composite PK orders on every column in
+     * declaration order. A `cursor` query orders on the CURSOR's field instead
+     * (see {@link cursorOrderBy}), and is left alone when that shape is ambiguous.
+     * `distinct` shapes are skipped (see {@link isUnorderedPage}). With the flag
+     * off this returns `undefined` before touching anything, so the emitted SQL is
+     * byte-identical to before.
+     */
+    private implicitPkOrderBy;
+    /**
+     * Dev-only, once per query shape: an unordered paginating findMany returns a
+     * non-deterministic page (see {@link isUnorderedPage}), and on real data it is
+     * also usually the slower plan (an unordered `LIMIT` can discard tens of
+     * thousands of heap rows that an index scan on the key would have skipped).
+     *
+     * Gated exactly like the other dev diagnostics (silent under
+     * `NODE_ENV=production`) and consistent with `warnOnUnlimited`: a per-call
+     * `warnOnUnlimited: false` silences it, `true` forces it past a config-level
+     * opt-out, and a config/per-table `warnOnUnlimited: false` silences it. Deduped
+     * process-wide through the shared warn registry, so it can never spam.
+     *
+     * Suppressed only when `implicitPkOrdering` will ACTUALLY order this query.
+     * The flag being on is not enough: a PK-less table and an ambiguous
+     * multi-field cursor both get no injected ordering, and those are precisely
+     * the shapes that still need saying out loud.
+     */
+    private maybeWarnUnorderedPage;
     /**
      * Whether a relation can be served by the batched loader, i.e. all its
      * correlation keys are single-column (the loader throws E017 on composite
@@ -234,18 +419,63 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
     /** The `_count` verdict under `'auto'`: any counted probe unindexed + all single-key. */
     private autoCountVerdict;
     /**
-     * Partition a top-level `with` clause under `'auto'`: each relation whose
-     * subtree has a PROVEN unindexed probe AND is fully batched-eligible routes to
-     * `batchedWith`; everything else (indexed, composite-key, unknown) stays in
-     * `joinWith` (byte-identical join). The reserved `_count` key partitions the
-     * same way. Also returns the engaged relations for the dev note.
+     * Whether a query's parent set is potentially large at plan time, which is the
+     * only cardinality signal available before the base query runs. A `findMany`
+     * with no `limit`/`take` (or one above {@link autoToOneJoinMaxRows}) can return
+     * an arbitrary number of parent rows; a small `limit` bounds it. `findUnique` /
+     * `findFirst` pass `false` explicitly (their parent set is one row).
+     */
+    private autoParentSetLarge;
+    /**
+     * The parent-row count at which `'auto'` stops preferring the single-statement
+     * join for a to-one relation.
+     *
+     * Resolution order:
+     *   1. an explicit `autoToOneJoinMaxRows` — an instruction, used verbatim
+     *      (no clamping: the caller has measured their own workload);
+     *   2. the configured `autoRoundTripMs` divided by
+     *      {@link AUTO_JOIN_PENALTY_MS_PER_ROW}, clamped to
+     *      [{@link AUTO_TO_ONE_JOIN_ROWS_MIN}, {@link AUTO_TO_ONE_JOIN_ROWS_MAX}];
+     *   3. {@link AUTO_TO_ONE_JOIN_MAX_ROWS}, which is that same division applied
+     *      to {@link AUTO_ASSUMED_ROUND_TRIP_MS}.
+     *
+     * Deriving it rather than hard-coding a row count is the whole point: the
+     * sweep in {@link AUTO_JOIN_PENALTY_MS_PER_ROW} shows the break-even moving
+     * 17x between a loopback link and a 2.7ms one while the per-row penalty stays
+     * put, so any single constant is wrong for someone by more than the margin it
+     * is trying to save. Placing the switch AT the break-even is also what removes
+     * the old cliff: two plans that cost the same at the boundary make the regret
+     * there ~1.0x, rising only as the true row count moves away from it — where
+     * the previous fixed 1000 put its WORST case (1.44x measured) immediately
+     * below its own switch point.
+     *
+     * Cheap enough to recompute per call (a division and two comparisons over
+     * readonly fields), so there is no cached copy to invalidate.
+     */
+    private autoToOneThreshold;
+    /**
+     * Partition a top-level `with` clause under `'auto'`. A relation routes to
+     * `batchedWith` when it is fully batched-eligible AND either
+     *
+     *   1. its subtree has a PROVEN unindexed probe (index metadata only), or
+     *   2. it is TO-ONE and the parent set is potentially large
+     *      ({@link AUTO_TO_ONE_JOIN_MAX_ROWS}), since a correlated to-one subquery
+     *      is re-evaluated per parent row no matter how well indexed it is.
+     *
+     * Everything else (indexed to-many, composite-key, unknown) stays in `joinWith`
+     * (byte-identical join). The reserved `_count` key falls back on rule 1 only,
+     * and only for a large parent set: an inline `_count` is one correlated
+     * `COUNT(*)` per parent row, so the grouped follow-up wins exactly when there
+     * are many parents, while for a handful of parents the extra round-trip costs
+     * more than the repeated (small) scans. Also returns the engaged relations for
+     * the dev note.
      */
     private partitionWithForAuto;
     /**
      * Plan the `'auto'` split for a query's `with` clause: normalize stable order,
      * partition, and return the split ONLY when at least one relation falls back
      * to batched. Returns `null` (→ run the plain join path, byte-identical, same
-     * cache keys) when there is no DB-backed index metadata or nothing qualifies.
+     * cache keys) when nothing qualifies.
      */
     private planAuto;
     /** Dev-only once-per-relation note that `'auto'` engaged the batched fallback. */
@@ -459,14 +689,19 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      * method fall back to the full cursor path.
      *
      * **Cursor path:** Uses DECLARE CURSOR within a dedicated transaction on a
-     * single pooled connection. The cursor is automatically closed and the
-     * connection released when iteration completes or is terminated early
-     * (e.g. `break` from `for await`).
+     * single pooled connection. The cursor is CLOSEd (in the dialect's `finally`)
+     * and the connection released both when iteration completes normally and when
+     * it ends early (`break` from `for await`). An error mid-stream skips the
+     * CLOSE and rolls back instead, which drops the cursor with the transaction.
      *
-     * **Snapshot semantics note:** The speculative fast-path runs outside a
-     * transaction. If the result overflows and the cursor path is opened, the
-     * cursor runs in its own transaction — spanning two separate snapshots.
-     * For strict single-snapshot semantics, wrap the call in `$transaction`.
+     * **Snapshot semantics note:** Outside a transaction the speculative
+     * fast-path runs unwrapped, and an overflow opens the cursor in its own
+     * transaction, so the two fetches span two separate snapshots. Wrapping the
+     * call in `$transaction` gives strict single-snapshot semantics: both the
+     * speculative fetch and the cursor then run on the caller's connection
+     * inside the caller's transaction (the cursor path issues no BEGIN/COMMIT of
+     * its own and releases nothing, so the caller's transaction is intact when
+     * iteration finishes).
      *
      * @example
      * ```ts
@@ -490,15 +725,15 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
     private runInImplicitTx;
     private buildNestedCtx;
     private makeTxProxy;
-    delete(args: DeleteArgs<T>): Promise<T>;
-    upsert(args: UpsertArgs<T>): Promise<T>;
-    updateMany(args: UpdateManyArgs<T>): Promise<{
+    delete(args: DeleteArgs<T, R>): Promise<T>;
+    upsert(args: UpsertArgs<T, R>): Promise<T>;
+    updateMany(args: UpdateManyArgs<T, R>): Promise<{
         count: number;
     }>;
-    deleteMany(args: DeleteManyArgs<T>): Promise<{
+    deleteMany(args: DeleteManyArgs<T, R>): Promise<{
         count: number;
     }>;
-    count(args?: CountArgs<T>): Promise<number>;
+    count(args?: CountArgs<T, R>): Promise<number>;
     buildCount(args?: CountArgs<T>): DeferredQuery<number>;
     /**
      * Group rows and compute per-group aggregates (Prisma-style). The result row
@@ -508,10 +743,10 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      * {@link GroupByResult}). Grouping by a JSON-path key yields a runtime alias
      * that cannot be typed, so those columns are not projected onto the row type.
      */
-    groupBy<A extends GroupByArgs<T>>(args: A): Promise<GroupByResult<T, A>[]>;
+    groupBy<A extends GroupByArgs<T, R>>(args: A): Promise<GroupByResult<T, A>[]>;
     buildGroupBy(args: GroupByArgs<T>): DeferredQuery<Record<string, unknown>[]>;
     buildAggregate(args: AggregateArgs<T>): DeferredQuery<AggregateResult<T>>;
-    aggregate(args: AggregateArgs<T>): Promise<AggregateResult<T>>;
+    aggregate(args: AggregateArgs<T, R>): Promise<AggregateResult<T>>;
     private resolveColumns;
     withFingerprint(withClause: WithClause | undefined, table?: string, depth?: number): string;
     private collectWithParams;
@@ -527,6 +762,42 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
     private getCamelDateFields;
     private makeNestedParser;
     private buildSelectWithRelations;
+    /**
+     * Compile the `relationLoadStrategy: 'flatten'` plan for a findMany-shaped
+     * query, or `null` to emit exactly the SQL (and cache key) the default
+     * strategy emits.
+     *
+     * `'flatten'` compiles an eligible to-one relation to a `LEFT JOIN` with a
+     * prefixed scalar projection instead of a correlated `json_build_object`
+     * subquery. The correlated form is re-evaluated once per parent row, so its
+     * cost scales with the parent set no matter how well the FK is indexed; the
+     * join does not, and unlike `'batched'` it stays a single round trip.
+     *
+     * It is an EXPLICIT opt-in: `'auto'` is unchanged and never selects it.
+     *
+     * Query-shape gates (any of these routes the WHOLE query back to the default
+     * strategy, silently and byte-identically):
+     *   - the resolved strategy is not `'flatten'`;
+     *   - `jsonEncoding: 'positional'` (a flattened relation emits no JSON at all,
+     *     so the two encodings are not composed in this version);
+     *   - the dialect owns relation-subquery generation
+     *     (`dialect.buildRelationSubquery`, i.e. SQL Server's `FOR JSON PATH`);
+     *   - `distinct` (the `DISTINCT ON` rewrite re-orders in an outer wrapper, and
+     *     the extra projected columns have not been proven safe there).
+     *
+     * `limit` / `offset` / `cursor` / `orderBy` need no gate: every flattened join
+     * is over a PROVABLY UNIQUE target key, so it matches at most one row per
+     * parent and cannot change the parent row count that pagination applies to.
+     *
+     * Per-relation eligibility lives in `planFlattenWith` / `planFlattenNode`.
+     * Only the findMany family is planned (`findMany`, `findFirst`,
+     * `findManyStream`, and pipelined `buildFindMany`); `findUnique` reads a single
+     * parent row, where the correlated subquery runs exactly once, so it stays on
+     * the default path.
+     */
+    private planFlatten;
+    /** Dev-only once-only note that `'flatten'` was refused for the whole query. */
+    private warnFlattenBlocked;
     /** Convert camelCase field name to snake_case column name (unquoted, for non-SQL uses) */
     private toColumn;
     /** Convert camelCase field name to a double-quoted SQL identifier */