@rvoh/dream 0.45.0 → 0.45.2

package/dist/cjs/src/Dream.js

@@ -1148,38 +1148,31 @@ class Dream {
      * await User.preload('posts', 'comments', 'replies').all()
      *
      * // Automatically preload everything needed for serialization:
-     * await User.preloadForSerialization({ serializerKey: 'summary' }).all()
+     * await User.preloadFor('summary').all()
      *
      * // Add where conditions to specific associations during preloading:
-     * await User.preloadForSerialization({
-     *   serializerKey: 'detailed',
-     *   modifierFn: (dreamClass, associationName) => {
-     *     if (dreamClass.typeof(Post) && associationName === 'comments') {
-     *       return { and: { published: true } }
-     *     }
+     * await User.preloadFor('default', (dreamClass, associationName) => {
+     *   if (dreamClass.typeof(Post) && associationName === 'comments') {
+     *     return { and: { published: true } }
      *   }
      * }).all()
      *
      * // Skip preloading specific associations to handle them manually:
-     * await User.preloadForSerialization({
-     *   serializerKey: 'summary',
-     *   modifierFn: (dreamClass, associationName) => {
-     *     if (dreamClass.typeof(User) && associationName === 'posts') {
-     *       return 'omit' // Handle posts preloading separately with custom logic
-     *     }
+     * await User.preloadFor('summary', (dreamClass, associationName) => {
+     *   if (dreamClass.typeof(User) && associationName === 'posts') {
+     *     return 'omit' // Handle posts preloading separately with custom logic
      *   }
      * })
      * .preload('posts', { and: { featured: true } }) // Custom preloading
      * .all()
      * ```
      *
-     * @param opts - Configuration options for serialization preloading
-     * @param opts.serializerKey - The serializer key to use for determining which associations to preload. Defaults to 'default'
-     * @param opts.modifierFn - Optional callback function to modify or omit specific associations during preloading. Called for each association with the Dream class and association name. Return an object with `and`, `andAny`, or `andNot` properties to add where conditions, return 'omit' to skip preloading that association (useful when you want to handle it manually), or return undefined to use default preloading
+     * @param serializerKey - The serializer key to use for determining which associations to preload.
+     * @param modifierFn - Optional callback function to modify or omit specific associations during preloading. Called for each association with the Dream class and association name. Return an object with `and`, `andAny`, or `andNot` properties to add where conditions, return 'omit' to skip preloading that association (useful when you want to handle it manually), or return undefined to use default preloading
      * @returns A Query with all serialization associations preloaded
      */
-    static preloadForSerialization(opts = {}) {
-        return this.query().preloadForSerialization(opts);
+    static preloadFor(serializerKey, modifierFn) {
+        return this.query().preloadFor(serializerKey, modifierFn);
     }
     /**
      * Recursively preloads all Dream associations referenced by `rendersOne` and `rendersMany`
@@ -1205,38 +1198,31 @@ class Dream {
      * await User.leftJoinPreload('posts', 'comments', 'replies').all()
      *
      * // Automatically left join preload everything needed for serialization:
-     * await User.leftJoinPreloadForSerialization({ serializerKey: 'summary' }).all()
+     * await User.leftJoinPreloadFor('summary').all()
      *
      * // Add where conditions to specific associations during left join preloading:
-     * await User.leftJoinPreloadForSerialization({
-     *   serializerKey: 'detailed',
-     *   modifierFn: (dreamClass, associationName) => {
-     *     if (dreamClass.typeof(Post) && associationName === 'comments') {
-     *       return { and: { published: true } }
-     *     }
+     * await User.leftJoinPreloadFor('detailed', (dreamClass, associationName) => {
+     *   if (dreamClass.typeof(Post) && associationName === 'comments') {
+     *     return { and: { published: true } }
      *   }
      * }).all()
      *
      * // Skip left join preloading specific associations to handle them manually:
-     * await User.leftJoinPreloadForSerialization({
-     *   serializerKey: 'summary',
-     *   modifierFn: (dreamClass, associationName) => {
-     *     if (dreamClass.typeof(User) && associationName === 'posts') {
-     *       return 'omit' // Handle posts preloading separately with custom logic
-     *     }
+     * await User.leftJoinPreloadFor('summary', (dreamClass, associationName) => {
+     *   if (dreamClass.typeof(User) && associationName === 'posts') {
+     *     return 'omit' // Handle posts preloading separately with custom logic
      *   }
      * })
      * .preload('posts', { and: { featured: true } }) // Custom preloading instead
      * .all()
      * ```
      *
-     * @param opts - Configuration options for serialization preloading
-     * @param opts.serializerKey - The serializer key to use for determining which associations to preload. Defaults to 'default'
-     * @param opts.modifierFn - Optional callback function to modify or omit specific associations during preloading. Called for each association with the Dream class and association name. Return an object with `and`, `andAny`, or `andNot` properties to add where conditions, return 'omit' to skip preloading that association (useful when you want to handle it manually), or return undefined to use default preloading
+     * @param serializerKey - The serializer key to use for determining which associations to preload.
+     * @param modifierFn - Optional callback function to modify or omit specific associations during preloading. Called for each association with the Dream class and association name. Return an object with `and`, `andAny`, or `andNot` properties to add where conditions, return 'omit' to skip preloading that association (useful when you want to handle it manually), or return undefined to use default preloading
      * @returns A Query with all serialization associations left join preloaded
      */
-    static leftJoinPreloadForSerialization(opts = {}) {
-        return this.query().leftJoinPreloadForSerialization(opts);
+    static leftJoinPreloadFor(serializerKey, modifierFn) {
+        return this.query().leftJoinPreloadFor(serializerKey, modifierFn);
     }
     /**
      * Returns a new Query instance with the provided
@@ -3083,6 +3069,54 @@ class Dream {
     load(...args) {
         return new LoadBuilder_js_1.default(this).load(...args);
     }
+    /**
+     * Recursively loads all Dream associations referenced by `rendersOne` and `rendersMany`
+     * in a DreamSerializer. This traverses the entire content tree of serializers to automatically
+     * load all necessary associations, eliminating N+1 query problems and removing the need to
+     * manually remember which associations to preload for serialization.
+     *
+     * This method decouples data loading code from data rendering code by having the serializer
+     * (rendering code) inform the query (loading code) about which associations are needed.
+     * As serializers evolve over time - adding new `rendersOne` and `rendersMany` calls or
+     * modifying existing ones - the loading code automatically adapts without requiring
+     * corresponding modifications to preload statements.
+     *
+     * This method analyzes the serializer (specified by `serializerKey` or 'default') and
+     * automatically preloads all associations that will be needed during serialization.
+     *
+     * ```ts
+     * // Instead of manually specifying all associations:
+     * await User.preload('posts', 'comments', 'replies').all()
+     *
+     * // Automatically preload everything needed for serialization:
+     * await user.loadFor('summary').execute()
+     *
+     * // Add where conditions to specific associations during preloading:
+     * await user.loadFor('detailed', (dreamClass, associationName) => {
+     *   if (dreamClass.typeof(Post) && associationName === 'comments') {
+     *     return { and: { published: true } }
+     *   }
+     * })
+     *    .execute()
+     *
+     * // Skip preloading specific associations to handle them manually:
+     * await user
+     *   .loadFor('summary', (dreamClass, associationName) => {
+     *     if (dreamClass.typeof(User) && associationName === 'posts') {
+     *       return 'omit' // Handle posts preloading separately with custom logic
+     *     }
+     *   })
+     *     .load('posts', { and: { featured: true } }) // Custom preloading
+     *     .execute()
+     * ```
+     *
+     * @param serializerKey - The serializer key to use for determining which associations to preload.
+     * @param modifierFn - Optional callback function to modify or omit specific associations during preloading. Called for each association with the Dream class and association name. Return an object with `and`, `andAny`, or `andNot` properties to add where conditions, return 'omit' to skip preloading that association (useful when you want to handle it manually), or return undefined to use default preloading
+     * @returns A Query with all serialization associations preloaded
+     */
+    loadFor(serializerKey, modifierFn) {
+        return new LoadBuilder_js_1.default(this)['loadFor'](serializerKey, modifierFn);
+    }
     /**
      * Load each specified association using a single SQL query.
      * See {@link Dream.load} for loading in separate queries.
@@ -3117,6 +3151,54 @@ class Dream {
     leftJoinLoad(...args) {
         return new LeftJoinLoadBuilder_js_1.default(this).leftJoinLoad(...args);
     }
+    /**
+     * Recursively loads all Dream associations referenced by `rendersOne` and `rendersMany`
+     * in a DreamSerializer. This traverses the entire content tree of serializers to automatically
+     * load all necessary associations, eliminating N+1 query problems and removing the need to
+     * manually remember which associations to preload for serialization.
+     *
+     * This method decouples data loading code from data rendering code by having the serializer
+     * (rendering code) inform the query (loading code) about which associations are needed.
+     * As serializers evolve over time - adding new `rendersOne` and `rendersMany` calls or
+     * modifying existing ones - the loading code automatically adapts without requiring
+     * corresponding modifications to preload statements.
+     *
+     * This method analyzes the serializer (specified by `serializerKey` or 'default') and
+     * automatically preloads all associations that will be needed during serialization.
+     *
+     * ```ts
+     * // Instead of manually specifying all associations:
+     * await User.preload('posts', 'comments', 'replies').all()
+     *
+     * // Automatically preload everything needed for serialization:
+     * await user.leftJoinLoadFor('summary').execute()
+     *
+     * // Add where conditions to specific associations during preloading:
+     * await user.leftJoinLoadFor('detailed', (dreamClass, associationName) => {
+     *   if (dreamClass.typeof(Post) && associationName === 'comments') {
+     *     return { and: { published: true } }
+     *   }
+     * })
+     *    .execute()
+     *
+     * // Skip preloading specific associations to handle them manually:
+     * await user
+     *   .loadFor('summary', (dreamClass, associationName) => {
+     *     if (dreamClass.typeof(User) && associationName === 'posts') {
+     *       return 'omit' // Handle posts preloading separately with custom logic
+     *     }
+     *   })
+     *     .load('posts', { and: { featured: true } }) // Custom preloading
+     *     .execute()
+     * ```
+     *
+     * @param serializerKey - The serializer key to use for determining which associations to preload.
+     * @param modifierFn - Optional callback function to modify or omit specific associations during preloading. Called for each association with the Dream class and association name. Return an object with `and`, `andAny`, or `andNot` properties to add where conditions, return 'omit' to skip preloading that association (useful when you want to handle it manually), or return undefined to use default preloading
+     * @returns A Query with all serialization associations preloaded
+     */
+    leftJoinLoadFor(serializerKey, modifierFn) {
+        return new LeftJoinLoadBuilder_js_1.default(this)['leftJoinLoadFor'](serializerKey, modifierFn);
+    }
     /**
      * Returns true if the association specified has
      * been loaded on this instance

package/dist/cjs/src/bin/index.js

@@ -21,13 +21,17 @@ class DreamBin {
         await Query_js_1.default.dbDriverClass().rollback(opts);
     }
     static async generateDream(fullyQualifiedModelName, columnsWithTypes, options) {
-        await (0, generateDream_js_1.default)({ fullyQualifiedModelName, columnsWithTypes, options });
+        await (0, generateDream_js_1.default)({
+            fullyQualifiedModelName,
+            columnsWithTypes,
+            options: { includeAdminSerializers: false, ...options },
+        });
     }
     static async generateStiChild(fullyQualifiedModelName, fullyQualifiedParentName, columnsWithTypes, options) {
         await (0, generateDream_js_1.default)({
             fullyQualifiedModelName,
             columnsWithTypes,
-            options: { ...options, stiBaseSerializer: false },
+            options: { includeAdminSerializers: false, ...options, stiBaseSerializer: false },
             fullyQualifiedParentName,
         });
     }

package/dist/cjs/src/cli/index.js

@@ -6,6 +6,40 @@ const index_js_2 = require("../dream-app/index.js");
 const EnvInternal_js_1 = require("../helpers/EnvInternal.js");
 const sspawn_js_1 = require("../helpers/sspawn.js");
 const DreamCliLogger_js_1 = require("./logger/DreamCliLogger.js");
+const INDENT = '                  ';
+const columnsWithTypesDescription = `space separated snake-case (except for belongs_to model name) properties like this:
+${INDENT}    title:citext subtitle:string body_markdown:text style:enum:post_styles:formal,informal User:belongs_to
+${INDENT}
+${INDENT}all properties default to not nullable; null can be allowed by appending ':optional':
+${INDENT}    subtitle:string:optional
+${INDENT}
+${INDENT}supported types:
+${INDENT}    - citext:
+${INDENT}        case insensitive text (indexes and queries are automatically case insensitive)
+${INDENT}
+${INDENT}    - string:
+${INDENT}        varchar; allowed length defaults to 255, but may be customized, e.g.: subtitle:string:128 or subtitle:string:128:optional
+${INDENT}
+${INDENT}    - text
+${INDENT}
+${INDENT}    - integer
+${INDENT}
+${INDENT}    - decimal:
+${INDENT}        scale,precision is required, e.g.: volume:decimal:3,2 or volume:decimal:3,2:optional
+${INDENT}
+${INDENT}    - enum:
+${INDENT}        include the enum name to automatically create the enum:
+${INDENT}          type:enum:room_types:bathroom,kitchen,bedroom or type:enum:room_types:bathroom,kitchen,bedroom:optional
+${INDENT}
+${INDENT}        omit the enum values to leverage an existing enum (omits the enum type creation):
+${INDENT}          type:enum:room_types or type:enum:room_types:optional
+${INDENT}
+${INDENT}    - belongs_to:
+${INDENT}        Not only updates the migration but also adds a BelongsTo association to the generated model:
+${INDENT}          Place:belongs_to
+${INDENT}        
+${INDENT}        Include the full Path to the model. E.g., if the Coach model is in src/app/models/Health/Coach:
+${INDENT}          Health/Coach:belongs_to`;
 class DreamCLI {
     /**
      * use this method for initializing a standalone dream application. If using Psychic and Dream together,
@@ -35,7 +69,7 @@ class DreamCLI {
             .alias('g:migration')
             .description('create a new migration')
             .argument('<migrationName>', 'end with -to-table-name to prepopulate with an alterTable command')
-            .argument('[columnsWithTypes...]', 'properties of the model column1:text/string/enum/etc. column2:text/string/enum/etc. ... columnN:text/string/enum/etc.')
+            .argument('[columnsWithTypes...]', columnsWithTypesDescription)
             .action(async (migrationName, columnsWithTypes) => {
             await initializeDreamApp();
             await index_js_1.default.generateMigration(migrationName, columnsWithTypes);
@@ -47,7 +81,7 @@ class DreamCLI {
             .alias('generate:dream')
             .alias('g:dream')
             .option('--no-serializer')
-            .option('--sti-base-serializer', 'Omits the serializer from the dream model, but does create the serializer so it can be extended by STI children')
+            .option('--sti-base-serializer', 'omits the serializer from the dream model, but does create the serializer so it can be extended by STI children')
             .description('create a new Dream model')
             .argument('<modelName>', 'the name of the model to create, e.g. Post or Settings/CommunicationPreferences')
             .argument('[columnsWithTypes...]', 'properties of the model property1:text/string/enum/etc. property2:text/string/enum/etc. ... propertyN:text/string/enum/etc.')
@@ -62,9 +96,11 @@ class DreamCLI {
             .description('create a new Dream model that extends another Dream model, leveraging STI (single table inheritance)')
             .option('--no-serializer')
             .argument('<childModelName>', 'the name of the model to create, e.g. Post or Settings/CommunicationPreferences')
-            .argument('<extends>', 'just the word extends')
-            .argument('<parentModelName>', 'name of the parent model')
-            .argument('[columnsWithTypes...]', 'properties of the model property1:text/string/enum/etc. property2:text/string/enum/etc. ... propertyN:text/string/enum/etc.')
+            .argument('<extends>', 'just the word "extends"')
+            .argument('<parentModelName>', `fully qualified name of the parent model, e.g.:
+${INDENT}    to extend the Room model in src/app/models/Room: Room
+${INDENT}    to extend the Coach model in src/app/models/Health/Coach: Health/Coach`)
+            .argument('[columnsWithTypes...]', columnsWithTypesDescription)
             .action(async (childModelName, extendsWord, parentModelName, columnsWithTypes, options) => {
             await initializeDreamApp();
             if (extendsWord !== 'extends')

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

@@ -370,6 +370,52 @@ class DreamClassTransactionBuilder {
     leftJoinPreload(...args) {
         return this.queryInstance().leftJoinPreload(...args);
     }
+    /**
+     * Recursively left-join-preloads all Dream associations referenced by `rendersOne` and `rendersMany`
+     * in a DreamSerializer. This traverses the entire content tree of serializers to automatically
+     * load all necessary associations, eliminating N+1 query problems and removing the need to
+     * manually remember which associations to preload for serialization.
+     *
+     * This method decouples data loading code from data rendering code by having the serializer
+     * (rendering code) inform the query (loading code) about which associations are needed.
+     * As serializers evolve over time - adding new `rendersOne` and `rendersMany` calls or
+     * modifying existing ones - the loading code automatically adapts without requiring
+     * corresponding modifications to preload statements.
+     *
+     * This method analyzes the serializer (specified by `serializerKey` or 'default') and
+     * automatically preloads all associations that will be needed during serialization.
+     *
+     * ```ts
+     * // Instead of manually specifying all associations:
+     * await User.preload('posts', 'comments', 'replies').all()
+     *
+     * // Automatically preload everything needed for serialization:
+     * await User.preloadFor('summary').all()
+     *
+     * // Add where conditions to specific associations during preloading:
+     * await User.txn(txn).leftJoinPreloadFor('detailed', (dreamClass, associationName) => {
+     *   if (dreamClass.typeof(Post) && associationName === 'comments') {
+     *     return { and: { published: true } }
+     *   }
+     * }).all()
+     *
+     * // Skip preloading specific associations to handle them manually:
+     * await User.txn(txn).leftJoinPreloadFor('summary', (dreamClass, associationName) => {
+     *   if (dreamClass.typeof(User) && associationName === 'posts') {
+     *     return 'omit' // Handle posts preloading separately with custom logic
+     *   }
+     * })
+     * .preload('posts', { and: { featured: true } }) // Custom preloading
+     * .all()
+     * ```
+     *
+     * @param serializerKey - The serializer key to use for determining which associations to preload.
+     * @param modifierFn - Optional callback function to modify or omit specific associations during preloading. Called for each association with the Dream class and association name. Return an object with `and`, `andAny`, or `andNot` properties to add where conditions, return 'omit' to skip preloading that association (useful when you want to handle it manually), or return undefined to use default preloading
+     * @returns A Query with all serialization associations preloaded
+     */
+    leftJoinPreloadFor(serializerKey, modifierFn) {
+        return this.queryInstance().leftJoinPreloadFor(serializerKey, modifierFn);
+    }
     /**
      * Applies preload statement to a Query scoped to this model.
      * Upon instantiating records of this model type,
@@ -394,6 +440,52 @@ class DreamClassTransactionBuilder {
     preload(...args) {
         return this.queryInstance().preload(...args);
     }
+    /**
+     * Recursively preloads all Dream associations referenced by `rendersOne` and `rendersMany`
+     * in a DreamSerializer. This traverses the entire content tree of serializers to automatically
+     * load all necessary associations, eliminating N+1 query problems and removing the need to
+     * manually remember which associations to preload for serialization.
+     *
+     * This method decouples data loading code from data rendering code by having the serializer
+     * (rendering code) inform the query (loading code) about which associations are needed.
+     * As serializers evolve over time - adding new `rendersOne` and `rendersMany` calls or
+     * modifying existing ones - the loading code automatically adapts without requiring
+     * corresponding modifications to preload statements.
+     *
+     * This method analyzes the serializer (specified by `serializerKey` or 'default') and
+     * automatically preloads all associations that will be needed during serialization.
+     *
+     * ```ts
+     * // Instead of manually specifying all associations:
+     * await User.preload('posts', 'comments', 'replies').all()
+     *
+     * // Automatically preload everything needed for serialization:
+     * await User.preloadFor('summary').all()
+     *
+     * // Add where conditions to specific associations during preloading:
+     * await User.txn(txn).preloadFor('detailed', (dreamClass, associationName) => {
+     *   if (dreamClass.typeof(Post) && associationName === 'comments') {
+     *     return { and: { published: true } }
+     *   }
+     * }).all()
+     *
+     * // Skip preloading specific associations to handle them manually:
+     * await User.txn(txn).preloadFor('summary', (dreamClass, associationName) => {
+     *   if (dreamClass.typeof(User) && associationName === 'posts') {
+     *     return 'omit' // Handle posts preloading separately with custom logic
+     *   }
+     * })
+     * .preload('posts', { and: { featured: true } }) // Custom preloading
+     * .all()
+     * ```
+     *
+     * @param serializerKey - The serializer key to use for determining which associations to preload.
+     * @param modifierFn - Optional callback function to modify or omit specific associations during preloading. Called for each association with the Dream class and association name. Return an object with `and`, `andAny`, or `andNot` properties to add where conditions, return 'omit' to skip preloading that association (useful when you want to handle it manually), or return undefined to use default preloading
+     * @returns A Query with all serialization associations preloaded
+     */
+    preloadFor(serializerKey, modifierFn) {
+        return this.queryInstance().preloadFor(serializerKey, modifierFn);
+    }
     /**
      * Returns a new Query instance with the provided
      * inner join statement attached

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

@@ -55,6 +55,55 @@ class DreamInstanceTransactionBuilder {
     load(...args) {
         return new LoadBuilder_js_1.default(this.dreamInstance, this.dreamTransaction).load(...args);
     }
+    /**
+     * Recursively loads all Dream associations referenced by `rendersOne` and `rendersMany`
+     * in a DreamSerializer. This traverses the entire content tree of serializers to automatically
+     * load all necessary associations, eliminating N+1 query problems and removing the need to
+     * manually remember which associations to preload for serialization.
+     *
+     * This method decouples data loading code from data rendering code by having the serializer
+     * (rendering code) inform the query (loading code) about which associations are needed.
+     * As serializers evolve over time - adding new `rendersOne` and `rendersMany` calls or
+     * modifying existing ones - the loading code automatically adapts without requiring
+     * corresponding modifications to preload statements.
+     *
+     * This method analyzes the serializer (specified by `serializerKey` or 'default') and
+     * automatically preloads all associations that will be needed during serialization.
+     *
+     * ```ts
+     * // Instead of manually specifying all associations:
+     * await User.preload('posts', 'comments', 'replies').all()
+     *
+     * // Automatically preload everything needed for serialization:
+     * await user.loadFor('summary').execute()
+     *
+     * // Add where conditions to specific associations during preloading:
+     * await user.txn(txn).loadFor('detailed', (dreamClass, associationName) => {
+     *   if (dreamClass.typeof(Post) && associationName === 'comments') {
+     *     return { and: { published: true } }
+     *   }
+     * })
+     *    .execute()
+     *
+     * // Skip preloading specific associations to handle them manually:
+     * await user
+     *   .txn(txn)
+     *   .loadFor('summary', (dreamClass, associationName) => {
+     *     if (dreamClass.typeof(User) && associationName === 'posts') {
+     *       return 'omit' // Handle posts preloading separately with custom logic
+     *     }
+     *   })
+     *     .load('posts', { and: { featured: true } }) // Custom preloading
+     *     .execute()
+     * ```
+     *
+     * @param serializerKey - The serializer key to use for determining which associations to preload.
+     * @param modifierFn - Optional callback function to modify or omit specific associations during preloading. Called for each association with the Dream class and association name. Return an object with `and`, `andAny`, or `andNot` properties to add where conditions, return 'omit' to skip preloading that association (useful when you want to handle it manually), or return undefined to use default preloading
+     * @returns A Query with all serialization associations preloaded
+     */
+    loadFor(serializerKey, modifierFn) {
+        return new LoadBuilder_js_1.default(this.dreamInstance, this.dreamTransaction)['loadFor'](serializerKey, modifierFn);
+    }
     /**
      * Load each specified association using a single SQL query.
      * See {@link #load} for loading in separate queries.
@@ -90,6 +139,55 @@ class DreamInstanceTransactionBuilder {
     leftJoinLoad(...args) {
         return new LeftJoinLoadBuilder_js_1.default(this.dreamInstance, this.dreamTransaction).leftJoinLoad(...args);
     }
+    /**
+     * Recursively loads all Dream associations referenced by `rendersOne` and `rendersMany`
+     * in a DreamSerializer. This traverses the entire content tree of serializers to automatically
+     * load all necessary associations, eliminating N+1 query problems and removing the need to
+     * manually remember which associations to preload for serialization.
+     *
+     * This method decouples data loading code from data rendering code by having the serializer
+     * (rendering code) inform the query (loading code) about which associations are needed.
+     * As serializers evolve over time - adding new `rendersOne` and `rendersMany` calls or
+     * modifying existing ones - the loading code automatically adapts without requiring
+     * corresponding modifications to preload statements.
+     *
+     * This method analyzes the serializer (specified by `serializerKey` or 'default') and
+     * automatically preloads all associations that will be needed during serialization.
+     *
+     * ```ts
+     * // Instead of manually specifying all associations:
+     * await User.preload('posts', 'comments', 'replies').all()
+     *
+     * // Automatically preload everything needed for serialization:
+     * await user.leftJoinLoadFor('summary').execute()
+     *
+     * // Add where conditions to specific associations during preloading:
+     * await user.txn(txn).leftJoinLoadFor('detailed', (dreamClass, associationName) => {
+     *   if (dreamClass.typeof(Post) && associationName === 'comments') {
+     *     return { and: { published: true } }
+     *   }
+     * })
+     *    .execute()
+     *
+     * // Skip preloading specific associations to handle them manually:
+     * await user
+     *   .txn(txn)
+     *   .leftJoinLoadFor('summary', (dreamClass, associationName) => {
+     *     if (dreamClass.typeof(User) && associationName === 'posts') {
+     *       return 'omit' // Handle posts preloading separately with custom logic
+     *     }
+     *   })
+     *     .load('posts', { and: { featured: true } }) // Custom preloading
+     *     .execute()
+     * ```
+     *
+     * @param serializerKey - The serializer key to use for determining which associations to preload.
+     * @param modifierFn - Optional callback function to modify or omit specific associations during preloading. Called for each association with the Dream class and association name. Return an object with `and`, `andAny`, or `andNot` properties to add where conditions, return 'omit' to skip preloading that association (useful when you want to handle it manually), or return undefined to use default preloading
+     * @returns A Query with all serialization associations preloaded
+     */
+    leftJoinLoadFor(serializerKey, modifierFn) {
+        return new LeftJoinLoadBuilder_js_1.default(this.dreamInstance, this.dreamTransaction)['leftJoinLoadFor'](serializerKey, modifierFn);
+    }
     /**
      * Returns a new Query instance with the provided
      * inner join statement attached

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

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 const UnexpectedUndefined_js_1 = require("../errors/UnexpectedUndefined.js");
+const unaliasTableName_js_1 = require("./internal/unaliasTableName.js");
 class LeftJoinLoadBuilder {
     dreamTransaction;
     dream;
@@ -45,6 +46,55 @@ class LeftJoinLoadBuilder {
         this.query = this.query.leftJoinPreload(...args);
         return this;
     }
+    /**
+     * Recursively loads all Dream associations referenced by `rendersOne` and `rendersMany`
+     * in a DreamSerializer. This traverses the entire content tree of serializers to automatically
+     * load all necessary associations, eliminating N+1 query problems and removing the need to
+     * manually remember which associations to preload for serialization.
+     *
+     * This method decouples data loading code from data rendering code by having the serializer
+     * (rendering code) inform the query (loading code) about which associations are needed.
+     * As serializers evolve over time - adding new `rendersOne` and `rendersMany` calls or
+     * modifying existing ones - the loading code automatically adapts without requiring
+     * corresponding modifications to preload statements.
+     *
+     * This method analyzes the serializer (specified by `serializerKey` or 'default') and
+     * automatically preloads all associations that will be needed during serialization.
+     *
+     * ```ts
+     * // Instead of manually specifying all associations:
+     * await User.preload('posts', 'comments', 'replies').all()
+     *
+     * // Automatically preload everything needed for serialization:
+     * await user.leftJoinLoadFor('summary').execute()
+     *
+     * // Add where conditions to specific associations during preloading:
+     * await user.leftJoinLoadFor('detailed', (dreamClass, associationName) => {
+     *   if (dreamClass.typeof(Post) && associationName === 'comments') {
+     *     return { and: { published: true } }
+     *   }
+     * })
+     *    .execute()
+     *
+     * // Skip preloading specific associations to handle them manually:
+     * await user
+     *   .leftJoinLoadFor('summary', (dreamClass, associationName) => {
+     *     if (dreamClass.typeof(User) && associationName === 'posts') {
+     *       return 'omit' // Handle posts preloading separately with custom logic
+     *     }
+     *   })
+     *     .load('posts', { and: { featured: true } }) // Custom preloading
+     *     .execute()
+     * ```
+     *
+     * @param serializerKey - The serializer key to use for determining which associations to preload.
+     * @param modifierFn - Optional callback function to modify or omit specific associations during preloading. Called for each association with the Dream class and association name. Return an object with `and`, `andAny`, or `andNot` properties to add where conditions, return 'omit' to skip preloading that association (useful when you want to handle it manually), or return undefined to use default preloading
+     * @returns A Query with all serialization associations preloaded
+     */
+    leftJoinLoadFor(serializerKey, modifierFn) {
+        this.query = this.query.leftJoinPreloadFor(serializerKey, modifierFn);
+        return this;
+    }
     /**
      * executes a load builder query, binding
      * all associations to their respective model
@@ -63,7 +113,8 @@ class LeftJoinLoadBuilder {
             this.query = this.query.txn(this.dreamTransaction);
         }
         const dreamWithLoadedAssociations = await this.query.firstOrFail();
-        Object.keys(this.query['leftJoinStatements']).forEach(associationName => {
+        Object.keys(this.query['leftJoinStatements']).forEach(aliasedAssociationName => {
+            const associationName = (0, unaliasTableName_js_1.default)(aliasedAssociationName);
             const associationMetadata = this.dream['getAssociationMetadata'](associationName);
             if (associationMetadata === undefined)
                 throw new UnexpectedUndefined_js_1.default();