@moicky/dynamodb 2.4.6 → 2.5.1

package/dist/index.d.ts

@@ -1,3 +1,6 @@
 export * from "./lib";
 export * from "./operations";
+export * from "./transactions";
+export { createCustomReference, getDependencies, resolveReferences, } from "./transactions/references";
+export type { ReferenceMetadata, ReferenceTo, ResolvedItem, WithoutReferences, } from "./transactions/references/types";
 export type * from "./types";

package/dist/index.js

@@ -14,5 +14,11 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveReferences = exports.getDependencies = exports.createCustomReference = void 0;
 __exportStar(require("./lib"), exports);
 __exportStar(require("./operations"), exports);
+__exportStar(require("./transactions"), exports);
+var references_1 = require("./transactions/references");
+Object.defineProperty(exports, "createCustomReference", { enumerable: true, get: function () { return references_1.createCustomReference; } });
+Object.defineProperty(exports, "getDependencies", { enumerable: true, get: function () { return references_1.getDependencies; } });
+Object.defineProperty(exports, "resolveReferences", { enumerable: true, get: function () { return references_1.resolveReferences; } });

package/dist/lib/fixes.d.ts

@@ -39,27 +39,27 @@ export declare const initFixes: (fixesConfig: DynamoDBFixes) => void;
  */
 export declare const getFixes: () => DynamoDBFixes;
 /**
- * Returns the current {@link DynamoDBFixes} used for all operations.
+ * Applies fixes in arguments for Query/Scan operations.
  * @param args - The arguments to override the default arguments with
  * @returns The merged arguments
  * @private
  */
 export declare const withFixes: (args: Partial<QueryCommandInput> | Partial<ScanCommandInput>) => Partial<QueryCommandInput> | Partial<ScanCommandInput>;
 /**
- * Returns the current {@link DynamoDBFixes} used for all operations.
+ * Returns the default {@link DynamoDBFixes} used for all operations.
  * @returns The current {@link DynamoDBFixes}
  * @private
  */
 export declare const getDefaultFixes: () => DynamoDBFixes;
 /**
- * Returns the current {@link DynamoDBFixes} used for all operations.
+ * Marshalls the input using {@link marshall} with the global options.
  * @param input - The input to marshall
  * @returns The marshalled input
  * @private
  */
 export declare const marshallWithOptions: (input: Parameters<typeof marshall>[0]) => Record<string, import("@aws-sdk/client-dynamodb").AttributeValue>;
 /**
- * Returns the current {@link DynamoDBFixes} used for all operations.
+ * Unmarshalls the input using {@link unmarshall} with the global options.
  * @param input - The input to unmarshall
  * @returns The unmarshalled input
  * @private

package/dist/lib/fixes.js

@@ -33,7 +33,7 @@ const handleIndex = (args) => {
     }
 };
 /**
- * Returns the current {@link DynamoDBFixes} used for all operations.
+ * Applies fixes in arguments for Query/Scan operations.
  * @param args - The arguments to override the default arguments with
  * @returns The merged arguments
  * @private
@@ -44,14 +44,14 @@ const withFixes = (args) => {
 };
 exports.withFixes = withFixes;
 /**
- * Returns the current {@link DynamoDBFixes} used for all operations.
+ * Returns the default {@link DynamoDBFixes} used for all operations.
  * @returns The current {@link DynamoDBFixes}
  * @private
  */
 const getDefaultFixes = () => defaults;
 exports.getDefaultFixes = getDefaultFixes;
 /**
- * Returns the current {@link DynamoDBFixes} used for all operations.
+ * Marshalls the input using {@link marshall} with the global options.
  * @param input - The input to marshall
  * @returns The marshalled input
  * @private
@@ -59,7 +59,7 @@ exports.getDefaultFixes = getDefaultFixes;
 const marshallWithOptions = (input) => (0, util_dynamodb_1.marshall)(input, fixes.marshallOptions);
 exports.marshallWithOptions = marshallWithOptions;
 /**
- * Returns the current {@link DynamoDBFixes} used for all operations.
+ * Unmarshalls the input using {@link unmarshall} with the global options.
  * @param input - The input to unmarshall
  * @returns The unmarshalled input
  * @private

package/dist/lib/helpers.d.ts

@@ -1,7 +1,34 @@
-export declare function stripKey(key: any, args?: {
+export declare function stripKey(key: Record<string, any>, args?: {
     TableName?: string;
 }): Record<string, import("@aws-sdk/client-dynamodb").AttributeValue>;
 export declare function splitEvery<T>(items: T[], limit?: number): T[][];
-export declare function getAttributeValues(key: any, attributesToGet?: string[]): Record<string, import("@aws-sdk/client-dynamodb").AttributeValue>;
-export declare function getAttributeNames(key: any, attributesToGet?: string[]): Record<string, string>;
+export declare function getAttributeValues(key: Record<string, any>, { attributesToGet, prefix, }?: {
+    attributesToGet?: string[];
+    prefix?: string;
+}): Record<string, import("@aws-sdk/client-dynamodb").AttributeValue>;
+export declare function getAttributeNames(key: Record<string, any>, { attributesToGet, prefix, }?: {
+    attributesToGet?: string[];
+    prefix?: string;
+}): Record<string, string>;
 export declare function getAttributesFromExpression(expression: string, prefix?: string): string[];
+export declare class ExpressionAttributes {
+    ExpressionAttributeValues: Record<string, any>;
+    ExpressionAttributeNames: Record<string, string>;
+    nameMapping: Record<string, string>;
+    valueMapping: Record<string, any>;
+    nameCounter: number;
+    valueCounter: number;
+    constructor(ExpressionAttributeValues?: Record<string, any>, ExpressionAttributeNames?: Record<string, string>);
+    appendNames(names: string[]): void;
+    appendValues(values: Record<string, any>): void;
+    appendBoth(values: Record<string, any>): void;
+    getAttributes(): {
+        ExpressionAttributeValues: Record<string, import("@aws-sdk/client-dynamodb").AttributeValue>;
+        ExpressionAttributeNames: Record<string, string>;
+    };
+    getName(attributeName: string): string;
+    getValue(attributeName: string): any;
+}
+export declare const getItemKey: (item: Record<string, any>, args?: {
+    TableName?: string;
+}) => string;

package/dist/lib/helpers.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getAttributesFromExpression = exports.getAttributeNames = exports.getAttributeValues = exports.splitEvery = exports.stripKey = void 0;
+exports.getItemKey = exports.ExpressionAttributes = exports.getAttributesFromExpression = exports.getAttributeNames = exports.getAttributeValues = exports.splitEvery = exports.stripKey = void 0;
 const fixes_1 = require("./fixes");
 const schemas_1 = require("./schemas");
 // Since dynamo only accepts key atrtributes which are described in table schema
@@ -22,16 +22,16 @@ function splitEvery(items, limit = 25) {
     return batches;
 }
 exports.splitEvery = splitEvery;
-function getAttributeValues(key, attributesToGet) {
+function getAttributeValues(key, { attributesToGet, prefix = ":", } = {}) {
     return (0, fixes_1.marshallWithOptions)((attributesToGet || Object.keys(key)).reduce((acc, keyName) => {
-        acc[`:${keyName}`] = key[keyName];
+        acc[`${prefix}${keyName}`] = key[keyName];
         return acc;
     }, {}));
 }
 exports.getAttributeValues = getAttributeValues;
-function getAttributeNames(key, attributesToGet) {
+function getAttributeNames(key, { attributesToGet, prefix = "#", } = {}) {
     return (attributesToGet || Object.keys(key)).reduce((acc, keyName) => {
-        acc[`#${keyName}`] = keyName;
+        acc[`${prefix}${keyName}`] = keyName;
         return acc;
     }, {});
 }
@@ -42,3 +42,65 @@ function getAttributesFromExpression(expression, prefix = "#") {
         ?.map((attr) => attr.slice(1)) || []);
 }
 exports.getAttributesFromExpression = getAttributesFromExpression;
+class ExpressionAttributes {
+    ExpressionAttributeValues;
+    ExpressionAttributeNames;
+    nameMapping = {};
+    valueMapping = {};
+    nameCounter = 0;
+    valueCounter = 0;
+    constructor(ExpressionAttributeValues = {}, ExpressionAttributeNames = {}) {
+        this.ExpressionAttributeValues = ExpressionAttributeValues;
+        this.ExpressionAttributeNames = ExpressionAttributeNames;
+    }
+    appendNames(names) {
+        names.forEach((name) => {
+            const parts = name.split(".");
+            parts.forEach((part) => {
+                if (!this.nameMapping[part]) {
+                    const newName = `#${this.nameCounter++}`;
+                    this.nameMapping[part] = newName;
+                    this.ExpressionAttributeNames[newName] = part;
+                }
+            });
+        });
+    }
+    appendValues(values) {
+        Object.entries(values).forEach(([key, value]) => {
+            const newValueName = `:${this.valueCounter++}`;
+            this.valueMapping[key] = newValueName;
+            this.ExpressionAttributeValues[newValueName] = value;
+        });
+    }
+    appendBoth(values) {
+        this.appendNames(Object.keys(values));
+        this.appendValues(values);
+    }
+    getAttributes() {
+        const marshalled = (0, fixes_1.marshallWithOptions)(this.ExpressionAttributeValues);
+        return {
+            ExpressionAttributeNames: this.ExpressionAttributeNames,
+            ...(Object.keys(marshalled).length > 0 && {
+                ExpressionAttributeValues: marshalled,
+            }),
+        };
+    }
+    getName(attributeName) {
+        return attributeName
+            .split(".")
+            .map((part) => this.nameMapping[part])
+            .join(".");
+    }
+    getValue(attributeName) {
+        return this.valueMapping[attributeName];
+    }
+}
+exports.ExpressionAttributes = ExpressionAttributes;
+const getItemKey = (item, args) => {
+    const { hash, range } = (0, schemas_1.getTableSchema)(args?.TableName);
+    return JSON.stringify({
+        [hash]: item[hash],
+        ...(range && { [range]: item[range] }),
+    });
+};
+exports.getItemKey = getItemKey;

package/dist/operations/query.js

@@ -15,14 +15,18 @@ async function _query(keyCondition, key, args = {}) {
     args = (0, lib_1.withFixes)(args);
     return (0, lib_1.getClient)().send(new client_dynamodb_1.QueryCommand({
         KeyConditionExpression: keyCondition,
-        ExpressionAttributeValues: (0, lib_1.getAttributeValues)(key, [
-            ...(0, lib_1.getAttributesFromExpression)(keyCondition, ":"),
-            ...(0, lib_1.getAttributesFromExpression)(args?.FilterExpression || "", ":"),
-        ]),
-        ExpressionAttributeNames: (0, lib_1.getAttributeNames)(key, [
-            ...(0, lib_1.getAttributesFromExpression)(keyCondition),
-            ...(0, lib_1.getAttributesFromExpression)(args?.FilterExpression || ""),
-        ]),
+        ExpressionAttributeValues: (0, lib_1.getAttributeValues)(key, {
+            attributesToGet: [
+                ...(0, lib_1.getAttributesFromExpression)(keyCondition, ":"),
+                ...(0, lib_1.getAttributesFromExpression)(args?.FilterExpression || "", ":"),
+            ],
+        }),
+        ExpressionAttributeNames: (0, lib_1.getAttributeNames)(key, {
+            attributesToGet: [
+                ...(0, lib_1.getAttributesFromExpression)(keyCondition),
+                ...(0, lib_1.getAttributesFromExpression)(args?.FilterExpression || ""),
+            ],
+        }),
         ...args,
         TableName: args?.TableName || (0, lib_1.getDefaultTable)(),
     }));
@@ -103,7 +107,7 @@ async function queryAllItems(keyCondition, key, args = {}) {
     args = (0, lib_1.withDefaults)(args, "queryAllItems");
     let data = await _query(keyCondition, key, args);
     while (data.LastEvaluatedKey) {
-        if (!Object.hasOwn(args, "Limit") || data.Items.length < args?.Limit) {
+        if (!("Limit" in args) || data.Items.length < args?.Limit) {
             let helper = await _query(keyCondition, key, {
                 ...args,
                 ExclusiveStartKey: data.LastEvaluatedKey,

package/dist/operations/transactWriteItems.js

@@ -53,8 +53,12 @@ async function transactWriteItems(transactItems, args = {}) {
 exports.transactWriteItems = transactWriteItems;
 function handleExpressionAttributes(rest, data) {
     return {
-        ExpressionAttributeValues: (0, lib_1.getAttributeValues)(data || {}, (0, lib_1.getAttributesFromExpression)(rest.ConditionExpression || "", ":")),
-        ExpressionAttributeNames: (0, lib_1.getAttributeNames)(data || {}, (0, lib_1.getAttributesFromExpression)(rest.ConditionExpression || "")),
+        ExpressionAttributeValues: (0, lib_1.getAttributeValues)(data || {}, {
+            attributesToGet: (0, lib_1.getAttributesFromExpression)(rest.ConditionExpression || "", ":"),
+        }),
+        ExpressionAttributeNames: (0, lib_1.getAttributeNames)(data || {}, {
+            attributesToGet: (0, lib_1.getAttributesFromExpression)(rest.ConditionExpression || ""),
+        }),
     };
 }
 function handleConditionCheck(params, args) {
@@ -106,7 +110,9 @@ function handleUpdateItem(params, args) {
             Key: (0, lib_1.stripKey)(key, { TableName: rest.TableName || args.table }),
             UpdateExpression,
             ExpressionAttributeValues: (0, lib_1.getAttributeValues)(mergedData),
-            ExpressionAttributeNames: (0, lib_1.getAttributeNames)({}, (0, lib_1.getAttributesFromExpression)(rest.ConditionExpression || "").concat(Object.keys(populatedData))),
+            ExpressionAttributeNames: (0, lib_1.getAttributeNames)({}, {
+                attributesToGet: (0, lib_1.getAttributesFromExpression)(rest.ConditionExpression || "").concat(Object.keys(populatedData)),
+            }),
             ...rest,
             TableName: rest.TableName || args.table,
         },

package/dist/operations/update.js

@@ -12,18 +12,17 @@ async function updateItem(key, data, args) {
     const namesInCondition = (0, lib_1.getAttributesFromExpression)(argsWithDefaults?.ConditionExpression || "");
     const attributesToUpdate = Object.keys(data).filter((key) => !valuesInCondition.includes(key));
     const UpdateExpression = "SET " + attributesToUpdate.map((key) => `#${key} = :${key}`).join(", ");
+    // @ts-ignore
     return (0, lib_1.getClient)()
         .send(new client_dynamodb_1.UpdateItemCommand({
         Key: (0, lib_1.stripKey)(key, argsWithDefaults),
         UpdateExpression,
-        ExpressionAttributeValues: (0, lib_1.getAttributeValues)(data, [
-            ...attributesToUpdate,
-            ...valuesInCondition,
-        ]),
-        ExpressionAttributeNames: (0, lib_1.getAttributeNames)(data, [
-            ...attributesToUpdate,
-            ...namesInCondition,
-        ]),
+        ExpressionAttributeValues: (0, lib_1.getAttributeValues)(data, {
+            attributesToGet: [...attributesToUpdate, ...valuesInCondition],
+        }),
+        ExpressionAttributeNames: (0, lib_1.getAttributeNames)(data, {
+            attributesToGet: [...attributesToUpdate, ...namesInCondition],
+        }),
         ...argsWithDefaults,
         TableName: argsWithDefaults?.TableName || (0, lib_1.getDefaultTable)(),
     }))

package/dist/transactions/index.d.ts

@@ -0,0 +1,20 @@
+import { TransactWriteItemsCommandInput } from "@aws-sdk/client-dynamodb";
+import { ConditionOperations, CreateOperations, UpdateOperations } from "./operations";
+import { WithoutReferences } from "./references/types";
+import { ConditionOperation, CreateOperation, DeleteOperation, DynamoDBItemKey, ItemWithKey, OnlyKey, UpdateOperation } from "./types";
+export declare class Transaction {
+    private tableName;
+    private timestamp;
+    private operations;
+    constructor({ tableName, timestamp, }?: {
+        tableName?: string;
+        timestamp?: number;
+    });
+    private getItemKey;
+    create<T extends ItemWithKey>(item: WithoutReferences<T>, args?: CreateOperation["args"]): CreateOperations<T>;
+    update<T extends DynamoDBItemKey>(item: OnlyKey<T>, args?: UpdateOperation["args"]): UpdateOperations<T>;
+    delete(item: DynamoDBItemKey, args?: DeleteOperation["args"]): void;
+    addConditionFor<T extends DynamoDBItemKey>(item: T, args?: Partial<ConditionOperation["args"]>): ConditionOperations<T>;
+    private handleOperation;
+    execute(args?: Partial<Omit<TransactWriteItemsCommandInput, "TransactItems">>): Promise<any>;
+}

package/dist/transactions/index.js

@@ -0,0 +1,139 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Transaction = void 0;
+const client_dynamodb_1 = require("@aws-sdk/client-dynamodb");
+const __1 = require("..");
+const operations_1 = require("./operations");
+// https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_TransactWriteItems.html
+const OPERATIONS_LIMIT = 100;
+class Transaction {
+    tableName;
+    timestamp = Date.now();
+    operations = {};
+    constructor({ tableName = (0, __1.getDefaultTable)(), timestamp = Date.now(), } = {}) {
+        this.tableName = tableName;
+        this.timestamp = timestamp;
+    }
+    getItemKey(item, tableName) {
+        return (0, __1.getItemKey)(item, { TableName: tableName || this.tableName });
+    }
+    create(item, args) {
+        const itemKey = this.getItemKey(item, args?.TableName);
+        const createOperation = {
+            _type: "create",
+            item: item,
+            args: { TableName: this.tableName, ...args },
+        };
+        this.operations[itemKey] = createOperation;
+        return new operations_1.CreateOperations(createOperation, this);
+    }
+    update(item, args) {
+        const itemKey = this.getItemKey(item, args?.TableName);
+        const updateOperation = {
+            _type: "update",
+            item,
+            actions: [{ _type: "set", values: { updatedAt: this.timestamp } }],
+            args: { TableName: this.tableName, ...args },
+        };
+        this.operations[itemKey] = updateOperation;
+        return new operations_1.UpdateOperations(updateOperation, this);
+    }
+    delete(item, args) {
+        const itemKey = this.getItemKey(item, args?.TableName);
+        this.operations[itemKey] = {
+            _type: "delete",
+            item,
+            args: { TableName: this.tableName, ...args },
+        };
+    }
+    addConditionFor(item, args) {
+        return new operations_1.ConditionOperations(this.operations, item, {
+            TableName: this.tableName,
+            ...args,
+        });
+    }
+    handleOperation(operation) {
+        switch (operation._type) {
+            case "create": {
+                const { item, args } = operation;
+                return {
+                    Put: {
+                        Item: (0, __1.marshallWithOptions)({ createdAt: this.timestamp, ...item }),
+                        ...args,
+                    },
+                };
+            }
+            case "update": {
+                const { item, actions, args } = operation;
+                const expressions = {
+                    add: [],
+                    delete: [],
+                    remove: [],
+                    set: [],
+                };
+                const { ExpressionAttributeValues, ExpressionAttributeNames, ...otherArgs } = args;
+                const attr = new __1.ExpressionAttributes(ExpressionAttributeValues, ExpressionAttributeNames);
+                actions.forEach((action) => {
+                    switch (action._type) {
+                        case "set":
+                            attr.appendBoth(action.values);
+                            expressions.set.push(Object.keys(action.values)
+                                .map((key) => `${attr.getName(key)} = ${attr.getValue(key)}`)
+                                .join(", "));
+                            break;
+                        case "remove":
+                            attr.appendNames(action.attributes);
+                            expressions.remove.push(action.attributes.map((key) => attr.getName(key)).join(", "));
+                            break;
+                        case "add":
+                            attr.appendBoth(action.values);
+                            expressions.add.push(Object.keys(action.values)
+                                .map((key) => `${attr.getName(key)} ${attr.getValue(key)}`)
+                                .join(", "));
+                            break;
+                        case "delete":
+                            attr.appendBoth(action.values);
+                            expressions.delete.push(Object.keys(action.values)
+                                .map((key) => `${attr.getName(key)} ${attr.getValue(key)}`)
+                                .join(", "));
+                            break;
+                    }
+                });
+                const joinedExpressions = Object.entries(expressions)
+                    .filter(([, value]) => value?.length)
+                    .reduce((acc, [t, v]) => [...acc, `${t.toUpperCase()} ${v.join(", ")}`], [])
+                    .join(" ");
+                return {
+                    Update: {
+                        Key: (0, __1.stripKey)(item),
+                        UpdateExpression: joinedExpressions,
+                        ...attr.getAttributes(),
+                        ...otherArgs,
+                    },
+                };
+            }
+            case "delete": {
+                const { item, args } = operation;
+                return { Delete: { Key: (0, __1.stripKey)(item), ...args } };
+            }
+            case "condition": {
+                const { item, args } = operation;
+                return { ConditionCheck: { Key: (0, __1.stripKey)(item), ...args } };
+            }
+        }
+    }
+    async execute(args) {
+        const operations = Object.values(this.operations).map((op) => this.handleOperation(op));
+        if (operations.length === 0 || operations.length > OPERATIONS_LIMIT) {
+            throw new Error("Invalid number of operations");
+        }
+        const input = {
+            TransactItems: operations,
+            ...args,
+        };
+        return (0, __1.getClient)()
+            .send(new client_dynamodb_1.TransactWriteItemsCommand(input))
+            .catch((err) => ({ ...err, args: input }));
+    }
+}
+exports.Transaction = Transaction;

package/dist/transactions/operations.d.ts

@@ -0,0 +1,41 @@
+import { Transaction } from ".";
+import { DynamoDBItem } from "../types";
+import { DynamoDBReference } from "./references/types";
+import { ConditionOperation, CreateOperation, DynamoDBItemKey, DynamoDBSet, ItemWithKey, NestedParams, NestedTypedParams, TypedParams, UpdateOperation, WithoutKey } from "./types";
+export declare class CreateOperations<U extends ItemWithKey> {
+    private operation;
+    private transaction;
+    constructor(operation: CreateOperation, transaction: Transaction);
+    setReferences(refs: SetReferencesParams<U>): void;
+}
+export declare class UpdateOperations<U extends DynamoDBItem> {
+    private operation;
+    private transaction;
+    constructor(operation: UpdateOperation, transaction: Transaction);
+    setReferences(refs: SetReferencesParams<U>): void;
+    set(values: WithoutKey<Partial<U>> & NestedParams): this;
+    adjustNumber(values: NestedTypedParams<U, number>): this;
+    removeAttributes(...attributes: string[]): this;
+    addItemsToSet(values: {
+        [Key in keyof U as NonNullable<U[Key]> extends DynamoDBSet ? Key : never]?: U[Key] extends Set<infer type> ? Set<type> | type[] : never;
+    } & NestedParams<Set<any> | any[]>): this;
+    deleteItemsFromSet(values: NestedTypedParams<U, Set<any>>): this;
+    onCondition({ expression, values, }: {
+        expression: string;
+        values: Partial<U> & Record<string, any>;
+    }): void;
+}
+export declare class ConditionOperations<U extends DynamoDBItem> {
+    private operations;
+    private item;
+    private args;
+    constructor(operations: Transaction["operations"], item: DynamoDBItemKey, args: Partial<ConditionOperation["args"]> & {
+        TableName: string;
+    });
+    matches({ expression, values, }: {
+        expression: string;
+        values: Partial<U> & Record<string, any>;
+    }): void;
+}
+type SetReferencesParams<U extends DynamoDBItem> = TypedParams<U, DynamoDBReference, DynamoDBItemKey> & TypedParams<U, Set<DynamoDBReference>, DynamoDBItemKey[] | Set<DynamoDBItemKey>> & NestedParams<DynamoDBItemKey | DynamoDBItemKey[] | Set<DynamoDBItemKey>>;
+export {};

package/dist/transactions/operations.js

@@ -0,0 +1,148 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConditionOperations = exports.UpdateOperations = exports.CreateOperations = void 0;
+const lib_1 = require("../lib");
+const references_1 = require("./references");
+class CreateOperations {
+    operation;
+    transaction;
+    constructor(operation, transaction) {
+        this.operation = operation;
+        this.transaction = transaction;
+    }
+    setReferences(refs) {
+        Object.entries(arraysToSets(refs)).forEach(([attributeName, ref]) => {
+            if (!ref)
+                return;
+            const refArgs = {
+                item: this.operation.item,
+                onAttribute: attributeName,
+            };
+            const refData = ref instanceof Set
+                ? [...ref].map((references) => (0, references_1.createReference)({ references, ...refArgs }, this.transaction))
+                : (0, references_1.createReference)({ references: ref, ...refArgs }, this.transaction);
+            const parts = attributeName.split(".");
+            parts.reduce((acc, part, index) => {
+                if (index === parts.length - 1) {
+                    acc[part] = refData;
+                }
+                else {
+                    acc[part] = acc[part] || {};
+                    return acc[part];
+                }
+            }, this.operation.item);
+        });
+    }
+}
+exports.CreateOperations = CreateOperations;
+class UpdateOperations {
+    operation;
+    transaction;
+    constructor(operation, transaction) {
+        this.operation = operation;
+        this.transaction = transaction;
+    }
+    setReferences(refs) {
+        Object.entries(arraysToSets(refs)).forEach(([attributeName, ref]) => {
+            if (!ref)
+                return;
+            const refArgs = {
+                item: this.operation.item,
+                onAttribute: attributeName,
+            };
+            this.operation.actions.push({
+                _type: "set",
+                values: {
+                    [attributeName]: ref instanceof Set
+                        ? [...ref].map((references) => (0, references_1.createReference)({ references, ...refArgs }, this.transaction))
+                        : (0, references_1.createReference)({ references: ref, ...refArgs }, this.transaction),
+                },
+            });
+        });
+    }
+    set(values) {
+        if (Object.keys(values).length === 0)
+            return this;
+        this.operation.actions.push({ _type: "set", values });
+        return this;
+    }
+    adjustNumber(values) {
+        if (Object.keys(values).length === 0)
+            return this;
+        this.operation.actions.push({ _type: "add", values });
+        return this;
+    }
+    removeAttributes(...attributes) {
+        if (attributes.length === 0)
+            return this;
+        this.operation.actions.push({ _type: "remove", attributes });
+        return this;
+    }
+    addItemsToSet(values) {
+        if (Object.keys(values).length === 0)
+            return this;
+        this.operation.actions.push({
+            _type: "add",
+            values: arraysToSets(values),
+        });
+        return this;
+    }
+    deleteItemsFromSet(values) {
+        if (Object.keys(values).length === 0)
+            return this;
+        this.operation.actions.push({
+            _type: "delete",
+            values: arraysToSets(values),
+        });
+        return this;
+    }
+    onCondition({ expression, values, }) {
+        this.operation.args = {
+            ...this.operation.args,
+            ConditionExpression: expression,
+            ExpressionAttributeNames: (0, lib_1.getAttributeNames)(values),
+            ExpressionAttributeValues: Object.keys(values).reduce((acc, keyName) => {
+                acc[`:${keyName}`] = values[keyName];
+                return acc;
+            }, {}),
+        };
+    }
+}
+exports.UpdateOperations = UpdateOperations;
+class ConditionOperations {
+    operations;
+    item;
+    args;
+    constructor(operations, item, args) {
+        this.operations = operations;
+        this.item = item;
+        this.args = args;
+    }
+    matches({ expression, values, }) {
+        if (Object.keys(values).length === 0) {
+            throw new Error("[@moicky/dynamodb]: No values in ConditionCheck provided");
+        }
+        const itemKey = (0, lib_1.getItemKey)(this.item, this.args);
+        this.operations[itemKey] = {
+            _type: "condition",
+            item: this.item,
+            args: {
+                ConditionExpression: expression,
+                ExpressionAttributeNames: (0, lib_1.getAttributeNames)(values),
+                ExpressionAttributeValues: (0, lib_1.getAttributeValues)(values),
+                ...this.args,
+            },
+        };
+    }
+}
+exports.ConditionOperations = ConditionOperations;
+const arraysToSets = (values) => {
+    return Object.entries(values).reduce((acc, [key, value]) => ({
+        ...acc,
+        [key]: value instanceof Set
+            ? value
+            : Array.isArray(value)
+                ? new Set(value)
+                : value,
+    }), {});
+};

package/dist/transactions/references/index.d.ts

@@ -0,0 +1,21 @@
+import { Transaction } from "..";
+import { DynamoDBItem } from "../../types";
+import { DynamoDBItemKey, ItemWithKey } from "../types";
+import { DynamoDBReference, ReferenceMetadata, ResolvedItem } from "./types";
+export declare const createReference: (ref: Pick<ReferenceMetadata, "item" | "references" | "onAttribute">, transaction: Transaction) => DynamoDBReference;
+export declare const createCustomReference: (baseItem: DynamoDBItemKey, references: DynamoDBItemKey, onAttribute?: string) => Promise<{
+    PK: "dynamodb:reference";
+    SK: `${string}-${string}-${string}-${string}-${string}`;
+    item: {
+        SK: string | number;
+        PK: string;
+    };
+    references: {
+        SK: string | number;
+        PK: string;
+    };
+    onAttribute: string;
+}>;
+export declare const resolveReferences: <T extends DynamoDBItem>(item: T) => Promise<ResolvedItem<T>>;
+export declare const getDependencies: (item: ItemWithKey) => Promise<ReferenceMetadata[]>;
+export declare const getResolvedDependencies: <T extends ItemWithKey = ItemWithKey>(item: ItemWithKey) => Promise<T[]>;

package/dist/transactions/references/index.js

@@ -0,0 +1,111 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getResolvedDependencies = exports.getDependencies = exports.resolveReferences = exports.createCustomReference = exports.createReference = void 0;
+const crypto_1 = require("crypto");
+const operations_1 = require("../../operations");
+const createReference = (ref, transaction) => {
+    const { item, references, onAttribute } = ref;
+    const referenceKey = {
+        PK: references.PK,
+        ...(references.SK && { SK: references.SK }),
+    };
+    const referenceItem = {
+        PK: "dynamodb:reference",
+        SK: (0, crypto_1.randomUUID)(),
+        item: {
+            PK: item.PK,
+            ...(item.SK && { SK: item.SK }),
+        },
+        references: referenceKey,
+        onAttribute,
+    };
+    transaction.create(referenceItem);
+    return {
+        _type: "dynamodb:reference",
+        _target: referenceKey,
+        _refId: referenceItem.SK,
+    };
+};
+exports.createReference = createReference;
+const itemToStringKey = (item) => `${item.PK}#|#${item.SK}`;
+const getRefsToResolve = (item) => {
+    const refs = [];
+    if (!item)
+        return refs;
+    if (typeof item !== "object")
+        return refs;
+    if (item?._type === "dynamodb:reference")
+        return [item?._target];
+    for (const value of Object.values(item)) {
+        if (typeof value === "object") {
+            if (value instanceof Set || Array.isArray(value)) {
+                refs.push(...[...value].map((v) => getRefsToResolve(v)).flat());
+            }
+            else if (value?._type === "dynamodb:reference") {
+                refs.push(value?._target);
+            }
+            else {
+                refs.push(...getRefsToResolve(value));
+            }
+        }
+    }
+    return refs;
+};
+const injectRefs = (item, refs) => {
+    if (!item)
+        return item;
+    if (typeof item !== "object")
+        return item;
+    if (item?._type === "dynamodb:reference") {
+        return refs[itemToStringKey(item._target)];
+    }
+    for (const [key, value] of Object.entries(item)) {
+        if (typeof value === "object") {
+            if (value instanceof Set || Array.isArray(value)) {
+                item[key] = new Set([...value].map((v) => injectRefs(v, refs)));
+            }
+            else if (value?._type === "dynamodb:reference") {
+                item[key] = refs[itemToStringKey(value._target)];
+            }
+            else {
+                item[key] = injectRefs(value, refs);
+            }
+        }
+    }
+    return item;
+};
+const createCustomReference = async (baseItem, references, onAttribute) => (0, operations_1.putItem)({
+    PK: "dynamodb:reference",
+    SK: (0, crypto_1.randomUUID)(),
+    item: {
+        PK: baseItem.PK,
+        ...(baseItem.SK && { SK: baseItem.SK }),
+    },
+    references: {
+        PK: references.PK,
+        ...(references.SK && { SK: references.SK }),
+    },
+    onAttribute: onAttribute || "",
+}, { ReturnValues: "ALL_NEW" });
+exports.createCustomReference = createCustomReference;
+const resolveReferences = async (item) => {
+    const resolvedItem = structuredClone(item);
+    let refs = getRefsToResolve(item);
+    if (!refs.length)
+        return item;
+    const fetchedRefs = await (0, operations_1.getItems)(refs).then((items) => items.reduce((acc, item) => ({ ...acc, [itemToStringKey(item)]: item }), {}));
+    return injectRefs(resolvedItem, fetchedRefs);
+};
+exports.resolveReferences = resolveReferences;
+const getDependencies = async (item) => (0, operations_1.queryAllItems)("#PK = :PK", {
+    PK: "dynamodb:reference",
+    references: {
+        PK: item.PK,
+        ...(item.SK && { SK: item.SK }),
+    },
+}, { FilterExpression: "#references = :references" });
+exports.getDependencies = getDependencies;
+const getResolvedDependencies = async (item) => (0, exports.getDependencies)(item).then((refs) => (0, operations_1.getItems)(refs
+    .map(({ item }) => item)
+    .filter((item, index, array) => array.findIndex((i) => i.SK === item.SK) === index)).then((items) => items.filter(Boolean)));
+exports.getResolvedDependencies = getResolvedDependencies;

package/dist/transactions/references/types.d.ts

@@ -0,0 +1,21 @@
+import { DynamoDBItem } from "../../types";
+import { DynamoDBItemKey, ItemWithKey } from "../types";
+export type DynamoDBReference<T extends ItemWithKey = ItemWithKey> = T extends any[] ? never : {
+    _type: "dynamodb:reference";
+    _target: T;
+    _refId: ReferenceMetadata["SK"];
+};
+export type ResolvedItem<T extends DynamoDBItem> = {
+    [Key in keyof T]: NonNullable<T[Key]> extends DynamoDBReference ? T[Key]["_target"] | undefined : NonNullable<T[Key]> extends Set<DynamoDBReference<infer T>> ? Set<T | undefined> : T[Key] extends object ? ResolvedItem<T[Key]> : T[Key];
+};
+export type WithoutReferences<T extends DynamoDBItem> = {
+    [Key in keyof T as NonNullable<T[Key]> extends DynamoDBReference | Set<DynamoDBReference> ? never : Key]: T[Key] extends object ? WithoutReferences<T[Key]> : T[Key];
+};
+export type ReferenceTo<T extends ItemWithKey> = T extends any[] ? void : DynamoDBReference<T>;
+export type ReferenceMetadata = {
+    PK: "dynamodb:reference";
+    SK: string;
+    item: DynamoDBItemKey;
+    references: DynamoDBItemKey;
+    onAttribute: string;
+};

package/dist/transactions/references/types.js

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

package/dist/transactions/types.d.ts

@@ -0,0 +1,54 @@
+import { ConditionCheck, Delete, Put, Update } from "@aws-sdk/client-dynamodb";
+import { DynamoDBItem } from "../types";
+export type DynamoDBItemKey = {
+    PK: string;
+    SK?: string | number | undefined;
+};
+export type ItemWithKey = DynamoDBItem & DynamoDBItemKey;
+export type WithoutKey<T> = Omit<T, keyof DynamoDBItemKey>;
+export type OnlyKey<T extends DynamoDBItemKey> = Pick<T, keyof DynamoDBItemKey>;
+export type Prettify<T> = {
+    [key in keyof T]: T[key];
+} & {};
+export type CreateOperation = {
+    _type: "create";
+    item: ItemWithKey;
+    args?: Omit<Put, "Item">;
+};
+export type UpdateOperation = {
+    _type: "update";
+    item: DynamoDBItemKey;
+    actions: Array<UpdateAction>;
+    args?: Omit<Update, "Key" | "UpdateExpression">;
+};
+export type DeleteOperation = {
+    _type: "delete";
+    item: DynamoDBItemKey;
+    args?: Omit<Delete, "Key">;
+};
+export type ConditionOperation = {
+    _type: "condition";
+    item: DynamoDBItemKey;
+    args?: Omit<ConditionCheck, "Key">;
+};
+export type UpdateAction = {
+    _type: "set";
+    values: Record<string, any>;
+} | {
+    _type: "remove";
+    attributes: string[];
+} | {
+    _type: "add";
+    values: Record<string, number | any[]>;
+} | {
+    _type: "delete";
+    values: Record<string, any[]>;
+};
+export type ItemOperation = CreateOperation | UpdateOperation | DeleteOperation | ConditionOperation;
+export type TypedParams<T extends DynamoDBItem, ValueType, ParamType = ValueType> = {
+    [Key in keyof T as NonNullable<T[Key]> extends ValueType ? Key : never]?: ParamType;
+};
+export type NestedParams<T = any> = Record<`${string}.${string}`, T>;
+export type NestedTypedParams<T extends DynamoDBItem, ValueType, ParamType = ValueType> = TypedParams<T, ValueType, ParamType> & NestedParams<ParamType>;
+export type DynamoDBSetMember = number | string | undefined;
+export type DynamoDBSet = Set<DynamoDBSetMember>;

package/dist/transactions/types.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moicky/dynamodb",
-  "version": "2.4.6",
+  "version": "2.5.1",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "description": "Contains a collection of convenience functions for working with AWS DynamoDB",

package/readme.md

@@ -452,7 +452,7 @@ const result = await client
   .then((result) => unmarshall(result.Attributes));
 
 // With helpers
-import { updateItem } from "@aws-sdk/lib-dynamodb";
+import { updateItem } from "@moicky/dynamodb";
 
 const result = await updateItem(
   { PK: "User/1", SK: "Book/1" },