dyno-table 0.1.7 → 0.2.0-0

package/dist/builders/transaction-builder.d.ts

@@ -0,0 +1,511 @@
+import { TransactWriteCommandInput } from '@aws-sdk/lib-dynamodb';
+import { P as PrimaryKeyWithoutExpression, C as Condition } from '../conditions--ld9a78i.js';
+import { a as PutCommandParams, D as DeleteCommandParams, U as UpdateCommandParams, C as ConditionCheckCommandParams } from '../builder-types-C_PDZhnP.js';
+import { DynamoItem } from '../types.js';
+
+/**
+ * Configuration options for DynamoDB transactions.
+ */
+interface TransactionOptions {
+    /** Unique identifier for the transaction request (idempotency token) */
+    clientRequestToken?: string;
+    /** Level of consumed capacity details to return */
+    returnConsumedCapacity?: "INDEXES" | "TOTAL" | "NONE";
+    /** Whether to return item collection metrics */
+    returnItemCollectionMetrics?: "SIZE" | "NONE";
+}
+/**
+ * Configuration for table indexes used in duplicate detection.
+ * Defines the key structure for checking uniqueness constraints.
+ */
+interface IndexConfig {
+    /** The partition key attribute name */
+    partitionKey: string;
+    /** Optional sort key attribute name */
+    sortKey?: string;
+}
+/**
+ * Function type for executing DynamoDB transaction operations.
+ * @param params - The complete transaction command input
+ * @returns A promise that resolves when the transaction completes
+ */
+type TransactionExecutor = (params: TransactWriteCommandInput) => Promise<void>;
+/**
+ * Builder for creating and executing DynamoDB transactions.
+ * Use this builder when you need to:
+ * - Perform multiple operations atomically
+ * - Ensure data consistency across operations
+ * - Implement complex business logic that requires atomic updates
+ * - Prevent duplicate items across tables
+ *
+ * The builder supports:
+ * - Put operations (insert/replace items)
+ * - Delete operations
+ * - Update operations
+ * - Condition checks
+ * - Duplicate detection
+ * - Transaction-wide options
+ *
+ * @example
+ * ```typescript
+ * // Create a transaction with multiple operations
+ * const transaction = new TransactionBuilder(executor, {
+ *   partitionKey: 'id',
+ *   sortKey: 'type'
+ * });
+ *
+ * // Add a new order
+ * transaction.put('orders', {
+ *   orderId: '123',
+ *   status: 'PENDING'
+ * });
+ *
+ * // Update inventory with condition
+ * transaction.update(
+ *   'inventory',
+ *   { productId: 'ABC' },
+ *   'set quantity = quantity - :amount',
+ *   { ':amount': 1 },
+ *   op => op.gte('quantity', 1)
+ * );
+ *
+ * // Execute the transaction atomically
+ * await transaction.execute();
+ * ```
+ *
+ * Note: DynamoDB transactions have some limitations:
+ * - Maximum 25 operations per transaction
+ * - All operations must be in the same AWS region
+ * - Cannot include table scans or queries
+ */
+declare class TransactionBuilder {
+    private items;
+    private options;
+    private indexConfig;
+    private readonly executor;
+    constructor(executor: TransactionExecutor, indexConfig: IndexConfig);
+    /**
+     * Checks if an item with the same primary key already exists in the transaction
+     * @private
+     */
+    private checkForDuplicateItem;
+    createKeyForPrimaryIndex(key: PrimaryKeyWithoutExpression): {
+        [x: string]: string;
+    };
+    /**
+     * Adds a put operation to the transaction.
+     * Use this method when you need to:
+     * - Insert new items as part of a transaction
+     * - Replace existing items atomically
+     * - Ensure items meet certain conditions before insertion
+     *
+     * The method automatically checks for duplicate items within the transaction
+     * to prevent multiple operations on the same item.
+     *
+     * @example
+     * ```typescript
+     * // Simple put operation
+     * transaction.put('orders', {
+     *   orderId: '123',
+     *   status: 'PENDING',
+     *   amount: 100
+     * });
+     *
+     * // Conditional put operation
+     * transaction.put(
+     *   'inventory',
+     *   { productId: 'ABC', quantity: 50 },
+     *   op => op.attributeNotExists('productId')
+     * );
+     *
+     * // Put with complex condition
+     * transaction.put(
+     *   'users',
+     *   { userId: '123', status: 'ACTIVE' },
+     *   op => op.and([
+     *     op.attributeNotExists('userId'),
+     *     op.beginsWith('status', 'ACTIVE')
+     *   ])
+     * );
+     * ```
+     *
+     * @param tableName - The name of the DynamoDB table
+     * @param item - The item to put into the table
+     * @param condition - Optional condition that must be satisfied
+     * @returns The transaction builder for method chaining
+     * @throws {Error} If a duplicate item is detected in the transaction
+     */
+    put<T extends DynamoItem>(tableName: string, item: T, condition?: Condition): this;
+    /**
+     * Adds a pre-configured put operation to the transaction.
+     * Use this method when you need to:
+     * - Reuse put commands from PutBuilder
+     * - Add complex put operations with pre-configured parameters
+     * - Integrate with existing put command configurations
+     *
+     * This method is particularly useful when working with PutBuilder
+     * to maintain consistency in put operations across your application.
+     *
+     * @example
+     * ```typescript
+     * // Create a put command with PutBuilder
+     * const putCommand = new PutBuilder(executor, newItem, 'users')
+     *   .condition(op => op.attributeNotExists('userId'))
+     *   .toDynamoCommand();
+     *
+     * // Add the command to the transaction
+     * transaction.putWithCommand(putCommand);
+     * ```
+     *
+     * @param command - The complete put command configuration
+     * @returns The transaction builder for method chaining
+     * @throws {Error} If a duplicate item is detected in the transaction
+     * @see PutBuilder for creating put commands
+     */
+    putWithCommand(command: PutCommandParams): TransactionBuilder;
+    /**
+     * Adds a delete operation to the transaction.
+     * Use this method when you need to:
+     * - Remove items as part of a transaction
+     * - Conditionally delete items
+     * - Ensure items exist before deletion
+     *
+     * The method automatically checks for duplicate items within the transaction
+     * to prevent multiple operations on the same item.
+     *
+     * @example
+     * ```typescript
+     * // Simple delete operation
+     * transaction.delete('orders', {
+     *   pk: 'ORDER#123',
+     *   sk: 'METADATA'
+     * });
+     *
+     * // Conditional delete operation
+     * transaction.delete(
+     *   'users',
+     *   { pk: 'USER#123' },
+     *   op => op.eq('status', 'INACTIVE')
+     * );
+     *
+     * // Delete with complex condition
+     * transaction.delete(
+     *   'products',
+     *   { pk: 'PROD#ABC' },
+     *   op => op.and([
+     *     op.eq('status', 'DRAFT'),
+     *     op.lt('version', 5)
+     *   ])
+     * );
+     * ```
+     *
+     * @param tableName - The name of the DynamoDB table
+     * @param key - The primary key of the item to delete
+     * @param condition - Optional condition that must be satisfied
+     * @returns The transaction builder for method chaining
+     * @throws {Error} If a duplicate item is detected in the transaction
+     */
+    delete(tableName: string, key: PrimaryKeyWithoutExpression, condition?: Condition): TransactionBuilder;
+    /**
+     * Adds a pre-configured delete operation to the transaction.
+     * Use this method when you need to:
+     * - Reuse delete commands from DeleteBuilder
+     * - Add complex delete operations with pre-configured parameters
+     * - Integrate with existing delete command configurations
+     *
+     * This method is particularly useful when working with DeleteBuilder
+     * to maintain consistency in delete operations across your application.
+     *
+     * @example
+     * ```typescript
+     * // Create a delete command with DeleteBuilder
+     * const deleteCommand = new DeleteBuilder(executor, 'users', { pk: 'USER#123' })
+     *   .condition(op => op.and([
+     *     op.attributeExists('pk'),
+     *     op.eq('status', 'INACTIVE')
+     *   ]))
+     *   .toDynamoCommand();
+     *
+     * // Add the command to the transaction
+     * transaction.deleteWithCommand(deleteCommand);
+     * ```
+     *
+     * @param command - The complete delete command configuration
+     * @returns The transaction builder for method chaining
+     * @throws {Error} If a duplicate item is detected in the transaction
+     * @see DeleteBuilder for creating delete commands
+     */
+    deleteWithCommand(command: DeleteCommandParams): this;
+    /**
+     * Adds an update operation to the transaction.
+     * Use this method when you need to:
+     * - Modify existing items as part of a transaction
+     * - Update multiple attributes atomically
+     * - Apply conditional updates
+     * - Perform complex attribute manipulations
+     *
+     * The method supports all DynamoDB update expressions:
+     * - SET: Modify or add attributes
+     * - REMOVE: Delete attributes
+     * - ADD: Update numbers and sets
+     * - DELETE: Remove elements from a set
+     *
+     * @example
+     * ```typescript
+     * // Simple update
+     * transaction.update(
+     *   'orders',
+     *   { pk: 'ORDER#123' },
+     *   'SET #status = :status',
+     *   { '#status': 'status' },
+     *   { ':status': 'PROCESSING' }
+     * );
+     *
+     * // Complex update with multiple operations
+     * transaction.update(
+     *   'products',
+     *   { pk: 'PROD#ABC' },
+     *   'SET #qty = #qty - :amount, #status = :status REMOVE #oldAttr',
+     *   { '#qty': 'quantity', '#status': 'status', '#oldAttr': 'deprecated_field' },
+     *   { ':amount': 1, ':status': 'LOW_STOCK' }
+     * );
+     *
+     * // Conditional update
+     * transaction.update(
+     *   'users',
+     *   { pk: 'USER#123' },
+     *   'SET #lastLogin = :now',
+     *   { '#lastLogin': 'lastLoginDate' },
+     *   { ':now': new Date().toISOString() },
+     *   op => op.attributeExists('pk')
+     * );
+     * ```
+     *
+     * @param tableName - The name of the DynamoDB table
+     * @param key - The primary key of the item to update
+     * @param updateExpression - The update expression (SET, REMOVE, ADD, DELETE)
+     * @param expressionAttributeNames - Map of attribute name placeholders to actual names
+     * @param expressionAttributeValues - Map of value placeholders to actual values
+     * @param condition - Optional condition that must be satisfied
+     * @returns The transaction builder for method chaining
+     * @throws {Error} If a duplicate item is detected in the transaction
+     */
+    update<T extends DynamoItem>(tableName: string, key: PrimaryKeyWithoutExpression, updateExpression: string, expressionAttributeNames?: Record<string, string>, expressionAttributeValues?: Record<string, unknown>, condition?: Condition): this;
+    /**
+     * Adds a pre-configured update operation to the transaction.
+     * Use this method when you need to:
+     * - Reuse update commands from UpdateBuilder
+     * - Add complex update operations with pre-configured parameters
+     * - Integrate with existing update command configurations
+     *
+     * This method is particularly useful when working with UpdateBuilder
+     * to maintain consistency in update operations across your application.
+     *
+     * @example
+     * ```typescript
+     * // Create an update command with UpdateBuilder
+     * const updateCommand = new UpdateBuilder(executor, 'inventory', { pk: 'PROD#ABC' })
+     *   .set('quantity', ':qty')
+     *   .set('lastUpdated', ':now')
+     *   .values({
+     *     ':qty': 100,
+     *     ':now': new Date().toISOString()
+     *   })
+     *   .condition(op => op.gt('quantity', 0))
+     *   .toDynamoCommand();
+     *
+     * // Add the command to the transaction
+     * transaction.updateWithCommand(updateCommand);
+     * ```
+     *
+     * @param command - The complete update command configuration
+     * @returns The transaction builder for method chaining
+     * @throws {Error} If a duplicate item is detected in the transaction
+     * @see UpdateBuilder for creating update commands
+     */
+    updateWithCommand(command: UpdateCommandParams): TransactionBuilder;
+    /**
+     * Adds a condition check operation to the transaction.
+     * Use this method when you need to:
+     * - Validate item state without modifying it
+     * - Ensure data consistency across tables
+     * - Implement complex business rules
+     * - Verify preconditions for other operations
+     *
+     * Condition checks are particularly useful for:
+     * - Implementing optimistic locking
+     * - Ensuring referential integrity
+     * - Validating business rules atomically
+     *
+     * @example
+     * ```typescript
+     * // Check if order is in correct state
+     * transaction.conditionCheck(
+     *   'orders',
+     *   { pk: 'ORDER#123' },
+     *   op => op.eq('status', 'PENDING')
+     * );
+     *
+     * // Complex condition check
+     * transaction.conditionCheck(
+     *   'inventory',
+     *   { pk: 'PROD#ABC' },
+     *   op => op.and([
+     *     op.gt('quantity', 0),
+     *     op.eq('status', 'ACTIVE'),
+     *     op.attributeExists('lastRestockDate')
+     *   ])
+     * );
+     *
+     * // Check with multiple attributes
+     * transaction.conditionCheck(
+     *   'users',
+     *   { pk: 'USER#123' },
+     *   op => op.or([
+     *     op.eq('status', 'PREMIUM'),
+     *     op.gte('credits', 100)
+     *   ])
+     * );
+     * ```
+     *
+     * @param tableName - The name of the DynamoDB table
+     * @param key - The primary key of the item to check
+     * @param condition - The condition that must be satisfied
+     * @returns The transaction builder for method chaining
+     * @throws {Error} If a duplicate item is detected in the transaction
+     * @throws {Error} If condition expression generation fails
+     */
+    conditionCheck(tableName: string, key: PrimaryKeyWithoutExpression, condition: Condition): TransactionBuilder;
+    /**
+     * Adds a pre-configured condition check operation to the transaction.
+     * Use this method when you need to:
+     * - Reuse condition checks from ConditionCheckBuilder
+     * - Add complex condition checks with pre-configured parameters
+     * - Integrate with existing condition check configurations
+     *
+     * This method is particularly useful when working with ConditionCheckBuilder
+     * to maintain consistency in condition checks across your application.
+     *
+     * @example
+     * ```typescript
+     * // Create a condition check with ConditionCheckBuilder
+     * const checkCommand = new ConditionCheckBuilder('inventory', { pk: 'PROD#ABC' })
+     *   .condition(op => op.and([
+     *     op.between('quantity', 10, 100),
+     *     op.beginsWith('category', 'ELECTRONICS'),
+     *     op.attributeExists('lastAuditDate')
+     *   ]))
+     *   .toDynamoCommand();
+     *
+     * // Add the command to the transaction
+     * transaction.conditionCheckWithCommand(checkCommand);
+     * ```
+     *
+     * @param command - The complete condition check command configuration
+     * @returns The transaction builder for method chaining
+     * @throws {Error} If a duplicate item is detected in the transaction
+     * @see ConditionCheckBuilder for creating condition check commands
+     */
+    conditionCheckWithCommand(command: ConditionCheckCommandParams): TransactionBuilder;
+    /**
+     * Sets options for the transaction execution.
+     * Use this method when you need to:
+     * - Enable idempotent transactions
+     * - Track consumed capacity
+     * - Monitor item collection metrics
+     *
+     * @example
+     * ```typescript
+     * // Enable idempotency and capacity tracking
+     * transaction.withOptions({
+     *   clientRequestToken: 'unique-request-id-123',
+     *   returnConsumedCapacity: 'TOTAL'
+     * });
+     *
+     * // Track item collection metrics
+     * transaction.withOptions({
+     *   returnItemCollectionMetrics: 'SIZE'
+     * });
+     * ```
+     *
+     * Note: ClientRequestToken can be used to make transactions idempotent,
+     * ensuring the same transaction is not executed multiple times.
+     *
+     * @param options - Configuration options for the transaction
+     * @returns The transaction builder for method chaining
+     */
+    withOptions(options: TransactionOptions): TransactionBuilder;
+    /**
+     * Gets a human-readable representation of the transaction items.
+     * Use this method when you need to:
+     * - Debug complex transactions
+     * - Verify operation parameters
+     * - Log transaction details
+     * - Troubleshoot condition expressions
+     *
+     * The method resolves all expression placeholders with their actual values,
+     * making it easier to understand the transaction's operations.
+     *
+     * @example
+     * ```typescript
+     * // Add multiple operations
+     * transaction
+     *   .put('orders', { orderId: '123', status: 'PENDING' })
+     *   .update('inventory',
+     *     { productId: 'ABC' },
+     *     'SET quantity = quantity - :amount',
+     *     undefined,
+     *     { ':amount': 1 }
+     *   );
+     *
+     * // Debug the transaction
+     * const debugInfo = transaction.debug();
+     * console.log('Transaction operations:', debugInfo);
+     * ```
+     *
+     * @returns An array of readable representations of the transaction items
+     */
+    debug(): DynamoItem[];
+    /**
+     * Executes all operations in the transaction atomically.
+     * Use this method when you need to:
+     * - Perform multiple operations atomically
+     * - Ensure all-or-nothing execution
+     * - Maintain data consistency across operations
+     *
+     * The transaction will only succeed if all operations succeed.
+     * If any operation fails, the entire transaction is rolled back.
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   // Build and execute transaction
+     *   await transaction
+     *     .put('orders', newOrder)
+     *     .update('inventory',
+     *       { productId: 'ABC' },
+     *       'SET quantity = quantity - :qty',
+     *       undefined,
+     *       { ':qty': 1 }
+     *     )
+     *     .conditionCheck('products',
+     *       { productId: 'ABC' },
+     *       op => op.eq('status', 'ACTIVE')
+     *     )
+     *     .execute();
+     *
+     *   console.log('Transaction completed successfully');
+     * } catch (error) {
+     *   // Handle transaction failure
+     *   console.error('Transaction failed:', error);
+     * }
+     * ```
+     *
+     * @throws {Error} If no transaction items are specified
+     * @throws {Error} If any operation in the transaction fails
+     * @returns A promise that resolves when the transaction completes
+     */
+    execute(): Promise<void>;
+}
+
+export { TransactionBuilder, type TransactionExecutor, type TransactionOptions };