dyno-table 0.2.0-0 → 1.0.0-alpha.1

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

@@ -1,511 +0,0 @@
-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 };