@rvoh/dream 1.2.1 → 1.3.0

package/dist/cjs/src/Dream.js

@@ -21,6 +21,7 @@ const destroyDream_js_1 = require("./dream/internal/destroyDream.js");
 const destroyOptions_js_1 = require("./dream/internal/destroyOptions.js");
 const ensureSTITypeFieldIsSet_js_1 = require("./dream/internal/ensureSTITypeFieldIsSet.js");
 const findOrCreateBy_js_1 = require("./dream/internal/findOrCreateBy.js");
+const printSerializerHierarchyLevel_js_1 = require("./dream/internal/printSerializerHierarchyLevel.js");
 const reload_js_1 = require("./dream/internal/reload.js");
 const runValidations_js_1 = require("./dream/internal/runValidations.js");
 const saveDream_js_1 = require("./dream/internal/saveDream.js");
@@ -49,10 +50,8 @@ const cloneDeepSafe_js_1 = require("./helpers/cloneDeepSafe.js");
 const DateTime_js_1 = require("./helpers/DateTime.js");
 const cachedTypeForAttribute_js_1 = require("./helpers/db/cachedTypeForAttribute.js");
 const isJsonColumn_js_1 = require("./helpers/db/types/isJsonColumn.js");
-const indent_js_1 = require("./helpers/indent.js");
 const notEqual_js_1 = require("./helpers/notEqual.js");
 const inferSerializerFromDreamOrViewModel_js_1 = require("./serializer/helpers/inferSerializerFromDreamOrViewModel.js");
-const serializerForAssociatedClass_js_1 = require("./serializer/helpers/serializerForAssociatedClass.js");
 class Dream {
     DB;
     /**
@@ -489,42 +488,65 @@ class Dream {
     static recursiveSerializationMap(serializer, { forDisplay = false, forDisplayDepth = 0, } = {}) {
         const serializerBuilder = serializer(undefined, undefined);
         const serializerAssociations = serializerBuilder['attributes'].filter(attribute => ['rendersOne', 'rendersMany', 'delegatedAttribute'].includes(attribute.type));
-        return serializerAssociations.reduce((acc, serializerAssociation) => {
+        return serializerAssociations.reduce((accumulator, serializerAssociation) => {
             const serializerAssociationName = serializerAssociation.targetName ??
                 serializerAssociation.name;
             const serializerAssociationType = serializerAssociation.type;
             const association = this['getAssociationMetadata'](serializerAssociationName);
             if (!association)
-                return acc;
-            const associatedClasses = association.modelCB();
-            const associatedClass = Array.isArray(associatedClasses) ? associatedClasses[0] : associatedClasses;
-            if (!associatedClass)
+                return accumulator;
+            const maybeAssociatedClasses = association.modelCB();
+            if (!maybeAssociatedClasses)
                 throw new Error(`No class defined on ${serializerAssociationName} association on ${this.sanitizedName}`);
-            const associationSerializer = (0, serializerForAssociatedClass_js_1.serializerForAssociatedClass)(this.prototype, serializerAssociationName, serializerAssociation.options);
-            if (!associationSerializer)
-                throw new Error(`No serializer found to render ${serializerAssociationName} on ${this.sanitizedName}`);
-            if (forDisplay && serializerAssociationType !== 'delegatedAttribute') {
-                const hierarchyLine = '└───';
-                const indentation = (0, indent_js_1.indent)((hierarchyLine.length + 1) * forDisplayDepth, {
-                    tabWidth: 1,
-                });
-                const prefix = `${hierarchyLine} `;
-                const nestedAssociationDisplay = indentation + `${prefix}${serializerAssociationType} ${yoctocolors_1.default.cyan(serializerAssociationName)}`;
-                console.log(nestedAssociationDisplay);
-                console.log(yoctocolors_1.default.gray(indentation +
-                    (0, indent_js_1.indent)(prefix.length, { tabWidth: 1 }) +
-                    associationSerializer.globalName));
-            }
-            acc[association.as] = {
-                parentDreamClass: this,
-                nestedSerializerInfo: serializerAssociation.type === 'delegatedAttribute'
-                    ? {}
-                    : associatedClass['recursiveSerializationMap'](associationSerializer, {
+            const associatedClasses = Array.isArray(maybeAssociatedClasses)
+                ? maybeAssociatedClasses
+                : [maybeAssociatedClasses];
+            /////////////////////////////////////////////////
+            // map associated classes to their serializers //
+            /////////////////////////////////////////////////
+            const associatedClassSerializerTuples = associatedClasses.flatMap(associatedClass => {
+                /**
+                 * `serializers` is an array because `associatedClass` may be an STI
+                 * base, with each of its STI children having its own serializer
+                 */
+                const serializers = serializerAssociation.options.serializer
+                    ? [serializerAssociation.options.serializer]
+                    : (0, inferSerializerFromDreamOrViewModel_js_1.inferSerializersFromDreamClassOrViewModelClass)(associatedClass, serializerAssociation.options.serializerKey);
+                if (!serializers.length)
+                    throw new Error(`No serializer found to render ${serializerAssociationName} on ${this.sanitizedName}`);
+                return serializers.map(serializer => [associatedClass, serializer]);
+            });
+            /////////////////////////////////////////////////////
+            // end:map associated classes to their serializers //
+            /////////////////////////////////////////////////////
+            ///////////////////////////////////////////////////////////////////////////////////////////////////
+            // reduce over all associated serializers, recursively building out their associated serializers //
+            ///////////////////////////////////////////////////////////////////////////////////////////////////
+            const innerAssociationSerializerInfo = associatedClassSerializerTuples.reduce((innerAccumulator, [associatedClass, associatedSerializer]) => {
+                if (forDisplay && serializerAssociationType !== 'delegatedAttribute') {
+                    (0, printSerializerHierarchyLevel_js_1.default)({
+                        serializerAssociationType,
+                        serializerAssociationName,
+                        associationSerializer: associatedSerializer,
+                        forDisplayDepth,
+                    });
+                }
+                return {
+                    ...innerAccumulator,
+                    ...associatedClass['recursiveSerializationMap'](associatedSerializer, {
                         forDisplay,
                         forDisplayDepth: forDisplayDepth + 1,
                     }),
+                };
+            }, {});
+            ///////////////////////////////////////////////////////////////////////////////////////////////////////
+            // end:reduce over all associated serializers, recursively building out their associated serializers //
+            ///////////////////////////////////////////////////////////////////////////////////////////////////////
+            accumulator[association.as] = {
+                parentDreamClass: this,
+                nestedSerializerInfo: serializerAssociation.type === 'delegatedAttribute' ? {} : innerAssociationSerializerInfo,
             };
-            return acc;
+            return accumulator;
         }, {});
     }
     /**
@@ -659,11 +681,57 @@ class Dream {
         return map;
     }
     /**
-     * @internal
+     * Checks whether the specified association has been defined on this Dream model.
+     *
+     * ```ts
+     * const user = User.new()
+     *
+     * user.hasAssociation('posts')
+     * // true (if User has a posts association defined)
+     *
+     * user.hasAssociation('nonExistentAssociation')
+     * // false
+     *
+     * // Useful for conditional association handling
+     * if (user.hasAssociation('posts')) {
+     *   user = await user.load('posts').execute()
+     * }
+     * ```
+     *
+     * @param associationName - The name of the association to check for
+     * @returns `true` if the association exists on this model, `false` otherwise
+     */
+    hasAssociation(associationName) {
+        return !!(this.associationMetadataByType.belongsTo.find(association => association.as === associationName) ||
+            this.associationMetadataByType.hasOne.find(association => association.as === associationName) ||
+            this.associationMetadataByType.hasMany.find(association => association.as === associationName));
+    }
+    /**
+     * Returns all of the association names for this Dream class.
+     * This includes all BelongsTo, HasOne, and HasMany associations
+     * defined on the model.
      *
-     * Returns all of the association names for this dream class
+     * This is useful for introspection, debugging, or dynamically working
+     * with all associations on a model.
+     *
+     * ```ts
+     * class User extends ApplicationModel {
+     *   @deco.HasMany('Post')
+     *   public posts: Post[]
+     *
+     *   @deco.HasOne('Profile')
+     *   public profile: Profile
+     *
+     *   @deco.BelongsTo('Company')
+     *   public company: Company
+     * }
+     *
+     * User.associationNames
+     * // ['posts', 'profile', 'company']
+     * })
+     * ```
      *
-     * @returns All of the association names for this dream class
+     * @returns An array containing all association names defined on this Dream class
      */
     static get associationNames() {
         const allAssociations = [

package/dist/cjs/src/dream/QueryDriver/Kysely.js

@@ -33,6 +33,7 @@ const dropDb_js_1 = require("../../helpers/db/dropDb.js");
 const loadPgClient_js_1 = require("../../helpers/db/loadPgClient.js");
 const runMigration_js_1 = require("../../helpers/db/runMigration.js");
 const EnvInternal_js_1 = require("../../helpers/EnvInternal.js");
+const groupBy_js_1 = require("../../helpers/groupBy.js");
 const isEmpty_js_1 = require("../../helpers/isEmpty.js");
 const namespaceColumn_js_1 = require("../../helpers/namespaceColumn.js");
 const normalizeUnicode_js_1 = require("../../helpers/normalizeUnicode.js");
@@ -1204,7 +1205,7 @@ class KyselyQueryDriver extends Base_js_1.default {
         const keys = Object.keys(preloadStatement);
         for (const key of keys) {
             const nestedDreams = await this.applyOnePreload(key, dream, this.applyablePreloadOnStatements(preloadOnStatements[key]));
-            if (nestedDreams) {
+            if (nestedDreams.length) {
                 await this.applyPreload(preloadStatement[key], preloadOnStatements[key], nestedDreams);
             }
         }
@@ -1699,18 +1700,10 @@ class KyselyQueryDriver extends Base_js_1.default {
      *
      * Used to preload polymorphic belongs to associations
      */
-    async preloadPolymorphicBelongsTo(association, dreams) {
-        if (!association.polymorphic)
-            throw new Error(`Association ${association.as} points to an array of models but is not designated polymorphic`);
-        if (association.type !== 'BelongsTo')
-            throw new Error(`Polymorphic association ${association.as} points to an array of models but is ${association.type}. Only BelongsTo associations may point to an array of models.`);
-        const nestedDreamsForNextRoundOfPreloading = [];
-        for (const associatedModel of association.modelCB()) {
-            await this.preloadPolymorphicAssociationModel(dreams, association, associatedModel, nestedDreamsForNextRoundOfPreloading);
-        }
-        return nestedDreamsForNextRoundOfPreloading;
+    async preloadPolymorphicBelongsTo(association, associatedModels, dreams) {
+        return (0, compact_js_1.default)(await Promise.all(associatedModels.map(associatedModel => this.preloadPolymorphicAssociationModel(dreams, association, associatedModel)))).flat();
     }
-    async preloadPolymorphicAssociationModel(dreams, association, associatedDreamClass, nestedDreamsForNextRoundOfPreloading) {
+    async preloadPolymorphicAssociationModel(dreams, association, associatedDreamClass) {
         const relevantAssociatedModels = dreams.filter((dream) => {
             const field = association.foreignKeyTypeField();
             return dream[field] === associatedDreamClass['stiBaseClassOrOwnClassName'] || dream[field] === null;
@@ -1729,7 +1722,6 @@ class KyselyQueryDriver extends Base_js_1.default {
                 [associatedDreamClass.primaryKey]: relevantAssociatedModels.map((dream) => dream[association.foreignKey()]),
             })
                 .all();
-            loadedAssociations.forEach((loadedAssociation) => nestedDreamsForNextRoundOfPreloading.push(loadedAssociation));
             //////////////////////////////////////////////////////////////////////////////////////////////
             // Associate each loaded association with each dream based on primary key and foreign key type
             //////////////////////////////////////////////////////////////////////////////////////////////
@@ -1744,6 +1736,7 @@ class KyselyQueryDriver extends Base_js_1.default {
             ///////////////////////////////////////////////////////////////////////////////////////////////////
             // end: Associate each loaded association with each dream based on primary key and foreign key type
             ///////////////////////////////////////////////////////////////////////////////////////////////////
+            return loadedAssociations;
         }
     }
     /**
@@ -1782,12 +1775,18 @@ class KyselyQueryDriver extends Base_js_1.default {
      *
      * Applies a preload statement
      */
-    async applyOnePreload(associationName, dreams, onStatement = {}) {
+    async applyOnePreload(associationNameAndMaybeAlias, dreams, onStatement = {}) {
         if (!Array.isArray(dreams))
             dreams = [dreams];
-        const dream = dreams.find(dream => dream['getAssociationMetadata'](associationName));
-        if (!dream)
-            return;
+        const { name: associationName } = (0, associationStringToNameAndAlias_js_1.default)(associationNameAndMaybeAlias);
+        dreams = dreams.filter(dream => dream.hasAssociation(associationName));
+        const groupedDreams = (0, groupBy_js_1.default)(dreams, dream => dream.sanitizedConstructorName);
+        return (await Promise.all(Object.keys(groupedDreams).map(key => this._applyOnePreload(associationName, groupedDreams[key], onStatement)))).flat();
+    }
+    async _applyOnePreload(associationName, dreams, onStatement = {}) {
+        if (!dreams.length)
+            return [];
+        const dream = dreams[0];
         const { name, alias: _alias } = (0, associationStringToNameAndAlias_js_1.default)(associationName);
         const alias = _alias || name;
         const association = dream['getAssociationMetadata'](name);
@@ -1795,8 +1794,10 @@ class KyselyQueryDriver extends Base_js_1.default {
             throw new UnexpectedUndefined_js_1.default();
         const dreamClass = dream.constructor;
         const dreamClassToHydrate = association.modelCB();
-        if ((association.polymorphic && association.type === 'BelongsTo') || Array.isArray(dreamClassToHydrate))
-            return this.preloadPolymorphicBelongsTo(association, dreams);
+        if (Array.isArray(dreamClassToHydrate)) {
+            const preloadedPolymorphicBelongsTos = await this.preloadPolymorphicBelongsTo(association, dreamClassToHydrate, dreams);
+            return preloadedPolymorphicBelongsTos;
+        }
         const dreamClassToHydrateColumns = [...dreamClassToHydrate.columns()];
         const columnsToPluck = dreamClassToHydrateColumns.map(column => this.namespaceColumn(column.toString(), alias));
         columnsToPluck.push(this.namespaceColumn(dreamClass.primaryKey, dreamClass.table));

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

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = printSerializerHierarchyLevel;
+const yoctocolors_1 = require("yoctocolors");
+const indent_js_1 = require("../../helpers/indent.js");
+function printSerializerHierarchyLevel({ serializerAssociationType, serializerAssociationName, associationSerializer, forDisplayDepth, }) {
+    const hierarchyLine = '└───';
+    const indentation = (0, indent_js_1.indent)((hierarchyLine.length + 1) * forDisplayDepth, {
+        tabWidth: 1,
+    });
+    const prefix = `${hierarchyLine} `;
+    const nestedAssociationDisplay = indentation + `${prefix}${serializerAssociationType} ${yoctocolors_1.default.cyan(serializerAssociationName)}`;
+    console.log(nestedAssociationDisplay);
+    console.log(yoctocolors_1.default.gray(indentation +
+        (0, indent_js_1.indent)(prefix.length, { tabWidth: 1 }) +
+        associationSerializer.globalName));
+}

package/dist/cjs/src/dream-app/cache.js

@@ -2,12 +2,22 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.cacheDreamApp = cacheDreamApp;
 exports.getCachedDreamAppOrFail = getCachedDreamAppOrFail;
+const EnvInternal_js_1 = require("../helpers/EnvInternal.js");
 let _dreamApp = undefined;
 function cacheDreamApp(dreamconf) {
     _dreamApp = dreamconf;
 }
 function getCachedDreamAppOrFail() {
-    if (!_dreamApp)
-        throw new Error('Must call `initializeDreamApp` or `initializePsychicApp` before loading cached DreamApp.getOrFail()');
+    if (!_dreamApp) {
+        const baseErrorMessage = 'Must call `initializeDreamApp` or `initializePsychicApp` before loading cached DreamApp.getOrFail().';
+        if (EnvInternal_js_1.default.isTest) {
+            throw new Error(`${baseErrorMessage}
+
+Check for specs running directly in a \`describe\` or \`context\` block rather than nested within an \`it\` block.`);
+        }
+        else {
+            throw new Error(baseErrorMessage);
+        }
+    }
     return _dreamApp;
 }

package/dist/cjs/src/helpers/cli/generateMigration.js

@@ -22,6 +22,7 @@ async function generateMigration({ migrationName, columnsWithTypes, fullyQualifi
             table: (0, snakeify_js_1.default)((0, pluralize_esm_1.default)((0, pascalizePath_js_1.default)(fullyQualifiedParentName))),
             columnsWithTypes,
             primaryKeyType: (0, primaryKeyType_js_1.default)(),
+            stiChildClassName: (0, pascalizePath_js_1.default)(fullyQualifiedModelName),
         });
     }
     else if (fullyQualifiedModelName) {

package/dist/cjs/src/helpers/cli/generateMigrationContent.js

@@ -9,13 +9,17 @@ const foreignKeyTypeFromPrimaryKey_js_1 = require("../db/foreignKeyTypeFromPrima
 const snakeify_js_1 = require("../snakeify.js");
 const STI_TYPE_COLUMN_NAME = 'type';
 const COLUMNS_TO_INDEX = [STI_TYPE_COLUMN_NAME];
-function generateMigrationContent({ table, columnsWithTypes = [], primaryKeyType = 'bigserial', createOrAlter = 'create', } = {}) {
+function generateMigrationContent({ table, columnsWithTypes = [], primaryKeyType = 'bigserial', createOrAlter = 'create', stiChildClassName, } = {}) {
     const altering = createOrAlter === 'alter';
     let requireCitextExtension = false;
-    const { columnDefs, columnDrops, indexDefs, indexDrops } = columnsWithTypes.reduce((acc, attribute) => {
+    const checkConstraints = [];
+    const { columnDefs, columnDrops, indexDefs, indexDrops } = columnsWithTypes.reduce((acc, attributeDeclaration) => {
         const { columnDefs, columnDrops, indexDefs, indexDrops } = acc;
-        const [nonStandardAttributeName, attributeType, ...descriptors] = attribute.split(':');
-        const optional = optionalFromDescriptors(descriptors);
+        const [nonStandardAttributeName, attributeType, ...descriptors] = attributeDeclaration.split(':');
+        const userWantsThisOptional = optionalFromDescriptors(descriptors);
+        // when creating a migration for an STI child, we don't want to include notNull;
+        // instead, we'll add a check constraint that uses the STI child class name
+        const optional = userWantsThisOptional || !!stiChildClassName;
         const sqlAttributeType = getAttributeType(attributeType, descriptors);
         let attributeName = (0, snakeify_js_1.default)(nonStandardAttributeName);
         if (attributeName === undefined)
@@ -24,6 +28,17 @@ function generateMigrationContent({ table, columnsWithTypes = [], primaryKeyType
             return acc;
         if (attributeType === 'citext')
             requireCitextExtension = true;
+        if (stiChildClassName && !userWantsThisOptional) {
+            checkConstraints.push(`
+
+  await db.schema
+    .alterTable('${table}')
+    .addCheckConstraint(
+      '${table}_not_null_${attributeName}',
+      sql\`type != '${stiChildClassName}' OR ${attributeName} IS NOT NULL\`,
+    )
+    .execute()`);
+        }
         switch (attributeType) {
             case 'belongs_to':
                 columnDefs.push(generateBelongsToStr(attributeName, {
@@ -100,7 +115,7 @@ ${citextExtension}${generateEnumStatements(columnsWithTypes)}  await db.schema
             ".addColumn('created_at', 'timestamp', col => col.notNull())" +
             newlineDoubleIndent +
             ".addColumn('updated_at', 'timestamp', col => col.notNull())"}
-    .execute()${indexDefs.length ? `\n${newlineIndent}` : ''}${indexDefs.join(newlineDoubleIndent)}
+    .execute()${indexDefs.length ? `\n${newlineIndent}` : ''}${indexDefs.join(newlineDoubleIndent)}${checkConstraints.join('')}
 }
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any

package/dist/cjs/src/helpers/cli/generateStiMigrationContent.js

@@ -2,6 +2,12 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.default = generateStiMigrationContent;
 const generateMigrationContent_js_1 = require("./generateMigrationContent.js");
-function generateStiMigrationContent({ table, columnsWithTypes = [], primaryKeyType = 'bigserial', } = {}) {
-    return (0, generateMigrationContent_js_1.default)({ table, columnsWithTypes, primaryKeyType, createOrAlter: 'alter' });
+function generateStiMigrationContent({ table, columnsWithTypes = [], primaryKeyType = 'bigserial', stiChildClassName, }) {
+    return (0, generateMigrationContent_js_1.default)({
+        table,
+        columnsWithTypes,
+        primaryKeyType,
+        createOrAlter: 'alter',
+        stiChildClassName,
+    });
 }

package/dist/cjs/src/serializer/helpers/serializerForAssociatedClass.js

@@ -14,7 +14,8 @@ function serializerForAssociatedClass(object, associationName, options) {
         return null;
     const dream = object;
     const association = dream['getAssociationMetadata'](associationName);
-    const associatedClasses = association.modelCB();
-    const associatedClass = Array.isArray(associatedClasses) ? associatedClasses[0] : associatedClasses;
+    const associatedClass = association.modelCB();
+    if (Array.isArray(associatedClass))
+        throw new Error('rendersOne flatten is incompatible with a polymorphic belongs-to association');
     return (0, inferSerializerFromDreamOrViewModel_js_1.inferSerializersFromDreamClassOrViewModelClass)(associatedClass, options.serializerKey)[0] ?? null;
 }

package/dist/esm/src/Dream.js

@@ -19,6 +19,7 @@ import destroyDream from './dream/internal/destroyDream.js';
 import { destroyOptions, reallyDestroyOptions, undestroyOptions, } from './dream/internal/destroyOptions.js';
 import ensureSTITypeFieldIsSet from './dream/internal/ensureSTITypeFieldIsSet.js';
 import findOrCreateBy from './dream/internal/findOrCreateBy.js';
+import printSerializerHierarchyLevel from './dream/internal/printSerializerHierarchyLevel.js';
 import reload from './dream/internal/reload.js';
 import runValidations from './dream/internal/runValidations.js';
 import saveDream from './dream/internal/saveDream.js';
@@ -47,10 +48,8 @@ import cloneDeepSafe from './helpers/cloneDeepSafe.js';
 import { DateTime } from './helpers/DateTime.js';
 import cachedTypeForAttribute from './helpers/db/cachedTypeForAttribute.js';
 import isJsonColumn from './helpers/db/types/isJsonColumn.js';
-import { indent } from './helpers/indent.js';
 import notEqual from './helpers/notEqual.js';
 import { inferSerializersFromDreamClassOrViewModelClass } from './serializer/helpers/inferSerializerFromDreamOrViewModel.js';
-import { serializerForAssociatedClass } from './serializer/helpers/serializerForAssociatedClass.js';
 export default class Dream {
     DB;
     /**
@@ -487,42 +486,65 @@ export default class Dream {
     static recursiveSerializationMap(serializer, { forDisplay = false, forDisplayDepth = 0, } = {}) {
         const serializerBuilder = serializer(undefined, undefined);
         const serializerAssociations = serializerBuilder['attributes'].filter(attribute => ['rendersOne', 'rendersMany', 'delegatedAttribute'].includes(attribute.type));
-        return serializerAssociations.reduce((acc, serializerAssociation) => {
+        return serializerAssociations.reduce((accumulator, serializerAssociation) => {
             const serializerAssociationName = serializerAssociation.targetName ??
                 serializerAssociation.name;
             const serializerAssociationType = serializerAssociation.type;
             const association = this['getAssociationMetadata'](serializerAssociationName);
             if (!association)
-                return acc;
-            const associatedClasses = association.modelCB();
-            const associatedClass = Array.isArray(associatedClasses) ? associatedClasses[0] : associatedClasses;
-            if (!associatedClass)
+                return accumulator;
+            const maybeAssociatedClasses = association.modelCB();
+            if (!maybeAssociatedClasses)
                 throw new Error(`No class defined on ${serializerAssociationName} association on ${this.sanitizedName}`);
-            const associationSerializer = serializerForAssociatedClass(this.prototype, serializerAssociationName, serializerAssociation.options);
-            if (!associationSerializer)
-                throw new Error(`No serializer found to render ${serializerAssociationName} on ${this.sanitizedName}`);
-            if (forDisplay && serializerAssociationType !== 'delegatedAttribute') {
-                const hierarchyLine = '└───';
-                const indentation = indent((hierarchyLine.length + 1) * forDisplayDepth, {
-                    tabWidth: 1,
-                });
-                const prefix = `${hierarchyLine} `;
-                const nestedAssociationDisplay = indentation + `${prefix}${serializerAssociationType} ${yoctocolors.cyan(serializerAssociationName)}`;
-                console.log(nestedAssociationDisplay);
-                console.log(yoctocolors.gray(indentation +
-                    indent(prefix.length, { tabWidth: 1 }) +
-                    associationSerializer.globalName));
-            }
-            acc[association.as] = {
-                parentDreamClass: this,
-                nestedSerializerInfo: serializerAssociation.type === 'delegatedAttribute'
-                    ? {}
-                    : associatedClass['recursiveSerializationMap'](associationSerializer, {
+            const associatedClasses = Array.isArray(maybeAssociatedClasses)
+                ? maybeAssociatedClasses
+                : [maybeAssociatedClasses];
+            /////////////////////////////////////////////////
+            // map associated classes to their serializers //
+            /////////////////////////////////////////////////
+            const associatedClassSerializerTuples = associatedClasses.flatMap(associatedClass => {
+                /**
+                 * `serializers` is an array because `associatedClass` may be an STI
+                 * base, with each of its STI children having its own serializer
+                 */
+                const serializers = serializerAssociation.options.serializer
+                    ? [serializerAssociation.options.serializer]
+                    : inferSerializersFromDreamClassOrViewModelClass(associatedClass, serializerAssociation.options.serializerKey);
+                if (!serializers.length)
+                    throw new Error(`No serializer found to render ${serializerAssociationName} on ${this.sanitizedName}`);
+                return serializers.map(serializer => [associatedClass, serializer]);
+            });
+            /////////////////////////////////////////////////////
+            // end:map associated classes to their serializers //
+            /////////////////////////////////////////////////////
+            ///////////////////////////////////////////////////////////////////////////////////////////////////
+            // reduce over all associated serializers, recursively building out their associated serializers //
+            ///////////////////////////////////////////////////////////////////////////////////////////////////
+            const innerAssociationSerializerInfo = associatedClassSerializerTuples.reduce((innerAccumulator, [associatedClass, associatedSerializer]) => {
+                if (forDisplay && serializerAssociationType !== 'delegatedAttribute') {
+                    printSerializerHierarchyLevel({
+                        serializerAssociationType,
+                        serializerAssociationName,
+                        associationSerializer: associatedSerializer,
+                        forDisplayDepth,
+                    });
+                }
+                return {
+                    ...innerAccumulator,
+                    ...associatedClass['recursiveSerializationMap'](associatedSerializer, {
                         forDisplay,
                         forDisplayDepth: forDisplayDepth + 1,
                     }),
+                };
+            }, {});
+            ///////////////////////////////////////////////////////////////////////////////////////////////////////
+            // end:reduce over all associated serializers, recursively building out their associated serializers //
+            ///////////////////////////////////////////////////////////////////////////////////////////////////////
+            accumulator[association.as] = {
+                parentDreamClass: this,
+                nestedSerializerInfo: serializerAssociation.type === 'delegatedAttribute' ? {} : innerAssociationSerializerInfo,
             };
-            return acc;
+            return accumulator;
         }, {});
     }
     /**
@@ -657,11 +679,57 @@ export default class Dream {
         return map;
     }
     /**
-     * @internal
+     * Checks whether the specified association has been defined on this Dream model.
+     *
+     * ```ts
+     * const user = User.new()
+     *
+     * user.hasAssociation('posts')
+     * // true (if User has a posts association defined)
+     *
+     * user.hasAssociation('nonExistentAssociation')
+     * // false
+     *
+     * // Useful for conditional association handling
+     * if (user.hasAssociation('posts')) {
+     *   user = await user.load('posts').execute()
+     * }
+     * ```
+     *
+     * @param associationName - The name of the association to check for
+     * @returns `true` if the association exists on this model, `false` otherwise
+     */
+    hasAssociation(associationName) {
+        return !!(this.associationMetadataByType.belongsTo.find(association => association.as === associationName) ||
+            this.associationMetadataByType.hasOne.find(association => association.as === associationName) ||
+            this.associationMetadataByType.hasMany.find(association => association.as === associationName));
+    }
+    /**
+     * Returns all of the association names for this Dream class.
+     * This includes all BelongsTo, HasOne, and HasMany associations
+     * defined on the model.
      *
-     * Returns all of the association names for this dream class
+     * This is useful for introspection, debugging, or dynamically working
+     * with all associations on a model.
+     *
+     * ```ts
+     * class User extends ApplicationModel {
+     *   @deco.HasMany('Post')
+     *   public posts: Post[]
+     *
+     *   @deco.HasOne('Profile')
+     *   public profile: Profile
+     *
+     *   @deco.BelongsTo('Company')
+     *   public company: Company
+     * }
+     *
+     * User.associationNames
+     * // ['posts', 'profile', 'company']
+     * })
+     * ```
      *
-     * @returns All of the association names for this dream class
+     * @returns An array containing all association names defined on this Dream class
      */
     static get associationNames() {
         const allAssociations = [