@rvoh/dream 2.5.7 → 2.6.0

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

@@ -20,30 +20,50 @@ export default class DreamSerializerBuilder {
     /**
      * Includes an attribute from a nested object in the serialized output.
      *
-     * Serializes an attribute from a target object. If the target object or
-     * the delegated attribute is null/undefined, the `default` option value
+     * Accesses `targetName.name` on the data object. If the target object
+     * or the delegated attribute is null/undefined, the `default` option value
      * will be used if provided.
      *
-     * @param targetName - The property name containing the target object
+     * When the target is a Dream model, OpenAPI types may be automatically inferred
+     * for standard database columns. For json/jsonb columns or non-Dream targets,
+     * the `openapi` option is required.
+     *
+     * @param targetName - The property name containing the target object (e.g., an association name)
      * @param name - The attribute name within the target object
-     * @param options - Configuration options including OpenAPI schema, default value, and output customization
+     * @param options - Configuration options:
+     *   - `as` - Rename the attribute key in the serialized output and OpenAPI shape
+     *     (e.g., delegating `'user', 'email'` with `as: 'userEmail'` outputs the value
+     *     under `userEmail`)
+     *   - `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;
+     *     when omitted, attributes are required by default
      * @returns The serializer builder for method chaining
      *
      * @example
      * ```typescript
-     * // Delegate to user.email
-     * .delegatedAttribute('user', 'email', {
-     *   openapi: { type: 'string', format: 'email' }
-     * })
+     * // Delegate to a Dream association's column (type inferred)
+     * .delegatedAttribute('currentLocalizedText', 'title', { openapi: 'string' })
      *
      * // With default value for null target or attribute
      * .delegatedAttribute('user', 'displayName', {
      *   openapi: { type: 'string' },
      *   default: 'Unknown User'
      * })
-     * ```
      *
-     * See: {@link https://your-docs-url.com/docs/serializers/attributes | Serializer Attributes Documentation}
+     * // Rename the output key
+     * .delegatedAttribute('profile', 'avatarUrl', {
+     *   openapi: 'string',
+     *   as: 'avatar'
+     * })
+     * ```
      */
     delegatedAttribute(targetName, name, options) {
         this.attributes.push({
@@ -62,7 +82,17 @@ export default class DreamSerializerBuilder {
      *
      * @param name - The attribute name for the computed value
      * @param fn - Callback function that returns the computed value
-     * @param options - Configuration options including required OpenAPI schema and optional flattening
+     * @param options - Configuration options:
+     *   - `openapi` - (required) OpenAPI schema definition for the computed value
+     *   - `as` - Rename the attribute key in the serialized output and OpenAPI shape
+     *   - `default` - Value to use when the callback returns undefined
+     *   - `flatten` - When `true`, spreads the returned object's properties directly into the
+     *     parent serialized output instead of nesting them under `name`; the `openapi` option
+     *     should then define each flattened property individually
+     *   - `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;
+     *     when omitted, attributes are required by default
      * @returns The serializer builder for method chaining
      *
      * @example
@@ -74,16 +104,20 @@ export default class DreamSerializerBuilder {
      * )
      *
      * // Flattened object properties
-     * .customAttribute('metadata', () => ({ age: 30, city: 'NYC' }), {
+     * .customAttribute('coordinates', () => ({ lat: 40.7, lng: -74.0 }), {
      *   flatten: true,
      *   openapi: {
-     *     age: { type: 'integer' },
-     *     city: { type: 'string' }
+     *     lat: { type: 'number' },
+     *     lng: { type: 'number' }
      *   }
      * })
-     * ```
      *
-     * See: {@link https://your-docs-url.com/docs/serializers/attributes | Serializer Attributes Documentation}
+     * // With decimal precision
+     * .customAttribute('averageRating', () => calculateAverage(ratings), {
+     *   openapi: 'decimal',
+     *   precision: 2
+     * })
+     * ```
      */
     customAttribute(name, fn, options) {
         this.attributes.push({
@@ -97,28 +131,50 @@ export default class DreamSerializerBuilder {
     /**
      * Includes a single associated object in the serialized output.
      *
-     * When rendering a Dream association, the OpenAPI shape is automatically
-     * inferred from that associated Dream's serializer.
+     * When rendering a Dream association, the serializer and OpenAPI shape are automatically
+     * inferred from that associated Dream model's registered serializers.
      *
      * @param name - The association property name
-     * @param options - Configuration options for serialization and schema definition
+     * @param options - Configuration options:
+     *   - `as` - Rename the association key in the serialized output
+     *   - `flatten` - When `true`, spreads the rendered association's attributes directly into
+     *     the parent serialized output instead of nesting them under `name`. Be aware of
+     *     attribute shadowing: if the parent and flattened association share attribute names
+     *     (e.g., `id`), the flattened association's values overwrite the parent's
+     *   - `optional` - When `true`, allows the association to be null/missing without causing
+     *     an `OpenapiResponseValidationFailure` during Psychic controller unit specs. By default,
+     *     `rendersOne` expects the association to be present (mirroring the `optional` option on
+     *     `@deco.BelongsTo`). Set this to `true` when the association is genuinely nullable
+     *   - `serializerKey` - Use a specific serializer key from the associated Dream model's
+     *     registered serializers (e.g., `'summary'`)
+     *   - `serializer` - Provide an explicit serializer function instead of using the
+     *     associated model's registered serializers
+     *
+     *   For ViewModel associations, one of these is required:
+     *   - `viewModelClass` + optional `serializerKey`
+     *   - `serializer`
+     *
+     *   For non-Dream/non-ViewModel associations:
+     *   - `serializer` is required
      * @returns The serializer builder for method chaining
      *
      * @example
      * ```typescript
-     * // DreamSerializer with inference
-     * .rendersOne('user') // Infers from Dream association
+     * // Auto-infer serializer from Dream association
+     * .rendersOne('profile')
      *
-     * // With specific serializer
+     * // With specific serializer key
      * .rendersOne('user', { serializerKey: 'summary' })
      *
-     * // ObjectSerializer (explicit configuration required)
-     * .rendersOne('owner', UserSerializer, {
-     *   openapi: { $ref: '#/components/schemas/User' }
-     * })
-     * ```
+     * // Allow null association
+     * .rendersOne('approver', { optional: true })
      *
-     * See: {@link https://your-docs-url.com/docs/serializers/associations | Serializer Associations Documentation}
+     * // Flatten into parent object
+     * .rendersOne('candidate', { serializerKey: 'summary', flatten: true })
+     *
+     * // Explicit serializer function
+     * .rendersOne('owner', { serializer: CustomOwnerSerializer })
+     * ```
      */
     rendersOne(name, options) {
         this.attributes.push({
@@ -131,31 +187,39 @@ export default class DreamSerializerBuilder {
     /**
      * Includes an array of associated objects in the serialized output.
      *
-     * When rendering a Dream association, the OpenAPI shape is automatically
-     * inferred from that associated Dream's serializer.
+     * When rendering a Dream association, the serializer and OpenAPI shape are automatically
+     * inferred from that associated Dream model's registered serializers.
+     *
+     * @param name - The association property name (should resolve to an array)
+     * @param options - Configuration options:
+     *   - `as` - Rename the association key in the serialized output
+     *   - `serializerKey` - Use a specific serializer key from the associated Dream model's
+     *     registered serializers (e.g., `'summary'`)
+     *   - `serializer` - Provide an explicit serializer function instead of using the
+     *     associated model's registered serializers
      *
-     * @param name - The association property name (should be an array)
-     * @param options - Configuration options for serialization and schema definition
+     *   For ViewModel associations, one of these is required:
+     *   - `viewModelClass` + optional `serializerKey`
+     *   - `serializer`
+     *
+     *   For non-Dream/non-ViewModel associations:
+     *   - `serializer` is required
      * @returns The serializer builder for method chaining
      *
      * @example
      * ```typescript
-     * // DreamSerializer with inference
-     * .rendersMany('posts') // Infers from Dream association
+     * // Auto-infer serializer from Dream association
+     * .rendersMany('rooms')
      *
-     * // With specific serializer
-     * .rendersMany('posts', { serializerKey: 'summary' })
+     * // With specific serializer key
+     * .rendersMany('rooms', { serializerKey: 'summary' })
      *
-     * // ObjectSerializer (explicit configuration required)
-     * .rendersMany('articles', ArticleSerializer, {
-     *   openapi: {
-     *     type: 'array',
-     *     items: { $ref: '#/components/schemas/Article' }
-     *   }
-     * })
-     * ```
+     * // Explicit serializer function (for non-Dream objects)
+     * .rendersMany('bedTypes', { serializer: BedTypeSerializer })
      *
-     * See: {@link https://your-docs-url.com/docs/serializers/associations | Serializer Associations Documentation}
+     * // Rename output key
+     * .rendersMany('rooms', { serializerKey: 'forGuests', as: 'guestRooms' })
+     * ```
      */
     rendersMany(name, options) {
         this.attributes.push({
@@ -168,24 +232,22 @@ export default class DreamSerializerBuilder {
     /**
      * Executes the serializer and returns the serialized output.
      *
-     * This method processes all defined attributes, custom attributes, delegated attributes,
-     * and associations to produce the final serialized object. The result is suitable for
-     * JSON.stringify() and API responses.
+     * Processes all defined attributes, custom attributes, delegated attributes,
+     * and associations to produce the final serialized object.
      *
      * @param passthrough - Additional data to pass through to nested serializers
+     *   (e.g., locale, current user context)
      * @param opts - Rendering options for customizing the serialization process
-     * @returns The serialized object
+     * @returns The serialized object, suitable for JSON responses
      *
      * @example
      * ```typescript
      * const result = UserSerializer(user).render()
      * // Returns: { id: 1, email: 'user@example.com', ... }
      *
-     * // With passthrough data
+     * // With passthrough data for nested serializers
      * const result = UserSerializer(user).render({ currentUserId: 123 })
      * ```
-     *
-     * See: {@link https://your-docs-url.com/docs/serializers/render | Serializer Rendering Documentation}
      */
     render(passthrough = {}, opts = {}) {
         return new SerializerRenderer(this, passthrough, opts).render();

package/dist/esm/src/serializer/builders/ObjectSerializerBuilder.js

@@ -14,7 +14,15 @@ export default class ObjectSerializerBuilder {
      * inference is not available for plain objects or ViewModels.
      *
      * @param name - The attribute name from the data object
-     * @param options - Configuration options including required OpenAPI schema, default value, and output customization
+     * @param options - Configuration options:
+     *   - `openapi` - (required) OpenAPI schema definition for the attribute
+     *   - `as` - Rename the attribute key in the serialized output and OpenAPI shape
+     *   - `default` - Value to use when the attribute is undefined
+     *   - `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;
+     *     when omitted, attributes are required by default, meaning `undefined` values will
+     *     serialize as `null`
      * @returns The serializer builder for method chaining
      *
      * @example
@@ -35,9 +43,19 @@ export default class ObjectSerializerBuilder {
      *   openapi: { type: 'string' },
      *   as: 'userEmail'
      * })
-     * ```
      *
-     * See: {@link https://your-docs-url.com/docs/serializers/attributes | Serializer Attributes Documentation}
+     * // Round decimal to 2 places
+     * .attribute('price', {
+     *   openapi: 'decimal',
+     *   precision: 2
+     * })
+     *
+     * // Mark as optional in OpenAPI (omitted from response when undefined)
+     * .attribute('nickname', {
+     *   openapi: 'string',
+     *   required: false
+     * })
+     * ```
      */
     attribute(name, options) {
         this.attributes.push({
@@ -50,13 +68,22 @@ export default class ObjectSerializerBuilder {
     /**
      * Includes an attribute from a nested object in the serialized output.
      *
-     * Pulls up an attribute from a target object property. The `openapi` option
-     * is always required. If the target object or the delegated attribute
-     * is null/undefined, the `default` option value will be used if provided.
+     * Accesses `targetName.name` on the data object. The `openapi` option is always
+     * required. If the target object or the delegated attribute is null/undefined,
+     * the `default` option value will be used if provided.
      *
      * @param targetName - The property name containing the target object
      * @param name - The attribute name within the target object
-     * @param options - Configuration options including required OpenAPI schema, default value, and output customization
+     * @param options - Configuration options:
+     *   - `openapi` - (required) OpenAPI schema definition for the attribute
+     *   - `as` - Rename the attribute key in the serialized output and OpenAPI shape
+     *     (e.g., delegating `'profile', 'avatarUrl'` with `as: 'avatar'` outputs the value
+     *     under `avatar`)
+     *   - `default` - Value to use when the target object or its attribute is null/undefined
+     *   - `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;
+     *     when omitted, attributes are required by default
      * @returns The serializer builder for method chaining
      *
      * @example
@@ -71,9 +98,13 @@ export default class ObjectSerializerBuilder {
      *   openapi: { type: 'string' },
      *   default: 'Anonymous User'
      * })
-     * ```
      *
-     * See: {@link https://your-docs-url.com/docs/serializers/attributes | Serializer Attributes Documentation}
+     * // Rename the output key
+     * .delegatedAttribute('profile', 'avatarUrl', {
+     *   openapi: 'string',
+     *   as: 'avatar'
+     * })
+     * ```
      */
     delegatedAttribute(targetName, name, options) {
         this.attributes.push({
@@ -90,9 +121,19 @@ export default class ObjectSerializerBuilder {
      * Executes a callback function to generate a custom attribute value.
      * The `openapi` option is always required since the return type cannot be inferred.
      *
+     * Unlike DreamSerializerBuilder's `customAttribute`, this version does not support `as`
+     * or `precision`.
+     *
      * @param name - The attribute name for the computed value
      * @param fn - Callback function that returns the computed value
-     * @param options - Configuration options including required OpenAPI schema and optional flattening
+     * @param options - Configuration options:
+     *   - `openapi` - (required) OpenAPI schema definition for the computed value
+     *   - `default` - Value to use when the callback returns undefined
+     *   - `flatten` - When `true`, spreads the returned object's properties directly into the
+     *     parent serialized output instead of nesting them under `name`; the `openapi` option
+     *     should then define each flattened property individually
+     *   - `required` - Set to `false` to mark the attribute as optional in the OpenAPI schema;
+     *     when omitted, attributes are required by default
      * @returns The serializer builder for method chaining
      *
      * @example
@@ -112,8 +153,6 @@ export default class ObjectSerializerBuilder {
      *   }
      * })
      * ```
-     *
-     * See: {@link https://your-docs-url.com/docs/serializers/attributes | Serializer Attributes Documentation}
      */
     customAttribute(name, fn, options) {
         this.attributes.push({
@@ -131,25 +170,47 @@ export default class ObjectSerializerBuilder {
      * since association schemas cannot be inferred from plain objects.
      *
      * @param name - The association property name
-     * @param options - Configuration options including required serializer and OpenAPI schema
+     * @param options - Configuration options:
+     *   - `as` - Rename the association key in the serialized output
+     *   - `flatten` - When `true`, spreads the rendered association's attributes directly into
+     *     the parent serialized output instead of nesting them under `name`. Be aware of
+     *     attribute shadowing: if the parent and flattened association share attribute names
+     *     (e.g., `id`), the flattened association's values overwrite the parent's
+     *   - `optional` - When `true`, allows the association to be null/missing without causing
+     *     an `OpenapiResponseValidationFailure` during Psychic controller unit specs. By default,
+     *     `rendersOne` expects the association to be present (mirroring the `optional` option on
+     *     `@deco.BelongsTo`). Set this to `true` when the association is genuinely nullable
+     *
+     *   For Dream associations:
+     *   - `dreamClass` - The Dream model class, enabling serializer inference; when specified,
+     *     `serializerKey` may also be provided to select a specific registered serializer
+     *   - `serializer` - Provide an explicit serializer function
+     *
+     *   For ViewModel associations:
+     *   - `viewModelClass` + optional `serializerKey`
+     *   - `serializer`
+     *
+     *   For non-Dream/non-ViewModel associations:
+     *   - `serializer` is required
      * @returns The serializer builder for method chaining
      *
      * @example
      * ```typescript
      * // With explicit serializer function
-     * .rendersOne('owner', UserSerializer, {
-     *   openapi: { $ref: '#/components/schemas/User' }
-     * })
+     * .rendersOne('owner', { serializer: CustomOwnerSerializer })
      *
-     * // With Dream class reference
+     * // With Dream class reference and serializer key
      * .rendersOne('creator', {
      *   dreamClass: User,
-     *   serializerKey: 'summary',
-     *   openapi: { $ref: '#/components/schemas/UserSummary' }
+     *   serializerKey: 'summary'
      * })
-     * ```
      *
-     * See: {@link https://your-docs-url.com/docs/serializers/associations | Serializer Associations Documentation}
+     * // Allow null association
+     * .rendersOne('approver', { serializer: UserSerializer, optional: true })
+     *
+     * // Flatten into parent object
+     * .rendersOne('profile', { serializer: ProfileSerializer, flatten: true })
+     * ```
      */
     rendersOne(name, options) {
         this.attributes.push({
@@ -165,32 +226,43 @@ export default class ObjectSerializerBuilder {
      * For ObjectSerializer, explicit serializer configuration is always required
      * since association schemas cannot be inferred from plain objects.
      *
-     * @param name - The association property name (should be an array)
-     * @param options - Configuration options including required serializer and OpenAPI schema
+     * @param name - The association property name (should resolve to an array)
+     * @param options - Configuration options:
+     *   - `as` - Rename the association key in the serialized output
+     *
+     *   For Dream associations:
+     *   - `dreamClass` - The Dream model class, enabling serializer inference; when specified,
+     *     `serializerKey` may also be provided to select a specific registered serializer
+     *   - `serializer` - Provide an explicit serializer function
+     *
+     *   For ViewModel associations:
+     *   - `viewModelClass` + optional `serializerKey`
+     *   - `serializer`
+     *
+     *   For non-Dream/non-ViewModel associations:
+     *   - `serializer` is required
      * @returns The serializer builder for method chaining
      *
      * @example
      * ```typescript
      * // With explicit serializer function
-     * .rendersMany('articles', ArticleSerializer, {
-     *   openapi: {
-     *     type: 'array',
-     *     items: { $ref: '#/components/schemas/Article' }
-     *   }
+     * .rendersMany('articles', { serializer: ArticleSerializer })
+     *
+     * // With Dream class reference and serializer key
+     * .rendersMany('posts', {
+     *   dreamClass: Post,
+     *   serializerKey: 'summary'
      * })
      *
      * // With ViewModel class reference
      * .rendersMany('comments', {
      *   viewModelClass: CommentViewModel,
-     *   serializer: CommentViewModelSerializer,
-     *   openapi: {
-     *     type: 'array',
-     *     items: { $ref: '#/components/schemas/Comment' }
-     *   }
+     *   serializer: CommentViewModelSerializer
      * })
-     * ```
      *
-     * See: {@link https://your-docs-url.com/docs/serializers/associations | Serializer Associations Documentation}
+     * // Rename output key
+     * .rendersMany('articles', { serializer: ArticleSerializer, as: 'posts' })
+     * ```
      */
     rendersMany(name, options) {
         this.attributes.push({
@@ -203,13 +275,13 @@ export default class ObjectSerializerBuilder {
     /**
      * Executes the serializer and returns the serialized output.
      *
-     * This method processes all defined attributes, custom attributes, delegated attributes,
-     * and associations to produce the final serialized object. The result is suitable for
-     * JSON.stringify() and API responses.
+     * Processes all defined attributes, custom attributes, delegated attributes,
+     * and associations to produce the final serialized object.
      *
      * @param passthrough - Additional data to pass through to nested serializers
+     *   (e.g., locale, current user context)
      * @param opts - Rendering options for customizing the serialization process
-     * @returns The serialized object
+     * @returns The serialized object, suitable for JSON responses
      *
      * @example
      * ```typescript
@@ -219,8 +291,6 @@ export default class ObjectSerializerBuilder {
      * // With passthrough data for nested serializers
      * const result = UserViewModelSerializer(userVm).render({ currentUserId: '456' })
      * ```
-     *
-     * See: {@link https://your-docs-url.com/docs/serializers/render | Serializer Rendering Documentation}
      */
     render(passthrough = {}, opts = {}) {
         return new SerializerRenderer(this, passthrough, opts).render();

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

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

package/dist/types/src/Dream.d.ts

@@ -2368,13 +2368,28 @@ export default class Dream {
      */
     passthrough<I extends Dream, PassthroughColumns extends PassthroughColumnNames<I>>(this: I, passthroughWhereStatement: PassthroughOnClause<PassthroughColumns>): LoadBuilder<I>;
     /**
-     * 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()
@@ -2387,7 +2402,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<I extends Dream, DB extends I['DB'], TableName extends I['table'], Schema extends I['schema'], const Arr extends readonly unknown[]>(this: I, ...args: [...Arr, VariadicLoadArgs<I, DB, Schema, TableName, Arr>]): LoadBuilder<I>;
     /**
@@ -2557,19 +2572,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()
@@ -2582,7 +2597,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<I extends Dream, DB extends I['DB'], TableName extends I['table'], Schema extends I['schema'], const Arr extends readonly unknown[]>(this: I, ...args: [...Arr, VariadicLeftJoinLoadArgs<I, DB, Schema, TableName, Arr>]): LeftJoinLoadBuilder<I>;
     /**