dyno-table 1.5.0 → 1.7.0

package/dist/index.js

@@ -208,10 +208,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
@@ -229,11 +225,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
@@ -265,11 +256,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
@@ -341,16 +327,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
@@ -392,10 +368,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.
@@ -426,11 +398,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
@@ -459,11 +426,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
@@ -494,11 +456,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
@@ -551,11 +508,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
@@ -622,11 +574,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.
@@ -893,10 +840,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
@@ -1029,10 +972,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
@@ -1065,6 +1004,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.
    *
@@ -1259,6 +1237,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.
    *
@@ -1501,11 +1517,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
@@ -1824,10 +1840,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.
@@ -1885,10 +1897,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.
@@ -1920,10 +1928,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.
@@ -1981,10 +1985,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.
@@ -2031,11 +2031,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
@@ -2113,10 +2108,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.
@@ -2166,11 +2157,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
@@ -2237,10 +2223,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.
@@ -2288,10 +2270,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
@@ -2319,11 +2297,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.
@@ -2352,10 +2325,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.
@@ -2479,10 +2448,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
@@ -2578,10 +2543,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
@@ -2611,11 +2572,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
@@ -2638,6 +2594,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 {
   /**
@@ -2659,10 +2892,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
@@ -2716,6 +2945,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.
    *
@@ -2741,15 +3024,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);
   }
 };
 
@@ -2762,10 +3038,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
    */
@@ -2777,11 +3049,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.
@@ -3176,6 +3443,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
    *
@@ -3316,9 +3630,55 @@ var Table = class {
   }
 };
 
+// src/builders/entity-aware-builders.ts
+function createEntityAwareBuilder(builder, entityName) {
+  return new Proxy(builder, {
+    get(target, prop, receiver) {
+      if (prop === "entityName") {
+        return entityName;
+      }
+      if (prop === "withBatch" && typeof target[prop] === "function") {
+        return (batch, entityType) => {
+          const typeToUse = entityType ?? entityName;
+          const fn = target[prop];
+          return fn.call(target, batch, typeToUse);
+        };
+      }
+      return Reflect.get(target, prop, receiver);
+    }
+  });
+}
+function createEntityAwarePutBuilder(builder, entityName) {
+  return createEntityAwareBuilder(builder, entityName);
+}
+function createEntityAwareGetBuilder(builder, entityName) {
+  return createEntityAwareBuilder(builder, entityName);
+}
+function createEntityAwareDeleteBuilder(builder, entityName) {
+  return createEntityAwareBuilder(builder, entityName);
+}
+
 // src/entity.ts
 function defineEntity(config) {
   const entityTypeAttributeName = config.settings?.entityTypeAttributeName ?? "entityType";
+  const wrapMethodWithPreparation = (originalMethod, prepareFn, context) => {
+    const wrappedMethod = (...args) => {
+      prepareFn();
+      return originalMethod.call(context, ...args);
+    };
+    Object.setPrototypeOf(wrappedMethod, originalMethod);
+    const propertyNames = Object.getOwnPropertyNames(originalMethod);
+    for (let i = 0; i < propertyNames.length; i++) {
+      const prop = propertyNames[i];
+      if (prop !== "length" && prop !== "name" && prop !== "prototype") {
+        const descriptor = Object.getOwnPropertyDescriptor(originalMethod, prop);
+        if (descriptor && descriptor.writable !== false && !descriptor.get) {
+          wrappedMethod[prop] = originalMethod[prop];
+        }
+      }
+    }
+    return wrappedMethod;
+  };
   const generateTimestamps = (timestampTypes) => {
     if (!config.settings?.timestamps) return {};
     const timestamps = {};
@@ -3341,39 +3701,33 @@ function defineEntity(config) {
     createRepository: (table) => {
       const repository = {
         create: (data) => {
-          const primaryKey = config.primaryKey.generateKey(data);
-          const indexes = Object.entries(config.indexes ?? {}).reduce(
-            (acc, [indexName, index]) => {
-              const key = index.generateKey(data);
-              const gsiConfig = table.gsis[indexName];
-              if (!gsiConfig) {
-                throw new Error(`GSI configuration not found for index: ${indexName}`);
-              }
-              if (key.pk) {
-                acc[gsiConfig.partitionKey] = key.pk;
-              }
-              if (key.sk && gsiConfig.sortKey) {
-                acc[gsiConfig.sortKey] = key.sk;
-              }
-              return acc;
-            },
-            {}
-          );
-          const builder = table.create({
-            ...data,
-            [entityTypeAttributeName]: config.name,
-            [table.partitionKey]: primaryKey.pk,
-            ...table.sortKey ? { [table.sortKey]: primaryKey.sk } : {},
-            ...indexes,
-            ...generateTimestamps(["createdAt", "updatedAt"])
-          });
+          const builder = table.create({});
           const prepareValidatedItemAsync = async () => {
-            const validationResult = await config.schema["~standard"].validate(data);
-            if ("issues" in validationResult && validationResult.issues) {
-              throw new Error(`Validation failed: ${validationResult.issues.map((i) => i.message).join(", ")}`);
+            const validationResult = config.schema["~standard"].validate(data);
+            const validatedData = validationResult instanceof Promise ? await validationResult : validationResult;
+            if ("issues" in validatedData && validatedData.issues) {
+              throw new Error(`Validation failed: ${validatedData.issues.map((i) => i.message).join(", ")}`);
             }
+            const primaryKey = config.primaryKey.generateKey(validatedData.value);
+            const indexes = Object.entries(config.indexes ?? {}).reduce(
+              (acc, [indexName, index]) => {
+                const key = index.generateKey(validatedData.value);
+                const gsiConfig = table.gsis[indexName];
+                if (!gsiConfig) {
+                  throw new Error(`GSI configuration not found for index: ${indexName}`);
+                }
+                if (key.pk) {
+                  acc[gsiConfig.partitionKey] = key.pk;
+                }
+                if (key.sk && gsiConfig.sortKey) {
+                  acc[gsiConfig.sortKey] = key.sk;
+                }
+                return acc;
+              },
+              {}
+            );
             const validatedItem = {
-              ...validationResult.value,
+              ...validatedData.value,
               [entityTypeAttributeName]: config.name,
               [table.partitionKey]: primaryKey.pk,
               ...table.sortKey ? { [table.sortKey]: primaryKey.sk } : {},
@@ -3386,11 +3740,31 @@ function defineEntity(config) {
           const prepareValidatedItemSync = () => {
             const validationResult = config.schema["~standard"].validate(data);
             if (validationResult instanceof Promise) {
-              throw new Error("Async validation is not supported in withTransaction. Use execute() instead.");
+              throw new Error(
+                "Async validation is not supported in create method. The schema must support synchronous validation for transaction compatibility."
+              );
             }
             if ("issues" in validationResult && validationResult.issues) {
               throw new Error(`Validation failed: ${validationResult.issues.map((i) => i.message).join(", ")}`);
             }
+            const primaryKey = config.primaryKey.generateKey(validationResult.value);
+            const indexes = Object.entries(config.indexes ?? {}).reduce(
+              (acc, [indexName, index]) => {
+                const key = index.generateKey(validationResult.value);
+                const gsiConfig = table.gsis[indexName];
+                if (!gsiConfig) {
+                  throw new Error(`GSI configuration not found for index: ${indexName}`);
+                }
+                if (key.pk) {
+                  acc[gsiConfig.partitionKey] = key.pk;
+                }
+                if (key.sk && gsiConfig.sortKey) {
+                  acc[gsiConfig.sortKey] = key.sk;
+                }
+                return acc;
+              },
+              {}
+            );
             const validatedItem = {
               ...validationResult.value,
               [entityTypeAttributeName]: config.name,
@@ -3409,45 +3783,50 @@ function defineEntity(config) {
           };
           const originalWithTransaction = builder.withTransaction;
           if (originalWithTransaction) {
-            const wrappedWithTransaction = (transaction) => {
-              prepareValidatedItemSync();
-              return originalWithTransaction.call(builder, transaction);
-            };
-            Object.setPrototypeOf(wrappedWithTransaction, originalWithTransaction);
-            const propertyNames = Object.getOwnPropertyNames(originalWithTransaction);
-            for (let i = 0; i < propertyNames.length; i++) {
-              const prop = propertyNames[i];
-              if (prop !== "length" && prop !== "name" && prop !== "prototype") {
-                try {
-                  wrappedWithTransaction[prop] = originalWithTransaction[prop];
-                } catch (e) {
-                }
-              }
-            }
-            builder.withTransaction = wrappedWithTransaction;
+            builder.withTransaction = wrapMethodWithPreparation(
+              originalWithTransaction,
+              prepareValidatedItemSync,
+              builder
+            );
           }
-          return builder;
+          const originalWithBatch = builder.withBatch;
+          if (originalWithBatch) {
+            builder.withBatch = wrapMethodWithPreparation(originalWithBatch, prepareValidatedItemSync, builder);
+          }
+          return createEntityAwarePutBuilder(builder, config.name);
         },
         upsert: (data) => {
-          const primaryKey = config.primaryKey.generateKey(data);
-          const builder = table.put({
-            [table.partitionKey]: primaryKey.pk,
-            ...table.sortKey ? { [table.sortKey]: primaryKey.sk } : {},
-            ...data,
-            [entityTypeAttributeName]: config.name,
-            ...generateTimestamps(["createdAt", "updatedAt"])
-          });
+          const builder = table.put({});
           const prepareValidatedItemAsync = async () => {
-            const validationResult = await config.schema["~standard"].validate(data);
-            if ("issues" in validationResult && validationResult.issues) {
-              throw new Error(`Validation failed: ${validationResult.issues.map((i) => i.message).join(", ")}`);
+            const validationResult = config.schema["~standard"].validate(data);
+            const validatedData = validationResult instanceof Promise ? await validationResult : validationResult;
+            if ("issues" in validatedData && validatedData.issues) {
+              throw new Error(`Validation failed: ${validatedData.issues.map((i) => i.message).join(", ")}`);
             }
-            const primaryKey2 = config.primaryKey.generateKey(validationResult.value);
+            const primaryKey = config.primaryKey.generateKey(validatedData.value);
+            const indexes = Object.entries(config.indexes ?? {}).reduce(
+              (acc, [indexName, index]) => {
+                const key = index.generateKey(validatedData.value);
+                const gsiConfig = table.gsis[indexName];
+                if (!gsiConfig) {
+                  throw new Error(`GSI configuration not found for index: ${indexName}`);
+                }
+                if (key.pk) {
+                  acc[gsiConfig.partitionKey] = key.pk;
+                }
+                if (key.sk && gsiConfig.sortKey) {
+                  acc[gsiConfig.sortKey] = key.sk;
+                }
+                return acc;
+              },
+              {}
+            );
             const validatedItem = {
-              [table.partitionKey]: primaryKey2.pk,
-              ...table.sortKey ? { [table.sortKey]: primaryKey2.sk } : {},
-              ...validationResult.value,
+              [table.partitionKey]: primaryKey.pk,
+              ...table.sortKey ? { [table.sortKey]: primaryKey.sk } : {},
+              ...validatedData.value,
               [entityTypeAttributeName]: config.name,
+              ...indexes,
               ...generateTimestamps(["createdAt", "updatedAt"])
             };
             Object.assign(builder, { item: validatedItem });
@@ -3461,12 +3840,30 @@ function defineEntity(config) {
             if ("issues" in validationResult && validationResult.issues) {
               throw new Error(`Validation failed: ${validationResult.issues.map((i) => i.message).join(", ")}`);
             }
-            const primaryKey2 = config.primaryKey.generateKey(validationResult.value);
+            const primaryKey = config.primaryKey.generateKey(validationResult.value);
+            const indexes = Object.entries(config.indexes ?? {}).reduce(
+              (acc, [indexName, index]) => {
+                const key = index.generateKey(validationResult.value);
+                const gsiConfig = table.gsis[indexName];
+                if (!gsiConfig) {
+                  throw new Error(`GSI configuration not found for index: ${indexName}`);
+                }
+                if (key.pk) {
+                  acc[gsiConfig.partitionKey] = key.pk;
+                }
+                if (key.sk && gsiConfig.sortKey) {
+                  acc[gsiConfig.sortKey] = key.sk;
+                }
+                return acc;
+              },
+              {}
+            );
             const validatedItem = {
-              [table.partitionKey]: primaryKey2.pk,
-              ...table.sortKey ? { [table.sortKey]: primaryKey2.sk } : {},
+              [table.partitionKey]: primaryKey.pk,
+              ...table.sortKey ? { [table.sortKey]: primaryKey.sk } : {},
               ...validationResult.value,
               [entityTypeAttributeName]: config.name,
+              ...indexes,
               ...generateTimestamps(["createdAt", "updatedAt"])
             };
             Object.assign(builder, { item: validatedItem });
@@ -3483,26 +3880,19 @@ function defineEntity(config) {
           };
           const originalWithTransaction = builder.withTransaction;
           if (originalWithTransaction) {
-            const wrappedWithTransaction = (transaction) => {
-              prepareValidatedItemSync();
-              return originalWithTransaction.call(builder, transaction);
-            };
-            Object.setPrototypeOf(wrappedWithTransaction, originalWithTransaction);
-            const propertyNames = Object.getOwnPropertyNames(originalWithTransaction);
-            for (let i = 0; i < propertyNames.length; i++) {
-              const prop = propertyNames[i];
-              if (prop !== "length" && prop !== "name" && prop !== "prototype") {
-                try {
-                  wrappedWithTransaction[prop] = originalWithTransaction[prop];
-                } catch (e) {
-                }
-              }
-            }
-            builder.withTransaction = wrappedWithTransaction;
+            builder.withTransaction = wrapMethodWithPreparation(
+              originalWithTransaction,
+              prepareValidatedItemSync,
+              builder
+            );
           }
-          return builder;
+          const originalWithBatch = builder.withBatch;
+          if (originalWithBatch) {
+            builder.withBatch = wrapMethodWithPreparation(originalWithBatch, prepareValidatedItemSync, builder);
+          }
+          return createEntityAwarePutBuilder(builder, config.name);
         },
-        get: (key) => table.get(config.primaryKey.generateKey(key)),
+        get: (key) => createEntityAwareGetBuilder(table.get(config.primaryKey.generateKey(key)), config.name),
         update: (key, data) => {
           const primaryKeyObj = config.primaryKey.generateKey(key);
           const builder = table.update(primaryKeyObj);
@@ -3514,13 +3904,13 @@ function defineEntity(config) {
         delete: (key) => {
           const builder = table.delete(config.primaryKey.generateKey(key));
           builder.condition(eq(entityTypeAttributeName, config.name));
-          return builder;
+          return createEntityAwareDeleteBuilder(builder, config.name);
         },
         query: Object.entries(config.queries || {}).reduce((acc, [key, inputCallback]) => {
           acc[key] = (input) => {
             const queryEntity = {
               scan: repository.scan,
-              get: (key2) => table.get(key2),
+              get: (key2) => createEntityAwareGetBuilder(table.get(key2), config.name),
               query: (keyCondition) => {
                 return table.query(keyCondition);
               }
@@ -3625,6 +4015,6 @@ function sortKey(strings, ...keys) {
   };
 }
 
-export { DeleteBuilder, PutBuilder, QueryBuilder, Table, TransactionBuilder, UpdateBuilder, and, attributeExists, attributeNotExists, beginsWith, between, contains, createIndex, createQueries, defineEntity, eq, gt, gte, inArray, lt, lte, ne, not, or, partitionKey, sortKey };
+export { BatchBuilder, BatchError, DeleteBuilder, PutBuilder, QueryBuilder, Table, TransactionBuilder, UpdateBuilder, and, attributeExists, attributeNotExists, beginsWith, between, contains, createIndex, createQueries, defineEntity, eq, gt, gte, inArray, lt, lte, ne, not, or, partitionKey, sortKey };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map