uql-orm 0.79.0 → 0.80.0

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/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, type FamilyOf, type 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
@@ -74,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 {

package/dist/util/fieldOption.util.js

@@ -86,8 +86,8 @@ 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')

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
@@ -26,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, RAW_TEXT, RelationAggregate, } from '../type/index.js';
-import { isInlinedExpression } from './field.util.js';
-import { hasKeys } from './object.util.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);
@@ -83,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.

package/package.json

@@ -3,7 +3,7 @@
   "homepage": "https://uql-orm.dev",
   "description": "The JSON-native TypeScript ORM for Bun, Browsers, Edge, Deno, Node, Workers. Supports PostgreSQL, PGlite, MySQL, MariaDB, SQLite, CockroachDB, SQL Server, Turso, Neon, Cloudflare D1 and MongoDB. Queries are plain JSON, typed to the leaf.",
   "license": "MIT",
-  "version": "0.79.0",
+  "version": "0.80.0",
   "type": "module",
   "engines": {
     "node": ">=24"
@@ -136,9 +136,9 @@
     "@electric-sql/pglite-pgvector": "0.0.9",
     "@libsql/client": "^0.18.0",
     "@neondatabase/serverless": "^1.1.0",
-    "@nestjs/common": "^12.0.3",
-    "@nestjs/core": "^12.0.3",
-    "@nestjs/testing": "^12.0.3",
+    "@nestjs/common": "^12.1.0",
+    "@nestjs/core": "^12.1.0",
+    "@nestjs/testing": "^12.1.0",
     "@tursodatabase/database": "^0.7.2",
     "@tursodatabase/serverless": "^1.4.0",
     "@types/better-sqlite3": "^9.6.0",

package/skills/uql-orm/SKILL.md

@@ -3,7 +3,7 @@ name: uql-orm
 description: >
   Write code with UQL (the uql-orm package), the TypeScript ORM whose queries are plain JSON objects,
   on PostgreSQL, MySQL, MariaDB, SQLite, CockroachDB, SQL Server, MongoDB, Turso, Neon, D1 and PGlite.
-  Use when a project imports uql-orm, or when defining entities, querying, populating relations,
+  Use when a project imports uql-orm, or when defining entities or triggers, querying, populating relations,
   writing transactions, raw SQL or migrations with it. UQL is not Prisma, Drizzle, TypeORM or MikroORM:
   their APIs do not carry over.
 ---
@@ -76,14 +76,15 @@ export class Post {
 
 - Every `@Field` states its `type` (`String`, `Number`, `Boolean`, `Date`, `BigInt`, or a column type such as `'uuid'`, `'text'`, `'jsonb'`), except a foreign key, which takes `references` and inherits the target key's type.
 - A column is nullable unless it says `nullable: false`, and its property must admit `null` to match: `title?: string | null`. A property typed without `| null` on a nullable column is a compile error.
-- An engine's own column type is a `raw` constant, `columnType: raw`tsvector``, rendered verbatim: never a bare string, so a misspelling cannot pass for one, and `length`/`precision`/`scale`/`dimensions` are refused beside it, the text carrying its own.
+- An engine's own column type is a `raw` constant, ``columnType: raw`tsvector` ``, rendered verbatim and carrying its own `length`/`precision`: never a bare string.
 - Members are named by callbacks, never by strings: `mappedBy: (post) => post.author`, `references: (post) => post.authorId`.
 - `@ManyToMany({ entity: () => Tag, through: () => PostTag })` names its junction entity.
 - `@Index((post) => [post.authorId], { where: { archived: { $ne: true } } })` states a partial index's filter as the predicate the query passes, never as `raw`: a planner matches the two by shape, so `raw` that means the same thing leaves the index unused.
-- `@Field({ type: Number, version: true })`, with `[versionKey]?: 'version'` on the class, makes the column an
-  optimistic lock: every update payload must carry the version it read (a compile error otherwise), the update
-  matches on it and writes the next one, and a write against a row someone else moved on throws
-  `UqlOptimisticLockError` (kind `optimisticLock`, HTTP 409) instead of overwriting it. Save and upsert are refused on such an entity; the update is named by its id, so `updateMany` over a many-row filter is refused too, and delete and restore carry no version.
+- `@Field({ type: Number, version: true })`, with `[versionKey]?: 'version'` on the class, is an optimistic lock:
+  an update must carry the version it read (a compile error otherwise), and one against a row someone else moved on throws `UqlOptimisticLockError` (kind `optimisticLock`, HTTP 409). Its updates name one row by its id; save and upsert are refused.
+- `@Field({ computed })` is a value the database produces, on a `readonly` property: SQL over the row, ``(u) => raw`${u.first} || ' ' || ${u.last}` ``, or a relation aggregate, `(order) => order.items.count()`.
+  `stored: true` makes the SQL a generated column; `stored: ['insert', 'update']` makes it a stamp, a trigger writing it on those events whoever writes the row (``computed: raw`CURRENT_TIMESTAMP` ``), where `onUpdate` covers only uql's own writes.
+- `@Trigger({ on: 'afterUpdate', of: (post) => [post.status], where: { $old: { status: 'draft' } }, run })` is a trigger the database fires; `where` holds a `$where` predicate per row it names, or SQL off the rows. `run` reads `{ newRow }` on insert, `{ newRow, oldRow }` on update, `{ oldRow }` on delete, and returns the engine's own SQL, one body for every engine or `{ postgres, mssql, ... }` where they differ (SQL Server fires per statement, reading `inserted`/`deleted` as tables, with no `before*` and no `where`). MongoDB has none, and refuses a write to an entity declaring one.
 - `defineEntity` defines the same entity without decorators: https://uql-orm.dev/entities/imperative.md
 
 ## Queries
@@ -111,6 +112,7 @@ const users = await pool.findMany(User, {
 - `$where` takes a value for equality or an operator map: `$eq`, `$ne`, `$lt`, `$lte`, `$gt`, `$gte`, `$in`,
   `$nin`, `$between`, `$like`, `$ilike`, `$regex`, `$startsWith`, `$endsWith`, `$includes`, `$isNull`,
   `$isNotNull`. `$and`, `$or`, `$not` and `$nor` combine clauses.
+- NULL compares the way the engine compares it: on SQL, `$ne`, `$nin`, `$not` and `$nor` leave out a NULL row, where MongoDB keeps it. Name NULL where you want it, `{ $or: [{ col: { $ne: 'a' } }, { col: null }] }`; ask for NULL with `{ col: null }` and its absence with `{ col: { $ne: null } }`.
 - `$text: { $value }` in `$where` searches text on every engine with full-text search, through the entity's
   `@Index(..., { type: 'fulltext', config })`, whose columns may carry a `weight`. `$sort: { $text: 'desc' }` ranks by
   relevance, and `{ $text: { $project: 'score' } }` also returns it, typed with `WithProjection<E, 'score'>`.
@@ -153,11 +155,14 @@ transaction. A querier from `pool.getQuerier()` is yours to release: bind it wit
 `npx uql-migrate` reads `uql.config.ts`. `sync` creates what the entities imply (development only);
 `generate:entities` writes the diff as a migration file to review; `up` applies migrations; `generate:from-db`
 writes entity classes from an existing database; `drift:check` fails when the database no longer matches.
+Triggers are part of the diff: uql installs its own under `_uql_`-prefixed names and never touches another.
 
 ## Where to read more
 
 - Operators, per-dialect SQL: https://uql-orm.dev/querying/comparison-operators.md
 - Relations and deep `$populate`: https://uql-orm.dev/querying/relations.md
+- Computed fields and stamps: https://uql-orm.dev/entities/computed-fields.md
+- Triggers: https://uql-orm.dev/entities/triggers.md
 - Every method's signature: https://uql-orm.dev/querying/methods.md
 - Coming from Prisma, Drizzle, TypeORM or MikroORM: https://uql-orm.dev/switching-to-uql.md
 - Breaking changes by version: https://uql-orm.dev/upgrade-guide.md