dyna-record 0.4.0 → 0.4.6

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

@@ -0,0 +1,432 @@
+import { z } from "zod";
+import type { EntityClass } from "../types";
+import type DynaRecord from "../DynaRecord";
+/**
+ * Zod schema that transforms table metadata to a serializable format.
+ * This is the main schema used to serialize {@link TableMetadata} instances,
+ * extracting only serializable values and converting EntityClass references to strings.
+ *
+ * @property {string} name - The name of the table
+ * @property {string} delimiter - The delimiter used in the table's composite keys (defaults to "#")
+ * @property {Record<string, AttributeMetadataTransform>} defaultAttributes - Default attributes for the entity, keyed by entity field names
+ * @property {Record<string, AttributeMetadataTransform>} defaultTableAttributes - Default attributes for the table, keyed by table field aliases
+ * @property {AttributeMetadataTransform} partitionKeyAttribute - Metadata for the table's partition key attribute
+ * @property {AttributeMetadataTransform} sortKeyAttribute - Metadata for the table's sort key attribute
+ * @property {Record<string, EntityMetadataTransform>} entities - Entities mapped to the table, keyed by entity class name
+ *
+ * @returns A serialized table metadata object containing only serializable values
+ *
+ * @example
+ * ```typescript
+ * const metadata = TableMetadataTransform.parse(tableMetadataInstance);
+ * // Returns a plain object with all EntityClass references converted to strings
+ * ```
+ */
+export declare const TableMetadataTransform: z.ZodObject<{
+    name: z.ZodString;
+    delimiter: z.ZodString;
+    defaultAttributes: z.ZodRecord<z.ZodString, z.ZodEffects<z.ZodObject<{
+        name: z.ZodString;
+        alias: z.ZodString;
+        nullable: z.ZodBoolean;
+        foreignKeyTarget: z.ZodOptional<z.ZodType<EntityClass<DynaRecord>, z.ZodTypeDef, EntityClass<DynaRecord>>>;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        nullable: boolean;
+        alias: string;
+        foreignKeyTarget?: EntityClass<DynaRecord> | undefined;
+    }, {
+        name: string;
+        nullable: boolean;
+        alias: string;
+        foreignKeyTarget?: EntityClass<DynaRecord> | undefined;
+    }>, {
+        foreignKeyTarget?: string | undefined;
+        name: string;
+        alias: string;
+        nullable: boolean;
+    }, {
+        name: string;
+        nullable: boolean;
+        alias: string;
+        foreignKeyTarget?: EntityClass<DynaRecord> | undefined;
+    }>>;
+    defaultTableAttributes: z.ZodRecord<z.ZodString, z.ZodEffects<z.ZodObject<{
+        name: z.ZodString;
+        alias: z.ZodString;
+        nullable: z.ZodBoolean;
+        foreignKeyTarget: z.ZodOptional<z.ZodType<EntityClass<DynaRecord>, z.ZodTypeDef, EntityClass<DynaRecord>>>;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        nullable: boolean;
+        alias: string;
+        foreignKeyTarget?: EntityClass<DynaRecord> | undefined;
+    }, {
+        name: string;
+        nullable: boolean;
+        alias: string;
+        foreignKeyTarget?: EntityClass<DynaRecord> | undefined;
+    }>, {
+        foreignKeyTarget?: string | undefined;
+        name: string;
+        alias: string;
+        nullable: boolean;
+    }, {
+        name: string;
+        nullable: boolean;
+        alias: string;
+        foreignKeyTarget?: EntityClass<DynaRecord> | undefined;
+    }>>;
+    partitionKeyAttribute: z.ZodEffects<z.ZodObject<{
+        name: z.ZodString;
+        alias: z.ZodString;
+        nullable: z.ZodBoolean;
+        foreignKeyTarget: z.ZodOptional<z.ZodType<EntityClass<DynaRecord>, z.ZodTypeDef, EntityClass<DynaRecord>>>;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        nullable: boolean;
+        alias: string;
+        foreignKeyTarget?: EntityClass<DynaRecord> | undefined;
+    }, {
+        name: string;
+        nullable: boolean;
+        alias: string;
+        foreignKeyTarget?: EntityClass<DynaRecord> | undefined;
+    }>, {
+        foreignKeyTarget?: string | undefined;
+        name: string;
+        alias: string;
+        nullable: boolean;
+    }, {
+        name: string;
+        nullable: boolean;
+        alias: string;
+        foreignKeyTarget?: EntityClass<DynaRecord> | undefined;
+    }>;
+    sortKeyAttribute: z.ZodEffects<z.ZodObject<{
+        name: z.ZodString;
+        alias: z.ZodString;
+        nullable: z.ZodBoolean;
+        foreignKeyTarget: z.ZodOptional<z.ZodType<EntityClass<DynaRecord>, z.ZodTypeDef, EntityClass<DynaRecord>>>;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        nullable: boolean;
+        alias: string;
+        foreignKeyTarget?: EntityClass<DynaRecord> | undefined;
+    }, {
+        name: string;
+        nullable: boolean;
+        alias: string;
+        foreignKeyTarget?: EntityClass<DynaRecord> | undefined;
+    }>, {
+        foreignKeyTarget?: string | undefined;
+        name: string;
+        alias: string;
+        nullable: boolean;
+    }, {
+        name: string;
+        nullable: boolean;
+        alias: string;
+        foreignKeyTarget?: EntityClass<DynaRecord> | undefined;
+    }>;
+    entities: z.ZodRecord<z.ZodString, z.ZodEffects<z.ZodObject<{
+        tableClassName: z.ZodString;
+        attributes: z.ZodRecord<z.ZodString, z.ZodEffects<z.ZodObject<{
+            name: z.ZodString;
+            alias: z.ZodString;
+            nullable: z.ZodBoolean;
+            foreignKeyTarget: z.ZodOptional<z.ZodType<EntityClass<DynaRecord>, z.ZodTypeDef, EntityClass<DynaRecord>>>;
+        }, "strip", z.ZodTypeAny, {
+            name: string;
+            nullable: boolean;
+            alias: string;
+            foreignKeyTarget?: EntityClass<DynaRecord> | undefined;
+        }, {
+            name: string;
+            nullable: boolean;
+            alias: string;
+            foreignKeyTarget?: EntityClass<DynaRecord> | undefined;
+        }>, {
+            foreignKeyTarget?: string | undefined;
+            name: string;
+            alias: string;
+            nullable: boolean;
+        }, {
+            name: string;
+            nullable: boolean;
+            alias: string;
+            foreignKeyTarget?: EntityClass<DynaRecord> | undefined;
+        }>>;
+        tableAttributes: z.ZodRecord<z.ZodString, z.ZodEffects<z.ZodObject<{
+            name: z.ZodString;
+            alias: z.ZodString;
+            nullable: z.ZodBoolean;
+            foreignKeyTarget: z.ZodOptional<z.ZodType<EntityClass<DynaRecord>, z.ZodTypeDef, EntityClass<DynaRecord>>>;
+        }, "strip", z.ZodTypeAny, {
+            name: string;
+            nullable: boolean;
+            alias: string;
+            foreignKeyTarget?: EntityClass<DynaRecord> | undefined;
+        }, {
+            name: string;
+            nullable: boolean;
+            alias: string;
+            foreignKeyTarget?: EntityClass<DynaRecord> | undefined;
+        }>, {
+            foreignKeyTarget?: string | undefined;
+            name: string;
+            alias: string;
+            nullable: boolean;
+        }, {
+            name: string;
+            nullable: boolean;
+            alias: string;
+            foreignKeyTarget?: EntityClass<DynaRecord> | undefined;
+        }>>;
+        relationships: z.ZodRecord<z.ZodString, z.ZodEffects<z.ZodObject<{
+            type: z.ZodString;
+            propertyName: z.ZodString;
+            target: z.ZodOptional<z.ZodType<EntityClass<DynaRecord>, z.ZodTypeDef, EntityClass<DynaRecord>>>;
+            foreignKey: z.ZodOptional<z.ZodString>;
+            joinTableName: z.ZodOptional<z.ZodString>;
+            uniDirectional: z.ZodOptional<z.ZodBoolean>;
+        }, "strip", z.ZodTypeAny, {
+            type: string;
+            propertyName: string;
+            foreignKey?: string | undefined;
+            uniDirectional?: boolean | undefined;
+            joinTableName?: string | undefined;
+            target?: EntityClass<DynaRecord> | undefined;
+        }, {
+            type: string;
+            propertyName: string;
+            foreignKey?: string | undefined;
+            uniDirectional?: boolean | undefined;
+            joinTableName?: string | undefined;
+            target?: EntityClass<DynaRecord> | undefined;
+        }>, {
+            uniDirectional?: boolean | undefined;
+            joinTableName?: string | undefined;
+            foreignKey?: string | undefined;
+            target?: string | undefined;
+            type: string;
+            propertyName: string;
+        }, {
+            type: string;
+            propertyName: string;
+            foreignKey?: string | undefined;
+            uniDirectional?: boolean | undefined;
+            joinTableName?: string | undefined;
+            target?: EntityClass<DynaRecord> | undefined;
+        }>>;
+        idField: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        tableClassName: string;
+        attributes: Record<string, {
+            foreignKeyTarget?: string | undefined;
+            name: string;
+            alias: string;
+            nullable: boolean;
+        }>;
+        tableAttributes: Record<string, {
+            foreignKeyTarget?: string | undefined;
+            name: string;
+            alias: string;
+            nullable: boolean;
+        }>;
+        relationships: Record<string, {
+            uniDirectional?: boolean | undefined;
+            joinTableName?: string | undefined;
+            foreignKey?: string | undefined;
+            target?: string | undefined;
+            type: string;
+            propertyName: string;
+        }>;
+        idField?: string | undefined;
+    }, {
+        tableClassName: string;
+        attributes: Record<string, {
+            name: string;
+            nullable: boolean;
+            alias: string;
+            foreignKeyTarget?: EntityClass<DynaRecord> | undefined;
+        }>;
+        tableAttributes: Record<string, {
+            name: string;
+            nullable: boolean;
+            alias: string;
+            foreignKeyTarget?: EntityClass<DynaRecord> | undefined;
+        }>;
+        relationships: Record<string, {
+            type: string;
+            propertyName: string;
+            foreignKey?: string | undefined;
+            uniDirectional?: boolean | undefined;
+            joinTableName?: string | undefined;
+            target?: EntityClass<DynaRecord> | undefined;
+        }>;
+        idField?: string | undefined;
+    }>, {
+        idField?: string | undefined;
+        tableClassName: string;
+        attributes: Record<string, {
+            foreignKeyTarget?: string | undefined;
+            name: string;
+            alias: string;
+            nullable: boolean;
+        }>;
+        tableAttributes: Record<string, {
+            foreignKeyTarget?: string | undefined;
+            name: string;
+            alias: string;
+            nullable: boolean;
+        }>;
+        relationships: Record<string, {
+            uniDirectional?: boolean | undefined;
+            joinTableName?: string | undefined;
+            foreignKey?: string | undefined;
+            target?: string | undefined;
+            type: string;
+            propertyName: string;
+        }>;
+    }, {
+        tableClassName: string;
+        attributes: Record<string, {
+            name: string;
+            nullable: boolean;
+            alias: string;
+            foreignKeyTarget?: EntityClass<DynaRecord> | undefined;
+        }>;
+        tableAttributes: Record<string, {
+            name: string;
+            nullable: boolean;
+            alias: string;
+            foreignKeyTarget?: EntityClass<DynaRecord> | undefined;
+        }>;
+        relationships: Record<string, {
+            type: string;
+            propertyName: string;
+            foreignKey?: string | undefined;
+            uniDirectional?: boolean | undefined;
+            joinTableName?: string | undefined;
+            target?: EntityClass<DynaRecord> | undefined;
+        }>;
+        idField?: string | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    delimiter: string;
+    defaultAttributes: Record<string, {
+        foreignKeyTarget?: string | undefined;
+        name: string;
+        alias: string;
+        nullable: boolean;
+    }>;
+    defaultTableAttributes: Record<string, {
+        foreignKeyTarget?: string | undefined;
+        name: string;
+        alias: string;
+        nullable: boolean;
+    }>;
+    partitionKeyAttribute: {
+        foreignKeyTarget?: string | undefined;
+        name: string;
+        alias: string;
+        nullable: boolean;
+    };
+    sortKeyAttribute: {
+        foreignKeyTarget?: string | undefined;
+        name: string;
+        alias: string;
+        nullable: boolean;
+    };
+    entities: Record<string, {
+        idField?: string | undefined;
+        tableClassName: string;
+        attributes: Record<string, {
+            foreignKeyTarget?: string | undefined;
+            name: string;
+            alias: string;
+            nullable: boolean;
+        }>;
+        tableAttributes: Record<string, {
+            foreignKeyTarget?: string | undefined;
+            name: string;
+            alias: string;
+            nullable: boolean;
+        }>;
+        relationships: Record<string, {
+            uniDirectional?: boolean | undefined;
+            joinTableName?: string | undefined;
+            foreignKey?: string | undefined;
+            target?: string | undefined;
+            type: string;
+            propertyName: string;
+        }>;
+    }>;
+}, {
+    name: string;
+    delimiter: string;
+    defaultAttributes: Record<string, {
+        name: string;
+        nullable: boolean;
+        alias: string;
+        foreignKeyTarget?: EntityClass<DynaRecord> | undefined;
+    }>;
+    defaultTableAttributes: Record<string, {
+        name: string;
+        nullable: boolean;
+        alias: string;
+        foreignKeyTarget?: EntityClass<DynaRecord> | undefined;
+    }>;
+    partitionKeyAttribute: {
+        name: string;
+        nullable: boolean;
+        alias: string;
+        foreignKeyTarget?: EntityClass<DynaRecord> | undefined;
+    };
+    sortKeyAttribute: {
+        name: string;
+        nullable: boolean;
+        alias: string;
+        foreignKeyTarget?: EntityClass<DynaRecord> | undefined;
+    };
+    entities: Record<string, {
+        tableClassName: string;
+        attributes: Record<string, {
+            name: string;
+            nullable: boolean;
+            alias: string;
+            foreignKeyTarget?: EntityClass<DynaRecord> | undefined;
+        }>;
+        tableAttributes: Record<string, {
+            name: string;
+            nullable: boolean;
+            alias: string;
+            foreignKeyTarget?: EntityClass<DynaRecord> | undefined;
+        }>;
+        relationships: Record<string, {
+            type: string;
+            propertyName: string;
+            foreignKey?: string | undefined;
+            uniDirectional?: boolean | undefined;
+            joinTableName?: string | undefined;
+            target?: EntityClass<DynaRecord> | undefined;
+        }>;
+        idField?: string | undefined;
+    }>;
+}>;
+/**
+ * Type representing the serialized output of table metadata.
+ * This type is inferred from the {@link TableMetadataTransform} schema and represents
+ * the structure of metadata after serialization, with all EntityClass references
+ * converted to strings and all non-serializable data (functions, Zod types, serializers) removed.
+ *
+ * @example
+ * ```typescript
+ * const metadata: SerializedTableMetadata = User.metadata();
+ * // metadata is a plain object with readonly properties
+ * ```
+ */
+export type SerializedTableMetadata = z.output<typeof TableMetadataTransform>;
+//# sourceMappingURL=schemas.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../../../src/metadata/schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAC5C,OAAO,KAAK,UAAU,MAAM,eAAe,CAAC;AA4F5C;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAQjC,CAAC;AAEH;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,sBAAsB,CAAC,CAAC"}

package/dist/src/metadata/schemas.js

@@ -0,0 +1,121 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TableMetadataTransform = void 0;
+const zod_1 = require("zod");
+/**
+ * Zod schema that transforms attribute metadata to a serializable format.
+ * Extracts only serializable properties (name, alias, nullable) and converts
+ * the foreignKeyTarget EntityClass reference to its class name string.
+ *
+ * @property {string} name - The name of the attribute as defined on the entity
+ * @property {string} alias - The alias of the attribute as defined in the database table
+ * @property {boolean} nullable - Indicates whether the attribute can be null
+ * @property {EntityClass<DynaRecord>} [foreignKeyTarget] - Optional entity class reference that will be converted to its name string
+ *
+ * @returns A serialized attribute metadata object with foreignKeyTarget as a string (class name) if present
+ */
+const AttributeMetadataTransform = zod_1.z
+    .object({
+    name: zod_1.z.string(),
+    alias: zod_1.z.string(),
+    nullable: zod_1.z.boolean(),
+    foreignKeyTarget: zod_1.z.custom().optional()
+})
+    .transform(attr => ({
+    name: attr.name,
+    alias: attr.alias,
+    nullable: attr.nullable,
+    ...(attr.foreignKeyTarget != null && {
+        foreignKeyTarget: attr.foreignKeyTarget.name
+    })
+}));
+/**
+ * Zod schema that transforms relationship metadata to a serializable format.
+ * Extracts serializable properties and converts EntityClass references to their class name strings.
+ *
+ * @property {string} type - The type of the relationship (e.g., "HasMany", "BelongsTo", "HasOne", "HasAndBelongsToMany", "OwnedBy")
+ * @property {string} propertyName - The property name on the source entity that holds the relationship
+ * @property {EntityClass<DynaRecord>} [target] - Optional target entity class reference that will be converted to its name string
+ * @property {string} [foreignKey] - Optional foreign key property name
+ * @property {string} [joinTableName] - Optional join table name for many-to-many relationships
+ * @property {boolean} [uniDirectional] - Optional flag indicating if the relationship is unidirectional
+ *
+ * @returns A serialized relationship metadata object with EntityClass references converted to strings
+ */
+const RelationshipMetadataTransform = zod_1.z
+    .object({
+    type: zod_1.z.string(),
+    propertyName: zod_1.z.string(),
+    target: zod_1.z.custom().optional(),
+    foreignKey: zod_1.z.string().optional(),
+    joinTableName: zod_1.z.string().optional(),
+    uniDirectional: zod_1.z.boolean().optional()
+})
+    .transform(rel => ({
+    type: rel.type,
+    propertyName: rel.propertyName,
+    ...(rel.target != null && { target: rel.target.name }),
+    ...(rel.foreignKey != null && { foreignKey: rel.foreignKey }),
+    ...(rel.joinTableName != null && { joinTableName: rel.joinTableName }),
+    ...(rel.uniDirectional !== undefined && {
+        uniDirectional: rel.uniDirectional
+    })
+}));
+/**
+ * Zod schema that transforms entity metadata to a serializable format.
+ * Extracts serializable properties and includes nested attribute and relationship metadata.
+ *
+ * @property {string} tableClassName - The name of the table class instance to which this entity belongs
+ * @property {Record<string, AttributeMetadataTransform>} attributes - Attribute metadata keyed by entity field names
+ * @property {Record<string, AttributeMetadataTransform>} tableAttributes - Attribute metadata keyed by table column names (aliases)
+ * @property {Record<string, RelationshipMetadataTransform>} relationships - Relationship metadata keyed by entity property names
+ * @property {string} [idField] - Optional custom id field name (used with @IdAttribute decorator)
+ *
+ * @returns A serialized entity metadata object with all nested metadata transformed
+ */
+const EntityMetadataTransform = zod_1.z
+    .object({
+    tableClassName: zod_1.z.string(),
+    attributes: zod_1.z.record(AttributeMetadataTransform),
+    tableAttributes: zod_1.z.record(AttributeMetadataTransform),
+    relationships: zod_1.z.record(RelationshipMetadataTransform),
+    idField: zod_1.z.string().optional()
+})
+    .transform(entity => ({
+    tableClassName: entity.tableClassName,
+    attributes: entity.attributes,
+    tableAttributes: entity.tableAttributes,
+    relationships: entity.relationships,
+    ...(entity.idField !== undefined &&
+        entity.idField !== "" && { idField: entity.idField })
+}));
+/**
+ * Zod schema that transforms table metadata to a serializable format.
+ * This is the main schema used to serialize {@link TableMetadata} instances,
+ * extracting only serializable values and converting EntityClass references to strings.
+ *
+ * @property {string} name - The name of the table
+ * @property {string} delimiter - The delimiter used in the table's composite keys (defaults to "#")
+ * @property {Record<string, AttributeMetadataTransform>} defaultAttributes - Default attributes for the entity, keyed by entity field names
+ * @property {Record<string, AttributeMetadataTransform>} defaultTableAttributes - Default attributes for the table, keyed by table field aliases
+ * @property {AttributeMetadataTransform} partitionKeyAttribute - Metadata for the table's partition key attribute
+ * @property {AttributeMetadataTransform} sortKeyAttribute - Metadata for the table's sort key attribute
+ * @property {Record<string, EntityMetadataTransform>} entities - Entities mapped to the table, keyed by entity class name
+ *
+ * @returns A serialized table metadata object containing only serializable values
+ *
+ * @example
+ * ```typescript
+ * const metadata = TableMetadataTransform.parse(tableMetadataInstance);
+ * // Returns a plain object with all EntityClass references converted to strings
+ * ```
+ */
+exports.TableMetadataTransform = zod_1.z.object({
+    name: zod_1.z.string(),
+    delimiter: zod_1.z.string(),
+    defaultAttributes: zod_1.z.record(AttributeMetadataTransform),
+    defaultTableAttributes: zod_1.z.record(AttributeMetadataTransform),
+    partitionKeyAttribute: AttributeMetadataTransform,
+    sortKeyAttribute: AttributeMetadataTransform,
+    entities: zod_1.z.record(EntityMetadataTransform)
+});

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

@@ -1,7 +1,7 @@
 import type DynaRecord from "../../DynaRecord";
 import type { EntityClass } from "../../types";
 import OperationBase from "../OperationBase";
-import type { CreateOptions } from "./types";
+import type { CreateOptions, CreateOperationOptions } from "./types";
 import { type EntityAttributesOnly } from "../types";
 /**
  * Represents an operation to create a new entity record in DynamoDB, including all necessary
@@ -37,11 +37,12 @@ declare class Create<T extends DynaRecord> extends OperationBase<T> {
      *   partition (due to "BelongsTo" links), retrieves and inserts those link records.
      *
      * @param attributes - Attributes to initialize the new entity. Must be defined on the model and valid per schema constraints.
+     * @param options - Optional operation options including referentialIntegrityCheck flag.
      * @returns A promise that resolves to the newly created entity with all attributes, including automatically set fields.
      * @throws If the entity already exists, a uniqueness violation error is raised.
-     * @throws If a required foreign key does not correspond to an existing entity, an error is raised.
+     * @throws If a required foreign key does not correspond to an existing entity, an error is raised (unless referentialIntegrityCheck is false).
      */
-    run(attributes: CreateOptions<T>): Promise<EntityAttributesOnly<T>>;
+    run(attributes: CreateOptions<T>, options?: CreateOperationOptions): Promise<EntityAttributesOnly<T>>;
     /**
      * Builds and returns entity attributes that must be reserved for system usage.
      *
@@ -75,6 +76,7 @@ declare class Create<T extends DynaRecord> extends OperationBase<T> {
      *
      * @param entityData - The complete set of entity attributes for the new entity.
      * @param tableItem - The main entity's DynamoDB table item.
+     * @param referentialIntegrityCheck - Whether to perform referential integrity checks.
      * @private
      */
     private buildBelongsToTransactions;
@@ -83,6 +85,8 @@ declare class Create<T extends DynaRecord> extends OperationBase<T> {
      * Ensures referenced entities exist even when denormalised access patterns are not defined.
      *
      * @param entityData - Attributes being persisted for the new entity.
+     * @param referentialIntegrityCheck - Whether to perform referential integrity checks.
+     * @private
      */
     private buildStandaloneForeignKeyConditionChecks;
     /**

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;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"}
+{"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,sBAAsB,EAAE,MAAM,SAAS,CAAC;AACrE,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;;;;;;;;;;;;;;;;;OAiBG;IACU,GAAG,CACd,UAAU,EAAE,aAAa,CAAC,CAAC,CAAC,EAC5B,OAAO,CAAC,EAAE,sBAAsB,GAC/B,OAAO,CAAC,oBAAoB,CAAC,CAAC,CAAC,CAAC;IAuCnC;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,uBAAuB;IA8B/B;;;;;;;;;OASG;IACH,OAAO,CAAC,uBAAuB;IAiB/B;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,0BAA0B;IAqClC;;;;;;;OAOG;IACH,OAAO,CAAC,wCAAwC;IAkChD;;;;;;;;;;;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

@@ -46,18 +46,20 @@ class Create extends OperationBase_1.default {
      *   partition (due to "BelongsTo" links), retrieves and inserts those link records.
      *
      * @param attributes - Attributes to initialize the new entity. Must be defined on the model and valid per schema constraints.
+     * @param options - Optional operation options including referentialIntegrityCheck flag.
      * @returns A promise that resolves to the newly created entity with all attributes, including automatically set fields.
      * @throws If the entity already exists, a uniqueness violation error is raised.
-     * @throws If a required foreign key does not correspond to an existing entity, an error is raised.
+     * @throws If a required foreign key does not correspond to an existing entity, an error is raised (unless referentialIntegrityCheck is false).
      */
-    async run(attributes) {
+    async run(attributes, options) {
+        const referentialIntegrityCheck = options?.referentialIntegrityCheck ?? true;
         const entityAttrs = this.entityMetadata.parseRawEntityDefinedAttributes(attributes);
         const reservedAttrs = this.buildReservedAttributes(entityAttrs);
         const entityData = { ...reservedAttrs, ...entityAttrs };
         const tableItem = (0, utils_1.entityToTableItem)(this.EntityClass, entityData);
         this.buildPutItemTransaction(tableItem, entityData.id);
-        this.buildBelongsToTransactions(entityData, tableItem);
-        this.buildStandaloneForeignKeyConditionChecks(entityData);
+        this.buildBelongsToTransactions(entityData, tableItem, referentialIntegrityCheck);
+        this.buildStandaloneForeignKeyConditionChecks(entityData, referentialIntegrityCheck);
         // 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
@@ -127,16 +129,19 @@ class Create extends OperationBase_1.default {
      *
      * @param entityData - The complete set of entity attributes for the new entity.
      * @param tableItem - The main entity's DynamoDB table item.
+     * @param referentialIntegrityCheck - Whether to perform referential integrity checks.
      * @private
      */
-    buildBelongsToTransactions(entityData, tableItem) {
+    buildBelongsToTransactions(entityData, tableItem, referentialIntegrityCheck) {
         const tableName = this.tableMetadata.name;
         const relMetadata = this.entityMetadata.belongsToOrOwnedByRelationships;
         for (const relMeta of relMetadata) {
             const foreignKey = (0, utils_2.extractForeignKeyFromEntity)(relMeta, entityData);
             if (foreignKey !== undefined) {
                 // Ensure referenced entity exists before linking
-                this.buildRelationshipExistsConditionTransaction(relMeta, foreignKey);
+                if (referentialIntegrityCheck) {
+                    this.buildRelationshipExistsConditionTransaction(relMeta, foreignKey);
+                }
                 const key = (0, utils_2.buildBelongsToLinkKey)(this.EntityClass, entityData.id, relMeta, foreignKey);
                 this.#transactionBuilder.addPut({
                     TableName: tableName,
@@ -151,8 +156,13 @@ class Create extends OperationBase_1.default {
      * Ensures referenced entities exist even when denormalised access patterns are not defined.
      *
      * @param entityData - Attributes being persisted for the new entity.
+     * @param referentialIntegrityCheck - Whether to perform referential integrity checks.
+     * @private
      */
-    buildStandaloneForeignKeyConditionChecks(entityData) {
+    buildStandaloneForeignKeyConditionChecks(entityData, referentialIntegrityCheck) {
+        if (!referentialIntegrityCheck) {
+            return;
+        }
         const standaloneForeignKeys = this.entityMetadata.standaloneForeignKeyAttributes;
         for (const attrMeta of standaloneForeignKeys) {
             const target = attrMeta.foreignKeyTarget;

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

@@ -1,5 +1,17 @@
 import type DynaRecord from "../../DynaRecord";
 import type { EntityDefinedAttributes } from "../types";
+/**
+ * Options for create operations
+ */
+export interface CreateOperationOptions {
+    /**
+     * Whether to perform referential integrity checks for foreign key references.
+     * When `true` (default), condition checks are added to verify that referenced entities exist.
+     * When `false`, these condition checks are skipped, allowing creation even if foreign key references don't exist.
+     * @default true
+     */
+    referentialIntegrityCheck?: boolean;
+}
 /**
  * Entity attribute fields that can be set on create. Excludes that are managed by dyna-record
  */