dyno-table 0.1.8 → 0.2.0-0

package/dist/builders/paginator.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/builders/paginator.ts"],"names":[],"mappings":"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","file":"paginator.js","sourcesContent":["import type { 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 Record<string, unknown>, TConfig extends TableConfig = TableConfig> {\n  private queryBuilder: QueryBuilderInterface<T, TConfig>;\n  private readonly pageSize: number;\n  private currentPage = 0;\n  private lastEvaluatedKey?: Record<string, unknown>;\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"]}
+{"version":3,"sources":["../../src/builders/paginator.ts"],"names":[],"mappings":"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","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

@@ -234,6 +234,14 @@ var PutBuilder = class {
       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:

package/dist/builders/put-builder.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/conditions.ts","../../src/expression.ts","../../src/utils/debug-expression.ts","../../src/builders/put-builder.ts"],"names":[],"mappings":";;;AA8FO,IAAM,yBACX,GAAA,CAAC,IACD,KAAA,CAAC,MAAc,KAA+B,MAAA;AAAA,EAC5C,IAAA;AAAA,EACA,IAAA;AAAA,EACA;AACF,CAAA,CAAA;AAQK,IAAM,EAAA,GAAK,0BAA0B,IAAI,CAAA;AAQzC,IAAM,EAAA,GAAK,0BAA0B,IAAI,CAAA;AAQzC,IAAM,EAAA,GAAK,0BAA0B,IAAI,CAAA;AAQzC,IAAM,GAAA,GAAM,0BAA0B,KAAK,CAAA;AAQ3C,IAAM,EAAA,GAAK,0BAA0B,IAAI,CAAA;AAQzC,IAAM,GAAA,GAAM,0BAA0B,KAAK,CAAA;AAQ3C,IAAM,OAAU,GAAA,CAAC,IAAc,EAAA,KAAA,EAAgB,KAA+B,MAAA;AAAA,EACnF,IAAM,EAAA,SAAA;AAAA,EACN,IAAA;AAAA,EACA,KAAA,EAAO,CAAC,KAAA,EAAO,KAAK;AACtB,CAAA,CAAA;AAQO,IAAM,UAAA,GAAa,0BAA0B,YAAY,CAAA;AAQzD,IAAM,QAAA,GAAW,0BAA0B,UAAU,CAAA;AAQrD,IAAM,eAAA,GAAkB,CAAC,IAA6B,MAAA;AAAA,EAC3D,IAAM,EAAA,iBAAA;AAAA,EACN;AACF,CAAA,CAAA;AAQO,IAAM,kBAAA,GAAqB,CAAC,IAA6B,MAAA;AAAA,EAC9D,IAAM,EAAA,oBAAA;AAAA,EACN;AACF,CAAA,CAAA;AAaO,IAAM,GAAA,GAAM,IAAI,UAAwC,MAAA;AAAA,EAC7D,IAAM,EAAA,KAAA;AAAA,EACN;AACF,CAAA,CAAA;AAWO,IAAM,EAAA,GAAK,IAAI,UAAwC,MAAA;AAAA,EAC5D,IAAM,EAAA,IAAA;AAAA,EACN;AACF,CAAA,CAAA;AAQO,IAAM,GAAA,GAAM,CAAC,SAAqC,MAAA;AAAA,EACvD,IAAM,EAAA,KAAA;AAAA,EACN;AACF,CAAA,CAAA;;;AC7OO,IAAM,qBAAA,GAAwB,CAAC,MAAA,EAA0B,IAAyB,KAAA;AAEvF,EAAW,KAAA,MAAA,CAAC,cAAc,YAAY,CAAA,IAAK,OAAO,OAAQ,CAAA,MAAA,CAAO,wBAAwB,CAAG,EAAA;AAC1F,IAAA,IAAI,iBAAiB,IAAM,EAAA;AACzB,MAAO,OAAA,YAAA;AAAA;AACT;AAIF,EAAA,MAAM,WAAW,CAAI,CAAA,EAAA,MAAA,CAAO,KAAK,MAAO,CAAA,wBAAwB,EAAE,MAAM,CAAA,CAAA;AACxE,EAAO,MAAA,CAAA,wBAAA,CAAyB,QAAQ,CAAI,GAAA,IAAA;AAC5C,EAAO,OAAA,QAAA;AACT,CAAA;AAEO,IAAM,iBAAA,GAAoB,CAAC,MAAA,EAA0B,KAA2B,KAAA;AACrF,EAAA,MAAM,SAAY,GAAA,CAAA,CAAA,EAAI,MAAO,CAAA,YAAA,CAAa,KAAO,EAAA,CAAA,CAAA;AACjD,EAAO,MAAA,CAAA,yBAAA,CAA0B,SAAS,CAAI,GAAA,KAAA;AAC9C,EAAO,OAAA,SAAA;AACT,CAAA;AAEA,IAAM,oBAAoB,CAAC,SAAA,EAAsB,YAAe,GAAA,IAAA,EAAM,gBAAgB,IAAe,KAAA;AACnG,EAAI,IAAA,YAAA,IAAgB,CAAC,SAAA,CAAU,IAAM,EAAA;AACnC,IAAA,MAAM,IAAI,KAAA,CAAM,CAA6B,0BAAA,EAAA,SAAA,CAAU,IAAI,CAAY,UAAA,CAAA,CAAA;AAAA;AAGzE,EAAI,IAAA,aAAA,IAAiB,SAAU,CAAA,KAAA,KAAU,KAAW,CAAA,EAAA;AAClD,IAAA,MAAM,IAAI,KAAA,CAAM,CAAyB,sBAAA,EAAA,SAAA,CAAU,IAAI,CAAY,UAAA,CAAA,CAAA;AAAA;AAEvE,CAAA;AAEA,IAAM,yBAA4B,GAAA,CAAC,SAAsB,EAAA,QAAA,EAAkB,MAAqC,KAAA;AAC9G,EAAA,iBAAA,CAAkB,SAAS,CAAA;AAE3B,EAAI,IAAA,CAAC,UAAU,IAAM,EAAA;AACnB,IAAA,MAAM,IAAI,KAAA,CAAM,CAA6B,0BAAA,EAAA,SAAA,CAAU,IAAI,CAAY,UAAA,CAAA,CAAA;AAAA;AAGzE,EAAA,MAAM,QAAW,GAAA,qBAAA,CAAsB,MAAQ,EAAA,SAAA,CAAU,IAAI,CAAA;AAC7D,EAAA,MAAM,SAAY,GAAA,iBAAA,CAAkB,MAAQ,EAAA,SAAA,CAAU,KAAK,CAAA;AAE3D,EAAA,OAAO,CAAG,EAAA,QAAQ,CAAI,CAAA,EAAA,QAAQ,IAAI,SAAS,CAAA,CAAA;AAC7C,CAAA;AAEA,IAAM,sBAAA,GAAyB,CAAC,SAAA,EAAsB,MAAqC,KAAA;AACzF,EAAA,iBAAA,CAAkB,SAAS,CAAA;AAE3B,EAAI,IAAA,CAAC,UAAU,IAAM,EAAA;AACnB,IAAA,MAAM,IAAI,KAAA,CAAM,CAA6B,0BAAA,EAAA,SAAA,CAAU,IAAI,CAAY,UAAA,CAAA,CAAA;AAAA;AAGzE,EAAI,IAAA,CAAC,MAAM,OAAQ,CAAA,SAAA,CAAU,KAAK,CAAK,IAAA,SAAA,CAAU,KAAM,CAAA,MAAA,KAAW,CAAG,EAAA;AACnE,IAAM,MAAA,IAAI,MAAM,mDAAmD,CAAA;AAAA;AAGrE,EAAA,MAAM,QAAW,GAAA,qBAAA,CAAsB,MAAQ,EAAA,SAAA,CAAU,IAAI,CAAA;AAC7D,EAAA,MAAM,YAAY,iBAAkB,CAAA,MAAA,EAAQ,SAAU,CAAA,KAAA,CAAM,CAAC,CAAC,CAAA;AAC9D,EAAA,MAAM,YAAY,iBAAkB,CAAA,MAAA,EAAQ,SAAU,CAAA,KAAA,CAAM,CAAC,CAAC,CAAA;AAE9D,EAAA,OAAO,CAAG,EAAA,QAAQ,CAAY,SAAA,EAAA,SAAS,QAAQ,SAAS,CAAA,CAAA;AAC1D,CAAA;AAEA,IAAM,uBAA0B,GAAA,CAAC,YAAsB,EAAA,SAAA,EAAsB,MAAqC,KAAA;AAChH,EAAA,iBAAA,CAAkB,SAAS,CAAA;AAE3B,EAAI,IAAA,CAAC,UAAU,IAAM,EAAA;AACnB,IAAA,MAAM,IAAI,KAAA,CAAM,CAA6B,0BAAA,EAAA,SAAA,CAAU,IAAI,CAAY,UAAA,CAAA,CAAA;AAAA;AAGzE,EAAA,MAAM,QAAW,GAAA,qBAAA,CAAsB,MAAQ,EAAA,SAAA,CAAU,IAAI,CAAA;AAC7D,EAAA,MAAM,SAAY,GAAA,iBAAA,CAAkB,MAAQ,EAAA,SAAA,CAAU,KAAK,CAAA;AAE3D,EAAA,OAAO,CAAG,EAAA,YAAY,CAAI,CAAA,EAAA,QAAQ,KAAK,SAAS,CAAA,CAAA,CAAA;AAClD,CAAA;AAEA,IAAM,sBAAyB,GAAA,CAAC,YAAsB,EAAA,SAAA,EAAsB,MAAqC,KAAA;AAC/G,EAAkB,iBAAA,CAAA,SAAA,EAAW,MAAM,KAAK,CAAA;AAExC,EAAI,IAAA,CAAC,UAAU,IAAM,EAAA;AACnB,IAAA,MAAM,IAAI,KAAA,CAAM,CAA6B,0BAAA,EAAA,SAAA,CAAU,IAAI,CAAY,UAAA,CAAA,CAAA;AAAA;AAGzE,EAAA,MAAM,QAAW,GAAA,qBAAA,CAAsB,MAAQ,EAAA,SAAA,CAAU,IAAI,CAAA;AAC7D,EAAO,OAAA,CAAA,EAAG,YAAY,CAAA,CAAA,EAAI,QAAQ,CAAA,CAAA,CAAA;AACpC,CAAA;AAEA,IAAM,sBAAyB,GAAA,CAAC,QAAkB,EAAA,UAAA,EAAyB,MAAqC,KAAA;AAC9G,EAAA,IAAI,CAAC,UAAA,IAAc,UAAW,CAAA,MAAA,KAAW,CAAG,EAAA;AAC1C,IAAA,MAAM,IAAI,KAAA,CAAM,CAA0C,uCAAA,EAAA,QAAQ,CAAa,WAAA,CAAA,CAAA;AAAA;AAGjF,EAAM,MAAA,WAAA,GAAc,WAAW,GAAI,CAAA,CAAC,MAAM,eAAgB,CAAA,CAAA,EAAG,MAAM,CAAC,CAAA;AACpE,EAAA,OAAO,IAAI,WAAY,CAAA,IAAA,CAAK,CAAI,CAAA,EAAA,QAAQ,GAAG,CAAC,CAAA,CAAA,CAAA;AAC9C,CAAA;AAEO,IAAM,eAAA,GAAkB,CAAC,SAAA,EAAsB,MAAqC,KAAA;AACzF,EAAI,IAAA,CAAC,WAAkB,OAAA,EAAA;AAEvB,EAAI,IAAA;AAEF,IAAA,MAAM,kBAAiF,GAAA;AAAA,MACrF,EAAI,EAAA,MAAM,yBAA0B,CAAA,SAAA,EAAW,KAAK,MAAM,CAAA;AAAA,MAC1D,EAAI,EAAA,MAAM,yBAA0B,CAAA,SAAA,EAAW,MAAM,MAAM,CAAA;AAAA,MAC3D,EAAI,EAAA,MAAM,yBAA0B,CAAA,SAAA,EAAW,KAAK,MAAM,CAAA;AAAA,MAC1D,GAAK,EAAA,MAAM,yBAA0B,CAAA,SAAA,EAAW,MAAM,MAAM,CAAA;AAAA,MAC5D,EAAI,EAAA,MAAM,yBAA0B,CAAA,SAAA,EAAW,KAAK,MAAM,CAAA;AAAA,MAC1D,GAAK,EAAA,MAAM,yBAA0B,CAAA,SAAA,EAAW,MAAM,MAAM,CAAA;AAAA,MAC5D,OAAS,EAAA,MAAM,sBAAuB,CAAA,SAAA,EAAW,MAAM,CAAA;AAAA,MACvD,UAAY,EAAA,MAAM,uBAAwB,CAAA,aAAA,EAAe,WAAW,MAAM,CAAA;AAAA,MAC1E,QAAU,EAAA,MAAM,uBAAwB,CAAA,UAAA,EAAY,WAAW,MAAM,CAAA;AAAA,MACrE,eAAiB,EAAA,MAAM,sBAAuB,CAAA,kBAAA,EAAoB,WAAW,MAAM,CAAA;AAAA,MACnF,kBAAoB,EAAA,MAAM,sBAAuB,CAAA,sBAAA,EAAwB,WAAW,MAAM,CAAA;AAAA,MAC1F,KAAK,MAAM;AACT,QAAI,IAAA,CAAC,UAAU,UAAY,EAAA;AACzB,UAAM,MAAA,IAAI,MAAM,+CAA+C,CAAA;AAAA;AAEjE,QAAA,OAAO,sBAAuB,CAAA,KAAA,EAAO,SAAU,CAAA,UAAA,EAAY,MAAM,CAAA;AAAA,OACnE;AAAA,MACA,IAAI,MAAM;AACR,QAAI,IAAA,CAAC,UAAU,UAAY,EAAA;AACzB,UAAM,MAAA,IAAI,MAAM,8CAA8C,CAAA;AAAA;AAEhE,QAAA,OAAO,sBAAuB,CAAA,IAAA,EAAM,SAAU,CAAA,UAAA,EAAY,MAAM,CAAA;AAAA,OAClE;AAAA,MACA,KAAK,MAAM;AACT,QAAI,IAAA,CAAC,UAAU,SAAW,EAAA;AACxB,UAAM,MAAA,IAAI,MAAM,wCAAwC,CAAA;AAAA;AAE1D,QAAA,OAAO,CAAQ,KAAA,EAAA,eAAA,CAAgB,SAAU,CAAA,SAAA,EAAW,MAAM,CAAC,CAAA,CAAA,CAAA;AAAA;AAC7D,KACF;AAEA,IAAM,MAAA,OAAA,GAAU,kBAAmB,CAAA,SAAA,CAAU,IAAI,CAAA;AACjD,IAAA,IAAI,CAAC,OAAS,EAAA;AACZ,MAAA,MAAM,IAAI,KAAA,CAAM,CAA2B,wBAAA,EAAA,SAAA,CAAU,IAAI,CAAE,CAAA,CAAA;AAAA;AAG7D,IAAA,OAAO,OAAQ,EAAA;AAAA,WACR,KAAgB,EAAA;AACvB,IAAA,IAAI,iBAAiB,KAAO,EAAA;AAC1B,MAAA,OAAA,CAAQ,MAAM,CAAgD,6CAAA,EAAA,SAAA,CAAU,IAAI,CAAA,CAAA,CAAA,EAAK,MAAM,OAAO,CAAA;AAAA,KACzF,MAAA;AACL,MAAA,OAAA,CAAQ,KAAM,CAAA,CAAA,6CAAA,EAAgD,SAAU,CAAA,IAAI,KAAK,KAAK,CAAA;AAAA;AAExF,IAAM,MAAA,KAAA;AAAA;AAEV,CAAA;AAEO,IAAM,uBAAA,GAA0B,CACrC,SAKG,KAAA;AACH,EAAI,IAAA,CAAC,SAAW,EAAA,OAAO,EAAC;AAExB,EAAA,MAAM,MAA2B,GAAA;AAAA,IAC/B,0BAA0B,EAAC;AAAA,IAC3B,2BAA2B,EAAC;AAAA,IAC5B,YAAA,EAAc,EAAE,KAAA,EAAO,CAAE;AAAA,GAC3B;AAEA,EAAM,MAAA,UAAA,GAAa,eAAgB,CAAA,SAAA,EAAW,MAAM,CAAA;AAEpD,EAAO,OAAA;AAAA,IACL,UAAA;AAAA,IACA,KAAA,EAAO,OAAO,IAAK,CAAA,MAAA,CAAO,wBAAwB,CAAE,CAAA,MAAA,GAAS,CAAI,GAAA,MAAA,CAAO,wBAA2B,GAAA,KAAA,CAAA;AAAA,IACnG,MAAA,EAAQ,OAAO,IAAK,CAAA,MAAA,CAAO,yBAAyB,CAAE,CAAA,MAAA,GAAS,CAAI,GAAA,MAAA,CAAO,yBAA4B,GAAA,KAAA;AAAA,GACxG;AACF,CAAA;;;AC9IO,SAAS,aACd,OAIA,EAAA;AAEA,EAAA,MAAM,SAAgC,EAAC;AAEvC,EAAA,SAAS,eAAe,gBAA0B,EAAA;AAChD,IAAA,IAAI,CAAC,gBAAkB,EAAA;AACrB,MAAO,OAAA,gBAAA;AAAA;AAGT,IAAA,IAAI,cAAiB,GAAA,gBAAA;AACrB,IAAW,KAAA,MAAA,KAAA,IAAS,QAAQ,wBAA0B,EAAA;AACpD,MAAM,MAAA,aAAA,GAAgB,OAAQ,CAAA,wBAAA,CAAyB,KAAK,CAAA;AAC5D,MAAA,MAAM,KAAQ,GAAA,IAAI,MAAO,CAAA,KAAA,EAAO,GAAG,CAAA;AAEnC,MAAiB,cAAA,GAAA,cAAA,CAAe,OAAQ,CAAA,KAAA,EAAO,aAAuB,CAAA;AAAA;AAGxE,IAAW,KAAA,MAAA,KAAA,IAAS,QAAQ,yBAA2B,EAAA;AACrD,MAAI,IAAA,cAAA,GAAiB,OAAQ,CAAA,yBAAA,CAA0B,KAAK,CAAA;AAG5D,MAAA,IAAI,0BAA0B,GAAK,EAAA;AACjC,QAAM,MAAA,KAAA,GAAQ,KAAM,CAAA,IAAA,CAAK,cAAc,CAAA;AACvC,QAAA,cAAA,GAAiB,CAAO,IAAA,EAAA,KAAA,CAAM,MAAM,CAAA,EAAA,EAAK,MAAM,GAAI,CAAA,CAAC,CAAM,KAAA,IAAA,CAAK,UAAU,CAAC,CAAC,CAAE,CAAA,IAAA,CAAK,IAAI,CAAC,CAAA,CAAA,CAAA;AAAA,OAClF,MAAA;AAEL,QAAiB,cAAA,GAAA,IAAA,CAAK,UAAU,cAAc,CAAA;AAAA;AAGhD,MAAA,MAAM,KAAQ,GAAA,IAAI,MAAO,CAAA,KAAA,EAAO,GAAG,CAAA;AACnC,MAAiB,cAAA,GAAA,cAAA,CAAe,OAAQ,CAAA,KAAA,EAAO,cAAwB,CAAA;AAAA;AAGzE,IAAO,OAAA,cAAA;AAAA;AAGT,EAAA,IAAI,QAAQ,gBAAkB,EAAA;AAC5B,IAAO,MAAA,CAAA,gBAAA,GAAmB,cAAe,CAAA,OAAA,CAAQ,gBAAgB,CAAA;AAAA;AAEnE,EAAA,IAAI,QAAQ,mBAAqB,EAAA;AAC/B,IAAO,MAAA,CAAA,mBAAA,GAAsB,cAAe,CAAA,OAAA,CAAQ,mBAAmB,CAAA;AAAA;AAEzE,EAAA,IAAI,QAAQ,gBAAkB,EAAA;AAC5B,IAAO,MAAA,CAAA,gBAAA,GAAmB,cAAe,CAAA,OAAA,CAAQ,gBAAgB,CAAA;AAAA;AAEnE,EAAA,IAAI,QAAQ,sBAAwB,EAAA;AAClC,IAAO,MAAA,CAAA,sBAAA,GAAyB,cAAe,CAAA,OAAA,CAAQ,sBAAsB,CAAA;AAAA;AAE/E,EAAA,IAAI,QAAQ,oBAAsB,EAAA;AAChC,IAAO,MAAA,CAAA,oBAAA,GAAuB,cAAe,CAAA,OAAA,CAAQ,oBAAoB,CAAA;AAAA;AAG3E,EAAO,OAAA;AAAA,IACL,GAAK,EAAA,OAAA;AAAA,IACL,QAAU,EAAA;AAAA,GACZ;AACF;;;ACpBO,IAAM,aAAN,MAAoD;AAAA,EACxC,IAAA;AAAA,EACT,OAAA;AAAA,EACS,QAAA;AAAA,EACA,SAAA;AAAA,EAEjB,WAAA,CAAY,QAA0B,EAAA,IAAA,EAAS,SAAmB,EAAA;AAChE,IAAA,IAAA,CAAK,QAAW,GAAA,QAAA;AAChB,IAAA,IAAA,CAAK,IAAO,GAAA,IAAA;AACZ,IAAA,IAAA,CAAK,SAAY,GAAA,SAAA;AACjB,IAAA,IAAA,CAAK,OAAU,GAAA;AAAA,MACb,YAAc,EAAA;AAAA,KAChB;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;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EA2DO,UAAU,SAAwE,EAAA;AACvF,IAAI,IAAA,OAAO,cAAc,UAAY,EAAA;AACnC,MAAA,MAAM,iBAA0C,GAAA;AAAA,QAC9C,EAAA;AAAA,QACA,EAAA;AAAA,QACA,EAAA;AAAA,QACA,GAAA;AAAA,QACA,EAAA;AAAA,QACA,GAAA;AAAA,QACA,OAAA;AAAA,QACA,UAAA;AAAA,QACA,QAAA;AAAA,QACA,eAAA;AAAA,QACA,kBAAA;AAAA,QACA,GAAA;AAAA,QACA,EAAA;AAAA,QACA;AAAA,OACF;AACA,MAAK,IAAA,CAAA,OAAA,CAAQ,SAAY,GAAA,SAAA,CAAU,iBAAiB,CAAA;AAAA,KAC/C,MAAA;AACL,MAAA,IAAA,CAAK,QAAQ,SAAY,GAAA,SAAA;AAAA;AAE3B,IAAO,OAAA,IAAA;AAAA;AACT;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,aAAa,YAAuD,EAAA;AACzE,IAAA,IAAA,CAAK,QAAQ,YAAe,GAAA,YAAA;AAC5B,IAAO,OAAA,IAAA;AAAA;AACT;AAAA;AAAA;AAAA,EAKQ,eAAoC,GAAA;AAC1C,IAAM,MAAA,EAAE,YAAY,KAAO,EAAA,MAAA,KAAW,uBAAwB,CAAA,IAAA,CAAK,QAAQ,SAAS,CAAA;AAEpF,IAAO,OAAA;AAAA,MACL,WAAW,IAAK,CAAA,SAAA;AAAA,MAChB,MAAM,IAAK,CAAA,IAAA;AAAA,MACX,mBAAqB,EAAA,UAAA;AAAA,MACrB,wBAA0B,EAAA,KAAA;AAAA,MAC1B,yBAA2B,EAAA,MAAA;AAAA,MAC3B,YAAA,EAAc,KAAK,OAAQ,CAAA;AAAA,KAC7B;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,EAmCO,gBAAgB,WAAuC,EAAA;AAC5D,IAAM,MAAA,OAAA,GAAU,KAAK,eAAgB,EAAA;AACrC,IAAA,WAAA,CAAY,eAAe,OAAO,CAAA;AAElC,IAAO,OAAA,IAAA;AAAA;AACT;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAwBA,MAAa,OAAkC,GAAA;AAC7C,IAAM,MAAA,MAAA,GAAS,KAAK,eAAgB,EAAA;AACpC,IAAO,OAAA,IAAA,CAAK,SAAS,MAAM,CAAA;AAAA;AAC7B;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,KAAiC,GAAA;AACtC,IAAM,MAAA,OAAA,GAAU,KAAK,eAAgB,EAAA;AACrC,IAAA,OAAO,aAAa,OAAO,CAAA;AAAA;AAE/B","file":"put-builder.cjs","sourcesContent":["import type { Path, PathType } from \"./builders/types\";\n\n/**\n * Supported comparison operators for DynamoDB conditions.\n * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html AWS DynamoDB - Comparison Operator Reference}\n *\n * - eq: Equals (=)\n * - ne: Not equals (≠ / <>)\n * - lt: Less than (<)\n * - lte: Less than or equal to (≤)\n * - gt: Greater than (>)\n * - gte: Greater than or equal to (≥)\n * - between: Between two values (inclusive)\n * - beginsWith: Checks if string attribute begins with specified substring\n * - contains: Checks if string/set attribute contains specified value\n * - attributeExists: Checks if attribute exists\n * - attributeNotExists: Checks if attribute does not exist\n */\nexport type ComparisonOperator =\n  | \"eq\"\n  | \"ne\"\n  | \"lt\"\n  | \"lte\"\n  | \"gt\"\n  | \"gte\"\n  | \"between\"\n  | \"beginsWith\"\n  | \"contains\"\n  | \"attributeExists\"\n  | \"attributeNotExists\";\n\n/**\n * Logical operators for combining multiple conditions.\n * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Logical AWS DynamoDB - Logical Operator Reference}\n *\n * - and: Evaluates to true if all conditions are true\n * - or: Evaluates to true if any condition is true\n * - not: Negate the result of a condition\n */\nexport type LogicalOperator = \"and\" | \"or\" | \"not\";\n\n/**\n * Represents a DynamoDB condition expression.\n * Can be either a comparison condition or a logical combination of conditions.\n *\n * @example\n * // Simple comparison condition\n * const condition: Condition = {\n *   type: \"eq\",\n *   attr: \"status\",\n *   value: \"ACTIVE\"\n * };\n *\n * @example\n * // Logical combination of conditions\n * const condition: Condition = {\n *   type: \"and\",\n *   conditions: [\n *     { type: \"eq\", attr: \"status\", value: \"ACTIVE\" },\n *     { type: \"gt\", attr: \"age\", value: 5 }\n *   ]\n * };\n */\nexport interface Condition {\n  /** The type of condition (comparison or logical operator) */\n  type: ComparisonOperator | LogicalOperator;\n  /** The attribute name for comparison conditions */\n  attr?: string;\n  /** The value to compare against for comparison conditions */\n  value?: unknown;\n  /** Array of conditions for logical operators (and/or) */\n  conditions?: Condition[];\n  /** Single condition for the 'not' operator */\n  condition?: Condition;\n}\n\n/**\n * Parameters used to build DynamoDB expression strings.\n * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.ExpressionAttributeNames.html Expression Attribute Names}\n * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.ExpressionAttributeValues.html Expression Attribute Values}\n */\nexport interface ExpressionParams {\n  /** Map of attribute name placeholders to actual attribute names */\n  expressionAttributeNames: Record<string, string>;\n  /** Map of value placeholders to actual values */\n  expressionAttributeValues: Record<string, unknown>;\n  /** Counter for generating unique value placeholders */\n  valueCounter: { count: number };\n}\n\n/**\n * Creates a comparison condition builder function for the specified operator.\n * @internal\n */\nexport const createComparisonCondition =\n  (type: ComparisonOperator) =>\n  (attr: string, value: unknown): Condition => ({\n    type,\n    attr,\n    value,\n  });\n\n/**\n * Creates an equals (=) condition\n * @example\n * eq(\"status\", \"ACTIVE\") // status = \"ACTIVE\"\n * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html}\n */\nexport const eq = createComparisonCondition(\"eq\");\n\n/**\n * Creates a not equals (≠) condition\n * @example\n * ne(\"status\", \"DELETED\") // status <> \"DELETED\"\n * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html}\n */\nexport const ne = createComparisonCondition(\"ne\");\n\n/**\n * Creates a less than (<) condition\n * @example\n * lt(\"age\", 18) // age < 18\n * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html}\n */\nexport const lt = createComparisonCondition(\"lt\");\n\n/**\n * Creates a less than or equal to (≤) condition\n * @example\n * lte(\"age\", 18) // age <= 18\n * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html}\n */\nexport const lte = createComparisonCondition(\"lte\");\n\n/**\n * Creates a greater than (>) condition\n * @example\n * gt(\"price\", 100) // price > 100\n * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html}\n */\nexport const gt = createComparisonCondition(\"gt\");\n\n/**\n * Creates a greater than or equal to (≥) condition\n * @example\n * gte(\"price\", 100) // price >= 100\n * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html}\n */\nexport const gte = createComparisonCondition(\"gte\");\n\n/**\n * Creates a between condition that checks if a value is within a range (inclusive)\n * @example\n * between(\"age\", 18, 65) // age BETWEEN 18 AND 65\n * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Comparators AWS DynamoDB - BETWEEN}\n */\nexport const between = (attr: string, lower: unknown, upper: unknown): Condition => ({\n  type: \"between\",\n  attr,\n  value: [lower, upper],\n});\n\n/**\n * Creates a begins_with condition that checks if a string attribute starts with a substring\n * @example\n * beginsWith(\"email\", \"@example.com\") // begins_with(email, \"@example.com\")\n * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Functions AWS DynamoDB - begins_with}\n */\nexport const beginsWith = createComparisonCondition(\"beginsWith\");\n\n/**\n * Creates a contains condition that checks if a string contains a substring or if a set contains an element\n * @example\n * contains(\"tags\", \"important\") // contains(tags, \"important\")\n * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Functions AWS DynamoDB - contains}\n */\nexport const contains = createComparisonCondition(\"contains\");\n\n/**\n * Creates a condition that checks if an attribute exists\n * @example\n * attributeExists(\"email\") // attribute_exists(email)\n * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Functions AWS DynamoDB - attribute_exists}\n */\nexport const attributeExists = (attr: string): Condition => ({\n  type: \"attributeExists\",\n  attr,\n});\n\n/**\n * Creates a condition that checks if an attribute does not exist\n * @example\n * attributeNotExists(\"deletedAt\") // attribute_not_exists(deletedAt)\n * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Functions AWS DynamoDB - attribute_not_exists}\n */\nexport const attributeNotExists = (attr: string): Condition => ({\n  type: \"attributeNotExists\",\n  attr,\n});\n\n// --- Logical Operators ---\n\n/**\n * Combines multiple conditions with AND operator\n * @example\n * and(\n *   eq(\"status\", \"ACTIVE\"),\n *   gt(\"age\", 18)\n * ) // status = \"ACTIVE\" AND age > 18\n * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Logical AWS DynamoDB - AND}\n */\nexport const and = (...conditions: Condition[]): Condition => ({\n  type: \"and\",\n  conditions,\n});\n\n/**\n * Combines multiple conditions with OR operator\n * @example\n * or(\n *   eq(\"status\", \"PENDING\"),\n *   eq(\"status\", \"PROCESSING\")\n * ) // status = \"PENDING\" OR status = \"PROCESSING\"\n * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Logical AWS DynamoDB - OR}\n */\nexport const or = (...conditions: Condition[]): Condition => ({\n  type: \"or\",\n  conditions,\n});\n\n/**\n * Negates a condition\n * @example\n * not(eq(\"status\", \"DELETED\")) // NOT status = \"DELETED\"\n * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Logical AWS DynamoDB - NOT}\n */\nexport const not = (condition: Condition): Condition => ({\n  type: \"not\",\n  condition,\n});\n\n/**\n * Type-safe operators for building key conditions in DynamoDB queries.\n * Only includes operators that are valid for key conditions.\n * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Query.html#Query.KeyConditionExpressions AWS DynamoDB - Key Condition Expressions}\n *\n * @example\n * // Using with sort key conditions\n * table.query({\n *   pk: \"USER#123\",\n *   sk: op => op.beginsWith(\"ORDER#\")\n * })\n */\nexport type KeyConditionOperator = {\n  /** Equals comparison for key attributes */\n  eq: (value: unknown) => Condition;\n  /** Less than comparison for key attributes */\n  lt: (value: unknown) => Condition;\n  /** Less than or equal comparison for key attributes */\n  lte: (value: unknown) => Condition;\n  /** Greater than comparison for key attributes */\n  gt: (value: unknown) => Condition;\n  /** Greater than or equal comparison for key attributes */\n  gte: (value: unknown) => Condition;\n  /** Between range comparison for key attributes */\n  between: (lower: unknown, upper: unknown) => Condition;\n  /** Begins with comparison for key attributes */\n  beginsWith: (value: unknown) => Condition;\n  /** Combines multiple key conditions with AND */\n  and: (...conditions: Condition[]) => Condition;\n};\n\n/**\n * Type-safe operators for building conditions in DynamoDB operations.\n * Includes all available condition operators with proper type inference.\n * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html AWS DynamoDB - Condition Expressions}\n *\n * @example\n * // Using with type-safe conditions\n * interface User {\n *   status: string;\n *   age: number;\n *   email?: string;\n * }\n *\n * table.scan<User>()\n *   .where(op => op.and(\n *     op.eq(\"status\", \"ACTIVE\"),\n *     op.gt(\"age\", 18),\n *     op.attributeExists(\"email\")\n *   ))\n *\n * @template T The type of the item being operated on\n */\nexport type ConditionOperator<T extends Record<string, unknown>> = {\n  eq: <K extends Path<T>>(attr: K, value: PathType<T, K>) => Condition;\n  ne: <K extends Path<T>>(attr: K, value: PathType<T, K>) => Condition;\n  lt: <K extends Path<T>>(attr: K, value: PathType<T, K>) => Condition;\n  lte: <K extends Path<T>>(attr: K, value: PathType<T, K>) => Condition;\n  gt: <K extends Path<T>>(attr: K, value: PathType<T, K>) => Condition;\n  gte: <K extends Path<T>>(attr: K, value: PathType<T, K>) => Condition;\n  between: <K extends Path<T>>(attr: K, lower: PathType<T, K>, upper: PathType<T, K>) => Condition;\n  beginsWith: <K extends Path<T>>(attr: K, value: PathType<T, K>) => Condition;\n  contains: <K extends Path<T>>(attr: K, value: PathType<T, K>) => Condition;\n  attributeExists: <K extends Path<T>>(attr: K) => Condition;\n  attributeNotExists: <K extends Path<T>>(attr: K) => Condition;\n  and: (...conditions: Condition[]) => Condition;\n  or: (...conditions: Condition[]) => Condition;\n  not: (condition: Condition) => Condition;\n};\n\n/**\n * Primary key type for QUERY operations.\n * Allows building complex key conditions for the sort key.\n * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Query.html AWS DynamoDB - Query Operations}\n *\n * @example\n * // Query items with a specific partition key and sort key prefix\n * table.query({\n *   pk: \"USER#123\",\n *   sk: op => op.beginsWith(\"ORDER#2023\")\n * })\n *\n * @example\n * // Query items within a specific sort key range\n * table.query({\n *   pk: \"USER#123\",\n *   sk: op => op.between(\"ORDER#2023-01\", \"ORDER#2023-12\")\n * })\n */\nexport type PrimaryKey = {\n  /** Partition key value */\n  pk: string;\n  /** Optional sort key condition builder */\n  sk?: (op: KeyConditionOperator) => Condition;\n};\n\n/**\n * Primary key type for GET and DELETE operations.\n * Used when you need to specify exact key values without conditions.\n * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/WorkingWithItems.html AWS DynamoDB - Working with Items}\n *\n * @example\n * // Get a specific item by its complete primary key\n * table.get({\n *   pk: \"USER#123\",\n *   sk: \"PROFILE#123\"\n * })\n *\n * @example\n * // Delete a specific item by its complete primary key\n * table.delete({\n *   pk: \"USER#123\",\n *   sk: \"ORDER#456\"\n * })\n */\nexport type PrimaryKeyWithoutExpression = {\n  /** Partition key value */\n  pk: string;\n  /** Optional sort key value */\n  sk?: string;\n};\n","import type { ComparisonOperator, Condition, ExpressionParams, LogicalOperator } from \"./conditions\";\n\nexport const generateAttributeName = (params: ExpressionParams, attr: string): string => {\n  // Check if the attribute already exists in the expressionAttributeNames\n  for (const [existingName, existingAttr] of Object.entries(params.expressionAttributeNames)) {\n    if (existingAttr === attr) {\n      return existingName;\n    }\n  }\n\n  // If not found, create a new attribute name\n  const attrName = `#${Object.keys(params.expressionAttributeNames).length}`;\n  params.expressionAttributeNames[attrName] = attr;\n  return attrName;\n};\n\nexport const generateValueName = (params: ExpressionParams, value: unknown): string => {\n  const valueName = `:${params.valueCounter.count++}`;\n  params.expressionAttributeValues[valueName] = value;\n  return valueName;\n};\n\nconst validateCondition = (condition: Condition, requiresAttr = true, requiresValue = true): void => {\n  if (requiresAttr && !condition.attr) {\n    throw new Error(`Attribute is required for ${condition.type} condition`);\n  }\n\n  if (requiresValue && condition.value === undefined) {\n    throw new Error(`Value is required for ${condition.type} condition`);\n  }\n};\n\nconst buildComparisonExpression = (condition: Condition, operator: string, params: ExpressionParams): string => {\n  validateCondition(condition);\n\n  if (!condition.attr) {\n    throw new Error(`Attribute is required for ${condition.type} condition`);\n  }\n\n  const attrName = generateAttributeName(params, condition.attr);\n  const valueName = generateValueName(params, condition.value);\n\n  return `${attrName} ${operator} ${valueName}`;\n};\n\nconst buildBetweenExpression = (condition: Condition, params: ExpressionParams): string => {\n  validateCondition(condition);\n\n  if (!condition.attr) {\n    throw new Error(`Attribute is required for ${condition.type} condition`);\n  }\n\n  if (!Array.isArray(condition.value) || condition.value.length !== 2) {\n    throw new Error(\"Between condition requires an array of two values\");\n  }\n\n  const attrName = generateAttributeName(params, condition.attr);\n  const lowerName = generateValueName(params, condition.value[0]);\n  const upperName = generateValueName(params, condition.value[1]);\n\n  return `${attrName} BETWEEN ${lowerName} AND ${upperName}`;\n};\n\nconst buildFunctionExpression = (functionName: string, condition: Condition, params: ExpressionParams): string => {\n  validateCondition(condition);\n\n  if (!condition.attr) {\n    throw new Error(`Attribute is required for ${condition.type} condition`);\n  }\n\n  const attrName = generateAttributeName(params, condition.attr);\n  const valueName = generateValueName(params, condition.value);\n\n  return `${functionName}(${attrName}, ${valueName})`;\n};\n\nconst buildAttributeFunction = (functionName: string, condition: Condition, params: ExpressionParams): string => {\n  validateCondition(condition, true, false);\n\n  if (!condition.attr) {\n    throw new Error(`Attribute is required for ${condition.type} condition`);\n  }\n\n  const attrName = generateAttributeName(params, condition.attr);\n  return `${functionName}(${attrName})`;\n};\n\nconst buildLogicalExpression = (operator: string, conditions: Condition[], params: ExpressionParams): string => {\n  if (!conditions || conditions.length === 0) {\n    throw new Error(`At least one condition is required for ${operator} expression`);\n  }\n\n  const expressions = conditions.map((c) => buildExpression(c, params));\n  return `(${expressions.join(` ${operator} `)})`;\n};\n\nexport const buildExpression = (condition: Condition, params: ExpressionParams): string => {\n  if (!condition) return \"\";\n\n  try {\n    // Map of condition types to their expression builders\n    const expressionBuilders: Record<ComparisonOperator | LogicalOperator, () => string> = {\n      eq: () => buildComparisonExpression(condition, \"=\", params),\n      ne: () => buildComparisonExpression(condition, \"<>\", params),\n      lt: () => buildComparisonExpression(condition, \"<\", params),\n      lte: () => buildComparisonExpression(condition, \"<=\", params),\n      gt: () => buildComparisonExpression(condition, \">\", params),\n      gte: () => buildComparisonExpression(condition, \">=\", params),\n      between: () => buildBetweenExpression(condition, params),\n      beginsWith: () => buildFunctionExpression(\"begins_with\", condition, params),\n      contains: () => buildFunctionExpression(\"contains\", condition, params),\n      attributeExists: () => buildAttributeFunction(\"attribute_exists\", condition, params),\n      attributeNotExists: () => buildAttributeFunction(\"attribute_not_exists\", condition, params),\n      and: () => {\n        if (!condition.conditions) {\n          throw new Error(\"Conditions array is required for AND operator\");\n        }\n        return buildLogicalExpression(\"AND\", condition.conditions, params);\n      },\n      or: () => {\n        if (!condition.conditions) {\n          throw new Error(\"Conditions array is required for OR operator\");\n        }\n        return buildLogicalExpression(\"OR\", condition.conditions, params);\n      },\n      not: () => {\n        if (!condition.condition) {\n          throw new Error(\"Condition is required for NOT operator\");\n        }\n        return `NOT (${buildExpression(condition.condition, params)})`;\n      },\n    };\n\n    const builder = expressionBuilders[condition.type];\n    if (!builder) {\n      throw new Error(`Unknown condition type: ${condition.type}`);\n    }\n\n    return builder();\n  } catch (error: unknown) {\n    if (error instanceof Error) {\n      console.error(`Error building expression for condition type ${condition.type}:`, error.message);\n    } else {\n      console.error(`Error building expression for condition type ${condition.type}:`, error);\n    }\n    throw error;\n  }\n};\n\nexport const prepareExpressionParams = (\n  condition?: Condition,\n): {\n  expression?: string;\n  names?: Record<string, string>;\n  values?: Record<string, unknown>;\n} => {\n  if (!condition) return {};\n\n  const params: ExpressionParams = {\n    expressionAttributeNames: {},\n    expressionAttributeValues: {},\n    valueCounter: { count: 0 },\n  };\n\n  const expression = buildExpression(condition, params);\n\n  return {\n    expression,\n    names: Object.keys(params.expressionAttributeNames).length > 0 ? params.expressionAttributeNames : undefined,\n    values: Object.keys(params.expressionAttributeValues).length > 0 ? params.expressionAttributeValues : undefined,\n  };\n};\n","/**\n * Interface for DynamoDB command objects that can contain expressions\n */\nexport interface DynamoCommandWithExpressions {\n  conditionExpression?: string;\n  updateExpression?: string;\n  filterExpression?: string;\n  keyConditionExpression?: string;\n  projectionExpression?: string;\n  expressionAttributeNames?: Record<string, string>;\n  expressionAttributeValues?: Record<string, unknown>;\n  [key: string]: unknown;\n}\n\ntype ReadableDynamoCommand = {\n  conditionExpression?: string;\n  updateExpression?: string;\n  filterExpression?: string;\n  keyConditionExpression?: string;\n  projectionExpression?: string;\n};\n\n/**\n * Utility function to debug a DynamoDB command by replacing all placeholders\n * in expressions with their actual values.\n *\n * @param command Any DynamoDB command with expressions and attribute maps\n * @returns An object with the same structure but with readable expressions\n */\nexport function debugCommand<T extends DynamoCommandWithExpressions>(\n  command: T,\n): {\n  raw: T;\n  readable: ReadableDynamoCommand;\n} {\n  // Create a copy of the command\n  const result: ReadableDynamoCommand = {};\n\n  function replaceAliases(expressionString: string) {\n    if (!expressionString) {\n      return expressionString;\n    }\n\n    let replacedString = expressionString;\n    for (const alias in command.expressionAttributeNames) {\n      const attributeName = command.expressionAttributeNames[alias];\n      const regex = new RegExp(alias, \"g\");\n\n      replacedString = replacedString.replace(regex, attributeName as string);\n    }\n\n    for (const alias in command.expressionAttributeValues) {\n      let attributeValue = command.expressionAttributeValues[alias];\n\n      // Handle Set objects for better readability\n      if (attributeValue instanceof Set) {\n        const array = Array.from(attributeValue);\n        attributeValue = `Set(${array.length}){${array.map((v) => JSON.stringify(v)).join(\", \")}}`;\n      } else {\n        // Stringify other values for display\n        attributeValue = JSON.stringify(attributeValue);\n      }\n\n      const regex = new RegExp(alias, \"g\");\n      replacedString = replacedString.replace(regex, attributeValue as string);\n    }\n\n    return replacedString;\n  }\n\n  if (command.updateExpression) {\n    result.updateExpression = replaceAliases(command.updateExpression);\n  }\n  if (command.conditionExpression) {\n    result.conditionExpression = replaceAliases(command.conditionExpression);\n  }\n  if (command.filterExpression) {\n    result.filterExpression = replaceAliases(command.filterExpression);\n  }\n  if (command.keyConditionExpression) {\n    result.keyConditionExpression = replaceAliases(command.keyConditionExpression);\n  }\n  if (command.projectionExpression) {\n    result.projectionExpression = replaceAliases(command.projectionExpression);\n  }\n\n  return {\n    raw: command,\n    readable: result,\n  };\n}\n","import type { Condition, ConditionOperator } from \"../conditions\";\nimport {\n  eq,\n  ne,\n  lt,\n  lte,\n  gt,\n  gte,\n  between,\n  beginsWith,\n  contains,\n  attributeExists,\n  attributeNotExists,\n  and,\n  or,\n  not,\n} from \"../conditions\";\nimport type { TransactionBuilder } from \"./transaction-builder\";\nimport { prepareExpressionParams } from \"../expression\";\nimport { debugCommand } from \"../utils/debug-expression\";\nimport type { PutCommandParams } from \"./builder-types\";\n\n/**\n * Configuration options for DynamoDB put operations.\n */\nexport interface PutOptions {\n  /** Optional condition that must be satisfied for the put operation to succeed */\n  condition?: Condition;\n  /** Determines how to handle the return value of the put operation\n   * @options\n   *  - NONE: No return value\n   *  - ALL_OLD: Returns the item's previous state if it existed\n   *  - CONSISTENT: (default) Performs a GET operation after the put to retrieve the item's new state\n   */\n  returnValues?: \"ALL_OLD\" | \"NONE\" | \"CONSISTENT\";\n}\n\ntype PutExecutor<T extends Record<string, unknown>> = (params: PutCommandParams) => Promise<T>;\n\n/**\n * Builder for creating DynamoDB put operations.\n *\n * @example\n * ```typescript\n * // Add new dinosaur\n * const result = await new PutBuilder(executor, {\n *   id: 'RAPTOR-001',\n *   species: 'Velociraptor',\n *   status: 'ACTIVE',\n *   stats: {\n *     health: 100,\n *     age: 5,\n *     threatLevel: 8\n *   }\n * }, 'dinosaurs').execute();\n *\n * // Create new habitat with conditions\n * const result = await new PutBuilder(executor, {\n *   id: 'PADDOCK-C',\n *   type: 'CARNIVORE',\n *   securityLevel: 'MAXIMUM',\n *   capacity: 3,\n *   environmentType: 'TROPICAL'\n * }, 'habitats')\n *   .condition(op => op.attributeNotExists('id'))\n *   .execute();\n * ```\n *\n * @typeParam T - The type of item being put into the table\n */\nexport class PutBuilder<T extends Record<string, unknown>> {\n  private readonly item: T;\n  private options: PutOptions;\n  private readonly executor: PutExecutor<T>;\n  private readonly tableName: string;\n\n  constructor(executor: PutExecutor<T>, item: T, tableName: string) {\n    this.executor = executor;\n    this.item = item;\n    this.tableName = tableName;\n    this.options = {\n      returnValues: \"NONE\",\n    };\n  }\n\n  /**\n   * Adds a condition that must be satisfied for the put operation to succeed.\n   * Use this method when you need to:\n   * - Prevent overwriting existing items (optimistic locking)\n   * - Ensure items meet certain criteria before replacement\n   * - Implement complex business rules for item updates\n   *\n   * @example\n   * ```ts\n   * // Ensure item doesn't exist (insert only)\n   * builder.condition(op => op.attributeNotExists('id'))\n   *\n   * // Complex condition with version check\n   * builder.condition(op =>\n   *   op.and([\n   *     op.attributeExists('id'),\n   *     op.eq('version', currentVersion),\n   *     op.eq('status', 'ACTIVE')\n   *   ])\n   * )\n   * ```\n   *\n   * @param condition - Either a Condition object or a callback function that builds the condition\n   * @returns The builder instance for method chaining\n   */\n  /**\n   * Adds a condition that must be satisfied for the put operation to succeed.\n   *\n   * @example\n   * ```typescript\n   * // Ensure unique dinosaur ID\n   * builder.condition(op =>\n   *   op.attributeNotExists('id')\n   * );\n   *\n   * // Verify habitat requirements\n   * builder.condition(op =>\n   *   op.and([\n   *     op.eq('securityStatus', 'READY'),\n   *     op.attributeExists('lastInspection'),\n   *     op.gt('securityLevel', 5)\n   *   ])\n   * );\n   *\n   * // Check breeding facility conditions\n   * builder.condition(op =>\n   *   op.and([\n   *     op.between('temperature', 25, 30),\n   *     op.between('humidity', 60, 80),\n   *     op.eq('quarantineStatus', 'CLEAR')\n   *   ])\n   * );\n   * ```\n   *\n   * @param condition - Either a Condition object or a callback function that builds the condition\n   * @returns The builder instance for method chaining\n   */\n  public condition(condition: Condition | ((op: ConditionOperator<T>) => Condition)): this {\n    if (typeof condition === \"function\") {\n      const conditionOperator: ConditionOperator<T> = {\n        eq,\n        ne,\n        lt,\n        lte,\n        gt,\n        gte,\n        between,\n        beginsWith,\n        contains,\n        attributeExists,\n        attributeNotExists,\n        and,\n        or,\n        not,\n      };\n      this.options.condition = condition(conditionOperator);\n    } else {\n      this.options.condition = condition;\n    }\n    return this;\n  }\n\n  /**\n   * Sets whether to return the item's previous values (if it existed).\n   *\n   * @options\n   *  - NONE: No return value\n   *  - ALL_OLD: Returns the item's previous state if it existed, no read capacity units are consumed\n   *  - CONSISTENT: (default) Performs a GET operation after the put to retrieve the item's new state\n   *\n   * @example\n   * ```ts\n   * // Get previous dinosaur state\n   * const result = await builder\n   *   .returnValues('ALL_OLD')\n   *   .execute();\n   *\n   * if (result) {\n   *   console.log('Previous profile:', {\n   *     species: result.species,\n   *     status: result.status,\n   *     stats: {\n   *       health: result.stats.health,\n   *       threatLevel: result.stats.threatLevel\n   *     }\n   *   });\n   * }\n   * ```\n   *\n   * @param returnValues - Use 'ALL_OLD' to return previous values if the item was overwritten, or 'NONE' (default).\n   * @returns The builder instance for method chaining\n   */\n  public returnValues(returnValues: \"ALL_OLD\" | \"NONE\" | \"CONSISTENT\"): this {\n    this.options.returnValues = returnValues;\n    return this;\n  }\n\n  /**\n   * Generate the DynamoDB command parameters\n   */\n  private toDynamoCommand(): PutCommandParams {\n    const { expression, names, values } = prepareExpressionParams(this.options.condition);\n\n    return {\n      tableName: this.tableName,\n      item: this.item,\n      conditionExpression: expression,\n      expressionAttributeNames: names,\n      expressionAttributeValues: values,\n      returnValues: this.options.returnValues,\n    };\n  }\n\n  /**\n   * Adds this put operation to a transaction.\n   * Use this method when you need to:\n   * - Transfer dinosaurs between habitats\n   * - Initialize new breeding programs\n   * - Update multiple facility records\n   *\n   * @example\n   * ```ts\n   * const transaction = new TransactionBuilder();\n   *\n   * // Add dinosaur to new habitat\n   * new PutBuilder(executor, {\n   *   id: 'TREX-002',\n   *   location: 'PADDOCK-B',\n   *   status: 'ACTIVE',\n   *   transferDate: new Date().toISOString()\n   * }, 'dinosaurs')\n   *   .withTransaction(transaction);\n   *\n   * // Update habitat records\n   * new UpdateBuilder(executor, 'habitats', { id: 'PADDOCK-B' })\n   *   .add('occupants', 1)\n   *   .set('lastTransfer', new Date().toISOString())\n   *   .withTransaction(transaction);\n   *\n   * // Execute transfer atomically\n   * await transaction.execute();\n   * ```\n   *\n   * @param transaction - The transaction builder to add this operation to\n   * @returns The builder instance for method chaining\n   */\n  public withTransaction(transaction: TransactionBuilder): this {\n    const command = this.toDynamoCommand();\n    transaction.putWithCommand(command);\n\n    return this;\n  }\n\n  /**\n   * Executes the put operation against DynamoDB.\n   *\n   * @example\n   * ```ts\n   * try {\n   *   // Put with condition and return old values\n   *   const result = await new PutBuilder(executor, newItem, 'myTable')\n   *     .condition(op => op.eq('version', 1))\n   *     .returnValues('ALL_OLD')\n   *     .execute();\n   *\n   *   console.log('Put successful, old item:', result);\n   * } catch (error) {\n   *   // Handle condition check failure or other errors\n   *   console.error('Put failed:', error);\n   * }\n   * ```\n   *\n   * @returns A promise that resolves to the operation result (type depends on returnValues setting)\n   * @throws Will throw an error if the condition check fails or other DynamoDB errors occur\n   */\n  public async execute(): Promise<T | undefined> {\n    const params = this.toDynamoCommand();\n    return this.executor(params);\n  }\n\n  /**\n   * Gets a human-readable representation of the put command\n   * with all expression placeholders replaced by their actual values.\n   *\n   * @example\n   * ```ts\n   * const debugInfo = new PutBuilder(executor, {\n   *   id: 'RAPTOR-003',\n   *   species: 'Velociraptor',\n   *   status: 'QUARANTINE',\n   *   stats: {\n   *     health: 100,\n   *     aggressionLevel: 7,\n   *     age: 2\n   *   }\n   * }, 'dinosaurs')\n   *   .condition(op =>\n   *     op.and([\n   *       op.attributeNotExists('id'),\n   *       op.eq('quarantineStatus', 'READY'),\n   *       op.gt('securityLevel', 8)\n   *     ])\n   *   )\n   *   .debug();\n   *\n   * console.log('Dinosaur transfer command:', debugInfo);\n   * ```\n   *\n   * @returns A readable representation of the put command with resolved expressions\n   */\n  public debug(): Record<string, unknown> {\n    const command = this.toDynamoCommand();\n    return debugCommand(command);\n  }\n}\n"]}
+{"version":3,"sources":["../../src/conditions.ts","../../src/expression.ts","../../src/utils/debug-expression.ts","../../src/builders/put-builder.ts"],"names":[],"mappings":"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","file":"put-builder.cjs","sourcesContent":["import type { Path, PathType } from \"./builders/types\";\nimport type { DynamoItem } from \"./types\";\n\n/**\n * Supported comparison operators for DynamoDB conditions.\n * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html AWS DynamoDB - Comparison Operator Reference}\n *\n * - eq: Equals (=)\n * - ne: Not equals (≠ / <>)\n * - lt: Less than (<)\n * - lte: Less than or equal to (≤)\n * - gt: Greater than (>)\n * - gte: Greater than or equal to (≥)\n * - between: Between two values (inclusive)\n * - beginsWith: Checks if string attribute begins with specified substring\n * - contains: Checks if string/set attribute contains specified value\n * - attributeExists: Checks if attribute exists\n * - attributeNotExists: Checks if attribute does not exist\n */\nexport type ComparisonOperator =\n  | \"eq\"\n  | \"ne\"\n  | \"lt\"\n  | \"lte\"\n  | \"gt\"\n  | \"gte\"\n  | \"between\"\n  | \"beginsWith\"\n  | \"contains\"\n  | \"attributeExists\"\n  | \"attributeNotExists\";\n\n/**\n * Logical operators for combining multiple conditions.\n * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Logical AWS DynamoDB - Logical Operator Reference}\n *\n * - and: Evaluates to true if all conditions are true\n * - or: Evaluates to true if any condition is true\n * - not: Negate the result of a condition\n */\nexport type LogicalOperator = \"and\" | \"or\" | \"not\";\n\n/**\n * Represents a DynamoDB condition expression.\n * Can be either a comparison condition or a logical combination of conditions.\n *\n * @example\n * // Simple comparison condition\n * const condition: Condition = {\n *   type: \"eq\",\n *   attr: \"status\",\n *   value: \"ACTIVE\"\n * };\n *\n * @example\n * // Logical combination of conditions\n * const condition: Condition = {\n *   type: \"and\",\n *   conditions: [\n *     { type: \"eq\", attr: \"status\", value: \"ACTIVE\" },\n *     { type: \"gt\", attr: \"age\", value: 5 }\n *   ]\n * };\n */\nexport interface Condition {\n  /** The type of condition (comparison or logical operator) */\n  type: ComparisonOperator | LogicalOperator;\n  /** The attribute name for comparison conditions */\n  attr?: string;\n  /** The value to compare against for comparison conditions */\n  value?: unknown;\n  /** Array of conditions for logical operators (and/or) */\n  conditions?: Condition[];\n  /** Single condition for the 'not' operator */\n  condition?: Condition;\n}\n\n/**\n * Parameters used to build DynamoDB expression strings.\n * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.ExpressionAttributeNames.html Expression Attribute Names}\n * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.ExpressionAttributeValues.html Expression Attribute Values}\n */\nexport interface ExpressionParams {\n  /** Map of attribute name placeholders to actual attribute names */\n  expressionAttributeNames: Record<string, string>;\n  /** Map of value placeholders to actual values */\n  expressionAttributeValues: DynamoItem;\n  /** Counter for generating unique value placeholders */\n  valueCounter: { count: number };\n}\n\n/**\n * Creates a comparison condition builder function for the specified operator.\n * @internal\n */\nexport const createComparisonCondition =\n  (type: ComparisonOperator) =>\n  (attr: string, value: unknown): Condition => ({\n    type,\n    attr,\n    value,\n  });\n\n/**\n * Creates an equals (=) condition\n * @example\n * eq(\"status\", \"ACTIVE\") // status = \"ACTIVE\"\n * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html}\n */\nexport const eq = createComparisonCondition(\"eq\");\n\n/**\n * Creates a not equals (≠) condition\n * @example\n * ne(\"status\", \"DELETED\") // status <> \"DELETED\"\n * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html}\n */\nexport const ne = createComparisonCondition(\"ne\");\n\n/**\n * Creates a less than (<) condition\n * @example\n * lt(\"age\", 18) // age < 18\n * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html}\n */\nexport const lt = createComparisonCondition(\"lt\");\n\n/**\n * Creates a less than or equal to (≤) condition\n * @example\n * lte(\"age\", 18) // age <= 18\n * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html}\n */\nexport const lte = createComparisonCondition(\"lte\");\n\n/**\n * Creates a greater than (>) condition\n * @example\n * gt(\"price\", 100) // price > 100\n * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html}\n */\nexport const gt = createComparisonCondition(\"gt\");\n\n/**\n * Creates a greater than or equal to (≥) condition\n * @example\n * gte(\"price\", 100) // price >= 100\n * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html}\n */\nexport const gte = createComparisonCondition(\"gte\");\n\n/**\n * Creates a between condition that checks if a value is within a range (inclusive)\n * @example\n * between(\"age\", 18, 65) // age BETWEEN 18 AND 65\n * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Comparators AWS DynamoDB - BETWEEN}\n */\nexport const between = (attr: string, lower: unknown, upper: unknown): Condition => ({\n  type: \"between\",\n  attr,\n  value: [lower, upper],\n});\n\n/**\n * Creates a begins_with condition that checks if a string attribute starts with a substring\n * @example\n * beginsWith(\"email\", \"@example.com\") // begins_with(email, \"@example.com\")\n * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Functions AWS DynamoDB - begins_with}\n */\nexport const beginsWith = createComparisonCondition(\"beginsWith\");\n\n/**\n * Creates a contains condition that checks if a string contains a substring or if a set contains an element\n * @example\n * contains(\"tags\", \"important\") // contains(tags, \"important\")\n * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Functions AWS DynamoDB - contains}\n */\nexport const contains = createComparisonCondition(\"contains\");\n\n/**\n * Creates a condition that checks if an attribute exists\n * @example\n * attributeExists(\"email\") // attribute_exists(email)\n * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Functions AWS DynamoDB - attribute_exists}\n */\nexport const attributeExists = (attr: string): Condition => ({\n  type: \"attributeExists\",\n  attr,\n});\n\n/**\n * Creates a condition that checks if an attribute does not exist\n * @example\n * attributeNotExists(\"deletedAt\") // attribute_not_exists(deletedAt)\n * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Functions AWS DynamoDB - attribute_not_exists}\n */\nexport const attributeNotExists = (attr: string): Condition => ({\n  type: \"attributeNotExists\",\n  attr,\n});\n\n// --- Logical Operators ---\n\n/**\n * Combines multiple conditions with AND operator\n * @example\n * and(\n *   eq(\"status\", \"ACTIVE\"),\n *   gt(\"age\", 18)\n * ) // status = \"ACTIVE\" AND age > 18\n * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Logical AWS DynamoDB - AND}\n */\nexport const and = (...conditions: Condition[]): Condition => ({\n  type: \"and\",\n  conditions,\n});\n\n/**\n * Combines multiple conditions with OR operator\n * @example\n * or(\n *   eq(\"status\", \"PENDING\"),\n *   eq(\"status\", \"PROCESSING\")\n * ) // status = \"PENDING\" OR status = \"PROCESSING\"\n * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Logical AWS DynamoDB - OR}\n */\nexport const or = (...conditions: Condition[]): Condition => ({\n  type: \"or\",\n  conditions,\n});\n\n/**\n * Negates a condition\n * @example\n * not(eq(\"status\", \"DELETED\")) // NOT status = \"DELETED\"\n * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Logical AWS DynamoDB - NOT}\n */\nexport const not = (condition: Condition): Condition => ({\n  type: \"not\",\n  condition,\n});\n\n/**\n * Type-safe operators for building key conditions in DynamoDB queries.\n * Only includes operators that are valid for key conditions.\n * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Query.html#Query.KeyConditionExpressions AWS DynamoDB - Key Condition Expressions}\n *\n * @example\n * // Using with sort key conditions\n * table.query({\n *   pk: \"USER#123\",\n *   sk: op => op.beginsWith(\"ORDER#\")\n * })\n */\nexport type KeyConditionOperator = {\n  /** Equals comparison for key attributes */\n  eq: (value: unknown) => Condition;\n  /** Less than comparison for key attributes */\n  lt: (value: unknown) => Condition;\n  /** Less than or equal comparison for key attributes */\n  lte: (value: unknown) => Condition;\n  /** Greater than comparison for key attributes */\n  gt: (value: unknown) => Condition;\n  /** Greater than or equal comparison for key attributes */\n  gte: (value: unknown) => Condition;\n  /** Between range comparison for key attributes */\n  between: (lower: unknown, upper: unknown) => Condition;\n  /** Begins with comparison for key attributes */\n  beginsWith: (value: unknown) => Condition;\n  /** Combines multiple key conditions with AND */\n  and: (...conditions: Condition[]) => Condition;\n};\n\n/**\n * Type-safe operators for building conditions in DynamoDB operations.\n * Includes all available condition operators with proper type inference.\n * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html AWS DynamoDB - Condition Expressions}\n *\n * @example\n * // Using with type-safe conditions\n * interface User {\n *   status: string;\n *   age: number;\n *   email?: string;\n * }\n *\n * table.scan<User>()\n *   .where(op => op.and(\n *     op.eq(\"status\", \"ACTIVE\"),\n *     op.gt(\"age\", 18),\n *     op.attributeExists(\"email\")\n *   ))\n *\n * @template T The type of the item being operated on\n */\nexport type ConditionOperator<T extends DynamoItem> = {\n  eq: <K extends Path<T>>(attr: K, value: PathType<T, K>) => Condition;\n  ne: <K extends Path<T>>(attr: K, value: PathType<T, K>) => Condition;\n  lt: <K extends Path<T>>(attr: K, value: PathType<T, K>) => Condition;\n  lte: <K extends Path<T>>(attr: K, value: PathType<T, K>) => Condition;\n  gt: <K extends Path<T>>(attr: K, value: PathType<T, K>) => Condition;\n  gte: <K extends Path<T>>(attr: K, value: PathType<T, K>) => Condition;\n  between: <K extends Path<T>>(attr: K, lower: PathType<T, K>, upper: PathType<T, K>) => Condition;\n  beginsWith: <K extends Path<T>>(attr: K, value: PathType<T, K>) => Condition;\n  contains: <K extends Path<T>>(attr: K, value: PathType<T, K>) => Condition;\n  attributeExists: <K extends Path<T>>(attr: K) => Condition;\n  attributeNotExists: <K extends Path<T>>(attr: K) => Condition;\n  and: (...conditions: Condition[]) => Condition;\n  or: (...conditions: Condition[]) => Condition;\n  not: (condition: Condition) => Condition;\n};\n\n/**\n * Primary key type for QUERY operations.\n * Allows building complex key conditions for the sort key.\n * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Query.html AWS DynamoDB - Query Operations}\n *\n * @example\n * // Query items with a specific partition key and sort key prefix\n * table.query({\n *   pk: \"USER#123\",\n *   sk: op => op.beginsWith(\"ORDER#2023\")\n * })\n *\n * @example\n * // Query items within a specific sort key range\n * table.query({\n *   pk: \"USER#123\",\n *   sk: op => op.between(\"ORDER#2023-01\", \"ORDER#2023-12\")\n * })\n */\nexport type PrimaryKey = {\n  /** Partition key value */\n  pk: string;\n  /** Optional sort key condition builder */\n  sk?: (op: KeyConditionOperator) => Condition;\n};\n\n/**\n * Primary key type for GET and DELETE operations.\n * Used when you need to specify exact key values without conditions.\n * @see {@link https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/WorkingWithItems.html AWS DynamoDB - Working with Items}\n *\n * @example\n * // Get a specific item by its complete primary key\n * table.get({\n *   pk: \"USER#123\",\n *   sk: \"PROFILE#123\"\n * })\n *\n * @example\n * // Delete a specific item by its complete primary key\n * table.delete({\n *   pk: \"USER#123\",\n *   sk: \"ORDER#456\"\n * })\n */\nexport type PrimaryKeyWithoutExpression = {\n  /** Partition key value */\n  pk: string;\n  /** Optional sort key value */\n  sk?: string;\n};\n","import type { ComparisonOperator, Condition, ExpressionParams, LogicalOperator } from \"./conditions\";\n\nexport const generateAttributeName = (params: ExpressionParams, attr: string): string => {\n  // Check if the attribute already exists in the expressionAttributeNames\n  for (const [existingName, existingAttr] of Object.entries(params.expressionAttributeNames)) {\n    if (existingAttr === attr) {\n      return existingName;\n    }\n  }\n\n  // If not found, create a new attribute name\n  const attrName = `#${Object.keys(params.expressionAttributeNames).length}`;\n  params.expressionAttributeNames[attrName] = attr;\n  return attrName;\n};\n\nexport const generateValueName = (params: ExpressionParams, value: unknown): string => {\n  const valueName = `:${params.valueCounter.count++}`;\n  params.expressionAttributeValues[valueName] = value;\n  return valueName;\n};\n\nconst validateCondition = (condition: Condition, requiresAttr = true, requiresValue = true): void => {\n  if (requiresAttr && !condition.attr) {\n    throw new Error(`Attribute is required for ${condition.type} condition`);\n  }\n\n  if (requiresValue && condition.value === undefined) {\n    throw new Error(`Value is required for ${condition.type} condition`);\n  }\n};\n\nconst buildComparisonExpression = (condition: Condition, operator: string, params: ExpressionParams): string => {\n  validateCondition(condition);\n\n  if (!condition.attr) {\n    throw new Error(`Attribute is required for ${condition.type} condition`);\n  }\n\n  const attrName = generateAttributeName(params, condition.attr);\n  const valueName = generateValueName(params, condition.value);\n\n  return `${attrName} ${operator} ${valueName}`;\n};\n\nconst buildBetweenExpression = (condition: Condition, params: ExpressionParams): string => {\n  validateCondition(condition);\n\n  if (!condition.attr) {\n    throw new Error(`Attribute is required for ${condition.type} condition`);\n  }\n\n  if (!Array.isArray(condition.value) || condition.value.length !== 2) {\n    throw new Error(\"Between condition requires an array of two values\");\n  }\n\n  const attrName = generateAttributeName(params, condition.attr);\n  const lowerName = generateValueName(params, condition.value[0]);\n  const upperName = generateValueName(params, condition.value[1]);\n\n  return `${attrName} BETWEEN ${lowerName} AND ${upperName}`;\n};\n\nconst buildFunctionExpression = (functionName: string, condition: Condition, params: ExpressionParams): string => {\n  validateCondition(condition);\n\n  if (!condition.attr) {\n    throw new Error(`Attribute is required for ${condition.type} condition`);\n  }\n\n  const attrName = generateAttributeName(params, condition.attr);\n  const valueName = generateValueName(params, condition.value);\n\n  return `${functionName}(${attrName}, ${valueName})`;\n};\n\nconst buildAttributeFunction = (functionName: string, condition: Condition, params: ExpressionParams): string => {\n  validateCondition(condition, true, false);\n\n  if (!condition.attr) {\n    throw new Error(`Attribute is required for ${condition.type} condition`);\n  }\n\n  const attrName = generateAttributeName(params, condition.attr);\n  return `${functionName}(${attrName})`;\n};\n\nconst buildLogicalExpression = (operator: string, conditions: Condition[], params: ExpressionParams): string => {\n  if (!conditions || conditions.length === 0) {\n    throw new Error(`At least one condition is required for ${operator} expression`);\n  }\n\n  const expressions = conditions.map((c) => buildExpression(c, params));\n  return `(${expressions.join(` ${operator} `)})`;\n};\n\nexport const buildExpression = (condition: Condition, params: ExpressionParams): string => {\n  if (!condition) return \"\";\n\n  try {\n    // Map of condition types to their expression builders\n    const expressionBuilders: Record<ComparisonOperator | LogicalOperator, () => string> = {\n      eq: () => buildComparisonExpression(condition, \"=\", params),\n      ne: () => buildComparisonExpression(condition, \"<>\", params),\n      lt: () => buildComparisonExpression(condition, \"<\", params),\n      lte: () => buildComparisonExpression(condition, \"<=\", params),\n      gt: () => buildComparisonExpression(condition, \">\", params),\n      gte: () => buildComparisonExpression(condition, \">=\", params),\n      between: () => buildBetweenExpression(condition, params),\n      beginsWith: () => buildFunctionExpression(\"begins_with\", condition, params),\n      contains: () => buildFunctionExpression(\"contains\", condition, params),\n      attributeExists: () => buildAttributeFunction(\"attribute_exists\", condition, params),\n      attributeNotExists: () => buildAttributeFunction(\"attribute_not_exists\", condition, params),\n      and: () => {\n        if (!condition.conditions) {\n          throw new Error(\"Conditions array is required for AND operator\");\n        }\n        return buildLogicalExpression(\"AND\", condition.conditions, params);\n      },\n      or: () => {\n        if (!condition.conditions) {\n          throw new Error(\"Conditions array is required for OR operator\");\n        }\n        return buildLogicalExpression(\"OR\", condition.conditions, params);\n      },\n      not: () => {\n        if (!condition.condition) {\n          throw new Error(\"Condition is required for NOT operator\");\n        }\n        return `NOT (${buildExpression(condition.condition, params)})`;\n      },\n    };\n\n    const builder = expressionBuilders[condition.type];\n    if (!builder) {\n      throw new Error(`Unknown condition type: ${condition.type}`);\n    }\n\n    return builder();\n  } catch (error: unknown) {\n    if (error instanceof Error) {\n      console.error(`Error building expression for condition type ${condition.type}:`, error.message);\n    } else {\n      console.error(`Error building expression for condition type ${condition.type}:`, error);\n    }\n    throw error;\n  }\n};\n\nexport const prepareExpressionParams = (\n  condition?: Condition,\n): {\n  expression?: string;\n  names?: Record<string, string>;\n  values?: Record<string, unknown>;\n} => {\n  if (!condition) return {};\n\n  const params: ExpressionParams = {\n    expressionAttributeNames: {},\n    expressionAttributeValues: {},\n    valueCounter: { count: 0 },\n  };\n\n  const expression = buildExpression(condition, params);\n\n  return {\n    expression,\n    names: Object.keys(params.expressionAttributeNames).length > 0 ? params.expressionAttributeNames : undefined,\n    values: Object.keys(params.expressionAttributeValues).length > 0 ? params.expressionAttributeValues : undefined,\n  };\n};\n","/**\n * Interface for DynamoDB command objects that can contain expressions\n */\nexport interface DynamoCommandWithExpressions {\n  conditionExpression?: string;\n  updateExpression?: string;\n  filterExpression?: string;\n  keyConditionExpression?: string;\n  projectionExpression?: string;\n  expressionAttributeNames?: Record<string, string>;\n  expressionAttributeValues?: Record<string, unknown>;\n  [key: string]: unknown;\n}\n\ntype ReadableDynamoCommand = {\n  conditionExpression?: string;\n  updateExpression?: string;\n  filterExpression?: string;\n  keyConditionExpression?: string;\n  projectionExpression?: string;\n};\n\n/**\n * Utility function to debug a DynamoDB command by replacing all placeholders\n * in expressions with their actual values.\n *\n * @param command Any DynamoDB command with expressions and attribute maps\n * @returns An object with the same structure but with readable expressions\n */\nexport function debugCommand<T extends DynamoCommandWithExpressions>(\n  command: T,\n): {\n  raw: T;\n  readable: ReadableDynamoCommand;\n} {\n  // Create a copy of the command\n  const result: ReadableDynamoCommand = {};\n\n  function replaceAliases(expressionString: string) {\n    if (!expressionString) {\n      return expressionString;\n    }\n\n    let replacedString = expressionString;\n    for (const alias in command.expressionAttributeNames) {\n      const attributeName = command.expressionAttributeNames[alias];\n      const regex = new RegExp(alias, \"g\");\n\n      replacedString = replacedString.replace(regex, attributeName as string);\n    }\n\n    for (const alias in command.expressionAttributeValues) {\n      let attributeValue = command.expressionAttributeValues[alias];\n\n      // Handle Set objects for better readability\n      if (attributeValue instanceof Set) {\n        const array = Array.from(attributeValue);\n        attributeValue = `Set(${array.length}){${array.map((v) => JSON.stringify(v)).join(\", \")}}`;\n      } else {\n        // Stringify other values for display\n        attributeValue = JSON.stringify(attributeValue);\n      }\n\n      const regex = new RegExp(alias, \"g\");\n      replacedString = replacedString.replace(regex, attributeValue as string);\n    }\n\n    return replacedString;\n  }\n\n  if (command.updateExpression) {\n    result.updateExpression = replaceAliases(command.updateExpression);\n  }\n  if (command.conditionExpression) {\n    result.conditionExpression = replaceAliases(command.conditionExpression);\n  }\n  if (command.filterExpression) {\n    result.filterExpression = replaceAliases(command.filterExpression);\n  }\n  if (command.keyConditionExpression) {\n    result.keyConditionExpression = replaceAliases(command.keyConditionExpression);\n  }\n  if (command.projectionExpression) {\n    result.projectionExpression = replaceAliases(command.projectionExpression);\n  }\n\n  return {\n    raw: command,\n    readable: result,\n  };\n}\n","import type { Condition, ConditionOperator } from \"../conditions\";\nimport {\n  eq,\n  ne,\n  lt,\n  lte,\n  gt,\n  gte,\n  between,\n  beginsWith,\n  contains,\n  attributeExists,\n  attributeNotExists,\n  and,\n  or,\n  not,\n} from \"../conditions\";\nimport type { TransactionBuilder } from \"./transaction-builder\";\nimport { prepareExpressionParams } from \"../expression\";\nimport { debugCommand } from \"../utils/debug-expression\";\nimport type { PutCommandParams } from \"./builder-types\";\nimport type { Path, PathType } from \"./types\";\nimport type { DynamoItem } from \"../types\";\n\n/**\n * Configuration options for DynamoDB put operations.\n */\nexport interface PutOptions {\n  /** Optional condition that must be satisfied for the put operation to succeed */\n  condition?: Condition;\n  /** Determines how to handle the return value of the put operation\n   * @options\n   *  - NONE: No return value\n   *  - ALL_OLD: Returns the item's previous state if it existed\n   *  - CONSISTENT: (default) Performs a GET operation after the put to retrieve the item's new state\n   */\n  returnValues?: \"ALL_OLD\" | \"NONE\" | \"CONSISTENT\";\n}\n\ntype PutExecutor<T extends DynamoItem> = (params: PutCommandParams) => Promise<T>;\n\n/**\n * Builder for creating DynamoDB put operations.\n *\n * @example\n * ```typescript\n * // Add new dinosaur\n * const result = await new PutBuilder(executor, {\n *   id: 'RAPTOR-001',\n *   species: 'Velociraptor',\n *   status: 'ACTIVE',\n *   stats: {\n *     health: 100,\n *     age: 5,\n *     threatLevel: 8\n *   }\n * }, 'dinosaurs').execute();\n *\n * // Create new habitat with conditions\n * const result = await new PutBuilder(executor, {\n *   id: 'PADDOCK-C',\n *   type: 'CARNIVORE',\n *   securityLevel: 'MAXIMUM',\n *   capacity: 3,\n *   environmentType: 'TROPICAL'\n * }, 'habitats')\n *   .condition(op => op.attributeNotExists('id'))\n *   .execute();\n * ```\n *\n * @typeParam T - The type of item being put into the table\n */\nexport class PutBuilder<T extends DynamoItem> {\n  private readonly item: T;\n  private options: PutOptions;\n  private readonly executor: PutExecutor<T>;\n  private readonly tableName: string;\n\n  constructor(executor: PutExecutor<T>, item: T, tableName: string) {\n    this.executor = executor;\n    this.item = item;\n    this.tableName = tableName;\n    this.options = {\n      returnValues: \"NONE\",\n    };\n  }\n\n  /**\n   * Sets multiple attributes of an item using an DynamoItem.\n   *\n   * @example\n   * ```typescript\n   * // Update multiple attributes\n   * builder.set({\n   *   species: 'Tyrannosaurus Rex',\n   *   height: 20,\n   *   diet: 'CARNIVORE',\n   *   'stats.threatLevel': 10\n   * });\n   * ```\n   */\n  set(values: Partial<T>): this;\n\n  /**\n   * Sets a single attribute to a specific value.\n   *\n   * @example\n   * ```typescript\n   * // Set simple attributes\n   * builder\n   *   .set('status', 'SLEEPING')\n   *   .set('lastFeeding', new Date().toISOString());\n   *\n   * // Set nested attributes\n   * builder\n   *   .set('location.zone', 'RESTRICTED')\n   *   .set('stats.health', 100);\n   * ```\n   */\n  set<K extends Path<T>>(path: K, value: PathType<T, K>): this;\n  set<K extends Path<T>>(valuesOrPath: K | Partial<T>, value?: PathType<T, K>): this {\n    if (typeof valuesOrPath === \"object\") {\n      Object.assign(this.item, valuesOrPath);\n    } else {\n      // @ts-ignore\n      this.item[valuesOrPath] = value;\n    }\n    return this;\n  }\n\n  /**\n   * Adds a condition that must be satisfied for the put operation to succeed.\n   * Use this method when you need to:\n   * - Prevent overwriting existing items (optimistic locking)\n   * - Ensure items meet certain criteria before replacement\n   * - Implement complex business rules for item updates\n   *\n   * @example\n   * ```ts\n   * // Ensure item doesn't exist (insert only)\n   * builder.condition(op => op.attributeNotExists('id'))\n   *\n   * // Complex condition with version check\n   * builder.condition(op =>\n   *   op.and([\n   *     op.attributeExists('id'),\n   *     op.eq('version', currentVersion),\n   *     op.eq('status', 'ACTIVE')\n   *   ])\n   * )\n   * ```\n   *\n   * @param condition - Either a Condition object or a callback function that builds the condition\n   * @returns The builder instance for method chaining\n   */\n  /**\n   * Adds a condition that must be satisfied for the put operation to succeed.\n   *\n   * @example\n   * ```typescript\n   * // Ensure unique dinosaur ID\n   * builder.condition(op =>\n   *   op.attributeNotExists('id')\n   * );\n   *\n   * // Verify habitat requirements\n   * builder.condition(op =>\n   *   op.and([\n   *     op.eq('securityStatus', 'READY'),\n   *     op.attributeExists('lastInspection'),\n   *     op.gt('securityLevel', 5)\n   *   ])\n   * );\n   *\n   * // Check breeding facility conditions\n   * builder.condition(op =>\n   *   op.and([\n   *     op.between('temperature', 25, 30),\n   *     op.between('humidity', 60, 80),\n   *     op.eq('quarantineStatus', 'CLEAR')\n   *   ])\n   * );\n   * ```\n   *\n   * @param condition - Either a Condition object or a callback function that builds the condition\n   * @returns The builder instance for method chaining\n   */\n  public condition(condition: Condition | ((op: ConditionOperator<T>) => Condition)): this {\n    if (typeof condition === \"function\") {\n      const conditionOperator: ConditionOperator<T> = {\n        eq,\n        ne,\n        lt,\n        lte,\n        gt,\n        gte,\n        between,\n        beginsWith,\n        contains,\n        attributeExists,\n        attributeNotExists,\n        and,\n        or,\n        not,\n      };\n      this.options.condition = condition(conditionOperator);\n    } else {\n      this.options.condition = condition;\n    }\n    return this;\n  }\n\n  /**\n   * Sets whether to return the item's previous values (if it existed).\n   *\n   * @options\n   *  - NONE: No return value\n   *  - ALL_OLD: Returns the item's previous state if it existed, no read capacity units are consumed\n   *  - CONSISTENT: (default) Performs a GET operation after the put to retrieve the item's new state\n   *\n   * @example\n   * ```ts\n   * // Get previous dinosaur state\n   * const result = await builder\n   *   .returnValues('ALL_OLD')\n   *   .execute();\n   *\n   * if (result) {\n   *   console.log('Previous profile:', {\n   *     species: result.species,\n   *     status: result.status,\n   *     stats: {\n   *       health: result.stats.health,\n   *       threatLevel: result.stats.threatLevel\n   *     }\n   *   });\n   * }\n   * ```\n   *\n   * @param returnValues - Use 'ALL_OLD' to return previous values if the item was overwritten, or 'NONE' (default).\n   * @returns The builder instance for method chaining\n   */\n  public returnValues(returnValues: \"ALL_OLD\" | \"NONE\" | \"CONSISTENT\"): this {\n    this.options.returnValues = returnValues;\n    return this;\n  }\n\n  /**\n   * Generate the DynamoDB command parameters\n   */\n  private toDynamoCommand(): PutCommandParams {\n    const { expression, names, values } = prepareExpressionParams(this.options.condition);\n\n    return {\n      tableName: this.tableName,\n      item: this.item,\n      conditionExpression: expression,\n      expressionAttributeNames: names,\n      expressionAttributeValues: values,\n      returnValues: this.options.returnValues,\n    };\n  }\n\n  /**\n   * Adds this put operation to a transaction.\n   * Use this method when you need to:\n   * - Transfer dinosaurs between habitats\n   * - Initialize new breeding programs\n   * - Update multiple facility records\n   *\n   * @example\n   * ```ts\n   * const transaction = new TransactionBuilder();\n   *\n   * // Add dinosaur to new habitat\n   * new PutBuilder(executor, {\n   *   id: 'TREX-002',\n   *   location: 'PADDOCK-B',\n   *   status: 'ACTIVE',\n   *   transferDate: new Date().toISOString()\n   * }, 'dinosaurs')\n   *   .withTransaction(transaction);\n   *\n   * // Update habitat records\n   * new UpdateBuilder(executor, 'habitats', { id: 'PADDOCK-B' })\n   *   .add('occupants', 1)\n   *   .set('lastTransfer', new Date().toISOString())\n   *   .withTransaction(transaction);\n   *\n   * // Execute transfer atomically\n   * await transaction.execute();\n   * ```\n   *\n   * @param transaction - The transaction builder to add this operation to\n   * @returns The builder instance for method chaining\n   */\n  public withTransaction(transaction: TransactionBuilder): this {\n    const command = this.toDynamoCommand();\n    transaction.putWithCommand(command);\n\n    return this;\n  }\n\n  /**\n   * Executes the put operation against DynamoDB.\n   *\n   * @example\n   * ```ts\n   * try {\n   *   // Put with condition and return old values\n   *   const result = await new PutBuilder(executor, newItem, 'myTable')\n   *     .condition(op => op.eq('version', 1))\n   *     .returnValues('ALL_OLD')\n   *     .execute();\n   *\n   *   console.log('Put successful, old item:', result);\n   * } catch (error) {\n   *   // Handle condition check failure or other errors\n   *   console.error('Put failed:', error);\n   * }\n   * ```\n   *\n   * @returns A promise that resolves to the operation result (type depends on returnValues setting)\n   * @throws Will throw an error if the condition check fails or other DynamoDB errors occur\n   */\n  public async execute(): Promise<T | undefined> {\n    const params = this.toDynamoCommand();\n    return this.executor(params);\n  }\n\n  /**\n   * Gets a human-readable representation of the put command\n   * with all expression placeholders replaced by their actual values.\n   *\n   * @example\n   * ```ts\n   * const debugInfo = new PutBuilder(executor, {\n   *   id: 'RAPTOR-003',\n   *   species: 'Velociraptor',\n   *   status: 'QUARANTINE',\n   *   stats: {\n   *     health: 100,\n   *     aggressionLevel: 7,\n   *     age: 2\n   *   }\n   * }, 'dinosaurs')\n   *   .condition(op =>\n   *     op.and([\n   *       op.attributeNotExists('id'),\n   *       op.eq('quarantineStatus', 'READY'),\n   *       op.gt('securityLevel', 8)\n   *     ])\n   *   )\n   *   .debug();\n   *\n   * console.log('Dinosaur transfer command:', debugInfo);\n   * ```\n   *\n   * @returns A readable representation of the put command with resolved expressions\n   */\n  public debug(): DynamoItem {\n    const command = this.toDynamoCommand();\n    return debugCommand(command);\n  }\n}\n"]}

package/dist/builders/put-builder.d.cts

@@ -0,0 +1,274 @@
+import { C as Condition, c as Path, d as PathType, b as ConditionOperator } from '../conditions-ChhQWd6z.cjs';
+import { TransactionBuilder } from './transaction-builder.cjs';
+import { a as PutCommandParams } from '../builder-types-DtwbqMeF.cjs';
+import { DynamoItem } from '../types.cjs';
+import '@aws-sdk/lib-dynamodb';
+
+/**
+ * Configuration options for DynamoDB put operations.
+ */
+interface PutOptions {
+    /** Optional condition that must be satisfied for the put operation to succeed */
+    condition?: Condition;
+    /** Determines how to handle the return value of the put operation
+     * @options
+     *  - NONE: No return value
+     *  - ALL_OLD: Returns the item's previous state if it existed
+     *  - CONSISTENT: (default) Performs a GET operation after the put to retrieve the item's new state
+     */
+    returnValues?: "ALL_OLD" | "NONE" | "CONSISTENT";
+}
+type PutExecutor<T extends DynamoItem> = (params: PutCommandParams) => Promise<T>;
+/**
+ * Builder for creating DynamoDB put operations.
+ *
+ * @example
+ * ```typescript
+ * // Add new dinosaur
+ * const result = await new PutBuilder(executor, {
+ *   id: 'RAPTOR-001',
+ *   species: 'Velociraptor',
+ *   status: 'ACTIVE',
+ *   stats: {
+ *     health: 100,
+ *     age: 5,
+ *     threatLevel: 8
+ *   }
+ * }, 'dinosaurs').execute();
+ *
+ * // Create new habitat with conditions
+ * const result = await new PutBuilder(executor, {
+ *   id: 'PADDOCK-C',
+ *   type: 'CARNIVORE',
+ *   securityLevel: 'MAXIMUM',
+ *   capacity: 3,
+ *   environmentType: 'TROPICAL'
+ * }, 'habitats')
+ *   .condition(op => op.attributeNotExists('id'))
+ *   .execute();
+ * ```
+ *
+ * @typeParam T - The type of item being put into the table
+ */
+declare class PutBuilder<T extends DynamoItem> {
+    private readonly item;
+    private options;
+    private readonly executor;
+    private readonly tableName;
+    constructor(executor: PutExecutor<T>, item: T, tableName: string);
+    /**
+     * Sets multiple attributes of an item using an DynamoItem.
+     *
+     * @example
+     * ```typescript
+     * // Update multiple attributes
+     * builder.set({
+     *   species: 'Tyrannosaurus Rex',
+     *   height: 20,
+     *   diet: 'CARNIVORE',
+     *   'stats.threatLevel': 10
+     * });
+     * ```
+     */
+    set(values: Partial<T>): this;
+    /**
+     * Sets a single attribute to a specific value.
+     *
+     * @example
+     * ```typescript
+     * // Set simple attributes
+     * builder
+     *   .set('status', 'SLEEPING')
+     *   .set('lastFeeding', new Date().toISOString());
+     *
+     * // Set nested attributes
+     * builder
+     *   .set('location.zone', 'RESTRICTED')
+     *   .set('stats.health', 100);
+     * ```
+     */
+    set<K extends Path<T>>(path: K, value: PathType<T, K>): 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: Condition | ((op: ConditionOperator<T>) => Condition)): 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: "ALL_OLD" | "NONE" | "CONSISTENT"): this;
+    /**
+     * Generate the DynamoDB command parameters
+     */
+    private toDynamoCommand;
+    /**
+     * 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: TransactionBuilder): 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
+     */
+    execute(): Promise<T | undefined>;
+    /**
+     * 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(): DynamoItem;
+}
+
+export { PutBuilder, type PutOptions };