dyno-table 1.0.0-alpha.1 → 1.0.0

package/dist/builder-types-C_PDZhnP.d.ts

@@ -0,0 +1,118 @@
+import { DynamoItem, TableConfig } from './types.js';
+
+/**
+ * Interface for DynamoDB command objects that can contain expressions
+ */
+interface DynamoCommandWithExpressions {
+    conditionExpression?: string;
+    updateExpression?: string;
+    filterExpression?: string;
+    keyConditionExpression?: string;
+    projectionExpression?: string;
+    expressionAttributeNames?: Record<string, string>;
+    expressionAttributeValues?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+
+interface DeleteCommandParams extends DynamoCommandWithExpressions {
+    tableName: string;
+    key: Record<string, unknown>;
+    conditionExpression?: string;
+    expressionAttributeNames?: Record<string, string>;
+    expressionAttributeValues?: DynamoItem;
+    returnValues?: "ALL_OLD";
+}
+/**
+ * Parameters for the DynamoDB put command.
+ *
+ * These parameters are used when executing the operation against DynamoDB.
+ *
+ * The `returnValues` property can be:
+ * - `"ALL_OLD"`: Return the attributes of the item as they were before the operation
+ * - `"NONE"`: Return nothing
+ * - `"CONSISTENT"`: Triggers a GET operation after the put to retrieve the updated item state
+ */
+interface PutCommandParams extends DynamoCommandWithExpressions {
+    tableName: string;
+    item: DynamoItem;
+    conditionExpression?: string;
+    expressionAttributeNames?: Record<string, string>;
+    expressionAttributeValues?: Record<string, unknown>;
+    returnValues?: "ALL_OLD" | "NONE" | "CONSISTENT";
+}
+/**
+ * Parameters for the DynamoDB update command.
+ * These parameters are used when executing the operation against DynamoDB.
+ */
+interface UpdateCommandParams extends DynamoCommandWithExpressions {
+    /** The name of the DynamoDB table */
+    tableName: string;
+    /** The primary key of the item to update */
+    key: Record<string, unknown>;
+    /** The update expression (SET, REMOVE, ADD, DELETE clauses) */
+    updateExpression: string;
+    /** Optional condition expression that must be satisfied */
+    conditionExpression?: string;
+    /** Map of expression attribute name placeholders to actual names */
+    expressionAttributeNames?: Record<string, string>;
+    /** Map of expression attribute value placeholders to actual values */
+    expressionAttributeValues?: DynamoItem;
+    /** Which item attributes to include in the response */
+    returnValues?: "ALL_NEW" | "UPDATED_NEW" | "ALL_OLD" | "UPDATED_OLD" | "NONE";
+}
+interface ConditionCheckCommandParams extends DynamoCommandWithExpressions {
+    tableName: string;
+    key: Record<string, unknown>;
+    conditionExpression: string;
+    expressionAttributeNames?: Record<string, string>;
+    expressionAttributeValues?: DynamoItem;
+}
+/**
+ * Base interface for all builder classes that support pagination
+ * to be used by Paginator without creating circular dependencies.
+ */
+interface BaseBuilderInterface<T extends DynamoItem, TConfig extends TableConfig = TableConfig, B = unknown> {
+    clone(): B;
+    limit(limit: number): B;
+    getLimit(): number | undefined;
+    startFrom(lastEvaluatedKey: DynamoItem): B;
+    execute(): Promise<{
+        items: T[];
+        lastEvaluatedKey?: DynamoItem;
+    }>;
+}
+/**
+ * Interface for the QueryBuilder class to be used by Paginator
+ * without creating a circular dependency.
+ */
+interface QueryBuilderInterface<T extends DynamoItem, TConfig extends TableConfig = TableConfig> extends BaseBuilderInterface<T, TConfig, QueryBuilderInterface<T, TConfig>> {
+}
+/**
+ * Interface for the ScanBuilder class to be used by Paginator
+ * without creating a circular dependency.
+ */
+interface ScanBuilderInterface<T extends DynamoItem, TConfig extends TableConfig = TableConfig> extends BaseBuilderInterface<T, TConfig, ScanBuilderInterface<T, TConfig>> {
+}
+/**
+ * Interface for the FilterBuilder class to be used by Paginator
+ * without creating a circular dependency.
+ */
+interface FilterBuilderInterface<T extends DynamoItem, TConfig extends TableConfig = TableConfig> extends BaseBuilderInterface<T, TConfig, FilterBuilderInterface<T, TConfig>> {
+}
+/**
+ * Represents the result of a single page query operation.
+ * This interface provides all necessary information about the current page
+ * and the availability of subsequent pages.
+ */
+interface PaginationResult<T> {
+    /** The items (dinosaurs, habitats, etc.) retrieved for the current page */
+    items: T[];
+    /** DynamoDB's last evaluated key, used internally for pagination */
+    lastEvaluatedKey?: DynamoItem;
+    /** Indicates whether there are more pages available */
+    hasNextPage: boolean;
+    /** The current page number (1-indexed) */
+    page: number;
+}
+
+export type { ConditionCheckCommandParams as C, DeleteCommandParams as D, FilterBuilderInterface as F, PaginationResult as P, QueryBuilderInterface as Q, ScanBuilderInterface as S, UpdateCommandParams as U, PutCommandParams as a };

package/dist/builder-types-DtwbqMeF.d.cts

@@ -0,0 +1,118 @@
+import { DynamoItem, TableConfig } from './types.cjs';
+
+/**
+ * Interface for DynamoDB command objects that can contain expressions
+ */
+interface DynamoCommandWithExpressions {
+    conditionExpression?: string;
+    updateExpression?: string;
+    filterExpression?: string;
+    keyConditionExpression?: string;
+    projectionExpression?: string;
+    expressionAttributeNames?: Record<string, string>;
+    expressionAttributeValues?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+
+interface DeleteCommandParams extends DynamoCommandWithExpressions {
+    tableName: string;
+    key: Record<string, unknown>;
+    conditionExpression?: string;
+    expressionAttributeNames?: Record<string, string>;
+    expressionAttributeValues?: DynamoItem;
+    returnValues?: "ALL_OLD";
+}
+/**
+ * Parameters for the DynamoDB put command.
+ *
+ * These parameters are used when executing the operation against DynamoDB.
+ *
+ * The `returnValues` property can be:
+ * - `"ALL_OLD"`: Return the attributes of the item as they were before the operation
+ * - `"NONE"`: Return nothing
+ * - `"CONSISTENT"`: Triggers a GET operation after the put to retrieve the updated item state
+ */
+interface PutCommandParams extends DynamoCommandWithExpressions {
+    tableName: string;
+    item: DynamoItem;
+    conditionExpression?: string;
+    expressionAttributeNames?: Record<string, string>;
+    expressionAttributeValues?: Record<string, unknown>;
+    returnValues?: "ALL_OLD" | "NONE" | "CONSISTENT";
+}
+/**
+ * Parameters for the DynamoDB update command.
+ * These parameters are used when executing the operation against DynamoDB.
+ */
+interface UpdateCommandParams extends DynamoCommandWithExpressions {
+    /** The name of the DynamoDB table */
+    tableName: string;
+    /** The primary key of the item to update */
+    key: Record<string, unknown>;
+    /** The update expression (SET, REMOVE, ADD, DELETE clauses) */
+    updateExpression: string;
+    /** Optional condition expression that must be satisfied */
+    conditionExpression?: string;
+    /** Map of expression attribute name placeholders to actual names */
+    expressionAttributeNames?: Record<string, string>;
+    /** Map of expression attribute value placeholders to actual values */
+    expressionAttributeValues?: DynamoItem;
+    /** Which item attributes to include in the response */
+    returnValues?: "ALL_NEW" | "UPDATED_NEW" | "ALL_OLD" | "UPDATED_OLD" | "NONE";
+}
+interface ConditionCheckCommandParams extends DynamoCommandWithExpressions {
+    tableName: string;
+    key: Record<string, unknown>;
+    conditionExpression: string;
+    expressionAttributeNames?: Record<string, string>;
+    expressionAttributeValues?: DynamoItem;
+}
+/**
+ * Base interface for all builder classes that support pagination
+ * to be used by Paginator without creating circular dependencies.
+ */
+interface BaseBuilderInterface<T extends DynamoItem, TConfig extends TableConfig = TableConfig, B = unknown> {
+    clone(): B;
+    limit(limit: number): B;
+    getLimit(): number | undefined;
+    startFrom(lastEvaluatedKey: DynamoItem): B;
+    execute(): Promise<{
+        items: T[];
+        lastEvaluatedKey?: DynamoItem;
+    }>;
+}
+/**
+ * Interface for the QueryBuilder class to be used by Paginator
+ * without creating a circular dependency.
+ */
+interface QueryBuilderInterface<T extends DynamoItem, TConfig extends TableConfig = TableConfig> extends BaseBuilderInterface<T, TConfig, QueryBuilderInterface<T, TConfig>> {
+}
+/**
+ * Interface for the ScanBuilder class to be used by Paginator
+ * without creating a circular dependency.
+ */
+interface ScanBuilderInterface<T extends DynamoItem, TConfig extends TableConfig = TableConfig> extends BaseBuilderInterface<T, TConfig, ScanBuilderInterface<T, TConfig>> {
+}
+/**
+ * Interface for the FilterBuilder class to be used by Paginator
+ * without creating a circular dependency.
+ */
+interface FilterBuilderInterface<T extends DynamoItem, TConfig extends TableConfig = TableConfig> extends BaseBuilderInterface<T, TConfig, FilterBuilderInterface<T, TConfig>> {
+}
+/**
+ * Represents the result of a single page query operation.
+ * This interface provides all necessary information about the current page
+ * and the availability of subsequent pages.
+ */
+interface PaginationResult<T> {
+    /** The items (dinosaurs, habitats, etc.) retrieved for the current page */
+    items: T[];
+    /** DynamoDB's last evaluated key, used internally for pagination */
+    lastEvaluatedKey?: DynamoItem;
+    /** Indicates whether there are more pages available */
+    hasNextPage: boolean;
+    /** The current page number (1-indexed) */
+    page: number;
+}
+
+export type { ConditionCheckCommandParams as C, DeleteCommandParams as D, FilterBuilderInterface as F, PaginationResult as P, QueryBuilderInterface as Q, ScanBuilderInterface as S, UpdateCommandParams as U, PutCommandParams as a };

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

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