turbine-orm 0.65.0 → 0.66.0

package/dist/query/builder.js

@@ -18,10 +18,10 @@ import { normalizeKeyColumns, snakeToCamel } from '../schema.js';
 import * as aggMod from './aggregates.js';
 import { assertProjectionShape, defaultProjectionFields, includeKeysForBatching, loadRelationsBatched, neededParentKeyFields, rejectNestedPickOrder, resolveCountRelations, stripFields, } from './batched-loader.js';
 import { expandCompoundUniqueWhere } from './compound-unique.js';
-import { isJsonPathOrderBy, isOrderBySpec, isRelationPickOrderBy, isVectorOrderBy, isWhereOperator, orderByEntries, sortedEntries, } from './filters.js';
+import { dedupeColumnList, dedupeOrderEntries, isJsonPathOrderBy, isOrderBySpec, isRelationPickOrderBy, isVectorOrderBy, isWhereOperator, orderByEntries, sortedEntries, } from './filters.js';
 import * as relationsMod from './relations.js';
 import { resolveSkipGlobalFilters, resolveUnsafeFlag, UNSAFE } from './types.js';
-import { isTemporalInfinity, LRUCache, ownLookup, parseDbDate, resolveColumnName, sqlToPreparedName, unknownFieldMessage, } from './utils.js';
+import { isTemporalInfinity, LRUCache, ownLookup, parseDbDate, resolveColumnName, sqlToPreparedName, unknownFieldMessage, warnRedundantSortTerm, } from './utils.js';
 import { shouldWarnOnce, WARN_NS } from './warn-registry.js';
 import * as whereMod from './where.js';
 import * as writesMod from './writes.js';
@@ -50,18 +50,55 @@ import * as writesMod from './writes.js';
  *   throws, same as dev. `0`, unset, or an unparseable value means never check.
  */
 function cacheCrossCheckMode() {
+    const env = crossCheckEnv ?? readCrossCheckEnv();
+    if (env.mode !== 'sampled')
+        return env.mode;
+    // The SAMPLING decision, and only it, is genuinely per hit.
+    return env.rate >= 1 || Math.random() < env.rate ? 'sampled' : 'off';
+}
+/**
+ * The env-derived half of {@link cacheCrossCheckMode}, resolved ONCE per
+ * process and memoized.
+ *
+ * `process.env` is not a plain object: every property read crosses a C++
+ * interceptor. Measured at 112.7 ns per read against 3.6 ns for a module-level
+ * constant, and this function ran TWO reads on every cache hit, which put it
+ * at the top of the SQL-build CPU profile (12.53% self time, with a further
+ * ~12% inside the interceptor) for a value that does not change.
+ *
+ * It is memoized rather than hoisted to a `const` because the toggle IS
+ * observed at runtime, contrary to what a quick look suggests: the
+ * cross-check and sampling suites flip `NODE_ENV` /
+ * `TURBINE_DISABLE_CACHE_CHECK` / `TURBINE_CACHE_CHECK_SAMPLE` around a
+ * synchronous block in-process, not at spawn. So the read is deferred to first
+ * use and {@link resetCacheCrossCheckEnv} re-arms it; that is the entire
+ * contract, and the only thing lost versus reading every time is that a
+ * process which mutates these variables mid-run must say so.
+ */
+let crossCheckEnv;
+function readCrossCheckEnv() {
+    let resolved;
     if (process.env.NODE_ENV !== 'production') {
-        return process.env.TURBINE_DISABLE_CACHE_CHECK === '1' ? 'off' : 'dev';
-    }
-    const raw = process.env.TURBINE_CACHE_CHECK_SAMPLE;
-    if (raw === undefined)
-        return 'off';
-    const rate = Number.parseFloat(raw);
-    if (!Number.isFinite(rate) || rate <= 0)
-        return 'off';
-    if (rate >= 1)
-        return 'sampled';
-    return Math.random() < rate ? 'sampled' : 'off';
+        resolved = { mode: process.env.TURBINE_DISABLE_CACHE_CHECK === '1' ? 'off' : 'dev' };
+    }
+    else {
+        const raw = process.env.TURBINE_CACHE_CHECK_SAMPLE;
+        const rate = raw === undefined ? Number.NaN : Number.parseFloat(raw);
+        resolved = !Number.isFinite(rate) || rate <= 0 ? { mode: 'off' } : { mode: 'sampled', rate };
+    }
+    crossCheckEnv = resolved;
+    return resolved;
+}
+/**
+ * Discard the memoized cross-check environment so the next cache hit re-reads
+ * `process.env`.
+ *
+ * @internal Exposed for the tests that toggle these variables in-process (see
+ * {@link crossCheckEnv}). Production code sets them before the first query and
+ * never again.
+ */
+export function resetCacheCrossCheckEnv() {
+    crossCheckEnv = undefined;
 }
 /**
  * Distinct cache-mismatch fingerprints already logged by the sampled production
@@ -380,6 +417,16 @@ export class QueryInterface {
      * inline, not through the top-level cache).
      */
     lastCacheHit = false;
+    /**
+     * Set while a build closure runs when the statement's WHERE (or HAVING)
+     * carries a caller-written `AND`/`OR` combinator array, i.e. when its SQL text
+     * is a function of an arity the caller chose. Read (and reset) by
+     * {@link acquireSql}, which brackets the single `build()` call, so the flag
+     * has no lifetime outside that synchronous window and cannot leak between
+     * queries. See {@link BuilderCtx.markVariableArity} for the unbounded
+     * server-side prepared-statement growth this exists to stop.
+     */
+    variableArityShape = false;
     middlewares;
     defaultLimit;
     warnOnUnlimited;
@@ -466,6 +513,17 @@ export class QueryInterface {
      * to Date as well (otherwise nested dates leak through as strings).
      */
     camelDateFieldCache = new Map();
+    /**
+     * Per-table memo of `Object.entries(meta.relations)`, consumed by the nested
+     * row parser (see `getRelationEntries` in relations.ts). Same rationale and
+     * same lifetime as {@link camelDateFieldCache}: the metadata is immutable, and
+     * the parser reads it once per row.
+     */
+    relationEntryCache = new Map();
+    /** Per-table memo of batched-loader child readers (see {@link batchedChild}). */
+    batchedChildCache = new Map();
+    /** The (option-invariant) options every batched child is built with. */
+    batchedChildOptions;
     /** True when this QI runs inside an active transaction (set via _txScoped option). */
     txScoped;
     /** Original options reference, forwarded to child QIs in nested writes. */
@@ -662,6 +720,9 @@ export class QueryInterface {
             set currentSkip(v) {
                 self.currentSkip = v;
             },
+            markVariableArity: () => {
+                this.variableArityShape = true;
+            },
             q: (name) => this.q(name),
             p: (index) => this.p(index),
             inParam: (values) => this.inParam(values),
@@ -679,6 +740,7 @@ export class QueryInterface {
             crossCheckCache: (op, cacheKey, entry, build, collectedParams) => this.crossCheckCache(op, cacheKey, entry, build, collectedParams),
             jsonEncoding: this.jsonEncoding,
             camelDateFieldCache: this.camelDateFieldCache,
+            relationEntryCache: this.relationEntryCache,
             limitOneClause: () => this.limitOneClause(),
             buildPagination: (limitPh, offsetPh, hasOrderBy) => this.buildPagination(limitPh, offsetPh, hasOrderBy),
             paginationRef: (value, params, arg) => this.paginationRef(value, params, arg),
@@ -1441,15 +1503,10 @@ export class QueryInterface {
     includePii, forceCustomPlan = false) {
         // The loader's own global-filter callback below needs the RESOLVED form.
         const resolvedSkip = resolveSkipGlobalFilters(skip);
-        const childOptions = {
-            ...this.options,
-            defaultLimit: undefined,
-            warnOnUnlimited: false,
-        };
         return {
             parentMeta: this.tableMeta,
             schema: this.schema,
-            makeChild: (table) => new QueryInterface(this.pool, table, this.schema, [], childOptions),
+            makeChild: (table) => this.batchedChild(table),
             // The per-query `forceCustomPlan` opt-in covers the relation follow-ups
             // too: a batched load re-issues the SAME tenant-shaped predicate one
             // level down, so leaving those named would keep exactly the plan-cache
@@ -1459,6 +1516,23 @@ export class QueryInterface {
             buildInClause: (expr, paramRef, negated) => this.inClause(expr, paramRef, negated),
             inClauseParam: (values) => this.inParam(values),
             paramPlaceholder: (index) => this.p(index),
+            // Bound each relation follow-up per correlation key when the engine can
+            // express it; absent leaves the loader on its client-side slice. Bound as
+            // a closure rather than passing `this.dialect` so the loader keeps
+            // needing nothing else from the dialect.
+            //
+            // The `dialect.name` test is NOT redundant with the hook's presence, and
+            // this is the same trap the `distinct` gate documents: every engine
+            // dialect is built by SPREADING `postgresDialect`, so an optional hook
+            // added there is INHERITED by sqlite / mysql / mssql, whose "absent"
+            // fallback would then never be taken. The wrapper is not portable as
+            // written either (T-SQL rejects an ORDER BY inside a derived table
+            // without TOP/OFFSET, and the compiled child query carries one), so the
+            // pushdown stays with the dialect that owns the implementation until
+            // another engine ships its own and asserts it.
+            buildPartitionLimit: this.dialect.name === 'postgresql' && this.dialect.buildPartitionLimit
+                ? (input) => this.dialect.buildPartitionLimit(input)
+                : undefined,
             skipGlobalFilters: skip,
             // Query-level opt-in threaded onto every follow-up child `buildFindMany`,
             // so a batched load excludes/includes PII exactly as the join strategy.
@@ -1480,6 +1554,36 @@ export class QueryInterface {
             },
         };
     }
+    /**
+     * The child {@link QueryInterface} the batched loader uses for `table`,
+     * memoized per table for the lifetime of this accessor.
+     *
+     * It used to be constructed fresh for every relation of every query, which
+     * threw away that child's SQL template cache each time: a relation follow-up
+     * therefore MISSED the cache on every single request and rebuilt its SQL,
+     * which is the one thing the template cache exists to avoid, and it allocated
+     * a whole QueryInterface (column type maps, camel-date memo, the ctx literal)
+     * per relation per query. `childOptions` was likewise a fresh spread per
+     * query although it is a pure function of this instance's options.
+     *
+     * Safe to share across queries: a QueryInterface holds no per-query state
+     * beyond the transient build fields, which live and die inside one
+     * synchronous `build*` call, and every child is bound to THIS instance's pool
+     * (so it still joins an active transaction) with `defaultLimit` cleared and
+     * unlimited-warnings silenced, because a relation load must fetch every
+     * matching child. Per-query values (`skipGlobalFilters`, `includePii`,
+     * `timeout`, `forceCustomPlan`) are passed as ARGUMENTS by the loader, never
+     * baked into the child, which is what makes the memo sound.
+     */
+    batchedChild(table) {
+        let child = this.batchedChildCache.get(table);
+        if (!child) {
+            this.batchedChildOptions ??= { ...this.options, defaultLimit: undefined, warnOnUnlimited: false };
+            child = new QueryInterface(this.pool, table, this.schema, [], this.batchedChildOptions);
+            this.batchedChildCache.set(table, child);
+        }
+        return child;
+    }
     /**
      * Run a findMany with the batched strategy: execute the base query WITHOUT
      * relation subqueries (all other clauses intact), then load each relation via
@@ -1564,9 +1668,7 @@ export class QueryInterface {
     acquireSql(cacheKey, build) {
         if (!this.sqlCacheEnabled) {
             this.lastCacheHit = false;
-            const sql = build([]);
-            this.cacheMisses++;
-            return { sql, name: sqlToPreparedName(sql) };
+            return this.buildCacheEntry(build);
         }
         const cached = this.sqlTemplateCache.get(cacheKey);
         if (cached) {
@@ -1575,12 +1677,38 @@ export class QueryInterface {
             return cached;
         }
         this.lastCacheHit = false;
-        const sql = build([]);
-        const entry = { sql, name: sqlToPreparedName(sql) };
+        const entry = this.buildCacheEntry(build);
         this.sqlTemplateCache.set(cacheKey, entry);
-        this.cacheMisses++;
         return entry;
     }
+    /**
+     * Run one build closure and pair its SQL with the prepared-statement name it
+     * should execute under.
+     *
+     * The `variableArityShape` flag is reset immediately BEFORE the build and read
+     * immediately AFTER it, so this method is the flag's entire lifetime: the
+     * build walk (`buildWhereClause` / `buildScopedWhere` / the HAVING combinator)
+     * is the only thing that can set it, nothing can observe a stale value, and a
+     * throw out of `build()` leaves nothing behind to affect the next query.
+     *
+     * An EMPTY name is how "send this unnamed" travels: `queryWithTimeout` tests
+     * the name for truthiness, so `''` takes the plain `(text, values)` form the
+     * driver never registers a named statement for. Doing it HERE rather than at
+     * the execute seam is what makes it survive the cache: the entry is created
+     * once, on the miss, and a later HIT reuses the same (empty) name, so a
+     * variable-arity shape can never acquire a name from a warmed template.
+     *
+     * See {@link BuilderCtx.markVariableArity} for what makes a shape
+     * variable-arity and the measured reason it must not be named.
+     */
+    buildCacheEntry(build) {
+        this.variableArityShape = false;
+        const sql = build([]);
+        const variableArity = this.variableArityShape;
+        this.variableArityShape = false;
+        this.cacheMisses++;
+        return { sql, name: variableArity ? '' : sqlToPreparedName(sql) };
+    }
     /**
      * Dev-mode SQL-cache lockstep cross-check (see {@link cacheCrossCheckEnabled}).
      *
@@ -1910,7 +2038,6 @@ export class QueryInterface {
         stripFields([entity], proj.strip);
         return entity;
     }
-    // biome-ignore lint/complexity/noBannedTypes: {} means "no with clause", matches TypedWithClause default
     buildFindUnique(args) {
         this.currentSkip = resolveSkipGlobalFilters(args.skipGlobalFilters);
         // Prisma compound-unique selector expansion (before global-filter merge and
@@ -2249,7 +2376,6 @@ export class QueryInterface {
         }
         return maxDepth;
     }
-    // biome-ignore lint/complexity/noBannedTypes: {} means "no with clause", matches TypedWithClause default
     buildFindMany(args) {
         this.currentSkip = resolveSkipGlobalFilters(args?.skipGlobalFilters);
         // Stable relation order (opt-in): fill PK-asc orderBy into unordered to-many
@@ -2270,6 +2396,32 @@ export class QueryInterface {
         if (args?.orderBy !== undefined && isEmptyOrderBy(args.orderBy)) {
             args = { ...args, orderBy: undefined };
         }
+        // Drop `orderBy` terms that sort by an expression an earlier term already
+        // sorted by, and `distinct` columns named twice. HERE, before the
+        // fingerprint, for the reason every other normalization in this method is
+        // here: the fingerprint, the SQL build and the param collect must all see
+        // ONE list, or the cache key and the statement it caches describe different
+        // queries. Rewritten into the array form, which flattens through
+        // `orderByEntries` to the identical entry list the object form does, so a
+        // caller who wrote no duplicate is untouched down to the cache key (the
+        // helpers return null unless something was actually dropped).
+        if (args?.orderBy !== undefined) {
+            const deduped = dedupeOrderEntries(this.tableMeta, orderByEntries(args.orderBy), this.table);
+            if (deduped) {
+                warnRedundantSortTerm(this.table, 'orderBy', deduped.dropped);
+                args = {
+                    ...args,
+                    orderBy: deduped.entries.map(([k, v]) => ({ [k]: v })),
+                };
+            }
+        }
+        if (args?.distinct && args.distinct.length > 0) {
+            const deduped = dedupeColumnList(this.tableMeta, args.distinct);
+            if (deduped) {
+                warnRedundantSortTerm(this.table, 'distinct', deduped.dropped);
+                args = { ...args, distinct: deduped.columns };
+            }
+        }
         // Deterministic pagination (opt-in): fill a PK-asc orderBy into a paginating
         // query that declares none, BEFORE fingerprinting so the ordered and
         // unordered shapes get distinct cache entries. No-op unless
@@ -2277,6 +2429,29 @@ export class QueryInterface {
         const implicitOrder = this.implicitPkOrderBy(args);
         if (implicitOrder)
             args = { ...args, orderBy: implicitOrder };
+        // `distinct` compiles to `SELECT DISTINCT ON (...)`, which is PostgreSQL
+        // syntax and nothing else's. Every other engine parsed it as far as the
+        // word `ON` and answered with a RAW driver error carrying no TURBINE_ code
+        // (SQLite: `near "ON": syntax error`; MySQL: ER_PARSE_ERROR), i.e. the one
+        // shape the typed-error surface exists to prevent. Refused with the same
+        // E017 the OTHER spelling of this feature already used, `groupBy({
+        // distinctOn })` in aggregates.ts, which was gated correctly all along.
+        //
+        // `dialect.name` rather than a new capability flag, deliberately, and this
+        // is the exception to the "capability flags, not engine names" rule the
+        // rest of the dialect follows: every engine dialect is built by SPREADING
+        // `postgresDialect`, so a flag defaulting to `true` would be inherited by
+        // all of them (which is the bug) and one defaulting to `false` would have
+        // to be re-declared on Postgres-compatible dialects that already work.
+        // The established precedent for exactly this feature is the `dialect.name`
+        // test in `buildDistinctOnSource`.
+        //
+        // Before the cache, like the two guards below, so a warmed template cannot
+        // serve the query the cold path refuses.
+        if (args?.distinct && args.distinct.length > 0 && this.dialect.name !== 'postgresql') {
+            throw new UnsupportedFeatureError('DISTINCT ON (findMany distinct)', this.dialect.name, 'findMany({ distinct }) requires PostgreSQL: SELECT DISTINCT ON is not portable. Group in ' +
+                'application code, or use groupBy({ by }) for one row per combination.');
+        }
         // `distinct` + relation orderBy is refused up front (E003): the distinct
         // path re-orders in an outer wrapper (`... AS "<table>_distinct" ORDER BY
         // <userOrder>`) where a correlated relation subquery (pick-row, `_count`,
@@ -2367,6 +2542,30 @@ export class QueryInterface {
             if (args?.distinct && args.distinct.length > 0) {
                 distinctCols = args.distinct.map((k) => this.toSqlColumn(k));
                 distinctPrefix = `DISTINCT ON (${distinctCols.join(', ')}) `;
+                // A MULTI-column `distinct` gives up its server-side prepared-statement
+                // name, for the same reason a caller-written `OR` array does and by the
+                // same mechanism (see markVariableArity). The channel here is ORDER, not
+                // arity: the column list is written into the SQL text one term at a
+                // time, so the reachable statement set is the ORDERED subsets of the
+                // table's columns. Measured on PostgreSQL 16, a seven-column table:
+                // 5,040 `distinct` permutations left 5,040 further permanent statements
+                // and took CachedPlanSource from 39.4 MB to 59.1 MB on ONE connection.
+                //
+                // UNNAMED rather than canonicalized, which is what `select` and the
+                // write `data` list do, and the asymmetry is the point. This list is
+                // re-emitted as the leading terms of the inner ORDER BY a few lines
+                // below, and with no `orderBy` at all PostgreSQL's choice of
+                // representative row per group is explicitly unpredictable, so
+                // reordering it could hand a caller a different row. Withholding the
+                // name changes no SQL text and therefore cannot. The cost is one extra
+                // server-side parse per execution on an already-rare query shape.
+                //
+                // `length > 1` because a single column has exactly one ordering and so
+                // no permutation space: the common `distinct: ['tenantId']` keeps its
+                // name. Repeats are already dropped upstream (dedupeColumnList), so the
+                // list here is distinct columns and nothing else.
+                if (args.distinct.length > 1)
+                    this.ctx.markVariableArity();
             }
             // Join-sink for `relationLoadStrategy: 'flatten'`. Filled while the SELECT
             // list is built (so the flattened relations' ON-clause params interleave
@@ -2634,7 +2833,6 @@ export class QueryInterface {
             return deferred.transform(result);
         });
     }
-    // biome-ignore lint/complexity/noBannedTypes: {} means "no with clause", matches TypedWithClause default
     buildFindFirst(args) {
         // Reuse findMany's SQL builder but force LIMIT 1
         const findManyArgs = { ...args, limit: 1 };
@@ -2659,7 +2857,6 @@ export class QueryInterface {
             return deferred.transform(result);
         });
     }
-    // biome-ignore lint/complexity/noBannedTypes: {} means "no with clause", matches TypedWithClause default
     buildFindFirstOrThrow(args) {
         const inner = this.buildFindFirst(args);
         return {
@@ -2689,7 +2886,6 @@ export class QueryInterface {
             return deferred.transform(result);
         });
     }
-    // biome-ignore lint/complexity/noBannedTypes: {} means "no with clause", matches TypedWithClause default
     buildFindUniqueOrThrow(args) {
         const inner = this.buildFindUnique(args);
         return {

package/dist/query/filters.d.ts

@@ -6,6 +6,7 @@
  * and execution rather than filter-shape bookkeeping.
  */
 import type { ArrayFilter, ColumnRef, JsonFilter, JsonPathOrderBy, OrderBySpec, OrderDirection, RelationPickOrderBy, TextSearchFilter, VectorFilter, VectorOrderBy, WhereOperator } from './types.js';
+import { type ColumnNameSource } from './utils.js';
 /** Check if a value is a where operator object (has at least one known operator key) */
 export declare function isWhereOperator(value: unknown): value is WhereOperator;
 /**
@@ -21,6 +22,41 @@ export declare function isUnmatchedPlainObject(value: unknown): boolean;
  * take values only.
  */
 export declare const COLUMN_REF_OPERATORS: Set<string>;
+/**
+ * THE relation-filter wrappers: the keys whose body is a clause against the
+ * relation's TARGET table rather than against this one.
+ *
+ * One named list, here, because everything that walks a where clause has to
+ * agree about them and the copies had already spread. It lived inlined in
+ * `where-compile.ts` (`'some' in x || 'every' in x || …`, the SQL compiler's
+ * own answer), again in `normalizeRelationFilter` (where.ts) as the negated
+ * conjunction of the same five, again in `cli/pii-predicate-guard.ts`, and a
+ * fourth time in `prisma-compat.ts` SPLIT across a
+ * `RELATION_QUANTIFIERS` set (`some`/`every`/`none`) plus two inline
+ * `k === 'is' || k === 'isNot'` tests, which is the copy most likely to drift
+ * because half of it does not read as a list and a grep for the list does not
+ * find it.
+ *
+ * The failure mode is not cosmetic: a wrapper the SQL compiler treats as a
+ * relation filter but a WALKER does not is a wrapper whose body reaches the
+ * builder unwalked. That is precisely the operand-position channel this
+ * release closed elsewhere.
+ *
+ * `query/` is the right home rather than `cli/` because the direction of the
+ * dependency is fixed: `cli/` and the prisma-compat shim may import from the
+ * query path, and the query path may never import from `cli/`
+ * (`scripts/check-import-cycles.mjs`).
+ */
+export declare const RELATION_FILTER_WRAPPERS: readonly ["some", "none", "every", "is", "isNot"];
+/** {@link RELATION_FILTER_WRAPPERS} as a membership set, for the walkers. */
+export declare const RELATION_FILTER_WRAPPER_SET: ReadonlySet<string>;
+/**
+ * True when a normalized relation-filter body carries at least one cardinality
+ * wrapper. THE predicate the SQL compiler branches on: a key that names a
+ * relation but whose value is not one of these falls through to the scalar
+ * path.
+ */
+export declare function hasRelationFilterWrapper(filterObj: Record<string, unknown>): boolean;
 /**
  * Check if an operator value is a column reference: a plain object whose ONLY
  * key is `col` with a string value. Anything else (extra keys, non-string
@@ -210,6 +246,132 @@ export declare function isRelationPickOrderBy(value: unknown): value is Relation
  * lockstep across build, param-collect, and cache-key fingerprint.
  */
 export declare function orderByEntries(orderBy: unknown): [string, unknown][];
+/**
+ * The longest `orderBy` whose statement keeps a NAMED prepared statement.
+ * Past this, the compile paths call `markVariableArity` and the statement is
+ * sent unnamed for the same reason a caller-written `OR` array is.
+ *
+ * WHY 3, and why a threshold at all. Refusing duplicate sort keys
+ * ({@link dedupeOrderEntries}) bounds an `orderBy` to the table's column
+ * count, which sounds like enough and is not: what is left is the PERMUTATION
+ * space. A 20-column table admits 20 one-key sorts, 380 two-key sorts, 6,840
+ * three-key sorts and 116,280 four-key sorts, and every one of those is a
+ * distinct SQL text and therefore a distinct un-reclaimable server-side
+ * prepared statement. The count is dominated by its longest term, so a cap on
+ * LENGTH is what actually bounds the total.
+ *
+ * 3 because that is where real sorts stop and generated ones start. The two
+ * shapes that show up in application code are a single sort key, and a sort key
+ * plus a tiebreaker for stable pagination (`[{createdAt:'desc'},{id:'asc'}]`).
+ * Three covers the widest genuinely hand-written form, a category or priority
+ * followed by recency followed by a primary-key tiebreak. A fourth key is
+ * effectively always a UI that lets the caller stack sort columns, which is
+ * exactly the shape that should not be minting named statements. The asymmetry
+ * of the two errors also points this way: naming a 4-key sort risks the 116,280
+ * above, while NOT naming one costs a single extra server-side parse per
+ * execution on a query that is already rare.
+ */
+export declare const MAX_NAMED_ORDER_KEYS = 3;
+/**
+ * Canonical identity of ONE order term's sort EXPRESSION, or `null` when this
+ * rule declines to decide for that shape.
+ *
+ * DIRECTION IS DELIBERATELY EXCLUDED. `ORDER BY id ASC, id DESC` sorts exactly
+ * like `ORDER BY id ASC`: the first term already totally orders the rows it
+ * covers, so no later term on the same expression can move anything, whichever
+ * way it points. Including the direction would have missed the very case that
+ * motivated this, a pair of entries spelled differently AND pointing
+ * differently.
+ *
+ * The column is RESOLVED rather than compared as spelled, via the same
+ * `resolveColumnName` every SQL builder resolves keys through, so `userId` and
+ * `user_id` on an introspected schema are recognised as the one column they
+ * both compile to. Falls back to the raw key when the key resolves to nothing
+ * (metadata-less test schemas): the compile path a few lines later is what
+ * reports an unknown field, and this function must not pre-empt that error with
+ * a worse one.
+ *
+ * `null` (not compared) for two shapes:
+ *  - VECTOR KNN ordering. Two distance terms on one column with DIFFERENT
+ *    target vectors are genuinely different expressions and the second is not a
+ *    no-op, so deciding would mean hashing the operand, which is a 1,536-float
+ *    array on a typical embedding column. Not worth the per-build cost for a
+ *    shape that {@link MAX_NAMED_ORDER_KEYS} already bounds.
+ *  - RELATION ordering (`{posts:{_count:'desc'}}`, `{author:{name:'asc'}}`,
+ *    pick-row). Same reason in a different key: the expression is a correlated
+ *    subquery whose identity is its whole nested shape.
+ * Both are bounded by the length cap; neither can be refused wrongly here.
+ */
+export declare function orderKeyIdentity(meta: ColumnNameSource | undefined, key: string, value: unknown): string | null;
+/** One term dropped as redundant: the key removed, and the key that outranked it. */
+export interface DroppedTerm {
+    key: string;
+    first: string;
+    /** What both keys resolved to: a column name, or a groupBy SELECT expression. */
+    resolved: string;
+}
+/**
+ * Remove `orderBy` entries that sort by an expression an earlier entry already
+ * sorted by. Returns `null` when nothing is redundant, which is the common case
+ * and the one that must stay allocation-light and byte-identical.
+ *
+ * WHY THIS DROPS RATHER THAN REFUSES, because the reverse was specified and the
+ * premise turned out not to hold. A repeated sort key is a no-op in SQL, and it
+ * is the only way to push an `orderBy` past the table's column count (measured:
+ * `[{id:'asc'}] x n` produced a distinct named prepared statement for every n,
+ * from ONE column, with no ceiling short of the request body size). Both of
+ * those are true. What is NOT true is that it is always a caller bug. The
+ * idiomatic stable-pagination shape is
+ *
+ *     orderBy: [{ [sortField]: sortDir }, { id: 'asc' }]
+ *
+ * appending a primary-key tiebreak unconditionally, which is correct defensive
+ * code, and which produces a duplicate exactly when the caller sorts by the
+ * primary key. That is a column header a user clicks, so refusing would turn a
+ * working table into a 500 on one column and no others. This repo's own
+ * differential fuzz generator writes that pattern, comment included ("a random
+ * key first, the PK as final tiebreaker"), and picks the sort field from a pool
+ * that contains `id`, so a refusal would have failed the suite on 10-35% of
+ * generated cases depending on table width.
+ *
+ * Dropping has no such failure mode: the removed term provably cannot move a
+ * row, so the result set and its order are unchanged, and the caller is told
+ * about the redundancy through a dev-only warn-once instead of an exception.
+ * The security outcome is identical, because what actually bounds the emitted
+ * statement set is the length cap ({@link MAX_NAMED_ORDER_KEYS}), which is
+ * shape-blind and applies to repeats and permutations alike. This function's
+ * job is narrower: keep the ordinary two-key sort under that cap so it keeps
+ * its named statement.
+ *
+ * A DROPPED TERM IS STILL VALIDATED, see {@link assertDroppedDirection}. The
+ * drop is an optimization, and an optimization must not decide whether an input
+ * is legal.
+ *
+ * @param table the table the sort is against, so a refused direction reads
+ *   exactly as it does when the compile path raises it. Defaults to the
+ *   metadata's own name, which is what a caller holding only a `TableMetadata`
+ *   would have passed anyway.
+ */
+export declare function dedupeOrderEntries(meta: ColumnNameSource | undefined, entries: [string, unknown][], table?: string | undefined): {
+    entries: [string, unknown][];
+    dropped: DroppedTerm[];
+} | null;
+/**
+ * The {@link dedupeOrderEntries} rule applied to a `DISTINCT ON` column list,
+ * the other caller-supplied list written into the SQL one term per element.
+ * `DISTINCT ON (a, a)` groups exactly as `DISTINCT ON (a)` does, so a repeat is
+ * a no-op here too, and the same generated-code shape produces it (a grouping
+ * column chosen by the caller, plus a fixed one appended by the code).
+ *
+ * No length cap to go with it, deliberately. Unlike `orderBy`, `DISTINCT ON`
+ * has a meaning that degrades as the list grows (every added column makes the
+ * result strictly less distinct, converging on the plain query), so a long list
+ * is self-limiting in a way a long sort is not.
+ */
+export declare function dedupeColumnList(meta: ColumnNameSource | undefined, columns: readonly string[]): {
+    columns: string[];
+    dropped: DroppedTerm[];
+} | null;
 /**
  * Normalize an orderBy value into `{ direction, nulls }`. Accepts a plain
  * direction string or an {@link OrderBySpec}. Used by every ORDER BY compile