@rvoh/dream 2.14.1 → 2.15.0

package/dist/cjs/src/Dream.js

@@ -36,7 +36,6 @@ import CannotDestroyAssociationOnUnpersistedDream from './errors/associations/Ca
 import CannotPassNullOrUndefinedToRequiredBelongsTo from './errors/associations/CannotPassNullOrUndefinedToRequiredBelongsTo.js';
 import CannotUpdateAssociationOnUnpersistedDream from './errors/associations/CannotUpdateAssociationOnUnpersistedDream.js';
 import CanOnlyPassBelongsToModelParam from './errors/associations/CanOnlyPassBelongsToModelParam.js';
-import NonLoadedAssociation from './errors/associations/NonLoadedAssociation.js';
 import CannotCallUndestroyOnANonSoftDeleteModel from './errors/CannotCallUndestroyOnANonSoftDeleteModel.js';
 import ConstructorOnlyForInternalUse from './errors/ConstructorOnlyForInternalUse.js';
 import CreateOrFindByFailedToCreateAndFind from './errors/CreateOrFindByFailedToCreateAndFind.js';
@@ -3349,17 +3348,10 @@ export default class Dream {
      * @returns A boolean
      */
     loaded(associationName) {
-        try {
-            // eslint-disable-next-line @typescript-eslint/no-unused-expressions
-            ;
-            this[associationName];
-            return true;
-        }
-        catch (error) {
-            if (error.constructor !== NonLoadedAssociation)
-                throw error;
+        const association = this['getAssociationMetadata'](associationName);
+        if (association === undefined)
             return false;
-        }
+        return this[associationToGetterSetterProp(association)] !== undefined;
     }
     /**
      * Reloads an instance, refreshing all it's attribute values

package/dist/cjs/src/decorators/field/association/BelongsTo.js

@@ -20,8 +20,35 @@ import { applyGetterAndSetter, associationPrimaryKeyAccessors, blankAssociations
  * }
  * ```
  *
+ * ## Required (non-optional) BelongsTo and nullability
+ *
+ * `optional` is the single source of truth for whether a BelongsTo can be
+ * absent. A non-optional BelongsTo (the default, `optional: false`) is typed
+ * non-null, and that non-null type flows through serializers into the generated
+ * OpenAPI spec as a non-nullable field. "Required" therefore means "always
+ * present"; if a parent can legitimately be absent, mark the association
+ * `optional: true` (which flows to OpenAPI as nullable).
+ *
+ * Two consequences follow from that guarantee:
+ *
+ * - **Compile-time:** a non-optional BelongsTo cannot take an explicit
+ *   load-time constraint. Passing `{ and: {...} }` (or any on-clause) as a
+ *   trailing argument to `preload`, `load`, `leftJoinPreload`, or `leftJoinLoad`
+ *   targeting a required BelongsTo is a type error, because such a constraint
+ *   could filter out a real, existing record and yield null for a value the
+ *   OpenAPI spec declares non-nullable. Constraints remain allowed on optional
+ *   BelongsTo, `HasOne`, and `HasMany`; `join` is unaffected.
+ *
+ * - **Runtime:** if a required BelongsTo is null when accessed — its row was
+ *   hard-deleted, or filtered out by an internal/default scope such as
+ *   soft-delete — accessing the getter throws
+ *   {@link MissingRequiredBelongsToAssociation}, a clear error in place of a
+ *   cryptic null-deref deep in serialization. An unexpected throw is surfacing a
+ *   modeling bug, typically a missing `dependent: 'destroy'` on the inverse
+ *   `HasOne`/`HasMany` (or the association should have been `optional: true`).
+ *
  * @param opts.on - A custom column name to use for joining associations on.
- * @param opts.optional - Whether or not this association is optional. Defaults to false.
+ * @param opts.optional - Whether or not this association is optional. Defaults to false. When false (the default) the association is required: it is typed non-null, serializes as a non-nullable OpenAPI field, rejects explicit load-time constraints at compile time, and throws {@link MissingRequiredBelongsToAssociation} if null when accessed.
  * @param opts.polymorphic - If true, this association will be treated as a polymorphic association.
  * @param opts.primaryKeyOverride - A custom column name to use for the primary key.
  * @param opts.withoutDefaultScopes - A list of default scopes to bypass when loading this association

package/dist/cjs/src/decorators/field/association/shared.js

@@ -1,6 +1,7 @@
 import pluralize from 'pluralize-esm';
 import { DreamConst } from '../../../dream/constants.js';
 import { checkForeignKey } from '../../../errors/associations/InvalidComputedForeignKey.js';
+import MissingRequiredBelongsToAssociation from '../../../errors/associations/MissingRequiredBelongsToAssociation.js';
 import NonLoadedAssociation from '../../../errors/associations/NonLoadedAssociation.js';
 import CannotDefineAssociationWithBothDependentAndPassthrough from '../../../errors/CannotDefineAssociationWithBothDependentAndPassthrough.js';
 import CannotDefineAssociationWithBothDependentAndRequiredAndClause from '../../../errors/CannotDefineAssociationWithBothDependentAndRequiredAndClause.js';
@@ -55,8 +56,26 @@ export function applyGetterAndSetter(target, partialAssociation, { foreignKeyBas
             const value = this[associationToGetterSetterProp(partialAssociation)];
             if (value === undefined)
                 throw new NonLoadedAssociation({ dreamClass, associationName: partialAssociation.as });
-            else
+            // Getter semantics should follow the association metadata. The `isBelongsTo`
+            // option below is only for setter FK side effects when assigning models.
+            if (partialAssociation.type === 'BelongsTo' && !partialAssociation.optional && value === null) {
+                const foreignKey = finalForeignKey(foreignKeyBase, dreamClass, partialAssociation);
+                const foreignKeyType = partialAssociation.polymorphic
+                    ? foreignKeyTypeField(foreignKeyBase, dreamClass, partialAssociation)
+                    : null;
+                throw new MissingRequiredBelongsToAssociation({
+                    dreamClass,
+                    associationName: partialAssociation.as,
+                    foreignKey,
+                    foreignKeyValue: this[foreignKey],
+                    foreignKeyTypeField: foreignKeyType,
+                    foreignKeyTypeValue: foreignKeyType ? this[foreignKeyType] : null,
+                    polymorphic: partialAssociation.polymorphic,
+                });
+            }
+            else {
                 return value;
+            }
         },
         set: function (associatedModel) {
             /**

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

@@ -1,3 +1,4 @@
+import associationToGetterSetterProp from '../decorators/field/association/associationToGetterSetterProp.js';
 import UnexpectedUndefined from '../errors/UnexpectedUndefined.js';
 import unaliasTableName from './internal/unaliasTableName.js';
 export default class LeftJoinLoadBuilder {
@@ -69,7 +70,10 @@ export default class LeftJoinLoadBuilder {
                 throw new UnexpectedUndefined();
             this.query.dbDriverInstance()['hydrateAssociation']([this.dream], associationMetadata, this.associationToPreloadedDreamsAndWhatTheyPointTo({
                 pointsToPrimaryKey: this.dream.primaryKeyValue(),
-                associatedModels: dreamWithLoadedAssociations[associationName],
+                associatedModels: this.leftJoinLoadedAssociationValue({
+                    dreamWithLoadedAssociations,
+                    associationMetadata,
+                }),
             }));
         });
         return this.dream;
@@ -77,4 +81,7 @@ export default class LeftJoinLoadBuilder {
     associationToPreloadedDreamsAndWhatTheyPointTo({ pointsToPrimaryKey, associatedModels, }) {
         return [associatedModels].flat().map(dream => ({ dream, pointsToPrimaryKey }));
     }
+    leftJoinLoadedAssociationValue({ dreamWithLoadedAssociations, associationMetadata, }) {
+        return dreamWithLoadedAssociations[associationToGetterSetterProp(associationMetadata)];
+    }
 }

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

@@ -755,15 +755,16 @@ export default class KyselyQueryDriver extends QueryDriverBase {
      * Used to hydrate dreams with the provided associations
      */
     hydrateAssociation(dreams, association, preloadedDreamsAndWhatTheyPointTo) {
+        const associationBackingProperty = associationToGetterSetterProp(association);
         switch (association.type) {
             case 'HasMany':
                 dreams.forEach((dream) => {
-                    dream[association.as] = [];
+                    dream[associationBackingProperty] = [];
                 });
                 break;
             default:
                 dreams.forEach((dream) => {
-                    dream[associationToGetterSetterProp(association)] = null;
+                    dream[associationBackingProperty] = null;
                 });
         }
         // dreams is a Rating
@@ -776,18 +777,18 @@ export default class KyselyQueryDriver extends QueryDriverBase {
                 .filter(dream => dream.primaryKeyValue() === preloadedDreamAndWhatItPointsTo.pointsToPrimaryKey)
                 .forEach((dream) => {
                 if (association.type === 'HasMany') {
-                    dream[association.as].push(preloadedDreamAndWhatItPointsTo.dream);
+                    dream[associationBackingProperty].push(preloadedDreamAndWhatItPointsTo.dream);
                 }
                 else {
                     // in a HasOne context, order clauses will be applied in advance,
                     // prior to hydration. Considering, we only want to set the first
                     // result and ignore other results, so we will use ||= to set.
-                    dream[association.as] ||= preloadedDreamAndWhatItPointsTo.dream;
+                    dream[associationBackingProperty] ||= preloadedDreamAndWhatItPointsTo.dream;
                 }
             });
         });
         if (association.type === 'HasMany') {
-            dreams.forEach((dream) => Object.freeze(dream[association.as]));
+            dreams.forEach((dream) => Object.freeze(dream[associationBackingProperty]));
         }
     }
     /**

package/dist/cjs/src/errors/associations/MissingRequiredBelongsToAssociation.js

@@ -0,0 +1,84 @@
+/**
+ * Thrown when a non-optional (`optional: false`) BelongsTo association is null
+ * at the moment its getter is accessed.
+ *
+ * A non-optional BelongsTo is typed non-null and serializes to a non-nullable
+ * field in the generated OpenAPI spec — "required" means "always present". When
+ * the loaded value is nevertheless null, this error fails loud in place of a
+ * cryptic null-deref deep in serialization. It arises when the associated row is
+ * absent for one of these reasons:
+ *
+ * - The associated row was hard-deleted, leaving a dangling foreign key. This
+ *   usually signals a missing `dependent: 'destroy'` on the inverse
+ *   `HasOne`/`HasMany`.
+ * - An internal or default scope (such as soft-delete) filtered the associated
+ *   row out at load time.
+ *
+ * The fix is one of:
+ *
+ * - Add `dependent: 'destroy'` to the inverse `HasOne`/`HasMany` so the parent
+ *   cannot outlive its children, or
+ * - Mark the BelongsTo `optional: true` if the parent can legitimately be absent
+ *   (which makes the field nullable in the OpenAPI spec).
+ *
+ * Note that an *explicit* load-time constraint on a required BelongsTo (e.g.
+ * `preload('parent', { and: {...} })`) is forbidden at compile time rather than
+ * surfacing here at runtime; see {@link BelongsTo}.
+ */
+export default class MissingRequiredBelongsToAssociation extends Error {
+    dreamClass;
+    associationName;
+    foreignKey;
+    foreignKeyValue;
+    foreignKeyTypeField;
+    foreignKeyTypeValue;
+    polymorphic;
+    constructor({ dreamClass, associationName, foreignKey, foreignKeyValue, foreignKeyTypeField = null, foreignKeyTypeValue = null, polymorphic, }) {
+        super();
+        this.dreamClass = dreamClass;
+        this.associationName = associationName;
+        this.foreignKey = foreignKey;
+        this.foreignKeyValue = foreignKeyValue;
+        this.foreignKeyTypeField = foreignKeyTypeField;
+        this.foreignKeyTypeValue = foreignKeyTypeValue;
+        this.polymorphic = polymorphic;
+    }
+    get message() {
+        return `
+Attempting to access required BelongsTo association \`${this.associationName}\` on an instance of \`${this.dreamClass.sanitizedName}\`,
+but the loaded association is null.
+
+${this.foreignKeyMessage}
+
+If the associated record was deleted, check whether the inverse HasOne/HasMany association should specify dependent: 'destroy'.
+`;
+    }
+    get foreignKeyMessage() {
+        if (this.foreignKeyValue === null || this.foreignKeyValue === undefined) {
+            return `The foreign key \`${this.foreignKey}\` is null, which violates this non-optional BelongsTo association.`;
+        }
+        return [
+            `The foreign key \`${this.foreignKey}\` is set to \`${this.formatValue(this.foreignKeyValue)}\`, but no associated record was loaded.`,
+            this.polymorphic && this.foreignKeyTypeField
+                ? `The polymorphic type field \`${this.foreignKeyTypeField}\` is set to \`${this.formatValue(this.foreignKeyTypeValue)}\`.`
+                : null,
+        ]
+            .filter(Boolean)
+            .join('\n');
+    }
+    formatValue(value) {
+        if (value === null)
+            return 'null';
+        if (value === undefined)
+            return 'undefined';
+        if (typeof value === 'string')
+            return value;
+        if (typeof value === 'number' || typeof value === 'boolean' || typeof value === 'bigint')
+            return value.toString();
+        if (typeof value === 'symbol')
+            return value.description ?? value.toString();
+        if (typeof value === 'function')
+            return value.name || '[function]';
+        return JSON.stringify(value);
+    }
+}

package/dist/esm/src/Dream.js

@@ -36,7 +36,6 @@ import CannotDestroyAssociationOnUnpersistedDream from './errors/associations/Ca
 import CannotPassNullOrUndefinedToRequiredBelongsTo from './errors/associations/CannotPassNullOrUndefinedToRequiredBelongsTo.js';
 import CannotUpdateAssociationOnUnpersistedDream from './errors/associations/CannotUpdateAssociationOnUnpersistedDream.js';
 import CanOnlyPassBelongsToModelParam from './errors/associations/CanOnlyPassBelongsToModelParam.js';
-import NonLoadedAssociation from './errors/associations/NonLoadedAssociation.js';
 import CannotCallUndestroyOnANonSoftDeleteModel from './errors/CannotCallUndestroyOnANonSoftDeleteModel.js';
 import ConstructorOnlyForInternalUse from './errors/ConstructorOnlyForInternalUse.js';
 import CreateOrFindByFailedToCreateAndFind from './errors/CreateOrFindByFailedToCreateAndFind.js';
@@ -3349,17 +3348,10 @@ export default class Dream {
      * @returns A boolean
      */
     loaded(associationName) {
-        try {
-            // eslint-disable-next-line @typescript-eslint/no-unused-expressions
-            ;
-            this[associationName];
-            return true;
-        }
-        catch (error) {
-            if (error.constructor !== NonLoadedAssociation)
-                throw error;
+        const association = this['getAssociationMetadata'](associationName);
+        if (association === undefined)
             return false;
-        }
+        return this[associationToGetterSetterProp(association)] !== undefined;
     }
     /**
      * Reloads an instance, refreshing all it's attribute values

package/dist/esm/src/decorators/field/association/BelongsTo.js

@@ -20,8 +20,35 @@ import { applyGetterAndSetter, associationPrimaryKeyAccessors, blankAssociations
  * }
  * ```
  *
+ * ## Required (non-optional) BelongsTo and nullability
+ *
+ * `optional` is the single source of truth for whether a BelongsTo can be
+ * absent. A non-optional BelongsTo (the default, `optional: false`) is typed
+ * non-null, and that non-null type flows through serializers into the generated
+ * OpenAPI spec as a non-nullable field. "Required" therefore means "always
+ * present"; if a parent can legitimately be absent, mark the association
+ * `optional: true` (which flows to OpenAPI as nullable).
+ *
+ * Two consequences follow from that guarantee:
+ *
+ * - **Compile-time:** a non-optional BelongsTo cannot take an explicit
+ *   load-time constraint. Passing `{ and: {...} }` (or any on-clause) as a
+ *   trailing argument to `preload`, `load`, `leftJoinPreload`, or `leftJoinLoad`
+ *   targeting a required BelongsTo is a type error, because such a constraint
+ *   could filter out a real, existing record and yield null for a value the
+ *   OpenAPI spec declares non-nullable. Constraints remain allowed on optional
+ *   BelongsTo, `HasOne`, and `HasMany`; `join` is unaffected.
+ *
+ * - **Runtime:** if a required BelongsTo is null when accessed — its row was
+ *   hard-deleted, or filtered out by an internal/default scope such as
+ *   soft-delete — accessing the getter throws
+ *   {@link MissingRequiredBelongsToAssociation}, a clear error in place of a
+ *   cryptic null-deref deep in serialization. An unexpected throw is surfacing a
+ *   modeling bug, typically a missing `dependent: 'destroy'` on the inverse
+ *   `HasOne`/`HasMany` (or the association should have been `optional: true`).
+ *
  * @param opts.on - A custom column name to use for joining associations on.
- * @param opts.optional - Whether or not this association is optional. Defaults to false.
+ * @param opts.optional - Whether or not this association is optional. Defaults to false. When false (the default) the association is required: it is typed non-null, serializes as a non-nullable OpenAPI field, rejects explicit load-time constraints at compile time, and throws {@link MissingRequiredBelongsToAssociation} if null when accessed.
  * @param opts.polymorphic - If true, this association will be treated as a polymorphic association.
  * @param opts.primaryKeyOverride - A custom column name to use for the primary key.
  * @param opts.withoutDefaultScopes - A list of default scopes to bypass when loading this association

package/dist/esm/src/decorators/field/association/shared.js

@@ -1,6 +1,7 @@
 import pluralize from 'pluralize-esm';
 import { DreamConst } from '../../../dream/constants.js';
 import { checkForeignKey } from '../../../errors/associations/InvalidComputedForeignKey.js';
+import MissingRequiredBelongsToAssociation from '../../../errors/associations/MissingRequiredBelongsToAssociation.js';
 import NonLoadedAssociation from '../../../errors/associations/NonLoadedAssociation.js';
 import CannotDefineAssociationWithBothDependentAndPassthrough from '../../../errors/CannotDefineAssociationWithBothDependentAndPassthrough.js';
 import CannotDefineAssociationWithBothDependentAndRequiredAndClause from '../../../errors/CannotDefineAssociationWithBothDependentAndRequiredAndClause.js';
@@ -55,8 +56,26 @@ export function applyGetterAndSetter(target, partialAssociation, { foreignKeyBas
             const value = this[associationToGetterSetterProp(partialAssociation)];
             if (value === undefined)
                 throw new NonLoadedAssociation({ dreamClass, associationName: partialAssociation.as });
-            else
+            // Getter semantics should follow the association metadata. The `isBelongsTo`
+            // option below is only for setter FK side effects when assigning models.
+            if (partialAssociation.type === 'BelongsTo' && !partialAssociation.optional && value === null) {
+                const foreignKey = finalForeignKey(foreignKeyBase, dreamClass, partialAssociation);
+                const foreignKeyType = partialAssociation.polymorphic
+                    ? foreignKeyTypeField(foreignKeyBase, dreamClass, partialAssociation)
+                    : null;
+                throw new MissingRequiredBelongsToAssociation({
+                    dreamClass,
+                    associationName: partialAssociation.as,
+                    foreignKey,
+                    foreignKeyValue: this[foreignKey],
+                    foreignKeyTypeField: foreignKeyType,
+                    foreignKeyTypeValue: foreignKeyType ? this[foreignKeyType] : null,
+                    polymorphic: partialAssociation.polymorphic,
+                });
+            }
+            else {
                 return value;
+            }
         },
         set: function (associatedModel) {
             /**

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

@@ -1,3 +1,4 @@
+import associationToGetterSetterProp from '../decorators/field/association/associationToGetterSetterProp.js';
 import UnexpectedUndefined from '../errors/UnexpectedUndefined.js';
 import unaliasTableName from './internal/unaliasTableName.js';
 export default class LeftJoinLoadBuilder {
@@ -69,7 +70,10 @@ export default class LeftJoinLoadBuilder {
                 throw new UnexpectedUndefined();
             this.query.dbDriverInstance()['hydrateAssociation']([this.dream], associationMetadata, this.associationToPreloadedDreamsAndWhatTheyPointTo({
                 pointsToPrimaryKey: this.dream.primaryKeyValue(),
-                associatedModels: dreamWithLoadedAssociations[associationName],
+                associatedModels: this.leftJoinLoadedAssociationValue({
+                    dreamWithLoadedAssociations,
+                    associationMetadata,
+                }),
             }));
         });
         return this.dream;
@@ -77,4 +81,7 @@ export default class LeftJoinLoadBuilder {
     associationToPreloadedDreamsAndWhatTheyPointTo({ pointsToPrimaryKey, associatedModels, }) {
         return [associatedModels].flat().map(dream => ({ dream, pointsToPrimaryKey }));
     }
+    leftJoinLoadedAssociationValue({ dreamWithLoadedAssociations, associationMetadata, }) {
+        return dreamWithLoadedAssociations[associationToGetterSetterProp(associationMetadata)];
+    }
 }

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

@@ -755,15 +755,16 @@ export default class KyselyQueryDriver extends QueryDriverBase {
      * Used to hydrate dreams with the provided associations
      */
     hydrateAssociation(dreams, association, preloadedDreamsAndWhatTheyPointTo) {
+        const associationBackingProperty = associationToGetterSetterProp(association);
         switch (association.type) {
             case 'HasMany':
                 dreams.forEach((dream) => {
-                    dream[association.as] = [];
+                    dream[associationBackingProperty] = [];
                 });
                 break;
             default:
                 dreams.forEach((dream) => {
-                    dream[associationToGetterSetterProp(association)] = null;
+                    dream[associationBackingProperty] = null;
                 });
         }
         // dreams is a Rating
@@ -776,18 +777,18 @@ export default class KyselyQueryDriver extends QueryDriverBase {
                 .filter(dream => dream.primaryKeyValue() === preloadedDreamAndWhatItPointsTo.pointsToPrimaryKey)
                 .forEach((dream) => {
                 if (association.type === 'HasMany') {
-                    dream[association.as].push(preloadedDreamAndWhatItPointsTo.dream);
+                    dream[associationBackingProperty].push(preloadedDreamAndWhatItPointsTo.dream);
                 }
                 else {
                     // in a HasOne context, order clauses will be applied in advance,
                     // prior to hydration. Considering, we only want to set the first
                     // result and ignore other results, so we will use ||= to set.
-                    dream[association.as] ||= preloadedDreamAndWhatItPointsTo.dream;
+                    dream[associationBackingProperty] ||= preloadedDreamAndWhatItPointsTo.dream;
                 }
             });
         });
         if (association.type === 'HasMany') {
-            dreams.forEach((dream) => Object.freeze(dream[association.as]));
+            dreams.forEach((dream) => Object.freeze(dream[associationBackingProperty]));
         }
     }
     /**

package/dist/esm/src/errors/associations/MissingRequiredBelongsToAssociation.js

@@ -0,0 +1,84 @@
+/**
+ * Thrown when a non-optional (`optional: false`) BelongsTo association is null
+ * at the moment its getter is accessed.
+ *
+ * A non-optional BelongsTo is typed non-null and serializes to a non-nullable
+ * field in the generated OpenAPI spec — "required" means "always present". When
+ * the loaded value is nevertheless null, this error fails loud in place of a
+ * cryptic null-deref deep in serialization. It arises when the associated row is
+ * absent for one of these reasons:
+ *
+ * - The associated row was hard-deleted, leaving a dangling foreign key. This
+ *   usually signals a missing `dependent: 'destroy'` on the inverse
+ *   `HasOne`/`HasMany`.
+ * - An internal or default scope (such as soft-delete) filtered the associated
+ *   row out at load time.
+ *
+ * The fix is one of:
+ *
+ * - Add `dependent: 'destroy'` to the inverse `HasOne`/`HasMany` so the parent
+ *   cannot outlive its children, or
+ * - Mark the BelongsTo `optional: true` if the parent can legitimately be absent
+ *   (which makes the field nullable in the OpenAPI spec).
+ *
+ * Note that an *explicit* load-time constraint on a required BelongsTo (e.g.
+ * `preload('parent', { and: {...} })`) is forbidden at compile time rather than
+ * surfacing here at runtime; see {@link BelongsTo}.
+ */
+export default class MissingRequiredBelongsToAssociation extends Error {
+    dreamClass;
+    associationName;
+    foreignKey;
+    foreignKeyValue;
+    foreignKeyTypeField;
+    foreignKeyTypeValue;
+    polymorphic;
+    constructor({ dreamClass, associationName, foreignKey, foreignKeyValue, foreignKeyTypeField = null, foreignKeyTypeValue = null, polymorphic, }) {
+        super();
+        this.dreamClass = dreamClass;
+        this.associationName = associationName;
+        this.foreignKey = foreignKey;
+        this.foreignKeyValue = foreignKeyValue;
+        this.foreignKeyTypeField = foreignKeyTypeField;
+        this.foreignKeyTypeValue = foreignKeyTypeValue;
+        this.polymorphic = polymorphic;
+    }
+    get message() {
+        return `
+Attempting to access required BelongsTo association \`${this.associationName}\` on an instance of \`${this.dreamClass.sanitizedName}\`,
+but the loaded association is null.
+
+${this.foreignKeyMessage}
+
+If the associated record was deleted, check whether the inverse HasOne/HasMany association should specify dependent: 'destroy'.
+`;
+    }
+    get foreignKeyMessage() {
+        if (this.foreignKeyValue === null || this.foreignKeyValue === undefined) {
+            return `The foreign key \`${this.foreignKey}\` is null, which violates this non-optional BelongsTo association.`;
+        }
+        return [
+            `The foreign key \`${this.foreignKey}\` is set to \`${this.formatValue(this.foreignKeyValue)}\`, but no associated record was loaded.`,
+            this.polymorphic && this.foreignKeyTypeField
+                ? `The polymorphic type field \`${this.foreignKeyTypeField}\` is set to \`${this.formatValue(this.foreignKeyTypeValue)}\`.`
+                : null,
+        ]
+            .filter(Boolean)
+            .join('\n');
+    }
+    formatValue(value) {
+        if (value === null)
+            return 'null';
+        if (value === undefined)
+            return 'undefined';
+        if (typeof value === 'string')
+            return value;
+        if (typeof value === 'number' || typeof value === 'boolean' || typeof value === 'bigint')
+            return value.toString();
+        if (typeof value === 'symbol')
+            return value.description ?? value.toString();
+        if (typeof value === 'function')
+            return value.name || '[function]';
+        return JSON.stringify(value);
+    }
+}

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

@@ -52,4 +52,5 @@ export default class LeftJoinLoadBuilder<DreamInstance extends Dream> {
      */
     execute(): Promise<DreamInstance>;
     private associationToPreloadedDreamsAndWhatTheyPointTo;
+    private leftJoinLoadedAssociationValue;
 }

package/dist/types/src/errors/associations/MissingRequiredBelongsToAssociation.d.ts

@@ -0,0 +1,49 @@
+import Dream from '../../Dream.js';
+/**
+ * Thrown when a non-optional (`optional: false`) BelongsTo association is null
+ * at the moment its getter is accessed.
+ *
+ * A non-optional BelongsTo is typed non-null and serializes to a non-nullable
+ * field in the generated OpenAPI spec — "required" means "always present". When
+ * the loaded value is nevertheless null, this error fails loud in place of a
+ * cryptic null-deref deep in serialization. It arises when the associated row is
+ * absent for one of these reasons:
+ *
+ * - The associated row was hard-deleted, leaving a dangling foreign key. This
+ *   usually signals a missing `dependent: 'destroy'` on the inverse
+ *   `HasOne`/`HasMany`.
+ * - An internal or default scope (such as soft-delete) filtered the associated
+ *   row out at load time.
+ *
+ * The fix is one of:
+ *
+ * - Add `dependent: 'destroy'` to the inverse `HasOne`/`HasMany` so the parent
+ *   cannot outlive its children, or
+ * - Mark the BelongsTo `optional: true` if the parent can legitimately be absent
+ *   (which makes the field nullable in the OpenAPI spec).
+ *
+ * Note that an *explicit* load-time constraint on a required BelongsTo (e.g.
+ * `preload('parent', { and: {...} })`) is forbidden at compile time rather than
+ * surfacing here at runtime; see {@link BelongsTo}.
+ */
+export default class MissingRequiredBelongsToAssociation extends Error {
+    dreamClass: typeof Dream;
+    associationName: string;
+    foreignKey: string;
+    foreignKeyValue: unknown;
+    foreignKeyTypeField: string | null;
+    foreignKeyTypeValue: unknown;
+    polymorphic: boolean;
+    constructor({ dreamClass, associationName, foreignKey, foreignKeyValue, foreignKeyTypeField, foreignKeyTypeValue, polymorphic, }: {
+        dreamClass: typeof Dream;
+        associationName: string;
+        foreignKey: string;
+        foreignKeyValue: unknown;
+        foreignKeyTypeField?: string | null;
+        foreignKeyTypeValue?: unknown;
+        polymorphic: boolean;
+    });
+    get message(): string;
+    private get foreignKeyMessage();
+    private formatValue;
+}

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

@@ -42,6 +42,15 @@ export type DreamAssociationNamesWithPassthroughOnClauses<DreamInstance extends
 }, PassthroughOnClauses = keyof RejectInterface<SchemaTypeInterface, null> & string> = PassthroughOnClauses;
 export type RequiredOnClauseKeys<Schema, TableName, AssociationName, Associations = TableName extends null ? null : TableName extends keyof Schema & string ? Schema[TableName]['associations' & keyof Schema[TableName]] : null, Association = Associations extends null ? null : AssociationName extends keyof Associations ? Associations[AssociationName] : null, RequiredOnClauses = Association extends null ? null : Association['requiredAndClauses' & keyof Association] & (string[] | null)> = RequiredOnClauses;
 export type PassthroughOnClauseKeys<Schema, TableName, AssociationName, Associations = TableName extends null ? null : TableName extends keyof Schema & string ? Schema[TableName]['associations' & keyof Schema[TableName]] : null, Association = Associations extends null ? null : AssociationName extends keyof Associations ? Associations[AssociationName] : null, PassthroughOnClauses = Association extends null ? null : Association['passthroughAndClauses' & keyof Association] & (string[] | null)> = PassthroughOnClauses;
+/**
+ * Resolves to `true` when the named association on the given table is a
+ * non-optional (required) BelongsTo, and `false` otherwise. A required
+ * BelongsTo getter is typed non-null and that non-null type flows through
+ * serializers into the generated OpenAPI spec as a non-nullable field, so a
+ * load-time constraint that could filter the parent out (nulling the value)
+ * must be forbidden at compile time for the hydrating load variants.
+ */
+export type IsNonOptionalBelongsToAssociation<Schema, TableName, AssociationName, Associations = TableName extends null ? null : TableName extends keyof Schema & string ? Schema[TableName]['associations' & keyof Schema[TableName]] : null, Association = Associations extends null ? null : AssociationName extends keyof Associations ? Associations[AssociationName] : null> = Association extends null ? false : Association['type' & keyof Association] extends 'BelongsTo' ? Association['optional' & keyof Association] extends false ? true : false : false;
 export type DreamAssociationNames<DreamInstance extends Dream, SchemaAssociations = DreamAssociationMetadata<DreamInstance>> = keyof SchemaAssociations;
 export type DreamBelongsToAssociationNames<DreamInstance extends Dream> = keyof DreamBelongsToAssociationMetadata<DreamInstance>;
 export type DreamHasOneAssociationNames<DreamInstance extends Dream> = keyof DreamHasOneAssociationMetadata<DreamInstance>;

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

@@ -224,6 +224,36 @@ export type PassthroughOnClauseKeys<
     : Association['passthroughAndClauses' & keyof Association] & (string[] | null),
 > = PassthroughOnClauses
 
+/**
+ * Resolves to `true` when the named association on the given table is a
+ * non-optional (required) BelongsTo, and `false` otherwise. A required
+ * BelongsTo getter is typed non-null and that non-null type flows through
+ * serializers into the generated OpenAPI spec as a non-nullable field, so a
+ * load-time constraint that could filter the parent out (nulling the value)
+ * must be forbidden at compile time for the hydrating load variants.
+ */
+export type IsNonOptionalBelongsToAssociation<
+  Schema,
+  TableName,
+  AssociationName,
+  Associations = TableName extends null
+    ? null
+    : TableName extends keyof Schema & string
+      ? Schema[TableName]['associations' & keyof Schema[TableName]]
+      : null,
+  Association = Associations extends null
+    ? null
+    : AssociationName extends keyof Associations
+      ? Associations[AssociationName]
+      : null,
+> = Association extends null
+  ? false
+  : Association['type' & keyof Association] extends 'BelongsTo'
+    ? Association['optional' & keyof Association] extends false
+      ? true
+      : false
+    : false
+
 export type DreamAssociationNames<
   DreamInstance extends Dream,
   SchemaAssociations = DreamAssociationMetadata<DreamInstance>,