turbine-orm 0.81.0 → 0.90.0

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

@@ -10,15 +10,30 @@
  * stay class-resident, reached through the ctx. See builder.ts for the thin
  * delegating methods and the async execute wrappers.
  */
-import type { ReturningSelection } from '../dialect.js';
+import { type ReturningSelection } from '../dialect.js';
 import type { TableMetadata } from '../schema.js';
 import type { DeferredQuery } from './deferred.js';
 import type { CreateArgs, CreateManyArgs, DeleteArgs, DeleteManyArgs, UpdateArgs, UpdateManyArgs, UpsertArgs } from './types.js';
 import type { BuilderCtx } from './where.js';
 /**
- * Normalize one `data` value before it is bound as a write param.
+ * Normalize one `data` value before it is bound as a write param. This is THE
+ * write bind seam: create, createMany, update, updateMany, both halves of
+ * upsert, the cache-hit param collectors and (through those public methods)
+ * the nested-write engine all bind through it.
  *
- * Two value shapes need rewriting, both a JS `Date` on a temporal column:
+ * JSON columns (json / jsonb):
+ *
+ * - A JS array is serialized with `JSON.stringify`. The drivers' default
+ *   array serialization is a Postgres ARRAY literal, so `[]` was stored as the
+ *   object `{}`, `["a"]` failed with 22P02, and `createMany`'s UNNEST
+ *   transpose flattened `[1, 2, 3]` into three rows.
+ * - A {@link jsonValue} wrapper is serialized with `JSON.stringify`, which is
+ *   how a JSON string or a JSON `null` is written.
+ * - A JS string is RAW JSON TEXT and passes through untouched, so
+ *   `JSON.stringify(value)` callers keep storing the parsed value. A plain
+ *   object passes through too: every driver already serializes it as JSON.
+ *
+ * Temporal columns, a JS `Date`:
  *
  * 1. A time-of-day column (`time` / `timetz`), the driver serializes a `Date`
  *    as a full ISO timestamp with the process offset and Postgres answers
@@ -28,14 +43,22 @@ import type { BuilderCtx } from './where.js';
  *    non-UTC process the stored value is wrong and (because the read path
  *    interprets an offset-less value as UTC) does not round-trip. Rewritten to
  *    the UTC components, mirroring `parseDbDate`. See `toLocalDateTimeLiteral`
- *    in query/utils.ts.
+ *    in query/utils.ts. `timestamptz` is deliberately untouched: it stores a
+ *    real instant and the driver's local-offset string is already correct.
  *
- * `timestamptz` is deliberately untouched: it stores a real instant and the
- * driver's local-offset string is already correct for it.
+ * A plain object or an array bound to a known scalar column (text, int, uuid,
+ * ...) is refused with E003, and so is a `Map` or `Set` anywhere; see
+ * {@link assertScalarBindable} and {@link assertNotCollection}.
  *
- * Every other value, including a string that is already a valid literal, is
- * returned by identity, so this is a byte-for-byte no-op for every non-temporal
- * column.
+ * Expressions (`expr.*`, `col()`) never bind as a value: the update paths
+ * compile them before reaching here, so one that arrives is in a position that
+ * takes values only (create data, `{ set }`) and is refused. An unbranded
+ * object shaped like one is refused on a non-JSON column on every engine.
+ *
+ * Every other value is returned by identity, so a primitive costs one check
+ * and no lookup. The exception is a string on an engine that defines the
+ * dialect's `checkTextWrite` (SQLite), which is checked against its column's
+ * type first; see {@link checkTextWrite}.
  */
 export declare function coerceWriteValue(qi: BuilderCtx, key: string, value: unknown): unknown;
 /**
@@ -44,21 +67,60 @@ export declare function coerceWriteValue(qi: BuilderCtx, key: string, value: unk
  * return rows from non-RETURNING engines. Reuses the same parameterized WHERE
  * builder as reads, so no user value is interpolated.
  */
-export declare function buildReselectByWhere(qi: BuilderCtx, whereObj: Record<string, unknown>, projection?: WriteProjection): {
+export declare function buildReselectByWhere(qi: BuilderCtx, whereObj: Record<string, unknown>, projection?: WriteProjection, lockRows?: boolean): {
     sql: string;
     params: unknown[];
 };
 export declare function buildCreate<T extends object>(qi: BuilderCtx, args: CreateArgs<T>, projection?: WriteProjection): DeferredQuery<T>;
 /**
- * Build the `'reselect'` plan for {@link buildCreate}: run the INSERT, then
- * `SELECT * WHERE pk = ?`. Returns `undefined` (skipped) unless the active
- * dialect's result strategy is `'reselect'`, so the PostgreSQL/RETURNING path
- * pays nothing. Not yet wired to a real non-RETURNING engine.
+ * Build the `'reselect'` plan for {@link buildCreate} (MySQL): run the INSERT,
+ * then `SELECT ... WHERE <key> = ?` by a key whose value is known exactly
+ * (see {@link createReselectKey}). Returns `undefined` unless the dialect's
+ * result strategy is `'reselect'`, so the RETURNING engines pay nothing.
  */
 export declare function makeCreateReselect<T extends object>(qi: BuilderCtx, insertSql: string, insertParams: unknown[], data: Record<string, unknown>, projection?: WriteProjection): DeferredQuery<T>['reselect'];
-export declare function buildCreateMany<T extends object>(qi: BuilderCtx, args: CreateManyArgs<T>): DeferredQuery<T[]>;
+export declare function buildCreateMany<T extends object>(qi: BuilderCtx, args: CreateManyArgs<T>, overBindLimit?: 'refuse' | 'allow', projection?: WriteProjection): DeferredQuery<T[]>;
+/**
+ * `createMany()` as the statements it runs: one when the rows fit one
+ * statement, else consecutive chunks that each do. The whole call is validated
+ * once, before any chunk is built, so a refusal (a duplicate conflict key in
+ * the last chunk included) sends nothing, and the chunks are sized before any
+ * statement is built, so no engine's own per-statement check refuses one.
+ *
+ * Built eagerly and synchronously: the chunks read state the call set on the
+ * builder (`skipGlobalFilters`), which a concurrent call could change across
+ * an await.
+ */
+export declare function planCreateMany<T extends object>(qi: BuilderCtx, args: CreateManyArgs<T>, projection?: WriteProjection): {
+    chunks: DeferredQuery<T[]>[];
+    rowsPerChunk: number;
+};
+/**
+ * `err` from running a `createMany({ onConflict })`, with the engine's
+ * "one statement touched one row twice" errors (PostgreSQL 21000, SQL Server
+ * 8672) turned into the E003 that names the cause. Anything else is returned
+ * as it was.
+ */
+export declare function explainConflictKeyCollision(qi: BuilderCtx, args: {
+    readonly onConflict?: unknown;
+}, err: unknown): unknown;
 export declare function buildUpdate<T extends object>(qi: BuilderCtx, args: UpdateArgs<T>, projection?: WriteProjection): DeferredQuery<T>;
 export declare function buildDelete<T extends object>(qi: BuilderCtx, args: DeleteArgs<T>, projection?: WriteProjection): DeferredQuery<T>;
+/**
+ * Refuse `limit` / `take` / `offset` / `skip` on `updateMany` / `deleteMany`.
+ * No engine applies them to a bulk write here, so `deleteMany({ where, limit:
+ * 1000 })` used to touch every matching row. Shared with the PowDB engine.
+ */
+export declare function assertNoBulkWritePaging(table: string, operation: 'updateMany' | 'deleteMany', args: object): void;
+/**
+ * Refuse `optimisticLock` on a write that does not implement it. It is an
+ * `update` option; on a sibling method it used to be ignored, so a stale
+ * write went through with no error, which is the one outcome the option
+ * exists to prevent. The message names the equivalent for each method.
+ */
+export declare function assertNoOptimisticLock(qi: BuilderCtx, args: object, operation: OptimisticLockRefusal): void;
+/** The equivalent of a version check for each write that refuses `optimisticLock`. */
+type OptimisticLockRefusal = 'upsert' | 'updateMany' | 'delete' | 'deleteMany';
 /**
  * Why an `upsert` cannot run as this engine's single conflict statement, or
  * `null` when it can. The one authority for that decision: `upsert()` asks it
@@ -72,6 +134,11 @@ export declare function buildDelete<T extends object>(qi: BuilderCtx, args: Dele
  * - `empty-update`: an `update` with no fields has no `DO UPDATE SET` to emit;
  *   every engine rejected the statement as a syntax error. Prisma reads it as
  *   "create it if it is missing", which the lookup answers.
+ * - `other-unique-key` (MySQL): `ON DUPLICATE KEY UPDATE` has no conflict
+ *   target and updates whichever row a unique key collides on first, so when
+ *   `create` could also collide on a unique key `where` does not pin (the
+ *   primary key included), it could update a row `where` does not name
+ *   (otherCollidingUniqueKey).
  * - `global-filter`: MySQL's `ON DUPLICATE KEY UPDATE` has no predicate slot
  *   and SQL Server's MERGE cannot take the builder's column references there,
  *   so the table's global filter cannot guard the conflict update. The lookup
@@ -80,7 +147,7 @@ export declare function buildDelete<T extends object>(qi: BuilderCtx, args: Dele
  *
  * Reads `currentSkip`, so it resolves `skipGlobalFilters` itself first.
  */
-export type UpsertLookupReason = 'where-differs' | 'empty-update' | 'global-filter';
+export type UpsertLookupReason = 'where-differs' | 'empty-update' | 'other-unique-key' | 'global-filter';
 export declare function upsertLookupReason<T extends object>(qi: BuilderCtx, args: UpsertArgs<T>): UpsertLookupReason | null;
 export declare function buildUpsert<T extends object>(qi: BuilderCtx, args: UpsertArgs<T>, projection?: WriteProjection): DeferredQuery<T>;
 export declare function buildUpdateMany<T extends object>(qi: BuilderCtx, args: UpdateManyArgs<T>): DeferredQuery<{
@@ -92,8 +159,8 @@ export declare function buildDeleteMany<T extends object>(qi: BuilderCtx, args:
 /**
  * The snake_case names of a table's PII-tagged (`defineSchema` `pii: true`)
  * columns. PII columns are excluded from default projections (findMany /
- * findUnique / relation subqueries / batched loads) unless the query opts in
- * via `includePii` or names the column explicitly in `select`. Returns an
+ * findUnique / relation subqueries / batched loads) unless a read passes
+ * `includePii: UNSAFE`; naming one in `select` without it is E003. Returns an
  * empty set for any table with no PII column, so untagged schemas keep their
  * byte-identical SQL.
  */
@@ -102,8 +169,8 @@ export declare function piiColumns(_qi: BuilderCtx, meta: TableMetadata): Set<st
  * The camelCase field names of a table's PII-tagged columns: the read-side
  * counterpart of {@link piiColumns} applied to already-parsed entities.
  * Used to strip PII from a write's RETURNING/reselect row (writes accept no
- * `includePii`/`select`, so their returned row always applies the default
- * exclusion; you may still write PII fields freely).
+ * `includePii`, and a PII column named in a write's `select` is E003, so their
+ * returned row never carries one; you may still write PII fields freely).
  */
 export declare function piiFields(_qi: BuilderCtx, meta: TableMetadata): string[];
 /**
@@ -114,9 +181,10 @@ export declare function piiFields(_qi: BuilderCtx, meta: TableMetadata): string[
  * resolve to a column or the call throws E003, a relation name gets its own
  * message, `select` must name something, `select` and `omit` are exclusive, the
  * list is in TABLE order (a caller's key order must not mint distinct
- * statements), and an explicit `select` of a PII column is the opt-in that
- * returns it while `omit` leaves PII excluded. (builder.ts rather than this
- * module because relations.ts already imports this one.)
+ * statements), and PII is never returned: a write takes no `includePii`, so a
+ * PII column named in `select` is E003 and `omit` leaves PII excluded.
+ * (builder.ts rather than this module because relations.ts already imports
+ * this one.)
  *
  * The point is bytes: `RETURNING *` sends back every column, a large JSON
  * payload included, on every insert. Measured with a 3.1 KB jsonb column at
@@ -143,8 +211,9 @@ export declare function writeProjectionCacheSegment(projection: WriteProjection
  * column so the PII values never leave the database on a write. A PII-tagged
  * PRIMARY KEY column is kept in the projection regardless (the returned row
  * must stay addressable): tag sensitive data, not keys, a PII PK is
- * documented out of scope for stripping. Writes accept no `select`/`includePii`
- * (unlike reads), so this is the whole write-return policy at the SQL level;
+ * documented out of scope for stripping. Writes accept no `includePii` and
+ * their `select` cannot name a PII column, so this is the whole write-return
+ * policy at the SQL level;
  * {@link parseWriteRow} remains as a defense-in-depth strip (a no-op once the
  * SQL already excludes the columns). Derived purely from static per-table
  * schema metadata, so the write SQL cache needs no extra key segment.
@@ -204,32 +273,22 @@ export declare function assertWritable(qi: BuilderCtx, operation: string): void;
  */
 export declare function assertNoGeneratedColumns(qi: BuilderCtx, data: Record<string, unknown>, operation: string): void;
 /**
- * Build a single SET clause entry for update/updateMany.
- *
- * Supports plain values and atomic operator objects ({ set, increment,
- * decrement, multiply, divide }). An operator object is detected ONLY when
- * it has EXACTLY one key that is one of the 5 operator keys, this avoids
- * misinterpreting JSON column values like `{ set: 'x' }` as operators
- * (real operator objects always have exactly one key, and a plain JSON
- * payload that happens to have a single `set` key is extremely unusual).
- * Multi-key objects are always treated as plain (JSON) values.
- *
- * Returns the SQL fragment (e.g., `"view_count" = "view_count" + $3`) and
- * pushes any required params onto the shared params array so that WHERE
- * clause numbering continues correctly afterward.
+ * The atomic operator a SET value names, or `null` when it is a plain value.
+ * THE one rule, read by the SET build, its fingerprint and its cache-hit param
+ * collector, so the three cannot disagree about whether a value is an
+ * operator.
  *
- * `refQualifier` prefixes the column REFERENCE an arithmetic operator reads
- * from (`"view_count" = <qualifier>"view_count" + $n`). A plain `UPDATE` has
- * one table in scope and passes nothing; `upsert` passes the table name,
- * because inside `ON CONFLICT ... DO UPDATE SET` the target table and
- * `excluded` are BOTH in scope and a bare reference is 42702 on PostgreSQL.
- * The assignment target on the left stays bare on every engine (it can only
- * ever be the target table's column), and `set` / literal values reference no
- * column at all, so their SQL is byte-identical with or without a qualifier.
+ * A branded expression or `col()` reference is checked FIRST and answers
+ * `'expr'`: it is a frozen plain object too, and must never reach the
+ * operator test below. An operator is a plain object with EXACTLY one key from
+ * {@link UPDATE_OPERATOR_KEYS}. On a json/jsonb column only `set` is an
+ * operator: an object there IS the JSON value, so `{ increment: 1 }` is the
+ * document `{"increment":1}`, and `{ set: doc }` is the way to write a
+ * document that is itself shaped like `{ set: ... }`.
  */
-export declare function buildSetClause(qi: BuilderCtx, key: string, value: unknown, params: unknown[], refQualifier?: string): string;
+export declare function setOperatorOf(qi: BuilderCtx, key: string, value: unknown): string | null;
 /**
- * Reject a `data` value that reached {@link buildSetClause}'s plain-value
+ * Reject a `data` value that reached {@link buildSetClauses}'s plain-value
  * fallthrough as a plain object with exactly ONE key that is not a known
  * atomic operator. On a scalar column that shape can only be a misspelled
  * operator (`{ incremnt: 1 }`, `{ bogus: 'x' }`); binding it plainly writes the
@@ -248,10 +307,13 @@ export declare function buildSetClause(qi: BuilderCtx, key: string, value: unkno
 export declare function assertBindableSetValue(qi: BuilderCtx, key: string, value: unknown): void;
 /**
  * Fingerprint SET clauses for update/updateMany.
- * Captures key names + operator types (set/increment/etc) but not values.
+ * Captures key names + operator types (set/increment/etc) but not values. An
+ * expression contributes `k:expr(<shape>)` from the same walk that compiles
+ * it, so a statement without one keeps its key byte-identical.
  */
 export declare function fingerprintSet(qi: BuilderCtx, data: Record<string, unknown>): string;
 /**
- * Collect SET params for update/updateMany. Mirrors buildSetClause param order.
+ * Collect SET params for update/updateMany. Mirrors buildSetClauses param order.
  */
 export declare function collectSetParams(qi: BuilderCtx, data: Record<string, unknown>, params: unknown[]): void;
+export {};