@rvoh/dream 2.24.0 → 2.25.0

package/dist/esm/src/dream/Query.js

@@ -3,10 +3,12 @@ import DreamApp from '../dream-app/index.js';
 import AssociationDeclaredWithoutAssociatedDreamClass from '../errors/associations/AssociationDeclaredWithoutAssociatedDreamClass.js';
 import CannotCallUndestroyOnANonSoftDeleteModel from '../errors/CannotCallUndestroyOnANonSoftDeleteModel.js';
 import CannotPassAdditionalFieldsToPluckEachAfterCallback from '../errors/CannotPassAdditionalFieldsToPluckEachAfterCallback.js';
+import BatchingIncompatibleWithLimitOrOffset from '../errors/BatchingIncompatibleWithLimitOrOffset.js';
 import InvalidBatchSize from '../errors/InvalidBatchSize.js';
 import LeftJoinPreloadIncompatibleWithFindEach from '../errors/LeftJoinPreloadIncompatibleWithFindEach.js';
 import RowLockIncompatibleWithDistinct from '../errors/RowLockIncompatibleWithDistinct.js';
 import MissingRequiredCallbackFunctionToPluckEach from '../errors/MissingRequiredCallbackFunctionToPluckEach.js';
+import MissingRequiredLockOptionForUpdateCallback from '../errors/MissingRequiredLockOptionForUpdateCallback.js';
 import NoUpdateAllOnJoins from '../errors/NoUpdateAllOnJoins.js';
 import NoUpdateOnAssociationQuery from '../errors/NoUpdateOnAssociationQuery.js';
 import CannotPaginateWithLeftJoinPreload from '../errors/pagination/CannotPaginateWithLeftJoinPreload.js';
@@ -51,10 +53,12 @@ export default class Query {
      */
     static BATCH_SIZES = {
         FIND_EACH: 1000,
-        // deliberately small: every record in a locked destroy batch stays
-        // row-locked for the whole batch, so an oversized batch blocks unrelated
-        // writers. See Query#destroy's `lock` option.
+        // deliberately small: every record in a locked destroy or update batch
+        // stays row-locked for the whole batch, so an oversized batch blocks
+        // unrelated writers. See the `lock` options on Query#destroy and
+        // Query#update.
         LOCKED_DESTROY: 10,
+        LOCKED_UPDATE: 10,
         PLUCK_EACH: 10000,
         PLUCK_EACH_THROUGH: 1000,
     };
@@ -446,26 +450,40 @@ export default class Query {
      * If you need records processed in a particular order, load them with a
      * regular ordered query instead of `findEach`.
      *
+     * A `limit` or `offset` on the Query cannot compose with the batch windows
+     * — each batch re-applies the Query's conditions, so the limit would be
+     * silently replaced by `batchSize` and the offset re-applied to every
+     * window — so a limit- or offset-carrying Query throws at runtime.
+     *
      * @param cb - The callback to call for each found record
      * @param __namedParameters - Options for batch processing
      * @param __namedParameters.batchSize - The batch size you wish to collect records in. If not provided, it will default to 1000
      * @returns void
+     * @throws BatchingIncompatibleWithLimitOrOffset if the query carries a `limit` or `offset`
      */
     async findEach(cb, { batchSize = Query.BATCH_SIZES.FIND_EACH } = {}) {
         if (this.joinLoadActivated)
             throw new LeftJoinPreloadIncompatibleWithFindEach();
+        // a limit or offset cannot compose with the batch windows: the window
+        // queries would re-apply it per batch — the limit silently replaced by
+        // batchSize, the offset skipping rows inside every window
+        if (this.limitStatement || this.offsetStatement)
+            throw new BatchingIncompatibleWithLimitOrOffset();
         let records;
         const query = this.order(null)
             .order(this.namespacedPrimaryKey)
             .limit(batchSize);
-        let lastId = null;
+        // the cursor is compared against a sentinel rather than tested for
+        // truthiness, since a primary key of 0 is a legitimate cursor value that
+        // would otherwise reset the window to the start of the set
+        let lastId = undefined;
         do {
-            if (lastId)
+            if (lastId === undefined)
+                records = await query.all();
+            else
                 records = await query
                     .where({ [this.dreamInstance['_primaryKey']]: ops.greaterThan(lastId) })
                     .all();
-            else
-                records = await query.all();
             for (const record of records) {
                 await cb(record);
             }
@@ -946,6 +964,12 @@ export default class Query {
      * // [User{id: 1}, User{id: 2}]
      * ```
      *
+     * A limit is incompatible with `paginate` and `leftJoinPreload`, and with
+     * the batched and set-write operations — `findEach`, `pluckEach`,
+     * `destroy`, `reallyDestroy`, `undestroy`, and `update` — none of which can
+     * honor one: the batched and set-write operations throw
+     * `BatchingIncompatibleWithLimitOrOffset` on a limit-carrying Query.
+     *
      * @returns A cloned Query with the limit clause applied
      */
     limit(limit) {
@@ -959,6 +983,12 @@ export default class Query {
      * // [User{id: 3}, User{id: 4}]
      * ```
      *
+     * An offset is incompatible with `paginate` and `leftJoinPreload`, and with
+     * the batched and set-write operations — `findEach`, `pluckEach`,
+     * `destroy`, `reallyDestroy`, `undestroy`, and `update` — none of which can
+     * honor one: the batched and set-write operations throw
+     * `BatchingIncompatibleWithLimitOrOffset` on an offset-carrying Query.
+     *
      * @returns A cloned Query with the offset clause applied
      */
     offset(offset) {
@@ -1322,8 +1352,14 @@ export default class Query {
      * // 3
      * ```
      *
+     * A `limit` or `offset` on the Query cannot compose with the batch windows
+     * — each window replaces the limit with the batch size and the offset with
+     * the running window offset, silently ignoring both — so a limit- or
+     * offset-carrying Query throws at runtime.
+     *
      * @param args - a list of column names to pluck, followed by a callback function to call for each set of found fields
      * @returns void
+     * @throws BatchingIncompatibleWithLimitOrOffset if the query carries a `limit` or `offset`
      */
     async pluckEach(...args) {
         const providedCbIndex = args.findIndex(v => typeof v === 'function');
@@ -1333,6 +1369,11 @@ export default class Query {
             throw new MissingRequiredCallbackFunctionToPluckEach('pluckEach', args);
         if (providedOpts !== undefined && !providedOpts?.batchSize)
             throw new CannotPassAdditionalFieldsToPluckEachAfterCallback('pluckEach', args);
+        // a limit or offset cannot compose with the batch windows: the window
+        // queries would replace the limit with batchSize and the offset with the
+        // running window offset, silently ignoring both
+        if (this.limitStatement || this.offsetStatement)
+            throw new BatchingIncompatibleWithLimitOrOffset();
         const onlyColumns = args.filter((_, index) => index < providedCbIndex);
         const batchSize = providedOpts?.batchSize || Query.BATCH_SIZES.PLUCK_EACH_THROUGH;
         let offset = 0;
@@ -1865,20 +1906,27 @@ export default class Query {
      *   scale, ties up connections. If that is a risk in your application, set a
      *   `lock_timeout` on the connection so a stuck batch fails instead of
      *   hanging.
+     * - **A `limit` or `offset` on the Query is incompatible with `destroy` on
+     *   every path.** The batches — locked and unlocked alike — re-apply the
+     *   Query's conditions to each window, where a limit or offset would skip
+     *   or truncate rows inside every window instead of bounding the run as a
+     *   whole, so `destroy` throws rather than silently corrupting the
+     *   windows.
      * - **If you are destroying a large set and do not need compare-and-set, do
      *   not pass `lock`.** Plain `destroy()` (hooks and cascade, no locking) or
      *   {@link Query.delete | delete} (a single statement, no hooks or cascade)
      *   are the right tools for bulk removal.
      *
-     * @param __namedParameters - Options for destroying the instance
-     * @param __namedParameters.skipHooks - If true, skips applying model hooks during the destroy operation. Defaults to false
-     * @param __namedParameters.cascade - If false, skips destroying associations marked `dependent: 'destroy'`. Defaults to true
-     * @param __namedParameters.lock - If true, each batch is re-selected with an exclusive row lock inside its own transaction before being destroyed, making the destroy a compare-and-set. Defaults to false
-     * @param __namedParameters.batchSize - The number of records to process per batch. Must be a positive integer. Defaults to 10 when `lock` is true, and to 1000 otherwise
-     * @param __namedParameters.bypassAllDefaultScopes - If true, bypasses all default scopes when cascade destroying. Defaults to false
-     * @param __namedParameters.defaultScopesToBypass - An array of default scope names to bypass when cascade destroying. Defaults to an empty array
+     * @param options - Options for destroying the instance
+     * @param options.skipHooks - If true, skips applying model hooks during the destroy operation. Defaults to false
+     * @param options.cascade - If false, skips destroying associations marked `dependent: 'destroy'`. Defaults to true
+     * @param options.lock - If true, each batch is re-selected with an exclusive row lock inside its own transaction before being destroyed, making the destroy a compare-and-set. Defaults to false
+     * @param options.batchSize - The number of records to process per batch. Must be a positive integer. Defaults to 10 when `lock` is true, and to 1000 otherwise
+     * @param options.bypassAllDefaultScopes - If true, bypasses all default scopes when cascade destroying. Defaults to false
+     * @param options.defaultScopesToBypass - An array of default scope names to bypass when cascade destroying. Defaults to an empty array
      * @returns The number of records that were removed
      * @throws InvalidBatchSize if `batchSize` is not a positive integer
+     * @throws BatchingIncompatibleWithLimitOrOffset if the query carries a `limit` or `offset`
      */
     async destroy({ skipHooks, cascade, lock, batchSize, } = {}) {
         let counter = 0;
@@ -1917,43 +1965,77 @@ export default class Query {
     /**
      * @internal
      *
-     * The compare-and-set implementation behind `destroy({ lock: true })`.
+     * The compare-and-set implementation behind `destroy({ lock: true })`,
+     * driven by {@link Query.lockedBatches}, which owns the keyset cursor, the
+     * pluck/claim two-step, and the transaction dispatch.
+     *
+     * Each claimed record is destroyed via the ordinary per-instance path, and
+     * every claimed record counts. (One thing the count does not account for,
+     * because it never has: a `beforeDestroy` hook that sets `_preventDeletion`
+     * leaves the record in place but still counts.)
+     */
+    async lockedDestroy(options, batchSize) {
+        if (this.joinLoadActivated)
+            throw new LeftJoinPreloadIncompatibleWithFindEach();
+        return await this.lockedBatches(batchSize, async (claimed, txn) => {
+            for (const record of claimed) {
+                const inTransaction = record.txn(txn);
+                if (this.shouldReallyDestroy) {
+                    await inTransaction.reallyDestroy(options);
+                }
+                else {
+                    await inTransaction.destroy(options);
+                }
+            }
+            return claimed.length;
+        });
+    }
+    /**
+     * @internal
+     *
+     * The shared batch driver behind `destroy({ lock: true })` and
+     * `update(..., { lock: true })`: the keyset cursor, the pluck/claim
+     * two-step, and the transaction dispatch live here, so the locked
+     * operations cannot drift apart.
      *
      * Each batch is handled in two steps inside one transaction:
      *
      * 1. an unlocked pluck of the next `batchSize` primary keys, in ascending
      *    primary key order, which establishes the batch's window (its keyset
-     *    cursor) and tells us how many records were *attempted*. Only the keys are
-     *    read: hydrating and preloading these records would duplicate the work
-     *    step 2 does over the same rows; then
+     *    cursor) and tells us how many records were *attempted*. Only the keys
+     *    are read: hydrating and preloading these records would duplicate the
+     *    work step 2 does over the same rows; then
      * 2. a locked re-read restricted to exactly those primary keys, which
-     *    re-applies every condition on the Query while acquiring an exclusive row
-     *    lock on each row it returns. Records a concurrent transaction has moved
-     *    out of the Query since step 1 do not come back, and are the records this
-     *    run lost the race for.
-     *
-     * The count comes from step 2's result set, which is why it reports records
-     * actually claimed rather than records attempted. (One thing it does not
-     * account for, because it never has: a `beforeDestroy` hook that sets
-     * `_preventDeletion` leaves the record in place but still counts.)
-     *
-     * The two-step shape is what keeps iteration correct. If the locked read both
-     * claimed rows and advanced the cursor, a batch whose records all lost the
-     * race would come back empty and end the run early, silently skipping every
-     * record after it. Advancing the cursor from step 1 instead means losing a
-     * race skips only the records that were lost.
+     *    re-applies every condition on the Query while acquiring an exclusive
+     *    row lock on each row it returns. Records a concurrent transaction has
+     *    moved out of the Query since step 1 do not come back, and are the
+     *    records this run lost the race for.
+     *
+     * The claimed records are handed to `perBatch` inside the batch's
+     * transaction; its return value — how many of the claimed records were
+     * processed — accumulates into the returned count.
+     *
+     * The two-step shape is what keeps iteration correct. If the locked read
+     * both claimed rows and advanced the cursor, a batch whose records all lost
+     * the race would come back empty and end the run early, silently skipping
+     * every record after it. Advancing the cursor from step 1 instead means
+     * losing a race skips only the records that were lost.
      *
      * When the Query already carries a transaction, that transaction is used for
      * every batch rather than opening one per batch, so the caller's transaction
      * boundary wins and the locks are held until the caller commits.
      */
-    async lockedDestroy(options, batchSize) {
-        if (this.joinLoadActivated)
-            throw new LeftJoinPreloadIncompatibleWithFindEach();
+    async lockedBatches(batchSize, perBatch) {
         // the driver seam refuses this combination too, but catching it here means
         // failing before any transaction is opened or any row is touched
         if (this.distinctColumn)
             throw new RowLockIncompatibleWithDistinct();
+        // a limit or offset cannot compose with the batch windows: the window
+        // queries would re-apply it per batch — the offset skipping rows in the
+        // candidate pluck and discarding already-claimed rows from the locked
+        // re-read, the limit silently replaced by batchSize
+        if (this.limitStatement || this.offsetStatement)
+            throw new BatchingIncompatibleWithLimitOrOffset();
         const primaryKey = this.dreamInstance['_primaryKey'];
         const orderedQuery = this.order(null)
             .order(this.namespacedPrimaryKey)
@@ -1968,30 +2050,21 @@ export default class Query {
             const batchQuery = lastId === undefined
                 ? orderedQuery
                 : orderedQuery.where({ [primaryKey]: ops.greaterThan(lastId) });
-            const destroyBatch = async (txn) => {
+            const processBatch = async (txn) => {
                 const candidateIds = await batchQuery.txn(txn).pluck(this.namespacedPrimaryKey);
                 if (!candidateIds.length)
-                    return { attempted: 0, claimed: 0, lastId };
+                    return { attempted: 0, processed: 0, lastId };
                 const claimed = await this.dbDriverInstance(batchQuery.txn(txn).where({ [primaryKey]: candidateIds })).takeAll({ lock: true });
-                for (const record of claimed) {
-                    const inTransaction = record.txn(txn);
-                    if (this.shouldReallyDestroy) {
-                        await inTransaction.reallyDestroy(options);
-                    }
-                    else {
-                        await inTransaction.destroy(options);
-                    }
-                }
                 return {
                     attempted: candidateIds.length,
-                    claimed: claimed.length,
+                    processed: await perBatch(claimed, txn),
                     lastId: candidateIds.at(-1),
                 };
             };
             const results = this.dreamTransaction
-                ? await destroyBatch(this.dreamTransaction)
-                : await this.dreamClass.transaction(async (txn) => await destroyBatch(txn));
-            counter += results.claimed;
+                ? await processBatch(this.dreamTransaction)
+                : await this.dreamClass.transaction(async (txn) => await processBatch(txn));
+            counter += results.processed;
             attemptedCount = results.attempted;
             lastId = results.lastId;
         } while (attemptedCount > 0 && attemptedCount === batchSize);
@@ -2015,15 +2088,20 @@ export default class Query {
      * // 12
      * ```
      *
-     * @param __namedParameters - Options for destroying the instance
-     * @param __namedParameters.skipHooks - If true, skips applying model hooks during the destroy operation. Defaults to false
-     * @param __namedParameters.cascade - If false, skips destroying associations marked `dependent: 'destroy'`. Defaults to true
-     * @param __namedParameters.lock - If true, each batch is re-selected with an exclusive row lock inside its own transaction before being destroyed, making the destroy a compare-and-set. See {@link Query.destroy} for the full semantics. Defaults to false
-     * @param __namedParameters.batchSize - The number of records to process per batch. Must be a positive integer. Defaults to 10 when `lock` is true, and to 1000 otherwise
-     * @param __namedParameters.bypassAllDefaultScopes - If true, bypasses all default scopes when cascade destroying. Defaults to false
-     * @param __namedParameters.defaultScopesToBypass - An array of default scope names to bypass when cascade destroying. Defaults to an empty array
+     * A `limit` or `offset` on the Query is incompatible with `reallyDestroy`,
+     * exactly as it is with {@link Query.destroy}: a limit- or offset-carrying
+     * Query throws at runtime.
+     *
+     * @param options - Options for destroying the instance
+     * @param options.skipHooks - If true, skips applying model hooks during the destroy operation. Defaults to false
+     * @param options.cascade - If false, skips destroying associations marked `dependent: 'destroy'`. Defaults to true
+     * @param options.lock - If true, each batch is re-selected with an exclusive row lock inside its own transaction before being destroyed, making the destroy a compare-and-set. See {@link Query.destroy} for the full semantics. Defaults to false
+     * @param options.batchSize - The number of records to process per batch. Must be a positive integer. Defaults to 10 when `lock` is true, and to 1000 otherwise
+     * @param options.bypassAllDefaultScopes - If true, bypasses all default scopes when cascade destroying. Defaults to false
+     * @param options.defaultScopesToBypass - An array of default scope names to bypass when cascade destroying. Defaults to an empty array
      * @returns The number of records that were removed
      * @throws InvalidBatchSize if `batchSize` is not a positive integer
+     * @throws BatchingIncompatibleWithLimitOrOffset if the query carries a `limit` or `offset`
      */
     async reallyDestroy({ skipHooks, cascade, lock, batchSize, } = {}) {
         return await this.clone({ shouldReallyDestroy: true }).destroy({ skipHooks, cascade, lock, batchSize });
@@ -2040,12 +2118,19 @@ export default class Query {
      * // 12
      * ```
      *
-     * @param __namedParameters - Options for undestroying the instance
-     * @param __namedParameters.skipHooks - If true, skips applying model hooks during the undestroy operation. Defaults to false
-     * @param __namedParameters.cascade - If false, skips undestroying associations marked `dependent: 'destroy'`. Defaults to true
-     * @param __namedParameters.bypassAllDefaultScopes - If true, bypasses all default scopes when cascade undestroying. Defaults to false
-     * @param __namedParameters.defaultScopesToBypass - An array of default scope names to bypass when cascade undestroying (soft delete is always bypassed). Defaults to an empty array
+     * A `limit` or `offset` on the Query cannot compose with the batch windows
+     * `undestroy` iterates in — each batch re-applies the Query's conditions,
+     * so the limit would be silently replaced by the batch size and the offset
+     * re-applied to every window — so a limit- or offset-carrying Query throws
+     * at runtime.
+     *
+     * @param options - Options for undestroying the instance
+     * @param options.skipHooks - If true, skips applying model hooks during the undestroy operation. Defaults to false
+     * @param options.cascade - If false, skips undestroying associations marked `dependent: 'destroy'`. Defaults to true
+     * @param options.bypassAllDefaultScopes - If true, bypasses all default scopes when cascade undestroying. Defaults to false
+     * @param options.defaultScopesToBypass - An array of default scope names to bypass when cascade undestroying (soft delete is always bypassed). Defaults to an empty array
      * @returns The number of records that were removed
+     * @throws BatchingIncompatibleWithLimitOrOffset if the query carries a `limit` or `offset`
      */
     async undestroy({ cascade, skipHooks, } = {}) {
         if (!this.dreamClass['softDelete'])
@@ -2084,25 +2169,120 @@ export default class Query {
     async delete() {
         return await this.dbDriverInstance().delete();
     }
-    async update(attributes, { skipHooks } = {}) {
+    async update(attributesOrCb, { skipHooks, lock, batchSize } = {}) {
         if (this.baseSelectQuery)
             throw new NoUpdateOnAssociationQuery();
         if (Object.keys(this.innerJoinStatements).length)
             throw new NoUpdateAllOnJoins();
         if (Object.keys(this.leftJoinStatements).length)
             throw new NoUpdateAllOnJoins();
-        if (skipHooks)
-            return await this.updateWithoutCallingModelHooks(attributes);
+        const cb = typeof attributesOrCb === 'function' ? attributesOrCb : undefined;
+        // the overloads already demand an options object with a boolean `lock`
+        // whenever a callback is passed; this backstops callers outside the type
+        // system, so a callback can never silently take (or skip) row locks the
+        // call site did not spell out
+        if (cb && typeof lock !== 'boolean')
+            throw new MissingRequiredLockOptionForUpdateCallback();
+        // resolve the default before validating: `??` would let an explicit 0
+        // through, and `limit(0)` means "no limit", which would turn a batched
+        // update into a single unbounded pass (and, with `lock`, a lock over the
+        // entire matched set)
+        const resolvedBatchSize = batchSize ?? (lock ? Query.BATCH_SIZES.LOCKED_UPDATE : Query.BATCH_SIZES.FIND_EACH);
+        if (!Number.isInteger(resolvedBatchSize) || resolvedBatchSize < 1)
+            throw new InvalidBatchSize(batchSize);
+        // a limit or offset cannot compose with any update path: the batched
+        // paths (findEach and lockedBatches, which also guard) would re-apply it
+        // to every batch window, silently skipping or truncating rows within each
+        // window rather than bounding the run, and the single-statement skipHooks
+        // path's SQL UPDATE cannot express it, so it would be silently ignored
+        if (this.limitStatement || this.offsetStatement)
+            throw new BatchingIncompatibleWithLimitOrOffset();
+        if (lock) {
+            // the attributes form never consumes the records it claims, so its
+            // preloads would be pure wasted queries run while every row in the
+            // batch is exclusively locked; the callback form keeps them, since the
+            // callback may consume the preloaded associations
+            const baseQuery = cb ? this : this.clone({ preloadStatements: {}, preloadOnStatements: {} });
+            return await baseQuery.lockedUpdate(cb
+                ? // the callback receives a clone of the claimed record, so that only
+                    // the attributes it *returns* are written: the per-instance write is
+                    // dirty-state-based, and mutations made directly on the record
+                    // Dream holds would otherwise ride along with the save
+                    (record) => cb(record['clone']())
+                : () => attributesOrCb, { skipHooks }, resolvedBatchSize);
+        }
+        if (!cb && skipHooks)
+            return await this.updateWithoutCallingModelHooks(attributesOrCb);
         let counter = 0;
         await this.findEach(async (result) => {
+            // as on the locked path, the callback receives a clone, so only the
+            // attributes it returns are written
+            const attributes = cb
+                ? await cb(result['clone']())
+                : attributesOrCb;
+            // null is not part of the callback's advertised contract, but it is
+            // the natural untyped-JS skip idiom; treat it as a skip rather than
+            // letting it crash the per-instance write mid-run
+            if (attributes == null)
+                return;
             const subquery = this.dreamTransaction
                 ? result.txn(this.dreamTransaction)
                 : result;
-            await subquery.update(attributes);
+            await subquery.update(attributes, skipHooks ? { skipHooks } : undefined);
             counter++;
+        }, {
+            batchSize: resolvedBatchSize,
         });
         return counter;
     }
+    /**
+     * @internal
+     *
+     * The compare-and-set implementation behind `update(attributes, { lock: true })`,
+     * driven by {@link Query.lockedBatches}, which owns the keyset cursor, the
+     * pluck/claim two-step, and the transaction dispatch.
+     *
+     * Each claimed record is handed to `cb`, which returns the attributes to
+     * write for it, or a nullish value to skip it. The attributes form is the
+     * constant-callback case (a callback ignoring the record and always
+     * returning the same attributes), which is how the two forms share this
+     * implementation. (`update` hands the user's own callback a clone of each
+     * claimed record, so only the returned attributes reach the write below —
+     * see the dispatch in {@link Query.update}.)
+     *
+     * The count is the number of claimed records the callback returned
+     * attributes for: records attempted but not claimed (lost races) never
+     * reach the callback, and claimed records the callback skipped are not
+     * counted. For the attributes form the callback is total, so the count
+     * degenerates to records claimed and submitted for writing. (A record whose
+     * write turns out to be a no-op still counts: the instance path returns
+     * without issuing SQL when nothing is dirty.)
+     *
+     * Each claimed record is written via the ordinary per-instance update, so
+     * hooks (unless `skipHooks`), custom setters, and virtual/encrypted
+     * attribute preprocessing behave exactly as in a plain instance update.
+     *
+     * No join-load guard is needed here: update's own joins guards have already
+     * thrown on every join-load query (leftJoinPreload always carries left-join
+     * statements).
+     */
+    async lockedUpdate(cb, { skipHooks }, batchSize) {
+        return await this.lockedBatches(batchSize, async (claimed, txn) => {
+            let written = 0;
+            for (const record of claimed) {
+                const attributes = await cb(record);
+                // null is not part of the callback's advertised contract, but it is
+                // the natural untyped-JS skip idiom; treat it as a skip rather than
+                // letting it crash the per-instance write mid-batch
+                if (attributes == null)
+                    continue;
+                const inTransaction = record.txn(txn);
+                await inTransaction.update(attributes, skipHooks ? { skipHooks } : undefined);
+                written++;
+            }
+            return written;
+        });
+    }
     async updateWithoutCallingModelHooks(attributes) {
         return await this.dbDriverInstance().update(attributes);
     }

package/dist/esm/src/errors/BatchingIncompatibleWithLimitOrOffset.js

@@ -0,0 +1,25 @@
+export default class BatchingIncompatibleWithLimitOrOffset extends Error {
+    get message() {
+        // batched iteration re-applies the Query's conditions to every batch
+        // window, so a limit or offset would be re-applied per batch — skipping or
+        // truncating rows inside each window — rather than bounding the run as a
+        // whole; and a single-statement set update has no way to express a limit
+        // or offset in SQL. Silently clearing them instead would touch rows the
+        // caller asked to scope out, so fail loudly before any row is touched.
+        return `
+A batched or set-write operation was called on a query carrying a \`limit\`
+or \`offset\`.
+
+These operations process the entire matched set, so a limit or offset cannot
+be honored: batched iteration re-applies the query's conditions to every
+batch window, where the limit or offset would be re-applied per batch —
+silently skipping or truncating rows within each window instead of bounding
+the run as a whole — and a single-statement set update cannot express a
+limit or offset in SQL at all.
+
+fix:
+  remove the \`limit\`/\`offset\` from the query, and scope the affected rows
+  with \`where\` conditions instead
+`;
+    }
+}

package/dist/esm/src/errors/InvalidMigrationTableName.js

@@ -0,0 +1,30 @@
+export default class InvalidMigrationTableName extends Error {
+    migrationName;
+    table;
+    /**
+     * @param migrationName - the migration name the generator was invoked with
+     * @param table - the table name the generator resolved for it
+     */
+    constructor(migrationName, table) {
+        super();
+        this.migrationName = migrationName;
+        this.table = table;
+    }
+    get message() {
+        return `
+generating the migration '${this.migrationName}' resolved the table name:
+  ${this.table}
+
+which is not a valid table name. The table name is written into the generated
+migration, which 'db:migrate' later executes, so it must be a plain
+identifier: lowercase letters, digits and underscores only.
+
+A standalone 'g:migration' takes the table from the text after the first
+'-to-'/'-from-' in the name, snake-cased and pluralized, e.g.:
+  add-phone-to-users
+
+A model generator takes it from the model name, or verbatim from
+'--table-name'.
+    `;
+    }
+}

package/dist/esm/src/errors/MissingRequiredLockOptionForUpdateCallback.js

@@ -0,0 +1,16 @@
+export default class MissingRequiredLockOptionForUpdateCallback extends Error {
+    get message() {
+        return `
+When passing a callback to Query#update, the options object and its \`lock\`
+key are required, and \`lock\` must be an explicit boolean:
+
+  await User.query().update(user => ({ ... }), { lock: true })
+  await User.query().update(user => ({ ... }), { lock: false })
+
+\`lock: true\` runs the callback on each record after re-selecting it under an
+exclusive row lock (a compare-then-write). \`lock: false\` actively opts out of
+locking: the callback runs on each record with no lock and no compare-and-set
+guarantee. Requiring the boolean keeps that choice visible at the call site.
+`;
+    }
+}

package/dist/esm/src/errors/NoColumnsToAlterMigration.js

@@ -1,17 +1,49 @@
 export default class NoColumnsToAlterMigration extends Error {
     table;
     alterDirection;
-    constructor(table, alterDirection) {
+    migrationName;
+    marker;
+    /**
+     * @param table - the table the migration resolved to
+     * @param alterDirection - 'add' for a `-to-` migration, 'remove' for a `-from-` migration
+     * @param migrationName - the migration name the user typed, when available. Only
+     * the standalone `g:migration` flow knows it, so the message degrades to a
+     * table-only explanation when it is omitted.
+     * @param marker - the `-to-`/`-from-` marker that matched within `migrationName`
+     */
+    constructor(table, alterDirection, migrationName, marker) {
         super();
         this.table = table;
         this.alterDirection = alterDirection;
+        this.migrationName = migrationName;
+        this.marker = marker;
     }
     get message() {
-        return `
-no valid columns to ${this.alterDirection === 'remove' ? 'drop from' : 'add to'} table '${this.table}' in this alter migration.
+        const verb = this.alterDirection === 'remove' ? 'drop from' : 'add to';
+        if (!this.migrationName || !this.marker) {
+            return `
+no valid columns to ${verb} table '${this.table}' in this alter migration.
 
 Pass at least one column declaration with a resolvable type, e.g.:
   name:string
+    `;
+        }
+        return `
+no valid columns to ${verb} table '${this.table}' in this alter migration.
+
+The migration name '${this.migrationName}' contains '${this.marker}', which selected that
+table and the '${this.alterDirection}' direction: everything after the marker's first
+occurrence - wherever in the name that falls - is snake-cased and pluralized
+into the table name. A '-to-' anywhere in the name wins, even when a '-from-'
+appears earlier; '-from-' applies only when the name contains no '-to-' at all.
+
+Either:
+
+  - pass at least one column declaration with a resolvable type, e.g.:
+      name:string
+
+  - or, if this was meant to be a hand-written migration, rename it so that
+    neither '-to-' nor '-from-' appears anywhere in the name.
     `;
     }
 }