dyno-table 1.0.0-alpha.1 → 1.1.0

package/dist/builders/put-builder.js

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

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

@@ -0,0 +1 @@
+{"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.js","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"]}