@rvoh/dream 2.5.8 → 2.6.0

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

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();
+}

package/dist/esm/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/esm/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/esm/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/esm/src/types/recursiveSerialization.js

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

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

@@ -1,6 +1,7 @@
 import Dream from '../Dream.js';
 import { PassthroughOnClause } from '../types/associations/shared.js';
-import { DreamSerializerKey, PassthroughColumnNames } from '../types/dream.js';
+import { DbConnectionType } from '../types/db.js';
+import { AllDefaultScopeNames, DreamSerializerKey, PassthroughColumnNames } from '../types/dream.js';
 import { LoadForModifierFn } from '../types/query.js';
 import { VariadicLoadArgs } from '../types/variadic.js';
 import DreamTransaction from './DreamTransaction.js';
@@ -23,6 +24,52 @@ export default class LoadBuilder<DreamInstance extends Dream> {
      */
     constructor(dream: Dream, dreamTransaction?: (DreamTransaction<any> | null) | undefined);
     passthrough<I extends LoadBuilder<DreamInstance>, PassthroughColumns extends PassthroughColumnNames<DreamInstance>>(this: I, passthroughWhereStatement: PassthroughOnClause<PassthroughColumns>): I;
+    /**
+     * 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<I extends LoadBuilder<DreamInstance>>(this: I, scopeName: AllDefaultScopeNames<DreamInstance>): I;
+    /**
+     * 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<I extends LoadBuilder<DreamInstance>>(this: I): I;
+    /**
+     * 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<I extends LoadBuilder<DreamInstance>>(this: I, connection: DbConnectionType): I;
     /**
      * Attaches a load statement to the load builder
      *

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

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

package/dist/types/src/dream/internal/buildAssociationPaths.d.ts

@@ -0,0 +1,12 @@
+import { DreamClassAndAssociationNameTuple } from '../../types/recursiveSerialization.js';
+export interface AssociationPathEdge<NodeType> {
+    nextNode: NodeType | null;
+    tuple: DreamClassAndAssociationNameTuple;
+}
+export default function buildAssociationPaths<NodeType>(rootNode: NodeType, opts: BuildAssociationPathsOptions<NodeType>): DreamClassAndAssociationNameTuple[][];
+type BuildAssociationPathsOptions<NodeType> = {
+    getKey: (node: NodeType) => string;
+    getEdges: (node: NodeType) => AssociationPathEdge<NodeType>[];
+    maxRepeats: number;
+};
+export {};

package/dist/types/src/dream/internal/buildDependentDestroyPreloadPaths.d.ts

@@ -0,0 +1,17 @@
+import Dream from '../../Dream.js';
+import { DreamClassAndAssociationNameTuple } from '../../types/recursiveSerialization.js';
+/**
+ * @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: typeof Dream): DreamClassAndAssociationNameTuple[][];

package/dist/types/src/dream/internal/buildSerializerPreloadPaths.d.ts

@@ -0,0 +1,3 @@
+import Dream from '../../Dream.js';
+import { DreamClassAndAssociationNameTuple } from '../../types/recursiveSerialization.js';
+export default function buildSerializerPreloadPaths(dreamClass: typeof Dream, serializerKey?: string): DreamClassAndAssociationNameTuple[][];

package/dist/types/src/dream/internal/convertDreamClassAndAssociationNameTupleArrayToPreloadArgs.d.ts

@@ -1,5 +1,5 @@
 import { LoadForModifierFn } from '../../types/query.js';
-import { DreamClassAndAssociationNameTuple } from './extractNestedPaths.js';
+import { DreamClassAndAssociationNameTuple } from '../../types/recursiveSerialization.js';
 export default function convertDreamClassAndAssociationNameTupleArrayToPreloadArgs(dreamClassAndAssociationNameTupleArray: DreamClassAndAssociationNameTuple[], modifierFn?: LoadForModifierFn, counter?: {
     count: number;
 }): (string | {

package/dist/types/src/dream/internal/destroyAssociatedRecords.d.ts

@@ -5,6 +5,10 @@ import { ReallyDestroyOptions } from './destroyDream.js';
  * @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 function destroyAssociatedRecords<I extends Dream>(dream: I, txn: DreamTransaction<I>, options: ReallyDestroyOptions<I>): Promise<void>;

package/dist/types/src/dream/internal/loadDependentDestroyTree.d.ts

@@ -0,0 +1,17 @@
+import Dream from '../../Dream.js';
+import { AllDefaultScopeNames } from '../../types/dream.js';
+import DreamTransaction from '../DreamTransaction.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 function loadDependentDestroyTree<I extends Dream>(dream: I, txn: DreamTransaction<I>, { reallyDestroy, bypassAllDefaultScopes, defaultScopesToBypass, }: {
+    reallyDestroy: boolean;
+    bypassAllDefaultScopes: boolean;
+    defaultScopesToBypass: AllDefaultScopeNames<I>[];
+}): Promise<I>;

package/dist/types/src/dream/internal/resolveSerializerAssociationEdges.d.ts

@@ -0,0 +1,13 @@
+import Dream from '../../Dream.js';
+import { DreamModelSerializerType, SimpleObjectSerializerType } from '../../types/serializer.js';
+export interface ResolvedSerializerAssociationEdge {
+    associationAs: string;
+    sourceDreamClass: typeof Dream;
+    type: 'rendersOne' | 'rendersMany' | 'delegatedAttribute';
+    serializerAssociationName: string;
+    targets: {
+        dreamClass: typeof Dream;
+        serializer: DreamModelSerializerType | SimpleObjectSerializerType;
+    }[];
+}
+export default function resolveSerializerAssociationEdges(dreamClass: typeof Dream, serializer: DreamModelSerializerType | SimpleObjectSerializerType): ResolvedSerializerAssociationEdge[];

package/dist/types/src/serializer/builders/DreamSerializerBuilder.d.ts

@@ -2,6 +2,7 @@ import Dream from '../../Dream.js';
 import { DreamOrViewModelSerializerKey, DreamVirtualColumns, NonJsonDreamColumnNames, ViewModel, ViewModelClass } from '../../types/dream.js';
 import { AutomaticSerializerAttributeOptions, AutomaticSerializerAttributeOptionsForType, InternalAnyTypedSerializerAttribute, InternalAnyTypedSerializerCustomAttribute, InternalAnyTypedSerializerDelegatedAttribute, InternalAnyTypedSerializerRendersMany, InternalAnyTypedSerializerRendersOne, NonAutomaticSerializerAttributeOptionsWithPossibleDecimalRenderOption, SerializerAttributeOptionsForVirtualColumn, SerializerType } from '../../types/serializer.js';
 import { SerializerRendererOpts } from '../SerializerRenderer.js';
+export type DreamPropertiesToExclude = keyof Dream | 'serializers';
 export default class DreamSerializerBuilder<DataTypeForOpenapi extends typeof Dream, MaybeNullDataType extends Dream | null, PassthroughDataType = any, DataType extends Exclude<MaybeNullDataType, null> = Exclude<MaybeNullDataType, null>> {
     protected $typeForOpenapi: DataTypeForOpenapi;
     protected data: MaybeNullDataType;
@@ -53,7 +54,7 @@ export default class DreamSerializerBuilder<DataTypeForOpenapi extends typeof Dr
      */
     attribute(name: NonJsonDreamColumnNames<DataType> & keyof DataType & 'type', options?: AutomaticSerializerAttributeOptionsForType): DreamSerializerBuilder<DataTypeForOpenapi, MaybeNullDataType, PassthroughDataType, DataType>;
     attribute(name: DreamVirtualColumns<DataType>[number], options?: SerializerAttributeOptionsForVirtualColumn): DreamSerializerBuilder<DataTypeForOpenapi, MaybeNullDataType, PassthroughDataType, DataType>;
-    attribute<MaybeAttributeName extends NonJsonDreamColumnNames<DataType> | (keyof DataType & string), AttributeName extends MaybeAttributeName extends NonJsonDreamColumnNames<DataType> ? never : Exclude<keyof DataType, keyof Dream> & string>(name: AttributeName, options: NonAutomaticSerializerAttributeOptionsWithPossibleDecimalRenderOption): DreamSerializerBuilder<DataTypeForOpenapi, MaybeNullDataType, PassthroughDataType, DataType>;
+    attribute<MaybeAttributeName extends NonJsonDreamColumnNames<DataType> | (keyof DataType & string), AttributeName extends MaybeAttributeName extends NonJsonDreamColumnNames<DataType> ? never : Exclude<keyof DataType, DreamPropertiesToExclude> & string>(name: AttributeName, options: NonAutomaticSerializerAttributeOptionsWithPossibleDecimalRenderOption): DreamSerializerBuilder<DataTypeForOpenapi, MaybeNullDataType, PassthroughDataType, DataType>;
     attribute<AttributeName extends NonJsonDreamColumnNames<DataType> & keyof DataType & string>(name: AttributeName, options?: AutomaticSerializerAttributeOptions): DreamSerializerBuilder<DataTypeForOpenapi, MaybeNullDataType, PassthroughDataType, DataType>;
     /**
      * Includes an attribute from a nested object in the serialized output.
@@ -75,6 +76,10 @@ export default class DreamSerializerBuilder<DataTypeForOpenapi extends typeof Dr
      *   - `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;
@@ -99,7 +104,11 @@ export default class DreamSerializerBuilder<DataTypeForOpenapi extends typeof Dr
      * })
      * ```
      */
-    delegatedAttribute<ProvidedModelType = undefined, ProvidedTargetName extends ProvidedModelType extends undefined ? undefined : Exclude<keyof ProvidedModelType, keyof Dream> = ProvidedModelType extends undefined ? undefined : Exclude<keyof ProvidedModelType, keyof Dream>, ActualDataType extends ProvidedModelType extends undefined ? DataType : ProvidedModelType = ProvidedModelType extends undefined ? DataType : ProvidedModelType, TargetName extends ProvidedTargetName extends undefined ? Exclude<keyof ActualDataType, keyof Dream> : ProvidedTargetName & keyof ActualDataType = ProvidedTargetName extends undefined ? Exclude<keyof ActualDataType, keyof Dream> : ProvidedTargetName & keyof ActualDataType, AssociatedModelType = Exclude<ActualDataType[TargetName], null>, TargetAttributeName extends AssociatedModelType extends object ? Exclude<keyof AssociatedModelType, keyof Dream> & string : never = AssociatedModelType extends object ? Exclude<keyof AssociatedModelType, keyof Dream> & string : never>(targetName: TargetName, name: TargetAttributeName, options?: AssociatedModelType extends Dream ? TargetAttributeName extends NonJsonDreamColumnNames<AssociatedModelType> & keyof AssociatedModelType & 'type' ? AutomaticSerializerAttributeOptionsForType : TargetAttributeName extends DreamVirtualColumns<AssociatedModelType>[number] ? SerializerAttributeOptionsForVirtualColumn : TargetAttributeName extends AssociatedModelType & keyof AssociatedModelType & string ? AutomaticSerializerAttributeOptions | NonAutomaticSerializerAttributeOptionsWithPossibleDecimalRenderOption : NonAutomaticSerializerAttributeOptionsWithPossibleDecimalRenderOption : NonAutomaticSerializerAttributeOptionsWithPossibleDecimalRenderOption): this;
+    delegatedAttribute<ProvidedModelType = undefined, ProvidedTargetName extends ProvidedModelType extends undefined ? undefined : Exclude<keyof ProvidedModelType, DreamPropertiesToExclude> = ProvidedModelType extends undefined ? undefined : Exclude<keyof ProvidedModelType, DreamPropertiesToExclude>, ActualDataType extends ProvidedModelType extends undefined ? InstanceType<DataTypeForOpenapi> : ProvidedModelType = ProvidedModelType extends undefined ? InstanceType<DataTypeForOpenapi> : ProvidedModelType, TargetName extends ProvidedTargetName extends undefined ? Exclude<keyof ActualDataType, DreamPropertiesToExclude> : ProvidedTargetName & keyof ActualDataType = ProvidedTargetName extends undefined ? Exclude<keyof ActualDataType, DreamPropertiesToExclude> : ProvidedTargetName & keyof ActualDataType, AssociatedModelType = Exclude<ActualDataType[TargetName], null>, TargetAttributeName extends AssociatedModelType extends object ? Exclude<keyof AssociatedModelType, DreamPropertiesToExclude> & string : never = AssociatedModelType extends object ? Exclude<keyof AssociatedModelType, DreamPropertiesToExclude> & string : never>(targetName: TargetName, name: TargetAttributeName, options?: AssociatedModelType extends Dream ? TargetAttributeName extends NonJsonDreamColumnNames<AssociatedModelType> & keyof AssociatedModelType & 'type' ? AutomaticSerializerAttributeOptionsForType & {
+        optional?: boolean;
+    } : TargetAttributeName extends DreamVirtualColumns<AssociatedModelType>[number] ? SerializerAttributeOptionsForVirtualColumn : TargetAttributeName extends NonJsonDreamColumnNames<AssociatedModelType> & keyof AssociatedModelType & string ? (AutomaticSerializerAttributeOptions & {
+        optional?: boolean;
+    }) | NonAutomaticSerializerAttributeOptionsWithPossibleDecimalRenderOption : NonAutomaticSerializerAttributeOptionsWithPossibleDecimalRenderOption : NonAutomaticSerializerAttributeOptionsWithPossibleDecimalRenderOption): this;
     /**
      * Includes a computed value in the serialized output.
      *
@@ -196,7 +205,7 @@ export default class DreamSerializerBuilder<DataTypeForOpenapi extends typeof Dr
      * .rendersOne('owner', { serializer: CustomOwnerSerializer })
      * ```
      */
-    rendersOne<ProvidedModelType = undefined, ProvidedAttributeName extends ProvidedModelType extends undefined ? undefined : Exclude<keyof ProvidedModelType, keyof Dream> = ProvidedModelType extends undefined ? undefined : Exclude<keyof ProvidedModelType, keyof Dream>, ActualDataType extends ProvidedModelType extends undefined ? DataType : ProvidedModelType = ProvidedModelType extends undefined ? DataType : ProvidedModelType, AttributeName extends ProvidedAttributeName extends undefined ? Exclude<keyof ActualDataType, keyof Dream> : ProvidedAttributeName & keyof ActualDataType = ProvidedAttributeName extends undefined ? Exclude<keyof ActualDataType, keyof Dream> : ProvidedAttributeName & keyof ActualDataType, AssociatedModelType = Exclude<ActualDataType[AttributeName], null>, SerializerOptions = AssociatedModelType extends Dream ? {
+    rendersOne<ProvidedModelType = undefined, ProvidedAttributeName extends ProvidedModelType extends undefined ? undefined : Exclude<keyof ProvidedModelType, DreamPropertiesToExclude> = ProvidedModelType extends undefined ? undefined : Exclude<keyof ProvidedModelType, DreamPropertiesToExclude>, ActualDataType extends ProvidedModelType extends undefined ? InstanceType<DataTypeForOpenapi> : ProvidedModelType = ProvidedModelType extends undefined ? InstanceType<DataTypeForOpenapi> : ProvidedModelType, AttributeName extends ProvidedAttributeName extends undefined ? Exclude<keyof ActualDataType, DreamPropertiesToExclude> : ProvidedAttributeName & keyof ActualDataType = ProvidedAttributeName extends undefined ? Exclude<keyof ActualDataType, DreamPropertiesToExclude> : ProvidedAttributeName & keyof ActualDataType, AssociatedModelType = Exclude<ActualDataType[AttributeName], null>, SerializerOptions = AssociatedModelType extends Dream ? {
         serializerKey?: DreamOrViewModelSerializerKey<AssociatedModelType>;
     } | {
         serializer?: SerializerType;
@@ -267,7 +276,7 @@ export default class DreamSerializerBuilder<DataTypeForOpenapi extends typeof Dr
      * .rendersMany('rooms', { serializerKey: 'forGuests', as: 'guestRooms' })
      * ```
      */
-    rendersMany<ProvidedModelType = undefined, ProvidedAttributeName extends ProvidedModelType extends undefined ? undefined : Exclude<keyof ProvidedModelType, keyof Dream> = ProvidedModelType extends undefined ? undefined : Exclude<keyof ProvidedModelType, keyof Dream>, ActualDataType extends ProvidedModelType extends undefined ? DataType : ProvidedModelType = ProvidedModelType extends undefined ? DataType : ProvidedModelType, AttributeName extends ProvidedAttributeName extends undefined ? Exclude<keyof ActualDataType, keyof Dream> : ProvidedAttributeName & keyof ActualDataType = ProvidedAttributeName extends undefined ? Exclude<keyof ActualDataType, keyof Dream> : ProvidedAttributeName & keyof ActualDataType, AssociatedModelType = ActualDataType[AttributeName] extends (Dream | ViewModel)[] ? ActualDataType[AttributeName] extends (infer U)[] ? U : object : object, SerializerOptions = AssociatedModelType extends Dream ? {
+    rendersMany<ProvidedModelType = undefined, ProvidedAttributeName extends ProvidedModelType extends undefined ? undefined : Exclude<keyof ProvidedModelType, DreamPropertiesToExclude> = ProvidedModelType extends undefined ? undefined : Exclude<keyof ProvidedModelType, DreamPropertiesToExclude>, ActualDataType extends ProvidedModelType extends undefined ? InstanceType<DataTypeForOpenapi> : ProvidedModelType = ProvidedModelType extends undefined ? InstanceType<DataTypeForOpenapi> : ProvidedModelType, AttributeName extends ProvidedAttributeName extends undefined ? Exclude<keyof ActualDataType, DreamPropertiesToExclude> : ProvidedAttributeName & keyof ActualDataType = ProvidedAttributeName extends undefined ? Exclude<keyof ActualDataType, DreamPropertiesToExclude> : ProvidedAttributeName & keyof ActualDataType, AssociatedModelType = ActualDataType[AttributeName] extends (Dream | ViewModel)[] ? ActualDataType[AttributeName] extends (infer U)[] ? U : object : object, SerializerOptions = AssociatedModelType extends Dream ? {
         serializerKey?: DreamOrViewModelSerializerKey<AssociatedModelType>;
     } | {
         serializer?: SerializerType;