dyna-record 0.3.6 → 0.4.1

package/README.md

@@ -172,6 +172,8 @@ Define foreign keys in order to support [@BelongsTo](https://dyna-record.com/fun
 - The [alias](https://dyna-record.com/interfaces/AttributeOptions.html#alias) option allows you to specify the attribute name as it appears in the DynamoDB table, different from your class property name.
 - Set nullable foreign key attributes as optional for optimal type safety
 - Attempting to remove an entity from a non-nullable foreign key will result in a [NullConstrainViolationError](https://dyna-record.com/classes/NullConstraintViolationError.html)
+- Always provide the referenced entity class to `@ForeignKeyAttribute` (for example `@ForeignKeyAttribute(() => Customer)`); this allows DynaRecord to enforce referential integrity even when no relationship decorator is defined.
+- `Create` and `Update` automatically add DynamoDB condition checks for standalone foreign keys (those without a relationship decorator) to ensure the referenced entity exists, enabling referential integrity even when no denormalised access pattern is required.
 
 ```typescript
 import {
@@ -184,8 +186,8 @@ import {
 
 @Entity
 class Assignment extends MyTable {
-  @ForeignKeyAttribute()
-  public readonly courseId: ForeignKey;
+  @ForeignKeyAttribute(() => Course)
+  public readonly courseId: ForeignKey<Course>;
 
   @BelongsTo(() => Course, { foreignKey: "courseId" })
   public readonly course: Course;
@@ -193,8 +195,8 @@ class Assignment extends MyTable {
 
 @Entity
 class Course extends MyTable {
-  @ForeignKeyAttribute({ nullable: true })
-  public readonly teacherId?: NullableForeignKey; // Set as optional
+  @ForeignKeyAttribute(() => Teacher, { nullable: true })
+  public readonly teacherId?: NullableForeignKey<Teacher>; // Set as optional
 
   @BelongsTo(() => Teacher, { foreignKey: "teacherId" })
   public readonly teacher?: Teacher; // Set as optional because its linked through NullableForeignKey
@@ -232,8 +234,8 @@ class Assignment extends MyTable {
 
 @Entity
 class Grade extends MyTable {
-  @ForeignKeyAttribute()
-  public readonly assignmentId: ForeignKey;
+  @ForeignKeyAttribute(() => Assignment)
+  public readonly assignmentId: ForeignKey<Assignment>;
 
   // 'assignmentId' Must be defined on self as ForeignKey or NullableForeignKey
   @BelongsTo(() => Assignment, { foreignKey: "assignmentId" })
@@ -257,8 +259,8 @@ class Teacher extends MyTable {
 
 @Entity
 class Course extends MyTable {
-  @ForeignKeyAttribute({ nullable: true })
-  public readonly teacherId?: NullableForeignKey; // Mark as optional
+  @ForeignKeyAttribute(() => Teacher, { nullable: true })
+  public readonly teacherId?: NullableForeignKey<Teacher>; // Mark as optional
 
   // 'teacherId' Must be defined on self as ForeignKey or NullableForeignKey
   @BelongsTo(() => Teacher, { foreignKey: "teacherId" })
@@ -282,8 +284,8 @@ class Teacher extends MyTable {
 
 @Entity
 class Course extends MyTable {
-  @ForeignKeyAttribute({ nullable: true })
-  public readonly teacherId?: NullableForeignKey; // Mark as optional
+  @ForeignKeyAttribute(() => Teacher, { nullable: true })
+  public readonly teacherId?: NullableForeignKey<Teacher>; // Mark as optional
 }
 ```
 
@@ -355,6 +357,25 @@ const grade: Grade = await Grade.create({
 });
 ```
 
+#### Skipping Referential Integrity Checks
+
+By default, when creating entities with foreign key references, dyna-record performs condition checks to ensure that referenced entities exist. This prevents creating entities with invalid foreign key references. However, in high-contention or high-throughput systems where the same foreign key may be referenced in parallel operations, these condition checks can fail due to transaction conflicts. In scenarios such as bulk imports or when you've already verified the references, you may want to skip these checks to prevent such failures.
+
+To skip referential integrity checks, pass an options object as the second parameter with `referentialIntegrityCheck: false`:
+
+```typescript
+const grade: Grade = await Grade.create(
+  {
+    gradeValue: "A+",
+    assignmentId: "123",
+    studentId: "456"
+  },
+  { referentialIntegrityCheck: false }
+);
+```
+
+**Note:** When `referentialIntegrityCheck` is set to `false`, the condition checks that verify foreign key references exist are skipped. This means you can create entities even if the referenced entities don't exist, which may lead to data integrity issues. Use this option with caution.
+
 #### Error handling
 
 The method is designed to throw errors under various conditions, such as transaction cancellation due to failed conditional checks. For instance, if you attempt to create a `Grade` for an `Assignment` that already has one, the method throws a [TransactionWriteFailedError](https://dyna-record.com/classes/TransactionWriteFailedError.html).
@@ -547,6 +568,31 @@ const updatedInstance = await petInstance.update({
 });
 ```
 
+#### Skipping Referential Integrity Checks
+
+By default, when updating entities with foreign key references, dyna-record performs condition checks to ensure that referenced entities exist. This prevents updating entities with invalid foreign key references. However, in high-contention or high-throughput systems where the same foreign key may be referenced in parallel operations, these condition checks can fail due to transaction conflicts. In scenarios such as bulk updates or when you've already verified the references, you may want to skip these checks to prevent such failures.
+
+To skip referential integrity checks, pass an options object as the third parameter with `referentialIntegrityCheck: false`:
+
+```typescript
+await PaymentMethod.update(
+  "123",
+  { customerId: "456" },
+  { referentialIntegrityCheck: false }
+);
+```
+
+For instance methods:
+
+```typescript
+const updatedInstance = await paymentMethodInstance.update(
+  { customerId: "456" },
+  { referentialIntegrityCheck: false }
+);
+```
+
+**Note:** When `referentialIntegrityCheck` is set to `false`, the condition checks that verify foreign key references exist are skipped. This means you can update entities even if the referenced entities don't exist, which may lead to data integrity issues. Use this option with caution.
+
 ### Delete
 
 [Docs](https://dyna-record.com/classes/default.html#delete)

package/dist/src/DynaRecord.d.ts

@@ -181,24 +181,36 @@ declare abstract class DynaRecord implements DynaRecordBase {
      */
     static query<T extends DynaRecord>(this: EntityClass<T>, key: IndexKeyConditions<T>, options: OptionsWithIndex): Promise<QueryResults<T>>;
     /**
-     * Create an entity. If foreign keys are included in the attributes then links will be demoralized accordingly
+     * Create an entity. If foreign keys are included in the attributes then links will be denormalized accordingly
      * @param attributes - Attributes of the model to create
+     * @param options - Optional operation options including referentialIntegrityCheck flag
      * @returns The new Entity
      *
+     * @example Basic usage
      * ```typescript
      * const newUser = await User.create({ name: "Alice", email: "alice@example.com", profileId: "123" });
      * ```
+     *
+     * @example With referential integrity check disabled
+     * ```typescript
+     * const newUser = await User.create(
+     *   { name: "Alice", email: "alice@example.com", profileId: "123" },
+     *   { referentialIntegrityCheck: false }
+     * );
+     * ```
      */
-    static create<T extends DynaRecord>(this: EntityClass<T>, attributes: CreateOptions<T>): Promise<ReturnType<Create<T>["run"]>>;
+    static create<T extends DynaRecord>(this: EntityClass<T>, attributes: CreateOptions<T>, options?: {
+        referentialIntegrityCheck?: boolean;
+    }): Promise<ReturnType<Create<T>["run"]>>;
     /**
-     * Update an entity. If foreign keys are included in the attribute then:
+     * Update an entity. If foreign keys are included in the attributes then:
      *   - Manages associated relationship links as needed
      *   - If the entity already had a foreign key relationship, then denormalized records will be deleted from each partition
      *     - If the foreign key is not nullable then a {@link NullConstraintViolationError} is thrown.
      *   - Validation errors will be thrown if the attribute being removed is not nullable
      * @param id - The id of the entity to update
      * @param attributes - Attributes to update
-     *
+     * @param options - Optional operation options including referentialIntegrityCheck flag
      *
      * @example Updating an entity.
      * ```typescript
@@ -209,12 +221,22 @@ declare abstract class DynaRecord implements DynaRecordBase {
      * ```typescript
      * await User.update("userId", { email: "newemail@example.com", someKey: null });
      * ```
+     *
+     * @example With referential integrity check disabled
+     * ```typescript
+     * await User.update(
+     *   "userId",
+     *   { email: "newemail@example.com", profileId: 789 },
+     *   { referentialIntegrityCheck: false }
+     * );
+     * ```
      */
-    static update<T extends DynaRecord>(this: EntityClass<T>, id: string, attributes: UpdateOptions<T>): Promise<void>;
+    static update<T extends DynaRecord>(this: EntityClass<T>, id: string, attributes: UpdateOptions<T>, options?: {
+        referentialIntegrityCheck?: boolean;
+    }): Promise<void>;
     /**
      *  Same as the static `update` method but on an instance. Returns the full updated instance
      *
-     *
      * @example Updating an entity.
      * ```typescript
      * const updatedInstance = await instance.update({ email: "newemail@example.com", profileId: 789 });
@@ -224,8 +246,18 @@ declare abstract class DynaRecord implements DynaRecordBase {
      * ```typescript
      * const updatedInstance = await instance.update({ email: "newemail@example.com", someKey: null });
      * ```
+     *
+     * @example With referential integrity check disabled
+     * ```typescript
+     * const updatedInstance = await instance.update(
+     *   { email: "newemail@example.com", profileId: 789 },
+     *   { referentialIntegrityCheck: false }
+     * );
+     * ```
      */
-    update<T extends this>(attributes: UpdateOptions<T>): Promise<EntityAttributesInstance<T>>;
+    update<T extends this>(attributes: UpdateOptions<T>, options?: {
+        referentialIntegrityCheck?: boolean;
+    }): Promise<EntityAttributesInstance<T>>;
     /**
      * Delete an entity by ID
      *   - Delete all denormalized records

package/dist/src/DynaRecord.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DynaRecord.d.ts","sourceRoot":"","sources":["../../src/DynaRecord.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"DynaRecord.d.ts","sourceRoot":"","sources":["../../src/DynaRecord.ts"],"names":[],"mappings":"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"}

package/dist/src/DynaRecord.js

@@ -145,27 +145,37 @@ let DynaRecord = (() => {
             return await op.run(key, options);
         }
         /**
-         * Create an entity. If foreign keys are included in the attributes then links will be demoralized accordingly
+         * Create an entity. If foreign keys are included in the attributes then links will be denormalized accordingly
          * @param attributes - Attributes of the model to create
+         * @param options - Optional operation options including referentialIntegrityCheck flag
          * @returns The new Entity
          *
+         * @example Basic usage
          * ```typescript
          * const newUser = await User.create({ name: "Alice", email: "alice@example.com", profileId: "123" });
          * ```
+         *
+         * @example With referential integrity check disabled
+         * ```typescript
+         * const newUser = await User.create(
+         *   { name: "Alice", email: "alice@example.com", profileId: "123" },
+         *   { referentialIntegrityCheck: false }
+         * );
+         * ```
          */
-        static async create(attributes) {
+        static async create(attributes, options) {
             const op = new operations_1.Create(this);
-            return await op.run(attributes);
+            return await op.run(attributes, options);
         }
         /**
-         * Update an entity. If foreign keys are included in the attribute then:
+         * Update an entity. If foreign keys are included in the attributes then:
          *   - Manages associated relationship links as needed
          *   - If the entity already had a foreign key relationship, then denormalized records will be deleted from each partition
          *     - If the foreign key is not nullable then a {@link NullConstraintViolationError} is thrown.
          *   - Validation errors will be thrown if the attribute being removed is not nullable
          * @param id - The id of the entity to update
          * @param attributes - Attributes to update
-         *
+         * @param options - Optional operation options including referentialIntegrityCheck flag
          *
          * @example Updating an entity.
          * ```typescript
@@ -176,15 +186,23 @@ let DynaRecord = (() => {
          * ```typescript
          * await User.update("userId", { email: "newemail@example.com", someKey: null });
          * ```
+         *
+         * @example With referential integrity check disabled
+         * ```typescript
+         * await User.update(
+         *   "userId",
+         *   { email: "newemail@example.com", profileId: 789 },
+         *   { referentialIntegrityCheck: false }
+         * );
+         * ```
          */
-        static async update(id, attributes) {
+        static async update(id, attributes, options) {
             const op = new operations_1.Update(this);
-            await op.run(id, attributes);
+            await op.run(id, attributes, options);
         }
         /**
          *  Same as the static `update` method but on an instance. Returns the full updated instance
          *
-         *
          * @example Updating an entity.
          * ```typescript
          * const updatedInstance = await instance.update({ email: "newemail@example.com", profileId: 789 });
@@ -194,11 +212,19 @@ let DynaRecord = (() => {
          * ```typescript
          * const updatedInstance = await instance.update({ email: "newemail@example.com", someKey: null });
          * ```
+         *
+         * @example With referential integrity check disabled
+         * ```typescript
+         * const updatedInstance = await instance.update(
+         *   { email: "newemail@example.com", profileId: 789 },
+         *   { referentialIntegrityCheck: false }
+         * );
+         * ```
          */
-        async update(attributes) {
+        async update(attributes, options) {
             const InstanceClass = this.constructor;
             const op = new operations_1.Update(InstanceClass);
-            const updatedAttributes = await op.run(this.id, attributes);
+            const updatedAttributes = await op.run(this.id, attributes, options);
             const clone = structuredClone(this);
             // Update the current instance with new attributes
             Object.assign(clone, updatedAttributes);

package/dist/src/decorators/attributes/ForeignKeyAttribute.d.ts

@@ -1,5 +1,5 @@
 import type DynaRecord from "../../DynaRecord";
-import type { ForeignKey, NullableForeignKey } from "../../types";
+import type { EntityClass, ForeignKey, NullableForeignKey } from "../../types";
 import type { AttributeDecoratorContext, AttributeOptions } from "../types";
 /**
  * A decorator for annotating class fields as foreign keys within the context of a single-table design entity, aimed at establishing and managing relationships between different entities in a relational manner. This decorator enables the clear and explicit declaration of foreign key relationships, contributing to the ORM's ability to navigate and resolve these associations efficiently.
@@ -8,21 +8,25 @@ import type { AttributeDecoratorContext, AttributeOptions } from "../types";
  *
  * Does not allow property to be optional.
  *
+ * Supplying the target entity enables DynaRecord to enforce referential integrity for the foreign key even when no relationship decorators are defined (for example when a foreign key is used purely for validation without denormalising related records).
+ *
  * @template T The entity the decorator is applied to.
+ * @template K The entity that the foreign key references.
+ * @param getTarget A function returning the constructor for the entity referenced by the foreign key. This allows deferred resolution to avoid circular dependency issues.
  * @param props An optional object of {@link AttributeOptions}, including configuration options such as metadata attributes. These options allow for additional customization of the foreign key attribute, including aliasing and metadata tagging.
  * @returns A class field decorator function that targets and initializes the class's prototype to register the foreign key with the ORM's metadata system. This registration is crucial for enabling the ORM to correctly interpret and manage the relationships between entities.
  *
  * Usage example:
  * ```typescript
  * class Order extends TableClass {
- *   @ForeignKeyAttribute({ alias: 'UserID' })
- *   public userId: ForeignKey; // Foreign key to the User entity. Cannot be optional.
+ *   @ForeignKeyAttribute(() => User, { alias: 'UserID' })
+ *   public userId: ForeignKey<User>; // Foreign key to the User entity. Cannot be optional.
  *
  *   @BelongsTo(() => User, { foreignKey: "userId" })
  *   public readonly user: User; // Cannot be optional
  *
- *   @ForeignKeyAttribute({ alias: 'ProfileId', nullable: true })
- *   public profileId?: NullableForeignKey; // Set to optional. Nullable foreign key to another entity (e.g., UserProfile)
+ *   @ForeignKeyAttribute(() => Profile, { alias: 'ProfileId', nullable: true })
+ *   public profileId?: NullableForeignKey<Profile>; // Set to optional. Nullable foreign key to another entity (e.g., UserProfile)
  *
  *   @BelongsTo(() => Profile, { foreignKey: "profileId" })
  *   public readonly profile?: Profile; // Set to optional because its linked via a NullableForeignKey
@@ -31,6 +35,6 @@ import type { AttributeDecoratorContext, AttributeOptions } from "../types";
  *
  * Here, `@ForeignKeyAttribute` decorates `userId` of `Order`, designating it as a foreign key that references the `User` entity. This decoration not only clarifies the nature of the relationship but also empowers the ORM to enforce relational integrity and facilitate entity association operations.
  */
-declare function ForeignKeyAttribute<T extends DynaRecord, P extends AttributeOptions>(props?: P): (_value: undefined, context: AttributeDecoratorContext<T, P["nullable"] extends true ? NullableForeignKey : ForeignKey, P>) => void;
+declare function ForeignKeyAttribute<TargetEntity extends DynaRecord, T extends DynaRecord, P extends AttributeOptions>(getTarget: () => EntityClass<TargetEntity>, props?: P): (_value: undefined, context: AttributeDecoratorContext<T, P["nullable"] extends true ? NullableForeignKey<TargetEntity> : ForeignKey<TargetEntity>, P>) => void;
 export default ForeignKeyAttribute;
 //# sourceMappingURL=ForeignKeyAttribute.d.ts.map

package/dist/src/decorators/attributes/ForeignKeyAttribute.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ForeignKeyAttribute.d.ts","sourceRoot":"","sources":["../../../../src/decorators/attributes/ForeignKeyAttribute.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,UAAU,MAAM,kBAAkB,CAAC;AAE/C,OAAO,KAAK,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAClE,OAAO,KAAK,EAAE,yBAAyB,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAE5E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,iBAAS,mBAAmB,CAAC,CAAC,SAAS,UAAU,EAAE,CAAC,SAAS,gBAAgB,EAC3E,KAAK,CAAC,EAAE,CAAC,YAGC,SAAS,WACR,yBAAyB,CAChC,CAAC,EACD,CAAC,CAAC,UAAU,CAAC,SAAS,IAAI,GAAG,kBAAkB,GAAG,UAAU,EAC5D,CAAC,CACF,UAaJ;AAED,eAAe,mBAAmB,CAAC"}
+{"version":3,"file":"ForeignKeyAttribute.d.ts","sourceRoot":"","sources":["../../../../src/decorators/attributes/ForeignKeyAttribute.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,UAAU,MAAM,kBAAkB,CAAC;AAE/C,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAC/E,OAAO,KAAK,EAAE,yBAAyB,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAE5E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,iBAAS,mBAAmB,CAC1B,YAAY,SAAS,UAAU,EAC/B,CAAC,SAAS,UAAU,EACpB,CAAC,SAAS,gBAAgB,EAC1B,SAAS,EAAE,MAAM,WAAW,CAAC,YAAY,CAAC,EAAE,KAAK,CAAC,EAAE,CAAC,YAE3C,SAAS,WACR,yBAAyB,CAChC,CAAC,EACD,CAAC,CAAC,UAAU,CAAC,SAAS,IAAI,GACtB,kBAAkB,CAAC,YAAY,CAAC,GAChC,UAAU,CAAC,YAAY,CAAC,EAC5B,CAAC,CACF,UAgBJ;AAED,eAAe,mBAAmB,CAAC"}

package/dist/src/decorators/attributes/ForeignKeyAttribute.js

@@ -12,21 +12,25 @@ const metadata_1 = __importDefault(require("../../metadata"));
  *
  * Does not allow property to be optional.
  *
+ * Supplying the target entity enables DynaRecord to enforce referential integrity for the foreign key even when no relationship decorators are defined (for example when a foreign key is used purely for validation without denormalising related records).
+ *
  * @template T The entity the decorator is applied to.
+ * @template K The entity that the foreign key references.
+ * @param getTarget A function returning the constructor for the entity referenced by the foreign key. This allows deferred resolution to avoid circular dependency issues.
  * @param props An optional object of {@link AttributeOptions}, including configuration options such as metadata attributes. These options allow for additional customization of the foreign key attribute, including aliasing and metadata tagging.
  * @returns A class field decorator function that targets and initializes the class's prototype to register the foreign key with the ORM's metadata system. This registration is crucial for enabling the ORM to correctly interpret and manage the relationships between entities.
  *
  * Usage example:
  * ```typescript
  * class Order extends TableClass {
- *   @ForeignKeyAttribute({ alias: 'UserID' })
- *   public userId: ForeignKey; // Foreign key to the User entity. Cannot be optional.
+ *   @ForeignKeyAttribute(() => User, { alias: 'UserID' })
+ *   public userId: ForeignKey<User>; // Foreign key to the User entity. Cannot be optional.
  *
  *   @BelongsTo(() => User, { foreignKey: "userId" })
  *   public readonly user: User; // Cannot be optional
  *
- *   @ForeignKeyAttribute({ alias: 'ProfileId', nullable: true })
- *   public profileId?: NullableForeignKey; // Set to optional. Nullable foreign key to another entity (e.g., UserProfile)
+ *   @ForeignKeyAttribute(() => Profile, { alias: 'ProfileId', nullable: true })
+ *   public profileId?: NullableForeignKey<Profile>; // Set to optional. Nullable foreign key to another entity (e.g., UserProfile)
  *
  *   @BelongsTo(() => Profile, { foreignKey: "profileId" })
  *   public readonly profile?: Profile; // Set to optional because its linked via a NullableForeignKey
@@ -35,14 +39,16 @@ const metadata_1 = __importDefault(require("../../metadata"));
  *
  * Here, `@ForeignKeyAttribute` decorates `userId` of `Order`, designating it as a foreign key that references the `User` entity. This decoration not only clarifies the nature of the relationship but also empowers the ORM to enforce relational integrity and facilitate entity association operations.
  */
-function ForeignKeyAttribute(props) {
+function ForeignKeyAttribute(getTarget, props) {
     return function (_value, context) {
         if (context.kind === "field") {
             context.addInitializer(function () {
+                const targetEntity = getTarget();
                 metadata_1.default.addEntityAttribute(this.constructor.name, {
                     attributeName: context.name.toString(),
                     nullable: props?.nullable,
                     type: zod_1.z.string(),
+                    foreignKeyTarget: targetEntity,
                     ...props
                 });
             });

package/dist/src/decorators/relationships/BelongsTo.d.ts

@@ -1,6 +1,7 @@
 import type DynaRecord from "../../DynaRecord";
 import type { EntityClass } from "../../types";
-import type { BelongsToField, BelongsToProps } from "./types";
+import type { BelongsToField, BelongsToProps, BelongsToTarget } from "./types";
+import type { ForeignEntityAttribute } from "../types";
 /**
  * A decorator for defining a "BelongsTo" relationship between entities in a single-table design using DynaRecord. This relationship indicates that the decorated field is a reference to another entity, effectively establishing a parent-child linkage. The decorator dynamically enforces the presence or optionality of this reference based on the nature of the foreign key, enhancing type safety and relationship integrity within the ORM model.
  *
@@ -29,6 +30,6 @@ import type { BelongsToField, BelongsToProps } from "./types";
  * ```
  * In this example, `@BelongsTo` decorates the `user` field of the `Order` entity, establishing a "BelongsTo" relationship with the `User` entity via the `userId` foreign key. This decoration signifies that each `Order` instance is related to a specific `User` instance.
  */
-declare function BelongsTo<T extends DynaRecord, K extends DynaRecord>(getTarget: () => EntityClass<K>, props: BelongsToProps<T>): (_value: undefined, context: ClassFieldDecoratorContext<T, BelongsToField<T, K, typeof props.foreignKey>>) => void;
+declare function BelongsTo<Source extends DynaRecord, FK extends ForeignEntityAttribute<Source>>(getTarget: () => EntityClass<BelongsToTarget<Source, FK>>, props: BelongsToProps<Source, FK>): (_value: undefined, context: ClassFieldDecoratorContext<Source, BelongsToField<Source, FK>>) => void;
 export default BelongsTo;
 //# sourceMappingURL=BelongsTo.d.ts.map

package/dist/src/decorators/relationships/BelongsTo.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"BelongsTo.d.ts","sourceRoot":"","sources":["../../../../src/decorators/relationships/BelongsTo.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,UAAU,MAAM,kBAAkB,CAAC;AAC/C,OAAO,KAAK,EAAE,WAAW,EAAsB,MAAM,aAAa,CAAC;AACnE,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE9D;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,iBAAS,SAAS,CAAC,CAAC,SAAS,UAAU,EAAE,CAAC,SAAS,UAAU,EAC3D,SAAS,EAAE,MAAM,WAAW,CAAC,CAAC,CAAC,EAC/B,KAAK,EAAE,cAAc,CAAC,CAAC,CAAC,YAGd,SAAS,WACR,0BAA0B,CACjC,CAAC,EACD,cAAc,CAAC,CAAC,EAAE,CAAC,EAAE,OAAO,KAAK,CAAC,UAAU,CAAC,CAC9C,UAaJ;AAED,eAAe,SAAS,CAAC"}
+{"version":3,"file":"BelongsTo.d.ts","sourceRoot":"","sources":["../../../../src/decorators/relationships/BelongsTo.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,UAAU,MAAM,kBAAkB,CAAC;AAC/C,OAAO,KAAK,EAAE,WAAW,EAAsB,MAAM,aAAa,CAAC;AACnE,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAC/E,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAC;AAEvD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,iBAAS,SAAS,CAChB,MAAM,SAAS,UAAU,EACzB,EAAE,SAAS,sBAAsB,CAAC,MAAM,CAAC,EAEzC,SAAS,EAAE,MAAM,WAAW,CAAC,eAAe,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,EACzD,KAAK,EAAE,cAAc,CAAC,MAAM,EAAE,EAAE,CAAC,YAGvB,SAAS,WACR,0BAA0B,CAAC,MAAM,EAAE,cAAc,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,UAa1E;AAED,eAAe,SAAS,CAAC"}

package/dist/src/decorators/relationships/types.d.ts

@@ -1,11 +1,16 @@
 import type DynaRecord from "../../DynaRecord";
-import type { NullableForeignKey, Optional } from "../../types";
+import type { ForeignKey, NullableForeignKey, Optional } from "../../types";
 import type { ForeignEntityAttribute } from "../types";
-export interface BelongsToProps<T extends DynaRecord> {
-    foreignKey: ForeignEntityAttribute<T>;
+type NullableForeignKeyBrand<T extends DynaRecord> = NonNullable<NullableForeignKey<T>>;
+type NormalizedForeignKey<Value> = NonNullable<Value>;
+type ExtractForeignKeyTarget<Value> = NormalizedForeignKey<Value> extends ForeignKey<infer Target> ? Target : NormalizedForeignKey<Value> extends NullableForeignKeyBrand<infer Target> ? Target : never;
+export interface BelongsToProps<T extends DynaRecord, FK extends ForeignEntityAttribute<T>> {
+    foreignKey: FK;
 }
+export type BelongsToTarget<T extends DynaRecord, FK extends ForeignEntityAttribute<T>> = FK extends keyof T ? ExtractForeignKeyTarget<T[FK]> : never;
 /**
- * If the relationship is linked by a NullableForeignKey then it allows the field to be optional, otherwise it ensures that is is not optional
+ * If the relationship is linked by a NullableForeignKey then it allows the field to be optional, otherwise it ensures that it is not optional
  */
-export type BelongsToField<T extends DynaRecord, K extends DynaRecord, FK extends ForeignEntityAttribute<T>> = FK extends keyof T ? T[FK] extends NullableForeignKey ? Optional<K> : K : never;
+export type BelongsToField<T extends DynaRecord, FK extends ForeignEntityAttribute<T>> = FK extends keyof T ? BelongsToTarget<T, FK> extends never ? never : undefined extends T[FK] ? Optional<BelongsToTarget<T, FK>> : BelongsToTarget<T, FK> : never;
+export {};
 //# sourceMappingURL=types.d.ts.map

package/dist/src/decorators/relationships/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/decorators/relationships/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,UAAU,MAAM,kBAAkB,CAAC;AAC/C,OAAO,KAAK,EAAE,kBAAkB,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAChE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAC;AAEvD,MAAM,WAAW,cAAc,CAAC,CAAC,SAAS,UAAU;IAClD,UAAU,EAAE,sBAAsB,CAAC,CAAC,CAAC,CAAC;CACvC;AAED;;GAEG;AACH,MAAM,MAAM,cAAc,CACxB,CAAC,SAAS,UAAU,EACpB,CAAC,SAAS,UAAU,EACpB,EAAE,SAAS,sBAAsB,CAAC,CAAC,CAAC,IAClC,EAAE,SAAS,MAAM,CAAC,GAClB,CAAC,CAAC,EAAE,CAAC,SAAS,kBAAkB,GAC9B,QAAQ,CAAC,CAAC,CAAC,GACX,CAAC,GACH,KAAK,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/decorators/relationships/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,UAAU,MAAM,kBAAkB,CAAC;AAC/C,OAAO,KAAK,EAAE,UAAU,EAAE,kBAAkB,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC5E,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAC;AAEvD,KAAK,uBAAuB,CAAC,CAAC,SAAS,UAAU,IAAI,WAAW,CAC9D,kBAAkB,CAAC,CAAC,CAAC,CACtB,CAAC;AAEF,KAAK,oBAAoB,CAAC,KAAK,IAAI,WAAW,CAAC,KAAK,CAAC,CAAC;AAEtD,KAAK,uBAAuB,CAAC,KAAK,IAChC,oBAAoB,CAAC,KAAK,CAAC,SAAS,UAAU,CAAC,MAAM,MAAM,CAAC,GACxD,MAAM,GACN,oBAAoB,CAAC,KAAK,CAAC,SAAS,uBAAuB,CAAC,MAAM,MAAM,CAAC,GACvE,MAAM,GACN,KAAK,CAAC;AAEd,MAAM,WAAW,cAAc,CAC7B,CAAC,SAAS,UAAU,EACpB,EAAE,SAAS,sBAAsB,CAAC,CAAC,CAAC;IAEpC,UAAU,EAAE,EAAE,CAAC;CAChB;AAED,MAAM,MAAM,eAAe,CACzB,CAAC,SAAS,UAAU,EACpB,EAAE,SAAS,sBAAsB,CAAC,CAAC,CAAC,IAClC,EAAE,SAAS,MAAM,CAAC,GAAG,uBAAuB,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,KAAK,CAAC;AAEhE;;GAEG;AACH,MAAM,MAAM,cAAc,CACxB,CAAC,SAAS,UAAU,EACpB,EAAE,SAAS,sBAAsB,CAAC,CAAC,CAAC,IAClC,EAAE,SAAS,MAAM,CAAC,GAClB,eAAe,CAAC,CAAC,EAAE,EAAE,CAAC,SAAS,KAAK,GAClC,KAAK,GACL,SAAS,SAAS,CAAC,CAAC,EAAE,CAAC,GACrB,QAAQ,CAAC,eAAe,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,GAChC,eAAe,CAAC,CAAC,EAAE,EAAE,CAAC,GAC1B,KAAK,CAAC"}

package/dist/src/metadata/AttributeMetadata.d.ts

@@ -1,5 +1,7 @@
 import { type ZodType } from "zod";
+import type DynaRecord from "../DynaRecord";
 import type { AttributeMetadataOptions, Serializers } from "./types";
+import type { EntityClass } from "../types";
 /**
  * Represents the metadata for an attribute of an entity, including its name, alias (if any), nullability, and serialization strategies.
  *
@@ -10,6 +12,7 @@ import type { AttributeMetadataOptions, Serializers } from "./types";
  * @property {boolean} nullable - Indicates whether the attribute can be `null`, defining the attribute's nullability constraint within the database.
  * @property {Serializers | undefined} serializers - Optional serialization strategies for converting the attribute between its database representation and its entity representation. This is particularly useful for custom data types not natively supported by DynamoDB.
  * @property {ZodType} type - Zod validator to run on the attribute
+ * @property {EntityClass | undefined} foreignKeyTarget - When present, identifies the entity referenced by a foreign key attribute, enabling referential integrity enforcement.
  *
  * @param {AttributeMetadataOptions} options - Configuration options for the attribute metadata, including the attribute's name, optional alias, nullability, and serialization strategies.
  */
@@ -19,6 +22,7 @@ declare class AttributeMetadata {
     readonly nullable: boolean;
     readonly serializers?: Serializers;
     readonly type: ZodType;
+    readonly foreignKeyTarget?: EntityClass<DynaRecord>;
     constructor(options: AttributeMetadataOptions);
 }
 export default AttributeMetadata;

package/dist/src/metadata/AttributeMetadata.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AttributeMetadata.d.ts","sourceRoot":"","sources":["../../../src/metadata/AttributeMetadata.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,OAAO,EAAE,MAAM,KAAK,CAAC;AACnC,OAAO,KAAK,EAAE,wBAAwB,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAErE;;;;;;;;;;;;GAYG;AACH,cAAM,iBAAiB;IACrB,SAAgB,IAAI,EAAE,MAAM,CAAC;IAC7B,SAAgB,KAAK,EAAE,MAAM,CAAC;IAC9B,SAAgB,QAAQ,EAAE,OAAO,CAAC;IAClC,SAAgB,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1C,SAAgB,IAAI,EAAE,OAAO,CAAC;gBAElB,OAAO,EAAE,wBAAwB;CAY9C;AAED,eAAe,iBAAiB,CAAC"}
+{"version":3,"file":"AttributeMetadata.d.ts","sourceRoot":"","sources":["../../../src/metadata/AttributeMetadata.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,OAAO,EAAE,MAAM,KAAK,CAAC;AACnC,OAAO,KAAK,UAAU,MAAM,eAAe,CAAC;AAC5C,OAAO,KAAK,EAAE,wBAAwB,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AACrE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAE5C;;;;;;;;;;;;;GAaG;AACH,cAAM,iBAAiB;IACrB,SAAgB,IAAI,EAAE,MAAM,CAAC;IAC7B,SAAgB,KAAK,EAAE,MAAM,CAAC;IAC9B,SAAgB,QAAQ,EAAE,OAAO,CAAC;IAClC,SAAgB,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1C,SAAgB,IAAI,EAAE,OAAO,CAAC;IAC9B,SAAgB,gBAAgB,CAAC,EAAE,WAAW,CAAC,UAAU,CAAC,CAAC;gBAE/C,OAAO,EAAE,wBAAwB;CAa9C;AAED,eAAe,iBAAiB,CAAC"}

package/dist/src/metadata/AttributeMetadata.js

@@ -10,6 +10,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
  * @property {boolean} nullable - Indicates whether the attribute can be `null`, defining the attribute's nullability constraint within the database.
  * @property {Serializers | undefined} serializers - Optional serialization strategies for converting the attribute between its database representation and its entity representation. This is particularly useful for custom data types not natively supported by DynamoDB.
  * @property {ZodType} type - Zod validator to run on the attribute
+ * @property {EntityClass | undefined} foreignKeyTarget - When present, identifies the entity referenced by a foreign key attribute, enabling referential integrity enforcement.
  *
  * @param {AttributeMetadataOptions} options - Configuration options for the attribute metadata, including the attribute's name, optional alias, nullability, and serialization strategies.
  */
@@ -19,11 +20,13 @@ class AttributeMetadata {
     nullable;
     serializers;
     type;
+    foreignKeyTarget;
     constructor(options) {
         this.name = options.attributeName;
         this.alias = options.alias ?? options.attributeName;
         this.nullable = options.nullable ?? false;
         this.serializers = options.serializers;
+        this.foreignKeyTarget = options.foreignKeyTarget;
         if (options.nullable === true) {
             this.type = options.type.optional().nullable();
         }

package/dist/src/metadata/EntityMetadata.d.ts

@@ -1,4 +1,4 @@
-import type { BelongsToRelationship, HasRelationships, AttributeMetadata, AttributeMetadataStorage, RelationshipMetadataStorage, RelationshipMetadata, OwnedByRelationship, BelongsToOrOwnedByRelationship } from ".";
+import type { BelongsToRelationship, HasRelationships, AttributeMetadata, AttributeMetadataStorage, RelationshipMetadataStorage, RelationshipMetadata, OwnedByRelationship, BelongsToOrOwnedByRelationship, ForeignKeyAttributeMetadata } from ".";
 import type DynaRecord from "../DynaRecord";
 import { type EntityDefinedAttributes } from "../operations";
 type EntityClass = new (...args: any) => DynaRecord;
@@ -83,6 +83,16 @@ declare class EntityMetadata {
      * Returns the "Has" relationship metadata for the entity (EX: "HasMany")
      */
     get hasRelationships(): HasRelationships;
+    /**
+     * Returns attribute metadata for attributes that reference a foreign entity via {@link ForeignKeyAttribute}.
+     * The returned metadata guarantees a non-null {@link ForeignKeyAttributeMetadata.foreignKeyTarget}.
+     */
+    get foreignKeyAttributes(): ForeignKeyAttributeMetadata[];
+    /**
+     * Returns foreign key attributes that are not linked through a relationship decorator.
+     * These attributes rely on standalone referential integrity checks during create and update operations.
+     */
+    get standaloneForeignKeyAttributes(): ForeignKeyAttributeMetadata[];
 }
 export default EntityMetadata;
 //# sourceMappingURL=EntityMetadata.d.ts.map

package/dist/src/metadata/EntityMetadata.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"EntityMetadata.d.ts","sourceRoot":"","sources":["../../../src/metadata/EntityMetadata.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,qBAAqB,EACrB,gBAAgB,EAChB,iBAAiB,EACjB,wBAAwB,EACxB,2BAA2B,EAC3B,oBAAoB,EACpB,mBAAmB,EACnB,8BAA8B,EAC/B,MAAM,GAAG,CAAC;AACX,OAAO,KAAK,UAAU,MAAM,eAAe,CAAC;AAE5C,OAAO,EAAE,KAAK,uBAAuB,EAAE,MAAM,eAAe,CAAC;AAU7D,KAAK,WAAW,GAAG,KAAK,GAAG,IAAI,EAAE,GAAG,KAAK,UAAU,CAAC;AAEpD;;;;;;;;;;;GAWG;AACH,cAAM,cAAc;;IAClB;;OAEG;IACH,SAAgB,cAAc,EAAE,MAAM,CAAC;IACvC;;OAEG;IACH,SAAgB,UAAU,EAAE,wBAAwB,CAAC;IACrD;;OAEG;IACH,SAAgB,eAAe,EAAE,wBAAwB,CAAC;IAE1D;;OAEG;IACH,SAAgB,aAAa,EAAE,2BAA2B,CAAC;IAE3D,SAAgB,WAAW,EAAE,WAAW,CAAC;IAEzC;;OAEG;IACI,OAAO,EAAE,MAAM,CAAC;gBAiBX,WAAW,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM;IAS5D;;;OAGG;IACI,YAAY,CAAC,QAAQ,EAAE,iBAAiB,GAAG,IAAI;IAOtD;;;;;OAKG;IACI,+BAA+B,CACpC,UAAU,EAAE,uBAAuB,CAAC,UAAU,CAAC,GAC9C,uBAAuB,CAAC,UAAU,CAAC;IAatC;;;;;;OAMG;IACI,sCAAsC,CAC3C,UAAU,EAAE,OAAO,CAAC,uBAAuB,CAAC,UAAU,CAAC,CAAC,GACvD,OAAO,CAAC,uBAAuB,CAAC,UAAU,CAAC,CAAC;IA0B/C;;;OAGG;IACH,OAAO,CAAC,oBAAoB;IAM5B;;OAEG;IACH,IAAW,gBAAgB,IAAI,oBAAoB,EAAE,CAEpD;IAED;;OAEG;IACH,IAAW,sBAAsB,IAAI,qBAAqB,EAAE,CAI3D;IAED;;OAEG;IACH,IAAW,oBAAoB,IAAI,mBAAmB,EAAE,CAIvD;IAED;;OAEG;IACH,IAAW,+BAA+B,IAAI,8BAA8B,EAAE,CAE7E;IAED;;OAEG;IACH,IAAW,gBAAgB,IAAI,gBAAgB,CAO9C;CACF;AAED,eAAe,cAAc,CAAC"}
+{"version":3,"file":"EntityMetadata.d.ts","sourceRoot":"","sources":["../../../src/metadata/EntityMetadata.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,qBAAqB,EACrB,gBAAgB,EAChB,iBAAiB,EACjB,wBAAwB,EACxB,2BAA2B,EAC3B,oBAAoB,EACpB,mBAAmB,EACnB,8BAA8B,EAC9B,2BAA2B,EAC5B,MAAM,GAAG,CAAC;AACX,OAAO,KAAK,UAAU,MAAM,eAAe,CAAC;AAE5C,OAAO,EAAE,KAAK,uBAAuB,EAAE,MAAM,eAAe,CAAC;AAY7D,KAAK,WAAW,GAAG,KAAK,GAAG,IAAI,EAAE,GAAG,KAAK,UAAU,CAAC;AAEpD;;;;;;;;;;;GAWG;AACH,cAAM,cAAc;;IAClB;;OAEG;IACH,SAAgB,cAAc,EAAE,MAAM,CAAC;IACvC;;OAEG;IACH,SAAgB,UAAU,EAAE,wBAAwB,CAAC;IACrD;;OAEG;IACH,SAAgB,eAAe,EAAE,wBAAwB,CAAC;IAE1D;;OAEG;IACH,SAAgB,aAAa,EAAE,2BAA2B,CAAC;IAE3D,SAAgB,WAAW,EAAE,WAAW,CAAC;IAEzC;;OAEG;IACI,OAAO,EAAE,MAAM,CAAC;gBAiBX,WAAW,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM;IAS5D;;;OAGG;IACI,YAAY,CAAC,QAAQ,EAAE,iBAAiB,GAAG,IAAI;IAOtD;;;;;OAKG;IACI,+BAA+B,CACpC,UAAU,EAAE,uBAAuB,CAAC,UAAU,CAAC,GAC9C,uBAAuB,CAAC,UAAU,CAAC;IAatC;;;;;;OAMG;IACI,sCAAsC,CAC3C,UAAU,EAAE,OAAO,CAAC,uBAAuB,CAAC,UAAU,CAAC,CAAC,GACvD,OAAO,CAAC,uBAAuB,CAAC,UAAU,CAAC,CAAC;IA0B/C;;;OAGG;IACH,OAAO,CAAC,oBAAoB;IAM5B;;OAEG;IACH,IAAW,gBAAgB,IAAI,oBAAoB,EAAE,CAEpD;IAED;;OAEG;IACH,IAAW,sBAAsB,IAAI,qBAAqB,EAAE,CAI3D;IAED;;OAEG;IACH,IAAW,oBAAoB,IAAI,mBAAmB,EAAE,CAIvD;IAED;;OAEG;IACH,IAAW,+BAA+B,IAAI,8BAA8B,EAAE,CAE7E;IAED;;OAEG;IACH,IAAW,gBAAgB,IAAI,gBAAgB,CAO9C;IAED;;;OAGG;IACH,IAAW,oBAAoB,IAAI,2BAA2B,EAAE,CAE/D;IAED;;;OAGG;IACH,IAAW,8BAA8B,IAAI,2BAA2B,EAAE,CAUzE;CACF;AAED,eAAe,cAAc,CAAC"}

package/dist/src/metadata/EntityMetadata.js

@@ -159,5 +159,22 @@ class EntityMetadata {
             (0, utils_1.isHasManyRelationship)(relMeta) ||
             (0, utils_1.isHasAndBelongsToManyRelationship)(relMeta));
     }
+    /**
+     * Returns attribute metadata for attributes that reference a foreign entity via {@link ForeignKeyAttribute}.
+     * The returned metadata guarantees a non-null {@link ForeignKeyAttributeMetadata.foreignKeyTarget}.
+     */
+    get foreignKeyAttributes() {
+        return Object.values(this.attributes).filter(utils_1.isForeignKeyAttributeMetadata);
+    }
+    /**
+     * Returns foreign key attributes that are not linked through a relationship decorator.
+     * These attributes rely on standalone referential integrity checks during create and update operations.
+     */
+    get standaloneForeignKeyAttributes() {
+        const associatedForeignKeys = new Set(Object.values(this.relationships)
+            .filter(utils_1.isRelationshipMetadataWithForeignKey)
+            .map(rel => rel.foreignKey.toString()));
+        return this.foreignKeyAttributes.filter(attr => !associatedForeignKeys.has(attr.name));
+    }
 }
 exports.default = EntityMetadata;

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

@@ -1,7 +1,7 @@
 import type { NativeScalarAttributeValue } from "@aws-sdk/util-dynamodb";
 import type { AttributeMetadata, BelongsToRelationship, EntityMetadata, JoinTableMetadata, OwnedByRelationship, RelationshipMetadata, TableMetadata } from ".";
 import type DynaRecord from "../DynaRecord";
-import type { MakeOptional } from "../types";
+import type { EntityClass, MakeOptional } from "../types";
 import type { ZodType } from "zod";
 /**
  * Represents relationship metadata that includes a foreign key reference to another entity.
@@ -94,9 +94,21 @@ export interface AttributeMetadataOptions {
     alias?: string;
     nullable?: boolean;
     serializers?: Serializers;
+    /**
+     * When the attribute represents a foreign key, this references the target entity class.
+     * Used to enforce referential integrity even when a relationship decorator is not present.
+     */
+    foreignKeyTarget?: EntityClass<DynaRecord>;
 }
 /**
  * A relationship that is either BelongsTo (bi-directional to parent) or OwnedBy (uni directional to parent)
  */
 export type BelongsToOrOwnedByRelationship = BelongsToRelationship | OwnedByRelationship;
+/**
+ * Attribute metadata for foreign key attributes where {@link AttributeMetadata.foreignKeyTarget} is guaranteed.
+ * Provides the target entity class so operations can enforce referential integrity even when no relationship metadata exists.
+ */
+export interface ForeignKeyAttributeMetadata extends AttributeMetadata {
+    foreignKeyTarget: NonNullable<AttributeMetadata["foreignKeyTarget"]>;
+}
 //# sourceMappingURL=types.d.ts.map