dyno-table 1.6.0 → 1.7.0

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
@@ -343,16 +329,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 +370,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 +400,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 +428,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 +458,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 +510,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
@@ -624,11 +576,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.
@@ -895,10 +842,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 +974,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 +1006,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 +1239,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 +1519,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 +1842,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 +1899,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 +1930,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 +1987,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 +2033,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 +2110,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 +2159,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 +2225,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 +2272,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 +2299,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 +2327,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 +2450,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 +2545,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 +2574,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 +2596,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 +2894,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 +2947,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 +3026,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 +3040,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
    */
@@ -2779,11 +3051,6 @@ var ScanBuilder = class _ScanBuilder extends FilterBuilder {
   }
   /**
    * 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
    *
    * 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.
@@ -3178,6 +3445,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
    *