turbine-orm 0.49.0 → 0.50.0

package/dist/cjs/query/where.js

@@ -47,6 +47,7 @@ exports.fingerprintScopedWhere = fingerprintScopedWhere;
 exports.buildRelationFilter = buildRelationFilter;
 exports.buildSubWhereForRelation = buildSubWhereForRelation;
 exports.pgTypeForColumn = pgTypeForColumn;
+exports.coerceWhereOperand = coerceWhereOperand;
 exports.enumTypeForColumn = enumTypeForColumn;
 exports.enumCastSuffix = enumCastSuffix;
 exports.assertBindableEqualityValue = assertBindableEqualityValue;
@@ -220,6 +221,7 @@ function collectScalarParams(qi, key, value, params) {
                 meta: qi.tableMeta,
                 table: qi.table,
                 prefix: '',
+                rawColumn,
             });
             return;
         default:
@@ -227,7 +229,7 @@ function collectScalarParams(qi, key, value, params) {
             // the build path, so a cache hit can never silently bind a
             // misspelled-operator object.
             assertBindableEqualityValue(qi, rawColumn, value, getColumnPgType(qi, rawColumn), qi.table);
-            params.push(value);
+            params.push(coerceWhereOperand(qi, qi.tableMeta, rawColumn, value));
             return;
     }
 }
@@ -290,24 +292,26 @@ function collectOperatorParams(qi, column, op, params, refCtx) {
             resolveColumnRef(qi, v, refCtx, op.mode);
         return true;
     };
+    // Mirrors buildOperatorClauses' temporal bind rewrite exactly.
+    const cv = (v) => (refCtx ? coerceWhereOperand(qi, refCtx.meta, refCtx.rawColumn, v) : v);
     if (op.equals !== undefined && op.equals !== null && !skipRef(op.equals)) {
         (0, filters_js_1.assertBindableEqualsOperand)(op.equals, `"${column}"`);
-        params.push(op.equals);
+        params.push(cv(op.equals));
     }
     if (op.gt !== undefined && !skipRef(op.gt))
-        params.push(op.gt);
+        params.push(cv(op.gt));
     if (op.gte !== undefined && !skipRef(op.gte))
-        params.push(op.gte);
+        params.push(cv(op.gte));
     if (op.lt !== undefined && !skipRef(op.lt))
-        params.push(op.lt);
+        params.push(cv(op.lt));
     if (op.lte !== undefined && !skipRef(op.lte))
-        params.push(op.lte);
+        params.push(cv(op.lte));
     if (op.not !== undefined && op.not !== null && !skipRef(op.not))
-        params.push(op.not);
+        params.push(cv(op.not));
     if (op.in !== undefined)
-        params.push(qi.inParam(op.in));
+        params.push(qi.inParam(cv(op.in)));
     if (op.notIn !== undefined)
-        params.push(qi.inParam(op.notIn));
+        params.push(qi.inParam(cv(op.notIn)));
     if (op.contains !== undefined)
         params.push(`%${(0, utils_js_1.escapeLike)(op.contains)}%`);
     if (op.startsWith !== undefined)
@@ -617,6 +621,7 @@ function buildScalarClause(qi, key, value, params, andClauses) {
                 meta: qi.tableMeta,
                 table: qi.table,
                 prefix: '',
+                rawColumn,
             }));
             return;
         default:
@@ -624,7 +629,7 @@ function buildScalarClause(qi, key, value, params, andClauses) {
             // is almost always a misspelled operator (`startWith` for `startsWith`);
             // the guard also runs on the cache-hit param-collect path.
             assertBindableEqualityValue(qi, rawColumn, value, getColumnPgType(qi, rawColumn), qi.table);
-            params.push(value);
+            params.push(coerceWhereOperand(qi, qi.tableMeta, rawColumn, value));
             andClauses.push(`${column} = ${qi.p(params.length)}`);
             return;
     }
@@ -766,11 +771,12 @@ function buildScopedScalarClause(qi, scope, field, value, params, clauses) {
             meta,
             table: scope.table,
             prefix: scope.qualifier,
+            rawColumn: col,
         }));
         return;
     }
     assertBindableEqualityValue(qi, col, value, pgTypeForColumn(qi, meta, col), scope.table);
-    params.push(value);
+    params.push(coerceWhereOperand(qi, meta, col, value));
     clauses.push(`${qCol} = ${qi.p(params.length)}`);
 }
 /**
@@ -822,11 +828,11 @@ function collectScopedScalarParams(qi, scope, field, value, params) {
         }
     }
     if ((0, filters_js_1.isWhereOperator)(value)) {
-        collectOperatorParams(qi, col, value, params, { meta, table: scope.table, prefix: '' });
+        collectOperatorParams(qi, col, value, params, { meta, table: scope.table, prefix: '', rawColumn: col });
         return;
     }
     assertBindableEqualityValue(qi, col, value, pgTypeForColumn(qi, meta, col), scope.table);
-    params.push(value);
+    params.push(coerceWhereOperand(qi, meta, col, value));
 }
 /**
  * Value-invariant fingerprint of a scoped sub-where. Same canonical
@@ -1006,6 +1012,30 @@ function buildSubWhereForRelation(qi, targetTable, subWhere, params) {
 function pgTypeForColumn(_qi, meta, column) {
     return meta.dialectTypes?.[column] ?? meta.pgTypes?.[column] ?? 'text';
 }
+/**
+ * Rewrite a WHERE operand bound against `column` the same way the write path
+ * rewrites a `data` value ({@link coerceTemporalValue}): a JS `Date` on a
+ * `time` / `timetz` column becomes a time-of-day literal (Postgres otherwise
+ * answers `22007 invalid input syntax for type time` for the ISO timestamp the
+ * driver would send), and on a zone-less `date` / `timestamp` column it becomes
+ * the UTC-component literal, so a predicate matches the value a write of the
+ * same `Date` stored.
+ *
+ * This is a VALUE transform only — it never changes the emitted SQL — so the
+ * SQL-template cache is unaffected, and it is applied on the cache-hit
+ * param-collect path as well as the build path.
+ *
+ * `timestamptz` and every non-temporal column are returned by identity.
+ */
+function coerceWhereOperand(qi, meta, column, value) {
+    if (!(value instanceof Date) && !Array.isArray(value))
+        return value;
+    return (0, utils_js_1.coerceTemporalValue)(pgTypeForColumn(qi, meta, column), value, 
+    // Same PostgreSQL + `utcTimestamps` gate as the write path (see
+    // `utcDateTimeWrites` in writes.ts): only the read/write-symmetric engine
+    // gets the zone-less rewrite. Time-of-day always rewrites.
+    qi.dialect.name === 'postgresql' && qi.utcTimestamps !== false);
+}
 /**
  * The Postgres enum type name for a column, when the schema knows one.
  *
@@ -1143,6 +1173,9 @@ function columnRefSql(qi, ref, ctx, mode) {
  */
 function buildOperatorClauses(qi, column, op, params, refCtx) {
     const clauses = [];
+    // Temporal bind rewrite, identical to `collectOperatorParams`. Value-only, so
+    // the emitted SQL (and therefore the template cache) is untouched.
+    const cv = (v) => (refCtx ? coerceWhereOperand(qi, refCtx.meta, refCtx.rawColumn, v) : v);
     if (op.equals !== undefined) {
         if (op.equals === null) {
             clauses.push(`${column} IS NULL`);
@@ -1152,7 +1185,7 @@ function buildOperatorClauses(qi, column, op, params, refCtx) {
         }
         else {
             (0, filters_js_1.assertBindableEqualsOperand)(op.equals, column);
-            params.push(op.equals);
+            params.push(cv(op.equals));
             clauses.push(`${column} = ${qi.p(params.length)}`);
         }
     }
@@ -1161,7 +1194,7 @@ function buildOperatorClauses(qi, column, op, params, refCtx) {
             clauses.push(`${column} > ${columnRefSql(qi, op.gt, refCtx, op.mode)}`);
         }
         else {
-            params.push(op.gt);
+            params.push(cv(op.gt));
             clauses.push(`${column} > ${qi.p(params.length)}`);
         }
     }
@@ -1170,7 +1203,7 @@ function buildOperatorClauses(qi, column, op, params, refCtx) {
             clauses.push(`${column} >= ${columnRefSql(qi, op.gte, refCtx, op.mode)}`);
         }
         else {
-            params.push(op.gte);
+            params.push(cv(op.gte));
             clauses.push(`${column} >= ${qi.p(params.length)}`);
         }
     }
@@ -1179,7 +1212,7 @@ function buildOperatorClauses(qi, column, op, params, refCtx) {
             clauses.push(`${column} < ${columnRefSql(qi, op.lt, refCtx, op.mode)}`);
         }
         else {
-            params.push(op.lt);
+            params.push(cv(op.lt));
             clauses.push(`${column} < ${qi.p(params.length)}`);
         }
     }
@@ -1188,7 +1221,7 @@ function buildOperatorClauses(qi, column, op, params, refCtx) {
             clauses.push(`${column} <= ${columnRefSql(qi, op.lte, refCtx, op.mode)}`);
         }
         else {
-            params.push(op.lte);
+            params.push(cv(op.lte));
             clauses.push(`${column} <= ${qi.p(params.length)}`);
         }
     }
@@ -1200,16 +1233,16 @@ function buildOperatorClauses(qi, column, op, params, refCtx) {
             clauses.push(`${column} != ${columnRefSql(qi, op.not, refCtx, op.mode)}`);
         }
         else {
-            params.push(op.not);
+            params.push(cv(op.not));
             clauses.push(`${column} != ${qi.p(params.length)}`);
         }
     }
     if (op.in !== undefined) {
-        params.push(qi.inParam(op.in));
+        params.push(qi.inParam(cv(op.in)));
         clauses.push(qi.inClause(column, qi.p(params.length), false));
     }
     if (op.notIn !== undefined) {
-        params.push(qi.inParam(op.notIn));
+        params.push(qi.inParam(cv(op.notIn)));
         clauses.push(qi.inClause(column, qi.p(params.length), true));
     }
     const buildLikeClause = (paramRef) => op.mode === 'insensitive' ? qi.dialect.buildInsensitiveLike(column, paramRef) : `${column} LIKE ${paramRef}`;
@@ -1269,7 +1302,10 @@ function vectorOperator(qi, field, rawColumn, metric) {
         throw new errors_js_1.ValidationError(`[turbine] Column "${field}" on table "${qi.table}" is not a vector column ` +
             `(actual type: ${colType}); cannot apply a vector distance operation.`);
     }
-    const op = filters_js_1.VECTOR_METRIC_OPERATORS[metric];
+    // ownLookup, not a bare index: an inherited Object.prototype member
+    // ("constructor", "toString", …) would otherwise resolve to a truthy builtin
+    // and be spliced into the ORDER BY / WHERE clause as its source text.
+    const op = (0, utils_js_1.ownLookup)(filters_js_1.VECTOR_METRIC_OPERATORS, metric);
     if (!op) {
         throw new errors_js_1.ValidationError(`[turbine] Unknown vector metric "${metric}" for column "${field}". ` +
             `Valid metrics: ${Object.keys(filters_js_1.VECTOR_METRIC_OPERATORS).join(', ')}.`);

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

@@ -0,0 +1,172 @@
+/**
+ * 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';
+/**
+ * Normalize one `data` value before it is bound as a write param.
+ *
+ * Two value shapes need rewriting, both a JS `Date` on a temporal column:
+ *
+ * 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
+ *    `22007 invalid input syntax for type time`. Rewritten on every engine.
+ * 2. A zone-less `date` / `timestamp` column on PostgreSQL — the driver's
+ *    local-offset serialization stores the PROCESS's calendar fields, so in a
+ *    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.
+ *
+ * `timestamptz` is deliberately untouched: it stores a real instant and the
+ * driver's local-offset string is already correct for it.
+ *
+ * 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.
+ */
+export declare function coerceWriteValue(qi: BuilderCtx, key: string, value: unknown): unknown;
+/**
+ * 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;
+/**
+ * Reject a `data` value that reached {@link buildSetClause}'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
+ * JSON text `{"bogus":"x"}` into the column and silently corrupts it.
+ *
+ * Deliberately narrow. Skipped for:
+ *  - json / jsonb columns, which legitimately take arbitrary objects;
+ *  - class instances (Buffer for bytea, Decimal wrappers, …), arrays and Dates,
+ *    which {@link isUnmatchedPlainObject} already excludes;
+ *  - multi-key objects, which are never operator-shaped (a real operator object
+ *    has exactly one key) and are far more likely a deliberate payload.
+ *
+ * Shared by the SQL-build path and the cache-hit param-collect path, so a
+ * warmed template can never skip the check.
+ */
+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.
+ */
+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;

package/dist/cjs/query/writes.js

@@ -45,6 +45,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.coerceWriteValue = coerceWriteValue;
 exports.buildReselectByWhere = buildReselectByWhere;
 exports.buildCreate = buildCreate;
 exports.makeCreateReselect = makeCreateReselect;
@@ -62,13 +63,64 @@ exports.parseWriteRow = parseWriteRow;
 exports.assertWritable = assertWritable;
 exports.assertNoGeneratedColumns = assertNoGeneratedColumns;
 exports.buildSetClause = buildSetClause;
+exports.assertBindableSetValue = assertBindableSetValue;
 exports.fingerprintSet = fingerprintSet;
 exports.collectSetParams = collectSetParams;
 const errors_js_1 = require("../errors.js");
 const schema_js_1 = require("../schema.js");
 const compound_unique_js_1 = require("./compound-unique.js");
 const filters_js_1 = require("./filters.js");
+const utils_js_1 = require("./utils.js");
 const whereMod = __importStar(require("./where.js"));
+/**
+ * Normalize one `data` value before it is bound as a write param.
+ *
+ * Two value shapes need rewriting, both a JS `Date` on a temporal column:
+ *
+ * 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
+ *    `22007 invalid input syntax for type time`. Rewritten on every engine.
+ * 2. A zone-less `date` / `timestamp` column on PostgreSQL — the driver's
+ *    local-offset serialization stores the PROCESS's calendar fields, so in a
+ *    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.
+ *
+ * `timestamptz` is deliberately untouched: it stores a real instant and the
+ * driver's local-offset string is already correct for it.
+ *
+ * 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.
+ */
+function coerceWriteValue(qi, key, value) {
+    // Cheap shape check first: the common path costs one check and no lookup.
+    if (!(value instanceof Date) && !Array.isArray(value))
+        return value;
+    // Non-throwing column resolution: this runs on the cache-HIT param-collect
+    // path too, where an unknown key must not turn into a different error than
+    // the build path already raises.
+    const column = (0, utils_js_1.ownLookup)(qi.tableMeta.columnMap, key);
+    if (!column)
+        return value;
+    // Metadata generated by an older Turbine still carries per-column types
+    // (`pgTypes` has always been part of TableMetadata), and a column missing
+    // from the map resolves to undefined → no coercion, today's behavior.
+    return (0, utils_js_1.coerceTemporalValue)(qi.columnPgTypeMap.get(column), value, utcDateTimeWrites(qi));
+}
+/**
+ * Whether the zone-less `date` / `timestamp` UTC rewrite applies.
+ *
+ * PostgreSQL only: MySQL's `TIMESTAMP`/`DATETIME` and SQL Server's
+ * `datetime2` are converted or bound by their own drivers, and MySQL in
+ * particular reads a zone-less literal in the SESSION time zone, so a UTC
+ * literal would be misread there. `utcTimestamps: false` opts out — it is the
+ * same switch that turns off the UTC READ parsing, so the two stay symmetric.
+ */
+function utcDateTimeWrites(qi) {
+    return qi.dialect.name === 'postgresql' && qi.utcTimestamps !== false;
+}
 /**
  * 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
@@ -86,7 +138,7 @@ function buildCreate(qi, args) {
     assertNoGeneratedColumns(qi, args.data, 'create');
     const entries = Object.entries(args.data).filter(([, v]) => v !== undefined);
     const columns = entries.map(([k]) => qi.toSqlColumn(k));
-    const params = entries.map(([, v]) => v);
+    const params = entries.map(([k, v]) => coerceWriteValue(qi, k, v));
     // Enum columns get an explicit `::"EnumName"` cast (see enumTypeForColumn).
     const placeholders = entries.map(([k], i) => `${qi.p(i + 1)}${whereMod.enumCastSuffix(qi, qi.toColumn(k))}`);
     const sql = qi.dialect.buildInsertStatement({
@@ -132,7 +184,9 @@ function makeCreateReselect(qi, insertSql, insertParams, data) {
         let idx = 1;
         for (const pk of qi.tableMeta.primaryKey) {
             const field = qi.tableMeta.reverseColumnMap[pk] ?? (0, schema_js_1.snakeToCamel)(pk);
-            selParams.push(data[field] ?? data[pk] ?? insertId);
+            // Same rewrite the INSERT's own params got: a temporal PK re-fetched with
+            // a raw Date would not match the literal that was just written.
+            selParams.push(coerceWriteValue(qi, field, data[field] ?? data[pk] ?? insertId));
             conds.push(`${qi.q(pk)} = ${qi.p(idx++)}`);
         }
         const where = conds.length > 0 ? ` WHERE ${conds.join(' AND ')}` : '';
@@ -157,7 +211,7 @@ function buildCreateMany(qi, args) {
     const columns = keys.map((k) => qi.toColumn(k));
     const rowValues = args.data.map((row) => {
         const record = row;
-        return keys.map((key) => record[key]);
+        return keys.map((key) => coerceWriteValue(qi, key, record[key]));
     });
     // Use actual Postgres types for array casts in the default PostgreSQL dialect.
     // Enum columns cast to `"EnumName"[]` — the generic text[] fallback would
@@ -357,7 +411,7 @@ function buildUpsert(qi, args) {
     // Build the INSERT part from create data
     const createEntries = Object.entries(args.create).filter(([, v]) => v !== undefined);
     const columns = createEntries.map(([k]) => qi.toSqlColumn(k));
-    const createParams = createEntries.map(([, v]) => v);
+    const createParams = createEntries.map(([k, v]) => coerceWriteValue(qi, k, v));
     // Enum columns get an explicit `::"EnumName"` cast (see enumTypeForColumn).
     const placeholders = createEntries.map(([k], i) => `${qi.p(i + 1)}${whereMod.enumCastSuffix(qi, qi.toColumn(k))}`);
     // The conflict target comes from `where` keys — must be unique/PK columns
@@ -371,7 +425,7 @@ function buildUpsert(qi, args) {
         paramIdx++;
         return clause;
     });
-    const updateParams = updateEntries.map(([, v]) => v);
+    const updateParams = updateEntries.map(([k, v]) => coerceWriteValue(qi, k, v));
     const params = [...createParams, ...updateParams];
     // Global filter → restrict the conflict-UPDATE (soft-delete / tenancy) so an
     // upsert never resurrects a soft-deleted row or writes across tenants. Only
@@ -611,7 +665,7 @@ function buildSetClause(qi, key, value, params) {
             const op = keys[0];
             const opValue = v[op];
             if (op === 'set') {
-                params.push(opValue);
+                params.push(coerceWriteValue(qi, key, opValue));
                 return `${col} = ${qi.p(params.length)}${cast}`;
             }
             // Arithmetic operators: must be finite numbers
@@ -636,12 +690,44 @@ function buildSetClause(qi, key, value, params) {
             }
         }
         // Fall through: multi-key objects or non-operator single-key objects
-        // are treated as plain values (e.g., JSONB column payloads).
+        // are treated as plain values (e.g., JSONB column payloads), unless the
+        // shape can only be a misspelled atomic operator (see below).
+        assertBindableSetValue(qi, key, value);
     }
     // Plain value (including null, Date, Buffer, arrays, JSON objects)
-    params.push(value);
+    params.push(coerceWriteValue(qi, key, value));
     return `${col} = ${qi.p(params.length)}${cast}`;
 }
+/**
+ * Reject a `data` value that reached {@link buildSetClause}'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
+ * JSON text `{"bogus":"x"}` into the column and silently corrupts it.
+ *
+ * Deliberately narrow. Skipped for:
+ *  - json / jsonb columns, which legitimately take arbitrary objects;
+ *  - class instances (Buffer for bytea, Decimal wrappers, …), arrays and Dates,
+ *    which {@link isUnmatchedPlainObject} already excludes;
+ *  - multi-key objects, which are never operator-shaped (a real operator object
+ *    has exactly one key) and are far more likely a deliberate payload.
+ *
+ * Shared by the SQL-build path and the cache-hit param-collect path, so a
+ * warmed template can never skip the check.
+ */
+function assertBindableSetValue(qi, key, value) {
+    if (!(0, filters_js_1.isUnmatchedPlainObject)(value))
+        return;
+    const keys = Object.keys(value);
+    if (keys.length !== 1 || filters_js_1.UPDATE_OPERATOR_KEYS.has(keys[0]))
+        return;
+    const column = qi.toColumn(key);
+    if (whereMod.isJsonColumnType(qi, whereMod.getColumnPgType(qi, column)))
+        return;
+    throw new errors_js_1.ValidationError(`[turbine] Unknown update operator "${keys[0]}" on "${qi.table}.${key}". ` +
+        `Supported: ${[...filters_js_1.UPDATE_OPERATOR_KEYS].join(', ')}. ` +
+        'A plain object is only written as a value on a json/jsonb column.');
+}
 /**
  * Fingerprint SET clauses for update/updateMany.
  * Captures key names + operator types (set/increment/etc) but not values.
@@ -668,9 +754,9 @@ function fingerprintSet(_qi, data) {
 /**
  * Collect SET params for update/updateMany. Mirrors buildSetClause param order.
  */
-function collectSetParams(_qi, data, params) {
+function collectSetParams(qi, data, params) {
     const entries = Object.entries(data).filter(([, v]) => v !== undefined);
-    for (const [, v] of entries) {
+    for (const [k, v] of entries) {
         if (v !== null &&
             typeof v === 'object' &&
             !Array.isArray(v) &&
@@ -679,10 +765,17 @@ function collectSetParams(_qi, data, params) {
             const obj = v;
             const keys = Object.keys(obj);
             if (keys.length === 1 && filters_js_1.UPDATE_OPERATOR_KEYS.has(keys[0])) {
-                params.push(obj[keys[0]]);
+                // `set` is the only operator that binds a user value of arbitrary type;
+                // the arithmetic operators are finite numbers, which coerceWriteValue
+                // returns untouched. Mirrors buildSetClause.
+                params.push(coerceWriteValue(qi, k, obj[keys[0]]));
                 continue;
             }
+            // Mirror the build path's misspelled-operator guard: the SET fingerprint
+            // is `key:eq` for both a plain value and a bogus operator object, so a
+            // cache HIT would otherwise bind the object and skip the check.
+            assertBindableSetValue(qi, k, v);
         }
-        params.push(v);
+        params.push(coerceWriteValue(qi, k, v));
     }
 }

package/dist/cjs/realtime.d.ts

@@ -0,0 +1,70 @@
+/**
+ * turbine-orm — LISTEN/NOTIFY realtime pub/sub
+ *
+ * Postgres LISTEN/NOTIFY is a first-class realtime primitive that neither
+ * Prisma nor Drizzle expose ergonomically. This module backs the thin
+ * `$listen` / `$notify` methods on TurbineClient.
+ *
+ * Design — **one dedicated connection per subscription**:
+ *
+ *   Each `$listen(channel, handler)` acquires its OWN long-lived client from
+ *   the pool, runs `LISTEN "chan"`, and keeps that connection checked out for
+ *   the life of the subscription. This is the simplest correct model: each
+ *   subscription owns its lifecycle, `unsubscribe()` cleanly UNLISTENs and
+ *   releases exactly one connection, and there is no shared multiplexing
+ *   state to reason about. The trade-off is one pool slot per active channel
+ *   — for the handful of channels a typical app listens on, that's a fine
+ *   price for clarity. (A future optimization could multiplex many channels
+ *   over a single shared notification connection.)
+ *
+ * Serverless / HTTP-pool caveat:
+ *
+ *   LISTEN requires a *persistent* TCP connection that can push asynchronous
+ *   notification messages back to the client. Stateless HTTP drivers
+ *   (Neon HTTP, Vercel Postgres over fetch) cannot hold such a connection, so
+ *   `$listen` will surface a clear error rather than hang. `$notify` works
+ *   everywhere — it's a single round-trip `SELECT pg_notify(...)`.
+ */
+import type { PgCompatPool } from './client.js';
+/**
+ * Validate a LISTEN/NOTIFY channel name. Throws ValidationError on anything
+ * that isn't a plain, reasonable-length SQL identifier. This is enforced for
+ * BOTH `$listen` (where the channel is interpolated) and `$notify` (where the
+ * channel is a bound param) — defensive parity, and it catches user typos
+ * loudly.
+ */
+export declare function validateChannel(channel: string): void;
+/** Handler invoked with the raw NOTIFY payload string (empty string if none). */
+export type NotificationHandler = (payload: string) => void;
+/**
+ * A live LISTEN subscription. Call `unsubscribe()` to UNLISTEN, detach the
+ * handler, and release the dedicated connection back to the pool.
+ */
+export interface Subscription {
+    /** The channel this subscription is listening on. */
+    readonly channel: string;
+    /**
+     * Stop listening: runs `UNLISTEN "chan"`, removes the notification listener,
+     * and releases the dedicated connection. Idempotent — safe to call twice.
+     */
+    unsubscribe(): Promise<void>;
+}
+/**
+ * Internal registry handle so TurbineClient can track and tear down active
+ * subscriptions on `disconnect()`.
+ */
+export interface ActiveSubscription extends Subscription {
+    /** Tear down WITHOUT issuing UNLISTEN (used when the pool is being ended). */
+    _forceRelease(): void;
+}
+/**
+ * Acquire a dedicated connection, run `LISTEN "channel"`, and wire the handler.
+ *
+ * @param pool        the pg-compatible pool to check a long-lived client out of
+ * @param channel     channel name — MUST already be validated by the caller
+ * @param quotedChannel  the channel run through quoteIdent (interpolated into SQL)
+ * @param handler     called with each notification's payload
+ * @param onClosed    invoked when the subscription releases, so the client can
+ *                    drop it from its active-subscription registry
+ */
+export declare function createSubscription(pool: PgCompatPool, channel: string, quotedChannel: string, handler: NotificationHandler, onClosed: (sub: ActiveSubscription) => void): Promise<ActiveSubscription>;