uql-orm 0.80.0 → 0.82.0

package/dist/schema/indexDifferences.d.ts

@@ -1,10 +1,12 @@
+import type { IndexSchema } from '../type/index.js';
 import type { IndexNode } from './types.js';
 /**
  * What an introspector reports about an index, and so all a diff may compare; apart from `IndexFeature`, what an engine emits.
- * `vector` is whether it is a vector index at all, for an engine with one vector index whatever type declared it.
+ * `vector` is whether it is a vector index at all, for an engine with one vector index whatever type declared it;
+ * `distance` is the metric a vector index was built for.
  * `textIndex` is a text index's weights and language, kept by an engine that lists its fields in no declared order.
  */
-export type IndexFacet = 'order' | 'nulls' | 'opsClass' | 'accessMethod' | 'include' | 'vector' | 'textIndex';
+export type IndexFacet = 'order' | 'nulls' | 'opsClass' | 'accessMethod' | 'include' | 'vector' | 'distance' | 'textIndex';
 type ComparableIndex = Pick<IndexNode, 'name' | 'entries' | 'unique'>;
 /**
  * Whether the table has this index already, by shape rather than name, uniqueness included. An index
@@ -17,16 +19,30 @@ export declare function indexSignature(index: ComparableIndex): string;
  */
 export declare function indexNameStem(name: string): string;
 /**
- * The indexes a table lacks and the ones it no longer needs, matched by `keyOf`. Only an index uql
- * named, or whose name the entity claims, is dropped: any other may have been made outside the ORM.
+ * Pairs by name, then what is left by shape: an index the database has under another name is still
+ * the one asked for. What stays unpaired is created or dropped.
  */
-export declare function indexChanges<I extends ComparableIndex>(table: string, declared: readonly I[], current: readonly IndexNode[], keyOf?: (index: ComparableIndex) => string): {
+export declare function pairIndexes<S extends ComparableIndex, T extends ComparableIndex>(source: readonly S[], target: readonly T[], normalizeName?: (name: string) => string): {
+    created: S[];
+    dropped: T[];
+    matched: (readonly [S, T])[];
+};
+/**
+ * The indexes a table lacks, the ones it no longer needs, and the ones to rebuild, differing in what
+ * `facets` let the engine report. Only an unpaired index uql named, or whose name the entity claims, is
+ * dropped: any other may have been made outside the ORM.
+ */
+export declare function indexChanges<I extends IndexSchema>(table: string, declared: readonly I[], current: readonly IndexNode[], facets: ReadonlySet<IndexFacet>): {
     toAdd: I[];
     toDrop: IndexNode[];
+    toAlter: {
+        from: IndexNode;
+        to: I;
+    }[];
 };
 /**
  * What two indexes differ by, comparing only what both sides state structurally: an expression, a JSON
  * path or a predicate is reprinted by the engine, so never compared.
  */
-export declare function describeIndexDifferences(source: IndexNode, target: IndexNode, facets: ReadonlySet<IndexFacet>): string[];
+export declare function describeIndexDifferences(source: IndexSchema, target: IndexSchema, facets: ReadonlySet<IndexFacet>): string[];
 export {};

package/dist/schema/indexDifferences.js

@@ -1,6 +1,7 @@
-import { isVectorIndexType } from '../type/vector.js';
+import { indexDistance, isVectorIndexType } from '../type/vector.js';
 import { fulltextConfig } from '../util/dialect.util.js';
 import { derivedIndexName } from '../util/sql.util.js';
+import { matchByKey } from './matchByKey.js';
 /** An entry the engine reprints in its own words, so never compared as written. */
 function isReprinted(entry) {
     return Boolean(entry.expression || entry.jsonPath || entry.jsonArray);
@@ -26,17 +27,27 @@ export function indexNameStem(name) {
     return bare.replace(/__/g, '_');
 }
 /**
- * The indexes a table lacks and the ones it no longer needs, matched by `keyOf`. Only an index uql
- * named, or whose name the entity claims, is dropped: any other may have been made outside the ORM.
+ * Pairs by name, then what is left by shape: an index the database has under another name is still
+ * the one asked for. What stays unpaired is created or dropped.
  */
-export function indexChanges(table, declared, current, keyOf = indexSignature) {
-    const present = new Set(current.map(keyOf));
-    const wanted = new Set(declared.map(keyOf));
+export function pairIndexes(source, target, normalizeName = (name) => name) {
+    const byName = matchByKey(source, target, (index) => normalizeName(indexNameStem(index.name)));
+    const byShape = matchByKey(byName.created, byName.dropped, indexSignature);
+    return { created: byShape.created, dropped: byShape.dropped, matched: [...byName.matched, ...byShape.matched] };
+}
+/**
+ * The indexes a table lacks, the ones it no longer needs, and the ones to rebuild, differing in what
+ * `facets` let the engine report. Only an unpaired index uql named, or whose name the entity claims, is
+ * dropped: any other may have been made outside the ORM.
+ */
+export function indexChanges(table, declared, current, facets) {
+    const { created, dropped, matched } = pairIndexes(declared, current);
     const claimed = new Set(declared.map((index) => index.name));
     const owned = (index) => claimed.has(index.name) || hasDerivedName(table, index);
     return {
-        toAdd: declared.filter((index) => !present.has(keyOf(index))),
-        toDrop: current.filter((index) => !wanted.has(keyOf(index)) && owned(index)),
+        toAdd: created,
+        toDrop: dropped.filter(owned),
+        toAlter: matched.flatMap(([to, from]) => (describeIndexDifferences(to, from, facets).length ? [{ from, to }] : [])),
     };
 }
 /**
@@ -85,6 +96,10 @@ export function describeIndexDifferences(source, target, facets) {
     if (facets.has('accessMethod') && (source.type ?? 'btree') !== (target.type ?? 'btree')) {
         differences.push(`type: ${target.type ?? 'btree'} -> ${source.type ?? 'btree'}`);
     }
+    const bothVector = isVectorIndexType(source.type) && isVectorIndexType(target.type);
+    if (facets.has('distance') && bothVector && indexDistance(source) !== indexDistance(target)) {
+        differences.push(`distance: ${indexDistance(target)} -> ${indexDistance(source)}`);
+    }
     if (facets.has('vector') && isVectorIndexType(source.type) !== isVectorIndexType(target.type)) {
         const [expected, actual] = [source, target].map((index) => (isVectorIndexType(index.type) ? 'yes' : 'no'));
         differences.push(`vector index: ${actual} -> ${expected}`);

package/dist/schema/matchByKey.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The only three ways two keyed collections can differ, which is the shape of every comparison in
+ * the schema diff: tables, columns, indexes and relationships all key and then split the same way.
+ * One counterpart each, so two items sharing a key (a duplicate index) are not collapsed into one.
+ */
+export declare function matchByKey<S, T>(source: Iterable<S>, target: Iterable<T>, key: (item: S | T) => string): {
+    created: S[];
+    dropped: T[];
+    matched: (readonly [S, T])[];
+};

package/dist/schema/matchByKey.js

@@ -0,0 +1,18 @@
+/**
+ * The only three ways two keyed collections can differ, which is the shape of every comparison in
+ * the schema diff: tables, columns, indexes and relationships all key and then split the same way.
+ * One counterpart each, so two items sharing a key (a duplicate index) are not collapsed into one.
+ */
+export function matchByKey(source, target, key) {
+    const unpaired = Map.groupBy(target, key);
+    const created = [];
+    const matched = [];
+    for (const item of source) {
+        const counterpart = unpaired.get(key(item))?.shift();
+        if (counterpart === undefined)
+            created.push(item);
+        else
+            matched.push([item, counterpart]);
+    }
+    return { created, dropped: [...unpaired.values()].flat(), matched };
+}

package/dist/schema/schemaAST.d.ts

@@ -1,6 +1,10 @@
-import type { IndexNode, RelationshipNode, TableNode } from './types.js';
+import type { PrimaryKeySchema } from '../type/migration.js';
+import type { IndexFacet } from './indexDifferences.js';
+import type { ColumnNode, IndexNode, RelationshipNode, TableNode } from './types.js';
 /** A table node with its collections empty, ready to be filled. */
-export declare function createTableNode(name: string, schema?: string, comment?: string): TableNode;
+export declare function createTableNode(name: string, schema?: string, indexFacets?: ReadonlySet<IndexFacet>): TableNode;
+/** The key the columns' own flags say, in their order, for a source that reports no key of its own. */
+export declare function keyOfColumns(columns: Iterable<Pick<ColumnNode, 'name' | 'isPrimaryKey'>>): PrimaryKeySchema | undefined;
 /** A database schema as a graph: tables, the foreign keys between them, and their indexes. */
 export declare class SchemaAST {
     readonly tables: Map<string, TableNode>;

package/dist/schema/schemaAST.js

@@ -1,19 +1,23 @@
 import { qualifyName } from '../util/sql.util.js';
 import { createOrder, dropOrder } from './dependencyGraph.js';
 /** A table node with its collections empty, ready to be filled. */
-export function createTableNode(name, schema, comment) {
+export function createTableNode(name, schema, indexFacets = new Set()) {
     return {
         name,
         schema,
-        comment,
+        indexFacets,
         columns: new Map(),
-        primaryKey: [],
         indexes: [],
         checks: [],
         incomingRelations: [],
         outgoingRelations: [],
     };
 }
+/** The key the columns' own flags say, in their order, for a source that reports no key of its own. */
+export function keyOfColumns(columns) {
+    const keyColumns = [...columns].filter((column) => column.isPrimaryKey).map((column) => column.name);
+    return keyColumns.length ? { columns: keyColumns } : undefined;
+}
 /** A database schema as a graph: tables, the foreign keys between them, and their indexes. */
 export class SchemaAST {
     tables = new Map();

package/dist/schema/schemaASTBuilder.d.ts

@@ -25,6 +25,8 @@ export interface BuildSchemaASTOptions {
     compileIndexPredicate?: (where: EntityWhereMeta<object>, entity: Type<object>, indexName: string) => string;
     /** Whether a weighted fulltext index declares one of its own for each heavier column, as MySQL scores through one. */
     textScoreIndexes?: boolean;
+    /** Whether a column a vector index covers is `NOT NULL` whatever the entity declares, as MariaDB demands. */
+    vectorIndexRequiresNotNull?: boolean;
 }
 /**
  * Build a SchemaAST from entity classes (decorated with `@Entity`, `@Field`, etc.).

package/dist/schema/schemaASTBuilder.js

@@ -4,8 +4,9 @@ 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, SchemaAST } from './schemaAST.js';
+import { createTableNode, keyOfColumns, SchemaAST } from './schemaAST.js';
 import { DEFAULT_FOREIGN_KEY_ACTION } from './types.js';
 /**
  * Build a SchemaAST from entity classes (decorated with `@Entity`, `@Field`, etc.).
@@ -26,6 +27,7 @@ export function buildSchemaAST(entities, options = {}) {
         compileDdl,
         compileIndexPredicate: options.compileIndexPredicate ?? compileDdl,
         textScoreIndexes: options.textScoreIndexes ?? false,
+        vectorIndexRequiresNotNull: options.vectorIndexRequiresNotNull ?? false,
     };
     for (const pass of [addTableFromEntity, addRelationshipsFromEntity, addIndexesFromEntity]) {
         for (const entity of entities) {
@@ -36,7 +38,13 @@ 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) {
+    return new Set((meta.indexes ?? [])
+        .filter((index) => index.type === 'vector')
+        .flatMap((index) => index.columns.map((entry) => entry.column)));
 }
 /**
  * Add a table from entity metadata.
@@ -44,8 +52,9 @@ function refuseDdl() {
 function addTableFromEntity(ctx, meta) {
     const tableName = ctx.resolveTableName(meta);
     const table = createTableNode(tableName, ctx.resolveSchema(meta));
-    const { columns, primaryKey } = table;
-    table.checks?.push(...(meta.checks ?? []).map(({ name, where }) => ({ name, expression: ctx.compileDdl(where, meta.entity) })));
+    const { columns } = table;
+    table.checks.push(...(meta.checks ?? []).map(({ name, where }) => ({ name, expression: ctx.compileDdl(where, meta.entity) })));
+    const notNull = ctx.vectorIndexRequiresNotNull ? vectorIndexedEntries(meta) : new Set();
     // Add columns from fields
     for (const [key, field] of definedEntries(meta.fields)) {
         // An inlined expression has no column; a stored one is a column like any other.
@@ -60,7 +69,7 @@ function addTableFromEntity(ctx, meta) {
             type,
             // A primary key is NOT NULL in every engine, whatever the entity's property says: `id?: number`
             // is optional because the database assigns it, not because the column accepts a null.
-            nullable: isPrimaryKey ? false : (field.nullable ?? true),
+            nullable: isPrimaryKey || notNull.has(key) ? false : (field.nullable ?? true),
             defaultValue: field.defaultValue,
             isPrimaryKey,
             isAutoIncrement: isAutoIncrement(field, isSoleKey),
@@ -74,10 +83,8 @@ function addTableFromEntity(ctx, meta) {
             references: undefined,
         };
         columns.set(columnName, column);
-        if (field.isId) {
-            primaryKey.push(column);
-        }
     }
+    table.primaryKey = keyOfColumns(columns.values());
     ctx.ast.addTable(table);
 }
 /** The node an entity maps to, found under the key {@link SchemaAST} stores it by. */
@@ -157,11 +164,10 @@ function addForeignKeyIndexes(ctx, meta, table) {
         });
     }
 }
-/** Whether the key, a unique column or an index already leads with `columns`, which is all a lookup needs. */
+/** Whether the key or an index already leads with `columns`, which is all a lookup needs. */
 function isIndexedBy(table, columns) {
     const leads = (indexed) => columns.every((column, at) => indexed[at] === column);
-    return (leads(table.primaryKey.map((column) => column.name)) ||
-        (columns.length === 1 && table.columns.get(columns[0])?.isUnique === true) ||
+    return (leads(table.primaryKey?.columns ?? []) ||
         table.indexes.some((index) => leads(index.entries.map((entry) => entry.expression || entry.jsonPath || entry.jsonArray ? undefined : entry.column))));
 }
 /** An `include` column is named like any other, so a naming strategy has to reach it too. */

package/dist/schema/schemaASTDiffer.d.ts

@@ -1,4 +1,3 @@
-import { type IndexFacet } from './indexDifferences.js';
 import type { SchemaAST } from './schemaAST.js';
 import type { CanonicalType } from './types.js';
 import type { ColumnDiff, ForeignKeyAction, IndexDiff, RelationshipDiff, RelationshipNode, SchemaDiffResult, TableDiff, TableNode } from './types.js';
@@ -8,8 +7,6 @@ import type { ColumnDiff, ForeignKeyAction, IndexDiff, RelationshipDiff, Relatio
 export interface DiffOptions {
     /** Compare indexes */
     compareIndexes?: boolean;
-    /** What the target side can report about an index, normally an introspector's `indexFacets`. Anything left out is not compared. */
-    indexFacets?: ReadonlySet<IndexFacet>;
     /** Compare foreign keys/relationships */
     compareRelationships?: boolean;
     /** Ignore case differences in names */
@@ -38,3 +35,5 @@ export declare function referentialActions(rel: RelationshipNode): {
     readonly onDelete: ForeignKeyAction;
     readonly onUpdate: ForeignKeyAction;
 };
+/** Two defaults compared as written, where no dialect reprints them: `now()` and `CURRENT_TIMESTAMP` are one. */
+export declare function defaultsEqualAsWritten(expected: unknown, actual: unknown): boolean;

package/dist/schema/schemaASTDiffer.js

@@ -1,37 +1,21 @@
 import { areTypesEqual, isBreakingTypeChange } from './canonicalType.js';
-import { describeIndexDifferences, indexNameStem } from './indexDifferences.js';
+import { describeIndexDifferences, pairIndexes } from './indexDifferences.js';
+import { matchByKey } from './matchByKey.js';
 import { DEFAULT_FOREIGN_KEY_ACTION } from './types.js';
 /**
  * Default diff options.
  */
 const DEFAULT_OPTIONS = {
     compareIndexes: true,
-    indexFacets: new Set(),
     compareRelationships: true,
     normalizeType: (type) => type,
-    defaultsEqual: (expected, actual) => normalizeDefault(expected) === normalizeDefault(actual),
+    defaultsEqual: defaultsEqualAsWritten,
     ignoreCase: false,
     excludeTables: [],
 };
 function nameNormalizer(opts) {
     return opts.ignoreCase ? (name) => name.toLowerCase() : (name) => name;
 }
-/**
- * The only three ways two keyed collections can differ, which is the shape of every comparison here:
- * tables, columns, indexes and relationships all key by name and then split the same way.
- */
-function matchByKey(source, target, key) {
-    const sourceByKey = new Map([...source].map((item) => [key(item), item]));
-    const targetByKey = new Map([...target].map((item) => [key(item), item]));
-    return {
-        created: [...sourceByKey].filter(([at]) => !targetByKey.has(at)).map(([, item]) => item),
-        dropped: [...targetByKey].filter(([at]) => !sourceByKey.has(at)).map(([, item]) => item),
-        matched: [...sourceByKey].flatMap(([at, item]) => {
-            const counterpart = targetByKey.get(at);
-            return counterpart ? [[item, counterpart]] : [];
-        }),
-    };
-}
 /** How a relationship diff names the pair it is about, whichever way it differs. */
 function relationEnds(relation) {
     return { name: relation.name, fromTable: relation.from.table.name, toTable: relation.to.table.name };
@@ -86,12 +70,12 @@ export function diffTable(source, target, options = {}) {
 }
 /** The two keys where they hold different columns, compared in order and never by the name the engine gave them. */
 function diffPrimaryKey(source, target) {
-    const expected = source.primaryKey.map((column) => column.name);
-    const actual = target.primaryKey.map((column) => column.name);
+    const expected = source.primaryKey?.columns ?? [];
+    const actual = target.primaryKey?.columns ?? [];
     if (expected.length === actual.length && expected.every((column, i) => column === actual[i])) {
         return undefined;
     }
-    return { table: source.name, expected, actual, actualName: target.primaryKeyName };
+    return { table: source.name, expected: source.primaryKey, actual: target.primaryKey };
 }
 /**
  * Compare columns between two tables.
@@ -120,17 +104,14 @@ function diffTableColumns(source, target, opts) {
             .filter((diff) => diff !== undefined),
     ];
 }
-/**
- * Compare indexes between two tables.
- */
+/** Compare indexes between two tables, paired by {@link pairIndexes}, in what the target's reader reports. */
 function diffTableIndexes(source, target, opts) {
-    const normalizeName = nameNormalizer(opts);
-    const { created, dropped, matched } = matchByKey(source.indexes, target.indexes, (index) => normalizeName(indexNameStem(index.name)));
+    const { created, dropped, matched } = pairIndexes(source.indexes, target.indexes, nameNormalizer(opts));
     return [
         ...created.map((index) => ({ name: index.name, table: source.name, type: 'create', expected: index })),
         ...dropped.map((index) => ({ name: index.name, table: target.name, type: 'drop', actual: index })),
         ...matched
-            .map(([sourceIndex, targetIndex]) => diffIndex(source.name, sourceIndex, targetIndex, opts.indexFacets))
+            .map(([sourceIndex, targetIndex]) => diffIndex(source.name, sourceIndex, targetIndex, target.indexFacets))
             .filter((diff) => diff !== undefined),
     ];
 }
@@ -158,12 +139,9 @@ function diffColumn(tableName, source, target, opts) {
     if (!impliedNotNull && source.nullable !== target.nullable) {
         differences.push(`nullable: ${target.nullable} -> ${source.nullable}`);
     }
-    // Compare unique constraint
-    if (source.isUnique !== target.isUnique) {
-        differences.push(`unique: ${target.isUnique} -> ${source.isUnique}`);
-    }
     // Not compared, since no statement this generator emits could settle a difference: `isAutoIncrement`,
-    // `enum` (a check the database reprints), `generatedAs`, and `comment`.
+    // `enum` (a check the database reprints), `generatedAs`, and `comment`. Nor `isUnique`: a unique
+    // column is a unique index, compared with the indexes.
     // Compare default values (if both defined)
     if (!opts.defaultsEqual(source.defaultValue, target.defaultValue)) {
         differences.push(`default: ${target.defaultValue ?? 'NULL'} -> ${source.defaultValue ?? 'NULL'}`);
@@ -262,9 +240,10 @@ function formatType(type) {
         result += ' unsigned';
     return result;
 }
-/**
- * Normalize default values for comparison.
- */
+/** Two defaults compared as written, where no dialect reprints them: `now()` and `CURRENT_TIMESTAMP` are one. */
+export function defaultsEqualAsWritten(expected, actual) {
+    return normalizeDefault(expected) === normalizeDefault(actual);
+}
 function normalizeDefault(value) {
     if (value === undefined || value === null)
         return '';

package/dist/schema/types.d.ts

@@ -1,4 +1,5 @@
-import type { IndexSchema } from '../type/migration.js';
+import type { IndexSchema, PrimaryKeySchema } from '../type/migration.js';
+import type { IndexFacet } from './indexDifferences.js';
 /**
  * Type categories universal across SQL dialects.
  * These represent logical/semantic types, not specific SQL types.
@@ -109,18 +110,17 @@ export interface TableNode {
     readonly schema?: string;
     /** Map of column name to column node */
     readonly columns: Map<string, ColumnNode>;
-    /** Primary key columns, in key order (supports composite keys) */
-    readonly primaryKey: ColumnNode[];
-    /**
-     * What the constraint is called, where a name is known: read back from the database on an
-     * introspected table, absent on one built from entities, where nothing has named it yet. A `DROP`
-     * is the only thing that needs it - see {@link TableSchema.primaryKeyName}.
-     */
-    primaryKeyName?: string;
+    /** The table's key, named where the database reported a name; none on a table without one. */
+    primaryKey?: PrimaryKeySchema;
     /** Indexes on this table */
     readonly indexes: IndexNode[];
-    /** `CHECK` constraints on this table. Optional: a node can be built without ever naming one. */
-    readonly checks?: CheckSchema[];
+    /**
+     * What the introspector that read this table reports about an index, and so all an index diff against
+     * it may compare. None on a table built from entities.
+     */
+    readonly indexFacets: ReadonlySet<IndexFacet>;
+    /** `CHECK` constraints on this table. */
+    readonly checks: CheckSchema[];
     /** Optional table comment */
     readonly comment?: string;
     /** Relationships pointing TO this table (other tables referencing this one) */
@@ -214,10 +214,9 @@ export interface TableDiff {
  */
 export interface PrimaryKeyDiff {
     readonly table: string;
-    readonly expected: string[];
-    readonly actual: string[];
-    /** What the *actual* side calls its constraint, which is the only name a `DROP` can use. */
-    readonly actualName?: string;
+    readonly expected?: PrimaryKeySchema;
+    /** Named as the database reported it, which is the only name a `DROP` can use. */
+    readonly actual?: PrimaryKeySchema;
 }
 /**
  * Difference between two index definitions.

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.
@@ -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.
      */