uql-orm 0.81.0 → 0.82.0

package/dist/type/dialect.d.ts

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

package/dist/type/entity.d.ts

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

package/dist/type/logger.d.ts

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

package/dist/type/querier.d.ts

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

package/dist/type/query.d.ts

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

package/dist/type/queryAggregate.d.ts

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

package/dist/type/queryRaw.d.ts

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

package/dist/type/queryRaw.js

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

package/dist/type/queryWhere.d.ts

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

package/dist/type/universalQuerier.d.ts

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

package/dist/type/vector.d.ts

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

package/dist/type/vector.js

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

package/dist/util/dialect.util.d.ts

@@ -1,5 +1,5 @@
 import type { IndexType } from '../schema/types.js';
-import { type AggregateCall, type CascadeType, type EntityData, type EntityId, type EntityIndexMeta, type EntityMeta, type FieldKey, type FieldOptions, type FieldUpdateOp, type JsonUpdateOp, type OnFieldCallback, type Query, type QueryAggMap, type QueryExclude, type QueryGroupMap, type QueryOptions, QueryRaw, type QuerySearch, type QuerySelect, type QuerySelectValue, type QuerySortDirection, type QuerySizeComparisonOps, type QuerySortMap, type QueryTextSearchOptions, type QueryVectorQuery, type QueryVectorSearch, type QueryWhere, type RelationKey, type UpdatePayload, type VectorDistance } from '../type/index.js';
+import { type AggregateCall, type CascadeType, type EntityData, type EntityId, type EntityIndexMeta, type EntityMeta, type FieldKey, type FieldOptions, type FieldUpdateOp, type JsonUpdateOp, type OnFieldCallback, type Query, type QueryAggMap, type QueryConflictPaths, type QueryExclude, type QueryGroupMap, type QueryOptions, QueryRaw, type QuerySearch, type QuerySelect, type QuerySelectValue, type QuerySortDirection, type QuerySizeComparisonOps, type QuerySortMap, type QueryTextSearchOptions, type QueryVectorQuery, type QueryVectorSearch, type QueryWhere, type QueryWhereArray, type RelationKey, type UpdatePayload, type VectorDistance } from '../type/index.js';
 export type CallbackKey = keyof Pick<FieldOptions, 'onInsert' | 'onUpdate'>;
 /** The keys of `payload` a write persists as columns. */
 export declare function filterFieldKeys<E>(meta: EntityMeta<E>, payload: EntityData<E> | UpdatePayload<E>, callbackKey: CallbackKey): FieldKey<E>[];
@@ -50,10 +50,18 @@ export declare function isCascadable(action: CascadeType, configuration?: boolea
  */
 export declare function isPagedQuery<E>(q: QuerySearch<E>): boolean;
 /**
- * `q` selecting nothing but the id: what a write hands its backend's own read builder to settle the
- * rows it will name. The cast is unavoidable - a computed key is not a `QuerySelect` key to the
- * compiler - so it is spelled once here rather than in each querier.
- */
+ * Each of `keys` switched on, as a `$select` or conflict paths name them. This and the `where*` builders
+ * below hold the casts a statement built in generic code needs: a key read at run time is no key of
+ * these maps to the compiler, whose values it works out per entity.
+ */
+export declare function keySet<E>(keys: readonly FieldKey<E>[]): QueryConflictPaths<E>;
+/** `where`, or no `$where`, with `key` held to `value` as well: spread, so the two `AND`. */
+export declare function whereWith<E>(key: FieldKey<E>, value: unknown, where?: QueryWhere<E>): QueryWhere<E>;
+/** The `$where` holding each of `keys` to what `valueOf` reads for it. */
+export declare function whereEach<E>(keys: readonly FieldKey<E>[], valueOf: (key: FieldKey<E>) => unknown): QueryWhere<E>;
+/** The `$where` any one of `clauses` satisfies. */
+export declare function whereAnyOf<E>(clauses: QueryWhereArray<E>): QueryWhere<E>;
+/** `q` selecting nothing but the id: what a write hands its backend's own read builder to settle the rows it will name. */
 export declare function idOnlyQuery<E>(meta: EntityMeta<E>, q: QuerySearch<E>): Query<E>;
 /**
  * The map form of a `$select` value, or `undefined` for the raw-array form. Centralizes the one

package/dist/util/dialect.util.js

@@ -2,7 +2,7 @@ import { getContext, UqlSecurityError } from '../context/context.js';
 import { soleIdOf } from '../entity/metadata/definition.js';
 import { QueryRaw, resolveAggregateOp, SOFT_DELETE_FILTER, } from '../type/index.js';
 import { DEFAULT_VECTOR_DISTANCE, VECTOR_INDEX_TYPES } from '../type/vector.js';
-import { getFieldKeys, isDatabaseWritten } from './field.util.js';
+import { defaultReadKeys, fieldKeys, isDatabaseWritten } from './field.util.js';
 import { entityName, getKeys, hasKeys, isOperatorObject, isScalarId, isRecord, isWhereMap, someKey, } from './object.util.js';
 import { UqlUsageError } from './uqlError.js';
 /** The keys of `payload` a write persists as columns. */
@@ -50,12 +50,7 @@ export function getInsertFieldKeys(meta, payloads) {
     for (const record of payloads) {
         addInsertFieldKeys(meta, record, seen, keys);
     }
-    for (const key of getKeys(meta.fields)) {
-        if (meta.fields[key].onInsert !== undefined && !seen.has(key)) {
-            keys.push(key);
-        }
-    }
-    return keys;
+    return [...keys, ...fieldKeys(meta, (field) => field.onInsert !== undefined).filter((key) => !seen.has(key))];
 }
 export function getFieldCallbackValue(val) {
     return typeof val === 'function' ? val() : val;
@@ -72,7 +67,7 @@ export function fillOnFields(meta, payload, callbackKey) {
     const payloads = Array.isArray(payload) ? payload : [payload];
     // By presence, not truthiness, as `addInsertFieldKeys` above reads it: `onInsert: 0` and `onInsert: ''`
     // are values a caller meant, and a falsy one was silently never filled.
-    const keys = getKeys(meta.fields).filter((key) => meta.fields[key][callbackKey] !== undefined);
+    const keys = fieldKeys(meta, (field) => field[callbackKey] !== undefined);
     if (keys.length === 0) {
         return payloads;
     }
@@ -120,12 +115,28 @@ export function isPagedQuery(q) {
     return q.$sort !== undefined || q.$limit !== undefined || q.$skip !== undefined;
 }
 /**
- * `q` selecting nothing but the id: what a write hands its backend's own read builder to settle the
- * rows it will name. The cast is unavoidable - a computed key is not a `QuerySelect` key to the
- * compiler - so it is spelled once here rather than in each querier.
+ * Each of `keys` switched on, as a `$select` or conflict paths name them. This and the `where*` builders
+ * below hold the casts a statement built in generic code needs: a key read at run time is no key of
+ * these maps to the compiler, whose values it works out per entity.
  */
+export function keySet(keys) {
+    return Object.fromEntries(keys.map((key) => [key, true]));
+}
+/** `where`, or no `$where`, with `key` held to `value` as well: spread, so the two `AND`. */
+export function whereWith(key, value, where) {
+    return { ...where, [key]: value };
+}
+/** The `$where` holding each of `keys` to what `valueOf` reads for it. */
+export function whereEach(keys, valueOf) {
+    return Object.fromEntries(keys.map((key) => [key, valueOf(key)]));
+}
+/** The `$where` any one of `clauses` satisfies. */
+export function whereAnyOf(clauses) {
+    return { $or: clauses };
+}
+/** `q` selecting nothing but the id: what a write hands its backend's own read builder to settle the rows it will name. */
 export function idOnlyQuery(meta, q) {
-    return { ...q, $select: Object.fromEntries(meta.ids.map((key) => [key, true])) };
+    return { ...q, $select: keySet(meta.ids) };
 }
 /**
  * The map form of a `$select` value, or `undefined` for the raw-array form. Centralizes the one
@@ -165,7 +176,7 @@ export function normalizeScalarFieldSelection(meta, select, exclude) {
             }
         }
     }
-    const allFields = getFieldKeys(meta.fields);
+    const allFields = defaultReadKeys(meta);
     if (!excludedFields) {
         return allFields;
     }
@@ -217,10 +228,7 @@ export function findVectorIndex(meta, key) {
  * serves no other, else cosine. The one fallback every engine resolves, so none can rank by another.
  */
 export function vectorDistanceOf(meta, key, search) {
-    return (search.$distance ??
-        meta.fields[key]?.distance ??
-        findVectorIndex(meta, key)?.distance ??
-        DEFAULT_VECTOR_DISTANCE);
+    return (search.$distance ?? meta.fields[key]?.distance ?? findVectorIndex(meta, key)?.distance ?? DEFAULT_VECTOR_DISTANCE);
 }
 /**
  * Whether a `$where` filters by vector distance anywhere in its tree, `$and`/`$or`/`$not` included.
@@ -271,7 +279,7 @@ export function fieldUpdateOf(key, value) {
  */
 export function whereIds(meta, ids) {
     if (Array.isArray(ids) ? ids.every(isScalarId) : isScalarId(ids)) {
-        return { [soleIdOf(meta, 'addressing by a bare id value')]: ids };
+        return whereWith(soleIdOf(meta, 'addressing by a bare id value'), ids);
     }
     return (Array.isArray(ids) ? { $or: ids } : ids);
 }
@@ -492,11 +500,11 @@ export function fulltextWeights(index) {
         return undefined;
     }
     if (index.type !== 'fulltext') {
-        throw new TypeError(`a column weight ranks a fulltext index, and this one is ${index.type ?? 'btree'}`);
+        throw new UqlUsageError(`a column weight ranks a fulltext index, and this one is ${index.type ?? 'btree'}`);
     }
     const weights = index.entries.map(({ weight = 1 }) => {
         if (!Number.isInteger(weight) || weight < 1 || weight > MAX_TEXT_WEIGHT) {
-            throw new TypeError(`a column weight is a whole number from 1 to ${MAX_TEXT_WEIGHT}, not ${weight}`);
+            throw new UqlUsageError(`a column weight is a whole number from 1 to ${MAX_TEXT_WEIGHT}, not ${weight}`);
         }
         return weight;
     });

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

@@ -1,4 +1,4 @@
-import { type ColumnFamily, type EntityMeta, type FieldKey, type FieldOptions, type StampEvent, type RelationAggregateSpec } from '../type/index.js';
+import { type ColumnFamily, type EntityMeta, type FieldKey, type FieldMeta, 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;
 /**
@@ -39,11 +39,11 @@ export declare function isSoleIdField<E>(meta: EntityMeta<E>, field: FieldOption
  * states its width. The one answer the create statement and the diff both read.
  */
 export declare function isAutoIncrement(field: FieldOptions, isPrimaryKey: boolean): boolean;
+/** The fields `meta` declares whose options `pick` accepts, in declaration order, each as the entity's own key. */
+export declare function fieldKeys<E>(meta: EntityMeta<E>, pick: (field: FieldMeta) => unknown): FieldKey<E>[];
 /**
  * The fields a read answers with where it names none. A relation aggregate is left out unless it asks
  * for `eager: true`: it reads the related rows, which is what a relation does, and a relation is loaded
  * only when a query asks for it. Naming one in `$select` reads it, whatever the default.
  */
-export declare function getFieldKeys<E>(fields: {
-    [K in FieldKey<E>]?: FieldOptions;
-}): FieldKey<E>[];
+export declare function defaultReadKeys<E>(meta: EntityMeta<E>): FieldKey<E>[];

package/dist/util/field.util.js

@@ -83,11 +83,19 @@ export function isAutoIncrement(field, isPrimaryKey) {
         return field.autoIncrement;
     return isPrimaryKey && columnFamily(field.type) === 'numeric' && !field.onInsert && !field.references;
 }
+/** The fields `meta` declares whose options `pick` accepts, in declaration order, each as the entity's own key. */
+export function fieldKeys(meta, pick) {
+    const fields = meta.fields;
+    return getKeys(fields).filter((key) => {
+        const field = fields[key];
+        return field !== undefined && Boolean(pick(field));
+    });
+}
 /**
  * The fields a read answers with where it names none. A relation aggregate is left out unless it asks
  * for `eager: true`: it reads the related rows, which is what a relation does, and a relation is loaded
  * only when a query asks for it. Naming one in `$select` reads it, whatever the default.
  */
-export function getFieldKeys(fields) {
-    return getKeys(fields).filter((field) => fields[field].eager ?? !aggregateOf(fields[field]));
+export function defaultReadKeys(meta) {
+    return fieldKeys(meta, (field) => field.eager ?? !aggregateOf(field));
 }

package/dist/util/hook.util.d.ts

@@ -11,4 +11,4 @@ export type HookContext = {
  * Hooks are invoked with `this` bound to the payload via `call`,
  * so mutations go directly to the original object.
  */
-export declare function runHooks<E extends object>(entity: Type<E>, event: HookEvent, payloads: E[], ctx: HookContext): Promise<void>;
+export declare function runHooks<E extends object>(entity: Type<E>, event: HookEvent, payloads: readonly E[], ctx: HookContext): Promise<void>;

package/dist/util/hook.util.js

@@ -1,4 +1,5 @@
 import { getMeta } from '../entity/index.js';
+import { UqlUsageError } from './uqlError.js';
 /**
  * Run all registered hooks for the given event on each payload.
  * Hooks are invoked with `this` bound to the payload via `call`,
@@ -9,9 +10,15 @@ export async function runHooks(entity, event, payloads, ctx) {
     const registrations = meta.hooks?.[event];
     if (!registrations?.length)
         return;
+    // A prototype is typed `any`, so what is read off it is typed here, where it enters.
+    const prototype = entity.prototype;
     for (const payload of payloads) {
         for (const { methodName } of registrations) {
-            const result = entity.prototype[methodName].call(payload, ctx);
+            const method = prototype[methodName];
+            if (typeof method !== 'function') {
+                throw new UqlUsageError(`'${entity.name}' runs '${methodName}' on ${event}, but has no such method`);
+            }
+            const result = method.call(payload, ctx);
             if (result instanceof Promise)
                 await result;
         }

package/dist/util/index.d.ts

@@ -7,6 +7,7 @@ export * from './ddlExpression.util.js';
 export * from './logger.js';
 export * from './object.util.js';
 export * from './raw.js';
+export * from './triggerWrite.js';
 export * from './rowKey.util.js';
 export * from './relationQuery.util.js';
 export * from './sql.util.js';