uql-orm 0.80.0 → 0.82.0

package/dist/migrate/triggerSql.js

@@ -1,7 +1,8 @@
 import { stampEvents } from '../util/field.util.js';
 import { definedEntries } from '../util/object.util.js';
-import { raw, rowColumn, rowRefs } from '../util/raw.js';
+import { raw, refs, rowRefs } from '../util/raw.js';
 import { ownedName } from '../util/sql.util.js';
+import { UqlUsageError } from '../util/uqlError.js';
 /**
  * One trigger for `dialect`, named for its table and label and ending in a hash of its own SQL. That hash
  * is the whole of change detection: a trigger is in place exactly when its name is installed, and an
@@ -20,7 +21,7 @@ export function renderTrigger(dialect, meta, trigger, position) {
  */
 export function dropTrigger(dialect, meta, name) {
     const { scope, body } = dialect.features.triggers;
-    const table = dialect.escapeId(dialect.resolveTableName(meta));
+    const table = dialect.escapedTableName(meta);
     return [
         `DROP TRIGGER IF EXISTS ${triggerId(dialect, meta, name)}${scope === 'table' ? ` ON ${table}` : ''}`,
         ...(body === 'function' ? [`DROP FUNCTION IF EXISTS ${schemaObjectId(dialect, meta, name)}()`] : []),
@@ -45,17 +46,15 @@ function schemaObjectId(dialect, meta, name) {
  */
 function triggerStatements(dialect, meta, trigger, name) {
     const features = dialect.features.triggers;
-    // The event, read apart once: `beforeUpdate` is `BEFORE` and `UPDATE`, and everything else follows.
-    const before = trigger.on.startsWith('before');
-    const operation = trigger.on.slice(before ? 6 : 5).toUpperCase();
+    const [timing, operation] = EVENT_PARTS[trigger.on];
+    const before = timing === 'BEFORE';
     const body = triggerBody(dialect, meta, trigger, before);
     const id = triggerId(dialect, meta, name);
-    const table = dialect.escapeId(dialect.resolveTableName(meta));
-    const column = (key) => dialect.escapeId(dialect.columnOf(meta, key));
+    const table = dialect.escapedTableName(meta);
     const names = rowNames(dialect);
-    const rows = [rowRefs(names.$new), rowRefs(names.$old)];
-    const sql = dialect.compileDdl(body(...rows), meta.entity);
-    const guard = triggerGuard(dialect, meta, trigger, rows, names, column);
+    const rows = [rowRefs(meta.entity, names.$new), rowRefs(meta.entity, names.$old)];
+    const sql = dialect.compileDdl(body(...rows), meta.entity, { rows: rowsFrom(dialect, meta, operation) });
+    const guard = triggerGuard(dialect, meta, trigger, rows, names);
     const inBody = features.guards !== 'clause';
     const guarded = !guard || !inBody
         ? sql
@@ -66,14 +65,14 @@ function triggerStatements(dialect, meta, trigger, name) {
     // which rows are touched, so it runs even when the guard keeps the statements from running.
     const opened = features.preamble ? `${features.preamble}\n${guarded}` : guarded;
     const of = features.guards === 'clause' && operation === 'UPDATE' && trigger.of?.length
-        ? ` OF ${trigger.of.map(column).join(', ')}`
+        ? ` OF ${trigger.of.map((key) => dialect.escapedColumnName(meta, key)).join(', ')}`
         : '';
     const each = features.rows === 'set' ? '' : '\nFOR EACH ROW';
     const clause = guard && !inBody ? `\nWHEN (${guard})` : '';
-    const timing = `${before ? 'BEFORE' : 'AFTER'} ${operation}${of}`;
+    const when = `${timing} ${operation}${of}`;
     const header = features.layout === 'tableFirst'
-        ? `CREATE TRIGGER ${id}\nON ${table} ${timing}${each}${clause}\nAS`
-        : `CREATE TRIGGER ${id}\n${timing} ON ${table}${each}${clause}`;
+        ? `CREATE TRIGGER ${id}\nON ${table} ${when}${each}${clause}\nAS`
+        : `CREATE TRIGGER ${id}\n${when} ON ${table}${each}${clause}`;
     if (features.body !== 'function') {
         return [`${header}\nBEGIN\n${opened}\nEND`];
     }
@@ -83,6 +82,15 @@ function triggerStatements(dialect, meta, trigger, name) {
     const fn = schemaObjectId(dialect, meta, name);
     return [plpgsqlFunction(fn, `BEGIN\n${opened}\nRETURN ${returned};\nEND`), `${header}\nEXECUTE FUNCTION ${fn}()`];
 }
+/** Each event read apart: `beforeUpdate` is `BEFORE` and `UPDATE`. */
+const EVENT_PARTS = {
+    beforeInsert: ['BEFORE', 'INSERT'],
+    afterInsert: ['AFTER', 'INSERT'],
+    beforeUpdate: ['BEFORE', 'UPDATE'],
+    afterUpdate: ['AFTER', 'UPDATE'],
+    beforeDelete: ['BEFORE', 'DELETE'],
+    afterDelete: ['AFTER', 'DELETE'],
+};
 /**
  * The body for the engine in use, refusing first what the engine cannot render at all. One body serves
  * every engine; in a map, one written for the family serves its forks: CockroachDB runs Postgres's
@@ -91,25 +99,25 @@ function triggerStatements(dialect, meta, trigger, name) {
 function triggerBody(dialect, meta, trigger, before) {
     const features = dialect.features.triggers;
     if (before && !features.before) {
-        throw new TypeError(`${dialect.dialectName} has no BEFORE trigger, only AFTER and INSTEAD OF, so '${trigger.on}' cannot be ` +
+        throw new UqlUsageError(`${dialect.dialectName} has no BEFORE trigger, only AFTER and INSTEAD OF, so '${trigger.on}' cannot be ` +
             'rendered there. Use the matching after event, which sees the row already written.');
     }
     if (trigger.where && features.rows === 'set') {
-        throw new TypeError(`${dialect.dialectName} fires a trigger once per statement, over the rows it touched, so no condition ` +
+        throw new UqlUsageError(`${dialect.dialectName} fires a trigger once per statement, over the rows it touched, so no condition ` +
             `can read one row: '${meta.entity.name}' cannot state a trigger 'where' there. Guard inside the body ` +
             'instead, where `inserted` and `deleted` can be read as tables.');
     }
     const { run } = trigger;
     const body = typeof run === 'function' ? run : (run[dialect.dialectName] ?? run[dialect.dialectFamily]);
     if (!body) {
-        throw new TypeError(`'${meta.entity.name}' has a trigger with no body for ${dialect.dialectName}, the engine in use. ` +
+        throw new UqlUsageError(`'${meta.entity.name}' has a trigger with no body for ${dialect.dialectName}, the engine in use. ` +
             'Write one for it, or one body for every engine.');
     }
     return body;
 }
 /** The one condition both guards reduce to: any watched column that moved, and whatever `where` asks. */
-function triggerGuard(dialect, meta, trigger, rows, names, column) {
-    const moved = movedColumns(dialect, meta, trigger.of ?? [], names, column);
+function triggerGuard(dialect, meta, trigger, rows, names) {
+    const moved = movedColumns(dialect, meta, trigger.of ?? [], names);
     return [
         ...(moved ? [moved] : []),
         ...(trigger.where ? condition(dialect, meta, trigger.where, rows, names, Boolean(moved)) : []),
@@ -137,16 +145,10 @@ function condition(dialect, meta, where, rows, names, operand) {
         return [operand ? `(${sql})` : sql];
     }
     const predicates = definedEntries(where);
-    return predicates.map(([row, predicate]) => {
-        const ctx = dialect.createContext({ inlineValues: true });
-        const escapedPrefix = `${names[row]}.`;
-        dialect.where(ctx, meta.entity, predicate, {
-            clause: false,
-            operand: operand || predicates.length > 1,
-            escapedPrefix,
-        });
-        return ctx.sql;
-    });
+    return predicates.map(([row, predicate]) => dialect.compileDdl(predicate, meta.entity, {
+        escapedPrefix: `${names[row]}.`,
+        operand: operand || predicates.length > 1,
+    }));
 }
 /**
  * The triggers a stamp needs: one per event it names, each assigning the field's expression to its
@@ -157,8 +159,8 @@ export function stampTriggers(dialect, meta) {
     const features = dialect.features.triggers;
     // Restating the row has to wait for it to be there, so those engines stamp after the write.
     const after = !features.assignsRow;
-    const newName = rowNames(dialect).$new;
-    return definedEntries(meta.fields).flatMap(([key, field]) => {
+    const fields = meta.fields;
+    return definedEntries(fields).flatMap(([key, field]) => {
         const events = stampEvents(field);
         const { computed } = field;
         if (!events?.length || !computed) {
@@ -169,7 +171,7 @@ export function stampTriggers(dialect, meta) {
             // The event is part of the name: a stamp on both writes installs two triggers, and one identifier
             // between them would have the second replace the first rather than sit beside it.
             name: `${key}_${event}`,
-            run: () => stampBody(dialect, meta, key, computed, newName),
+            run: (newRow) => stampBody(dialect, meta, key, computed, newRow),
         }));
     });
 }
@@ -178,26 +180,25 @@ const STAMP_EVENTS = {
     before: { insert: 'beforeInsert', update: 'beforeUpdate' },
     after: { insert: 'afterInsert', update: 'afterUpdate' },
 };
-/** The one statement a stamp runs, in whichever of the two shapes the engine leaves open. */
-function stampBody(dialect, meta, key, value, newName) {
-    const features = dialect.features.triggers;
-    const read = (member) => rowColumn(newName, member);
-    if (features.assignsRow) {
-        const target = read(key);
-        return features.body === 'function' ? raw `${target} := ${value};` : raw `SET ${target} = ${value};`;
+/**
+ * The one statement a stamp runs, in whichever of the two shapes the engine leaves open: an assignment
+ * to the incoming row, or where it may not be written, the row restated after the write, as any write in
+ * a trigger's body is, keyed on its whole key and only where the stamp still differs: that `UPDATE` fires
+ * the trigger again, and with recursive triggers on it then finds nothing left to change.
+ */
+function stampBody(dialect, meta, key, value, newRow) {
+    const { entity } = meta;
+    if (dialect.features.triggers.assignsRow) {
+        const target = newRow[key];
+        return dialect.features.triggers.body === 'function' ? raw `${target} := ${value};` : raw `SET ${target} = ${value};`;
     }
-    const table = dialect.escapeId(dialect.resolveTableName(meta));
-    const column = dialect.escapeId(dialect.columnOf(meta, key));
-    const keyed = meta.ids
-        .map((id) => raw `${text(`${table}.${dialect.escapeId(dialect.columnOf(meta, id))}`)} = ${read(id)}`)
-        .reduce((all, part) => raw `${all} AND ${part}`);
-    // A set-based engine hands the rows as a table, which an `UPDATE` has to name in a `FROM` before its
-    // condition can read one: `inserted."id"` binds to nothing on its own.
-    const from = features.rows === 'set' ? ` FROM ${newName}` : '';
-    // Only where the stamp still differs: this `UPDATE` fires the trigger again, and with recursive triggers
-    // on, the restatement it runs then finds nothing left to change instead of recursing without end.
-    const differs = dialect.neExpr(`${table}.${column}`, dialect.compileDdl(value, meta.entity));
-    return raw `UPDATE ${text(table)} SET ${text(column)} = ${value}${text(from)} WHERE ${keyed} AND ${text(differs)};`;
+    const table = refs(entity);
+    const keyed = meta.ids.map((id) => raw `${table[id]} = ${newRow[id]}`);
+    // Read through the write's own qualifier, as `keyed` is: `inserted` holds the same column name.
+    const stamped = dialect.compileDdl(value, entity);
+    const differs = raw(({ ctx, escapedPrefix }) => ctx.append(dialect.neExpr(`${escapedPrefix}${dialect.escapedColumnName(meta, key)}`, stamped)));
+    const where = { $and: [...keyed, differs] };
+    return raw(({ ctx, rows }) => dialect.triggerWrite(ctx, { kind: 'update', entity, set: { [key]: value }, where }, rows));
 }
 /** A dollar quote the body does not contain, so no `$$` in it - a literal, a comment - ends the function early. */
 function dollarQuote(body) {
@@ -207,23 +208,38 @@ function dollarQuote(body) {
     }
     return tag;
 }
-/** SQL already written out, for the identifiers a statement splices rather than binds. */
-function text(sql) {
-    return raw((opts) => opts.ctx.append(sql));
-}
 /**
  * Whether any watched column moved, null-safely, or `undefined` where none is watched: the two records
  * compared on a row-based engine, and on a set-based one the same question over a join of its two tables.
  */
-function movedColumns(dialect, meta, of, { $new: newName, $old: oldName }, column) {
+function movedColumns(dialect, meta, of, { $new: newName, $old: oldName }) {
     if (!of.length) {
         return undefined;
     }
-    const differs = of.map((key) => dialect.neExpr(`${oldName}.${column(key)}`, `${newName}.${column(key)}`));
+    const differs = of.map((key) => {
+        const column = dialect.escapedColumnName(meta, key);
+        return dialect.neExpr(`${oldName}.${column}`, `${newName}.${column}`);
+    });
     const moved = differs.length > 1 ? `(${differs.join(' OR ')})` : differs.join('');
-    if (dialect.features.triggers.rows === 'row') {
-        return moved;
+    const source = rowsFrom(dialect, meta, 'UPDATE');
+    return source ? `EXISTS (SELECT 1 ${source} WHERE ${moved})` : moved;
+}
+/**
+ * Where a set-based engine's body reads the rows it fires for, as the `FROM` a statement names them in:
+ * `inserted` on an insert, `deleted` on a delete, and on an update both, joined on the whole key. None on a
+ * row-based engine, whose body reads `NEW` and `OLD` bare.
+ */
+function rowsFrom(dialect, meta, operation) {
+    if (dialect.features.triggers.rows !== 'set') {
+        return undefined;
+    }
+    const { $new, $old } = rowNames(dialect);
+    if (operation !== 'UPDATE') {
+        return `FROM ${operation === 'INSERT' ? $new : $old}`;
     }
-    const keyed = meta.ids.map((id) => `${newName}.${column(id)} = ${oldName}.${column(id)}`).join(' AND ');
-    return `EXISTS (SELECT 1 FROM ${newName} JOIN ${oldName} ON ${keyed} WHERE ${moved})`;
+    const keyed = meta.ids.map((id) => {
+        const column = dialect.escapedColumnName(meta, id);
+        return `${$new}.${column} = ${$old}.${column}`;
+    });
+    return `FROM ${$new} JOIN ${$old} ON ${keyed.join(' AND ')}`;
 }

package/dist/mongo/mongoDialect.d.ts

@@ -90,9 +90,7 @@ export declare class MongoDialect extends AbstractDialect {
      * apply to JSON paths.
      */
     private assertKnownPathRoot;
-    /**
-     * Transform UQL operators to MongoDB operators.
-     */
+    /** Transform UQL operators to MongoDB operators, refusing as `refusal` a key that is none. */
     private transformOperators;
     /**
      * What a value holding `value` matches, as the SQL engines read it: an operator map tests it, an array

package/dist/mongo/mongoDialect.js

@@ -1,7 +1,7 @@
 import { ObjectId } from 'mongodb';
 import { AbstractDialect } from '../dialect/abstractDialect.js';
 import { AGGREGATE_VALUE_ALIAS, REL_NESTED_KEY, REL_TEMP_PREFIX, SUM_COUNT_ALIAS, nullsSortField, sortAggregateField, TEXT_SCORE_ALIAS, } from '../dialect/aliases.js';
-import { GROUP_OPS, groupClauses, isGroupOp } from '../dialect/operators.js';
+import { betweenBounds, GROUP_OPS, groupClauses, isGroupOp, whereOperators } from '../dialect/operators.js';
 import { aggregateColumnField, groupPathField, resolveGroupJoins, relationSortTerms, resolveQueryJoins, resolveSortableJoin, } from '../dialect/queryJoins.js';
 import { assertSoleId, fieldOf, getMeta, relationOf, soleIdOf } from '../entity/index.js';
 import { COUNT_RESULT_KEY } from '../type/query.js';
@@ -334,12 +334,10 @@ export class MongoDialect extends AbstractDialect {
         }
         throw new UqlUsageError(`path ${key} does not exist in ${entityName(meta)}`);
     }
-    /**
-     * Transform UQL operators to MongoDB operators.
-     */
-    transformOperators(ops) {
+    /** Transform UQL operators to MongoDB operators, refusing as `refusal` a key that is none. */
+    transformOperators(ops, refusal = 'unknown operator') {
         const result = {};
-        for (const [op, val] of Object.entries(ops)) {
+        for (const [op, val] of whereOperators(ops, refusal)) {
             // `$elemMatch`'s value is itself a condition, so the operators inside it need the same
             // mapping - passing it through raw sends UQL-only operators (`$startsWith`, `$between`, ...)
             // straight to the server, which rejects them as unknown.
@@ -349,7 +347,7 @@ export class MongoDialect extends AbstractDialect {
             }
             // `$not` wraps a condition too, so a uql-only operator inside it (`$isNull`, `$startsWith`) is mapped.
             if (op === '$not' && isOperatorObject(val)) {
-                result[op] = this.transformOperators(val);
+                result[op] = this.transformOperators(val, refusal);
                 continue;
             }
             // An object or an array is matched by what it holds, as the SQL engines read it, where native `$all`
@@ -374,7 +372,7 @@ export class MongoDialect extends AbstractDialect {
             // Structural transforms
             switch (op) {
                 case '$between': {
-                    const [min, max] = val;
+                    const [min, max] = betweenBounds(val);
                     result['$gte'] = min;
                     result['$lte'] = max;
                     break;
@@ -390,9 +388,6 @@ export class MongoDialect extends AbstractDialect {
                     // reads: converting a distance would mean guessing the metric, so this refuses.
                     throw new UqlUsageError('$near is not supported on MongoDB: Atlas scores by index-defined similarity, not distance. ' +
                         "Project the score with $sort's $project and filter on it instead.");
-                default:
-                    result[op] = val;
-                    break;
             }
         }
         return result;
@@ -1072,7 +1067,7 @@ export class MongoDialect extends AbstractDialect {
         if (columnFamily(field.type) === 'string') {
             return;
         }
-        throw new TypeError(`'${entityName(meta)}.${meta.ids[0]}' is declared '${declaredTypeName(field.type)}' and left to the ` +
+        throw new UqlUsageError(`'${entityName(meta)}.${meta.ids[0]}' is declared '${declaredTypeName(field.type)}' and left to the ` +
             'database, which MongoDB cannot do: the only key it generates is an ObjectId, read back as a string. ' +
             "Declare the key as a string, or give it an 'onInsert' generator.");
     }
@@ -1282,7 +1277,7 @@ export class MongoDialect extends AbstractDialect {
             // on identical input. Keeping only numbers and objects dropped a string or boolean without a
             // word, handing back every group instead of the filtered ones.
             if (isOperatorMap(condition)) {
-                filter[alias] = this.transformOperators(condition);
+                filter[alias] = this.transformOperators(condition, 'unsupported HAVING operator');
             }
             else {
                 filter[alias] = Array.isArray(condition) ? { $in: condition } : condition;
@@ -1368,6 +1363,6 @@ function sortNulls(value) {
 function assertReadable(meta, key) {
     const field = meta.fields[key];
     if (field?.computed && !aggregateOf(field)) {
-        throw new TypeError(`cannot read '${meta.entity.name}.${key}' on MongoDB: a 'computed' field writing SQL is not something a document engine evaluates`);
+        throw new UqlUsageError(`cannot read '${meta.entity.name}.${key}' on MongoDB: a 'computed' field writing SQL is not something a document engine evaluates`);
     }
 }

package/dist/mongo/mongodbQuerier.js

@@ -2,7 +2,7 @@ import { AGGREGATE_VALUE_ALIAS } from '../dialect/aliases.js';
 import { hasRequiredJoin } from '../dialect/queryJoins.js';
 import { fieldOf, getMeta, namesKey, soleIdOf } from '../entity/index.js';
 import { AbstractQuerier, enrichError } from '../querier/index.js';
-import { clone, getKeys, getSoftDeleteValue, hasKeys, hasTriggers, populatesRelations, textSortOf, throwNoPendingTransaction, throwPendingTransaction, vectorCandidates, withoutSoftDeleteFilter, } from '../util/index.js';
+import { clone, getKeys, getSoftDeleteValue, hasKeys, hasTriggers, populatesRelations, textSortOf, throwNoPendingTransaction, throwPendingTransaction, vectorCandidates, withoutSoftDeleteFilter, whereEach, } from '../util/index.js';
 import { UqlUsageError } from '../util/uqlError.js';
 /**
  * `$limit: 0` asks for no rows, the way it does on every SQL dialect - but MongoDB reads `limit(0)`
@@ -223,11 +223,7 @@ export class MongodbQuerier extends AbstractQuerier {
         return update;
     }
     buildConflictFilter(entity, conflictPaths, item) {
-        const where = getKeys(conflictPaths).reduce((acc, key) => {
-            acc[key] = item[key];
-            return acc;
-        }, {});
-        return this.dialect.where(entity, where);
+        return this.dialect.where(entity, whereEach(getKeys(conflictPaths), (key) => item[key]));
     }
     async internalUpsertOne(entity, conflictPaths, payload) {
         refuseTriggers(entity);
@@ -314,7 +310,7 @@ export class MongodbQuerier extends AbstractQuerier {
     /** Every read and write goes through here, which makes it where a released querier is caught. */
     collection(entity) {
         if (this.released) {
-            throw new TypeError('querier already released');
+            throw new UqlUsageError('querier already released');
         }
         const { name } = getMeta(entity);
         return this.db.collection(name);

package/dist/querier/abstractQuerier.d.ts

@@ -87,7 +87,7 @@ export declare abstract class AbstractQuerier implements Querier {
      * The `onInsert` values are filled here, before the write, so the after hooks and the ids read the
      * same rows the statement wrote.
      */
-    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)[]>;
     /** Writes `rows`, and onto each one the key the database generated for it, where it can tell. */
     protected abstract internalInsertMany<E extends object>(entity: Type<E>, rows: EntityData<E>[]): Promise<void>;
     updateOneById<E extends object>(entity: Type<E>, id: EntityId<E>, payload: UpdateWrite<E>, opts?: QueryOptions): Promise<number>;
@@ -118,9 +118,14 @@ export declare abstract class AbstractQuerier implements Querier {
     protected abstract internalUpdateMany<E extends object>(entity: Type<E>, q: QuerySearch<E>, payload: UpdatePayload<E>, opts?: QueryOptions): Promise<number>;
     restoreOneById<E extends object>(entity: Type<E>, id: EntityId<E>): Promise<number>;
     restoreMany<E extends object>(entity: Type<E>, q: QuerySearch<E>): Promise<number>;
+    /**
+     * An update the library writes of its own, hooked as a caller's is but carrying no version: a restore's
+     * cleared stamp, or a row pointed at the relation just inserted for it.
+     */
+    private unversionedUpdate;
     /** Fires `beforeUpsert`/`afterUpsert`: which branch a row takes is the database's to decide, so neither the insert's nor the update's pair fits. */
     upsertOne<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityWrite<E>): Promise<QueryUpsertOneResult<E>>;
-    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>>;
     protected abstract internalUpsertOne<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityData<E>): Promise<QueryUpdateResult>;
     protected abstract internalUpsertMany<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityData<E>[]): Promise<QueryUpdateResult>;
     deleteOneById<E extends object>(entity: Type<E>, id: EntityId<E>, opts?: QueryOptions): Promise<number>;
@@ -137,7 +142,7 @@ export declare abstract class AbstractQuerier implements Querier {
      * upserts on that key, so a stale id is written rather than silently missed, and an unnamed one
      * inserts. A composite is always named. The hooks follow the statement: a named row fires the upsert pair.
      */
-    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)[]>;
     /** Writes each inserted row's relations, one set of statements per relation whatever the number of rows. */
     protected insertRelations<E extends object>(entity: Type<E>, rows: E[]): Promise<void>;
     /** `EntityId` because a settled composite row is an object, which {@link childrenOf} reads each foreign key column out of. */
@@ -182,7 +187,7 @@ export declare abstract class AbstractQuerier implements Querier {
     /** Runs `task` after everything already queued, one at a time. Not re-entrant: never nest `serialize` calls. */
     protected serialize<T>(task: () => Promise<T>): Promise<T>;
     /** Runs `task`, logs `query` with its duration, and tags a failure with it: a method, since a decorator would lose the generics. */
-    protected timed<T>(query: string, values: unknown[] | undefined, task: () => Promise<T>): Promise<T>;
+    protected timed<T>(query: string, values: readonly unknown[] | undefined, task: () => Promise<T>): Promise<T>;
     abstract beginTransaction(opts?: TransactionOptions): Promise<void>;
     /** Strict: this is the check that catches a forgotten `beginTransaction`. */
     abstract commitTransaction(): Promise<void>;

package/dist/querier/abstractQuerier.js

@@ -1,6 +1,7 @@
 import { assertSoleId, getMeta, idOf, namesKey, relationOf } from '../entity/index.js';
+import { namesRows } from '../dialect/operators.js';
 import { parseQueryLock } from '../type/index.js';
-import { cascadesOnDelete, childrenOf, clone, entityName, fillOnFields, filterFieldKeys, filterPersistableRelationKeys, forEachRequestedRelation, getKeys, getRelationRequestSummary, idOnlyQuery, isPagedQuery, hasKeys, isScalarId, LoggerWrapper, parentJoins, queryLoggerFor, parseRelationAtKey, parseRelationQueryValue, rowKey, runHooks, someKey, targetKeyColumns, whereIds, withoutSoftDeleteFilter, } from '../util/index.js';
+import { cascadesOnDelete, childrenOf, clone, entityName, fillOnFields, filterFieldKeys, filterPersistableRelationKeys, forEachRequestedRelation, getKeys, getRelationRequestSummary, idOnlyQuery, keySet, isPagedQuery, isScalarId, LoggerWrapper, parentJoins, queryLoggerFor, parseRelationAtKey, parseRelationQueryValue, rowKey, runHooks, someKey, targetKeyColumns, whereAnyOf, whereEach, whereIds, whereWith, withoutSoftDeleteFilter, } from '../util/index.js';
 import { UqlOptimisticLockError, UqlUsageError } from '../util/uqlError.js';
 import { enrichError } from './queryError.js';
 /**
@@ -35,7 +36,7 @@ function soleParentColumn(relOpts) {
  * every table look narrowed, which is the case this exists to catch.
  */
 function assertNamesRows(entity, method, q, opts) {
-    if (opts?.unfiltered || hasKeys(q?.$where) || q?.$limit !== undefined) {
+    if (opts?.unfiltered || namesRows(q?.$where) || q?.$limit !== undefined) {
         return;
     }
     throw new UqlUsageError(`'${method}' over '${entity.name}' names no rows, so it would address every one: pass '{ unfiltered: true }' to mean it`);
@@ -53,7 +54,7 @@ function lockVersion(meta, key, q, row) {
     const next = typeof expected === 'bigint' ? expected + 1n : expected + 1;
     // Spread, as every other added predicate here is: one flat `AND`, and a caller already filtering on
     // the version contradicts itself into matching nothing, which is what they asked for.
-    return { expected, next, q: { ...q, $where: { ...q.$where, [key]: expected } } };
+    return { expected, next, q: { ...q, $where: whereWith(key, expected, q.$where) } };
 }
 /**
  * Refuses a write that cannot carry the lock, rather than writing over whatever the row holds now.
@@ -72,8 +73,8 @@ function assertUnversioned(meta, what) {
  * an `UPDATE` - reads the ids and writes them separately, putting the race back in the gap between.
  */
 function assertLockableUpdate(meta, q, settles) {
-    const where = q.$where;
-    const namesOneRow = meta.ids.every((key) => where?.[key] !== undefined && isScalarId(where[key]));
+    const where = { ...q.$where };
+    const namesOneRow = meta.ids.every((key) => where[key] !== undefined && isScalarId(where[key]));
     if (!namesOneRow || settles) {
         throw new UqlUsageError(`cannot update '${entityName(meta)}' this way: a versioned row is matched and written in one statement, so it is named by its ${meta.ids.map((id) => `'${id}'`).join(', ')}, takes no '$sort', '$limit' or '$skip', writes no relation, and filters by none`);
     }
@@ -290,9 +291,7 @@ export class AbstractQuerier {
      */
     async throwStaleVersion(entity, key, q, expected, opts) {
         const meta = getMeta(entity);
-        const where = q.$where;
-        const byId = Object.fromEntries(meta.ids.map((id) => [id, where[id]]));
-        const row = await this.findOne(entity, { $select: { [key]: true }, $where: byId }, opts);
+        const row = await this.findOne(entity, { $select: keySet([key]), $where: whereIds(meta, idOf(meta, { ...q.$where })) }, opts);
         const actual = row?.[key];
         const message = actual === undefined
             ? `no row of '${entityName(meta)}' has that id any more: it is gone`
@@ -329,10 +328,17 @@ export class AbstractQuerier {
         if (!meta.softDelete) {
             throw new UqlUsageError(`'${entity.name}' has not enabled 'softDelete'`);
         }
-        const $where = { ...q.$where, [meta.softDelete]: { $ne: null } };
+        const $where = whereWith(meta.softDelete, { $ne: null }, q.$where);
         // No version: a restore only undoes the stamp a delete left, which takes none either, and two of
         // them racing agree on the result anyway. A lock is for content, and a restore writes none.
-        return this.hooked(entity, 'Update', [{ [meta.softDelete]: null }], ([row]) => this.updateRows(entity, { ...q, $where }, row, { filters: { softDelete: false } }, undefined));
+        return this.unversionedUpdate(entity, { ...q, $where }, { [meta.softDelete]: null }, { filters: { softDelete: false } });
+    }
+    /**
+     * An update the library writes of its own, hooked as a caller's is but carrying no version: a restore's
+     * cleared stamp, or a row pointed at the relation just inserted for it.
+     */
+    unversionedUpdate(entity, q, payload, opts) {
+        return this.hooked(entity, 'Update', [payload], ([row]) => this.updateRows(entity, q, row, opts, undefined));
     }
     /** Fires `beforeUpsert`/`afterUpsert`: which branch a row takes is the database's to decide, so neither the insert's nor the update's pair fits. */
     async upsertOne(entity, conflictPaths, payload) {
@@ -426,7 +432,7 @@ export class AbstractQuerier {
                 }
             }
             if (toUpsert.length) {
-                const conflictPaths = Object.fromEntries(meta.ids.map((key) => [key, true]));
+                const conflictPaths = keySet(meta.ids);
                 const { ids: upserted } = await this.upsertMany(entity, conflictPaths, toUpsert.map((index) => payload[index]));
                 for (let position = 0; position < toUpsert.length; position++) {
                     ids[toUpsert[position]] = upserted[position];
@@ -492,7 +498,7 @@ export class AbstractQuerier {
         const savedIds = await this.saveMany(relEntity, children.map(({ row }) => row));
         // A link needs the target's id, which a MySQL batch mixing supplied and generated keys cannot report.
         if (savedIds.includes(undefined)) {
-            throw new TypeError(`'${relEntity.name}' rows saved through '${holder.name}' reported no id, so they cannot be linked. ` +
+            throw new UqlUsageError(`'${relEntity.name}' rows saved through '${holder.name}' reported no id, so they cannot be linked. ` +
                 'Insert them with their own ids, or save the relation in its own statement.');
         }
         const [targetColumn] = targetKeyColumns(relOpts, 1);
@@ -506,7 +512,8 @@ export class AbstractQuerier {
         const pointing = writes.filter(({ value }) => value);
         const referenceIds = await this.insertMany(relEntity, pointing.map(({ value }) => value));
         for (const [index, { id }] of pointing.entries()) {
-            await this.updateOneById(entity, id, { [localColumn]: referenceIds[index] });
+            assertIdValue(entity, id);
+            await this.unversionedUpdate(entity, { $where: whereIds(getMeta(entity), id) }, { [localColumn]: referenceIds[index] });
         }
     }
     /**
@@ -573,8 +580,8 @@ export class AbstractQuerier {
         const [idKey] = meta.ids;
         const keys = getKeys(conflictPaths);
         const q = {
-            $select: Object.fromEntries([idKey, ...keys].map((key) => [key, true])),
-            $where: { $or: rows.map((row) => Object.fromEntries(keys.map((key) => [key, row[key]]))) },
+            $select: keySet([idKey, ...keys]),
+            $where: whereAnyOf(rows.map((row) => whereEach(keys, (key) => row[key]))),
         };
         const found = await this.internalFindMany(entity, q, { filters: withoutSoftDeleteFilter(undefined) });
         const byConflict = new Map();
@@ -590,12 +597,12 @@ export class AbstractQuerier {
      * the write filled in - a generated key, an `onInsert` value - without it landing on the caller's.
      */
     async hooked(entity, event, payloads, write) {
-        // The one place a caller's write becomes the row the rest of the library handles. They are the
-        // same object: a write is the entity's data without the keys the database fills, which
-        // TypeScript cannot relate across an entity it has not resolved.
+        // The one place a write becomes the row the rest of the library handles. They are the same object:
+        // a write is the entity's data without the keys the database fills, which TypeScript cannot relate
+        // across an entity it has not resolved.
         const asRows = payloads;
         await this.emitHook(entity, `before${event}`, asRows);
-        const rows = clone(asRows);
+        const rows = asRows.map((row) => clone(row));
         const result = await write(rows);
         await this.emitHook(entity, `after${event}`, rows);
         return result;

package/dist/querier/abstractQuerierPool.d.ts

@@ -38,13 +38,13 @@ export declare abstract class AbstractQuerierPool<Q extends Querier, D extends A
     aggregate<E extends object, const G extends QueryGroupMap<E>, const A extends QueryAggMap<E>>(entity: Type<E>, q: QueryAggregate<E, G, A>, opts?: QueryOptions): Promise<QueryAggregateResult<E, G, A>[]>;
     estimatedCount<E extends object>(entity: Type<E>): Promise<number>;
     insertOne<E extends object>(entity: Type<E>, payload: EntityWrite<E>): Promise<WrittenId<E> | undefined>;
-    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)[]>;
     updateOneById<E extends object>(entity: Type<E>, id: EntityId<E>, payload: UpdateWrite<E>, opts?: QueryOptions): Promise<number>;
     updateMany<E extends object>(entity: Type<E>, q: QuerySearch<E>, payload: UpdateWrite<E>, opts?: QueryOptions): Promise<number>;
     upsertOne<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityWrite<E>): Promise<QueryUpsertOneResult<E>>;
-    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>>;
     saveOne<E extends object>(entity: Type<E>, payload: EntityWrite<E>): Promise<WrittenId<E> | undefined>;
-    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)[]>;
     deleteOneById<E extends object>(entity: Type<E>, id: EntityId<E>, opts?: QueryOptions): Promise<number>;
     deleteMany<E extends object>(entity: Type<E>, q: QuerySearch<E>, opts?: QueryOptions): Promise<number>;
     restoreOneById<E extends object>(entity: Type<E>, id: EntityId<E>): Promise<number>;

package/dist/querier/abstractSqlQuerier.d.ts

@@ -32,8 +32,8 @@ export declare abstract class AbstractSqlQuerier extends AbstractQuerier impleme
      * caught for every SQL backend.
      */
     protected lazyConnect(): Promise<void>;
-    all<T>(query: string, values?: unknown[]): Promise<T[]>;
-    run(query: string, values?: unknown[]): Promise<QueryUpdateResult>;
+    all<T>(query: string, values?: readonly unknown[]): Promise<T[]>;
+    run(query: string, values?: readonly unknown[]): Promise<QueryUpdateResult>;
     /** The rows of a statement the dialect builds. */
     private query;
     /** Runs a statement the dialect builds. */

package/dist/querier/abstractSqlQuerier.js

@@ -91,7 +91,7 @@ export class AbstractSqlQuerier extends AbstractQuerier {
      */
     async lazyConnect() {
         if (this.released) {
-            throw new TypeError('querier already released');
+            throw new UqlUsageError('querier already released');
         }
     }
     async all(query, values) {

package/dist/querier/abstractSqlQuerierPool.d.ts

@@ -6,6 +6,6 @@ import { AbstractQuerierPool } from './abstractQuerierPool.js';
  * the connection-per-call semantics.
  */
 export declare abstract class AbstractSqlQuerierPool<Q extends SqlQuerier, D extends AbstractSqlDialect> extends AbstractQuerierPool<Q, D> implements SqlQuerierPool<Q, D> {
-    all<T>(query: string, values?: unknown[]): Promise<T[]>;
-    run(query: string, values?: unknown[]): Promise<QueryUpdateResult>;
+    all<T>(query: string, values?: readonly unknown[]): Promise<T[]>;
+    run(query: string, values?: readonly unknown[]): Promise<QueryUpdateResult>;
 }

package/dist/querier/queryError.d.ts

@@ -6,7 +6,7 @@ import { type QueryErrorKind } from '../util/uqlError.js';
  */
 export interface QueryError extends Error {
     query?: string;
-    values?: unknown[];
+    values?: readonly unknown[];
 }
 /**
  * Names what `err` ran into on any engine, or `undefined` for anything else. Pure: the error is only
@@ -18,4 +18,4 @@ export declare function queryErrorKind(err: unknown): QueryErrorKind | undefined
  * control flow it is. `values` are attached only when `logger?.willLogValues()`: they already surface
  * in the logs then, so this opens no new leak.
  */
-export declare function enrichError(err: unknown, logger: LoggerWrapper | undefined, query: string, values?: unknown[]): unknown;
+export declare function enrichError(err: unknown, logger: LoggerWrapper | undefined, query: string, values?: readonly unknown[]): unknown;