dyno-table 2.5.2 → 2.6.1

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

@@ -0,0 +1,249 @@
+import type { PrimaryKeyWithoutExpression } from "../conditions";
+import { BatchError } from "../errors";
+import type { BatchWriteOperation } from "../operation-types";
+import type { DynamoItem } from "../types";
+import type { DeleteCommandParams, PutCommandParams } from "./builder-types";
+import type { GetCommandParams } from "./get-builder";
+/**
+ * Represents a single operation within a DynamoDB batch.
+ * Each operation can be one of:
+ * - Put: Insert or replace an item
+ * - Delete: Remove an item
+ * - Get: Retrieve an item
+ */
+export type BatchItem = {
+    type: "Put";
+    params: PutCommandParams;
+} | {
+    type: "Delete";
+    params: DeleteCommandParams;
+} | {
+    type: "Get";
+    params: GetCommandParams;
+};
+/**
+ * Typed batch item that preserves entity type information
+ */
+export type TypedBatchItem<T extends DynamoItem = DynamoItem> = {
+    type: "Put";
+    params: PutCommandParams;
+    entityType?: string;
+    resultType?: T;
+} | {
+    type: "Delete";
+    params: DeleteCommandParams;
+    entityType?: string;
+} | {
+    type: "Get";
+    params: GetCommandParams;
+    entityType?: string;
+    resultType?: T;
+};
+/**
+ * Configuration for batch operations
+ */
+export interface BatchConfig {
+    partitionKey: string;
+    sortKey?: string;
+}
+/**
+ * Executor function for batch write operations
+ */
+type BatchWriteExecutor = (operations: Array<BatchWriteOperation<DynamoItem>>) => Promise<{
+    unprocessedItems: Array<BatchWriteOperation<DynamoItem>>;
+}>;
+/**
+ * Executor function for batch get operations
+ */
+type BatchGetExecutor = (keys: Array<PrimaryKeyWithoutExpression>) => Promise<{
+    items: DynamoItem[];
+    unprocessedKeys: PrimaryKeyWithoutExpression[];
+}>;
+/**
+ * Result structure for batch operations
+ */
+export interface BatchResult {
+    /** Whether the batch operation completed successfully */
+    success: boolean;
+    /** Write operation results */
+    writes: {
+        /** Number of write operations processed successfully */
+        processed: number;
+        /** Write operations that were not processed and may need retry */
+        unprocessed: Array<BatchWriteOperation<DynamoItem>>;
+    };
+    /** Read operation results */
+    reads: {
+        /** Items retrieved from the batch get operations */
+        items: DynamoItem[];
+        /** Number of items found and returned */
+        found: number;
+        /** Keys that were not processed and may need retry */
+        unprocessed: PrimaryKeyWithoutExpression[];
+    };
+    /** Total number of operations in the batch */
+    totalOperations: number;
+    /** Any errors that occurred during batch processing */
+    errors?: BatchError[];
+}
+/**
+ * Typed result structure for batch operations with entity type information
+ */
+export interface TypedBatchResult<TEntities extends Record<string, DynamoItem> = Record<string, DynamoItem>> {
+    /** Whether the batch operation completed successfully */
+    success: boolean;
+    /** Write operation results */
+    writes: {
+        /** Number of write operations processed successfully */
+        processed: number;
+        /** Write operations that were not processed and may need retry */
+        unprocessed: Array<BatchWriteOperation<DynamoItem>>;
+    };
+    /** Read operation results with typed items */
+    reads: {
+        /** Items retrieved from the batch get operations, grouped by entity type */
+        itemsByType: {
+            [K in keyof TEntities]: TEntities[K][];
+        };
+        /** All items retrieved (typed as union of all entity types) */
+        items: TEntities[keyof TEntities][];
+        /** Number of items found and returned */
+        found: number;
+        /** Keys that were not processed and may need retry */
+        unprocessed: PrimaryKeyWithoutExpression[];
+    };
+    /** Total number of operations in the batch */
+    totalOperations: number;
+    /** Any errors that occurred during batch execution */
+    errors?: BatchError[];
+}
+/**
+ * Builder for creating and executing DynamoDB batch operations with full entity support and type inference.
+ *
+ * Use BatchBuilder when you need to:
+ * - Perform multiple operations efficiently (up to 25 writes, 100 reads per batch)
+ * - Maintain entity validation, key generation, and type safety
+ * - Mix read and write operations in a single batch
+ * - Get typed results grouped by entity type
+ *
+ * @example Basic Usage
+ * ```typescript
+ * // Define entity types for the batch
+ * const batch = table.batchBuilder<{
+ *   User: UserEntity;
+ *   Order: OrderEntity;
+ * }>();
+ *
+ * // Add operations using entity repositories
+ * userRepo.create(newUser).withBatch(batch, 'User')
+ * userRepo.delete({ id: 'old-user' }).withBatch(batch, 'User')
+ * orderRepo.get({ id: 'existing-order' }).withBatch(batch, 'Order')
+ *
+ * // Execute all operations and get typed results
+ * const result = await batch.execute()
+ * const users: UserEntity[] = result.reads.itemsByType.User
+ * const orders: OrderEntity[] = result.reads.itemsByType.Order
+ * ```
+ *
+ * @example Error Handling
+ * ```typescript
+ * try {
+ *   const result = await batch.execute()
+ *
+ *   if (result.writes.unprocessed.length > 0) {
+ *     console.warn('Some writes were not processed:', result.writes.unprocessed)
+ *   }
+ * } catch (error) {
+ *   if (error instanceof BatchError) {
+ *     console.error('Batch operation failed:', error.message)
+ *   }
+ * }
+ * ```
+ */
+export declare class BatchBuilder<TEntities extends Record<string, DynamoItem> = Record<string, DynamoItem>> {
+    private batchWriteExecutor;
+    private batchGetExecutor;
+    private config;
+    private writeItems;
+    private getItems;
+    constructor(batchWriteExecutor: BatchWriteExecutor, batchGetExecutor: BatchGetExecutor, config: BatchConfig);
+    /**
+     * Checks if the batch is empty (contains no operations)
+     *
+     * @returns true if the batch contains no operations
+     */
+    isEmpty(): boolean;
+    /**
+     * Gets the count of operations in the batch
+     *
+     * @returns Object containing the count of write and read operations
+     */
+    getOperationCount(): {
+        writes: number;
+        reads: number;
+    };
+    /**
+     * Validates that the batch is not empty before execution
+     *
+     * @throws {BatchError} If the batch is empty
+     */
+    private validateNotEmpty;
+    /**
+     * Adds a put operation to the batch with entity type information.
+     * This method is used internally by entity builders.
+     *
+     * @param command - The complete put command configuration
+     * @param entityType - The entity type name for type tracking
+     * @returns The batch builder for method chaining
+     * @internal
+     */
+    putWithCommand<K extends keyof TEntities>(command: PutCommandParams, entityType?: K): this;
+    /**
+     * Adds a delete operation to the batch with entity type information.
+     * This method is used internally by entity builders.
+     *
+     * @param command - The complete delete command configuration
+     * @param entityType - The entity type name for type tracking
+     * @returns The batch builder for method chaining
+     * @internal
+     */
+    deleteWithCommand<K extends keyof TEntities>(command: DeleteCommandParams, entityType?: K): this;
+    /**
+     * Adds a get operation to the batch with entity type information.
+     * This method is used internally by entity builders.
+     *
+     * @param command - The complete get command configuration
+     * @param entityType - The entity type name for type tracking
+     * @returns The batch builder for method chaining
+     * @internal
+     */
+    getWithCommand<K extends keyof TEntities>(command: GetCommandParams, entityType?: K): this;
+    /**
+     * Executes all write operations in the batch.
+     *
+     * @returns A promise that resolves to any unprocessed operations
+     * @private
+     */
+    private executeWrites;
+    /**
+     * Executes all get operations in the batch.
+     *
+     * @returns A promise that resolves to the retrieved items
+     * @private
+     */
+    private executeGets;
+    /**
+     * Groups retrieved items by their entity type.
+     * @private
+     */
+    private groupItemsByType;
+    /**
+     * Executes all operations in the batch with typed results.
+     * Performs write operations first, then get operations.
+     *
+     * @returns A promise that resolves to a TypedBatchResult with entity type information
+     * @throws {BatchError} If the batch is empty or if operations fail
+     */
+    execute(): Promise<TypedBatchResult<TEntities>>;
+}
+export {};

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

@@ -0,0 +1,123 @@
+import type { DynamoItem, TableConfig } from "../types";
+import type { DynamoCommandWithExpressions } from "../utils/debug-expression";
+import type { ResultIterator } from "./result-iterator";
+export interface DeleteCommandParams extends DynamoCommandWithExpressions {
+    tableName: string;
+    key: Record<string, unknown>;
+    conditionExpression?: string;
+    expressionAttributeNames?: Record<string, string>;
+    expressionAttributeValues?: DynamoItem;
+    returnValues?: "ALL_OLD";
+}
+/**
+ * Parameters for the DynamoDB put command.
+ *
+ * These parameters are used when executing the operation against DynamoDB.
+ *
+ * The `returnValues` property can be:
+ * - `"ALL_OLD"`: Return the attributes of the item as they were before the operation
+ * - `"NONE"`: Return nothing
+ * - `"CONSISTENT"`: Triggers a GET operation after the put to retrieve the updated item state
+ * - `"INPUT"`: Return the input values that were passed to the operation (useful for create operations)
+ */
+export interface PutCommandParams extends DynamoCommandWithExpressions {
+    tableName: string;
+    item: DynamoItem;
+    conditionExpression?: string;
+    expressionAttributeNames?: Record<string, string>;
+    expressionAttributeValues?: Record<string, unknown>;
+    returnValues?: "ALL_OLD" | "NONE" | "CONSISTENT" | "INPUT";
+}
+/**
+ * Parameters for the DynamoDB update command.
+ * These parameters are used when executing the operation against DynamoDB.
+ */
+export interface UpdateCommandParams extends DynamoCommandWithExpressions {
+    /** The name of the DynamoDB table */
+    tableName: string;
+    /** The primary key of the item to update */
+    key: Record<string, unknown>;
+    /** The update expression (SET, REMOVE, ADD, DELETE clauses) */
+    updateExpression: string;
+    /** Optional condition expression that must be satisfied */
+    conditionExpression?: string;
+    /** Map of expression attribute name placeholders to actual names */
+    expressionAttributeNames?: Record<string, string>;
+    /** Map of expression attribute value placeholders to actual values */
+    expressionAttributeValues?: DynamoItem;
+    /** Which item attributes to include in the response */
+    returnValues?: "ALL_NEW" | "UPDATED_NEW" | "ALL_OLD" | "UPDATED_OLD" | "NONE";
+}
+export interface ConditionCheckCommandParams extends DynamoCommandWithExpressions {
+    tableName: string;
+    key: Record<string, unknown>;
+    conditionExpression: string;
+    expressionAttributeNames?: Record<string, string>;
+    expressionAttributeValues?: DynamoItem;
+}
+/**
+ * Base interface for all builder classes that support pagination
+ * to be used by Paginator without creating circular dependencies.
+ */
+export interface BaseBuilderInterface<T extends DynamoItem, TConfig extends TableConfig = TableConfig, B = unknown> {
+    clone(): B;
+    limit(limit: number): B;
+    getLimit(): number | undefined;
+    startFrom(lastEvaluatedKey: DynamoItem): B;
+    execute(): Promise<ResultIterator<T, TConfig>>;
+    findOne(): Promise<T | undefined>;
+}
+/**
+ * Interface for the QueryBuilder class to be used by Paginator
+ * without creating a circular dependency.
+ */
+export interface QueryBuilderInterface<T extends DynamoItem, TConfig extends TableConfig = TableConfig> extends BaseBuilderInterface<T, TConfig, QueryBuilderInterface<T, TConfig>> {
+}
+/**
+ * Interface for the ScanBuilder class to be used by Paginator
+ * without creating a circular dependency.
+ */
+export interface ScanBuilderInterface<T extends DynamoItem, TConfig extends TableConfig = TableConfig> extends BaseBuilderInterface<T, TConfig, ScanBuilderInterface<T, TConfig>> {
+}
+/**
+ * Interface for the FilterBuilder class to be used by Paginator
+ * without creating a circular dependency.
+ */
+export interface FilterBuilderInterface<T extends DynamoItem, TConfig extends TableConfig = TableConfig> extends BaseBuilderInterface<T, TConfig, FilterBuilderInterface<T, TConfig>> {
+}
+/**
+ * Represents the result of a single page query operation.
+ * This interface provides all necessary information about the current page
+ * and the availability of subsequent pages.
+ */
+export interface PaginationResult<T> {
+    /** The items (dinosaurs, habitats, etc.) retrieved for the current page */
+    items: T[];
+    /** DynamoDB's last evaluated key, used internally for pagination */
+    lastEvaluatedKey?: DynamoItem;
+    /** Indicates whether there are more pages available */
+    hasNextPage: boolean;
+    /** The current page number (1-indexed) */
+    page: number;
+}
+/**
+ * Represents a single operation within a DynamoDB transaction.
+ * Each operation can be one of:
+ * - Put: Insert or replace an item
+ * - Update: Modify an existing item
+ * - Delete: Remove an item
+ * - ConditionCheck: Verify item state without modification
+ */
+export type TransactionItem = {
+    type: "Put";
+    params: PutCommandParams;
+} | {
+    type: "Update";
+    params: UpdateCommandParams;
+} | {
+    type: "Delete";
+    params: DeleteCommandParams;
+} | {
+    type: "ConditionCheck";
+    params: ConditionCheckCommandParams;
+};

package/dist/builders/condition-check-builder.d.ts

@@ -0,0 +1,149 @@
+import type { Condition, ConditionOperator, PrimaryKeyWithoutExpression } from "../conditions";
+import type { DynamoItem } from "../types";
+import type { ConditionCheckCommandParams } from "./builder-types";
+import type { TransactionBuilder } from "./transaction-builder";
+/**
+ * Builder for creating DynamoDB condition check operations.
+ * Use this builder when you need to:
+ * - Verify item state without modifying it
+ * - Ensure preconditions in transactions
+ * - Implement optimistic locking patterns
+ * - Validate business rules
+ *
+ * @example
+ * ```typescript
+ * // Check if dinosaur is ready for feeding
+ * const check = new ConditionCheckBuilder('dinosaurs', { id: 'TREX-001' })
+ *   .condition(op =>
+ *     op.and([
+ *       op.eq('status', 'HUNTING'),
+ *       op.gt('stats.hunger', 80),
+ *       op.lt('stats.health', 100)
+ *     ])
+ *   )
+ *   .toDynamoCommand();
+ *
+ * // Check habitat security status
+ * const securityCheck = new ConditionCheckBuilder('habitats', { id: 'PADDOCK-A' })
+ *   .condition(op =>
+ *     op.and([
+ *       op.eq('securityStatus', 'ACTIVE'),
+ *       op.attributeExists('lastInspection'),
+ *       op.lt('threatLevel', 5)
+ *     ])
+ *   )
+ *   .toDynamoCommand();
+ * ```
+ */
+export declare class ConditionCheckBuilder {
+    private readonly key;
+    private readonly tableName;
+    private conditionExpression?;
+    constructor(tableName: string, key: PrimaryKeyWithoutExpression);
+    /**
+     * Adds a condition that must be satisfied for the check to succeed.
+     *
+     * @example
+     * ```typescript
+     * // Check dinosaur health and behavior
+     * builder.condition(op =>
+     *   op.and([
+     *     op.gt('stats.health', 50),
+     *     op.not(op.eq('status', 'SEDATED')),
+     *     op.lt('aggressionLevel', 8)
+     *   ])
+     * );
+     *
+     * // Verify habitat conditions
+     * builder.condition(op =>
+     *   op.and([
+     *     op.eq('powerStatus', 'ONLINE'),
+     *     op.between('temperature', 20, 30),
+     *     op.attributeExists('lastMaintenance')
+     *   ])
+     * );
+     *
+     * // Check breeding conditions
+     * builder.condition(op =>
+     *   op.and([
+     *     op.eq('species', 'VELOCIRAPTOR'),
+     *     op.gte('age', 3),
+     *     op.eq('geneticPurity', 100)
+     *   ])
+     * );
+     * ```
+     *
+     * @param condition - Either a Condition DynamoItem or a callback function that builds the condition
+     * @returns The builder instance for method chaining
+     */
+    condition<T extends DynamoItem>(condition: Condition | ((op: ConditionOperator<T>) => Condition)): this;
+    /**
+     * Generates the DynamoDB command parameters for direct execution.
+     * Use this method when you want to:
+     * - Execute the condition check as a standalone operation
+     * - Get the raw DynamoDB command for custom execution
+     * - Inspect the generated command parameters
+     *
+     * @example
+     * ```ts
+     * const command = new ConditionCheckBuilder('myTable', { id: '123' })
+     *   .condition(op => op.attributeExists('status'))
+     *   .toDynamoCommand();
+     * // Use command with DynamoDB client
+     * ```
+     *
+     * @throws {Error} If no condition has been set
+     * @returns The DynamoDB command parameters
+     */
+    private toDynamoCommand;
+    /**
+     * Adds this condition check operation to a transaction.
+     *
+     * @example
+     * ```ts
+     * const transaction = new TransactionBuilder();
+     * new ConditionCheckBuilder('habitats', { id: 'PADDOCK-B' })
+     *   .condition(op => op.and([
+     *     op.eq('securityStatus', 'ACTIVE'),
+     *     op.lt('currentOccupants', 3),
+     *     op.eq('habitatType', 'CARNIVORE')
+     *   ]))
+     *   .withTransaction(transaction);
+     * // Add dinosaur transfer operations
+     * ```
+     *
+     * @param transaction - The transaction builder to add this operation to
+     * @throws {Error} If no condition has been set
+     * @returns The builder instance for method chaining
+     */
+    withTransaction(transaction: TransactionBuilder): this;
+    /**
+     * Gets a human-readable representation of the condition check command
+     * with all expression placeholders replaced by their actual values.
+     *
+     * @example
+     * ```ts
+     * const debugInfo = new ConditionCheckBuilder('dinosaurs', { id: 'TREX-001' })
+     *   .condition(op => op.and([
+     *     op.between('stats.health', 50, 100),
+     *     op.not(op.eq('status', 'SEDATED')),
+     *     op.attributeExists('lastFeedingTime')
+     *     op.eq('version', 1)
+     *   ]))
+     *   .debug();
+     * console.log(debugInfo);
+     * ```
+     *
+     * @returns A readable representation of the condition check command with resolved expressions
+     */
+    debug(): {
+        raw: ConditionCheckCommandParams;
+        readable: {
+            conditionExpression?: string;
+            updateExpression?: string;
+            filterExpression?: string;
+            keyConditionExpression?: string;
+            projectionExpression?: string;
+        };
+    };
+}