uql-orm 0.80.0 → 0.82.0

package/dist/dialect/abstractSqlDialect.js

@@ -1,12 +1,12 @@
 import { fieldOf, getMeta, relationOf, soleIdOf } from '../entity/index.js';
 import { COUNT_RESULT_KEY, parseQueryLock, QueryRaw, RAW_ALIAS, } from '../type/index.js';
 import { isInlinedExpression } from '../util/field.util.js';
-import { asSelectMap, assertNonNegativeInteger, escapeSqlId, fillOnFields, filterFieldKeys, getInsertFieldKeys, getKeys, getRelationRequestSummary, getSoftDeleteValue, hasKeys, idOnlyQuery, columnFamily, countedRelations, fieldUpdateOf, fulltextIndexOver, fulltextWeights, isFieldUpdateOp, isJsonObject, isJsonUpdateOp, isOperatorMap, isOperatorKey, isVectorSearch, normalizeScalarFieldSelection, parentJoins, rankedTextSearch, targetKeyColumns, textSearchFields, textSortOf, textWeightSteps, parseGroupMap, parseRelationAtKey, parseRelationSize, populatesRelations, aggregateOf, raw, refs, throwUnknownAggregateColumn, withoutSoftDeleteFilter, } from '../util/index.js';
+import { asSelectMap, assertNonNegativeInteger, assertWhere, definedEntries, escapeSqlId, fillOnFields, filterFieldKeys, getInsertFieldKeys, getKeys, getRelationRequestSummary, getSoftDeleteValue, hasKeys, idOnlyQuery, columnFamily, countedRelations, fieldUpdateOf, fulltextIndexOver, fulltextWeights, isFieldUpdateOp, isJsonObject, isJsonUpdateOp, isOperatorMap, isOperatorKey, isVectorSearch, normalizeScalarFieldSelection, parentJoins, rankedTextSearch, targetKeyColumns, textSearchFields, textSortOf, textWeightSteps, parseGroupMap, parseRelationAtKey, parseRelationSize, populatesRelations, aggregateOf, raw, refs, throwUnknownAggregateColumn, withoutSoftDeleteFilter, } from '../util/index.js';
 import { escapeAnsiSqlLiteral } from '../util/sqlLiteral.js';
 import { kindOf, UqlUsageError } from '../util/uqlError.js';
 import { AGGREGATE_PAGE_ALIAS, AGGREGATE_VALUE_ALIAS, ROWS_ALIAS, JSON_ELEM_ALIAS, JSON_PULL_ALIAS, relationSortColumn, } from './aliases.js';
 import { holdsOperator, isJsonScalar, jsonCompareMode, jsonElemExists, jsonPath, } from './jsonSql.js';
-import { betweenBounds, COMPARE_OPS, EQUALITY_OPS, GROUP_OPS, groupClauses, inOperands, isGroupOp, isOrderedOp, isVectorQuery, LIKE_OPS, ORDERED_OPS, VECTOR_QUERY_KEY_SET, whereOperators, } from './operators.js';
+import { betweenBounds, COMPARE_OPS, EQUALITY_OPS, GROUP_OPS, groupClauses, inOperands, isGroupOp, isOrderedOp, isVectorQuery, LIKE_OPS, namesRows, ORDERED_OPS, VECTOR_QUERY_KEY_SET, whereOperators, } from './operators.js';
 import { SqlQueryContext } from './queryContext.js';
 import { groupPathField, NO_JOINS, aggregateColumnField, resolveGroupJoins, resolveQueryJoins, relationSortTerms, resolveSortableJoin, } from './queryJoins.js';
 import { resolveVectorCast } from './vectorCast.js';
@@ -34,6 +34,13 @@ function orRefuse(value, refusal) {
     }
     return value;
 }
+/**
+ * Whether an assignment builds on what each row before it left: `$inc`, `$mul`, `$push`. A set-based
+ * `UPDATE` writes a target once however many rows of its set match it, so it would apply one of them.
+ */
+function accumulates(value) {
+    return isFieldUpdateOp(value) || (isJsonUpdateOp(value) && value.$push !== undefined);
+}
 /** Conditions joined by `AND`, parenthesized where there is more than one. */
 function conjunction(parts) {
     return parts.length > 1 ? `(${parts.join(' AND ')})` : parts.join('');
@@ -178,7 +185,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
     returningIdExpression(meta) {
         const [idKey] = meta.ids;
         return meta.ids.length === 1
-            ? `${this.returnedRowPrefix}${this.escapeId(this.columnOf(meta, idKey))} ${this.escapeId('id')}`
+            ? `${this.returnedRowPrefix}${this.escapedColumnName(meta, idKey)} ${this.escapeId('id')}`
             : '';
     }
     search(ctx, entity, q = {}, opts = {}, joins = NO_JOINS, order) {
@@ -423,7 +430,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
             join.relation.references.forEach((reference, index) => {
                 if (index > 0)
                     ctx.append(' AND ');
-                const foreign = this.escapeId(this.columnOf(join.meta, reference.foreign));
+                const foreign = this.escapedColumnName(join.meta, reference.foreign);
                 // Two calls rather than one over a union: the parent is either another join's entity or the
                 // queried one, and their metadata types have nothing in common.
                 const local = this.escapeId(join.parent ? this.columnOf(join.parent.meta, reference.local) : this.columnOf(meta, reference.local));
@@ -1254,30 +1261,99 @@ export class AbstractSqlDialect extends VectorSqlDialect {
         const meta = getMeta(entity);
         const [filledPayload] = fillOnFields(meta, payload, 'onUpdate');
         const keys = filterFieldKeys(meta, filledPayload, 'onUpdate');
-        const tableName = this.escapedTableName(meta);
-        ctx.append(`UPDATE ${tableName} SET `);
+        ctx.append(`UPDATE ${this.escapedTableName(meta)} SET `);
         for (let i = 0; i < keys.length; i++) {
             if (i > 0) {
                 ctx.append(', ');
             }
-            const key = keys[i];
-            const field = meta.fields[key];
-            const escapedCol = this.escapedColumnName(meta, key);
-            const value = filledPayload[key];
-            if (isJsonUpdateOp(value)) {
-                this.formatJsonUpdate(ctx, escapedCol, value, field);
-            }
-            else if (isFieldUpdateOp(value)) {
-                const [op, operand] = fieldUpdateOf(key, value);
-                ctx.append(`${escapedCol} = COALESCE(${escapedCol}, 0) ${SQL_ARITHMETIC[op]} `);
-                ctx.addValue(operand);
+            this.appendAssignment(ctx, meta, keys[i], filledPayload[keys[i]]);
+        }
+        this.search(ctx, entity, q, opts);
+    }
+    /** `col = value`, a JSON operator or a `$inc`/`$mul` spelled as the engine's. */
+    appendAssignment(ctx, meta, key, value) {
+        const field = meta.fields[key];
+        const escapedCol = this.escapedColumnName(meta, key);
+        if (isJsonUpdateOp(value)) {
+            this.formatJsonUpdate(ctx, escapedCol, value, field);
+        }
+        else if (isFieldUpdateOp(value)) {
+            const [op, operand] = fieldUpdateOf(key, value);
+            ctx.append(`${escapedCol} = COALESCE(${escapedCol}, 0) ${SQL_ARITHMETIC[op]} `);
+            ctx.addValue(operand);
+        }
+        else {
+            ctx.append(`${escapedCol} = `);
+            this.formatPersistableValue(ctx, field, value);
+        }
+    }
+    /**
+     * A write in a trigger's body. Only the columns it names, none filled in JavaScript - that would bake
+     * one value into the trigger - no id read back, and no entity filter, which a request resolves and a
+     * trigger has none of. `rows` is the `FROM` a set-based engine's body reads its rows through.
+     */
+    triggerWrite(ctx, write, rows) {
+        const meta = getMeta(write.entity);
+        const table = this.escapedTableName(meta);
+        if (write.kind === 'insert') {
+            const unfilled = definedEntries(meta.fields).find(([key, field]) => field.onInsert !== undefined && field.defaultValue === undefined && write.row[key] === undefined);
+            if (unfilled) {
+                throw new UqlUsageError(`'${meta.name}.${unfilled[0]}' is filled on insert by uql, which a trigger does not run: ` +
+                    'name it, or give it a defaultValue');
             }
-            else {
-                ctx.append(`${escapedCol} = `);
-                this.formatPersistableValue(ctx, field, value);
+            const entries = this.writtenEntries(meta, write.row);
+            const columns = entries.map(([key]) => this.escapedColumnName(meta, key)).join(', ');
+            const [open, close] = rows ? ['SELECT ', ` ${rows};`] : ['VALUES (', ');'];
+            ctx.append(`INSERT INTO ${table} (${columns}) ${open}`);
+            entries.forEach(([key, value], i) => {
+                if (i > 0) {
+                    ctx.append(', ');
+                }
+                this.formatPersistableValue(ctx, meta.fields[key], value);
+            });
+            ctx.append(close);
+            return;
+        }
+        assertWhere(meta, write.where);
+        if (!namesRows(write.where)) {
+            throw new UqlUsageError(`a trigger's ${write.kind} over '${meta.name}' names no rows, so it would address every one`);
+        }
+        if (write.kind === 'update') {
+            const entries = this.writtenEntries(meta, write.set);
+            const accumulating = rows && entries.find(([, value]) => accumulates(value));
+            if (accumulating) {
+                throw new UqlUsageError(`'${meta.name}.${accumulating[0]}' cannot accumulate per row in a trigger fired once per statement, ` +
+                    'which applies $inc, $mul and $push once');
             }
+            ctx.append(`UPDATE ${table} SET `);
+            entries.forEach(([key, value], i) => {
+                if (i > 0) {
+                    ctx.append(', ');
+                }
+                this.appendAssignment(ctx, meta, key, value);
+            });
         }
-        this.search(ctx, entity, q, opts);
+        else {
+            ctx.append(`DELETE FROM ${table}`);
+        }
+        if (rows) {
+            ctx.append(` ${rows}`);
+        }
+        // Qualified by the table: on a set-based engine `inserted` holds the same column names.
+        this.renderWhere(ctx, write.entity, write.where, { escapedPrefix: `${table}.` });
+        ctx.append(';');
+    }
+    /** The values a write names, refusing one the entity has no column for. */
+    writtenEntries(meta, values) {
+        const entries = Object.entries(values).filter(([, value]) => value !== undefined);
+        const unknown = entries.find(([key]) => !meta.fields[key]);
+        if (unknown) {
+            throw new UqlUsageError(`'${meta.name}' has no field '${unknown[0]}' for a trigger to write`);
+        }
+        if (!entries.length) {
+            throw new UqlUsageError(`a trigger's write to '${meta.name}' names no field`);
+        }
+        return entries;
     }
     /**
      * `INSERT ... ON CONFLICT ... DO UPDATE/NOTHING RETURNING`. The assignments are built before the insert
@@ -1312,23 +1388,18 @@ export class AbstractSqlDialect extends VectorSqlDialect {
         return fields
             .filter((col) => !conflictPaths[col])
             .map((col) => {
-            const field = meta.fields[col];
-            const columnName = this.resolveColumnName(col, field);
+            const column = this.escapedColumnName(meta, col);
             if (Object.hasOwn(sample, col)) {
-                return `${this.escapeId(columnName)} = ${callback(this.escapeId(columnName))}`;
+                return `${column} = ${callback(column)}`;
             }
-            const text = this.buildFragment(ctx, (fragmentCtx) => this.formatPersistableValue(fragmentCtx, field, filledPayload[col]));
-            return `${this.escapeId(columnName)} = ${text}`;
+            const text = this.buildFragment(ctx, (fragmentCtx) => this.formatPersistableValue(fragmentCtx, meta.fields[col], filledPayload[col]));
+            return `${column} = ${text}`;
         })
             .join(', ');
     }
     getUpsertConflictPathsStr(meta, conflictPaths) {
         return getKeys(conflictPaths)
-            .map((key) => {
-            const field = meta.fields[key];
-            const columnName = this.resolveColumnName(key, field);
-            return this.escapeId(columnName);
-        })
+            .map((key) => this.escapedColumnName(meta, key))
             .join(', ');
     }
     delete(ctx, entity, q, opts = {}) {
@@ -1337,10 +1408,8 @@ export class AbstractSqlDialect extends VectorSqlDialect {
         // Soft-delete (stamp only live rows) unless `hardDelete` is requested or the entity has no
         // soft-delete field (e.g. a cascade onto a non-soft-deletable child).
         if (!opts.hardDelete && meta.softDelete) {
-            const field = fieldOf(meta, meta.softDelete);
-            const columnName = this.resolveColumnName(meta.softDelete, field);
-            ctx.append(`UPDATE ${tableName} SET ${this.escapeId(columnName)} = `);
-            this.formatPersistableValue(ctx, field, getSoftDeleteValue(field));
+            ctx.append(`UPDATE ${tableName} SET `);
+            this.appendAssignment(ctx, meta, meta.softDelete, getSoftDeleteValue(fieldOf(meta, meta.softDelete)));
             this.search(ctx, entity, q, opts);
             return;
         }
@@ -1537,19 +1606,19 @@ export class AbstractSqlDialect extends VectorSqlDialect {
     jsonDiffers(elem, operand) {
         return `${elem} <> ${operand}`;
     }
-    compileDdl(sql, entity) {
+    compileDdl(sql, entity, { rows, escapedPrefix, operand } = {}) {
         const ctx = this.createContext({ inlineValues: true });
         if (sql instanceof QueryRaw) {
-            sql.render({ ctx, dialect: this, prefix: '', escapedPrefix: '', entity });
+            sql.render({ ctx, dialect: this, prefix: '', escapedPrefix: escapedPrefix ?? '', entity, rows });
         }
         else if (entity) {
-            this.renderWhere(ctx, entity, sql, { clause: false });
+            this.renderWhere(ctx, entity, sql, { clause: false, escapedPrefix, operand });
         }
         else {
-            throw new TypeError('a predicate compiles against the entity it is written for, and none was given');
+            throw new UqlUsageError('a predicate compiles against the entity it is written for, and none was given');
         }
         if (ctx.values.length) {
-            throw new TypeError(`DDL has no placeholder to bind a value into, and this SQL left one bound: ${ctx.sql}`);
+            throw new UqlUsageError(`DDL has no placeholder to bind a value into, and this SQL left one bound: ${ctx.sql}`);
         }
         return ctx.sql;
     }

package/dist/dialect/operators.d.ts

@@ -1,4 +1,4 @@
-import { type QueryGroupOp, type QueryOrderedOp, type QueryVectorQuery, type QueryWhereArray, type QueryWhereFieldOp } from '../type/index.js';
+import { type QueryGroupOp, type QueryOrderedOp, type QueryVectorQuery, type QueryWhere, type QueryWhereArray, type QueryWhereFieldOp } from '../type/index.js';
 /**
  * How each grouping operator renders: the operator joining its clauses, and whether the group is
  * negated (`$not` is `NOT (a AND b)`). Total over {@link QueryGroupOp}.
@@ -29,6 +29,12 @@ export declare function isGroupOp(key: string): key is QueryGroupOp;
  * refuse the same payload rather than one throwing and the other failing further in.
  */
 export declare function groupClauses<E>(key: QueryGroupOp, val: QueryWhereArray<E> | undefined): QueryWhereArray<E>;
+/**
+ * Whether a `$where` names any rows, as the WHERE it renders would: an `undefined` value, an empty
+ * operator map and a group none of whose clauses names one all render nothing, which a write reads as
+ * the whole table.
+ */
+export declare function namesRows<E>(where: QueryWhere<E> | undefined): boolean;
 /**
  * A WHERE value as the operators it applies: an array is `$in`, an operator map its own entries, and
  * anything else `$eq`. Each key is checked here, once, refused as `refusal` where it is no operator.

package/dist/dialect/operators.js

@@ -1,5 +1,6 @@
-import { VECTOR_QUERY_KEYS, } from '../type/index.js';
+import { QueryRaw, VECTOR_QUERY_KEYS, } from '../type/index.js';
 import { isOperatorMap } from '../util/dialect.util.js';
+import { hasKeys, isWhereMap, someKey } from '../util/object.util.js';
 import { kindOf, UqlUsageError } from '../util/uqlError.js';
 /**
  * How each grouping operator renders: the operator joining its clauses, and whether the group is
@@ -26,6 +27,17 @@ export function groupClauses(key, val) {
     }
     return val ?? [];
 }
+/**
+ * Whether a `$where` names any rows, as the WHERE it renders would: an `undefined` value, an empty
+ * operator map and a group none of whose clauses names one all render nothing, which a write reads as
+ * the whole table.
+ */
+export function namesRows(where) {
+    return (where !== undefined &&
+        someKey(where, (key) => isGroupOp(key)
+            ? groupClauses(key, where[key]).some((clause) => clause instanceof QueryRaw || namesRows(clause))
+            : where[key] !== undefined && !(isWhereMap(where[key]) && !hasKeys(where[key]))));
+}
 /**
  * A WHERE value as the operators it applies: an array is `$in`, an operator map its own entries, and
  * anything else `$eq`. Each key is checked here, once, refused as `refusal` where it is no operator.

package/dist/dialect/vectorSqlDialect.d.ts

@@ -30,6 +30,8 @@ export declare abstract class VectorSqlDialect extends AbstractDialect {
     readonly vectorMetrics: ReadonlyMap<VectorDistance, VectorMetric>;
     /** Whether this engine has a vector index: the one a metric's `index` names. */
     hasVectorIndex(): boolean;
+    /** The distance a vector index built for `metric`, as {@link vectorMetrics} names it for an index, measures. */
+    indexedDistance(metric: string | undefined): VectorDistance | undefined;
     /** Quotes an identifier; supplied by the SQL dialect built on top of this layer. */
     abstract escapeId(val: string | undefined, forbidQualified?: boolean, addDot?: boolean): string;
     /** What a distance expression reads, for a `$sort` and a `$near` alike. */

package/dist/dialect/vectorSqlDialect.js

@@ -45,6 +45,10 @@ export class VectorSqlDialect extends AbstractDialect {
     hasVectorIndex() {
         return [...this.vectorMetrics.values()].some((metric) => metric.index);
     }
+    /** The distance a vector index built for `metric`, as {@link vectorMetrics} names it for an index, measures. */
+    indexedDistance(metric) {
+        return [...this.vectorMetrics].find(([, { index }]) => index === metric)?.[0];
+    }
     /** What a distance expression reads, for a `$sort` and a `$near` alike. */
     resolveVectorDistance(meta, key, search) {
         const field = meta.fields[key];

package/dist/entity/metadata/definition.d.ts

@@ -45,7 +45,7 @@ export declare function fieldOf<E>(meta: EntityMeta<E>, key: string): FieldMeta;
 /** The relation `key` names, for a caller that took `key` from the metadata itself. */
 export declare function relationOf<E>(meta: EntityMeta<E>, key: RelationKey<E>): RelationMeta;
 /** A row of `E` as far as reading its key goes: a record or a write, whatever its values. */
-type KeyedRow<E> = {
+export type KeyedRow<E> = {
     readonly [K in keyof E]?: unknown;
 };
 /** Whether the row names every column of its primary key, `0` and `''` included. */
@@ -67,4 +67,3 @@ export declare function getMeta<E>(entity: Type<E>): EntityMeta<E>;
  * schema build constrains and a junction joins by, settling the relations holding them first.
  */
 export declare function foreignKeysOf<E>(meta: EntityMeta<E>): RelationMeta[];
-export {};

package/dist/entity/metadata/definition.js

@@ -1,6 +1,7 @@
 import { RelationAggregate, SOFT_DELETE_FILTER } from '../../type/index.js';
-import { isInlinedExpression } from '../../util/field.util.js';
-import { entitySql, entityWhere, fieldOptionConflict, getKeys, hasKeys, isToManyRelation, memberRefs, fulltextWeights, normalizeIndexColumn, definedEntries, } from '../../util/index.js';
+import { fieldKeys, isInlinedExpression } from '../../util/field.util.js';
+import { entitySql, entityWhere, fieldOptionConflict, hasKeys, isToManyRelation, memberRefs, fulltextWeights, normalizeIndexColumn, definedEntries, whereWith, } from '../../util/index.js';
+import { UqlUsageError } from '../../util/uqlError.js';
 import { ownRegistrations } from '../decorator/bag.js';
 /**
  * A map held on `globalThis` through the global symbol registry, so a single one survives multiple
@@ -22,18 +23,18 @@ export function defineField(entity, key, opts = {}) {
     // A relation aggregate reads as a correlated subquery, which no engine accepts in a generated column:
     // keeping one on the row takes the triggers a write fires, which are not built yet.
     if (opts.stored && sql instanceof RelationAggregate) {
-        throw new TypeError(`'${entity.name}.${key}' cannot be 'stored': a relation aggregate reads as a subquery, which no ` +
+        throw new UqlUsageError(`'${entity.name}.${key}' cannot be 'stored': a relation aggregate reads as a subquery, which no ` +
             "engine keeps in a generated column. Drop 'stored' to have it read on each query.");
     }
     // A stored computed column is a real column and still needs a type; only an inlined one is exempt,
     // its expression being spliced in rather than declared.
     if (!opts.type && !opts.references && !isInlinedExpression(opts)) {
-        throw new TypeError(`'${entity.name}.${key}' needs a 'type'. Declare it - '@Field({ type: String })' - or point the field ` +
+        throw new UqlUsageError(`'${entity.name}.${key}' needs a 'type'. Declare it - '@Field({ type: String })' - or point the field ` +
             "at another entity with 'references', which resolves the column type from its primary key.");
     }
     const conflict = fieldOptionConflict(opts);
     if (conflict) {
-        throw new TypeError(`'${entity.name}.${key}' ${conflict}.`);
+        throw new UqlUsageError(`'${entity.name}.${key}' ${conflict}.`);
     }
     const fieldKey = key;
     // Flagged when the author gave `references` but no `type`, so schema generation knows to resolve the
@@ -75,10 +76,10 @@ function keyMap() {
 const KEY_MAP = new Proxy({}, { get: (_, key) => key });
 function addRelation(entity, key, registration) {
     if (!registration.entity) {
-        throw new TypeError(`'${entity.name}.${key}' needs an 'entity' getter, e.g. '@ManyToOne({ entity: () => Company })'.`);
+        throw new UqlUsageError(`'${entity.name}.${key}' needs an 'entity' getter, e.g. '@ManyToOne({ entity: () => Company })'.`);
     }
     if (registration.through && registration.references) {
-        throw new TypeError(`'${entity.name}.${key}' joins through a junction, whose column referencing each side is the join; ` +
+        throw new UqlUsageError(`'${entity.name}.${key}' joins through a junction, whose column referencing each side is the join; ` +
             "'references' pairs the declaring entity's columns with the target's instead.");
     }
     const meta = ensureWritableMeta(entity);
@@ -120,10 +121,10 @@ export function defineTrigger(entity, trigger) {
     const meta = ensureWritableMeta(entity);
     // The type already refuses an empty map; this is the same answer for plain JavaScript.
     if (typeof trigger.run !== 'function' && !hasKeys(trigger.run)) {
-        throw new TypeError(`'${entity.name}' has a trigger whose body names at least one engine to run on`);
+        throw new UqlUsageError(`'${entity.name}' has a trigger whose body names at least one engine to run on`);
     }
     if (trigger.name && meta.triggers?.some((it) => it.name === trigger.name)) {
-        throw new TypeError(`'${entity.name}' already has a trigger named '${trigger.name}'`);
+        throw new UqlUsageError(`'${entity.name}' already has a trigger named '${trigger.name}'`);
     }
     (meta.triggers ??= []).push({ ...trigger, of: trigger.of?.(memberRefs()).map((ref) => ref.key) });
     return meta;
@@ -131,12 +132,12 @@ export function defineTrigger(entity, trigger) {
 export function defineFilter(entity, name, opts) {
     const meta = ensureWritableMeta(entity);
     if (name === SOFT_DELETE_FILTER) {
-        throw TypeError(`'${entity.name}' filter name '${SOFT_DELETE_FILTER}' is reserved; it is auto-registered from @Field({ softDelete })`);
+        throw new UqlUsageError(`'${entity.name}' filter name '${SOFT_DELETE_FILTER}' is reserved; it is auto-registered from @Field({ softDelete })`);
     }
     // Widened for a caller the types did not reach, which is the only one this can refuse.
     const { security, onMissing } = opts;
     if (security && onMissing === 'skip') {
-        throw TypeError(`'${entity.name}' security filter '${name}' cannot use onMissing: 'skip' (it must fail closed)`);
+        throw new UqlUsageError(`'${entity.name}' security filter '${name}' cannot use onMissing: 'skip' (it must fail closed)`);
     }
     (meta.filters ??= {})[name] = opts;
     return meta;
@@ -173,7 +174,7 @@ export function defineEntity(entity, opts = {}) {
     // statement builds and then fails at the database. `schema` is the way to say it.
     if (opts.name?.includes('.')) {
         const [schema, ...rest] = opts.name.split('.');
-        throw new TypeError(`'${entity.name}' has a dotted name '${opts.name}'. Name the schema separately as ` +
+        throw new UqlUsageError(`'${entity.name}' has a dotted name '${opts.name}'. Name the schema separately as ` +
             `{ schema: '${schema}', name: '${rest.join('.')}' }.`);
     }
     const meta = ensureWritableMeta(entity);
@@ -201,7 +202,7 @@ export function defineEntity(entity, opts = {}) {
         defineFilter(entity, name, filter);
     }
     if (!hasKeys(meta.fields)) {
-        throw TypeError(`'${entity.name}' must have fields`);
+        throw new UqlUsageError(`'${entity.name}' must have fields`);
     }
     // A later call composes onto the entity, so a name is only ever set, and `derivedName` records that
     // the class name stood in, which is what a naming strategy derives from.
@@ -221,21 +222,18 @@ export function defineEntity(entity, opts = {}) {
     // Derive soft-delete from the (inheritance-merged) fields, so own and inherited markers are handled
     // uniformly. Exactly one field may be marked; it auto-registers the built-in `softDelete` read
     // filter (a reserved name - see defineFilter - so it never clobbers a user filter).
-    const softDeleteKeys = getKeys(meta.fields).filter((key) => {
-        const softDelete = meta.fields[key]?.softDelete;
-        return softDelete !== undefined && softDelete !== false;
-    });
+    const softDeleteKeys = fieldKeys(meta, ({ softDelete }) => softDelete !== undefined && softDelete !== false);
     if (softDeleteKeys.length > 1) {
-        throw TypeError(`'${entity.name}' must have at most one field with 'softDelete'`);
+        throw new UqlUsageError(`'${entity.name}' must have at most one field with 'softDelete'`);
     }
     if (softDeleteKeys.length) {
         meta.softDelete = softDeleteKeys[0];
-        (meta.filters ??= {})[SOFT_DELETE_FILTER] = { where: { [meta.softDelete]: null }, default: true };
+        (meta.filters ??= {})[SOFT_DELETE_FILTER] = { where: whereWith(meta.softDelete, null), default: true };
     }
     // The optimistic lock, derived the same way and just as singular: one row has one version.
-    const versionKeys = getKeys(meta.fields).filter((key) => meta.fields[key]?.version);
+    const versionKeys = fieldKeys(meta, (field) => field.version);
     if (versionKeys.length > 1) {
-        throw TypeError(`'${entity.name}' must have at most one field with 'version'`);
+        throw new UqlUsageError(`'${entity.name}' must have at most one field with 'version'`);
     }
     if (versionKeys.length) {
         meta.version = versionKeys[0];
@@ -246,7 +244,7 @@ export function defineEntity(entity, opts = {}) {
     }
     const ids = getIdKeys(meta);
     if (!ids.length) {
-        throw TypeError(`'${entity.name}' must have at least one id field (use @Id, defineId, or defineEntity({ fields: { ..., isId: true } }))`);
+        throw new UqlUsageError(`'${entity.name}' must have at least one id field (use @Id, defineId, or defineEntity({ fields: { ..., isId: true } }))`);
     }
     meta.ids = ids;
     return meta;
@@ -262,7 +260,7 @@ export function assertSoleId(meta, what) {
     if (ids.length === 1) {
         return;
     }
-    throw new TypeError(ids.length
+    throw new UqlUsageError(ids.length
         ? `'${meta.entity.name}' has a composite primary key (${ids.join(', ')}), which ${what} does not support yet.`
         : // An entity registered with `@Field` but no `@Entity` never ran the check in `defineEntity`.
             `'${meta.entity.name}' has no primary key, which ${what} needs.`);
@@ -276,7 +274,7 @@ export function soleIdOf(meta, what) {
 export function fieldOf(meta, key) {
     const field = meta.fields[key];
     if (!field) {
-        throw new TypeError(`'${meta.entity.name}' has no field '${key}'`);
+        throw new UqlUsageError(`'${meta.entity.name}' has no field '${key}'`);
     }
     return field;
 }
@@ -284,7 +282,7 @@ export function fieldOf(meta, key) {
 export function relationOf(meta, key) {
     const relation = meta.relations[key];
     if (!relation) {
-        throw new TypeError(`'${meta.entity.name}' has no relation '${key}'`);
+        throw new UqlUsageError(`'${meta.entity.name}' has no relation '${key}'`);
     }
     return relation;
 }
@@ -342,7 +340,7 @@ export function getMeta(entity) {
 function registeredMeta(entity) {
     const meta = metas.get(entity);
     if (!meta) {
-        throw TypeError(`'${entity.name}' is not an entity`);
+        throw new UqlUsageError(`'${entity.name}' is not an entity`);
     }
     return meta;
 }
@@ -351,7 +349,7 @@ function fillRelations(meta) {
         const at = `'${meta.entity.name}.${relKey}'`;
         const references = settledReferences(at, meta, relKey, relation);
         if (!references.length) {
-            throw new TypeError(`${at} has no columns to join on.`);
+            throw new UqlUsageError(`${at} has no columns to join on.`);
         }
         if (!relation.through) {
             assertJoins(at, meta, relation, references);
@@ -371,7 +369,7 @@ function settledReferences(at, meta, relKey, relOpts) {
     if (typeof references === 'string') {
         const target = ensureMeta(relOpts.entity());
         if (mappedBy || isToManyRelation(relOpts) || target.ids.length > 1) {
-            throw new TypeError(`${at} names one column, '${references}', which only a to-one holding a foreign key to a one-column key ` +
+            throw new UqlUsageError(`${at} names one column, '${references}', which only a to-one holding a foreign key to a one-column key ` +
                 'can: pair the columns, [{ local, foreign }].');
         }
         relOpts.references = [{ local: references, foreign: soleIdOf(target, 'a foreign key') }];
@@ -383,7 +381,7 @@ function settledReferences(at, meta, relKey, relOpts) {
         return fillInverseSide(at, meta, relOpts, mappedBy);
     if (through)
         return fillThrough(at, meta, relOpts, through);
-    throw new TypeError(isToManyRelation(relOpts)
+    throw new UqlUsageError(isToManyRelation(relOpts)
         ? `${at} is a to-many relation with no way to join: it needs 'mappedBy' (the member on the other side), ` +
             "'through' (a junction entity), or 'references' (the columns)."
         : `${at} needs 'references', the foreign key column it joins by, or 'mappedBy', the member on the other ` +
@@ -407,7 +405,7 @@ function fillInverseSide(at, meta, relOpts, mappedBy) {
     const other = `'${relMeta.entity.name}.${mappedBy}'`;
     if (relMeta.fields[mappedBy]) {
         if (meta.ids.length > 1) {
-            throw new TypeError(`${at} is mapped by ${other}, one column, but the primary key of ` +
+            throw new UqlUsageError(`${at} is mapped by ${other}, one column, but the primary key of ` +
                 `'${meta.entity.name}' is composite (${meta.ids.join(', ')}). Map it by the relation on the other side ` +
                 'instead, which joins every column of the key.');
         }
@@ -417,14 +415,14 @@ function fillInverseSide(at, meta, relOpts, mappedBy) {
     }
     const owner = relMeta.relations[mappedBy];
     if (!owner) {
-        throw new TypeError(`${at} is mapped by '${mappedBy}', which is neither a field nor a relation of '${relMeta.entity.name}'.`);
+        throw new UqlUsageError(`${at} is mapped by '${mappedBy}', which is neither a field nor a relation of '${relMeta.entity.name}'.`);
     }
     if (owner.mappedBy) {
-        throw new TypeError(`${at} is mapped by ${other}, an inverse side too, so neither owns the foreign key.`);
+        throw new UqlUsageError(`${at} is mapped by ${other}, an inverse side too, so neither owns the foreign key.`);
     }
     const ownerTarget = owner.entity();
     if (!isA(meta.entity, ownerTarget)) {
-        throw new TypeError(`${at} is mapped by ${other}, a relation to '${ownerTarget.name}', not to '${meta.entity.name}'.`);
+        throw new UqlUsageError(`${at} is mapped by ${other}, a relation to '${ownerTarget.name}', not to '${meta.entity.name}'.`);
     }
     const ownerReferences = settledReferences(other, relMeta, mappedBy, owner);
     // Two different flips: a junction's pairs are the owner's group followed by ours, so the two groups
@@ -454,11 +452,11 @@ function assertJoins(at, meta, relOpts, pairs) {
             const column = `'${side.meta.entity.name}.${key}'`;
             const field = side.meta.fields[key];
             if (!field || isInlinedExpression(field)) {
-                throw new TypeError(`${at} joins ${column}, which is not a column: declare it with '@Field'.`);
+                throw new UqlUsageError(`${at} joins ${column}, which is not a column: declare it with '@Field'.`);
             }
             const referenced = side.holds && pairs.length === 1 ? field.references?.() : undefined;
             if (referenced && !isA(side.joins, referenced)) {
-                throw new TypeError(`${at} joins ${column}, a foreign key to '${referenced.name}', not to '${side.joins.name}'.`);
+                throw new UqlUsageError(`${at} joins ${column}, a foreign key to '${referenced.name}', not to '${side.joins.name}'.`);
             }
         }
     }
@@ -491,7 +489,7 @@ export function foreignKeysOf(meta) {
         if (!target.ids.length)
             return [];
         if (target.ids.length > 1) {
-            throw new TypeError(`'${meta.entity.name}.${key}' cannot reference '${target.entity.name}', whose primary key is composite ` +
+            throw new UqlUsageError(`'${meta.entity.name}.${key}' cannot reference '${target.entity.name}', whose primary key is composite ` +
                 `(${target.ids.join(', ')}): a column points at one. Declare a column per key and pair each with it ` +
                 `in a '@ManyToOne' to '${target.entity.name}'.`);
         }
@@ -509,11 +507,11 @@ function junctionReferences(at, junction, side) {
             const declare = side.ids.length > 1
                 ? `a column per key, paired in a '@ManyToOne' to '${side.entity.name}'`
                 : `'@Field({ references: () => ${side.entity.name} })'`;
-            throw new TypeError(`${at} joins through '${junction.entity.name}', which has no column referencing ${referenced}: declare ${declare}.`);
+            throw new UqlUsageError(`${at} joins through '${junction.entity.name}', which has no column referencing ${referenced}: declare ${declare}.`);
         }
         if (others.length) {
             const columns = [pair, ...others].map(({ local }) => `'${local}'`).join(' and ');
-            throw new TypeError(`${at} joins through '${junction.entity.name}', where ${columns} each reference ${referenced}: a junction ` +
+            throw new UqlUsageError(`${at} joins through '${junction.entity.name}', where ${columns} each reference ${referenced}: a junction ` +
                 'needs exactly one column per key of each side.');
         }
         return { local: pair.local, foreign: key };
@@ -521,7 +519,7 @@ function junctionReferences(at, junction, side) {
 }
 /** Every key the entity marks, in declaration order. More than one is a composite primary key. */
 function getIdKeys(meta) {
-    return getKeys(meta.fields).filter((key) => meta.fields[key]?.isId);
+    return fieldKeys(meta, (field) => field.isId);
 }
 /**
  * Merges `ancestor` and its ancestors into `meta`, nearest first, draining an undecorated base's

package/dist/http/handler.js

@@ -1,6 +1,7 @@
 import { withContext } from '../context/context.js';
 import { getEntities, getMeta, soleIdOf } from '../entity/index.js';
-import { whereIds } from '../util/dialect.util.js';
+import { whereIds, whereWith } from '../util/dialect.util.js';
+import { UqlUsageError } from '../util/uqlError.js';
 import { entityPath, matchRoute } from './contract.js';
 import { parseQueryParams } from './query.js';
 /** `Company (crm.Company)`: the class, and the table it maps, which is what tells two apart. */
@@ -16,14 +17,14 @@ export function createRequestHandler(opts) {
         entities = entities.filter((entity) => !exclude.includes(entity));
     }
     if (!entities.length) {
-        throw new TypeError('no entities for the uql middleware');
+        throw new UqlUsageError('no entities for the uql middleware');
     }
     // All of them at once, so fixing the first collision does not just reveal the next.
     const byPath = Map.groupBy(entities, pathOf);
     const collisions = [...byPath].filter(([, clashing]) => clashing.length > 1);
     if (collisions.length) {
         const lines = collisions.map(([path, clashing]) => `  /${path} <- ${clashing.map(tableOf).join(', ')}`);
-        throw new TypeError(`every entity below shares a route with another, so all but the first are unreachable:\n${lines.join('\n')}\n` +
+        throw new UqlUsageError(`every entity below shares a route with another, so all but the first are unreachable:\n${lines.join('\n')}\n` +
             "A route is the kebab-cased class name unless 'entityPath' says otherwise. Name them apart, " +
             "pass an 'entityPath', or pass only one of them in 'include'.");
     }
@@ -157,6 +158,6 @@ function ok(body) {
     return { status: 200, body };
 }
 function buildIdQuery(meta, id, query) {
-    query.$where = { ...query.$where, [soleIdOf(meta, 'the HTTP handler')]: id };
+    query.$where = whereWith(soleIdOf(meta, 'the HTTP handler'), id, query.$where);
     return query;
 }

package/dist/http/query.d.ts

@@ -3,7 +3,7 @@ import type { WireQuery } from '../type/index.js';
  * Parse raw query-string entries (with JSON-stringified values) into a UQL query object.
  * Symmetric counterpart of {@link stringifyQuery}. Only {@link ALLOWED_QUERY_KEYS} are honored.
  */
-export declare function parseQueryParams(params?: Record<string, unknown>): WireQuery<unknown>;
+export declare function parseQueryParams<E = unknown>(params?: Record<string, unknown>): WireQuery<E>;
 /**
  * Serialize a UQL query object into a percent-encoded query string where object values
  * are JSON-stringified. Symmetric counterpart of {@link parseQueryParams}.

package/dist/http/query.js

@@ -105,11 +105,11 @@ export function wireJson(value) {
             return held;
         }
         if (RAW_VALUE in held) {
-            throw new TypeError('raw SQL cannot travel over HTTP: what leaves the browser is JSON');
+            throw new UqlUsageError('raw SQL cannot travel over HTTP: what leaves the browser is JSON');
         }
         // A blob is a field value, so no type parameter reaches it: this is the only place it is caught.
         if (held instanceof ArrayBuffer || ArrayBuffer.isView(held)) {
-            throw new TypeError('binary cannot travel over HTTP: what leaves the browser is JSON');
+            throw new UqlUsageError('binary cannot travel over HTTP: what leaves the browser is JSON');
         }
         return held;
     });