turbine-orm 0.81.0 → 0.90.0

package/dist/cjs/query/where-compile.d.ts

@@ -15,10 +15,11 @@
  *
  * This module removes the drift BY CONSTRUCTION:
  *   - {@link walkWhere} is the ONE enumeration. It sorts keys canonically,
- *     skips `undefined`, dispatches the `OR`/`AND`/`NOT` combinators and
- *     relation filters, and yields a flat, ordered {@link WhereEvent} stream.
- *     All three consumers iterate this same stream, so their key order and
- *     combinator structure can never diverge again.
+ *     skips `undefined` values, applies the one combinator-shape rule
+ *     ({@link combinatorBranches}), dispatches relation filters, and yields a
+ *     flat, ordered {@link WhereEvent} stream. All three consumers iterate this
+ *     same stream, so their key order, combinator structure and view of
+ *     `undefined` can never diverge.
  *   - {@link classifyScalarForSql} is the ONE scalar-shape decision the SQL
  *     paths use. `buildWhereClause` and `collectWhereParams` BOTH call it with
  *     the same `(rawColumn, value)`, so they always take the same branch and
@@ -120,10 +121,17 @@ export type ScalarSqlClass = {
  */
 export type WhereEvent = {
     kind: 'or';
-    conditions: WhereRecord[];
-} | {
+    conditions: readonly WhereRecord[];
+}
+/**
+ * `fixedArity` marks an `AND` written as one object (`AND: { ... }`): its
+ * SQL has one branch whatever the caller sends, so it need not give up the
+ * prepared-statement name a caller-sized array does.
+ */
+ | {
     kind: 'and';
-    conditions: WhereRecord[];
+    conditions: readonly WhereRecord[];
+    fixedArity?: true;
 } | {
     kind: 'not';
     condition: WhereRecord;
@@ -138,17 +146,133 @@ export type WhereEvent = {
     value: unknown;
 };
 /**
- * THE canonical WHERE enumeration. Yields events in sorted-key order (skipping
- * `undefined`), dispatching combinators and relation filters, so every consumer
+ * Why a relation-filter key's value cannot be read, or `null` when it can.
+ * `some` / `none` / `every` take a where object; `is` / `isNot` take a where
+ * object or `null`. Any other value (`null` on a quantifier, a scalar, an
+ * array) used to compile to no condition at all, so a filter, or a tenant
+ * global filter, built from a missing value matched every row. Shared with the
+ * PowDB engine so both refuse the same values in the same words.
+ */
+export declare function relationFilterValueProblem(wrapper: string, value: unknown): string | null;
+/**
+ * Why a relation filter reads a to-one key on a to-many relation, or `null`
+ * when it does not. `posts: { is: {...} }` compiled to "at least one post
+ * matches" and `isNot` to "no post matches", which is not what either word says
+ * about a list of rows, and the typed API never offers them there. The
+ * quantifiers on a to-one relation are left alone: with at most one related
+ * row, `some` / `none` / `every` each have one reading. Shared with the PowDB
+ * engine so both refuse the same filters in the same words.
+ */
+export declare function relationCardinalityProblem(relDef: RelationDef, filterObj: WhereRecord): string | null;
+/**
+ * A bare where object on a to-one relation is an implicit `is`
+ * (`{ author: { name: 'x' } }` is `{ author: { is: { name: 'x' } } }`). To-many
+ * relations still require a quantifier. The one rule, used by the SQL engines'
+ * hosts and by PowDB.
+ */
+export declare function normalizeToOneRelationFilter(relDef: RelationDef, filterObj: WhereRecord): WhereRecord;
+/** The where combinators. */
+export type CombinatorKey = 'AND' | 'OR' | 'NOT';
+/**
+ * THE combinator-shape rule, shared by every walker over a where (or having)
+ * clause: the SQL walk below, `having`, and the `globalFilters` check at
+ * construction. Returns the branches `value` stands for, or throws
+ * {@link ValidationError} (E003).
+ *
+ *   - `AND` and `NOT` take one where object (a single branch) or an array of
+ *     them; `OR` takes an array. This is Prisma's shape.
+ *   - Anything else is refused by name: `OR: { ... }`, a string, a number,
+ *     `null`, and an array holding one of those. A combinator the compiler
+ *     cannot read would compile to nothing, so a mistyped filter, or a
+ *     tenant filter built as `{ OR: { orgId } }`, would match every row.
+ *   - An `undefined` member is absent and is dropped. When every member was
+ *     `undefined` the combinator itself is absent and this returns `null`, the
+ *     same reading the args seam gives it.
+ *
+ * An array written empty is returned empty; what that means is the caller's
+ * rule (in a where clause: `OR: []` matches nothing, `AND: []` and `NOT: []`
+ * apply no condition). Returns the input array by reference when it holds no
+ * `undefined`, so the common path allocates nothing.
+ */
+export declare function combinatorBranches(key: CombinatorKey, value: unknown, table: string, clause?: 'where' | 'having'): readonly WhereRecord[] | null;
+/**
+ * THE canonical WHERE enumeration. Yields events in sorted-key order,
+ * dispatching combinators and relation filters, so every consumer
  * (fingerprint, SQL build, param collect) walks identically.
  *
- * Combinator SKIP rules match the historical code exactly: an `OR`/`AND` whose
- * value is a non-array or an empty array is skipped entirely (it contributes
- * neither SQL, params, nor a fingerprint token); `NOT` is always emitted.
- * A key that names a relation but whose value is not a `{ some/every/none/is/
- * isNot }` filter falls through to the scalar path, exactly as before.
+ * `undefined`: the args seam is the authority and removes it, with every
+ * object it emptied, before any of this runs. This walk is the backstop for
+ * callers below the seam and reads only `undefined` itself: a key holding it
+ * is skipped, a combinator member holding it is dropped, and a relation filter
+ * whose wrapper keys all hold it is absent. Values are never looked inside, so
+ * a JSON operand is data whatever its shape.
+ *
+ * Combinators follow {@link combinatorBranches}. `AND` and `NOT` with no
+ * branches apply no condition; `OR` with none matches no row
+ * ({@link matchNothingEvent}), and an `OR` member made only of `undefined` is
+ * dropped ({@link isAbsentBranch}). A `NOT` array negates each branch (`NOT a AND
+ * NOT b`), as Prisma does; a `NOT` object negates the object as a whole. A key
+ * that names a relation takes only the relation-filter keys (a to-one relation
+ * also takes a bare where object, read as `is`), each holding a value the
+ * compiler reads ({@link relationFilterValueProblem}), and anything else is
+ * refused (E003). Only when the key also names a column, and its object names
+ * no relation-filter key, is it that column's filter.
  */
 export declare function walkWhere(host: WhereHost, where: WhereRecord): WhereEvent[];
+/**
+ * What a where clause is for every row, read from the SQL it compiles to:
+ *
+ *   - `'empty'`: it compiles to no SQL (`{}`, `AND: []`, `NOT: {}`);
+ *   - `'true'` / `'false'`: a constant whatever the row holds, NULLs included
+ *     (`NOT: { OR: [] }` and `OR: [{}, ...]` are TRUE, `OR: []` is FALSE);
+ *   - `'row'`: it depends on the row.
+ *
+ * The mass-mutation guard reads it: a where that is `'true'` writes every row
+ * exactly as an empty one does. It mirrors the compiler rather than ideal
+ * logic, branch for branch: a branch that compiles to nothing makes its `OR`
+ * TRUE (the compiler writes the constant), and `NOT` of something that
+ * compiles to nothing applies no condition, as in the SQL. Only shapes whose
+ * SQL is a constant fold; anything else is `'row'`, so folding never refuses a
+ * filter that narrows. Constants come from an empty `in` list (FALSE), an
+ * empty `notIn` list (TRUE), an `OR` with a branch that applies no condition
+ * (TRUE), and an `EXISTS` / `NOT EXISTS` over a sub-where that is itself
+ * constant.
+ *
+ * `hostFor` gives the host of a relation's target table, or `undefined` when
+ * the schema has no such table (the compiler emits nothing for it).
+ *
+ * With `options.notNull` the fold also reads what the schema says about the
+ * rows: on a NOT NULL column `{ not: null }`, `contains: ''` (and
+ * `startsWith` / `endsWith`), a comparison of the column with itself, and
+ * `hasEvery: []` are TRUE for every row, and `null` / `equals: null` FALSE; on
+ * a belongsTo relation whose foreign key is NOT NULL and enforced, and whose
+ * target has no global filter, `is: {}` (or a bare `{}`) is TRUE. Only the
+ * mass-mutation guard asks for it: a where that is TRUE because of a NOT NULL
+ * column writes every row just as an empty one does.
+ */
+export type WhereFold = 'empty' | 'true' | 'false' | 'row';
+/** What {@link foldWhere} may read beyond the SQL. */
+export interface WhereFoldOptions {
+    notNull?: {
+        /** Whether the engine enforces declared foreign keys (an orphan row has no related row). */
+        foreignKeys: boolean;
+        /** Whether `table` has a global filter, which applies inside a relation filter's EXISTS. */
+        hasGlobalFilter(table: string): boolean;
+    };
+}
+export declare function foldWhere(host: WhereHost, where: WhereRecord, hostFor: (table: string) => WhereHost | undefined, depth?: number, options?: WhereFoldOptions): WhereFold;
+/**
+ * A {@link WhereHost} over plain table metadata, for callers with no SQL
+ * builder (PowDB, construction-time checks). Same column-type and to-one rules
+ * as the SQL engines' scoped hosts.
+ */
+export declare function metadataWhereHost(meta: TableMetadata): WhereHost;
+/**
+ * {@link foldWhere} for `table` in `tables`, with plain metadata hosts. Also
+ * validates the whole clause shape at every depth (combinators, relation-filter
+ * keys and values), so a construction-time check can run it on a static filter.
+ */
+export declare function foldWhereFor(tables: Readonly<Record<string, TableMetadata>>, table: string, where: WhereRecord, options?: WhereFoldOptions): WhereFold;
 /**
  * Column-aware SQL classification of a scalar WHERE value. Reproduces the SQL
  * builder's linear fall-through: a JSON/array-shaped value on a non-JSON/array