dyno-table 1.6.0 → 1.8.0-next.1

package/dist/batch-builder-CKYnMRyz.d.cts

@@ -0,0 +1,398 @@
+import { DynamoItem } from './types.cjs';
+import { r as PrimaryKeyWithoutExpression } from './conditions-3ae5znV_.cjs';
+import { a as PutCommandParams, D as DeleteCommandParams } from './builder-types-BTVhQSHI.cjs';
+
+type BatchWriteOperation<T extends Record<string, unknown>> = {
+    type: "put";
+    item: T;
+} | {
+    type: "delete";
+    key: PrimaryKeyWithoutExpression;
+};
+
+/**
+ * Parameters for the DynamoDB get command.
+ */
+interface GetCommandParams {
+    /** The name of the DynamoDB table */
+    tableName: string;
+    /** The primary key of the item to get */
+    key: PrimaryKeyWithoutExpression;
+    /** Comma-separated list of attributes to return */
+    projectionExpression?: string;
+    /** Map of expression attribute name placeholders to actual names */
+    expressionAttributeNames?: Record<string, string>;
+    /** Whether to use strongly consistent reads */
+    consistentRead?: boolean;
+}
+/**
+ * Function type for executing DynamoDB get operations.
+ * @typeParam T - The type of item being retrieved
+ */
+type GetExecutor<T extends DynamoItem> = (params: GetCommandParams) => Promise<{
+    item: T | undefined;
+}>;
+/**
+ * Builder for creating DynamoDB get operations.
+ * Use this builder when you need to:
+ * - Retrieve a single dinosaur by its primary key
+ * - Project specific dinosaur attributes
+ * - Use consistent reads for critical dinosaur data
+ *
+ * @example
+ * ```typescript
+ * // Simple get
+ * const result = await new GetBuilder(executor, { pk: 'dinosaur#123', sk: 'profile' })
+ *   .execute();
+ *
+ * // Get with projection and consistent read
+ * const result = await new GetBuilder(executor, { pk: 'dinosaur#123', sk: 'profile' })
+ *   .select(['species', 'name', 'diet'])
+ *   .consistentRead()
+ *   .execute();
+ * ```
+ *
+ * @typeParam T - The type of item being retrieved
+ */
+declare class GetBuilder<T extends DynamoItem> {
+    private readonly executor;
+    private readonly params;
+    private options;
+    private selectedFields;
+    /**
+     * Creates a new GetBuilder instance.
+     *
+     * @param executor - Function that executes the get operation
+     * @param key - Primary key of the item to retrieve
+     * @param tableName - Name of the DynamoDB table
+     */
+    constructor(executor: GetExecutor<T>, key: PrimaryKeyWithoutExpression, tableName: string);
+    /**
+     * Specifies which attributes to return in the get results.
+     *
+     * @example
+     * ```typescript
+     * // Select single attribute
+     * builder.select('species')
+     *
+     * // Select multiple attributes
+     * builder.select(['id', 'species', 'diet'])
+     *
+     * // Chain multiple select calls
+     * builder
+     *   .select('id')
+     *   .select(['species', 'diet'])
+     * ```
+     *
+     * @param fields - A single field name or an array of field names to return
+     * @returns The builder instance for method chaining
+     */
+    select(fields: string | string[]): GetBuilder<T>;
+    /**
+     * Sets whether to use strongly consistent reads for the get operation.
+     * Use this method when you need:
+     * - The most up-to-date dinosaur data
+     * - To ensure you're reading the latest dinosaur status
+     * - Critical safety information about dangerous species
+     *
+     * Note: Consistent reads consume twice the throughput
+     *
+     * @example
+     * ```typescript
+     * // Get the latest T-Rex data
+     * const result = await new GetBuilder(executor, { pk: 'dinosaur#123', sk: 'profile' })
+     *   .consistentRead()
+     *   .execute();
+     * ```
+     *
+     * @param consistentRead - Whether to use consistent reads (defaults to true)
+     * @returns The builder instance for method chaining
+     */
+    consistentRead(consistentRead?: boolean): GetBuilder<T>;
+    /**
+     * Adds this get operation to a batch with optional entity type information.
+     *
+     * @example Basic Usage
+     * ```ts
+     * const batch = table.batchBuilder();
+     *
+     * // Add multiple get operations to batch
+     * dinosaurRepo.get({ id: 'dino-1' }).withBatch(batch);
+     * dinosaurRepo.get({ id: 'dino-2' }).withBatch(batch);
+     * dinosaurRepo.get({ id: 'dino-3' }).withBatch(batch);
+     *
+     * // Execute all gets efficiently
+     * const results = await batch.execute();
+     * ```
+     *
+     * @example Typed Usage
+     * ```ts
+     * const batch = table.batchBuilder<{
+     *   User: UserEntity;
+     *   Order: OrderEntity;
+     * }>();
+     *
+     * // Add operations with type information
+     * userRepo.get({ id: 'user-1' }).withBatch(batch, 'User');
+     * orderRepo.get({ id: 'order-1' }).withBatch(batch, 'Order');
+     *
+     * // Execute and get typed results
+     * const result = await batch.execute();
+     * const users: UserEntity[] = result.reads.itemsByType.User;
+     * const orders: OrderEntity[] = result.reads.itemsByType.Order;
+     * ```
+     *
+     * @param batch - The batch builder to add this operation to
+     * @param entityType - Optional entity type key for type tracking
+     */
+    withBatch<TEntities extends Record<string, DynamoItem> = Record<string, DynamoItem>, K extends keyof TEntities = keyof TEntities>(batch: BatchBuilder<TEntities>, entityType?: K): void;
+    /**
+     * Converts the builder configuration to a DynamoDB command
+     */
+    private toDynamoCommand;
+    /**
+     * Executes the get operation against DynamoDB.
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   const result = await new GetBuilder(executor, { pk: 'dinosaur#123', sk: 'profile' })
+     *     .select(['species', 'name', 'diet'])
+     *     .consistentRead()
+     *     .execute();
+     *
+     *   if (result.item) {
+     *     console.log('Dinosaur found:', result.item);
+     *   } else {
+     *     console.log('Dinosaur not found');
+     *   }
+     * } catch (error) {
+     *   console.error('Error getting dinosaur:', error);
+     * }
+     * ```
+     *
+     * @returns A promise that resolves to an object containing:
+     *          - item: The retrieved dinosaur or undefined if not found
+     */
+    execute(): Promise<{
+        item: T | undefined;
+    }>;
+}
+
+/**
+ * Configuration for batch operations
+ */
+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[];
+}>;
+/**
+ * Error class for batch operation failures
+ */
+declare class BatchError extends Error {
+    readonly operation: "write" | "read";
+    readonly cause?: Error;
+    constructor(message: string, operation: "write" | "read", cause?: Error);
+}
+/**
+ * Result structure for batch operations
+ */
+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
+ */
+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)
+ *   }
+ * }
+ * ```
+ */
+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 { BatchBuilder as B, GetBuilder as G, BatchError as a, type BatchResult as b, type BatchWriteOperation as c };

package/dist/{builder-types-DlaUSc-b.d.cts → builder-types-BTVhQSHI.d.cts}

@@ -14,6 +14,59 @@ interface DynamoCommandWithExpressions {
     [key: string]: unknown;
 }
 
+/**
+ * Function type for executing DynamoDB operations and returning raw results.
+ */
+type DirectExecutor<T extends DynamoItem> = () => Promise<{
+    items: T[];
+    lastEvaluatedKey?: DynamoItem;
+}>;
+/**
+ * Minimal result generator that provides async iteration over DynamoDB results with automatic pagination.
+ *
+ * @example
+ * ```typescript
+ * const results = await queryBuilder.execute();
+ *
+ * for await (const item of results) {
+ *   console.log(item);
+ * }
+ * ```
+ */
+declare class ResultIterator<T extends DynamoItem, TConfig extends TableConfig = TableConfig> {
+    private queryBuilder;
+    private directExecutor;
+    private lastEvaluatedKey?;
+    private itemsYielded;
+    private readonly overallLimit?;
+    constructor(queryBuilder: QueryBuilderInterface<T, TConfig>, directExecutor: DirectExecutor<T>);
+    /**
+     * Async iterator with automatic pagination
+     */
+    [Symbol.asyncIterator](): AsyncIterableIterator<T>;
+    /**
+     * Convert to array (loads all pages).
+     *
+     * ```ts
+     * const result = await table.query({ pk: "foo" }).execute();
+     * const allItemsFromDynamo = await result.toArray();
+     * ```
+     *
+     * Note: This will load all pages into memory. For large datasets, consider using async iteration instead.
+     *```ts
+     * const result = await table.query({ pk: "foo" }).execute();
+     * for await (const item of result) {
+     *   // Process each item
+     * }
+     * ```
+     */
+    toArray(): Promise<T[]>;
+    /**
+     * Get the last evaluated key
+     */
+    getLastEvaluatedKey(): DynamoItem | undefined;
+}
+
 interface DeleteCommandParams extends DynamoCommandWithExpressions {
     tableName: string;
     key: Record<string, unknown>;
@@ -77,10 +130,7 @@ interface BaseBuilderInterface<T extends DynamoItem, TConfig extends TableConfig
     limit(limit: number): B;
     getLimit(): number | undefined;
     startFrom(lastEvaluatedKey: DynamoItem): B;
-    execute(): Promise<{
-        items: T[];
-        lastEvaluatedKey?: DynamoItem;
-    }>;
+    execute(): Promise<ResultIterator<T, TConfig>>;
 }
 /**
  * Interface for the QueryBuilder class to be used by Paginator
@@ -116,4 +166,4 @@ interface PaginationResult<T> {
     page: number;
 }
 
-export type { ConditionCheckCommandParams as C, DeleteCommandParams as D, FilterBuilderInterface as F, PaginationResult as P, QueryBuilderInterface as Q, ScanBuilderInterface as S, UpdateCommandParams as U, PutCommandParams as a };
+export { type ConditionCheckCommandParams as C, type DeleteCommandParams as D, type FilterBuilderInterface as F, type PaginationResult as P, type QueryBuilderInterface as Q, ResultIterator as R, type ScanBuilderInterface as S, type UpdateCommandParams as U, type PutCommandParams as a };

package/dist/{builder-types-B_tCpn9F.d.ts → builder-types-CzuLR4Th.d.ts}

@@ -14,6 +14,59 @@ interface DynamoCommandWithExpressions {
     [key: string]: unknown;
 }
 
+/**
+ * Function type for executing DynamoDB operations and returning raw results.
+ */
+type DirectExecutor<T extends DynamoItem> = () => Promise<{
+    items: T[];
+    lastEvaluatedKey?: DynamoItem;
+}>;
+/**
+ * Minimal result generator that provides async iteration over DynamoDB results with automatic pagination.
+ *
+ * @example
+ * ```typescript
+ * const results = await queryBuilder.execute();
+ *
+ * for await (const item of results) {
+ *   console.log(item);
+ * }
+ * ```
+ */
+declare class ResultIterator<T extends DynamoItem, TConfig extends TableConfig = TableConfig> {
+    private queryBuilder;
+    private directExecutor;
+    private lastEvaluatedKey?;
+    private itemsYielded;
+    private readonly overallLimit?;
+    constructor(queryBuilder: QueryBuilderInterface<T, TConfig>, directExecutor: DirectExecutor<T>);
+    /**
+     * Async iterator with automatic pagination
+     */
+    [Symbol.asyncIterator](): AsyncIterableIterator<T>;
+    /**
+     * Convert to array (loads all pages).
+     *
+     * ```ts
+     * const result = await table.query({ pk: "foo" }).execute();
+     * const allItemsFromDynamo = await result.toArray();
+     * ```
+     *
+     * Note: This will load all pages into memory. For large datasets, consider using async iteration instead.
+     *```ts
+     * const result = await table.query({ pk: "foo" }).execute();
+     * for await (const item of result) {
+     *   // Process each item
+     * }
+     * ```
+     */
+    toArray(): Promise<T[]>;
+    /**
+     * Get the last evaluated key
+     */
+    getLastEvaluatedKey(): DynamoItem | undefined;
+}
+
 interface DeleteCommandParams extends DynamoCommandWithExpressions {
     tableName: string;
     key: Record<string, unknown>;
@@ -77,10 +130,7 @@ interface BaseBuilderInterface<T extends DynamoItem, TConfig extends TableConfig
     limit(limit: number): B;
     getLimit(): number | undefined;
     startFrom(lastEvaluatedKey: DynamoItem): B;
-    execute(): Promise<{
-        items: T[];
-        lastEvaluatedKey?: DynamoItem;
-    }>;
+    execute(): Promise<ResultIterator<T, TConfig>>;
 }
 /**
  * Interface for the QueryBuilder class to be used by Paginator
@@ -116,4 +166,4 @@ interface PaginationResult<T> {
     page: number;
 }
 
-export type { ConditionCheckCommandParams as C, DeleteCommandParams as D, FilterBuilderInterface as F, PaginationResult as P, QueryBuilderInterface as Q, ScanBuilderInterface as S, UpdateCommandParams as U, PutCommandParams as a };
+export { type ConditionCheckCommandParams as C, type DeleteCommandParams as D, type FilterBuilderInterface as F, type PaginationResult as P, type QueryBuilderInterface as Q, ResultIterator as R, type ScanBuilderInterface as S, type UpdateCommandParams as U, type PutCommandParams as a };

package/dist/builders/condition-check-builder.cjs

@@ -252,10 +252,6 @@ var ConditionCheckBuilder = class {
   }
   /**
    * Adds a condition that must be satisfied for the check to succeed.
-   * Use this method when you need to:
-   * - Validate complex item states
-   * - Check multiple attributes together
-   * - Ensure safety conditions are met
    *
    * @example
    * ```typescript
@@ -351,10 +347,6 @@ var ConditionCheckBuilder = class {
   }
   /**
    * Adds this condition check operation to a transaction.
-   * Use this method when you need to:
-   * - Verify habitat safety before transfers
-   * - Ensure proper feeding conditions
-   * - Validate security protocols
    *
    * @example
    * ```ts
@@ -384,11 +376,6 @@ var ConditionCheckBuilder = class {
   /**
    * Gets a human-readable representation of the condition check command
    * with all expression placeholders replaced by their actual values.
-   * Use this method when you need to:
-   * - Debug complex condition expressions
-   * - Verify condition parameters
-   * - Log safety checks
-   * - Troubleshoot condition failures
    *
    * @example
    * ```ts