dyno-table 1.6.0 → 1.8.0-next.1

package/dist/{table-CY9byPEg.d.cts → table-CHitMHXE.d.cts}

@@ -1,152 +1,13 @@
 import { DynamoItem, TableConfig, Index } from './types.cjs';
 import { r as PrimaryKeyWithoutExpression, P as PrimaryKey } from './conditions-3ae5znV_.cjs';
-import { F as FilterBuilder, b as FilterOptions, Q as QueryBuilder } from './query-builder-CbHvimBk.cjs';
+import { F as FilterBuilder, b as FilterOptions, Q as QueryBuilder } from './query-builder-DFkxojBM.cjs';
 import { PutBuilder } from './builders/put-builder.cjs';
 import { DeleteBuilder } from './builders/delete-builder.cjs';
 import { UpdateBuilder } from './builders/update-builder.cjs';
 import { TransactionBuilder, TransactionOptions } from './builders/transaction-builder.cjs';
+import { G as GetBuilder, B as BatchBuilder, c as BatchWriteOperation } from './batch-builder-CKYnMRyz.cjs';
 import { ConditionCheckBuilder } from './builders/condition-check-builder.cjs';
-import { S as ScanBuilderInterface } from './builder-types-DlaUSc-b.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.
-     * Use this method when you need to:
-     * - Reduce data transfer by selecting specific dinosaur attributes
-     * - Optimize response size for dinosaur records
-     * - Focus on relevant dinosaur characteristics only
-     *
-     * @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>;
-    /**
-     * 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;
-    }>;
-}
+import { S as ScanBuilderInterface, R as ResultIterator } from './builder-types-BTVhQSHI.cjs';
 
 /**
  * Configuration options for DynamoDB scan operations.
@@ -211,57 +72,46 @@ declare class ScanBuilder<T extends DynamoItem, TConfig extends TableConfig = Ta
     constructor(executor: ScanExecutor<T>);
     /**
      * Creates a deep clone of this ScanBuilder instance.
-     * Use this method when you need to:
-     * - Create scan templates
-     * - Run multiple variations of a scan
-     * - Implement pagination (used internally by paginate())
      *
      * @returns A new ScanBuilder instance with the same configuration
      */
     clone(): ScanBuilder<T, TConfig>;
     /**
-     * Executes the scan against DynamoDB.
-     * Use this method when you need to:
-     * - Search across the entire table
-     * - Find items matching specific criteria
-     * - Perform full table analysis
-     * - Generate reports across all data
+     * Executes the scan against DynamoDB and returns a generator that behaves like an array.
      *
-     * The method returns both the matched items and, if there are more results,
-     * a lastEvaluatedKey that can be used with startFrom() to continue the scan.
+     * The generator automatically handles pagination and provides array-like methods
+     * for processing results efficiently without loading everything into memory at once.
      *
      * @example
      * ```typescript
      * try {
-     *   // Find all dinosaurs with high aggression levels
-     *   const result = await new ScanBuilder(executor)
+     *   // Find all dinosaurs with high aggression levels with automatic pagination
+     *   const results = await new ScanBuilder(executor)
      *     .filter(op =>
      *       op.and([
      *         op.eq('status', 'ACTIVE'),
      *         op.gt('aggressionLevel', 7)
      *       ])
      *     )
-     *     .limit(20)
      *     .execute();
      *
-     *   console.log(`Found ${result.items.length} potentially dangerous dinosaurs`);
-     *
-     *   if (result.lastEvaluatedKey) {
-     *     console.log('More results available');
+     *   // Use like an array with automatic pagination
+     *   for await (const dinosaur of results) {
+     *     console.log(`Processing dangerous dinosaur: ${dinosaur.name}`);
      *   }
+     *
+     *   // Or convert to array and use array methods
+     *   const allItems = await results.toArray();
+     *   const criticalThreats = allItems.filter(dino => dino.aggressionLevel > 9);
+     *   const totalCount = allItems.length;
      * } catch (error) {
      *   console.error('Security scan failed:', error);
      * }
      * ```
      *
-     * @returns A promise that resolves to an object containing:
-     *          - items: Array of items matching the scan criteria
-     *          - lastEvaluatedKey: Token for continuing the scan, if more items exist
+     * @returns A promise that resolves to a ResultGenerator that behaves like an array
      */
-    execute(): Promise<{
-        items: T[];
-        lastEvaluatedKey?: Record<string, unknown>;
-    }>;
+    execute(): Promise<ResultIterator<T, TConfig>>;
 }
 
 declare class Table<TConfig extends TableConfig = TableConfig> {
@@ -348,6 +198,42 @@ declare class Table<TConfig extends TableConfig = TableConfig> {
      * Creates a transaction builder for performing multiple operations atomically
      */
     transactionBuilder(): TransactionBuilder;
+    /**
+     * Creates a batch builder for performing multiple operations efficiently with optional type inference
+     *
+     * @example Basic Usage
+     * ```typescript
+     * const batch = table.batchBuilder();
+     *
+     * // Add operations
+     * userRepo.create(newUser).withBatch(batch);
+     * orderRepo.get({ id: 'order-1' }).withBatch(batch);
+     *
+     * // Execute operations
+     * const result = await batch.execute();
+     * ```
+     *
+     * @example Typed Usage
+     * ```typescript
+     * // Define entity types for the batch
+     * const batch = table.batchBuilder<{
+     *   User: UserEntity;
+     *   Order: OrderEntity;
+     *   Product: ProductEntity;
+     * }>();
+     *
+     * // Add operations with type information
+     * userRepo.create(newUser).withBatch(batch, 'User');
+     * orderRepo.get({ id: 'order-1' }).withBatch(batch, 'Order');
+     * productRepo.delete({ id: 'old-product' }).withBatch(batch, 'Product');
+     *
+     * // Execute and get typed results
+     * const result = await batch.execute();
+     * const users: UserEntity[] = result.reads.itemsByType.User;
+     * const orders: OrderEntity[] = result.reads.itemsByType.Order;
+     * ```
+     */
+    batchBuilder<TEntities extends Record<string, DynamoItem> = Record<string, DynamoItem>>(): BatchBuilder<TEntities>;
     /**
      * Executes a transaction using a callback function
      *
@@ -386,4 +272,4 @@ declare class Table<TConfig extends TableConfig = TableConfig> {
     }>;
 }
 
-export { GetBuilder as G, ScanBuilder as S, Table as T };
+export { ScanBuilder as S, Table as T };

package/dist/{table-Des8C2od.d.ts → table-m7DQk5dK.d.ts}

@@ -1,152 +1,13 @@
 import { DynamoItem, TableConfig, Index } from './types.js';
 import { r as PrimaryKeyWithoutExpression, P as PrimaryKey } from './conditions-BtynAviC.js';
-import { F as FilterBuilder, b as FilterOptions, Q as QueryBuilder } from './query-builder-BhrR31oO.js';
+import { F as FilterBuilder, b as FilterOptions, Q as QueryBuilder } from './query-builder-CaHzZmDf.js';
 import { PutBuilder } from './builders/put-builder.js';
 import { DeleteBuilder } from './builders/delete-builder.js';
 import { UpdateBuilder } from './builders/update-builder.js';
 import { TransactionBuilder, TransactionOptions } from './builders/transaction-builder.js';
+import { G as GetBuilder, B as BatchBuilder, c as BatchWriteOperation } from './batch-builder-BOBwOIUE.js';
 import { ConditionCheckBuilder } from './builders/condition-check-builder.js';
-import { S as ScanBuilderInterface } from './builder-types-B_tCpn9F.js';
-
-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.
-     * Use this method when you need to:
-     * - Reduce data transfer by selecting specific dinosaur attributes
-     * - Optimize response size for dinosaur records
-     * - Focus on relevant dinosaur characteristics only
-     *
-     * @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>;
-    /**
-     * 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;
-    }>;
-}
+import { S as ScanBuilderInterface, R as ResultIterator } from './builder-types-CzuLR4Th.js';
 
 /**
  * Configuration options for DynamoDB scan operations.
@@ -211,57 +72,46 @@ declare class ScanBuilder<T extends DynamoItem, TConfig extends TableConfig = Ta
     constructor(executor: ScanExecutor<T>);
     /**
      * Creates a deep clone of this ScanBuilder instance.
-     * Use this method when you need to:
-     * - Create scan templates
-     * - Run multiple variations of a scan
-     * - Implement pagination (used internally by paginate())
      *
      * @returns A new ScanBuilder instance with the same configuration
      */
     clone(): ScanBuilder<T, TConfig>;
     /**
-     * Executes the scan against DynamoDB.
-     * Use this method when you need to:
-     * - Search across the entire table
-     * - Find items matching specific criteria
-     * - Perform full table analysis
-     * - Generate reports across all data
+     * Executes the scan against DynamoDB and returns a generator that behaves like an array.
      *
-     * The method returns both the matched items and, if there are more results,
-     * a lastEvaluatedKey that can be used with startFrom() to continue the scan.
+     * The generator automatically handles pagination and provides array-like methods
+     * for processing results efficiently without loading everything into memory at once.
      *
      * @example
      * ```typescript
      * try {
-     *   // Find all dinosaurs with high aggression levels
-     *   const result = await new ScanBuilder(executor)
+     *   // Find all dinosaurs with high aggression levels with automatic pagination
+     *   const results = await new ScanBuilder(executor)
      *     .filter(op =>
      *       op.and([
      *         op.eq('status', 'ACTIVE'),
      *         op.gt('aggressionLevel', 7)
      *       ])
      *     )
-     *     .limit(20)
      *     .execute();
      *
-     *   console.log(`Found ${result.items.length} potentially dangerous dinosaurs`);
-     *
-     *   if (result.lastEvaluatedKey) {
-     *     console.log('More results available');
+     *   // Use like an array with automatic pagination
+     *   for await (const dinosaur of results) {
+     *     console.log(`Processing dangerous dinosaur: ${dinosaur.name}`);
      *   }
+     *
+     *   // Or convert to array and use array methods
+     *   const allItems = await results.toArray();
+     *   const criticalThreats = allItems.filter(dino => dino.aggressionLevel > 9);
+     *   const totalCount = allItems.length;
      * } catch (error) {
      *   console.error('Security scan failed:', error);
      * }
      * ```
      *
-     * @returns A promise that resolves to an object containing:
-     *          - items: Array of items matching the scan criteria
-     *          - lastEvaluatedKey: Token for continuing the scan, if more items exist
+     * @returns A promise that resolves to a ResultGenerator that behaves like an array
      */
-    execute(): Promise<{
-        items: T[];
-        lastEvaluatedKey?: Record<string, unknown>;
-    }>;
+    execute(): Promise<ResultIterator<T, TConfig>>;
 }
 
 declare class Table<TConfig extends TableConfig = TableConfig> {
@@ -348,6 +198,42 @@ declare class Table<TConfig extends TableConfig = TableConfig> {
      * Creates a transaction builder for performing multiple operations atomically
      */
     transactionBuilder(): TransactionBuilder;
+    /**
+     * Creates a batch builder for performing multiple operations efficiently with optional type inference
+     *
+     * @example Basic Usage
+     * ```typescript
+     * const batch = table.batchBuilder();
+     *
+     * // Add operations
+     * userRepo.create(newUser).withBatch(batch);
+     * orderRepo.get({ id: 'order-1' }).withBatch(batch);
+     *
+     * // Execute operations
+     * const result = await batch.execute();
+     * ```
+     *
+     * @example Typed Usage
+     * ```typescript
+     * // Define entity types for the batch
+     * const batch = table.batchBuilder<{
+     *   User: UserEntity;
+     *   Order: OrderEntity;
+     *   Product: ProductEntity;
+     * }>();
+     *
+     * // Add operations with type information
+     * userRepo.create(newUser).withBatch(batch, 'User');
+     * orderRepo.get({ id: 'order-1' }).withBatch(batch, 'Order');
+     * productRepo.delete({ id: 'old-product' }).withBatch(batch, 'Product');
+     *
+     * // Execute and get typed results
+     * const result = await batch.execute();
+     * const users: UserEntity[] = result.reads.itemsByType.User;
+     * const orders: OrderEntity[] = result.reads.itemsByType.Order;
+     * ```
+     */
+    batchBuilder<TEntities extends Record<string, DynamoItem> = Record<string, DynamoItem>>(): BatchBuilder<TEntities>;
     /**
      * Executes a transaction using a callback function
      *
@@ -386,4 +272,4 @@ declare class Table<TConfig extends TableConfig = TableConfig> {
     }>;
 }
 
-export { GetBuilder as G, ScanBuilder as S, Table as T };
+export { ScanBuilder as S, Table as T };