turbine-orm 0.50.0 → 0.51.0

package/dist/query/writes.js

@@ -21,10 +21,10 @@ import * as whereMod from './where.js';
  *
  * 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`
+ * 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
+ * 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
@@ -59,7 +59,7 @@ export function coerceWriteValue(qi, key, value) {
  * 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
+ * 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) {
@@ -158,7 +158,7 @@ export function buildCreateMany(qi, args) {
         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
+    // Enum columns cast to `"EnumName"[]`, the generic text[] fallback would
     // type the UNNEST output as text, which Postgres refuses to coerce to the
     // enum ("column X is of type Y but expression is of type text").
     const typeCasts = columns.map((col) => {
@@ -166,6 +166,18 @@ export function buildCreateMany(qi, args) {
         return enumType ? `${qi.q(enumType)}[]` : whereMod.getColumnArrayType(qi, col);
     });
     const quotedColumns = columns.map((c) => qi.q(c));
+    // ARRAY-TYPED COLUMNS force the row-at-a-time VALUES form.
+    //
+    // The default PostgreSQL shape is `SELECT * FROM UNNEST($1::text[], …)`,
+    // one bound array per COLUMN. That is a column-major transpose, and it
+    // cannot express an array-valued column: `unnest` flattens, so N rows each
+    // holding a `text[]` arrive as one flat `text[]` and PostgreSQL rejects the
+    // insert with 42804 ("column is of type text[] but expression is of type
+    // text"). Single-row `create` never hit it because it binds each value
+    // directly. Detected from the column's own declared type rather than from
+    // the shape of the first row's value, so a row whose array column happens to
+    // be null or absent still takes the correct form.
+    const hasArrayColumn = columns.some((col) => (qi.columnPgTypeMap.get(col) ?? '').startsWith('_'));
     const built = qi.dialect.buildBulkInsertStatement({
         table: qt,
         columns: quotedColumns,
@@ -173,6 +185,7 @@ export function buildCreateMany(qi, args) {
         columnArrayTypes: typeCasts,
         skipDuplicates: args.skipDuplicates,
         returning: writeReturningColumns(qi),
+        requireRowValues: hasArrayColumn,
     });
     return {
         sql: built.sql,
@@ -184,20 +197,51 @@ export function buildCreateMany(qi, args) {
 export function buildUpdate(qi, args) {
     assertWritable(qi, 'update');
     qi.currentSkip = args.skipGlobalFilters;
-    const dataObj = args.data;
+    // `updatedAt`-tagged columns are filled in before anything reads `data`, so
+    // the SET list, the fingerprint and the param collector all see one object.
+    const dataObj = applyUpdatedAtColumns(qi, args.data);
     assertNoGeneratedColumns(qi, dataObj, 'update');
     // Prisma compound-unique selector (e.g. `{ orgId_userId: { orgId, userId } }`)
     // → the column conjunction, before the empty-`where` guard so the expanded
     // members count as a real predicate.
     const userWhere = expandCompoundUniqueWhere(qi.tableMeta, args.where);
     const lock = args.optimisticLock;
-    // The empty-`where` guard checks the USER predicate only — a global filter
+    // The empty-`where` guard checks the USER predicate only, a global filter
     // must never turn an unguarded mass update into an allowed one.
     const userHasPredicate = !whereMod.userPredicateIsEmpty(qi, userWhere) || !!lock;
     whereMod.assertMutationHasPredicate(qi, 'update', userHasPredicate ? ' WHERE x' : '', args.allowFullTableScan);
     // The SQL is built from the global-filter-merged where (soft-delete keeps an
     // update from touching already-deleted rows).
     const whereObj = (whereMod.mergeGlobalFilter(qi, userWhere) ?? {});
+    // An update with nothing to set is a NO-OP that returns the current row.
+    //
+    // It used to render `UPDATE t SET WHERE …` and fail with a raw PostgreSQL
+    // 42601 syntax error. That is easy to hit honestly: any handler that builds
+    // its payload from optional request fields produces `{}` on a request that
+    // supplied none of them, so a legitimate request turned into a 500. Prisma
+    // treats the same call as a no-op and returns the row, so a ported handler
+    // inherited a crash where the original returned 200.
+    //
+    // The row is re-selected through the same projection a real update would
+    // return (PII columns excluded on tagged tables), and a where matching no
+    // row still raises NotFoundError, so only the SQL differs, not the contract.
+    // `optimisticLock` is excluded: it always has a version column to SET and a
+    // version check that must still run.
+    const hasSetData = Object.values(dataObj).some((v) => v !== undefined);
+    if (!hasSetData && !lock) {
+        const sel = buildReselectByWhere(qi, whereObj);
+        return {
+            sql: sel.sql,
+            params: sel.params,
+            transform: (result) => {
+                const row = result.rows[0];
+                if (!row)
+                    throw new NotFoundError({ table: qi.table, where: args.where, operation: 'update' });
+                return parseWriteRow(qi, row);
+            },
+            tag: `${qi.table}.update`,
+        };
+    }
     const setFp = fingerprintSet(qi, dataObj);
     const whereFp = whereMod.fingerprintWhere(qi, whereObj);
     const ck = lock ? null : `u:${setFp}|${whereFp}${whereMod.globalFilterCacheSegment(qi)}`;
@@ -277,7 +321,7 @@ export function buildUpdate(qi, args) {
                 // Optimistic-lock conflict: the version-checked UPDATE matched no
                 // row. The re-fetch below uses `where` WITHOUT the version
                 // predicate, so it would return the stale row and silently mask
-                // the conflict — detect it from affected-rows here instead, to
+                // the conflict, detect it from affected-rows here instead, to
                 // match the OptimisticLockError thrown on RETURNING/OUTPUT engines.
                 if (lock && (writeResult.rowCount ?? 0) === 0) {
                     throw new OptimisticLockError({
@@ -358,7 +402,7 @@ export function buildUpsert(qi, args) {
     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
+    // The conflict target comes from `where` keys, must be unique/PK columns
     const conflictKeys = Object.keys(upsertWhere).filter((k) => upsertWhere[k] !== undefined);
     const conflictColumns = conflictKeys.map((k) => qi.toSqlColumn(k));
     // Build the UPDATE SET part
@@ -419,10 +463,22 @@ export function buildUpsert(qi, args) {
 export function buildUpdateMany(qi, args) {
     assertWritable(qi, 'updateMany');
     qi.currentSkip = args.skipGlobalFilters;
-    const dataObj = args.data;
+    const dataObj = applyUpdatedAtColumns(qi, args.data);
     assertNoGeneratedColumns(qi, dataObj, 'updateMany');
     whereMod.assertMutationHasPredicate(qi, 'updateMany', whereMod.userPredicateIsEmpty(qi, args.where) ? '' : ' WHERE x', args.allowFullTableScan);
     const whereObj = (whereMod.mergeGlobalFilter(qi, args.where) ?? {});
+    // Nothing to SET: a no-op, for the same reason as `update` above (that path
+    // has the full rationale). Reports `count: 0` because zero rows were
+    // modified, no statement is issued at all, so this is not the count of rows
+    // the predicate MATCHED.
+    if (!Object.values(dataObj).some((v) => v !== undefined)) {
+        return {
+            sql: `SELECT ${qi.p(1)} AS count`,
+            params: [0],
+            transform: () => ({ count: 0 }),
+            tag: `${qi.table}.updateMany`,
+        };
+    }
     const setFp = fingerprintSet(qi, dataObj);
     const whereFp = whereMod.fingerprintWhere(qi, whereObj);
     const ck = `um:${setFp}|${whereFp}${whereMod.globalFilterCacheSegment(qi)}`;
@@ -503,17 +559,49 @@ export function piiFields(_qi, meta) {
 }
 /**
  * The `RETURNING` / `OUTPUT` selection for a write on this table. A table with
- * no PII column returns `'*'` (every column — byte-identical SQL to before);
+ * 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
+ * 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.
  */
+/**
+ * Return `data` with every `updatedAt`-tagged column the caller did not name
+ * set to `now`, or the original object when the table has none.
+ *
+ * Prisma's `@updatedAt` has no turbine equivalent, so a migrated application
+ * had to remember the field on every single update, and the value is usually
+ * load-bearing in the response body, so forgetting it is a silent staleness
+ * bug rather than a crash. The tag is opt-in per column and never inferred
+ * from a column's name, so a schema that does not use it emits byte-identical
+ * SQL and an application already managing its own timestamp is untouched.
+ *
+ * The timestamp is generated CLIENT-side (like Prisma) rather than as a SQL
+ * `now()`, so it flows through the same temporal coercion as any other bound
+ * `Date` and lands in UTC on every engine.
+ *
+ * An explicit value always wins, including an explicit `null`: naming the
+ * column is a statement of intent.
+ */
+export function applyUpdatedAtColumns(qi, data) {
+    const tagged = qi.tableMeta.columns.filter((c) => c.updatedAt);
+    if (tagged.length === 0)
+        return data;
+    let out = null;
+    const now = new Date();
+    for (const col of tagged) {
+        if (Object.hasOwn(data, col.field) && data[col.field] !== undefined)
+            continue;
+        out ??= { ...data };
+        out[col.field] = now;
+    }
+    return out ?? data;
+}
 export function writeReturningColumns(qi) {
     const piiCols = piiColumns(qi, qi.tableMeta);
     if (piiCols.size === 0)
@@ -571,7 +659,7 @@ export function assertNoGeneratedColumns(qi, data, operation) {
         const col = qi.tableMeta.columns.find((c) => c.field === key || c.name === key || c.name === camelToSnake(key));
         if (col?.isGeneratedStored) {
             throw new ValidationError(`[turbine] Cannot ${operation} "${qi.table}": column "${key}" is a GENERATED ALWAYS AS (…) STORED ` +
-                'column whose value the database computes — remove it from your data.');
+                'column whose value the database computes, remove it from your data.');
         }
     }
 }
@@ -580,7 +668,7 @@ export function assertNoGeneratedColumns(qi, data, operation) {
  *
  * 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
+ * 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).

package/dist/realtime.d.ts

@@ -1,11 +1,11 @@
 /**
- * turbine-orm — LISTEN/NOTIFY realtime pub/sub
+ * 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**:
+ * 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
@@ -13,7 +13,7 @@
  *   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
+ *   - 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.)
  *
@@ -23,14 +23,14 @@
  *   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(...)`.
+ *   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
+ * channel is a bound param), defensive parity, and it catches user typos
  * loudly.
  */
 export declare function validateChannel(channel: string): void;
@@ -45,7 +45,7 @@ export interface Subscription {
     readonly channel: string;
     /**
      * Stop listening: runs `UNLISTEN "chan"`, removes the notification listener,
-     * and releases the dedicated connection. Idempotent — safe to call twice.
+     * and releases the dedicated connection. Idempotent, safe to call twice.
      */
     unsubscribe(): Promise<void>;
 }
@@ -61,7 +61,7 @@ export interface ActiveSubscription extends Subscription {
  * 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 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

package/dist/realtime.js

@@ -1,11 +1,11 @@
 /**
- * turbine-orm — LISTEN/NOTIFY realtime pub/sub
+ * 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**:
+ * 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
@@ -13,7 +13,7 @@
  *   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
+ *   - 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.)
  *
@@ -23,7 +23,7 @@
  *   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(...)`.
+ *   everywhere, it's a single round-trip `SELECT pg_notify(...)`.
  */
 import { ConnectionError, ValidationError, wrapPgError } from './errors.js';
 // ---------------------------------------------------------------------------
@@ -33,7 +33,7 @@ import { ConnectionError, ValidationError, wrapPgError } from './errors.js';
  * Strict Postgres identifier: a letter or underscore followed by letters,
  * digits, or underscores. Channel names CANNOT be parameterized in
  * LISTEN/UNLISTEN (`LISTEN $1` is a syntax error), so the channel is the one
- * place an identifier is interpolated into SQL — it MUST pass this regex AND
+ * place an identifier is interpolated into SQL, it MUST pass this regex AND
  * go through `quoteIdent` before reaching the SQL string.
  */
 const CHANNEL_REGEX = /^[A-Za-z_][A-Za-z0-9_]*$/;
@@ -43,7 +43,7 @@ const MAX_CHANNEL_LEN = 63;
  * 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
+ * channel is a bound param), defensive parity, and it catches user typos
  * loudly.
  */
 export function validateChannel(channel) {
@@ -54,7 +54,7 @@ export function validateChannel(channel) {
         throw new ValidationError(`[turbine] $listen/$notify channel "${channel}" exceeds the ${MAX_CHANNEL_LEN}-character Postgres identifier limit`);
     }
     if (!CHANNEL_REGEX.test(channel)) {
-        throw new ValidationError(`[turbine] Invalid $listen/$notify channel "${channel}" — must match /^[A-Za-z_][A-Za-z0-9_]*$/ ` +
+        throw new ValidationError(`[turbine] Invalid $listen/$notify channel "${channel}", must match /^[A-Za-z_][A-Za-z0-9_]*$/ ` +
             '(letters, digits, underscores; cannot start with a digit)');
     }
 }
@@ -62,7 +62,7 @@ export function validateChannel(channel) {
  * 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 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
@@ -77,7 +77,7 @@ export async function createSubscription(pool, channel, quotedChannel, handler,
         throw wrapPgError(err);
     }
     // Verify the checked-out client can actually receive async notifications.
-    // Stateless HTTP drivers return a client with no `.on` — LISTEN would hang
+    // Stateless HTTP drivers return a client with no `.on`, LISTEN would hang
     // forever waiting for messages that can never arrive, so fail loudly now and
     // give the connection straight back.
     if (typeof client.on !== 'function') {

package/dist/schema-builder.d.ts

@@ -1,8 +1,8 @@
 /**
- * turbine-orm — Schema Builder
+ * turbine-orm, Schema Builder
  *
  * TypeScript-first schema definition API. Define your database schema
- * as plain objects — no method chaining, no DSL. Fully type-checked,
+ * as plain objects, no method chaining, no DSL. Fully type-checked,
  * JSON-serializable, and easy to read.
  *
  * @example
@@ -56,9 +56,9 @@ export interface ColumnDef {
     references?: string | ReferenceDef;
     /** Max length for varchar columns */
     maxLength?: number;
-    /** Enum type name — required when `type: 'enum'`. */
+    /** Enum type name, required when `type: 'enum'`. */
     enumName?: string;
-    /** pgvector dimension count — required when `type: 'vector'`. */
+    /** pgvector dimension count, required when `type: 'vector'`. */
     dimensions?: number;
     /** When true, the column is an array of `type` (e.g. `text[]`). */
     array?: boolean;
@@ -73,6 +73,13 @@ export interface ColumnDef {
      * `includePii: true`) and redacted by Studio. Introspection never auto-tags PII.
      */
     pii?: boolean;
+    /**
+     * Set this column to the current time on every `update` that does not name
+     * it explicitly (Prisma's `@updatedAt`). Opt-in per column and never
+     * inferred from the column name: see
+     * {@link import('./schema.js').ColumnMetadata.updatedAt}.
+     */
+    updatedAt?: boolean;
 }
 /** Postgres-level column type (uppercase, as used in DDL) */
 export type ColumnType = 'SERIAL' | 'BIGSERIAL' | 'BIGINT' | 'INTEGER' | 'SMALLINT' | 'TEXT' | 'BOOLEAN' | 'TIMESTAMPTZ' | 'JSONB' | 'UUID' | 'REAL' | 'DOUBLE PRECISION' | 'NUMERIC' | 'BYTEA' | 'DATE' | 'VARCHAR' | 'ENUM' | 'VECTOR';
@@ -99,13 +106,15 @@ export interface ColumnConfig {
     check: string | null;
     /** Whether this column is tagged as PII (personally identifiable information). */
     pii: boolean;
+    /** Whether this column is auto-set to the current time on update. */
+    updatedAt: boolean;
 }
 /**
  * Explicit many-to-many relation declaration for the code-first schema.
  *
  * Auto-detecting m2m from a junction table is intentionally conservative (a
  * junction with payload columns is treated as a first-class entity, not a join
- * table — see `introspect.ts`). This declaration lets users opt in to an m2m
+ * table, see `introspect.ts`). This declaration lets users opt in to an m2m
  * relation explicitly, mirroring how Prisma/Drizzle require an explicit
  * `@relation` / `relation()` for join tables.
  *
@@ -196,7 +205,7 @@ export interface TableDef {
     /**
      * Optional composite primary key. When present, takes precedence over any
      * column-level `primaryKey: true` flags. Column names listed here are the
-     * camelCase JS-facing field names — they will be converted to snake_case
+     * camelCase JS-facing field names, they will be converted to snake_case
      * when emitted as a `PRIMARY KEY (...)` table constraint.
      */
     primaryKey?: readonly string[];
@@ -311,6 +320,8 @@ export declare class ColumnBuilder {
     }): this;
     check(expression: string): this;
     pii(): this;
+    /** Auto-set this column to the current time on every update. Prisma's `@updatedAt`. */
+    updatedAt(): this;
     array(): this;
     build(): ColumnConfig;
 }
@@ -331,7 +342,7 @@ export declare function table(columns: Record<string, ColumnBuilder>): TableDef;
  *
  * This is the runtime bridge for the code-first m2m API: `defineSchema` only
  * produces DDL, so after `introspect()`ing the live database you call this to
- * attach the m2m relations you declared. It is PURELY ADDITIVE — existing
+ * attach the m2m relations you declared. It is PURELY ADDITIVE, existing
  * belongsTo/hasMany/hasOne relations are preserved, and a declared relation is
  * skipped (not overwritten) if its name already exists on the source table.
  *

package/dist/schema-builder.js

@@ -1,8 +1,8 @@
 /**
- * turbine-orm — Schema Builder
+ * turbine-orm, Schema Builder
  *
  * TypeScript-first schema definition API. Define your database schema
- * as plain objects — no method chaining, no DSL. Fully type-checked,
+ * as plain objects, no method chaining, no DSL. Fully type-checked,
  * JSON-serializable, and easy to read.
  *
  * @example
@@ -25,7 +25,7 @@
 /** Maps shorthand names to actual Postgres type strings */
 const TYPE_MAP = {
     // `serial` maps to SERIAL (int4). Its values fit in a JS `number` and pg
-    // returns them as numbers — so the generated `number` type is accurate.
+    // returns them as numbers, so the generated `number` type is accurate.
     // For 64-bit auto-increment keys use `bigserial` (int8), noting that values
     // above Number.MAX_SAFE_INTEGER read back as string. (Changed in 0.24.0;
     // `serial` previously emitted BIGSERIAL.)
@@ -37,7 +37,7 @@ const TYPE_MAP = {
     text: 'TEXT',
     varchar: 'VARCHAR',
     boolean: 'BOOLEAN',
-    // `timestamp` is an honest alias for TIMESTAMPTZ (timezone-aware) — Turbine
+    // `timestamp` is an honest alias for TIMESTAMPTZ (timezone-aware), Turbine
     // has always emitted TIMESTAMPTZ for it. `timestamptz` is the explicit spelling.
     timestamp: 'TIMESTAMPTZ',
     timestamptz: 'TIMESTAMPTZ',
@@ -51,7 +51,7 @@ const TYPE_MAP = {
     double: 'DOUBLE PRECISION',
     numeric: 'NUMERIC',
     bytea: 'BYTEA',
-    // Sentinels — the real DDL type is derived from `enumName` / `dimensions`
+    // Sentinels, the real DDL type is derived from `enumName` / `dimensions`
     // in schema-sql.ts, never from these placeholders.
     enum: 'ENUM',
     vector: 'VECTOR',
@@ -95,6 +95,7 @@ function resolveColumn(def) {
         isArray: def.array ?? false,
         check: def.check ?? null,
         pii: def.pii ?? false,
+        updatedAt: def.updatedAt ?? false,
     };
 }
 /** Type guard: is this index declaration a doc-field expression index? */
@@ -188,7 +189,7 @@ export function defineSchema(input, options) {
             }
             // Validate composite PK references real columns and clear column-level PKs
             // for those columns so we don't double-emit `PRIMARY KEY` clauses.
-            // Composite PK members are implicitly NOT NULL — preserve that even
+            // Composite PK members are implicitly NOT NULL, preserve that even
             // when the user clears the column-level `primaryKey: true` flag.
             if (pk && pk.length > 0) {
                 for (const colName of pk) {
@@ -197,7 +198,7 @@ export function defineSchema(input, options) {
                             `Known columns: ${Object.keys(columns).join(', ') || '(none)'}`);
                     }
                     // A composite PK at the table level supersedes any column-level
-                    // `primaryKey: true` flag — silently clear it so DDL emission
+                    // `primaryKey: true` flag, silently clear it so DDL emission
                     // produces a single, valid table-level PRIMARY KEY constraint.
                     // Force NOT NULL since PK columns can never be nullable.
                     const c = columns[colName];
@@ -228,7 +229,7 @@ function camelToSnakeLocal(s) {
     return s.replace(/[A-Z]/g, (c) => `_${c.toLowerCase()}`);
 }
 // ---------------------------------------------------------------------------
-// Legacy compat — ColumnBuilder still works for existing code
+// Legacy compat, ColumnBuilder still works for existing code
 // ---------------------------------------------------------------------------
 export class ColumnBuilder {
     _config;
@@ -249,6 +250,7 @@ export class ColumnBuilder {
             isArray: false,
             check: null,
             pii: false,
+            updatedAt: false,
         };
     }
     serial() {
@@ -359,6 +361,11 @@ export class ColumnBuilder {
         this._config.pii = true;
         return this;
     }
+    /** Auto-set this column to the current time on every update. Prisma's `@updatedAt`. */
+    updatedAt() {
+        this._config.updatedAt = true;
+        return this;
+    }
     array() {
         this._config.isArray = true;
         return this;
@@ -421,7 +428,7 @@ export function table(columns) {
  *
  * This is the runtime bridge for the code-first m2m API: `defineSchema` only
  * produces DDL, so after `introspect()`ing the live database you call this to
- * attach the m2m relations you declared. It is PURELY ADDITIVE — existing
+ * attach the m2m relations you declared. It is PURELY ADDITIVE, existing
  * belongsTo/hasMany/hasOne relations are preserved, and a declared relation is
  * skipped (not overwritten) if its name already exists on the source table.
  *
@@ -460,7 +467,7 @@ export function applyManyToManyRelations(meta, def) {
         const sourceTable = tableDef.name;
         const sourceMeta = tables[sourceTable];
         if (!sourceMeta)
-            continue; // table not present in introspected metadata — skip
+            continue; // table not present in introspected metadata, skip
         const relations = { ...sourceMeta.relations };
         for (const m of tableDef.manyToMany) {
             // Additive-only: never clobber an existing relation name.

package/dist/schema-metadata.d.ts

@@ -1,9 +1,9 @@
 /**
- * turbine-orm — defineSchema() → SchemaMetadata bridge
+ * turbine-orm, defineSchema() → SchemaMetadata bridge
  *
  * Converts a code-first {@link SchemaDef} (the output of `defineSchema()`)
  * into the runtime {@link SchemaMetadata} shape that the query builder,
- * `TurbineClient`, and the non-SQL engines consume — without touching a
+ * `TurbineClient`, and the non-SQL engines consume, without touching a
  * live database.
  *
  * Why this exists: the historical converter path (`introspect()` +
@@ -49,7 +49,7 @@ import { type SchemaDef } from './schema-builder.js';
 /**
  * Convert a code-first {@link SchemaDef} into runtime {@link SchemaMetadata}.
  *
- * Pure function — no database connection, no side effects, input untouched.
+ * Pure function, no database connection, no side effects, input untouched.
  * The output is shaped identically to the `SCHEMA` constant `turbine generate`
  * emits from introspection, so it can be handed to any consumer that expects
  * introspected metadata: `new TurbineClient(config, metadata)`,

package/dist/schema-metadata.js

@@ -1,9 +1,9 @@
 /**
- * turbine-orm — defineSchema() → SchemaMetadata bridge
+ * turbine-orm, defineSchema() → SchemaMetadata bridge
  *
  * Converts a code-first {@link SchemaDef} (the output of `defineSchema()`)
  * into the runtime {@link SchemaMetadata} shape that the query builder,
- * `TurbineClient`, and the non-SQL engines consume — without touching a
+ * `TurbineClient`, and the non-SQL engines consume, without touching a
  * live database.
  *
  * Why this exists: the historical converter path (`introspect()` +
@@ -77,13 +77,13 @@ function udtName(config) {
         return 'vector';
     return DDL_TO_UDT[config.type];
 }
-/** Server-generated (sequence-backed) types — pg's `nextval(...)` default. */
+/** Server-generated (sequence-backed) types, pg's `nextval(...)` default. */
 function isSerialType(type) {
     return type === 'SERIAL' || type === 'BIGSERIAL';
 }
 /**
  * Resolve the raw column part of a `references: 'table.column'` target to a
- * snake_case column name — accepting either the camelCase field name or the
+ * snake_case column name, accepting either the camelCase field name or the
  * snake_case DDL name, mirroring how schema-sql.ts accepts both table forms.
  */
 function resolveColumnName(raw, target) {
@@ -163,7 +163,7 @@ function mapIndexes(tableDef, declared) {
 /**
  * Convert a code-first {@link SchemaDef} into runtime {@link SchemaMetadata}.
  *
- * Pure function — no database connection, no side effects, input untouched.
+ * Pure function, no database connection, no side effects, input untouched.
  * The output is shaped identically to the `SCHEMA` constant `turbine generate`
  * emits from introspection, so it can be handed to any consumer that expects
  * introspected metadata: `new TurbineClient(config, metadata)`,
@@ -197,7 +197,7 @@ function mapIndexes(tableDef, declared) {
 export function schemaDefToMetadata(def) {
     // ----- Pass 1: resolve every table's snake_case names for FK lookups -----
     // Lookup accepts the accessor key (camelCase), the DDL name (snake_case),
-    // and the explicit `accessor` field — same tolerance as schema-sql.ts.
+    // and the explicit `accessor` field, same tolerance as schema-sql.ts.
     const lookup = new Map();
     for (const [key, tableDef] of Object.entries(def.tables)) {
         const fieldToColumn = new Map();
@@ -224,7 +224,7 @@ export function schemaDefToMetadata(def) {
             if (parts.length !== 2)
                 continue;
             const target = lookup.get(parts[0]);
-            // Reference to a table outside this SchemaDef — skip, exactly like
+            // Reference to a table outside this SchemaDef, skip, exactly like
             // introspection skips FKs whose target is excluded from the table set.
             if (!target)
                 continue;
@@ -246,14 +246,14 @@ export function schemaDefToMetadata(def) {
     // catalog: legacy-first naming, per-column disambiguation for several FKs to
     // the same target, and collision resolution against scalar column fields
     // (json/jsonb `unknown`-typed shadows keep the historical name). The old
-    // local reimplementation had NO collision guard — `posts.user` (text) +
+    // local reimplementation had NO collision guard, `posts.user` (text) +
     // `userId references users.id` produced a relation `user` that shadowed the
     // scalar, and two FKs deriving the same name silently clobbered each other
     // (N-4).
     //
     // Constraint names are synthesized in pg's default `<table>_<column>_fkey`
     // form; they only feed the referential-action lookup and composite-FK
-    // naming (never hit here — `references:` is single-column by design).
+    // naming (never hit here, `references:` is single-column by design).
     const fkEntries = [];
     const fkActions = new Map();
     for (const fk of foreignKeys) {