turbine-orm 0.81.0 → 0.90.0

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

@@ -5,15 +5,29 @@
  * compiler. Kept out of builder.ts so the class file stays about SQL assembly
  * 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 { ArrayFilter, 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;
 /**
- * True for a *plain object literal* that reached an equality fallthrough
- * without matching any known filter shape, the misspelled-operator case.
- * Class instances (Buffer for bytea, Decimal wrappers, ...) are legitimate
- * bind values and return false, as do arrays and Dates.
+ * THE plain-object test for argument trees: an object literal (or a
+ * prototype-less object), never an array, Date, Buffer, typed array or other
+ * class instance. Class instances are values a driver binds (a Decimal, an
+ * interval wrapper), so no walker over caller arguments may descend into one.
+ */
+export declare function isPlainRecord(value: unknown): value is Record<string, unknown>;
+/**
+ * `target[key] = value`, always as an OWN property. A plain assignment of the
+ * key `__proto__` replaces the object's prototype instead, so a caller key
+ * spelled that way (`JSON.parse` produces it as an ordinary own key) would
+ * vanish from a rebuilt argument object rather than reach the check that
+ * refuses it, and a filter would silently stop filtering.
+ */
+export declare function setOwn(target: Record<string, unknown>, key: string, value: unknown): void;
+/**
+ * {@link isPlainRecord} read at an equality fallthrough: a plain object that
+ * matched no known filter shape is a misspelled operator, while a class
+ * instance (Buffer for bytea, a Decimal wrapper) is a legitimate bind value.
  */
 export declare function isUnmatchedPlainObject(value: unknown): boolean;
 /**
@@ -26,50 +40,104 @@ 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.
+ * Everything that walks a where clause has to agree about them: a wrapper the
+ * SQL compiler treats as a relation filter but a walker does not is a wrapper
+ * whose body reaches the builder unwalked. The SQL walk (`walkWhere` in
+ * where-compile.ts), the bare to-one normalization (`normalizeRelationFilter`
+ * in where.ts) and the PII predicate guard (`cli/pii-predicate-guard.ts`) all
+ * read this list. `prisma-compat.ts` still carries its own copy
+ * (`RELATION_QUANTIFIERS` plus inline `is` / `isNot` tests).
  *
  * `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`).
- *
- * ## STATUS: a landing spot, not yet a deduplication. Read this before trusting it.
- *
- * NOTHING IMPORTS THIS YET. The three copies listed above are all still in
- * place and still hand-synced; declaring the canonical home did not by itself
- * move any of them onto it. It is kept, rather than deleted as unused, because
- * `cli/pii-predicate-guard.ts` names this module as where its own copy wants to
- * go, and deleting the destination is the one change that makes converging
- * harder. Wiring the copies up is a separate change: each one sits on a
- * different walk, so each has to be re-tested on its own.
- *
- * So do not read this constant as evidence that the walkers agree. The comment
- * on each copy is still the only thing holding them in step.
  */
 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>;
+export { isColumnRef } from './column-ref.js';
+/**
+ * `value` without its `undefined`-valued keys, one level deep. Returns the
+ * input BY REFERENCE when there are none, so the common path allocates
+ * nothing. Symbol-keyed properties (internal brands) survive a copy.
+ *
+ * This is the where walkers' backstop only. The args seam
+ * (`pruneUndefinedArgs` in normalize-args.ts) is the authority on `undefined`:
+ * it removes undefined keys at every where position and objects that became
+ * empty because of them. The walkers see what the seam missed (internal
+ * callers below it), skip a key whose value is `undefined`, and never look
+ * inside a value, so a JSON operand is data however it is shaped.
+ */
+export declare function dropUndefinedKeys(value: Record<string, unknown>): Record<string, unknown>;
+/**
+ * What a column's type allows at a value position. Decided from the column's
+ * type token: json/jsonb take JSON values, an array column (`_text`) takes
+ * arrays, a pgvector column takes a number array, and everything else takes a
+ * scalar.
+ */
+export type OperandColumnKind = 'scalar' | 'array' | 'vector' | 'json';
+/** {@link OperandColumnKind} for a column type token (case-insensitive). */
+export declare function operandColumnKind(columnType: string | undefined): OperandColumnKind;
+/** Short, value-free description of an operand for an error message. */
+export declare function describeOperand(value: unknown): string;
+/**
+ * Where an operand sits, for the refusal message and for the column kind it is
+ * checked against. `column` is the label the message prints (the column name,
+ * or the expression a groupBy JSON key compiles to).
+ */
+export interface OperandContext {
+    column: string;
+    table: string;
+    kind: OperandColumnKind;
+}
+/**
+ * Validate every operand of an operator object against its column, and throw
+ * {@link ValidationError} (E003) naming the column, the operator, what was
+ * received and what is accepted.
+ *
+ * An operator object must state at least one comparison. One made only of
+ * `mode` (or of operators whose value is `undefined`) compares nothing, so it
+ * is refused rather than compiled to no predicate: inside a relation filter
+ * that silence turned `deleteMany` into a delete of every row. The args seam
+ * removes the object when `undefined` emptied it, so Prisma's optional-search
+ * idiom (`{ contains: q, mode: 'insensitive' }` with `q` undefined) still
+ * reads as "no filter".
+ *
+ * Called by the SQL build AND the cache-hit param collect with the same
+ * arguments, so a warmed template can never bind an operand the cold build
+ * refuses. Recurses into a `not` operator object, bounded by `depth`. Runs on
+ * every operator object of every query, so it reads only the keys present and
+ * builds a message only when it throws.
+ */
+export declare function assertOperatorOperands(op: Record<string, unknown>, ctx: OperandContext, depth?: number): void;
+/**
+ * On a JSON column `not` takes a JSON VALUE (`not: { a: 1 }` compares
+ * documents), so `not: { contains: {...} }` was compared as the literal document
+ * `{"contains": ...}` and matched nearly every row, while the same spelling on a
+ * text column negates the filter. An object made only of filter-operator keys
+ * is therefore refused, except `not: { equals: X }`, which negates the
+ * whole-document equality. A literal document with such keys stays expressible.
+ * Every engine runs it (PowDB too), so the spelling means one thing everywhere.
+ */
+export declare function assertJsonNotOperand(value: unknown, ctx: OperandContext): void;
+/**
+ * Validate a BARE value (implicit equality, `{ id: 5 }`) against its column.
+ * Shared by the build and collect paths of every where scope.
+ */
+export declare function assertEqualityOperand(value: unknown, ctx: OperandContext): void;
 /**
- * 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
- * `col`) is treated as a plain value so JSON payloads that merely contain a
- * `col` property keep their equality meaning.
+ * One `cursor` field's value, checked and unwrapped. A cursor value is the
+ * value the last row holds in that column, so it takes the bare-equality rule
+ * (`{ equals: v }` is the same as `v`); an operator object, a list on a scalar
+ * column or a column reference is refused (E003) in terms of cursors, not
+ * filters. NULL is a row's value only in a column that can hold it: in a NOT
+ * NULL column (the primary key included) no row has it, so it is refused
+ * rather than placing the page nowhere. Shared by every engine's cursor path.
  */
-export declare function isColumnRef(value: unknown): value is ColumnRef;
+export declare function cursorFieldValue(field: string, written: unknown, ctx: OperandContext & {
+    nullable: boolean;
+}): unknown;
 /**
  * Fingerprint the SHAPE of a where-operator object. Null-valued `equals` /
  * `not` compile to parameterless `IS NULL` / `IS NOT NULL` (different SQL, no
@@ -77,22 +145,16 @@ export declare function isColumnRef(value: unknown): value is ColumnRef;
  * warmed by `{ not: 5 }` would serve `{ not: null }` with a desynced param list.
  *
  * Column references ({@link ColumnRef}) compile the referenced column into the
- * SQL TEXT (no param bound), so the referenced field name is part of the shape
- *: `{ equals: { col: 'a' } }` and `{ equals: { col: 'b' } }` must never share
- * a cache entry. The name is JSON-encoded so exotic field names cannot collide
+ * SQL TEXT (no param bound), so the referenced field name is part of the
+ * shape: `{ equals: col('a') }` and `{ equals: col('b') }` must never share a
+ * cache entry. The name is JSON-encoded so exotic field names cannot collide
  * with other fingerprint tokens.
+ *
+ * A `not` operator object compiles to `NOT (<inner>)`, so its whole inner shape
+ * is part of the token, with the inner object's EFFECTIVE mode (its own, else
+ * the inherited one). Keys holding `undefined` are skipped, as the builders skip them.
  */
-export declare function fingerprintOperatorShape(value: WhereOperator): string;
-/**
- * Guard for the value of an `equals` operator reaching the plain-equality
- * operator path. A plain object literal can only legitimately be an equality
- * value on a json/jsonb column, and those route to the JSONB filter branch
- * BEFORE the operator branch, so any plain object that reaches here is a
- * mistake (e.g. `{ equals: { foo: 1 } }` on a text column). Shared by the
- * SQL-build path and the cache-hit param-collect path so a warmed cache can
- * never skip the check.
- */
-export declare function assertBindableEqualsOperand(value: unknown, column: string): void;
+export declare function fingerprintOperatorShape(value: WhereOperator, inheritedMode?: unknown, depth?: number): string;
 /**
  * Object keys in sorted order, mirroring the canonical order used by every
  * cache fingerprint. The SQL-build and cache-hit param-collect paths MUST
@@ -373,8 +435,11 @@ export declare function dedupeOrderEntries(meta: ColumnNameSource | undefined, e
  * 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.
+ *
+ * Every element must be a field name: anything else (an `undefined` hole, a
+ * number) is E003 here, the first place either caller reads the list.
  */
-export declare function dedupeColumnList(meta: ColumnNameSource | undefined, columns: readonly string[]): {
+export declare function dedupeColumnList(meta: ColumnNameSource | undefined, columns: readonly string[], label?: string): {
     columns: string[];
     dropped: DroppedTerm[];
 } | null;
@@ -395,3 +460,40 @@ export declare function normalizeOrderBy(value: OrderDirection | OrderBySpec): {
  * never overwritten while an empty one still gets the synthesized PK order.
  */
 export declare function isEmptyOrderBy(orderBy: unknown): boolean;
+/**
+ * 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;
+/**
+ * Whether {@link findUndefinedPath} would find anything, without building the
+ * path strings. Same walk, same leaves, same plain-object rule, same depth bound.
+ */
+export declare function holdsUndefinedValue(value: unknown, depth: number): boolean;
+/**
+ * The key path of the first `undefined` inside a where object (a global filter),
+ * or `null`.
+ * Walks plain objects and arrays; values of any other kind (Dates, Buffers,
+ * column references) are leaves. Key NAMES only, never values, so the path is
+ * safe in an error message.
+ */
+export declare function findUndefinedPath(value: unknown, path: string, depth: number): string | null;
+/**
+ * Refuse an {@link ArrayFilter} that would compile to less than it says: a key
+ * that is not an array operator (it would be dropped, so `{ has: 'a', hsa: 'b' }`
+ * filtered on `has` alone), an `isEmpty` that is not a boolean (it compiled to
+ * nothing), or no comparison at all. Called by the SQL build and the cache-hit
+ * param collect alike.
+ */
+export declare function assertArrayFilter(filter: ArrayFilter, column: string): void;