dyno-table 0.1.7 → 0.1.8

package/dist/builders/update-builder.js

@@ -0,0 +1,660 @@
+// 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;
+  }
+};
+
+// 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/update-builder.ts
+var UpdateBuilder = class {
+  updates = [];
+  options = {
+    returnValues: "ALL_NEW"
+  };
+  executor;
+  tableName;
+  key;
+  constructor(executor, tableName, key) {
+    this.executor = executor;
+    this.tableName = tableName;
+    this.key = key;
+  }
+  set(valuesOrPath, value) {
+    if (typeof valuesOrPath === "object") {
+      for (const [key, value2] of Object.entries(valuesOrPath)) {
+        this.updates.push({
+          type: "SET",
+          path: key,
+          value: value2
+        });
+      }
+    } else {
+      this.updates.push({
+        type: "SET",
+        path: valuesOrPath,
+        value
+      });
+    }
+    return this;
+  }
+  /**
+   * Removes an attribute from the item.
+   * Use this method when you need to:
+   * - Delete attributes completely
+   * - Remove nested attributes
+   * - Clean up deprecated fields
+   *
+   * @example
+   * ```typescript
+   * // Remove simple attributes
+   * builder
+   *   .remove('temporaryTag')
+   *   .remove('previousLocation');
+   *
+   * // Remove nested attributes
+   * builder
+   *   .remove('metadata.testData')
+   *   .remove('stats.experimentalMetrics');
+   * ```
+   *
+   * @param path - The path to the attribute to remove
+   * @returns The builder instance for method chaining
+   */
+  remove(path) {
+    this.updates.push({
+      type: "REMOVE",
+      path
+    });
+    return this;
+  }
+  /**
+   * Adds a value to a number attribute or adds elements to a set.
+   * Use this method when you need to:
+   * - Increment counters
+   * - Add elements to a set atomically
+   * - Update numerical statistics
+   *
+   * @example
+   * ```typescript
+   * // Increment counters
+   * builder
+   *   .add('escapeAttempts', 1)
+   *   .add('feedingCount', 1);
+   *
+   * // Add to sets
+   * builder
+   *   .add('knownBehaviors', new Set(['PACK_HUNTING', 'AMBUSH_TACTICS']))
+   *   .add('visitedZones', new Set(['ZONE_A', 'ZONE_B']));
+   * ```
+   *
+   * @param path - The path to the attribute to update
+   * @param value - The value to add (number or set)
+   * @returns The builder instance for method chaining
+   */
+  add(path, value) {
+    this.updates.push({
+      type: "ADD",
+      path,
+      value
+    });
+    return this;
+  }
+  /**
+   * Removes elements from a set attribute.
+   * Use this method when you need to:
+   * - Remove specific elements from a set
+   * - Update set-based attributes atomically
+   * - Maintain set membership
+   *
+   * @example
+   * ```typescript
+   * // Remove from sets using arrays
+   * builder.deleteElementsFromSet(
+   *   'allowedHabitats',
+   *   ['JUNGLE', 'COASTAL']
+   * );
+   *
+   * // Remove from sets using Set objects
+   * builder.deleteElementsFromSet(
+   *   'knownBehaviors',
+   *   new Set(['NOCTURNAL', 'TERRITORIAL'])
+   * );
+   *
+   * // Remove from nested sets
+   * builder.deleteElementsFromSet(
+   *   'stats.compatibleSpecies',
+   *   ['VELOCIRAPTOR', 'DILOPHOSAURUS']
+   * );
+   * ```
+   *
+   * @param path - The path to the set attribute
+   * @param value - Elements to remove (array or Set)
+   * @returns The builder instance for method chaining
+   */
+  deleteElementsFromSet(path, value) {
+    let valuesToDelete;
+    if (Array.isArray(value)) {
+      valuesToDelete = new Set(value);
+    } else {
+      valuesToDelete = value;
+    }
+    this.updates.push({
+      type: "DELETE",
+      path,
+      value: valuesToDelete
+    });
+    return this;
+  }
+  /**
+   * Adds a condition that must be satisfied for the update to succeed.
+   * Use this method when you need to:
+   * - Implement optimistic locking
+   * - Ensure item state before update
+   * - Validate business rules
+   * - Prevent concurrent modifications
+   *
+   * @example
+   * ```typescript
+   * // Simple condition
+   * builder.condition(op =>
+   *   op.eq('status', 'ACTIVE')
+   * );
+   *
+   * // Health check condition
+   * builder.condition(op =>
+   *   op.and([
+   *     op.gt('health', 50),
+   *     op.eq('status', 'HUNTING')
+   *   ])
+   * );
+   *
+   * // Complex security condition
+   * builder.condition(op =>
+   *   op.and([
+   *     op.attributeExists('securitySystem'),
+   *     op.eq('containmentStatus', 'SECURE'),
+   *     op.lt('aggressionLevel', 8)
+   *   ])
+   * );
+   *
+   * // Version check (optimistic locking)
+   * builder.condition(op =>
+   *   op.eq('version', currentVersion)
+   * );
+   * ```
+   *
+   * @param condition - Either a Condition object or a callback function that builds the condition
+   * @returns The builder instance for method chaining
+   */
+  condition(condition) {
+    if (typeof condition === "function") {
+      const conditionOperator = {
+        eq,
+        ne,
+        lt,
+        lte,
+        gt,
+        gte,
+        between,
+        beginsWith,
+        contains,
+        attributeExists,
+        attributeNotExists,
+        and,
+        or,
+        not
+      };
+      this.options.condition = condition(conditionOperator);
+    } else {
+      this.options.condition = condition;
+    }
+    return this;
+  }
+  /**
+   * Sets which item attributes to include in the response.
+   * Use this method when you need to:
+   * - Get the complete updated item
+   * - Track changes to specific attributes
+   * - Compare old and new values
+   * - Monitor attribute modifications
+   *
+   * Available options:
+   * - ALL_NEW: All attributes after the update
+   * - UPDATED_NEW: Only updated attributes, new values
+   * - ALL_OLD: All attributes before the update
+   * - UPDATED_OLD: Only updated attributes, old values
+   * - NONE: No attributes returned (default)
+   *
+   * @example
+   * ```typescript
+   * // Get complete updated dinosaur
+   * const result = await builder
+   *   .set('status', 'SLEEPING')
+   *   .returnValues('ALL_NEW')
+   *   .execute();
+   *
+   * // Track specific attribute changes
+   * const result = await builder
+   *   .set({
+   *     'stats.health': 100,
+   *     'stats.energy': 95
+   *   })
+   *   .returnValues('UPDATED_OLD')
+   *   .execute();
+   *
+   * if (result.item) {
+   *   console.log('Previous health:', result.item.stats?.health);
+   * }
+   * ```
+   *
+   * @param returnValues - Which attributes to return in the response
+   * @returns The builder instance for method chaining
+   */
+  returnValues(returnValues) {
+    this.options.returnValues = returnValues;
+    return this;
+  }
+  /**
+   * Generate the DynamoDB command parameters
+   */
+  toDynamoCommand() {
+    if (this.updates.length === 0) {
+      throw new Error("No update actions specified");
+    }
+    const expressionParams = {
+      expressionAttributeNames: {},
+      expressionAttributeValues: {},
+      valueCounter: { count: 0 }
+    };
+    let updateExpression = "";
+    const setUpdates = [];
+    const removeUpdates = [];
+    const addUpdates = [];
+    const deleteUpdates = [];
+    for (const update of this.updates) {
+      switch (update.type) {
+        case "SET":
+          setUpdates.push(update);
+          break;
+        case "REMOVE":
+          removeUpdates.push(update);
+          break;
+        case "ADD":
+          addUpdates.push(update);
+          break;
+        case "DELETE":
+          deleteUpdates.push(update);
+          break;
+      }
+    }
+    if (setUpdates.length > 0) {
+      updateExpression += "SET ";
+      updateExpression += setUpdates.map((update) => {
+        const attrName = generateAttributeName(expressionParams, update.path);
+        const valueName = generateValueName(expressionParams, update.value);
+        expressionParams.expressionAttributeValues[valueName] = update.value;
+        return `${attrName} = ${valueName}`;
+      }).join(", ");
+    }
+    if (removeUpdates.length > 0) {
+      if (updateExpression) {
+        updateExpression += " ";
+      }
+      updateExpression += "REMOVE ";
+      updateExpression += removeUpdates.map((update) => {
+        return generateAttributeName(expressionParams, update.path);
+      }).join(", ");
+    }
+    if (addUpdates.length > 0) {
+      if (updateExpression) {
+        updateExpression += " ";
+      }
+      updateExpression += "ADD ";
+      updateExpression += addUpdates.map((update) => {
+        const attrName = generateAttributeName(expressionParams, update.path);
+        const valueName = generateValueName(expressionParams, update.value);
+        return `${attrName} ${valueName}`;
+      }).join(", ");
+    }
+    if (deleteUpdates.length > 0) {
+      if (updateExpression) {
+        updateExpression += " ";
+      }
+      updateExpression += "DELETE ";
+      updateExpression += deleteUpdates.map((update) => {
+        const attrName = generateAttributeName(expressionParams, update.path);
+        const valueName = generateValueName(expressionParams, update.value);
+        return `${attrName} ${valueName}`;
+      }).join(", ");
+    }
+    let conditionExpression;
+    if (this.options.condition) {
+      conditionExpression = buildExpression(this.options.condition, expressionParams);
+    }
+    const { expressionAttributeNames, expressionAttributeValues } = expressionParams;
+    return {
+      tableName: this.tableName,
+      key: this.key,
+      updateExpression,
+      conditionExpression,
+      expressionAttributeNames: Object.keys(expressionAttributeNames).length > 0 ? expressionAttributeNames : void 0,
+      expressionAttributeValues: Object.keys(expressionAttributeValues).length > 0 ? expressionAttributeValues : void 0,
+      returnValues: this.options.returnValues
+    };
+  }
+  /**
+   * Adds this update operation to a transaction.
+   * Use this method when you need to:
+   * - Update items as part of a larger transaction
+   * - Ensure multiple updates are atomic
+   * - Coordinate updates across multiple items
+   *
+   * @example
+   * ```typescript
+   * const transaction = new TransactionBuilder(executor);
+   *
+   * // Update dinosaur status and habitat occupancy atomically
+   * new UpdateBuilder(executor, 'dinosaurs', { id: 'TREX-001' })
+   *   .set('location', 'PADDOCK_A')
+   *   .set('status', 'CONTAINED')
+   *   .withTransaction(transaction);
+   *
+   * new UpdateBuilder(executor, 'habitats', { id: 'PADDOCK-A' })
+   *   .add('occupants', 1)
+   *   .set('lastOccupied', new Date().toISOString())
+   *   .withTransaction(transaction);
+   *
+   * // Execute all operations atomically
+   * await transaction.execute();
+   * ```
+   *
+   * @param transaction - The transaction builder to add this operation to
+   * @returns The builder instance for method chaining
+   */
+  withTransaction(transaction) {
+    const command = this.toDynamoCommand();
+    transaction.updateWithCommand(command);
+  }
+  /**
+   * Gets a human-readable representation of the update command.
+   * Use this method when you need to:
+   * - Debug complex update expressions
+   * - Verify attribute names and values
+   * - Log update operations
+   * - Troubleshoot condition expressions
+   *
+   * @example
+   * ```typescript
+   * // Create complex update
+   * const builder = new UpdateBuilder(executor, 'dinosaurs', { id: 'RAPTOR-001' })
+   *   .set({
+   *     status: 'HUNTING',
+   *     'stats.health': 95,
+   *     'behavior.lastObserved': new Date().toISOString()
+   *   })
+   *   .add('huntingSuccesses', 1)
+   *   .condition(op => op.gt('health', 50));
+   *
+   * // Debug the update
+   * const debugInfo = builder.debug();
+   * console.log('Update operation:', debugInfo);
+   * ```
+   *
+   * @returns A readable representation of the update command with resolved expressions
+   */
+  debug() {
+    const command = this.toDynamoCommand();
+    return debugCommand(command);
+  }
+  /**
+   * Executes the update operation against DynamoDB.
+   * Use this method when you need to:
+   * - Apply updates immediately
+   * - Get the updated item values
+   * - Handle conditional update failures
+   *
+   * @example
+   * ```typescript
+   * try {
+   *   // Update dinosaur status with conditions
+   *   const result = await new UpdateBuilder(executor, 'dinosaurs', { id: 'TREX-001' })
+   *     .set({
+   *       status: 'FEEDING',
+   *       lastMeal: new Date().toISOString(),
+   *       'stats.hunger': 0
+   *     })
+   *     .add('feedingCount', 1)
+   *     .condition(op =>
+   *       op.and([
+   *         op.gt('stats.hunger', 80),
+   *         op.eq('status', 'HUNTING')
+   *       ])
+   *     )
+   *     .returnValues('ALL_NEW')
+   *     .execute();
+   *
+   *   if (result.item) {
+   *     console.log('Updated dinosaur:', result.item);
+   *   }
+   * } catch (error) {
+   *   // Handle condition check failure
+   *   console.error('Failed to update dinosaur:', error);
+   *   // Check if dinosaur wasn't hungry enough
+   *   if (error.name === 'ConditionalCheckFailedException') {
+   *     console.log('Dinosaur not ready for feeding');
+   *   }
+   * }
+   * ```
+   *
+   * @returns A promise that resolves to an object containing the updated item (if returnValues is set)
+   * @throws {ConditionalCheckFailedException} If the condition check fails
+   * @throws {Error} If the update operation fails for other reasons
+   */
+  async execute() {
+    const params = this.toDynamoCommand();
+    return this.executor(params);
+  }
+};
+
+export { UpdateBuilder };
+//# sourceMappingURL=update-builder.js.map
+//# sourceMappingURL=update-builder.js.map