dyno-table 1.6.0 → 1.8.0-next.1

package/dist/table.cjs

@@ -210,10 +210,6 @@ var Paginator = class {
   }
   /**
    * Gets the current page number (1-indexed).
-   * Use this method when you need to:
-   * - Track progress through dinosaur lists
-   * - Display habitat inspection status
-   * - Monitor security sweep progress
    *
    * @example
    * ```ts
@@ -231,11 +227,6 @@ var Paginator = class {
   }
   /**
    * Checks if there are more pages of dinosaurs or habitats to process.
-   * Use this method when you need to:
-   * - Check for more dinosaurs to review
-   * - Continue habitat inspections
-   * - Process security incidents
-   * - Complete feeding schedules
    *
    * This method takes into account both:
    * - DynamoDB's lastEvaluatedKey mechanism
@@ -267,11 +258,6 @@ var Paginator = class {
   }
   /**
    * Retrieves the next page of dinosaurs or habitats from DynamoDB.
-   * Use this method when you need to:
-   * - Process dinosaur groups systematically
-   * - Review habitat inspections in batches
-   * - Monitor security incidents in sequence
-   * - Schedule feeding rotations
    *
    * This method handles:
    * - Automatic continuation between groups
@@ -323,13 +309,31 @@ var Paginator = class {
           page: this.currentPage
         };
       }
-      effectivePageSize = Math.min(effectivePageSize, remainingItems);
+      if (effectivePageSize !== void 0) {
+        effectivePageSize = Math.min(effectivePageSize, remainingItems);
+      } else {
+        effectivePageSize = remainingItems;
+      }
+    }
+    const query = this.queryBuilder.clone();
+    if (effectivePageSize !== void 0) {
+      query.limit(effectivePageSize);
     }
-    const query = this.queryBuilder.clone().limit(effectivePageSize);
     if (this.lastEvaluatedKey) {
       query.startFrom(this.lastEvaluatedKey);
     }
-    const result = await query.execute();
+    const generator = await query.execute();
+    const items = [];
+    let itemCount = 0;
+    for await (const item of generator) {
+      if (effectivePageSize !== void 0 && itemCount >= effectivePageSize) {
+        break;
+      }
+      items.push(item);
+      itemCount++;
+    }
+    const lastEvaluatedKey = generator.getLastEvaluatedKey();
+    const result = { items, lastEvaluatedKey };
     this.currentPage += 1;
     this.lastEvaluatedKey = result.lastEvaluatedKey;
     this.totalItemsRetrieved += result.items.length;
@@ -343,16 +347,6 @@ var Paginator = class {
   }
   /**
    * Gets all remaining dinosaurs or habitats and combines them into a single array.
-   * Use this method when you need to:
-   * - Generate complete park inventory
-   * - Perform full security audit
-   * - Create comprehensive feeding schedule
-   * - Run park-wide health checks
-   *
-   * Note: Use with caution! This method:
-   * - Could overwhelm systems with large dinosaur populations
-   * - Makes multiple database requests
-   * - May cause system strain during peak hours
    *
    * @example
    * ```ts
@@ -394,10 +388,6 @@ var FilterBuilder = class {
   selectedFields = /* @__PURE__ */ new Set();
   /**
    * Sets the maximum number of items to return.
-   * Use this method when you need to:
-   * - Limit the number of dinosaurs returned
-   * - Control the size of habitat reports
-   * - Implement manual pagination of security logs
    *
    * Note: This limit applies to the items that match the key condition
    * before any filter expressions are applied.
@@ -428,11 +418,6 @@ var FilterBuilder = class {
   }
   /**
    * Specifies a Global Secondary Index (GSI) to use for the operation.
-   * Use this method when you need to:
-   * - Find dinosaurs by species or status
-   * - Search habitats by security level
-   * - Find incidents by date
-   * - List feeding schedules by time
    *
    * @example
    * ```typescript
@@ -461,11 +446,6 @@ var FilterBuilder = class {
   }
   /**
    * Sets whether to use strongly consistent reads for the operation.
-   * Use this method when you need to:
-   * - Get real-time dinosaur status updates
-   * - Monitor critical security systems
-   * - Track immediate habitat changes
-   * - Verify containment protocols
    *
    * Note:
    * - Consistent reads are not available on GSIs
@@ -496,11 +476,6 @@ var FilterBuilder = class {
   }
   /**
    * Adds a filter expression to refine the operation results.
-   * Use this method when you need to:
-   * - Filter dinosaurs by behavior patterns
-   * - Find habitats with specific conditions
-   * - Search for security incidents
-   * - Monitor feeding patterns
    *
    * @example
    * ```typescript
@@ -553,11 +528,6 @@ var FilterBuilder = class {
   }
   /**
    * Specifies which attributes to return in the results.
-   * Use this method when you need to:
-   * - Get specific dinosaur attributes
-   * - Retrieve habitat statistics
-   * - Monitor security metrics
-   * - Optimize response size
    *
    * @example
    * ```typescript
@@ -602,11 +572,16 @@ var FilterBuilder = class {
    *
    * @example
    * ```typescript
-   * // Create a paginator for dinosaur records
+   * // Create a paginator for dinosaur records with specific page size
    * const paginator = builder
    *   .filter(op => op.eq('status', 'ACTIVE'))
    *   .paginate(10);
    *
+   * // Create a paginator with automatic DynamoDB paging (no page size limit)
+   * const autoPaginator = builder
+   *   .filter(op => op.eq('status', 'ACTIVE'))
+   *   .paginate();
+   *
    * // Process pages of dinosaur results
    * while (paginator.hasNextPage()) {
    *   const page = await paginator.getNextPage();
@@ -615,7 +590,7 @@ var FilterBuilder = class {
    * }
    * ```
    *
-   * @param pageSize - The number of items to return per page
+   * @param pageSize - The number of items to return per page. If not provided, DynamoDB will automatically determine page sizes.
    * @returns A Paginator instance that manages the pagination state
    * @see Paginator for more pagination control options
    */
@@ -624,11 +599,6 @@ var FilterBuilder = class {
   }
   /**
    * Sets the starting point using a previous lastEvaluatedKey.
-   * Use this method when you need to:
-   * - Implement manual dinosaur list pagination
-   * - Resume habitat inspection reviews
-   * - Continue security incident analysis
-   * - Store operation position between sessions
    *
    * Note: This method is typically used for manual pagination.
    * For automatic pagination, use the paginate() method instead.
@@ -641,15 +611,17 @@ var FilterBuilder = class {
    *   .limit(5)
    *   .execute();
    *
-   * if (result1.lastEvaluatedKey) {
+   * const lastKey = result1.getLastEvaluatedKey();
+   * if (lastKey) {
    *   // Continue listing dinosaurs
    *   const result2 = await builder
    *     .filter(op => op.eq('status', 'ACTIVE'))
-   *     .startFrom(result1.lastEvaluatedKey)
+   *     .startFrom(lastKey)
    *     .limit(5)
    *     .execute();
    *
-   *   console.log('Additional dinosaurs:', result2.items);
+   *   const items = await result2.toArray();
+   *   console.log('Additional dinosaurs:', items);
    * }
    * ```
    *
@@ -662,6 +634,72 @@ var FilterBuilder = class {
   }
 };
 
+// src/builders/result-iterator.ts
+var ResultIterator = class {
+  constructor(queryBuilder, directExecutor) {
+    this.queryBuilder = queryBuilder;
+    this.directExecutor = directExecutor;
+    this.overallLimit = queryBuilder.getLimit();
+  }
+  lastEvaluatedKey;
+  itemsYielded = 0;
+  overallLimit;
+  /**
+   * Async iterator with automatic pagination
+   */
+  async *[Symbol.asyncIterator]() {
+    let hasMorePages = true;
+    while (hasMorePages) {
+      const result = await this.directExecutor();
+      for (const item of result.items) {
+        if (this.overallLimit !== void 0 && this.itemsYielded >= this.overallLimit) {
+          return;
+        }
+        yield item;
+        this.itemsYielded++;
+      }
+      if (result.lastEvaluatedKey !== null && result.lastEvaluatedKey !== void 0) {
+        this.lastEvaluatedKey = result.lastEvaluatedKey;
+        this.queryBuilder.startFrom(result.lastEvaluatedKey);
+      } else if (result.lastEvaluatedKey === null) {
+        if (this.lastEvaluatedKey === void 0) {
+          this.lastEvaluatedKey = null;
+        }
+      }
+      hasMorePages = !!result.lastEvaluatedKey && (this.overallLimit === void 0 || this.itemsYielded < this.overallLimit);
+    }
+  }
+  /**
+   * 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
+   * }
+   * ```
+   */
+  async toArray() {
+    const items = [];
+    for await (const item of this) {
+      items.push(item);
+    }
+    return items;
+  }
+  /**
+   * Get the last evaluated key
+   */
+  getLastEvaluatedKey() {
+    return this.lastEvaluatedKey === null ? void 0 : this.lastEvaluatedKey;
+  }
+};
+
 // src/builders/query-builder.ts
 var QueryBuilder = class _QueryBuilder extends FilterBuilder {
   keyCondition;
@@ -783,16 +821,16 @@ var QueryBuilder = class _QueryBuilder extends FilterBuilder {
     return clone;
   }
   /**
-   * Executes the query against DynamoDB.
+   * Executes the query 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 query.
+   * 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 active carnivores in specific habitat
-   *   const result = await new QueryBuilder(executor, eq('habitatId', 'PADDOCK-A'))
+   *   // Find active carnivores with automatic pagination
+   *   const results = await new QueryBuilder(executor, eq('habitatId', 'PADDOCK-A'))
    *     .useIndex('species-status-index')
    *     .filter(op =>
    *       op.and([
@@ -802,25 +840,27 @@ var QueryBuilder = class _QueryBuilder extends FilterBuilder {
    *       ])
    *     )
    *     .sortDescending()
-   *     .limit(5)
    *     .execute();
    *
-   *   console.log(`Found ${result.items.length} dangerous dinosaurs`);
-   *
-   *   if (result.lastEvaluatedKey) {
-   *     console.log('Additional threats detected');
+   *   // Use like an array with automatic pagination
+   *   for await (const dinosaur of results) {
+   *     console.log(`Processing ${dinosaur.name}`);
    *   }
+   *
+   *   // Or convert to array and use array methods
+   *   const allItems = await results.toArray();
+   *   const dangerousOnes = 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 query
-   *          - lastEvaluatedKey: Token for continuing the query, if more items exist
+   * @returns A promise that resolves to a ResultGenerator that behaves like an array
    */
   async execute() {
-    return this.executor(this.keyCondition, this.options);
+    const directExecutor = () => this.executor(this.keyCondition, this.options);
+    return new ResultIterator(this, directExecutor);
   }
 };
 
@@ -895,10 +935,6 @@ var PutBuilder = class {
   }
   /**
    * Adds a condition that must be satisfied for the put operation to succeed.
-   * Use this method when you need to:
-   * - Prevent overwriting existing items (optimistic locking)
-   * - Ensure items meet certain criteria before replacement
-   * - Implement complex business rules for item updates
    *
    * @example
    * ```ts
@@ -1031,10 +1067,6 @@ var PutBuilder = class {
   }
   /**
    * Adds this put operation to a transaction.
-   * Use this method when you need to:
-   * - Transfer dinosaurs between habitats
-   * - Initialize new breeding programs
-   * - Update multiple facility records
    *
    * @example
    * ```ts
@@ -1067,6 +1099,45 @@ var PutBuilder = class {
     transaction.putWithCommand(command);
     return this;
   }
+  /**
+   * Adds this put operation to a batch with optional entity type information.
+   *
+   * @example Basic Usage
+   * ```ts
+   * const batch = table.batchBuilder();
+   *
+   * // Add multiple dinosaurs to batch
+   * dinosaurRepo.create(newDino1).withBatch(batch);
+   * dinosaurRepo.create(newDino2).withBatch(batch);
+   * dinosaurRepo.create(newDino3).withBatch(batch);
+   *
+   * // Execute all operations efficiently
+   * await batch.execute();
+   * ```
+   *
+   * @example Typed Usage
+   * ```ts
+   * const batch = table.batchBuilder<{
+   *   User: UserEntity;
+   *   Order: OrderEntity;
+   * }>();
+   *
+   * // Add operations with type information
+   * userRepo.create(newUser).withBatch(batch, 'User');
+   * orderRepo.create(newOrder).withBatch(batch, 'Order');
+   *
+   * // Execute and get typed results
+   * const result = await batch.execute();
+   * const users: UserEntity[] = result.reads.itemsByType.User;
+   * ```
+   *
+   * @param batch - The batch builder to add this operation to
+   * @param entityType - Optional entity type key for type tracking
+   */
+  withBatch(batch, entityType) {
+    const command = this.toDynamoCommand();
+    batch.putWithCommand(command, entityType);
+  }
   /**
    * Executes the put operation against DynamoDB.
    *
@@ -1261,6 +1332,44 @@ var DeleteBuilder = class {
     const command = this.toDynamoCommand();
     transaction.deleteWithCommand(command);
   }
+  /**
+   * Adds this delete operation to a batch with optional entity type information.
+   *
+   * @example Basic Usage
+   * ```ts
+   * const batch = table.batchBuilder();
+   *
+   * // Remove multiple dinosaurs in batch
+   * dinosaurRepo.delete({ id: 'old-dino-1' }).withBatch(batch);
+   * dinosaurRepo.delete({ id: 'old-dino-2' }).withBatch(batch);
+   * dinosaurRepo.delete({ id: 'old-dino-3' }).withBatch(batch);
+   *
+   * // Execute all deletions efficiently
+   * await batch.execute();
+   * ```
+   *
+   * @example Typed Usage
+   * ```ts
+   * const batch = table.batchBuilder<{
+   *   User: UserEntity;
+   *   Order: OrderEntity;
+   * }>();
+   *
+   * // Add operations with type information
+   * userRepo.delete({ id: 'user-1' }).withBatch(batch, 'User');
+   * orderRepo.delete({ id: 'order-1' }).withBatch(batch, 'Order');
+   *
+   * // Execute batch operations
+   * await batch.execute();
+   * ```
+   *
+   * @param batch - The batch builder to add this operation to
+   * @param entityType - Optional entity type key for type tracking
+   */
+  withBatch(batch, entityType) {
+    const command = this.toDynamoCommand();
+    batch.deleteWithCommand(command, entityType);
+  }
   /**
    * Executes the delete operation against DynamoDB.
    *
@@ -1503,11 +1612,11 @@ var UpdateBuilder = class {
    * Sets which item attributes to include in the response.
    *
    * Available options:
-   * - ALL_NEW: All attributes after the update
+   * - ALL_NEW: All attributes after the update (default)
    * - UPDATED_NEW: Only updated attributes, new values
    * - ALL_OLD: All attributes before the update
    * - UPDATED_OLD: Only updated attributes, old values
-   * - NONE: No attributes returned (default)
+   * - NONE: No attributes returned
    *
    * @example
    * ```typescript
@@ -1826,10 +1935,6 @@ var TransactionBuilder = class {
   }
   /**
    * Adds a put operation to the transaction.
-   * Use this method when you need to:
-   * - Insert new items as part of a transaction
-   * - Replace existing items atomically
-   * - Ensure items meet certain conditions before insertion
    *
    * The method automatically checks for duplicate items within the transaction
    * to prevent multiple operations on the same item.
@@ -1887,10 +1992,6 @@ var TransactionBuilder = class {
   }
   /**
    * Adds a pre-configured put operation to the transaction.
-   * Use this method when you need to:
-   * - Reuse put commands from PutBuilder
-   * - Add complex put operations with pre-configured parameters
-   * - Integrate with existing put command configurations
    *
    * This method is particularly useful when working with PutBuilder
    * to maintain consistency in put operations across your application.
@@ -1922,10 +2023,6 @@ var TransactionBuilder = class {
   }
   /**
    * Adds a delete operation to the transaction.
-   * Use this method when you need to:
-   * - Remove items as part of a transaction
-   * - Conditionally delete items
-   * - Ensure items exist before deletion
    *
    * The method automatically checks for duplicate items within the transaction
    * to prevent multiple operations on the same item.
@@ -1983,10 +2080,6 @@ var TransactionBuilder = class {
   }
   /**
    * Adds a pre-configured delete operation to the transaction.
-   * Use this method when you need to:
-   * - Reuse delete commands from DeleteBuilder
-   * - Add complex delete operations with pre-configured parameters
-   * - Integrate with existing delete command configurations
    *
    * This method is particularly useful when working with DeleteBuilder
    * to maintain consistency in delete operations across your application.
@@ -2033,11 +2126,6 @@ var TransactionBuilder = class {
   }
   /**
    * Adds an update operation to the transaction.
-   * Use this method when you need to:
-   * - Modify existing items as part of a transaction
-   * - Update multiple attributes atomically
-   * - Apply conditional updates
-   * - Perform complex attribute manipulations
    *
    * The method supports all DynamoDB update expressions:
    * - SET: Modify or add attributes
@@ -2115,10 +2203,6 @@ var TransactionBuilder = class {
   }
   /**
    * Adds a pre-configured update operation to the transaction.
-   * Use this method when you need to:
-   * - Reuse update commands from UpdateBuilder
-   * - Add complex update operations with pre-configured parameters
-   * - Integrate with existing update command configurations
    *
    * This method is particularly useful when working with UpdateBuilder
    * to maintain consistency in update operations across your application.
@@ -2168,11 +2252,6 @@ var TransactionBuilder = class {
   }
   /**
    * Adds a condition check operation to the transaction.
-   * Use this method when you need to:
-   * - Validate item state without modifying it
-   * - Ensure data consistency across tables
-   * - Implement complex business rules
-   * - Verify preconditions for other operations
    *
    * Condition checks are particularly useful for:
    * - Implementing optimistic locking
@@ -2239,10 +2318,6 @@ var TransactionBuilder = class {
   }
   /**
    * Adds a pre-configured condition check operation to the transaction.
-   * Use this method when you need to:
-   * - Reuse condition checks from ConditionCheckBuilder
-   * - Add complex condition checks with pre-configured parameters
-   * - Integrate with existing condition check configurations
    *
    * This method is particularly useful when working with ConditionCheckBuilder
    * to maintain consistency in condition checks across your application.
@@ -2290,10 +2365,6 @@ var TransactionBuilder = class {
   }
   /**
    * Sets options for the transaction execution.
-   * Use this method when you need to:
-   * - Enable idempotent transactions
-   * - Track consumed capacity
-   * - Monitor item collection metrics
    *
    * @example
    * ```typescript
@@ -2321,11 +2392,6 @@ var TransactionBuilder = class {
   }
   /**
    * Gets a human-readable representation of the transaction items.
-   * Use this method when you need to:
-   * - Debug complex transactions
-   * - Verify operation parameters
-   * - Log transaction details
-   * - Troubleshoot condition expressions
    *
    * The method resolves all expression placeholders with their actual values,
    * making it easier to understand the transaction's operations.
@@ -2354,10 +2420,6 @@ var TransactionBuilder = class {
   }
   /**
    * Executes all operations in the transaction atomically.
-   * Use this method when you need to:
-   * - Perform multiple operations atomically
-   * - Ensure all-or-nothing execution
-   * - Maintain data consistency across operations
    *
    * The transaction will only succeed if all operations succeed.
    * If any operation fails, the entire transaction is rolled back.
@@ -2481,10 +2543,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
@@ -2580,10 +2638,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
@@ -2613,11 +2667,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
@@ -2640,6 +2689,283 @@ var ConditionCheckBuilder = class {
   }
 };
 
+// src/builders/batch-builder.ts
+var BatchError = class extends Error {
+  operation;
+  cause;
+  constructor(message, operation, cause) {
+    super(message);
+    this.name = "BatchError";
+    this.operation = operation;
+    this.cause = cause;
+  }
+};
+var BatchBuilder = class {
+  constructor(batchWriteExecutor, batchGetExecutor, config) {
+    this.batchWriteExecutor = batchWriteExecutor;
+    this.batchGetExecutor = batchGetExecutor;
+    this.config = config;
+  }
+  writeItems = [];
+  getItems = [];
+  /**
+   * Checks if the batch is empty (contains no operations)
+   *
+   * @returns true if the batch contains no operations
+   */
+  isEmpty() {
+    return this.writeItems.length === 0 && this.getItems.length === 0;
+  }
+  /**
+   * Gets the count of operations in the batch
+   *
+   * @returns Object containing the count of write and read operations
+   */
+  getOperationCount() {
+    return {
+      writes: this.writeItems.length,
+      reads: this.getItems.length
+    };
+  }
+  /**
+   * Validates that the batch is not empty before execution
+   *
+   * @throws {BatchError} If the batch is empty
+   */
+  validateNotEmpty() {
+    if (this.isEmpty()) {
+      throw new BatchError(
+        "Cannot execute empty batch. Add operations using entity builders with .withBatch()",
+        "write"
+      );
+    }
+  }
+  /**
+   * 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(command, entityType) {
+    const batchItem = {
+      type: "Put",
+      params: command,
+      entityType
+    };
+    this.writeItems.push(batchItem);
+    return 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(command, entityType) {
+    const batchItem = {
+      type: "Delete",
+      params: command,
+      entityType
+    };
+    this.writeItems.push(batchItem);
+    return 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(command, entityType) {
+    const batchItem = {
+      type: "Get",
+      params: command,
+      entityType
+    };
+    this.getItems.push(batchItem);
+    return this;
+  }
+  /**
+   * Executes all write operations in the batch.
+   *
+   * @returns A promise that resolves to any unprocessed operations
+   * @private
+   */
+  async executeWrites() {
+    if (this.writeItems.length === 0) {
+      return { unprocessedItems: [] };
+    }
+    try {
+      const operations = this.writeItems.map((item) => {
+        if (item.type === "Put") {
+          return {
+            type: "put",
+            item: item.params.item
+          };
+        }
+        if (item.type === "Delete") {
+          let key;
+          if (typeof item.params.key === "object" && item.params.key !== null && "pk" in item.params.key) {
+            key = item.params.key;
+          } else {
+            const tableKey = item.params.key;
+            key = {
+              pk: tableKey[this.config.partitionKey],
+              sk: this.config.sortKey ? tableKey[this.config.sortKey] : void 0
+            };
+          }
+          return {
+            type: "delete",
+            key
+          };
+        }
+        throw new BatchError(`Unsupported batch item type for write operation: ${item.type}`, "write");
+      });
+      return await this.batchWriteExecutor(operations);
+    } catch (error) {
+      throw new BatchError(
+        `Failed to execute batch write operations: ${error instanceof Error ? error.message : "Unknown error"}`,
+        "write",
+        error instanceof Error ? error : void 0
+      );
+    }
+  }
+  /**
+   * Executes all get operations in the batch.
+   *
+   * @returns A promise that resolves to the retrieved items
+   * @private
+   */
+  async executeGets() {
+    if (this.getItems.length === 0) {
+      return { items: [], unprocessedKeys: [] };
+    }
+    try {
+      const keys = this.getItems.map((item) => {
+        if (item.type === "Get") {
+          if (typeof item.params.key === "object" && item.params.key !== null && "pk" in item.params.key) {
+            return item.params.key;
+          }
+          const tableKey = item.params.key;
+          return {
+            pk: tableKey[this.config.partitionKey],
+            sk: this.config.sortKey ? tableKey[this.config.sortKey] : void 0
+          };
+        }
+        throw new BatchError(`Unsupported batch item type for get operation: ${item.type}`, "read");
+      });
+      return await this.batchGetExecutor(keys);
+    } catch (error) {
+      throw new BatchError(
+        `Failed to execute batch get operations: ${error instanceof Error ? error.message : "Unknown error"}`,
+        "read",
+        error instanceof Error ? error : void 0
+      );
+    }
+  }
+  /**
+   * Groups retrieved items by their entity type.
+   * @private
+   */
+  groupItemsByType(items) {
+    const grouped = {};
+    for (const item of this.getItems) {
+      if (item.entityType) {
+        const entityType = item.entityType;
+        if (!grouped[entityType]) {
+          grouped[entityType] = [];
+        }
+      }
+    }
+    for (const item of items) {
+      const entityType = item.entityType;
+      if (entityType && grouped[entityType]) {
+        grouped[entityType].push(item);
+      }
+    }
+    return grouped;
+  }
+  /**
+   * 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
+   */
+  async execute() {
+    this.validateNotEmpty();
+    const errors = [];
+    let writeResults = { unprocessedItems: [] };
+    let getResults = {
+      items: [],
+      unprocessedKeys: []
+    };
+    if (this.writeItems.length > 0) {
+      try {
+        writeResults = await this.executeWrites();
+      } catch (error) {
+        if (error instanceof BatchError) {
+          errors.push(error);
+        } else {
+          errors.push(
+            new BatchError(
+              "Unexpected error during write operations",
+              "write",
+              error instanceof Error ? error : void 0
+            )
+          );
+        }
+      }
+    }
+    if (this.getItems.length > 0) {
+      try {
+        getResults = await this.executeGets();
+      } catch (error) {
+        if (error instanceof BatchError) {
+          errors.push(error);
+        } else {
+          errors.push(
+            new BatchError(
+              "Unexpected error during read operations",
+              "read",
+              error instanceof Error ? error : void 0
+            )
+          );
+        }
+      }
+    }
+    if (errors.length > 0 && (writeResults.unprocessedItems.length === this.writeItems.length || getResults.unprocessedKeys.length === this.getItems.length)) {
+      throw errors[0];
+    }
+    const totalOperations = this.writeItems.length + this.getItems.length;
+    const success = errors.length === 0 && writeResults.unprocessedItems.length === 0 && getResults.unprocessedKeys.length === 0;
+    return {
+      success,
+      writes: {
+        processed: this.writeItems.length - writeResults.unprocessedItems.length,
+        unprocessed: writeResults.unprocessedItems
+      },
+      reads: {
+        itemsByType: this.groupItemsByType(getResults.items),
+        items: getResults.items,
+        found: getResults.items.length,
+        unprocessed: getResults.unprocessedKeys
+      },
+      totalOperations,
+      errors: errors.length > 0 ? errors : void 0
+    };
+  }
+};
+
 // src/builders/get-builder.ts
 var GetBuilder = class {
   /**
@@ -2661,10 +2987,6 @@ var GetBuilder = class {
   selectedFields = /* @__PURE__ */ new Set();
   /**
    * 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
@@ -2718,6 +3040,60 @@ var GetBuilder = class {
     this.params.consistentRead = consistentRead;
     return this;
   }
+  /**
+   * 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(batch, entityType) {
+    const command = this.toDynamoCommand();
+    batch.getWithCommand(command, entityType);
+  }
+  /**
+   * Converts the builder configuration to a DynamoDB command
+   */
+  toDynamoCommand() {
+    const expressionParams = {
+      expressionAttributeNames: {}};
+    const projectionExpression = Array.from(this.selectedFields).map((p) => generateAttributeName(expressionParams, p)).join(", ");
+    const { expressionAttributeNames } = expressionParams;
+    return {
+      ...this.params,
+      projectionExpression: projectionExpression.length > 0 ? projectionExpression : void 0,
+      expressionAttributeNames: Object.keys(expressionAttributeNames).length > 0 ? expressionAttributeNames : void 0
+    };
+  }
   /**
    * Executes the get operation against DynamoDB.
    *
@@ -2743,15 +3119,8 @@ var GetBuilder = class {
    *          - item: The retrieved dinosaur or undefined if not found
    */
   async execute() {
-    const expressionParams = {
-      expressionAttributeNames: {}};
-    const projectionExpression = Array.from(this.selectedFields).map((p) => generateAttributeName(expressionParams, p)).join(", ");
-    const { expressionAttributeNames } = expressionParams;
-    return this.executor({
-      ...this.params,
-      projectionExpression: projectionExpression.length > 0 ? projectionExpression : void 0,
-      expressionAttributeNames: Object.keys(expressionAttributeNames).length > 0 ? expressionAttributeNames : void 0
-    });
+    const command = this.toDynamoCommand();
+    return this.executor(command);
   }
 };
 
@@ -2764,10 +3133,6 @@ var ScanBuilder = class _ScanBuilder extends FilterBuilder {
   }
   /**
    * 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
    */
@@ -2778,46 +3143,43 @@ var ScanBuilder = class _ScanBuilder extends FilterBuilder {
     return clone;
   }
   /**
-   * 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
    */
   async execute() {
-    return this.executor(this.options);
+    const directExecutor = () => this.executor(this.options);
+    return new ResultIterator(this, directExecutor);
   }
 };
 
@@ -3178,6 +3540,53 @@ var Table = class {
       sortKey: this.sortKey
     });
   }
+  /**
+   * 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() {
+    const batchWriteExecutor = async (operations) => {
+      return this.batchWrite(operations);
+    };
+    const batchGetExecutor = async (keys) => {
+      return this.batchGet(keys);
+    };
+    return new BatchBuilder(batchWriteExecutor, batchGetExecutor, {
+      partitionKey: this.partitionKey,
+      sortKey: this.sortKey
+    });
+  }
   /**
    * Executes a transaction using a callback function
    *