dyno-table 2.2.1 → 2.3.0

package/dist/index.js

@@ -1,4442 +1,5 @@
-// src/builders/batch-builder.ts
-var BatchError = class extends Error {
-  operation;
-  cause;
-  constructor(message, operation, cause) {
-    super(message);
-    this.name = "BatchError";
-    this.operation = operation;
-    this.cause = cause;
-  }
-};
-var BatchBuilder = class {
-  constructor(batchWriteExecutor, batchGetExecutor, config) {
-    this.batchWriteExecutor = batchWriteExecutor;
-    this.batchGetExecutor = batchGetExecutor;
-    this.config = config;
-  }
-  writeItems = [];
-  getItems = [];
-  /**
-   * Checks if the batch is empty (contains no operations)
-   *
-   * @returns true if the batch contains no operations
-   */
-  isEmpty() {
-    return this.writeItems.length === 0 && this.getItems.length === 0;
-  }
-  /**
-   * Gets the count of operations in the batch
-   *
-   * @returns Object containing the count of write and read operations
-   */
-  getOperationCount() {
-    return {
-      writes: this.writeItems.length,
-      reads: this.getItems.length
-    };
-  }
-  /**
-   * Validates that the batch is not empty before execution
-   *
-   * @throws {BatchError} If the batch is empty
-   */
-  validateNotEmpty() {
-    if (this.isEmpty()) {
-      throw new BatchError(
-        "Cannot execute empty batch. Add operations using entity builders with .withBatch()",
-        "write"
-      );
-    }
-  }
-  /**
-   * Adds a put operation to the batch with entity type information.
-   * This method is used internally by entity builders.
-   *
-   * @param command - The complete put command configuration
-   * @param entityType - The entity type name for type tracking
-   * @returns The batch builder for method chaining
-   * @internal
-   */
-  putWithCommand(command, entityType) {
-    const batchItem = {
-      type: "Put",
-      params: command,
-      entityType
-    };
-    this.writeItems.push(batchItem);
-    return this;
-  }
-  /**
-   * Adds a delete operation to the batch with entity type information.
-   * This method is used internally by entity builders.
-   *
-   * @param command - The complete delete command configuration
-   * @param entityType - The entity type name for type tracking
-   * @returns The batch builder for method chaining
-   * @internal
-   */
-  deleteWithCommand(command, entityType) {
-    const batchItem = {
-      type: "Delete",
-      params: command,
-      entityType
-    };
-    this.writeItems.push(batchItem);
-    return this;
-  }
-  /**
-   * Adds a get operation to the batch with entity type information.
-   * This method is used internally by entity builders.
-   *
-   * @param command - The complete get command configuration
-   * @param entityType - The entity type name for type tracking
-   * @returns The batch builder for method chaining
-   * @internal
-   */
-  getWithCommand(command, entityType) {
-    const batchItem = {
-      type: "Get",
-      params: command,
-      entityType
-    };
-    this.getItems.push(batchItem);
-    return this;
-  }
-  /**
-   * Executes all write operations in the batch.
-   *
-   * @returns A promise that resolves to any unprocessed operations
-   * @private
-   */
-  async executeWrites() {
-    if (this.writeItems.length === 0) {
-      return { unprocessedItems: [] };
-    }
-    try {
-      const operations = this.writeItems.map((item) => {
-        if (item.type === "Put") {
-          return {
-            type: "put",
-            item: item.params.item
-          };
-        }
-        if (item.type === "Delete") {
-          let key;
-          if (typeof item.params.key === "object" && item.params.key !== null && "pk" in item.params.key) {
-            key = item.params.key;
-          } else {
-            const tableKey = item.params.key;
-            key = {
-              pk: tableKey[this.config.partitionKey],
-              sk: this.config.sortKey ? tableKey[this.config.sortKey] : void 0
-            };
-          }
-          return {
-            type: "delete",
-            key
-          };
-        }
-        throw new BatchError(`Unsupported batch item type for write operation: ${item.type}`, "write");
-      });
-      return await this.batchWriteExecutor(operations);
-    } catch (error) {
-      throw new BatchError(
-        `Failed to execute batch write operations: ${error instanceof Error ? error.message : "Unknown error"}`,
-        "write",
-        error instanceof Error ? error : void 0
-      );
-    }
-  }
-  /**
-   * Executes all get operations in the batch.
-   *
-   * @returns A promise that resolves to the retrieved items
-   * @private
-   */
-  async executeGets() {
-    if (this.getItems.length === 0) {
-      return { items: [], unprocessedKeys: [] };
-    }
-    try {
-      const keys = this.getItems.map((item) => {
-        if (item.type === "Get") {
-          if (typeof item.params.key === "object" && item.params.key !== null && "pk" in item.params.key) {
-            return item.params.key;
-          }
-          const tableKey = item.params.key;
-          return {
-            pk: tableKey[this.config.partitionKey],
-            sk: this.config.sortKey ? tableKey[this.config.sortKey] : void 0
-          };
-        }
-        throw new BatchError(`Unsupported batch item type for get operation: ${item.type}`, "read");
-      });
-      return await this.batchGetExecutor(keys);
-    } catch (error) {
-      throw new BatchError(
-        `Failed to execute batch get operations: ${error instanceof Error ? error.message : "Unknown error"}`,
-        "read",
-        error instanceof Error ? error : void 0
-      );
-    }
-  }
-  /**
-   * Groups retrieved items by their entity type.
-   * @private
-   */
-  groupItemsByType(items) {
-    const grouped = {};
-    for (const item of this.getItems) {
-      if (item.entityType) {
-        const entityType = item.entityType;
-        if (!grouped[entityType]) {
-          grouped[entityType] = [];
-        }
-      }
-    }
-    for (const item of items) {
-      const entityType = item.entityType;
-      if (entityType && grouped[entityType]) {
-        grouped[entityType].push(item);
-      }
-    }
-    return grouped;
-  }
-  /**
-   * Executes all operations in the batch with typed results.
-   * Performs write operations first, then get operations.
-   *
-   * @returns A promise that resolves to a TypedBatchResult with entity type information
-   * @throws {BatchError} If the batch is empty or if operations fail
-   */
-  async execute() {
-    this.validateNotEmpty();
-    const errors = [];
-    let writeResults = { unprocessedItems: [] };
-    let getResults = {
-      items: [],
-      unprocessedKeys: []
-    };
-    if (this.writeItems.length > 0) {
-      try {
-        writeResults = await this.executeWrites();
-      } catch (error) {
-        if (error instanceof BatchError) {
-          errors.push(error);
-        } else {
-          errors.push(
-            new BatchError(
-              "Unexpected error during write operations",
-              "write",
-              error instanceof Error ? error : void 0
-            )
-          );
-        }
-      }
-    }
-    if (this.getItems.length > 0) {
-      try {
-        getResults = await this.executeGets();
-      } catch (error) {
-        if (error instanceof BatchError) {
-          errors.push(error);
-        } else {
-          errors.push(
-            new BatchError(
-              "Unexpected error during read operations",
-              "read",
-              error instanceof Error ? error : void 0
-            )
-          );
-        }
-      }
-    }
-    if (errors.length > 0 && (writeResults.unprocessedItems.length === this.writeItems.length || getResults.unprocessedKeys.length === this.getItems.length)) {
-      throw errors[0];
-    }
-    const totalOperations = this.writeItems.length + this.getItems.length;
-    const success = errors.length === 0 && writeResults.unprocessedItems.length === 0 && getResults.unprocessedKeys.length === 0;
-    return {
-      success,
-      writes: {
-        processed: this.writeItems.length - writeResults.unprocessedItems.length,
-        unprocessed: writeResults.unprocessedItems
-      },
-      reads: {
-        itemsByType: this.groupItemsByType(getResults.items),
-        items: getResults.items,
-        found: getResults.items.length,
-        unprocessed: getResults.unprocessedKeys
-      },
-      totalOperations,
-      errors: errors.length > 0 ? errors : void 0
-    };
-  }
-};
-
-// src/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 new Error(`Attribute is required for ${condition.type} condition`);
-  }
-  if (requiresValue && condition.value === void 0) {
-    throw new Error(`Value is required for ${condition.type} condition`);
-  }
-};
-var buildComparisonExpression = (condition, operator, params) => {
-  validateCondition(condition);
-  if (!condition.attr) {
-    throw new Error(`Attribute is required for ${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 new Error(`Attribute is required for ${condition.type} condition`);
-  }
-  if (!Array.isArray(condition.value) || condition.value.length !== 2) {
-    throw new Error("Between condition requires an array of two values");
-  }
-  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 new Error(`Attribute is required for ${condition.type} condition`);
-  }
-  if (!Array.isArray(condition.value) || condition.value.length === 0) {
-    throw new Error("In condition requires a non-empty array of values");
-  }
-  if (condition.value.length > 100) {
-    throw new Error("In condition supports a maximum of 100 values");
-  }
-  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 new Error(`Attribute is required for ${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 new Error(`Attribute is required for ${condition.type} condition`);
-  }
-  const attrName = generateAttributeName(params, condition.attr);
-  return `${functionName}(${attrName})`;
-};
-var buildLogicalExpression = (operator, conditions, params) => {
-  if (!conditions || conditions.length === 0) {
-    throw new Error(`At least one condition is required for ${operator} expression`);
-  }
-  const expressions = conditions.map((c) => buildExpression(c, params));
-  return `(${expressions.join(` ${operator} `)})`;
-};
-var buildExpression = (condition, params) => {
-  if (!condition) return "";
-  try {
-    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 new Error("Conditions array is required for AND operator");
-        }
-        return buildLogicalExpression("AND", condition.conditions, params);
-      },
-      or: () => {
-        if (!condition.conditions) {
-          throw new Error("Conditions array is required for OR operator");
-        }
-        return buildLogicalExpression("OR", condition.conditions, params);
-      },
-      not: () => {
-        if (!condition.condition) {
-          throw new Error("Condition is required for NOT operator");
-        }
-        return `NOT (${buildExpression(condition.condition, params)})`;
-      }
-    };
-    const builder = expressionBuilders[condition.type];
-    if (!builder) {
-      throw new Error(`Unknown condition type: ${condition.type}`);
-    }
-    return builder();
-  } catch (error) {
-    if (error instanceof Error) {
-      console.error(`Error building expression for condition type ${condition.type}:`, error.message);
-    } else {
-      console.error(`Error building expression for condition type ${condition.type}:`, error);
-    }
-    throw error;
-  }
-};
-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/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/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/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;
-  }
-};
-
-// 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;
-  constructor(executor, keyCondition) {
-    super();
-    this.executor = executor;
-    this.keyCondition = keyCondition;
-  }
-  /**
-   * 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;
-  }
-  /**
-   * 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);
-    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 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 = () => this.executor(this.keyCondition, 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 new Error(`Primary key value for '${pkName}' is missing`);
-    }
-    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 new Error(
-        `Duplicate item detected in transaction: Table=${tableName}, ${pkName}=${String(pkValue)}, ${skName}=${skValue !== void 0 ? String(skValue) : "undefined"}. DynamoDB transactions do not allow multiple operations on the same item.`
-      );
-    }
-  }
-  createKeyForPrimaryIndex(key) {
-    const keyCondition = {
-      [this.indexConfig.partitionKey]: key.pk
-    };
-    if (this.indexConfig.sortKey) {
-      if (key.sk === void 0) {
-        throw new Error("Sort key is required for delete operation");
-      }
-      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 new Error("Failed to generate condition expression");
-    }
-    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 new Error("No transaction items specified");
-    }
-    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 new Error(`Unsupported transaction item type: ${String(exhaustiveCheck)}`);
-        }
-      }
-    });
-    const params = {
-      TransactItems: transactItems,
-      ClientRequestToken: this.options.clientRequestToken,
-      ReturnConsumedCapacity: this.options.returnConsumedCapacity,
-      ReturnItemCollectionMetrics: this.options.returnItemCollectionMetrics
-    };
-    try {
-      await this.executor(params);
-    } catch (error) {
-      console.log(this.debug());
-      console.error("Error executing transaction:", error);
-      throw error;
-    }
-  }
-};
-
-// 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)) {
-        this.updates.push({
-          type: "SET",
-          path: key,
-          value: value2
-        });
-      }
-    } else {
-      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) {
-    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) {
-    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 new Error("No update actions specified");
-    }
-    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);
-  }
-};
-
-// src/builders/entity-aware-builders.ts
-function createEntityAwareBuilder(builder, entityName) {
-  return new Proxy(builder, {
-    get(target, prop, receiver) {
-      if (prop === "entityName") {
-        return entityName;
-      }
-      if (prop === "withBatch" && typeof target[prop] === "function") {
-        return (batch, entityType) => {
-          const typeToUse = entityType ?? entityName;
-          const fn = target[prop];
-          return fn.call(target, batch, typeToUse);
-        };
-      }
-      return Reflect.get(target, prop, receiver);
-    }
-  });
-}
-function createEntityAwarePutBuilder(builder, entityName) {
-  return createEntityAwareBuilder(builder, entityName);
-}
-function createEntityAwareGetBuilder(builder, entityName) {
-  return createEntityAwareBuilder(builder, entityName);
-}
-function createEntityAwareDeleteBuilder(builder, entityName) {
-  return createEntityAwareBuilder(builder, entityName);
-}
-var EntityAwareUpdateBuilder = class {
-  forceRebuildIndexes = [];
-  entityName;
-  builder;
-  entityConfig;
-  updateDataApplied = false;
-  constructor(builder, entityName) {
-    this.builder = builder;
-    this.entityName = entityName;
-  }
-  /**
-   * Configure entity-specific logic for automatic timestamp generation and index updates
-   */
-  configureEntityLogic(config) {
-    this.entityConfig = config;
-  }
-  /**
-   * Forces a rebuild of one or more readonly indexes during the update operation.
-   *
-   * By default, readonly indexes are not updated during entity updates to prevent
-   * errors when required index attributes are missing. This method allows you to
-   * override that behavior and force specific indexes to be rebuilt.
-   *
-   * @example
-   * ```typescript
-   * // Force rebuild a single readonly index
-   * const result = await repo.update({ id: 'TREX-001' }, { status: 'ACTIVE' })
-   *   .forceIndexRebuild('gsi1')
-   *   .execute();
-   *
-   * // Force rebuild multiple readonly indexes
-   * const result = await repo.update({ id: 'TREX-001' }, { status: 'ACTIVE' })
-   *   .forceIndexRebuild(['gsi1', 'gsi2'])
-   *   .execute();
-   *
-   * // Chain with other update operations
-   * const result = await repo.update({ id: 'TREX-001' }, { status: 'ACTIVE' })
-   *   .set('lastUpdated', new Date().toISOString())
-   *   .forceIndexRebuild('gsi1')
-   *   .condition(op => op.eq('status', 'INACTIVE'))
-   *   .execute();
-   * ```
-   *
-   * @param indexes - A single index name or array of index names to force rebuild
-   * @returns The builder instance for method chaining
-   */
-  forceIndexRebuild(indexes) {
-    if (Array.isArray(indexes)) {
-      this.forceRebuildIndexes = [...this.forceRebuildIndexes, ...indexes];
-    } else {
-      this.forceRebuildIndexes.push(indexes);
-    }
-    return this;
-  }
-  /**
-   * Gets the list of indexes that should be force rebuilt.
-   * This is used internally by entity update logic.
-   *
-   * @returns Array of index names to force rebuild
-   */
-  getForceRebuildIndexes() {
-    return [...this.forceRebuildIndexes];
-  }
-  /**
-   * Apply entity-specific update data (timestamps and index updates)
-   * This is called automatically when needed
-   */
-  applyEntityUpdates() {
-    if (!this.entityConfig || this.updateDataApplied) return;
-    const timestamps = this.entityConfig.generateTimestamps();
-    const updatedItem = { ...this.entityConfig.key, ...this.entityConfig.data, ...timestamps };
-    const indexUpdates = this.entityConfig.buildIndexUpdates(
-      this.entityConfig.key,
-      updatedItem,
-      this.entityConfig.table,
-      this.entityConfig.indexes,
-      this.forceRebuildIndexes
-    );
-    this.builder.set({ ...this.entityConfig.data, ...timestamps, ...indexUpdates });
-    this.updateDataApplied = true;
-  }
-  set(valuesOrPath, value) {
-    if (typeof valuesOrPath === "object") {
-      this.builder.set(valuesOrPath);
-    } else {
-      if (value === void 0) {
-        throw new Error("Value is required when setting a single path");
-      }
-      this.builder.set(valuesOrPath, value);
-    }
-    return this;
-  }
-  remove(path) {
-    this.builder.remove(path);
-    return this;
-  }
-  add(path, value) {
-    this.builder.add(path, value);
-    return this;
-  }
-  deleteElementsFromSet(path, value) {
-    this.builder.deleteElementsFromSet(path, value);
-    return this;
-  }
-  condition(condition) {
-    this.builder.condition(condition);
-    return this;
-  }
-  returnValues(returnValues) {
-    this.builder.returnValues(returnValues);
-    return this;
-  }
-  toDynamoCommand() {
-    return this.builder.toDynamoCommand();
-  }
-  withTransaction(transaction) {
-    this.applyEntityUpdates();
-    this.builder.withTransaction(transaction);
-  }
-  debug() {
-    return this.builder.debug();
-  }
-  async execute() {
-    this.updateDataApplied = false;
-    this.applyEntityUpdates();
-    return this.builder.execute();
-  }
-};
-function createEntityAwareUpdateBuilder(builder, entityName) {
-  return new EntityAwareUpdateBuilder(builder, entityName);
-}
-
-// src/entity/ddb-indexing.ts
-var IndexBuilder = class {
-  /**
-   * Creates a new IndexBuilder instance
-   *
-   * @param table - The DynamoDB table instance
-   * @param indexes - The index definitions
-   */
-  constructor(table, indexes = {}) {
-    this.table = table;
-    this.indexes = indexes;
-  }
-  /**
-   * Build index attributes for item creation
-   *
-   * @param item - The item to generate indexes for
-   * @param options - Options for building indexes
-   * @returns Record of GSI attribute names to their values
-   */
-  buildForCreate(item, options = {}) {
-    const attributes = {};
-    for (const [indexName, indexDef] of Object.entries(this.indexes)) {
-      if (options.excludeReadOnly && indexDef.isReadOnly) {
-        continue;
-      }
-      const key = indexDef.generateKey(item);
-      const gsiConfig = this.table.gsis[indexName];
-      if (!gsiConfig) {
-        throw new Error(`GSI configuration not found for index: ${indexName}`);
-      }
-      if (key.pk) {
-        attributes[gsiConfig.partitionKey] = key.pk;
-      }
-      if (key.sk && gsiConfig.sortKey) {
-        attributes[gsiConfig.sortKey] = key.sk;
-      }
-    }
-    return attributes;
-  }
-  /**
-   * Build index attributes for item updates
-   *
-   * @param currentData - The current data before update
-   * @param updates - The update data
-   * @param options - Options for building indexes
-   * @returns Record of GSI attribute names to their updated values
-   */
-  buildForUpdate(currentData, updates, options = {}) {
-    const attributes = {};
-    const updatedItem = { ...currentData, ...updates };
-    if (options.forceRebuildIndexes && options.forceRebuildIndexes.length > 0) {
-      const invalidIndexes = options.forceRebuildIndexes.filter((indexName) => !this.indexes[indexName]);
-      if (invalidIndexes.length > 0) {
-        throw new Error(
-          `Cannot force rebuild unknown indexes: ${invalidIndexes.join(", ")}. Available indexes: ${Object.keys(this.indexes).join(", ")}`
-        );
-      }
-    }
-    for (const [indexName, indexDef] of Object.entries(this.indexes)) {
-      const isForced = options.forceRebuildIndexes?.includes(indexName);
-      if (indexDef.isReadOnly && !isForced) {
-        continue;
-      }
-      if (!isForced) {
-        let shouldUpdateIndex = false;
-        try {
-          const currentKey = indexDef.generateKey(currentData);
-          const updatedKey = indexDef.generateKey(updatedItem);
-          if (currentKey.pk !== updatedKey.pk || currentKey.sk !== updatedKey.sk) {
-            shouldUpdateIndex = true;
-          }
-        } catch {
-          shouldUpdateIndex = true;
-        }
-        if (!shouldUpdateIndex) {
-          continue;
-        }
-      }
-      let key;
-      try {
-        key = indexDef.generateKey(updatedItem);
-      } catch (error) {
-        if (error instanceof Error) {
-          throw new Error(`Missing attributes: ${error.message}`);
-        }
-        throw error;
-      }
-      if (this.hasUndefinedValues(key)) {
-        throw new Error(
-          `Missing attributes: Cannot update entity: insufficient data to regenerate index "${indexName}". All attributes required by the index must be provided in the update operation, or the index must be marked as readOnly.`
-        );
-      }
-      const gsiConfig = this.table.gsis[indexName];
-      if (!gsiConfig) {
-        throw new Error(`GSI configuration not found for index: ${indexName}`);
-      }
-      if (key.pk) {
-        attributes[gsiConfig.partitionKey] = key.pk;
-      }
-      if (key.sk && gsiConfig.sortKey) {
-        attributes[gsiConfig.sortKey] = key.sk;
-      }
-    }
-    return attributes;
-  }
-  /**
-   * Check if a key has undefined values
-   *
-   * @param key - The index key to check
-   * @returns True if the key contains undefined values, false otherwise
-   */
-  hasUndefinedValues(key) {
-    return (key.pk?.includes("undefined") ?? false) || (key.sk?.includes("undefined") ?? false);
-  }
-};
-
-// src/entity/index-utils.ts
-function buildIndexes(dataForKeyGeneration, table, indexes, excludeReadOnly = false) {
-  if (!indexes) {
-    return {};
-  }
-  const indexBuilder = new IndexBuilder(table, indexes);
-  return indexBuilder.buildForCreate(dataForKeyGeneration, { excludeReadOnly });
-}
-function buildIndexUpdates(currentData, updates, table, indexes, forceRebuildIndexes) {
-  if (!indexes) {
-    return {};
-  }
-  const indexBuilder = new IndexBuilder(table, indexes);
-  return indexBuilder.buildForUpdate(currentData, updates, { forceRebuildIndexes });
-}
-
-// src/entity/entity.ts
-function defineEntity(config) {
-  const entityTypeAttributeName = config.settings?.entityTypeAttributeName ?? "entityType";
-  const buildIndexes2 = (dataForKeyGeneration, table, excludeReadOnly = false) => {
-    return buildIndexes(dataForKeyGeneration, table, config.indexes, excludeReadOnly);
-  };
-  const wrapMethodWithPreparation = (originalMethod, prepareFn, context) => {
-    const wrappedMethod = (...args) => {
-      prepareFn();
-      return originalMethod.call(context, ...args);
-    };
-    Object.setPrototypeOf(wrappedMethod, originalMethod);
-    const propertyNames = Object.getOwnPropertyNames(originalMethod);
-    for (let i = 0; i < propertyNames.length; i++) {
-      const prop = propertyNames[i];
-      if (prop !== "length" && prop !== "name" && prop !== "prototype") {
-        const descriptor = Object.getOwnPropertyDescriptor(originalMethod, prop);
-        if (descriptor && descriptor.writable !== false && !descriptor.get) {
-          wrappedMethod[prop] = originalMethod[prop];
-        }
-      }
-    }
-    return wrappedMethod;
-  };
-  const generateTimestamps = (timestampsToGenerate, data) => {
-    if (!config.settings?.timestamps) return {};
-    const timestamps = {};
-    const now = /* @__PURE__ */ new Date();
-    const unixTime = Math.floor(Date.now() / 1e3);
-    const { createdAt, updatedAt } = config.settings.timestamps;
-    if (createdAt && timestampsToGenerate.includes("createdAt") && !data.createdAt) {
-      const name = createdAt.attributeName ?? "createdAt";
-      timestamps[name] = createdAt.format === "UNIX" ? unixTime : now.toISOString();
-    }
-    if (updatedAt && timestampsToGenerate.includes("updatedAt") && !data.updatedAt) {
-      const name = updatedAt.attributeName ?? "updatedAt";
-      timestamps[name] = updatedAt.format === "UNIX" ? unixTime : now.toISOString();
-    }
-    return timestamps;
-  };
-  return {
-    name: config.name,
-    createRepository: (table) => {
-      const repository = {
-        create: (data) => {
-          const builder = table.create({});
-          const prepareValidatedItemAsync = async () => {
-            const validatedData = await config.schema["~standard"].validate(data);
-            if ("issues" in validatedData && validatedData.issues) {
-              throw new Error(`Validation failed: ${validatedData.issues.map((i) => i.message).join(", ")}`);
-            }
-            const dataForKeyGeneration = {
-              ...validatedData.value,
-              ...generateTimestamps(["createdAt", "updatedAt"], validatedData.value)
-            };
-            const primaryKey = config.primaryKey.generateKey(dataForKeyGeneration);
-            const indexes = buildIndexes(dataForKeyGeneration, table, config.indexes, false);
-            const validatedItem = {
-              ...dataForKeyGeneration,
-              [entityTypeAttributeName]: config.name,
-              [table.partitionKey]: primaryKey.pk,
-              ...table.sortKey ? { [table.sortKey]: primaryKey.sk } : {},
-              ...indexes
-            };
-            Object.assign(builder, { item: validatedItem });
-            return validatedItem;
-          };
-          const prepareValidatedItemSync = () => {
-            const validationResult = config.schema["~standard"].validate(data);
-            if (validationResult instanceof Promise) {
-              throw new Error(
-                "Async validation is not supported in withBatch or withTransaction. The schema must support synchronous validation for compatibility."
-              );
-            }
-            if ("issues" in validationResult && validationResult.issues) {
-              throw new Error(`Validation failed: ${validationResult.issues.map((i) => i.message).join(", ")}`);
-            }
-            const dataForKeyGeneration = {
-              ...validationResult.value,
-              ...generateTimestamps(["createdAt", "updatedAt"], validationResult.value)
-            };
-            const primaryKey = config.primaryKey.generateKey(dataForKeyGeneration);
-            const indexes = buildIndexes(dataForKeyGeneration, table, config.indexes, false);
-            const validatedItem = {
-              ...dataForKeyGeneration,
-              [entityTypeAttributeName]: config.name,
-              [table.partitionKey]: primaryKey.pk,
-              ...table.sortKey ? { [table.sortKey]: primaryKey.sk } : {},
-              ...indexes
-            };
-            Object.assign(builder, { item: validatedItem });
-            return validatedItem;
-          };
-          const originalExecute = builder.execute;
-          builder.execute = async () => {
-            await prepareValidatedItemAsync();
-            return await originalExecute.call(builder);
-          };
-          const originalWithTransaction = builder.withTransaction;
-          if (originalWithTransaction) {
-            builder.withTransaction = wrapMethodWithPreparation(
-              originalWithTransaction,
-              prepareValidatedItemSync,
-              builder
-            );
-          }
-          const originalWithBatch = builder.withBatch;
-          if (originalWithBatch) {
-            builder.withBatch = wrapMethodWithPreparation(originalWithBatch, prepareValidatedItemSync, builder);
-          }
-          return createEntityAwarePutBuilder(builder, config.name);
-        },
-        upsert: (data) => {
-          const builder = table.put({});
-          const prepareValidatedItemAsync = async () => {
-            const validatedData = await config.schema["~standard"].validate(data);
-            if ("issues" in validatedData && validatedData.issues) {
-              throw new Error(`Validation failed: ${validatedData.issues.map((i) => i.message).join(", ")}`);
-            }
-            const dataForKeyGeneration = {
-              ...validatedData.value,
-              ...generateTimestamps(["createdAt", "updatedAt"], validatedData.value)
-            };
-            const primaryKey = config.primaryKey.generateKey(dataForKeyGeneration);
-            const indexes = buildIndexes2(dataForKeyGeneration, table, false);
-            const validatedItem = {
-              [table.partitionKey]: primaryKey.pk,
-              ...table.sortKey ? { [table.sortKey]: primaryKey.sk } : {},
-              ...dataForKeyGeneration,
-              [entityTypeAttributeName]: config.name,
-              ...indexes
-            };
-            Object.assign(builder, { item: validatedItem });
-            return validatedItem;
-          };
-          const prepareValidatedItemSync = () => {
-            const validationResult = config.schema["~standard"].validate(data);
-            if (validationResult instanceof Promise) {
-              throw new Error(
-                "Async validation is not supported in withTransaction or withBatch. Use execute() instead."
-              );
-            }
-            if ("issues" in validationResult && validationResult.issues) {
-              throw new Error(`Validation failed: ${validationResult.issues.map((i) => i.message).join(", ")}`);
-            }
-            const dataForKeyGeneration = {
-              ...validationResult.value,
-              ...generateTimestamps(["createdAt", "updatedAt"], validationResult.value)
-            };
-            const primaryKey = config.primaryKey.generateKey(dataForKeyGeneration);
-            const indexes = buildIndexes(dataForKeyGeneration, table, config.indexes, false);
-            const validatedItem = {
-              [table.partitionKey]: primaryKey.pk,
-              ...table.sortKey ? { [table.sortKey]: primaryKey.sk } : {},
-              ...dataForKeyGeneration,
-              [entityTypeAttributeName]: config.name,
-              ...indexes
-            };
-            Object.assign(builder, { item: validatedItem });
-            return validatedItem;
-          };
-          const originalExecute = builder.execute;
-          builder.execute = async () => {
-            await prepareValidatedItemAsync();
-            const result = await originalExecute.call(builder);
-            if (!result) {
-              throw new Error("Failed to upsert item");
-            }
-            return result;
-          };
-          const originalWithTransaction = builder.withTransaction;
-          if (originalWithTransaction) {
-            builder.withTransaction = wrapMethodWithPreparation(
-              originalWithTransaction,
-              prepareValidatedItemSync,
-              builder
-            );
-          }
-          const originalWithBatch = builder.withBatch;
-          if (originalWithBatch) {
-            builder.withBatch = wrapMethodWithPreparation(originalWithBatch, prepareValidatedItemSync, builder);
-          }
-          return createEntityAwarePutBuilder(builder, config.name);
-        },
-        get: (key) => {
-          return createEntityAwareGetBuilder(table.get(config.primaryKey.generateKey(key)), config.name);
-        },
-        update: (key, data) => {
-          const primaryKeyObj = config.primaryKey.generateKey(key);
-          const builder = table.update(primaryKeyObj);
-          builder.condition(eq(entityTypeAttributeName, config.name));
-          const entityAwareBuilder = createEntityAwareUpdateBuilder(builder, config.name);
-          entityAwareBuilder.configureEntityLogic({
-            data,
-            key,
-            table,
-            indexes: config.indexes,
-            generateTimestamps: () => generateTimestamps(["updatedAt"], data),
-            buildIndexUpdates
-          });
-          return entityAwareBuilder;
-        },
-        delete: (key) => {
-          const builder = table.delete(config.primaryKey.generateKey(key));
-          builder.condition(eq(entityTypeAttributeName, config.name));
-          return createEntityAwareDeleteBuilder(builder, config.name);
-        },
-        query: Object.entries(config.queries || {}).reduce((acc, [key, inputCallback]) => {
-          acc[key] = (input) => {
-            const queryEntity = {
-              scan: repository.scan,
-              get: (key2) => createEntityAwareGetBuilder(table.get(key2), config.name),
-              query: (keyCondition) => {
-                return table.query(keyCondition);
-              }
-            };
-            const queryBuilderCallback = inputCallback(input);
-            const builder = queryBuilderCallback(queryEntity);
-            if (builder && typeof builder === "object" && "filter" in builder && typeof builder.filter === "function") {
-              builder.filter(eq(entityTypeAttributeName, config.name));
-            }
-            if (builder && typeof builder === "object" && "execute" in builder) {
-              const originalExecute = builder.execute;
-              builder.execute = async () => {
-                const queryFn = config.queries[key];
-                if (queryFn && typeof queryFn === "function") {
-                  const schema = queryFn.schema;
-                  if (schema?.["~standard"]?.validate && typeof schema["~standard"].validate === "function") {
-                    const validationResult = schema["~standard"].validate(input);
-                    if ("issues" in validationResult && validationResult.issues) {
-                      throw new Error(
-                        `Validation failed: ${validationResult.issues.map((issue) => issue.message).join(", ")}`
-                      );
-                    }
-                  }
-                }
-                const result = await originalExecute.call(builder);
-                if (!result) {
-                  throw new Error("Failed to execute query");
-                }
-                return result;
-              };
-            }
-            return builder;
-          };
-          return acc;
-        }, {}),
-        scan: () => {
-          const builder = table.scan();
-          builder.filter(eq(entityTypeAttributeName, config.name));
-          return builder;
-        }
-      };
-      return repository;
-    }
-  };
-}
-function createQueries() {
-  return {
-    input: (schema) => ({
-      query: (handler) => {
-        const queryFn = (input) => (entity) => handler({ input, entity });
-        queryFn.schema = schema;
-        return queryFn;
-      }
-    })
-  };
-}
-function createIndex() {
-  return {
-    input: (schema) => {
-      const createIndexBuilder = (isReadOnly = false) => ({
-        partitionKey: (pkFn) => ({
-          sortKey: (skFn) => {
-            const index = {
-              name: "custom",
-              partitionKey: "pk",
-              sortKey: "sk",
-              isReadOnly,
-              generateKey: (item) => {
-                const data = schema["~standard"].validate(item);
-                if ("issues" in data && data.issues) {
-                  throw new Error(`Index validation failed: ${data.issues.map((i) => i.message).join(", ")}`);
-                }
-                const validData = "value" in data ? data.value : item;
-                return { pk: pkFn(validData), sk: skFn(validData) };
-              }
-            };
-            return Object.assign(index, {
-              readOnly: (value = false) => ({
-                ...index,
-                isReadOnly: value
-              })
-            });
-          },
-          withoutSortKey: () => {
-            const index = {
-              name: "custom",
-              partitionKey: "pk",
-              isReadOnly,
-              generateKey: (item) => {
-                const data = schema["~standard"].validate(item);
-                if ("issues" in data && data.issues) {
-                  throw new Error(`Index validation failed: ${data.issues.map((i) => i.message).join(", ")}`);
-                }
-                const validData = "value" in data ? data.value : item;
-                return { pk: pkFn(validData) };
-              }
-            };
-            return Object.assign(index, {
-              readOnly: (value = true) => ({
-                ...index,
-                isReadOnly: value
-              })
-            });
-          }
-        }),
-        readOnly: (value = true) => createIndexBuilder(value)
-      });
-      return createIndexBuilder(false);
-    }
-  };
-}
-
-// 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 new Error("Condition is required for condition check operations");
-    }
-    const { expression, names, values } = prepareExpressionParams(this.conditionExpression);
-    if (!expression) {
-      throw new Error("Failed to generate condition expression");
-    }
-    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 new Error("Condition is required for condition check operations");
-    }
-    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/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) {
-    this.executor = executor;
-    this.params = {
-      tableName,
-      key
-    };
-  }
-  params;
-  options = {};
-  selectedFields = /* @__PURE__ */ new Set();
-  /**
-   * 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);
-      }
-    }
-    this.options.projection = Array.from(this.selectedFields);
-    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
-    };
-  }
-  /**
-   * 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();
-    return this.executor(command);
-  }
-};
-
-// 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/chunk-array.ts
-function* chunkArray(array, size) {
-  if (size <= 0) {
-    throw new Error("Chunk size must be greater than 0");
-  }
-  for (let i = 0; i < array.length; i += size) {
-    yield array.slice(i, i + size);
-  }
-}
-
-// src/table.ts
-var DDB_BATCH_WRITE_LIMIT = 25;
-var DDB_BATCH_GET_LIMIT = 100;
-var Table = class {
-  dynamoClient;
-  tableName;
-  /**
-   * The column name of the partitionKey for the Table
-   */
-  partitionKey;
-  /**
-   * The column name of the sortKey for the Table
-   */
-  sortKey;
-  /**
-   * The Global Secondary Indexes that are configured on this table
-   */
-  gsis;
-  constructor(config) {
-    this.dynamoClient = config.client;
-    this.tableName = config.tableName;
-    this.partitionKey = config.indexes.partitionKey;
-    this.sortKey = config.indexes.sortKey;
-    this.gsis = config.indexes.gsis || {};
-  }
-  createKeyForPrimaryIndex(keyCondition) {
-    const primaryCondition = { [this.partitionKey]: keyCondition.pk };
-    if (this.sortKey) {
-      if (!keyCondition.sk) {
-        throw new Error("Sort key has not been provided but the Table has a sort key");
-      }
-      primaryCondition[this.sortKey] = keyCondition.sk;
-    }
-    return primaryCondition;
-  }
-  /**
-   * Creates a new item in the table, it will fail if the item already exists.
-   *
-   * By default, this method returns the input values passed to the create operation
-   * upon successful creation.
-   *
-   * You can customise the return behaviour by chaining the `.returnValues()` method:
-   *
-   * @param item The item to create
-   * @returns A PutBuilder instance for chaining additional conditions and executing the create operation
-   *
-   * @example
-   * ```ts
-   * // Create with default behavior (returns input values)
-   * const result = await table.create({
-   *   id: 'user-123',
-   *   name: 'John Doe',
-   *   email: 'john@example.com'
-   * }).execute();
-   * console.log(result); // Returns the input object
-   *
-   * // Create with no return value for better performance
-   * await table.create(userData).returnValues('NONE').execute();
-   *
-   * // Create and get fresh data from dynamodb using a strongly consistent read
-   * const freshData = await table.create(userData).returnValues('CONSISTENT').execute();
-   *
-   * // Create and get previous values (if the item was overwritten)
-   * const oldData = await table.create(userData).returnValues('ALL_OLD').execute();
-   * ```
-   */
-  create(item) {
-    return this.put(item).condition((op) => op.attributeNotExists(this.partitionKey)).returnValues("INPUT");
-  }
-  get(keyCondition) {
-    const executor = async (params) => {
-      try {
-        const result = await this.dynamoClient.get({
-          TableName: params.tableName,
-          Key: this.createKeyForPrimaryIndex(keyCondition),
-          ProjectionExpression: params.projectionExpression,
-          ExpressionAttributeNames: params.expressionAttributeNames,
-          ConsistentRead: params.consistentRead
-        });
-        return {
-          item: result.Item ? result.Item : void 0
-        };
-      } catch (error) {
-        console.error("Error getting item:", error);
-        throw error;
-      }
-    };
-    return new GetBuilder(executor, keyCondition, this.tableName);
-  }
-  /**
-   * Updates an item in the table
-   *
-   * @param item The item to update
-   * @returns A PutBuilder instance for chaining conditions and executing the put operation
-   */
-  put(item) {
-    const executor = async (params) => {
-      try {
-        const result = await this.dynamoClient.put({
-          TableName: params.tableName,
-          Item: params.item,
-          ConditionExpression: params.conditionExpression,
-          ExpressionAttributeNames: params.expressionAttributeNames,
-          ExpressionAttributeValues: params.expressionAttributeValues,
-          // CONSISTENT and INPUT are not valid ReturnValues for DDB, so we set NONE as we are not interested in its
-          // response and will be handling these cases separately
-          ReturnValues: params.returnValues === "CONSISTENT" || params.returnValues === "INPUT" ? "NONE" : params.returnValues
-        });
-        if (params.returnValues === "INPUT") {
-          return params.item;
-        }
-        if (params.returnValues === "CONSISTENT") {
-          const getResult = await this.dynamoClient.get({
-            TableName: params.tableName,
-            Key: this.createKeyForPrimaryIndex({
-              pk: params.item[this.partitionKey],
-              ...this.sortKey && { sk: params.item[this.sortKey] }
-            }),
-            ConsistentRead: true
-          });
-          return getResult.Item;
-        }
-        return result.Attributes;
-      } catch (error) {
-        console.error("Error creating item:", error);
-        throw error;
-      }
-    };
-    return new PutBuilder(executor, item, this.tableName);
-  }
-  /**
-   * Creates a query builder for complex queries
-   * If useIndex is called on the returned QueryBuilder, it will use the GSI configuration
-   */
-  query(keyCondition) {
-    const pkAttributeName = this.partitionKey;
-    const skAttributeName = this.sortKey;
-    let keyConditionExpression = eq(pkAttributeName, keyCondition.pk);
-    if (keyCondition.sk) {
-      if (!skAttributeName) {
-        throw new Error("Sort key is not defined for Index");
-      }
-      const keyConditionOperator = {
-        eq: (value) => eq(skAttributeName, value),
-        lt: (value) => lt(skAttributeName, value),
-        lte: (value) => lte(skAttributeName, value),
-        gt: (value) => gt(skAttributeName, value),
-        gte: (value) => gte(skAttributeName, value),
-        between: (lower, upper) => between(skAttributeName, lower, upper),
-        beginsWith: (value) => beginsWith(skAttributeName, value),
-        and: (...conditions) => and(...conditions)
-      };
-      const skCondition = keyCondition.sk(keyConditionOperator);
-      keyConditionExpression = and(eq(pkAttributeName, keyCondition.pk), skCondition);
-    }
-    const executor = async (originalKeyCondition, options) => {
-      let finalKeyCondition = originalKeyCondition;
-      if (options.indexName) {
-        const gsiName = String(options.indexName);
-        const gsi = this.gsis[gsiName];
-        if (!gsi) {
-          throw new Error(`GSI with name "${gsiName}" does not exist on table "${this.tableName}"`);
-        }
-        const gsiPkAttributeName = gsi.partitionKey;
-        const gsiSkAttributeName = gsi.sortKey;
-        let pkValue;
-        let skValue;
-        let extractedSkCondition;
-        if (originalKeyCondition.type === "eq") {
-          pkValue = originalKeyCondition.value;
-        } else if (originalKeyCondition.type === "and" && originalKeyCondition.conditions) {
-          const pkCondition = originalKeyCondition.conditions.find(
-            (c) => c.type === "eq" && c.attr === pkAttributeName
-          );
-          if (pkCondition && pkCondition.type === "eq") {
-            pkValue = pkCondition.value;
-          }
-          const skConditions = originalKeyCondition.conditions.filter((c) => c.attr === skAttributeName);
-          if (skConditions.length > 0) {
-            if (skConditions.length === 1) {
-              extractedSkCondition = skConditions[0];
-              if (extractedSkCondition && extractedSkCondition.type === "eq") {
-                skValue = extractedSkCondition.value;
-              }
-            } else if (skConditions.length > 1) {
-              extractedSkCondition = and(...skConditions);
-            }
-          }
-        }
-        if (!pkValue) {
-          throw new Error("Could not extract partition key value from key condition");
-        }
-        let gsiKeyCondition = eq(gsiPkAttributeName, pkValue);
-        if (skValue && gsiSkAttributeName) {
-          gsiKeyCondition = and(gsiKeyCondition, eq(gsiSkAttributeName, skValue));
-        } else if (extractedSkCondition && gsiSkAttributeName) {
-          if (extractedSkCondition.attr === skAttributeName) {
-            const updatedSkCondition = {
-              ...extractedSkCondition,
-              attr: gsiSkAttributeName
-            };
-            gsiKeyCondition = and(gsiKeyCondition, updatedSkCondition);
-          } else {
-            gsiKeyCondition = and(gsiKeyCondition, extractedSkCondition);
-          }
-        }
-        finalKeyCondition = gsiKeyCondition;
-      }
-      const expressionParams = {
-        expressionAttributeNames: {},
-        expressionAttributeValues: {},
-        valueCounter: { count: 0 }
-      };
-      const keyConditionExpression2 = buildExpression(finalKeyCondition, expressionParams);
-      let filterExpression;
-      if (options.filter) {
-        filterExpression = buildExpression(options.filter, expressionParams);
-      }
-      const projectionExpression = options.projection?.map((p) => generateAttributeName(expressionParams, p)).join(", ");
-      const { expressionAttributeNames, expressionAttributeValues } = expressionParams;
-      const { indexName, limit, consistentRead, scanIndexForward, lastEvaluatedKey } = options;
-      const params = {
-        TableName: this.tableName,
-        KeyConditionExpression: keyConditionExpression2,
-        FilterExpression: filterExpression,
-        ExpressionAttributeNames: expressionAttributeNames,
-        ExpressionAttributeValues: expressionAttributeValues,
-        IndexName: indexName,
-        Limit: limit,
-        ConsistentRead: consistentRead,
-        ScanIndexForward: scanIndexForward,
-        ProjectionExpression: projectionExpression,
-        ExclusiveStartKey: lastEvaluatedKey
-      };
-      try {
-        const result = await this.dynamoClient.query(params);
-        return {
-          items: result.Items,
-          lastEvaluatedKey: result.LastEvaluatedKey
-        };
-      } catch (error) {
-        console.log(debugCommand(params));
-        console.error("Error querying items:", error);
-        throw error;
-      }
-    };
-    return new QueryBuilder(executor, keyConditionExpression);
-  }
-  /**
-   * Creates a scan builder for scanning the entire table
-   * Use this when you need to:
-   * - Process all items in a table
-   * - Apply filters to a large dataset
-   * - Use a GSI for scanning
-   *
-   * @returns A ScanBuilder instance for chaining operations
-   */
-  scan() {
-    const executor = async (options) => {
-      const expressionParams = {
-        expressionAttributeNames: {},
-        expressionAttributeValues: {},
-        valueCounter: { count: 0 }
-      };
-      let filterExpression;
-      if (options.filter) {
-        filterExpression = buildExpression(options.filter, expressionParams);
-      }
-      const projectionExpression = options.projection?.map((p) => generateAttributeName(expressionParams, p)).join(", ");
-      const { expressionAttributeNames, expressionAttributeValues } = expressionParams;
-      const { indexName, limit, consistentRead, lastEvaluatedKey } = options;
-      const params = {
-        TableName: this.tableName,
-        FilterExpression: filterExpression,
-        ExpressionAttributeNames: Object.keys(expressionAttributeNames).length > 0 ? expressionAttributeNames : void 0,
-        ExpressionAttributeValues: Object.keys(expressionAttributeValues).length > 0 ? expressionAttributeValues : void 0,
-        IndexName: indexName,
-        Limit: limit,
-        ConsistentRead: consistentRead,
-        ProjectionExpression: projectionExpression,
-        ExclusiveStartKey: lastEvaluatedKey
-      };
-      try {
-        const result = await this.dynamoClient.scan(params);
-        return {
-          items: result.Items,
-          lastEvaluatedKey: result.LastEvaluatedKey
-        };
-      } catch (error) {
-        console.log(debugCommand(params));
-        console.error("Error scanning items:", error);
-        throw error;
-      }
-    };
-    return new ScanBuilder(executor);
-  }
-  delete(keyCondition) {
-    const executor = async (params) => {
-      try {
-        const result = await this.dynamoClient.delete({
-          TableName: params.tableName,
-          Key: this.createKeyForPrimaryIndex(keyCondition),
-          ConditionExpression: params.conditionExpression,
-          ExpressionAttributeNames: params.expressionAttributeNames,
-          ExpressionAttributeValues: params.expressionAttributeValues,
-          ReturnValues: params.returnValues
-        });
-        return {
-          item: result.Attributes
-        };
-      } catch (error) {
-        console.error("Error deleting item:", error);
-        throw error;
-      }
-    };
-    return new DeleteBuilder(executor, this.tableName, keyCondition);
-  }
-  /**
-   * Updates an item in the table
-   *
-   * @param keyCondition The primary key of the item to update
-   * @returns An UpdateBuilder instance for chaining update operations and conditions
-   */
-  update(keyCondition) {
-    const executor = async (params) => {
-      try {
-        const result = await this.dynamoClient.update({
-          TableName: params.tableName,
-          Key: this.createKeyForPrimaryIndex(keyCondition),
-          UpdateExpression: params.updateExpression,
-          ConditionExpression: params.conditionExpression,
-          ExpressionAttributeNames: params.expressionAttributeNames,
-          ExpressionAttributeValues: params.expressionAttributeValues,
-          ReturnValues: params.returnValues
-        });
-        return {
-          item: result.Attributes
-        };
-      } catch (error) {
-        console.error("Error updating item:", error);
-        throw error;
-      }
-    };
-    return new UpdateBuilder(executor, this.tableName, keyCondition);
-  }
-  /**
-   * Creates a transaction builder for performing multiple operations atomically
-   */
-  transactionBuilder() {
-    const executor = async (params) => {
-      await this.dynamoClient.transactWrite(params);
-    };
-    return new TransactionBuilder(executor, {
-      partitionKey: this.partitionKey,
-      sortKey: this.sortKey
-    });
-  }
-  /**
-   * Creates a batch builder for performing multiple operations efficiently with optional type inference
-   *
-   * @example Basic Usage
-   * ```typescript
-   * const batch = table.batchBuilder();
-   *
-   * // Add operations
-   * userRepo.create(newUser).withBatch(batch);
-   * orderRepo.get({ id: 'order-1' }).withBatch(batch);
-   *
-   * // Execute operations
-   * const result = await batch.execute();
-   * ```
-   *
-   * @example Typed Usage
-   * ```typescript
-   * // Define entity types for the batch
-   * const batch = table.batchBuilder<{
-   *   User: UserEntity;
-   *   Order: OrderEntity;
-   *   Product: ProductEntity;
-   * }>();
-   *
-   * // Add operations with type information
-   * userRepo.create(newUser).withBatch(batch, 'User');
-   * orderRepo.get({ id: 'order-1' }).withBatch(batch, 'Order');
-   * productRepo.delete({ id: 'old-product' }).withBatch(batch, 'Product');
-   *
-   * // Execute and get typed results
-   * const result = await batch.execute();
-   * const users: UserEntity[] = result.reads.itemsByType.User;
-   * const orders: OrderEntity[] = result.reads.itemsByType.Order;
-   * ```
-   */
-  batchBuilder() {
-    const batchWriteExecutor = async (operations) => {
-      return this.batchWrite(operations);
-    };
-    const batchGetExecutor = async (keys) => {
-      return this.batchGet(keys);
-    };
-    return new BatchBuilder(batchWriteExecutor, batchGetExecutor, {
-      partitionKey: this.partitionKey,
-      sortKey: this.sortKey
-    });
-  }
-  /**
-   * Executes a transaction using a callback function
-   *
-   * @param callback A function that receives a transaction context and performs operations on it
-   * @param options Optional transaction options
-   * @returns A promise that resolves when the transaction is complete
-   */
-  async transaction(callback, options) {
-    const transactionExecutor = async (params) => {
-      await this.dynamoClient.transactWrite(params);
-    };
-    const transaction = new TransactionBuilder(transactionExecutor, {
-      partitionKey: this.partitionKey,
-      sortKey: this.sortKey
-    });
-    if (options) {
-      transaction.withOptions(options);
-    }
-    const result = await callback(transaction);
-    await transaction.execute();
-    return result;
-  }
-  /**
-   * Creates a condition check operation for use in transactions
-   *
-   * This is useful for when you require a transaction to succeed only when a specific condition is met on a
-   * a record within the database that you are not directly updating.
-   *
-   * For example, you are updating a record and you want to ensure that another record exists and/or has a specific value before proceeding.
-   */
-  conditionCheck(keyCondition) {
-    return new ConditionCheckBuilder(this.tableName, keyCondition);
-  }
-  /**
-   * Performs a batch get operation to retrieve multiple items at once
-   *
-   * @param keys Array of primary keys to retrieve
-   * @returns A promise that resolves to the retrieved items
-   */
-  async batchGet(keys) {
-    const allItems = [];
-    const allUnprocessedKeys = [];
-    for (const chunk of chunkArray(keys, DDB_BATCH_GET_LIMIT)) {
-      const formattedKeys = chunk.map((key) => ({
-        [this.partitionKey]: key.pk,
-        ...this.sortKey ? { [this.sortKey]: key.sk } : {}
-      }));
-      const params = {
-        RequestItems: {
-          [this.tableName]: {
-            Keys: formattedKeys
-          }
-        }
-      };
-      try {
-        const result = await this.dynamoClient.batchGet(params);
-        if (result.Responses?.[this.tableName]) {
-          allItems.push(...result.Responses[this.tableName]);
-        }
-        const unprocessedKeysArray = result.UnprocessedKeys?.[this.tableName]?.Keys || [];
-        const unprocessedKeys = unprocessedKeysArray.map((key) => ({
-          pk: key[this.partitionKey],
-          sk: this.sortKey ? key[this.sortKey] : void 0
-        }));
-        if (unprocessedKeys.length > 0) {
-          allUnprocessedKeys.push(...unprocessedKeys);
-        }
-      } catch (error) {
-        console.error("Error in batch get operation:", error);
-        throw error;
-      }
-    }
-    return {
-      items: allItems,
-      unprocessedKeys: allUnprocessedKeys
-    };
-  }
-  /**
-   * Performs a batch write operation to put or delete multiple items at once
-   *
-   * @param operations Array of put or delete operations
-   * @returns A promise that resolves to any unprocessed operations
-   */
-  async batchWrite(operations) {
-    const allUnprocessedItems = [];
-    for (const chunk of chunkArray(operations, DDB_BATCH_WRITE_LIMIT)) {
-      const writeRequests = chunk.map((operation) => {
-        if (operation.type === "put") {
-          return {
-            PutRequest: {
-              Item: operation.item
-            }
-          };
-        }
-        return {
-          DeleteRequest: {
-            Key: this.createKeyForPrimaryIndex(operation.key)
-          }
-        };
-      });
-      const params = {
-        RequestItems: {
-          [this.tableName]: writeRequests
-        }
-      };
-      try {
-        const result = await this.dynamoClient.batchWrite(params);
-        const unprocessedRequestsArray = result.UnprocessedItems?.[this.tableName] || [];
-        if (unprocessedRequestsArray.length > 0) {
-          const unprocessedItems = unprocessedRequestsArray.map((request) => {
-            if (request?.PutRequest?.Item) {
-              return {
-                type: "put",
-                item: request.PutRequest.Item
-              };
-            }
-            if (request?.DeleteRequest?.Key) {
-              return {
-                type: "delete",
-                key: {
-                  pk: request.DeleteRequest.Key[this.partitionKey],
-                  sk: this.sortKey ? request.DeleteRequest.Key[this.sortKey] : void 0
-                }
-              };
-            }
-            throw new Error("Invalid unprocessed item format returned from DynamoDB");
-          });
-          allUnprocessedItems.push(...unprocessedItems);
-        }
-      } catch (error) {
-        console.error("Error in batch write operation:", error);
-        throw error;
-      }
-    }
-    return {
-      unprocessedItems: allUnprocessedItems
-    };
-  }
-};
-
-// src/utils/partition-key-template.ts
-function partitionKey(strings, ...keys) {
-  return (params) => {
-    let result = strings[0] ?? "";
-    for (let i = 0; i < keys.length; i++) {
-      const key = keys[i];
-      if (key) {
-        result += params[key] + (strings[i + 1] ?? "");
-      }
-    }
-    return result;
-  };
-}
-
-// src/utils/sort-key-template.ts
-function sortKey(strings, ...keys) {
-  return (params) => {
-    let result = strings[0] ?? "";
-    for (let i = 0; i < keys.length; i++) {
-      const key = keys[i];
-      if (key && params && key in params) {
-        result += params[key] + (strings[i + 1] ?? "");
-      }
-    }
-    return result;
-  };
-}
-
-export { BatchBuilder, BatchError, DeleteBuilder, PutBuilder, QueryBuilder, Table, TransactionBuilder, UpdateBuilder, and, attributeExists, attributeNotExists, beginsWith, between, contains, createIndex, createQueries, defineEntity, eq, gt, gte, inArray, lt, lte, ne, not, or, partitionKey, sortKey };
-//# sourceMappingURL=index.js.map
-//# sourceMappingURL=index.js.map
+export { Table } from './chunk-EODPMYPE.js';
+export { createIndex, createQueries, defineEntity } from './chunk-2EWNZOUK.js';
+export { partitionKey, sortKey } from './chunk-QVRMYGC4.js';
+export { BatchBuilder, BatchError, DeleteBuilder, PutBuilder, QueryBuilder, TransactionBuilder, UpdateBuilder } from './chunk-DTFJJASK.js';
+export { and, attributeExists, attributeNotExists, beginsWith, between, contains, eq, gt, gte, inArray, lt, lte, ne, not, or } from './chunk-2WIBY7PZ.js';