dyna-record 0.3.6 → 0.4.0

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
 }
 ```
 

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

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

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/metadata/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,wBAAwB,CAAC;AACzE,OAAO,KAAK,EACV,iBAAiB,EACjB,qBAAqB,EACrB,cAAc,EACd,iBAAiB,EACjB,mBAAmB,EACnB,oBAAoB,EACpB,aAAa,EACd,MAAM,GAAG,CAAC;AACX,OAAO,KAAK,UAAU,MAAM,eAAe,CAAC;AAC5C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAC7C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,KAAK,CAAC;AAEnC;;GAEG;AACH,MAAM,MAAM,kCAAkC,GAAG,OAAO,CACtD,oBAAoB,EACpB;IAAE,UAAU,EAAE,MAAM,UAAU,CAAA;CAAE,CACjC,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,wBAAwB,GAAG,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;AAEzE;;GAEG;AACH,MAAM,MAAM,2BAA2B,GAAG,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC;AAE/E;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAAG,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;AAEjE;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAAG,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;AAEnE;;GAEG;AACH,MAAM,MAAM,wBAAwB,GAAG,MAAM,CAAC,MAAM,EAAE,iBAAiB,EAAE,CAAC,CAAC;AAE3E;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG,WAAW,GAAG,WAAW,CAAC;AAE1D;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG;KACzB,CAAC,IAAI,MAAM,UAAU,GAAG,UAAU,CAAC,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,GAClE,KAAK,GACL,CAAC;CACN,CAAC,MAAM,UAAU,CAAC,CAAC;AAEpB;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG,MAAM,CACrC,aAAa,EACb,IAAI,CAAC,iBAAiB,EAAE,OAAO,CAAC,CACjC,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,MAAM,oBAAoB,GAAG,IAAI,CAAC,aAAa,EAAE,MAAM,CAAC,GAC5D,OAAO,CAAC,IAAI,CAAC,aAAa,EAAE,WAAW,CAAC,CAAC,GAAG;IAC1C,aAAa,CAAC,EAAE,OAAO,CAAC,kBAAkB,CAAC,CAAC;CAC7C,CAAC;AAEJ;;GAEG;AACH,MAAM,MAAM,4BAA4B,GAAG,YAAY,CACrD,IAAI,CAAC,wBAAwB,EAAE,UAAU,CAAC,EAC1C,OAAO,CACR,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,KAAK,EAAE,0BAA0B,KAAK,GAAG,CAAC;AAE1E;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,KAAK,EAAE,GAAG,KAAK,0BAA0B,CAAC;AAEzE;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B;;OAEG;IACH,iBAAiB,EAAE,gBAAgB,CAAC;IACpC;;OAEG;IACH,gBAAgB,EAAE,eAAe,CAAC;CACnC;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,wBAAwB;IACvC,aAAa,EAAE,MAAM,CAAC;IACtB,IAAI,EAAE,OAAO,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,WAAW,CAAC,EAAE,WAAW,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,MAAM,8BAA8B,GACtC,qBAAqB,GACrB,mBAAmB,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/metadata/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,wBAAwB,CAAC;AACzE,OAAO,KAAK,EACV,iBAAiB,EACjB,qBAAqB,EACrB,cAAc,EACd,iBAAiB,EACjB,mBAAmB,EACnB,oBAAoB,EACpB,aAAa,EACd,MAAM,GAAG,CAAC;AACX,OAAO,KAAK,UAAU,MAAM,eAAe,CAAC;AAC5C,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAC1D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,KAAK,CAAC;AAEnC;;GAEG;AACH,MAAM,MAAM,kCAAkC,GAAG,OAAO,CACtD,oBAAoB,EACpB;IAAE,UAAU,EAAE,MAAM,UAAU,CAAA;CAAE,CACjC,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,wBAAwB,GAAG,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;AAEzE;;GAEG;AACH,MAAM,MAAM,2BAA2B,GAAG,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC;AAE/E;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAAG,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;AAEjE;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAAG,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;AAEnE;;GAEG;AACH,MAAM,MAAM,wBAAwB,GAAG,MAAM,CAAC,MAAM,EAAE,iBAAiB,EAAE,CAAC,CAAC;AAE3E;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG,WAAW,GAAG,WAAW,CAAC;AAE1D;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG;KACzB,CAAC,IAAI,MAAM,UAAU,GAAG,UAAU,CAAC,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,GAClE,KAAK,GACL,CAAC;CACN,CAAC,MAAM,UAAU,CAAC,CAAC;AAEpB;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG,MAAM,CACrC,aAAa,EACb,IAAI,CAAC,iBAAiB,EAAE,OAAO,CAAC,CACjC,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,MAAM,oBAAoB,GAAG,IAAI,CAAC,aAAa,EAAE,MAAM,CAAC,GAC5D,OAAO,CAAC,IAAI,CAAC,aAAa,EAAE,WAAW,CAAC,CAAC,GAAG;IAC1C,aAAa,CAAC,EAAE,OAAO,CAAC,kBAAkB,CAAC,CAAC;CAC7C,CAAC;AAEJ;;GAEG;AACH,MAAM,MAAM,4BAA4B,GAAG,YAAY,CACrD,IAAI,CAAC,wBAAwB,EAAE,UAAU,CAAC,EAC1C,OAAO,CACR,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,KAAK,EAAE,0BAA0B,KAAK,GAAG,CAAC;AAE1E;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,KAAK,EAAE,GAAG,KAAK,0BAA0B,CAAC;AAEzE;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B;;OAEG;IACH,iBAAiB,EAAE,gBAAgB,CAAC;IACpC;;OAEG;IACH,gBAAgB,EAAE,eAAe,CAAC;CACnC;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,wBAAwB;IACvC,aAAa,EAAE,MAAM,CAAC;IACtB,IAAI,EAAE,OAAO,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B;;;OAGG;IACH,gBAAgB,CAAC,EAAE,WAAW,CAAC,UAAU,CAAC,CAAC;CAC5C;AAED;;GAEG;AACH,MAAM,MAAM,8BAA8B,GACtC,qBAAqB,GACrB,mBAAmB,CAAC;AAExB;;;GAGG;AACH,MAAM,WAAW,2BAA4B,SAAQ,iBAAiB;IACpE,gBAAgB,EAAE,WAAW,CAAC,iBAAiB,CAAC,kBAAkB,CAAC,CAAC,CAAC;CACtE"}

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

@@ -1,7 +1,8 @@
-import type { RelationshipMetadata, HasManyRelationship, BelongsToRelationship, HasOneRelationship, HasAndBelongsToManyRelationship, OwnedByRelationship } from ".";
+import type { RelationshipMetadata, HasManyRelationship, BelongsToRelationship, HasOneRelationship, HasAndBelongsToManyRelationship, OwnedByRelationship, ForeignKeyAttributeMetadata } from ".";
 import type DynaRecord from "../DynaRecord";
 import type { BelongsToOrOwnedByRelationship, RelationshipMetadataWithForeignKey } from "./types";
 import type { EntityClass } from "../types";
+import type AttributeMetadata from "./AttributeMetadata";
 /**
  * Type guard to check if the relationship is a HasMany
  */
@@ -28,6 +29,11 @@ export declare const isOwnedByRelationship: (rel: RelationshipMetadata) => rel i
  * @returns
  */
 export declare const isRelationshipMetadataWithForeignKey: (rel: RelationshipMetadata) => rel is RelationshipMetadataWithForeignKey;
+/**
+ * Type guard that checks whether attribute metadata represents a foreign key.
+ * Returns {@link ForeignKeyAttributeMetadata} with a guaranteed target entity.
+ */
+export declare const isForeignKeyAttributeMetadata: (attr: AttributeMetadata) => attr is ForeignKeyAttributeMetadata;
 /**
  * Returns true if an "Entity" BelongsTo the provided relationship as a HasOne
  * @param Entity

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

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../../src/metadata/utils.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,oBAAoB,EACpB,mBAAmB,EACnB,qBAAqB,EACrB,kBAAkB,EAClB,+BAA+B,EAC/B,mBAAmB,EACpB,MAAM,GAAG,CAAC;AACX,OAAO,KAAK,UAAU,MAAM,eAAe,CAAC;AAC5C,OAAO,KAAK,EACV,8BAA8B,EAC9B,kCAAkC,EACnC,MAAM,SAAS,CAAC;AACjB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAE5C;;GAEG;AACH,eAAO,MAAM,qBAAqB,QAC3B,oBAAoB,KACxB,GAAG,IAAI,mBAET,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,uBAAuB,QAC7B,oBAAoB,KACxB,GAAG,IAAI,qBAET,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,oBAAoB,QAC1B,oBAAoB,KACxB,GAAG,IAAI,kBAET,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,iCAAiC,QACvC,oBAAoB,KACxB,GAAG,IAAI,+BAET,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,qBAAqB,QAC3B,oBAAoB,KACxB,GAAG,IAAI,mBAET,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,oCAAoC,QAC1C,oBAAoB,KACxB,GAAG,IAAI,kCAET,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,6BAA6B,GAAI,CAAC,SAAS,UAAU,UACxD,WAAW,CAAC,CAAC,CAAC,OACjB,8BAA8B,KAClC,OAMF,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,8BAA8B,GAAI,CAAC,SAAS,UAAU,UACzD,WAAW,CAAC,CAAC,CAAC,OACjB,8BAA8B,KAClC,OAMF,CAAC"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../../src/metadata/utils.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,oBAAoB,EACpB,mBAAmB,EACnB,qBAAqB,EACrB,kBAAkB,EAClB,+BAA+B,EAC/B,mBAAmB,EACnB,2BAA2B,EAC5B,MAAM,GAAG,CAAC;AACX,OAAO,KAAK,UAAU,MAAM,eAAe,CAAC;AAC5C,OAAO,KAAK,EACV,8BAA8B,EAC9B,kCAAkC,EACnC,MAAM,SAAS,CAAC;AACjB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAC5C,OAAO,KAAK,iBAAiB,MAAM,qBAAqB,CAAC;AAEzD;;GAEG;AACH,eAAO,MAAM,qBAAqB,QAC3B,oBAAoB,KACxB,GAAG,IAAI,mBAET,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,uBAAuB,QAC7B,oBAAoB,KACxB,GAAG,IAAI,qBAET,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,oBAAoB,QAC1B,oBAAoB,KACxB,GAAG,IAAI,kBAET,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,iCAAiC,QACvC,oBAAoB,KACxB,GAAG,IAAI,+BAET,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,qBAAqB,QAC3B,oBAAoB,KACxB,GAAG,IAAI,mBAET,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,oCAAoC,QAC1C,oBAAoB,KACxB,GAAG,IAAI,kCAET,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,6BAA6B,SAClC,iBAAiB,KACtB,IAAI,IAAI,2BAEV,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,6BAA6B,GAAI,CAAC,SAAS,UAAU,UACxD,WAAW,CAAC,CAAC,CAAC,OACjB,8BAA8B,KAClC,OAMF,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,8BAA8B,GAAI,CAAC,SAAS,UAAU,UACzD,WAAW,CAAC,CAAC,CAAC,OACjB,8BAA8B,KAClC,OAMF,CAAC"}

package/dist/src/metadata/utils.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.doesEntityBelongToRelAsHasMany = exports.doesEntityBelongToRelAsHasOne = exports.isRelationshipMetadataWithForeignKey = exports.isOwnedByRelationship = exports.isHasAndBelongsToManyRelationship = exports.isHasOneRelationship = exports.isBelongsToRelationship = exports.isHasManyRelationship = void 0;
+exports.doesEntityBelongToRelAsHasMany = exports.doesEntityBelongToRelAsHasOne = exports.isForeignKeyAttributeMetadata = exports.isRelationshipMetadataWithForeignKey = exports.isOwnedByRelationship = exports.isHasAndBelongsToManyRelationship = exports.isHasOneRelationship = exports.isBelongsToRelationship = exports.isHasManyRelationship = void 0;
 const _1 = __importDefault(require("./"));
 /**
  * Type guard to check if the relationship is a HasMany
@@ -49,6 +49,14 @@ const isRelationshipMetadataWithForeignKey = (rel) => {
     return "foreignKey" in rel;
 };
 exports.isRelationshipMetadataWithForeignKey = isRelationshipMetadataWithForeignKey;
+/**
+ * Type guard that checks whether attribute metadata represents a foreign key.
+ * Returns {@link ForeignKeyAttributeMetadata} with a guaranteed target entity.
+ */
+const isForeignKeyAttributeMetadata = (attr) => {
+    return attr.foreignKeyTarget !== undefined;
+};
+exports.isForeignKeyAttributeMetadata = isForeignKeyAttributeMetadata;
 /**
  * Returns true if an "Entity" BelongsTo the provided relationship as a HasOne
  * @param Entity

package/dist/src/operations/Create/Create.d.ts

@@ -78,6 +78,13 @@ declare class Create<T extends DynaRecord> extends OperationBase<T> {
      * @private
      */
     private buildBelongsToTransactions;
+    /**
+     * Adds DynamoDB condition checks for foreign keys that are not associated with a relationship decorator.
+     * Ensures referenced entities exist even when denormalised access patterns are not defined.
+     *
+     * @param entityData - Attributes being persisted for the new entity.
+     */
+    private buildStandaloneForeignKeyConditionChecks;
     /**
      * Retrieves the DynamoDB items for all entities that the new entity references via "BelongsTo" relationships.
      *

package/dist/src/operations/Create/Create.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Create.d.ts","sourceRoot":"","sources":["../../../../src/operations/Create/Create.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,UAAU,MAAM,kBAAkB,CAAC;AAE/C,OAAO,KAAK,EAAmB,WAAW,EAAE,MAAM,aAAa,CAAC;AAOhE,OAAO,aAAa,MAAM,kBAAkB,CAAC;AAE7C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC7C,OAAO,EAGL,KAAK,oBAAoB,EAC1B,MAAM,UAAU,CAAC;AAIlB;;;;;;;;;;;;;;;;;GAiBG;AACH,cAAM,MAAM,CAAC,CAAC,SAAS,UAAU,CAAE,SAAQ,aAAa,CAAC,CAAC,CAAC;;gBAG7C,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC;IAKlC;;;;;;;;;;;;;;;;OAgBG;IACU,GAAG,CACd,UAAU,EAAE,aAAa,CAAC,CAAC,CAAC,GAC3B,OAAO,CAAC,oBAAoB,CAAC,CAAC,CAAC,CAAC;IA4BnC;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,uBAAuB;IA8B/B;;;;;;;;;OASG;IACH,OAAO,CAAC,uBAAuB;IAiB/B;;;;;;;;;;OAUG;IACH,OAAO,CAAC,0BAA0B;IAkClC;;;;;;;;;;;OAWG;YACW,sBAAsB;IAmCpC;;;;;;;;;;OAUG;IACH,OAAO,CAAC,2CAA2C;IAmBnD;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,uCAAuC;CA0BhD;AAED,eAAe,MAAM,CAAC"}
+{"version":3,"file":"Create.d.ts","sourceRoot":"","sources":["../../../../src/operations/Create/Create.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,UAAU,MAAM,kBAAkB,CAAC;AAE/C,OAAO,KAAK,EAAmB,WAAW,EAAE,MAAM,aAAa,CAAC;AAOhE,OAAO,aAAa,MAAM,kBAAkB,CAAC;AAE7C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC7C,OAAO,EAGL,KAAK,oBAAoB,EAC1B,MAAM,UAAU,CAAC;AAIlB;;;;;;;;;;;;;;;;;GAiBG;AACH,cAAM,MAAM,CAAC,CAAC,SAAS,UAAU,CAAE,SAAQ,aAAa,CAAC,CAAC,CAAC;;gBAG7C,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC;IAKlC;;;;;;;;;;;;;;;;OAgBG;IACU,GAAG,CACd,UAAU,EAAE,aAAa,CAAC,CAAC,CAAC,GAC3B,OAAO,CAAC,oBAAoB,CAAC,CAAC,CAAC,CAAC;IA6BnC;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,uBAAuB;IA8B/B;;;;;;;;;OASG;IACH,OAAO,CAAC,uBAAuB;IAiB/B;;;;;;;;;;OAUG;IACH,OAAO,CAAC,0BAA0B;IAkClC;;;;;OAKG;IACH,OAAO,CAAC,wCAAwC;IA8BhD;;;;;;;;;;;OAWG;YACW,sBAAsB;IAmCpC;;;;;;;;;;OAUG;IACH,OAAO,CAAC,2CAA2C;IAmBnD;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,uCAAuC;CA0BhD;AAED,eAAe,MAAM,CAAC"}

package/dist/src/operations/Create/Create.js

@@ -57,6 +57,7 @@ class Create extends OperationBase_1.default {
         const tableItem = (0, utils_1.entityToTableItem)(this.EntityClass, entityData);
         this.buildPutItemTransaction(tableItem, entityData.id);
         this.buildBelongsToTransactions(entityData, tableItem);
+        this.buildStandaloneForeignKeyConditionChecks(entityData);
         // Attempt to fetch all belongs-to entities to properly create reverse denormalization links
         const belongsToTableItems = await this.getBelongsToTableItems(entityData);
         // If there are any belongs-to relationships, add the inverse link records into the new entity's partition
@@ -145,6 +146,32 @@ class Create extends OperationBase_1.default {
             }
         }
     }
+    /**
+     * Adds DynamoDB condition checks for foreign keys that are not associated with a relationship decorator.
+     * Ensures referenced entities exist even when denormalised access patterns are not defined.
+     *
+     * @param entityData - Attributes being persisted for the new entity.
+     */
+    buildStandaloneForeignKeyConditionChecks(entityData) {
+        const standaloneForeignKeys = this.entityMetadata.standaloneForeignKeyAttributes;
+        for (const attrMeta of standaloneForeignKeys) {
+            const target = attrMeta.foreignKeyTarget;
+            const foreignKeyValue = entityData[attrMeta.name];
+            if (!(0, utils_1.isString)(foreignKeyValue))
+                continue;
+            const foreignKey = foreignKeyValue;
+            const errMsg = `${target.name} with ID '${foreignKey}' does not exist`;
+            const conditionCheck = {
+                TableName: this.tableMetadata.name,
+                Key: {
+                    [this.partitionKeyAlias]: target.partitionKeyValue(foreignKey),
+                    [this.sortKeyAlias]: target.name
+                },
+                ConditionExpression: `attribute_exists(${this.partitionKeyAlias})`
+            };
+            this.#transactionBuilder.addConditionCheck(conditionCheck, errMsg);
+        }
+    }
     /**
      * Retrieves the DynamoDB items for all entities that the new entity references via "BelongsTo" relationships.
      *

package/dist/src/operations/Update/Update.d.ts

@@ -46,6 +46,12 @@ declare class Update<T extends DynaRecord> extends OperationBase<T> {
      * @returns
      */
     private getBelongsToRelMetaAndKeyForUpdatedKeys;
+    /**
+     * Adds condition checks for standalone foreign keys present in the update payload to ensure the referenced records exist.
+     *
+     * @param attributes - Partial entity attributes supplied to the update call.
+     */
+    private addStandaloneForeignKeyConditionChecks;
     /**
      * Pre-fetches the target entity and any related entities from the database. This is done using a strong read operation to ensure consistency.
      *

package/dist/src/operations/Update/Update.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Update.d.ts","sourceRoot":"","sources":["../../../../src/operations/Update/Update.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,UAAU,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAGL,oBAAoB,EACrB,MAAM,oBAAoB,CAAC;AAkB5B,OAAO,aAAa,MAAM,kBAAkB,CAAC;AAC7C,OAAO,KAAK,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAChE,OAAO,KAAK,EAAmB,WAAW,EAAgB,MAAM,aAAa,CAAC;AA4D9E;;;;;;;;;;;;;;;;;GAiBG;AACH,cAAM,MAAM,CAAC,CAAC,SAAS,UAAU,CAAE,SAAQ,aAAa,CAAC,CAAC,CAAC;IACzD,SAAS,CAAC,QAAQ,CAAC,kBAAkB,EAAE,oBAAoB,CAAC;gBAG1D,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC,EACtB,kBAAkB,CAAC,EAAE,oBAAoB;IAO3C;;;;;;;;;;;;;OAaG;IACU,GAAG,CACd,EAAE,EAAE,MAAM,EACV,UAAU,EAAE,aAAa,CAAC,UAAU,CAAC,GACpC,OAAO,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC;cA4ChB,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC;IAIlD;;;;OAIG;IACH,OAAO,CAAC,uCAAuC;IAY/C;;;;;;;;;;;;;;;OAeG;YACW,QAAQ;IAsDtB;;;;;;OAMG;IACH,OAAO,CAAC,qBAAqB;IA4B7B;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,mBAAmB;IAY3B;;;;;;;;;;OAUG;IACH,OAAO,CAAC,0BAA0B;IAyBlC;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,0BAA0B;IAuDlC;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,iCAAiC;IAuBzC;;;;;;;;;;OAUG;IACH,OAAO,CAAC,8BAA8B;IA+BtC;;;;OAIG;IACH,OAAO,CAAC,0BAA0B;IAkBlC;;;;;OAKG;IACH,OAAO,CAAC,mCAAmC;IAsB3C;;;;;;;;OAQG;IACH,OAAO,CAAC,sCAAsC;IAqC9C;;;;;;;;;;OAUG;IACH,OAAO,CAAC,6BAA6B;IAuCrC;;;;;;;OAOG;IACH,OAAO,CAAC,4BAA4B;IA6BpC;;;;;;;;;;OAUG;IACH,OAAO,CAAC,6BAA6B;IAwBrC;;;;;;OAMG;IACH,OAAO,CAAC,gCAAgC;IAgBxC;;;OAGG;IACH,OAAO,CAAC,iCAAiC;CAU1C;AAED,eAAe,MAAM,CAAC"}
+{"version":3,"file":"Update.d.ts","sourceRoot":"","sources":["../../../../src/operations/Update/Update.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,UAAU,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAGL,oBAAoB,EACrB,MAAM,oBAAoB,CAAC;AAmB5B,OAAO,aAAa,MAAM,kBAAkB,CAAC;AAC7C,OAAO,KAAK,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAChE,OAAO,KAAK,EAAmB,WAAW,EAAgB,MAAM,aAAa,CAAC;AA4D9E;;;;;;;;;;;;;;;;;GAiBG;AACH,cAAM,MAAM,CAAC,CAAC,SAAS,UAAU,CAAE,SAAQ,aAAa,CAAC,CAAC,CAAC;IACzD,SAAS,CAAC,QAAQ,CAAC,kBAAkB,EAAE,oBAAoB,CAAC;gBAG1D,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC,EACtB,kBAAkB,CAAC,EAAE,oBAAoB;IAO3C;;;;;;;;;;;;;OAaG;IACU,GAAG,CACd,EAAE,EAAE,MAAM,EACV,UAAU,EAAE,aAAa,CAAC,UAAU,CAAC,GACpC,OAAO,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC;cA6ChB,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC;IAIlD;;;;OAIG;IACH,OAAO,CAAC,uCAAuC;IAY/C;;;;OAIG;IACH,OAAO,CAAC,sCAAsC;IAgC9C;;;;;;;;;;;;;;;OAeG;YACW,QAAQ;IAsDtB;;;;;;OAMG;IACH,OAAO,CAAC,qBAAqB;IA4B7B;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,mBAAmB;IAY3B;;;;;;;;;;OAUG;IACH,OAAO,CAAC,0BAA0B;IAyBlC;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,0BAA0B;IAuDlC;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,iCAAiC;IAuBzC;;;;;;;;;;OAUG;IACH,OAAO,CAAC,8BAA8B;IA+BtC;;;;OAIG;IACH,OAAO,CAAC,0BAA0B;IAkBlC;;;;;OAKG;IACH,OAAO,CAAC,mCAAmC;IAsB3C;;;;;;;;OAQG;IACH,OAAO,CAAC,sCAAsC;IAqC9C;;;;;;;;;;OAUG;IACH,OAAO,CAAC,6BAA6B;IAuCrC;;;;;;;OAOG;IACH,OAAO,CAAC,4BAA4B;IA6BpC;;;;;;;;;;OAUG;IACH,OAAO,CAAC,6BAA6B;IAwBrC;;;;;;OAMG;IACH,OAAO,CAAC,gCAAgC;IAgBxC;;;OAGG;IACH,OAAO,CAAC,iCAAiC;CAU1C;AAED,eAAe,MAAM,CAAC"}

package/dist/src/operations/Update/Update.js

@@ -54,6 +54,7 @@ class Update extends OperationBase_1.default {
         const entityAttrs = entityMeta.parseRawEntityDefinedAttributesPartial(attributes);
         const { updatedAttrs, expression } = this.buildUpdateMetadata(entityAttrs);
         this.buildUpdateItemTransaction(id, expression);
+        this.addStandaloneForeignKeyConditionChecks(entityAttrs);
         // Only need to prefetch if the entity has relationships
         if (entityMeta.allRelationships.length > 0) {
             const belongsToRelMetaBeingUpdated = this.getBelongsToRelMetaAndKeyForUpdatedKeys(entityAttrs);
@@ -86,6 +87,33 @@ class Update extends OperationBase_1.default {
             return acc;
         }, []);
     }
+    /**
+     * Adds condition checks for standalone foreign keys present in the update payload to ensure the referenced records exist.
+     *
+     * @param attributes - Partial entity attributes supplied to the update call.
+     */
+    addStandaloneForeignKeyConditionChecks(attributes) {
+        const standaloneForeignKeys = this.entityMetadata.standaloneForeignKeyAttributes;
+        for (const attrMeta of standaloneForeignKeys) {
+            const target = attrMeta.foreignKeyTarget;
+            if (!(0, utils_1.isKeyOfObject)(attributes, attrMeta.name))
+                continue;
+            const foreignKeyValue = attributes[attrMeta.name];
+            if (!(0, utils_1.isString)(foreignKeyValue))
+                continue;
+            const foreignKey = foreignKeyValue;
+            const errMsg = `${target.name} with ID '${foreignKey}' does not exist`;
+            const conditionCheck = {
+                TableName: this.tableMetadata.name,
+                Key: {
+                    [this.partitionKeyAlias]: target.partitionKeyValue(foreignKey),
+                    [this.sortKeyAlias]: target.name
+                },
+                ConditionExpression: `attribute_exists(${this.partitionKeyAlias})`
+            };
+            this.transactionBuilder.addConditionCheck(conditionCheck, errMsg);
+        }
+    }
     /**
      * Pre-fetches the target entity and any related entities from the database. This is done using a strong read operation to ensure consistency.
      *

package/dist/src/types.d.ts

@@ -16,13 +16,23 @@ export type SortKey = Brand<string, "SortKey">;
  */
 export type PartitionKey = Brand<string, "PartitionKey">;
 /**
- * A branded string type to represent foreign keys in DynamoDB tables
+ * A branded string type to represent foreign keys in DynamoDB tables.
+ *
+ * @typeParam T - The entity that the foreign key references. Defaults to {@link DynaRecord}.
  */
-export type ForeignKey = Brand<string, "ForeignKey">;
+export type ForeignKey<T extends DynaRecord = DynaRecord> = Brand<string, {
+    kind: "ForeignKey";
+    entity: T;
+}>;
 /**
  * A branded string type to represent nullable foreign keys in DynamoDB tables, which can also be undefined.
+ *
+ * @typeParam T - The entity that the foreign key references. Defaults to {@link DynaRecord}.
  */
-export type NullableForeignKey = Optional<Brand<string, "NullableForeignKey">>;
+export type NullableForeignKey<T extends DynaRecord = DynaRecord> = Optional<Brand<string, {
+    kind: "NullableForeignKey";
+    entity: T;
+}>>;
 /**
  * Represents a foreign key property on an entity within a DynaRecord model
  */

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

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,0BAA0B,EAAE,MAAM,wBAAwB,CAAC;AACzE,OAAO,KAAK,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAC9E,OAAO,KAAK,UAAU,MAAM,cAAc,CAAC;AAE3C;;GAEG;AACH,MAAM,MAAM,KAAK,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,GAAG;IAAE,OAAO,EAAE,CAAC,CAAA;CAAE,CAAC;AAE7C;;GAEG;AACH,MAAM,MAAM,OAAO,GAAG,KAAK,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;AAE/C;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,KAAK,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;AAEzD;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,KAAK,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;AAErD;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG,QAAQ,CAAC,KAAK,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC,CAAC;AAE/E;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG,MAAM,UAAU,GAAG,UAAU,CAAC;AAE/D;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,0BAA0B,CAAC,CAAC;AAEzE;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAE/C;;GAEG;AACH,MAAM,MAAM,QAAQ,CAAC,CAAC,IAAI,CAAC,GAAG,SAAS,CAAC;AAExC;;GAEG;AACH,MAAM,MAAM,QAAQ,CAAC,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;AAEnC;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC;AAEtE;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,eAAe,EAAE,kBAAkB,CAAC;IACpC,sBAAsB,EAAE,qBAAqB,EAAE,CAAC;CACjD;AAED;;GAEG;AACH,MAAM,MAAM,YAAY,CAAC,CAAC,EAAE,CAAC,SAAS,MAAM,CAAC,IAAI,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,GACzD,OAAO,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;AAEtB;;GAEG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,GAAG,OAAO,UAAU,CAAC;AAE/D;;GAEG;AACH,MAAM,MAAM,YAAY,CAAC,CAAC,EAAE,CAAC,SAAS,MAAM,CAAC,IAAI,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG;KAC3D,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;CACjB,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,0BAA0B,EAAE,MAAM,wBAAwB,CAAC;AACzE,OAAO,KAAK,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAC9E,OAAO,KAAK,UAAU,MAAM,cAAc,CAAC;AAE3C;;GAEG;AACH,MAAM,MAAM,KAAK,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,GAAG;IAAE,OAAO,EAAE,CAAC,CAAA;CAAE,CAAC;AAE7C;;GAEG;AACH,MAAM,MAAM,OAAO,GAAG,KAAK,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;AAE/C;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,KAAK,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;AAEzD;;;;GAIG;AACH,MAAM,MAAM,UAAU,CAAC,CAAC,SAAS,UAAU,GAAG,UAAU,IAAI,KAAK,CAC/D,MAAM,EACN;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,MAAM,EAAE,CAAC,CAAA;CAAE,CAClC,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,CAAC,CAAC,SAAS,UAAU,GAAG,UAAU,IAAI,QAAQ,CAC1E,KAAK,CAAC,MAAM,EAAE;IAAE,IAAI,EAAE,oBAAoB,CAAC;IAAC,MAAM,EAAE,CAAC,CAAA;CAAE,CAAC,CACzD,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG,MAAM,UAAU,GAAG,UAAU,CAAC;AAE/D;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,0BAA0B,CAAC,CAAC;AAEzE;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAE/C;;GAEG;AACH,MAAM,MAAM,QAAQ,CAAC,CAAC,IAAI,CAAC,GAAG,SAAS,CAAC;AAExC;;GAEG;AACH,MAAM,MAAM,QAAQ,CAAC,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;AAEnC;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC;AAEtE;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,eAAe,EAAE,kBAAkB,CAAC;IACpC,sBAAsB,EAAE,qBAAqB,EAAE,CAAC;CACjD;AAED;;GAEG;AACH,MAAM,MAAM,YAAY,CAAC,CAAC,EAAE,CAAC,SAAS,MAAM,CAAC,IAAI,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,GACzD,OAAO,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;AAEtB;;GAEG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,GAAG,OAAO,UAAU,CAAC;AAE/D;;GAEG;AACH,MAAM,MAAM,YAAY,CAAC,CAAC,EAAE,CAAC,SAAS,MAAM,CAAC,IAAI,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG;KAC3D,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;CACjB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dyna-record",
-  "version": "0.3.6",
+  "version": "0.4.0",
   "description": "Typescript Data Modeler and ORM for Dynamo",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",