dyno-table 0.0.1 → 0.1.2

package/dist/index.js

@@ -1,1083 +1,3289 @@
-"use strict";
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  return to;
-};
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-
-// src/index.ts
-var index_exports = {};
-__export(index_exports, {
-  BaseRepository: () => BaseRepository,
-  ConditionalCheckFailedError: () => ConditionalCheckFailedError,
-  DynamoError: () => DynamoError,
-  ExponentialBackoffStrategy: () => ExponentialBackoffStrategy,
-  ResourceNotFoundError: () => ResourceNotFoundError,
-  Table: () => Table
+// 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 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
 });
-module.exports = __toCommonJS(index_exports);
 
-// src/builders/expression-builder.ts
-var ExpressionBuilder = class {
-  nameCount = 0;
-  valueCount = 0;
-  generateAlias(type, prefix = type === "name" ? "n" : "v") {
-    const count = type === "name" ? this.nameCount++ : this.valueCount++;
-    const symbol = type === "name" ? "#" : ":";
-    return `${symbol}${prefix}${count}`;
-  }
-  reset() {
-    this.nameCount = 0;
-    this.valueCount = 0;
-  }
-  createAttributePath(path) {
-    const parts = path.split(".");
-    const aliases = parts.map(() => this.generateAlias("name"));
-    return {
-      path: aliases.join("."),
-      names: Object.fromEntries(parts.map((part, i) => [aliases[i], part]))
-    };
+// src/expression.ts
+var generateAttributeName = (params, attr) => {
+  for (const [existingName, existingAttr] of Object.entries(params.expressionAttributeNames)) {
+    if (existingAttr === attr) {
+      return existingName;
+    }
   }
-  addValue(attributes, value, prefix) {
-    const alias = this.generateAlias("value", prefix);
-    attributes.values[alias] = value;
-    return alias;
+  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`);
   }
-  buildComparison(path, operator, value, attributes, prefix) {
-    const simpleOperators = ["=", "<>", "<", "<=", ">", ">="];
-    if (simpleOperators.includes(operator)) {
-      const valueAlias = this.addValue(attributes, value, prefix);
-      return `${path} ${operator} ${valueAlias}`;
-    }
-    switch (operator) {
-      case "attribute_exists":
-      case "attribute_not_exists":
-        return `${operator}(${path})`;
-      case "begins_with":
-      case "contains":
-      case "attribute_type":
-        return `${operator}(${path}, ${this.addValue(attributes, value, prefix)})`;
-      case "not_contains":
-        return `NOT contains(${path}, ${this.addValue(attributes, value, prefix)})`;
-      case "size": {
-        const { compare, value: sizeValue } = value;
-        return `size(${path}) ${compare} ${this.addValue(attributes, sizeValue, prefix)}`;
-      }
-      case "BETWEEN": {
-        const valueAlias = this.addValue(attributes, value, prefix);
-        return `${path} BETWEEN ${valueAlias}[0] AND ${valueAlias}[1]`;
-      }
-      case "IN":
-        return `${path} IN (${this.addValue(attributes, value, prefix)})`;
-      default:
-        throw new Error(`Unsupported operator: ${operator}`);
-    }
+  if (requiresValue && condition.value === void 0) {
+    throw new Error(`Value is required for ${condition.type} condition`);
   }
-  createExpression(conditions) {
-    this.reset();
-    const attributes = { names: {}, values: {} };
-    const expressions = conditions.map(({ field, operator, value }) => {
-      const { path, names } = this.createAttributePath(field);
-      Object.assign(attributes.names, names);
-      return this.buildComparison(path, operator, value, attributes);
-    });
-    return {
-      expression: expressions.length ? expressions.join(" AND ") : void 0,
-      attributes: this.formatAttributes(attributes)
-    };
+};
+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 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`);
   }
-  formatAttributes({
-    names,
-    values
-  }) {
-    return {
-      ...Object.keys(names).length && { names },
-      ...Object.keys(values).length && { values }
-    };
+  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`);
   }
-  buildKeyCondition(key, indexConfig) {
-    this.reset();
-    const attributes = { names: {}, values: {} };
-    const conditions = [];
-    const pkName = this.generateAlias("name", "pk");
-    attributes.names[pkName] = indexConfig.pkName;
-    conditions.push(`${pkName} = ${this.addValue(attributes, key.pk, "pk")}`);
-    if (key.sk && indexConfig.skName) {
-      const skName = this.generateAlias("name", "sk");
-      attributes.names[skName] = indexConfig.skName;
-      if (typeof key.sk === "string") {
-        conditions.push(
-          `${skName} = ${this.addValue(attributes, key.sk, "sk")}`
-        );
-      } else {
-        conditions.push(
-          this.buildComparison(
-            skName,
-            key.sk.operator,
-            key.sk.value,
-            attributes
-          )
-        );
+  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),
+      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)})`;
       }
-    }
-    return {
-      expression: conditions.join(" AND "),
-      attributes: this.formatAttributes(attributes)
     };
-  }
-  buildUpdateExpression(updates) {
-    this.reset();
-    const attributes = { names: {}, values: {} };
-    const operations = { sets: [], removes: [] };
-    for (const [key, value] of Object.entries(updates)) {
-      if (key === "") {
-        throw new Error("Empty key provided");
-      }
-      const nameAlias = this.generateAlias("name", "u");
-      attributes.names[nameAlias] = key;
-      if (value == null) {
-        operations.removes.push(nameAlias);
-      } else {
-        const valueAlias = this.addValue(attributes, value, "u");
-        operations.sets.push(`${nameAlias} = ${valueAlias}`);
-      }
+    const builder = expressionBuilders[condition.type];
+    if (!builder) {
+      throw new Error(`Unknown condition type: ${condition.type}`);
     }
-    const expression = [
-      operations.sets.length && `SET ${operations.sets.join(", ")}`,
-      operations.removes.length && `REMOVE ${operations.removes.join(", ")}`
-    ].filter(Boolean).join(" ");
-    return {
-      expression,
-      attributes: this.formatAttributes(attributes)
-    };
+    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/builders/operation-builder.ts
-var OperationBuilder = class {
-  constructor(expressionBuilder) {
-    this.expressionBuilder = expressionBuilder;
-  }
-  conditions = [];
-  where(field, operator, value) {
-    this.conditions.push({ field, operator, value });
-    return this;
+// 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();
   }
-  whereExists(field) {
-    this.conditions.push({ field, operator: "attribute_exists" });
-    return this;
-  }
-  whereNotExists(field) {
-    this.conditions.push({ field, operator: "attribute_not_exists" });
-    return this;
-  }
-  whereEquals(field, value) {
-    return this.where(field, "=", value);
-  }
-  whereBetween(field, start, end) {
-    return this.where(field, "BETWEEN", [start, end]);
-  }
-  whereIn(field, values) {
-    return this.where(field, "IN", values);
-  }
-  buildConditionExpression() {
-    return this.expressionBuilder.createExpression(this.conditions);
+  /**
+   * Gets the current page number (1-indexed).
+   * Use this method when you need to:
+   * - Track progress through dinosaur lists
+   * - Display habitat inspection status
+   * - Monitor security sweep progress
+   * 
+   * @example
+   * ```ts
+   * 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;
   }
-};
-
-// src/builders/put-builder.ts
-var PutBuilder = class extends OperationBuilder {
-  constructor(item, expressionBuilder, onBuild) {
-    super(expressionBuilder);
-    this.item = item;
-    this.onBuild = onBuild;
+  /**
+   * Checks if there are more pages of dinosaurs or habitats to process.
+   * Use this method when you need to:
+   * - Check for more dinosaurs to review
+   * - Continue habitat inspections
+   * - Process security incidents
+   * - Complete feeding schedules
+   * 
+   * This method takes into account both:
+   * - DynamoDB's lastEvaluatedKey mechanism
+   * - 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;
   }
-  build() {
-    const { expression, attributes } = this.buildConditionExpression();
+  /**
+   * Retrieves the next page of dinosaurs or habitats from DynamoDB.
+   * Use this method when you need to:
+   * - Process dinosaur groups systematically
+   * - Review habitat inspections in batches
+   * - Monitor security incidents in sequence
+   * - Schedule feeding rotations
+   * 
+   * This method handles:
+   * - Automatic continuation between groups
+   * - 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
+        };
+      }
+      effectivePageSize = Math.min(effectivePageSize, remainingItems);
+    }
+    const query = this.queryBuilder.clone().limit(effectivePageSize);
+    if (this.lastEvaluatedKey) {
+      query.startFrom(this.lastEvaluatedKey);
+    }
+    const result = await query.execute();
+    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 {
-      type: "put",
-      item: this.item,
-      condition: expression ? {
-        expression,
-        names: attributes.names,
-        values: attributes.values
-      } : void 0
+      items: result.items,
+      lastEvaluatedKey: result.lastEvaluatedKey,
+      hasNextPage: this.hasNextPage(),
+      page: this.currentPage
     };
   }
-  async execute() {
-    return this.onBuild(this.build());
+  /**
+   * Gets all remaining dinosaurs or habitats and combines them into a single array.
+   * Use this method when you need to:
+   * - Generate complete park inventory
+   * - Perform full security audit
+   * - Create comprehensive feeding schedule
+   * - Run park-wide health checks
+   * 
+   * Note: Use with caution! This method:
+   * - Could overwhelm systems with large dinosaur populations
+   * - Makes multiple database requests
+   * - May cause system strain during peak hours
+   * 
+   * @example
+   * ```ts
+   * // 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/query-builder.ts
-var QueryBuilder = class extends OperationBuilder {
-  constructor(key, indexConfig, expressionBuilder, onBuild) {
-    super(expressionBuilder);
-    this.key = key;
-    this.indexConfig = indexConfig;
-    this.onBuild = onBuild;
+var QueryBuilder = class _QueryBuilder {
+  keyCondition;
+  options = {};
+  selectedFields = /* @__PURE__ */ new Set();
+  executor;
+  constructor(executor, keyCondition) {
+    this.executor = executor;
+    this.keyCondition = keyCondition;
   }
-  limitValue;
-  indexNameValue;
-  limit(value) {
-    this.limitValue = value;
+  /**
+   * Sets the maximum number of items to return from the query.
+   * Use this method when you need to:
+   * - Limit the result set size
+   * - Implement manual pagination
+   * - Control data transfer size
+   *
+   * Note: This limit applies to the items that match the key condition
+   * before any filter expressions are applied.
+   *
+   * @example
+   * ```ts
+   * // Get first 10 orders for a user
+   * const result = await new QueryBuilder(executor, eq('userId', '123'))
+   *   .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 query.
+   * 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 query.
+   * Use this method when you need to:
+   * - Query data using non-primary key attributes
+   * - Access data through alternate access patterns
+   * - Optimize query performance for specific access patterns
+   *
+   * This method provides type safety by only allowing valid GSI names
+   * defined in your table configuration.
+   *
+   * @example
+   * ```ts
+   * // Query by status using a GSI
+   * const result = await new QueryBuilder(executor, eq('status', 'ACTIVE'))
+   *   .useIndex('status-index')
+   *   .execute();
+   *
+   * // Query by category and date range
+   * const result = await new QueryBuilder(executor, eq('category', 'books'))
+   *   .useIndex('category-date-index')
+   *   .filter(op => op.between('date', startDate, endDate))
+   *   .execute();
+   * ```
+   *
+   * Note: Be aware that GSIs:
+   * - May have different projected attributes
+   * - Have eventually consistent reads only
+   * - May have different provisioned throughput
+   *
+   * @param indexName - The name of the GSI to use (type-safe based on table configuration)
+   * @returns The builder instance for method chaining
+   */
+  /**
+   * Specifies a Global Secondary Index (GSI) to use for the query.
+   * Use this method when you need to:
+   * - Query dinosaurs by species or status
+   * - Search habitats by security level
+   * - Find incidents by date
+   * - List feeding schedules by time
+   * 
+   * @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.indexNameValue = indexName;
+    this.options.indexName = indexName;
     return this;
   }
-  build() {
-    const filter = this.buildConditionExpression();
-    const keyCondition = this.expressionBuilder.buildKeyCondition(
-      this.key,
-      this.indexConfig
-    );
-    return {
-      type: "query",
-      keyCondition: {
-        expression: keyCondition.expression,
-        names: keyCondition.attributes.names,
-        values: keyCondition.attributes.values
-      },
-      filter: filter.expression ? {
-        expression: filter.expression,
-        names: filter.attributes.names,
-        values: filter.attributes.values
-      } : void 0,
-      limit: this.limitValue,
-      indexName: this.indexNameValue
-    };
-  }
-  async execute() {
-    return this.onBuild(this.build());
-  }
-};
-
-// src/builders/update-builder.ts
-var UpdateBuilder = class extends OperationBuilder {
-  constructor(key, expressionBuilder, onBuild) {
-    super(expressionBuilder);
-    this.key = key;
-    this.onBuild = onBuild;
-  }
-  updates = {};
-  set(field, value) {
-    this.updates[field] = value;
+  /**
+   * Sets whether to use strongly consistent reads for the query.
+   * Use this method when you need to:
+   * - Get real-time dinosaur status updates
+   * - Monitor critical security systems
+   * - Track immediate habitat changes
+   * - Verify containment protocols
+   * 
+   * Note:
+   * - Consistent reads are not available on GSIs
+   * - Consistent reads consume twice the throughput
+   * - Default is eventually consistent reads
+   * 
+   * @example
+   * ```ts
+   * // Check immediate dinosaur status
+   * const result = await new QueryBuilder(executor, eq('species', 'Velociraptor'))
+   *   .filter(op => op.eq('status', 'ACTIVE'))
+   *   .consistentRead()
+   *   .execute();
+   * 
+   * // Monitor security breaches
+   * const result = await new QueryBuilder(executor, eq('type', 'SECURITY_ALERT'))
+   *   .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;
   }
-  setMany(attribtues) {
-    this.updates = { ...this.updates, ...attribtues };
+  /**
+   * Adds a filter expression to the query.
+   * Use this method when you need to:
+   * - Filter results based on non-key attributes
+   * - Apply complex filtering conditions
+   * - Combine multiple filter conditions
+   *
+   * Note: Filter expressions are applied after the key condition,
+   * so they don't reduce the amount of data read from DynamoDB.
+   *
+   * @example
+   * ```ts
+   * // Simple filter
+   * builder.filter(op => op.eq('status', 'ACTIVE'))
+   *
+   * // Complex filter with multiple conditions
+   * builder.filter(op =>
+   *   op.and([
+   *     op.gt('amount', 1000),
+   *     op.beginsWith('category', 'ELECTRONICS'),
+   *     op.attributeExists('reviewDate')
+   *   ])
+   * )
+   * ```
+   *
+   * @param condition - Either a Condition object or a callback function that builds the condition
+   * @returns The builder instance for method chaining
+   */
+  /**
+   * Adds a filter expression to refine the query results.
+   * Use this method when you need to:
+   * - Filter dinosaurs by behavior patterns
+   * - Find habitats with specific conditions
+   * - Search for security incidents
+   * - Monitor feeding patterns
+   * 
+   * @example
+   * ```typescript
+   * // 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) {
+    if (typeof condition === "function") {
+      const conditionOperator = {
+        eq,
+        ne,
+        lt,
+        lte,
+        gt,
+        gte,
+        between,
+        beginsWith,
+        contains,
+        attributeExists,
+        attributeNotExists,
+        and,
+        or,
+        not
+      };
+      this.options.filter = condition(conditionOperator);
+    } else {
+      this.options.filter = condition;
+    }
     return this;
   }
-  remove(...fields) {
-    for (const field of fields) {
-      this.updates[field] = null;
+  /**
+   * Specifies which attributes to return in the query results.
+   * Use this method when you need to:
+   * - Reduce data transfer by selecting specific attributes
+   * - Optimize response size
+   * - Focus on relevant attributes only
+   *
+   * Note: Using projection can significantly reduce the amount
+   * of data returned and lower your costs.
+   *
+   * @example
+   * ```ts
+   * // Select single attribute
+   * builder.select('email')
+   *
+   * // Select multiple attributes
+   * builder.select(['id', 'name', 'email'])
+   *
+   * // Chain multiple select calls
+   * builder
+   *   .select('id')
+   *   .select(['name', 'email'])
+   * ```
+   *
+   * @param fields - A single field name or an array of field names to return
+   * @returns The builder instance for method chaining
+   */
+  /**
+   * Specifies which attributes to return in the query results.
+   * Use this method when you need to:
+   * - Get specific dinosaur attributes
+   * - Retrieve habitat statistics
+   * - Monitor security metrics
+   * - Optimize response size
+   * 
+   * @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;
   }
-  increment(field, by = 1) {
-    this.updates[field] = { $add: by };
+  /**
+   * Sets the query to return items in ascending order by sort key.
+   * Use this method when you need to:
+   * - Retrieve items in natural order (e.g., timestamps, versions)
+   * - Implement chronological ordering
+   * - Get oldest items first
+   *
+   * 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.
+   * Use this method when you need to:
+   * - List dinosaurs by age (youngest first)
+   * - View incidents chronologically
+   * - Track feeding schedule progression
+   * - Monitor habitat inspections
+   * 
+   * @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;
   }
-  build() {
-    const condition = this.buildConditionExpression();
-    const update = this.expressionBuilder.buildUpdateExpression(this.updates);
-    return {
-      type: "update",
-      key: this.key,
-      update: {
-        expression: update.expression,
-        names: update.attributes.names,
-        values: update.attributes.values
-      },
-      condition: condition.expression ? {
-        expression: condition.expression,
-        names: condition.attributes.names,
-        values: condition.attributes.values
-      } : void 0
-    };
+  /**
+   * Sets the query to return items in descending order by sort key.
+   * Use this method when you need to:
+   * - Get most recent security breaches
+   * - Find oldest dinosaurs first
+   * - Check latest habitat modifications
+   * - Monitor recent feeding events
+   *
+   * @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;
   }
-  async execute() {
-    return this.onBuild(this.build());
+  /**
+   * Creates a paginator that handles DynamoDB pagination automatically.
+   * Use this method when you need to:
+   * - Browse large dinosaur collections
+   * - View habitat inspection history
+   * - Monitor security incidents
+   * - Track feeding patterns
+   * 
+   * The paginator handles:
+   * - Tracking the last evaluated key
+   * - Managing page boundaries
+   * - Respecting overall query limits
+   * 
+   * @example
+   * ```typescript
+   * // List dinosaurs by species
+   * const paginator = new QueryBuilder(executor, eq('species', 'Velociraptor'))
+   *   .filter(op => op.eq('status', 'ACTIVE'))
+   *   .useIndex('species-index')
+   *   .paginate(10);
+   * 
+   * // Process pages of security incidents
+   * const paginator = new QueryBuilder(executor, eq('type', 'SECURITY_BREACH'))
+   *   .filter(op => op.gt('severityLevel', 7))
+   *   .sortDescending()
+   *   .paginate(25);
+   * 
+   * while (paginator.hasNextPage()) {
+   *   const page = await paginator.getNextPage();
+   *   console.log(`Processing incidents page ${page.page}, count: ${page.items.length}`);
+   *   // Handle security incidents
+   * }
+   * ```
+   * 
+   * @param pageSize - The number of items to return per page
+   * @returns A Paginator instance that manages the pagination state
+   * @see Paginator for more pagination control options
+   */
+  paginate(pageSize) {
+    return new Paginator(this, pageSize);
   }
-};
-
-// src/errors/dynamo-error.ts
-var DynamoError = class _DynamoError extends Error {
-  constructor(message, originalError, context) {
-    super(message);
-    this.originalError = originalError;
-    this.context = context;
-    this.name = "DynamoError";
-    if (Error.captureStackTrace) {
-      Error.captureStackTrace(this, _DynamoError);
-    }
+  /**
+   * Sets the starting point for the query using a previous lastEvaluatedKey.
+   * Use this method when you need to:
+   * - Implement manual dinosaur list pagination
+   * - Resume habitat inspection reviews
+   * - Continue security incident analysis
+   * - Store query position between sessions
+   * 
+   * 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 new QueryBuilder(executor, eq('species', 'Velociraptor'))
+   *   .filter(op => op.eq('status', 'ACTIVE'))
+   *   .limit(5)
+   *   .execute();
+   * 
+   * if (result1.lastEvaluatedKey) {
+   *   // Continue listing dinosaurs
+   *   const result2 = await new QueryBuilder(executor, eq('species', 'Velociraptor'))
+   *     .filter(op => op.eq('status', 'ACTIVE'))
+   *     .startFrom(result1.lastEvaluatedKey)
+   *     .limit(5)
+   *     .execute();
+   * 
+   *   console.log('Additional dinosaurs:', result2.items);
+   * }
+   * ```
+   * 
+   * @param lastEvaluatedKey - The exclusive start key from a previous query result
+   * @returns The builder instance for method chaining
+   */
+  startFrom(lastEvaluatedKey) {
+    this.options.lastEvaluatedKey = lastEvaluatedKey;
+    return this;
   }
-};
-var ConditionalCheckFailedError = class extends DynamoError {
-  constructor(message, originalError, context) {
-    super(message, originalError, context);
-    this.name = "ConditionalCheckFailedError";
+  /**
+   * Creates a deep clone of this QueryBuilder instance.
+   * Use this method when you need to:
+   * - Query different dinosaur statuses
+   * - Check multiple habitat conditions
+   * - Monitor various security levels
+   * - Create report templates
+   * 
+   * 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 };
+    clone.selectedFields = new Set(this.selectedFields);
+    return clone;
   }
-};
-var ResourceNotFoundError = class extends DynamoError {
-  constructor(message, originalError, context) {
-    super(message, originalError, context);
-    this.name = "ResourceNotFoundError";
+  /**
+   * Executes the query against DynamoDB.
+   * Use this method when you need to:
+   * - Find specific dinosaur groups
+   * - Check habitat conditions
+   * - Monitor security incidents
+   * - Track feeding patterns
+   * 
+   * The method returns both the matched items and, if there are more results,
+   * a lastEvaluatedKey that can be used with startFrom() to continue the query.
+   * 
+   * @example
+   * ```typescript
+   * try {
+   *   // Find active carnivores in specific habitat
+   *   const result = 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()
+   *     .limit(5)
+   *     .execute();
+   * 
+   *   console.log(`Found ${result.items.length} dangerous dinosaurs`);
+   * 
+   *   if (result.lastEvaluatedKey) {
+   *     console.log('Additional threats detected');
+   *   }
+   * } catch (error) {
+   *   console.error('Security scan failed:', error);
+   * }
+   * ```
+   * 
+   * @returns A promise that resolves to an object containing:
+   *          - items: Array of items matching the query
+   *          - lastEvaluatedKey: Token for continuing the query, if more items exist
+   */
+  async execute() {
+    return this.executor(this.keyCondition, this.options);
   }
 };
 
-// src/errors/error-handler.ts
-function translateExpression(expression, attributes) {
-  if (!expression || !attributes) return expression || "";
-  let translated = expression;
-  if (attributes.names) {
-    for (const [alias, name] of Object.entries(attributes.names)) {
-      translated = translated.replace(new RegExp(alias, "g"), name);
-    }
-  }
-  if (attributes.values) {
-    for (const [alias, value] of Object.entries(attributes.values)) {
-      translated = translated.replace(
-        new RegExp(alias, "g"),
-        typeof value === "string" ? `"${value}"` : String(value)
-      );
+// src/utils/debug-expression.ts
+function debugCommand(command) {
+  const result = {};
+  function replaceAliases(expressionString) {
+    if (!expressionString) {
+      return expressionString;
     }
-  }
-  return translated;
-}
-function buildErrorMessage(context, error) {
-  const parts = [`DynamoDB ${context.operation} operation failed`];
-  if (context.tableName) {
-    parts.push(`
-Table: ${context.tableName}`);
-  }
-  if (context.key) {
-    parts.push(`
-Key: ${JSON.stringify(context.key, null, 2)}`);
-  }
-  if (context.expression) {
-    const { condition, update, filter, keyCondition } = context.expression;
-    if (condition) {
-      parts.push(
-        `
-Condition: ${translateExpression(condition, context.attributes)}`
-      );
-    }
-    if (update) {
-      parts.push(
-        `
-Update: ${translateExpression(update, context.attributes)}`
-      );
-    }
-    if (filter) {
-      parts.push(
-        `
-Filter: ${translateExpression(filter, context.attributes)}`
-      );
+    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);
     }
-    if (keyCondition) {
-      parts.push(
-        `
-Key Condition: ${translateExpression(keyCondition, context.attributes)}`
-      );
+    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;
   }
-  parts.push(`
-Original Error: ${error.message}`);
-  return parts.join("");
-}
-function handleDynamoError(error, context) {
-  if (!(error instanceof Error)) {
-    throw error;
+  if (command.updateExpression) {
+    result.updateExpression = replaceAliases(command.updateExpression);
   }
-  const errorMessage = buildErrorMessage(context, error);
-  switch (error.name) {
-    case "ConditionalCheckFailedException":
-      throw new ConditionalCheckFailedError(errorMessage, error, context);
-    case "ResourceNotFoundException":
-      throw new ResourceNotFoundError(errorMessage, error, context);
-    default:
-      throw new DynamoError(errorMessage, error, context);
+  if (command.conditionExpression) {
+    result.conditionExpression = replaceAliases(command.conditionExpression);
   }
-}
-
-// src/retry/retry-strategy.ts
-var RETRYABLE_ERRORS = /* @__PURE__ */ new Set([
-  "ProvisionedThroughputExceededException",
-  "ThrottlingException",
-  "RequestLimitExceeded",
-  "InternalServerError",
-  "ServiceUnavailable"
-]);
-var isRetryableError = (error) => {
-  if (!error || typeof error !== "object") return false;
-  return "name" in error && RETRYABLE_ERRORS.has(error.name);
-};
-
-// src/retry/exponential-backoff-strategy.ts
-var ExponentialBackoffStrategy = class {
-  constructor(maxAttempts = 3, baseDelay = 100, maxDelay = 5e3, jitter = true) {
-    this.maxAttempts = maxAttempts;
-    this.baseDelay = baseDelay;
-    this.maxDelay = maxDelay;
-    this.jitter = jitter;
-  }
-  shouldRetry(error, attempt) {
-    return attempt < this.maxAttempts && isRetryableError(error);
-  }
-  getDelay(attempt) {
-    const delay = Math.min(this.baseDelay * attempt ** 2, this.maxDelay);
-    if (!this.jitter) return delay;
-    return delay * (0.5 + Math.random());
+  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/dynamo/dynamo-converter.ts
-var DynamoConverter = class {
-  constructor(tableName) {
+// 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;
   }
   /**
-   * Converts our expression format to DynamoDB expression format
+   * Adds a condition that must be satisfied for the put operation to succeed.
+   * Use this method when you need to:
+   * - Prevent overwriting existing items (optimistic locking)
+   * - Ensure items meet certain criteria before replacement
+   * - Implement complex business rules for item updates
+   *
+   * @example
+   * ```ts
+   * // 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
    */
-  convertExpression(expr) {
-    if (!expr) return {};
-    return {
-      ...expr.expression && { Expression: expr.expression },
-      ...expr.names && { ExpressionAttributeNames: expr.names },
-      ...expr.values && { ExpressionAttributeValues: expr.values }
-    };
+  /**
+   * Adds a condition that must be satisfied for the put operation to succeed.
+   * Use this method when you need to:
+   * - Prevent duplicate dinosaur entries
+   * - Ensure habitat requirements
+   * - Validate security protocols
+   * 
+   * @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,
+        beginsWith,
+        contains,
+        attributeExists,
+        attributeNotExists,
+        and,
+        or,
+        not
+      };
+      this.options.condition = condition(conditionOperator);
+    } else {
+      this.options.condition = condition;
+    }
+    return this;
   }
   /**
-   * Convert our format to DynamoDB put command input
+   * Sets whether to return the item's previous values (if it existed).
+   * Use this method when you need to:
+   * - Track dinosaur profile updates
+   * - Monitor habitat modifications
+   * - Maintain change history
+   * 
+   * @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
+   *     }
+   *   });
+   * }
+   * ```
+   * 
+   * @param returnValues - Use 'ALL_OLD' to return previous values, or 'NONE' (default)
+   * @returns The builder instance for method chaining
    */
-  toPutCommand(options) {
-    return {
-      TableName: this.tableName,
-      Item: options.item,
-      ...options.condition && {
-        ConditionExpression: options.condition.expression,
-        ExpressionAttributeNames: options.condition.names,
-        ExpressionAttributeValues: options.condition.values
-      }
-    };
+  returnValues(returnValues) {
+    this.options.returnValues = returnValues;
+    return this;
   }
   /**
-   * Convert our format to DynamoDB get command input
+   * Generate the DynamoDB command parameters
    */
-  toGetCommand(options) {
+  toDynamoCommand() {
+    const { expression, names, values } = prepareExpressionParams(this.options.condition);
     return {
-      TableName: this.tableName,
-      Key: options.key,
-      ...options.indexName && { IndexName: options.indexName }
+      tableName: this.tableName,
+      item: this.item,
+      conditionExpression: expression,
+      expressionAttributeNames: names,
+      expressionAttributeValues: values,
+      returnValues: this.options.returnValues
     };
   }
   /**
-   * Convert our format to DynamoDB update command input
+   * Adds this put operation to a transaction.
+   * Use this method when you need to:
+   * - Transfer dinosaurs between habitats
+   * - Initialize new breeding programs
+   * - Update multiple facility records
+   * 
+   * @example
+   * ```ts
+   * 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
    */
-  toUpdateCommand(options) {
-    return {
-      TableName: this.tableName,
-      Key: options.key,
-      UpdateExpression: options.update.expression,
-      ExpressionAttributeNames: {
-        ...options.update.names,
-        ...options.condition?.names
-      },
-      ExpressionAttributeValues: {
-        ...options.update.values,
-        ...options.condition?.values
-      },
-      ...options.condition && {
-        ConditionExpression: options.condition.expression
-      },
-      ...options.returnValues && {
-        ReturnValues: options.returnValues
-      }
-    };
+  withTransaction(transaction) {
+    const command = this.toDynamoCommand();
+    transaction.putWithCommand(command);
+    return this;
   }
   /**
-   * Convert our format to DynamoDB delete command input
+   * 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
    */
-  toDeleteCommand(options) {
-    return {
-      TableName: this.tableName,
-      Key: options.key,
-      ...options.condition && {
-        ConditionExpression: options.condition.expression,
-        ExpressionAttributeNames: options.condition.names,
-        ExpressionAttributeValues: options.condition.values
-      }
-    };
+  async execute() {
+    const params = this.toDynamoCommand();
+    return this.executor(params);
   }
   /**
-   * Convert our format to DynamoDB query command input
+   * Gets a human-readable representation of the put command
+   * with all expression placeholders replaced by their actual values.
+   * Use this method when you need to:
+   * - Debug complex dinosaur transfers
+   * - Verify habitat assignments
+   * - Log security protocols
+   * - Troubleshoot breeding program conditions
+   * 
+   * @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
    */
-  toQueryCommand(options) {
-    return {
-      TableName: this.tableName,
-      ...options.keyCondition && {
-        KeyConditionExpression: options.keyCondition.expression,
-        ExpressionAttributeNames: {
-          ...options.keyCondition.names,
-          ...options.filter?.names
-        },
-        ExpressionAttributeValues: {
-          ...options.keyCondition.values,
-          ...options.filter?.values
-        }
-      },
-      ...options.filter && {
-        FilterExpression: options.filter.expression
-      },
-      IndexName: options.indexName,
-      Limit: options.limit,
-      ExclusiveStartKey: options.pageKey,
-      ConsistentRead: options.consistentRead
-    };
+  debug() {
+    const command = this.toDynamoCommand();
+    return debugCommand(command);
+  }
+};
+
+// src/builders/delete-builder.ts
+var DeleteBuilder = class {
+  options = {
+    returnValues: "ALL_OLD"
+  };
+  executor;
+  tableName;
+  key;
+  constructor(executor, tableName, key) {
+    this.executor = executor;
+    this.tableName = tableName;
+    this.key = key;
   }
   /**
-   * Convert our format to DynamoDB scan command input
+   * Adds a condition that must be satisfied for the delete operation to succeed.
+   * Use this method when you need to:
+   * - Implement optimistic locking (e.g., version check)
+   * - Ensure item exists before deletion
+   * - Validate item state before deletion
+   *
+   * @example
+   * ```ts
+   * // Simple condition
+   * builder.condition(op => op.attributeExists('id'))
+   *
+   * // Complex condition with version check
+   * builder.condition(op =>
+   *   op.and([
+   *     op.eq('version', 1),
+   *     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
    */
-  toScanCommand(options) {
-    return {
-      TableName: this.tableName,
-      ...options.filter && {
-        FilterExpression: options.filter.expression,
-        ExpressionAttributeNames: options.filter.names,
-        ExpressionAttributeValues: options.filter.values
-      },
-      IndexName: options.indexName,
-      Limit: options.limit,
-      ExclusiveStartKey: options.pageKey
-    };
+  /**
+   * Adds a condition that must be satisfied for the delete operation to succeed.
+   * Use this method when you need to:
+   * - Ensure safe removal conditions
+   * - Verify habitat status before deletion
+   * - Implement safety protocols
+   * 
+   * @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,
+        beginsWith,
+        contains,
+        attributeExists,
+        attributeNotExists,
+        and,
+        or,
+        not
+      };
+      this.options.condition = condition(conditionOperator);
+    } else {
+      this.options.condition = condition;
+    }
+    return this;
   }
   /**
-   * Convert our format to DynamoDB batch write command input
+   * Sets whether to return the item's attribute values before deletion.
+   * Use this method when you need to:
+   * - Archive removed dinosaur data
+   * - Track habitat decommissioning history
+   * - Maintain removal audit logs
+   * 
+   * @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
    */
-  toBatchWriteCommand(items) {
-    const requests = items.map((item) => {
-      if (item.put) {
-        return {
-          PutRequest: {
-            Item: item.put
-          }
-        };
-      }
-      if (item.delete) {
-        return {
-          DeleteRequest: {
-            Key: item.delete
-          }
-        };
-      }
-      throw new Error("Invalid batch write item");
-    });
-    return {
-      RequestItems: {
-        [this.tableName]: requests
-      }
-    };
+  returnValues(returnValues) {
+    this.options.returnValues = returnValues;
+    return this;
   }
   /**
-   * Convert our format to DynamoDB transact write command input
+   * Generate the DynamoDB command parameters
    */
-  toTransactWriteCommand(items) {
+  toDynamoCommand() {
+    const { expression, names, values } = prepareExpressionParams(this.options.condition);
     return {
-      TransactItems: items.map((item) => {
-        if (item.put) {
-          return {
-            Put: {
-              TableName: this.tableName,
-              Item: item.put.item,
-              ...item.put.condition && {
-                ConditionExpression: item.put.condition.expression,
-                ExpressionAttributeNames: item.put.condition.names,
-                ExpressionAttributeValues: item.put.condition.values
-              }
-            }
-          };
-        }
-        if (item.delete) {
-          return {
-            Delete: {
-              TableName: this.tableName,
-              Key: item.delete.key,
-              ...item.delete.condition && {
-                ConditionExpression: item.delete.condition.expression,
-                ExpressionAttributeNames: item.delete.condition.names,
-                ExpressionAttributeValues: item.delete.condition.values
-              }
-            }
-          };
-        }
-        if (item.update) {
-          return {
-            Update: {
-              TableName: this.tableName,
-              Key: item.update.key,
-              UpdateExpression: item.update.update.expression,
-              ...item.update.condition && {
-                ConditionExpression: item.update.condition.expression,
-                ExpressionAttributeNames: {
-                  ...item.update.update.names,
-                  ...item.update.condition.names
-                },
-                ExpressionAttributeValues: {
-                  ...item.update.update.values,
-                  ...item.update.condition.values
-                }
-              }
-            }
-          };
-        }
-        throw new Error("Invalid transaction item");
-      })
+      tableName: this.tableName,
+      key: this.key,
+      conditionExpression: expression,
+      expressionAttributeNames: names,
+      expressionAttributeValues: values,
+      returnValues: this.options.returnValues
     };
   }
   /**
-   * Convert DynamoDB batch write response to our format
+   * Adds this delete operation to a transaction.
+   * Use this method when you need to:
+   * - Coordinate dinosaur transfers
+   * - Manage habitat decommissioning
+   * - Handle species relocations
+   *
+   * @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
    */
-  fromBatchWriteResponse(response) {
-    return response.map((item) => {
-      if ("PutRequest" in item) {
-        return {
-          put: item.PutRequest.Item
-        };
-      }
-      if ("DeleteRequest" in item) {
-        return {
-          delete: item.DeleteRequest.Key
-        };
-      }
-      throw new Error("Invalid batch write response item");
-    });
+  withTransaction(transaction) {
+    const command = this.toDynamoCommand();
+    transaction.deleteWithCommand(command);
   }
-};
-
-// src/dynamo/dynamo-service.ts
-var BATCH_WRITE_LIMIT = 25;
-var TRANSACTION_LIMIT = 100;
-var DynamoService = class {
-  constructor(client, tableName) {
-    this.client = client;
-    this.tableName = tableName;
-    this.converter = new DynamoConverter(tableName);
+  /**
+   * 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);
   }
-  converter;
-  async put(options) {
-    try {
-      const params = this.converter.toPutCommand(options);
-      return await this.withRetry(() => this.client.put(params));
-    } catch (error) {
-      handleDynamoError(error, {
-        operation: "PUT",
-        tableName: this.tableName,
-        key: options.item,
-        expression: {
-          condition: options.condition?.expression
-        }
+  /**
+   * Gets a human-readable representation of the delete command
+   * with all expression placeholders replaced by their actual values.
+   * Use this method when you need to:
+   * - Debug complex deletion conditions
+   * - Verify safety checks
+   * - Log removal operations
+   * - Troubleshoot failed deletions
+   * 
+   * @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/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;
   }
-  async update(options) {
-    try {
-      const params = this.converter.toUpdateCommand(options);
-      return await this.withRetry(() => this.client.update(params));
-    } catch (error) {
-      handleDynamoError(error, {
-        operation: "UPDATE",
-        tableName: this.tableName,
-        key: options.key,
-        expression: {
-          update: options.update.expression,
-          condition: options.condition?.expression
-        }
-      });
+  /**
+   * Removes an attribute from the item.
+   * Use this method when you need to:
+   * - Delete attributes completely
+   * - Remove nested attributes
+   * - Clean up deprecated fields
+   * 
+   * @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.
+   * Use this method when you need to:
+   * - Increment counters
+   * - Add elements to a set atomically
+   * - Update numerical statistics
+   * 
+   * @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.
+   * Use this method when you need to:
+   * - Remove specific elements from a set
+   * - Update set-based attributes atomically
+   * - Maintain set membership
+   * 
+   * @example
+   * ```typescript
+   * // Remove from sets using arrays
+   * builder.deleteElementsFromSet(
+   *   'allowedHabitats',
+   *   ['JUNGLE', 'COASTAL']
+   * );
+   * 
+   * // Remove from sets using Set objects
+   * 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;
   }
-  async delete(options) {
-    const params = this.converter.toDeleteCommand(options);
-    try {
-      return await this.withRetry(() => this.client.delete(params));
-    } catch (error) {
-      handleDynamoError(error, {
-        operation: "DELETE",
-        tableName: this.tableName,
-        key: options.key,
-        expression: {
-          condition: params.ConditionExpression
-        }
-      });
+  /**
+   * Adds a condition that must be satisfied for the update to succeed.
+   * Use this method when you need to:
+   * - Implement optimistic locking
+   * - Ensure item state before update
+   * - Validate business rules
+   * - Prevent concurrent modifications
+   * 
+   * @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 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,
+        beginsWith,
+        contains,
+        attributeExists,
+        attributeNotExists,
+        and,
+        or,
+        not
+      };
+      this.options.condition = condition(conditionOperator);
+    } else {
+      this.options.condition = condition;
     }
+    return this;
   }
-  async get(key, options) {
-    try {
-      const params = this.converter.toGetCommand({ key, ...options });
-      return await this.withRetry(() => this.client.get(params));
-    } catch (error) {
-      handleDynamoError(error, {
-        operation: "GET",
-        tableName: this.tableName,
-        key
-      });
+  /**
+   * Sets which item attributes to include in the response.
+   * Use this method when you need to:
+   * - Get the complete updated item
+   * - Track changes to specific attributes
+   * - Compare old and new values
+   * - Monitor attribute modifications
+   * 
+   * Available options:
+   * - ALL_NEW: All attributes after the update
+   * - UPDATED_NEW: Only updated attributes, new values
+   * - ALL_OLD: All attributes before the update
+   * - UPDATED_OLD: Only updated attributes, old values
+   * - NONE: No attributes returned (default)
+   * 
+   * @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
+    };
   }
-  async query(options) {
-    try {
-      if (options.autoPaginate) {
-        return await this.executeWithAutoPagination(options);
+  /**
+   * Adds this update operation to a transaction.
+   * Use this method when you need to:
+   * - Update items as part of a larger transaction
+   * - Ensure multiple updates are atomic
+   * - Coordinate updates across multiple items
+   * 
+   * @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.
+   * Use this method when you need to:
+   * - Debug complex update expressions
+   * - Verify attribute names and values
+   * - Log update operations
+   * - Troubleshoot condition expressions
+   * 
+   * @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.
+   * Use this method when you need to:
+   * - Apply updates immediately
+   * - Get the updated item values
+   * - Handle conditional update failures
+   * 
+   * @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 object 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/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;
       }
-      const params = this.converter.toQueryCommand(options);
-      return await this.withRetry(() => this.client.query(params));
-    } catch (error) {
-      handleDynamoError(error, {
-        operation: "QUERY",
-        tableName: this.tableName,
-        expression: {
-          keyCondition: options.keyCondition?.expression,
-          filter: options.filter?.expression
+      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.`
+      );
     }
   }
-  async scan(options) {
-    try {
-      const params = this.converter.toScanCommand(options);
-      return await this.withRetry(() => this.client.scan(params));
-    } catch (error) {
-      handleDynamoError(error, {
-        operation: "SCAN",
-        tableName: this.tableName,
-        expression: {
-          filter: options.filter?.expression
+  /**
+   * Adds a put operation to the transaction.
+   * Use this method when you need to:
+   * - Insert new items as part of a transaction
+   * - Replace existing items atomically
+   * - Ensure items meet certain conditions before insertion
+   * 
+   * The method automatically checks for duplicate items within the transaction
+   * to prevent multiple operations on the same item.
+   * 
+   * @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.
+   * Use this method when you need to:
+   * - Reuse put commands from PutBuilder
+   * - Add complex put operations with pre-configured parameters
+   * - Integrate with existing put command configurations
+   * 
+   * This method is particularly useful when working with PutBuilder
+   * to maintain consistency in put operations across your application.
+   * 
+   * @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.
+   * Use this method when you need to:
+   * - Remove items as part of a transaction
+   * - Conditionally delete items
+   * - Ensure items exist before deletion
+   * 
+   * The method automatically checks for duplicate items within the transaction
+   * to prevent multiple operations on the same item.
+   * 
+   * @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) {
+    this.checkForDuplicateItem(tableName, key);
+    const transactionItem = {
+      type: "Delete",
+      params: {
+        tableName,
+        key: {
+          pk: key.pk,
+          sk: key.sk
         }
-      });
+      }
+    };
+    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;
   }
-  async batchWrite(items) {
-    try {
-      const chunks = this.chunkArray(items, BATCH_WRITE_LIMIT);
-      return await Promise.all(
-        chunks.map((chunk) => this.processBatchWrite(chunk))
-      );
-    } catch (error) {
-      handleDynamoError(error, {
-        operation: "BATCH_WRITE",
-        tableName: this.tableName
-      });
+  /**
+   * Adds a pre-configured delete operation to the transaction.
+   * Use this method when you need to:
+   * - Reuse delete commands from DeleteBuilder
+   * - Add complex delete operations with pre-configured parameters
+   * - Integrate with existing delete command configurations
+   * 
+   * This method is particularly useful when working with DeleteBuilder
+   * to maintain consistency in delete operations across your application.
+   * 
+   * @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) {
+    this.checkForDuplicateItem(command.tableName, command.key);
+    const transactionItem = {
+      type: "Delete",
+      params: command
+    };
+    this.items.push(transactionItem);
+    return this;
+  }
+  /**
+   * Adds an update operation to the transaction.
+   * Use this method when you need to:
+   * - Modify existing items as part of a transaction
+   * - Update multiple attributes atomically
+   * - Apply conditional updates
+   * - Perform complex attribute manipulations
+   * 
+   * The method supports all DynamoDB update expressions:
+   * - SET: Modify or add attributes
+   * - 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) {
+    this.checkForDuplicateItem(tableName, key);
+    const transactionItem = {
+      type: "Update",
+      params: {
+        tableName,
+        key: {
+          pk: key.pk,
+          sk: key.sk
+        },
+        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;
   }
-  async transactWrite(items) {
-    if (items.length > TRANSACTION_LIMIT) {
-      throw new Error(
-        `Transaction limit exceeded. Maximum is ${TRANSACTION_LIMIT} items, got ${items.length}`
-      );
+  /**
+   * Adds a pre-configured update operation to the transaction.
+   * Use this method when you need to:
+   * - Reuse update commands from UpdateBuilder
+   * - Add complex update operations with pre-configured parameters
+   * - Integrate with existing update command configurations
+   * 
+   * This method is particularly useful when working with UpdateBuilder
+   * to maintain consistency in update operations across your application.
+   * 
+   * @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) {
+    this.checkForDuplicateItem(command.tableName, command.key);
+    const transactionItem = {
+      type: "Update",
+      params: command
+    };
+    this.items.push(transactionItem);
+    return this;
+  }
+  /**
+   * Adds a condition check operation to the transaction.
+   * Use this method when you need to:
+   * - Validate item state without modifying it
+   * - Ensure data consistency across tables
+   * - Implement complex business rules
+   * - Verify preconditions for other operations
+   * 
+   * Condition checks are particularly useful for:
+   * - Implementing optimistic locking
+   * - 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) {
+    this.checkForDuplicateItem(tableName, key);
+    const { expression, names, values } = prepareExpressionParams(condition);
+    if (!expression) {
+      throw new Error("Failed to generate condition expression");
     }
+    const transactionItem = {
+      type: "ConditionCheck",
+      params: {
+        tableName,
+        key: {
+          pk: key.pk,
+          sk: key.sk
+        },
+        conditionExpression: expression,
+        expressionAttributeNames: names,
+        expressionAttributeValues: values
+      }
+    };
+    this.items.push(transactionItem);
+    return this;
+  }
+  /**
+   * Adds a pre-configured condition check operation to the transaction.
+   * Use this method when you need to:
+   * - Reuse condition checks from ConditionCheckBuilder
+   * - Add complex condition checks with pre-configured parameters
+   * - Integrate with existing condition check configurations
+   * 
+   * This method is particularly useful when working with ConditionCheckBuilder
+   * to maintain consistency in condition checks across your application.
+   * 
+   * @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) {
+    this.checkForDuplicateItem(command.tableName, command.key);
+    const transactionItem = {
+      type: "ConditionCheck",
+      params: command
+    };
+    this.items.push(transactionItem);
+    return this;
+  }
+  /**
+   * Sets options for the transaction execution.
+   * Use this method when you need to:
+   * - Enable idempotent transactions
+   * - Track consumed capacity
+   * - Monitor item collection metrics
+   * 
+   * @example
+   * ```typescript
+   * // 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.
+   * Use this method when you need to:
+   * - Debug complex transactions
+   * - Verify operation parameters
+   * - Log transaction details
+   * - Troubleshoot condition expressions
+   * 
+   * The method resolves all expression placeholders with their actual values,
+   * making it easier to understand the transaction's operations.
+   * 
+   * @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.
+   * Use this method when you need to:
+   * - Perform multiple operations atomically
+   * - Ensure all-or-nothing execution
+   * - Maintain data consistency across operations
+   * 
+   * The transaction will only succeed if all operations succeed.
+   * If any operation fails, the entire transaction is rolled back.
+   * 
+   * @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 {
-      const params = this.converter.toTransactWriteCommand(items);
-      return await this.withRetry(() => this.client.transactWrite(params));
+      await this.executor(params);
     } catch (error) {
-      handleDynamoError(error, {
-        operation: "TRANSACT_WRITE",
-        tableName: this.tableName
-      });
+      console.log(this.debug());
+      console.error("Error executing transaction:", error);
+      throw error;
     }
   }
-  async executeWithAutoPagination(options) {
-    const allItems = [];
-    let lastEvaluatedKey;
-    do {
-      const result = await this.query({
-        ...options,
-        pageKey: lastEvaluatedKey,
-        autoPaginate: false
-      });
-      if (result.Items) {
-        allItems.push(...result.Items);
-      }
-      lastEvaluatedKey = result.LastEvaluatedKey;
-    } while (lastEvaluatedKey);
+};
+
+// 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/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.
+   * Use this method when you need to:
+   * - Validate complex item states
+   * - Check multiple attributes together
+   * - Ensure safety conditions are met
+   * 
+   * @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 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,
+        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 {
-      Items: allItems,
-      Count: allItems.length,
-      ScannedCount: allItems.length,
-      LastEvaluatedKey: void 0
+      tableName: this.tableName,
+      key: this.key,
+      conditionExpression: expression,
+      expressionAttributeNames: names,
+      expressionAttributeValues: values
     };
   }
-  async processBatchWrite(items) {
-    const processUnprocessedItems = async (unprocessedItems2) => {
-      const params2 = this.converter.toBatchWriteCommand(unprocessedItems2);
-      const result = await this.client.batchWrite(params2);
-      if (result.UnprocessedItems?.[this.tableName]?.length) {
-        const remainingItems = this.converter.fromBatchWriteResponse(
-          result.UnprocessedItems[this.tableName]
-        );
-        throw {
-          name: "UnprocessedItemsError",
-          unprocessedItems: remainingItems
-        };
-      }
-      return result;
-    };
-    const params = this.converter.toBatchWriteCommand(items);
-    const initialResult = await this.client.batchWrite(params);
-    if (!initialResult.UnprocessedItems?.[this.tableName]?.length) {
-      return initialResult;
+  /**
+   * Adds this condition check operation to a transaction.
+   * Use this method when you need to:
+   * - Verify habitat safety before transfers
+   * - Ensure proper feeding conditions
+   * - Validate security protocols
+   *
+   * @example
+   * ```ts
+   * 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 unprocessedItems = this.converter.fromBatchWriteResponse(
-      initialResult.UnprocessedItems[this.tableName]
-    );
-    return this.withRetry(() => processUnprocessedItems(unprocessedItems));
-  }
-  async withRetry(operation, strategy = new ExponentialBackoffStrategy()) {
-    let attempt = 0;
-    while (true) {
-      try {
-        return await operation();
-      } catch (error) {
-        if (!strategy.shouldRetry(error, attempt)) {
-          throw error;
-        }
-        await new Promise(
-          (resolve) => setTimeout(resolve, strategy.getDelay(attempt))
-        );
-        attempt++;
+    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.
+   * Use this method when you need to:
+   * - Debug complex condition expressions
+   * - Verify condition parameters
+   * - Log safety checks
+   * - Troubleshoot condition failures
+   *
+   * @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.
+   * Use this method when you need to:
+   * - Reduce data transfer by selecting specific dinosaur attributes
+   * - Optimize response size for dinosaur records
+   * - Focus on relevant dinosaur characteristics only
+   *
+   * @example
+   * ```typescript
+   * // 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;
   }
-  chunkArray(array, size) {
-    return Array.from(
-      { length: Math.ceil(array.length / size) },
-      (_, index) => array.slice(index * size, (index + 1) * size)
-    );
+  /**
+   * 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() {
+    if (this.selectedFields.size > 0) {
+      const expressionAttributeNames = {};
+      const projectionParts = [];
+      for (const path of this.selectedFields) {
+        const attrName = `#attr${projectionParts.length}`;
+        expressionAttributeNames[attrName] = path;
+        projectionParts.push(attrName);
+      }
+      this.params.projectionExpression = projectionParts.join(", ");
+      this.params.expressionAttributeNames = expressionAttributeNames;
+    }
+    return this.executor(this.params);
   }
 };
 
 // src/table.ts
+var DDB_BATCH_WRITE_LIMIT = 25;
+var DDB_BATCH_GET_LIMIT = 100;
 var Table = class {
-  dynamoService;
-  expressionBuilder;
-  indexes;
-  constructor({
-    client,
-    tableName,
-    tableIndexes,
-    expressionBuilder
-  }) {
-    this.dynamoService = new DynamoService(client, tableName);
-    this.expressionBuilder = expressionBuilder ?? new ExpressionBuilder();
-    this.indexes = tableIndexes;
-  }
-  getIndexConfig(indexName) {
-    if (!indexName) {
-      return this.indexes.primary;
-    }
-    if (this.indexes[indexName]) {
-      return this.indexes[indexName];
-    }
-    throw new Error(`Index ${indexName} does not exist`);
+  dynamoClient;
+  tableName;
+  partitionKey;
+  sortKey;
+  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 || {};
+  }
+  /**
+   * Creates a new item in the table, it will fail if the item already exists
+   *
+   * @param item The item to create
+   * @returns A PutBuilder instance for chaining conditions and executing the put operation
+   */
+  create(item) {
+    return this.put(item).condition((op) => op.attributeNotExists(this.partitionKey));
   }
+  get(keyCondition) {
+    const executor = async (params) => {
+      try {
+        const result = await this.dynamoClient.get({
+          TableName: params.tableName,
+          Key: params.key,
+          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) {
-    return new PutBuilder(
-      item,
-      this.expressionBuilder,
-      (operation) => this.executeOperation(operation)
-    );
-  }
-  update(key, data) {
-    const builder = new UpdateBuilder(
-      key,
-      this.expressionBuilder,
-      (operation) => this.executeOperation(operation)
-    );
-    if (data) {
-      builder.setMany(data);
-    }
-    return builder;
-  }
-  query(key) {
-    return new QueryBuilder(
-      key,
-      this.getIndexConfig(),
-      this.expressionBuilder,
-      (operation) => this.executeOperation(operation)
-    );
-  }
-  async get(key, options) {
-    const indexConfig = this.getIndexConfig(options?.indexName);
-    const keyObject = this.buildKeyFromIndex(key, indexConfig);
-    const result = await this.dynamoService.get(keyObject, options);
-    return result.Item;
-  }
-  async delete(key) {
-    const operation = {
-      type: "delete",
-      key
+    const executor = async (params) => {
+      try {
+        await this.dynamoClient.put({
+          TableName: params.tableName,
+          Item: params.item,
+          ConditionExpression: params.conditionExpression,
+          ExpressionAttributeNames: params.expressionAttributeNames,
+          ExpressionAttributeValues: params.expressionAttributeValues,
+          ReturnValues: params.returnValues
+        });
+        return params.item;
+      } catch (error) {
+        console.error("Error creating item:", error);
+        throw error;
+      }
     };
-    return this.executeOperation(operation);
-  }
-  async scan(filters, options) {
-    let filter = void 0;
-    if (filters?.length) {
-      const filterResult = this.expressionBuilder.createExpression(filters);
-      filter = {
-        expression: filterResult.expression,
-        names: filterResult.attributes.names,
-        values: filterResult.attributes.values
+    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 = "pk";
+    const skAttributeName = "sk";
+    let keyConditionExpression = eq(pkAttributeName, keyCondition.pk);
+    if (keyCondition.sk) {
+      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);
     }
-    return this.dynamoService.scan({
-      filter,
-      limit: options?.limit,
-      pageKey: options?.pageKey,
-      indexName: options?.indexName
-    });
-  }
-  async batchWrite(operations) {
-    const batchOperation = {
-      type: "batchWrite",
-      operations: operations.map((op) => {
-        if (op.type === "put") {
-          return { put: op.item };
+    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");
         }
-        return { delete: op.key };
-      })
+        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 this.executeOperation(batchOperation);
+    return new QueryBuilder(executor, keyConditionExpression);
   }
-  async transactWrite(operations) {
-    const transactOperation = {
-      type: "transactWrite",
-      operations
-    };
-    return this.executeOperation(transactOperation);
-  }
-  async executeOperation(operation) {
-    switch (operation.type) {
-      case "put":
-        return this.dynamoService.put({
-          item: operation.item,
-          condition: operation.condition
-        });
-      case "update":
-        return this.dynamoService.update({
-          key: operation.key,
-          update: operation.update,
-          condition: operation.condition,
-          returnValues: "ALL_NEW"
-        });
-      case "query":
-        return this.dynamoService.query({
-          keyCondition: operation.keyCondition,
-          filter: operation.filter,
-          limit: operation.limit,
-          indexName: operation.indexName
-        });
-      case "delete":
-        return this.dynamoService.delete({
-          key: operation.key
+  delete(keyCondition) {
+    const executor = async (params) => {
+      try {
+        const result = await this.dynamoClient.delete({
+          TableName: params.tableName,
+          Key: params.key,
+          ConditionExpression: params.conditionExpression,
+          ExpressionAttributeNames: params.expressionAttributeNames,
+          ExpressionAttributeValues: params.expressionAttributeValues,
+          ReturnValues: params.returnValues
         });
-      case "batchWrite":
-        return this.dynamoService.batchWrite(operation.operations);
-      case "transactWrite":
-        return this.dynamoService.transactWrite(operation.operations);
-      default:
-        throw new Error("Unknown operation type");
-    }
+        return {
+          item: result.Attributes
+        };
+      } catch (error) {
+        console.error("Error deleting item:", error);
+        throw error;
+      }
+    };
+    return new DeleteBuilder(executor, this.tableName, keyCondition);
   }
-  buildKeyFromIndex(key, indexConfig) {
-    this.validateKey(key, indexConfig);
-    const keyObject = {
-      [indexConfig.pkName]: key.pk
+  /**
+   * 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: params.key,
+          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;
+      }
     };
-    if (indexConfig.skName && key.sk) {
-      keyObject[indexConfig.skName] = key.sk;
-    }
-    return keyObject;
+    return new UpdateBuilder(executor, this.tableName, keyCondition);
   }
-  validateKey(key, indexConfig) {
-    if (!key.pk) {
-      throw new Error("Partition key is required");
-    }
-    if (key.sk && !indexConfig.skName) {
-      throw new Error("Sort key provided but index does not support sort keys");
-    }
-    if (!key.sk && indexConfig.skName) {
-      throw new Error("Index requires a sort key but none was provided");
-    }
+  /**
+   * 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
+    });
   }
-};
-
-// src/repository/base-repository.ts
-var BaseRepository = class {
-  constructor(table, schema) {
-    this.table = table;
-    this.schema = schema;
-  }
-  beforeInsert(data) {
-    return data;
-  }
-  beforeUpdate(data) {
-    return data;
-  }
-  async create(data) {
-    const parsed = this.schema.parse(data);
-    const key = this.createPrimaryKey(parsed);
-    const item = {
-      ...parsed,
-      ...key
+  /**
+   * 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
+   */
+  transaction(callback, options) {
+    const executor = async () => {
+      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;
     };
-    const indexConfig = this.table.getIndexConfig();
-    await this.table.put(item).whereNotExists(indexConfig.pkName).execute();
-    return parsed;
-  }
-  async update(key, updates) {
-    const parsed = this.schema.parse(updates);
-    const result = await this.table.update(key).setMany(parsed).execute();
-    return result.Attributes ? this.schema.parse(result.Attributes) : null;
-  }
-  async delete(key) {
-    await this.table.delete(key);
-  }
-  async findOne(key) {
-    const item = await this.table.query(key).where(this.getTypeAttributeName(), "=", this.getType()).execute();
-    if (!item) {
-      return null;
-    }
-    return this.schema.parse(item);
+    return executor();
+  }
+  /**
+   * 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);
   }
-  async findOrFail(key) {
-    const result = await this.findOne(key);
-    if (!result) {
-      throw new Error("Item not found");
+  /**
+   * 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) => ({
+        pk: key.pk,
+        sk: 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.pk,
+          sk: key.sk
+        }));
+        if (unprocessedKeys.length > 0) {
+          allUnprocessedKeys.push(...unprocessedKeys);
+        }
+      } catch (error) {
+        console.error("Error in batch get operation:", error);
+        throw error;
+      }
     }
-    return this.schema.parse(result);
+    return {
+      items: allItems,
+      unprocessedKeys: allUnprocessedKeys
+    };
   }
-  query(key) {
-    return this.table.query(key).where(this.getTypeAttributeName(), "=", this.getType());
+  /**
+   * 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: {
+              pk: operation.key.pk,
+              sk: operation.key.sk
+            }
+          }
+        };
+      });
+      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.pk,
+                  sk: request.DeleteRequest.Key.sk
+                }
+              };
+            }
+            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
+    };
   }
 };
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  BaseRepository,
-  ConditionalCheckFailedError,
-  DynamoError,
-  ExponentialBackoffStrategy,
-  ResourceNotFoundError,
-  Table
-});
+export {
+  ConditionCheckBuilder,
+  DeleteBuilder,
+  Paginator,
+  PutBuilder,
+  QueryBuilder,
+  Table,
+  TransactionBuilder,
+  UpdateBuilder,
+  and,
+  attributeExists,
+  attributeNotExists,
+  beginsWith,
+  between,
+  contains,
+  eq,
+  gt,
+  gte,
+  lt,
+  lte,
+  ne,
+  not,
+  or
+};