uql-orm 0.76.0 → 0.77.0

package/dist/querier/abstractQuerier.d.ts

@@ -87,8 +87,14 @@ export declare abstract class AbstractQuerier implements Querier {
     /** Settles the rows first where the update cascades, so a payload changing what `$where` reads still names them. */
     updateMany<E extends object>(entity: Type<E>, q: QuerySearch<E>, payload: UpdateWrite<E>, opts?: QueryOptions): Promise<number>;
     /**
-     * Why an update matched no row: another writer moved the version on, or the row is gone. One read
-     * without the version predicate answers it, and it runs only on the failure, so the happy path
+     * The write every update runs, matching the version `lockKey` names where one is being held. Only a
+     * restore passes none: it writes no content, so there is no update of anyone's to lose.
+     */
+    private updateRows;
+    /**
+     * Why an update matched no row. The filter named the row by its id, so reading by that id alone
+     * separates the three: the row is gone, another writer moved the version on, or the rest of the
+     * filter excluded a row still at that version. One read, only on the failure, so the happy path
      * still costs one statement. Best effort by nature - the row can change again while we ask.
      */
     private throwStaleVersion;

package/dist/querier/abstractQuerier.js

@@ -1,6 +1,6 @@
 import { assertSoleId, getMeta, idOf, namesKey, relationOf } from '../entity/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 { enrichError, UqlOptimisticLockError } from './queryError.js';
+import { enrichError, UqlLockUsageError, UqlOptimisticLockError } from './queryError.js';
 /**
  * Refuses a nullish id, which would reduce to no filter at all, and a composite id missing a column,
  * which would address every row agreeing on the rest. Callers are `async`, so it always rejects.
@@ -39,26 +39,41 @@ function assertNamesRows(entity, method, q, opts) {
     throw new TypeError(`'${method}' over '${entity.name}' names no rows, so it would address every one: pass '{ unfiltered: true }' to mean it`);
 }
 /**
- * An optimistic lock as one update applies it: the value the payload carried, out of the payload and
- * into the filter, and the next one back in its place. The bump is a plain value rather than SQL
- * arithmetic, since the filter pins what the column holds, which spares every engine a read-back.
+ * An optimistic lock as one update applies it: the version the payload carried, the one that replaces
+ * it, and the filter pinning what the column still holds. The bump is a plain value rather than SQL
+ * arithmetic, since that filter already pins it, which spares every engine a read-back.
  */
 function lockVersion(meta, key, q, row) {
     const expected = row[key];
-    if (expected === undefined || expected === null) {
-        throw new TypeError(`an update of '${entityName(meta)}' carries no '${key}': a versioned row is written against the version it was read at`);
+    if (typeof expected !== 'number' && typeof expected !== 'bigint') {
+        throw new UqlLockUsageError(`an update of '${entityName(meta)}' carries no '${key}': a versioned row is written against the version it was read at`);
     }
-    row[key] = (typeof expected === 'bigint' ? expected + 1n : Number(expected) + 1);
-    return { expected, q: { ...q, $where: { $and: [q.$where ?? {}, { [key]: expected }] } } };
+    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 } } };
 }
 /**
  * Refuses a write that cannot carry the lock, rather than writing over whatever the row holds now.
  * An upsert has no portable way to match a version - MySQL's `ON DUPLICATE KEY UPDATE` takes no
  * `WHERE` - and a write the library itself composes has no version to carry.
  */
-function assertUnversioned(meta, method) {
+function assertUnversioned(meta, what) {
     if (meta.version) {
-        throw new TypeError(`cannot '${method}' the versioned '${entityName(meta)}': it carries no '${meta.version}' to match, so update it by id`);
+        throw new UqlLockUsageError(`cannot ${what} the versioned '${entityName(meta)}': it carries no '${meta.version}' to match, so update it by id`);
+    }
+}
+/**
+ * What a versioned update has to be for its lock to hold: one row, named by its id, written by one
+ * statement. A filter naming more than one row cannot say which of them the payload's single version
+ * belongs to, and anything settled first - a page, a relation write, a filter an engine cannot read in
+ * 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]));
+    if (!namesOneRow || settles) {
+        throw new UqlLockUsageError(`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`);
     }
 }
 /**
@@ -218,45 +233,55 @@ export class AbstractQuerier {
     /** Settles the rows first where the update cascades, so a payload changing what `$where` reads still names them. */
     async updateMany(entity, q, payload, opts) {
         assertNamesRows(entity, 'updateMany', q, opts);
+        return this.hooked(entity, 'Update', [payload], ([row]) => this.updateRows(entity, q, row, opts, getMeta(entity).version));
+    }
+    /**
+     * The write every update runs, matching the version `lockKey` names where one is being held. Only a
+     * restore passes none: it writes no content, so there is no update of anyone's to lose.
+     */
+    async updateRows(entity, q, row, opts, lockKey) {
         const meta = getMeta(entity);
-        return this.hooked(entity, 'Update', [payload], async ([row]) => {
-            fillOnFields(meta, [row], 'onUpdate');
-            const { version } = meta;
-            const lock = version && lockVersion(meta, version, q, row);
-            const relKeys = filterPersistableRelationKeys(meta, row, 'persist');
-            if (!relKeys.length && !this.settlesWrite(entity, q)) {
-                const changes = await this.updateColumns(entity, lock ? lock.q : q, row, opts, 0);
-                return lock && !changes ? this.throwStaleVersion(entity, version, q, lock.expected, opts) : changes;
-            }
-            if (lock) {
-                // Everything below reads the ids first and writes them in a second statement, which puts the
-                // race back in the gap between the two - the very thing the version is here to close.
-                // `settlesWrite` covers the paged forms, so `$sort`, `$limit` and `$skip` land here as well.
-                throw new TypeError(`cannot update '${entityName(meta)}' this way: a versioned row is matched and written in one statement, so it takes no '$sort', '$limit' or '$skip', writes no relation, and filters by none`);
-            }
-            const ids = await this.settleIds(entity, q, opts);
-            if (!ids.length) {
-                return 0;
-            }
-            const changes = await this.updateColumns(entity, { $where: whereIds(meta, ids) }, row, opts, ids.length);
-            for (const relKey of relKeys) {
-                await this.saveRelation(entity, relKey, ids.map((id) => ({ id, value: row[relKey] })), true);
-            }
-            return changes;
-        });
+        fillOnFields(meta, [row], 'onUpdate');
+        const relKeys = filterPersistableRelationKeys(meta, row, 'persist');
+        const settles = !!relKeys.length || this.settlesWrite(entity, q);
+        if (lockKey) {
+            assertLockableUpdate(meta, q, settles);
+            const lock = lockVersion(meta, lockKey, q, row);
+            row[lockKey] = lock.next;
+            const changes = await this.updateColumns(entity, lock.q, row, opts, 0);
+            return changes || this.throwStaleVersion(entity, lockKey, q, lock.expected, opts);
+        }
+        if (!settles) {
+            return this.updateColumns(entity, q, row, opts, 0);
+        }
+        const ids = await this.settleIds(entity, q, opts);
+        if (!ids.length) {
+            return 0;
+        }
+        const changes = await this.updateColumns(entity, { $where: whereIds(meta, ids) }, row, opts, ids.length);
+        for (const relKey of relKeys) {
+            await this.saveRelation(entity, relKey, ids.map((id) => ({ id, value: row[relKey] })), true);
+        }
+        return changes;
     }
     /**
-     * Why an update matched no row: another writer moved the version on, or the row is gone. One read
-     * without the version predicate answers it, and it runs only on the failure, so the happy path
+     * Why an update matched no row. The filter named the row by its id, so reading by that id alone
+     * separates the three: the row is gone, another writer moved the version on, or the rest of the
+     * filter excluded a row still at that version. One read, only on the failure, so the happy path
      * still costs one statement. Best effort by nature - the row can change again while we ask.
      */
     async throwStaleVersion(entity, key, q, expected, opts) {
         const meta = getMeta(entity);
-        const row = await this.findOne(entity, { $select: { [key]: true }, $where: q.$where }, opts);
+        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 actual = row?.[key];
-        throw new UqlOptimisticLockError(actual === undefined
-            ? `no row of '${entityName(meta)}' matched the update: it is gone, or the filter names none`
-            : `'${entityName(meta)}' moved on: the payload carries '${key}' ${String(expected)}, the row is at ${String(actual)}`, expected, actual);
+        const message = actual === undefined
+            ? `no row of '${entityName(meta)}' has that id any more: it is gone`
+            : actual === expected
+                ? `'${entityName(meta)}' is still at '${key}' ${String(actual)}: another condition of the update's '$where' excluded it`
+                : `'${entityName(meta)}' moved on: the payload carries '${key}' ${String(expected)}, the row is at ${String(actual)}`;
+        throw new UqlOptimisticLockError(message, expected, actual);
     }
     /** The UPDATE, skipped where the payload writes no column, reporting `unwritten` instead. */
     async updateColumns(entity, q, row, opts, unwritten) {
@@ -286,16 +311,15 @@ export class AbstractQuerier {
         if (!meta.softDelete) {
             throw new TypeError(`'${entity.name}' has not enabled 'softDelete'`);
         }
-        assertUnversioned(meta, 'restoreMany');
         const $where = { ...q.$where, [meta.softDelete]: { $ne: null } };
-        return this.updateMany(entity, { ...q, $where }, { [meta.softDelete]: null }, {
-            filters: { softDelete: false },
-        });
+        // 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));
     }
     /** 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) {
         const meta = getMeta(entity);
-        assertUnversioned(meta, 'upsertOne');
+        assertUnversioned(meta, "'upsertOne'");
         return this.hooked(entity, 'Upsert', [payload], async (rows) => {
             const { ids, changes, created } = await this.internalUpsertOne(entity, conflictPaths, rows[0]);
             adoptReportedIds(meta, rows, ids);
@@ -305,7 +329,7 @@ export class AbstractQuerier {
     }
     async upsertMany(entity, conflictPaths, payload) {
         const meta = getMeta(entity);
-        assertUnversioned(meta, 'upsertMany');
+        assertUnversioned(meta, "'upsertMany'");
         return this.hooked(entity, 'Upsert', payload, async (rows) => {
             const { ids, changes } = await this.internalUpsertMany(entity, conflictPaths, rows);
             adoptReportedIds(meta, rows, ids);
@@ -343,8 +367,6 @@ export class AbstractQuerier {
         return changes;
     }
     async saveOne(entity, payload) {
-        // Named here as well as in `saveMany`, so the refusal names the method the caller reached for.
-        assertUnversioned(getMeta(entity), 'saveOne');
         const [id] = await this.saveMany(entity, [payload]);
         return id;
     }
@@ -355,7 +377,7 @@ export class AbstractQuerier {
      */
     async saveMany(entity, payload) {
         const meta = getMeta(entity);
-        assertUnversioned(meta, 'saveMany');
+        assertUnversioned(meta, "'save'");
         // Indexes, not rows: the result is reported in payload order so it can be zipped with what was
         // passed, which concatenating the branches did not do.
         const toInsert = [];

package/dist/querier/queryError.d.ts

@@ -24,6 +24,16 @@ export declare class UqlOptimisticLockError extends Error {
     readonly status = 409;
     constructor(message: string, expected: unknown, actual: unknown);
 }
+/**
+ * Thrown where a write cannot carry the optimistic lock: an update payload without its version, or a
+ * method with no version to match. A `TypeError` still, since the caller used the API wrong, but one
+ * carrying the `status` an HTTP transport answers with - the request is malformed, not the server's
+ * failure, and an untyped client is exactly who reaches this.
+ */
+export declare class UqlLockUsageError extends TypeError {
+    name: string;
+    readonly status = 400;
+}
 /**
  * Names what `err` ran into on any engine, or `undefined` for anything else. Pure: the error is only
  * read, so it works on any driver error, whether or not a querier saw it first.

package/dist/querier/queryError.js

@@ -14,6 +14,16 @@ export class UqlOptimisticLockError extends Error {
         this.actual = actual;
     }
 }
+/**
+ * Thrown where a write cannot carry the optimistic lock: an update payload without its version, or a
+ * method with no version to match. A `TypeError` still, since the caller used the API wrong, but one
+ * carrying the `status` an HTTP transport answers with - the request is malformed, not the server's
+ * failure, and an untyped client is exactly who reaches this.
+ */
+export class UqlLockUsageError extends TypeError {
+    name = 'UqlLockUsageError';
+    status = 400;
+}
 /** Postgres, CockroachDB, PGlite and Neon in `code`; Bun SQL in `errno`. */
 const SQLSTATE_KINDS = new Map([
     ['23505', 'uniqueViolation'],

package/package.json

@@ -3,7 +3,7 @@
   "homepage": "https://uql-orm.dev",
   "description": "The JSON-native TypeScript ORM for Bun, Browsers, Edge, Deno, Node, Workers. Supports PostgreSQL, PGlite, MySQL, MariaDB, SQLite, CockroachDB, SQL Server, Turso, Neon, Cloudflare D1 and MongoDB. Queries are plain JSON, typed to the leaf.",
   "license": "MIT",
-  "version": "0.76.0",
+  "version": "0.77.0",
   "type": "module",
   "engines": {
     "node": ">=24"

package/skills/uql-orm/SKILL.md

@@ -82,9 +82,7 @@ export class Post {
 - `@Field({ type: Number, version: true })`, with `[versionKey]?: 'version'` on the class, makes the column an
   optimistic lock: every update payload must carry the version it read (a compile error otherwise), the update
   matches on it and writes the next one, and a write against a row someone else moved on throws
-  `UqlOptimisticLockError` (`status` 409) instead of overwriting it. Save, upsert and `restoreMany` are refused on such
-  an entity (restore with `updateOneById`, `{ filters: { softDelete: false } }`); `updateMany` writes only the rows
-  still at the version it carries, and delete needs none.
+  `UqlOptimisticLockError` (`status` 409) instead of overwriting it. Save and upsert are refused on such an entity; the update is named by its id, so `updateMany` over a many-row filter is refused too, and delete and restore carry no version.
 - `defineEntity` defines the same entity without decorators: https://uql-orm.dev/entities/imperative.md
 
 ## Queries