dyna-record 0.0.1

package/dist/src/query-utils/types.d.ts

@@ -0,0 +1,89 @@
+import { type QueryCommandInput } from "@aws-sdk/lib-dynamodb";
+import { type NativeScalarAttributeValue } from "@aws-sdk/util-dynamodb";
+/**
+ * Represents conditions used to specify the partition key and sort key (if applicable) for querying items in DynamoDB.
+ *
+ * @type {KeyConditions} - Derived from the `KeyConditions` part of the `QueryCommandInput` from AWS SDK, excluding the "undefined" type to ensure type safety.
+ */
+export type KeyConditions = Omit<QueryCommandInput["KeyConditions"], "undefined">;
+/**
+ * Defines the structure for a filter expression used in querying items, including the expression string and a record of values associated with the expression placeholders.
+ *
+ * @property {Record<string, NativeScalarAttributeValue>} values - A mapping of placeholder tokens in the filter expression to their actual values.
+ * @property {string} expression - The filter expression string, using DynamoDB's expression syntax.
+ */
+export interface FilterExpression {
+    values: Record<string, NativeScalarAttributeValue>;
+    expression: string;
+}
+/**
+ * Represents a filter condition specifying that a value must begin with a certain prefix.
+ *
+ * @type {BeginsWithFilter} - A record with "$beginsWith" key pointing to the prefix value.
+ */
+export type BeginsWithFilter = Record<"$beginsWith", NativeScalarAttributeValue>;
+/**
+ * Defines possible types of values that can be used in a filter condition, including begins with, exact value, or an array for "IN" conditions.
+ *
+ * @type {FilterTypes} - A union of `BeginsWithFilter`, a single scalar value, or an array of scalar values.
+ */
+export type FilterTypes = BeginsWithFilter | NativeScalarAttributeValue | NativeScalarAttributeValue[];
+/**
+ * Represents a filter condition using an AND logical operator. All items in this record will be queried with "AND"
+ *
+ * @type {AndFilter} - A record mapping attribute names to their filter conditions, implying all conditions must be met (AND logic).
+ */
+export type AndFilter = Record<string, FilterTypes>;
+/**
+ * Represents a filter condition using an OR logical operator, allowing for grouping of multiple `AndFilter` conditions under a single '$or' key.
+ *
+ * @type {OrFilter} - A record with an "$or" key containing an array of `AndFilter` objects, indicating any of the conditions can be met (OR logic).
+ */
+export type OrFilter = Record<"$or", AndFilter[]>;
+/**
+ * Makes the '$or' key optional in an `OrFilter`, allowing for filters that primarily use AND logic but optionally include OR conditions.
+ *
+ * @type {OrOptional} - An `OrFilter` type with the '$or' key made optional.
+ */
+export type OrOptional = Omit<OrFilter, "$or"> & Partial<Pick<OrFilter, "$or">>;
+/**
+ * Combines `AndFilter` and `OrFilter` types, supporting complex filters that use both AND and OR logic within the same filter structure.
+ *
+ * @type {FilterParams} - A combination of `AndFilter` or `OrFilter` with optional OR conditions.
+ */
+export type FilterParams = (AndFilter | OrFilter) & OrOptional;
+/**
+ * Represents complex filters combining AND and OR logic, specifically allowing for an 'OrFilter' at the top level.
+ *
+ * @type {AndOrFilter} - A `FilterParams` type further combined with an `OrFilter` for additional flexibility.
+ */
+export type AndOrFilter = FilterParams & OrFilter;
+/**
+ * Defines the condition for a sort key in a query, allowing for exact matches or "begins with" conditions.
+ *
+ * @type {SortKeyCondition} - A `BeginsWithFilter` or a single scalar value, used for sort key conditions in queries.
+ */
+export type SortKeyCondition = BeginsWithFilter | NativeScalarAttributeValue;
+/**
+ * Specifies additional options for querying items, including optional index name and filter conditions.
+ *
+ * @property {string?} indexName - Optional name of the secondary index to use in the query.
+ * @property {FilterParams?} filter - Optional filter conditions to apply to the query.
+ */
+export interface QueryOptions {
+    indexName?: string;
+    filter?: FilterParams;
+}
+/**
+ * Combines key conditions and query options to define the properties for a query command.
+ *
+ * @property {string} entityClassName - The name of the entity class being queried.
+ * @property {KeyConditions} key - The partition key conditions for the query.
+ * @property {QueryOptions?} options - Optional additional query options.
+ */
+export interface QueryCommandProps {
+    entityClassName: string;
+    key: KeyConditions;
+    options?: QueryOptions;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/src/query-utils/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/query-utils/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC/D,OAAO,EAAE,KAAK,0BAA0B,EAAE,MAAM,wBAAwB,CAAC;AAEzE;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG,IAAI,CAC9B,iBAAiB,CAAC,eAAe,CAAC,EAClC,WAAW,CACZ,CAAC;AAEF;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,0BAA0B,CAAC,CAAC;IACnD,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG,MAAM,CACnC,aAAa,EACb,0BAA0B,CAC3B,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,WAAW,GACnB,gBAAgB,GAChB,0BAA0B,GAC1B,0BAA0B,EAAE,CAAC;AAEjC;;;;GAIG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;AAEpD;;;;GAIG;AACH,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAC,KAAK,EAAE,SAAS,EAAE,CAAC,CAAC;AAElD;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG,IAAI,CAAC,QAAQ,EAAE,KAAK,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC,CAAC;AAEhF;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,SAAS,GAAG,QAAQ,CAAC,GAAG,UAAU,CAAC;AAE/D;;;;GAIG;AACH,MAAM,MAAM,WAAW,GAAG,YAAY,GAAG,QAAQ,CAAC;AAElD;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG,gBAAgB,GAAG,0BAA0B,CAAC;AAE7E;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,YAAY,CAAC;CACvB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IAChC,eAAe,EAAE,MAAM,CAAC;IACxB,GAAG,EAAE,aAAa,CAAC;IACnB,OAAO,CAAC,EAAE,YAAY,CAAC;CACxB"}

package/dist/src/query-utils/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/src/relationships/BelongsToLink.d.ts

@@ -0,0 +1,50 @@
+import type DynaRecord from "../DynaRecord";
+import type { ForeignKey } from "../types";
+/**
+ * Extends `DynaRecord` with properties specific to "BelongsTo" relationships, such as `foreignEntityType` and `foreignKey`.
+ */
+interface BelongsToLinkProps extends DynaRecord {
+    foreignEntityType: string;
+    foreignKey: string;
+}
+/**
+ * Represents a "BelongsTo" relationship link between entities within the ORM system. Instances of this class are used to track and manage associations where one entity belongs to another, encapsulating the connection details including the type of the foreign entity and its foreign key.
+ *
+ * This class implements the `BelongsToLinkProps` interface, ensuring consistency in the properties used to describe the "BelongsTo" relationship.
+ */
+declare class BelongsToLink implements BelongsToLinkProps {
+    /**
+     * A unique identifier for the link itself, automatically generated upon creation.
+     */
+    readonly id: string;
+    /**
+     * The type of the link, statically set to "BelongsToLink".
+     */
+    readonly type: string;
+    /**
+     * The name of the entity type to which the link points (the "parent" entity in the relationship).
+     */
+    readonly foreignEntityType: string;
+    /**
+     * The foreign key value identifying the specific instance of the foreign entity to which the link belongs. While it is a string, it represents the value of a `ForeignKey` attribute in the related entity.
+     */
+    readonly foreignKey: ForeignKey;
+    /**
+     * The timestamp marking when the link was created
+     */
+    readonly createdAt: Date;
+    /**
+     * The timestamp marking the last update to the link. Initially set to the same value as `createdAt`.
+     */
+    readonly updatedAt: Date;
+    constructor(item?: BelongsToLink);
+    /**
+     * A static method to construct a `BelongsToLinkProps` object with specified properties, including auto-generated `id` and timestamp fields. This method facilitates the creation of new link instances without directly instantiating the class.
+     * @param {string} foreignEntityType - The name of the entity type to which the new link will belong.
+     * @param {string} foreignKey - The foreign key value identifying the specific instance of the foreign entity.
+     * @returns {BelongsToLinkProps} - A new `BelongsToLinkProps` object ready for use in creating or managing a "BelongsTo" relationship.
+     */
+    static build(foreignEntityType: string, foreignKey: string): BelongsToLinkProps;
+}
+export default BelongsToLink;
+//# sourceMappingURL=BelongsToLink.d.ts.map

package/dist/src/relationships/BelongsToLink.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BelongsToLink.d.ts","sourceRoot":"","sources":["../../../src/relationships/BelongsToLink.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,UAAU,MAAM,eAAe,CAAC;AAC5C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAE3C;;GAEG;AACH,UAAU,kBAAmB,SAAQ,UAAU;IAC7C,iBAAiB,EAAE,MAAM,CAAC;IAC1B,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;GAIG;AACH,cAAM,aAAc,YAAW,kBAAkB;IAC/C;;OAEG;IACH,SAAgB,EAAE,EAAE,MAAM,CAAC;IAC3B;;OAEG;IACH,SAAgB,IAAI,EAAE,MAAM,CAAC;IAC7B;;OAEG;IACH,SAAgB,iBAAiB,EAAE,MAAM,CAAC;IAC1C;;OAEG;IACH,SAAgB,UAAU,EAAE,UAAU,CAAC;IACvC;;OAEG;IACH,SAAgB,SAAS,EAAE,IAAI,CAAC;IAChC;;OAEG;IACH,SAAgB,SAAS,EAAE,IAAI,CAAC;gBAEpB,IAAI,CAAC,EAAE,aAAa;IAMhC;;;;;OAKG;WACW,KAAK,CACjB,iBAAiB,EAAE,MAAM,EACzB,UAAU,EAAE,MAAM,GACjB,kBAAkB;CAYtB;AAED,eAAe,aAAa,CAAC"}

package/dist/src/relationships/BelongsToLink.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const uuid_1 = require("uuid");
+/**
+ * Represents a "BelongsTo" relationship link between entities within the ORM system. Instances of this class are used to track and manage associations where one entity belongs to another, encapsulating the connection details including the type of the foreign entity and its foreign key.
+ *
+ * This class implements the `BelongsToLinkProps` interface, ensuring consistency in the properties used to describe the "BelongsTo" relationship.
+ */
+class BelongsToLink {
+    /**
+     * A unique identifier for the link itself, automatically generated upon creation.
+     */
+    id;
+    /**
+     * The type of the link, statically set to "BelongsToLink".
+     */
+    type;
+    /**
+     * The name of the entity type to which the link points (the "parent" entity in the relationship).
+     */
+    foreignEntityType;
+    /**
+     * The foreign key value identifying the specific instance of the foreign entity to which the link belongs. While it is a string, it represents the value of a `ForeignKey` attribute in the related entity.
+     */
+    foreignKey;
+    /**
+     * The timestamp marking when the link was created
+     */
+    createdAt;
+    /**
+     * The timestamp marking the last update to the link. Initially set to the same value as `createdAt`.
+     */
+    updatedAt;
+    constructor(item) {
+        if (item !== undefined) {
+            Object.assign(this, item);
+        }
+    }
+    /**
+     * A static method to construct a `BelongsToLinkProps` object with specified properties, including auto-generated `id` and timestamp fields. This method facilitates the creation of new link instances without directly instantiating the class.
+     * @param {string} foreignEntityType - The name of the entity type to which the new link will belong.
+     * @param {string} foreignKey - The foreign key value identifying the specific instance of the foreign entity.
+     * @returns {BelongsToLinkProps} - A new `BelongsToLinkProps` object ready for use in creating or managing a "BelongsTo" relationship.
+     */
+    static build(foreignEntityType, foreignKey) {
+        const createdAt = new Date();
+        return {
+            id: (0, uuid_1.v4)(),
+            type: BelongsToLink.name,
+            foreignKey,
+            foreignEntityType,
+            createdAt,
+            updatedAt: createdAt
+        };
+    }
+}
+exports.default = BelongsToLink;

package/dist/src/relationships/JoinTable.d.ts

@@ -0,0 +1,68 @@
+import type DynaRecord from "../DynaRecord";
+import type { ForeignKey, EntityClass } from "../types";
+/**
+ * Exclude the type1 type2 instance keys
+ */
+type ExcludeKeys = "type1" | "type2";
+/**
+ * ForeignKey properties of the join table
+ */
+type ForeignKeyProperties<T> = {
+    [P in Exclude<keyof T, ExcludeKeys>]: T[P] extends ForeignKey ? string : never;
+};
+/**
+ * Abstract class representing a join table for HasAndBelongsToMany relationships.
+ * This class should be extended for specific join table implementations.
+ * It is virtual and not persisted to the database but manages the BelongsToLinks
+ * in each related entity's partition.
+ *
+ * Example:
+ * ```
+ * class ExampleJoinTable extends JoinTable {
+ *   public exampleId1: ForeignKey;
+ *   public exampleId2: ForeignKey;
+ * }
+ * ```
+ */
+declare abstract class JoinTable<T extends DynaRecord, K extends DynaRecord> {
+    private readonly type1;
+    private readonly type2;
+    constructor(type1: EntityClass<T>, type2: EntityClass<K>);
+    /**
+     * Create a JoinTable entry
+     * Adds BelongsToLink to each associated Entity's partition
+     * @param this
+     * @param keys
+     */
+    static create<ThisClass extends JoinTable<T, K>, T extends DynaRecord, K extends DynaRecord>(this: new (type1: EntityClass<T>, type2: EntityClass<K>) => ThisClass, keys: ForeignKeyProperties<ThisClass>): Promise<void>;
+    /**
+     * Delete a JoinTable entry
+     * Deletes BelongsToLink from each associated Entity's partition
+     * @param this
+     * @param keys
+     */
+    static delete<ThisClass extends JoinTable<T, K>, T extends DynaRecord, K extends DynaRecord>(this: new (type1: EntityClass<T>, type2: EntityClass<K>) => ThisClass, keys: ForeignKeyProperties<ThisClass>): Promise<void>;
+    /**
+     * Creates transactions:
+     *   1. Create a BelongsToLink in parents partition if its not already linked
+     *   2. Ensures that the parent EntityExists
+     * @param transactionBuilder
+     * @param keys
+     * @param parentEntityMeta
+     * @param linkedEntityMeta
+     */
+    private static createBelongsToLink;
+    /**
+     * Deletes transactions:
+     *   1. Delete a BelongsToLink in parents partition if its linked
+     * @param transactionBuilder
+     * @param keys
+     * @param parentEntityMeta
+     * @param linkedEntityMeta
+     */
+    private static deleteBelongsToLink;
+    private static joinTableKey;
+    private static transactionProps;
+}
+export default JoinTable;
+//# sourceMappingURL=JoinTable.d.ts.map

package/dist/src/relationships/JoinTable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"JoinTable.d.ts","sourceRoot":"","sources":["../../../src/relationships/JoinTable.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,UAAU,MAAM,eAAe,CAAC;AAM5C,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAIxD;;GAEG;AACH,KAAK,WAAW,GAAG,OAAO,GAAG,OAAO,CAAC;AAErC;;GAEG;AACH,KAAK,oBAAoB,CAAC,CAAC,IAAI;KAC5B,CAAC,IAAI,OAAO,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,UAAU,GACzD,MAAM,GACN,KAAK;CACV,CAAC;AAcF;;;;;;;;;;;;;GAaG;AACH,uBAAe,SAAS,CAAC,CAAC,SAAS,UAAU,EAAE,CAAC,SAAS,UAAU;IAE/D,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,KAAK;gBADL,KAAK,EAAE,WAAW,CAAC,CAAC,CAAC,EACrB,KAAK,EAAE,WAAW,CAAC,CAAC,CAAC;IAGxC;;;;;OAKG;WACiB,MAAM,CACxB,SAAS,SAAS,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,EACjC,CAAC,SAAS,UAAU,EACpB,CAAC,SAAS,UAAU,EAEpB,IAAI,EAAE,KAAK,KAAK,EAAE,WAAW,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,WAAW,CAAC,CAAC,CAAC,KAAK,SAAS,EACrE,IAAI,EAAE,oBAAoB,CAAC,SAAS,CAAC,GACpC,OAAO,CAAC,IAAI,CAAC;IAWhB;;;;;OAKG;WACiB,MAAM,CACxB,SAAS,SAAS,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,EACjC,CAAC,SAAS,UAAU,EACpB,CAAC,SAAS,UAAU,EAEpB,IAAI,EAAE,KAAK,KAAK,EAAE,WAAW,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,WAAW,CAAC,CAAC,CAAC,KAAK,SAAS,EACrE,IAAI,EAAE,oBAAoB,CAAC,SAAS,CAAC,GACpC,OAAO,CAAC,IAAI,CAAC;IAWhB;;;;;;;;OAQG;IACH,OAAO,CAAC,MAAM,CAAC,mBAAmB;IA6ClC;;;;;;;OAOG;IACH,OAAO,CAAC,MAAM,CAAC,mBAAmB;IA0BlC,OAAO,CAAC,MAAM,CAAC,YAAY;IAoB3B,OAAO,CAAC,MAAM,CAAC,gBAAgB;CAmBhC;AAED,eAAe,SAAS,CAAC"}

package/dist/src/relationships/JoinTable.js

@@ -0,0 +1,133 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const TransactWriteBuilder_1 = __importDefault(require("../dynamo-utils/TransactWriteBuilder"));
+const metadata_1 = __importDefault(require("../metadata"));
+const utils_1 = require("../utils");
+const BelongsToLink_1 = __importDefault(require("./BelongsToLink"));
+/**
+ * Abstract class representing a join table for HasAndBelongsToMany relationships.
+ * This class should be extended for specific join table implementations.
+ * It is virtual and not persisted to the database but manages the BelongsToLinks
+ * in each related entity's partition.
+ *
+ * Example:
+ * ```
+ * class ExampleJoinTable extends JoinTable {
+ *   public exampleId1: ForeignKey;
+ *   public exampleId2: ForeignKey;
+ * }
+ * ```
+ */
+class JoinTable {
+    type1;
+    type2;
+    constructor(type1, type2) {
+        this.type1 = type1;
+        this.type2 = type2;
+    }
+    /**
+     * Create a JoinTable entry
+     * Adds BelongsToLink to each associated Entity's partition
+     * @param this
+     * @param keys
+     */
+    static async create(keys) {
+        const transactionBuilder = new TransactWriteBuilder_1.default();
+        const [rel1, rel2] = metadata_1.default.getJoinTable(this.name);
+        JoinTable.createBelongsToLink(transactionBuilder, keys, rel1, rel2);
+        JoinTable.createBelongsToLink(transactionBuilder, keys, rel2, rel1);
+        await transactionBuilder.executeTransaction();
+    }
+    /**
+     * Delete a JoinTable entry
+     * Deletes BelongsToLink from each associated Entity's partition
+     * @param this
+     * @param keys
+     */
+    static async delete(keys) {
+        const transactionBuilder = new TransactWriteBuilder_1.default();
+        const [rel1, rel2] = metadata_1.default.getJoinTable(this.name);
+        JoinTable.deleteBelongsToLink(transactionBuilder, keys, rel1, rel2);
+        JoinTable.deleteBelongsToLink(transactionBuilder, keys, rel2, rel1);
+        await transactionBuilder.executeTransaction();
+    }
+    /**
+     * Creates transactions:
+     *   1. Create a BelongsToLink in parents partition if its not already linked
+     *   2. Ensures that the parent EntityExists
+     * @param transactionBuilder
+     * @param keys
+     * @param parentEntityMeta
+     * @param linkedEntityMeta
+     */
+    static createBelongsToLink(transactionBuilder, keys, parentEntityMeta, linkedEntityMeta) {
+        const { tableProps, entities, ids } = this.transactionProps(keys, parentEntityMeta, linkedEntityMeta);
+        const { name: tableName } = tableProps;
+        const { alias: partitionKeyAlias } = tableProps.partitionKeyAttribute;
+        const { alias: sortKeyAlias } = tableProps.sortKeyAttribute;
+        const { parentEntity, linkedEntity } = entities;
+        const { parentId, linkedEntityId } = ids;
+        transactionBuilder.addPut({
+            TableName: tableName,
+            Item: {
+                ...this.joinTableKey(keys, parentEntityMeta, linkedEntityMeta),
+                ...(0, utils_1.entityToTableItem)(linkedEntity, BelongsToLink_1.default.build(linkedEntity.name, parentId))
+            },
+            ConditionExpression: `attribute_not_exists(${partitionKeyAlias})` // Ensure item doesn't already exist
+        }, `${parentEntity.name} with ID ${linkedEntityId} is already linked to ${linkedEntity.name} with ID ${parentId}`);
+        transactionBuilder.addConditionCheck({
+            TableName: tableName,
+            Key: {
+                [partitionKeyAlias]: parentEntity.partitionKeyValue(linkedEntityId),
+                [sortKeyAlias]: parentEntity.name
+            },
+            ConditionExpression: `attribute_exists(${partitionKeyAlias})`
+        }, `${parentEntity.name} with ID ${linkedEntityId} does not exist`);
+    }
+    /**
+     * Deletes transactions:
+     *   1. Delete a BelongsToLink in parents partition if its linked
+     * @param transactionBuilder
+     * @param keys
+     * @param parentEntityMeta
+     * @param linkedEntityMeta
+     */
+    static deleteBelongsToLink(transactionBuilder, keys, parentEntityMeta, linkedEntityMeta) {
+        const { entity: parentEntity, foreignKey: parentKey } = parentEntityMeta;
+        const { entity: linkedEntity, foreignKey: linkedKey } = linkedEntityMeta;
+        const parentId = keys[parentKey];
+        const linkedEntityId = keys[linkedKey];
+        const { name: tableName, partitionKeyAttribute } = metadata_1.default.getEntityTable(parentEntity.name);
+        transactionBuilder.addDelete({
+            TableName: tableName,
+            Key: this.joinTableKey(keys, parentEntityMeta, linkedEntityMeta),
+            ConditionExpression: `attribute_exists(${partitionKeyAttribute.alias})`
+        }, `${parentEntity.name} with ID ${linkedEntityId} is not linked to ${linkedEntity.name} with ID ${parentId}`);
+    }
+    static joinTableKey(keys, parentEntityMeta, linkedEntityMeta) {
+        const { tableProps, entities, ids } = this.transactionProps(keys, parentEntityMeta, linkedEntityMeta);
+        const { parentEntity, linkedEntity } = entities;
+        const { alias: partitionKeyAlias } = tableProps.partitionKeyAttribute;
+        const { alias: sortKeyAlias } = tableProps.sortKeyAttribute;
+        return {
+            [partitionKeyAlias]: parentEntity.partitionKeyValue(ids.linkedEntityId),
+            [sortKeyAlias]: linkedEntity.partitionKeyValue(ids.parentId)
+        };
+    }
+    static transactionProps(keys, parentEntityMeta, linkedEntityMeta) {
+        const { entity: parentEntity, foreignKey: parentFK } = parentEntityMeta;
+        const { entity: linkedEntity, foreignKey: linkedFK } = linkedEntityMeta;
+        const tableMetadata = metadata_1.default.getEntityTable(parentEntity.name);
+        const parentId = keys[parentFK];
+        const linkedEntityId = keys[linkedFK];
+        return {
+            tableProps: tableMetadata,
+            entities: { parentEntity, linkedEntity },
+            ids: { parentId, linkedEntityId }
+        };
+    }
+}
+exports.default = JoinTable;

package/dist/src/relationships/index.d.ts

@@ -0,0 +1,3 @@
+export { default as BelongsToLink } from "./BelongsToLink";
+export { default as JoinTable } from "./JoinTable";
+//# sourceMappingURL=index.d.ts.map

package/dist/src/relationships/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/relationships/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAC3D,OAAO,EAAE,OAAO,IAAI,SAAS,EAAE,MAAM,aAAa,CAAC"}

package/dist/src/relationships/index.js

@@ -0,0 +1,10 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JoinTable = exports.BelongsToLink = void 0;
+var BelongsToLink_1 = require("./BelongsToLink");
+Object.defineProperty(exports, "BelongsToLink", { enumerable: true, get: function () { return __importDefault(BelongsToLink_1).default; } });
+var JoinTable_1 = require("./JoinTable");
+Object.defineProperty(exports, "JoinTable", { enumerable: true, get: function () { return __importDefault(JoinTable_1).default; } });

package/dist/src/types.d.ts

@@ -0,0 +1,73 @@
+import { type NativeScalarAttributeValue } from "@aws-sdk/util-dynamodb";
+import { type BelongsToLink } from "./relationships";
+import type { BelongsToRelationship, RelationshipMetadata } from "./metadata";
+import type DynaRecord from "./DynaRecord";
+/**
+ * A utility type for branding primitives to ensure type safety with unique identifiers.
+ */
+export type Brand<K, T> = K & {
+    __brand: T;
+};
+/**
+ * A branded string type to represent sort keys in DynamoDB tables
+ */
+export type SortKey = Brand<string, "SortKey">;
+/**
+ * A branded string type to represent partition keys in DynamoDB tables
+ */
+export type PartitionKey = Brand<string, "PartitionKey">;
+/**
+ * A branded string type to represent foreign keys in DynamoDB tables
+ */
+export type ForeignKey = Brand<string, "ForeignKey">;
+/**
+ * A branded string type to represent nullable foreign keys in DynamoDB tables, which can also be undefined.
+ */
+export type NullableForeignKey = Optional<Brand<string, "NullableForeignKey">>;
+/**
+ * Represents a foreign key property on an entity within a DynaRecord model
+ */
+export type ForeignKeyProperty = keyof DynaRecord & ForeignKey;
+/**
+ * Defines a general type for items stored in a DynamoDB table, using string keys and native scalar attribute values.
+ */
+export type DynamoTableItem = Record<string, NativeScalarAttributeValue>;
+/**
+ * A utility type for objects with string keys and string values.
+ */
+export type StringObj = Record<string, string>;
+/**
+ * Describes the shape of a DynamoDB item representing a `BelongsToLink`, enforcing type consistency.
+ */
+export interface BelongsToLinkDynamoItem {
+    Type: typeof BelongsToLink.name;
+    [key: string]: NativeScalarAttributeValue;
+}
+/**
+ * A utility type for making a type optional, allowing it to be undefined.
+ */
+export type Optional<T> = T | undefined;
+/**
+ * A utility type for making a type nullable, allowing it to be null.
+ */
+export type Nullable<T> = T | null;
+/**
+ * Represents a lookup object to access relationship metadata by related entity name for DynaRecord models.
+ */
+export type RelationshipLookup = Record<string, RelationshipMetadata>;
+/**
+ * An object structure for holding relationship metadata, aimed at optimizing lookup operations and iterations.
+ */
+export interface RelationshipMetaObj {
+    relationsLookup: RelationshipLookup;
+    belongsToRelationships: BelongsToRelationship[];
+}
+/**
+ * A utility type for modifying certain keys of an object type to be optional.
+ */
+export type MakeOptional<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
+/**
+ * Represents an instance of a class decorated with the `Entity` decorator in DynaRecord, encapsulating entity logic.
+ */
+export type EntityClass<T> = (new () => T) & typeof DynaRecord;
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +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,EAAE,KAAK,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACrD,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,WAAW,uBAAuB;IACtC,IAAI,EAAE,OAAO,aAAa,CAAC,IAAI,CAAC;IAChC,CAAC,GAAG,EAAE,MAAM,GAAG,0BAA0B,CAAC;CAC3C;AAED;;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"}

package/dist/src/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/src/utils.d.ts

@@ -0,0 +1,89 @@
+import type DynaRecord from "./DynaRecord";
+import type { DynamoTableItem, BelongsToLinkDynamoItem } from "./types";
+import { type TableMetadata } from "./metadata";
+import { BelongsToLink } from "./relationships";
+/**
+ * Convert an entity to its aliased table item fields to for dynamo interactions
+ * @param entityClassName
+ * @param entityData
+ * @returns
+ */
+export declare const entityToTableItem: <T extends DynaRecord>(EntityClass: new () => T, entityData: Partial<DynaRecord>) => DynamoTableItem;
+/**
+ * Serialize a table item to its associated Entity class, using the class attribute property names
+ * @param EntityClass
+ * @param tableItem
+ * @returns
+ */
+export declare const tableItemToEntity: <T extends DynaRecord>(EntityClass: new () => T, tableItem: DynamoTableItem) => T;
+/**
+ * Serialize a dynamo table item response to a BelongsToLink
+ * @param tableMeta - Table metadata
+ * @param tableItem - Table item from dynamo response
+ * @returns - { @link BelongsToLink }
+ */
+export declare const tableItemToBelongsToLink: (tableMeta: TableMetadata, tableItem: BelongsToLinkDynamoItem) => BelongsToLink;
+/**
+ * Type guard to check if the key is defined on the entity
+ */
+export declare const isKeyOfEntity: (entity: DynaRecord, key: string) => key is keyof DynaRecord;
+/**
+ * Type guard to check if the key is a defined property on the entity
+ * @param entity
+ * @param key
+ * @returns
+ */
+export declare const isKeyOfObject: <T>(entity: Partial<DynaRecord>, key: any) => key is keyof T;
+/**
+ * Type guard to check if the DynamoTableItem is a BelongsToLink
+ * @param res DynamoTableItem
+ * @returns boolean
+ */
+export declare const isBelongsToLinkDynamoItem: (res: DynamoTableItem, tableMeta: TableMetadata) => res is BelongsToLinkDynamoItem;
+/**
+ * Break an array into chunks
+ * @param array
+ * @param size
+ * @returns Array split into chunks of given  size
+ */
+export declare const chunkArray: <T>(array: T[], size: number) => T[][];
+/**
+ * Checks if a value is a valid property key (string, number, or symbol).
+ *
+ * @param value The value to be checked. This can be of any type.
+ * @returns `true` if the value is a `string`, `number`, or `symbol` (i.e., a valid property key); otherwise, `false`.
+ *
+ * @example
+ * Logger.log(isPropertyKey('test')); // true
+ * Logger.log(isPropertyKey(123)); // true
+ * Logger.log(isPropertyKey(Symbol('sym'))); // true
+ * Logger.log(isPropertyKey({})); // false
+ */
+export declare const isPropertyKey: (value: any) => value is PropertyKey;
+/**
+ * Checks if the given value is a string.
+ *
+ * @param value - The value to check. This can be any type as the function is meant to validate if it's a string.
+ * @returns `true` if `value` is a string; otherwise, `false`.
+ */
+export declare const isString: (value: any) => value is string;
+/**
+ * Safely assigns a value to a property of an object.
+ * It's useful for dynamically assigning properties to objects where the property names might be known but the types could vary.
+ *
+ * @template TObject - The object type to which the property belongs.
+ * @template TKey - The type of the keys of `TObject`
+ * @template TValue - The  value to be assigned.
+ *
+ * @param {TObject} object - The target object to which the property will be assigned.
+ * @param {TKey} key - The property name under which the value should be assigned. Must be a key of `TObject`.
+ * @param {TValue} value - The value to assign to the property on the object.
+ *
+ * @returns {void} - This function does not return a value; it performs the assignment operation directly on the passed object.
+ *
+ * @example
+ * let entity = { id: "123" };
+ * safeAssign(entity, "name", "Jane Doe");
+ */
+export declare const safeAssign: <TObject extends DynaRecord, TKey extends keyof TObject, TValue>(object: TObject, key: TKey, value: TValue) => void;
+//# sourceMappingURL=utils.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,UAAU,MAAM,cAAc,CAAC;AAC3C,OAAO,KAAK,EAAE,eAAe,EAAE,uBAAuB,EAAE,MAAM,SAAS,CAAC;AACxE,OAAiB,EAEf,KAAK,aAAa,EACnB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAGhD;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,+DAEhB,QAAQ,UAAU,CAAC,KAC9B,eAmBF,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,8DAEjB,eAAe,MAwB3B,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,cACxB,aAAa,aACb,uBAAuB,KACjC,aA2BF,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,aAAa,WAChB,UAAU,OACb,MAAM,4BAGZ,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,aAAa,cAChB,QAAQ,UAAU,CAAC,OACtB,GAAG,mBAGT,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,QAC/B,eAAe,aACT,aAAa,mCAGzB,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,UAAU,wBAAyB,MAAM,UAIrD,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,aAAa,UAAW,GAAG,yBAMvC,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,QAAQ,UAAW,GAAG,oBAElC,CAAC;AAEF;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,UAAU,iHAQpB,IAEF,CAAC"}