uql-orm 0.80.0 → 0.82.0

package/dist/type/migration.d.ts

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

package/dist/type/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/ddlExpression.util.d.ts

@@ -4,7 +4,11 @@ import { type EntityIndexColumn, type EntityIndexMeta, type EntityMeta, type Ind
  * object reach the schema as one: a column read off the refs as its key, any other `raw` as it is.
  */
 export declare function normalizeIndexColumn(entry: IndexColumnInput): EntityIndexColumn;
-/** Every index an entity declares: each `@Field({ index })` as the one-column `@Index` it is, then its `@Index`es. */
+/**
+ * Every index an entity declares: each `@Field({ index })` or `@Field({ unique })` as the one-column
+ * `@Index` it is, then its `@Index`es. A unique column is a unique index, the one spelling of uniqueness
+ * every engine can add and drop.
+ */
 export declare function declaredIndexes<E>(meta: EntityMeta<E>): EntityIndexMeta<E>[];
 /** An index entry as the schema holds it, its expression rendered to text by `render`. */
 export declare function renderIndexColumn(entry: EntityIndexColumn, render: (sql: QueryRaw) => string): IndexColumnSchema;

package/dist/util/ddlExpression.util.js

@@ -9,9 +9,13 @@ export function normalizeIndexColumn(entry) {
     const { column, ...modifiers } = typeof entry === 'string' || entry instanceof QueryRaw ? { column: entry } : entry;
     return { ...modifiers, column: column instanceof ColumnRef ? column.key : column };
 }
-/** Every index an entity declares: each `@Field({ index })` as the one-column `@Index` it is, then its `@Index`es. */
+/**
+ * Every index an entity declares: each `@Field({ index })` or `@Field({ unique })` as the one-column
+ * `@Index` it is, then its `@Index`es. A unique column is a unique index, the one spelling of uniqueness
+ * every engine can add and drop.
+ */
 export function declaredIndexes(meta) {
-    const fieldIndexes = definedEntries(meta.fields).flatMap(([key, field]) => field.index
+    const fieldIndexes = definedEntries(meta.fields).flatMap(([key, field]) => field.index || field.unique
         ? [
             {
                 columns: [{ column: key }],

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;
         }