captify 0.1.15

package/dist/services/dynamodb/services/dynamodb.service.d.ts

@@ -0,0 +1,292 @@
+import type { DynamoDbBaseOptions, DynamoDbBatchGetParams, DynamoDbBatchGetResult, DynamoDbConfig, DynamoDbQueryResult, DynamoDbScanResult, DynamoDbTransactGetItem, DynamoDbTransactionAction } from "../interfaces";
+import type { BaseAwsError } from "../../shared";
+import type { Logger } from "../../logger";
+import { BaseAwsService } from "../../shared/services";
+import { type BatchWriteCommandOutput, DynamoDBDocumentClient, type QueryCommandInput, type ScanCommandInput } from "@aws-sdk/lib-dynamodb";
+/**
+ * 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 declare class DynamoDbService extends BaseAwsService {
+    private readonly client;
+    private readonly defaultTableName?;
+    private constructor();
+    protected classifyError(err: unknown): BaseAwsError;
+    private resolveTableName;
+    /**
+     * 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
+     */
+    private getClientForOperation;
+    /**
+     * 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: Partial<DynamoDbConfig>, logger?: Logger): DynamoDbService;
+    static loadEnvConfig(): Partial<DynamoDbConfig>;
+    static createWithClient(client: DynamoDBDocumentClient, tableName: string, logger?: Logger): DynamoDbService;
+    /**
+     * 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.
+     */
+    putItem<T extends Record<string, unknown>>(item: T, options?: DynamoDbBaseOptions): Promise<import("@aws-sdk/lib-dynamodb").PutCommandOutput>;
+    /**
+     * 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.
+     */
+    getItem<T extends Record<string, unknown>>(key: T, options?: DynamoDbBaseOptions): Promise<import("@aws-sdk/lib-dynamodb").GetCommandOutput>;
+    /**
+     * 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.
+     */
+    updateItem<T extends Record<string, unknown>, U extends Record<string, string>>(key: T, updateExpression: string, expressionAttributeNames?: U, expressionAttributeValues?: T, options?: DynamoDbBaseOptions): Promise<import("@aws-sdk/lib-dynamodb").UpdateCommandOutput>;
+    /**
+     * 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.
+     */
+    deleteItem<T extends Record<string, unknown>>(key: T, options?: DynamoDbBaseOptions): Promise<import("@aws-sdk/lib-dynamodb").DeleteCommandOutput>;
+    /**
+     * 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.
+     */
+    queryItems(params: Omit<QueryCommandInput, "TableName">, options?: DynamoDbBaseOptions): Promise<import("@aws-sdk/lib-dynamodb").QueryCommandOutput>;
+    /**
+     * 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.
+     */
+    scanItems(params: Omit<ScanCommandInput, "TableName">, options?: DynamoDbBaseOptions): Promise<import("@aws-sdk/lib-dynamodb").ScanCommandOutput>;
+    /**
+     * 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<T extends Record<string, unknown>>(params: Omit<QueryCommandInput, "TableName" | "ExclusiveStartKey">, options?: DynamoDbBaseOptions): AsyncGenerator<DynamoDbQueryResult<T>, void, undefined>;
+    /**
+     * 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<T extends Record<string, unknown>>(params: Omit<ScanCommandInput, "TableName" | "ExclusiveStartKey">, options?: DynamoDbBaseOptions): AsyncGenerator<DynamoDbScanResult<T>, void, undefined>;
+    /**
+     * 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.
+     */
+    batchWrite<T extends Record<string, unknown>>(items: T[], operation?: "put" | "delete", options?: DynamoDbBaseOptions): Promise<BatchWriteCommandOutput>;
+    /**
+     * 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
+     */
+    transactWrite(actions: DynamoDbTransactionAction[], options?: Omit<DynamoDbBaseOptions, "tableName">): Promise<import("@aws-sdk/lib-dynamodb").TransactWriteCommandOutput>;
+    /**
+     * 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
+     */
+    transactGet(items: DynamoDbTransactGetItem[], options?: Omit<DynamoDbBaseOptions, "tableName">): Promise<import("@aws-sdk/lib-dynamodb").TransactGetCommandOutput>;
+    /**
+     * 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
+     */
+    batchGet<T extends Record<string, unknown>>(params: DynamoDbBatchGetParams, options?: DynamoDbBaseOptions): Promise<DynamoDbBatchGetResult<T>>;
+    /**
+     * 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'
+     * );
+     * ```
+     */
+    putIfNotExists<T extends Record<string, unknown>>(item: T, partitionKeyName: string, options?: DynamoDbBaseOptions): Promise<import("@aws-sdk/lib-dynamodb").PutCommandOutput>;
+    /**
+     * 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' }
+     *   }
+     * );
+     * ```
+     */
+    updateIfExists(key: Record<string, unknown>, updateExpression: string, partitionKeyName: string, options?: {
+        tableName?: string;
+        expressionAttributeNames?: Record<string, string>;
+        expressionAttributeValues?: Record<string, unknown>;
+        additionalCondition?: string;
+        userCredentials?: import("../../shared").UserAwsCredentials;
+    }): Promise<import("@aws-sdk/lib-dynamodb").UpdateCommandOutput>;
+    protected onMetric(name: string, dims: Record<string, unknown>): void;
+    getDefaultTableName(): string | undefined;
+    /**
+     * Cleanup and destroy the DynamoDB client
+     * Call this when shutting down the service to free resources
+     */
+    destroy(): Promise<void>;
+}
+//# sourceMappingURL=dynamodb.service.d.ts.map

package/dist/services/dynamodb/services/dynamodb.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dynamodb.service.d.ts","sourceRoot":"","sources":["../../../../lib/services/dynamodb/services/dynamodb.service.ts"],"names":[],"mappings":"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"}