@rvoh/dream 2.5.7 → 2.6.0

package/dist/esm/src/Dream.js

@@ -5,6 +5,7 @@ import { blankAssociationsFactory } from './decorators/field/association/shared.
 import { blankHooksFactory } from './decorators/field/lifecycle/shared.js';
 import resortAllRecords from './decorators/field/sortable/helpers/resortAllRecords.js';
 import DreamApp from './dream-app/index.js';
+import { RECURSIVE_SERIALIZATION_MAX_REPEATS } from './dream/constants.js';
 import DreamClassTransactionBuilder from './dream/DreamClassTransactionBuilder.js';
 import DreamInstanceTransactionBuilder from './dream/DreamInstanceTransactionBuilder.js';
 import associationQuery from './dream/internal/associations/associationQuery.js';
@@ -20,6 +21,7 @@ import ensureSTITypeFieldIsSet from './dream/internal/ensureSTITypeFieldIsSet.js
 import findOrCreateBy from './dream/internal/findOrCreateBy.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';
@@ -43,14 +45,11 @@ import GlobalNameNotSet from './errors/dream-app/GlobalNameNotSet.js';
 import DreamMissingRequiredOverride from './errors/DreamMissingRequiredOverride.js';
 import NonExistentScopeProvidedToResort from './errors/NonExistentScopeProvidedToResort.js';
 import RecordNotFound from './errors/RecordNotFound.js';
-import MissingSerializersDefinition from './errors/serializers/MissingSerializersDefinition.js';
 import areEqual from './helpers/areEqual.js';
 import cloneDeepSafe from './helpers/cloneDeepSafe.js';
-import compact from './helpers/compact.js';
 import isJsonColumn from './helpers/db/types/isJsonColumn.js';
 import notEqual from './helpers/notEqual.js';
 import { inferSerializersFromDreamClassOrViewModelClass } from './serializer/helpers/inferSerializerFromDreamOrViewModel.js';
-const RECURSIVE_SERIALIZATION_MAX_REPEATS = 4;
 export default class Dream {
     DB;
     /**
@@ -568,72 +567,29 @@ export default class Dream {
         if (repeatedAssociationTracker[depthTrackerId] + 1 > RECURSIVE_SERIALIZATION_MAX_REPEATS)
             return {};
         repeatedAssociationTracker[depthTrackerId]++;
-        const serializerBuilder = serializer(undefined, undefined);
-        const serializerAssociations = serializerBuilder['attributes'].filter(attribute => ['rendersOne', 'rendersMany', 'delegatedAttribute'].includes(attribute.type));
-        const mappedAssociations = serializerAssociations.reduce((accumulator, serializerAssociation) => {
-            const serializerAssociationName = serializerAssociation.targetName ??
-                serializerAssociation.name;
-            const serializerAssociationType = serializerAssociation.type;
-            const association = this['getAssociationMetadata'](serializerAssociationName);
-            if (!association)
-                return accumulator;
-            const maybeAssociatedClasses = association.modelCB();
-            if (!maybeAssociatedClasses)
-                throw new Error(`No class defined on ${serializerAssociationName} association on ${this.sanitizedName}`);
-            const associatedClasses = Array.isArray(maybeAssociatedClasses)
-                ? maybeAssociatedClasses
-                : [maybeAssociatedClasses];
-            /////////////////////////////////////////////////
-            // map associated classes to their serializers //
-            /////////////////////////////////////////////////
-            const associatedClassSerializerTuples = associatedClasses.flatMap(associatedClass => {
-                /**
-                 * `serializers` is an array because `associatedClass` may be an STI
-                 * base, with each of its STI children having its own serializer
-                 */
-                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 = [];
-                }
-                return serializers.map(serializer => [associatedClass, serializer]);
-            });
-            /////////////////////////////////////////////////////
-            // end:map associated classes to their serializers //
-            /////////////////////////////////////////////////////
-            ///////////////////////////////////////////////////////////////////////////////////////////////////
-            // reduce over all associated serializers, recursively building out their associated serializers //
-            ///////////////////////////////////////////////////////////////////////////////////////////////////
-            const innerAssociationSerializerInfo = associatedClassSerializerTuples.reduce((innerAccumulator, [associatedClass, associatedSerializer]) => {
-                if (forDisplay && serializerAssociationType !== 'delegatedAttribute') {
+        const edges = resolveSerializerAssociationEdges(this, serializer);
+        const mappedAssociations = edges.reduce((accumulator, edge) => {
+            const innerAssociationSerializerInfo = edge.targets.reduce((innerAccumulator, target) => {
+                if (forDisplay && edge.type !== 'delegatedAttribute') {
                     printSerializerHierarchyLevel({
-                        serializerAssociationType,
-                        serializerAssociationName,
-                        associationSerializer: associatedSerializer,
+                        serializerAssociationType: edge.type,
+                        serializerAssociationName: edge.serializerAssociationName,
+                        associationSerializer: target.serializer,
                         forDisplayDepth,
                     });
                 }
                 return {
                     ...innerAccumulator,
-                    ...associatedClass['recursiveSerializationMap'](associatedSerializer, {
+                    ...target.dreamClass['recursiveSerializationMap'](target.serializer, {
                         forDisplay,
                         forDisplayDepth: forDisplayDepth + 1,
                         repeatedAssociationTracker,
                     }),
                 };
             }, {});
-            ///////////////////////////////////////////////////////////////////////////////////////////////////////
-            // end:reduce over all associated serializers, recursively building out their associated serializers //
-            ///////////////////////////////////////////////////////////////////////////////////////////////////////
-            accumulator[association.as] = {
+            accumulator[edge.associationAs] = {
                 parentDreamClass: this,
-                nestedSerializerInfo: serializerAssociation.type === 'delegatedAttribute' ? {} : innerAssociationSerializerInfo,
+                nestedSerializerInfo: edge.type === 'delegatedAttribute' ? {} : innerAssociationSerializerInfo,
             };
             return accumulator;
         }, {});
@@ -3238,13 +3194,28 @@ export default class Dream {
         return new LoadBuilder(this).passthrough(passthroughWhereStatement);
     }
     /**
-     * Loads the requested associations upon execution
+     * Loads the requested associations upon execution.
+     *
+     * **IMPORTANT:** `load().execute()` returns a **new clone** of the model with the
+     * associations loaded. It does NOT modify the original instance. You must use the
+     * returned value:
+     *
+     * ```ts
+     * // CORRECT — use the returned clone:
+     * const loaded = await user.load('posts').execute()
+     * loaded.posts // works
+     *
+     * // WRONG — original is not modified:
+     * await user.load('posts').execute()
+     * user.posts // association not loaded!
+     * ```
      *
      * NOTE: {@link Dream.preload} is often a preferrable way of achieving the
-     * same goal.
+     * same goal. Alternatively, `await model.association('posts')` loads only
+     * if the association is not already loaded.
      *
      * ```ts
-     * await user
+     * const user = await user
      *  .load('posts', { body: ops.ilike('%hello world%') }, 'comments', 'replies')
      *  .load('images')
      *  .execute()
@@ -3257,7 +3228,7 @@ export default class Dream {
      * ```
      *
      * @param args - A list of associations (and optional where clauses) to load
-     * @returns A chainable LoadBuilder instance
+     * @returns A chainable LoadBuilder instance. Call `.execute()` to get the cloned model with associations loaded.
      */
     load(...args) {
         return new LoadBuilder(this).load(...args);
@@ -3326,19 +3297,19 @@ export default class Dream {
      * Load each specified association using a single SQL query.
      * See {@link Dream.load} for loading in separate queries.
      *
+     * **IMPORTANT:** Like `load()`, `leftJoinLoad().execute()` returns a **new clone** of the
+     * model with associations loaded. It does NOT modify the original instance.
+     *
      * Note: since leftJoinLoad loads via single query, it has
-     * some downsides and that may be avoided using {@link Dream.load}:
+     * some downsides that may be avoided using {@link Dream.load}:
      * 1. `limit` and `offset` will be automatically removed
      * 2. `through` associations will bring additional namespaces into the query that can conflict with through associations from other associations, creating an invalid query
      * 3. each nested association will result in an additional record which duplicates data from the outer record. E.g., given `.leftJoinLoad('a', 'b', 'c')`, if each `a` has 10 `b` and each `b` has 10 `c`, then for one `a`, 100 records will be returned, each of which has all of the columns of `a`. `.load('a', 'b', 'c')` would perform three separate SQL queries, but the data for a single `a` would only be returned once.
      * 4. the individual query becomes more complex the more associations are included
      * 5. associations loading associations loading associations could result in exponential amounts of data; in those cases, `.load(...).findEach(...)` avoids instantiating massive amounts of data at once
      *
-     * Note: Left join loading loads all data in a single SQL query but has trade-offs compared
-     * to regular preloading. See {@link Dream.leftJoinPreload} for details about limitations.
-     *
      * ```ts
-     * await user
+     * const user = await user
      *  .leftJoinLoad('posts', { body: ops.ilike('%hello world%') }, 'comments', 'replies')
      *  .leftJoinLoad('images')
      *  .execute()
@@ -3351,7 +3322,7 @@ export default class Dream {
      * ```
      *
      * @param args - A list of associations (and optional where clauses) to load
-     * @returns A chainable LeftJoinLoadBuilder instance
+     * @returns A chainable LeftJoinLoadBuilder instance. Call `.execute()` to get the cloned model with associations loaded.
      */
     leftJoinLoad(...args) {
         return new LeftJoinLoadBuilder(this).leftJoinLoad(...args);

package/dist/esm/src/decorators/class/STI.js

@@ -3,7 +3,7 @@ import StiChildIncompatibleWithReplicaSafeDecorator from '../../errors/sti/StiCh
 import StiChildIncompatibleWithSoftDeleteDecorator from '../../errors/sti/StiChildIncompatibleWithSoftDeleteDecorator.js';
 import { scopeImplementation } from '../static-method/Scope.js';
 export const STI_SCOPE_NAME = 'dream:STI';
-export default function STI(dreamClass, { value } = {}) {
+export default function STI(dreamClass) {
     return function (target) {
         const stiChildClass = target;
         const baseClass = dreamClass['sti'].baseClass || dreamClass;
@@ -21,7 +21,7 @@ export default function STI(dreamClass, { value } = {}) {
         stiChildClass['sti'] = {
             active: true,
             baseClass,
-            value: value || stiChildClass.sanitizedName,
+            value: stiChildClass.sanitizedName,
         };
         stiChildClass[STI_SCOPE_NAME] = function (query) {
             return query.where({ type: stiChildClass['sti'].value });

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

@@ -5,13 +5,16 @@ export default class LeftJoinLoadBuilder {
     dream;
     query;
     /**
-     * An intermediate class on the way to executing a load
-     * query. this can be accessed on an instance of a dream
-     * model by using the `#load` method:
+     * An intermediate builder for loading associations onto a Dream model
+     * via a single left-join SQL query. Accessed via `#leftJoinLoad`.
+     *
+     * **Note:** The LeftJoinLoadBuilder works on a clone of the original model.
+     * Call `.execute()` to get the clone with associations loaded.
      *
      * ```ts
      * const user = await User.firstOrFail()
-     * await user.load('settings').execute()
+     * const loaded = await user.leftJoinLoad('settings').execute()
+     * loaded.settings // association is loaded on the returned clone
      * ```
      */
     constructor(dream, dreamTransaction) {
@@ -39,17 +42,20 @@ export default class LeftJoinLoadBuilder {
         return this;
     }
     /**
-     * executes a load builder query, binding
-     * all associations to their respective model
-     * instances.
+     * Executes the left-join load query, returning a **clone** of the original model
+     * with all requested associations loaded. The original instance is not modified.
      *
      * ```ts
      * const user = await User.firstOrFail()
-     * await user
-     *   .load('settings')
-     *   .load('posts', 'comments', 'replies', ['image', 'localizedText'])
+     * const loaded = await user
+     *   .leftJoinLoad('settings')
+     *   .leftJoinLoad('posts', 'comments', 'replies')
      *   .execute()
+     *
+     * loaded.settings // works — associations are on the returned clone
      * ```
+     *
+     * @returns A clone of the Dream instance with all requested associations loaded
      */
     async execute() {
         if (this.dreamTransaction) {

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

@@ -3,13 +3,16 @@ export default class LoadBuilder {
     dream;
     query;
     /**
-     * An intermediate class on the way to executing a load
-     * query. this can be accessed on an instance of a dream
-     * model by using the `#load` method:
+     * An intermediate builder for loading associations onto a Dream model.
+     * Accessed via the `#load` method on a Dream instance.
+     *
+     * **Note:** The LoadBuilder works on a clone of the original model.
+     * Call `.execute()` to get the clone with associations loaded.
      *
      * ```ts
      * const user = await User.firstOrFail()
-     * await user.load('settings').execute()
+     * const loaded = await user.load('settings').execute()
+     * loaded.settings // association is loaded on the returned clone
      * ```
      */
     constructor(dream, dreamTransaction) {
@@ -21,6 +24,61 @@ export default class LoadBuilder {
         this.query = this.query.passthrough(passthroughWhereStatement);
         return this;
     }
+    /**
+     * Prevents a specific default scope from applying when
+     * loading associations
+     *
+     * ```ts
+     * const user = await User.firstOrFail()
+     * const loaded = await user
+     *   .load('posts')
+     *   .removeDefaultScope('dream:SoftDelete')
+     *   .execute()
+     * ```
+     *
+     * @param scopeName - The default scope to bypass
+     * @returns The LoadBuilder instance for chaining
+     */
+    removeDefaultScope(scopeName) {
+        this.query = this.query.removeDefaultScope(scopeName);
+        return this;
+    }
+    /**
+     * Prevents all default scopes from applying when
+     * loading associations
+     *
+     * ```ts
+     * const user = await User.firstOrFail()
+     * const loaded = await user
+     *   .load('posts')
+     *   .removeAllDefaultScopes()
+     *   .execute()
+     * ```
+     *
+     * @returns The LoadBuilder instance for chaining
+     */
+    removeAllDefaultScopes() {
+        this.query = this.query.removeAllDefaultScopes();
+        return this;
+    }
+    /**
+     * Sets the database connection to use when loading associations
+     *
+     * ```ts
+     * const user = await User.firstOrFail()
+     * const loaded = await user
+     *   .load('posts')
+     *   .connection('replica')
+     *   .execute()
+     * ```
+     *
+     * @param connection - The connection type ('primary' or 'replica')
+     * @returns The LoadBuilder instance for chaining
+     */
+    connection(connection) {
+        this.query = this.query.connection(connection);
+        return this;
+    }
     /**
      * Attaches a load statement to the load builder
      *
@@ -89,19 +147,22 @@ export default class LoadBuilder {
         return this;
     }
     /**
-     * Executes a load builder query, binding
-     * all associations to their respective model
-     * instances.
+     * Executes the load query, binding all associations to a **clone** of the
+     * original model instance. The original instance is not modified.
+     *
+     * You must use the returned value to access the loaded associations:
      *
      * ```ts
      * const user = await User.firstOrFail()
-     * await user
+     * const loaded = await user
      *   .load('settings')
      *   .load('posts', 'comments', 'replies', ['image', 'localizedText'])
      *   .execute()
+     *
+     * loaded.settings // works — associations are on the returned clone
      * ```
      *
-     * @returns The Dream instance with all associations loaded
+     * @returns A clone of the Dream instance with all requested associations loaded
      */
     async execute() {
         if (this.dreamTransaction) {

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

@@ -17,10 +17,10 @@ import namespaceColumn from '../helpers/namespaceColumn.js';
 import protectAgainstPollutingAssignment from '../helpers/protectAgainstPollutingAssignment.js';
 import { toSafeObject } from '../helpers/toSafeObject.js';
 import ops from '../ops/index.js';
+import buildSerializerPreloadPaths from './internal/buildSerializerPreloadPaths.js';
 import computedPaginatePage from './internal/computedPaginatePage.js';
 import convertDreamClassAndAssociationNameTupleArrayToPreloadArgs from './internal/convertDreamClassAndAssociationNameTupleArrayToPreloadArgs.js';
-import extractNestedPaths from './internal/extractNestedPaths.js';
-// Cache for extractNestedPaths results, keyed by "${sanitizedName}:${serializerKey}"
+// Cache for serializer preload-path results, keyed by "${globalName}:${serializerKey}"
 const extractedNestedPathsCache = new Map();
 export default class Query {
     /**
@@ -526,11 +526,10 @@ export default class Query {
      * @returns A Query with all serialization associations preloaded
      */
     preloadFor(serializerKey, modifierFn) {
-        const cacheKey = `${this.dreamClass.sanitizedName}:${serializerKey ?? 'default'}`;
+        const cacheKey = `${this.dreamClass.globalName}:${serializerKey ?? 'default'}`;
         let preloadArgs = extractedNestedPathsCache.get(cacheKey);
         if (!preloadArgs) {
-            // Cache miss - compute and store
-            preloadArgs = extractNestedPaths(this.dreamClass['serializationMap'](serializerKey));
+            preloadArgs = buildSerializerPreloadPaths(this.dreamClass, serializerKey);
             extractedNestedPathsCache.set(cacheKey, preloadArgs);
         }
         let query = this;
@@ -1698,7 +1697,7 @@ export default class Query {
      * Updates all records matching the Query
      *
      * ```ts
-     * await User.where({ email: ops.ilike('%burpcollaborator%') }).updateAll({ email: null })
+     * await User.where({ email: ops.ilike('%burpcollaborator%') }).update({ email: null })
      * // 12
      * ```
      * @param attributes - The attributes used to update the records

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

@@ -1,5 +1,7 @@
 export const primaryKeyTypes = ['uuid7', 'uuid4', 'bigserial', 'bigint', 'integer'];
 export const TRIGRAM_OPERATORS = ['%', '<%', '<<%'];
+export const RECURSIVE_SERIALIZATION_MAX_REPEATS = 4;
+export const RECURSIVE_DESTROY_PRELOAD_MAX_REPEATS = RECURSIVE_SERIALIZATION_MAX_REPEATS;
 class RequiredAttribute {
     constructor() { }
 }

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

@@ -0,0 +1,33 @@
+export default function buildAssociationPaths(rootNode, opts) {
+    const paths = [];
+    traverseAssociationPaths(rootNode, [], {}, paths, opts);
+    return paths;
+}
+function traverseAssociationPaths(node, currentPath, depthTracker, paths, opts) {
+    const trackerId = opts.getKey(node);
+    depthTracker[trackerId] ??= 0;
+    if (depthTracker[trackerId] + 1 > opts.maxRepeats) {
+        if (currentPath.length > 0) {
+            paths.push([...currentPath]);
+        }
+        return;
+    }
+    depthTracker[trackerId]++;
+    const edges = opts.getEdges(node);
+    if (edges.length === 0) {
+        if (currentPath.length > 0) {
+            paths.push([...currentPath]);
+        }
+        depthTracker[trackerId]--;
+        return;
+    }
+    for (const edge of edges) {
+        const newPath = [...currentPath, edge.tuple];
+        if (!edge.nextNode) {
+            paths.push(newPath);
+            continue;
+        }
+        traverseAssociationPaths(edge.nextNode, newPath, depthTracker, paths, opts);
+    }
+    depthTracker[trackerId]--;
+}

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

@@ -0,0 +1,43 @@
+import { RECURSIVE_DESTROY_PRELOAD_MAX_REPEATS } from '../constants.js';
+import buildAssociationPaths from './buildAssociationPaths.js';
+const dependentDestroyPreloadPathsCache = new Map();
+/**
+ * @internal
+ *
+ * Recursively walks `dependent: 'destroy'` associations starting from the given
+ * Dream class, producing an array of preload paths. Each path is an array of
+ * [DreamClass, associationName] tuples representing a chain from root to leaf.
+ *
+ * Allows the same Dream class to appear up to MAX_REPEATS times in a single
+ * path to support tree structures (e.g. a Category with `dependent: 'destroy'`
+ * on its children, which are also Categories).
+ *
+ * Used to build a preload tree so that all records in the cascade can be loaded
+ * upfront, eliminating N+1 queries during destroy.
+ */
+export default function buildDependentDestroyPreloadPaths(dreamClass) {
+    const cacheKey = dreamClass.globalName;
+    const cached = dependentDestroyPreloadPathsCache.get(cacheKey);
+    if (cached)
+        return cached;
+    const paths = [];
+    paths.push(...buildAssociationPaths(dreamClass, {
+        getKey: currentDreamClass => currentDreamClass.globalName,
+        getEdges: currentDreamClass => {
+            const associationMap = currentDreamClass['associationMetadataMap']();
+            const dependentDestroyNames = Object.keys(associationMap).filter(key => associationMap[key].dependent === 'destroy');
+            return dependentDestroyNames.flatMap(associationName => {
+                const association = associationMap[associationName];
+                const modelCBResult = association.modelCB();
+                const targetClasses = Array.isArray(modelCBResult) ? modelCBResult : [modelCBResult];
+                return targetClasses.map(targetClass => ({
+                    nextNode: targetClass,
+                    tuple: [currentDreamClass, associationName],
+                }));
+            });
+        },
+        maxRepeats: RECURSIVE_DESTROY_PRELOAD_MAX_REPEATS,
+    }));
+    dependentDestroyPreloadPathsCache.set(cacheKey, paths);
+    return paths;
+}

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

@@ -0,0 +1,38 @@
+import { inferSerializersFromDreamClassOrViewModelClass } from '../../serializer/helpers/inferSerializerFromDreamOrViewModel.js';
+import { RECURSIVE_SERIALIZATION_MAX_REPEATS } from '../constants.js';
+import buildAssociationPaths from './buildAssociationPaths.js';
+import resolveSerializerAssociationEdges from './resolveSerializerAssociationEdges.js';
+export default function buildSerializerPreloadPaths(dreamClass, serializerKey) {
+    const key = serializerKey || 'default';
+    const serializer = inferSerializersFromDreamClassOrViewModelClass(dreamClass, key)[0] ?? null;
+    if (!serializer)
+        throw new Error(`unable to find serializer with key: ${key}`);
+    const paths = buildAssociationPaths({
+        dreamClass,
+        serializer,
+    }, {
+        getKey: node => node.dreamClass.globalName,
+        getEdges: serializerNodeToEdges,
+        maxRepeats: RECURSIVE_SERIALIZATION_MAX_REPEATS,
+    });
+    const dedupedPaths = new Map();
+    for (const path of paths) {
+        dedupedPaths.set(path
+            .map(([pathDreamClass, associationName]) => `${pathDreamClass.globalName}:${associationName}`)
+            .join('|'), path);
+    }
+    return [...dedupedPaths.values()];
+}
+function serializerNodeToEdges({ dreamClass, serializer, }) {
+    const edges = resolveSerializerAssociationEdges(dreamClass, serializer);
+    return edges.flatMap(edge => {
+        const tuple = [dreamClass, edge.associationAs];
+        if (edge.type === 'delegatedAttribute' || edge.targets.length === 0) {
+            return [{ nextNode: null, tuple }];
+        }
+        return edge.targets.map(target => ({
+            nextNode: target,
+            tuple,
+        }));
+    });
+}

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

@@ -2,17 +2,25 @@
  * @internal
  *
  * Destroys all HasOne/HasMany associations on this
- * dream that are marked as `dependent: 'destroy'`
+ * dream that are marked as `dependent: 'destroy'`.
+ *
+ * Expects associations to be preloaded onto the dream instance
+ * via `loadDependentDestroyTree`. Iterates loaded associations
+ * directly instead of querying the database.
  */
 export default async function destroyAssociatedRecords(dream, txn, options) {
     const dreamClass = dream.constructor;
     const { reallyDestroy } = options;
     for (const associationName of dreamClass['dependentDestroyAssociationNames']()) {
-        if (reallyDestroy) {
-            await dream.txn(txn).reallyDestroyAssociation(associationName, options);
-        }
-        else {
-            await dream.txn(txn).destroyAssociation(associationName, options);
+        const loaded = dream[associationName];
+        const records = Array.isArray(loaded) ? loaded : loaded ? [loaded] : [];
+        for (const record of records) {
+            if (reallyDestroy) {
+                await record.txn(txn).reallyDestroy(options);
+            }
+            else {
+                await record.txn(txn).destroy(options);
+            }
         }
     }
 }

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

@@ -1,5 +1,6 @@
 import DreamApp from '../../dream-app/index.js';
 import destroyAssociatedRecords from './destroyAssociatedRecords.js';
+import loadDependentDestroyTree from './loadDependentDestroyTree.js';
 import runHooksFor from './runHooksFor.js';
 /**
  * @internal
@@ -30,7 +31,12 @@ export default async function destroyDream(dream, txn = null, options) {
 async function destroyDreamWithTransaction(dream, txn, options) {
     const { cascade, reallyDestroy, skipHooks } = options;
     if (cascade) {
-        await destroyAssociatedRecords(dream, txn, options);
+        const dreamWithAssociations = await loadDependentDestroyTree(dream, txn, {
+            reallyDestroy,
+            bypassAllDefaultScopes: options.bypassAllDefaultScopes ?? false,
+            defaultScopesToBypass: options.defaultScopesToBypass ?? [],
+        });
+        await destroyAssociatedRecords(dreamWithAssociations, txn, options);
     }
     if (!skipHooks) {
         await runHooksFor('beforeDestroy', dream, true, null, txn);

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

@@ -0,0 +1,35 @@
+import LoadBuilder from '../LoadBuilder.js';
+import buildDependentDestroyPreloadPaths from './buildDependentDestroyPreloadPaths.js';
+import convertDreamClassAndAssociationNameTupleArrayToPreloadArgs from './convertDreamClassAndAssociationNameTupleArrayToPreloadArgs.js';
+/**
+ * @internal
+ *
+ * Loads all `dependent: 'destroy'` associations onto the dream instance
+ * upfront, eliminating N+1 queries during cascade destruction.
+ *
+ * Returns a clone of the dream with all associations loaded.
+ * If there are no dependent-destroy associations, returns the original dream.
+ */
+export default async function loadDependentDestroyTree(dream, txn, { reallyDestroy, bypassAllDefaultScopes, defaultScopesToBypass, }) {
+    const dreamClass = dream.constructor;
+    const paths = buildDependentDestroyPreloadPaths(dreamClass);
+    if (paths.length === 0)
+        return dream;
+    let loadBuilder = new LoadBuilder(dream, txn);
+    for (const path of paths) {
+        const args = convertDreamClassAndAssociationNameTupleArrayToPreloadArgs(path);
+        loadBuilder = loadBuilder.load(...args);
+    }
+    if (bypassAllDefaultScopes) {
+        loadBuilder = loadBuilder.removeAllDefaultScopes();
+    }
+    else {
+        for (const scopeName of defaultScopesToBypass) {
+            loadBuilder = loadBuilder.removeDefaultScope(scopeName);
+        }
+    }
+    if (reallyDestroy) {
+        loadBuilder = loadBuilder.removeDefaultScope('dream:SoftDelete');
+    }
+    return await loadBuilder.execute();
+}