@rvoh/dream 2.24.1 → 2.26.0

package/dist/esm/src/serializer/helpers/inferSerializerFromDreamOrViewModel.js

@@ -9,33 +9,51 @@ import expandStiClasses from '../../helpers/sti/expandStiClasses.js';
 import uniq from '../../helpers/uniq.js';
 import isDreamSerializer from './isDreamSerializer.js';
 export const DEFAULT_SERIALIZER_KEY = 'default';
-export default function inferSerializerFromDreamOrViewModel(obj, serializerKey = DEFAULT_SERIALIZER_KEY) {
+/**
+ * `resolutionContext` says how resolution reached `obj` — the `rendersOne`/`rendersMany` edge that
+ * led here, and the STI base it was expanded from. It is threaded down purely so that the errors
+ * below can name the route instead of only the class, and it is optional so that a caller with no
+ * route to describe (and every existing caller outside this repo) is unaffected. See
+ * `SerializerResolutionContext`.
+ */
+export default function inferSerializerFromDreamOrViewModel(obj, serializerKey = DEFAULT_SERIALIZER_KEY, resolutionContext) {
     if (!obj)
         return null;
     const serializers = obj.serializers;
     if (!serializers)
-        throw new MissingSerializersDefinition(obj);
+        throw new MissingSerializersDefinition(obj, serializerKey, resolutionContext);
     const serializerOrGlobalName = serializers[serializerKey];
     if (!serializerOrGlobalName)
-        throw new MissingSerializersDefinitionForKey(obj, serializerKey);
+        throw new MissingSerializersDefinitionForKey(obj, serializerKey, resolutionContext);
     if (isDreamSerializer(serializerOrGlobalName))
         return serializerOrGlobalName;
     const globalName = serializerOrGlobalName;
     const dreamApp = DreamApp.getOrFail();
     const serializer = dreamApp.serializers[globalName];
     if (!serializer)
-        throw new NoGlobalSerializerForSpecifiedKey(obj, serializerKey, globalName);
+        throw new NoGlobalSerializerForSpecifiedKey(obj, serializerKey, globalName, resolutionContext);
     if (!isDreamSerializer(serializer))
-        throw new NonDreamSerializerDerivedFromGlobalSerializerForSpecifiedKey(obj, serializerKey, globalName, serializer);
+        throw new NonDreamSerializerDerivedFromGlobalSerializerForSpecifiedKey(obj, serializerKey, globalName, serializer, resolutionContext);
     return serializer;
 }
-export function inferSerializersFromDreamClassOrViewModelClass(classDef, serializerKey = undefined) {
+export function inferSerializersFromDreamClassOrViewModelClass(classDef, serializerKey = undefined, resolutionContext) {
     if (!classDef)
         return [];
     const classes = expandStiClasses(classDef);
-    const serializers = classes.map(classDef => inferSerializerFromDreamOrViewModel(classDef.prototype, serializerKey));
+    // This is the one place that knows *whether* the class an error ends up naming came from STI
+    // expansion: below this line the class the caller passed is gone, replaced by one child per
+    // iteration, and every downstream error names a child. Identity rather than `isSTIBase` because
+    // `classDef` may be a ViewModelClass, which `expandStiClasses` hands straight back.
+    const expandedFromStiBase = classes.length !== 1 || classes[0] !== classDef;
+    const childResolutionContext = expandedFromStiBase
+        ? { ...resolutionContext, stiBase: stiBaseName(classDef) }
+        : resolutionContext;
+    const serializers = classes.map(classDef => inferSerializerFromDreamOrViewModel(classDef.prototype, serializerKey, childResolutionContext));
     return uniq(compact(serializers));
 }
+function stiBaseName(classDef) {
+    return classDef.sanitizedName ?? classDef.name;
+}
 /**
  * As `inferSerializersFromDreamClassOrViewModelClass`, but guarantees a non-empty result.
  *
@@ -51,9 +69,9 @@ export function inferSerializersFromDreamClassOrViewModelClass(classDef, seriali
  * preload-path building and serialization display — so that they raise one typed error between
  * them.
  */
-export function inferSerializersFromDreamClassOrViewModelClassOrFail(classDef, serializerKey) {
-    const serializers = inferSerializersFromDreamClassOrViewModelClass(classDef, serializerKey);
+export function inferSerializersFromDreamClassOrViewModelClassOrFail(classDef, serializerKey, resolutionContext) {
+    const serializers = inferSerializersFromDreamClassOrViewModelClass(classDef, serializerKey, resolutionContext);
     if (serializers.length === 0)
-        throw new NoSerializersResolvedForKey(classDef, serializerKey);
+        throw new NoSerializersResolvedForKey(classDef, serializerKey, resolutionContext);
     return serializers;
 }

package/dist/esm/src/serializer/helpers/serializerForAssociatedClass.js

@@ -28,5 +28,10 @@ export function serializerForAssociatedClass(object, associationName, options) {
     // would flatten. Unioning every child's serializer here — which is what buildSerializerPreloadPaths
     // does for preload paths — is meaningless: exactly one set of keys can be flattened into the
     // payload.
-    return inferSerializersFromDreamClassOrViewModelClass(associatedClass, options.serializerKey)[0] ?? null;
+    return (inferSerializersFromDreamClassOrViewModelClass(associatedClass, options.serializerKey, {
+        // Reached only from SerializerRenderer's rendersOne branch, so the edge type is fixed. No
+        // declaring serializer: the renderer holds the rendered attribute, not the serializer that
+        // declared it.
+        edge: { type: 'rendersOne', associationName },
+    })[0] ?? null);
 }

package/dist/esm/src/serializer/helpers/serializerGlobalName.js

@@ -0,0 +1,16 @@
+/**
+ * @internal
+ *
+ * The single reader of a serializer's `globalName`.
+ *
+ * Serializers are plain functions; `globalName` is stamped onto them by `importSerializers` when the
+ * app loads them, so the property is not on any serializer type and every reader would otherwise
+ * have to invent its own cast — three different spellings of it existed before this helper.
+ *
+ * `undefined` is a legitimate answer: a serializer built inline (a spec, or a `{ serializer }`
+ * option) is never stamped. Callers decide what that means for them — the resolution-context message
+ * simply drops the declarer.
+ */
+export default function serializerGlobalName(serializer) {
+    return serializer.globalName;
+}

package/dist/types/src/Dream.d.ts

@@ -8,7 +8,7 @@ import LoadBuilder from './dream/LoadBuilder.js';
 import Query from './dream/Query.js';
 import { OnStatementForSpecificColumns, PassthroughOnClause, WhereStatement } from './types/associations/shared.js';
 import { AssociationTableNames, DbConnectionType } from './types/db.js';
-import { AllDefaultScopeNames, AssociationNameToDream, AttributeKeys, CreateOrFindByExtraOpts, DefaultOrNamedScopeName, DreamAssociationNames, DreamAssociationNamesWithoutRequiredOnClauses, DreamAssociationNamesWithPassthroughOnClauses, DreamAssociationNamesWithRequiredOnClauses, DreamAttributes, DreamBelongsToAssociationNames, DreamColumnNames, DreamHasManyAssociationNames, DreamHasOneAssociationNames, DreamModelAssociationNames, DreamParamSafeColumnNames, DreamPrimaryKeyType, DreamSerializerKey, FindablePropertiesForClass, GlobalModelNames, GlobalSerializerName, JoinAndStatements, OrderDir, PassthroughColumnNames, PassthroughOnClauseKeys, PluckEachArgs, PrimaryKeyForFind, RequiredOnClauseKeys, TableColumnNames, UpdateableAssociationProperties, UpdateableProperties, UpdateablePropertiesForClass, UpdateOrCreateByExtraOpts } from './types/dream.js';
+import { AllDefaultScopeNames, AssociationNameToDream, AttributeKeys, CreateOrFindByExtraOpts, DefaultOrNamedScopeName, DreamAssociationNames, DreamAssociationNamesWithoutRequiredOnClauses, DreamAssociationNamesWithPassthroughOnClauses, DreamAssociationNamesWithRequiredOnClauses, DreamAttributes, DreamBelongsToAssociationNames, DreamColumnNames, DreamHasManyAssociationNames, DreamHasOneAssociationNames, DreamModelAssociationNames, DreamPrimaryKeyType, DreamSerializerKey, FindablePropertiesForClass, GlobalModelNames, GlobalSerializerName, JoinAndStatements, OrderDir, PassthroughColumnNames, PassthroughOnClauseKeys, PluckEachArgs, PrimaryKeyForFind, RequiredOnClauseKeys, TableColumnNames, UpdateableAssociationProperties, UpdateableProperties, UpdateablePropertiesForClass, UpdateOrCreateByExtraOpts } from './types/dream.js';
 import { BaseModelColumnTypes, CursorPaginatedDreamQueryOptions, CursorPaginatedDreamQueryResult, DefaultQueryTypeOptions, FindEachOpts, LoadForModifierFn, PaginatedDreamQueryOptions, PaginatedDreamQueryResult, QueryWithJoinedAssociationsType, QueryWithJoinedAssociationsTypeAndNoPreload } from './types/query.js';
 import { DreamModelSerializerType, SimpleObjectSerializerType } from './types/serializer.js';
 import { ValidationType } from './types/validation.js';
@@ -458,9 +458,15 @@ export default class Dream {
      *   * foreign key fields for belongs to associations (these should usually be verified before being set)
      *   * type fields corresponding to polymorphic associations
      *
+     * @internal
+     *
+     * Not part of the public API. Psychic reaches it through the bracketed
+     * back-door (`dreamClass['paramSafeColumnsOrFallback']()`), the same escape
+     * hatch used for other Dream internals such as `virtualAttributes`.
+     *
      * @returns A subset of columns for the given dream class
      */
-    static paramSafeColumnsOrFallback<T extends typeof Dream, I extends InstanceType<T>, ParamSafeColumnsOverride extends InstanceType<T>['paramSafeColumns' & keyof InstanceType<T>] extends never ? undefined : InstanceType<T>['paramSafeColumns' & keyof InstanceType<T>] & string[], ReturnVal extends ParamSafeColumnsOverride extends string[] ? Extract<DreamParamSafeColumnNames<I>, ParamSafeColumnsOverride[number] & DreamParamSafeColumnNames<I>>[] : DreamParamSafeColumnNames<I>[]>(this: T): ReturnVal;
+    private static paramSafeColumnsOrFallback;
     private static defaultParamSafeColumns;
     /**
      * @internal

package/dist/types/src/cli/index.d.ts

@@ -23,7 +23,7 @@ export declare const columnsWithTypesDescriptionForStiChild: string;
  * example that drifts from what the generator actually produces then fails the
  * suite instead of shipping.
  */
-export declare const migrationNameArgumentDescription = "Kebab-case name describing the change. A -to-<table_name>\n                  anywhere in the name \u2014 not just at the end \u2014 auto-generates\n                  an add-columns alterTable scaffold for that table;\n                  -from-<table_name> generates a remove-columns scaffold, but\n                  only when the name contains no -to- at all. The text after\n                  the marker's first occurrence is snake-cased and pluralized\n                  into the table name, so add-a-to-b-to-cs targets b_to_cs. A\n                  hand-written migration must avoid both strings anywhere in\n                  its name.\n                  \n                  Examples:\n                    add-phone-to-users phone:encrypted      # scaffolds alterTable('users', ...)\n                    remove-status-from-posts status:string  # scaffolds alterTable('posts', ...)\n                    create-many-to-many-posts-users         # WRONG: selects 'many_posts_users'\n                      # -to- inside \"many-to-many\" matches: with no columns\n                      # this errors; with columns it silently scaffolds it\n                    create-posts-users-join-table           # correct: no marker match\n                      # scaffolds alterTable('<table-name>') to hand-edit";
+export declare const migrationNameArgumentDescription = "Kebab-case name describing the change. A -to-<table_name>\n                  anywhere in the name \u2014 not just at the end \u2014 auto-generates\n                  an add-columns alterTable scaffold for that table;\n                  -from-<table_name> generates a remove-columns scaffold, but\n                  only when the name contains no -to- at all. The text after\n                  the marker's first occurrence is snake-cased and pluralized\n                  into the table name, so add-a-to-b-to-cs targets b_to_cs. A\n                  hand-written migration must avoid both strings anywhere in\n                  its name.\n                  \n                  Examples:\n                    add-phone-to-users phone:encrypted      # scaffolds alterTable('users', ...)\n                    remove-status-from-posts status:string  # scaffolds alterTable('posts', ...)\n                    create-many-to-many-posts-users         # WRONG: selects 'many_posts_users'\n                      # -to- inside \"many-to-many\" matches: with no columns\n                      # this errors; with columns it silently scaffolds it\n                    create-posts-users-join-table           # correct: no marker match\n                      # with no columns, generates empty up/down methods to\n                      # write by hand; with columns, scaffolds\n                      # alterTable('<table-name>') to hand-edit";
 export default class DreamCLI {
     /**
      * Starts the Dream console

package/dist/types/src/dream/Query.d.ts

@@ -27,6 +27,7 @@ export default class Query<DreamInstance extends Dream, QueryTypeOpts extends Re
     static readonly BATCH_SIZES: {
         FIND_EACH: number;
         LOCKED_DESTROY: number;
+        LOCKED_UPDATE: number;
         PLUCK_EACH: number;
         PLUCK_EACH_THROUGH: number;
     };
@@ -317,10 +318,16 @@ export default class Query<DreamInstance extends Dream, QueryTypeOpts extends Re
      * 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`
      */
     findEach(this: Query<DreamInstance, QueryTypeOpts>, cb: (instance: DreamInstance) => void | Promise<void>, { batchSize }?: {
         batchSize?: number;
@@ -639,6 +646,12 @@ export default class Query<DreamInstance extends Dream, QueryTypeOpts extends Re
      * // [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<Q extends Query<DreamInstance, any>, Incompatible extends Q['queryTypeOpts'] extends Readonly<{
@@ -655,6 +668,12 @@ export default class Query<DreamInstance extends Dream, QueryTypeOpts extends Re
      * // [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<Q extends Query<DreamInstance, any>, Incompatible extends Q['queryTypeOpts'] extends Readonly<{
@@ -978,8 +997,14 @@ export default class Query<DreamInstance extends Dream, QueryTypeOpts extends Re
      * // 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`
      */
     pluckEach<Q extends Query<DreamInstance, QueryTypeOpts>, DB extends DreamInstance['DB'], const ColumnNames extends ColumnNamesAccountingForJoinedAssociations<Q['queryTypeOpts']['joinedAssociations'], DB, QueryTypeOpts['rootTableName'], QueryTypeOpts['rootTableAlias']>[], CbArgTypes extends NamespacedOrBaseModelColumnTypes<ColumnNames, Q, DreamInstance>>(this: Q, ...args: PluckEachArgs<ColumnNames, CbArgTypes>): Promise<void>;
     /**
@@ -1307,20 +1332,27 @@ export default class Query<DreamInstance extends Dream, QueryTypeOpts extends Re
      *   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`
      */
     destroy({ skipHooks, cascade, lock, batchSize, }?: {
         skipHooks?: boolean | undefined;
@@ -1331,37 +1363,52 @@ export default class Query<DreamInstance extends Dream, QueryTypeOpts extends Re
     /**
      * @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.)
+     */
+    private lockedDestroy;
+    /**
+     * @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.
      */
-    private lockedDestroy;
+    private lockedBatches;
     /**
      * Destroys all records matching the Query,
      * ignoring the SoftDelete decorator and
@@ -1380,15 +1427,20 @@ export default class Query<DreamInstance extends Dream, QueryTypeOpts extends Re
      * // 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`
      */
     reallyDestroy({ skipHooks, cascade, lock, batchSize, }?: {
         skipHooks?: boolean;
@@ -1408,12 +1460,19 @@ export default class Query<DreamInstance extends Dream, QueryTypeOpts extends Re
      * // 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`
      */
     undestroy({ cascade, skipHooks, }?: {
         cascade?: boolean;
@@ -1443,15 +1502,232 @@ export default class Query<DreamInstance extends Dream, QueryTypeOpts extends Re
      * await User.where({ email: ops.ilike('%burpcollaborator%') }).update({ email: null })
      * // 12
      * ```
-     * @param attributes - The attributes used to update the records
+     *
+     * Instead of an attributes object, the first argument may be a callback
+     * that derives each record's attributes from the record itself. The
+     * callback (sync or async) receives each matching record and returns the
+     * attributes to write for it, or `undefined` to skip it — a skipped record
+     * gets no write, runs no hooks, and is not counted (a `null` return, from
+     * untyped callers, is treated the same). Only the returned attributes are
+     * written: the callback receives a clone of the record, so mutations made
+     * directly on the received record are discarded rather than riding along
+     * with the write. With a callback, the options object and its `lock` key
+     * are mandatory, and `lock` is a full boolean, so every call site says out
+     * loud whether the callback runs under row locks:
+     *
+     * ```ts
+     * await User.query().update(
+     *   user => (user.email.endsWith('@example.com') ? { name: 'example user' } : undefined),
+     *   { lock: false }
+     * )
+     * ```
+     *
+     * Under `lock: false`, the callback runs once per matching record —
+     * batched reads (`batchSize` defaults to 1000 here), no locks, no claim
+     * step, no compare-and-set guarantee — the right shape for a derived
+     * backfill where racing writers are not a concern. (On a `@ReplicaSafe`
+     * model, these unlocked batch reads may come from a lagging replica,
+     * feeding stale column values into the callback; use `lock: true` to
+     * derive from the freshest committed state — its transactional reads pin
+     * the primary.) Under `lock: true`, the callback runs once per claimed
+     * record, under that record's row lock, inside the batch's transaction,
+     * receiving a clone of the freshly locked read; Dream applies the returned
+     * attributes to the record it holds and writes before the batch commits,
+     * so there is no transaction handle for the caller to forget. (The record
+     * the callback receives is not bound to the batch's transaction — see the
+     * callback bullet below before touching the database from inside a
+     * callback.) That makes the callback form the tool
+     * for serializing writers on state a `WHERE` clause cannot express — for
+     * example an `@Encrypted` column, whose ciphertext changes on every write
+     * and whose plaintext has no column to compare against in the database:
+     *
+     * ```ts
+     * const rotated = await User.where({ id: userId }).update(
+     *   user => (user.secret === expectedSecret ? { secret: newSecret } : undefined),
+     *   { lock: true }
+     * )
+     * // 1 — or 0, if a competing writer got there first (the callback saw a
+     * // different secret and skipped the record)
+     * ```
+     *
+     * With a callback, the returned count is the number of records the
+     * callback returned attributes for: skipped records are not counted, and
+     * under `lock: true` records that lost the race never reach the callback
+     * at all. (As with the attributes form, a write that turns out to be a
+     * no-op still counts — the count means "the callback chose to write", not
+     * "SQL was emitted".)
+     *
+     * The `lock` option turns the update into a guarded (compare-and-set)
+     * update: each record is written only if it still matches the Query at the
+     * moment an exclusive row lock on it is acquired. Use it when the Query's
+     * conditions are the thing being changed and a concurrent writer racing this
+     * call must not have its write clobbered:
+     *
+     * ```ts
+     * const updated = await Order.where({ status: 'pending' })
+     *   .update({ status: 'processing' }, { lock: true })
+     * // 0 — someone else moved every one of them out of 'pending' first
+     * ```
+     *
+     * With `lock: true`, records are processed in batches, and each batch runs
+     * in its own transaction which first re-selects that batch's records with an
+     * exclusive row lock and then updates them before committing. Because the
+     * database re-checks the Query's conditions after acquiring each row lock, a
+     * record a concurrent transaction has already moved out of the Query drops
+     * out of the locked read and is never updated. The returned count is the
+     * number of records claimed and submitted for writing, so a caller can
+     * detect that it lost a race by comparing the count against what it
+     * expected. (A claimed record whose write turns out to be a no-op — the
+     * attributes already match, or a hook cleared every dirty attribute — still
+     * counts; the count is not a guarantee that SQL was emitted per counted
+     * record.)
+     *
+     * Things to know before relying on it:
+     *
+     * - **The guarantee is per batch, not set-wide.** A run spanning more than
+     *   one batch can win a race in batch 1 and lose one in batch 2; nothing
+     *   holds the whole matched set still for the duration of the run. Sharing
+     *   one transaction across every batch — by threading a transaction onto the
+     *   Query itself, `Order.query().txn(txn).where({ ... }).update({ ... },
+     *   { lock: true })` — buys two things: the updates become all-or-nothing (a
+     *   rollback undoes the whole run), and the row locks taken by every batch
+     *   are held until you commit. It does **not** extend the compare-and-set to
+     *   the part of the set the run has not reached yet: under READ COMMITTED
+     *   each statement takes a fresh snapshot, so a record moved out of the
+     *   Query between batch 1 and batch 2 still drops out of batch 2's locked
+     *   read. A genuinely set-wide guarantee needs REPEATABLE READ /
+     *   SERIALIZABLE, or a single locking statement over the whole set.
+     * - **Only a transaction carried by the Query is shared.** Merely wrapping
+     *   the call in `Model.transaction(...)` does not thread that transaction
+     *   onto the Query — `Dream.transaction` establishes no ambient transaction,
+     *   it only hands a `txn` to your callback — so each batch would open its
+     *   own transaction on a different pooled connection. Worse, if the
+     *   surrounding transaction has already written to any of the matched rows,
+     *   each batch's locked read blocks on locks the surrounding transaction
+     *   holds while that transaction awaits the update: a cycle across two
+     *   connections, which Postgres's deadlock detector cannot see, so it hangs
+     *   rather than aborting. Always pass the transaction with `.txn(txn)`.
+     * - **Behavior above READ COMMITTED differs.** The drop-out-of-the-result
+     *   behavior described above is READ COMMITTED (Postgres's default). Under
+     *   REPEATABLE READ or SERIALIZABLE, the same race raises a serialization
+     *   failure instead of silently returning a lower count. Both are safe; only
+     *   one of them is quiet.
+     * - **`batchSize` defaults to 10 here**, not `findEach`'s 1000, and the
+     *   default is deliberately small. Every row in a batch stays locked for the
+     *   whole batch, including the time spent running each record's hooks — and,
+     *   on the callback form, the time spent running the Query's `preload`
+     *   queries, which are fetched inside the lock window (the attributes form
+     *   strips preloads, which it never consumes) — so an oversized batch blocks
+     *   unrelated writers touching those rows and surfaces as timeouts somewhere
+     *   else in the application, which is very hard to trace back to this
+     *   update. Too small a batch, by contrast, only slows down this call, which
+     *   you can see and fix. Lower it further for models with expensive update
+     *   hooks.
+     * - **The callback must not write to the database.** The record handed to
+     *   the callback is not bound to the batch's transaction: a write through it
+     *   (e.g. `await record.update(...)`) goes out on a different pooled
+     *   connection and blocks on the batch's own row locks while the batch
+     *   transaction waits on the callback — a cycle across two connections that
+     *   the database's deadlock detector cannot see, so with no `lock_timeout`
+     *   the run hangs indefinitely and pins both connections. Reads through the
+     *   record (`reload`, `associationQuery`, ...) likewise run on a separate
+     *   connection and snapshot. Derive the attributes and return them; Dream
+     *   performs the write inside the batch's transaction.
+     * - **`lock: false` can throw mid-run when racing a deleter.** On the
+     *   unlocked paths, a matched record that a concurrent transaction destroys
+     *   between a batch's read and that record's write aborts the run with an
+     *   error: earlier batches stay committed, and no count is returned. Use
+     *   `lock: true` when deleters may race the update — claimed rows are held
+     *   under their locks until written.
+     * - **A `limit` or `offset` on the Query is incompatible with `update` on
+     *   every path.** The batched paths re-apply the Query's conditions to each
+     *   batch window, where a limit or offset would skip or truncate rows
+     *   inside every window instead of bounding the run as a whole, and the
+     *   single-statement `skipHooks` attributes form cannot express either in
+     *   its SQL UPDATE. Every form throws rather than silently corrupting the
+     *   windows or ignoring the caller's scope.
+     * - **A batch waits, without bound, for whoever holds the row.** The locked
+     *   read is a plain `FOR UPDATE`: if another transaction already holds a
+     *   lock on one of the batch's rows, this call blocks until that transaction
+     *   ends, holding its own transaction and its pooled connection open the
+     *   whole time. Dream sets no `lock_timeout` or `statement_timeout`, so a
+     *   long-running writer on the other side stalls the run indefinitely and,
+     *   at 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.
+     * - **`skipHooks` composes with `lock`, but stays on the per-instance
+     *   path.** With an attributes object and no `lock`, `skipHooks: true`
+     *   issues a single `UPDATE ... WHERE` statement that writes raw columns.
+     *   With `lock: true`, `skipHooks: true` skips the model hooks on each
+     *   claimed record but still writes through the instance, so custom setters
+     *   — including the setters encrypted attributes encrypt through — run as
+     *   they would for a plain instance update. (Virtual attributes whose
+     *   processing lives in a hook are still skipped, exactly as in an instance
+     *   update with `skipHooks`.) A callback never takes the single-statement
+     *   path: `skipHooks` beside a callback only skips the hooks on each
+     *   per-record write, under `lock: true` and `lock: false` alike.
+     * - **If you are updating a large set and do not need compare-and-set, do
+     *   not pass `lock`.** Plain `update(attributes)` (hooks, no locking) or
+     *   `update(attributes, { skipHooks: true })` (a single statement, no hooks)
+     *   are the right tools for bulk updates.
+     *
+     * @param attributesOrCb - The attributes used to update the records, or a callback receiving each record and returning the attributes to write for it (or `undefined` to skip that record). Passing a callback makes `options` and its `lock` key mandatory
      * @param options - Options for updating the instance
      * @param options.skipHooks - If true, skips applying model hooks. Defaults to false
+     * @param options.lock - If true, each batch is re-selected with an exclusive row lock inside its own transaction before being updated, making the update a compare-and-set. Defaults to false for the attributes form; with a callback there is no default — an explicit boolean is required. One typing asymmetry to know: with an attributes object, an explicit `lock: false` keeps the raw single-statement (`DreamTableSchema`) typing that `skipHooks` uses, so virtual/encrypted attributes type-check only when the options object is omitted entirely or `lock` is `true`
+     * @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 for the unlocked callback form
      * @returns The number of records that were updated
+     * @throws InvalidBatchSize if `batchSize` is not a positive integer
+     * @throws MissingRequiredLockOptionForUpdateCallback if a callback is passed without an options object carrying a boolean `lock`
+     * @throws BatchingIncompatibleWithLimitOrOffset if the query carries a `limit` or `offset`
      */
+    update(cb: (record: DreamInstance) => UpdateableProperties<DreamInstance> | undefined | Promise<UpdateableProperties<DreamInstance> | undefined>, options: {
+        lock: boolean;
+        batchSize?: number;
+        skipHooks?: boolean;
+    }): Promise<number>;
+    update(attributes: UpdateableProperties<DreamInstance>, options: {
+        lock: true;
+        batchSize?: number;
+        skipHooks?: boolean;
+    }): Promise<number>;
     update(attributes: DreamTableSchema<DreamInstance>, options?: {
         skipHooks?: boolean;
+        lock?: false;
     }): Promise<number>;
     update(attributes: UpdateableProperties<DreamInstance>): Promise<number>;
+    /**
+     * @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).
+     */
+    private lockedUpdate;
     private updateWithoutCallingModelHooks;
     private invertOrder;
 }

package/dist/types/src/errors/BatchingIncompatibleWithLimitOrOffset.d.ts

@@ -0,0 +1,3 @@
+export default class BatchingIncompatibleWithLimitOrOffset extends Error {
+    get message(): string;
+}