turbine-orm 0.49.0 → 0.50.0

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

@@ -0,0 +1,849 @@
+/**
+ * turbine-orm — Query builder
+ *
+ * Each table accessor (db.users, db.posts, etc.) returns a QueryInterface<T>
+ * that builds parameterized SQL and executes it through the connection pool.
+ *
+ * Nested relations use json_build_object + json_agg subqueries for single-query
+ * resolution — a PostgreSQL-native approach that eliminates N+1 query patterns.
+ *
+ * Schema-driven: all column names, types, and relations come from introspected
+ * metadata — nothing is hardcoded.
+ */
+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 = {}> {
+    private readonly pool;
+    private readonly table;
+    private readonly schema;
+    private readonly tableMeta;
+    /**
+     * SQL template cache: cacheKey → SqlCacheEntry (sql + prepared statement name).
+     * Capacity is set once in the constructor from `options.sqlCacheSize`
+     * (default 1000). See {@link QueryInterfaceOptions.sqlCacheSize}.
+     */
+    private readonly sqlTemplateCache;
+    /**
+     * Whether the most recent {@link acquireSql} call was a cache HIT. Read by
+     * {@link crossCheckCache} to decide whether to run the dev-mode lockstep
+     * cross-check. Safe as a single mutable flag: each `build*()` method calls
+     * `acquireSql` then `crossCheckCache` synchronously with no intervening
+     * `await` and no re-entrant `acquireSql` (relation subqueries are built
+     * inline, not through the top-level cache).
+     */
+    private lastCacheHit;
+    private readonly middlewares;
+    private readonly defaultLimit?;
+    private readonly warnOnUnlimited;
+    private readonly utcTimestamps;
+    private readonly preparedStatementsEnabled;
+    /**
+     * Whether the SQL template cache is active. Set once in the constructor.
+     * Mutable (not `readonly`) only so {@link withSqlCacheDisabled} can flip it
+     * off around a single synchronous compile (see {@link explain}).
+     */
+    private sqlCacheEnabled;
+    private readonly dialect;
+    /**
+     * Client-level default relation-loading strategy. When nothing is configured
+     * this is `'auto'` (the implicit default): per-relation, keep the single-
+     * statement join unless the introspected metadata proves a probe is unindexed,
+     * in which case that relation falls back to the batched loader. An explicit
+     * `'join'`/`'batched'` (client or query level) always wins.
+     */
+    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;
+    /**
+     * Client-level automatic WHERE filters keyed by table accessor (soft-delete /
+     * multi-tenancy). AND-merged into every query on the keyed table and every
+     * relation subquery targeting it. Undefined when none are configured, in
+     * which case every path is byte-identical to the pre-0.28 behavior.
+     */
+    private readonly globalFilters?;
+    /**
+     * Tracks tables that have already triggered an unlimited-query warning so
+     * the user is not spammed once per row. Per-instance state — each
+     * QueryInterface is bound to a single table, so this set will only ever
+     * contain at most one entry, but using a Set keeps the API consistent with
+     * the audit's "Set<string>" guidance and leaves room for future
+     * cross-table sharing.
+     */
+    private readonly warnedTables;
+    /** Cache hit/miss counters for diagnostics */
+    private cacheHits;
+    private cacheMisses;
+    /** Pre-computed column type lookups (avoids linear scans per query) */
+    private readonly columnPgTypeMap;
+    private readonly columnArrayTypeMap;
+    /**
+     * Columns whose type lives in a DIFFERENT schema than the introspected one
+     * (ColumnMetadata.pgTypeSchema is recorded only in that case) — such columns
+     * must never receive this schema's `::"enum"` cast (see enumTypeForColumn).
+     */
+    private readonly crossSchemaTypeColumns;
+    /**
+     * Per-table memo of date columns keyed by their camelCase FIELD name.
+     * `meta.dateColumns` is keyed by raw snake_case column name, which matches
+     * top-level rows from pg. Nested relation rows arrive from json_build_object
+     * with camelCase keys, so they need this camelCase-keyed set to be coerced
+     * to Date as well (otherwise nested dates leak through as strings).
+     */
+    private readonly camelDateFieldCache;
+    /** True when this QI runs inside an active transaction (set via _txScoped option). */
+    private readonly txScoped;
+    /** Original options reference — forwarded to child QIs in nested writes. */
+    private readonly options?;
+    /** Set by executeWithMiddleware so queryWithTimeout can include it in events. */
+    private currentAction;
+    /**
+     * Tags the query events of an in-flight `relationLoadStrategy: 'auto'` query
+     * that engaged the batched fallback (`'auto-batched'`), so observability sees
+     * which queries the auto default re-planned. Same transient-instance-state
+     * caveat as {@link currentAction}: set for the whole auto-split operation and
+     * cleared afterward; a concurrent unrelated query on the same accessor during
+     * that window could read it (a best-effort diagnostic tag, not load-bearing).
+     */
+    private currentStrategyTag;
+    /**
+     * The active query's `skipGlobalFilters` opt-out, set at the top of each
+     * `build*` method and read deep in the (synchronous) SQL-build + param-collect
+     * tree — so relation subqueries, relation filters, `_count`, and relation
+     * `orderBy` all see it without threading it through dozens of signatures.
+     * Only load-bearing when {@link globalFilters} is configured; build+collect are
+     * synchronous per call, so this transient is never observed across an await.
+     */
+    private currentSkip;
+    /**
+     * The bound view of this instance passed to the shared WHERE walk
+     * (`where-compile.ts`). Built once in the constructor so `fingerprintWhere` /
+     * `buildWhereClause` / `collectWhereParams` all drive ONE enumeration + ONE
+     * scalar classifier without widening the class's public surface or allocating
+     * per call. See {@link WhereHost}.
+     */
+    private readonly whereHost;
+    /**
+     * Per-target-table {@link WhereHost} memo for scoped sub-wheres (relation
+     * `EXISTS` filters + relation `with`-clause `where`s). Keyed by table name;
+     * the host depends only on the target table's metadata, so it is shared across
+     * every alias/qualifier for that table. Lazily filled by {@link scopedWhereHost}.
+     */
+    private readonly scopedHostCache;
+    /**
+     * The privacy-preserving view of this instance handed to the extracted WHERE
+     * module (`where.ts`). Built once in the constructor (mirroring the
+     * `whereHost` precedent) so the free functions there reach exactly the
+     * class-resident primitives they need without widening the public surface.
+     */
+    private readonly ctx;
+    constructor(pool: pg.Pool, table: string, schema: SchemaMetadata, middlewares?: MiddlewareFn[], options?: QueryInterfaceOptions);
+    /** Quote an identifier through the active SQL dialect. */
+    private q;
+    /** Return the active dialect's placeholder for a 1-indexed parameter position. */
+    private p;
+    /**
+     * Cast an aggregate expression to an integer/float result type through the
+     * active dialect. PostgreSQL keeps the historical postfix cast (`expr::int` /
+     * `expr::float`); SQLite (no `::` operator) maps to `CAST(expr AS INTEGER/REAL)`.
+     * Falls back to the Postgres postfix cast for dialects without the hook.
+     */
+    private castAgg;
+    /**
+     * Build the trailing pagination clause for an OUTER SELECT. PostgreSQL/MySQL/
+     * SQLite use ` LIMIT <ph>` and/or ` OFFSET <ph>`. SQL Server has no `LIMIT`, so
+     * its dialect implements {@link Dialect.buildLimitOffset} to emit
+     * `[ORDER BY (SELECT NULL)] OFFSET <off> ROWS [FETCH NEXT <lim> ROWS ONLY]`.
+     * Param-push order (limit before offset) is owned by the caller and unchanged —
+     * this only varies the SQL text, so PG output stays byte-identical.
+     */
+    private buildPagination;
+    /**
+     * The single-row limit appended to findUnique / findFirst-style lookups. ` LIMIT 1`
+     * for PG/MySQL/SQLite; SQL Server routes through {@link Dialect.buildLimitOffset}
+     * (literal `1`, no params) → ` ORDER BY (SELECT NULL) OFFSET 0 ROWS FETCH NEXT 1
+     * 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
+     * integer, so inlining cannot inject SQL.
+     */
+    private limitOffsetLiteral;
+    /**
+     * Resolve a LIMIT/OFFSET value to either an inline literal (no param pushed, on
+     * `dialect.inlineLimitOffset` engines) or a bound placeholder (the value is
+     * pushed to `params`). Build and collect paths both gate on the same flag so
+     * the param order stays mirrored; PG/SQLite/SQL Server keep parameterizing and
+     * stay byte-identical.
+     */
+    private paginationRef;
+    /**
+     * Build an `IN` / `NOT IN` predicate through the active dialect. PostgreSQL
+     * keeps the array-param form (`expr = ANY($n)` / `expr != ALL($n)`); other
+     * engines (SQLite) use a length-independent single-placeholder form. Paired
+     * with {@link inParam}, which supplies the single bound value.
+     */
+    private inClause;
+    /** The single bound parameter for an `IN` list (PG: the array; SQLite: a JSON string). */
+    private inParam;
+    /**
+     * Resolve the effective relation-loading strategy for a query: the per-query
+     * arg wins, then the client-level default, then `'auto'`. Only meaningful when
+     * a `with` clause is present; the callers gate on that.
+     */
+    private resolveLoadStrategy;
+    /**
+     * The effective {@link QueryInterfaceOptions.stableRelationOrder} for a query:
+     * the per-query arg wins, then the client-level default (off).
+     */
+    private resolveStableOrder;
+    /**
+     * Fill a PK-ascending `orderBy` into every to-many `with` relation that has no
+     * explicit one, recursing into nested `with`. Returns a CLONED clause (user
+     * args are never mutated); when nothing needs filling it returns the input
+     * object unchanged, so the byte-identical fast path stays free. Only called
+     * when {@link resolveStableOrder} is true; runs BEFORE `withFingerprint`, so
+     * the two orderings get distinct SQL-cache entries automatically. To-one
+     * relations are single rows (no array to order) and PK-less targets have
+     * 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
+     * keys). Composite-key relations therefore always stay on the join plan under
+     * `'auto'` (and keep the existing unindexed-probe dev warning).
+     */
+    private relationBatchEligible;
+    /**
+     * The verdict for one relation SUBTREE under `'auto'`: is any probe in the
+     * subtree unindexed, is EVERY relation in the subtree batched-eligible, and
+     * the first unindexed probe found (for the dev note). Subtree-atomic: a whole
+     * top-level relation falls back only when its entire subtree is eligible,
+     * mirroring the batched loader recursing the same tree.
+     */
+    private autoSubtreeVerdict;
+    /** The `_count` verdict under `'auto'`: any counted probe unindexed + all single-key. */
+    private autoCountVerdict;
+    /**
+     * 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 nothing qualifies.
+     */
+    private planAuto;
+    /** Dev-only once-per-relation note that `'auto'` engaged the batched fallback. */
+    private emitAutoNotes;
+    /**
+     * Execute a findMany/findUnique `'auto'` split: run the base query with the
+     * residual `joinWith` (plus any parent stitch keys the batched subset needs),
+     * then load `batchedWith` via the batched loader and stitch. `single` returns
+     * the first entity (findUnique) instead of the array. Output is identical in
+     * shape to the pure join plan.
+     */
+    private runAutoSplit;
+    /**
+     * Build the {@link RelationLoadContext} the batched loader needs, closing over
+     * this interface's pool/dialect/executor. Child readers are constructed on the
+     * SAME pool (so they join an active transaction) with `defaultLimit` cleared
+     * and unlimited-warnings silenced — a relation load must fetch every matching
+     * child, and the per-relation `limit` is applied client-side by the loader.
+     */
+    private batchedContext;
+    /**
+     * Run a findMany with the batched strategy: execute the base query WITHOUT
+     * relation subqueries (all other clauses intact), then load each relation via
+     * one flat follow-up query and stitch client-side. Parent stitch keys the
+     * caller's `select`/`omit` excluded are added for the base query and stripped
+     * from the returned rows, so the shape matches the join strategy exactly.
+     */
+    private runFindManyBatched;
+    /**
+     * Build the base findMany args for a batched run: drop `with`, and ensure every
+     * parent correlation key needed for stitching is projected (returning the list
+     * of keys that must be stripped from the output afterwards).
+     */
+    private prepareBatchedBase;
+    /**
+     * Return cache hit/miss statistics for this QueryInterface instance.
+     * Useful for monitoring and benchmarking.
+     */
+    cacheStats(): {
+        hits: number;
+        misses: number;
+        hitRate: number;
+        size: number;
+    };
+    /**
+     * Look up or build a SQL template in the cache.
+     * On miss, calls `build()` to generate the SQL, stores the entry, and returns it.
+     * On hit, increments counters and returns the cached entry.
+     *
+     * When `sqlCache` is disabled, always calls `build()` without caching.
+     *
+     * `build` receives a fresh `$N` param scratch array. On a miss those params
+     * are discarded (the returned params come from each call site's dedicated
+     * collect path); the array exists so the build path can number placeholders
+     * via `params.length` exactly as it does today. On a HIT, `build` is skipped
+     * here but re-run by {@link crossCheckCache} (dev only) with a fresh array to
+     * verify the collect path stayed in lockstep with the build path.
+     *
+     * Sets {@link lastCacheHit} so the caller's `crossCheckCache` knows whether a
+     * cross-check is warranted.
+     */
+    private acquireSql;
+    /**
+     * Dev-mode SQL-cache lockstep cross-check (see {@link cacheCrossCheckEnabled}).
+     *
+     * Runs only when the most recent {@link acquireSql} was a cache HIT and the
+     * check is enabled. Rebuilds the SQL + `$N` params fresh via the same `build`
+     * closure the caller passed to `acquireSql`, then compares:
+     *   (a) the cached SQL string byte-for-byte against the fresh SQL, and
+     *   (b) the params the cache-hit collect path produced against the fresh
+     *       build-path params (length and element-wise strict deep-equal).
+     *
+     * A mismatch means the fingerprint / build / collect paths have drifted out
+     * of lockstep (the exact class of bug that has silently corrupted results
+     * before), so it throws a {@link ValidationError} (E003) naming the
+     * fingerprint, the operation, and both SQL strings (truncated). Failing loud
+     * in dev/test is the point. Production never reaches the comparison.
+     *
+     * @param op human label of the calling build method (for the error message).
+     * @param cacheKey the cache fingerprint that HIT.
+     * @param entry the cached SQL entry that will be executed.
+     * @param build the same closure passed to `acquireSql`; re-run here to
+     *   capture the fresh build-path SQL + params.
+     * @param collectedParams the params the caller's collect path produced.
+     */
+    private crossCheckCache;
+    /**
+     * Reset the per-instance unlimited-query warning dedupe set.
+     * Exposed for tests so a single test process can verify the warning fires
+     * exactly once per table without bleeding state between assertions.
+     */
+    resetUnlimitedWarnings(): void;
+    private emitQueryEvent;
+    /**
+     * Execute a pool.query with an optional timeout.
+     * If timeout is set, races the query against a timer and rejects on expiry.
+     * pg driver errors are translated to typed Turbine errors via wrapPgError.
+     */
+    private queryWithTimeout;
+    /**
+     * Execute a write `DeferredQuery` (create/update/delete/upsert) according to
+     * the active dialect's {@link Dialect.resultStrategy}, then apply its
+     * transform.
+     *
+     *   - `'returning'` / `'output'`: the statement returns its own affected rows
+     *     (`RETURNING *` / `OUTPUT INSERTED.*`). Byte-identical to the historical
+     *     single `queryWithTimeout` + `transform(result)` path — the PostgreSQL
+     *     route is unchanged.
+     *   - `'reselect'`: the engine cannot return rows from a write, so the build
+     *     method attached a {@link DeferredQuery.reselect} plan that runs the
+     *     write and a follow-up SELECT; the SELECT's rows feed the transform.
+     */
+    private executeMutation;
+    buildCreate(args: CreateArgs<T>): DeferredQuery<T>;
+    buildCreateMany(args: CreateManyArgs<T>): DeferredQuery<T[]>;
+    buildUpdate(args: UpdateArgs<T>): DeferredQuery<T>;
+    buildDelete(args: DeleteArgs<T>): DeferredQuery<T>;
+    buildUpsert(args: UpsertArgs<T>): DeferredQuery<T>;
+    buildUpdateMany(args: UpdateManyArgs<T>): DeferredQuery<{
+        count: number;
+    }>;
+    buildDeleteMany(args: DeleteManyArgs<T>): DeferredQuery<{
+        count: number;
+    }>;
+    /**
+     * Best-effort extraction of an auto-generated primary key from a write
+     * result for `'reselect'` engines (e.g. mysql2's `insertId`). Returns
+     * `undefined` when the driver exposes no such field.
+     */
+    private mutationInsertId;
+    /**
+     * Execute a query through the middleware chain.
+     * If no middlewares are registered, executes directly.
+     *
+     * Middleware can inspect and log query parameters, measure timing, and
+     * transform the result returned by `next()`. Note: query SQL is generated
+     * BEFORE middleware runs — `params.args` is a read-only snapshot, and
+     * mutating it does NOT change the executed SQL. Cross-cutting filters
+     * (e.g. soft deletes) belong in the query itself: pass an explicit
+     * `where: { deletedAt: null }` or wrap the table accessor in a small helper.
+     */
+    private executeWithMiddleware;
+    findUnique<W extends TypedWithClause<R> = {}, S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined>(args: FindUniqueArgs<T, R, W, S, O>): Promise<QueryResult<T, R, W, S, O> | null>;
+    /**
+     * Batched-strategy findUnique: fetch the single base row without relation
+     * subqueries (adding any parent stitch keys the projection excluded), then load
+     * its relations via one follow-up query each and stitch. Mirrors the join
+     * strategy's shape for the one row.
+     */
+    private runFindUniqueBatched;
+    buildFindUnique<W extends TypedWithClause<R> = {}>(args: FindUniqueArgs<T, R, W, Record<string, boolean> | undefined, Record<string, boolean> | undefined>): DeferredQuery<T | null>;
+    findMany<W extends TypedWithClause<R> = {}, S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined>(args?: FindManyArgs<T, R, W, S, O>): Promise<QueryResult<T, R, W, S, O>[]>;
+    /**
+     * Return the engine's query plan for a {@link findMany}-shaped query as plain
+     * text lines: a diagnostic surface for inspecting how the database will run a
+     * query (index usage, join strategy, scan type).
+     *
+     * The compiled SELECT is prefixed with the dialect's explain syntax
+     * (Postgres `EXPLAIN`, SQLite `EXPLAIN QUERY PLAN`, MySQL `EXPLAIN
+     * FORMAT=TREE`) and run as a read. The findMany args are compiled with the
+     * SQL template cache disabled, so an explain never reads or writes the shared
+     * cache. Middleware is NOT applied: the returned rows are plan text, not
+     * entity rows. Each result row is flattened to one line by joining its column
+     * values with a single space (Postgres returns one `QUERY PLAN` text column,
+     * SQLite's `EXPLAIN QUERY PLAN` returns four, MySQL's tree format one).
+     *
+     * Only `findMany` shapes are supported (where / orderBy / with / limit /
+     * pagination). Engines whose plan cannot be requested in-band from a compiled
+     * query (SQL Server, whose SHOWPLAN is a session toggle) throw
+     * {@link UnsupportedFeatureError} (E017).
+     *
+     * The plan text itself is engine-owned and NOT covered by semver: its content
+     * and formatting can change with the underlying database version.
+     */
+    explain(args?: FindManyArgs<T, R>): Promise<string[]>;
+    /**
+     * Run `fn` with the SQL template cache forced off, restoring the prior state
+     * afterward. Used by {@link explain}, whose one-off prefixed statement must
+     * neither read nor write the shared cache. `fn` is synchronous, so no query
+     * interleaves between the toggle and its restore.
+     */
+    private withSqlCacheDisabled;
+    /**
+     * Emit a one-time `console.warn` when {@link findMany} is called without an
+     * explicit `limit`/`take` and `warnOnUnlimited` has not been disabled.
+     *
+     * Deduped per QueryInterface instance via {@link warnedTables} so a busy
+     * loop calling `db.users.findMany()` thousands of times only logs once.
+     * Suppressed when `defaultLimit` is configured (the caller has already
+     * opted in to a bounded query) and when the user passed an explicit
+     * `limit`, `take`, or `cursor`. A per-call `warnOnUnlimited` overrides the
+     * config-level setting in either direction (`false` silences a call that
+     * intentionally reads the full set; `true` forces the warning even when
+     * disabled in config).
+     */
+    private maybeWarnUnlimited;
+    /**
+     * Recursively measure the maximum depth of a `with` clause tree.
+     * Used by the dev-only deep-with warning guard.
+     */
+    private measureWithDepth;
+    buildFindMany<W extends TypedWithClause<R> = {}>(args?: FindManyArgs<T, R, W, Record<string, boolean> | undefined, Record<string, boolean> | undefined>): DeferredQuery<T[]>;
+    /**
+     * Stream rows from a findMany query using PostgreSQL cursors.
+     * Returns an AsyncIterable that yields individual rows, fetching in batches internally.
+     *
+     * **Speculative fast-path:** Before opening a cursor, issues a single
+     * `SELECT ... LIMIT batchSize+1`. If the result fits within `batchSize`,
+     * all rows are yielded immediately with zero cursor overhead (no BEGIN /
+     * DECLARE / CLOSE / COMMIT). Only when the result overflows does the
+     * 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 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:** 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
+     * for await (const user of db.users.findManyStream({ where: { orgId: 1 }, batchSize: 500 })) {
+     *   process.stdout.write(`${user.email}\n`);
+     * }
+     * ```
+     */
+    findManyStream<W extends TypedWithClause<R> = {}, S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined>(args?: FindManyStreamArgs<T, R, W, S, O>): AsyncGenerator<QueryResult<T, R, W, S, O>, void, undefined>;
+    findFirst<W extends TypedWithClause<R> = {}, S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined>(args?: FindManyArgs<T, R, W, S, O>): Promise<QueryResult<T, R, W, S, O> | null>;
+    buildFindFirst<W extends TypedWithClause<R> = {}>(args?: FindManyArgs<T, R, W, Record<string, boolean> | undefined, Record<string, boolean> | undefined>): DeferredQuery<T | null>;
+    findFirstOrThrow<W extends TypedWithClause<R> = {}, S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined>(args?: FindManyArgs<T, R, W, S, O>): Promise<QueryResult<T, R, W, S, O>>;
+    buildFindFirstOrThrow<W extends TypedWithClause<R> = {}>(args?: FindManyArgs<T, R, W, Record<string, boolean> | undefined, Record<string, boolean> | undefined>): DeferredQuery<T>;
+    findUniqueOrThrow<W extends TypedWithClause<R> = {}, S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined>(args: FindUniqueArgs<T, R, W, S, O>): Promise<QueryResult<T, R, W, S, O>>;
+    buildFindUniqueOrThrow<W extends TypedWithClause<R> = {}>(args: FindUniqueArgs<T, R, W, Record<string, boolean> | undefined, Record<string, boolean> | undefined>): DeferredQuery<T>;
+    create(args: CreateArgs<T, R>): Promise<T>;
+    createMany(args: CreateManyArgs<T>): Promise<T[]>;
+    update(args: UpdateArgs<T, R>): Promise<T>;
+    private nestedCreate;
+    private nestedUpdate;
+    private runInImplicitTx;
+    private buildNestedCtx;
+    private makeTxProxy;
+    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, R>): Promise<{
+        count: 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
+     * type is INFERRED from the args: each `by` field carries its entity field
+     * type, `_count` is always a number, and each requested `_sum` / `_avg` /
+     * `_min` / `_max` block maps its fields to properly typed values (see
+     * {@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, 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, R>): Promise<AggregateResult<T>>;
+    private resolveColumns;
+    withFingerprint(withClause: WithClause | undefined, table?: string, depth?: number): string;
+    private collectWithParams;
+    private orderByEntryFingerprint;
+    private buildOrderBy;
+    private isRelationOrderByValue;
+    private nullsSuffix;
+    private resolveOrderByColumn;
+    private validateJsonPathOrderBy;
+    private buildJsonPathOrderEntry;
+    private collectRelationPickOrderParams;
+    private collectRelationCountParams;
+    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 */
+    private toSqlColumn;
+    fingerprintWhere(where: Record<string, unknown>): string;
+    collectWhereParams(where: Record<string, unknown>, params: unknown[]): void;
+    private resolveGlobalFilter;
+    private mergeGlobalFilter;
+    private collectTargetGlobalFilterAlias;
+    private globalFilterCacheSegment;
+    private buildWhereClause;
+    private buildAliasWhere;
+    private vectorOperator;
+    private pushVectorParam;
+    private normalizeRelationFilter;
+    private isJsonColumnType;
+    private getColumnPgType;
+    private jsonPathParam;
+    /**
+     * Collect params for an orderBy clause. Vector KNN ordering pushes the
+     * `$n::vector` query vector and JSON-path ordering pushes its text[] path;
+     * plain direction ordering is parameterless. Mirrors buildOrderBy's push
+     * order exactly so the cached-SQL param re-collection stays in lockstep.
+     */
+    private collectOrderByParams;
+    /**
+     * The {@link WhereHost} for a scoped sub-where over `meta`'s table. Memoized
+     * per table (see {@link scopedHostCache}); the host depends only on the target
+     * metadata, not on the caller's alias/qualifier.
+     */
+    /**
+     * Build ORDER BY clause from an object.
+     *
+     * Each value is either a plain direction (`'asc'`/`'desc'`) or — for pgvector
+     * columns — a `{ distance: { to, metric, direction? } }` KNN ordering object.
+     * Vector ordering binds the query vector as a `$n::vector` param, so a `params`
+     * array MUST be supplied when a vector ordering may be present (top-level
+     * findMany path). When `params` is omitted (groupBy / relation path) a vector
+     * ordering throws — KNN ordering is only supported at the top level.
+     */
+    /** Parse a flat row: convert snake_case to camelCase + Date coercion */
+    /**
+     * Returns the set of camelCase field names for a table's date columns,
+     * derived once from `meta.dateColumns` (snake_case) via reverseColumnMap and
+     * memoized per table. Used so nested relation rows (camelCase keys) coerce
+     * dates the same way top-level rows do.
+     */
+    private parseRow;
+}