turbine-orm 0.81.0 → 0.90.0

package/dist/query/where.d.ts

@@ -10,14 +10,17 @@
  * instance (built once in its constructor) exposing exactly the class-resident
  * primitives this module needs. See builder.ts for the thin delegating methods.
  */
+import { type ResolvedDiagnostics } from '../diagnostics.js';
 import type { Dialect } from '../dialect.js';
 import { ValidationError } from '../errors.js';
+import { type TurbineLogger } from '../logger.js';
 import type { PgCompatQueryResult } from '../pg-types.js';
 import type { RelationDef, SchemaMetadata, TableMetadata } from '../schema.js';
 import type { TemporalInfinityReading } from './deferred.js';
 import type { ArrayFilter, ColumnRef, GlobalFilters, JsonEncoding, JsonFilter, JsonPathOrderBy, ResolvedSkipGlobalFilters, TextSearchFilter, VectorFilter, WhereClause, WhereOperator } from './types.js';
 import { type SqlCacheEntry } from './utils.js';
 import { type WhereHost, type WhereRecord } from './where-compile.js';
+export { assertJsonFilterKeys } from './filters.js';
 /**
  * The privacy-preserving view of a {@link QueryInterface} instance passed as the
  * first argument to every function in this module. Built once as an object
@@ -51,6 +54,14 @@ export interface BuilderCtx {
      * default.
      */
     readonly temporalInfinity?: TemporalInfinityReading;
+    /**
+     * The owning client's resolved `diagnostics`. Resolved once, at client
+     * construction; the modules never read the environment. Read through
+     * {@link adviceLogger}.
+     */
+    readonly diagnostics?: ResolvedDiagnostics;
+    /** The owning client's logger. Read through {@link adviceLogger}. */
+    readonly logger?: TurbineLogger;
     readonly crossSchemaTypeColumns: Set<string>;
     /**
      * The active query's `skipGlobalFilters` opt-out. A live getter/setter over
@@ -158,6 +169,16 @@ export interface BuilderCtx {
      */
     paginationValue(value: unknown, arg?: string): number;
 }
+/**
+ * Where per-query advice goes for this context: the client's logger when its
+ * `diagnostics.advice` is on, else `undefined`. A site calls this first and
+ * builds its message only on a logger.
+ *
+ * A context without the client's diagnostics (one built by hand) resolves
+ * them here; every context a QueryInterface builds carries them, so on a query
+ * path this never reads the environment.
+ */
+export declare function adviceLogger(qi: Pick<BuilderCtx, 'diagnostics' | 'logger'>): TurbineLogger | undefined;
 /**
  * Column-reference resolution context threaded into
  * {@link QueryInterface.buildOperatorClauses} / `collectOperatorParams`: the
@@ -177,6 +198,12 @@ interface ColumnRefContext {
      * from here instead, the one value both sides pass identically.
      */
     rawColumn: string;
+    /**
+     * The column's type token, which decides what its operands may be (see
+     * `operandColumnKind`). Resolved by the caller from the same source its
+     * classification used, identically on the build and collect side.
+     */
+    pgType: string;
 }
 /**
  * A table-scoped WHERE compilation context for a sub-where that is NOT the
@@ -219,10 +246,11 @@ interface WhereScope {
 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
- * `<branch>(null)`; a present branch recurses through
+ * fixed order some→every→none→is→isNot. A present branch recurses through
  * {@link fingerprintRelFilter} so the FULL inner shape is captured (two
- * different sub-wheres must never collide on one cached SQL text).
+ * different sub-wheres must never collide on one cached SQL text). `is: null`
+ * and `isNot: null` tokenize as `<branch>(null)`; the where walk refuses any
+ * other non-object value before this runs.
  */
 export declare function fingerprintRelationParts(qi: BuilderCtx, relDef: RelationDef, filterObj: WhereRecord, depth?: number): string[];
 /**
@@ -235,11 +263,12 @@ export declare function fingerprintRelFilter(qi: BuilderCtx, targetTable: 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
- * without rebuilding SQL.
+ * without rebuilding SQL. Returns whether the clause compiles to a condition,
+ * i.e. whether `buildWhereClause` returns non-null for it.
  *
  * @internal Exposed as package-private for testing.
  */
-export declare function collectWhereParams(qi: BuilderCtx, where: Record<string, unknown>, params: unknown[], depth?: number): void;
+export declare function collectWhereParams(qi: BuilderCtx, where: Record<string, unknown>, params: unknown[], depth?: number): boolean;
 /**
  * Push a scalar WHERE value's params, mirroring {@link buildScalarClause}'s
  * emissions exactly. Both resolve the value's shape via the shared
@@ -259,14 +288,18 @@ export declare function collectScalarParams(qi: BuilderCtx, key: string, value:
  * the gf calls are no-ops, so this stays byte-identical to the pre-0.28 path.
  * Shared by every collect site that mirrors buildRelationFilter
  * (collectWhereParams, collectRelFilterParams, collectAliasWhereParams).
+ * Returns whether {@link buildRelationFilter} emits a clause for it.
  */
-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;
+export declare function collectRelationFilterParams(qi: BuilderCtx, relDef: RelationDef, filterObj: Record<string, unknown>, params: unknown[], depth?: number): boolean;
+/** Collect a relation sub-where's params; returns whether it compiles to a condition. */
+export declare function collectRelFilterParams(qi: BuilderCtx, targetTable: string, subWhere: Record<string, unknown>, params: unknown[], depth?: number): boolean;
 /**
  * Collect params from operator clauses. Mirrors buildOperatorClauses:
  * {@link ColumnRef} values compile into the SQL text, so they push NOTHING -
  * but they re-run the same validation (unknown ref / insensitive mode) so a
- * warmed cache can never skip a check the build path enforces.
+ * warmed cache can never skip a check the build path enforces. The operand
+ * validation ({@link assertOperatorOperands}) runs here too, for the same
+ * reason.
  */
 export declare function collectOperatorParams(qi: BuilderCtx, column: string, op: WhereOperator, params: unknown[], refCtx?: ColumnRefContext): void;
 /**
@@ -277,7 +310,7 @@ export declare function collectOperatorParams(qi: BuilderCtx, column: string, op
  */
 export declare function collectJsonFilterParams(qi: BuilderCtx, filter: JsonFilter, params: unknown[], column: string): void;
 /** Collect params from array filter. Mirrors buildArrayFilterClauses. */
-export declare function collectArrayFilterParams(qi: BuilderCtx, filter: ArrayFilter, params: unknown[]): void;
+export declare function collectArrayFilterParams(qi: BuilderCtx, filter: ArrayFilter, params: unknown[], column: string): void;
 /**
  * Collect params for a vector distance WHERE filter. Mirrors
  * {@link buildVectorFilterClauses}: the `$n::vector` query vector first, then
@@ -295,16 +328,24 @@ export declare function buildWhere<T extends object>(qi: BuilderCtx, where: Wher
  * THE global-filter resolution rule, with no dependency on a `BuilderCtx`.
  *
  * Split out from {@link resolveGlobalFilter} so `PowqlInterface` can consume
- * the SAME rule rather than a transcription of it. It is a parallel
- * implementation of the public surface, and this repository's history is
- * unambiguous that a rule written twice is how two engines come to disagree
- * (the 0.64 projection resolver, the 0.73 findUnique guard). Every clause here
- * is load-bearing on both engines: a function filter is evaluated PER BUILD so
- * per-request tenancy works, an all-undefined filter is treated as absent so it
- * cannot emit a dangling clause, and `skip` is honoured in both its whole-query
- * and per-table forms.
+ * the SAME rule rather than a transcription of it: a rule written twice is how
+ * two engines come to disagree. A function filter is evaluated PER BUILD so
+ * per-request tenancy works, and `skip` is honoured in both its whole-query and
+ * per-table forms.
+ *
+ * FAIL CLOSED. A filter that resolves to `undefined`, or to an object holding
+ * an `undefined` anywhere inside it, throws {@link ValidationError} (E003). A
+ * missing tenant context is exactly what produces `{ tenantId: undefined }`,
+ * and treating that as "no filter" read and wrote every tenant's rows. The
+ * explicit values `null` and `{}` still mean "no filter for this call": neither
+ * is what a missing value produces.
+ *
+ * A `skipGlobalFilters` list names tables by table name or client accessor,
+ * the two spellings `globalFilters` keys take. With `tables` (the schema's
+ * table map), an entry that names no table is refused (E003): it would skip
+ * nothing, so the caller who meant to lift a filter would silently keep it.
  */
-export declare function resolveGlobalFilterFrom(filters: GlobalFilters | undefined, table: string, skip: ResolvedSkipGlobalFilters | undefined): Record<string, unknown> | null;
+export declare function resolveGlobalFilterFrom(filters: GlobalFilters | undefined, table: string, skip: ResolvedSkipGlobalFilters | undefined, tables?: Readonly<Record<string, unknown>>): Record<string, unknown> | null;
 /**
  * Resolve the configured global filter for `table`, evaluating a function
  * filter, honoring the active query's `skipGlobalFilters`. Returns `null` when
@@ -317,6 +358,13 @@ export declare function resolveGlobalFilter(qi: BuilderCtx, table: string, skip?
  * reference, so fingerprints/SQL stay byte-identical to the pre-0.28 path.
  */
 export declare function mergeGlobalFilter(qi: BuilderCtx, userWhere: Record<string, unknown> | undefined): Record<string, unknown> | undefined;
+/**
+ * Apply `table`'s global filter as a relation target: `apply(gf)` with the
+ * table on the stack, or `none` when no filter applies or the table's filter
+ * is already being compiled further out (see {@link filtersBeingApplied}).
+ * Every target application goes through here, build and collect alike.
+ */
+export declare function withTargetGlobalFilter<T>(qi: BuilderCtx, table: string, none: T, apply: (gf: Record<string, unknown>) => T): T;
 /**
  * SQL clause for `targetTable`'s global filter rendered against `alias`
  * (relation subqueries, `_count`, relation `orderBy`). Pushes its params to
@@ -347,15 +395,24 @@ export declare function collectTargetGlobalFilterExists(qi: BuilderCtx, targetTa
  */
 export declare function globalFilterCacheSegment(qi: BuilderCtx): string;
 /**
- * True when the USER-supplied `where` compiles to no predicate (`{}`,
- * `{ id: undefined }`, `{ OR: [{ a: undefined }] }`, …). This is the exact
- * signal the empty-`where` guard needs, the compiled emptiness, NOT the
- * fingerprint (which is non-empty for an all-undefined `OR`/`AND`). It ignores
- * any configured global filter, so a global filter never lets an unguarded
- * mass mutation through.
+ * True when the USER-supplied `where` narrows no row: it compiles to no
+ * predicate (`{}`, `{ id: undefined }`, `{ OR: [{ a: undefined }] }`, …), or
+ * to one that is TRUE for every row (`{ NOT: { OR: [] } }`,
+ * `{ id: { notIn: [] } }`, and on a NOT NULL column `{ email: { contains: '' } }`
+ * or `{ id: { not: null } }`, see {@link foldWhere}). Either way a mutation
+ * guarded by it would write every row. It reads the compiled emptiness, NOT
+ * the fingerprint (which is non-empty for an all-undefined `OR`/`AND`), and it
+ * ignores any configured global filter, so a global filter never lets an
+ * unguarded mass mutation through.
  */
 export declare function userPredicateIsEmpty(qi: BuilderCtx, userWhere: Record<string, unknown>): boolean;
 export declare function assertMutationHasPredicate(qi: BuilderCtx, operation: 'update' | 'updateMany' | 'delete' | 'deleteMany', whereSql: string, allowFullTableScan: boolean | undefined): void;
+/**
+ * The mass-mutation refusal, one text for every engine. "Empty" covers a where
+ * that is always true (see {@link userPredicateIsEmpty}), which writes every
+ * row just the same.
+ */
+export declare function emptyMutationWhereMessage(operation: string, table: string): string;
 /**
  * Build the inner WHERE expression (without the WHERE keyword).
  * Returns null if no conditions exist.
@@ -440,9 +497,10 @@ export declare function buildScopedScalarClause(qi: BuilderCtx, scope: WhereScop
  * Cache-hit param-collect mirror of {@link buildScopedWhere}: pushes the exact
  * same params in the exact same order (driven by the same {@link walkWhere}),
  * without rebuilding SQL. Serves both {@link collectRelFilterParams} and
- * {@link collectAliasWhereParams}.
+ * {@link collectAliasWhereParams}. Returns whether the clause compiles to a
+ * condition (`buildScopedWhere` non-null).
  */
-export declare function collectScopedWhereParams(qi: BuilderCtx, scope: WhereScope, where: Record<string, unknown>, params: unknown[], depth?: number): void;
+export declare function collectScopedWhereParams(qi: BuilderCtx, scope: WhereScope, where: Record<string, unknown>, params: unknown[], depth?: number): boolean;
 /** Param-collect mirror of {@link buildScopedScalarClause}. */
 export declare function collectScopedScalarParams(qi: BuilderCtx, scope: WhereScope, field: string, value: unknown, params: unknown[]): void;
 /**
@@ -513,9 +571,41 @@ export declare function pgTypeForColumn(_qi: BuilderCtx, meta: TableMetadata, co
  * SQL-template cache is unaffected, and it is applied on the cache-hit
  * param-collect path as well as the build path.
  *
+ * On MySQL a number, bigint or boolean compared with a text column binds as
+ * text ({@link textComparedOperand}), and so does each such element of a list.
+ *
  * `timestamptz` and every non-temporal column are returned by identity.
  */
 export declare function coerceWhereOperand(qi: BuilderCtx, meta: TableMetadata, column: string, value: unknown): unknown;
+/**
+ * Column types MySQL compares with a NUMBER numerically, converting each
+ * stored text to a number: `'0zz' = 0` and `'abc' = 0` are both true, and a
+ * boolean is the number 1 or 0 there. A request body that carries `0` or
+ * `false` where a token string belongs would match the first row whose token
+ * does not start with a digit. Exported so the write path's re-read keys use
+ * this one list rather than a copy.
+ */
+export declare const TEXT_COMPARED_TYPES: ReadonlySet<string>;
+/**
+ * A value bound against a column of `columnType`, as MySQL must receive it to
+ * compare it as the value it is: a number or bigint becomes its decimal text
+ * and a boolean `'1'` / `'0'` (what MySQL stores when a boolean is written to
+ * a text column), so the comparison is text with text. Every other engine,
+ * value and column type is returned unchanged. THE rule for every value Turbine
+ * binds against a column on MySQL: the where compiler applies it to each
+ * operand, and the writes apply it to the keys they re-read a row by.
+ */
+export declare function textComparedOperand(qi: Pick<BuilderCtx, 'dialect'>, columnType: string | undefined, value: unknown): unknown;
+/**
+ * Whether a `Date` bound against `dbType` gets the zone-less UTC rewrite (the
+ * write path's gate). A `date` column takes the UTC date part on every SQL
+ * engine: the write path stores `YYYY-MM-DD` there, and a full timestamp
+ * compared with that text matches nothing. A zone-less `timestamp` is
+ * rewritten on PostgreSQL only, because MySQL reads a zone-less literal in the
+ * session time zone. `utcTimestamps: false` turns both off. Time-of-day
+ * columns always rewrite.
+ */
+export declare function utcDateTimeRewrite(qi: BuilderCtx, dbType: string | undefined): boolean;
 /**
  * The Postgres enum type name for a column, when the schema knows one.
  *
@@ -526,10 +616,10 @@ export declare function coerceWhereOperand(qi: BuilderCtx, meta: TableMetadata,
  * value as text and Postgres refuses the implicit text→enum coercion
  * ("column X is of type Y but expression is of type text").
  *
- * Postgres-only by construction: gated on the active dialect being
- * `postgresql` AND on `schema.enums` having entries (only PG introspection
- * produces them, `defineSchema` and the other engines leave it empty), so
- * SQLite/MySQL/MSSQL/PowDB output is byte-identical.
+ * Postgres-only by construction: gated on the engine having named enum types
+ * (`namedEnumTypes`) AND on `schema.enums` having entries (only PG
+ * introspection produces them, `defineSchema` and the other engines leave it
+ * empty), so SQLite/MySQL/MSSQL/PowDB output is byte-identical.
  */
 export declare function enumTypeForColumn(qi: BuilderCtx, column: string): string | null;
 /**
@@ -540,14 +630,13 @@ export declare function enumTypeForColumn(qi: BuilderCtx, column: string): strin
 export declare function enumCastSuffix(qi: BuilderCtx, column: string): string;
 /**
  * Equality-fallthrough guard shared by every SQL-build path AND every
- * cache-hit param-collect path. A plain object literal that matched no known
- * filter shape on a non-JSON column is almost always a misspelled operator
- * (`startWith` for `startsWith`); binding it as `col = $1` silently returns
- * wrong rows. Class instances (Buffer for bytea, Decimal wrappers, ...) are
- * legitimate bind values and pass through, as do objects on json/jsonb
- * columns (object equality).
+ * cache-hit param-collect path: a bare value must fit its column
+ * ({@link assertEqualityOperand}). A plain object literal that matched no
+ * known filter shape on a non-JSON column is almost always a misspelled
+ * operator (`startWith` for `startsWith`), and binding it as `col = $1` would
+ * silently return wrong rows. Objects on json/jsonb columns are JSON values.
  */
-export declare function assertBindableEqualityValue(qi: BuilderCtx, rawColumn: string, value: unknown, columnPgType: string, table: string): void;
+export declare function assertBindableEqualityValue(_qi: BuilderCtx, rawColumn: string, value: unknown, columnPgType: string, table: string): void;
 /**
  * Build the user-supplied `where` filter of a relation `with` clause against
  * the relation's table alias. Supports the same scalar surface as the
@@ -560,7 +649,7 @@ export declare function assertBindableEqualityValue(qi: BuilderCtx, rawColumn: s
  */
 export declare function buildAliasWhere(qi: BuilderCtx, targetTable: string, targetMeta: TableMetadata, alias: string, where: Record<string, unknown>, params: unknown[]): string | null;
 /** Mirrors {@link buildAliasWhere} param-push order for the cache-hit collect path. */
-export declare function collectAliasWhereParams(qi: BuilderCtx, targetTable: string, targetMeta: TableMetadata, where: Record<string, unknown>, params: unknown[]): void;
+export declare function collectAliasWhereParams(qi: BuilderCtx, targetTable: string, targetMeta: TableMetadata, where: Record<string, unknown>, params: unknown[]): boolean;
 /**
  * Value-invariant, shape-aware fingerprint for a relation `with` clause's
  * `where` filter. Must distinguish every SQL shape {@link buildAliasWhere}
@@ -587,9 +676,12 @@ export declare function columnRefSql(qi: BuilderCtx, ref: ColumnRef, ctx: Column
  * Each operator key becomes its own clause, all ANDed together.
  *
  * `equals`/`not`/`gt`/`gte`/`lt`/`lte` also accept a {@link ColumnRef}
- * (`{ col: 'otherField' }`) which compiles to a column-to-column comparison
+ * (`col('otherField')`) which compiles to a column-to-column comparison
  * against `refCtx`: no param bound, so `collectOperatorParams` mirrors by
  * pushing nothing and the referenced name lives in the fingerprint.
+ *
+ * `not` also accepts an operator object, compiled as `NOT (<inner clauses>)`
+ * (see {@link WhereOperator.not}).
  */
 export declare function buildOperatorClauses(qi: BuilderCtx, column: string, op: WhereOperator, params: unknown[], refCtx?: ColumnRefContext): string[];
 /**
@@ -602,9 +694,8 @@ export declare function buildOperatorClauses(qi: BuilderCtx, column: string, op:
  */
 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}.
+ * Gate the pathless JSON filters, `contains` (containment) and `equals`
+ * (whole-document equality), 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
@@ -666,22 +757,6 @@ export declare function getColumnPgType(qi: BuilderCtx, column: string): string;
  * E.g. '_text' → 'text', '_int4' → 'integer'
  */
 export declare function getArrayElementType(_qi: BuilderCtx, pgType: string): string;
-/**
- * Refuse a {@link JsonFilter} carrying a key that is not a JSON operator, and
- * refuse a filter that selects a `path` but never compares it.
- *
- * Both shapes used to compile to NOTHING. `buildJsonFilterClauses` only ever
- * emitted a clause for a key it recognized, so `{ path: ['title'],
- * string_contains: 'x' }`, the Prisma spelling, and an easy typo besides -
- * produced an empty clause list, the predicate vanished, and the query
- * returned EVERY row. Inside an `AND` it silently dropped that conjunct, so a
- * tenant scope written this way widened to the whole table. The equivalent
- * typo on a scalar column has always thrown; this closes the inconsistency.
- *
- * Called from both the SQL-build path and the cache-hit param-collect path, so
- * a warmed SQL cache cannot skip the check.
- */
-export declare function assertJsonFilterKeys(filter: JsonFilter, column: string): void;
 /**
  * Validate and enumerate the substring comparisons on a JSON filter, in the
  * fixed {@link JSON_STRING_OPERATORS} order. Shared by the build and collect
@@ -697,6 +772,25 @@ export declare function jsonRangeEntries(_qi: BuilderCtx, filter: JsonFilter, co
     sqlOp: string;
     value: number | string;
 }[];
+/**
+ * The bound operand of `{ path, equals }`, shared by the build and collect
+ * paths so both bind (and refuse) identically.
+ *
+ * PostgreSQL compares JSON to JSON, so the operand is its JSON text: `5`,
+ * `"5"`, `null`, `[1,2]` and `{"a":1}` each match only that JSON value at the
+ * path (numbers compare numerically, so `5` also matches `5.0`). A Date is the
+ * ISO string JSON would store, and a bigint is a JSON number.
+ *
+ * MySQL and SQL Server compare typed through `Dialect.buildJsonPathEquals`
+ * and never reach this function. SQLite compares the value its path
+ * extraction returns, so only a value with a text form can match: a string,
+ * number, boolean, bigint or Date.
+ * There a number and a numeric string match the same rows, except on SQLite,
+ * whose extraction returns typed values: a number binds as a number there, and
+ * a boolean is refused because SQLite reads `true` and `1` alike. `null`,
+ * objects and arrays matched no row on those engines and are refused (E017).
+ */
+export declare function jsonPathEqualsOperand(qi: BuilderCtx, value: unknown, column: string): unknown;
 /**
  * Build SQL clauses for JSONB filter operators on a column.
  * Supports: path, equals, contains, hasKey, gt, gte, lt, lte.
@@ -716,6 +810,13 @@ export declare function buildJsonFilterClauses(qi: BuilderCtx, column: string, f
  * params) and fail at runtime with the engine's bad-JSON-path error. The
  * encoded path stays a bound parameter, never spliced into SQL text, so
  * the build/collect param mirrors stay in lockstep and injection-safe.
+ *
+ * A key segment is written as a JSON string literal (`JSON.stringify`), the
+ * form the engines' JSONPath grammars read a quoted key in: a backslash, a
+ * quote and a control character are each escaped. Escaping only the quote
+ * read a key holding a backslash as an escape sequence, so the key `a\b` was
+ * looked up as a different key and matched nothing, a key ending in a
+ * backslash was a bad path, and MySQL refused a key holding a newline.
  */
 export declare function jsonPathParam(qi: BuilderCtx, path: readonly (string | number)[], nativeForm?: unknown): unknown;
 /**
@@ -776,4 +877,3 @@ export declare function buildTextSearchClause(qi: BuilderCtx, column: string, fi
  * Uses pre-computed Map for O(1) lookup instead of linear scan.
  */
 export declare function getColumnArrayType(qi: BuilderCtx, column: string): string;
-export {};