dyno-table 2.5.2 → 2.6.1

package/dist/builders.js

@@ -1,3 +1,3648 @@
-export { BatchBuilder, ConditionCheckBuilder, DeleteBuilder, FilterBuilder, GetBuilder, Paginator, PutBuilder, QueryBuilder, ResultIterator, ScanBuilder, TransactionBuilder, UpdateBuilder } from './chunk-NYJGW3XH.js';
-import './chunk-FF7FYGDH.js';
-import './chunk-2WIBY7PZ.js';
+// src/errors.ts
+var DynoTableError = class extends Error {
+  /**
+   * Machine-readable error code for programmatic error handling
+   * @example "KEY_GENERATION_FAILED", "VALIDATION_ERROR", etc.
+   */
+  code;
+  /**
+   * Additional context about the error
+   * Contains operation-specific details like entity names, table names,
+   * expressions, conditions, and other relevant debugging information
+   */
+  context;
+  /**
+   * The original error that caused this error (if wrapping another error)
+   * Useful for preserving AWS SDK errors or other underlying errors
+   */
+  cause;
+  constructor(message, code, context = {}, cause) {
+    super(message);
+    this.name = "DynoTableError";
+    this.code = code;
+    this.context = context;
+    this.cause = cause;
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, this.constructor);
+    }
+  }
+};
+var ValidationError = class extends DynoTableError {
+  constructor(message, code, context = {}, cause) {
+    super(message, code, context, cause);
+    this.name = "ValidationError";
+  }
+};
+var TransactionError = class extends DynoTableError {
+  constructor(message, code, context = {}, cause) {
+    super(message, code, context, cause);
+    this.name = "TransactionError";
+  }
+};
+var BatchError = class extends DynoTableError {
+  /**
+   * The type of batch operation that failed
+   */
+  operation;
+  /**
+   * The items that were not processed during the batch operation
+   */
+  unprocessedItems;
+  constructor(message, code, operation, unprocessedItems = [], context = {}, cause) {
+    super(message, code, context, cause);
+    this.name = "BatchError";
+    this.operation = operation;
+    this.unprocessedItems = unprocessedItems;
+  }
+};
+var ExpressionError = class extends DynoTableError {
+  constructor(message, code, context = {}, cause) {
+    super(message, code, context, cause);
+    this.name = "ExpressionError";
+  }
+};
+var ConfigurationError = class extends DynoTableError {
+  constructor(message, code, context = {}, cause) {
+    super(message, code, context, cause);
+    this.name = "ConfigurationError";
+  }
+};
+var ErrorCodes = {
+  QUERY_INPUT_VALIDATION_FAILED: "QUERY_INPUT_VALIDATION_FAILED",
+  SCHEMA_VALIDATION_FAILED: "SCHEMA_VALIDATION_FAILED",
+  UNDEFINED_VALUE: "UNDEFINED_VALUE",
+  // Expression Errors
+  EXPRESSION_MISSING_ATTRIBUTE: "EXPRESSION_MISSING_ATTRIBUTE",
+  EXPRESSION_MISSING_VALUE: "EXPRESSION_MISSING_VALUE",
+  EXPRESSION_INVALID_CONDITION: "EXPRESSION_INVALID_CONDITION",
+  EXPRESSION_EMPTY_ARRAY: "EXPRESSION_EMPTY_ARRAY",
+  EXPRESSION_UNKNOWN_TYPE: "EXPRESSION_UNKNOWN_TYPE",
+  BATCH_GET_FAILED: "BATCH_GET_FAILED",
+  BATCH_WRITE_FAILED: "BATCH_WRITE_FAILED",
+  NO_UPDATE_ACTIONS: "NO_UPDATE_ACTIONS",
+  // Transaction Errors
+  TRANSACTION_FAILED: "TRANSACTION_FAILED",
+  TRANSACTION_DUPLICATE_ITEM: "TRANSACTION_DUPLICATE_ITEM",
+  TRANSACTION_EMPTY: "TRANSACTION_EMPTY",
+  TRANSACTION_UNSUPPORTED_TYPE: "TRANSACTION_UNSUPPORTED_TYPE",
+  // Batch Errors
+  BATCH_EMPTY: "BATCH_EMPTY",
+  BATCH_UNSUPPORTED_TYPE: "BATCH_UNSUPPORTED_TYPE",
+  // Configuration Errors
+  GSI_NOT_FOUND: "GSI_NOT_FOUND",
+  SORT_KEY_REQUIRED: "SORT_KEY_REQUIRED",
+  SORT_KEY_NOT_DEFINED: "SORT_KEY_NOT_DEFINED",
+  PRIMARY_KEY_MISSING: "PRIMARY_KEY_MISSING",
+  INVALID_CHUNK_SIZE: "INVALID_CHUNK_SIZE",
+  CONDITION_REQUIRED: "CONDITION_REQUIRED",
+  CONDITION_GENERATION_FAILED: "CONDITION_GENERATION_FAILED",
+  PK_EXTRACTION_FAILED: "PK_EXTRACTION_FAILED"};
+
+// src/utils/error-factory.ts
+var ExpressionErrors = {
+  missingAttribute: (conditionType, condition) => new ExpressionError(
+    `Attribute is required for ${conditionType} condition`,
+    ErrorCodes.EXPRESSION_MISSING_ATTRIBUTE,
+    {
+      conditionType,
+      condition,
+      suggestion: "Ensure the condition includes an attribute name"
+    }
+  ),
+  missingValue: (conditionType, condition) => new ExpressionError(`Value is required for ${conditionType} condition`, ErrorCodes.EXPRESSION_MISSING_VALUE, {
+    conditionType,
+    condition,
+    suggestion: "Provide a value for the condition"
+  }),
+  invalidCondition: (conditionType, condition, suggestion) => new ExpressionError(`Invalid condition for ${conditionType}`, ErrorCodes.EXPRESSION_INVALID_CONDITION, {
+    conditionType,
+    condition,
+    suggestion: suggestion || "Check that the condition is properly formed"
+  }),
+  emptyArray: (conditionType, providedValue) => new ExpressionError(
+    `${conditionType} condition requires a non-empty array of values`,
+    ErrorCodes.EXPRESSION_EMPTY_ARRAY,
+    {
+      conditionType,
+      providedValue,
+      suggestion: "Provide at least one value in the array"
+    }
+  ),
+  unknownType: (conditionType, condition) => new ExpressionError(`Unknown condition type: ${conditionType}`, ErrorCodes.EXPRESSION_UNKNOWN_TYPE, {
+    conditionType,
+    condition,
+    suggestion: "Use a supported condition type from the query builder"
+  })
+};
+var ValidationErrors = {
+  indexSchemaValidationFailed: (validationIssues, keyType) => {
+    const keyLabel = keyType === "partition" ? "partition key" : keyType === "sort" ? "sort key" : "partition/sort key";
+    return new ValidationError(
+      `Index validation failed while generating ${keyLabel}: missing required attribute(s) or invalid values.`,
+      ErrorCodes.SCHEMA_VALIDATION_FAILED,
+      {
+        keyType,
+        validationIssues,
+        suggestion: `Provide the required attributes to construct the index ${keyLabel}`
+      }
+    );
+  },
+  noUpdateActions: (tableName, key) => new ValidationError("No update actions specified", ErrorCodes.NO_UPDATE_ACTIONS, {
+    tableName,
+    key,
+    suggestion: "Use set(), remove(), add(), or delete() to specify update actions"
+  }),
+  conditionRequired: (tableName, key) => new ValidationError("Condition is required for condition check operations", ErrorCodes.CONDITION_REQUIRED, {
+    tableName,
+    key,
+    suggestion: "Use the condition() method to specify a condition"
+  }),
+  queryInputValidationFailed: (entityName, queryName, validationIssues, providedInput) => new ValidationError(
+    `Query input validation failed for "${queryName}" on entity "${entityName}"`,
+    ErrorCodes.QUERY_INPUT_VALIDATION_FAILED,
+    {
+      entityName,
+      queryName,
+      validationIssues,
+      providedInput,
+      suggestion: "Ensure the query input matches the expected schema"
+    }
+  ),
+  undefinedValue: (path, tableName, key) => new ValidationError(`Cannot set undefined value for attribute "${path}"`, ErrorCodes.UNDEFINED_VALUE, {
+    path,
+    tableName,
+    key,
+    suggestion: "DynamoDB does not support undefined values. Use remove() to delete an attribute, or provide a valid value (null, string, number, etc.)"
+  })
+};
+var ConfigurationErrors = {
+  invalidChunkSize: (size) => new ConfigurationError("Chunk size must be greater than 0", ErrorCodes.INVALID_CHUNK_SIZE, {
+    size,
+    suggestion: "Provide a chunk size greater than 0"
+  }),
+  sortKeyRequired: (tableName, partitionKey, sortKey) => new ConfigurationError("Sort key is required for this operation", ErrorCodes.SORT_KEY_REQUIRED, {
+    tableName,
+    partitionKey,
+    sortKey,
+    suggestion: "Provide a sort key value or use a table with only a partition key"
+  }),
+  sortKeyNotDefined: (tableName, partitionKey, indexName) => new ConfigurationError("Sort key is not defined for this table/index", ErrorCodes.SORT_KEY_NOT_DEFINED, {
+    tableName,
+    partitionKey,
+    indexName,
+    suggestion: "This operation requires a table/index with a sort key defined"
+  }),
+  gsiNotFound: (indexName, tableName, availableIndexes) => new ConfigurationError(`GSI "${indexName}" not found in table configuration`, ErrorCodes.GSI_NOT_FOUND, {
+    indexName,
+    tableName,
+    availableIndexes,
+    suggestion: `Use one of the available indexes: ${availableIndexes.join(", ")}`
+  }),
+  primaryKeyMissing: (tableName, partitionKeyName, providedItem) => new ConfigurationError(`Primary key value for '${partitionKeyName}' is missing`, ErrorCodes.PRIMARY_KEY_MISSING, {
+    tableName,
+    partitionKeyName,
+    providedItem,
+    suggestion: `Ensure the item includes a value for '${partitionKeyName}'`
+  }),
+  pkExtractionFailed: (tableName, indexName, item, cause) => new ConfigurationError(
+    `Failed to extract partition key from item for index "${indexName}"`,
+    ErrorCodes.PK_EXTRACTION_FAILED,
+    {
+      tableName,
+      indexName,
+      item,
+      suggestion: "Ensure the item has the required partition key attribute"
+    },
+    cause
+  ),
+  conditionGenerationFailed: (condition, suggestion) => new ExpressionError("Failed to generate condition expression", ErrorCodes.CONDITION_GENERATION_FAILED, {
+    condition,
+    suggestion: suggestion || "Check that the condition is properly formed"
+  })
+};
+var TransactionErrors = {
+  transactionFailed: (itemCount, context, cause) => new TransactionError(
+    `Transaction failed with ${itemCount} item(s)`,
+    ErrorCodes.TRANSACTION_FAILED,
+    {
+      itemCount,
+      ...context
+    },
+    cause
+  ),
+  duplicateItem: (tableName, partitionKey, sortKey) => new TransactionError("Duplicate item detected in transaction", ErrorCodes.TRANSACTION_DUPLICATE_ITEM, {
+    tableName,
+    partitionKey,
+    sortKey,
+    suggestion: "Each item in a transaction must be unique. Check for duplicate keys in your transaction items."
+  }),
+  transactionEmpty: () => new TransactionError("No transaction items specified", ErrorCodes.TRANSACTION_EMPTY, {
+    suggestion: "Add at least one operation using put(), delete(), update(), or conditionCheck()"
+  }),
+  unsupportedType: (item) => new TransactionError("Unsupported transaction item type", ErrorCodes.TRANSACTION_UNSUPPORTED_TYPE, {
+    item,
+    suggestion: "Transaction items must be created using put(), delete(), update(), or conditionCheck()"
+  })
+};
+var BatchErrors = {
+  batchEmpty: (operation) => new BatchError(`No items specified for batch ${operation} operation`, ErrorCodes.BATCH_EMPTY, operation, [], {
+    suggestion: operation === "write" ? "Use put() or delete() to add items to the batch" : "Use get() to add keys to the batch"
+  }),
+  unsupportedType: (operation, item) => new BatchError(`Unsupported batch ${operation} item type`, ErrorCodes.BATCH_UNSUPPORTED_TYPE, operation, [], {
+    item,
+    suggestion: operation === "write" ? "Batch items must be put or delete operations" : "Batch items must be get operations"
+  }),
+  batchWriteFailed: (unprocessedItems, context, cause) => new BatchError(
+    `Batch write failed with ${unprocessedItems.length} unprocessed item(s)`,
+    ErrorCodes.BATCH_WRITE_FAILED,
+    "write",
+    unprocessedItems,
+    context,
+    cause
+  ),
+  batchGetFailed: (unprocessedItems, context, cause) => new BatchError(
+    `Batch get failed with ${unprocessedItems.length} unprocessed item(s)`,
+    ErrorCodes.BATCH_GET_FAILED,
+    "read",
+    unprocessedItems,
+    context,
+    cause
+  )
+};
+
+// src/builders/batch-builder.ts
+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 BatchErrors.batchEmpty("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 BatchErrors.unsupportedType("write", item);
+      });
+      return await this.batchWriteExecutor(operations);
+    } catch (error) {
+      if (error instanceof BatchError) throw error;
+      throw BatchErrors.batchWriteFailed(
+        [],
+        { operationCount: this.writeItems.length },
+        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 BatchErrors.unsupportedType("read", item);
+      });
+      return await this.batchGetExecutor(keys);
+    } catch (error) {
+      if (error instanceof BatchError) throw error;
+      throw BatchErrors.batchGetFailed(
+        [],
+        { operationCount: this.getItems.length },
+        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",
+              ErrorCodes.BATCH_WRITE_FAILED,
+              "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",
+              ErrorCodes.BATCH_GET_FAILED,
+              "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/conditions.ts
+var createComparisonCondition = (type) => (attr, value) => ({
+  type,
+  attr,
+  value
+});
+var eq = createComparisonCondition("eq");
+var ne = createComparisonCondition("ne");
+var lt = createComparisonCondition("lt");
+var lte = createComparisonCondition("lte");
+var gt = createComparisonCondition("gt");
+var gte = createComparisonCondition("gte");
+var between = (attr, lower, upper) => ({
+  type: "between",
+  attr,
+  value: [lower, upper]
+});
+var inArray = (attr, values) => ({
+  type: "in",
+  attr,
+  value: values
+});
+var beginsWith = createComparisonCondition("beginsWith");
+var contains = createComparisonCondition("contains");
+var attributeExists = (attr) => ({
+  type: "attributeExists",
+  attr
+});
+var attributeNotExists = (attr) => ({
+  type: "attributeNotExists",
+  attr
+});
+var and = (...conditions) => ({
+  type: "and",
+  conditions
+});
+var or = (...conditions) => ({
+  type: "or",
+  conditions
+});
+var not = (condition) => ({
+  type: "not",
+  condition
+});
+
+// src/expression.ts
+var generateAttributeName = (params, attr) => {
+  if (attr.includes(".")) {
+    const pathSegments = attr.split(".");
+    const segmentNames = [];
+    for (const segment of pathSegments) {
+      let segmentName;
+      for (const [existingName, existingAttr] of Object.entries(params.expressionAttributeNames)) {
+        if (existingAttr === segment) {
+          segmentName = existingName;
+          break;
+        }
+      }
+      if (!segmentName) {
+        segmentName = `#${Object.keys(params.expressionAttributeNames).length}`;
+        params.expressionAttributeNames[segmentName] = segment;
+      }
+      segmentNames.push(segmentName);
+    }
+    return segmentNames.join(".");
+  }
+  for (const [existingName, existingAttr] of Object.entries(params.expressionAttributeNames)) {
+    if (existingAttr === attr) {
+      return existingName;
+    }
+  }
+  const attrName = `#${Object.keys(params.expressionAttributeNames).length}`;
+  params.expressionAttributeNames[attrName] = attr;
+  return attrName;
+};
+var generateValueName = (params, value) => {
+  const valueName = `:${params.valueCounter.count++}`;
+  params.expressionAttributeValues[valueName] = value;
+  return valueName;
+};
+var validateCondition = (condition, requiresAttr = true, requiresValue = true) => {
+  if (requiresAttr && !condition.attr) {
+    throw ExpressionErrors.missingAttribute(condition.type, condition);
+  }
+  if (requiresValue && condition.value === void 0) {
+    throw ExpressionErrors.missingValue(condition.type, condition);
+  }
+};
+var buildComparisonExpression = (condition, operator, params) => {
+  validateCondition(condition);
+  if (!condition.attr) {
+    throw ExpressionErrors.missingAttribute(condition.type, condition);
+  }
+  const attrName = generateAttributeName(params, condition.attr);
+  const valueName = generateValueName(params, condition.value);
+  return `${attrName} ${operator} ${valueName}`;
+};
+var buildBetweenExpression = (condition, params) => {
+  validateCondition(condition);
+  if (!condition.attr) {
+    throw ExpressionErrors.missingAttribute(condition.type, condition);
+  }
+  if (!Array.isArray(condition.value) || condition.value.length !== 2) {
+    throw ExpressionErrors.invalidCondition(
+      condition.type,
+      condition,
+      "Provide an array with exactly two values: [lowerBound, upperBound]"
+    );
+  }
+  const attrName = generateAttributeName(params, condition.attr);
+  const lowerName = generateValueName(params, condition.value[0]);
+  const upperName = generateValueName(params, condition.value[1]);
+  return `${attrName} BETWEEN ${lowerName} AND ${upperName}`;
+};
+var buildInExpression = (condition, params) => {
+  validateCondition(condition);
+  if (!condition.attr) {
+    throw ExpressionErrors.missingAttribute(condition.type, condition);
+  }
+  if (!Array.isArray(condition.value) || condition.value.length === 0) {
+    throw ExpressionErrors.emptyArray(condition.type, condition.value);
+  }
+  if (condition.value.length > 100) {
+    throw ExpressionErrors.invalidCondition(
+      condition.type,
+      condition,
+      "Split your query into multiple operations or use a different condition type"
+    );
+  }
+  const attrName = generateAttributeName(params, condition.attr);
+  const valueNames = condition.value.map((value) => generateValueName(params, value));
+  return `${attrName} IN (${valueNames.join(", ")})`;
+};
+var buildFunctionExpression = (functionName, condition, params) => {
+  validateCondition(condition);
+  if (!condition.attr) {
+    throw ExpressionErrors.missingAttribute(condition.type, condition);
+  }
+  const attrName = generateAttributeName(params, condition.attr);
+  const valueName = generateValueName(params, condition.value);
+  return `${functionName}(${attrName}, ${valueName})`;
+};
+var buildAttributeFunction = (functionName, condition, params) => {
+  validateCondition(condition, true, false);
+  if (!condition.attr) {
+    throw ExpressionErrors.missingAttribute(condition.type, condition);
+  }
+  const attrName = generateAttributeName(params, condition.attr);
+  return `${functionName}(${attrName})`;
+};
+var buildLogicalExpression = (operator, conditions, params) => {
+  if (!conditions || conditions.length === 0) {
+    throw ExpressionErrors.emptyArray(operator, conditions);
+  }
+  const expressions = conditions.map((c) => buildExpression(c, params));
+  return `(${expressions.join(` ${operator} `)})`;
+};
+var buildExpression = (condition, params) => {
+  if (!condition) return "";
+  const expressionBuilders = {
+    eq: () => buildComparisonExpression(condition, "=", params),
+    ne: () => buildComparisonExpression(condition, "<>", params),
+    lt: () => buildComparisonExpression(condition, "<", params),
+    lte: () => buildComparisonExpression(condition, "<=", params),
+    gt: () => buildComparisonExpression(condition, ">", params),
+    gte: () => buildComparisonExpression(condition, ">=", params),
+    between: () => buildBetweenExpression(condition, params),
+    in: () => buildInExpression(condition, params),
+    beginsWith: () => buildFunctionExpression("begins_with", condition, params),
+    contains: () => buildFunctionExpression("contains", condition, params),
+    attributeExists: () => buildAttributeFunction("attribute_exists", condition, params),
+    attributeNotExists: () => buildAttributeFunction("attribute_not_exists", condition, params),
+    and: () => {
+      if (!condition.conditions) {
+        throw ExpressionErrors.invalidCondition(
+          condition.type,
+          condition,
+          "Provide an array of conditions to combine with AND"
+        );
+      }
+      return buildLogicalExpression("AND", condition.conditions, params);
+    },
+    or: () => {
+      if (!condition.conditions) {
+        throw ExpressionErrors.invalidCondition(
+          condition.type,
+          condition,
+          "Provide an array of conditions to combine with OR"
+        );
+      }
+      return buildLogicalExpression("OR", condition.conditions, params);
+    },
+    not: () => {
+      if (!condition.condition) {
+        throw ExpressionErrors.invalidCondition(condition.type, condition, "Provide a condition to negate with NOT");
+      }
+      return `NOT (${buildExpression(condition.condition, params)})`;
+    }
+  };
+  const builder = expressionBuilders[condition.type];
+  if (!builder) {
+    throw ExpressionErrors.unknownType(condition.type, condition);
+  }
+  return builder();
+};
+var prepareExpressionParams = (condition) => {
+  if (!condition) return {};
+  const params = {
+    expressionAttributeNames: {},
+    expressionAttributeValues: {},
+    valueCounter: { count: 0 }
+  };
+  const expression = buildExpression(condition, params);
+  return {
+    expression,
+    names: Object.keys(params.expressionAttributeNames).length > 0 ? params.expressionAttributeNames : void 0,
+    values: Object.keys(params.expressionAttributeValues).length > 0 ? params.expressionAttributeValues : void 0
+  };
+};
+
+// src/utils/debug-expression.ts
+function debugCommand(command) {
+  const result = {};
+  function replaceAliases(expressionString) {
+    if (!expressionString) {
+      return expressionString;
+    }
+    let replacedString = expressionString;
+    for (const alias in command.expressionAttributeNames) {
+      const attributeName = command.expressionAttributeNames[alias];
+      const regex = new RegExp(alias, "g");
+      replacedString = replacedString.replace(regex, attributeName);
+    }
+    for (const alias in command.expressionAttributeValues) {
+      let attributeValue = command.expressionAttributeValues[alias];
+      if (attributeValue instanceof Set) {
+        const array = Array.from(attributeValue);
+        attributeValue = `Set(${array.length}){${array.map((v) => JSON.stringify(v)).join(", ")}}`;
+      } else {
+        attributeValue = JSON.stringify(attributeValue);
+      }
+      const regex = new RegExp(alias, "g");
+      replacedString = replacedString.replace(regex, attributeValue);
+    }
+    return replacedString;
+  }
+  if (command.updateExpression) {
+    result.updateExpression = replaceAliases(command.updateExpression);
+  }
+  if (command.conditionExpression) {
+    result.conditionExpression = replaceAliases(command.conditionExpression);
+  }
+  if (command.filterExpression) {
+    result.filterExpression = replaceAliases(command.filterExpression);
+  }
+  if (command.keyConditionExpression) {
+    result.keyConditionExpression = replaceAliases(command.keyConditionExpression);
+  }
+  if (command.projectionExpression) {
+    result.projectionExpression = replaceAliases(command.projectionExpression);
+  }
+  return {
+    raw: command,
+    readable: result
+  };
+}
+
+// src/builders/condition-check-builder.ts
+var ConditionCheckBuilder = class {
+  key;
+  tableName;
+  conditionExpression;
+  constructor(tableName, key) {
+    this.tableName = tableName;
+    this.key = key;
+  }
+  /**
+   * Adds a condition that must be satisfied for the check to succeed.
+   *
+   * @example
+   * ```typescript
+   * // Check dinosaur health and behavior
+   * builder.condition(op =>
+   *   op.and([
+   *     op.gt('stats.health', 50),
+   *     op.not(op.eq('status', 'SEDATED')),
+   *     op.lt('aggressionLevel', 8)
+   *   ])
+   * );
+   *
+   * // Verify habitat conditions
+   * builder.condition(op =>
+   *   op.and([
+   *     op.eq('powerStatus', 'ONLINE'),
+   *     op.between('temperature', 20, 30),
+   *     op.attributeExists('lastMaintenance')
+   *   ])
+   * );
+   *
+   * // Check breeding conditions
+   * builder.condition(op =>
+   *   op.and([
+   *     op.eq('species', 'VELOCIRAPTOR'),
+   *     op.gte('age', 3),
+   *     op.eq('geneticPurity', 100)
+   *   ])
+   * );
+   * ```
+   *
+   * @param condition - Either a Condition DynamoItem or a callback function that builds the condition
+   * @returns The builder instance for method chaining
+   */
+  condition(condition) {
+    if (typeof condition === "function") {
+      const conditionOperator = {
+        eq,
+        ne,
+        lt,
+        lte,
+        gt,
+        gte,
+        between,
+        inArray,
+        beginsWith,
+        contains,
+        attributeExists,
+        attributeNotExists,
+        and,
+        or,
+        not
+      };
+      this.conditionExpression = condition(conditionOperator);
+    } else {
+      this.conditionExpression = condition;
+    }
+    return this;
+  }
+  /**
+   * Generates the DynamoDB command parameters for direct execution.
+   * Use this method when you want to:
+   * - Execute the condition check as a standalone operation
+   * - Get the raw DynamoDB command for custom execution
+   * - Inspect the generated command parameters
+   *
+   * @example
+   * ```ts
+   * const command = new ConditionCheckBuilder('myTable', { id: '123' })
+   *   .condition(op => op.attributeExists('status'))
+   *   .toDynamoCommand();
+   * // Use command with DynamoDB client
+   * ```
+   *
+   * @throws {Error} If no condition has been set
+   * @returns The DynamoDB command parameters
+   */
+  toDynamoCommand() {
+    if (!this.conditionExpression) {
+      throw ValidationErrors.conditionRequired(this.tableName, this.key);
+    }
+    const { expression, names, values } = prepareExpressionParams(this.conditionExpression);
+    if (!expression) {
+      throw ConfigurationErrors.conditionGenerationFailed(this.conditionExpression);
+    }
+    return {
+      tableName: this.tableName,
+      key: this.key,
+      conditionExpression: expression,
+      expressionAttributeNames: names,
+      expressionAttributeValues: values
+    };
+  }
+  /**
+   * Adds this condition check operation to a transaction.
+   *
+   * @example
+   * ```ts
+   * const transaction = new TransactionBuilder();
+   * new ConditionCheckBuilder('habitats', { id: 'PADDOCK-B' })
+   *   .condition(op => op.and([
+   *     op.eq('securityStatus', 'ACTIVE'),
+   *     op.lt('currentOccupants', 3),
+   *     op.eq('habitatType', 'CARNIVORE')
+   *   ]))
+   *   .withTransaction(transaction);
+   * // Add dinosaur transfer operations
+   * ```
+   *
+   * @param transaction - The transaction builder to add this operation to
+   * @throws {Error} If no condition has been set
+   * @returns The builder instance for method chaining
+   */
+  withTransaction(transaction) {
+    if (!this.conditionExpression) {
+      throw ValidationErrors.conditionRequired(this.tableName, this.key);
+    }
+    const command = this.toDynamoCommand();
+    transaction.conditionCheckWithCommand(command);
+    return this;
+  }
+  /**
+   * Gets a human-readable representation of the condition check command
+   * with all expression placeholders replaced by their actual values.
+   *
+   * @example
+   * ```ts
+   * const debugInfo = new ConditionCheckBuilder('dinosaurs', { id: 'TREX-001' })
+   *   .condition(op => op.and([
+   *     op.between('stats.health', 50, 100),
+   *     op.not(op.eq('status', 'SEDATED')),
+   *     op.attributeExists('lastFeedingTime')
+   *     op.eq('version', 1)
+   *   ]))
+   *   .debug();
+   * console.log(debugInfo);
+   * ```
+   *
+   * @returns A readable representation of the condition check command with resolved expressions
+   */
+  debug() {
+    const command = this.toDynamoCommand();
+    return debugCommand(command);
+  }
+};
+
+// src/builders/delete-builder.ts
+var DeleteBuilder = class {
+  options = {
+    returnValues: "ALL_OLD"
+  };
+  executor;
+  tableName;
+  key;
+  constructor(executor, tableName, key) {
+    this.executor = executor;
+    this.tableName = tableName;
+    this.key = key;
+  }
+  /**
+   * Adds a condition that must be satisfied for the delete operation to succeed.
+   *
+   * @example
+   * ```typescript
+   * // Ensure dinosaur can be safely removed
+   * builder.condition(op =>
+   *   op.and([
+   *     op.eq('status', 'SEDATED'),
+   *     op.eq('location', 'MEDICAL_BAY'),
+   *     op.attributeExists('lastCheckup')
+   *   ])
+   * );
+   *
+   * // Verify habitat is empty
+   * builder.condition(op =>
+   *   op.and([
+   *     op.eq('occupants', 0),
+   *     op.eq('maintenanceStatus', 'COMPLETE'),
+   *     op.not(op.attributeExists('activeAlerts'))
+   *   ])
+   * );
+   * ```
+   *
+   * @param condition - Either a Condition object or a callback function that builds the condition
+   * @returns The builder instance for method chaining
+   */
+  condition(condition) {
+    if (typeof condition === "function") {
+      const conditionOperator = {
+        eq,
+        ne,
+        lt,
+        lte,
+        gt,
+        gte,
+        between,
+        inArray,
+        beginsWith,
+        contains,
+        attributeExists,
+        attributeNotExists,
+        and,
+        or,
+        not
+      };
+      this.options.condition = condition(conditionOperator);
+    } else {
+      this.options.condition = condition;
+    }
+    return this;
+  }
+  /**
+   * Sets whether to return the item's attribute values before deletion.
+   *
+   * @example
+   * ```ts
+   * // Archive dinosaur data before removal
+   * const result = await builder
+   *   .returnValues('ALL_OLD')
+   *   .execute();
+   *
+   * if (result.item) {
+   *   console.log('Removed dinosaur data:', {
+   *     species: result.item.species,
+   *     age: result.item.age,
+   *     lastLocation: result.item.location
+   *   });
+   * }
+   * ```
+   *
+   * @param returnValues - Use 'ALL_OLD' to return all attributes of the deleted item
+   * @returns The builder instance for method chaining
+   */
+  returnValues(returnValues) {
+    this.options.returnValues = returnValues;
+    return this;
+  }
+  /**
+   * Generate the DynamoDB command parameters
+   */
+  toDynamoCommand() {
+    const { expression, names, values } = prepareExpressionParams(this.options.condition);
+    return {
+      tableName: this.tableName,
+      key: this.key,
+      conditionExpression: expression,
+      expressionAttributeNames: names,
+      expressionAttributeValues: values,
+      returnValues: this.options.returnValues
+    };
+  }
+  /**
+   * Adds this delete operation to a transaction.
+   *
+   * @example
+   * ```ts
+   * const transaction = new TransactionBuilder();
+   *
+   * // Remove dinosaur from old habitat
+   * new DeleteBuilder(executor, 'dinosaurs', { id: 'RAPTOR-001' })
+   *   .condition(op => op.eq('status', 'SEDATED'))
+   *   .withTransaction(transaction);
+   *
+   * // Update old habitat occupancy
+   * new UpdateBuilder(executor, 'habitats', { id: 'PADDOCK-A' })
+   *   .add('occupants', -1)
+   *   .withTransaction(transaction);
+   *
+   * // Execute transfer atomically
+   * await transaction.execute();
+   * ```
+   *
+   * @param transaction - The transaction builder to add this operation to
+   */
+  withTransaction(transaction) {
+    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.
+   *
+   * @example
+   * ```ts
+   * // Delete with condition and retrieve old values
+   * const result = await new DeleteBuilder(executor, 'myTable', { id: '123' })
+   *   .condition(op => op.eq('status', 'INACTIVE'))
+   *   .returnValues('ALL_OLD')
+   *   .execute();
+   *
+   * if (result.item) {
+   *   console.log('Deleted item:', result.item);
+   * }
+   * ```
+   *
+   * @returns A promise that resolves to an object containing the deleted item's attributes (if returnValues is 'ALL_OLD')
+   */
+  async execute() {
+    const params = this.toDynamoCommand();
+    return this.executor(params);
+  }
+  /**
+   * Gets a human-readable representation of the delete command
+   * with all expression placeholders replaced by their actual values.
+   *
+   * @example
+   * ```ts
+   * const debugInfo = new DeleteBuilder(executor, 'dinosaurs', { id: 'TREX-001' })
+   *   .condition(op => op.and([
+   *     op.eq('status', 'SEDATED'),
+   *     op.eq('location', 'MEDICAL_BAY'),
+   *     op.gt('sedationLevel', 8)
+   *     op.eq('version', 1),
+   *     op.attributeExists('status')
+   *   ]))
+   *   .debug();
+   *
+   * console.log('Delete command:', debugInfo);
+   * ```
+   *
+   * @returns A readable representation of the delete command with resolved expressions
+   */
+  debug() {
+    const command = this.toDynamoCommand();
+    return debugCommand(command);
+  }
+};
+
+// src/builders/paginator.ts
+var Paginator = class {
+  queryBuilder;
+  pageSize;
+  currentPage = 0;
+  lastEvaluatedKey;
+  hasMorePages = true;
+  totalItemsRetrieved = 0;
+  overallLimit;
+  constructor(queryBuilder, pageSize) {
+    this.queryBuilder = queryBuilder;
+    this.pageSize = pageSize;
+    this.overallLimit = queryBuilder.getLimit();
+  }
+  /**
+   * Gets the current page number (1-indexed).
+   *
+   * @example
+   * ```ts
+   * const paginator = new QueryBuilder(executor, eq('species', 'Tyrannosaurus'))
+   *   .paginate(5);
+   *
+   * await paginator.getNextPage();
+   * console.log(`Reviewing T-Rex group ${paginator.getCurrentPage()}`);
+   * ```
+   *
+   * @returns The current page number, starting from 1
+   */
+  getCurrentPage() {
+    return this.currentPage;
+  }
+  /**
+   * Checks if there are more pages of dinosaurs or habitats to process.
+   *
+   * This method takes into account both:
+   * - DynamoDB's lastEvaluatedKey mechanism
+   * - Any overall limit set on the query
+   *
+   * @example
+   * ```ts
+   * // Process all security incidents
+   * const paginator = new QueryBuilder(executor, eq('type', 'SECURITY_BREACH'))
+   *   .sortDescending()
+   *   .paginate(10);
+   *
+   * while (paginator.hasNextPage()) {
+   *   const page = await paginator.getNextPage();
+   *   for (const incident of page.items) {
+   *     await processSecurityBreach(incident);
+   *   }
+   *   console.log(`Processed incidents page ${page.page}`);
+   * }
+   * ```
+   *
+   * @returns true if there are more pages available, false otherwise
+   */
+  hasNextPage() {
+    if (this.overallLimit !== void 0 && this.totalItemsRetrieved >= this.overallLimit) {
+      return false;
+    }
+    return this.hasMorePages;
+  }
+  /**
+   * Retrieves the next page of dinosaurs or habitats from DynamoDB.
+   *
+   * This method handles:
+   * - Automatic continuation between groups
+   * - Respect for park capacity limits
+   * - Group size adjustments for safety
+   *
+   * @example
+   * ```ts
+   * const paginator = new QueryBuilder(executor, eq('species', 'Velociraptor'))
+   *   .filter(op => op.eq('status', 'ACTIVE'))
+   *   .paginate(5);
+   *
+   * // Check first raptor group
+   * const page1 = await paginator.getNextPage();
+   * console.log(`Found ${page1.items.length} active raptors`);
+   *
+   * // Continue inspection if more groups exist
+   * if (page1.hasNextPage) {
+   *   const page2 = await paginator.getNextPage();
+   *   console.log(`Inspecting raptor group ${page2.page}`);
+   *
+   *   for (const raptor of page2.items) {
+   *     await performHealthCheck(raptor);
+   *   }
+   * }
+   * ```
+   *
+   * @returns A promise that resolves to a PaginationResult containing:
+   *          - items: The dinosaurs/habitats for this page
+   *          - hasNextPage: Whether more groups exist
+   *          - page: The current group number
+   *          - lastEvaluatedKey: DynamoDB's continuation token
+   */
+  async getNextPage() {
+    if (!this.hasNextPage()) {
+      return {
+        items: [],
+        hasNextPage: false,
+        page: this.currentPage
+      };
+    }
+    let effectivePageSize = this.pageSize;
+    if (this.overallLimit !== void 0) {
+      const remainingItems = this.overallLimit - this.totalItemsRetrieved;
+      if (remainingItems <= 0) {
+        return {
+          items: [],
+          hasNextPage: false,
+          page: this.currentPage
+        };
+      }
+      if (effectivePageSize !== void 0) {
+        effectivePageSize = Math.min(effectivePageSize, remainingItems);
+      } else {
+        effectivePageSize = remainingItems;
+      }
+    }
+    const query = this.queryBuilder.clone();
+    if (effectivePageSize !== void 0) {
+      query.limit(effectivePageSize);
+    }
+    if (this.lastEvaluatedKey) {
+      query.startFrom(this.lastEvaluatedKey);
+    }
+    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;
+    this.hasMorePages = !!result.lastEvaluatedKey && (this.overallLimit === void 0 || this.totalItemsRetrieved < this.overallLimit);
+    return {
+      items: result.items,
+      lastEvaluatedKey: result.lastEvaluatedKey,
+      hasNextPage: this.hasNextPage(),
+      page: this.currentPage
+    };
+  }
+  /**
+   * Gets all remaining dinosaurs or habitats and combines them into a single array.
+   *
+   * @example
+   * ```ts
+   * // Get complete carnivore inventory
+   * const paginator = new QueryBuilder(executor, eq('diet', 'CARNIVORE'))
+   *   .filter(op => op.eq('status', 'ACTIVE'))
+   *   .paginate(10);
+   *
+   * try {
+   *   const allCarnivores = await paginator.getAllPages();
+   *   console.log(`Park contains ${allCarnivores.length} active carnivores`);
+   *
+   *   // Calculate total threat level
+   *   const totalThreat = allCarnivores.reduce(
+   *     (sum, dino) => sum + dino.stats.threatLevel,
+   *     0
+   *   );
+   *   console.log(`Total threat level: ${totalThreat}`);
+   * } catch (error) {
+   *   console.error('Failed to complete carnivore census:', error);
+   * }
+   * ```
+   *
+   * @returns A promise that resolves to an array containing all remaining items
+   */
+  async getAllPages() {
+    const allItems = [];
+    while (this.hasNextPage()) {
+      const result = await this.getNextPage();
+      allItems.push(...result.items);
+    }
+    return allItems;
+  }
+};
+
+// src/builders/filter-builder.ts
+var FilterBuilder = class {
+  options = {};
+  selectedFields = /* @__PURE__ */ new Set();
+  /**
+   * Sets the maximum number of items to return.
+   *
+   * Note: This limit applies to the items that match the key condition
+   * before any filter expressions are applied.
+   *
+   * @example
+   * ```typescript
+   * // Get first 10 dinosaurs
+   * const result = await builder
+   *   .limit(10)
+   *   .execute();
+   * ```
+   *
+   * @param limit - Maximum number of items to return
+   * @returns The builder instance for method chaining
+   */
+  limit(limit) {
+    this.options.limit = limit;
+    return this;
+  }
+  /**
+   * Gets the current limit set on the operation.
+   * This is used internally by the paginator to manage result sets.
+   *
+   * @returns The current limit or undefined if no limit is set
+   */
+  getLimit() {
+    return this.options.limit;
+  }
+  /**
+   * Specifies a Global Secondary Index (GSI) to use for the operation.
+   *
+   * @example
+   * ```typescript
+   * // Find all dinosaurs of a specific species
+   * builder
+   *   .useIndex('species-status-index')
+   *   .filter(op => op.eq('status', 'ACTIVE'));
+   *
+   * // Search high-security habitats
+   * builder
+   *   .useIndex('security-level-index')
+   *   .filter(op =>
+   *     op.and([
+   *       op.gt('securityLevel', 8),
+   *       op.eq('status', 'OPERATIONAL')
+   *     ])
+   *   );
+   * ```
+   *
+   * @param indexName - The name of the GSI to use (type-safe based on table configuration)
+   * @returns The builder instance for method chaining
+   */
+  useIndex(indexName) {
+    this.options.indexName = indexName;
+    return this;
+  }
+  /**
+   * Sets whether to use strongly consistent reads for the operation.
+   *
+   * Note:
+   * - Consistent reads are not available on GSIs
+   * - Consistent reads consume twice the throughput
+   * - Default is eventually consistent reads
+   *
+   * @example
+   * ```typescript
+   * // Check immediate dinosaur status
+   * const result = await builder
+   *   .filter(op => op.eq('status', 'ACTIVE'))
+   *   .consistentRead()
+   *   .execute();
+   *
+   * // Monitor security breaches
+   * const result = await builder
+   *   .useIndex('primary-index')
+   *   .consistentRead(isEmergencyMode)
+   *   .execute();
+   * ```
+   *
+   * @param consistentRead - Whether to use consistent reads (defaults to true)
+   * @returns The builder instance for method chaining
+   */
+  consistentRead(consistentRead = true) {
+    this.options.consistentRead = consistentRead;
+    return this;
+  }
+  /**
+   * Adds a filter expression to refine the operation results.
+   *
+   * @example
+   * ```typescript
+   * // Find aggressive carnivores
+   * builder.filter(op =>
+   *   op.and([
+   *     op.eq('diet', 'CARNIVORE'),
+   *     op.gt('aggressionLevel', 7),
+   *     op.eq('status', 'ACTIVE')
+   *   ])
+   * );
+   *
+   * // Search suitable breeding habitats
+   * builder.filter(op =>
+   *   op.and([
+   *     op.between('temperature', 25, 30),
+   *     op.lt('currentOccupants', 3),
+   *     op.eq('quarantineStatus', 'CLEAR')
+   *   ])
+   * );
+   * ```
+   *
+   * @param condition - Either a Condition object or a callback function that builds the condition
+   * @returns The builder instance for method chaining
+   */
+  filter(condition) {
+    const newCondition = typeof condition === "function" ? condition(this.getConditionOperator()) : condition;
+    if (this.options.filter) {
+      if (this.options.filter.type === "and" && this.options.filter.conditions) {
+        if (newCondition.type === "and" && newCondition.conditions) {
+          this.options.filter = {
+            type: "and",
+            conditions: [...this.options.filter.conditions, ...newCondition.conditions]
+          };
+        } else {
+          this.options.filter = {
+            type: "and",
+            conditions: [...this.options.filter.conditions, newCondition]
+          };
+        }
+      } else {
+        if (newCondition.type === "and" && newCondition.conditions) {
+          this.options.filter = {
+            type: "and",
+            conditions: [this.options.filter, ...newCondition.conditions]
+          };
+        } else {
+          this.options.filter = and(this.options.filter, newCondition);
+        }
+      }
+    } else {
+      this.options.filter = newCondition;
+    }
+    return this;
+  }
+  getConditionOperator() {
+    return {
+      eq,
+      ne,
+      lt,
+      lte,
+      gt,
+      gte,
+      between,
+      inArray,
+      beginsWith,
+      contains,
+      attributeExists,
+      attributeNotExists,
+      and,
+      or,
+      not
+    };
+  }
+  /**
+   * Specifies which attributes to return in the results.
+   *
+   * @example
+   * ```typescript
+   * // Get basic dinosaur info
+   * builder.select([
+   *   'species',
+   *   'status',
+   *   'stats.health',
+   *   'stats.aggressionLevel'
+   * ]);
+   *
+   * // Monitor habitat conditions
+   * builder
+   *   .select('securityStatus')
+   *   .select([
+   *     'currentOccupants',
+   *     'temperature',
+   *     'lastInspectionDate'
+   *   ]);
+   * ```
+   *
+   * @param fields - A single field name or an array of field names to return
+   * @returns The builder instance for method chaining
+   */
+  select(fields) {
+    if (typeof fields === "string") {
+      this.selectedFields.add(fields);
+    } else if (Array.isArray(fields)) {
+      for (const field of fields) {
+        this.selectedFields.add(field);
+      }
+    }
+    this.options.projection = Array.from(this.selectedFields);
+    return this;
+  }
+  /**
+   * Creates a paginator that handles DynamoDB pagination automatically.
+   * The paginator handles:
+   * - Tracking the last evaluated key
+   * - Managing page boundaries
+   * - Respecting overall query limits
+   *
+   * @example
+   * ```typescript
+   * // 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();
+   *   console.log(`Processing page ${page.page}, count: ${page.items.length}`);
+   *   // Process dinosaur data
+   * }
+   * ```
+   *
+   * @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
+   */
+  paginate(pageSize) {
+    return new Paginator(this, pageSize);
+  }
+  /**
+   * Sets the starting point using a previous lastEvaluatedKey.
+   *
+   * Note: This method is typically used for manual pagination.
+   * For automatic pagination, use the paginate() method instead.
+   *
+   * @example
+   * ```typescript
+   * // First batch of dinosaurs
+   * const result1 = await builder
+   *   .filter(op => op.eq('status', 'ACTIVE'))
+   *   .limit(5)
+   *   .execute();
+   *
+   * const lastKey = result1.getLastEvaluatedKey();
+   * if (lastKey) {
+   *   // Continue listing dinosaurs
+   *   const result2 = await builder
+   *     .filter(op => op.eq('status', 'ACTIVE'))
+   *     .startFrom(lastKey)
+   *     .limit(5)
+   *     .execute();
+   *
+   *   const items = await result2.toArray();
+   *   console.log('Additional dinosaurs:', items);
+   * }
+   * ```
+   *
+   * @param lastEvaluatedKey - The exclusive start key from a previous result
+   * @returns The builder instance for method chaining
+   */
+  startFrom(lastEvaluatedKey) {
+    this.options.lastEvaluatedKey = lastEvaluatedKey;
+    return this;
+  }
+  /**
+   * Executes the operation and returns the first matching item, if any.
+   *
+   * This helper:
+   * - Applies an internal limit of 1
+   * - Streams results until a match is found or there are no more pages
+   * - Avoids mutating the current builder by using a clone
+   *
+   * @example
+   * ```typescript
+   * const latest = await table
+   *   .query(eq("moduleId", moduleId))
+   *   .useIndex("module-version-index")
+   *   .sortDescending()
+   *   .findOne();
+   * ```
+   *
+   * @returns The first matching item, or undefined if none found
+   */
+  async findOne() {
+    const iterator = await this.clone().limit(1).execute();
+    for await (const item of iterator) {
+      return item;
+    }
+    return void 0;
+  }
+};
+
+// src/builders/get-builder.ts
+var GetBuilder = class {
+  /**
+   * Creates a new GetBuilder instance.
+   *
+   * @param executor - Function that executes the get operation
+   * @param key - Primary key of the item to retrieve
+   * @param tableName - Name of the DynamoDB table
+   */
+  constructor(executor, key, tableName, indexAttributeNames = []) {
+    this.executor = executor;
+    this.params = {
+      tableName,
+      key
+    };
+    this.indexAttributeNames = indexAttributeNames;
+  }
+  params;
+  options = {};
+  selectedFields = /* @__PURE__ */ new Set();
+  includeIndexAttributes = false;
+  indexAttributeNames;
+  /**
+   * Specifies which attributes to return in the get results.
+   *
+   * @example
+   * ```typescript
+   * // Select single attribute
+   * builder.select('species')
+   *
+   * // Select multiple attributes
+   * builder.select(['id', 'species', 'diet'])
+   *
+   * // Chain multiple select calls
+   * builder
+   *   .select('id')
+   *   .select(['species', 'diet'])
+   * ```
+   *
+   * @param fields - A single field name or an array of field names to return
+   * @returns The builder instance for method chaining
+   */
+  select(fields) {
+    if (typeof fields === "string") {
+      this.selectedFields.add(fields);
+    } else if (Array.isArray(fields)) {
+      for (const field of fields) {
+        this.selectedFields.add(field);
+      }
+    }
+    if (this.includeIndexAttributes) {
+      this.addIndexAttributesToSelection();
+    }
+    this.options.projection = Array.from(this.selectedFields);
+    return this;
+  }
+  /**
+   * Ensures index attributes are included in the result.
+   * By default, index attributes are removed from get responses.
+   */
+  includeIndexes() {
+    this.includeIndexAttributes = true;
+    if (this.selectedFields.size > 0) {
+      this.addIndexAttributesToSelection();
+    }
+    return this;
+  }
+  /**
+   * Sets whether to use strongly consistent reads for the get operation.
+   * Use this method when you need:
+   * - The most up-to-date dinosaur data
+   * - To ensure you're reading the latest dinosaur status
+   * - Critical safety information about dangerous species
+   *
+   * Note: Consistent reads consume twice the throughput
+   *
+   * @example
+   * ```typescript
+   * // Get the latest T-Rex data
+   * const result = await new GetBuilder(executor, { pk: 'dinosaur#123', sk: 'profile' })
+   *   .consistentRead()
+   *   .execute();
+   * ```
+   *
+   * @param consistentRead - Whether to use consistent reads (defaults to true)
+   * @returns The builder instance for method chaining
+   */
+  consistentRead(consistentRead = true) {
+    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
+    };
+  }
+  addIndexAttributesToSelection() {
+    if (this.indexAttributeNames.length === 0) return;
+    for (const attributeName of this.indexAttributeNames) {
+      this.selectedFields.add(attributeName);
+    }
+    this.options.projection = Array.from(this.selectedFields);
+  }
+  omitIndexAttributes(item) {
+    if (!item || this.includeIndexAttributes || this.indexAttributeNames.length === 0) {
+      return item;
+    }
+    let didOmit = false;
+    const cleaned = { ...item };
+    for (const attributeName of this.indexAttributeNames) {
+      if (attributeName in cleaned) {
+        delete cleaned[attributeName];
+        didOmit = true;
+      }
+    }
+    return didOmit ? cleaned : item;
+  }
+  /**
+   * Executes the get operation against DynamoDB.
+   *
+   * @example
+   * ```typescript
+   * try {
+   *   const result = await new GetBuilder(executor, { pk: 'dinosaur#123', sk: 'profile' })
+   *     .select(['species', 'name', 'diet'])
+   *     .consistentRead()
+   *     .execute();
+   *
+   *   if (result.item) {
+   *     console.log('Dinosaur found:', result.item);
+   *   } else {
+   *     console.log('Dinosaur not found');
+   *   }
+   * } catch (error) {
+   *   console.error('Error getting dinosaur:', error);
+   * }
+   * ```
+   *
+   * @returns A promise that resolves to an object containing:
+   *          - item: The retrieved dinosaur or undefined if not found
+   */
+  async execute() {
+    const command = this.toDynamoCommand();
+    const result = await this.executor(command);
+    return {
+      item: this.omitIndexAttributes(result.item)
+    };
+  }
+};
+
+// src/builders/put-builder.ts
+var PutBuilder = class {
+  item;
+  options;
+  executor;
+  tableName;
+  constructor(executor, item, tableName) {
+    this.executor = executor;
+    this.item = item;
+    this.tableName = tableName;
+    this.options = {
+      returnValues: "NONE"
+    };
+  }
+  set(valuesOrPath, value) {
+    if (typeof valuesOrPath === "object") {
+      Object.assign(this.item, valuesOrPath);
+    } else {
+      this.item[valuesOrPath] = value;
+    }
+    return this;
+  }
+  /**
+   * Adds a condition that must be satisfied for the put operation to succeed.
+   *
+   * @example
+   * ```ts
+   * // Ensure item doesn't exist (insert only)
+   * builder.condition(op => op.attributeNotExists('id'))
+   *
+   * // Complex condition with version check
+   * builder.condition(op =>
+   *   op.and([
+   *     op.attributeExists('id'),
+   *     op.eq('version', currentVersion),
+   *     op.eq('status', 'ACTIVE')
+   *   ])
+   * )
+   * ```
+   *
+   * @param condition - Either a Condition object or a callback function that builds the condition
+   * @returns The builder instance for method chaining
+   */
+  /**
+   * Adds a condition that must be satisfied for the put operation to succeed.
+   *
+   * @example
+   * ```typescript
+   * // Ensure unique dinosaur ID
+   * builder.condition(op =>
+   *   op.attributeNotExists('id')
+   * );
+   *
+   * // Verify habitat requirements
+   * builder.condition(op =>
+   *   op.and([
+   *     op.eq('securityStatus', 'READY'),
+   *     op.attributeExists('lastInspection'),
+   *     op.gt('securityLevel', 5)
+   *   ])
+   * );
+   *
+   * // Check breeding facility conditions
+   * builder.condition(op =>
+   *   op.and([
+   *     op.between('temperature', 25, 30),
+   *     op.between('humidity', 60, 80),
+   *     op.eq('quarantineStatus', 'CLEAR')
+   *   ])
+   * );
+   * ```
+   *
+   * @param condition - Either a Condition object or a callback function that builds the condition
+   * @returns The builder instance for method chaining
+   */
+  condition(condition) {
+    if (typeof condition === "function") {
+      const conditionOperator = {
+        eq,
+        ne,
+        lt,
+        lte,
+        gt,
+        gte,
+        between,
+        inArray,
+        beginsWith,
+        contains,
+        attributeExists,
+        attributeNotExists,
+        and,
+        or,
+        not
+      };
+      this.options.condition = condition(conditionOperator);
+    } else {
+      this.options.condition = condition;
+    }
+    return this;
+  }
+  /**
+   * Sets whether to return the item's previous values (if it existed).
+   *
+   * @options
+   *  - NONE: No return value
+   *  - ALL_OLD: Returns the item's previous state if it existed, no read capacity units are consumed
+   *  - CONSISTENT: Performs a GET operation after the put to retrieve the item's new state
+   *  - INPUT: Returns the input values that were passed to the operation
+   *
+   * @example
+   * ```ts
+   * // Get previous dinosaur state
+   * const result = await builder
+   *   .returnValues('ALL_OLD')
+   *   .execute();
+   *
+   * if (result) {
+   *   console.log('Previous profile:', {
+   *     species: result.species,
+   *     status: result.status,
+   *     stats: {
+   *       health: result.stats.health,
+   *       threatLevel: result.stats.threatLevel
+   *     }
+   *   });
+   * }
+   *
+   * // Return input values for create operations
+   * const createResult = await builder
+   *   .returnValues('INPUT')
+   *   .execute();
+   * ```
+   *
+   * @param returnValues - Use 'ALL_OLD' to return previous values, 'INPUT' to return input values, 'CONSISTENT' for fresh data, or 'NONE' (default).
+   * @returns The builder instance for method chaining
+   */
+  returnValues(returnValues) {
+    this.options.returnValues = returnValues;
+    return this;
+  }
+  /**
+   * Generate the DynamoDB command parameters
+   */
+  toDynamoCommand() {
+    const { expression, names, values } = prepareExpressionParams(this.options.condition);
+    return {
+      tableName: this.tableName,
+      item: this.item,
+      conditionExpression: expression,
+      expressionAttributeNames: names,
+      expressionAttributeValues: values,
+      returnValues: this.options.returnValues
+    };
+  }
+  /**
+   * Adds this put operation to a transaction.
+   *
+   * @example
+   * ```ts
+   * const transaction = new TransactionBuilder();
+   *
+   * // Add dinosaur to new habitat
+   * new PutBuilder(executor, {
+   *   id: 'TREX-002',
+   *   location: 'PADDOCK-B',
+   *   status: 'ACTIVE',
+   *   transferDate: new Date().toISOString()
+   * }, 'dinosaurs')
+   *   .withTransaction(transaction);
+   *
+   * // Update habitat records
+   * new UpdateBuilder(executor, 'habitats', { id: 'PADDOCK-B' })
+   *   .add('occupants', 1)
+   *   .set('lastTransfer', new Date().toISOString())
+   *   .withTransaction(transaction);
+   *
+   * // Execute transfer atomically
+   * await transaction.execute();
+   * ```
+   *
+   * @param transaction - The transaction builder to add this operation to
+   * @returns The builder instance for method chaining
+   */
+  withTransaction(transaction) {
+    const command = this.toDynamoCommand();
+    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.
+   *
+   * @example
+   * ```ts
+   * try {
+   *   // Put with condition and return old values
+   *   const result = await new PutBuilder(executor, newItem, 'myTable')
+   *     .condition(op => op.eq('version', 1))
+   *     .returnValues('ALL_OLD')
+   *     .execute();
+   *
+   *   console.log('Put successful, old item:', result);
+   * } catch (error) {
+   *   // Handle condition check failure or other errors
+   *   console.error('Put failed:', error);
+   * }
+   * ```
+   *
+   * @returns A promise that resolves to the operation result (type depends on returnValues setting)
+   * @throws Will throw an error if the condition check fails or other DynamoDB errors occur
+   */
+  async execute() {
+    const params = this.toDynamoCommand();
+    return this.executor(params);
+  }
+  /**
+   * Gets a human-readable representation of the put command
+   * with all expression placeholders replaced by their actual values.
+   *
+   * @example
+   * ```ts
+   * const debugInfo = new PutBuilder(executor, {
+   *   id: 'RAPTOR-003',
+   *   species: 'Velociraptor',
+   *   status: 'QUARANTINE',
+   *   stats: {
+   *     health: 100,
+   *     aggressionLevel: 7,
+   *     age: 2
+   *   }
+   * }, 'dinosaurs')
+   *   .condition(op =>
+   *     op.and([
+   *       op.attributeNotExists('id'),
+   *       op.eq('quarantineStatus', 'READY'),
+   *       op.gt('securityLevel', 8)
+   *     ])
+   *   )
+   *   .debug();
+   *
+   * console.log('Dinosaur transfer command:', debugInfo);
+   * ```
+   *
+   * @returns A readable representation of the put command with resolved expressions
+   */
+  debug() {
+    const command = this.toDynamoCommand();
+    return debugCommand(command);
+  }
+};
+
+// 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;
+  options = {};
+  executor;
+  includeIndexAttributes = false;
+  indexAttributeNames;
+  constructor(executor, keyCondition, indexAttributeNames = []) {
+    super();
+    this.executor = executor;
+    this.keyCondition = keyCondition;
+    this.indexAttributeNames = indexAttributeNames;
+  }
+  /**
+   * Sets the maximum number of items to return from the query.
+   *
+   * Note: This is the default behavior if no sort order is specified.
+   *
+   * @example
+   * ```typescript
+   * // Get orders in chronological order
+   * const result = await new QueryBuilder(executor, eq('userId', '123'))
+   *   .sortAscending()
+   *   .execute();
+   *
+   * // Get events from oldest to newest
+   * const result = await new QueryBuilder(executor, eq('entityId', 'order-123'))
+   *   .useIndex('entity-timestamp-index')
+   *   .sortAscending()
+   *   .execute();
+   * ```
+   *
+   * @returns The builder instance for method chaining
+   */
+  /**
+   * Sets the query to return items in ascending order by sort key.
+   *
+   * @example
+   * ```typescript
+   * // List dinosaurs by age
+   * const result = await new QueryBuilder(executor, eq('species', 'Velociraptor'))
+   *   .useIndex('age-index')
+   *   .sortAscending()
+   *   .execute();
+   *
+   * // View incidents chronologically
+   * const result = await new QueryBuilder(executor, eq('type', 'SECURITY_BREACH'))
+   *   .useIndex('date-index')
+   *   .sortAscending()
+   *   .execute();
+   * ```
+   *
+   * @returns The builder instance for method chaining
+   */
+  sortAscending() {
+    this.options.scanIndexForward = true;
+    return this;
+  }
+  /**
+   * Sets the query to return items in descending order by sort key.
+   *
+   * @example
+   * ```typescript
+   * // Get most recent security incidents
+   * const result = await new QueryBuilder(executor, eq('type', 'SECURITY_BREACH'))
+   *   .useIndex('date-index')
+   *   .sortDescending()
+   *   .limit(10)
+   *   .execute();
+   *
+   * // Check latest dinosaur activities
+   * const result = await new QueryBuilder(executor, eq('species', 'Velociraptor'))
+   *   .useIndex('activity-time-index')
+   *   .filter(op => op.eq('status', 'ACTIVE'))
+   *   .sortDescending()
+   *   .execute();
+   * ```
+   *
+   * @returns The builder instance for method chaining
+   */
+  sortDescending() {
+    this.options.scanIndexForward = false;
+    return this;
+  }
+  /**
+   * Ensures index attributes are included in the result.
+   * By default, index attributes are removed from query responses.
+   */
+  includeIndexes() {
+    this.includeIndexAttributes = true;
+    if (this.selectedFields.size > 0) {
+      this.addIndexAttributesToSelection();
+    }
+    return this;
+  }
+  select(fields) {
+    super.select(fields);
+    if (this.includeIndexAttributes) {
+      this.addIndexAttributesToSelection();
+    }
+    return this;
+  }
+  /**
+   * Creates a deep clone of this QueryBuilder instance.
+   *
+   * This is particularly useful when:
+   * - Implementing pagination (used internally by paginate())
+   * - Creating query templates
+   * - Running multiple variations of a query
+   *
+   * @example
+   * ```typescript
+   * // Create base dinosaur query
+   * const baseQuery = new QueryBuilder(executor, eq('species', 'Velociraptor'))
+   *   .useIndex('status-index')
+   *   .select(['id', 'status', 'location']);
+   *
+   * // Check active dinosaurs
+   * const activeRaptors = baseQuery.clone()
+   *   .filter(op => op.eq('status', 'HUNTING'))
+   *   .execute();
+   *
+   * // Check contained dinosaurs
+   * const containedRaptors = baseQuery.clone()
+   *   .filter(op => op.eq('status', 'CONTAINED'))
+   *   .execute();
+   *
+   * // Check sedated dinosaurs
+   * const sedatedRaptors = baseQuery.clone()
+   *   .filter(op => op.eq('status', 'SEDATED'))
+   *   .execute();
+   * ```
+   *
+   * @returns A new QueryBuilder instance with the same configuration
+   */
+  clone() {
+    const clone = new _QueryBuilder(this.executor, this.keyCondition, this.indexAttributeNames);
+    clone.options = {
+      ...this.options,
+      filter: this.deepCloneFilter(this.options.filter)
+    };
+    clone.selectedFields = new Set(this.selectedFields);
+    clone.includeIndexAttributes = this.includeIndexAttributes;
+    return clone;
+  }
+  deepCloneFilter(filter) {
+    if (!filter) return filter;
+    if (filter.type === "and" || filter.type === "or") {
+      return {
+        ...filter,
+        conditions: filter.conditions?.map((condition) => this.deepCloneFilter(condition)).filter((c) => c !== void 0)
+      };
+    }
+    return { ...filter };
+  }
+  /**
+   * Executes the query against DynamoDB and returns a generator that behaves like an array.
+   *
+   * 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 with automatic pagination
+   *   const results = await new QueryBuilder(executor, eq('habitatId', 'PADDOCK-A'))
+   *     .useIndex('species-status-index')
+   *     .filter(op =>
+   *       op.and([
+   *         op.eq('diet', 'CARNIVORE'),
+   *         op.eq('status', 'ACTIVE'),
+   *         op.gt('aggressionLevel', 7)
+   *       ])
+   *     )
+   *     .sortDescending()
+   *     .execute();
+   *
+   *   // 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 a ResultGenerator that behaves like an array
+   */
+  async execute() {
+    const directExecutor = async () => {
+      const result = await this.executor(this.keyCondition, this.options);
+      if (this.includeIndexAttributes || this.indexAttributeNames.length === 0) {
+        return result;
+      }
+      return {
+        ...result,
+        items: result.items.map((item) => this.omitIndexAttributes(item))
+      };
+    };
+    return new ResultIterator(this, directExecutor);
+  }
+  addIndexAttributesToSelection() {
+    if (this.indexAttributeNames.length === 0) return;
+    for (const attributeName of this.indexAttributeNames) {
+      this.selectedFields.add(attributeName);
+    }
+    this.options.projection = Array.from(this.selectedFields);
+  }
+  omitIndexAttributes(item) {
+    if (this.indexAttributeNames.length === 0) {
+      return item;
+    }
+    let didOmit = false;
+    const cleaned = { ...item };
+    for (const attributeName of this.indexAttributeNames) {
+      if (attributeName in cleaned) {
+        delete cleaned[attributeName];
+        didOmit = true;
+      }
+    }
+    return didOmit ? cleaned : item;
+  }
+};
+
+// src/builders/scan-builder.ts
+var ScanBuilder = class _ScanBuilder extends FilterBuilder {
+  executor;
+  constructor(executor) {
+    super();
+    this.executor = executor;
+  }
+  /**
+   * Creates a deep clone of this ScanBuilder instance.
+   *
+   * @returns A new ScanBuilder instance with the same configuration
+   */
+  clone() {
+    const clone = new _ScanBuilder(this.executor);
+    clone.options = {
+      ...this.options,
+      filter: this.deepCloneFilter(this.options.filter)
+    };
+    clone.selectedFields = new Set(this.selectedFields);
+    return clone;
+  }
+  deepCloneFilter(filter) {
+    if (!filter) return filter;
+    if (filter.type === "and" || filter.type === "or") {
+      return {
+        ...filter,
+        conditions: filter.conditions?.map((condition) => this.deepCloneFilter(condition)).filter((c) => c !== void 0)
+      };
+    }
+    return { ...filter };
+  }
+  /**
+   * Executes the scan against DynamoDB and returns a generator that behaves like an array.
+   *
+   * 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 with automatic pagination
+   *   const results = await new ScanBuilder(executor)
+   *     .filter(op =>
+   *       op.and([
+   *         op.eq('status', 'ACTIVE'),
+   *         op.gt('aggressionLevel', 7)
+   *       ])
+   *     )
+   *     .execute();
+   *
+   *   // 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 a ResultGenerator that behaves like an array
+   */
+  async execute() {
+    const directExecutor = () => this.executor(this.options);
+    return new ResultIterator(this, directExecutor);
+  }
+};
+
+// src/utils/debug-transaction.ts
+function debugTransactionItem(item) {
+  const result = {
+    type: item.type,
+    tableName: item.params.tableName
+  };
+  if ("key" in item.params) {
+    result.key = item.params.key;
+  }
+  if (item.type === "Put") {
+    result.item = item.params.item;
+  }
+  switch (item.type) {
+    case "Put":
+    case "Delete":
+    case "ConditionCheck":
+      result.readable = debugCommand(item.params).readable;
+      break;
+    case "Update":
+      result.readable = debugCommand(item.params).readable;
+      break;
+  }
+  return result;
+}
+function debugTransaction(items) {
+  return items.map((item) => debugTransactionItem(item));
+}
+
+// src/builders/transaction-builder.ts
+var TransactionBuilder = class {
+  items = [];
+  options = {};
+  indexConfig;
+  executor;
+  constructor(executor, indexConfig) {
+    this.executor = executor;
+    this.indexConfig = indexConfig;
+  }
+  /**
+   * Checks if an item with the same primary key already exists in the transaction
+   * @private
+   */
+  checkForDuplicateItem(tableName, newItem) {
+    const pkName = this.indexConfig.partitionKey;
+    const skName = this.indexConfig.sortKey ?? "";
+    const pkValue = newItem[pkName];
+    const skValue = skName ? newItem[skName] : void 0;
+    if (!pkValue) {
+      throw ConfigurationErrors.primaryKeyMissing(tableName, pkName, newItem);
+    }
+    const duplicateItem = this.items.find((item) => {
+      let itemKey;
+      let itemTableName;
+      switch (item.type) {
+        case "Put":
+          itemTableName = item.params.tableName;
+          itemKey = item.params.item;
+          break;
+        case "Update":
+        case "Delete":
+        case "ConditionCheck":
+          itemTableName = item.params.tableName;
+          itemKey = item.params.key;
+          break;
+      }
+      if (itemTableName === tableName && itemKey) {
+        const itemPkValue = itemKey[pkName];
+        const itemSkValue = skName ? itemKey[skName] : void 0;
+        if (itemPkValue === pkValue) {
+          if (skValue === void 0 && itemSkValue === void 0) {
+            return true;
+          }
+          if (skValue !== void 0 && itemSkValue !== void 0 && skValue === itemSkValue) {
+            return true;
+          }
+        }
+      }
+      return false;
+    });
+    if (duplicateItem) {
+      throw TransactionErrors.duplicateItem(
+        tableName,
+        { name: pkName, value: pkValue },
+        skName ? { name: skName, value: skValue } : void 0
+      );
+    }
+  }
+  createKeyForPrimaryIndex(key) {
+    const keyCondition = {
+      [this.indexConfig.partitionKey]: key.pk
+    };
+    if (this.indexConfig.sortKey) {
+      if (key.sk === void 0) {
+        throw ConfigurationErrors.sortKeyRequired("", this.indexConfig.partitionKey, this.indexConfig.sortKey);
+      }
+      keyCondition[this.indexConfig.sortKey] = key.sk;
+    }
+    return keyCondition;
+  }
+  /**
+   * Adds a put operation to the transaction.
+   *
+   * The method automatically checks for duplicate items within the transaction
+   * to prevent multiple operations on the same item.
+   *
+   * @example
+   * ```typescript
+   * // Simple put operation
+   * transaction.put('orders', {
+   *   orderId: '123',
+   *   status: 'PENDING',
+   *   amount: 100
+   * });
+   *
+   * // Conditional put operation
+   * transaction.put(
+   *   'inventory',
+   *   { productId: 'ABC', quantity: 50 },
+   *   op => op.attributeNotExists('productId')
+   * );
+   *
+   * // Put with complex condition
+   * transaction.put(
+   *   'users',
+   *   { userId: '123', status: 'ACTIVE' },
+   *   op => op.and([
+   *     op.attributeNotExists('userId'),
+   *     op.beginsWith('status', 'ACTIVE')
+   *   ])
+   * );
+   * ```
+   *
+   * @param tableName - The name of the DynamoDB table
+   * @param item - The item to put into the table
+   * @param condition - Optional condition that must be satisfied
+   * @returns The transaction builder for method chaining
+   * @throws {Error} If a duplicate item is detected in the transaction
+   */
+  put(tableName, item, condition) {
+    this.checkForDuplicateItem(tableName, item);
+    const transactionItem = {
+      type: "Put",
+      params: {
+        tableName,
+        item
+      }
+    };
+    if (condition) {
+      const { expression, names, values } = prepareExpressionParams(condition);
+      transactionItem.params.conditionExpression = expression;
+      transactionItem.params.expressionAttributeNames = names;
+      transactionItem.params.expressionAttributeValues = values;
+    }
+    this.items.push(transactionItem);
+    return this;
+  }
+  /**
+   * Adds a pre-configured put operation to the transaction.
+   *
+   * This method is particularly useful when working with PutBuilder
+   * to maintain consistency in put operations across your application.
+   *
+   * @example
+   * ```typescript
+   * // Create a put command with PutBuilder
+   * const putCommand = new PutBuilder(executor, newItem, 'users')
+   *   .condition(op => op.attributeNotExists('userId'))
+   *   .toDynamoCommand();
+   *
+   * // Add the command to the transaction
+   * transaction.putWithCommand(putCommand);
+   * ```
+   *
+   * @param command - The complete put command configuration
+   * @returns The transaction builder for method chaining
+   * @throws {Error} If a duplicate item is detected in the transaction
+   * @see PutBuilder for creating put commands
+   */
+  putWithCommand(command) {
+    this.checkForDuplicateItem(command.tableName, command.item);
+    const transactionItem = {
+      type: "Put",
+      params: command
+    };
+    this.items.push(transactionItem);
+    return this;
+  }
+  /**
+   * Adds a delete operation to the transaction.
+   *
+   * The method automatically checks for duplicate items within the transaction
+   * to prevent multiple operations on the same item.
+   *
+   * @example
+   * ```typescript
+   * // Simple delete operation
+   * transaction.delete('orders', {
+   *   pk: 'ORDER#123',
+   *   sk: 'METADATA'
+   * });
+   *
+   * // Conditional delete operation
+   * transaction.delete(
+   *   'users',
+   *   { pk: 'USER#123' },
+   *   op => op.eq('status', 'INACTIVE')
+   * );
+   *
+   * // Delete with complex condition
+   * transaction.delete(
+   *   'products',
+   *   { pk: 'PROD#ABC' },
+   *   op => op.and([
+   *     op.eq('status', 'DRAFT'),
+   *     op.lt('version', 5)
+   *   ])
+   * );
+   * ```
+   *
+   * @param tableName - The name of the DynamoDB table
+   * @param key - The primary key of the item to delete
+   * @param condition - Optional condition that must be satisfied
+   * @returns The transaction builder for method chaining
+   * @throws {Error} If a duplicate item is detected in the transaction
+   */
+  delete(tableName, key, condition) {
+    const keyCondition = this.createKeyForPrimaryIndex(key);
+    this.checkForDuplicateItem(tableName, keyCondition);
+    const transactionItem = {
+      type: "Delete",
+      params: {
+        tableName,
+        key: keyCondition
+      }
+    };
+    if (condition) {
+      const { expression, names, values } = prepareExpressionParams(condition);
+      transactionItem.params.conditionExpression = expression;
+      transactionItem.params.expressionAttributeNames = names;
+      transactionItem.params.expressionAttributeValues = values;
+    }
+    this.items.push(transactionItem);
+    return this;
+  }
+  /**
+   * Adds a pre-configured delete operation to the transaction.
+   *
+   * This method is particularly useful when working with DeleteBuilder
+   * to maintain consistency in delete operations across your application.
+   *
+   * @example
+   * ```typescript
+   * // Create a delete command with DeleteBuilder
+   * const deleteCommand = new DeleteBuilder(executor, 'users', { pk: 'USER#123' })
+   *   .condition(op => op.and([
+   *     op.attributeExists('pk'),
+   *     op.eq('status', 'INACTIVE')
+   *   ]))
+   *   .toDynamoCommand();
+   *
+   * // Add the command to the transaction
+   * transaction.deleteWithCommand(deleteCommand);
+   * ```
+   *
+   * @param command - The complete delete command configuration
+   * @returns The transaction builder for method chaining
+   * @throws {Error} If a duplicate item is detected in the transaction
+   * @see DeleteBuilder for creating delete commands
+   */
+  deleteWithCommand(command) {
+    let keyForDuplicateCheck;
+    let keyForTransaction;
+    if (typeof command.key === "object" && command.key !== null && "pk" in command.key) {
+      keyForTransaction = this.createKeyForPrimaryIndex(command.key);
+      keyForDuplicateCheck = keyForTransaction;
+    } else {
+      keyForTransaction = command.key;
+      keyForDuplicateCheck = command.key;
+    }
+    this.checkForDuplicateItem(command.tableName, keyForDuplicateCheck);
+    const transactionItem = {
+      type: "Delete",
+      params: {
+        ...command,
+        key: keyForTransaction
+      }
+    };
+    this.items.push(transactionItem);
+    return this;
+  }
+  /**
+   * Adds an update operation to the transaction.
+   *
+   * The method supports all DynamoDB update expressions:
+   * - SET: Modify or add attributes
+   * - REMOVE: Delete attributes
+   * - ADD: Update numbers and sets
+   * - DELETE: Remove elements from a set
+   *
+   * @example
+   * ```typescript
+   * // Simple update
+   * transaction.update(
+   *   'orders',
+   *   { pk: 'ORDER#123' },
+   *   'SET #status = :status',
+   *   { '#status': 'status' },
+   *   { ':status': 'PROCESSING' }
+   * );
+   *
+   * // Complex update with multiple operations
+   * transaction.update(
+   *   'products',
+   *   { pk: 'PROD#ABC' },
+   *   'SET #qty = #qty - :amount, #status = :status REMOVE #oldAttr',
+   *   { '#qty': 'quantity', '#status': 'status', '#oldAttr': 'deprecated_field' },
+   *   { ':amount': 1, ':status': 'LOW_STOCK' }
+   * );
+   *
+   * // Conditional update
+   * transaction.update(
+   *   'users',
+   *   { pk: 'USER#123' },
+   *   'SET #lastLogin = :now',
+   *   { '#lastLogin': 'lastLoginDate' },
+   *   { ':now': new Date().toISOString() },
+   *   op => op.attributeExists('pk')
+   * );
+   * ```
+   *
+   * @param tableName - The name of the DynamoDB table
+   * @param key - The primary key of the item to update
+   * @param updateExpression - The update expression (SET, REMOVE, ADD, DELETE)
+   * @param expressionAttributeNames - Map of attribute name placeholders to actual names
+   * @param expressionAttributeValues - Map of value placeholders to actual values
+   * @param condition - Optional condition that must be satisfied
+   * @returns The transaction builder for method chaining
+   * @throws {Error} If a duplicate item is detected in the transaction
+   */
+  update(tableName, key, updateExpression, expressionAttributeNames, expressionAttributeValues, condition) {
+    const keyCondition = this.createKeyForPrimaryIndex(key);
+    this.checkForDuplicateItem(tableName, keyCondition);
+    const transactionItem = {
+      type: "Update",
+      params: {
+        tableName,
+        key: keyCondition,
+        updateExpression,
+        expressionAttributeNames,
+        expressionAttributeValues
+      }
+    };
+    if (condition) {
+      const { expression, names, values } = prepareExpressionParams(condition);
+      transactionItem.params.conditionExpression = expression;
+      transactionItem.params.expressionAttributeNames = {
+        ...transactionItem.params.expressionAttributeNames,
+        ...names
+      };
+      transactionItem.params.expressionAttributeValues = {
+        ...transactionItem.params.expressionAttributeValues,
+        ...values
+      };
+    }
+    this.items.push(transactionItem);
+    return this;
+  }
+  /**
+   * Adds a pre-configured update operation to the transaction.
+   *
+   * This method is particularly useful when working with UpdateBuilder
+   * to maintain consistency in update operations across your application.
+   *
+   * @example
+   * ```typescript
+   * // Create an update command with UpdateBuilder
+   * const updateCommand = new UpdateBuilder(executor, 'inventory', { pk: 'PROD#ABC' })
+   *   .set('quantity', ':qty')
+   *   .set('lastUpdated', ':now')
+   *   .values({
+   *     ':qty': 100,
+   *     ':now': new Date().toISOString()
+   *   })
+   *   .condition(op => op.gt('quantity', 0))
+   *   .toDynamoCommand();
+   *
+   * // Add the command to the transaction
+   * transaction.updateWithCommand(updateCommand);
+   * ```
+   *
+   * @param command - The complete update command configuration
+   * @returns The transaction builder for method chaining
+   * @throws {Error} If a duplicate item is detected in the transaction
+   * @see UpdateBuilder for creating update commands
+   */
+  updateWithCommand(command) {
+    let keyForDuplicateCheck;
+    let keyForTransaction;
+    if (typeof command.key === "object" && command.key !== null && "pk" in command.key) {
+      keyForTransaction = this.createKeyForPrimaryIndex(command.key);
+      keyForDuplicateCheck = keyForTransaction;
+    } else {
+      keyForTransaction = command.key;
+      keyForDuplicateCheck = command.key;
+    }
+    this.checkForDuplicateItem(command.tableName, keyForDuplicateCheck);
+    const transactionItem = {
+      type: "Update",
+      params: {
+        ...command,
+        key: keyForTransaction
+      }
+    };
+    this.items.push(transactionItem);
+    return this;
+  }
+  /**
+   * Adds a condition check operation to the transaction.
+   *
+   * Condition checks are particularly useful for:
+   * - Implementing optimistic locking
+   * - Ensuring referential integrity
+   * - Validating business rules atomically
+   *
+   * @example
+   * ```typescript
+   * // Check if order is in correct state
+   * transaction.conditionCheck(
+   *   'orders',
+   *   { pk: 'ORDER#123' },
+   *   op => op.eq('status', 'PENDING')
+   * );
+   *
+   * // Complex condition check
+   * transaction.conditionCheck(
+   *   'inventory',
+   *   { pk: 'PROD#ABC' },
+   *   op => op.and([
+   *     op.gt('quantity', 0),
+   *     op.eq('status', 'ACTIVE'),
+   *     op.attributeExists('lastRestockDate')
+   *   ])
+   * );
+   *
+   * // Check with multiple attributes
+   * transaction.conditionCheck(
+   *   'users',
+   *   { pk: 'USER#123' },
+   *   op => op.or([
+   *     op.eq('status', 'PREMIUM'),
+   *     op.gte('credits', 100)
+   *   ])
+   * );
+   * ```
+   *
+   * @param tableName - The name of the DynamoDB table
+   * @param key - The primary key of the item to check
+   * @param condition - The condition that must be satisfied
+   * @returns The transaction builder for method chaining
+   * @throws {Error} If a duplicate item is detected in the transaction
+   * @throws {Error} If condition expression generation fails
+   */
+  conditionCheck(tableName, key, condition) {
+    const keyCondition = this.createKeyForPrimaryIndex(key);
+    this.checkForDuplicateItem(tableName, keyCondition);
+    const { expression, names, values } = prepareExpressionParams(condition);
+    if (!expression) {
+      throw ConfigurationErrors.conditionGenerationFailed(condition);
+    }
+    const transactionItem = {
+      type: "ConditionCheck",
+      params: {
+        tableName,
+        key: keyCondition,
+        conditionExpression: expression,
+        expressionAttributeNames: names,
+        expressionAttributeValues: values
+      }
+    };
+    this.items.push(transactionItem);
+    return this;
+  }
+  /**
+   * Adds a pre-configured condition check operation to the transaction.
+   *
+   * This method is particularly useful when working with ConditionCheckBuilder
+   * to maintain consistency in condition checks across your application.
+   *
+   * @example
+   * ```typescript
+   * // Create a condition check with ConditionCheckBuilder
+   * const checkCommand = new ConditionCheckBuilder('inventory', { pk: 'PROD#ABC' })
+   *   .condition(op => op.and([
+   *     op.between('quantity', 10, 100),
+   *     op.beginsWith('category', 'ELECTRONICS'),
+   *     op.attributeExists('lastAuditDate')
+   *   ]))
+   *   .toDynamoCommand();
+   *
+   * // Add the command to the transaction
+   * transaction.conditionCheckWithCommand(checkCommand);
+   * ```
+   *
+   * @param command - The complete condition check command configuration
+   * @returns The transaction builder for method chaining
+   * @throws {Error} If a duplicate item is detected in the transaction
+   * @see ConditionCheckBuilder for creating condition check commands
+   */
+  conditionCheckWithCommand(command) {
+    let keyForDuplicateCheck;
+    let keyForTransaction;
+    if (typeof command.key === "object" && command.key !== null && "pk" in command.key) {
+      keyForTransaction = this.createKeyForPrimaryIndex(command.key);
+      keyForDuplicateCheck = keyForTransaction;
+    } else {
+      keyForTransaction = command.key;
+      keyForDuplicateCheck = command.key;
+    }
+    this.checkForDuplicateItem(command.tableName, keyForDuplicateCheck);
+    const transactionItem = {
+      type: "ConditionCheck",
+      params: {
+        ...command,
+        key: keyForTransaction
+      }
+    };
+    this.items.push(transactionItem);
+    return this;
+  }
+  /**
+   * Sets options for the transaction execution.
+   *
+   * @example
+   * ```typescript
+   * // Enable idempotency and capacity tracking
+   * transaction.withOptions({
+   *   clientRequestToken: 'unique-request-id-123',
+   *   returnConsumedCapacity: 'TOTAL'
+   * });
+   *
+   * // Track item collection metrics
+   * transaction.withOptions({
+   *   returnItemCollectionMetrics: 'SIZE'
+   * });
+   * ```
+   *
+   * Note: ClientRequestToken can be used to make transactions idempotent,
+   * ensuring the same transaction is not executed multiple times.
+   *
+   * @param options - Configuration options for the transaction
+   * @returns The transaction builder for method chaining
+   */
+  withOptions(options) {
+    this.options = { ...this.options, ...options };
+    return this;
+  }
+  /**
+   * Gets a human-readable representation of the transaction items.
+   *
+   * The method resolves all expression placeholders with their actual values,
+   * making it easier to understand the transaction's operations.
+   *
+   * @example
+   * ```typescript
+   * // Add multiple operations
+   * transaction
+   *   .put('orders', { orderId: '123', status: 'PENDING' })
+   *   .update('inventory',
+   *     { productId: 'ABC' },
+   *     'SET quantity = quantity - :amount',
+   *     undefined,
+   *     { ':amount': 1 }
+   *   );
+   *
+   * // Debug the transaction
+   * const debugInfo = transaction.debug();
+   * console.log('Transaction operations:', debugInfo);
+   * ```
+   *
+   * @returns An array of readable representations of the transaction items
+   */
+  debug() {
+    return debugTransaction(this.items);
+  }
+  /**
+   * Executes all operations in the transaction atomically.
+   *
+   * The transaction will only succeed if all operations succeed.
+   * If any operation fails, the entire transaction is rolled back.
+   *
+   * @example
+   * ```typescript
+   * try {
+   *   // Build and execute transaction
+   *   await transaction
+   *     .put('orders', newOrder)
+   *     .update('inventory',
+   *       { productId: 'ABC' },
+   *       'SET quantity = quantity - :qty',
+   *       undefined,
+   *       { ':qty': 1 }
+   *     )
+   *     .conditionCheck('products',
+   *       { productId: 'ABC' },
+   *       op => op.eq('status', 'ACTIVE')
+   *     )
+   *     .execute();
+   *
+   *   console.log('Transaction completed successfully');
+   * } catch (error) {
+   *   // Handle transaction failure
+   *   console.error('Transaction failed:', error);
+   * }
+   * ```
+   *
+   * @throws {Error} If no transaction items are specified
+   * @throws {Error} If any operation in the transaction fails
+   * @returns A promise that resolves when the transaction completes
+   */
+  async execute() {
+    if (this.items.length === 0) {
+      throw TransactionErrors.transactionEmpty();
+    }
+    const transactItems = this.items.map((item) => {
+      switch (item.type) {
+        case "Put":
+          return {
+            Put: {
+              TableName: item.params.tableName,
+              Item: item.params.item,
+              ConditionExpression: item.params.conditionExpression,
+              ExpressionAttributeNames: item.params.expressionAttributeNames,
+              ExpressionAttributeValues: item.params.expressionAttributeValues
+            }
+          };
+        case "Delete":
+          return {
+            Delete: {
+              TableName: item.params.tableName,
+              Key: item.params.key,
+              ConditionExpression: item.params.conditionExpression,
+              ExpressionAttributeNames: item.params.expressionAttributeNames,
+              ExpressionAttributeValues: item.params.expressionAttributeValues
+            }
+          };
+        case "Update":
+          return {
+            Update: {
+              TableName: item.params.tableName,
+              Key: item.params.key,
+              UpdateExpression: item.params.updateExpression,
+              ConditionExpression: item.params.conditionExpression,
+              ExpressionAttributeNames: item.params.expressionAttributeNames,
+              ExpressionAttributeValues: item.params.expressionAttributeValues
+            }
+          };
+        case "ConditionCheck":
+          return {
+            ConditionCheck: {
+              TableName: item.params.tableName,
+              Key: item.params.key,
+              ConditionExpression: item.params.conditionExpression,
+              ExpressionAttributeNames: item.params.expressionAttributeNames,
+              ExpressionAttributeValues: item.params.expressionAttributeValues
+            }
+          };
+        default: {
+          const exhaustiveCheck = item;
+          throw TransactionErrors.unsupportedType(exhaustiveCheck);
+        }
+      }
+    });
+    const params = {
+      TransactItems: transactItems,
+      ClientRequestToken: this.options.clientRequestToken,
+      ReturnConsumedCapacity: this.options.returnConsumedCapacity,
+      ReturnItemCollectionMetrics: this.options.returnItemCollectionMetrics
+    };
+    try {
+      await this.executor(params);
+    } catch (error) {
+      throw TransactionErrors.transactionFailed(this.items.length, {}, error instanceof Error ? error : void 0);
+    }
+  }
+};
+
+// src/builders/update-builder.ts
+var UpdateBuilder = class {
+  updates = [];
+  options = {
+    returnValues: "ALL_NEW"
+  };
+  executor;
+  tableName;
+  key;
+  constructor(executor, tableName, key) {
+    this.executor = executor;
+    this.tableName = tableName;
+    this.key = key;
+  }
+  set(valuesOrPath, value) {
+    if (typeof valuesOrPath === "object") {
+      for (const [key, value2] of Object.entries(valuesOrPath)) {
+        if (value2 === void 0) {
+          throw ValidationErrors.undefinedValue(key, this.tableName, this.key);
+        }
+        this.updates.push({
+          type: "SET",
+          path: key,
+          value: value2
+        });
+      }
+    } else {
+      if (value === void 0) {
+        throw ValidationErrors.undefinedValue(valuesOrPath, this.tableName, this.key);
+      }
+      this.updates.push({
+        type: "SET",
+        path: valuesOrPath,
+        value
+      });
+    }
+    return this;
+  }
+  /**
+   * Removes an attribute from the item.
+   *
+   * @example
+   * ```typescript
+   * // Remove simple attributes
+   * builder
+   *   .remove('temporaryTag')
+   *   .remove('previousLocation');
+   *
+   * // Remove nested attributes
+   * builder
+   *   .remove('metadata.testData')
+   *   .remove('stats.experimentalMetrics');
+   * ```
+   *
+   * @param path - The path to the attribute to remove
+   * @returns The builder instance for method chaining
+   */
+  remove(path) {
+    this.updates.push({
+      type: "REMOVE",
+      path
+    });
+    return this;
+  }
+  /**
+   * Adds a value to a number attribute or adds elements to a set.
+   *
+   * @example
+   * ```typescript
+   * // Increment counters
+   * builder
+   *   .add('escapeAttempts', 1)
+   *   .add('feedingCount', 1);
+   *
+   * // Add to sets
+   * builder
+   *   .add('knownBehaviors', new Set(['PACK_HUNTING', 'AMBUSH_TACTICS']))
+   *   .add('visitedZones', new Set(['ZONE_A', 'ZONE_B']));
+   * ```
+   *
+   * @param path - The path to the attribute to update
+   * @param value - The value to add (number or set)
+   * @returns The builder instance for method chaining
+   */
+  add(path, value) {
+    if (value === void 0) {
+      throw ValidationErrors.undefinedValue(path, this.tableName, this.key);
+    }
+    this.updates.push({
+      type: "ADD",
+      path,
+      value
+    });
+    return this;
+  }
+  /**
+   * Removes elements from a set attribute.
+   *
+   * @example
+   * ```typescript
+   * // Remove from sets using arrays
+   * builder.deleteElementsFromSet(
+   *   'allowedHabitats',
+   *   ['JUNGLE', 'COASTAL']
+   * );
+   *
+   * // Remove from sets using Set DynamoItems
+   * builder.deleteElementsFromSet(
+   *   'knownBehaviors',
+   *   new Set(['NOCTURNAL', 'TERRITORIAL'])
+   * );
+   *
+   * // Remove from nested sets
+   * builder.deleteElementsFromSet(
+   *   'stats.compatibleSpecies',
+   *   ['VELOCIRAPTOR', 'DILOPHOSAURUS']
+   * );
+   * ```
+   *
+   * @param path - The path to the set attribute
+   * @param value - Elements to remove (array or Set)
+   * @returns The builder instance for method chaining
+   */
+  deleteElementsFromSet(path, value) {
+    if (value === void 0) {
+      throw ValidationErrors.undefinedValue(path, this.tableName, this.key);
+    }
+    let valuesToDelete;
+    if (Array.isArray(value)) {
+      valuesToDelete = new Set(value);
+    } else {
+      valuesToDelete = value;
+    }
+    this.updates.push({
+      type: "DELETE",
+      path,
+      value: valuesToDelete
+    });
+    return this;
+  }
+  /**
+   * Adds a condition that must be satisfied for the update to succeed.
+   *
+   * @example
+   * ```typescript
+   * // Simple condition
+   * builder.condition(op =>
+   *   op.eq('status', 'ACTIVE')
+   * );
+   *
+   * // Health check condition
+   * builder.condition(op =>
+   *   op.and([
+   *     op.gt('health', 50),
+   *     op.eq('status', 'HUNTING')
+   *   ])
+   * );
+   *
+   * // Complex security condition
+   * builder.condition(op =>
+   *   op.and([
+   *     op.attributeExists('securitySystem'),
+   *     op.eq('containmentStatus', 'SECURE'),
+   *     op.lt('aggressionLevel', 8)
+   *   ])
+   * );
+   *
+   * // Version check (optimistic locking)
+   * builder.condition(op =>
+   *   op.eq('version', currentVersion)
+   * );
+   * ```
+   *
+   * @param condition - Either a Condition DynamoItem or a callback function that builds the condition
+   * @returns The builder instance for method chaining
+   */
+  condition(condition) {
+    if (typeof condition === "function") {
+      const conditionOperator = {
+        eq,
+        ne,
+        lt,
+        lte,
+        gt,
+        gte,
+        between,
+        inArray,
+        beginsWith,
+        contains,
+        attributeExists,
+        attributeNotExists,
+        and,
+        or,
+        not
+      };
+      this.options.condition = condition(conditionOperator);
+    } else {
+      this.options.condition = condition;
+    }
+    return this;
+  }
+  /**
+   * Sets which item attributes to include in the response.
+   *
+   * Available options:
+   * - 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
+   *
+   * @example
+   * ```typescript
+   * // Get complete updated dinosaur
+   * const result = await builder
+   *   .set('status', 'SLEEPING')
+   *   .returnValues('ALL_NEW')
+   *   .execute();
+   *
+   * // Track specific attribute changes
+   * const result = await builder
+   *   .set({
+   *     'stats.health': 100,
+   *     'stats.energy': 95
+   *   })
+   *   .returnValues('UPDATED_OLD')
+   *   .execute();
+   *
+   * if (result.item) {
+   *   console.log('Previous health:', result.item.stats?.health);
+   * }
+   * ```
+   *
+   * @param returnValues - Which attributes to return in the response
+   * @returns The builder instance for method chaining
+   */
+  returnValues(returnValues) {
+    this.options.returnValues = returnValues;
+    return this;
+  }
+  /**
+   * Generate the DynamoDB command parameters
+   */
+  toDynamoCommand() {
+    if (this.updates.length === 0) {
+      throw ValidationErrors.noUpdateActions(this.tableName, this.key);
+    }
+    const expressionParams = {
+      expressionAttributeNames: {},
+      expressionAttributeValues: {},
+      valueCounter: { count: 0 }
+    };
+    let updateExpression = "";
+    const setUpdates = [];
+    const removeUpdates = [];
+    const addUpdates = [];
+    const deleteUpdates = [];
+    for (const update of this.updates) {
+      switch (update.type) {
+        case "SET":
+          setUpdates.push(update);
+          break;
+        case "REMOVE":
+          removeUpdates.push(update);
+          break;
+        case "ADD":
+          addUpdates.push(update);
+          break;
+        case "DELETE":
+          deleteUpdates.push(update);
+          break;
+      }
+    }
+    if (setUpdates.length > 0) {
+      updateExpression += "SET ";
+      updateExpression += setUpdates.map((update) => {
+        const attrName = generateAttributeName(expressionParams, update.path);
+        const valueName = generateValueName(expressionParams, update.value);
+        expressionParams.expressionAttributeValues[valueName] = update.value;
+        return `${attrName} = ${valueName}`;
+      }).join(", ");
+    }
+    if (removeUpdates.length > 0) {
+      if (updateExpression) {
+        updateExpression += " ";
+      }
+      updateExpression += "REMOVE ";
+      updateExpression += removeUpdates.map((update) => {
+        return generateAttributeName(expressionParams, update.path);
+      }).join(", ");
+    }
+    if (addUpdates.length > 0) {
+      if (updateExpression) {
+        updateExpression += " ";
+      }
+      updateExpression += "ADD ";
+      updateExpression += addUpdates.map((update) => {
+        const attrName = generateAttributeName(expressionParams, update.path);
+        const valueName = generateValueName(expressionParams, update.value);
+        return `${attrName} ${valueName}`;
+      }).join(", ");
+    }
+    if (deleteUpdates.length > 0) {
+      if (updateExpression) {
+        updateExpression += " ";
+      }
+      updateExpression += "DELETE ";
+      updateExpression += deleteUpdates.map((update) => {
+        const attrName = generateAttributeName(expressionParams, update.path);
+        const valueName = generateValueName(expressionParams, update.value);
+        return `${attrName} ${valueName}`;
+      }).join(", ");
+    }
+    let conditionExpression;
+    if (this.options.condition) {
+      conditionExpression = buildExpression(this.options.condition, expressionParams);
+    }
+    const { expressionAttributeNames, expressionAttributeValues } = expressionParams;
+    return {
+      tableName: this.tableName,
+      key: this.key,
+      updateExpression,
+      conditionExpression,
+      expressionAttributeNames: Object.keys(expressionAttributeNames).length > 0 ? expressionAttributeNames : void 0,
+      expressionAttributeValues: Object.keys(expressionAttributeValues).length > 0 ? expressionAttributeValues : void 0,
+      returnValues: this.options.returnValues
+    };
+  }
+  /**
+   * Adds this update operation to a transaction.
+   *
+   * @example
+   * ```typescript
+   * const transaction = new TransactionBuilder(executor);
+   *
+   * // Update dinosaur status and habitat occupancy atomically
+   * new UpdateBuilder(executor, 'dinosaurs', { id: 'TREX-001' })
+   *   .set('location', 'PADDOCK_A')
+   *   .set('status', 'CONTAINED')
+   *   .withTransaction(transaction);
+   *
+   * new UpdateBuilder(executor, 'habitats', { id: 'PADDOCK-A' })
+   *   .add('occupants', 1)
+   *   .set('lastOccupied', new Date().toISOString())
+   *   .withTransaction(transaction);
+   *
+   * // Execute all operations atomically
+   * await transaction.execute();
+   * ```
+   *
+   * @param transaction - The transaction builder to add this operation to
+   * @returns The builder instance for method chaining
+   */
+  withTransaction(transaction) {
+    const command = this.toDynamoCommand();
+    transaction.updateWithCommand(command);
+  }
+  /**
+   * Gets a human-readable representation of the update command.
+   *
+   * @example
+   * ```typescript
+   * // Create complex update
+   * const builder = new UpdateBuilder(executor, 'dinosaurs', { id: 'RAPTOR-001' })
+   *   .set({
+   *     status: 'HUNTING',
+   *     'stats.health': 95,
+   *     'behavior.lastObserved': new Date().toISOString()
+   *   })
+   *   .add('huntingSuccesses', 1)
+   *   .condition(op => op.gt('health', 50));
+   *
+   * // Debug the update
+   * const debugInfo = builder.debug();
+   * console.log('Update operation:', debugInfo);
+   * ```
+   *
+   * @returns A readable representation of the update command with resolved expressions
+   */
+  debug() {
+    const command = this.toDynamoCommand();
+    return debugCommand(command);
+  }
+  /**
+   * Executes the update operation against DynamoDB.
+   *
+   * @example
+   * ```typescript
+   * try {
+   *   // Update dinosaur status with conditions
+   *   const result = await new UpdateBuilder(executor, 'dinosaurs', { id: 'TREX-001' })
+   *     .set({
+   *       status: 'FEEDING',
+   *       lastMeal: new Date().toISOString(),
+   *       'stats.hunger': 0
+   *     })
+   *     .add('feedingCount', 1)
+   *     .condition(op =>
+   *       op.and([
+   *         op.gt('stats.hunger', 80),
+   *         op.eq('status', 'HUNTING')
+   *       ])
+   *     )
+   *     .returnValues('ALL_NEW')
+   *     .execute();
+   *
+   *   if (result.item) {
+   *     console.log('Updated dinosaur:', result.item);
+   *   }
+   * } catch (error) {
+   *   // Handle condition check failure
+   *   console.error('Failed to update dinosaur:', error);
+   *   // Check if dinosaur wasn't hungry enough
+   *   if (error.name === 'ConditionalCheckFailedException') {
+   *     console.log('Dinosaur not ready for feeding');
+   *   }
+   * }
+   * ```
+   *
+   * @returns A promise that resolves to an DynamoItem containing the updated item (if returnValues is set)
+   * @throws {ConditionalCheckFailedException} If the condition check fails
+   * @throws {Error} If the update operation fails for other reasons
+   */
+  async execute() {
+    const params = this.toDynamoCommand();
+    return this.executor(params);
+  }
+};
+
+export { BatchBuilder, ConditionCheckBuilder, DeleteBuilder, FilterBuilder, GetBuilder, Paginator, PutBuilder, QueryBuilder, ResultIterator, ScanBuilder, TransactionBuilder, UpdateBuilder };