uql-orm 0.81.0 → 0.83.0

package/dist/util/date.js

@@ -0,0 +1,19 @@
+/**
+ * `YYYY-MM-DD HH:mm:ss.SSS` in UTC, then `zone`: how a date is written, whichever machine writes it. Not
+ * `toISOString` as it is, whose `T` and `Z` MySQL rejects outright ("Invalid default value").
+ */
+export function utcTimestamp(date, zone = '') {
+    return date.toISOString().replace('T', ' ').replace('Z', zone);
+}
+/** A time of day that names no zone, which `Date` would read in the process's own. */
+const ZONELESS_TIME = /T[\d:.]+$/;
+/**
+ * A timestamp's text as the `Date` it names, the one rule every driver and hydration read dates by: UTC
+ * where it names no zone, its own offset where it does, a bare day at UTC midnight, and the fraction cut
+ * to the milliseconds a `Date` holds. Text that is none of these, such as `infinity`, stays text.
+ */
+export function decodeDate(text) {
+    const iso = text.replace(' ', 'T').replace(/(\.\d{3})\d+/, '$1');
+    const date = new Date(ZONELESS_TIME.test(iso) ? `${iso}Z` : iso);
+    return Number.isNaN(date.getTime()) ? text : date;
+}

package/dist/util/dialect.util.d.ts

@@ -1,5 +1,5 @@
 import type { IndexType } from '../schema/types.js';
-import { type AggregateCall, type CascadeType, type EntityData, type EntityId, type EntityIndexMeta, type EntityMeta, type FieldKey, type FieldOptions, type FieldUpdateOp, type JsonUpdateOp, type OnFieldCallback, type Query, type QueryAggMap, type QueryExclude, type QueryGroupMap, type QueryOptions, QueryRaw, type QuerySearch, type QuerySelect, type QuerySelectValue, type QuerySortDirection, type QuerySizeComparisonOps, type QuerySortMap, type QueryTextSearchOptions, type QueryVectorQuery, type QueryVectorSearch, type QueryWhere, type RelationKey, type UpdatePayload, type VectorDistance } from '../type/index.js';
+import { type AggregateCall, type CascadeType, type EntityData, type EntityId, type EntityIndexMeta, type EntityMeta, type FieldKey, type FieldOptions, type FieldUpdateOp, type JsonUpdateOp, type OnFieldCallback, type Query, type QueryAggMap, type QueryConflictPaths, type QueryExclude, type QueryGroupMap, type QueryOptions, QueryRaw, type QuerySearch, type QuerySelect, type QuerySelectValue, type QuerySortDirection, type QuerySizeComparisonOps, type QuerySortMap, type QueryTextSearchOptions, type QueryVectorQuery, type QueryVectorSearch, type QueryWhere, type QueryWhereArray, type RelationKey, type UpdatePayload, type VectorDistance } from '../type/index.js';
 export type CallbackKey = keyof Pick<FieldOptions, 'onInsert' | 'onUpdate'>;
 /** The keys of `payload` a write persists as columns. */
 export declare function filterFieldKeys<E>(meta: EntityMeta<E>, payload: EntityData<E> | UpdatePayload<E>, callbackKey: CallbackKey): FieldKey<E>[];
@@ -50,10 +50,18 @@ export declare function isCascadable(action: CascadeType, configuration?: boolea
  */
 export declare function isPagedQuery<E>(q: QuerySearch<E>): boolean;
 /**
- * `q` selecting nothing but the id: what a write hands its backend's own read builder to settle the
- * rows it will name. The cast is unavoidable - a computed key is not a `QuerySelect` key to the
- * compiler - so it is spelled once here rather than in each querier.
- */
+ * Each of `keys` switched on, as a `$select` or conflict paths name them. This and the `where*` builders
+ * below hold the casts a statement built in generic code needs: a key read at run time is no key of
+ * these maps to the compiler, whose values it works out per entity.
+ */
+export declare function keySet<E>(keys: readonly FieldKey<E>[]): QueryConflictPaths<E>;
+/** `where`, or no `$where`, with `key` held to `value` as well: spread, so the two `AND`. */
+export declare function whereWith<E>(key: FieldKey<E>, value: unknown, where?: QueryWhere<E>): QueryWhere<E>;
+/** The `$where` holding each of `keys` to what `valueOf` reads for it. */
+export declare function whereEach<E>(keys: readonly FieldKey<E>[], valueOf: (key: FieldKey<E>) => unknown): QueryWhere<E>;
+/** The `$where` any one of `clauses` satisfies. */
+export declare function whereAnyOf<E>(clauses: QueryWhereArray<E>): QueryWhere<E>;
+/** `q` selecting nothing but the id: what a write hands its backend's own read builder to settle the rows it will name. */
 export declare function idOnlyQuery<E>(meta: EntityMeta<E>, q: QuerySearch<E>): Query<E>;
 /**
  * The map form of a `$select` value, or `undefined` for the raw-array form. Centralizes the one

package/dist/util/dialect.util.js

@@ -2,7 +2,7 @@ import { getContext, UqlSecurityError } from '../context/context.js';
 import { soleIdOf } from '../entity/metadata/definition.js';
 import { QueryRaw, resolveAggregateOp, SOFT_DELETE_FILTER, } from '../type/index.js';
 import { DEFAULT_VECTOR_DISTANCE, VECTOR_INDEX_TYPES } from '../type/vector.js';
-import { getFieldKeys, isDatabaseWritten } from './field.util.js';
+import { defaultReadKeys, fieldKeys, isDatabaseWritten } from './field.util.js';
 import { entityName, getKeys, hasKeys, isOperatorObject, isScalarId, isRecord, isWhereMap, someKey, } from './object.util.js';
 import { UqlUsageError } from './uqlError.js';
 /** The keys of `payload` a write persists as columns. */
@@ -50,12 +50,7 @@ export function getInsertFieldKeys(meta, payloads) {
     for (const record of payloads) {
         addInsertFieldKeys(meta, record, seen, keys);
     }
-    for (const key of getKeys(meta.fields)) {
-        if (meta.fields[key].onInsert !== undefined && !seen.has(key)) {
-            keys.push(key);
-        }
-    }
-    return keys;
+    return [...keys, ...fieldKeys(meta, (field) => field.onInsert !== undefined).filter((key) => !seen.has(key))];
 }
 export function getFieldCallbackValue(val) {
     return typeof val === 'function' ? val() : val;
@@ -72,7 +67,7 @@ export function fillOnFields(meta, payload, callbackKey) {
     const payloads = Array.isArray(payload) ? payload : [payload];
     // By presence, not truthiness, as `addInsertFieldKeys` above reads it: `onInsert: 0` and `onInsert: ''`
     // are values a caller meant, and a falsy one was silently never filled.
-    const keys = getKeys(meta.fields).filter((key) => meta.fields[key][callbackKey] !== undefined);
+    const keys = fieldKeys(meta, (field) => field[callbackKey] !== undefined);
     if (keys.length === 0) {
         return payloads;
     }
@@ -120,12 +115,28 @@ export function isPagedQuery(q) {
     return q.$sort !== undefined || q.$limit !== undefined || q.$skip !== undefined;
 }
 /**
- * `q` selecting nothing but the id: what a write hands its backend's own read builder to settle the
- * rows it will name. The cast is unavoidable - a computed key is not a `QuerySelect` key to the
- * compiler - so it is spelled once here rather than in each querier.
+ * Each of `keys` switched on, as a `$select` or conflict paths name them. This and the `where*` builders
+ * below hold the casts a statement built in generic code needs: a key read at run time is no key of
+ * these maps to the compiler, whose values it works out per entity.
  */
+export function keySet(keys) {
+    return Object.fromEntries(keys.map((key) => [key, true]));
+}
+/** `where`, or no `$where`, with `key` held to `value` as well: spread, so the two `AND`. */
+export function whereWith(key, value, where) {
+    return { ...where, [key]: value };
+}
+/** The `$where` holding each of `keys` to what `valueOf` reads for it. */
+export function whereEach(keys, valueOf) {
+    return Object.fromEntries(keys.map((key) => [key, valueOf(key)]));
+}
+/** The `$where` any one of `clauses` satisfies. */
+export function whereAnyOf(clauses) {
+    return { $or: clauses };
+}
+/** `q` selecting nothing but the id: what a write hands its backend's own read builder to settle the rows it will name. */
 export function idOnlyQuery(meta, q) {
-    return { ...q, $select: Object.fromEntries(meta.ids.map((key) => [key, true])) };
+    return { ...q, $select: keySet(meta.ids) };
 }
 /**
  * The map form of a `$select` value, or `undefined` for the raw-array form. Centralizes the one
@@ -165,7 +176,7 @@ export function normalizeScalarFieldSelection(meta, select, exclude) {
             }
         }
     }
-    const allFields = getFieldKeys(meta.fields);
+    const allFields = defaultReadKeys(meta);
     if (!excludedFields) {
         return allFields;
     }
@@ -217,10 +228,7 @@ export function findVectorIndex(meta, key) {
  * serves no other, else cosine. The one fallback every engine resolves, so none can rank by another.
  */
 export function vectorDistanceOf(meta, key, search) {
-    return (search.$distance ??
-        meta.fields[key]?.distance ??
-        findVectorIndex(meta, key)?.distance ??
-        DEFAULT_VECTOR_DISTANCE);
+    return (search.$distance ?? meta.fields[key]?.distance ?? findVectorIndex(meta, key)?.distance ?? DEFAULT_VECTOR_DISTANCE);
 }
 /**
  * Whether a `$where` filters by vector distance anywhere in its tree, `$and`/`$or`/`$not` included.
@@ -271,7 +279,7 @@ export function fieldUpdateOf(key, value) {
  */
 export function whereIds(meta, ids) {
     if (Array.isArray(ids) ? ids.every(isScalarId) : isScalarId(ids)) {
-        return { [soleIdOf(meta, 'addressing by a bare id value')]: ids };
+        return whereWith(soleIdOf(meta, 'addressing by a bare id value'), ids);
     }
     return (Array.isArray(ids) ? { $or: ids } : ids);
 }
@@ -492,11 +500,11 @@ export function fulltextWeights(index) {
         return undefined;
     }
     if (index.type !== 'fulltext') {
-        throw new TypeError(`a column weight ranks a fulltext index, and this one is ${index.type ?? 'btree'}`);
+        throw new UqlUsageError(`a column weight ranks a fulltext index, and this one is ${index.type ?? 'btree'}`);
     }
     const weights = index.entries.map(({ weight = 1 }) => {
         if (!Number.isInteger(weight) || weight < 1 || weight > MAX_TEXT_WEIGHT) {
-            throw new TypeError(`a column weight is a whole number from 1 to ${MAX_TEXT_WEIGHT}, not ${weight}`);
+            throw new UqlUsageError(`a column weight is a whole number from 1 to ${MAX_TEXT_WEIGHT}, not ${weight}`);
         }
         return weight;
     });

package/dist/util/field.util.d.ts

@@ -1,4 +1,4 @@
-import { type ColumnFamily, type EntityMeta, type FieldKey, type FieldOptions, type StampEvent, type RelationAggregateSpec } from '../type/index.js';
+import { type ColumnFamily, type EntityMeta, type FieldKey, type FieldMeta, type FieldOptions, type StampEvent, type RelationAggregateSpec } from '../type/index.js';
 /** The family of a logical field type, or `undefined` where it names none. */
 export declare function columnFamily(type: unknown): ColumnFamily | undefined;
 /**
@@ -39,11 +39,11 @@ export declare function isSoleIdField<E>(meta: EntityMeta<E>, field: FieldOption
  * states its width. The one answer the create statement and the diff both read.
  */
 export declare function isAutoIncrement(field: FieldOptions, isPrimaryKey: boolean): boolean;
+/** The fields `meta` declares whose options `pick` accepts, in declaration order, each as the entity's own key. */
+export declare function fieldKeys<E>(meta: EntityMeta<E>, pick: (field: FieldMeta) => unknown): FieldKey<E>[];
 /**
  * The fields a read answers with where it names none. A relation aggregate is left out unless it asks
  * for `eager: true`: it reads the related rows, which is what a relation does, and a relation is loaded
  * only when a query asks for it. Naming one in `$select` reads it, whatever the default.
  */
-export declare function getFieldKeys<E>(fields: {
-    [K in FieldKey<E>]?: FieldOptions;
-}): FieldKey<E>[];
+export declare function defaultReadKeys<E>(meta: EntityMeta<E>): FieldKey<E>[];

package/dist/util/field.util.js

@@ -83,11 +83,19 @@ export function isAutoIncrement(field, isPrimaryKey) {
         return field.autoIncrement;
     return isPrimaryKey && columnFamily(field.type) === 'numeric' && !field.onInsert && !field.references;
 }
+/** The fields `meta` declares whose options `pick` accepts, in declaration order, each as the entity's own key. */
+export function fieldKeys(meta, pick) {
+    const fields = meta.fields;
+    return getKeys(fields).filter((key) => {
+        const field = fields[key];
+        return field !== undefined && Boolean(pick(field));
+    });
+}
 /**
  * The fields a read answers with where it names none. A relation aggregate is left out unless it asks
  * for `eager: true`: it reads the related rows, which is what a relation does, and a relation is loaded
  * only when a query asks for it. Naming one in `$select` reads it, whatever the default.
  */
-export function getFieldKeys(fields) {
-    return getKeys(fields).filter((field) => fields[field].eager ?? !aggregateOf(fields[field]));
+export function defaultReadKeys(meta) {
+    return fieldKeys(meta, (field) => field.eager ?? !aggregateOf(field));
 }

package/dist/util/fieldOption.util.d.ts

@@ -1,6 +1,6 @@
 import { type ColumnFamily, type FamilyOf, type FieldOptions, QueryRaw, type StampEvent } from '../type/index.js';
 /**
- * The column family each field option means anything on, or `'*'` where it applies to every column.
+ * The column families each field option means anything on, or `'*'` where it applies to every column.
  * Exhaustive over {@link FieldOptions}, so a new option cannot be added without placing it - the
  * discipline `INDEX_FEATURE_LABELS` uses for index features.
  */
@@ -23,7 +23,7 @@ declare const FIELD_OPTION_FAMILY: {
     readonly version: 'numeric';
     readonly columnType: '*';
     readonly length: 'string';
-    readonly precision: 'numeric';
+    readonly precision: readonly ["numeric", "date"];
     readonly scale: 'numeric';
     readonly nullable: '*';
     readonly unique: '*';
@@ -91,8 +91,10 @@ type DeadOptions<O> = (O extends {
     readonly nullable: true;
 } ? 'nullable' : never);
 type Given<O> = Extract<keyof O, keyof FieldOptions>;
+/** The families option `K` applies to, `'*'` for every one. */
+type OptionFamilies<K extends keyof FieldOptions> = (typeof FIELD_OPTION_FAMILY)[K] extends readonly (infer F)[] ? F : (typeof FIELD_OPTION_FAMILY)[K];
 type Offending<O> = {
-    [K in Given<O>]: (typeof FIELD_OPTION_FAMILY)[K] extends OptionsFamily<O> | '*' ? K extends DeadOptions<O> ? K : never : K;
+    [K in Given<O>]: [Extract<OptionFamilies<K>, OptionsFamily<O> | '*'>] extends [never] ? K : K extends DeadOptions<O> ? K : never;
 }[Given<O>];
 /**
  * Every option `O` states but cannot use, mapped to `never`, so one that would be ignored does not compile.

package/dist/util/fieldOption.util.js

@@ -3,7 +3,7 @@ import { columnFamily, isInlinedExpression } from './field.util.js';
 import { getKeys } from './object.util.js';
 import { constantSql } from './raw.js';
 /**
- * The column family each field option means anything on, or `'*'` where it applies to every column.
+ * The column families each field option means anything on, or `'*'` where it applies to every column.
  * Exhaustive over {@link FieldOptions}, so a new option cannot be added without placing it - the
  * discipline `INDEX_FEATURE_LABELS` uses for index features.
  */
@@ -26,7 +26,8 @@ const FIELD_OPTION_FAMILY = {
     version: 'numeric',
     columnType: '*',
     length: 'string',
-    precision: 'numeric',
+    // A decimal's digits, or a timestamp's fractional-second digits.
+    precision: ['numeric', 'date'],
     scale: 'numeric',
     nullable: '*',
     unique: '*',
@@ -116,11 +117,11 @@ export function fieldOptionConflict(opts) {
     // conflicts always reports the same one. An option no rule knows is a typo, which `@Field`'s own check
     // reports where it can still be spelled right.
     for (const key of getKeys(FIELD_OPTION_FAMILY)) {
-        const applies = FIELD_OPTION_FAMILY[key];
+        const applies = [FIELD_OPTION_FAMILY[key]].flat();
         if (opts[key] === undefined)
             continue;
-        if (family && applies !== '*' && applies !== family) {
-            return `cannot use '${key}': it applies to a ${applies} column, not to a ${family} one`;
+        if (family && !applies.includes('*') && !applies.includes(family)) {
+            return `cannot use '${key}': it applies to a ${applies.join(' or ')} column, not to a ${family} one`;
         }
         const dead = deadOn(opts, key);
         if (dead) {

package/dist/util/hook.util.d.ts

@@ -11,4 +11,4 @@ export type HookContext = {
  * Hooks are invoked with `this` bound to the payload via `call`,
  * so mutations go directly to the original object.
  */
-export declare function runHooks<E extends object>(entity: Type<E>, event: HookEvent, payloads: E[], ctx: HookContext): Promise<void>;
+export declare function runHooks<E extends object>(entity: Type<E>, event: HookEvent, payloads: readonly E[], ctx: HookContext): Promise<void>;

package/dist/util/hook.util.js

@@ -1,4 +1,5 @@
 import { getMeta } from '../entity/index.js';
+import { UqlUsageError } from './uqlError.js';
 /**
  * Run all registered hooks for the given event on each payload.
  * Hooks are invoked with `this` bound to the payload via `call`,
@@ -9,9 +10,15 @@ export async function runHooks(entity, event, payloads, ctx) {
     const registrations = meta.hooks?.[event];
     if (!registrations?.length)
         return;
+    // A prototype is typed `any`, so what is read off it is typed here, where it enters.
+    const prototype = entity.prototype;
     for (const payload of payloads) {
         for (const { methodName } of registrations) {
-            const result = entity.prototype[methodName].call(payload, ctx);
+            const method = prototype[methodName];
+            if (typeof method !== 'function') {
+                throw new UqlUsageError(`'${entity.name}' runs '${methodName}' on ${event}, but has no such method`);
+            }
+            const result = method.call(payload, ctx);
             if (result instanceof Promise)
                 await result;
         }

package/dist/util/index.d.ts

@@ -7,6 +7,7 @@ export * from './ddlExpression.util.js';
 export * from './logger.js';
 export * from './object.util.js';
 export * from './raw.js';
+export * from './triggerWrite.js';
 export * from './rowKey.util.js';
 export * from './relationQuery.util.js';
 export * from './sql.util.js';

package/dist/util/index.js

@@ -7,6 +7,7 @@ export * from './ddlExpression.util.js';
 export * from './logger.js';
 export * from './object.util.js';
 export * from './raw.js';
+export * from './triggerWrite.js';
 export * from './rowKey.util.js';
 export * from './relationQuery.util.js';
 export * from './sql.util.js';

package/dist/util/logger.d.ts

@@ -3,8 +3,8 @@ import type { Logger, LoggingOptions } from '../type/logger.js';
  * Default implementation of the Logger interface using console methods.
  */
 export declare class DefaultLogger implements Logger {
-    logQuery(query: string, values?: unknown[], duration?: number): void;
-    logSlowQuery(query: string, values?: unknown[], duration?: number): void;
+    logQuery(query: string, values?: readonly unknown[], duration?: number): void;
+    logSlowQuery(query: string, values?: readonly unknown[], duration?: number): void;
     logWarn(message: string): void;
     logError(message: string, error?: unknown): void;
     logInfo(message: string): void;
@@ -37,7 +37,7 @@ export declare class LoggerWrapper implements Logger {
     constructor(options?: LoggingOptions, config?: LoggerWrapperConfig);
     /** Whether `logQuery` would ever actually surface bound values, given the configured levels/slowQuery/logValues. */
     willLogValues(): boolean;
-    logQuery(query: string, values?: unknown[], duration?: number): void;
+    logQuery(query: string, values?: readonly unknown[], duration?: number): void;
     logWarn(message: string): void;
     logError(message: string, error?: unknown): void;
     logInfo(message: string): void;

package/dist/util/object.util.js

@@ -1,8 +1,9 @@
+import { UqlUsageError } from './uqlError.js';
 export function throwPendingTransaction() {
-    throw TypeError('pending transaction');
+    throw new UqlUsageError('pending transaction');
 }
 export function throwNoPendingTransaction() {
-    throw TypeError('not a pending transaction');
+    throw new UqlUsageError('not a pending transaction');
 }
 export function clone(value) {
     if (typeof value !== 'object' || value === null) {

package/dist/util/raw.d.ts

@@ -1,4 +1,4 @@
-import { ColumnRef, type EntitySql, type EntityWhere, type EntityWhereMeta, QueryRaw, type QueryRawFn, type ComputedRefs, type RefMap, type TriggerRowName, type Type } from '../type/index.js';
+import { type EntitySql, type EntityWhere, type EntityWhereMeta, QueryRaw, type QueryRawFn, type ComputedRefs, type RefMap, type TriggerRowName, type Type } from '../type/index.js';
 /**
  * Raw SQL, where an interpolated value binds, a `refs` field renders its column, and a `raw` renders
  * in place: `raw`GREATEST(0, ${user.credits} - ${amount})``. A callback writes whatever it writes, so
@@ -27,10 +27,9 @@ export declare function entitySql<E>(sql: EntitySql<E>): QueryRaw;
 /** A definition's predicate, its callback resolved the way {@link entitySql} resolves one. */
 export declare function entityWhere<E>(where: EntityWhere<E>): EntityWhereMeta<E>;
 /**
- * The fields of `E` as the row a trigger body reads them off, qualified by the side it names: `NEW."col"`
- * against the incoming row, `OLD."col"` against the outgoing one. Columns only, never a relation's
- * aggregate: that is a subquery, and a trigger fires on one row rather than over a table to correlate to.
+ * The fields of `entity` as the row a trigger body reads them off, qualified by the side it names:
+ * `NEW."col"` against the incoming row, `OLD."col"` against the outgoing one. Bound to the entity, as
+ * {@link refs} are, so each names its own column wherever it renders, a write to another table included.
+ * Columns only: a relation's aggregate is a subquery, and a trigger fires on one row, not over a table.
  */
-export declare function rowRefs<E>(qualifier: TriggerRowName): RefMap<E>;
-/** One field of a trigger's row, for code that names it by its key rather than off {@link rowRefs}. */
-export declare function rowColumn(qualifier: TriggerRowName, key: string): ColumnRef;
+export declare function rowRefs<E>(entity: Type<E>, qualifier: TriggerRowName): RefMap<E>;

package/dist/util/raw.js

@@ -2,6 +2,7 @@ import { getMeta } from '../entity/metadata/definition.js';
 import { ColumnRef, QueryRaw, RAW_TEXT, RelationAggregate, } from '../type/index.js';
 import { aggregateOf, isInlinedExpression } from './field.util.js';
 import { entityName, hasKeys } from './object.util.js';
+import { UqlUsageError } from './uqlError.js';
 export function raw(value, ...rest) {
     if (!isTemplateStrings(value)) {
         return new QueryRaw(value);
@@ -78,22 +79,19 @@ function rowsOf(q) {
 function relationAggregate(spec) {
     return new RelationAggregate(spec, (opts) => {
         if (!opts.entity) {
-            throw new TypeError(`'${spec.relation}' was read off a definition's refs, so it renders only inside its entity's SQL`);
+            throw new UqlUsageError(`'${spec.relation}' was read off a definition's refs, so it renders only inside its entity's SQL`);
         }
         opts.dialect.appendRelationAggregate(opts.ctx, opts.entity, spec, opts.prefix);
     });
 }
 /**
- * The fields of `E` as the row a trigger body reads them off, qualified by the side it names: `NEW."col"`
- * against the incoming row, `OLD."col"` against the outgoing one. Columns only, never a relation's
- * aggregate: that is a subquery, and a trigger fires on one row rather than over a table to correlate to.
+ * The fields of `entity` as the row a trigger body reads them off, qualified by the side it names:
+ * `NEW."col"` against the incoming row, `OLD."col"` against the outgoing one. Bound to the entity, as
+ * {@link refs} are, so each names its own column wherever it renders, a write to another table included.
+ * Columns only: a relation's aggregate is a subquery, and a trigger fires on one row, not over a table.
  */
-export function rowRefs(qualifier) {
-    return new Proxy({}, { get: (_, key) => rowColumn(qualifier, String(key)) });
-}
-/** One field of a trigger's row, for code that names it by its key rather than off {@link rowRefs}. */
-export function rowColumn(qualifier, key) {
-    return columnRef(undefined, key, qualifier);
+export function rowRefs(entity, qualifier) {
+    return new Proxy({}, { get: (_, key) => columnRef(entity, String(key), qualifier) });
 }
 /**
  * One field as SQL, against its own entity or, read off a definition, the entity rendering it. A
@@ -103,7 +101,7 @@ function columnRef(entity, key, qualifier) {
     return new ColumnRef(key, (opts) => {
         const owner = entity ?? opts.entity;
         if (!owner) {
-            throw new TypeError(`'${key}' was read off a definition's refs, so it renders only inside its entity's SQL`);
+            throw new UqlUsageError(`'${key}' was read off a definition's refs, so it renders only inside its entity's SQL`);
         }
         renderColumn(getMeta(owner), key, { ...opts, entity: owner }, qualifier);
     });
@@ -119,7 +117,7 @@ function renderColumn(meta, key, opts, qualifier) {
     if (field && isInlinedExpression(field)) {
         // A relation aggregate is a subquery correlated to a table in scope, and a trigger's row is not one.
         if (qualifier !== undefined && aggregateOf(field)) {
-            throw new TypeError(`'${entityName(meta)}.${key}' reads a relation, which a trigger's row cannot: it fires on one row, ` +
+            throw new UqlUsageError(`'${entityName(meta)}.${key}' reads a relation, which a trigger's row cannot: it fires on one row, ` +
                 'with no table in scope to correlate a subquery to. Name the columns it is derived from instead.');
         }
         scope.ctx.append('(');

package/dist/util/sqlLiteral.d.ts

@@ -2,7 +2,14 @@
 export declare function escapeSingleQuotes(val: string): string;
 /** The text a MySQL string literal's body stands for: its backslash escapes and doubled quotes undone. */
 export declare function unescapeMysqlString(body: string): string;
-/** Escape `value` for Postgres, SQLite and related dialects (single-quote doubling). */
+/** How a Postgres timestamp says it is UTC. */
+export declare const PG_UTC = "+00";
+/** Escape `value` for SQLite and SQL Server (single-quote doubling). */
 export declare const escapeAnsiSqlLiteral: (value: unknown) => string;
+/**
+ * Escape `value` for the Postgres family: ANSI, a date marked UTC, which a `TIMESTAMPTZ` otherwise reads
+ * in the session's zone.
+ */
+export declare const escapePgSqlLiteral: (value: unknown) => string;
 /** Escape `value` for MySQL and MariaDB (backslash escaping). */
 export declare const escapeMysqlSqlLiteral: (value: unknown) => string;

package/dist/util/sqlLiteral.js

@@ -1,6 +1,8 @@
 // SQL literal escaping for `Dialect.escape`: ANSI quote doubling, or MySQL's backslashes. UQL binds
 // values instead, so this is the hand-written-SQL hatch, and inline MySQL literals break under
 // `NO_BACKSLASH_ESCAPES` or a GBK-like charset: prefer bound parameters. Postgres arrays are separate.
+import { utcTimestamp } from './date.js';
+import { UqlUsageError } from './uqlError.js';
 const SINGLE_QUOTE = /'/g;
 /** Doubles every single quote in `val`, the ANSI escaping shared by string literals and JSON path keys. */
 export function escapeSingleQuotes(val) {
@@ -42,12 +44,8 @@ function bytesToHexLiteral(bytes) {
  * A factory, not a function taking `escapeString` as an argument: threading it through every call
  * measured 1.1-1.5x slower. Rejects unsupported types rather than stringifying them into SQL.
  */
-function createEscaper(escapeString) {
-    /**
-     * `YYYY-MM-DD HH:mm:ss.SSS` in UTC, so the SQL is the same whichever machine wrote it. Not `toISOString`
-     * as it is, whose `T` and `Z` MySQL rejects outright ("Invalid default value").
-     */
-    const dateLiteral = (date) => escapeString(date.toISOString().replace('T', ' ').replace('Z', ''));
+function createEscaper(escapeString, zone = '') {
+    const dateLiteral = (date) => escapeString(utcTimestamp(date, zone));
     const sqlList = (arr) => {
         let sql = '';
         for (let i = 0; i < arr.length; i++) {
@@ -73,7 +71,7 @@ function createEscaper(escapeString) {
         if ('toSqlString' in value && typeof value.toSqlString === 'function') {
             return String(value.toSqlString());
         }
-        throw new TypeError('escapeSqlLiteral: plain objects are not supported; use bound parameters or JSON.stringify + a string column.');
+        throw new UqlUsageError('escapeSqlLiteral: plain objects are not supported; use bound parameters or JSON.stringify + a string column.');
     };
     const escapeValue = (value) => {
         if (value === undefined || value === null) {
@@ -92,12 +90,19 @@ function createEscaper(escapeString) {
                 return escapeObject(value);
             default:
                 // A symbol or a function, or a future JS type: none of them may silently become SQL.
-                throw new TypeError(`escapeSqlLiteral: unsupported value type '${typeof value}'; use bound parameters.`);
+                throw new UqlUsageError(`escapeSqlLiteral: unsupported value type '${typeof value}'; use bound parameters.`);
         }
     };
     return escapeValue;
 }
-/** Escape `value` for Postgres, SQLite and related dialects (single-quote doubling). */
+/** How a Postgres timestamp says it is UTC. */
+export const PG_UTC = '+00';
+/** Escape `value` for SQLite and SQL Server (single-quote doubling). */
 export const escapeAnsiSqlLiteral = createEscaper(ansiStringLiteral);
+/**
+ * Escape `value` for the Postgres family: ANSI, a date marked UTC, which a `TIMESTAMPTZ` otherwise reads
+ * in the session's zone.
+ */
+export const escapePgSqlLiteral = createEscaper(ansiStringLiteral, PG_UTC);
 /** Escape `value` for MySQL and MariaDB (backslash escaping). */
 export const escapeMysqlSqlLiteral = createEscaper(mysqlStringLiteral);

package/dist/util/triggerWrite.d.ts

@@ -0,0 +1,15 @@
+import type { EntityPredicate, QueryRaw, Type, UpdatePayload, WritableKey, WriteRow } from '../type/index.js';
+/**
+ * A row inserted by a trigger's body, into any table: `insertInto(PostAudit, { postId: newRow.id })`.
+ * Each value is a literal or SQL, a row's ref most often, and every engine renders it, SQL Server's
+ * set-based trigger included, where it inserts one row for each the statement touched.
+ */
+export declare function insertInto<E extends object>(entity: Type<E>, row: WriteRow<E>): QueryRaw;
+/** The rows `q.$where` names updated by a trigger's body: `updateTable(Post, { $where: { id: newRow.postId } }, set)`. */
+export declare function updateTable<E extends object>(entity: Type<E>, q: {
+    readonly $where: EntityPredicate<E>;
+}, set: UpdatePayload<E, QueryRaw, WritableKey<E>, never>): QueryRaw;
+/** The rows `q.$where` names deleted by a trigger's body, outright: a soft delete is an `updateTable`. */
+export declare function deleteFrom<E extends object>(entity: Type<E>, q: {
+    readonly $where: EntityPredicate<E>;
+}): QueryRaw;

package/dist/util/triggerWrite.js

@@ -0,0 +1,20 @@
+import { raw } from './raw.js';
+/**
+ * A row inserted by a trigger's body, into any table: `insertInto(PostAudit, { postId: newRow.id })`.
+ * Each value is a literal or SQL, a row's ref most often, and every engine renders it, SQL Server's
+ * set-based trigger included, where it inserts one row for each the statement touched.
+ */
+export function insertInto(entity, row) {
+    return written({ kind: 'insert', entity, row });
+}
+/** The rows `q.$where` names updated by a trigger's body: `updateTable(Post, { $where: { id: newRow.postId } }, set)`. */
+export function updateTable(entity, q, set) {
+    return written({ kind: 'update', entity, set, where: q.$where });
+}
+/** The rows `q.$where` names deleted by a trigger's body, outright: a soft delete is an `updateTable`. */
+export function deleteFrom(entity, q) {
+    return written({ kind: 'delete', entity, where: q.$where });
+}
+function written(write) {
+    return raw(({ ctx, dialect, rows }) => dialect.triggerWrite(ctx, write, rows));
+}

package/package.json

@@ -3,7 +3,7 @@
   "homepage": "https://uql-orm.dev",
   "description": "The JSON-native TypeScript ORM for Bun, Browsers, Edge, Deno, Node, Workers. Supports PostgreSQL, PGlite, MySQL, MariaDB, SQLite, CockroachDB, SQL Server, Turso, Neon, Cloudflare D1 and MongoDB. Queries are plain JSON, typed to the leaf.",
   "license": "MIT",
-  "version": "0.81.0",
+  "version": "0.83.0",
   "type": "module",
   "engines": {
     "node": ">=24"

package/skills/uql-orm/SKILL.md

@@ -74,7 +74,7 @@ export class Post {
 }
 ```
 
-- Every `@Field` states its `type` (`String`, `Number`, `Boolean`, `Date`, `BigInt`, or a column type such as `'uuid'`, `'text'`, `'jsonb'`), except a foreign key, which takes `references` and inherits the target key's type.
+- Every `@Field` states its `type` (`String`, `Number`, `Boolean`, `Date` (an instant, bound and read as UTC on every engine; `TIMESTAMPTZ` on Postgres and CockroachDB, `DATETIME(3)` on MySQL and MariaDB; `precision` sets its fractional-second digits), `BigInt`, or a column type such as `'uuid'`, `'text'`, `'jsonb'`), except a foreign key, which takes `references` and inherits the target key's type.
 - A column is nullable unless it says `nullable: false`, and its property must admit `null` to match: `title?: string | null`. A property typed without `| null` on a nullable column is a compile error.
 - An engine's own column type is a `raw` constant, ``columnType: raw`tsvector` ``, rendered verbatim and carrying its own `length`/`precision`: never a bare string.
 - Members are named by callbacks, never by strings: `mappedBy: (post) => post.author`, `references: (post) => post.authorId`.
@@ -84,7 +84,7 @@ export class Post {
   an update must carry the version it read (a compile error otherwise), and one against a row someone else moved on throws `UqlOptimisticLockError` (kind `optimisticLock`, HTTP 409). Its updates name one row by its id; save and upsert are refused.
 - `@Field({ computed })` is a value the database produces, on a `readonly` property: SQL over the row, ``(u) => raw`${u.first} || ' ' || ${u.last}` ``, or a relation aggregate, `(order) => order.items.count()`.
   `stored: true` makes the SQL a generated column; `stored: ['insert', 'update']` makes it a stamp, a trigger writing it on those events whoever writes the row (``computed: raw`CURRENT_TIMESTAMP` ``), where `onUpdate` covers only uql's own writes.
-- `@Trigger({ on: 'afterUpdate', of: (post) => [post.status], where: { $old: { status: 'draft' } }, run })` is a trigger the database fires; `where` holds a `$where` predicate per row it names, or SQL off the rows. `run` reads `{ newRow }` on insert, `{ newRow, oldRow }` on update, `{ oldRow }` on delete, and returns the engine's own SQL, one body for every engine or `{ postgres, mssql, ... }` where they differ (SQL Server fires per statement, reading `inserted`/`deleted` as tables, with no `before*` and no `where`). MongoDB has none, and refuses a write to an entity declaring one.
+- `@Trigger({ on: 'afterUpdate', of: (post) => [post.status], where: { $old: { status: 'draft' } }, run })` is a trigger the database fires (`defineEntity`'s `triggers` or `defineTrigger` without decorators); `where` holds a `$where` predicate per row it names, or SQL off the rows. `run` takes `(newRow, oldRow)`, each only where the event has it (no `oldRow` on insert, no `newRow` on delete), and returns the body: `insertInto(Audit, { postId: newRow.id })`, `updateTable(Audit, { $where: { postId: newRow.id } }, { status: newRow.status })` or `deleteFrom(Audit, { $where: { postId: oldRow.id } })`, typed by the entity written and rendered on every engine (no `onInsert`/`onUpdate` fills, so an insert names each field uql fills on insert unless its column has a `defaultValue`; `$where` reads the entity's own fields; no entity filters, security ones included, so a soft-delete entity is hard-deleted; an update or delete naming no rows is refused; no `$inc`/`$mul`/`$push` on SQL Server), several joined in one `raw`. Anything else is `raw` SQL over the refs, one body for every engine or `{ postgres, mssql, ... }` where they differ (SQL Server fires per statement, reading `inserted`/`deleted` as tables, with no `before*` and no `where`). MongoDB has none, and refuses a write to an entity declaring one.
 - `defineEntity` defines the same entity without decorators: https://uql-orm.dev/entities/imperative.md
 
 ## Queries
@@ -123,7 +123,7 @@ const users = await pool.findMany(User, {
 - Methods: `findMany`, `findOne`, `findOneById`, `findManyAndCount`, `findManyStream`, `count`, `exists`,
   `aggregate`, `insertOne`, `insertMany`, `updateOneById`, `updateMany`, `saveOne`, `saveMany`, `upsertOne`,
   `upsertMany`, `deleteOneById`, `deleteMany`. Each takes the entity class first.
-- `updateMany` and `deleteMany` naming no rows - no `$where`, no `$limit` - throw; `{ unfiltered: true }` means the whole table.
+- `updateMany` and `deleteMany` naming no rows - no `$where` holding a value (an `undefined` or an empty group holds none), no `$limit` - throw; `{ unfiltered: true }` means the whole table.
 - An update takes `{ stock: { $inc: -1 } }` to add, or `$mul` to multiply, in the statement, a NULL counting as 0,
   so a guard in `$where` (`stock: { $gte: 1 }`) makes a decrement race-safe. JSON fields take `$set`, `$unset`,
   `$push`, `$pull`.
@@ -133,7 +133,7 @@ const users = await pool.findMany(User, {
 - `queryErrorKind(err)` names any failure the same on every engine - `uniqueViolation`, `foreignKeyViolation`,
   `notNullViolation`, `checkViolation`, `optimisticLock`, `retryable`, `usage` - so catch by kind rather than by
   a driver's code or an `instanceof`.
-- `raw()` embeds SQL anywhere a value or field goes; `pool.all(sql, values)` runs a raw `SELECT`.
+- `raw()` embeds SQL anywhere a value or field goes; `pool.all(sql, values)` runs a raw `SELECT`. A field read off `refs(Entity)` carries its type: on its own as a value it fits only a field of that type.
 
 ## Connections and transactions