captify 0.1.15

package/dist/services/dynamodb/services/dynamodb.service.js

@@ -0,0 +1,816 @@
+var __await = (this && this.__await) || function (v) { return this instanceof __await ? (this.v = v, this) : new __await(v); }
+var __asyncGenerator = (this && this.__asyncGenerator) || function (thisArg, _arguments, generator) {
+    if (!Symbol.asyncIterator) throw new TypeError("Symbol.asyncIterator is not defined.");
+    var g = generator.apply(thisArg, _arguments || []), i, q = [];
+    return i = Object.create((typeof AsyncIterator === "function" ? AsyncIterator : Object).prototype), verb("next"), verb("throw"), verb("return", awaitReturn), i[Symbol.asyncIterator] = function () { return this; }, i;
+    function awaitReturn(f) { return function (v) { return Promise.resolve(v).then(f, reject); }; }
+    function verb(n, f) { if (g[n]) { i[n] = function (v) { return new Promise(function (a, b) { q.push([n, v, a, b]) > 1 || resume(n, v); }); }; if (f) i[n] = f(i[n]); } }
+    function resume(n, v) { try { step(g[n](v)); } catch (e) { settle(q[0][3], e); } }
+    function step(r) { r.value instanceof __await ? Promise.resolve(r.value.v).then(fulfill, reject) : settle(q[0][2], r); }
+    function fulfill(value) { resume("next", value); }
+    function reject(value) { resume("throw", value); }
+    function settle(f, v) { if (f(v), q.shift(), q.length) resume(q[0][0], q[0][1]); }
+};
+import { BaseAwsService } from "../../shared/services";
+import { invariant } from "../../../utils";
+import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
+import { BatchGetCommand, BatchWriteCommand, DeleteCommand, DynamoDBDocumentClient, GetCommand, PutCommand, QueryCommand, ScanCommand, TransactGetCommand, TransactWriteCommand, UpdateCommand, } from "@aws-sdk/lib-dynamodb";
+import { DYNAMODB_BATCH_WRITE_CHUNK_SIZE, DYNAMODB_ERROR_MESSAGES } from "../constants";
+import { classifyDynamoDbError } from "../errors";
+import { validateItemSize, validateKey, validateTableName } from "../utilities";
+/**
+ * Generic DynamoDB service that provides type-safe operations for any DynamoDB table.
+ *
+ * Features:
+ * - Generic table handling with per-operation table name override
+ * - Automatic retry with exponential backoff for transient errors
+ * - Input validation (table names, item sizes, keys)
+ * - Error classification (retryable vs fatal errors)
+ * - Transaction support (ACID operations)
+ * - Batch operations (get, write)
+ * - Pagination helpers (async generators)
+ * - Conditional operations (putIfNotExists, updateIfExists)
+ *
+ * @example Basic usage with default table
+ * ```typescript
+ * const service = DynamoDbService.create({
+ *   region: 'us-east-1',
+ *   accessKeyId: 'YOUR_ACCESS_KEY',
+ *   secretAccessKey: 'YOUR_SECRET_KEY',
+ *   tableName: 'users'
+ * });
+ *
+ * // Put item
+ * await service.putItem({ id: '123', name: 'John' });
+ *
+ * // Get item
+ * const result = await service.getItem({ id: '123' });
+ * ```
+ *
+ * @example Multi-table usage with per-operation override
+ * ```typescript
+ * const service = DynamoDbService.create({
+ *   region: 'us-east-1',
+ *   accessKeyId: 'YOUR_ACCESS_KEY',
+ *   secretAccessKey: 'YOUR_SECRET_KEY',
+ *   tableName: 'default-table' // optional default
+ * });
+ *
+ * // Use different tables per operation
+ * await service.putItem({ id: '1' }, { tableName: 'users' });
+ * await service.putItem({ id: '2' }, { tableName: 'products' });
+ * ```
+ *
+ * @example Pagination with async generators
+ * ```typescript
+ * for await (const page of service.queryAllPages({
+ *   KeyConditionExpression: 'userId = :userId',
+ *   ExpressionAttributeValues: { ':userId': '123' }
+ * })) {
+ *   console.log(`Got ${page.items.length} items`);
+ *   // Process page.items
+ * }
+ * ```
+ *
+ * @example Transactions
+ * ```typescript
+ * await service.transactWrite([
+ *   { operation: 'put', item: { id: '1', balance: 100 } },
+ *   { operation: 'update', key: { id: '2' }, updateExpression: 'SET balance = balance - :amount', expressionAttributeValues: { ':amount': 50 } }
+ * ]);
+ * ```
+ */
+export class DynamoDbService extends BaseAwsService {
+    constructor(deps) {
+        super({ logger: deps.logger, serviceName: "dynamodb" });
+        this.client = deps.client;
+        this.defaultTableName = deps.tableName;
+    }
+    classifyError(err) {
+        return classifyDynamoDbError(err);
+    }
+    resolveTableName(tableName) {
+        const resolved = tableName !== null && tableName !== void 0 ? tableName : this.defaultTableName;
+        if (!(resolved === null || resolved === void 0 ? void 0 : resolved.trim())) {
+            throw new Error(DYNAMODB_ERROR_MESSAGES.TABLE_NAME_REQUIRED);
+        }
+        validateTableName(resolved);
+        return resolved;
+    }
+    /**
+     * Get DynamoDB client with user-specific credentials for governance compliance
+     * If userCredentials are provided, creates a new client with those credentials
+     * Otherwise, returns the default service account client
+     */
+    getClientForOperation(userCredentials) {
+        if (!userCredentials) {
+            return this.client;
+        }
+        // Create a new client with user's temporary credentials
+        // This enables IAM-based access control per user
+        const credentials = this.getAwsCredentials(userCredentials);
+        const baseClient = new DynamoDBClient(Object.assign(Object.assign({ region: this.client.config.region }, (this.client.config.endpoint ? { endpoint: this.client.config.endpoint } : {})), (credentials ? { credentials } : {})));
+        return DynamoDBDocumentClient.from(baseClient);
+    }
+    /**
+     * Creates a new DynamoDB service instance with the provided configuration.
+     *
+     * @param config - Configuration object for DynamoDB connection
+     * @param config.region - AWS region (e.g., 'us-east-1')
+     * @param config.accessKeyId - AWS access key ID
+     * @param config.secretAccessKey - AWS secret access key
+     * @param config.tableName - Optional default table name (can be overridden per operation)
+     * @param config.endpoint - Optional custom endpoint (useful for local DynamoDB)
+     * @param logger - Optional logger instance (defaults to LoggerFactory based logger)
+     * @returns A new DynamoDbService instance
+     * @throws Error if required configuration is missing
+     *
+     * @example Creating with default table
+     * ```typescript
+     * const service = DynamoDbService.create({
+     *   region: 'us-east-1',
+     *   accessKeyId: process.env.AWS_ACCESS_KEY_ID,
+     *   secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
+     *   tableName: 'my-table'
+     * });
+     * ```
+     *
+     * @example Creating for multi-table usage
+     * ```typescript
+     * const service = DynamoDbService.create({
+     *   region: 'us-east-1',
+     *   accessKeyId: process.env.AWS_ACCESS_KEY_ID,
+     *   secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY
+     *   // No default table - must specify per operation
+     * });
+     * ```
+     *
+     * @example Local DynamoDB
+     * ```typescript
+     * const service = DynamoDbService.create({
+     *   region: 'local',
+     *   accessKeyId: 'fakeKey',
+     *   secretAccessKey: 'fakeSecret',
+     *   endpoint: 'http://localhost:8000',
+     *   tableName: 'test-table'
+     * });
+     * ```
+     */
+    static create(config, logger) {
+        var _a, _b, _c, _d;
+        invariant((_a = config.tableName) === null || _a === void 0 ? void 0 : _a.trim(), "DynamoDB Table Name is required");
+        invariant((_b = config.region) === null || _b === void 0 ? void 0 : _b.trim(), "AWS Region is required");
+        invariant((_c = config.accessKeyId) === null || _c === void 0 ? void 0 : _c.trim(), "AWS Access Key ID is required");
+        invariant((_d = config.secretAccessKey) === null || _d === void 0 ? void 0 : _d.trim(), "AWS Secret Access Key is required");
+        const clientConfig = {
+            region: config.region,
+            endpoint: config.endpoint,
+            credentials: {
+                accessKeyId: config.accessKeyId,
+                secretAccessKey: config.secretAccessKey,
+            },
+        };
+        const client = new DynamoDBClient(clientConfig);
+        const documentClient = DynamoDBDocumentClient.from(client);
+        const deps = {
+            client: documentClient,
+            logger,
+            tableName: config.tableName,
+        };
+        return new DynamoDbService(deps);
+    }
+    static loadEnvConfig() {
+        return {
+            endpoint: process.env.AWS_ENDPOINT,
+            region: process.env.AWS_REGION,
+            accessKeyId: process.env.AWS_ACCESS_KEY_ID,
+            secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
+        };
+    }
+    static createWithClient(client, tableName, logger) {
+        const deps = {
+            client,
+            logger,
+            tableName,
+        };
+        return new DynamoDbService(deps);
+    }
+    /**
+     * Inserts or replaces an item in the DynamoDB table.
+     * @param item The item to be created or updated.
+     * @param options Optional parameters including table name override and user credentials
+     * @returns The result of the Put operation.
+     */
+    async putItem(item, options) {
+        return this.executeWithRetry(async () => {
+            const tableName = this.resolveTableName(options === null || options === void 0 ? void 0 : options.tableName);
+            validateItemSize(item);
+            const usingUserCredentials = Boolean(options === null || options === void 0 ? void 0 : options.userCredentials);
+            this.logger.info(`Putting item into ${tableName}`, {
+                userCredentials: usingUserCredentials,
+            });
+            const command = new PutCommand({
+                TableName: tableName,
+                Item: item,
+            });
+            const client = this.getClientForOperation(options === null || options === void 0 ? void 0 : options.userCredentials);
+            const result = await client.send(command);
+            this.logger.info(`Successfully put item into ${tableName}`, {
+                userCredentials: usingUserCredentials,
+            });
+            return result;
+        });
+    }
+    /**
+     * Retrieves an item from the DynamoDB table by its primary key.
+     * @param key The primary key of the item to retrieve.
+     * @param options Optional parameters including table name override and user credentials
+     * @returns The result of the Get operation, containing the item if found.
+     */
+    async getItem(key, options) {
+        return this.executeWithRetry(async () => {
+            const tableName = this.resolveTableName(options === null || options === void 0 ? void 0 : options.tableName);
+            validateKey(key);
+            const usingUserCredentials = Boolean(options === null || options === void 0 ? void 0 : options.userCredentials);
+            this.logger.info(`Getting item from ${tableName}`, {
+                userCredentials: usingUserCredentials,
+            });
+            const command = new GetCommand({
+                TableName: tableName,
+                Key: key,
+            });
+            const client = this.getClientForOperation(options === null || options === void 0 ? void 0 : options.userCredentials);
+            const result = await client.send(command);
+            this.logger.info(`Successfully got item from ${tableName}`, {
+                userCredentials: usingUserCredentials,
+            });
+            return result;
+        });
+    }
+    /**
+     * Updates an existing item in the DynamoDB table.
+     * @param key The primary key of the item to update.
+     * @param updateExpression A string that defines the attributes to be updated.
+     * @param expressionAttributeNames Attribute name placeholders
+     * @param expressionAttributeValues A map of values to substitute in the expression.
+     * @param options Optional parameters including table name override and user credentials
+     * @returns The result of the Update operation.
+     */
+    async updateItem(key, updateExpression, expressionAttributeNames, expressionAttributeValues, options) {
+        return this.executeWithRetry(async () => {
+            const tableName = this.resolveTableName(options === null || options === void 0 ? void 0 : options.tableName);
+            validateKey(key);
+            const usingUserCredentials = Boolean(options === null || options === void 0 ? void 0 : options.userCredentials);
+            this.logger.info(`Updating item in ${tableName}`, {
+                userCredentials: usingUserCredentials,
+            });
+            const command = new UpdateCommand({
+                TableName: tableName,
+                Key: key,
+                UpdateExpression: updateExpression,
+                ExpressionAttributeNames: expressionAttributeNames,
+                ExpressionAttributeValues: expressionAttributeValues,
+                ReturnValues: "ALL_NEW",
+            });
+            const client = this.getClientForOperation(options === null || options === void 0 ? void 0 : options.userCredentials);
+            const result = await client.send(command);
+            this.logger.info(`Successfully updated item in ${tableName}`, {
+                userCredentials: usingUserCredentials,
+            });
+            return result;
+        });
+    }
+    /**
+     * Deletes an item from the DynamoDB table by its primary key.
+     * @param key The primary key of the item to delete.
+     * @param options Optional parameters including table name override and user credentials
+     * @returns The result of the Delete operation.
+     */
+    async deleteItem(key, options) {
+        return this.executeWithRetry(async () => {
+            const tableName = this.resolveTableName(options === null || options === void 0 ? void 0 : options.tableName);
+            validateKey(key);
+            const usingUserCredentials = Boolean(options === null || options === void 0 ? void 0 : options.userCredentials);
+            this.logger.info(`Deleting item from ${tableName}`, {
+                userCredentials: usingUserCredentials,
+            });
+            const command = new DeleteCommand({
+                TableName: tableName,
+                Key: key,
+            });
+            const client = this.getClientForOperation(options === null || options === void 0 ? void 0 : options.userCredentials);
+            const result = await client.send(command);
+            this.logger.info(`Successfully deleted item from ${tableName}`, {
+                userCredentials: usingUserCredentials,
+            });
+            return result;
+        });
+    }
+    /**
+     * Queries items from the table based on a key condition.
+     * Supports pagination via the `ExclusiveStartKey` parameter.
+     * @param params The parameters for the Query operation, including the key condition and optional filters.
+     * @param options Optional parameters including table name override and user credentials
+     * @returns The result of the Query operation, containing the matching items.
+     */
+    async queryItems(params, options) {
+        return this.executeWithRetry(async () => {
+            const tableName = this.resolveTableName(options === null || options === void 0 ? void 0 : options.tableName);
+            const usingUserCredentials = Boolean(options === null || options === void 0 ? void 0 : options.userCredentials);
+            this.logger.info(`Querying items from ${tableName}`, {
+                userCredentials: usingUserCredentials,
+            });
+            const command = new QueryCommand(Object.assign({ TableName: tableName }, params));
+            const client = this.getClientForOperation(options === null || options === void 0 ? void 0 : options.userCredentials);
+            const result = await client.send(command);
+            this.logger.info(`Successfully queried items from ${tableName}`, {
+                userCredentials: usingUserCredentials,
+            });
+            return result;
+        });
+    }
+    /**
+     * Scans all items in the table.
+     * Supports pagination via the `ExclusiveStartKey` parameter.
+     * @param params The parameters for the Scan operation, including optional filters.
+     * @param options Optional parameters including table name override and user credentials
+     * @returns The result of the Scan operation, containing the scanned items.
+     */
+    async scanItems(params, options) {
+        return this.executeWithRetry(async () => {
+            const tableName = this.resolveTableName(options === null || options === void 0 ? void 0 : options.tableName);
+            const usingUserCredentials = Boolean(options === null || options === void 0 ? void 0 : options.userCredentials);
+            this.logger.info(`Scanning items from ${tableName}`, {
+                userCredentials: usingUserCredentials,
+            });
+            const command = new ScanCommand(Object.assign({ TableName: tableName }, params));
+            const client = this.getClientForOperation(options === null || options === void 0 ? void 0 : options.userCredentials);
+            const result = await client.send(command);
+            this.logger.info(`Successfully scanned items from ${tableName}`, {
+                userCredentials: usingUserCredentials,
+            });
+            return result;
+        });
+    }
+    /**
+     * Async generator that automatically handles pagination for query operations.
+     * Yields items one page at a time until all results are retrieved.
+     * @param params The parameters for the Query operation (excluding ExclusiveStartKey).
+     * @param options Optional parameters including table name override and user credentials
+     * @yields Pages of query results with items, count, and scannedCount
+     * @example
+     * ```typescript
+     * for await (const page of service.queryAllPages({ KeyConditionExpression: '...' })) {
+     *   console.log(`Got ${page.items.length} items`);
+     *   // Process page.items
+     * }
+     * ```
+     */
+    queryAllPages(params, options) {
+        return __asyncGenerator(this, arguments, function* queryAllPages_1() {
+            var _a;
+            const tableName = this.resolveTableName(options === null || options === void 0 ? void 0 : options.tableName);
+            let lastEvaluatedKey;
+            do {
+                const result = yield __await(this.queryItems(Object.assign(Object.assign({}, params), { ExclusiveStartKey: lastEvaluatedKey }), { tableName, userCredentials: options === null || options === void 0 ? void 0 : options.userCredentials }));
+                yield yield __await({
+                    items: (result.Items || []),
+                    count: result.Count || 0,
+                    scannedCount: result.ScannedCount,
+                    lastEvaluatedKey: result.LastEvaluatedKey,
+                    consumed: (_a = result.ConsumedCapacity) === null || _a === void 0 ? void 0 : _a.CapacityUnits,
+                });
+                lastEvaluatedKey = result.LastEvaluatedKey;
+            } while (lastEvaluatedKey);
+        });
+    }
+    /**
+     * Async generator that automatically handles pagination for scan operations.
+     * Yields items one page at a time until all results are retrieved.
+     * @param params The parameters for the Scan operation (excluding ExclusiveStartKey).
+     * @param options Optional parameters including table name override and user credentials
+     * @yields Pages of scan results with items, count, and scannedCount
+     * @example
+     * ```typescript
+     * for await (const page of service.scanAllPages({ FilterExpression: '...' })) {
+     *   console.log(`Got ${page.items.length} items`);
+     *   // Process page.items
+     * }
+     * ```
+     */
+    scanAllPages(params, options) {
+        return __asyncGenerator(this, arguments, function* scanAllPages_1() {
+            var _a;
+            const tableName = this.resolveTableName(options === null || options === void 0 ? void 0 : options.tableName);
+            let lastEvaluatedKey;
+            do {
+                const result = yield __await(this.scanItems(Object.assign(Object.assign({}, params), { ExclusiveStartKey: lastEvaluatedKey }), { tableName, userCredentials: options === null || options === void 0 ? void 0 : options.userCredentials }));
+                yield yield __await({
+                    items: (result.Items || []),
+                    count: result.Count || 0,
+                    scannedCount: result.ScannedCount,
+                    lastEvaluatedKey: result.LastEvaluatedKey,
+                    consumed: (_a = result.ConsumedCapacity) === null || _a === void 0 ? void 0 : _a.CapacityUnits,
+                });
+                lastEvaluatedKey = result.LastEvaluatedKey;
+            } while (lastEvaluatedKey);
+        });
+    }
+    /**
+     * Performs a batch write operation (put or delete) on multiple items.
+     * @param items An array of items to be put or deleted.
+     * @param operation The operation to perform on the items: "put" or "delete" (default: "put").
+     * @param options Optional parameters including table name override and user credentials
+     * @returns The final result of the BatchWrite operation after all retries.
+     * @throws `Error` if the items array is empty.
+     * @throws `Error` if retry attempts are exhausted.
+     */
+    async batchWrite(items, operation = "put", options) {
+        invariant(items.length > 0, "Items must be provided");
+        return this.executeWithRetry(async () => {
+            var _a;
+            const tableName = this.resolveTableName(options === null || options === void 0 ? void 0 : options.tableName);
+            const usingUserCredentials = Boolean(options === null || options === void 0 ? void 0 : options.userCredentials);
+            const client = this.getClientForOperation(options === null || options === void 0 ? void 0 : options.userCredentials);
+            this.logger.info(`Batch writing items to ${tableName} with operation: ${operation}`, {
+                userCredentials: usingUserCredentials,
+            });
+            const chunks = [];
+            for (let i = 0; i < items.length; i += DYNAMODB_BATCH_WRITE_CHUNK_SIZE) {
+                chunks.push(items.slice(i, i + DYNAMODB_BATCH_WRITE_CHUNK_SIZE));
+            }
+            let lastResult;
+            const unprocessedItems = [];
+            for (const chunk of chunks) {
+                let currentChunk = chunk;
+                let retries = 0;
+                const maxChunkRetries = 3;
+                while (currentChunk.length > 0 && retries < maxChunkRetries) {
+                    const requests = currentChunk.map((item) => operation === "put"
+                        ? {
+                            PutRequest: {
+                                Item: item,
+                            },
+                        }
+                        : {
+                            DeleteRequest: {
+                                Key: item,
+                            },
+                        });
+                    lastResult = await client.send(new BatchWriteCommand({
+                        RequestItems: {
+                            [tableName]: requests,
+                        },
+                    }));
+                    // Check for unprocessed items
+                    const unprocessed = (_a = lastResult.UnprocessedItems) === null || _a === void 0 ? void 0 : _a[tableName];
+                    if (!unprocessed || unprocessed.length === 0) {
+                        // All items processed successfully
+                        break;
+                    }
+                    // Extract unprocessed items for retry
+                    currentChunk = unprocessed.map((req) => { var _a, _b; return operation === "put" ? (_a = req.PutRequest) === null || _a === void 0 ? void 0 : _a.Item : (_b = req.DeleteRequest) === null || _b === void 0 ? void 0 : _b.Key; });
+                    retries++;
+                    if (retries < maxChunkRetries) {
+                        // Exponential backoff before retry
+                        const delay = Math.min(1000 * Math.pow(2, retries), 5000);
+                        this.logger.warn(`Retrying ${currentChunk.length} unprocessed items after ${delay}ms`, {
+                            retries,
+                            tableName,
+                        });
+                        await new Promise((resolve) => setTimeout(resolve, delay));
+                    }
+                    // If items remain unprocessed after retries, collect them
+                    if (currentChunk.length > 0) {
+                        unprocessedItems.push(...currentChunk);
+                    }
+                }
+            }
+            if (unprocessedItems.length > 0) {
+                this.logger.error(`Failed to process ${unprocessedItems.length} items after retries`, {
+                    tableName,
+                    operation,
+                });
+                throw new Error(`Failed to process ${unprocessedItems.length} out of ${items.length} items in batch write`);
+            }
+            this.logger.info(`Successfully batch wrote items to ${tableName} with operation: ${operation}`, { userCredentials: usingUserCredentials });
+            invariant(lastResult, "Unexpected empty batch write result");
+            return lastResult;
+        });
+    }
+    /**
+     * Performs a transactional write operation (up to 100 actions)
+     * All actions succeed or all fail atomically
+     * @param actions Array of transaction actions to perform
+     * @param options Optional parameters including user credentials
+     * @returns The result of the transaction
+     */
+    async transactWrite(actions, options) {
+        if (actions.length === 0) {
+            throw new Error("Transaction requires at least one action");
+        }
+        if (actions.length > 100) {
+            throw new Error("DynamoDB supports maximum of 100 actions per transaction");
+        }
+        return this.executeWithRetry(async () => {
+            const usingUserCredentials = Boolean(options === null || options === void 0 ? void 0 : options.userCredentials);
+            this.logger.info(`Executing transaction with ${actions.length} actions`, {
+                userCredentials: usingUserCredentials,
+            });
+            const transactItems = actions.map((action) => {
+                const tableName = this.resolveTableName(action.tableName);
+                switch (action.operation) {
+                    case "put":
+                        if (!action.item) {
+                            throw new Error("Put operation requires an item");
+                        }
+                        validateItemSize(action.item);
+                        return {
+                            Put: {
+                                TableName: tableName,
+                                Item: action.item,
+                                ConditionExpression: action.conditionExpression,
+                                ExpressionAttributeNames: action.expressionAttributeNames,
+                                ExpressionAttributeValues: action.expressionAttributeValues,
+                            },
+                        };
+                    case "update":
+                        if (!action.key || !action.updateExpression) {
+                            throw new Error("Update operation requires key and updateExpression");
+                        }
+                        validateKey(action.key);
+                        return {
+                            Update: {
+                                TableName: tableName,
+                                Key: action.key,
+                                UpdateExpression: action.updateExpression,
+                                ConditionExpression: action.conditionExpression,
+                                ExpressionAttributeNames: action.expressionAttributeNames,
+                                ExpressionAttributeValues: action.expressionAttributeValues,
+                            },
+                        };
+                    case "delete":
+                        if (!action.key) {
+                            throw new Error("Delete operation requires a key");
+                        }
+                        validateKey(action.key);
+                        return {
+                            Delete: {
+                                TableName: tableName,
+                                Key: action.key,
+                                ConditionExpression: action.conditionExpression,
+                                ExpressionAttributeNames: action.expressionAttributeNames,
+                                ExpressionAttributeValues: action.expressionAttributeValues,
+                            },
+                        };
+                    case "conditionCheck":
+                        if (!action.key || !action.conditionExpression) {
+                            throw new Error("ConditionCheck operation requires key and conditionExpression");
+                        }
+                        validateKey(action.key);
+                        return {
+                            ConditionCheck: {
+                                TableName: tableName,
+                                Key: action.key,
+                                ConditionExpression: action.conditionExpression,
+                                ExpressionAttributeNames: action.expressionAttributeNames,
+                                ExpressionAttributeValues: action.expressionAttributeValues,
+                            },
+                        };
+                    default:
+                        throw new Error(`Unknown transaction operation: ${action.operation}`);
+                }
+            });
+            const command = new TransactWriteCommand({
+                TransactItems: transactItems,
+            });
+            const client = this.getClientForOperation(options === null || options === void 0 ? void 0 : options.userCredentials);
+            const result = await client.send(command);
+            this.logger.info(`Transaction completed successfully`, {
+                userCredentials: usingUserCredentials,
+            });
+            return result;
+        });
+    }
+    /**
+     * Performs a transactional read operation (up to 100 items)
+     * Provides a consistent snapshot across multiple items
+     * @param items Array of items to read transactionally
+     * @param options Optional parameters including user credentials
+     * @returns The result of the transaction
+     */
+    async transactGet(items, options) {
+        if (items.length === 0) {
+            throw new Error("Transaction requires at least one item");
+        }
+        if (items.length > 100) {
+            throw new Error("DynamoDB supports maximum of 100 items per transactional read");
+        }
+        return this.executeWithRetry(async () => {
+            const usingUserCredentials = Boolean(options === null || options === void 0 ? void 0 : options.userCredentials);
+            this.logger.info(`Executing transactional get for ${items.length} items`, {
+                userCredentials: usingUserCredentials,
+            });
+            const transactItems = items.map((itemConfig) => {
+                const tableName = this.resolveTableName(itemConfig.tableName);
+                validateKey(itemConfig.key);
+                return {
+                    Get: {
+                        TableName: tableName,
+                        Key: itemConfig.key,
+                        ProjectionExpression: itemConfig.projectionExpression,
+                        ExpressionAttributeNames: itemConfig.expressionAttributeNames,
+                    },
+                };
+            });
+            const command = new TransactGetCommand({
+                TransactItems: transactItems,
+            });
+            const client = this.getClientForOperation(options === null || options === void 0 ? void 0 : options.userCredentials);
+            const result = await client.send(command);
+            this.logger.info(`Transactional get completed successfully`, {
+                userCredentials: usingUserCredentials,
+            });
+            return result;
+        });
+    }
+    /**
+     * Retrieves multiple items in a single batch request (up to 100 items)
+     * More efficient than individual get operations
+     * @param params Batch get parameters
+     * @param options Optional parameters including table name override and user credentials
+     * @returns The result containing retrieved items and any unprocessed keys
+     */
+    async batchGet(params, options) {
+        if (params.keys.length === 0) {
+            throw new Error("At least one key must be provided for batch get");
+        }
+        if (params.keys.length > 100) {
+            throw new Error(`Cannot get more than 100 items in a single batch. Got ${params.keys.length} items.`);
+        }
+        return this.executeWithRetry(async () => {
+            var _a, _b, _c, _d;
+            const tableName = this.resolveTableName(options === null || options === void 0 ? void 0 : options.tableName);
+            const usingUserCredentials = Boolean(options === null || options === void 0 ? void 0 : options.userCredentials);
+            const client = this.getClientForOperation(options === null || options === void 0 ? void 0 : options.userCredentials);
+            // Validate all keys
+            params.keys.forEach(validateKey);
+            this.logger.info(`Batch getting ${params.keys.length} items from ${tableName}`, {
+                userCredentials: usingUserCredentials,
+            });
+            const command = new BatchGetCommand({
+                RequestItems: {
+                    [tableName]: {
+                        Keys: params.keys,
+                        ConsistentRead: params.consistentRead,
+                        ProjectionExpression: params.projectionExpression,
+                        ExpressionAttributeNames: params.expressionAttributeNames,
+                    },
+                },
+            });
+            let result = await client.send(command);
+            const items = (((_a = result.Responses) === null || _a === void 0 ? void 0 : _a[tableName]) || []);
+            // Handle unprocessed keys with retry
+            let retries = 0;
+            const maxRetries = 3;
+            while (result.UnprocessedKeys &&
+                Object.keys(result.UnprocessedKeys).length > 0 &&
+                retries < maxRetries) {
+                retries++;
+                const delay = Math.min(1000 * Math.pow(2, retries), 5000);
+                this.logger.warn(`Retrying unprocessed keys after ${delay}ms`, {
+                    retries,
+                    tableName,
+                });
+                await new Promise((resolve) => setTimeout(resolve, delay));
+                result = await client.send(new BatchGetCommand({
+                    RequestItems: result.UnprocessedKeys,
+                }));
+                items.push(...(((_b = result.Responses) === null || _b === void 0 ? void 0 : _b[tableName]) || []));
+            }
+            const unprocessedKeys = (_d = (_c = result.UnprocessedKeys) === null || _c === void 0 ? void 0 : _c[tableName]) === null || _d === void 0 ? void 0 : _d.Keys;
+            if (unprocessedKeys && unprocessedKeys.length > 0) {
+                this.logger.error(`Failed to retrieve all items after retries`, {
+                    tableName,
+                    unprocessedCount: unprocessedKeys.length,
+                });
+            }
+            this.logger.info(`Successfully batch got ${items.length} items from ${tableName}`, {
+                userCredentials: usingUserCredentials,
+            });
+            return { items, unprocessedKeys };
+        });
+    }
+    /**
+     * Conditional put operation - only puts the item if it doesn't already exist.
+     * Uses attribute_not_exists() condition on the partition key.
+     * @param item The item to put
+     * @param partitionKeyName The name of the partition key attribute
+     * @param options Optional parameters including table name override and user credentials
+     * @returns The result of the put operation
+     * @throws Error if the item already exists (ConditionalCheckFailedException)
+     * @example
+     * ```typescript
+     * await service.putIfNotExists(
+     *   { id: '123', name: 'John' },
+     *   'id'
+     * );
+     * ```
+     */
+    async putIfNotExists(item, partitionKeyName, options) {
+        return this.executeWithRetry(async () => {
+            const tableName = this.resolveTableName(options === null || options === void 0 ? void 0 : options.tableName);
+            validateItemSize(item);
+            const usingUserCredentials = Boolean(options === null || options === void 0 ? void 0 : options.userCredentials);
+            this.logger.info(`Putting item into ${tableName} if not exists (key: ${partitionKeyName})`, {
+                userCredentials: usingUserCredentials,
+            });
+            const command = new PutCommand({
+                TableName: tableName,
+                Item: item,
+                ConditionExpression: `attribute_not_exists(${partitionKeyName})`,
+            });
+            const client = this.getClientForOperation(options === null || options === void 0 ? void 0 : options.userCredentials);
+            const result = await client.send(command);
+            this.logger.info(`Successfully put item into ${tableName} (conditional)`, {
+                userCredentials: usingUserCredentials,
+            });
+            return result;
+        });
+    }
+    /**
+     * Conditional update operation - only updates the item if it exists.
+     * Uses attribute_exists() condition on the partition key.
+     * @param key The key of the item to update
+     * @param updateExpression The update expression
+     * @param partitionKeyName The name of the partition key attribute
+     * @param options Optional parameters including table name override, expression attribute names/values, additional conditions, and user credentials
+     * @returns The result of the update operation
+     * @throws Error if the item doesn't exist (ConditionalCheckFailedException)
+     * @example
+     * ```typescript
+     * await service.updateIfExists(
+     *   { id: '123' },
+     *   'SET #name = :name',
+     *   'id',
+     *   {
+     *     expressionAttributeNames: { '#name': 'name' },
+     *     expressionAttributeValues: { ':name': 'Jane' }
+     *   }
+     * );
+     * ```
+     */
+    async updateIfExists(key, updateExpression, partitionKeyName, options) {
+        return this.executeWithRetry(async () => {
+            const tableName = this.resolveTableName(options === null || options === void 0 ? void 0 : options.tableName);
+            validateKey(key);
+            const usingUserCredentials = Boolean(options === null || options === void 0 ? void 0 : options.userCredentials);
+            this.logger.info(`Updating item in ${tableName} if exists (key: ${partitionKeyName})`, {
+                userCredentials: usingUserCredentials,
+            });
+            // Combine attribute_exists with any additional conditions
+            const conditionExpression = (options === null || options === void 0 ? void 0 : options.additionalCondition)
+                ? `attribute_exists(${partitionKeyName}) AND ${options.additionalCondition}`
+                : `attribute_exists(${partitionKeyName})`;
+            const command = new UpdateCommand({
+                TableName: tableName,
+                Key: key,
+                UpdateExpression: updateExpression,
+                ConditionExpression: conditionExpression,
+                ExpressionAttributeNames: options === null || options === void 0 ? void 0 : options.expressionAttributeNames,
+                ExpressionAttributeValues: options === null || options === void 0 ? void 0 : options.expressionAttributeValues,
+                ReturnValues: "ALL_NEW",
+            });
+            const client = this.getClientForOperation(options === null || options === void 0 ? void 0 : options.userCredentials);
+            const result = await client.send(command);
+            this.logger.info(`Successfully updated item in ${tableName} (conditional)`, {
+                userCredentials: usingUserCredentials,
+            });
+            return result;
+        });
+    }
+    onMetric(name, dims) {
+        this.logger.debug(`DynamoDB Metric: ${name}`, dims);
+    }
+    getDefaultTableName() {
+        return this.defaultTableName;
+    }
+    /**
+     * Cleanup and destroy the DynamoDB client
+     * Call this when shutting down the service to free resources
+     */
+    async destroy() {
+        this.logger.info("Destroying DynamoDbService", {
+            defaultTable: this.defaultTableName,
+        });
+        try {
+            this.client.destroy();
+            this.logger.info("DynamoDbService destroyed successfully");
+        }
+        catch (error) {
+            this.logger.error("Error destroying DynamoDB client", { error });
+            throw error;
+        }
+    }
+}
+//# sourceMappingURL=dynamodb.service.js.map