turbine-orm 0.34.0 → 0.36.0

package/dist/query/writes.d.ts

@@ -0,0 +1,131 @@
+/**
+ * turbine-orm: write compilation (extracted from builder.ts)
+ *
+ * SQL builders for the mutating operations (create / createMany / update /
+ * delete / upsert / updateMany / deleteMany) plus the write-projection helpers
+ * (writeReturningColumns / writeReselectSelection / parseWriteRow, the PII
+ * column set, optimistic-lock and atomic-operator SET clauses). All functions
+ * take a {@link BuilderCtx} first argument; WHERE compilation is reused from
+ * where.ts (via `whereMod`), and the cache / dialect / row-parse primitives
+ * 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 { 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';
+/**
+ * Build a `SELECT * ... WHERE <predicate>` that re-fetches the row(s) matched
+ * by a write's `where` clause. Used by the `'reselect'` result strategy to
+ * 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>): {
+    sql: string;
+    params: unknown[];
+};
+export declare function buildCreate<T extends object>(qi: BuilderCtx, args: CreateArgs<T>): 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.
+ */
+export declare function makeCreateReselect<T extends object>(qi: BuilderCtx, insertSql: string, insertParams: unknown[], data: Record<string, unknown>): DeferredQuery<T>['reselect'];
+export declare function buildCreateMany<T extends object>(qi: BuilderCtx, args: CreateManyArgs<T>): DeferredQuery<T[]>;
+export declare function buildUpdate<T extends object>(qi: BuilderCtx, args: UpdateArgs<T>): DeferredQuery<T>;
+export declare function buildDelete<T extends object>(qi: BuilderCtx, args: DeleteArgs<T>): DeferredQuery<T>;
+export declare function buildUpsert<T extends object>(qi: BuilderCtx, args: UpsertArgs<T>): DeferredQuery<T>;
+export declare function buildUpdateMany<T extends object>(qi: BuilderCtx, args: UpdateManyArgs<T>): DeferredQuery<{
+    count: number;
+}>;
+export declare function buildDeleteMany<T extends object>(qi: BuilderCtx, args: DeleteManyArgs<T>): DeferredQuery<{
+    count: number;
+}>;
+/**
+ * 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
+ * empty set for any table with no PII column, so untagged schemas keep their
+ * byte-identical SQL.
+ */
+export declare function piiColumns(_qi: BuilderCtx, meta: TableMetadata): Set<string>;
+/**
+ * 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).
+ */
+export declare function piiFields(_qi: BuilderCtx, meta: TableMetadata): string[];
+/**
+ * The `RETURNING` / `OUTPUT` selection for a write on this table. A table with
+ * no PII column returns `'*'` (every column — byte-identical SQL to before);
+ * a table WITH PII columns returns an explicit quoted list of every non-PII
+ * 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;
+ * {@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.
+ */
+export declare function writeReturningColumns(qi: BuilderCtx): ReturningSelection;
+/**
+ * String form of {@link writeReturningColumns} for a `SELECT` list (the
+ * `'reselect'` result strategy re-fetches via a SELECT, not RETURNING).
+ * `'*'` when there is no PII column; otherwise the comma-joined quoted list.
+ */
+export declare function writeReselectSelection(qi: BuilderCtx): string;
+/**
+ * Parse a write's returned row (create/update/upsert/delete), then strip the
+ * table's PII fields: the write-side read policy. On PII-tagged tables the
+ * statement's RETURNING/OUTPUT already omits these columns (see
+ * {@link writeReturningColumns}), so this strip is defense-in-depth and a
+ * no-op. Untagged tables incur only one `for` over a zero-length field list,
+ * so behavior is unchanged.
+ */
+export declare function parseWriteRow(qi: BuilderCtx, row: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Reject any write against a view (H4). Views are introspected with
+ * `isView: true` and are read-only in every engine; a write raises a
+ * {@link ValidationError} (E003) rather than emitting SQL Postgres would
+ * reject (or, worse, silently applying to an updatable view).
+ */
+export declare function assertWritable(qi: BuilderCtx, operation: string): void;
+/**
+ * Reject a write whose `data` names a `GENERATED ALWAYS AS (...) STORED`
+ * column (H3). Postgres computes these from other columns and errors if you
+ * try to write them; we fail early with a clear {@link ValidationError} (E003)
+ * instead of surfacing a cryptic driver error. Undefined values are ignored
+ * (they're stripped from the statement anyway).
+ */
+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.
+ */
+export declare function buildSetClause(qi: BuilderCtx, key: string, value: unknown, params: unknown[]): string;
+/**
+ * Fingerprint SET clauses for update/updateMany.
+ * Captures key names + operator types (set/increment/etc) but not values.
+ */
+export declare function fingerprintSet(_qi: BuilderCtx, data: Record<string, unknown>): string;
+/**
+ * Collect SET params for update/updateMany. Mirrors buildSetClause param order.
+ */
+export declare function collectSetParams(_qi: BuilderCtx, data: Record<string, unknown>, params: unknown[]): void;