uql-orm 0.81.0 → 0.83.0

package/dist/schema/canonicalType.js

@@ -120,7 +120,8 @@ const MYSQL_SCALAR_MAP = {
     boolean: 'TINYINT(1)',
     date: 'DATE',
     time: 'TIME',
-    timestamp: 'DATETIME',
+    // The milliseconds a `Date` holds, which a bare `DATETIME` rounds away.
+    timestamp: 'DATETIME(3)',
     json: 'JSON',
     uuid: 'CHAR(36)',
     blob: 'BLOB',
@@ -193,25 +194,28 @@ const ENGINE_TYPES = {
     postgres: {
         scalars: { ...PG_SCALAR_MAP, vector: 'VECTOR', halfvec: 'HALFVEC', sparsevec: 'SPARSEVEC' },
         sizes: PG_SIZES,
+        timestampPrecision: 6,
     },
     // CockroachDB's VECTOR is native, no extension needed.
-    cockroachdb: { scalars: withVectorType(PG_SCALAR_MAP, 'VECTOR'), sizes: PG_SIZES },
+    cockroachdb: { scalars: withVectorType(PG_SCALAR_MAP, 'VECTOR'), sizes: PG_SIZES, timestampPrecision: 6 },
     // MySQL does have a `VECTOR` type (26.7), but no distance function outside HeatWave and no vector
     // index, so JSON keeps the column queryable with the JSON operators and needs no conversion.
     mysql: {
         scalars: withVectorType(MYSQL_SCALAR_MAP, 'JSON'),
         sizes: MYSQL_SIZES,
         decimal: { precision: 10, scale: 2 },
+        timestampPrecision: 0,
     },
     mariadb: {
         scalars: withVectorType(MYSQL_SCALAR_MAP, 'VECTOR'),
         sizes: MYSQL_SIZES,
         decimal: { precision: 10, scale: 2 },
+        timestampPrecision: 0,
     },
     // SQLite uses affinity, so no size variants. `F32_BLOB` is libSQL's vector type; elsewhere just a name of BLOB affinity.
     sqlite: { scalars: withVectorType(SQLITE_SCALAR_MAP, 'F32_BLOB') },
     // 2025 and up; below that the server refuses the type rather than storing it as text.
-    mssql: { scalars: withVectorType(MSSQL_SCALAR_MAP, 'VECTOR'), sizes: MSSQL_SIZES },
+    mssql: { scalars: withVectorType(MSSQL_SCALAR_MAP, 'VECTOR'), sizes: MSSQL_SIZES, timestampPrecision: 7 },
     mongodb: { scalars: withVectorType(MONGO_SCALAR_MAP, 'array') },
 };
 /**
@@ -241,8 +245,11 @@ export function sqlToCanonical(sqlType) {
     const normalized = sqlType.toLowerCase().trim();
     const unsigned = normalized.includes('unsigned');
     const withoutUnsigned = normalized.replace(/\s*unsigned\s*/i, ' ').trim();
-    // Extract base type and parameters: "VARCHAR(255)" -> ["varchar", "255"]
-    const match = withoutUnsigned.match(/^([a-z][a-z0-9_ ]*?)(?:\(([^)]+)\))?$/);
+    // Extract base type and parameters: "VARCHAR(255)" -> ["varchar", "255"], and Postgres's
+    // "timestamp(3) with time zone", whose parameter sits inside the name, as "timestamp with time zone(3)".
+    const match = withoutUnsigned
+        .replace(/^(\w+)\((\d+)\)\s+(.+)$/, '$1 $3($2)')
+        .match(/^([a-z][a-z0-9_ ]*?)(?:\(([^)]+)\))?$/);
     const base = match ? SQL_TO_CANONICAL[match[1]] : undefined;
     if (!match || !base) {
         return { category: 'string', raw: sqlType };
@@ -260,7 +267,7 @@ export function sqlToCanonical(sqlType) {
         size: measured && params[0] === 'max' ? 'small' : base.size,
         withTimezone: base.withTimezone,
         length: measured ? first : undefined,
-        precision: decimal ? first : undefined,
+        precision: decimal || base.category === 'timestamp' ? first : undefined,
         scale: decimal ? second : undefined,
         unsigned: unsigned || undefined,
     };
@@ -317,6 +324,9 @@ export function canonicalToSql(type, dialect) {
     if (type.category === 'timestamp' && type.withTimezone && features.supportsTimestamptz) {
         sqlType = 'TIMESTAMPTZ';
     }
+    if (type.category === 'timestamp' && type.precision !== undefined && engine.timestampPrecision !== undefined) {
+        sqlType = `${sqlType.replace(/\(\d+\)$/, '')}(${type.precision})`;
+    }
     return type.unsigned && features.supportsUnsigned ? `${sqlType} UNSIGNED` : sqlType;
 }
 /** See {@link DialectFeatures.stringSizing} for what each mode means. */
@@ -343,12 +353,22 @@ function formatDecimalSqlType(type, fallback, baseType) {
 export function canonicalToTypeScript(type) {
     return CANONICAL_TO_TS[type.category];
 }
+/** The fractional-second digits an engine's timestamp holds when its type states none; `undefined` where it counts none. */
+export function defaultTimestampPrecision(dialectName) {
+    return ENGINE_TYPES[dialectName].timestampPrecision;
+}
 /**
  * A type as `dialect` stores it, rendered and read back: several types share one storage type, and only
  * the engine settles an unstated bound. Migrations and drift both compare through it.
  */
 export function engineType(dialect) {
-    return (type) => sqlToCanonical(canonicalToSql(type, dialect));
+    const timestampPrecision = defaultTimestampPrecision(dialect.dialectName);
+    return (type) => {
+        const stored = sqlToCanonical(canonicalToSql(type, dialect));
+        return stored.category === 'timestamp' && stored.precision === undefined
+            ? { ...stored, precision: timestampPrecision }
+            : stored;
+    };
 }
 /**
  * Convert UQL FieldOptions to a canonical type.
@@ -363,14 +383,16 @@ export function fieldOptionsToCanonical(options) {
     switch (columnFamily(options.type)) {
         case 'numeric':
             // BIGINT for every `Number` without a scale, key or not: a 32-bit column is a migration waiting
-            // to happen, and the pools decode it back to a JS number at the wire (see `pgNumericTypes`).
+            // to happen, and the pools decode it back to a JS number at the wire (see `pgWireTypes`).
             return isIntegerColumn(options)
                 ? { category: 'integer', size: 'big' }
                 : { category: 'decimal', precision: options.precision, scale: options.scale };
         case 'boolean':
             return { category: 'boolean' };
+        // An instant: uql reads a zoneless timestamp as UTC, but the database's own clock and every other
+        // client read one in the session's zone.
         case 'date':
-            return { category: 'timestamp' };
+            return { category: 'timestamp', withTimezone: true, precision: options.precision };
         // `String`, and anything a reflected type left unrecognised.
         default:
             return { category: 'string', length: options.length };

package/dist/schema/schemaASTBuilder.js

@@ -4,6 +4,7 @@ import { fulltextWeights, textWeightSteps } from '../util/dialect.util.js';
 import { isAutoIncrement, isInlinedExpression, isSoleIdField } from '../util/field.util.js';
 import { definedEntries } from '../util/object.util.js';
 import { derivedForeignKeyName, derivedIndexName, qualifyName } from '../util/sql.util.js';
+import { UqlUsageError } from '../util/uqlError.js';
 import { resolveColumnCanonicalType } from './canonicalType.js';
 import { createTableNode, keyOfColumns, SchemaAST } from './schemaAST.js';
 import { DEFAULT_FOREIGN_KEY_ACTION } from './types.js';
@@ -37,7 +38,7 @@ export function buildSchemaAST(entities, options = {}) {
 }
 /** The `compileDdl` of a build given no dialect, which has nothing to render an entity's SQL with. */
 function refuseDdl() {
-    throw new TypeError('building the schema of an entity that declares SQL (a check, a stored computed column, an index expression or predicate) needs a dialect to render it: pass `compileDdl`, as `buildEntityAST` does');
+    throw new UqlUsageError('building the schema of an entity that declares SQL (a check, a stored computed column, an index expression or predicate) needs a dialect to render it: pass `compileDdl`, as `buildEntityAST` does');
 }
 /** The entries a vector index of `meta` covers: the members it names, and any expression. */
 function vectorIndexedEntries(meta) {

package/dist/schema/schemaASTDiffer.js

@@ -124,7 +124,9 @@ function diffColumn(tableName, source, target, opts) {
     // inconsistently (`BIGINT(20)`, SQLite's `notnull: 0` rowid), so neither is compared.
     const generatedType = source.isAutoIncrement && target.isAutoIncrement;
     const impliedNotNull = source.isPrimaryKey && target.isPrimaryKey;
-    const typeChanged = !generatedType && !areTypesEqual(opts.normalizeType(source.type), opts.normalizeType(target.type));
+    const expectedType = opts.normalizeType(source.type);
+    const actualType = opts.normalizeType(target.type);
+    const typeChanged = !generatedType && !areTypesEqual(expectedType, actualType);
     if (typeChanged) {
         differences.push(`type: ${formatType(source.type)} -> ${formatType(target.type)}`);
     }
@@ -158,7 +160,7 @@ function diffColumn(tableName, source, target, opts) {
         // Only the type this diff actually reports: a column altered for its default carries no data loss,
         // and a generated key's type - never compared above - reads as unsigned against an entity that
         // cannot say so.
-        isBreaking: (typeChanged || signednessChanged) && isBreakingTypeChange(target.type, source.type),
+        isBreaking: (typeChanged || signednessChanged) && isBreakingTypeChange(actualType, expectedType),
         description: differences.join(', '),
     };
 }

package/dist/sqlite/sqliteDialect.d.ts

@@ -1,4 +1,4 @@
-import { AbstractSqlDialect, type DerivedRelation, type HydrateKind, type RelationRows } from '../dialect/abstractSqlDialect.js';
+import { AbstractSqlDialect, type DerivedRelation, type RelationRows } from '../dialect/abstractSqlDialect.js';
 import { type JsonAccessMode, type JsonSlot } from '../dialect/jsonSql.js';
 import { type EntityMeta, type FieldOptions, type Query, type QueryContext, type QueryPager, type QueryTextSearchOptions, type QueryWhere, type SqlDialectFeatures, type VectorDistance, type VectorMetric } from '../type/index.js';
 /** What SQLite and the engines derived from it have. */
@@ -60,8 +60,6 @@ export declare class SqliteDialect extends AbstractSqlDialect {
         vector: (expr: string) => string;
     };
     private bytesAsText;
-    /** A date reads back as SQLite stored it, a number or text, which JSON carries unchanged. */
-    protected hydrateKind(field: FieldOptions | undefined): HydrateKind | undefined;
     /**
      * FTS5 matches the table itself, so this works only where the table *is* an FTS5 virtual table (UQL does
      * not create those; declare it outside your entities). The whole query is bound, column filter and all.

package/dist/sqlite/sqliteDialect.js

@@ -3,9 +3,10 @@ import { BYTES_PREFIX } from '../dialect/hydrateColumn.js';
 import { chainedCall, groupsPerCall, jsonSetCall, jsonPath, jsonArraySlotArgs, jsonSlotArgs, jsonRemoveCall, jsonSetTarget, } from '../dialect/jsonSql.js';
 import { QueryRaw, } from '../type/index.js';
 import { indexDistance, isVectorIndexType } from '../type/vector.js';
+import { utcTimestamp } from '../util/date.js';
 import { declaredIndexName } from '../util/ddlExpression.util.js';
 import { findVectorIndex, findVectorSort, textSearchFields, vectorCandidates } from '../util/dialect.util.js';
-import { columnFamily, isIntegerColumn } from '../util/field.util.js';
+import { isIntegerColumn } from '../util/field.util.js';
 /**
  * An FTS5 query over `columns` for what a person typed: each word a quoted string, which FTS5 reads as a
  * term to match and never as syntax, and every one required, as the other engines read plain words.
@@ -128,7 +129,7 @@ export class SqliteDialect extends AbstractSqlDialect {
     }
     normalizeValue(value) {
         if (value instanceof Date)
-            return value.getTime();
+            return utcTimestamp(value);
         return super.normalizeValue(value);
     }
     /**
@@ -169,10 +170,6 @@ export class SqliteDialect extends AbstractSqlDialect {
     bytesAsText(expr) {
         return `${this.escape(BYTES_PREFIX)} || hex(${expr})`;
     }
-    /** A date reads back as SQLite stored it, a number or text, which JSON carries unchanged. */
-    hydrateKind(field) {
-        return columnFamily(field?.type) === 'date' ? undefined : super.hydrateKind(field);
-    }
     /**
      * FTS5 matches the table itself, so this works only where the table *is* an FTS5 virtual table (UQL does
      * not create those; declare it outside your entities). The whole query is bound, column filter and all.

package/dist/type/dialect.d.ts

@@ -1,6 +1,7 @@
-import type { EntityMeta, UpdatePayload } from './entity.js';
+import type { EntityMeta, EntityPredicate, UpdatePayload } from './entity.js';
 import type { Query, QueryConflictPaths, QueryPage, QueryRenderOptions, QuerySearch, RelationQuery } from './query.js';
 import type { QueryAggMap, QueryAggregate, QueryAggregateOp, QueryGroupMap } from './queryAggregate.js';
+import type { QueryRawRenderOptions } from './queryRaw.js';
 import type { QueryWhere } from './queryWhere.js';
 import type { Type } from './utility.js';
 import type { QueryVectorQuery } from './vector.js';
@@ -231,6 +232,25 @@ export interface TriggerFeatures {
      */
     readonly before: boolean;
 }
+/** Where DDL's SQL sits: the row a trigger's predicate reads, as its prefix, and a set-based body's rows. */
+export type DdlRenderOptions = Pick<QueryComparisonOptions, 'escapedPrefix' | 'operand'> & Pick<QueryRawRenderOptions, 'rows'>;
+/**
+ * A write a trigger's body runs, as `insertInto`, `updateTable` and `deleteFrom` state it. Held untyped
+ * here, past those helpers' typing, since the dialect renders it by the entity's metadata alone.
+ */
+export type TriggerWrite = {
+    readonly entity: Type<object>;
+} & ({
+    readonly kind: 'insert';
+    readonly row: Readonly<Record<string, unknown>>;
+} | {
+    readonly kind: 'update';
+    readonly set: Readonly<Record<string, unknown>>;
+    readonly where: EntityPredicate<object>;
+} | {
+    readonly kind: 'delete';
+    readonly where: EntityPredicate<object>;
+});
 /**
  * What a SQL statement is rendered through, as a `raw` callback and a query context see it:
  * `AbstractSqlDialect` is the one implementation.
@@ -262,6 +282,8 @@ export interface SqlQueryDialect {
     update<E>(ctx: QueryContext, entity: Type<E>, q: QuerySearch<E>, payload: UpdatePayload<E>, opts?: QueryRenderOptions): void;
     /** An upsert of one record or many by their conflict paths. */
     upsert<E>(ctx: QueryContext, entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: E | E[]): void;
+    /** A write in a trigger's body; `rows` is where a set-based engine's body reads its rows from. */
+    triggerWrite(ctx: QueryContext, write: TriggerWrite, rows?: string): void;
     /** A delete of the records the query matches, a soft delete where the entity has one. */
     delete<E>(ctx: QueryContext, entity: Type<E>, q: QuerySearch<E>, opts?: QueryRenderOptions): void;
     /**

package/dist/type/entity.d.ts

@@ -1,7 +1,7 @@
 import type { EnumValues, ForeignKeyAction, IndexType } from '../schema/types.js';
 import type { SqlDialectName } from './dialect.js';
 import type { FilterOptions, RelationQuery } from './query.js';
-import type { ColumnRef, QueryRaw, RelationAggregate } from './queryRaw.js';
+import type { ColumnRef, QueryRaw, RawFor, RelationAggregate } from './queryRaw.js';
 import type { QueryWhere } from './queryWhere.js';
 import type { AtLeastOne, Except, ExactlyOne, IsEqual, IsMany, Json, Scalar, Type, Unpacked, Writable } from './utility.js';
 import type { VectorDistance, VectorIndexOptions, VectorIndexType } from './vector.js';
@@ -37,6 +37,10 @@ export type WritableKey<E> = {
 }[FieldKey<E>];
 /** A whole-record write as a caller supplies one: {@link EntityData} without the fields it cannot write. */
 export type EntityWrite<E> = EntityData<E, WritableKey<E>>;
+/** A row a trigger's body writes: each writable field its value, or SQL - a row's ref most often. */
+export type WriteRow<E, F extends keyof E = WritableKey<E>> = {
+    readonly [K in F]?: E[K] | RawFor<QueryRaw, E[K]>;
+};
 /**
  * The property an entity brands with {@link versionKey} as its optimistic lock, `never` where it
  * brands none. The brand is what carries `@Field({ version: true })` to the type level, since a
@@ -114,7 +118,7 @@ export type JsonArrayFields<T> = {
  */
 export type JsonUpdateOp<T = unknown> = {
     readonly $set?: Partial<T>;
-    readonly $unset?: unknown extends T ? string[] : (keyof T & string)[];
+    readonly $unset?: unknown extends T ? readonly string[] : readonly (keyof T & string)[];
     readonly $push?: JsonArrayFields<T>;
     readonly $pull?: JsonArrayFields<T>;
 };
@@ -133,7 +137,7 @@ export type FieldUpdateOp<T extends number | bigint = number | bigint> = Exactly
 /** The {@link FieldUpdateOp} a field takes: `never` on one it has no operator for, which is any but a number. */
 type FieldUpdateOpFor<V> = [NonNullable<V>] extends [number] ? FieldUpdateOp<number> : [NonNullable<V>] extends [bigint] ? FieldUpdateOp<bigint> : never;
 /** What an update takes beyond the value: `null` to clear an optional member, `raw` SQL, and update operators. */
-type UpdateExtra<V, Raw> = (undefined extends V ? null : never) | Raw | JsonUpdateOpFor<V> | FieldUpdateOpFor<V>;
+type UpdateExtra<V, Raw> = (undefined extends V ? null : never) | RawFor<Raw, V> | JsonUpdateOpFor<V> | FieldUpdateOpFor<V>;
 /**
  * What a whole-record write persists: the fields and relations with their declared optionality, a
  * related row's alike, and no methods. Two mapped types, since asking each key costs a conditional.
@@ -284,7 +288,7 @@ export type FieldOptions<V = TsTypeOf<FieldType>, E = unknown> = {
     readonly columnType?: ColumnType | QueryRaw;
     /** A string column's length. */
     readonly length?: number;
-    /** A decimal column's precision. */
+    /** A decimal column's digits, or a timestamp's fractional-second digits. */
     readonly precision?: number;
     /** A decimal column's scale. */
     readonly scale?: number;
@@ -411,6 +415,10 @@ export type RelationReference<O, E> = {
         readonly foreign: F;
     };
 }[FieldKey<E>];
+/** The fields of `E` whose value is a `T`, however optional: `FieldKeyOf<E, number | bigint>` are the ones a sum adds up. */
+export type FieldKeyOf<E, T> = {
+    readonly [K in FieldKey<E>]-?: [NonNullable<E[K]>] extends [T] ? K : never;
+}[FieldKey<E>];
 /** The fields of `O` that can hold any value `V` takes. */
 type FieldKeyHolding<O, V> = {
     readonly [K in keyof O]-?: [NonNullable<V>] extends [NonNullable<O[K]>] ? K : never;
@@ -446,16 +454,12 @@ export type KeyMap<E> = {
 };
 /** The fields of `E` as {@link ColumnRef}s, for SQL that names them: `refs(User)`, or a definition's callback. */
 export type RefMap<E, F extends keyof E = FieldKey<E>> = {
-    readonly [K in F]-?: ColumnRef<K & string>;
+    readonly [K in F]-?: ColumnRef<K & string, E[K]>;
 };
 /** SQL a definition writes: `raw`, or a callback reading the fields off its refs, bivariant so the registry can hold it. */
 export type EntitySql<E> = QueryRaw | {
     sql(refs: RefMap<E>): QueryRaw;
 }['sql'];
-/** The fields of `C` a `sum` or an `avg` can add up. */
-type NumericKey<C> = {
-    readonly [K in FieldKey<C>]-?: [NonNullable<C[K]>] extends [number | bigint] ? K : never;
-}[FieldKey<C>];
 /** One field of `C`, read off its refs: `(item) => item.amount`. */
 type PickRef<C, K extends keyof C> = (refs: RefMap<C>) => ColumnRef<K & string>;
 /**
@@ -466,11 +470,11 @@ type PickRef<C, K extends keyof C> = (refs: RefMap<C>) => ColumnRef<K & string>;
 export type RelationRef<C> = {
     count(q?: AggregateFilter<C>): RelationAggregate<number, true>;
     count(q: AggregatePage<C>): RelationAggregate<number, false>;
-    sum<K extends NumericKey<C>>(pick: PickRef<C, K>, q?: AggregateFilter<C>): RelationAggregate<NonNullable<C[K]>, true>;
-    sum<K extends NumericKey<C>>(pick: PickRef<C, K>, q: AggregateTopRows<C>): RelationAggregate<NonNullable<C[K]>, false>;
+    sum<K extends FieldKeyOf<C, number | bigint>>(pick: PickRef<C, K>, q?: AggregateFilter<C>): RelationAggregate<NonNullable<C[K]>, true>;
+    sum<K extends FieldKeyOf<C, number | bigint>>(pick: PickRef<C, K>, q: AggregateTopRows<C>): RelationAggregate<NonNullable<C[K]>, false>;
     min<K extends FieldKey<C>>(pick: PickRef<C, K>, q?: AggregateRows<C>): RelationAggregate<NonNullable<C[K]> | null, false>;
     max<K extends FieldKey<C>>(pick: PickRef<C, K>, q?: AggregateRows<C>): RelationAggregate<NonNullable<C[K]> | null, false>;
-    avg<K extends NumericKey<C>>(pick: PickRef<C, K>, q?: AggregateRows<C>): RelationAggregate<number | null, false>;
+    avg<K extends FieldKeyOf<C, number | bigint>>(pick: PickRef<C, K>, q?: AggregateRows<C>): RelationAggregate<number | null, false>;
 };
 /**
  * What an aggregate reads of the related rows. The predicate is an {@link EntityPredicate} rather than a

package/dist/type/logger.d.ts

@@ -12,9 +12,9 @@ export interface Logger {
      * @param values - The parameters passed to the query.
      * @param duration - The time it took to execute the query in milliseconds.
      */
-    logQuery?(query: string, values?: unknown[], duration?: number): void;
+    logQuery?(query: string, values?: readonly unknown[], duration?: number): void;
     /** Logs a query that took longer than the threshold, its values `undefined` unless `logValues` is on. */
-    logSlowQuery?(query: string, values?: unknown[], duration?: number): void;
+    logSlowQuery?(query: string, values?: readonly unknown[], duration?: number): void;
     /**
      * Logs a warning.
      */

package/dist/type/querier.d.ts

@@ -106,11 +106,11 @@ export interface SqlQuerier extends Querier {
     /**
      * Execute a raw SQL query and return results
      */
-    all<T>(query: string, values?: unknown[]): Promise<T[]>;
+    all<T>(query: string, values?: readonly unknown[]): Promise<T[]>;
     /**
      * Execute a raw SQL command (INSERT, UPDATE, DELETE, DDL)
      */
-    run(query: string, values?: unknown[]): Promise<QueryUpdateResult>;
+    run(query: string, values?: readonly unknown[]): Promise<QueryUpdateResult>;
 }
 /**
  * Type guard to check if a querier supports raw SQL execution
@@ -136,7 +136,7 @@ export declare function isMongoQuerier(querier: Querier): querier is MongoQuerie
 export type ListenerContext<E extends object = object> = {
     readonly entity: Type<E>;
     readonly querier: Querier;
-    readonly payloads: E[];
+    readonly payloads: readonly E[];
     readonly event: HookEvent;
 };
 /**

package/dist/type/query.d.ts

@@ -1,4 +1,4 @@
-import type { FieldKey, JsonFieldPaths, RelationKey, RelationTarget, ToManyRelationKey, WrittenId } from './entity.js';
+import type { FieldKey, FieldKeyOf, JsonFieldPaths, RelationKey, RelationTarget, ToManyRelationKey, WrittenId } from './entity.js';
 import type { QueryLock } from './queryLock.js';
 import type { QueryRaw } from './queryRaw.js';
 import type { QueryWhere } from './queryWhere.js';
@@ -145,17 +145,13 @@ export type QuerySortValue = QuerySortDirection | QueryVectorSearch;
 export type QuerySortByCount = {
     $count: QuerySortDirection;
 };
-/** The fields of `E` a vector search can rank by. */
-type VectorFieldKey<E> = {
-    [P in FieldKey<E>]: NonNullable<E[P]> extends readonly number[] ? P : never;
-}[FieldKey<E>];
 /**
  * Ordering parents by the row of a to-many nearest a vector, per vector field: its distance is the
  * smallest of theirs. Nothing to `$project`, since no one row of the parent's answers under it. Never
  * where the target has no vector, since an empty map would admit any value at all.
  */
-export type QuerySortByNearest<E> = [VectorFieldKey<E>] extends [never] ? never : {
-    [P in VectorFieldKey<E>]?: QueryVectorQuery;
+export type QuerySortByNearest<E> = [FieldKeyOf<E, readonly number[]>] extends [never] ? never : {
+    [P in FieldKeyOf<E, readonly number[]>]?: QueryVectorQuery;
 };
 /**
  * Ordering by relevance to the `$text` at the root of `$where`, in either direction as any key sorts. The
@@ -371,12 +367,6 @@ Pick<E, Exclude<ProjectedKeys<E, S, V, X, P>, PopulatedToMany<E, P>> & keyof E>
 } : E;
 /** The to-many relations a query populated, which come back as lists rather than as optional ones. */
 type PopulatedToMany<E, P> = Extract<P, ToManyRelationKey<E>>;
-/**
- * stringified query.
- */
-export type QueryStringified = {
-    [K in keyof Query<unknown>]?: string;
-};
 /** What upserting one row reports. `created` is only knowable for a single statement, so a batch has none. */
 export type QueryUpsertOneResult<E> = {
     readonly id?: WrittenId<E>;

package/dist/type/queryAggregate.d.ts

@@ -1,4 +1,4 @@
-import type { FieldKey, RelationKey, RelationTarget } from './entity.js';
+import type { FieldKey, FieldKeyOf, RelationKey, RelationTarget } from './entity.js';
 import type { QueryPager, QuerySelect, QuerySortDirection } from './query.js';
 import type { QueryRaw } from './queryRaw.js';
 import type { QueryWhere, QueryWhereFieldValue } from './queryWhere.js';
@@ -44,13 +44,6 @@ export declare function resolveAggregateOp(key: string): {
 export type QueryFieldRef<E, F extends keyof E = FieldKey<E>> = ExactlyOne<Required<QuerySelect<E, F, true>>>;
 /** The argument of an aggregate function: a field, or `'*'` (only meaningful for `COUNT(*)`). */
 export type QueryAggregateArg<E> = QueryFieldRef<E> | '*';
-/**
- * Fields `SUM`/`AVG` can total. Restricted to numeric columns because totalling a text or date one is
- * either an engine error or a coercion, and neither produces the value the signature promises.
- */
-type NumericFieldKey<E> = {
-    readonly [K in FieldKey<E>]: [NonNullable<E[K]>] extends [number | bigint] ? K : never;
-}[FieldKey<E>];
 /** Every aggregate op, plain and DISTINCT-qualified. */
 type AggregateOp = QueryAggregateOp | QueryAggregateDistinctOp;
 /**
@@ -67,9 +60,10 @@ type AveragingOp = OpsOf<'$avg'>;
 type TotallingOp = SummingOp | AveragingOp;
 /**
  * Every aggregate op mapped to the argument it accepts: `$count` a field or `'*'` (`COUNT(*)`),
- * the totalling ops a numeric field, `$min`/`$max`/`$countDistinct` any field.
+ * the totalling ops a numeric field, since totalling any other is an engine error or a coercion,
+ * and `$min`/`$max`/`$countDistinct` any field.
  */
-type QueryAggregateArgMap<E> = Record<'$count', QueryAggregateArg<E>> & Record<TotallingOp, QueryFieldRef<E, NumericFieldKey<E>>> & Record<Exclude<AggregateOp, '$count' | TotallingOp>, QueryFieldRef<E>>;
+type QueryAggregateArgMap<E> = Record<'$count', QueryAggregateArg<E>> & Record<TotallingOp, QueryFieldRef<E, FieldKeyOf<E, number | bigint>>> & Record<Exclude<AggregateOp, '$count' | TotallingOp>, QueryFieldRef<E>>;
 /**
  * An aggregate over one field, exactly one op per entry: `{ $sum: { amount: true } }` is `SUM("amount")`,
  * `{ $countDistinct: { id: true } }` is `COUNT(DISTINCT "id")`, and only `$count` takes `'*'`. Its own

package/dist/type/queryRaw.d.ts

@@ -15,6 +15,11 @@ export type QueryRawRenderOptions = {
      * computed field's own, or the one whose schema is built. Absent where a statement renders SQL.
      */
     entity?: Type<unknown>;
+    /**
+     * The `FROM` a set-based trigger's body reads its rows through, `FROM inserted` and the like, which a
+     * write in it names. Absent where the body reads `NEW` and `OLD` bare, and outside a trigger.
+     */
+    rows?: string;
 };
 /** {@link QueryRawRenderOptions} as the callers along the way fill them in, every one still optional. */
 export type QueryRawFnOptions = Partial<QueryRawRenderOptions>;
@@ -45,12 +50,21 @@ export declare class QueryRaw {
 }
 /**
  * A field of an entity as SQL, read off `refs(Entity)` or a definition's refs: interpolated into `raw`, it
- * renders as the field's column. Its `key` is how an index tells a column from an expression.
+ * renders as the field's column. Its `key` is how an index tells a column from an expression, and `V`,
+ * the field's type, is what a value slot checks it against: see {@link RawFor}.
  */
-export declare class ColumnRef<K extends string = string> extends QueryRaw {
+export declare class ColumnRef<K extends string = string, V = unknown> extends QueryRaw {
     readonly key: K;
+    readonly __value?: V;
     constructor(key: K, value: QueryRawFn);
 }
+/**
+ * SQL where a value of type `V` goes: bare SQL, whose type is its author's to know, or a ref to a column
+ * holding one, nullability aside. `Raw` is what the transport carries, so the wire's `never` stays one.
+ */
+export type RawFor<Raw, V> = Raw & {
+    readonly __value?: V | null;
+};
 /**
  * A relation aggregate as SQL, read off a `computed` field's refs: `(user) => user.resources.count()`.
  * It renders as the correlated subquery a `$count` reads, so a field holding one is read, filtered and
@@ -63,7 +77,7 @@ export declare class ColumnRef<K extends string = string> extends QueryRaw {
 export declare class RelationAggregate<V = unknown, Storable extends boolean = boolean> extends QueryRaw {
     /** What it reads, kept beside the SQL so a read decodes the value the way the target's field does. */
     readonly spec: RelationAggregateSpec;
-    private readonly __value;
+    readonly __value?: V;
     private readonly __storable;
     constructor(
     /** What it reads, kept beside the SQL so a read decodes the value the way the target's field does. */

package/dist/type/queryRaw.js

@@ -29,7 +29,8 @@ export class QueryRaw {
 }
 /**
  * A field of an entity as SQL, read off `refs(Entity)` or a definition's refs: interpolated into `raw`, it
- * renders as the field's column. Its `key` is how an index tells a column from an expression.
+ * renders as the field's column. Its `key` is how an index tells a column from an expression, and `V`,
+ * the field's type, is what a value slot checks it against: see {@link RawFor}.
  */
 export class ColumnRef extends QueryRaw {
     key;

package/dist/type/queryWhere.d.ts

@@ -1,6 +1,6 @@
 import type { FieldKey, JsonFieldPaths, JsonFieldPathValue, RelationKey, RelationTarget } from './entity.js';
 import type { QuerySelect } from './query.js';
-import type { QueryRaw } from './queryRaw.js';
+import type { QueryRaw, RawFor } from './queryRaw.js';
 import type { AtLeastOne, ExpandScalar, IsMany, QueryComparableScalar, Scalar } from './utility.js';
 import type { QueryVectorQuery } from './vector.js';
 /**
@@ -136,7 +136,7 @@ export type QueryWhereFieldOperatorMap<T, Raw = QueryRaw> = {
      * whether a value is between two values (inclusive). Shorthand for $gte + $lte.
      * @example { age: { $between: [18, 65] } }
      */
-    $between?: [ExpandScalar<T>, ExpandScalar<T>];
+    $between?: readonly [ExpandScalar<T>, ExpandScalar<T>];
     /**
      * whether a string begins with the given string (case sensitive).
      */
@@ -176,11 +176,11 @@ export type QueryWhereFieldOperatorMap<T, Raw = QueryRaw> = {
     /**
      * whether a value matches any of the given values.
      */
-    $in?: ExpandScalar<T>[];
+    $in?: readonly ExpandScalar<T>[];
     /**
      * whether a value does not match any of the given values.
      */
-    $nin?: ExpandScalar<T>[];
+    $nin?: readonly ExpandScalar<T>[];
     /**
      * whether a value is null.
      * @example { deletedAt: { $isNull: true } }
@@ -195,7 +195,7 @@ export type QueryWhereFieldOperatorMap<T, Raw = QueryRaw> = {
      * whether an array contains all the specified values.
      * @example { tags: { $all: ['typescript', 'orm'] } }
      */
-    $all?: unknown extends T ? unknown[] : NonNullable<T> extends readonly (infer U)[] ? ExpandScalar<U>[] : never;
+    $all?: unknown extends T ? readonly unknown[] : NonNullable<T> extends readonly (infer U)[] ? readonly ExpandScalar<U>[] : never;
     /** whether an array has the given length, or one in range: `{ roles: { $size: { $gte: 2 } } }`. */
     $size?: number | QuerySizeComparisonOps;
     /**
@@ -284,9 +284,9 @@ type IsUntypedColumn<T> = [Scalar] extends [NonNullable<T>] ? true : false;
  * A field's filter value: the value, `null` where it is optional, a list as an implicit `$in` (not on
  * an array field, where it would be ambiguous), or an operator map.
  */
-export type QueryWhereFieldValue<T, Raw = QueryRaw> = T | (undefined extends T ? null : never) | (IsMany<T> extends true ? never : T[]) | QueryWhereFieldOperators<T, Raw> | Raw;
+export type QueryWhereFieldValue<T, Raw = QueryRaw> = T | (undefined extends T ? null : never) | (IsMany<T> extends true ? never : readonly T[]) | QueryWhereFieldOperators<T, Raw> | RawFor<Raw, T>;
 /**
  * query filter array - the value every {@link QueryGroupOp} takes.
  */
-export type QueryWhereArray<E, Raw = QueryRaw> = (QueryWhere<E, Raw> | Raw)[];
+export type QueryWhereArray<E, Raw = QueryRaw> = readonly (QueryWhere<E, Raw> | Raw)[];
 export {};

package/dist/type/universalQuerier.d.ts

@@ -65,11 +65,11 @@ export interface UniversalQuerier extends SharedQuerier<'server', QueryOptions>
      * Ids are exact everywhere but MySQL, which infers them from its header and reports `undefined` rather
      * than a guess where it cannot: a batch naming some keys, or a key that is not `AUTO_INCREMENT`.
      */
-    insertMany<E extends object>(entity: Type<E>, payload: EntityWrite<E>[]): Promise<(WrittenId<E> | undefined)[]>;
+    insertMany<E extends object>(entity: Type<E>, payload: readonly EntityWrite<E>[]): Promise<(WrittenId<E> | undefined)[]>;
     /** Insert or update a record by its conflict paths; resolves to its id and whether it was created. */
     upsertOne<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityWrite<E>): Promise<QueryUpsertOneResult<E>>;
     /** Insert or update records by their conflict paths; resolves to their ids in payload order. */
-    upsertMany<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityWrite<E>[]): Promise<QueryUpsertManyResult<E>>;
+    upsertMany<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: readonly EntityWrite<E>[]): Promise<QueryUpsertManyResult<E>>;
     /**
      * insert or update a record.
      * @param entity the entity to persist on
@@ -83,7 +83,7 @@ export interface UniversalQuerier extends SharedQuerier<'server', QueryOptions>
      * @param payload the data to be persisted
      * @return the IDs
      */
-    saveMany<E extends object>(entity: Type<E>, payload: EntityWrite<E>[]): Promise<(WrittenId<E> | undefined)[]>;
+    saveMany<E extends object>(entity: Type<E>, payload: readonly EntityWrite<E>[]): Promise<(WrittenId<E> | undefined)[]>;
     /**
      * Restore soft-deleted records (sets the soft-delete field back to `null`). Throws if the
      * entity has no soft-delete field.

package/dist/type/vector.d.ts

@@ -1,5 +1,6 @@
 import type { VectorCast } from '../dialect/vectorCast.js';
 import type { IndexType } from '../schema/types.js';
+import { UqlUsageError } from '../util/uqlError.js';
 /**
  * A vector search's metric: `cosine` (the default), `l2`, `inner` product or `l1`. No hamming: every
  * engine's takes a bit vector, which no field type maps to.
@@ -37,7 +38,7 @@ export type VectorMetric = {
     readonly index?: string;
 };
 /** The error every dialect throws for a metric it lacks. */
-export declare function unsupportedVectorMetric(dialectName: string, distance: VectorDistance, indexName?: string): TypeError;
+export declare function unsupportedVectorMetric(dialectName: string, distance: VectorDistance, indexName?: string): UqlUsageError;
 /**
  * Vector-specific tuning options shared by `@Index` decorator, entity metadata, and migration schema.
  */

package/dist/type/vector.js

@@ -1,9 +1,10 @@
+import { UqlUsageError } from '../util/uqlError.js';
 /** The keys that describe the search rather than bound it, so `$near`'s bounds are what is left. */
 export const VECTOR_QUERY_KEYS = ['$vector', '$distance'];
 /** The error every dialect throws for a metric it lacks. */
 export function unsupportedVectorMetric(dialectName, distance, indexName) {
     const where = indexName === undefined ? '' : ` (index "${indexName}")`;
-    return new TypeError(`${dialectName} does not support vector distance metric: ${distance}${where}`);
+    return new UqlUsageError(`${dialectName} does not support vector distance metric: ${distance}${where}`);
 }
 /** The metric a search or an index measures by where nothing names one: every engine with vectors has it. */
 export const DEFAULT_VECTOR_DISTANCE = 'cosine';

package/dist/util/date.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `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 declare function utcTimestamp(date: Date, zone?: string): string;
+/**
+ * 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 declare function decodeDate(text: string): Date | string;