dyno-table 1.0.0-alpha.1 → 1.0.0

package/dist/builders/paginator.js

@@ -0,0 +1,197 @@
+// src/builders/paginator.ts
+var Paginator = class {
+  queryBuilder;
+  pageSize;
+  currentPage = 0;
+  lastEvaluatedKey;
+  hasMorePages = true;
+  totalItemsRetrieved = 0;
+  overallLimit;
+  constructor(queryBuilder, pageSize) {
+    this.queryBuilder = queryBuilder;
+    this.pageSize = pageSize;
+    this.overallLimit = queryBuilder.getLimit();
+  }
+  /**
+   * Gets the current page number (1-indexed).
+   * 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;
+  }
+  /**
+   * 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;
+  }
+  /**
+   * 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 {
+      items: result.items,
+      lastEvaluatedKey: result.lastEvaluatedKey,
+      hasNextPage: this.hasNextPage(),
+      page: this.currentPage
+    };
+  }
+  /**
+   * Gets all remaining dinosaurs or habitats and combines them into a single array.
+   * 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;
+  }
+};
+
+export { Paginator };
+//# sourceMappingURL=paginator.js.map
+//# sourceMappingURL=paginator.js.map

package/dist/builders/paginator.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/builders/paginator.ts"],"names":[],"mappings":";AAqCO,IAAM,YAAN,MAAiF;AAAA,EAC9E,YAAA;AAAA,EACS,QAAA;AAAA,EACT,WAAc,GAAA,CAAA;AAAA,EACd,gBAAA;AAAA,EACA,YAAe,GAAA,IAAA;AAAA,EACf,mBAAsB,GAAA,CAAA;AAAA,EACb,YAAA;AAAA,EAEjB,WAAA,CAAY,cAAiD,QAAkB,EAAA;AAC7E,IAAA,IAAA,CAAK,YAAe,GAAA,YAAA;AACpB,IAAA,IAAA,CAAK,QAAW,GAAA,QAAA;AAEhB,IAAK,IAAA,CAAA,YAAA,GAAe,aAAa,QAAS,EAAA;AAAA;AAC5C;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAoBO,cAAyB,GAAA;AAC9B,IAAA,OAAO,IAAK,CAAA,WAAA;AAAA;AACd;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAgCO,WAAuB,GAAA;AAE5B,IAAA,IAAI,KAAK,YAAiB,KAAA,KAAA,CAAA,IAAa,IAAK,CAAA,mBAAA,IAAuB,KAAK,YAAc,EAAA;AACpF,MAAO,OAAA,KAAA;AAAA;AAET,IAAA,OAAO,IAAK,CAAA,YAAA;AAAA;AACd;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EA0CA,MAAa,WAA4C,GAAA;AACvD,IAAI,IAAA,CAAC,IAAK,CAAA,WAAA,EAAe,EAAA;AACvB,MAAO,OAAA;AAAA,QACL,OAAO,EAAC;AAAA,QACR,WAAa,EAAA,KAAA;AAAA,QACb,MAAM,IAAK,CAAA;AAAA,OACb;AAAA;AAIF,IAAA,IAAI,oBAAoB,IAAK,CAAA,QAAA;AAG7B,IAAI,IAAA,IAAA,CAAK,iBAAiB,KAAW,CAAA,EAAA;AACnC,MAAM,MAAA,cAAA,GAAiB,IAAK,CAAA,YAAA,GAAe,IAAK,CAAA,mBAAA;AAChD,MAAA,IAAI,kBAAkB,CAAG,EAAA;AACvB,QAAO,OAAA;AAAA,UACL,OAAO,EAAC;AAAA,UACR,WAAa,EAAA,KAAA;AAAA,UACb,MAAM,IAAK,CAAA;AAAA,SACb;AAAA;AAEF,MAAoB,iBAAA,GAAA,IAAA,CAAK,GAAI,CAAA,iBAAA,EAAmB,cAAc,CAAA;AAAA;AAIhE,IAAA,MAAM,QAAQ,IAAK,CAAA,YAAA,CAAa,KAAM,EAAA,CAAE,MAAM,iBAAiB,CAAA;AAG/D,IAAA,IAAI,KAAK,gBAAkB,EAAA;AACzB,MAAM,KAAA,CAAA,SAAA,CAAU,KAAK,gBAAgB,CAAA;AAAA;AAIvC,IAAM,MAAA,MAAA,GAAS,MAAM,KAAA,CAAM,OAAQ,EAAA;AAGnC,IAAA,IAAA,CAAK,WAAe,IAAA,CAAA;AACpB,IAAA,IAAA,CAAK,mBAAmB,MAAO,CAAA,gBAAA;AAC/B,IAAK,IAAA,CAAA,mBAAA,IAAuB,OAAO,KAAM,CAAA,MAAA;AAMzC,IAAK,IAAA,CAAA,YAAA,GACH,CAAC,CAAC,MAAO,CAAA,gBAAA,KAAqB,KAAK,YAAiB,KAAA,KAAA,CAAA,IAAa,IAAK,CAAA,mBAAA,GAAsB,IAAK,CAAA,YAAA,CAAA;AAEnG,IAAO,OAAA;AAAA,MACL,OAAO,MAAO,CAAA,KAAA;AAAA,MACd,kBAAkB,MAAO,CAAA,gBAAA;AAAA,MACzB,WAAA,EAAa,KAAK,WAAY,EAAA;AAAA,MAC9B,MAAM,IAAK,CAAA;AAAA,KACb;AAAA;AACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAuCA,MAAa,WAA4B,GAAA;AACvC,IAAA,MAAM,WAAgB,EAAC;AAEvB,IAAO,OAAA,IAAA,CAAK,aAAe,EAAA;AACzB,MAAM,MAAA,MAAA,GAAS,MAAM,IAAA,CAAK,WAAY,EAAA;AACtC,MAAS,QAAA,CAAA,IAAA,CAAK,GAAG,MAAA,CAAO,KAAK,CAAA;AAAA;AAG/B,IAAO,OAAA,QAAA;AAAA;AAEX","file":"paginator.js","sourcesContent":["import type { DynamoItem, TableConfig } from \"../types\";\nimport type { PaginationResult, QueryBuilderInterface } from \"./builder-types\";\n\n/**\n * A utility class for handling DynamoDB pagination.\n * Use this class when you need to:\n * - Browse large collections of dinosaurs\n * - Review extensive security logs\n * - Analyze habitat inspection history\n * - Process feeding schedules\n *\n * The paginator maintains internal state and automatically handles:\n * - Page boundaries\n * - Result set limits\n * - Continuation tokens\n *\n * @example\n * ```typescript\n * // List all velociraptors with pagination\n * const paginator = new QueryBuilder(executor, eq('species', 'Velociraptor'))\n *   .filter(op => op.eq('status', 'ACTIVE'))\n *   .paginate(10);\n *\n * // Process each page of dinosaurs\n * while (paginator.hasNextPage()) {\n *   const page = await paginator.getNextPage();\n *   console.log(`Processing page ${page.page} of velociraptors`);\n *\n *   for (const raptor of page.items) {\n *     console.log(`- ${raptor.id}: Health=${raptor.stats.health}`);\n *   }\n * }\n * ```\n *\n * @typeParam T - The type of items being paginated\n * @typeParam TConfig - The table configuration type\n */\nexport class Paginator<T extends DynamoItem, TConfig extends TableConfig = TableConfig> {\n  private queryBuilder: QueryBuilderInterface<T, TConfig>;\n  private readonly pageSize: number;\n  private currentPage = 0;\n  private lastEvaluatedKey?: DynamoItem;\n  private hasMorePages = true;\n  private totalItemsRetrieved = 0;\n  private readonly overallLimit?: number;\n\n  constructor(queryBuilder: QueryBuilderInterface<T, TConfig>, pageSize: number) {\n    this.queryBuilder = queryBuilder;\n    this.pageSize = pageSize;\n    // Store the overall limit from the query builder if it exists\n    this.overallLimit = queryBuilder.getLimit();\n  }\n\n  /**\n   * Gets the current page number (1-indexed).\n   * Use this method when you need to:\n   * - Track progress through dinosaur lists\n   * - Display habitat inspection status\n   * - Monitor security sweep progress\n   *\n   * @example\n   * ```ts\n   * const paginator = new QueryBuilder(executor, eq('species', 'Tyrannosaurus'))\n   *   .paginate(5);\n   *\n   * await paginator.getNextPage();\n   * console.log(`Reviewing T-Rex group ${paginator.getCurrentPage()}`);\n   * ```\n   *\n   * @returns The current page number, starting from 1\n   */\n  public getCurrentPage(): number {\n    return this.currentPage;\n  }\n\n  /**\n   * Checks if there are more pages of dinosaurs or habitats to process.\n   * Use this method when you need to:\n   * - Check for more dinosaurs to review\n   * - Continue habitat inspections\n   * - Process security incidents\n   * - Complete feeding schedules\n   *\n   * This method takes into account both:\n   * - DynamoDB's lastEvaluatedKey mechanism\n   * - Any overall limit set on the query\n   *\n   * @example\n   * ```ts\n   * // Process all security incidents\n   * const paginator = new QueryBuilder(executor, eq('type', 'SECURITY_BREACH'))\n   *   .sortDescending()\n   *   .paginate(10);\n   *\n   * while (paginator.hasNextPage()) {\n   *   const page = await paginator.getNextPage();\n   *   for (const incident of page.items) {\n   *     await processSecurityBreach(incident);\n   *   }\n   *   console.log(`Processed incidents page ${page.page}`);\n   * }\n   * ```\n   *\n   * @returns true if there are more pages available, false otherwise\n   */\n  public hasNextPage(): boolean {\n    // If we have an overall limit and we've already retrieved that many items, there are no more pages\n    if (this.overallLimit !== undefined && this.totalItemsRetrieved >= this.overallLimit) {\n      return false;\n    }\n    return this.hasMorePages;\n  }\n\n  /**\n   * Retrieves the next page of dinosaurs or habitats from DynamoDB.\n   * Use this method when you need to:\n   * - Process dinosaur groups systematically\n   * - Review habitat inspections in batches\n   * - Monitor security incidents in sequence\n   * - Schedule feeding rotations\n   *\n   * This method handles:\n   * - Automatic continuation between groups\n   * - Respect for park capacity limits\n   * - Group size adjustments for safety\n   *\n   * @example\n   * ```ts\n   * const paginator = new QueryBuilder(executor, eq('species', 'Velociraptor'))\n   *   .filter(op => op.eq('status', 'ACTIVE'))\n   *   .paginate(5);\n   *\n   * // Check first raptor group\n   * const page1 = await paginator.getNextPage();\n   * console.log(`Found ${page1.items.length} active raptors`);\n   *\n   * // Continue inspection if more groups exist\n   * if (page1.hasNextPage) {\n   *   const page2 = await paginator.getNextPage();\n   *   console.log(`Inspecting raptor group ${page2.page}`);\n   *\n   *   for (const raptor of page2.items) {\n   *     await performHealthCheck(raptor);\n   *   }\n   * }\n   * ```\n   *\n   * @returns A promise that resolves to a PaginationResult containing:\n   *          - items: The dinosaurs/habitats for this page\n   *          - hasNextPage: Whether more groups exist\n   *          - page: The current group number\n   *          - lastEvaluatedKey: DynamoDB's continuation token\n   */\n  public async getNextPage(): Promise<PaginationResult<T>> {\n    if (!this.hasNextPage()) {\n      return {\n        items: [],\n        hasNextPage: false,\n        page: this.currentPage,\n      };\n    }\n\n    // Calculate how many items to fetch for this page\n    let effectivePageSize = this.pageSize;\n\n    // If we have an overall limit, make sure we don't fetch more than what's left\n    if (this.overallLimit !== undefined) {\n      const remainingItems = this.overallLimit - this.totalItemsRetrieved;\n      if (remainingItems <= 0) {\n        return {\n          items: [],\n          hasNextPage: false,\n          page: this.currentPage,\n        };\n      }\n      effectivePageSize = Math.min(effectivePageSize, remainingItems);\n    }\n\n    // Clone the query builder to avoid modifying the original\n    const query = this.queryBuilder.clone().limit(effectivePageSize);\n\n    // Apply the last evaluated key if we have one\n    if (this.lastEvaluatedKey) {\n      query.startFrom(this.lastEvaluatedKey);\n    }\n\n    // Execute the query\n    const result = await query.execute();\n\n    // Update pagination state\n    this.currentPage += 1;\n    this.lastEvaluatedKey = result.lastEvaluatedKey;\n    this.totalItemsRetrieved += result.items.length;\n\n    // Determine if there are more pages\n    // We have more pages if:\n    // 1. DynamoDB returned a lastEvaluatedKey AND\n    // 2. We haven't hit our overall limit (if one exists)\n    this.hasMorePages =\n      !!result.lastEvaluatedKey && (this.overallLimit === undefined || this.totalItemsRetrieved < this.overallLimit);\n\n    return {\n      items: result.items,\n      lastEvaluatedKey: result.lastEvaluatedKey,\n      hasNextPage: this.hasNextPage(),\n      page: this.currentPage,\n    };\n  }\n\n  /**\n   * Gets all remaining dinosaurs or habitats and combines them into a single array.\n   * Use this method when you need to:\n   * - Generate complete park inventory\n   * - Perform full security audit\n   * - Create comprehensive feeding schedule\n   * - Run park-wide health checks\n   *\n   * Note: Use with caution! This method:\n   * - Could overwhelm systems with large dinosaur populations\n   * - Makes multiple database requests\n   * - May cause system strain during peak hours\n   *\n   * @example\n   * ```ts\n   * // Get complete carnivore inventory\n   * const paginator = new QueryBuilder(executor, eq('diet', 'CARNIVORE'))\n   *   .filter(op => op.eq('status', 'ACTIVE'))\n   *   .paginate(10);\n   *\n   * try {\n   *   const allCarnivores = await paginator.getAllPages();\n   *   console.log(`Park contains ${allCarnivores.length} active carnivores`);\n   *\n   *   // Calculate total threat level\n   *   const totalThreat = allCarnivores.reduce(\n   *     (sum, dino) => sum + dino.stats.threatLevel,\n   *     0\n   *   );\n   *   console.log(`Total threat level: ${totalThreat}`);\n   * } catch (error) {\n   *   console.error('Failed to complete carnivore census:', error);\n   * }\n   * ```\n   *\n   * @returns A promise that resolves to an array containing all remaining items\n   */\n  public async getAllPages(): Promise<T[]> {\n    const allItems: T[] = [];\n\n    while (this.hasNextPage()) {\n      const result = await this.getNextPage();\n      allItems.push(...result.items);\n    }\n\n    return allItems;\n  }\n}\n"]}

package/dist/builders/put-builder.cjs

@@ -0,0 +1,476 @@
+'use strict';
+
+// 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
+});
+
+// src/expression.ts
+var generateAttributeName = (params, attr) => {
+  for (const [existingName, existingAttr] of Object.entries(params.expressionAttributeNames)) {
+    if (existingAttr === attr) {
+      return existingName;
+    }
+  }
+  const attrName = `#${Object.keys(params.expressionAttributeNames).length}`;
+  params.expressionAttributeNames[attrName] = attr;
+  return attrName;
+};
+var generateValueName = (params, value) => {
+  const valueName = `:${params.valueCounter.count++}`;
+  params.expressionAttributeValues[valueName] = value;
+  return valueName;
+};
+var validateCondition = (condition, requiresAttr = true, requiresValue = true) => {
+  if (requiresAttr && !condition.attr) {
+    throw new Error(`Attribute is required for ${condition.type} condition`);
+  }
+  if (requiresValue && condition.value === void 0) {
+    throw new Error(`Value is required for ${condition.type} condition`);
+  }
+};
+var buildComparisonExpression = (condition, operator, params) => {
+  validateCondition(condition);
+  if (!condition.attr) {
+    throw new Error(`Attribute is required for ${condition.type} condition`);
+  }
+  const attrName = generateAttributeName(params, condition.attr);
+  const valueName = generateValueName(params, condition.value);
+  return `${attrName} ${operator} ${valueName}`;
+};
+var buildBetweenExpression = (condition, params) => {
+  validateCondition(condition);
+  if (!condition.attr) {
+    throw new Error(`Attribute is required for ${condition.type} condition`);
+  }
+  if (!Array.isArray(condition.value) || condition.value.length !== 2) {
+    throw new Error("Between condition requires an array of two values");
+  }
+  const attrName = generateAttributeName(params, condition.attr);
+  const lowerName = generateValueName(params, condition.value[0]);
+  const upperName = generateValueName(params, condition.value[1]);
+  return `${attrName} BETWEEN ${lowerName} AND ${upperName}`;
+};
+var buildFunctionExpression = (functionName, condition, params) => {
+  validateCondition(condition);
+  if (!condition.attr) {
+    throw new Error(`Attribute is required for ${condition.type} condition`);
+  }
+  const attrName = generateAttributeName(params, condition.attr);
+  const valueName = generateValueName(params, condition.value);
+  return `${functionName}(${attrName}, ${valueName})`;
+};
+var buildAttributeFunction = (functionName, condition, params) => {
+  validateCondition(condition, true, false);
+  if (!condition.attr) {
+    throw new Error(`Attribute is required for ${condition.type} condition`);
+  }
+  const attrName = generateAttributeName(params, condition.attr);
+  return `${functionName}(${attrName})`;
+};
+var buildLogicalExpression = (operator, conditions, params) => {
+  if (!conditions || conditions.length === 0) {
+    throw new Error(`At least one condition is required for ${operator} expression`);
+  }
+  const expressions = conditions.map((c) => buildExpression(c, params));
+  return `(${expressions.join(` ${operator} `)})`;
+};
+var buildExpression = (condition, params) => {
+  if (!condition) return "";
+  try {
+    const expressionBuilders = {
+      eq: () => buildComparisonExpression(condition, "=", params),
+      ne: () => buildComparisonExpression(condition, "<>", params),
+      lt: () => buildComparisonExpression(condition, "<", params),
+      lte: () => buildComparisonExpression(condition, "<=", params),
+      gt: () => buildComparisonExpression(condition, ">", params),
+      gte: () => buildComparisonExpression(condition, ">=", params),
+      between: () => buildBetweenExpression(condition, params),
+      beginsWith: () => buildFunctionExpression("begins_with", condition, params),
+      contains: () => buildFunctionExpression("contains", condition, params),
+      attributeExists: () => buildAttributeFunction("attribute_exists", condition, params),
+      attributeNotExists: () => buildAttributeFunction("attribute_not_exists", condition, params),
+      and: () => {
+        if (!condition.conditions) {
+          throw new Error("Conditions array is required for AND operator");
+        }
+        return buildLogicalExpression("AND", condition.conditions, params);
+      },
+      or: () => {
+        if (!condition.conditions) {
+          throw new Error("Conditions array is required for OR operator");
+        }
+        return buildLogicalExpression("OR", condition.conditions, params);
+      },
+      not: () => {
+        if (!condition.condition) {
+          throw new Error("Condition is required for NOT operator");
+        }
+        return `NOT (${buildExpression(condition.condition, params)})`;
+      }
+    };
+    const builder = expressionBuilders[condition.type];
+    if (!builder) {
+      throw new Error(`Unknown condition type: ${condition.type}`);
+    }
+    return builder();
+  } catch (error) {
+    if (error instanceof Error) {
+      console.error(`Error building expression for condition type ${condition.type}:`, error.message);
+    } else {
+      console.error(`Error building expression for condition type ${condition.type}:`, error);
+    }
+    throw error;
+  }
+};
+var prepareExpressionParams = (condition) => {
+  if (!condition) return {};
+  const params = {
+    expressionAttributeNames: {},
+    expressionAttributeValues: {},
+    valueCounter: { count: 0 }
+  };
+  const expression = buildExpression(condition, params);
+  return {
+    expression,
+    names: Object.keys(params.expressionAttributeNames).length > 0 ? params.expressionAttributeNames : void 0,
+    values: Object.keys(params.expressionAttributeValues).length > 0 ? params.expressionAttributeValues : void 0
+  };
+};
+
+// src/utils/debug-expression.ts
+function debugCommand(command) {
+  const result = {};
+  function replaceAliases(expressionString) {
+    if (!expressionString) {
+      return expressionString;
+    }
+    let replacedString = expressionString;
+    for (const alias in command.expressionAttributeNames) {
+      const attributeName = command.expressionAttributeNames[alias];
+      const regex = new RegExp(alias, "g");
+      replacedString = replacedString.replace(regex, attributeName);
+    }
+    for (const alias in command.expressionAttributeValues) {
+      let attributeValue = command.expressionAttributeValues[alias];
+      if (attributeValue instanceof Set) {
+        const array = Array.from(attributeValue);
+        attributeValue = `Set(${array.length}){${array.map((v) => JSON.stringify(v)).join(", ")}}`;
+      } else {
+        attributeValue = JSON.stringify(attributeValue);
+      }
+      const regex = new RegExp(alias, "g");
+      replacedString = replacedString.replace(regex, attributeValue);
+    }
+    return replacedString;
+  }
+  if (command.updateExpression) {
+    result.updateExpression = replaceAliases(command.updateExpression);
+  }
+  if (command.conditionExpression) {
+    result.conditionExpression = replaceAliases(command.conditionExpression);
+  }
+  if (command.filterExpression) {
+    result.filterExpression = replaceAliases(command.filterExpression);
+  }
+  if (command.keyConditionExpression) {
+    result.keyConditionExpression = replaceAliases(command.keyConditionExpression);
+  }
+  if (command.projectionExpression) {
+    result.projectionExpression = replaceAliases(command.projectionExpression);
+  }
+  return {
+    raw: command,
+    readable: result
+  };
+}
+
+// src/builders/put-builder.ts
+var PutBuilder = class {
+  item;
+  options;
+  executor;
+  tableName;
+  constructor(executor, item, tableName) {
+    this.executor = executor;
+    this.item = item;
+    this.tableName = tableName;
+    this.options = {
+      returnValues: "NONE"
+    };
+  }
+  set(valuesOrPath, value) {
+    if (typeof valuesOrPath === "object") {
+      Object.assign(this.item, valuesOrPath);
+    } else {
+      this.item[valuesOrPath] = value;
+    }
+    return this;
+  }
+  /**
+   * Adds a condition that must be satisfied for the put operation to succeed.
+   * 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
+   */
+  /**
+   * Adds a condition that must be satisfied for the put operation to succeed.
+   *
+   * @example
+   * ```typescript
+   * // Ensure unique dinosaur ID
+   * builder.condition(op =>
+   *   op.attributeNotExists('id')
+   * );
+   *
+   * // Verify habitat requirements
+   * builder.condition(op =>
+   *   op.and([
+   *     op.eq('securityStatus', 'READY'),
+   *     op.attributeExists('lastInspection'),
+   *     op.gt('securityLevel', 5)
+   *   ])
+   * );
+   *
+   * // Check breeding facility conditions
+   * builder.condition(op =>
+   *   op.and([
+   *     op.between('temperature', 25, 30),
+   *     op.between('humidity', 60, 80),
+   *     op.eq('quarantineStatus', 'CLEAR')
+   *   ])
+   * );
+   * ```
+   *
+   * @param condition - Either a Condition object or a callback function that builds the condition
+   * @returns The builder instance for method chaining
+   */
+  condition(condition) {
+    if (typeof condition === "function") {
+      const conditionOperator = {
+        eq,
+        ne,
+        lt,
+        lte,
+        gt,
+        gte,
+        between,
+        beginsWith,
+        contains,
+        attributeExists,
+        attributeNotExists,
+        and,
+        or,
+        not
+      };
+      this.options.condition = condition(conditionOperator);
+    } else {
+      this.options.condition = condition;
+    }
+    return this;
+  }
+  /**
+   * Sets whether to return the item's previous values (if it existed).
+   *
+   * @options
+   *  - NONE: No return value
+   *  - ALL_OLD: Returns the item's previous state if it existed, no read capacity units are consumed
+   *  - CONSISTENT: (default) Performs a GET operation after the put to retrieve the item's new state
+   *
+   * @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 if the item was overwritten, or 'NONE' (default).
+   * @returns The builder instance for method chaining
+   */
+  returnValues(returnValues) {
+    this.options.returnValues = returnValues;
+    return this;
+  }
+  /**
+   * Generate the DynamoDB command parameters
+   */
+  toDynamoCommand() {
+    const { expression, names, values } = prepareExpressionParams(this.options.condition);
+    return {
+      tableName: this.tableName,
+      item: this.item,
+      conditionExpression: expression,
+      expressionAttributeNames: names,
+      expressionAttributeValues: values,
+      returnValues: this.options.returnValues
+    };
+  }
+  /**
+   * Adds this put operation to a transaction.
+   * 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
+   */
+  withTransaction(transaction) {
+    const command = this.toDynamoCommand();
+    transaction.putWithCommand(command);
+    return this;
+  }
+  /**
+   * Executes the put operation against DynamoDB.
+   *
+   * @example
+   * ```ts
+   * try {
+   *   // Put with condition and return old values
+   *   const result = await new PutBuilder(executor, newItem, 'myTable')
+   *     .condition(op => op.eq('version', 1))
+   *     .returnValues('ALL_OLD')
+   *     .execute();
+   *
+   *   console.log('Put successful, old item:', result);
+   * } catch (error) {
+   *   // Handle condition check failure or other errors
+   *   console.error('Put failed:', error);
+   * }
+   * ```
+   *
+   * @returns A promise that resolves to the operation result (type depends on returnValues setting)
+   * @throws Will throw an error if the condition check fails or other DynamoDB errors occur
+   */
+  async execute() {
+    const params = this.toDynamoCommand();
+    return this.executor(params);
+  }
+  /**
+   * Gets a human-readable representation of the put command
+   * with all expression placeholders replaced by their actual values.
+   *
+   * @example
+   * ```ts
+   * const debugInfo = new PutBuilder(executor, {
+   *   id: 'RAPTOR-003',
+   *   species: 'Velociraptor',
+   *   status: 'QUARANTINE',
+   *   stats: {
+   *     health: 100,
+   *     aggressionLevel: 7,
+   *     age: 2
+   *   }
+   * }, 'dinosaurs')
+   *   .condition(op =>
+   *     op.and([
+   *       op.attributeNotExists('id'),
+   *       op.eq('quarantineStatus', 'READY'),
+   *       op.gt('securityLevel', 8)
+   *     ])
+   *   )
+   *   .debug();
+   *
+   * console.log('Dinosaur transfer command:', debugInfo);
+   * ```
+   *
+   * @returns A readable representation of the put command with resolved expressions
+   */
+  debug() {
+    const command = this.toDynamoCommand();
+    return debugCommand(command);
+  }
+};
+
+exports.PutBuilder = PutBuilder;
+//# sourceMappingURL=put-builder.cjs.map
+//# sourceMappingURL=put-builder.cjs.map