@rvoh/dream 2.21.1 → 2.23.0

package/dist/cjs/src/errors/serializers/NoSerializersResolvedForKey.js

@@ -0,0 +1,30 @@
+/**
+ * Raised when resolving a serializer key against a class yields an empty set of serializers.
+ *
+ * This is an internal-invariant failure, not a misconfiguration: an unresolvable serializer key
+ * raises `MissingSerializersDefinitionForKey` (and a class with no `serializers` getter at all
+ * raises `MissingSerializersDefinition`) while it is being resolved, and STI expansion always
+ * yields at least one class, so there is no supported application shape that reaches this. It is
+ * typed rather than a bare `Error` so that it can be asserted on, and so that the two callers that
+ * guard the invariant raise the same thing.
+ */
+export default class NoSerializersResolvedForKey extends Error {
+    classDef;
+    serializerKey;
+    constructor(classDef, serializerKey) {
+        super();
+        this.classDef = classDef;
+        this.serializerKey = serializerKey;
+    }
+    get message() {
+        const className = this.classDef === null || this.classDef === undefined
+            ? String(this.classDef)
+            : (this.classDef.globalName ?? this.classDef.name);
+        return `
+No serializers resolved for \`${className}\` under serializer key \`${this.serializerKey}\`
+
+This should be impossible — a serializer key that cannot be resolved throws while it is being
+resolved, before reaching here — and indicates a bug in Dream rather than a problem with your
+application. Please report it.`;
+    }
+}

package/dist/cjs/src/ops/index.js

@@ -117,11 +117,27 @@ const ops = {
     /**
      * Creates an `OpsStatement` using the `=` operator for strict equality.
      *
+     * **Array columns:** passing an array means literal array equality — the
+     * whole array is bound as a single parameter, so the column must match
+     * element-for-element, in order. This is the opt-in counterpart to a bare
+     * array in a where clause (`Post.where({ tags: ['a', 'b'] })`), which means
+     * `IN`, and to `ops.any`, which tests for containment of a single element.
+     * Element types are constrained by the column, so an enum array column
+     * rejects a string that is not a member of its enum.
+     *
+     * Note that PostgreSQL defines no equality operator for `json` (as opposed
+     * to `jsonb`), so `ops.equal` against a `json[]` column raises at the
+     * database.
+     *
      * @param equal - The value the column must equal.
      * @returns An `OpsStatement` using the `=` operator.
      *
      * @example
      * User.where({ role: ops.equal('admin') })
+     *
+     * @example
+     * // matches only rows whose tags column is exactly ['a', 'b'], in that order
+     * Post.where({ tags: ops.equal(['a', 'b']) })
      */
     equal: (equal) => new OpsStatement('=', equal),
     /**
@@ -260,6 +276,9 @@ const ops = {
         /**
          * Creates an `OpsStatement` using the `!=` operator for inequality.
          *
+         * **Array columns:** as with `ops.equal`, passing an array compares against
+         * the whole array rather than against its elements.
+         *
          * @param equal - The value the column must not equal.
          * @returns An `OpsStatement` using the `!=` operator.
          *

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

@@ -3,6 +3,7 @@ import MissingSerializersDefinition from '../../errors/serializers/MissingSerial
 import MissingSerializersDefinitionForKey from '../../errors/serializers/MissingSerializersDefinitionForKey.js';
 import NoGlobalSerializerForSpecifiedKey from '../../errors/serializers/NoGlobalSerializerForSpecifiedKey.js';
 import NonDreamSerializerDerivedFromGlobalSerializerForSpecifiedKey from '../../errors/serializers/NonDreamSerializerDerivedFromGlobalSerializerForSpecifiedKey.js';
+import NoSerializersResolvedForKey from '../../errors/serializers/NoSerializersResolvedForKey.js';
 import compact from '../../helpers/compact.js';
 import expandStiClasses from '../../helpers/sti/expandStiClasses.js';
 import uniq from '../../helpers/uniq.js';
@@ -35,3 +36,24 @@ export function inferSerializersFromDreamClassOrViewModelClass(classDef, seriali
     const serializers = classes.map(classDef => inferSerializerFromDreamOrViewModel(classDef.prototype, serializerKey));
     return uniq(compact(serializers));
 }
+/**
+ * As `inferSerializersFromDreamClassOrViewModelClass`, but guarantees a non-empty result.
+ *
+ * The guard is unreachable today, and deliberately not phrased as "no serializer found for key": a
+ * serializer key that a class does not register throws `MissingSerializersDefinitionForKey` (and a
+ * class with no `serializers` getter at all throws `MissingSerializersDefinition`) from inside the
+ * inference above, and `expandStiClasses` always yields at least one class. It exists only so that
+ * a future change to any of those cannot turn an unresolvable serializer key into a silently empty
+ * serializer set — which, for the callers below, means a silently empty preload set and a
+ * `NonLoadedAssociation` at render rather than an error naming the real problem.
+ *
+ * Used by everything that walks a serializer graph rooted on a class rather than an instance —
+ * 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);
+    if (serializers.length === 0)
+        throw new NoSerializersResolvedForKey(classDef, serializerKey);
+    return serializers;
+}

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

@@ -15,5 +15,18 @@ export function serializerForAssociatedClass(object, associationName, options) {
     const associatedClass = association.modelCB();
     if (Array.isArray(associatedClass))
         throw new Error('rendersOne flatten is incompatible with a polymorphic belongs-to association');
+    // Taking the first is only a narrowing when `associatedClass` is an STI base, where
+    // inferSerializersFromDreamClassOrViewModelClass returns one serializer per child sorted by
+    // sanitizedName. It is correct here because there is no associated row: this function is reached
+    // only from SerializerRenderer's `flatten: true` branch for a *null* associated object, so no
+    // child of the base is the right one — the row that would have decided is absent. (rendersMany
+    // never reaches here and does not accept `flatten`.)
+    //
+    // It is observable, though, so it is not "nothing happens": the picked serializer is invoked and
+    // its output spread into the parent's payload, so the parent JSON carries the
+    // alphabetically-first child's flattened keys as nulls, and omits keys only a later-sorting child
+    // 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;
 }

package/dist/esm/src/Dream.js

@@ -19,9 +19,9 @@ import destroyDream from './dream/internal/destroyDream.js';
 import { destroyOptions, reallyDestroyOptions, undestroyOptions, } from './dream/internal/destroyOptions.js';
 import ensureSTITypeFieldIsSet from './dream/internal/ensureSTITypeFieldIsSet.js';
 import findOrCreateBy from './dream/internal/findOrCreateBy.js';
+import mergeSerializerAssociationEdges from './dream/internal/mergeSerializerAssociationEdges.js';
 import printSerializerHierarchyLevel from './dream/internal/printSerializerHierarchyLevel.js';
 import reload from './dream/internal/reload.js';
-import resolveSerializerAssociationEdges from './dream/internal/resolveSerializerAssociationEdges.js';
 import runValidations from './dream/internal/runValidations.js';
 import saveDream from './dream/internal/saveDream.js';
 import { DEFAULT_BYPASS_ALL_DEFAULT_SCOPES, DEFAULT_DEFAULT_SCOPES_TO_BYPASS, DEFAULT_SKIP_HOOKS, } from './dream/internal/scopeHelpers.js';
@@ -48,7 +48,7 @@ import areEqual from './helpers/areEqual.js';
 import cloneDeepSafe from './helpers/cloneDeepSafe.js';
 import isJsonColumn from './helpers/db/types/isJsonColumn.js';
 import notEqual from './helpers/notEqual.js';
-import { inferSerializersFromDreamClassOrViewModelClass } from './serializer/helpers/inferSerializerFromDreamOrViewModel.js';
+import { inferSerializersFromDreamClassOrViewModelClassOrFail } from './serializer/helpers/inferSerializerFromDreamOrViewModel.js';
 export default class Dream {
     DB;
     /**
@@ -542,44 +542,89 @@ export default class Dream {
     }
     static serializationMap(serializerKey) {
         const key = serializerKey || 'default';
-        const serializer = inferSerializersFromDreamClassOrViewModelClass(this, key)[0] ?? null;
-        if (!serializer)
-            throw new Error(`unable to find serializer with key: ${key}`);
-        return this.recursiveSerializationMap(serializer);
+        // Deliberately one serializer: this maps a single serializer's view of the class, and taking
+        // the first is only a narrowing when `this` is an STI base (where
+        // inferSerializersFromDreamClassOrViewModelClass returns one serializer per child, sorted by
+        // sanitizedName). That narrowing is deliberate and differs from `buildSerializerPreloadPaths`
+        // and `displaySerialization` below, both of which union every child's serializer because they
+        // answer "what does a query load / display for this class", not "what does one serializer
+        // render". Nothing in src/ calls
+        // this method; it exists as the single-serializer entry point onto recursiveSerializationMap and
+        // is exercised by spec/unit/dream/serializationMap.spec.ts, which pins the narrowing on an STI
+        // base so that the divergence from displaySerialization is executable rather than only
+        // described here. A caller that wants the union for an STI base wants displaySerialization's
+        // shape, not this one.
+        //
+        // Note that the narrowing is to one serializer of *this* class only: every association this
+        // serializer renders is still walked with the full set of serializers its target resolves to,
+        // so an STI base reached as a target below is unioned.
+        const serializer = inferSerializersFromDreamClassOrViewModelClassOrFail(this, key)[0];
+        return this.recursiveSerializationMap([serializer]);
     }
     static displaySerialization(serializerKey) {
         const key = serializerKey || 'default';
-        const serializer = inferSerializersFromDreamClassOrViewModelClass(this, key)[0] ?? null;
-        if (!serializer)
-            throw new Error(`unable to find serializer with key: ${key}`);
+        /**
+         * When `this` is an STI base, this is one serializer per STI child (deduped), since each child
+         * may register a different serializer under `key`. Every one is walked, because this method
+         * backs `psy i:serialization`, whose purpose is verifying what gets preloaded — and
+         * `preloadFor` unions the preload paths of every child's serializer. Walking only one child's
+         * serializer would print a strict subset of what the query actually loads.
+         */
+        // ...OrFail, rather than the plain inference, so that an empty serializer set raises
+        // NoSerializersResolvedForKey instead of silently printing a class name with nothing under it.
+        // That guard is unreachable today and is documented where it lives; it is shared with
+        // buildSerializerPreloadPaths so that the display and the preload walk raise the same thing.
+        const serializers = inferSerializersFromDreamClassOrViewModelClassOrFail(this, key);
         // eslint-disable-next-line no-console
         console.log(yoctocolors.cyan(this.sanitizedName));
-        // eslint-disable-next-line no-console
-        console.log(yoctocolors.gray(serializer.globalName));
-        return this.recursiveSerializationMap(serializer, {
+        // One line per serializer: for an STI base the displayed tree is the union across its children,
+        // so naming a single child's serializer under the base's own name would misattribute the tree.
+        serializers.forEach(serializer => {
+            // eslint-disable-next-line no-console
+            console.log(yoctocolors.gray(serializer.globalName));
+        });
+        return this.recursiveSerializationMap(serializers, {
             forDisplay: true,
         });
     }
-    static recursiveSerializationMap(serializer, { forDisplay = false, forDisplayDepth = 0, repeatedAssociationTracker = {}, } = {}) {
+    /**
+     * @internal
+     *
+     * Maps the association tree reachable from `serializers` — every serializer that can render this
+     * class at this point in the walk, which is more than one when this class is an STI base. The
+     * serializers are merged into one edge set (see mergeSerializerAssociationEdges) rather than
+     * walked one at a time, so an association several of them render is visited once and the nested
+     * trees of a shared target merge instead of clobbering each other.
+     */
+    static recursiveSerializationMap(serializers, { forDisplay = false, forDisplayDepth = 0, repeatedAssociationTracker = {}, } = {}) {
         const depthTrackerId = this.globalName;
         repeatedAssociationTracker[depthTrackerId] ??= 0;
         if (repeatedAssociationTracker[depthTrackerId] + 1 > RECURSIVE_SERIALIZATION_MAX_REPEATS)
             return {};
         repeatedAssociationTracker[depthTrackerId]++;
-        const edges = resolveSerializerAssociationEdges(this, serializer);
+        const edges = mergeSerializerAssociationEdges(this, serializers);
         const mappedAssociations = edges.reduce((accumulator, edge) => {
+            // An edge with no targets terminates: either a delegatedAttribute (never printed, and
+            // carrying `targets: []` by construction) or an association resolving to no serializer. Its
+            // nestedSerializerInfo is `{}` because this reduce never runs.
             const innerAssociationSerializerInfo = edge.targets.reduce((innerAccumulator, target) => {
-                if (forDisplay && edge.type !== 'delegatedAttribute') {
-                    printSerializerHierarchyLevel({
-                        serializerAssociationType: edge.type,
-                        serializerAssociationName: edge.serializerAssociationName,
-                        associationSerializer: target.serializer,
-                        forDisplayDepth,
-                    });
+                if (forDisplay) {
+                    // One heading per (association, target class), naming every serializer that renders that
+                    // target underneath it, and then — below all of them — the union of their association
+                    // trees, which is what `preloadFor` loads through this association.
+                    //
+                    // The recursion below is a single merged walk of every serializer of the target, so
+                    // there is one tree, not one per child. Grouping the serializer names under a single
+                    // heading is what keeps that honest — repeating the heading per serializer would leave
+                    // the merged tree indented directly beneath the last one's name and attribute every
+                    // sibling's associations to it.
+                    printSerializerHierarchyLevel({ targetSerializers: target.serializers, forDisplayDepth });
                 }
                 return {
                     ...innerAccumulator,
-                    ...target.dreamClass['recursiveSerializationMap'](target.serializer, {
+                    // recursed once per target class with *all* of that class's serializers, so their nested
+                    // trees merge rather than the last one winning a shallow spread
+                    ...target.dreamClass['recursiveSerializationMap'](target.serializers.map(({ serializer }) => serializer), {
                         forDisplay,
                         forDisplayDepth: forDisplayDepth + 1,
                         repeatedAssociationTracker,
@@ -588,7 +633,7 @@ export default class Dream {
             }, {});
             accumulator[edge.associationAs] = {
                 parentDreamClass: this,
-                nestedSerializerInfo: edge.type === 'delegatedAttribute' ? {} : innerAssociationSerializerInfo,
+                nestedSerializerInfo: innerAssociationSerializerInfo,
             };
             return accumulator;
         }, {});
@@ -1330,6 +1375,9 @@ export default class Dream {
      * // User{email: 'goodbye@world'}
      * ```
      *
+     * Records are always visited in ascending primary key order; any `order`
+     * applied to the query is discarded. See {@link Query.findEach} for why.
+     *
      * @param cb - The callback to call for each found record
      * @param opts - Optional parameters for batch processing
      * @param opts.batchSize - the batch size you wish to collect records in. If not provided, it will default to 1000

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

@@ -421,6 +421,9 @@ export default class DreamClassTransactionBuilder {
      * // User{email: 'goodbye@world'}
      * ```
      *
+     * Records are always visited in ascending primary key order; any `order`
+     * applied to the query is discarded. See {@link Query.findEach} for why.
+     *
      * @param cb - The callback to call for each found record
      * @param options.batchSize - The batch size you wish to collect records in. If not provided, it will default to 1000
      * @returns void

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

@@ -3,7 +3,9 @@ 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 InvalidBatchSize from '../errors/InvalidBatchSize.js';
 import LeftJoinPreloadIncompatibleWithFindEach from '../errors/LeftJoinPreloadIncompatibleWithFindEach.js';
+import RowLockIncompatibleWithDistinct from '../errors/RowLockIncompatibleWithDistinct.js';
 import MissingRequiredCallbackFunctionToPluckEach from '../errors/MissingRequiredCallbackFunctionToPluckEach.js';
 import NoUpdateAllOnJoins from '../errors/NoUpdateAllOnJoins.js';
 import NoUpdateOnAssociationQuery from '../errors/NoUpdateOnAssociationQuery.js';
@@ -20,8 +22,26 @@ import ops from '../ops/index.js';
 import buildSerializerPreloadPaths from './internal/buildSerializerPreloadPaths.js';
 import computedPaginatePage from './internal/computedPaginatePage.js';
 import convertDreamClassAndAssociationNameTupleArrayToPreloadArgs from './internal/convertDreamClassAndAssociationNameTupleArrayToPreloadArgs.js';
-// Cache for serializer preload-path results, keyed by "${globalName}:${serializerKey}"
-const extractedNestedPathsCache = new Map();
+/**
+ * Cache for serializer preload-path results, keyed on the root class itself and then the serializer
+ * key. Keying on the class rather than its global name is what makes the cache self-invalidating:
+ * loading a fresh set of model classes into the process yields new class objects, so entries
+ * resolved against the previous ones become unreachable and collectable rather than being served
+ * under a name that now means something else.
+ */
+let extractedNestedPathsCache = new WeakMap();
+/**
+ * @internal
+ *
+ * Drops every memoized preload path. Only needed when a class object that stays in the process has
+ * its `serializers` getter replaced, which the cache cannot detect — specs that install or remove
+ * one around an example. Replacing the model classes themselves needs no call, since the cache
+ * keys on the class object. See `clearResolvedSerializerAssociationEdgesCache`, which has the same
+ * contract and is cleared alongside it.
+ */
+export function clearSerializerPreloadPathsCache() {
+    extractedNestedPathsCache = new WeakMap();
+}
 export default class Query {
     /**
      * @internal
@@ -31,6 +51,10 @@ 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.
+        LOCKED_DESTROY: 10,
         PLUCK_EACH: 10000,
         PLUCK_EACH_THROUGH: 1000,
     };
@@ -398,13 +422,30 @@ export default class Query {
      * records matching the Query have been fetched.
      *
      * ```ts
-     * await User.order('id').findEach(user => {
+     * await User.where({ deletedAt: null }).findEach(user => {
      *   DreamApp.log(user)
      * })
      * // User{id: 1}
      * // User{id: 2}
      * ```
      *
+     * IMPORTANT: `findEach` always iterates in ascending primary key order.
+     * Any `order` applied to the Query is discarded; passing one has no effect
+     * on the order records are visited in.
+     *
+     * This is not a limitation that can be lifted. `findEach` guarantees that
+     * every matching record is visited exactly once, and it delivers that by
+     * paginating on a keyset: each batch selects the next `batchSize` records
+     * with a primary key greater than the last record of the previous batch.
+     * That guarantee only holds over a stable, unique key. Ordering by a
+     * mutable, non-unique column would mean a record whose sort value changed
+     * partway through the iteration could be skipped entirely or visited twice.
+     * ({@link Query.cursorPaginate} can honor an arbitrary order precisely
+     * because a paginated UI tolerates that anomaly; a full traversal cannot.)
+     *
+     * If you need records processed in a particular order, load them with a
+     * regular ordered query instead of `findEach`.
+     *
      * @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
@@ -537,17 +578,30 @@ export default class Query {
      * @returns A Query with all serialization associations preloaded
      */
     preloadFor(serializerKey, modifierFn) {
-        const cacheKey = `${this.dreamClass.globalName}:${serializerKey ?? 'default'}`;
-        let preloadArgs = extractedNestedPathsCache.get(cacheKey);
+        const cacheKey = serializerKey ?? 'default';
+        let pathsBySerializerKey = extractedNestedPathsCache.get(this.dreamClass);
+        if (!pathsBySerializerKey) {
+            pathsBySerializerKey = new Map();
+            extractedNestedPathsCache.set(this.dreamClass, pathsBySerializerKey);
+        }
+        let preloadArgs = pathsBySerializerKey.get(cacheKey);
         if (!preloadArgs) {
             preloadArgs = buildSerializerPreloadPaths(this.dreamClass, serializerKey);
-            extractedNestedPathsCache.set(cacheKey, preloadArgs);
+            pathsBySerializerKey.set(cacheKey, preloadArgs);
         }
-        let query = this;
+        // Rather than calling `preload` once per path (which deep clones the accumulating preload tree
+        // on every call, making this quadratic in the number of paths), clone once, flesh out every
+        // path against the same accumulators, and clone the Query once at the end. Iteration order is
+        // preserved, so a later path's `and` still wins over an earlier path's for a shared prefix.
+        const preloadStatements = cloneDeepSafe(this.preloadStatements);
+        const preloadOnStatements = cloneDeepSafe(this.preloadOnStatements);
         preloadArgs.forEach(dreamClassAndAssociationNameTupleArray => {
-            query = query.preload(...convertDreamClassAndAssociationNameTupleArrayToPreloadArgs(dreamClassAndAssociationNameTupleArray, modifierFn));
+            const args = convertDreamClassAndAssociationNameTupleArrayToPreloadArgs(dreamClassAndAssociationNameTupleArray, modifierFn);
+            // `modifierFn` returning 'omit' prunes the path from the omitted association down, which can
+            // leave nothing to preload; `fleshOutJoinStatements` treats an empty arg list as a no-op.
+            this.fleshOutJoinStatements([], preloadStatements, preloadOnStatements, null, args);
         });
-        return query;
+        return this.clone({ preloadStatements, preloadOnStatements });
     }
     /**
      * Returns a new Query instance, with the provided
@@ -1741,21 +1795,109 @@ export default class Query {
      * // 12
      * ```
      *
+     * ## Guarded (compare-and-set) destroy
+     *
+     * By default, `destroy` reads the matching records and then destroys each of
+     * them, so a concurrent writer can change a record in between — the record is
+     * destroyed even though it no longer matches the Query that selected it.
+     * Passing `lock: true` closes that window, making `destroy` a compare-and-set
+     * the way `update(..., { skipHooks: true })` already is:
+     *
+     * ```ts
+     * const destroyed = await Order.where({ status: 'pending' }).destroy({ 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 destroys 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 destroyed. The returned count is the
+     * number of records actually claimed, so a caller can detect that it lost a
+     * race by comparing the count against what it expected.
+     *
+     * 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({ ... }).destroy({ lock: true })` —
+     *   buys two things: the destroys 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 destroy: 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
+     *   `dependent: 'destroy'` cascade, 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 destroy. Too small a
+     *   batch, by contrast, only slows down this call, which you can see and fix.
+     *   Lower it further for models with deep `dependent: 'destroy'` cascades or
+     *   expensive destroy hooks.
+     * - **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.
+     * - **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
      * @returns The number of records that were removed
+     * @throws InvalidBatchSize if `batchSize` is not a positive integer
      */
-    async destroy({ skipHooks, cascade, } = {}) {
+    async destroy({ skipHooks, cascade, lock, batchSize, } = {}) {
         let counter = 0;
+        // resolve the default before validating: `??` would let an explicit 0
+        // through, and `limit(0)` means "no limit", which would turn a batched
+        // destroy into a single unbounded pass (and, with `lock`, a lock over the
+        // entire matched set)
+        const resolvedBatchSize = batchSize ?? (lock ? Query.BATCH_SIZES.LOCKED_DESTROY : Query.BATCH_SIZES.FIND_EACH);
+        if (!Number.isInteger(resolvedBatchSize) || resolvedBatchSize < 1)
+            throw new InvalidBatchSize(batchSize);
         const options = {
             bypassAllDefaultScopes: this.bypassAllDefaultScopes,
             defaultScopesToBypass: this.defaultScopesToBypass,
             skipHooks,
             cascade,
         };
+        if (lock) {
+            return await this.lockedDestroy(options, resolvedBatchSize);
+        }
         await this.findEach(async (result) => {
             const subquery = this.dreamTransaction
                 ? result.txn(this.dreamTransaction)
@@ -1767,9 +1909,94 @@ export default class Query {
                 await subquery.destroy(options);
             }
             counter++;
+        }, {
+            batchSize: resolvedBatchSize,
         });
         return counter;
     }
+    /**
+     * @internal
+     *
+     * The compare-and-set implementation behind `destroy({ lock: true })`.
+     *
+     * 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
+     * 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.
+     *
+     * 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();
+        // 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();
+        const primaryKey = this.dreamInstance['_primaryKey'];
+        const orderedQuery = this.order(null)
+            .order(this.namespacedPrimaryKey)
+            .limit(batchSize);
+        let counter = 0;
+        // 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;
+        let attemptedCount = 0;
+        do {
+            const batchQuery = lastId === undefined
+                ? orderedQuery
+                : orderedQuery.where({ [primaryKey]: ops.greaterThan(lastId) });
+            const destroyBatch = async (txn) => {
+                const candidateIds = await batchQuery.txn(txn).pluck(this.namespacedPrimaryKey);
+                if (!candidateIds.length)
+                    return { attempted: 0, claimed: 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,
+                    lastId: candidateIds.at(-1),
+                };
+            };
+            const results = this.dreamTransaction
+                ? await destroyBatch(this.dreamTransaction)
+                : await this.dreamClass.transaction(async (txn) => await destroyBatch(txn));
+            counter += results.claimed;
+            attemptedCount = results.attempted;
+            lastId = results.lastId;
+        } while (attemptedCount > 0 && attemptedCount === batchSize);
+        return counter;
+    }
     /**
      * Destroys all records matching the Query,
      * ignoring the SoftDelete decorator and
@@ -1791,12 +2018,15 @@ export default class Query {
      * @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
      * @returns The number of records that were removed
+     * @throws InvalidBatchSize if `batchSize` is not a positive integer
      */
-    async reallyDestroy({ skipHooks, cascade, } = {}) {
-        return await this.clone({ shouldReallyDestroy: true }).destroy({ skipHooks, cascade });
+    async reallyDestroy({ skipHooks, cascade, lock, batchSize, } = {}) {
+        return await this.clone({ shouldReallyDestroy: true }).destroy({ skipHooks, cascade, lock, batchSize });
     }
     /**
      * Undestroys a SoftDelete model, unsetting