uql-orm 0.81.0 → 0.83.0

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)`
@@ -13,12 +13,13 @@ function asksForNoRows(q) {
     return q.$limit === 0;
 }
 /**
- * MongoDB has no triggers, so a write to an entity declaring one - a stamp included - would skip it
- * silently. Refused instead, as a query naming SQL is.
+ * MongoDB runs no trigger within a write (Atlas Database Triggers fire after the commit), so a write to
+ * an entity declaring one - a stamp included - would skip it silently. Refused instead, as a query naming
+ * SQL is. The why, in `architecture/triggers.md`.
  */
 function refuseTriggers(entity) {
     if (hasTriggers(getMeta(entity))) {
-        throw new UqlUsageError(`'${entity.name}' declares triggers, which MongoDB has none of: a write here would skip them. ` +
+        throw new UqlUsageError(`'${entity.name}' declares triggers, which MongoDB cannot run within a write: a write here would skip them. ` +
             'Keep the entity on a SQL engine, or drop its triggers and stamps.');
     }
 }
@@ -223,11 +224,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 +311,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/mssql/mssqlQuerier.d.ts

@@ -1,3 +1,4 @@
+import { DateTime2 } from 'mssql';
 import { AbstractPoolQuerier } from '../querier/abstractPoolQuerier.js';
 import type { QueryUpdateResult, RawRow, TransactionOptions } from '../type/index.js';
 /** What `tedious` hands back for one statement, whichever shape it took. */
@@ -17,6 +18,7 @@ type MsSqlRowStream = AsyncIterable<unknown> & {
 /** The part of an `mssql` `Request` a querier drives. */
 type MsSqlRequest = {
     input(name: string, value: unknown): unknown;
+    input(name: string, type: typeof DateTime2, value: unknown): unknown;
     query(command: string): Promise<MsSqlResult>;
     toReadableStream(): MsSqlRowStream;
     cancel(): unknown;

package/dist/mssql/mssqlQuerier.js

@@ -1,4 +1,4 @@
-import { ISOLATION_LEVEL } from 'mssql';
+import { DateTime2, ISOLATION_LEVEL } from 'mssql';
 import { AbstractPoolQuerier } from '../querier/abstractPoolQuerier.js';
 import { decodeWireTypes } from './mssqlWireTypes.js';
 /**
@@ -9,13 +9,16 @@ import { decodeWireTypes } from './mssqlWireTypes.js';
 export class MsSqlQuerier extends AbstractPoolQuerier {
     #transaction;
     /**
-     * Values bind by name, `@p1` upward, matching {@link MsSqlDialect.placeholder}. `tedious` infers
-     * a type from the JS value, which is why a `Date` and a `Uint8Array` reach it unconverted - the
-     * inference is right for both, and wrong only for a bare `null`, which it calls `NVarChar`.
+     * Values bind by name, `@p1` upward, matching {@link MsSqlDialect.placeholder}. `mssql` infers a type
+     * from the JS value, right for a `Uint8Array` and harmlessly wrong for a bare `null` (`NVarChar`), but
+     * a `Date` it binds as the legacy `DATETIME`, whose 1/300 s steps no `DATETIME2` column compares equal to.
      */
     #request(values) {
         const request = this.#transaction ? this.#transaction.request() : this.getConn().request();
-        values?.forEach((value, index) => request.input(`p${index + 1}`, value));
+        values?.forEach((value, index) => {
+            const name = `p${index + 1}`;
+            return value instanceof Date ? request.input(name, DateTime2, value) : request.input(name, value);
+        });
         return request;
     }
     async internalAll(query, values) {

package/dist/mysql/mysql2QuerierPool.d.ts

@@ -4,6 +4,7 @@ import type { ExtraOptions } from '../type/index.js';
 import { MySql2Querier } from './mysql2Querier.js';
 import { MySqlDialect } from './mysqlDialect.js';
 export declare class MySql2QuerierPool extends AbstractSqlQuerierPool<MySql2Querier, MySqlDialect> {
+    #private;
     readonly pool: Pool;
     constructor(opts: PoolOptions, extra?: ExtraOptions);
     getQuerier(): Promise<MySql2Querier>;

package/dist/mysql/mysql2QuerierPool.js

@@ -5,14 +5,32 @@ import { MySql2Querier } from './mysql2Querier.js';
 import { MySqlDialect } from './mysqlDialect.js';
 export class MySql2QuerierPool extends AbstractSqlQuerierPool {
     pool;
+    #utcSessions = new WeakSet();
     constructor(opts, extra) {
         super(new MySqlDialect(dialectOptionsFrom(extra)), extra);
         // A BIGINT past 2^53 as its exact text rather than a rounded number, the rule every driver here
         // decodes by (`decodeWideNumber`); within that range it stays a number, and DECIMAL is untouched.
-        this.pool = createPool({ supportBigNumbers: true, ...opts });
+        // A date reads as the UTC it holds, whichever zone the process runs in.
+        this.pool = createPool({ supportBigNumbers: true, timezone: 'Z', ...opts });
     }
     async getQuerier() {
-        return new MySql2Querier(() => this.pool.getConnection(), this.dialect, this.extra);
+        return new MySql2Querier(() => this.#connection(), this.dialect, this.extra);
+    }
+    /** A connection whose session is UTC too, so `NOW()` agrees with a bound date: set once per connection. */
+    async #connection() {
+        const connection = await this.pool.getConnection();
+        if (this.#utcSessions.has(connection.connection)) {
+            return connection;
+        }
+        try {
+            await connection.query("SET time_zone = '+00:00'");
+        }
+        catch (error) {
+            connection.release();
+            throw error;
+        }
+        this.#utcSessions.add(connection.connection);
+        return connection;
     }
     async end() {
         await this.pool.end();

package/dist/neon/neonQuerierPool.js

@@ -1,11 +1,11 @@
 import { Pool, types } from '@neondatabase/serverless';
 import { dialectOptionsFrom } from '../dialect/abstractDialect.js';
 import { AbstractPgQuerierPool } from '../postgres/abstractPgQuerierPool.js';
-import { numericTypes } from '../postgres/pgNumericTypes.js';
+import { wireTypes } from '../postgres/pgWireTypes.js';
 import { PostgresDialect } from '../postgres/postgresDialect.js';
 export class NeonQuerierPool extends AbstractPgQuerierPool {
     constructor(opts, extra) {
         // Neon's own `types`, not `pg`'s: this entry has to load on an edge runtime where `pg` is absent.
-        super(new PostgresDialect(dialectOptionsFrom(extra)), new Pool({ types: numericTypes(types), ...opts }), extra);
+        super(new PostgresDialect(dialectOptionsFrom(extra)), new Pool({ types: wireTypes(types), ...opts }), extra);
     }
 }

package/dist/pglite/pgliteQuerierPool.js

@@ -1,6 +1,7 @@
 import { dialectOptionsFrom } from '../dialect/abstractDialect.js';
 import { PostgresDialect } from '../postgres/postgresDialect.js';
 import { AbstractSharedHandleQuerierPool } from '../querier/abstractSharedHandleQuerierPool.js';
+import { decodeDate } from '../util/date.js';
 import { decodeWideNumber } from '../util/wideNumber.js';
 import { PgliteQuerier } from './pgliteQuerier.js';
 /**
@@ -18,12 +19,17 @@ export class PgliteQuerierPool extends AbstractSharedHandleQuerierPool {
     }
     async openDb() {
         const { PGlite, types } = await import('@electric-sql/pglite');
-        // INT8 by the one wide-integer rule, where PGlite's own answers a `bigint` past 2^53; a caller's own
-        // `parsers` still win. The declared return type is what checks {@link PgliteDatabase} against the
-        // real driver, so no cast is needed here or anywhere below it.
+        // INT8 by the one wide-integer rule, where PGlite's own answers a `bigint` past 2^53, and a zoneless
+        // TIMESTAMP or a DATE as UTC, as every pool reads one; a caller's own `parsers` still win. The declared
+        // return type is what checks {@link PgliteDatabase} against the real driver, so no cast is needed below it.
         return PGlite.create(this.dataDir, {
             ...this.opts,
-            parsers: { [types.INT8]: decodeWideNumber, ...this.opts?.parsers },
+            parsers: {
+                [types.INT8]: decodeWideNumber,
+                [types.TIMESTAMP]: decodeDate,
+                [types.DATE]: decodeDate,
+                ...this.opts?.parsers,
+            },
         });
     }
     buildQuerier(db) {

package/dist/postgres/pgQuerierPool.js

@@ -1,12 +1,12 @@
 import { Pool, types } from 'pg';
 import { dialectOptionsFrom } from '../dialect/abstractDialect.js';
 import { AbstractPgQuerierPool } from './abstractPgQuerierPool.js';
-import { numericTypes } from './pgNumericTypes.js';
+import { wireTypes } from './pgWireTypes.js';
 import { PostgresDialect } from './postgresDialect.js';
 export class PgQuerierPool extends AbstractPgQuerierPool {
     constructor(opts, extra) {
         // keepAlive reduces (but can't eliminate) idle connections being silently
         // dropped by NATs/firewalls on long-lived remote connections.
-        super(new PostgresDialect(dialectOptionsFrom(extra)), new Pool({ keepAlive: true, types: numericTypes(types), ...opts }), extra);
+        super(new PostgresDialect(dialectOptionsFrom(extra)), new Pool({ keepAlive: true, types: wireTypes(types), ...opts }), extra);
     }
 }

package/dist/postgres/{pgNumericTypes.d.ts → pgWireTypes.d.ts}

@@ -11,8 +11,9 @@ type PgTypes = {
 };
 /**
  * Decodes `INT8` by `decodeWideNumber` and `FLOAT8` as the float64 it is, since `type: Number` maps to
- * BIGINT. At the wire, which every result crosses; `NUMERIC` is left to hydration, which knows the field.
- * Per pool, never a global parser, and a caller's own `types` win.
+ * BIGINT, and a zoneless `TIMESTAMP` or a `DATE` as UTC, where `pg` reads both in the process's zone. At
+ * the wire, which every result crosses; `NUMERIC` is left to hydration, which knows the field. Per pool,
+ * never a global parser, and a caller's own `types` win.
  */
-export declare function numericTypes(types: PgTypes): CustomTypesConfig;
+export declare function wireTypes(types: PgTypes): CustomTypesConfig;
 export {};

package/dist/postgres/{pgNumericTypes.js → pgWireTypes.js}

@@ -1,14 +1,18 @@
+import { decodeDate } from '../util/date.js';
 import { decodeWideNumber } from '../util/wideNumber.js';
 /**
  * Decodes `INT8` by `decodeWideNumber` and `FLOAT8` as the float64 it is, since `type: Number` maps to
- * BIGINT. At the wire, which every result crosses; `NUMERIC` is left to hydration, which knows the field.
- * Per pool, never a global parser, and a caller's own `types` win.
+ * BIGINT, and a zoneless `TIMESTAMP` or a `DATE` as UTC, where `pg` reads both in the process's zone. At
+ * the wire, which every result crosses; `NUMERIC` is left to hydration, which knows the field. Per pool,
+ * never a global parser, and a caller's own `types` win.
  */
-export function numericTypes(types) {
+export function wireTypes(types) {
     // Text only: in binary mode an INT8 arrives as an 8-byte Buffer, and `Number(buffer)` is `NaN`.
     const decoders = new Map([
         [types.builtins['INT8'], decodeWideNumber],
         [types.builtins['FLOAT8'], Number],
+        [types.builtins['TIMESTAMP'], decodeDate],
+        [types.builtins['DATE'], decodeDate],
     ]);
     return {
         getTypeParser: (oid, format) => (format === 'text' && decoders.get(oid)) || types.getTypeParser(oid, format),

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;

package/dist/schema/canonicalType.d.ts

@@ -1,6 +1,7 @@
 import type { AbstractDialect } from '../dialect/abstractDialect.js';
 import type { VectorCast } from '../dialect/vectorCast.js';
 import type { ColumnType, EntityGetter, FieldMeta, FieldOptions } from '../type/entity.js';
+import { type DialectName } from '../type/index.js';
 import type { CanonicalType, TypeCategory } from './types.js';
 /** Whether a category is one of the vector types, narrowing it to the cast pgvector names use. */
 export declare function isVectorCategory(category: TypeCategory | undefined): category is VectorCast;
@@ -29,6 +30,8 @@ export declare function canonicalToSql(type: CanonicalType, dialect: AbstractDia
  * Convert a canonical type to a TypeScript type string.
  */
 export declare function canonicalToTypeScript(type: CanonicalType): string;
+/** The fractional-second digits an engine's timestamp holds when its type states none; `undefined` where it counts none. */
+export declare function defaultTimestampPrecision(dialectName: DialectName): number | undefined;
 /**
  * A type as `dialect` stores it, rendered and read back: several types share one storage type, and only
  * the engine settles an unstated bound. Migrations and drift both compare through it.