@rvoh/dream 2.21.1 → 2.23.0

package/dist/esm/src/dream/internal/resolveSerializerAssociationEdges.js

@@ -1,19 +1,78 @@
-import MissingSerializersDefinition from '../../errors/serializers/MissingSerializersDefinition.js';
 import compact from '../../helpers/compact.js';
 import { inferSerializersFromDreamClassOrViewModelClass } from '../../serializer/helpers/inferSerializerFromDreamOrViewModel.js';
+/**
+ * Keyed on the two arguments. Weak on both, so an entry is collectable once either the Dream class
+ * or the serializer is. The cached arrays are handed out by reference and must be treated as
+ * read-only by callers.
+ */
+let resolvedEdgesCache = new WeakMap();
+/**
+ * @internal
+ *
+ * Drops every memoized edge set. Only needed when a class object that stays in the process has its
+ * `serializers` getter replaced, which the memo cannot detect — specs that install or remove one
+ * around an example. Replacing the model classes themselves needs no call, since the memo keys on
+ * the class and serializer objects and entries resolved against the previous ones become
+ * unreachable.
+ */
+export function clearResolvedSerializerAssociationEdgesCache() {
+    resolvedEdgesCache = new WeakMap();
+}
+/**
+ * @internal
+ *
+ * Resolves the rendersOne/rendersMany/delegatedAttribute attributes of `serializer` to the
+ * associations of `dreamClass` they preload, along with the classes and serializers each one
+ * targets.
+ *
+ * Memoized on its two arguments, because every call rebuilds a throwaway serializer builder and
+ * re-infers the serializers of every association target, and the traversal in
+ * buildSerializerPreloadPaths revisits the same (class, serializer) pair many times.
+ *
+ * The two arguments are not the function's only inputs, though: resolving a target's serializers
+ * also reads that target's `serializers` getter, the STI children registered on it, and the
+ * DreamApp serializer registry. Loading a fresh set of classes replaces the keys along with that
+ * state, so the memo follows it. Mutating a `serializers` getter in place does not, and needs
+ * `clearResolvedSerializerAssociationEdgesCache` — see there.
+ */
 export default function resolveSerializerAssociationEdges(dreamClass, serializer) {
+    let cachedForDreamClass = resolvedEdgesCache.get(dreamClass);
+    if (cachedForDreamClass === undefined) {
+        cachedForDreamClass = new WeakMap();
+        resolvedEdgesCache.set(dreamClass, cachedForDreamClass);
+    }
+    const cached = cachedForDreamClass.get(serializer);
+    if (cached !== undefined)
+        return cached;
+    const edges = buildSerializerAssociationEdges(dreamClass, serializer);
+    cachedForDreamClass.set(serializer, edges);
+    return edges;
+}
+function buildSerializerAssociationEdges(dreamClass, serializer) {
     const serializerBuilder = serializer(undefined, undefined);
     const serializerAssociations = serializerBuilder['attributes'].filter(attribute => ['rendersOne', 'rendersMany', 'delegatedAttribute'].includes(attribute.type));
     return compact(serializerAssociations.map(serializerAssociation => {
         const serializerAssociationName = serializerAssociation.targetName ??
             serializerAssociation.name;
+        // `dreamClass` is the class the walk is rooted at, which for an STI base is the base itself
+        // even while `serializer` is one child's serializer. That pairing is safe because an STI child
+        // cannot declare associations of its own — the `STI` class decorator throws
+        // StiChildCannotDefineNewAssociations — so every association a child's serializer can render
+        // is declared on the base and resolves here.
+        //
+        // The one hole: that guard reads decorator metadata and
+        // `associationDeclarationNamesFromMetadata` returns [] when the metadata is absent, which is
+        // also what happens when the `STI` decorator runs without a `context`. Under a TS config that
+        // does not emit decorator metadata the guard silently passes, a child-declared association
+        // survives, and it is dropped *here*, silently, by the return below — the symptom is then a
+        // missing preload and a NonLoadedAssociation at render, not a decorator error naming the real
+        // problem.
         const association = dreamClass['getAssociationMetadata'](serializerAssociationName);
         if (!association)
             return null;
         if (serializerAssociation.type === 'delegatedAttribute') {
             return {
                 associationAs: association.as,
-                sourceDreamClass: dreamClass,
                 type: serializerAssociation.type,
                 serializerAssociationName,
                 targets: [],
@@ -26,17 +85,24 @@ export default function resolveSerializerAssociationEdges(dreamClass, serializer
             ? maybeAssociatedClasses
             : [maybeAssociatedClasses];
         const targets = associatedClasses.flatMap(associatedClass => {
-            let serializers = [];
-            try {
-                serializers = serializerAssociation.options.serializer
-                    ? compact([serializerAssociation.options.serializer])
-                    : compact(inferSerializersFromDreamClassOrViewModelClass(associatedClass, serializerAssociation.options.serializerKey));
-            }
-            catch (error) {
-                if (!(error instanceof MissingSerializersDefinition))
-                    throw error;
-                serializers = [];
-            }
+            // Deliberately unguarded: every serializer that cannot be resolved while building preload
+            // paths throws, and there is no tolerance here by design.
+            //
+            // Why: an unresolvable serializer is a configuration error, and the first query that walks
+            // the serializer graph is where it should be found — no rows, no rendering required.
+            // Swallowing it means the only way to discover a broken `serializerKey` (or a missing
+            // `serializers` getter) is a spec that creates a row of the affected class *and* renders it.
+            //
+            // Why the obvious tolerance is also wrong, not merely undesirable:
+            // `inferSerializersFromDreamClassOrViewModelClass` below expands STI and throws on the
+            // *first* child that fails, so catching here would drop the serializers of *every* child of
+            // this target. An edge with no targets is treated as terminal by buildSerializerPreloadPaths,
+            // so the association is preloaded but never descended into, and a row of a *well-formed*
+            // sibling fails at render with NonLoadedAssociation — an error naming a class that has
+            // nothing wrong with it.
+            const serializers = serializerAssociation.options.serializer
+                ? compact([serializerAssociation.options.serializer])
+                : compact(inferSerializersFromDreamClassOrViewModelClass(associatedClass, serializerAssociation.options.serializerKey));
             return serializers.map(associatedSerializer => ({
                 dreamClass: associatedClass,
                 serializer: associatedSerializer,
@@ -44,7 +110,6 @@ export default function resolveSerializerAssociationEdges(dreamClass, serializer
         });
         return {
             associationAs: association.as,
-            sourceDreamClass: dreamClass,
             type: serializerAssociation.type,
             serializerAssociationName,
             targets,

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

@@ -0,0 +1,19 @@
+export default class InvalidBatchSize extends Error {
+    batchSize;
+    constructor(batchSize) {
+        super();
+        this.batchSize = batchSize;
+    }
+    get message() {
+        return `
+Invalid batchSize provided.
+
+batchSize given:
+  ${String(this.batchSize)}
+
+batchSize must be a positive integer. A batchSize of 0 is especially dangerous,
+since a limit of 0 is treated as "no limit", which would collapse a batched
+operation into a single unbounded pass over the entire matched set.
+`;
+    }
+}

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

@@ -0,0 +1,14 @@
+export default class RowLockIncompatibleWithDistinct extends Error {
+    get message() {
+        // `SELECT DISTINCT ON (...) ... FOR UPDATE` is rejected by the database
+        // ("FOR UPDATE is not allowed with DISTINCT clause"), so fail here, with a
+        // message that names the two incompatible parts, rather than surfacing a
+        // raw driver error from inside a per-batch transaction.
+        return `
+An exclusive row lock was requested on a query that also calls \`distinct\`.
+
+A locked read cannot be combined with DISTINCT. Drop the \`distinct\` call, or
+drop the lock.
+`;
+    }
+}

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

@@ -0,0 +1,14 @@
+export default class RowLockIncompatibleWithJoinLoad extends Error {
+    get message() {
+        // A join load builds its own select statement (one row per joined
+        // association row, later collapsed in memory), which cannot carry the
+        // Query's row lock. Rather than silently performing an unlocked read and
+        // dropping the compare-and-set guarantee the caller asked for, refuse.
+        return `
+An exclusive row lock was requested on a query that also uses leftJoinPreload.
+
+A join-loaded query cannot be locked. Use \`preload\` instead of
+\`leftJoinPreload\`, or drop the lock.
+`;
+    }
+}

package/dist/esm/src/errors/ops/ArrayEqualityRequiresArrayColumn.js

@@ -0,0 +1,23 @@
+export default class ArrayEqualityRequiresArrayColumn extends Error {
+    dreamClass;
+    column;
+    operator;
+    constructor(dreamClass, column, operator) {
+        super();
+        this.dreamClass = dreamClass;
+        this.column = column;
+        this.operator = operator;
+    }
+    get message() {
+        return `
+Attempting to compare an array for equality against a column that is not an
+array in the database:
+
+  ${this.dreamClass.sanitizedName}#${this.column} (operator: ${this.operator})
+
+Whole-array equality (\`=\`, \`!=\`, \`<>\`) is only meaningful for array columns.
+If you meant "is this column one of these values", use \`ops.in([...])\`
+(or a bare array) instead.
+`;
+    }
+}

package/dist/esm/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/esm/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/esm/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/esm/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/types/src/Dream.d.ts

@@ -429,6 +429,15 @@ export default class Dream {
     private static setGlobalName;
     private static serializationMap;
     private static displaySerialization;
+    /**
+     * @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.
+     */
     private static recursiveSerializationMap;
     /**
      * Returns the column names for the given model
@@ -1011,6 +1020,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/types/src/dream/DreamClassTransactionBuilder.d.ts

@@ -384,6 +384,9 @@ export default class DreamClassTransactionBuilder<DreamClass extends typeof Drea
      * // 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/types/src/dream/Query.d.ts

@@ -7,6 +7,16 @@ import { CursorPaginatedDreamQueryOptions, CursorPaginatedDreamQueryResult, Defa
 import { JoinedAssociation, JoinedAssociationsTypeFromAssociations, QueryTypeOptions, VariadicJoinsArgs, VariadicLeftJoinLoadArgs, VariadicLoadArgs } from '../types/variadic.js';
 import DreamTransaction from './DreamTransaction.js';
 import QueryDriverBase from './QueryDriver/Base.js';
+/**
+ * @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 declare function clearSerializerPreloadPathsCache(): void;
 export default class Query<DreamInstance extends Dream, QueryTypeOpts extends Readonly<QueryTypeOptions> = DefaultQueryTypeOptions<DreamInstance>> {
     /**
      * @internal
@@ -16,6 +26,7 @@ export default class Query<DreamInstance extends Dream, QueryTypeOpts extends Re
      */
     static readonly BATCH_SIZES: {
         FIND_EACH: number;
+        LOCKED_DESTROY: number;
         PLUCK_EACH: number;
         PLUCK_EACH_THROUGH: number;
     };
@@ -282,13 +293,30 @@ export default class Query<DreamInstance extends Dream, QueryTypeOpts extends Re
      * 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
@@ -1209,17 +1237,131 @@ export default class Query<DreamInstance extends Dream, QueryTypeOpts extends Re
      * // 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
      */
-    destroy({ skipHooks, cascade, }?: {
+    destroy({ skipHooks, cascade, lock, batchSize, }?: {
         skipHooks?: boolean | undefined;
         cascade?: boolean | undefined;
+        lock?: boolean | undefined;
+        batchSize?: number | undefined;
     }): Promise<number>;
+    /**
+     * @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.
+     */
+    private lockedDestroy;
     /**
      * Destroys all records matching the Query,
      * ignoring the SoftDelete decorator and
@@ -1241,13 +1383,18 @@ export default class Query<DreamInstance extends Dream, QueryTypeOpts extends Re
      * @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
      */
-    reallyDestroy({ skipHooks, cascade, }?: {
+    reallyDestroy({ skipHooks, cascade, lock, batchSize, }?: {
         skipHooks?: boolean;
         cascade?: boolean;
+        lock?: boolean;
+        batchSize?: number;
     }): Promise<number>;
     /**
      * Undestroys a SoftDelete model, unsetting

package/dist/types/src/dream/QueryDriver/Base.d.ts

@@ -190,7 +190,28 @@ export default class QueryDriverBase<DreamInstance extends Dream> {
      */
     takeAll(options?: {
         columns?: DreamColumnNames<DreamInstance>[];
+        lock?: boolean;
     }): Promise<DreamInstance[]>;
+    /**
+     * @internal
+     *
+     * Adapter seam for exclusive row locking. Given the select statement about to
+     * be executed, return a statement that additionally acquires an exclusive
+     * lock on each row it returns, held until the enclosing transaction commits
+     * or rolls back (Postgres: `SELECT ... FOR UPDATE OF <table>`).
+     *
+     * This is only ever reached when a caller opts into a locked read (today,
+     * `Query#destroy({ lock: true })`), and only from inside a transaction. The
+     * base implementation throws so that an adapter which has not implemented row
+     * locking fails loud rather than silently performing an unlocked read and
+     * quietly dropping the compare-and-set guarantee the caller asked for.
+     *
+     * @param kyselyQuery - the select statement to lock
+     * @param tableAlias - the alias of the Query's base table; only rows of that
+     * table are locked, so a joined query does not lock unrelated rows and does
+     * not fail on the nullable side of an outer join
+     */
+    applyRowLock(kyselyQuery: SelectQueryBuilder<any, any, any>, tableAlias: string): SelectQueryBuilder<any, any, any>;
     /**
      * Retrieves the max value of the specified column
      * for this Query

package/dist/types/src/dream/QueryDriver/Kysely.d.ts

@@ -142,6 +142,7 @@ export default class KyselyQueryDriver<DreamInstance extends Dream> extends Quer
      */
     takeAll(options?: {
         columns?: DreamColumnNames<DreamInstance>[];
+        lock?: boolean;
     }): Promise<DreamInstance[]>;
     /**
      * Retrieves the max value of the specified column

package/dist/types/src/dream/QueryDriver/Postgres.d.ts

@@ -1,3 +1,4 @@
+import { type SelectQueryBuilder } from 'kysely';
 import Dream from '../../Dream.js';
 import { SchemaBuilderAssociationData, SchemaBuilderColumnData } from '../../helpers/cli/ASTBuilder.js';
 import KyselyQueryDriver from './Kysely.js';
@@ -34,6 +35,25 @@ export default class PostgresQueryDriver<DreamInstance extends Dream> extends Ky
         [key: string]: SchemaBuilderColumnData;
     }>;
     static duplicateDatabase(connectionName: string): Promise<void>;
+    /**
+     * @internal
+     *
+     * Postgres implementation of the row-locking seam: appends
+     * `FOR UPDATE OF "<tableAlias>"` to the select, so every row the statement
+     * returns is exclusively locked until the enclosing transaction ends.
+     *
+     * Scoping the lock to the Query's own base table (rather than a bare
+     * `FOR UPDATE`) means a query that joins other tables neither locks rows the
+     * caller never asked about nor raises Postgres's "FOR UPDATE cannot be
+     * applied to the nullable side of an outer join".
+     *
+     * This is a waiting lock: neither `NOWAIT` nor `SKIP LOCKED` is applied, so a
+     * statement that collides with another transaction's lock blocks until that
+     * transaction ends. Callers that cannot afford an unbounded wait should set a
+     * `lock_timeout` on the connection; see the guarded-destroy notes on
+     * `Query#destroy`.
+     */
+    applyRowLock(kyselyQuery: SelectQueryBuilder<any, any, any>, tableAlias: string): SelectQueryBuilder<any, any, any>;
     static supportsParallelTestDatabases: boolean;
     /**
      * @internal