dyno-table 2.3.3 → 2.4.0

package/dist/chunk-ELULXDSB.cjs

@@ -0,0 +1,564 @@
+'use strict';
+
+// src/errors.ts
+var DynoTableError = class extends Error {
+  /**
+   * Machine-readable error code for programmatic error handling
+   * @example "KEY_GENERATION_FAILED", "VALIDATION_ERROR", etc.
+   */
+  code;
+  /**
+   * Additional context about the error
+   * Contains operation-specific details like entity names, table names,
+   * expressions, conditions, and other relevant debugging information
+   */
+  context;
+  /**
+   * The original error that caused this error (if wrapping another error)
+   * Useful for preserving AWS SDK errors or other underlying errors
+   */
+  cause;
+  constructor(message, code, context = {}, cause) {
+    super(message);
+    this.name = "DynoTableError";
+    this.code = code;
+    this.context = context;
+    this.cause = cause;
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, this.constructor);
+    }
+  }
+};
+var ValidationError = class extends DynoTableError {
+  constructor(message, code, context = {}, cause) {
+    super(message, code, context, cause);
+    this.name = "ValidationError";
+  }
+};
+var OperationError = class extends DynoTableError {
+  constructor(message, code, context = {}, cause) {
+    super(message, code, context, cause);
+    this.name = "OperationError";
+  }
+};
+var TransactionError = class extends DynoTableError {
+  constructor(message, code, context = {}, cause) {
+    super(message, code, context, cause);
+    this.name = "TransactionError";
+  }
+};
+var BatchError = class extends DynoTableError {
+  /**
+   * The type of batch operation that failed
+   */
+  operation;
+  /**
+   * The items that were not processed during the batch operation
+   */
+  unprocessedItems;
+  constructor(message, code, operation, unprocessedItems = [], context = {}, cause) {
+    super(message, code, context, cause);
+    this.name = "BatchError";
+    this.operation = operation;
+    this.unprocessedItems = unprocessedItems;
+  }
+};
+var ExpressionError = class extends DynoTableError {
+  constructor(message, code, context = {}, cause) {
+    super(message, code, context, cause);
+    this.name = "ExpressionError";
+  }
+};
+var ConfigurationError = class extends DynoTableError {
+  constructor(message, code, context = {}, cause) {
+    super(message, code, context, cause);
+    this.name = "ConfigurationError";
+  }
+};
+var EntityError = class extends DynoTableError {
+  constructor(message, code, context = {}, cause) {
+    super(message, code, context, cause);
+    this.name = "EntityError";
+  }
+};
+var KeyGenerationError = class extends EntityError {
+  constructor(message, code, context = {}, cause) {
+    super(message, code, context, cause);
+    this.name = "KeyGenerationError";
+  }
+};
+var IndexGenerationError = class extends EntityError {
+  constructor(message, code, context = {}, cause) {
+    super(message, code, context, cause);
+    this.name = "IndexGenerationError";
+  }
+};
+var EntityValidationError = class extends ValidationError {
+  constructor(message, code, context = {}, cause) {
+    super(message, code, context, cause);
+    this.name = "EntityValidationError";
+  }
+};
+var ErrorCodes = {
+  // Key Generation Errors
+  KEY_GENERATION_FAILED: "KEY_GENERATION_FAILED",
+  KEY_MISSING_ATTRIBUTES: "KEY_MISSING_ATTRIBUTES",
+  KEY_INVALID_FORMAT: "KEY_INVALID_FORMAT",
+  // Index Errors
+  INDEX_GENERATION_FAILED: "INDEX_GENERATION_FAILED",
+  INDEX_MISSING_ATTRIBUTES: "INDEX_MISSING_ATTRIBUTES",
+  INDEX_NOT_FOUND: "INDEX_NOT_FOUND",
+  INDEX_READONLY_UPDATE_FAILED: "INDEX_READONLY_UPDATE_FAILED",
+  INDEX_UNDEFINED_VALUES: "INDEX_UNDEFINED_VALUES",
+  // Validation Errors
+  ENTITY_VALIDATION_FAILED: "ENTITY_VALIDATION_FAILED",
+  ASYNC_VALIDATION_NOT_SUPPORTED: "ASYNC_VALIDATION_NOT_SUPPORTED",
+  QUERY_INPUT_VALIDATION_FAILED: "QUERY_INPUT_VALIDATION_FAILED",
+  VALIDATION_ERROR: "VALIDATION_ERROR",
+  VALIDATION_FAILED: "VALIDATION_FAILED",
+  SCHEMA_VALIDATION_FAILED: "SCHEMA_VALIDATION_FAILED",
+  INVALID_PARAMETER: "INVALID_PARAMETER",
+  MISSING_REQUIRED_FIELD: "MISSING_REQUIRED_FIELD",
+  UNDEFINED_VALUE: "UNDEFINED_VALUE",
+  // Expression Errors
+  EXPRESSION_MISSING_ATTRIBUTE: "EXPRESSION_MISSING_ATTRIBUTE",
+  EXPRESSION_MISSING_VALUE: "EXPRESSION_MISSING_VALUE",
+  EXPRESSION_INVALID_CONDITION: "EXPRESSION_INVALID_CONDITION",
+  EXPRESSION_EMPTY_ARRAY: "EXPRESSION_EMPTY_ARRAY",
+  EXPRESSION_UNKNOWN_TYPE: "EXPRESSION_UNKNOWN_TYPE",
+  EXPRESSION_INVALID: "EXPRESSION_INVALID",
+  EXPRESSION_INVALID_OPERATOR: "EXPRESSION_INVALID_OPERATOR",
+  // Operation Errors
+  QUERY_FAILED: "QUERY_FAILED",
+  SCAN_FAILED: "SCAN_FAILED",
+  GET_FAILED: "GET_FAILED",
+  PUT_FAILED: "PUT_FAILED",
+  DELETE_FAILED: "DELETE_FAILED",
+  UPDATE_FAILED: "UPDATE_FAILED",
+  BATCH_GET_FAILED: "BATCH_GET_FAILED",
+  BATCH_WRITE_FAILED: "BATCH_WRITE_FAILED",
+  NO_UPDATE_ACTIONS: "NO_UPDATE_ACTIONS",
+  CONDITIONAL_CHECK_FAILED: "CONDITIONAL_CHECK_FAILED",
+  // Transaction Errors
+  TRANSACTION_FAILED: "TRANSACTION_FAILED",
+  TRANSACTION_DUPLICATE_ITEM: "TRANSACTION_DUPLICATE_ITEM",
+  TRANSACTION_EMPTY: "TRANSACTION_EMPTY",
+  TRANSACTION_UNSUPPORTED_TYPE: "TRANSACTION_UNSUPPORTED_TYPE",
+  TRANSACTION_ITEM_LIMIT: "TRANSACTION_ITEM_LIMIT",
+  TRANSACTION_CANCELLED: "TRANSACTION_CANCELLED",
+  // Batch Errors
+  BATCH_EMPTY: "BATCH_EMPTY",
+  BATCH_UNSUPPORTED_TYPE: "BATCH_UNSUPPORTED_TYPE",
+  BATCH_UNPROCESSED_ITEMS: "BATCH_UNPROCESSED_ITEMS",
+  BATCH_SIZE_EXCEEDED: "BATCH_SIZE_EXCEEDED",
+  // Configuration Errors
+  GSI_NOT_FOUND: "GSI_NOT_FOUND",
+  SORT_KEY_REQUIRED: "SORT_KEY_REQUIRED",
+  SORT_KEY_NOT_DEFINED: "SORT_KEY_NOT_DEFINED",
+  PRIMARY_KEY_MISSING: "PRIMARY_KEY_MISSING",
+  INVALID_CHUNK_SIZE: "INVALID_CHUNK_SIZE",
+  CONDITION_REQUIRED: "CONDITION_REQUIRED",
+  CONDITION_GENERATION_FAILED: "CONDITION_GENERATION_FAILED",
+  PK_EXTRACTION_FAILED: "PK_EXTRACTION_FAILED",
+  CONFIGURATION_INVALID: "CONFIGURATION_INVALID",
+  CONFIGURATION_MISSING_SORT_KEY: "CONFIGURATION_MISSING_SORT_KEY",
+  CONFIGURATION_INVALID_GSI: "CONFIGURATION_INVALID_GSI"
+};
+
+// src/utils/error-factory.ts
+var ExpressionErrors = {
+  missingAttribute: (conditionType, condition) => new ExpressionError(
+    `Attribute is required for ${conditionType} condition`,
+    ErrorCodes.EXPRESSION_MISSING_ATTRIBUTE,
+    {
+      conditionType,
+      condition,
+      suggestion: "Ensure the condition includes an attribute name"
+    }
+  ),
+  missingValue: (conditionType, condition) => new ExpressionError(`Value is required for ${conditionType} condition`, ErrorCodes.EXPRESSION_MISSING_VALUE, {
+    conditionType,
+    condition,
+    suggestion: "Provide a value for the condition"
+  }),
+  invalidCondition: (conditionType, condition, suggestion) => new ExpressionError(`Invalid condition for ${conditionType}`, ErrorCodes.EXPRESSION_INVALID_CONDITION, {
+    conditionType,
+    condition,
+    suggestion: suggestion || "Check that the condition is properly formed"
+  }),
+  emptyArray: (conditionType, providedValue) => new ExpressionError(
+    `${conditionType} condition requires a non-empty array of values`,
+    ErrorCodes.EXPRESSION_EMPTY_ARRAY,
+    {
+      conditionType,
+      providedValue,
+      suggestion: "Provide at least one value in the array"
+    }
+  ),
+  unknownType: (conditionType, condition) => new ExpressionError(`Unknown condition type: ${conditionType}`, ErrorCodes.EXPRESSION_UNKNOWN_TYPE, {
+    conditionType,
+    condition,
+    suggestion: "Use a supported condition type from the query builder"
+  })
+};
+var ValidationErrors = {
+  indexSchemaValidationFailed: (validationIssues, keyType) => {
+    const keyLabel = keyType === "partition" ? "partition key" : keyType === "sort" ? "sort key" : "partition/sort key";
+    return new ValidationError(
+      `Index validation failed while generating ${keyLabel}: missing required attribute(s) or invalid values.`,
+      ErrorCodes.SCHEMA_VALIDATION_FAILED,
+      {
+        keyType,
+        validationIssues,
+        suggestion: `Provide the required attributes to construct the index ${keyLabel}`
+      }
+    );
+  },
+  noUpdateActions: (tableName, key) => new ValidationError("No update actions specified", ErrorCodes.NO_UPDATE_ACTIONS, {
+    tableName,
+    key,
+    suggestion: "Use set(), remove(), add(), or delete() to specify update actions"
+  }),
+  conditionRequired: (tableName, key) => new ValidationError("Condition is required for condition check operations", ErrorCodes.CONDITION_REQUIRED, {
+    tableName,
+    key,
+    suggestion: "Use the condition() method to specify a condition"
+  }),
+  queryInputValidationFailed: (entityName, queryName, validationIssues, providedInput) => new ValidationError(
+    `Query input validation failed for "${queryName}" on entity "${entityName}"`,
+    ErrorCodes.QUERY_INPUT_VALIDATION_FAILED,
+    {
+      entityName,
+      queryName,
+      validationIssues,
+      providedInput,
+      suggestion: "Ensure the query input matches the expected schema"
+    }
+  ),
+  undefinedValue: (path, tableName, key) => new ValidationError(`Cannot set undefined value for attribute "${path}"`, ErrorCodes.UNDEFINED_VALUE, {
+    path,
+    tableName,
+    key,
+    suggestion: "DynamoDB does not support undefined values. Use remove() to delete an attribute, or provide a valid value (null, string, number, etc.)"
+  })
+};
+var ConfigurationErrors = {
+  invalidChunkSize: (size) => new ConfigurationError("Chunk size must be greater than 0", ErrorCodes.INVALID_CHUNK_SIZE, {
+    size,
+    suggestion: "Provide a chunk size greater than 0"
+  }),
+  sortKeyRequired: (tableName, partitionKey, sortKey) => new ConfigurationError("Sort key is required for this operation", ErrorCodes.SORT_KEY_REQUIRED, {
+    tableName,
+    partitionKey,
+    sortKey,
+    suggestion: "Provide a sort key value or use a table with only a partition key"
+  }),
+  sortKeyNotDefined: (tableName, partitionKey, indexName) => new ConfigurationError("Sort key is not defined for this table/index", ErrorCodes.SORT_KEY_NOT_DEFINED, {
+    tableName,
+    partitionKey,
+    indexName,
+    suggestion: "This operation requires a table/index with a sort key defined"
+  }),
+  gsiNotFound: (indexName, tableName, availableIndexes) => new ConfigurationError(`GSI "${indexName}" not found in table configuration`, ErrorCodes.GSI_NOT_FOUND, {
+    indexName,
+    tableName,
+    availableIndexes,
+    suggestion: `Use one of the available indexes: ${availableIndexes.join(", ")}`
+  }),
+  primaryKeyMissing: (tableName, partitionKeyName, providedItem) => new ConfigurationError(`Primary key value for '${partitionKeyName}' is missing`, ErrorCodes.PRIMARY_KEY_MISSING, {
+    tableName,
+    partitionKeyName,
+    providedItem,
+    suggestion: `Ensure the item includes a value for '${partitionKeyName}'`
+  }),
+  pkExtractionFailed: (tableName, indexName, item, cause) => new ConfigurationError(
+    `Failed to extract partition key from item for index "${indexName}"`,
+    ErrorCodes.PK_EXTRACTION_FAILED,
+    {
+      tableName,
+      indexName,
+      item,
+      suggestion: "Ensure the item has the required partition key attribute"
+    },
+    cause
+  ),
+  conditionGenerationFailed: (condition, suggestion) => new ExpressionError("Failed to generate condition expression", ErrorCodes.CONDITION_GENERATION_FAILED, {
+    condition,
+    suggestion: suggestion || "Check that the condition is properly formed"
+  })
+};
+var OperationErrors = {
+  queryFailed: (tableName, context, cause) => new OperationError(
+    `Query operation failed on table "${tableName}"`,
+    ErrorCodes.QUERY_FAILED,
+    {
+      tableName,
+      operation: "query",
+      ...context
+    },
+    cause
+  ),
+  scanFailed: (tableName, context, cause) => new OperationError(
+    `Scan operation failed on table "${tableName}"`,
+    ErrorCodes.SCAN_FAILED,
+    {
+      tableName,
+      operation: "scan",
+      ...context
+    },
+    cause
+  ),
+  getFailed: (tableName, key, cause) => new OperationError(
+    `Get operation failed on table "${tableName}"`,
+    ErrorCodes.GET_FAILED,
+    {
+      tableName,
+      operation: "get",
+      key
+    },
+    cause
+  ),
+  putFailed: (tableName, item, cause) => new OperationError(
+    `Put operation failed on table "${tableName}"`,
+    ErrorCodes.PUT_FAILED,
+    {
+      tableName,
+      operation: "put",
+      item
+    },
+    cause
+  ),
+  updateFailed: (tableName, key, cause) => new OperationError(
+    `Update operation failed on table "${tableName}"`,
+    ErrorCodes.UPDATE_FAILED,
+    {
+      tableName,
+      operation: "update",
+      key
+    },
+    cause
+  ),
+  deleteFailed: (tableName, key, cause) => new OperationError(
+    `Delete operation failed on table "${tableName}"`,
+    ErrorCodes.DELETE_FAILED,
+    {
+      tableName,
+      operation: "delete",
+      key
+    },
+    cause
+  ),
+  batchGetFailed: (tableName, context, cause) => new OperationError(
+    `Batch get operation failed on table "${tableName}"`,
+    ErrorCodes.BATCH_GET_FAILED,
+    {
+      tableName,
+      operation: "batchGet",
+      ...context
+    },
+    cause
+  ),
+  batchWriteFailed: (tableName, context, cause) => new OperationError(
+    `Batch write operation failed on table "${tableName}"`,
+    ErrorCodes.BATCH_WRITE_FAILED,
+    {
+      tableName,
+      operation: "batchWrite",
+      ...context
+    },
+    cause
+  )
+};
+var TransactionErrors = {
+  transactionFailed: (itemCount, context, cause) => new TransactionError(
+    `Transaction failed with ${itemCount} item(s)`,
+    ErrorCodes.TRANSACTION_FAILED,
+    {
+      itemCount,
+      ...context
+    },
+    cause
+  ),
+  duplicateItem: (tableName, partitionKey, sortKey) => new TransactionError("Duplicate item detected in transaction", ErrorCodes.TRANSACTION_DUPLICATE_ITEM, {
+    tableName,
+    partitionKey,
+    sortKey,
+    suggestion: "Each item in a transaction must be unique. Check for duplicate keys in your transaction items."
+  }),
+  transactionEmpty: () => new TransactionError("No transaction items specified", ErrorCodes.TRANSACTION_EMPTY, {
+    suggestion: "Add at least one operation using put(), delete(), update(), or conditionCheck()"
+  }),
+  unsupportedType: (item) => new TransactionError("Unsupported transaction item type", ErrorCodes.TRANSACTION_UNSUPPORTED_TYPE, {
+    item,
+    suggestion: "Transaction items must be created using put(), delete(), update(), or conditionCheck()"
+  })
+};
+var BatchErrors = {
+  batchEmpty: (operation) => new BatchError(`No items specified for batch ${operation} operation`, ErrorCodes.BATCH_EMPTY, operation, [], {
+    suggestion: operation === "write" ? "Use put() or delete() to add items to the batch" : "Use get() to add keys to the batch"
+  }),
+  unsupportedType: (operation, item) => new BatchError(`Unsupported batch ${operation} item type`, ErrorCodes.BATCH_UNSUPPORTED_TYPE, operation, [], {
+    item,
+    suggestion: operation === "write" ? "Batch items must be put or delete operations" : "Batch items must be get operations"
+  }),
+  batchWriteFailed: (unprocessedItems, context, cause) => new BatchError(
+    `Batch write failed with ${unprocessedItems.length} unprocessed item(s)`,
+    ErrorCodes.BATCH_WRITE_FAILED,
+    "write",
+    unprocessedItems,
+    context,
+    cause
+  ),
+  batchGetFailed: (unprocessedItems, context, cause) => new BatchError(
+    `Batch get failed with ${unprocessedItems.length} unprocessed item(s)`,
+    ErrorCodes.BATCH_GET_FAILED,
+    "read",
+    unprocessedItems,
+    context,
+    cause
+  )
+};
+var EntityErrors = {
+  validationFailed: (entityName, operation, validationIssues, providedData) => new EntityValidationError(
+    `Validation failed for entity "${entityName}" during ${operation} operation`,
+    ErrorCodes.ENTITY_VALIDATION_FAILED,
+    {
+      entityName,
+      operation,
+      validationIssues,
+      providedData,
+      suggestion: "Check that all required fields are provided and match the schema"
+    }
+  ),
+  queryInputValidationFailed: (entityName, queryName, validationIssues, providedInput) => new EntityValidationError(
+    `Query input validation failed for "${queryName}" on entity "${entityName}"`,
+    ErrorCodes.QUERY_INPUT_VALIDATION_FAILED,
+    {
+      entityName,
+      queryName,
+      validationIssues,
+      providedInput,
+      suggestion: "Ensure the query input matches the expected schema"
+    }
+  ),
+  asyncValidationNotSupported: (entityName, operation) => new EntityValidationError(
+    `Entity "${entityName}" uses async validation which is not supported in transactions/batches`,
+    ErrorCodes.ASYNC_VALIDATION_NOT_SUPPORTED,
+    {
+      entityName,
+      operation,
+      suggestion: "Use .execute() for async validation or switch to synchronous schema validation"
+    }
+  ),
+  keyGenerationFailed: (entityName, operation, providedData, requiredAttributes, cause) => new KeyGenerationError(
+    `Failed to generate primary key for entity "${entityName}"`,
+    ErrorCodes.KEY_GENERATION_FAILED,
+    {
+      entityName,
+      operation,
+      providedData,
+      requiredAttributes,
+      suggestion: requiredAttributes ? `Ensure these attributes are provided: ${requiredAttributes.join(", ")}` : "Check that all required attributes for key generation are provided"
+    },
+    cause
+  ),
+  keyInvalidFormat: (entityName, operation, providedData, generatedKey) => new KeyGenerationError(
+    `Primary key generation for entity "${entityName}" produced undefined/null partition key`,
+    ErrorCodes.KEY_INVALID_FORMAT,
+    {
+      entityName,
+      operation,
+      providedData,
+      generatedKey,
+      suggestion: "Ensure the key generation function returns valid pk (and sk if applicable) values"
+    }
+  ),
+  keyMissingAttributes: (entityName, operation, missingAttributes, providedData) => new KeyGenerationError(
+    `Missing required attributes for key generation in entity "${entityName}": ${missingAttributes.join(", ")}`,
+    ErrorCodes.KEY_MISSING_ATTRIBUTES,
+    {
+      entityName,
+      operation,
+      missingAttributes,
+      providedData,
+      suggestion: `Provide the following attributes: ${missingAttributes.join(", ")}`
+    }
+  )
+};
+var IndexErrors = {
+  generationFailed: (indexName, operation, providedItem, partitionKeyAttribute, sortKeyAttribute, cause) => new IndexGenerationError(
+    `Failed to generate key for index "${indexName}"`,
+    ErrorCodes.INDEX_GENERATION_FAILED,
+    {
+      indexName,
+      operation,
+      providedItem,
+      partitionKeyAttribute,
+      sortKeyAttribute,
+      suggestion: "Ensure all attributes required by the index are present in the item"
+    },
+    cause
+  ),
+  missingAttributes: (indexName, operation, missingAttributes, providedData, isReadOnly) => new IndexGenerationError(
+    `Cannot regenerate readonly index "${indexName}" - missing required attributes: ${missingAttributes.join(", ")}`,
+    ErrorCodes.INDEX_MISSING_ATTRIBUTES,
+    {
+      indexName,
+      operation,
+      missingAttributes,
+      providedData,
+      isReadOnly,
+      suggestion: isReadOnly ? "For readonly indexes, provide all attributes or use forceIndexRebuild() with complete data" : `Provide the following attributes: ${missingAttributes.join(", ")}`
+    }
+  ),
+  undefinedValues: (indexName, operation, generatedKey, providedItem) => new IndexGenerationError(`Index "${indexName}" generated undefined values`, ErrorCodes.INDEX_UNDEFINED_VALUES, {
+    indexName,
+    operation,
+    generatedKey,
+    providedItem,
+    suggestion: "Ensure all attributes required by the index are present in the item"
+  }),
+  notFound: (requestedIndexes, availableIndexes, entityName, tableName) => new IndexGenerationError(
+    `Requested indexes not found: ${requestedIndexes.join(", ")}`,
+    ErrorCodes.INDEX_NOT_FOUND,
+    {
+      requestedIndexes,
+      availableIndexes,
+      entityName,
+      tableName,
+      suggestion: `Available indexes are: ${availableIndexes.join(", ")}`
+    }
+  ),
+  readonlyUpdateFailed: (indexName, operation, providedData) => new IndexGenerationError(
+    `Cannot update readonly index "${indexName}" without forcing rebuild`,
+    ErrorCodes.INDEX_READONLY_UPDATE_FAILED,
+    {
+      indexName,
+      operation,
+      providedData,
+      isReadOnly: true,
+      suggestion: "Use forceIndexRebuild() to update readonly indexes, or provide all required attributes"
+    }
+  )
+};
+
+exports.BatchError = BatchError;
+exports.BatchErrors = BatchErrors;
+exports.ConfigurationError = ConfigurationError;
+exports.ConfigurationErrors = ConfigurationErrors;
+exports.DynoTableError = DynoTableError;
+exports.EntityError = EntityError;
+exports.EntityErrors = EntityErrors;
+exports.EntityValidationError = EntityValidationError;
+exports.ErrorCodes = ErrorCodes;
+exports.ExpressionError = ExpressionError;
+exports.ExpressionErrors = ExpressionErrors;
+exports.IndexErrors = IndexErrors;
+exports.IndexGenerationError = IndexGenerationError;
+exports.KeyGenerationError = KeyGenerationError;
+exports.OperationError = OperationError;
+exports.OperationErrors = OperationErrors;
+exports.TransactionError = TransactionError;
+exports.TransactionErrors = TransactionErrors;
+exports.ValidationError = ValidationError;
+exports.ValidationErrors = ValidationErrors;