uql-orm 0.79.0 → 0.81.0

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/sqlite/sqliteDialect.d.ts

@@ -36,7 +36,7 @@ export declare class SqliteDialect extends AbstractSqlDialect {
      */
     protected appendDefaultInsertValue(ctx: QueryContext, field: FieldOptions | undefined): void;
     protected readonly caseInsensitiveMatch = "native";
-    protected get neOp(): string;
+    neExpr(field: string, ph: string): string;
     normalizeValue(value: unknown): unknown;
     /**
      * `OFFSET` is only legal after a `LIMIT` here too, so a bare `$skip` needs one - `-1` being

package/dist/sqlite/sqliteDialect.js

@@ -17,7 +17,6 @@ function ftsQuery(columns, value) {
 }
 /** What SQLite and the engines derived from it have. */
 export const SQLITE_FEATURES = {
-    ifNotExists: true,
     indexIfNotExists: true,
     schemas: false, // SQLite's namespaces are attached database files, not declared objects
     dropTableCascade: false,
@@ -41,6 +40,16 @@ export const SQLITE_FEATURES = {
     narrowVectorTypes: false,
     vectorTuningNeedsTransaction: false,
     serialDeclaresPrimaryKey: true,
+    triggers: {
+        preamble: '',
+        assignsRow: false,
+        body: 'inline',
+        guards: 'clause',
+        layout: 'timingFirst',
+        rows: 'row',
+        scope: 'schema',
+        before: true,
+    },
 };
 export class SqliteDialect extends AbstractSqlDialect {
     features = SQLITE_FEATURES;
@@ -114,8 +123,8 @@ export class SqliteDialect extends AbstractSqlDialect {
     // SQLite's `LIKE` already ignores case on both sides, for ASCII - and only ASCII, with or without
     // `NOCASE`, so folding the pattern here would break the accented text the engine leaves alone.
     caseInsensitiveMatch = 'native';
-    get neOp() {
-        return 'IS NOT';
+    neExpr(field, ph) {
+        return `${field} IS NOT ${ph}`;
     }
     normalizeValue(value) {
         if (value instanceof Date)

package/dist/type/dialect.d.ts

@@ -1,5 +1,5 @@
 import type { EntityMeta, UpdatePayload } from './entity.js';
-import type { Query, QueryConflictPaths, QueryOptions, QueryPage, QuerySearch, RelationQuery } from './query.js';
+import type { Query, QueryConflictPaths, QueryPage, QueryRenderOptions, QuerySearch, RelationQuery } from './query.js';
 import type { QueryAggMap, QueryAggregate, QueryAggregateOp, QueryGroupMap } from './queryAggregate.js';
 import type { QueryWhere } from './queryWhere.js';
 import type { Type } from './utility.js';
@@ -7,7 +7,7 @@ import type { QueryVectorQuery } from './vector.js';
 /**
  * comparison options.
  */
-export type QueryComparisonOptions = QueryOptions & {
+export type QueryComparisonOptions = QueryRenderOptions & {
     /**
      * Whether this fragment is rendered as an operand of an enclosing `AND`/`OR`/`NOT`. An operand
      * parenthesizes itself when it emits more than one term, so no fragment ever depends on the
@@ -78,7 +78,6 @@ export type InsertIdSource = 'returning' | 'firstId';
  * Features of the database engine (SQL syntax layer).
  */
 export interface DialectFeatures {
-    readonly ifNotExists: boolean;
     readonly indexIfNotExists: boolean;
     /**
      * Whether the engine has namespaces a table can sit behind. `false` leaves every table
@@ -176,6 +175,61 @@ export interface SqlDialectFeatures extends DialectFeatures {
     readonly vectorTuningNeedsTransaction: boolean;
     /** Whether the serial column type states `PRIMARY KEY` itself, as SQLite's `AUTOINCREMENT` must. */
     readonly serialDeclaresPrimaryKey: boolean;
+    /** How the engine spells a trigger. One value rather than a flag each, as {@link rowLocks} is. */
+    readonly triggers: TriggerFeatures;
+}
+/**
+ * What a trigger body calls the rows it reads. Row-based engines hand it a record on each side; SQL
+ * Server hands it the two tables of the set it touched.
+ */
+export type TriggerRowName = 'NEW' | 'OLD' | 'inserted' | 'deleted';
+/** How a dialect spells a trigger, once {@link SqlDialectFeatures.triggers} names its shape. */
+export interface TriggerFeatures {
+    /**
+     * Where the body lives: a function of its own that the trigger names (the Postgres family), or inside
+     * the `CREATE TRIGGER` itself (everywhere else).
+     */
+    readonly body: 'function' | 'inline';
+    /**
+     * How it states which rows it fires for: `UPDATE OF` beside a `WHEN` (`'clause'`), or, where there is
+     * no usable `WHEN` - the MySQL family, CockroachDB, SQL Server - the same condition wrapping the body,
+     * as `IF c THEN ... END IF;` (`'thenEndIf'`) or T-SQL's `IF c BEGIN ... END` (`'beginEnd'`).
+     */
+    readonly guards: 'clause' | 'thenEndIf' | 'beginEnd';
+    /**
+     * Whether it fires once per row, with a row on each side, or once per statement over the set it
+     * touched. SQL Server is the only one here that is set-based, reading `inserted` and `deleted`.
+     */
+    readonly rows: 'row' | 'set';
+    /**
+     * Where a trigger's name is unique, and so what a `DROP` has to name: per table on the Postgres
+     * family, which spells `DROP TRIGGER x ON t`, and per schema everywhere else, which spells
+     * `DROP TRIGGER x`. Two tables may carry the same trigger name only under `'table'`.
+     */
+    readonly scope: 'table' | 'schema';
+    /**
+     * Where the table sits in the statement: after the timing, `BEFORE UPDATE ON t`, or ahead of it and
+     * behind an `AS`, `ON t AFTER UPDATE AS` - which is T-SQL's shape and nobody else's.
+     */
+    readonly layout: 'timingFirst' | 'tableFirst';
+    /**
+     * What every body opens with, or `''`. T-SQL wants `SET NOCOUNT ON`: a trigger running its own DML
+     * otherwise sends a rowcount of its own back, and the client reads that as what the original statement
+     * affected. Nothing else here needs a preamble.
+     */
+    readonly preamble: string;
+    /**
+     * Whether a body may assign to the row it was handed, `NEW."col" := ...`. SQLite forbids writing `NEW`
+     * at all, and SQL Server is handed a set rather than a row, so on both a trigger that fills a column
+     * has to restate the row as an `UPDATE` after the write instead.
+     */
+    readonly assignsRow: boolean;
+    /**
+     * Whether it can fire before the write, which is what a stamp needs. SQL Server has only `AFTER` and
+     * `INSTEAD OF`, and `INSTEAD OF` would make the trigger responsible for performing the write itself,
+     * so a `before*` event is refused there rather than silently made to mean something else.
+     */
+    readonly before: boolean;
 }
 /**
  * What a SQL statement is rendered through, as a `raw` callback and a query context see it:
@@ -186,6 +240,12 @@ export interface SqlQueryDialect {
      * The SQL dialect name.
      */
     readonly dialectName: SqlDialectName;
+    /**
+     * The engine whose SQL this one also accepts, which is itself unless it is a fork: CockroachDB runs
+     * Postgres's PL/pgSQL and MariaDB runs MySQL's. What lets a body, or any other hand-written SQL, be
+     * declared once for a family rather than copied per member.
+     */
+    readonly dialectFamily: SqlDialectName;
     /**
      * the escape character for identifiers.
      */
@@ -193,17 +253,17 @@ export interface SqlQueryDialect {
     /** What the engine can do. */
     readonly features: SqlDialectFeatures;
     /** A read; with `totalAlias`, every row also carries the unpaged match count under that alias. */
-    find<E>(ctx: QueryContext, entity: Type<E>, q: Query<E>, opts?: QueryOptions, totalAlias?: string): void;
+    find<E>(ctx: QueryContext, entity: Type<E>, q: Query<E>, opts?: QueryRenderOptions, totalAlias?: string): void;
     /** A count of the records matching the filter, or of those a page of it takes. */
-    count<E>(ctx: QueryContext, entity: Type<E>, q: QueryPage<E>, opts?: QueryOptions): void;
+    count<E>(ctx: QueryContext, entity: Type<E>, q: QueryPage<E>, opts?: QueryRenderOptions): void;
     /** An insert of one record or many. */
-    insert<E>(ctx: QueryContext, entity: Type<E>, payload: E | E[], opts?: QueryOptions): void;
+    insert<E>(ctx: QueryContext, entity: Type<E>, payload: E | E[], opts?: QueryRenderOptions): void;
     /** An update of the records the query matches. */
-    update<E>(ctx: QueryContext, entity: Type<E>, q: QuerySearch<E>, payload: UpdatePayload<E>, opts?: QueryOptions): void;
+    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 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?: QueryOptions): void;
+    delete<E>(ctx: QueryContext, entity: Type<E>, q: QuerySearch<E>, opts?: QueryRenderOptions): void;
     /**
      * escape an identifier.
      * @param val the value to be escaped
@@ -237,7 +297,7 @@ export interface SqlQueryDialect {
     /**
      * Build an aggregate query.
      */
-    aggregate<E, G extends QueryGroupMap<E>, A extends QueryAggMap<E>>(ctx: QueryContext, entity: Type<E>, q: QueryAggregate<E, G, A>, opts?: QueryOptions): void;
+    aggregate<E, G extends QueryGroupMap<E>, A extends QueryAggMap<E>>(ctx: QueryContext, entity: Type<E>, q: QueryAggregate<E, G, A>, opts?: QueryRenderOptions): void;
     /**
      * Get the placeholder for a parameter at the given index (1-based).
      * Default: '?' for MySQL/MariaDB/SQLite, '$n' for PostgreSQL.

package/dist/type/entity.d.ts

@@ -1,8 +1,9 @@
 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 { QueryWhere } from './queryWhere.js';
-import type { Except, ExactlyOne, IsEqual, IsMany, Json, Scalar, Type, Unpacked, Writable } from './utility.js';
+import type { AtLeastOne, Except, ExactlyOne, IsEqual, IsMany, Json, Scalar, Type, Unpacked, Writable } from './utility.js';
 import type { VectorDistance, VectorIndexOptions, VectorIndexType } from './vector.js';
 /** Brands the property an entity is identified by, where it is not `id`, `_id` or `uuid`. */
 export declare const idKey: unique symbol;
@@ -254,8 +255,12 @@ export type FieldOptions<V = TsTypeOf<FieldType>, E = unknown> = {
      * subquery a `$count` reads. Both resolve to SQL at registration, so everything downstream sees one.
      */
     readonly computed?: ComputedSql<E>;
-    /** Whether {@link FieldOptions.computed} is a generated column rather than spliced into each read; no query changes either way. */
-    readonly stored?: boolean;
+    /**
+     * Where {@link FieldOptions.computed} lives instead of being spliced into each read. `true` makes it a
+     * generated column, which takes only an immutable expression; a list of events makes it a stamp a trigger
+     * writes on each, whoever writes the row - how `CURRENT_TIMESTAMP` is kept, where `onUpdate` sees only uql's writes.
+     */
+    readonly stored?: boolean | readonly StampEvent[];
     readonly updatable?: boolean;
     readonly eager?: boolean;
     readonly onInsert?: OnFieldCallback<V>;
@@ -691,11 +696,97 @@ export type EntityMeta<E> = {
     checks?: EntityCheckMeta<E>[];
     /** Lifecycle hooks registered via @BeforeInsert, @AfterUpdate, etc. */
     hooks?: Partial<Record<HookEvent, HookRegistration[]>>;
+    /** Triggers the database runs, compiled when the schema is built. */
+    triggers?: EntityTriggerMeta<E>[];
     /** Bumped by every `define*` call, so what is derived from the metadata can tell it changed. */
     revision: number;
     /** The revision `getMeta` last finalized, which is what makes finalizing idempotent and re-entrant. */
     processedAt?: number;
 };
+/** When the database writes a stamp: as the row is inserted, as it is updated, or both. */
+export type StampEvent = 'insert' | 'update';
+/**
+ * The events a trigger fires on: the lifecycle names, minus the upsert pair, which names no event of its
+ * own because `ON CONFLICT` fires the insert or the update triggers, and minus `afterLoad`, which is a
+ * read. Derived from {@link HookEvent} so the two vocabularies cannot drift.
+ */
+export type TriggerEvent = Exclude<HookEvent, 'beforeUpsert' | 'afterUpsert' | 'afterLoad'>;
+/** Both events for one operation, since a trigger's timing never changes which rows it has. */
+type TriggerEventOn<Op extends string> = Extract<TriggerEvent, `before${Op}` | `after${Op}`>;
+/** The events with a row on both sides, the only ones that can say which columns moved. */
+type TriggerUpdateEvent = TriggerEventOn<'Update'>;
+/**
+ * The rows an event has, as `where` keys them: the incoming one on an insert, the outgoing one on a
+ * delete, both on an update.
+ */
+type TriggerRow<Ev extends TriggerEvent> = Ev extends TriggerEventOn<'Insert'> ? '$new' : Ev extends TriggerEventOn<'Delete'> ? '$old' : '$new' | '$old';
+/** One row's refs, rendering `NEW."col"` or `OLD."col"`, or `never` where the event has no such row. */
+type TriggerRowRefs<E, Ev extends TriggerEvent, R extends '$new' | '$old'> = R extends TriggerRow<Ev> ? RefMap<E> : never;
+/**
+ * What a trigger runs, over its rows: the incoming row first and the outgoing one second, on every event.
+ * The one an event lacks is `never`, so reading it does not compile, and a body reading only the outgoing
+ * row - `(_newRow, oldRow)` - serves an update and a delete alike.
+ */
+type TriggerBody<E, Ev extends TriggerEvent> = (newRow: TriggerRowRefs<E, Ev, '$new'>, oldRow: TriggerRowRefs<E, Ev, '$old'>) => QueryRaw;
+/**
+ * A condition as data: a predicate on each row it names, of the rows the event has, all of which hold.
+ * The row is `$`-marked, as the operators inside it are, so it never reads as a field of the entity.
+ */
+type TriggerPredicate<E, Ev extends TriggerEvent> = {
+    readonly [R in TriggerRow<Ev>]?: EntityPredicate<E>;
+};
+/**
+ * The body, the engine's own SQL: one for every engine it reads alike, or a map naming one per engine
+ * where they differ, as SQL Server's set-based `inserted`/`deleted` does. A missing entry for the engine
+ * in use is refused at `sync`, since an entity is declared without knowing which pool will render it.
+ */
+type TriggerRun<E, Ev extends TriggerEvent> = TriggerBody<E, Ev> | Readonly<AtLeastOne<Record<SqlDialectName, TriggerBody<E, Ev>>>>;
+/**
+ * A trigger, `{ on: 'beforeUpdate', of: (post) => [post.body], run: (newRow) => raw`...` }`.
+ *
+ * A list rather than a map keyed by the event, as `checks` and `indexes` are lists: several triggers may
+ * share an event, they fire in the order written, and each is named, diffed and dropped by that name.
+ */
+export type TriggerOptions<E = unknown> = {
+    [Ev in TriggerEvent]: {
+        readonly on: Ev;
+        /**
+         * What to call this trigger within the entity, for a clearer identifier than its event and position.
+         * A label, not the identifier: uql prefixes and qualifies what it installs, so it can tell its own
+         * objects from hand-written ones and two entities may share a label.
+         */
+        readonly name?: string;
+        /**
+         * The columns whose change the trigger waits for, reading as the `UPDATE OF` it renders. Beside it
+         * goes a `WHEN` comparing each with `IS DISTINCT FROM`, which is the point of the pair: `UPDATE OF`
+         * fires on a column that was merely assigned, and the comparison narrows that to one that moved.
+         */
+        readonly of?: Ev extends TriggerUpdateEvent ? (refs: RefMap<E>) => readonly ColumnRef<string>[] : never;
+        /**
+         * A further condition, as the `WHEN` the engine evaluates before entering the body, over the rows the
+         * body reads: a predicate on each, `{ $old: { status: 'draft' }, $new: { status: 'published' } }`,
+         * rendered on every engine from the one declaration, or SQL off them for what no predicate states.
+         */
+        readonly where?: TriggerPredicate<E, Ev> | TriggerBody<E, Ev>;
+        readonly run: TriggerRun<E, Ev>;
+    };
+}[TriggerEvent];
+/**
+ * A trigger as entity metadata keeps it: the column callback resolved to keys, and a body widened to
+ * take both rows, which the renderer passes whatever the event, each body reading only its own.
+ */
+export type EntityTriggerMeta<E = object> = Except<TriggerOptions<E>, 'of' | 'where' | 'run'> & {
+    readonly of?: readonly string[];
+    readonly where?: TriggerPredicate<E, TriggerUpdateEvent> | TriggerMetaBody<E>;
+    readonly run: TriggerMetaBody<E> | Readonly<Partial<Record<SqlDialectName, TriggerMetaBody<E>>>>;
+};
+/**
+ * A body as the renderer calls it, with both rows whatever the event. Bivariant, as {@link EntitySql} is,
+ * so a body typing the row its event lacks as `never` is still held here.
+ */
+export type TriggerMetaBody<E> = {
+    run(newRow: RefMap<E>, oldRow: RefMap<E>): QueryRaw;
+}['run'];
 /**
  * A table's `CHECK`, `{ where: { balance: { $gte: 0 } } }`, or SQL off the refs,
  * `{ where: (wallet) => raw`${wallet.spent} <= ${wallet.balance}` }`.
@@ -743,6 +834,8 @@ export type EntityOptions<E = unknown> = {
     readonly checks?: readonly CheckOptions<E>[];
     /** Each lifecycle event and the methods it runs, read off the key map: `{ beforeInsert: (post) => [post.stamp] }`. */
     readonly hooks?: Partial<Record<HookEvent, (keys: KeyMap<E>) => readonly MethodKey<E>[]>>;
+    /** Triggers the database runs, in the order written. See {@link TriggerOptions}. */
+    readonly triggers?: readonly TriggerOptions<E>[];
 };
 /**
  * Everything an index carries beyond its columns, as the migration builder's `table.index(...)` takes it,

package/dist/type/migration.d.ts

@@ -118,14 +118,7 @@ export interface ColumnSchema extends Omit<ColumnNode, 'type' | 'table' | 'refer
 export interface TableSchema {
     readonly name: string;
     readonly columns: ColumnSchema[];
-    /** The key's columns **in order**, which is what a composite is: `(a, b)` is not `(b, a)`. */
-    readonly primaryKey?: string[];
-    /**
-     * What the engine calls the key's constraint, where it names one at all - Postgres's `Member_pkey`,
-     * MySQL's literal `PRIMARY`, nothing on SQLite. Only a `DROP` needs it, and only the name the
-     * database actually reported will do: a derived one would name a constraint that is not there.
-     */
-    readonly primaryKeyName?: string;
+    readonly primaryKey?: PrimaryKeySchema;
     readonly indexes?: IndexSchema[];
     readonly foreignKeys?: ForeignKeySchema[];
 }
@@ -176,8 +169,26 @@ export interface ForeignKeySchema {
     readonly onUpdate?: ForeignKeyAction;
 }
 /**
- * Represents a difference between current and desired schema
+ * One object's change: added (`to` alone), dropped (`from` alone), or altered (both), each whole so the
+ * change is undone by swapping its ends. No engine alters an index, a key or a foreign key in place, so
+ * an alter of one is its drop and its add, which safe mode holds back together.
  */
+export interface Change<T> {
+    readonly from?: T;
+    readonly to?: T;
+}
+/** A primary key, whichever side it is read from: the entities, the database, or a diff between them. */
+export interface PrimaryKeySchema {
+    /** Its columns **in order**, which is what a composite is: `(a, b)` is not `(b, a)`. */
+    readonly columns: readonly string[];
+    /**
+     * What the engine calls its constraint, where it names one at all - Postgres's `Member_pkey`, MySQL's
+     * literal `PRIMARY`, nothing on SQLite. Only a `DROP` needs it, and only the name the database
+     * reported will do: a derived one would name a constraint that is not there.
+     */
+    readonly name?: string;
+}
+/** A table's differences from what its entity declares, or the table to create or drop. */
 export interface SchemaDiff {
     /** Qualified where the table has a schema, since it is also the key the table is found under. */
     readonly tableName: string;
@@ -187,36 +198,10 @@ export interface SchemaDiff {
      */
     readonly schema?: string;
     readonly type: 'create' | 'alter' | 'drop';
-    /**
-     * The table's key against the entity's, where their columns differ; `fromName` is the name the
-     * database reported, which is what a `DROP` needs.
-     */
-    readonly primaryKey?: {
-        readonly from: string[];
-        readonly to: string[];
-        readonly fromName?: string;
-    };
-    readonly columnsToAdd?: ColumnSchema[];
-    readonly columnsToAlter?: {
-        from: ColumnSchema;
-        to: ColumnSchema;
-    }[];
-    readonly columnsToDrop?: string[];
-    readonly indexesToAdd?: IndexSchema[];
-    /** Whole rather than by name, so the rollback can create each again. */
-    readonly indexesToDrop?: IndexSchema[];
-    readonly foreignKeysToAdd?: ForeignKeySchema[];
-    /** Dropped under the name the *database* reported, which is the only name a `DROP` can use. */
-    readonly foreignKeysToDrop?: string[];
-    /**
-     * A constraint whose referential actions changed. Its own field rather than a pair of entries in
-     * the two above, because no engine alters an action in place: it is a drop and an add that have to
-     * travel together, and safe mode has to hold back both or neither.
-     */
-    readonly foreignKeysToAlter?: {
-        readonly from: ForeignKeySchema;
-        readonly to: ForeignKeySchema;
-    }[];
+    readonly primaryKey?: Change<PrimaryKeySchema>;
+    readonly columns?: readonly Change<ColumnSchema>[];
+    readonly indexes?: readonly Change<IndexSchema>[];
+    readonly foreignKeys?: readonly Change<ForeignKeySchema>[];
 }
 /**
  * What every sync entry point takes: `safe` keeps it additive, `drop` lets it remove a column, and
@@ -248,10 +233,14 @@ export interface DropSchemaOptions {
     readonly ifExists?: boolean;
     readonly cascade?: boolean;
 }
+/** The triggers uql installed on one table, by name, each with the statements that recreate it as it stands. */
+export type InstalledTriggers = ReadonlyMap<string, readonly string[]>;
 /**
  * Interface for generating DDL statements from entity metadata
  */
 export interface SchemaGenerator {
+    /** Whether a column's stored default is the one the entity declares, as the engine reprints it. Absent where columns are not compared. */
+    readonly defaultsEqual?: (expected: unknown, actual: unknown) => boolean;
     /** The whole schema for `entities`, tables then the foreign keys between them, which need every entity at once. */
     generateCreateSchema(entities: readonly Type<object>[], options?: CreateSchemaOptions): string[];
     /**
@@ -263,13 +252,16 @@ export interface SchemaGenerator {
     /** Generate DROP TABLE statement. */
     generateDropTable(tableName: string, options?: DropSchemaOptions): string;
     /**
-     * Generate ALTER TABLE statements based on schema diff
+     * What takes the triggers on `entity`'s table from `installed` - each by name, with the statements that
+     * recreate it - to what it declares: nothing where the two agree, which is always on MongoDB.
      */
+    generateTriggers(entity: Type<object>, installed?: InstalledTriggers): string[];
+    /** The inverse of {@link generateTriggers} from the same `installed`: its triggers dropped, and the ones it dropped restored. */
+    generateTriggersDown(entity: Type<object>, installed?: InstalledTriggers): string[];
+    /** A `DROP` for each trigger uql owns among `names` on `entity`'s table, whatever the entity declares. */
+    generateTriggerDrops(entity: Type<object>, names: readonly string[]): string[];
+    /** The statements taking a table through `diff`; its rollback is the diff reversed, see `reverseDiff`. */
     generateAlterTable(diff: SchemaDiff): string[];
-    /**
-     * Generate rollback (down) statements for ALTER TABLE based on schema diff
-     */
-    generateAlterTableDown(diff: SchemaDiff): string[];
     /**
      * Generate CREATE INDEX statement
      */
@@ -321,6 +313,13 @@ export interface SchemaGenerator {
  * Interface for introspecting the current database schema
  */
 export interface SchemaIntrospector {
+    /**
+     * Every trigger uql installed on `table`, by name, each with the statements that recreate it as it
+     * stands. The names say which to drop once an entity no longer declares them; the statements are what
+     * a rollback puts back, read off the engine rather than recorded anywhere by uql. One table's alone,
+     * so reading it never meets a trigger another writer is dropping from some other table.
+     */
+    ownedTriggers(table: string): Promise<InstalledTriggers>;
     /**
      * What this introspector can read back about an index, and so all that diffing may compare.
      * Comparing a feature it cannot read reports the same drift forever: the entity side declares it,

package/dist/type/query.d.ts

@@ -22,13 +22,22 @@ export type QueryOptions = {
      * table look alike. The entity's own filters never count as naming one.
      */
     unfiltered?: boolean;
-    /**
-     * prefix the query with this.
-     */
+};
+/**
+ * What a statement is rendered with, on top of the options its caller passed. Kept apart from
+ * {@link QueryOptions} because that one is public - it is the third argument of every querier method -
+ * and none of this is a caller's to set: an alias is the dialect's to choose and to spell.
+ */
+export type QueryRenderOptions = QueryOptions & {
+    /** The alias columns are read off, escaped by the dialect unless {@link escapedPrefix} spells it. */
     prefix?: string;
     /**
-     * automatically infer the prefix for the query.
+     * The prefix already written out, for the one caller whose row is not an identifier: a trigger reads
+     * `NEW."col"`, where `NEW` is a record the engine declares, and quoting it names a table that is not
+     * in scope. Defaults to {@link prefix} escaped.
      */
+    escapedPrefix?: string;
+    /** Whether to infer the alias where none is given. */
     autoPrefix?: boolean;
 };
 /**

package/dist/type/queryWhere.d.ts

@@ -223,6 +223,8 @@ export type QueryWhereElemMatch<U, Raw = QueryRaw> = unknown extends U ? {
 } : NonNullable<U> extends Scalar ? QueryWhereFieldOperators<NonNullable<U>, Raw> : {
     [K in keyof NonNullable<U>]?: QueryWhereFieldValue<NonNullable<U>[K], Raw>;
 };
+/** Every operator a field condition takes, which is what a key of one is once checked. */
+export type QueryWhereFieldOp = keyof QueryWhereFieldOperatorMap<unknown>;
 /**
  * Simple relational comparison operators. `Pick`'s constraint ties this back to
  * {@link QueryWhereFieldOperatorMap} so a rename there breaks this union at compile time.
@@ -251,7 +253,7 @@ type QueryArrayOp = keyof Pick<QueryWhereFieldOperatorMap<unknown>, '$all' | '$s
 /**
  * Ordering operators: {@link QueryCompareOp} plus `$between`.
  */
-type QueryOrderedOp = QueryCompareOp | keyof Pick<QueryWhereFieldOperatorMap<unknown>, '$between'>;
+export type QueryOrderedOp = QueryCompareOp | keyof Pick<QueryWhereFieldOperatorMap<unknown>, '$between'>;
 /**
  * Vector-only operators. `Pick`'s constraint ties this back to {@link QueryWhereFieldOperatorMap}
  * so a rename there breaks this union at compile time.
@@ -261,7 +263,7 @@ type QueryVectorOp = keyof Pick<QueryWhereFieldOperatorMap<unknown>, '$near'>;
  * The operators every field takes. A subtraction, so an operator added to the map without being
  * classified above is offered on every field: classify it first.
  */
-type QueryCommonOp = Exclude<keyof QueryWhereFieldOperatorMap<unknown>, QueryStringOp | QueryArrayOp | QueryOrderedOp | QueryVectorOp>;
+type QueryCommonOp = Exclude<QueryWhereFieldOp, QueryStringOp | QueryArrayOp | QueryOrderedOp | QueryVectorOp>;
 /**
  * Operator keys applicable to a field of type `T`. Brackets prevent union distribution so an
  * optional field (`string | undefined`) or a literal union (`'a' | 'b'`) gates as one type.