uql-orm 0.78.0 → 0.80.0

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>;
@@ -271,8 +276,12 @@ export type FieldOptions<V = TsTypeOf<FieldType>, E = unknown> = {
      * column is `NOT NULL DEFAULT 0`, and the entity brands the property with {@link versionKey}.
      */
     readonly version?: true;
-    /** The SQL type, where it differs from the one `type` implies: `type: String, columnType: 'decimal'`. */
-    readonly columnType?: ColumnType;
+    /**
+     * The SQL type, where it differs from the one `type` implies: `type: String, columnType: 'decimal'`.
+     * An engine's own type is a `raw` constant, `columnType: raw`tsvector``, rendered verbatim and
+     * never translated, so a column declaring one is yours to keep portable.
+     */
+    readonly columnType?: ColumnType | QueryRaw;
     /** A string column's length. */
     readonly length?: number;
     /** A decimal column's precision. */
@@ -687,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}` }`.
@@ -739,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

@@ -248,6 +248,8 @@ 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
  */
@@ -262,6 +264,15 @@ export interface SchemaGenerator {
     generateDropSchema(entities: readonly Type<object>[], options?: DropSchemaOptions): string[];
     /** Generate DROP TABLE statement. */
     generateDropTable(tableName: string, options?: DropSchemaOptions): string;
+    /**
+     * 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[];
     /**
      * Generate ALTER TABLE statements based on schema diff
      */
@@ -321,6 +332,12 @@ export interface SchemaGenerator {
  * Interface for introspecting the current database schema
  */
 export interface SchemaIntrospector {
+    /**
+     * Every trigger uql installed in this schema, by table and then 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.
+     */
+    ownedTriggers(): Promise<Map<string, 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/queryRaw.d.ts

@@ -27,10 +27,17 @@ export type QueryRawFnOptions = Partial<QueryRawRenderOptions>;
 export type QueryRawFn = (opts: QueryRawRenderOptions) => unknown;
 export declare const RAW_VALUE: unique symbol;
 export declare const RAW_ALIAS: unique symbol;
+export declare const RAW_TEXT: unique symbol;
 export declare class QueryRaw {
     readonly [RAW_VALUE]: QueryRawFn;
     readonly [RAW_ALIAS]?: string;
-    constructor(value: QueryRawFn, alias?: string);
+    /**
+     * The SQL verbatim, set only where it is a constant: a template that interpolates nothing binds no
+     * value and reads no column, so it needs no dialect to render. What a DDL clause with nowhere to
+     * bind reads - see {@link constantSql}.
+     */
+    readonly [RAW_TEXT]?: string;
+    constructor(value: QueryRawFn, alias?: string, text?: string);
     /** The same expression under an alias, for a `$select` projection. */
     as(alias: string): QueryRaw;
     /** Writes the expression into `opts.ctx`. The alias is the projection's to write, after the term. */

package/dist/type/queryRaw.js

@@ -1,15 +1,23 @@
 export const RAW_VALUE = Symbol('rawValue');
 export const RAW_ALIAS = Symbol('rawAlias');
+export const RAW_TEXT = Symbol('rawText');
 export class QueryRaw {
     [RAW_VALUE];
     [RAW_ALIAS];
-    constructor(value, alias) {
+    /**
+     * The SQL verbatim, set only where it is a constant: a template that interpolates nothing binds no
+     * value and reads no column, so it needs no dialect to render. What a DDL clause with nowhere to
+     * bind reads - see {@link constantSql}.
+     */
+    [RAW_TEXT];
+    constructor(value, alias, text) {
         this[RAW_VALUE] = value;
         this[RAW_ALIAS] = alias;
+        this[RAW_TEXT] = text;
     }
     /** The same expression under an alias, for a `$select` projection. */
     as(alias) {
-        return new QueryRaw(this[RAW_VALUE], alias);
+        return new QueryRaw(this[RAW_VALUE], alias, this[RAW_TEXT]);
     }
     /** Writes the expression into `opts.ctx`. The alias is the projection's to write, after the term. */
     render(opts) {

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.

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

@@ -1,4 +1,4 @@
-import { type ColumnFamily, type EntityMeta, type FieldKey, type FieldOptions, type RelationAggregateSpec } from '../type/index.js';
+import { type ColumnFamily, type EntityMeta, type FieldKey, type FieldOptions, type StampEvent, type RelationAggregateSpec } from '../type/index.js';
 /** The family of a logical field type, or `undefined` where it names none. */
 export declare function columnFamily(type: unknown): ColumnFamily | undefined;
 /**
@@ -12,6 +12,14 @@ export declare function isIntegerColumn(field: Pick<FieldOptions, 'type' | 'colu
  * because an inlined field has no column to name, while a stored one is read like any other.
  */
 export declare function isInlinedExpression<F extends FieldOptions>(field: F): field is F & Required<Pick<F, 'computed'>>;
+/** Whether the entity puts anything on its table the database runs: an authored trigger, or a stamp. */
+export declare function hasTriggers<E>(meta: EntityMeta<E>): boolean;
+/**
+ * The events the database writes this field on, or `undefined` where it is not a stamp. A stamp is a
+ * real column the engine fills on each event, which is how an expression too volatile for a generated
+ * column - `now()` - is still kept by the database rather than by whoever happens to write the row.
+ */
+export declare function stampEvents(field: FieldOptions): readonly StampEvent[] | undefined;
 /**
  * The relation aggregate a field computes, where it computes one rather than writing SQL: what it
  * reads, off which relation, narrowed and capped how. Every engine renders it from this - a correlated

package/dist/util/field.util.js

@@ -1,5 +1,5 @@
 import { COLUMN_TYPES, RelationAggregate, } from '../type/index.js';
-import { getKeys } from './object.util.js';
+import { definedEntries, getKeys } from './object.util.js';
 // Constructors and type strings in one map: a logical type is either, and every caller asks the same
 // question of both.
 const FAMILY_OF = new Map([
@@ -39,7 +39,19 @@ export function isIntegerColumn(field) {
  * because an inlined field has no column to name, while a stored one is read like any other.
  */
 export function isInlinedExpression(field) {
-    return field.computed !== undefined && field.stored !== true;
+    return field.computed !== undefined && !field.stored;
+}
+/** Whether the entity puts anything on its table the database runs: an authored trigger, or a stamp. */
+export function hasTriggers(meta) {
+    return Boolean(meta.triggers?.length) || definedEntries(meta.fields).some(([, field]) => stampEvents(field));
+}
+/**
+ * The events the database writes this field on, or `undefined` where it is not a stamp. A stamp is a
+ * real column the engine fills on each event, which is how an expression too volatile for a generated
+ * column - `now()` - is still kept by the database rather than by whoever happens to write the row.
+ */
+export function stampEvents(field) {
+    return Array.isArray(field.stored) ? field.stored : undefined;
 }
 /**
  * The relation aggregate a field computes, where it computes one rather than writing SQL: what it

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

@@ -1,4 +1,4 @@
-import type { ColumnFamily, FamilyOf, FieldOptions, QueryRaw } from '../type/index.js';
+import { type ColumnFamily, type FamilyOf, type FieldOptions, QueryRaw, type StampEvent } from '../type/index.js';
 /**
  * The column family each field option means anything on, or `'*'` where it applies to every column.
  * Exhaustive over {@link FieldOptions}, so a new option cannot be added without placing it - the
@@ -54,6 +54,12 @@ type GeneratedWrite = (typeof GENERATED_WRITES)[number];
  */
 declare const VERSION_WRITES: readonly ["updatable", "onInsert", "onUpdate", "softDelete", "defaultValue", "autoIncrement", "computed", "stored", "isId"];
 type VersionWrite = (typeof VERSION_WRITES)[number];
+/**
+ * What bounds a type: stated separately where uql spells the type, and part of the text where the
+ * engine's own is written out, which renders verbatim and leaves these unread.
+ */
+declare const TYPE_BOUNDS: readonly ["length", "precision", "scale", "dimensions"];
+type TypeBound = (typeof TYPE_BOUNDS)[number];
 /**
  * The first option `opts` cannot use, phrased as the tail of `'Entity.field' ...`, or `undefined`
  * where every option applies. The runtime half of the decorators' check, so the imperative API and
@@ -68,7 +74,7 @@ type OptionsFamily<O> = O extends {
 } ? FamilyOf<T> : ColumnFamily;
 /** What the field's own values leave unread, matching {@link deadOn} line for line. */
 type DeadOptions<O> = (O extends {
-    readonly stored: true;
+    readonly stored: true | readonly StampEvent[];
 } ? GeneratedWrite : O extends {
     readonly computed: QueryRaw;
 } ? Exclude<keyof FieldOptions, InlineRead> : never) | (O extends {
@@ -77,6 +83,8 @@ type DeadOptions<O> = (O extends {
 } ? 'nullable' : never) | (O extends {
     readonly updatable: false;
 } ? 'onUpdate' : never) | (O extends {
+    readonly columnType: QueryRaw;
+} ? TypeBound : never) | (O extends {
     readonly version: true;
 } ? VersionWrite : never) | (O extends {
     readonly version: true;

package/dist/util/fieldOption.util.js

@@ -1,5 +1,7 @@
+import { QueryRaw } from '../type/index.js';
 import { columnFamily, isInlinedExpression } from './field.util.js';
 import { getKeys } from './object.util.js';
+import { constantSql } from './raw.js';
 /**
  * The column family each field option means anything on, or `'*'` where it applies to every column.
  * Exhaustive over {@link FieldOptions}, so a new option cannot be added without placing it - the
@@ -68,6 +70,11 @@ const GENERATED_WRITES = [...VALUE_DECIDERS, 'version'];
  * would make it another kind of column entirely. Its `nullable: false` and `DEFAULT 0` are implied.
  */
 const VERSION_WRITES = [...VALUE_DECIDERS, 'computed', 'stored', 'isId'];
+/**
+ * What bounds a type: stated separately where uql spells the type, and part of the text where the
+ * engine's own is written out, which renders verbatim and leaves these unread.
+ */
+const TYPE_BOUNDS = ['length', 'precision', 'scale', 'dimensions'];
 /**
  * Whether `key` is the `nullable: true` a NOT NULL column contradicts. `nullable: false` says what
  * such a column already is, and rejecting an accurate statement teaches an author to distrust the check.
@@ -79,12 +86,15 @@ function contradictsNotNull(opts, key) {
 function deadOn(opts, key) {
     if (isInlinedExpression(opts) && !INLINE_READS.some((read) => read === key))
         return 'an inlined computed field';
-    if (opts.stored === true && GENERATED_WRITES.some((write) => write === key))
-        return 'a stored computed column';
+    if (opts.stored && GENERATED_WRITES.some((write) => write === key))
+        return 'a column the database writes';
     if (opts.isId === true && contradictsNotNull(opts, key))
         return 'a primary key';
     if (opts.updatable === false && key === 'onUpdate')
         return "a field declared 'updatable: false'";
+    if (opts.columnType instanceof QueryRaw && TYPE_BOUNDS.some((bound) => bound === key)) {
+        return 'a column type written out as SQL, which carries its own bounds';
+    }
     if (opts.version === true && (VERSION_WRITES.some((write) => write === key) || contradictsNotNull(opts, key))) {
         return 'a version field';
     }
@@ -96,6 +106,11 @@ function deadOn(opts, key) {
  * plain JavaScript reach the same answer.
  */
 export function fieldOptionConflict(opts) {
+    // Caught here rather than where the type is resolved, which is a migration on most engines and a
+    // query on SQL Server, and which knows no field to name.
+    if (opts.columnType instanceof QueryRaw && constantSql(opts.columnType) === undefined) {
+        return "cannot use 'columnType': a `raw` one names a constant type, so it can bind no value and read no column";
+    }
     const family = columnFamily(opts.columnType ?? opts.type);
     // Walked in table order, not in the order the field happened to be written, so a field with two
     // conflicts always reports the same one. An option no rule knows is a typo, which `@Field`'s own check

package/dist/util/raw.d.ts

@@ -1,4 +1,4 @@
-import { type EntitySql, type EntityWhere, type EntityWhereMeta, QueryRaw, type QueryRawFn, type ComputedRefs, type RefMap, type Type } from '../type/index.js';
+import { ColumnRef, type EntitySql, type EntityWhere, type EntityWhereMeta, QueryRaw, type QueryRawFn, type ComputedRefs, type RefMap, type TriggerRowName, type Type } from '../type/index.js';
 /**
  * Raw SQL, where an interpolated value binds, a `refs` field renders its column, and a `raw` renders
  * in place: `raw`GREATEST(0, ${user.credits} - ${amount})``. A callback writes whatever it writes, so
@@ -6,6 +6,11 @@ import { type EntitySql, type EntityWhere, type EntityWhereMeta, QueryRaw, type
  */
 export declare function raw(strings: TemplateStringsArray, ...values: readonly unknown[]): QueryRaw;
 export declare function raw(value: QueryRawFn): QueryRaw;
+/**
+ * The SQL of a `raw` that names a constant, for a DDL clause with no dialect to render against and
+ * nowhere to bind a value; `undefined` where it interpolates and so needs one.
+ */
+export declare function constantSql(value: QueryRaw): string | undefined;
 /**
  * The fields of `entity` as {@link ColumnRef}s, each rendering inside `raw` as its column: named the way
  * the dialect names it, so the naming strategy and `@Field({ name })` apply, and qualified by the alias
@@ -21,3 +26,11 @@ export declare function memberRefs<E>(): ComputedRefs<E>;
 export declare function entitySql<E>(sql: EntitySql<E>): QueryRaw;
 /** A definition's predicate, its callback resolved the way {@link entitySql} resolves one. */
 export declare function entityWhere<E>(where: EntityWhere<E>): EntityWhereMeta<E>;
+/**
+ * The fields of `E` as the row a trigger body reads them off, qualified by the side it names: `NEW."col"`
+ * against the incoming row, `OLD."col"` against the outgoing one. Columns only, never a relation's
+ * aggregate: that is a subquery, and a trigger fires on one row rather than over a table to correlate to.
+ */
+export declare function rowRefs<E>(qualifier: TriggerRowName): RefMap<E>;
+/** One field of a trigger's row, for code that names it by its key rather than off {@link rowRefs}. */
+export declare function rowColumn(qualifier: TriggerRowName, key: string): ColumnRef;

package/dist/util/raw.js

@@ -1,7 +1,7 @@
 import { getMeta } from '../entity/metadata/definition.js';
-import { ColumnRef, QueryRaw, RelationAggregate, } from '../type/index.js';
-import { isInlinedExpression } from './field.util.js';
-import { hasKeys } from './object.util.js';
+import { ColumnRef, QueryRaw, RAW_TEXT, RelationAggregate, } from '../type/index.js';
+import { aggregateOf, isInlinedExpression } from './field.util.js';
+import { entityName, hasKeys } from './object.util.js';
 export function raw(value, ...rest) {
     if (!isTemplateStrings(value)) {
         return new QueryRaw(value);
@@ -18,7 +18,14 @@ export function raw(value, ...rest) {
             }
             ctx.append(value[i + 1]);
         });
-    });
+    }, undefined, rest.length === 0 ? value[0] : undefined);
+}
+/**
+ * The SQL of a `raw` that names a constant, for a DDL clause with no dialect to render against and
+ * nowhere to bind a value; `undefined` where it interpolates and so needs one.
+ */
+export function constantSql(value) {
+    return value[RAW_TEXT];
 }
 /**
  * The fields of `entity` as {@link ColumnRef}s, each rendering inside `raw` as its column: named the way
@@ -76,26 +83,51 @@ function relationAggregate(spec) {
         opts.dialect.appendRelationAggregate(opts.ctx, opts.entity, spec, opts.prefix);
     });
 }
-/** One field as SQL, against its own entity or, read off a definition, the entity rendering it. */
-function columnRef(entity, key) {
+/**
+ * The fields of `E` as the row a trigger body reads them off, qualified by the side it names: `NEW."col"`
+ * against the incoming row, `OLD."col"` against the outgoing one. Columns only, never a relation's
+ * aggregate: that is a subquery, and a trigger fires on one row rather than over a table to correlate to.
+ */
+export function rowRefs(qualifier) {
+    return new Proxy({}, { get: (_, key) => rowColumn(qualifier, String(key)) });
+}
+/** One field of a trigger's row, for code that names it by its key rather than off {@link rowRefs}. */
+export function rowColumn(qualifier, key) {
+    return columnRef(undefined, key, qualifier);
+}
+/**
+ * One field as SQL, against its own entity or, read off a definition, the entity rendering it. A
+ * `qualifier` names the row it reads from, `NEW` or `OLD`, instead of the alias in scope.
+ */
+function columnRef(entity, key, qualifier) {
     return new ColumnRef(key, (opts) => {
         const owner = entity ?? opts.entity;
         if (!owner) {
             throw new TypeError(`'${key}' was read off a definition's refs, so it renders only inside its entity's SQL`);
         }
-        renderColumn(getMeta(owner), key, { ...opts, entity: owner });
+        renderColumn(getMeta(owner), key, { ...opts, entity: owner }, qualifier);
     });
 }
-/** A field's column, or the expression an inlined computed one stands for, as a `$where` on it reads it. */
-function renderColumn(meta, key, opts) {
+/**
+ * A field's column, or the expression an inlined computed one stands for, as a `$where` on it reads it.
+ * Under a `qualifier` the column is read off that row rather than off the alias in scope, and the row is
+ * written verbatim: it is a record the engine declares, not an identifier to quote and case-fold.
+ */
+function renderColumn(meta, key, opts, qualifier) {
+    const scope = qualifier === undefined ? opts : { ...opts, escapedPrefix: `${qualifier}.` };
     const field = meta.fields[key];
     if (field && isInlinedExpression(field)) {
-        opts.ctx.append('(');
-        field.computed.render(opts);
-        opts.ctx.append(')');
+        // A relation aggregate is a subquery correlated to a table in scope, and a trigger's row is not one.
+        if (qualifier !== undefined && aggregateOf(field)) {
+            throw new TypeError(`'${entityName(meta)}.${key}' reads a relation, which a trigger's row cannot: it fires on one row, ` +
+                'with no table in scope to correlate a subquery to. Name the columns it is derived from instead.');
+        }
+        scope.ctx.append('(');
+        field.computed.render(scope);
+        scope.ctx.append(')');
         return;
     }
-    opts.ctx.append(opts.escapedPrefix + opts.dialect.escapeId(opts.dialect.columnOf(meta, key), true));
+    scope.ctx.append(scope.escapedPrefix + scope.dialect.escapeId(scope.dialect.columnOf(meta, key), true));
 }
 /** A tag call passes the frozen strings array, which carries its own `raw` counterpart. */
 function isTemplateStrings(value) {

package/dist/util/sql.util.d.ts

@@ -23,6 +23,18 @@ export declare function qualifyName(name: string, schema?: string): string;
 export declare function derivedConstraintName(table: string, parts: readonly (string | number)[], kind: ConstraintKind): string;
 /** The kinds of derived name, which is also what `indexNameStem` strips to compare them. */
 export type ConstraintKind = 'pk' | 'fk' | 'idx' | 'ck' | 'uk';
+/**
+ * Whether uql installed the object called `name`. Ownership is the prefix and nothing else, since no
+ * engine records who created one - so this is the only thing standing between a hand-written trigger and
+ * a `DROP`, and it is asked on both sides: when reading the catalogue, and again before emitting.
+ */
+export declare function isOwnedName(name: string): boolean;
+/**
+ * The identifier uql installs a schema object under: its own prefix, the table it hangs off, the label
+ * the author gave it, and last a hash of the object's `content`, which no clamping cuts. The table keeps
+ * two entities sharing a label apart where an engine scopes such names to the schema.
+ */
+export declare function ownedName(table: string, label: string, content: string): string;
 /**
  * The name a derived index gets when nothing named it: `Order__total_idx`, or `Order__total_uk` for a
  * unique one - which the builder has always spelled apart, and which reads as what it enforces.

package/dist/util/sql.util.js

@@ -1,3 +1,4 @@
+import { OWNED_PREFIX } from '../dialect/aliases.js';
 import { hasKeys } from './object.util.js';
 /** Pre-computed regex for each SQL identifier escape character to avoid per-call allocation. */
 const escapeIdRegexCache = { '`': /`/g, '"': /"/g };
@@ -75,13 +76,33 @@ export function derivedConstraintName(table, parts, kind) {
 }
 /** Between table and columns, doubled: index names share one namespace per database, where `a` + `b_c` and `a_b` + `c` would collide. */
 const TABLE_SEPARATOR = '__';
+/** What every name uql installs begins with, so the two ends asking about one cannot spell it apart. */
+const OWNED_START = `${OWNED_PREFIX}_`;
+/**
+ * Whether uql installed the object called `name`. Ownership is the prefix and nothing else, since no
+ * engine records who created one - so this is the only thing standing between a hand-written trigger and
+ * a `DROP`, and it is asked on both sides: when reading the catalogue, and again before emitting.
+ */
+export function isOwnedName(name) {
+    return name.startsWith(OWNED_START);
+}
+/**
+ * The identifier uql installs a schema object under: its own prefix, the table it hangs off, the label
+ * the author gave it, and last a hash of the object's `content`, which no clamping cuts. The table keeps
+ * two entities sharing a label apart where an engine scopes such names to the schema.
+ */
+export function ownedName(table, label, content) {
+    const version = `_${hashIdentifier(content)}`;
+    return clampIdentifier(`${OWNED_START}${table}${TABLE_SEPARATOR}${label}`, version.length) + version;
+}
 /** A name the engine stores whole, shortened around a hash of the full one, which stays stable across runs. */
-function clampIdentifier(name) {
-    if (name.length <= MAX_IDENTIFIER_LENGTH) {
+function clampIdentifier(name, reserved = 0) {
+    const max = MAX_IDENTIFIER_LENGTH - reserved;
+    if (name.length <= max) {
         return name;
     }
     const suffix = `_${hashIdentifier(name)}`;
-    return name.slice(0, MAX_IDENTIFIER_LENGTH - suffix.length) + suffix;
+    return name.slice(0, max - suffix.length) + suffix;
 }
 /**
  * FNV-1a, by hand: the package ships zero runtime dependencies, and `node:crypto` is not reachable

package/dist/util/uqlError.d.ts

@@ -18,6 +18,8 @@ export declare class UqlUsageError extends TypeError {
     /** What an HTTP transport answers with. */
     readonly status = 400;
 }
+/** What a value is, for a refusal naming what `/http` handed over instead of what the types require. */
+export declare function kindOf(value: unknown): string;
 /**
  * @deprecated since 0.77.1 - use {@link UqlUsageError}, which every misuse throws, lock or not. The
  * same class under both names, so an existing `instanceof` keeps working.

package/dist/util/uqlError.js

@@ -11,6 +11,10 @@ export class UqlUsageError extends TypeError {
     /** What an HTTP transport answers with. */
     status = 400;
 }
+/** What a value is, for a refusal naming what `/http` handed over instead of what the types require. */
+export function kindOf(value) {
+    return value === null ? 'null' : Array.isArray(value) ? 'array' : typeof value;
+}
 /**
  * @deprecated since 0.77.1 - use {@link UqlUsageError}, which every misuse throws, lock or not. The
  * same class under both names, so an existing `instanceof` keeps working.