@rvoh/dream 0.45.0 → 0.45.1

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

@@ -13,12 +13,12 @@ const CannotPaginateWithLimit_js_1 = require("../errors/pagination/CannotPaginat
 const CannotPaginateWithOffset_js_1 = require("../errors/pagination/CannotPaginateWithOffset.js");
 const RecordNotFound_js_1 = require("../errors/RecordNotFound.js");
 const cloneDeepSafe_js_1 = require("../helpers/cloneDeepSafe.js");
-const compact_js_1 = require("../helpers/compact.js");
 const isObject_js_1 = require("../helpers/isObject.js");
 const namespaceColumn_js_1 = require("../helpers/namespaceColumn.js");
 const protectAgainstPollutingAssignment_js_1 = require("../helpers/protectAgainstPollutingAssignment.js");
 const index_js_2 = require("../ops/index.js");
 const computedPaginatePage_js_1 = require("./internal/computedPaginatePage.js");
+const convertDreamClassAndAssociationNameTupleArrayToPreloadArgs_js_1 = require("./internal/convertDreamClassAndAssociationNameTupleArrayToPreloadArgs.js");
 const extractNestedPaths_js_1 = require("./internal/extractNestedPaths.js");
 const Postgres_js_1 = require("./QueryDriver/Postgres.js");
 class Query {
@@ -493,41 +493,35 @@ class Query {
      * 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('detailed', (dreamClass, associationName) => {
+     *   if (dreamClass.typeof(Post) && associationName === 'comments') {
+     *     return { and: { published: true } }
      *   }
-     * }).all()
+     * })
+     *   .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()
+     *   .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
      */
-    preloadForSerialization({ serializerKey, modifierFn, } = {}) {
+    preloadFor(serializerKey, modifierFn) {
         const preloadArgs = (0, extractNestedPaths_js_1.default)(this.dreamClass['serializationMap'](serializerKey));
         let query = this;
         preloadArgs.forEach(dreamClassAndAssociationNameTupleArray => {
-            query = query.preload(...this.convertDreamClassAndAssociationNameTupleArrayToPreloadArgs(dreamClassAndAssociationNameTupleArray, modifierFn));
+            query = query.preload(...(0, convertDreamClassAndAssociationNameTupleArrayToPreloadArgs_js_1.default)(dreamClassAndAssociationNameTupleArray, modifierFn));
         });
         return query;
     }
@@ -555,59 +549,39 @@ class Query {
      * 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()
+     * })
+     *   .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()
+     *   .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
      */
-    leftJoinPreloadForSerialization({ serializerKey, modifierFn, } = {}) {
+    leftJoinPreloadFor(serializerKey, modifierFn) {
         const preloadArgs = (0, extractNestedPaths_js_1.default)(this.dreamClass['serializationMap'](serializerKey));
         let query = this;
         const counter = { count: 0 };
         preloadArgs.forEach(dreamClassAndAssociationNameTupleArray => {
-            query = query.leftJoinPreload(...this.convertDreamClassAndAssociationNameTupleArrayToPreloadArgs(dreamClassAndAssociationNameTupleArray, modifierFn, counter));
+            query = query.leftJoinPreload(...(0, convertDreamClassAndAssociationNameTupleArrayToPreloadArgs_js_1.default)(dreamClassAndAssociationNameTupleArray, modifierFn, counter));
         });
         return query;
     }
-    convertDreamClassAndAssociationNameTupleArrayToPreloadArgs(dreamClassAndAssociationNameTupleArray, modifierFn, counter) {
-        return (0, compact_js_1.default)(dreamClassAndAssociationNameTupleArray.flatMap(dreamClassAndAssociationNameTuple => {
-            const associationName = dreamClassAndAssociationNameTuple[1];
-            const aliasedAssociationName = counter
-                ? `${dreamClassAndAssociationNameTuple[1]} as drsz${counter.count++}`
-                : dreamClassAndAssociationNameTuple[1];
-            if (!modifierFn)
-                return aliasedAssociationName;
-            const modifier = modifierFn(dreamClassAndAssociationNameTuple[0], associationName);
-            if (modifier === 'omit')
-                return undefined;
-            return [aliasedAssociationName, modifier];
-        }));
-    }
     /**
      * Returns a new Query instance, with the provided
      * joins statement attached

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

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = convertDreamClassAndAssociationNameTupleArrayToPreloadArgs;
+const compact_js_1 = require("../../helpers/compact.js");
+function convertDreamClassAndAssociationNameTupleArrayToPreloadArgs(dreamClassAndAssociationNameTupleArray, modifierFn, counter) {
+    return (0, compact_js_1.default)(dreamClassAndAssociationNameTupleArray.flatMap(dreamClassAndAssociationNameTuple => {
+        const associationName = dreamClassAndAssociationNameTuple[1];
+        const aliasedAssociationName = counter
+            ? `${dreamClassAndAssociationNameTuple[1]} as drsz${counter.count++}`
+            : dreamClassAndAssociationNameTuple[1];
+        if (!modifierFn)
+            return aliasedAssociationName;
+        const modifier = modifierFn(dreamClassAndAssociationNameTuple[0], associationName);
+        if (modifier === 'omit')
+            return undefined;
+        return [aliasedAssociationName, modifier];
+    }));
+}

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

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = unaliasTableName;
+const extractAssociationMetadataFromAssociationName_js_1 = require("./extractAssociationMetadataFromAssociationName.js");
+function unaliasTableName(tableName) {
+    return (0, extractAssociationMetadataFromAssociationName_js_1.default)(tableName).name;
+}

package/dist/esm/src/Dream.js

@@ -1146,38 +1146,31 @@ export default 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`
@@ -1203,38 +1196,31 @@ export default 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
@@ -3081,6 +3067,54 @@ export default class Dream {
     load(...args) {
         return new LoadBuilder(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(this)['loadFor'](serializerKey, modifierFn);
+    }
     /**
      * Load each specified association using a single SQL query.
      * See {@link Dream.load} for loading in separate queries.
@@ -3115,6 +3149,54 @@ export default class Dream {
     leftJoinLoad(...args) {
         return new LeftJoinLoadBuilder(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(this)['leftJoinLoadFor'](serializerKey, modifierFn);
+    }
     /**
      * Returns true if the association specified has
      * been loaded on this instance

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

@@ -368,6 +368,52 @@ export default 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,
@@ -392,6 +438,52 @@ export default 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/esm/src/dream/DreamInstanceTransactionBuilder.js

@@ -53,6 +53,55 @@ export default class DreamInstanceTransactionBuilder {
     load(...args) {
         return new LoadBuilder(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(this.dreamInstance, this.dreamTransaction)['loadFor'](serializerKey, modifierFn);
+    }
     /**
      * Load each specified association using a single SQL query.
      * See {@link #load} for loading in separate queries.
@@ -88,6 +137,55 @@ export default class DreamInstanceTransactionBuilder {
     leftJoinLoad(...args) {
         return new LeftJoinLoadBuilder(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(this.dreamInstance, this.dreamTransaction)['leftJoinLoadFor'](serializerKey, modifierFn);
+    }
     /**
      * Returns a new Query instance with the provided
      * inner join statement attached