dyno-table 0.1.7 → 0.1.8

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Scott Maunder
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -28,23 +28,45 @@ await table
 
 ## 📑 Table of Contents
 
-- [Installation](#-installation)
-- [Quick Start](#-quick-start)
-- [Query](#-type-safe-query-building)
-- [Update](#update-operations)
-  - [Condition Operators](#condition-operators)
-  - [Multiple Operations](#multiple-operations)
-- [Type Safety Features](#-type-safety-features)
-  - [Nested Object Support](#nested-object-support)
-  - [Type-Safe Conditions](#type-safe-conditions)
-- [Batch Operations](#-batch-operations)
-  - [Batch Get](#batch-get)
-  - [Batch Write](#batch-write)
-- [Transaction Operations](#-transaction-operations)
-  - [Transaction Builder](#transaction-builder)
-  - [Transaction Options](#transaction-options)
-- [Error Handling](#-error-handling)
-- [API Reference](#-api-reference)
+- [🦖 dyno-table  ](#-dyno-table--)
+  - [🌟 Why dyno-table?](#-why-dyno-table)
+  - [📑 Table of Contents](#-table-of-contents)
+  - [📦 Installation](#-installation)
+  - [🚀 Quick Start](#-quick-start)
+    - [1. Configure Your Table](#1-configure-your-table)
+    - [2. Perform Type-Safe Operations](#2-perform-type-safe-operations)
+  - [🧩 Advanced Features](#-advanced-features)
+    - [Transactional Operations](#transactional-operations)
+    - [Batch Processing](#batch-processing)
+    - [Pagination Made Simple](#pagination-made-simple)
+  - [🛡️ Type-Safe Query Building](#️-type-safe-query-building)
+    - [Comparison Operators](#comparison-operators)
+    - [Logical Operators](#logical-operators)
+    - [Query Operations](#query-operations)
+    - [Put Operations](#put-operations)
+    - [Update Operations](#update-operations)
+      - [Condition Operators](#condition-operators)
+      - [Multiple Operations](#multiple-operations)
+  - [🔄 Type Safety Features](#-type-safety-features)
+    - [Nested Object Support](#nested-object-support)
+    - [Type-Safe Conditions](#type-safe-conditions)
+  - [🔄 Batch Operations](#-batch-operations)
+    - [Batch Get](#batch-get)
+    - [Batch Write](#batch-write)
+  - [🔒 Transaction Operations](#-transaction-operations)
+    - [Transaction Builder](#transaction-builder)
+    - [Transaction Options](#transaction-options)
+  - [🏗️ Entity Pattern Best Practices (Coming Soon TM)](#️-entity-pattern-best-practices-coming-soon-tm)
+  - [🚨 Error Handling](#-error-handling)
+  - [📚 API Reference](#-api-reference)
+    - [Condition Operators](#condition-operators-1)
+      - [Comparison Operators](#comparison-operators-1)
+      - [Attribute Operators](#attribute-operators)
+      - [Logical Operators](#logical-operators-1)
+    - [Key Condition Operators](#key-condition-operators)
+  - [🔮 Future Roadmap](#-future-roadmap)
+  - [🤝 Contributing](#-contributing)
+  - [🦔 Running Examples](#-running-examples)
 
 ## 📦 Installation
 
@@ -426,6 +448,51 @@ const limited = await table
   .execute();
 ```
 
+### Put Operations
+
+| Operation           | Method Example                                                      | Description                                                            |
+|---------------------|---------------------------------------------------------------------|------------------------------------------------------------------------|
+| **Create New Item** | `.create<Dinosaur>({ pk: "SPECIES#trex", sk: "PROFILE#001", ... })` | Creates a new item with a condition to ensure it doesn't already exist |
+| **Put Item**        | `.put<Dinosaur>({ pk: "SPECIES#trex", sk: "PROFILE#001", ... })`    | Creates or replaces an item                                            |
+| **With Condition**  | `.put(item).condition(op => op.attributeNotExists("pk"))`           | Adds a condition that must be satisfied                                |
+
+#### Return Values
+
+Control what data is returned from put operations:
+
+| Option         | Description                                                                                                        | Example                                           |
+|----------------|--------------------------------------------------------------------------------------------------------------------|---------------------------------------------------|
+| **NONE**       | Default. No return value.                                                                                          | `.put(item).returnValues("NONE").execute()`       |
+| **ALL_OLD**    | Returns the item's previous state if it existed. (Does not consume any RCU and returns strongly consistent values) | `.put(item).returnValues("ALL_OLD").execute()`    |
+| **CONSISTENT** | Performs a consistent GET operation after the put to retrieve the item's new state. (Does consume RCU)             | `.put(item).returnValues("CONSISTENT").execute()` |
+
+```ts
+// Create with no return value (default)
+await table.put<Dinosaur>({
+  pk: "SPECIES#trex",
+  sk: "PROFILE#001",
+  name: "Tyrannosaurus Rex",
+  diet: "carnivore"
+}).execute();
+
+// Create and return the newly created item
+const newDino = await table.put<Dinosaur>({
+  pk: "SPECIES#trex",
+  sk: "PROFILE#002",
+  name: "Tyrannosaurus Rex",
+  diet: "carnivore"
+}).returnValues("CONSISTENT").execute();
+
+// Update with condition and get previous values
+const oldDino = await table.put<Dinosaur>({
+  pk: "SPECIES#trex",
+  sk: "PROFILE#001",
+  name: "Tyrannosaurus Rex",
+  diet: "omnivore", // Updated diet
+  discoveryYear: 1905
+}).returnValues("ALL_OLD").execute();
+```
+
 ### Update Operations
 
 | Operation            | Method Example                                        | Generated Expression |
@@ -782,3 +849,34 @@ pnpm test
 # Build the project
 pnpm build
 ```
+
+## 🦔 Running Examples
+
+There's a few pre-configured example scripts in the `examples` directory.
+
+First you'll need to install the dependencies:
+
+```bash
+pnpm install
+```
+Then setup the test table in local DynamoDB by running the following command:
+
+```bash
+pnpm run ddb:start
+pnpm run local:setup
+```
+
+To run the examples, you can use the following command:
+
+```bash
+npx tsx examples/[EXAMPLE_NAME].ts
+```
+
+To view the test table GUI in action: [DynamoDB Admin](http://localhost:8001/)
+
+<br />
+To teardown the test table when you're done, run the following command:
+
+```bash
+pnpm run local:teardown
+```

package/dist/builders/condition-check-builder.cjs

@@ -0,0 +1,394 @@
+'use strict';
+
+// src/conditions.ts
+var createComparisonCondition = (type) => (attr, value) => ({
+  type,
+  attr,
+  value
+});
+var eq = createComparisonCondition("eq");
+var ne = createComparisonCondition("ne");
+var lt = createComparisonCondition("lt");
+var lte = createComparisonCondition("lte");
+var gt = createComparisonCondition("gt");
+var gte = createComparisonCondition("gte");
+var between = (attr, lower, upper) => ({
+  type: "between",
+  attr,
+  value: [lower, upper]
+});
+var beginsWith = createComparisonCondition("beginsWith");
+var contains = createComparisonCondition("contains");
+var attributeExists = (attr) => ({
+  type: "attributeExists",
+  attr
+});
+var attributeNotExists = (attr) => ({
+  type: "attributeNotExists",
+  attr
+});
+var and = (...conditions) => ({
+  type: "and",
+  conditions
+});
+var or = (...conditions) => ({
+  type: "or",
+  conditions
+});
+var not = (condition) => ({
+  type: "not",
+  condition
+});
+
+// src/expression.ts
+var generateAttributeName = (params, attr) => {
+  for (const [existingName, existingAttr] of Object.entries(params.expressionAttributeNames)) {
+    if (existingAttr === attr) {
+      return existingName;
+    }
+  }
+  const attrName = `#${Object.keys(params.expressionAttributeNames).length}`;
+  params.expressionAttributeNames[attrName] = attr;
+  return attrName;
+};
+var generateValueName = (params, value) => {
+  const valueName = `:${params.valueCounter.count++}`;
+  params.expressionAttributeValues[valueName] = value;
+  return valueName;
+};
+var validateCondition = (condition, requiresAttr = true, requiresValue = true) => {
+  if (requiresAttr && !condition.attr) {
+    throw new Error(`Attribute is required for ${condition.type} condition`);
+  }
+  if (requiresValue && condition.value === void 0) {
+    throw new Error(`Value is required for ${condition.type} condition`);
+  }
+};
+var buildComparisonExpression = (condition, operator, params) => {
+  validateCondition(condition);
+  if (!condition.attr) {
+    throw new Error(`Attribute is required for ${condition.type} condition`);
+  }
+  const attrName = generateAttributeName(params, condition.attr);
+  const valueName = generateValueName(params, condition.value);
+  return `${attrName} ${operator} ${valueName}`;
+};
+var buildBetweenExpression = (condition, params) => {
+  validateCondition(condition);
+  if (!condition.attr) {
+    throw new Error(`Attribute is required for ${condition.type} condition`);
+  }
+  if (!Array.isArray(condition.value) || condition.value.length !== 2) {
+    throw new Error("Between condition requires an array of two values");
+  }
+  const attrName = generateAttributeName(params, condition.attr);
+  const lowerName = generateValueName(params, condition.value[0]);
+  const upperName = generateValueName(params, condition.value[1]);
+  return `${attrName} BETWEEN ${lowerName} AND ${upperName}`;
+};
+var buildFunctionExpression = (functionName, condition, params) => {
+  validateCondition(condition);
+  if (!condition.attr) {
+    throw new Error(`Attribute is required for ${condition.type} condition`);
+  }
+  const attrName = generateAttributeName(params, condition.attr);
+  const valueName = generateValueName(params, condition.value);
+  return `${functionName}(${attrName}, ${valueName})`;
+};
+var buildAttributeFunction = (functionName, condition, params) => {
+  validateCondition(condition, true, false);
+  if (!condition.attr) {
+    throw new Error(`Attribute is required for ${condition.type} condition`);
+  }
+  const attrName = generateAttributeName(params, condition.attr);
+  return `${functionName}(${attrName})`;
+};
+var buildLogicalExpression = (operator, conditions, params) => {
+  if (!conditions || conditions.length === 0) {
+    throw new Error(`At least one condition is required for ${operator} expression`);
+  }
+  const expressions = conditions.map((c) => buildExpression(c, params));
+  return `(${expressions.join(` ${operator} `)})`;
+};
+var buildExpression = (condition, params) => {
+  if (!condition) return "";
+  try {
+    const expressionBuilders = {
+      eq: () => buildComparisonExpression(condition, "=", params),
+      ne: () => buildComparisonExpression(condition, "<>", params),
+      lt: () => buildComparisonExpression(condition, "<", params),
+      lte: () => buildComparisonExpression(condition, "<=", params),
+      gt: () => buildComparisonExpression(condition, ">", params),
+      gte: () => buildComparisonExpression(condition, ">=", params),
+      between: () => buildBetweenExpression(condition, params),
+      beginsWith: () => buildFunctionExpression("begins_with", condition, params),
+      contains: () => buildFunctionExpression("contains", condition, params),
+      attributeExists: () => buildAttributeFunction("attribute_exists", condition, params),
+      attributeNotExists: () => buildAttributeFunction("attribute_not_exists", condition, params),
+      and: () => {
+        if (!condition.conditions) {
+          throw new Error("Conditions array is required for AND operator");
+        }
+        return buildLogicalExpression("AND", condition.conditions, params);
+      },
+      or: () => {
+        if (!condition.conditions) {
+          throw new Error("Conditions array is required for OR operator");
+        }
+        return buildLogicalExpression("OR", condition.conditions, params);
+      },
+      not: () => {
+        if (!condition.condition) {
+          throw new Error("Condition is required for NOT operator");
+        }
+        return `NOT (${buildExpression(condition.condition, params)})`;
+      }
+    };
+    const builder = expressionBuilders[condition.type];
+    if (!builder) {
+      throw new Error(`Unknown condition type: ${condition.type}`);
+    }
+    return builder();
+  } catch (error) {
+    if (error instanceof Error) {
+      console.error(`Error building expression for condition type ${condition.type}:`, error.message);
+    } else {
+      console.error(`Error building expression for condition type ${condition.type}:`, error);
+    }
+    throw error;
+  }
+};
+var prepareExpressionParams = (condition) => {
+  if (!condition) return {};
+  const params = {
+    expressionAttributeNames: {},
+    expressionAttributeValues: {},
+    valueCounter: { count: 0 }
+  };
+  const expression = buildExpression(condition, params);
+  return {
+    expression,
+    names: Object.keys(params.expressionAttributeNames).length > 0 ? params.expressionAttributeNames : void 0,
+    values: Object.keys(params.expressionAttributeValues).length > 0 ? params.expressionAttributeValues : void 0
+  };
+};
+
+// src/utils/debug-expression.ts
+function debugCommand(command) {
+  const result = {};
+  function replaceAliases(expressionString) {
+    if (!expressionString) {
+      return expressionString;
+    }
+    let replacedString = expressionString;
+    for (const alias in command.expressionAttributeNames) {
+      const attributeName = command.expressionAttributeNames[alias];
+      const regex = new RegExp(alias, "g");
+      replacedString = replacedString.replace(regex, attributeName);
+    }
+    for (const alias in command.expressionAttributeValues) {
+      let attributeValue = command.expressionAttributeValues[alias];
+      if (attributeValue instanceof Set) {
+        const array = Array.from(attributeValue);
+        attributeValue = `Set(${array.length}){${array.map((v) => JSON.stringify(v)).join(", ")}}`;
+      } else {
+        attributeValue = JSON.stringify(attributeValue);
+      }
+      const regex = new RegExp(alias, "g");
+      replacedString = replacedString.replace(regex, attributeValue);
+    }
+    return replacedString;
+  }
+  if (command.updateExpression) {
+    result.updateExpression = replaceAliases(command.updateExpression);
+  }
+  if (command.conditionExpression) {
+    result.conditionExpression = replaceAliases(command.conditionExpression);
+  }
+  if (command.filterExpression) {
+    result.filterExpression = replaceAliases(command.filterExpression);
+  }
+  if (command.keyConditionExpression) {
+    result.keyConditionExpression = replaceAliases(command.keyConditionExpression);
+  }
+  if (command.projectionExpression) {
+    result.projectionExpression = replaceAliases(command.projectionExpression);
+  }
+  return {
+    raw: command,
+    readable: result
+  };
+}
+
+// src/builders/condition-check-builder.ts
+var ConditionCheckBuilder = class {
+  key;
+  tableName;
+  conditionExpression;
+  constructor(tableName, key) {
+    this.tableName = tableName;
+    this.key = key;
+  }
+  /**
+   * Adds a condition that must be satisfied for the check to succeed.
+   * Use this method when you need to:
+   * - Validate complex item states
+   * - Check multiple attributes together
+   * - Ensure safety conditions are met
+   *
+   * @example
+   * ```typescript
+   * // Check dinosaur health and behavior
+   * builder.condition(op =>
+   *   op.and([
+   *     op.gt('stats.health', 50),
+   *     op.not(op.eq('status', 'SEDATED')),
+   *     op.lt('aggressionLevel', 8)
+   *   ])
+   * );
+   *
+   * // Verify habitat conditions
+   * builder.condition(op =>
+   *   op.and([
+   *     op.eq('powerStatus', 'ONLINE'),
+   *     op.between('temperature', 20, 30),
+   *     op.attributeExists('lastMaintenance')
+   *   ])
+   * );
+   *
+   * // Check breeding conditions
+   * builder.condition(op =>
+   *   op.and([
+   *     op.eq('species', 'VELOCIRAPTOR'),
+   *     op.gte('age', 3),
+   *     op.eq('geneticPurity', 100)
+   *   ])
+   * );
+   * ```
+   *
+   * @param condition - Either a Condition object or a callback function that builds the condition
+   * @returns The builder instance for method chaining
+   */
+  condition(condition) {
+    if (typeof condition === "function") {
+      const conditionOperator = {
+        eq,
+        ne,
+        lt,
+        lte,
+        gt,
+        gte,
+        between,
+        beginsWith,
+        contains,
+        attributeExists,
+        attributeNotExists,
+        and,
+        or,
+        not
+      };
+      this.conditionExpression = condition(conditionOperator);
+    } else {
+      this.conditionExpression = condition;
+    }
+    return this;
+  }
+  /**
+   * Generates the DynamoDB command parameters for direct execution.
+   * Use this method when you want to:
+   * - Execute the condition check as a standalone operation
+   * - Get the raw DynamoDB command for custom execution
+   * - Inspect the generated command parameters
+   *
+   * @example
+   * ```ts
+   * const command = new ConditionCheckBuilder('myTable', { id: '123' })
+   *   .condition(op => op.attributeExists('status'))
+   *   .toDynamoCommand();
+   * // Use command with DynamoDB client
+   * ```
+   *
+   * @throws {Error} If no condition has been set
+   * @returns The DynamoDB command parameters
+   */
+  toDynamoCommand() {
+    if (!this.conditionExpression) {
+      throw new Error("Condition is required for condition check operations");
+    }
+    const { expression, names, values } = prepareExpressionParams(this.conditionExpression);
+    if (!expression) {
+      throw new Error("Failed to generate condition expression");
+    }
+    return {
+      tableName: this.tableName,
+      key: this.key,
+      conditionExpression: expression,
+      expressionAttributeNames: names,
+      expressionAttributeValues: values
+    };
+  }
+  /**
+   * Adds this condition check operation to a transaction.
+   * Use this method when you need to:
+   * - Verify habitat safety before transfers
+   * - Ensure proper feeding conditions
+   * - Validate security protocols
+   *
+   * @example
+   * ```ts
+   * const transaction = new TransactionBuilder();
+   * new ConditionCheckBuilder('habitats', { id: 'PADDOCK-B' })
+   *   .condition(op => op.and([
+   *     op.eq('securityStatus', 'ACTIVE'),
+   *     op.lt('currentOccupants', 3),
+   *     op.eq('habitatType', 'CARNIVORE')
+   *   ]))
+   *   .withTransaction(transaction);
+   * // Add dinosaur transfer operations
+   * ```
+   *
+   * @param transaction - The transaction builder to add this operation to
+   * @throws {Error} If no condition has been set
+   * @returns The builder instance for method chaining
+   */
+  withTransaction(transaction) {
+    if (!this.conditionExpression) {
+      throw new Error("Condition is required for condition check operations");
+    }
+    const command = this.toDynamoCommand();
+    transaction.conditionCheckWithCommand(command);
+    return this;
+  }
+  /**
+   * Gets a human-readable representation of the condition check command
+   * with all expression placeholders replaced by their actual values.
+   * Use this method when you need to:
+   * - Debug complex condition expressions
+   * - Verify condition parameters
+   * - Log safety checks
+   * - Troubleshoot condition failures
+   *
+   * @example
+   * ```ts
+   * const debugInfo = new ConditionCheckBuilder('dinosaurs', { id: 'TREX-001' })
+   *   .condition(op => op.and([
+   *     op.between('stats.health', 50, 100),
+   *     op.not(op.eq('status', 'SEDATED')),
+   *     op.attributeExists('lastFeedingTime')
+   *     op.eq('version', 1)
+   *   ]))
+   *   .debug();
+   * console.log(debugInfo);
+   * ```
+   *
+   * @returns A readable representation of the condition check command with resolved expressions
+   */
+  debug() {
+    const command = this.toDynamoCommand();
+    return debugCommand(command);
+  }
+};
+
+exports.ConditionCheckBuilder = ConditionCheckBuilder;
+//# sourceMappingURL=condition-check-builder.cjs.map
+//# sourceMappingURL=condition-check-builder.cjs.map

package/dist/builders/condition-check-builder.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/conditions.ts","../../src/expression.ts","../../src/utils/debug-expression.ts","../../src/builders/condition-check-builder.ts"],"names":[],"mappings":"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","file":"condition-check-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, PrimaryKeyWithoutExpression } 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 type { DynamoCommandWithExpressions } from \"../utils/debug-expression\";\nimport { debugCommand } from \"../utils/debug-expression\";\nimport type { ConditionCheckCommandParams } from \"./builder-types\";\n\n/**\n * Builder for creating DynamoDB condition check operations.\n * Use this builder when you need to:\n * - Verify item state without modifying it\n * - Ensure preconditions in transactions\n * - Implement optimistic locking patterns\n * - Validate business rules\n *\n * @example\n * ```typescript\n * // Check if dinosaur is ready for feeding\n * const check = new ConditionCheckBuilder('dinosaurs', { id: 'TREX-001' })\n *   .condition(op =>\n *     op.and([\n *       op.eq('status', 'HUNTING'),\n *       op.gt('stats.hunger', 80),\n *       op.lt('stats.health', 100)\n *     ])\n *   )\n *   .toDynamoCommand();\n *\n * // Check habitat security status\n * const securityCheck = new ConditionCheckBuilder('habitats', { id: 'PADDOCK-A' })\n *   .condition(op =>\n *     op.and([\n *       op.eq('securityStatus', 'ACTIVE'),\n *       op.attributeExists('lastInspection'),\n *       op.lt('threatLevel', 5)\n *     ])\n *   )\n *   .toDynamoCommand();\n * ```\n */\nexport class ConditionCheckBuilder {\n  private readonly key: PrimaryKeyWithoutExpression;\n  private readonly tableName: string;\n  private conditionExpression?: Condition;\n\n  constructor(tableName: string, key: PrimaryKeyWithoutExpression) {\n    this.tableName = tableName;\n    this.key = key;\n  }\n\n  /**\n   * Adds a condition that must be satisfied for the check to succeed.\n   * Use this method when you need to:\n   * - Validate complex item states\n   * - Check multiple attributes together\n   * - Ensure safety conditions are met\n   *\n   * @example\n   * ```typescript\n   * // Check dinosaur health and behavior\n   * builder.condition(op =>\n   *   op.and([\n   *     op.gt('stats.health', 50),\n   *     op.not(op.eq('status', 'SEDATED')),\n   *     op.lt('aggressionLevel', 8)\n   *   ])\n   * );\n   *\n   * // Verify habitat conditions\n   * builder.condition(op =>\n   *   op.and([\n   *     op.eq('powerStatus', 'ONLINE'),\n   *     op.between('temperature', 20, 30),\n   *     op.attributeExists('lastMaintenance')\n   *   ])\n   * );\n   *\n   * // Check breeding conditions\n   * builder.condition(op =>\n   *   op.and([\n   *     op.eq('species', 'VELOCIRAPTOR'),\n   *     op.gte('age', 3),\n   *     op.eq('geneticPurity', 100)\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  condition<T extends Record<string, unknown>>(\n    condition: Condition | ((op: ConditionOperator<T>) => Condition),\n  ): ConditionCheckBuilder {\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.conditionExpression = condition(conditionOperator);\n    } else {\n      this.conditionExpression = condition;\n    }\n    return this;\n  }\n\n  /**\n   * Generates the DynamoDB command parameters for direct execution.\n   * Use this method when you want to:\n   * - Execute the condition check as a standalone operation\n   * - Get the raw DynamoDB command for custom execution\n   * - Inspect the generated command parameters\n   *\n   * @example\n   * ```ts\n   * const command = new ConditionCheckBuilder('myTable', { id: '123' })\n   *   .condition(op => op.attributeExists('status'))\n   *   .toDynamoCommand();\n   * // Use command with DynamoDB client\n   * ```\n   *\n   * @throws {Error} If no condition has been set\n   * @returns The DynamoDB command parameters\n   */\n  private toDynamoCommand(): ConditionCheckCommandParams {\n    if (!this.conditionExpression) {\n      throw new Error(\"Condition is required for condition check operations\");\n    }\n\n    const { expression, names, values } = prepareExpressionParams(this.conditionExpression);\n\n    if (!expression) {\n      throw new Error(\"Failed to generate condition expression\");\n    }\n\n    return {\n      tableName: this.tableName,\n      key: this.key,\n      conditionExpression: expression,\n      expressionAttributeNames: names,\n      expressionAttributeValues: values,\n    };\n  }\n\n  /**\n   * Adds this condition check operation to a transaction.\n   * Use this method when you need to:\n   * - Verify habitat safety before transfers\n   * - Ensure proper feeding conditions\n   * - Validate security protocols\n   *\n   * @example\n   * ```ts\n   * const transaction = new TransactionBuilder();\n   * new ConditionCheckBuilder('habitats', { id: 'PADDOCK-B' })\n   *   .condition(op => op.and([\n   *     op.eq('securityStatus', 'ACTIVE'),\n   *     op.lt('currentOccupants', 3),\n   *     op.eq('habitatType', 'CARNIVORE')\n   *   ]))\n   *   .withTransaction(transaction);\n   * // Add dinosaur transfer operations\n   * ```\n   *\n   * @param transaction - The transaction builder to add this operation to\n   * @throws {Error} If no condition has been set\n   * @returns The builder instance for method chaining\n   */\n  withTransaction(transaction: TransactionBuilder): ConditionCheckBuilder {\n    if (!this.conditionExpression) {\n      throw new Error(\"Condition is required for condition check operations\");\n    }\n\n    const command = this.toDynamoCommand();\n    transaction.conditionCheckWithCommand(command);\n\n    return this;\n  }\n\n  /**\n   * Gets a human-readable representation of the condition check command\n   * with all expression placeholders replaced by their actual values.\n   * Use this method when you need to:\n   * - Debug complex condition expressions\n   * - Verify condition parameters\n   * - Log safety checks\n   * - Troubleshoot condition failures\n   *\n   * @example\n   * ```ts\n   * const debugInfo = new ConditionCheckBuilder('dinosaurs', { id: 'TREX-001' })\n   *   .condition(op => op.and([\n   *     op.between('stats.health', 50, 100),\n   *     op.not(op.eq('status', 'SEDATED')),\n   *     op.attributeExists('lastFeedingTime')\n   *     op.eq('version', 1)\n   *   ]))\n   *   .debug();\n   * console.log(debugInfo);\n   * ```\n   *\n   * @returns A readable representation of the condition check command with resolved expressions\n   */\n  debug(): Record<string, unknown> {\n    const command = this.toDynamoCommand();\n    return debugCommand(command);\n  }\n}\n"]}