dyno-table 0.1.8 → 1.0.0-alpha.1

package/dist/builders/update-builder.cjs

@@ -1,662 +0,0 @@
-'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;
-  }
-};
-
-// 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);
-  }
-};
-
-exports.UpdateBuilder = UpdateBuilder;
-//# sourceMappingURL=update-builder.cjs.map
-//# sourceMappingURL=update-builder.cjs.map