@rvoh/dream 2.5.8 → 2.6.1-alpha.1

package/dist/cjs/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;
         }, {});

package/dist/cjs/src/db/migration-helpers/DreamMigrationHelpers.js

@@ -1,15 +1,14 @@
 import { sql } from 'kysely';
 export default class DreamMigrationHelpers {
     /**
-     * Rename a table and its associated primary key sequence.
+     * Rename a table and its associated primary key index and sequence.
      *
-     * This method renames both the table and its primary key sequence to keep them
-     * in sync. When PostgreSQL creates a table with a serial or bigserial primary key,
-     * it automatically creates a sequence named `{tablename}_id_seq`. If you only rename
-     * the table, the sequence keeps the old name, which can cause confusion and issues.
+     * This method renames the table, its primary key index (`{tablename}_pkey`),
+     * and its primary key sequence (`{tablename}_id_seq`) to keep them in sync.
      *
-     * This method is only suitable for tables that have a serial or bigserial primary
-     * key column named 'id'.
+     * The sequence rename is skipped for tables with UUID primary keys (which have
+     * no associated sequence). The primary key index is always renamed since
+     * PostgreSQL does not automatically rename it when the table is renamed.
      *
      * @param db - The Kysely database object passed into the migration up/down function
      * @param from - The current name of the table to rename
@@ -17,10 +16,15 @@ export default class DreamMigrationHelpers {
      */
     static async renameTable(db, from, to) {
         await db.schema.alterTable(from).renameTo(to).execute();
-        const fromSequenceName = `${from}_id_seq`;
-        const toSequenceName = `${to}_id_seq`;
-        const sqlStatement = `ALTER SEQUENCE ${fromSequenceName} RENAME TO ${toSequenceName}`;
-        await sql.raw(sqlStatement).execute(db);
+        await sql `ALTER INDEX IF EXISTS ${sql.ref(`${from}_pkey`)} RENAME TO ${sql.ref(`${to}_pkey`)}`.execute(db);
+        const sequenceExists = await sql `
+      SELECT EXISTS (
+        SELECT 1 FROM pg_class WHERE relkind = 'S' AND relname = ${`${from}_id_seq`}
+      )
+    `.execute(db);
+        if (sequenceExists.rows[0]?.exists) {
+            await sql `ALTER SEQUENCE ${sql.ref(`${from}_id_seq`)} RENAME TO ${sql.ref(`${to}_id_seq`)}`.execute(db);
+        }
     }
     /**
      * Unique indexes cannot be populated by the same value even within a transaction,

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

@@ -24,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
      *

package/dist/cjs/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;

package/dist/cjs/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/cjs/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/cjs/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/cjs/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/cjs/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/cjs/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/cjs/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();
+}

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

@@ -0,0 +1,53 @@
+import MissingSerializersDefinition from '../../errors/serializers/MissingSerializersDefinition.js';
+import compact from '../../helpers/compact.js';
+import { inferSerializersFromDreamClassOrViewModelClass } from '../../serializer/helpers/inferSerializerFromDreamOrViewModel.js';
+export default function resolveSerializerAssociationEdges(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;
+        const association = dreamClass['getAssociationMetadata'](serializerAssociationName);
+        if (!association)
+            return null;
+        if (serializerAssociation.type === 'delegatedAttribute') {
+            return {
+                associationAs: association.as,
+                sourceDreamClass: dreamClass,
+                type: serializerAssociation.type,
+                serializerAssociationName,
+                targets: [],
+            };
+        }
+        const maybeAssociatedClasses = association.modelCB();
+        if (!maybeAssociatedClasses)
+            throw new Error(`No class defined on ${serializerAssociationName} association on ${dreamClass.sanitizedName}`);
+        const associatedClasses = Array.isArray(maybeAssociatedClasses)
+            ? 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 = [];
+            }
+            return serializers.map(associatedSerializer => ({
+                dreamClass: associatedClass,
+                serializer: associatedSerializer,
+            }));
+        });
+        return {
+            associationAs: association.as,
+            sourceDreamClass: dreamClass,
+            type: serializerAssociation.type,
+            serializerAssociationName,
+            targets,
+        };
+    }));
+}

package/dist/cjs/src/serializer/SerializerRenderer.js

@@ -158,7 +158,7 @@ export default class SerializerRenderer {
                             // does not pass it into the call to DreamSerializer/ObjectSerializer,
                             // then it would be lost to serializers rendered via rendersOne/Many, and SerializerRenderer
                             // handles passing its passthrough data into those
-                            .render(passthroughData));
+                            .render(passthroughData, this.renderOpts));
                     });
                     return accumulator;
                 }

package/dist/cjs/src/serializer/builders/DreamSerializerBuilder.js

@@ -37,6 +37,10 @@ export default class DreamSerializerBuilder {
      *   - `default` - Value to use when the target object or its attribute is null/undefined
      *   - `openapi` - OpenAPI schema definition; required for non-Dream targets and json/jsonb
      *     columns, optional for standard Dream columns (where types are inferred)
+     *   - `optional` - Set to `true` to indicate the value can be null in the OpenAPI schema
+     *     (wraps the type in `anyOf: [schema, { type: 'null' }]`). For Dream models, this is
+     *     auto-inferred from optional BelongsTo associations. Use this when delegating through
+     *     a HasOne or other nullable association.
      *   - `precision` - Round decimal values to the specified number of decimal places (0–9)
      *     during rendering; does not affect the OpenAPI shape
      *   - `required` - Set to `false` to mark the attribute as optional in the OpenAPI schema;

package/dist/cjs/src/types/recursiveSerialization.js

@@ -0,0 +1 @@
+export {};