turbine-orm 0.81.0 → 0.90.0

package/dist/query/column-ref.d.ts

@@ -0,0 +1,61 @@
+/**
+ * turbine-orm: branded column references
+ *
+ * `{ equals: col('publishedVersionId') }` compares a column against another
+ * column of the same row instead of against a bound value. The reference is
+ * written into the SQL TEXT (`"a" = "b"`), so it is the one operand that
+ * removes the bound value entirely.
+ *
+ * That is why it carries a brand. A plain `{ col: 'id' }` object is exactly
+ * what `JSON.parse` produces from a request body: were that shape a reference,
+ * `delete({ where: { id: body.id } })` with a body of
+ * `{"id":{"equals":{"col":"id"}}}` would compile to `WHERE "id" = "id"` and
+ * delete every row. A symbol cannot come out of `JSON.parse`, a query string, a
+ * form body or a `structuredClone` of parsed input, so only code can build one.
+ * Same reasoning as the `UNSAFE` sentinel.
+ *
+ * `Symbol.for` rather than `Symbol()` because the package ships dual ESM and
+ * CJS builds: a reference built by one copy must be recognized by the other.
+ */
+/** The brand every {@link ColumnRef} carries. Registered, see the module note. */
+export declare const COLUMN_REF: unique symbol;
+/**
+ * A column-to-column comparison operand, built only by {@link col}.
+ *
+ * Accepted by `equals`, `not`, `gt`, `gte`, `lt` and `lte` on a non-JSON
+ * column. The referenced field resolves through the table's column map
+ * (camelCase or snake_case) and compiles to a quoted identifier, so no
+ * parameter is bound. An unknown field throws `ValidationError` (E003), and
+ * `mode: 'insensitive'` cannot be combined with a reference.
+ *
+ * `F` narrows the referenced name to the table's field names when the
+ * surrounding where clause knows the entity type.
+ *
+ * ```ts
+ * import { col } from 'turbine-orm';
+ * where: { currentVersionId: { equals: col('publishedVersionId') } }
+ * // → WHERE "current_version_id" = "published_version_id"
+ * ```
+ */
+export interface ColumnRef<F extends string = string> {
+    readonly col: F;
+    readonly [COLUMN_REF]: true;
+}
+/**
+ * Build a column reference: `{ gt: col('startsAt') }` compares against the
+ * `startsAt` column of the same row.
+ */
+export declare function col<F extends string>(name: F): ColumnRef<F>;
+/** True only for a reference built by {@link col}. */
+export declare function isColumnRef(value: unknown): value is ColumnRef;
+/**
+ * True for the UNBRANDED `{ col: '<name>' }` shape, which is what parsed
+ * request data produces. Callers refuse it with {@link plainColumnRefMessage}
+ * rather than reading it as a value, because whoever wrote it almost certainly
+ * meant a reference.
+ */
+export declare function isPlainColumnRefShape(value: unknown): boolean;
+/** The refusal for a plain `{ col }` object at an operand position. */
+export declare function plainColumnRefMessage(value: {
+    col: string;
+}, operator: string, column: string, table: string): string;

package/dist/query/column-ref.js

@@ -0,0 +1,66 @@
+/**
+ * turbine-orm: branded column references
+ *
+ * `{ equals: col('publishedVersionId') }` compares a column against another
+ * column of the same row instead of against a bound value. The reference is
+ * written into the SQL TEXT (`"a" = "b"`), so it is the one operand that
+ * removes the bound value entirely.
+ *
+ * That is why it carries a brand. A plain `{ col: 'id' }` object is exactly
+ * what `JSON.parse` produces from a request body: were that shape a reference,
+ * `delete({ where: { id: body.id } })` with a body of
+ * `{"id":{"equals":{"col":"id"}}}` would compile to `WHERE "id" = "id"` and
+ * delete every row. A symbol cannot come out of `JSON.parse`, a query string, a
+ * form body or a `structuredClone` of parsed input, so only code can build one.
+ * Same reasoning as the `UNSAFE` sentinel.
+ *
+ * `Symbol.for` rather than `Symbol()` because the package ships dual ESM and
+ * CJS builds: a reference built by one copy must be recognized by the other.
+ */
+import { ValidationError } from '../errors.js';
+/** The brand every {@link ColumnRef} carries. Registered, see the module note. */
+export const COLUMN_REF = Symbol.for('turbine-orm.columnRef');
+/**
+ * Build a column reference: `{ gt: col('startsAt') }` compares against the
+ * `startsAt` column of the same row.
+ */
+export function col(name) {
+    if (typeof name !== 'string' || name.length === 0) {
+        throw new ValidationError('col() takes the name of a field on the table, as a non-empty string.');
+    }
+    const ref = { col: name };
+    // Non-enumerable so a reference prints and compares as `{ col }`; a symbol
+    // key is never visited by `Object.keys`, so no where walker sees it either.
+    Object.defineProperty(ref, COLUMN_REF, { value: true, enumerable: false });
+    return Object.freeze(ref);
+}
+/** True only for a reference built by {@link col}. */
+export function isColumnRef(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        value[COLUMN_REF] === true &&
+        typeof value.col === 'string');
+}
+/**
+ * True for the UNBRANDED `{ col: '<name>' }` shape, which is what parsed
+ * request data produces. Callers refuse it with {@link plainColumnRefMessage}
+ * rather than reading it as a value, because whoever wrote it almost certainly
+ * meant a reference.
+ */
+export function isPlainColumnRefShape(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value) || isColumnRef(value))
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    if (proto !== Object.prototype && proto !== null)
+        return false;
+    const keys = Object.keys(value);
+    return keys.length === 1 && keys[0] === 'col' && typeof value.col === 'string';
+}
+/** The refusal for a plain `{ col }` object at an operand position. */
+export function plainColumnRefMessage(value, operator, column, table) {
+    const name = JSON.stringify(value.col);
+    return (`A plain { col: ${name} } object at '${operator}' on "${column}" for table "${table}" is not a column ` +
+        `reference. Build one with col(${name}) (import { col } from 'turbine-orm'): references carry a ` +
+        'symbol brand so that parsed request data can never name a column. To compare against a value, pass a ' +
+        'string, number, boolean, bigint, Date or Buffer.');
+}

package/dist/query/compound-unique.d.ts

@@ -193,3 +193,24 @@ export declare function whereIdentifiesOneRow(meta: TableMetadata, where: Record
  * anything.
  */
 export declare function upsertWhereMatchesCreate(meta: TableMetadata, where: Record<string, unknown>, create: Record<string, unknown>): boolean;
+/**
+ * A unique key, other than the ones in `pinned`, that a new row could collide
+ * on, or `undefined` when there is none.
+ *
+ * The question MySQL's `ON DUPLICATE KEY UPDATE` raises: it has no conflict
+ * target and updates the row whichever unique key collides first, so a row
+ * that also collides on another key can update a row the caller did not name.
+ * A key collides only when every member holds a value, so a key is ruled out
+ * when a member is NULL (written as null, or absent with no default), when
+ * none of its members is set (defaults are server-generated values in
+ * practice), or when it contains a pinned key (it then collides only where the
+ * pinned key does, on the same row). `undefined` is the safe answer only for
+ * shapes that can never collide; anything uncertain returns the key.
+ */
+export declare function otherCollidingUniqueKey(meta: TableMetadata, pinned: readonly (readonly string[])[], stateOf: (column: string) => 'value' | 'null' | 'absent'): string[] | undefined;
+/**
+ * {@link otherCollidingUniqueKey} for a single-row upsert: the keys `where`
+ * pins, against the values `create` inserts. Read only after
+ * {@link upsertWhereMatchesCreate} holds, so every `where` key is a column.
+ */
+export declare function upsertCreateCollidingKey(meta: TableMetadata, where: Record<string, unknown>, create: Record<string, unknown>): string[] | undefined;

package/dist/query/compound-unique.js

@@ -39,7 +39,7 @@
  * {@link TableMetadata} in a module-level `WeakMap`.
  */
 import { ValidationError } from '../errors.js';
-import { isArrayFilter, isJsonFilter, isVectorFilter, isWhereOperator } from './filters.js';
+import { isArrayFilter, isJsonFilter, isPlainRecord, isVectorFilter, isWhereOperator } from './filters.js';
 import { isInternalCombinator, ownLookup, resolveColumnName, resolveRelationDef } from './utils.js';
 const syntheticKeyCache = new WeakMap();
 /**
@@ -466,32 +466,110 @@ export function upsertWhereMatchesCreate(meta, where, create) {
     }
     return keys > 0;
 }
+/**
+ * A unique key, other than the ones in `pinned`, that a new row could collide
+ * on, or `undefined` when there is none.
+ *
+ * The question MySQL's `ON DUPLICATE KEY UPDATE` raises: it has no conflict
+ * target and updates the row whichever unique key collides first, so a row
+ * that also collides on another key can update a row the caller did not name.
+ * A key collides only when every member holds a value, so a key is ruled out
+ * when a member is NULL (written as null, or absent with no default), when
+ * none of its members is set (defaults are server-generated values in
+ * practice), or when it contains a pinned key (it then collides only where the
+ * pinned key does, on the same row). `undefined` is the safe answer only for
+ * shapes that can never collide; anything uncertain returns the key.
+ */
+export function otherCollidingUniqueKey(meta, pinned, stateOf) {
+    for (const key of uniqueKeyNames(meta)) {
+        if (pinned.some((p) => p.every((c) => key.includes(c))))
+            continue;
+        let sets = false;
+        let nullMember = false;
+        for (const column of key) {
+            const state = stateOf(column);
+            if (state === 'value')
+                sets = true;
+            else if (state === 'null' || defaultsToNull(meta, column))
+                nullMember = true;
+        }
+        if (sets && !nullMember)
+            return key;
+    }
+    return undefined;
+}
+/** A nullable column with no default: absent from an INSERT, it is NULL. */
+function defaultsToNull(meta, column) {
+    const col = meta.columns.find((c) => c.name === column);
+    return col?.nullable === true && !col.hasDefault;
+}
+/**
+ * {@link otherCollidingUniqueKey} for a single-row upsert: the keys `where`
+ * pins, against the values `create` inserts. Read only after
+ * {@link upsertWhereMatchesCreate} holds, so every `where` key is a column.
+ */
+export function upsertCreateCollidingKey(meta, where, create) {
+    const whereColumns = new Set();
+    for (const [key, value] of Object.entries(expandCompoundUniqueWhere(meta, where))) {
+        if (value === undefined)
+            continue;
+        const column = resolveColumnName(meta, key);
+        if (column !== undefined)
+            whereColumns.add(column);
+    }
+    const pinned = uniqueKeyNames(meta).filter((key) => key.every((c) => whereColumns.has(c)));
+    const createState = new Map();
+    for (const [key, value] of Object.entries(create)) {
+        if (value === undefined)
+            continue;
+        const column = resolveColumnName(meta, key);
+        if (column !== undefined)
+            createState.set(column, value === null ? 'null' : 'value');
+    }
+    return otherCollidingUniqueKey(meta, pinned, (c) => createState.get(c) ?? 'absent');
+}
 /** `{ equals: v }` and nothing else (a `mode` beside it changes the match). */
 function isBareEquals(value) {
-    return isPlainObject(value) && Object.keys(value).length === 1 && 'equals' in value;
+    return isPlainRecord(value) && Object.keys(value).length === 1 && 'equals' in value;
 }
 /** Equal non-null key values; two Dates compare by instant, other objects by identity. */
 function sameKeyValue(a, b) {
     return a != null && (a instanceof Date && b instanceof Date ? a.getTime() === b.getTime() : a === b);
 }
-/** A bare value, or an operator object whose `equals` is a value. */
+/**
+ * A bare scalar, or `{ equals: <scalar> }` (optionally with `mode: 'default'`).
+ *
+ * Nothing else pins a column, and the refusals are the point. A column
+ * reference (`{ equals: col('id') }`, or the plain `{ col }` a request body
+ * carries) compiles to `"id" = "id"`, which every row satisfies, so a
+ * `delete({ where: { id: body.id } })` would delete the table. A plain object
+ * is a relation filter or a sub-where, `mode: 'insensitive'` matches every
+ * casing of the value, and a JSON / array / vector filter narrows rather than
+ * identifies.
+ */
 function isPinnedToOneValue(value) {
-    if (value === undefined || value === null)
-        return false;
-    if (isWhereOperator(value)) {
-        const eq = value.equals;
-        return eq !== undefined && eq !== null;
-    }
-    // A JSON / array / vector filter narrows, it does not identify.
-    if (isJsonFilter(value) || isArrayFilter(value) || isVectorFilter(value))
+    if (isIdentityScalar(value))
+        return true;
+    if (!isPlainRecord(value))
         return false;
-    // Anything else that is a plain object is a relation filter or a sub-where,
-    // neither of which pins a column. Dates, Buffers and primitives are values.
-    return !isPlainObject(value);
+    const keys = Object.keys(value).filter((k) => value[k] !== undefined);
+    const op = value;
+    return (keys.every((k) => k === 'equals' || (k === 'mode' && op.mode === 'default')) &&
+        keys.includes('equals') &&
+        isIdentityScalar(op.equals));
 }
-function isPlainObject(value) {
-    if (typeof value !== 'object' || value === null || Array.isArray(value))
-        return false;
-    const proto = Object.getPrototypeOf(value);
-    return proto === Object.prototype || proto === null;
+/** A non-null scalar a unique index compares by value. */
+function isIdentityScalar(value) {
+    switch (typeof value) {
+        case 'string':
+        case 'bigint':
+        case 'boolean':
+            return true;
+        case 'number':
+            return !Number.isNaN(value);
+        case 'object':
+            return value instanceof Date || ArrayBuffer.isView(value);
+        default:
+            return false;
+    }
 }

package/dist/query/deferred.d.ts

@@ -3,10 +3,13 @@
  *
  * Split from builder.ts so the class file focuses on SQL assembly / execution.
  */
+import type { DiagnosticsConfig } from '../diagnostics.js';
 import type { Dialect } from '../dialect.js';
+import type { TurbineLogger } from '../logger.js';
 import type { PgCompatPool, PgCompatQueryResult } from '../pg-types.js';
 import type { SchemaMetadata } from '../schema.js';
-import type { QueryInterface } from './builder.js';
+import type { SqlCommenter, SqlCommentOptions } from './sql-comment.js';
+import type { TableClient } from './table-client.js';
 import type { GlobalFilters, JsonEncoding, RelationLoadStrategy } from './types.js';
 /**
  * Runs a SQL statement and resolves its raw result. Passed to a
@@ -34,6 +37,13 @@ export interface DeferredQuery<T> {
      * rows), so the PostgreSQL path never allocates or consults it.
      */
     reselect?: (exec: ReselectExecutor) => Promise<PgCompatQueryResult>;
+    /**
+     * Set when the statement is a locking read (`lock`). Its locks last until
+     * the transaction ends, so a runner that executes it outside a transaction
+     * (an autocommit pipeline) must refuse it: the rows would be unlocked again
+     * before the caller saw them.
+     */
+    rowLock?: true;
 }
 /**
  * How the ORM hands back a Postgres temporal `infinity` / `-infinity`.
@@ -108,6 +118,14 @@ export interface QueryEvent {
      * batch statements are timed individually. Absent for everything else.
      */
     batch?: 'pipeline' | 'transaction';
+    /**
+     * The `sqlComment` this statement was sent with, exactly as appended
+     * (`/*action='findMany',model='users'*\/`). `sql` stays the commentless
+     * text, so events for one statement shape compare equal whatever the
+     * comment; the text on the wire was `${sql} ${comment}`. Absent when the
+     * statement carried none (no `sqlComment`, raw SQL, transaction control).
+     */
+    comment?: string;
     /**
      * Set on a READ that failed because its connection had already been closed
      * by the server, and that Turbine therefore sent once more on a fresh one.
@@ -167,21 +185,15 @@ export interface QueryInterfaceOptions {
      *
      * Default: `true`. Set to `false` as a nuclear kill switch.
      *
-     * Dev-mode safety net: when `NODE_ENV !== 'production'`, every cache HIT is
+     * Safety net: {@link diagnostics}' `cacheCheck` decides whether a cache HIT is
      * cross-checked by rebuilding the SQL + params fresh and comparing them
      * against the cache-hit result, catching any drift between the fingerprint,
      * SQL-build, and param-collect paths (which has silently corrupted results
-     * before). A mismatch throws a `ValidationError` (E003). This runs only
-     * outside production, so it never touches the production hot path. Set the
-     * env var `TURBINE_DISABLE_CACHE_CHECK=1` to opt out when dev traffic is
-     * perf-sensitive.
-     *
-     * Production sampling: the check is off in production by default. Set
-     * `TURBINE_CACHE_CHECK_SAMPLE` to a float in `(0,1]` to re-verify that
-     * fraction of cache hits under real load (e.g. `0.001` for one in a
-     * thousand). A sampled mismatch logs `console.error` once per distinct
-     * fingerprint AND throws the same `ValidationError` (E003). `0`, unset, or an
-     * unparseable value keeps the check fully off.
+     * before). Every hit in development, none in production, or a sampled
+     * fraction (`{ sample: 0.001 }`); a sampled mismatch is logged once per
+     * distinct fingerprint as well as thrown. Independently of that, every MISS
+     * compares the built and collected params and every HIT checks the param
+     * count, in every mode; any mismatch is an `InvariantError` (E020).
      */
     sqlCache?: boolean;
     /**
@@ -195,6 +207,12 @@ export interface QueryInterfaceOptions {
      * per table).
      */
     sqlCacheSize?: number;
+    /**
+     * The client's `streamIdleTimeoutMs`: how long a cursor stream may wait for
+     * its consumer before Turbine closes it. Default 300000; `0` disables. See
+     * `FindManyStreamArgs.idleTimeoutMs`, which overrides it per call.
+     */
+    streamIdleTimeoutMs?: number;
     /** SQL dialect implementation. Defaults to PostgreSQL. */
     dialect?: Dialect;
     /**
@@ -288,6 +306,25 @@ export interface QueryInterfaceOptions {
      * {@link GlobalFilters}.
      */
     globalFilters?: GlobalFilters;
+    /**
+     * `diagnostics`: per-query advice and the SQL-cache self-check. TurbineClient
+     * resolves it once and hands the same resolved object to every interface it
+     * builds (resolving that again returns it by reference). An interface
+     * constructed directly may pass any `diagnostics` config, or none, and
+     * resolves it at construction, never per call.
+     */
+    diagnostics?: DiagnosticsConfig;
+    /** Where this interface's log lines go. Defaults to the console logger. */
+    logger?: TurbineLogger;
+    /**
+     * `sqlComment`: sqlcommenter key/values appended to every statement this
+     * interface sends (see `TurbineConfig.sqlComment`), resolved at
+     * construction. TurbineClient resolves it once instead and hands every
+     * interface the same commenter as `_sqlCommenter`.
+     */
+    sqlComment?: SqlCommentOptions;
+    /** @internal The client's resolved `sqlComment`, shared by its accessors; wins over `sqlComment`. */
+    _sqlCommenter?: SqlCommenter;
     /** @internal Set by TransactionClient, signals that this QI runs inside an active transaction. */
     _txScoped?: boolean;
     /** @internal Callback from TurbineClient for query event emission. */
@@ -295,9 +332,9 @@ export interface QueryInterfaceOptions {
     /**
      * @internal Factory that builds the per-table query interface. Defaults to
      * `new QueryInterface` (the SQL path). Non-SQL backends (PowDB) supply a
-     * factory returning a structurally-compatible interface that generates their
-     * own query language instead of SQL. The SQL dialects never set this, so their
+     * factory returning a {@link TableClient}, which generates their own query
+     * language instead of SQL. The SQL dialects never set this, so their
      * `table()` behavior is byte-identical.
      */
-    queryInterfaceFactory?: (pool: PgCompatPool, table: string, schema: SchemaMetadata, middlewares: MiddlewareFn[], options: QueryInterfaceOptions) => QueryInterface<object>;
+    queryInterfaceFactory?: (pool: PgCompatPool, table: string, schema: SchemaMetadata, middlewares: MiddlewareFn[], options: QueryInterfaceOptions) => TableClient<object>;
 }

package/dist/query/expr.d.ts

@@ -0,0 +1,217 @@
+/**
+ * turbine-orm: SQL expressions in update data.
+ *
+ * `expr.greatest(col('viewCount'), 100)` and friends are branded node objects,
+ * and `expr.excluded('events')` names the incoming row of an upsert. Both are
+ * written into the SQL TEXT, so both carry a symbol brand: `JSON.parse` cannot
+ * produce one, so request data can never become an expression (the same
+ * reasoning as `col()` and `UNSAFE`). `Symbol.for` so the ESM and CJS copies of
+ * the package recognize each other's nodes. A plain look-alike object
+ * (`{ kind: 'greatest', args: [...] }`) is a VALUE, and on a non-JSON column
+ * the write path refuses it.
+ *
+ * The public types live in `query/types.ts` (`SqlExpr`, `ExcludedRef`). This
+ * module holds the node constructors, their validation, and
+ * {@link compileSetExpr}: the ONE traversal that produces an expression's SQL,
+ * its bound parameters and its cache fingerprint together, so the SET build,
+ * the cache-hit param collector and the fingerprint cannot disagree (the
+ * failure class behind the where-clause cache bugs).
+ *
+ * Where expressions are accepted: `update`, `updateMany`, `upsert`'s `update`,
+ * `createMany`'s `onConflict.update`, and nested update data (which runs
+ * through `update()`). Not in `create` / `createMany` data, where the write
+ * bind seam refuses a node.
+ */
+import type { TableMetadata } from '../schema.js';
+import { type ColumnRef } from './column-ref.js';
+import type { ExcludedRef, SqlExpr } from './types.js';
+import { type BuilderCtx } from './where.js';
+/** The brand every {@link SqlExpr} node carries. */
+export declare const SQL_EXPR: unique symbol;
+/** The brand an {@link ExcludedRef} carries (the incoming row of an upsert). */
+export declare const EXCLUDED_REF: unique symbol;
+/**
+ * An operand of an expression: a JS scalar (string, number, bigint, boolean,
+ * Date, Buffer or null), `col('field')` for the current row's column, or
+ * another expression.
+ */
+export type ExprOperand<V = unknown> = NotInferred<V> | null | ColumnRef | SqlExpr<V>;
+/**
+ * `V` as a type the compiler does not infer from (the pre-TypeScript-5.4
+ * spelling of `NoInfer`, so the published declarations need no newer
+ * compiler). Without it a `col('x')` operand is itself a candidate for `V`,
+ * and `expr.greatest(col('a'), col('b'))` would be typed as producing a
+ * column reference. `V` comes from the expression operands and from where the
+ * result is assigned instead.
+ */
+type NotInferred<V> = [V][V extends unknown ? 0 : never];
+/**
+ * A numeric operand: a number or bigint, `col()` of a numeric column, or a
+ * numeric expression (`string` covers a numeric/decimal column typed as text).
+ * One union-typed `SqlExpr`, not a union of three, so a nested call such as
+ * `expr.add(col('a'), expr.mul(col('b'), 2))` infers without a type argument.
+ */
+export type NumericOperand = number | bigint | null | ColumnRef | SqlExpr<number | bigint | string>;
+/** One `expr.case` arm: when the current row matches `when`, the value is `then`. */
+export interface CaseArm<V = unknown> {
+    /** A predicate on the current row's columns, written like `where`. No relation filters. */
+    readonly when: Record<string, unknown>;
+    readonly then: ExprOperand<V>;
+}
+/** The node an `expr.case` call builds. */
+export interface CaseExpr<V = unknown> extends SqlExpr<V> {
+    readonly kind: 'case';
+    readonly args: readonly CaseArm<V>[];
+    /** The value when no arm matches; absent means NULL. */
+    readonly else?: ExprOperand<V>;
+}
+/**
+ * Builders for SQL expressions in update data. Each returns a frozen, branded
+ * node; the SQL is generated per engine when the update compiles.
+ *
+ * ```ts
+ * import { col, expr } from 'turbine-orm';
+ * await db.posts.update({
+ *   where: { id },
+ *   data: {
+ *     viewCount: expr.greatest(col('viewCount'), 100),
+ *     score: expr.add(col('score'), expr.mul(col('bonus'), 2)),
+ *     editedAt: expr.now(),
+ *   },
+ * });
+ * ```
+ */
+export declare const expr: Readonly<{
+    /** `a + b`. Numbers, bigints, numeric columns and numeric expressions. */
+    add<V extends number | bigint | string = number>(a: NumericOperand, b: NumericOperand): SqlExpr<V>;
+    /** `a - b`. */
+    sub<V extends number | bigint | string = number>(a: NumericOperand, b: NumericOperand): SqlExpr<V>;
+    /** `a * b`. */
+    mul<V extends number | bigint | string = number>(a: NumericOperand, b: NumericOperand): SqlExpr<V>;
+    /**
+     * `a / b`. When both operands are integers (an integer column, an integer
+     * number or bigint, or an integer expression) the division truncates toward
+     * zero on every engine, as the `divide` update operator does on an integer
+     * column. With a non-integer operand it is a decimal division.
+     */
+    div<V extends number | bigint | string = number>(a: NumericOperand, b: NumericOperand): SqlExpr<V>;
+    /** The first non-NULL operand (2 to 8). */
+    coalesce<V>(a: ExprOperand<V>, b: ExprOperand<V>, ...rest: ExprOperand<V>[]): SqlExpr<V>;
+    /**
+     * The largest operand (2 to 8), IGNORING NULLs on every engine (PostgreSQL's
+     * meaning; MySQL and SQLite are rewritten to match). NULL only when every
+     * operand is NULL.
+     */
+    greatest<V>(a: ExprOperand<V>, b: ExprOperand<V>, ...rest: ExprOperand<V>[]): SqlExpr<V>;
+    /** The smallest operand (2 to 8), ignoring NULLs on every engine. */
+    least<V>(a: ExprOperand<V>, b: ExprOperand<V>, ...rest: ExprOperand<V>[]): SqlExpr<V>;
+    /**
+     * `CASE WHEN ... THEN ... ELSE ... END`. Each arm's `when` is a predicate on
+     * the current row's columns written like `where` (no relation filters); the
+     * first matching arm wins. Without `otherwise` an unmatched row gets NULL.
+     */
+    case<V>(arms: readonly CaseArm<V>[], otherwise?: ExprOperand<V>): SqlExpr<V>;
+    /**
+     * The database server's current time, stored in the zone convention Turbine
+     * reads with: a zone-less `timestamp` / `date` gets the UTC wall clock (unless
+     * the client sets `utcTimestamps: false`). On PostgreSQL it is the
+     * TRANSACTION's start time; on MySQL, the statement's. Temporal columns only.
+     */
+    now(): SqlExpr<Date>;
+    /**
+     * The incoming row's value for `field`: inside `upsert`'s `update` (the value
+     * `create` supplies) and `createMany`'s `onConflict.update` (each row's own
+     * value). Refused anywhere else.
+     */
+    excluded<F extends string>(field: F): ExcludedRef<F>;
+}>;
+/** True only for a node built by {@link expr} (any loaded copy of the package). */
+export declare function isSqlExpr(value: unknown): value is SqlExpr;
+/** True only for `expr.excluded(...)`. */
+export declare function isExcludedRef(value: unknown): value is ExcludedRef;
+/**
+ * True for an UNBRANDED object shaped like a node (`{ kind: 'greatest', args }`),
+ * which is what parsed request data produces. The write path refuses it on a
+ * non-JSON column rather than storing it as JSON text.
+ */
+export declare function isPlainExprShape(value: unknown): boolean;
+/** The refusal for {@link isPlainExprShape}. */
+export declare function plainExprShapeMessage(table: string, key: string, kind: string): string;
+/** The refusal for a node at a position that takes values only (create data, `{ set }`). */
+export declare function exprNotAllowedMessage(table: string, key: string, value: SqlExpr | ColumnRef): string;
+/**
+ * Refuse an expression assigned to a column it cannot target in this release
+ * (json/jsonb and array columns). Shared by the walker and the single-row
+ * upsert's `excluded` resolution, so both paths refuse the same columns.
+ */
+export declare function assertExprTarget(qi: BuilderCtx, key: string, value: SqlExpr | ColumnRef, operation: string): string;
+/** What {@link compileSetExpr} needs from its caller (the write module). */
+export interface ExprCompileEnv {
+    readonly qi: BuilderCtx;
+    /** The `data` key being assigned. */
+    readonly targetKey: string;
+    /** The operation, for messages: `update`, `updateMany`, `upsert`, `createMany`. */
+    readonly operation: string;
+    /**
+     * Bind one value leaf (coerced for the target column) and return its
+     * placeholder, cast included. `arithmetic` is the leaf's class when it is an
+     * arithmetic operand, where PostgreSQL types it from its own value rather than
+     * from the target column.
+     */
+    bind(value: unknown, arithmetic?: 'int' | 'dec'): string;
+    /** Render a column of the target row. */
+    column(column: string): string;
+    /** Render the incoming row's column, or absent where `expr.excluded` has no meaning. */
+    readonly excluded?: ((column: string) => string) | undefined;
+    /** The columns the incoming rows supply; `expr.excluded` must name one. */
+    readonly insertColumns?: ReadonlySet<string> | undefined;
+    /** Compile a `case` arm's predicate (already pruned and validated) against the target row. */
+    predicate(when: Record<string, unknown>): string;
+}
+/** One compiled expression. */
+export interface CompiledSetExpr {
+    /** The right-hand side of the assignment. */
+    readonly sql: string;
+    /**
+     * Value-free shape: node kinds, resolved column names, value-leaf positions,
+     * each arm's predicate fingerprint and the `now()` rendering. Never a value.
+     */
+    readonly fingerprint: string;
+    /** Columns of the target row the expression reads (MySQL assignment order). */
+    readonly reads: ReadonlySet<string>;
+}
+/**
+ * Compile one expression (or `col()` reference) assigned to `env.targetKey`.
+ * The single traversal: SQL, params (through `env.bind`, in emission order)
+ * and fingerprint come out of one walk.
+ *
+ * What an expression stores is the same on every engine, by one rule:
+ * arithmetic is integer arithmetic when both operands are integers (integer
+ * columns, integer numbers, bigints, integer expressions), and integer
+ * division truncates toward zero, as `{ divide }` does on an integer column.
+ * Any other numeric operand makes it decimal. A non-integer result is refused
+ * on an integer column, because the engines disagree on converting one (round
+ * half away from zero, round half to even, truncate, or store it unconverted).
+ * The class is decided from the operands' types and the bound values' kinds,
+ * both part of the fingerprint, so the SQL text never depends on anything the
+ * cache key does not capture.
+ */
+export declare function compileSetExpr(env: ExprCompileEnv, value: SqlExpr | ColumnRef): CompiledSetExpr;
+/**
+ * Rewrite every `expr.excluded(f)` in a single-row upsert's `update` to the
+ * value `create` supplies for `f`. The incoming row of a one-row upsert IS
+ * `create`, so the statement path, the lookup-first path (a plain update) and
+ * a nested upsert store the same row. A top-level reference becomes
+ * `{ set: value }`, which writes the value exactly as a plain value would be
+ * written, on every column type (json and array columns take `set` too). A
+ * reference inside an expression becomes a value operand, checked as the
+ * node's constructor checks one; the expression is then compiled by the
+ * update, with the column-type rules every expression gets. Needs only the
+ * table's name and metadata, so the nested-write engine shares it. Returns
+ * `update` by reference when it holds no reference.
+ */
+export declare function resolveExcludedFromCreate(target: {
+    readonly table: string;
+    readonly tableMeta: TableMetadata;
+}, update: Record<string, unknown> | undefined, create: Record<string, unknown> | undefined): Record<string, unknown> | undefined;
+export {};