turbine-orm 0.65.0 → 0.66.0

package/dist/query/where.d.ts

@@ -59,6 +59,62 @@ export interface BuilderCtx {
      * `resolveGlobalFilter`.
      */
     currentSkip: ResolvedSkipGlobalFilters | undefined;
+    /**
+     * Record that the statement being COMPILED right now has a SQL text whose
+     * LENGTH is a function of an arity the caller chose, rather than of the
+     * application's code. Two shapes qualify:
+     *
+     *  1. a caller-written `AND` / `OR` combinator array (one parenthesised
+     *     branch per element), marked in {@link buildWhereClause} and its
+     *     table-scoped twin;
+     *  2. an `orderBy` longer than {@link MAX_NAMED_ORDER_KEYS} (one comma-
+     *     separated term per entry), marked in relations.ts' `buildOrderBy` and
+     *     `buildRelationOrderClause`.
+     *
+     * WHY THIS EXISTS, since it is the only "tell the builder something about the
+     * shape" callback on this interface. Every distinct SQL text Turbine emits is
+     * parsed on the server as a NAMED prepared statement (the name is a hash of
+     * the text) and is never DEALLOCATEd. The client-side template cache is an
+     * LRU bounded at 1,000 entries; the SERVER side has no bound at all, and each
+     * pooled connection accumulates its own. That is fine while the set of SQL
+     * texts is fixed by the application's code, which it is for every clause
+     * except these: a `where.OR` assembled from a UI multi-select, or an
+     * `orderBy` assembled from an "advanced sort" panel, lets a caller mint
+     * unbounded distinct statements with no identifier and no value under their
+     * control. Measured on PostgreSQL 16: 600 distinct `OR` arities left 600
+     * prepared statements and 20.9 MB of CachedPlan memory resident on ONE
+     * connection, and 200 further executions of an existing shape reclaimed none
+     * of it. The `orderBy` half was measured the same way and is worse in one
+     * respect: repeating a single key (`[{id:'asc'}, {id:'asc'}, ...]`) reached
+     * eight distinct statements from ONE column, so the arity was not even
+     * bounded by the table's width. That particular door is closed separately and
+     * more directly, by refusing duplicate sort keys outright
+     * ({@link dedupeOrderEntries}); this mark handles what remains, which is
+     * the PERMUTATION space of distinct columns.
+     *
+     * `in: [...]` is deliberately NOT this shape and is not marked: it binds
+     * `= ANY($1)`, one parameter whatever the list length, so a thousand-element
+     * `in` is still one statement.
+     *
+     * What the mark does: {@link acquireSql} reads it immediately after the build
+     * closure returns and gives the cache entry an EMPTY prepared-statement name,
+     * so every execution of that shape goes out unnamed. Unnamed is what bounds
+     * the server: node-postgres only skips `Parse` for a statement it has already
+     * parsed BY NAME, so an unnamed statement is re-parsed each execution and
+     * replaces the single unnamed cached plan source instead of adding to the
+     * named table. It is the same mechanism the per-query `forceCustomPlan`
+     * option uses, and it changes NO SQL text.
+     *
+     * The cost is honest and worth stating: a fixed two-branch `OR` (a search box
+     * over name and email, say) is not actually variable-arity, and it loses its
+     * named statement too, because the builder sees one call and cannot know
+     * whether the length varies across calls. It pays one server-side parse per
+     * execution and gives up generic-plan promotion, which for a skewed predicate
+     * is frequently the better plan anyway. The `orderBy` threshold is chosen so
+     * that this cost lands only on shapes that are already unusual: see
+     * {@link MAX_NAMED_ORDER_KEYS}.
+     */
+    markVariableArity(): void;
     q(name: string): string;
     p(index: number): string;
     inParam(values: unknown): unknown;
@@ -76,6 +132,13 @@ export interface BuilderCtx {
     crossCheckCache(op: string, cacheKey: string, entry: SqlCacheEntry, build: (params: unknown[]) => string, collectedParams: unknown[]): void;
     readonly jsonEncoding: 'object' | 'positional';
     readonly camelDateFieldCache: Map<string, Set<string>>;
+    /**
+     * Per-table memo of `Object.entries(meta.relations)`. See
+     * `getRelationEntries` in relations.ts: the nested-row parser walks it once
+     * per ROW, so rebuilding the array there was the hottest allocation in the
+     * parse path.
+     */
+    readonly relationEntryCache: Map<string, [string, RelationDef][]>;
     limitOneClause(): string;
     buildPagination(limitPh: string | undefined, offsetPh: string | undefined, hasOrderBy: boolean): string;
     paginationRef(value: unknown, params: unknown[], arg?: string): string;
@@ -138,7 +201,7 @@ interface WhereScope {
  *
  * @internal Exposed as package-private for testing via class access.
  */
-export declare function fingerprintWhere(qi: BuilderCtx, where: Record<string, unknown>): string;
+export declare function fingerprintWhere(qi: BuilderCtx, where: Record<string, unknown>, depth?: number): string;
 /**
  * Fingerprint the present branches of a normalized relation filter, in the
  * fixed order some→every→none→is→isNot. A `null` branch tokenizes as
@@ -146,14 +209,14 @@ export declare function fingerprintWhere(qi: BuilderCtx, where: Record<string, u
  * {@link fingerprintRelFilter} so the FULL inner shape is captured (two
  * different sub-wheres must never collide on one cached SQL text).
  */
-export declare function fingerprintRelationParts(qi: BuilderCtx, relDef: RelationDef, filterObj: WhereRecord): string[];
+export declare function fingerprintRelationParts(qi: BuilderCtx, relDef: RelationDef, filterObj: WhereRecord, depth?: number): string[];
 /**
  * Fingerprint a relation filter sub-where for some/every/none. Thin wrapper
  * over the unified {@link fingerprintScopedWhere}. When the target table is
  * unknown, an empty-relations host makes every key scalar (matching the old
  * `meta?.relations` short-circuit).
  */
-export declare function fingerprintRelFilter(qi: BuilderCtx, targetTable: string, subWhere: Record<string, unknown>): string;
+export declare function fingerprintRelFilter(qi: BuilderCtx, targetTable: string, subWhere: Record<string, unknown>, depth?: number): string;
 /**
  * Walk a where clause and push ONLY values into `params`, in the EXACT same
  * order that `buildWhereClause` pushes them. Used on cache hit to fill params
@@ -161,7 +224,7 @@ export declare function fingerprintRelFilter(qi: BuilderCtx, targetTable: string
  *
  * @internal Exposed as package-private for testing.
  */
-export declare function collectWhereParams(qi: BuilderCtx, where: Record<string, unknown>, params: unknown[]): void;
+export declare function collectWhereParams(qi: BuilderCtx, where: Record<string, unknown>, params: unknown[], depth?: number): void;
 /**
  * Push a scalar WHERE value's params, mirroring {@link buildScalarClause}'s
  * emissions exactly. Both resolve the value's shape via the shared
@@ -182,8 +245,8 @@ export declare function collectScalarParams(qi: BuilderCtx, key: string, value:
  * Shared by every collect site that mirrors buildRelationFilter
  * (collectWhereParams, collectRelFilterParams, collectAliasWhereParams).
  */
-export declare function collectRelationFilterParams(qi: BuilderCtx, relDef: RelationDef, filterObj: Record<string, unknown>, params: unknown[]): void;
-export declare function collectRelFilterParams(qi: BuilderCtx, targetTable: string, subWhere: Record<string, unknown>, params: unknown[]): void;
+export declare function collectRelationFilterParams(qi: BuilderCtx, relDef: RelationDef, filterObj: Record<string, unknown>, params: unknown[], depth?: number): void;
+export declare function collectRelFilterParams(qi: BuilderCtx, targetTable: string, subWhere: Record<string, unknown>, params: unknown[], depth?: number): void;
 /**
  * Collect params from operator clauses. Mirrors buildOperatorClauses:
  * {@link ColumnRef} values compile into the SQL text, so they push NOTHING -
@@ -203,7 +266,9 @@ export declare function collectArrayFilterParams(qi: BuilderCtx, filter: ArrayFi
 /**
  * Collect params for a vector distance WHERE filter. Mirrors
  * {@link buildVectorFilterClauses}: the `$n::vector` query vector first, then
- * the comparison threshold(s).
+ * the comparison threshold(s), both enumerated AND validated by the shared
+ * {@link vectorThresholdEntries} (see there for the production-only bug that
+ * inlining the loop on both sides produced).
  */
 export declare function collectVectorFilterParams(qi: BuilderCtx, field: string, rawColumn: string, filter: VectorFilter, params: unknown[]): void;
 /** Build WHERE clause from a where object (supports operators, NULL, OR) */
@@ -267,7 +332,7 @@ export declare function assertMutationHasPredicate(qi: BuilderCtx, operation: 'u
  * Returns null if no conditions exist.
  * Supports: equality, operators, NULL, OR, AND, NOT, relation filters (some/every/none).
  */
-export declare function buildWhereClause(qi: BuilderCtx, where: Record<string, unknown>, params: unknown[]): string | null;
+export declare function buildWhereClause(qi: BuilderCtx, where: Record<string, unknown>, params: unknown[], depth?: number): string | null;
 /**
  * Emit the SQL clause(s) for one scalar WHERE key onto `andClauses`, pushing
  * any params. The shape decision comes from the shared
@@ -295,7 +360,7 @@ export declare function aliasWhereScope(qi: BuilderCtx, targetTable: string, met
  * former hand-mirrored walkers, since it renders the same clauses in the same
  * ({@link walkWhere}-canonical) key order.
  */
-export declare function buildScopedWhere(qi: BuilderCtx, scope: WhereScope, where: Record<string, unknown>, params: unknown[]): string | null;
+export declare function buildScopedWhere(qi: BuilderCtx, scope: WhereScope, where: Record<string, unknown>, params: unknown[], depth?: number): string | null;
 /**
  * Emit the SQL clause(s) for one scalar key of a scoped sub-where. Reproduces
  * the null / JSON / array / operator / equality fall-through both former
@@ -311,7 +376,7 @@ export declare function buildScopedScalarClause(qi: BuilderCtx, scope: WhereScop
  * without rebuilding SQL. Serves both {@link collectRelFilterParams} and
  * {@link collectAliasWhereParams}.
  */
-export declare function collectScopedWhereParams(qi: BuilderCtx, scope: WhereScope, where: Record<string, unknown>, params: unknown[]): void;
+export declare function collectScopedWhereParams(qi: BuilderCtx, scope: WhereScope, where: Record<string, unknown>, params: unknown[], depth?: number): void;
 /** Param-collect mirror of {@link buildScopedScalarClause}. */
 export declare function collectScopedScalarParams(qi: BuilderCtx, scope: WhereScope, field: string, value: unknown, params: unknown[]): void;
 /**
@@ -323,17 +388,24 @@ export declare function collectScopedScalarParams(qi: BuilderCtx, scope: WhereSc
  * may differ from the pre-unification walkers as long as collisions stay
  * impossible.
  */
-export declare function fingerprintScopedWhere(qi: BuilderCtx, host: WhereHost, where: Record<string, unknown>): string;
+export declare function fingerprintScopedWhere(qi: BuilderCtx, host: WhereHost, where: Record<string, unknown>, depth?: number): string;
 /**
  * Build relation filter SQL: WHERE EXISTS / NOT EXISTS subquery
  * Supports: some (EXISTS), every (NOT EXISTS ... NOT), none (NOT EXISTS)
  */
-export declare function buildRelationFilter(qi: BuilderCtx, _relName: string, relDef: RelationDef, filterObj: Record<string, unknown>, params: unknown[], parentTable?: string): string | null;
+export declare function buildRelationFilter(qi: BuilderCtx, _relName: string, relDef: RelationDef, filterObj: Record<string, unknown>, params: unknown[], parentTable?: string, 
+/**
+ * Nesting depth of the WHERE walk that reached this relation filter. Each
+ * relation descent is a level too: `{ posts: { some: { comments: { some:
+ * … } } } }` recurses through here just as `NOT` does, and is exactly as
+ * unbounded without a cap (see {@link assertWhereDepth}).
+ */
+depth?: number): string | null;
 /**
  * Build WHERE clause conditions for a relation filter subquery.
  * Uses the target table's column mapping to resolve field names.
  */
-export declare function buildSubWhereForRelation(qi: BuilderCtx, targetTable: string, subWhere: Record<string, unknown>, params: unknown[]): string | null;
+export declare function buildSubWhereForRelation(qi: BuilderCtx, targetTable: string, subWhere: Record<string, unknown>, params: unknown[], depth?: number): string | null;
 /**
  * Resolve a column's Postgres type from an arbitrary table's metadata
  * (relation targets, not just `qi.table`).
@@ -440,6 +512,26 @@ export declare function buildOperatorClauses(qi: BuilderCtx, column: string, op:
  * gate) so the two paths can never diverge.
  */
 export declare function requireFullTextSearch(qi: BuilderCtx): void;
+/**
+ * Gate the pathless JSON containment filters (`contains`, and the `equals`
+ * spelling that compiles to the same expression) on
+ * {@link Dialect.supportsJsonContains}.
+ *
+ * The engine this exists for is SQLite, whose emulation compares a decoded
+ * `json_each.value` against a param bound as JSON TEXT and therefore matched
+ * NOTHING, for every operand type: object, array, string and number alike all
+ * returned zero rows where PostgreSQL and MySQL returned the document (measured
+ * in-process, table in dialect.ts). Fewer rows with no error is precisely what
+ * the capability contract exists to convert into a refusal, and since the
+ * feature never worked there, refusing it removes nothing.
+ *
+ * Called from BOTH the build and the param-collect side, and here that is
+ * load-bearing rather than symmetric-for-its-own-sake: a {@link JsonFilter}
+ * fingerprints by which KEYS are present, not by what they hold, so every
+ * `contains` on a column shares one cache entry and a build-only gate would be
+ * skipped for the entire warm life of that entry.
+ */
+export declare function requireJsonContains(qi: BuilderCtx, clause: 'contains' | 'equals'): void;
 /**
  * Gate the array filter operators (`has` / `hasEvery` / `hasSome` / `isEmpty`)
  * on {@link Dialect.supportsArrayColumns}. They compile to PostgreSQL array
@@ -562,6 +654,29 @@ export declare function buildArrayFilterClauses(qi: BuilderCtx, column: string,
  * {@link collectVectorFilterParams}.
  */
 export declare function buildVectorFilterClauses(qi: BuilderCtx, field: string, rawColumn: string, filter: VectorFilter, params: unknown[]): string[];
+/**
+ * Validate and enumerate the distance comparisons on a vector filter, in the
+ * fixed {@link VECTOR_DISTANCE_COMPARATORS} order. Shared by the SQL-build path
+ * ({@link buildVectorFilterClauses}) and the cache-hit param-collect path
+ * ({@link collectVectorFilterParams}), exactly like {@link jsonRangeEntries}.
+ *
+ * IT IS THE VALIDATION THAT MAKES THIS SHARED, not the enumeration. Both sides
+ * used to inline the same `for` loop, and only the build side checked the
+ * threshold. That build side does not run on a cache HIT, and outside dev the
+ * lockstep cross-check (which re-runs it, and is what masked this) is off, so a
+ * warmed template bound `lt: NaN`, `lt: '5'` or `lt: { a: 1 }` straight into
+ * the statement. NaN is the one that matters: Postgres sorts it above every
+ * real distance, so `distance < NaN` matches EVERY row, i.e. the predicate
+ * inverts, silently, in production only. Same bug class as the 0.19.2 /
+ * 0.32.1 cache-hit drifts, and the same fix: one function, both paths.
+ *
+ * The "at least one comparison" refusal lives here too, so the collect path
+ * cannot quietly accept a filter the build path rejects.
+ */
+export declare function vectorThresholdEntries(filter: VectorFilter, field: string): {
+    sqlOp: string;
+    threshold: number;
+}[];
 /**
  * Build SQL clause for full-text search using to_tsvector @@ to_tsquery.
  * The config name is validated to prevent injection (only alphanumeric + underscore).