dyno-table 2.3.3 → 2.4.0

package/dist/index.cjs

@@ -1,28 +1,113 @@
 'use strict';
 
-var chunkKA3VPIPS_cjs = require('./chunk-KA3VPIPS.cjs');
-var chunk3J5DY7KG_cjs = require('./chunk-3J5DY7KG.cjs');
+var chunkOLURZQ7R_cjs = require('./chunk-OLURZQ7R.cjs');
+var chunkZXM6LPRV_cjs = require('./chunk-ZXM6LPRV.cjs');
 var chunkPB7BBCZO_cjs = require('./chunk-PB7BBCZO.cjs');
-var chunkXYL43FDX_cjs = require('./chunk-XYL43FDX.cjs');
+var chunkAHF4H42Q_cjs = require('./chunk-AHF4H42Q.cjs');
+var chunkELULXDSB_cjs = require('./chunk-ELULXDSB.cjs');
 var chunk7UJJ7JXM_cjs = require('./chunk-7UJJ7JXM.cjs');
 
 
 
 Object.defineProperty(exports, "Table", {
   enumerable: true,
-  get: function () { return chunkKA3VPIPS_cjs.Table; }
+  get: function () { return chunkOLURZQ7R_cjs.Table; }
 });
 Object.defineProperty(exports, "createIndex", {
   enumerable: true,
-  get: function () { return chunk3J5DY7KG_cjs.createIndex; }
+  get: function () { return chunkZXM6LPRV_cjs.createIndex; }
 });
 Object.defineProperty(exports, "createQueries", {
   enumerable: true,
-  get: function () { return chunk3J5DY7KG_cjs.createQueries; }
+  get: function () { return chunkZXM6LPRV_cjs.createQueries; }
 });
 Object.defineProperty(exports, "defineEntity", {
   enumerable: true,
-  get: function () { return chunk3J5DY7KG_cjs.defineEntity; }
+  get: function () { return chunkZXM6LPRV_cjs.defineEntity; }
+});
+Object.defineProperty(exports, "extractRequiredAttributes", {
+  enumerable: true,
+  get: function () { return chunkZXM6LPRV_cjs.extractRequiredAttributes; }
+});
+Object.defineProperty(exports, "formatErrorContext", {
+  enumerable: true,
+  get: function () { return chunkZXM6LPRV_cjs.formatErrorContext; }
+});
+Object.defineProperty(exports, "getAwsErrorCode", {
+  enumerable: true,
+  get: function () { return chunkZXM6LPRV_cjs.getAwsErrorCode; }
+});
+Object.defineProperty(exports, "getAwsErrorMessage", {
+  enumerable: true,
+  get: function () { return chunkZXM6LPRV_cjs.getAwsErrorMessage; }
+});
+Object.defineProperty(exports, "getErrorSummary", {
+  enumerable: true,
+  get: function () { return chunkZXM6LPRV_cjs.getErrorSummary; }
+});
+Object.defineProperty(exports, "isBatchError", {
+  enumerable: true,
+  get: function () { return chunkZXM6LPRV_cjs.isBatchError; }
+});
+Object.defineProperty(exports, "isConditionalCheckFailed", {
+  enumerable: true,
+  get: function () { return chunkZXM6LPRV_cjs.isConditionalCheckFailed; }
+});
+Object.defineProperty(exports, "isConfigurationError", {
+  enumerable: true,
+  get: function () { return chunkZXM6LPRV_cjs.isConfigurationError; }
+});
+Object.defineProperty(exports, "isDynoTableError", {
+  enumerable: true,
+  get: function () { return chunkZXM6LPRV_cjs.isDynoTableError; }
+});
+Object.defineProperty(exports, "isEntityError", {
+  enumerable: true,
+  get: function () { return chunkZXM6LPRV_cjs.isEntityError; }
+});
+Object.defineProperty(exports, "isEntityValidationError", {
+  enumerable: true,
+  get: function () { return chunkZXM6LPRV_cjs.isEntityValidationError; }
+});
+Object.defineProperty(exports, "isExpressionError", {
+  enumerable: true,
+  get: function () { return chunkZXM6LPRV_cjs.isExpressionError; }
+});
+Object.defineProperty(exports, "isIndexGenerationError", {
+  enumerable: true,
+  get: function () { return chunkZXM6LPRV_cjs.isIndexGenerationError; }
+});
+Object.defineProperty(exports, "isKeyGenerationError", {
+  enumerable: true,
+  get: function () { return chunkZXM6LPRV_cjs.isKeyGenerationError; }
+});
+Object.defineProperty(exports, "isOperationError", {
+  enumerable: true,
+  get: function () { return chunkZXM6LPRV_cjs.isOperationError; }
+});
+Object.defineProperty(exports, "isProvisionedThroughputExceeded", {
+  enumerable: true,
+  get: function () { return chunkZXM6LPRV_cjs.isProvisionedThroughputExceeded; }
+});
+Object.defineProperty(exports, "isRetryableError", {
+  enumerable: true,
+  get: function () { return chunkZXM6LPRV_cjs.isRetryableError; }
+});
+Object.defineProperty(exports, "isTransactionCanceled", {
+  enumerable: true,
+  get: function () { return chunkZXM6LPRV_cjs.isTransactionCanceled; }
+});
+Object.defineProperty(exports, "isTransactionError", {
+  enumerable: true,
+  get: function () { return chunkZXM6LPRV_cjs.isTransactionError; }
+});
+Object.defineProperty(exports, "isValidationError", {
+  enumerable: true,
+  get: function () { return chunkZXM6LPRV_cjs.isValidationError; }
+});
+Object.defineProperty(exports, "isValidationException", {
+  enumerable: true,
+  get: function () { return chunkZXM6LPRV_cjs.isValidationException; }
 });
 Object.defineProperty(exports, "partitionKey", {
   enumerable: true,
@@ -34,31 +119,107 @@ Object.defineProperty(exports, "sortKey", {
 });
 Object.defineProperty(exports, "BatchBuilder", {
   enumerable: true,
-  get: function () { return chunkXYL43FDX_cjs.BatchBuilder; }
-});
-Object.defineProperty(exports, "BatchError", {
-  enumerable: true,
-  get: function () { return chunkXYL43FDX_cjs.BatchError; }
+  get: function () { return chunkAHF4H42Q_cjs.BatchBuilder; }
 });
 Object.defineProperty(exports, "DeleteBuilder", {
   enumerable: true,
-  get: function () { return chunkXYL43FDX_cjs.DeleteBuilder; }
+  get: function () { return chunkAHF4H42Q_cjs.DeleteBuilder; }
 });
 Object.defineProperty(exports, "PutBuilder", {
   enumerable: true,
-  get: function () { return chunkXYL43FDX_cjs.PutBuilder; }
+  get: function () { return chunkAHF4H42Q_cjs.PutBuilder; }
 });
 Object.defineProperty(exports, "QueryBuilder", {
   enumerable: true,
-  get: function () { return chunkXYL43FDX_cjs.QueryBuilder; }
+  get: function () { return chunkAHF4H42Q_cjs.QueryBuilder; }
 });
 Object.defineProperty(exports, "TransactionBuilder", {
   enumerable: true,
-  get: function () { return chunkXYL43FDX_cjs.TransactionBuilder; }
+  get: function () { return chunkAHF4H42Q_cjs.TransactionBuilder; }
 });
 Object.defineProperty(exports, "UpdateBuilder", {
   enumerable: true,
-  get: function () { return chunkXYL43FDX_cjs.UpdateBuilder; }
+  get: function () { return chunkAHF4H42Q_cjs.UpdateBuilder; }
+});
+Object.defineProperty(exports, "BatchError", {
+  enumerable: true,
+  get: function () { return chunkELULXDSB_cjs.BatchError; }
+});
+Object.defineProperty(exports, "BatchErrors", {
+  enumerable: true,
+  get: function () { return chunkELULXDSB_cjs.BatchErrors; }
+});
+Object.defineProperty(exports, "ConfigurationError", {
+  enumerable: true,
+  get: function () { return chunkELULXDSB_cjs.ConfigurationError; }
+});
+Object.defineProperty(exports, "ConfigurationErrors", {
+  enumerable: true,
+  get: function () { return chunkELULXDSB_cjs.ConfigurationErrors; }
+});
+Object.defineProperty(exports, "DynoTableError", {
+  enumerable: true,
+  get: function () { return chunkELULXDSB_cjs.DynoTableError; }
+});
+Object.defineProperty(exports, "EntityError", {
+  enumerable: true,
+  get: function () { return chunkELULXDSB_cjs.EntityError; }
+});
+Object.defineProperty(exports, "EntityErrors", {
+  enumerable: true,
+  get: function () { return chunkELULXDSB_cjs.EntityErrors; }
+});
+Object.defineProperty(exports, "EntityValidationError", {
+  enumerable: true,
+  get: function () { return chunkELULXDSB_cjs.EntityValidationError; }
+});
+Object.defineProperty(exports, "ErrorCodes", {
+  enumerable: true,
+  get: function () { return chunkELULXDSB_cjs.ErrorCodes; }
+});
+Object.defineProperty(exports, "ExpressionError", {
+  enumerable: true,
+  get: function () { return chunkELULXDSB_cjs.ExpressionError; }
+});
+Object.defineProperty(exports, "ExpressionErrors", {
+  enumerable: true,
+  get: function () { return chunkELULXDSB_cjs.ExpressionErrors; }
+});
+Object.defineProperty(exports, "IndexErrors", {
+  enumerable: true,
+  get: function () { return chunkELULXDSB_cjs.IndexErrors; }
+});
+Object.defineProperty(exports, "IndexGenerationError", {
+  enumerable: true,
+  get: function () { return chunkELULXDSB_cjs.IndexGenerationError; }
+});
+Object.defineProperty(exports, "KeyGenerationError", {
+  enumerable: true,
+  get: function () { return chunkELULXDSB_cjs.KeyGenerationError; }
+});
+Object.defineProperty(exports, "OperationError", {
+  enumerable: true,
+  get: function () { return chunkELULXDSB_cjs.OperationError; }
+});
+Object.defineProperty(exports, "OperationErrors", {
+  enumerable: true,
+  get: function () { return chunkELULXDSB_cjs.OperationErrors; }
+});
+Object.defineProperty(exports, "TransactionError", {
+  enumerable: true,
+  get: function () { return chunkELULXDSB_cjs.TransactionError; }
+});
+Object.defineProperty(exports, "TransactionErrors", {
+  enumerable: true,
+  get: function () { return chunkELULXDSB_cjs.TransactionErrors; }
+});
+Object.defineProperty(exports, "ValidationError", {
+  enumerable: true,
+  get: function () { return chunkELULXDSB_cjs.ValidationError; }
+});
+Object.defineProperty(exports, "ValidationErrors", {
+  enumerable: true,
+  get: function () { return chunkELULXDSB_cjs.ValidationErrors; }
 });
 Object.defineProperty(exports, "and", {
   enumerable: true,

package/dist/index.d.cts

@@ -1,8 +1,273 @@
-export { B as BatchBuilder, a as BatchError, b as BatchResult, D as DeleteBuilder, c as DeleteOptions, P as PutBuilder, d as PutOptions, Q as QueryBuilder, e as QueryOptions, T as TransactionBuilder, f as TransactionOptions, U as UpdateBuilder, g as UpdateOptions } from './index-DlN8G9hd.cjs';
-export { C as ComparisonOperator, a as Condition, b as ConditionOperator, E as ExpressionParams, K as KeyConditionOperator, L as LogicalOperator, P as PrimaryKey, c as PrimaryKeyWithoutExpression, d as and, e as attributeExists, f as attributeNotExists, g as beginsWith, h as between, i as contains, j as eq, k as gt, l as gte, m as inArray, n as lt, o as lte, p as ne, q as not, r as or } from './conditions-CcZL0sR2.cjs';
+import { c as BatchError, d as ConfigurationError, E as ExpressionError, e as EntityValidationError, K as KeyGenerationError, I as IndexGenerationError, O as OperationError, f as TransactionError, V as ValidationError, g as DynoTableError, h as EntityError } from './index-BX-MSZHj.cjs';
+export { B as BatchBuilder, i as BatchResult, D as DeleteBuilder, j as DeleteOptions, o as ErrorCode, n as ErrorCodes, P as PutBuilder, k as PutOptions, Q as QueryBuilder, l as QueryOptions, T as TransactionBuilder, a as TransactionOptions, U as UpdateBuilder, m as UpdateOptions } from './index-BX-MSZHj.cjs';
+export { C as ComparisonOperator, b as Condition, c as ConditionOperator, E as ExpressionParams, K as KeyConditionOperator, L as LogicalOperator, a as PrimaryKey, P as PrimaryKeyWithoutExpression, d as and, e as attributeExists, f as attributeNotExists, g as beginsWith, h as between, i as contains, j as eq, k as gt, l as gte, m as inArray, n as lt, o as lte, p as ne, q as not, r as or } from './conditions-C8bM__Pn.cjs';
 export { EntityConfig, EntityRepository, IndexDefinition, QueryEntity, QueryRecord, createIndex, createQueries, defineEntity } from './entity.cjs';
 export { Table } from './table.cjs';
 export { partitionKey, sortKey } from './utils.cjs';
 import './types.cjs';
 import '@aws-sdk/lib-dynamodb';
 import './standard-schema.cjs';
+
+/**
+ * Factory functions for Expression errors
+ */
+declare const ExpressionErrors: {
+    missingAttribute: (conditionType: string, condition: unknown) => ExpressionError;
+    missingValue: (conditionType: string, condition: unknown) => ExpressionError;
+    invalidCondition: (conditionType: string, condition: unknown, suggestion?: string) => ExpressionError;
+    emptyArray: (conditionType: string, providedValue: unknown) => ExpressionError;
+    unknownType: (conditionType: string, condition: unknown) => ExpressionError;
+};
+/**
+ * Factory functions for Validation errors
+ */
+declare const ValidationErrors: {
+    indexSchemaValidationFailed: (validationIssues: unknown, keyType: "partition" | "sort" | "both") => ValidationError;
+    noUpdateActions: (tableName: string, key: Record<string, unknown>) => ValidationError;
+    conditionRequired: (tableName: string, key: Record<string, unknown>) => ValidationError;
+    queryInputValidationFailed: (entityName: string, queryName: string, validationIssues: unknown, providedInput: unknown) => ValidationError;
+    undefinedValue: (path: string, tableName: string, key: Record<string, unknown>) => ValidationError;
+};
+/**
+ * Factory functions for Configuration errors
+ */
+declare const ConfigurationErrors: {
+    invalidChunkSize: (size: number) => ConfigurationError;
+    sortKeyRequired: (tableName: string, partitionKey: string, sortKey?: string) => ConfigurationError;
+    sortKeyNotDefined: (tableName: string, partitionKey: string, indexName?: string) => ConfigurationError;
+    gsiNotFound: (indexName: string, tableName: string, availableIndexes: string[]) => ConfigurationError;
+    primaryKeyMissing: (tableName: string, partitionKeyName: string, providedItem: unknown) => ConfigurationError;
+    pkExtractionFailed: (tableName: string, indexName: string, item: unknown, cause?: Error) => ConfigurationError;
+    conditionGenerationFailed: (condition: unknown, suggestion?: string) => ExpressionError;
+};
+/**
+ * Factory functions for Operation errors
+ */
+declare const OperationErrors: {
+    queryFailed: (tableName: string, context: Record<string, unknown>, cause?: Error) => OperationError;
+    scanFailed: (tableName: string, context: Record<string, unknown>, cause?: Error) => OperationError;
+    getFailed: (tableName: string, key: Record<string, unknown>, cause?: Error) => OperationError;
+    putFailed: (tableName: string, item: unknown, cause?: Error) => OperationError;
+    updateFailed: (tableName: string, key: Record<string, unknown>, cause?: Error) => OperationError;
+    deleteFailed: (tableName: string, key: Record<string, unknown>, cause?: Error) => OperationError;
+    batchGetFailed: (tableName: string, context: Record<string, unknown>, cause?: Error) => OperationError;
+    batchWriteFailed: (tableName: string, context: Record<string, unknown>, cause?: Error) => OperationError;
+};
+/**
+ * Factory functions for Transaction errors
+ */
+declare const TransactionErrors: {
+    transactionFailed: (itemCount: number, context: Record<string, unknown>, cause?: Error) => TransactionError;
+    duplicateItem: (tableName: string, partitionKey: {
+        name: string;
+        value: unknown;
+    }, sortKey?: {
+        name: string;
+        value: unknown;
+    }) => TransactionError;
+    transactionEmpty: () => TransactionError;
+    unsupportedType: (item: unknown) => TransactionError;
+};
+/**
+ * Factory functions for Batch errors
+ */
+declare const BatchErrors: {
+    batchEmpty: (operation: "write" | "read") => BatchError;
+    unsupportedType: (operation: "write" | "read", item: unknown) => BatchError;
+    batchWriteFailed: (unprocessedItems: unknown[], context: Record<string, unknown>, cause?: Error) => BatchError;
+    batchGetFailed: (unprocessedItems: unknown[], context: Record<string, unknown>, cause?: Error) => BatchError;
+};
+/**
+ * Factory functions for Entity errors
+ */
+declare const EntityErrors: {
+    validationFailed: (entityName: string, operation: string, validationIssues: unknown, providedData: unknown) => EntityValidationError;
+    queryInputValidationFailed: (entityName: string, queryName: string, validationIssues: unknown, providedInput: unknown) => EntityValidationError;
+    asyncValidationNotSupported: (entityName: string, operation: string) => EntityValidationError;
+    keyGenerationFailed: (entityName: string, operation: string, providedData: unknown, requiredAttributes?: string[], cause?: Error) => KeyGenerationError;
+    keyInvalidFormat: (entityName: string, operation: string, providedData: unknown, generatedKey: unknown) => KeyGenerationError;
+    keyMissingAttributes: (entityName: string, operation: string, missingAttributes: string[], providedData: unknown) => KeyGenerationError;
+};
+/**
+ * Factory functions for Index errors
+ */
+declare const IndexErrors: {
+    generationFailed: (indexName: string, operation: string, providedItem: unknown, partitionKeyAttribute?: string, sortKeyAttribute?: string, cause?: Error) => IndexGenerationError;
+    missingAttributes: (indexName: string, operation: string, missingAttributes: string[], providedData: unknown, isReadOnly: boolean) => IndexGenerationError;
+    undefinedValues: (indexName: string, operation: string, generatedKey: unknown, providedItem: unknown) => IndexGenerationError;
+    notFound: (requestedIndexes: string[], availableIndexes: string[], entityName?: string, tableName?: string) => IndexGenerationError;
+    readonlyUpdateFailed: (indexName: string, operation: string, providedData: unknown) => IndexGenerationError;
+};
+
+/**
+ * Utility functions for error handling
+ *
+ * This module provides helper functions for wrapping AWS SDK errors,
+ * extracting information from errors, and formatting error context.
+ */
+
+/**
+ * Checks if an error is a DynamoDB conditional check failure
+ *
+ * @param error - The error to check
+ * @returns true if the error is a conditional check failure
+ */
+declare function isConditionalCheckFailed(error: unknown): boolean;
+/**
+ * Checks if an error is a DynamoDB transaction cancellation
+ *
+ * @param error - The error to check
+ * @returns true if the error is a transaction cancellation
+ */
+declare function isTransactionCanceled(error: unknown): boolean;
+/**
+ * Checks if an error is a DynamoDB validation exception
+ *
+ * @param error - The error to check
+ * @returns true if the error is a validation exception
+ */
+declare function isValidationException(error: unknown): boolean;
+/**
+ * Checks if an error is a DynamoDB provisioned throughput exceeded exception
+ *
+ * @param error - The error to check
+ * @returns true if the error is a throughput exceeded exception
+ */
+declare function isProvisionedThroughputExceeded(error: unknown): boolean;
+/**
+ * Checks if an error is a retryable error
+ *
+ * Retryable errors include:
+ * - ProvisionedThroughputExceededException
+ * - ThrottlingException
+ * - RequestLimitExceeded
+ * - InternalServerError
+ * - ServiceUnavailable
+ *
+ * @param error - The error to check
+ * @returns true if the error is retryable
+ */
+declare function isRetryableError(error: unknown): boolean;
+/**
+ * Extracts the AWS error code from an error
+ *
+ * @param error - The error to extract the code from
+ * @returns The error code, or undefined if not found
+ */
+declare function getAwsErrorCode(error: unknown): string | undefined;
+/**
+ * Extracts the AWS error message from an error
+ *
+ * @param error - The error to extract the message from
+ * @returns The error message, or undefined if not found
+ */
+declare function getAwsErrorMessage(error: unknown): string | undefined;
+/**
+ * Attempts to extract required attribute names from an error message
+ *
+ * This is a best-effort function that looks for common patterns in error
+ * messages to identify which attributes are missing or required.
+ *
+ * @param error - The error to extract attributes from
+ * @returns Array of attribute names, or undefined if none found
+ */
+declare function extractRequiredAttributes(error: unknown): string[] | undefined;
+/**
+ * Formats error context for logging
+ *
+ * Converts the error context object to a readable string format,
+ * handling special types like arrays and nested objects.
+ *
+ * @param context - The error context to format
+ * @param indent - The indentation level (for nested objects)
+ * @returns Formatted context string
+ */
+declare function formatErrorContext(context: Record<string, unknown>, indent?: number): string;
+/**
+ * Creates a detailed error summary including context
+ *
+ * Useful for logging or displaying error information to developers.
+ *
+ * @param error - The DynoTableError to summarize
+ * @returns Formatted error summary
+ */
+declare function getErrorSummary(error: DynoTableError): string;
+/**
+ * Type guard to check if an error is a DynoTableError
+ *
+ * @param error - The error to check
+ * @returns true if the error is a DynoTableError
+ */
+declare function isDynoTableError(error: unknown): error is DynoTableError;
+/**
+ * Type guard to check if an error is a ValidationError
+ *
+ * @param error - The error to check
+ * @returns true if the error is a ValidationError
+ */
+declare function isValidationError(error: unknown): error is ValidationError;
+/**
+ * Type guard to check if an error is an OperationError
+ *
+ * @param error - The error to check
+ * @returns true if the error is an OperationError
+ */
+declare function isOperationError(error: unknown): error is OperationError;
+/**
+ * Type guard to check if an error is a TransactionError
+ *
+ * @param error - The error to check
+ * @returns true if the error is a TransactionError
+ */
+declare function isTransactionError(error: unknown): error is TransactionError;
+/**
+ * Type guard to check if an error is a BatchError
+ *
+ * @param error - The error to check
+ * @returns true if the error is a BatchError
+ */
+declare function isBatchError(error: unknown): error is BatchError;
+/**
+ * Type guard to check if an error is an ExpressionError
+ *
+ * @param error - The error to check
+ * @returns true if the error is an ExpressionError
+ */
+declare function isExpressionError(error: unknown): error is ExpressionError;
+/**
+ * Type guard to check if an error is a ConfigurationError
+ *
+ * @param error - The error to check
+ * @returns true if the error is a ConfigurationError
+ */
+declare function isConfigurationError(error: unknown): error is ConfigurationError;
+/**
+ * Type guard to check if an error is an EntityError
+ *
+ * @param error - The error to check
+ * @returns true if the error is an EntityError
+ */
+declare function isEntityError(error: unknown): error is EntityError;
+/**
+ * Type guard to check if an error is a KeyGenerationError
+ *
+ * @param error - The error to check
+ * @returns true if the error is a KeyGenerationError
+ */
+declare function isKeyGenerationError(error: unknown): error is KeyGenerationError;
+/**
+ * Type guard to check if an error is an IndexGenerationError
+ *
+ * @param error - The error to check
+ * @returns true if the error is an IndexGenerationError
+ */
+declare function isIndexGenerationError(error: unknown): error is IndexGenerationError;
+/**
+ * Type guard to check if an error is an EntityValidationError
+ *
+ * @param error - The error to check
+ * @returns true if the error is an EntityValidationError
+ */
+declare function isEntityValidationError(error: unknown): error is EntityValidationError;
+
+export { BatchError, BatchErrors, ConfigurationError, ConfigurationErrors, DynoTableError, EntityError, EntityErrors, EntityValidationError, ExpressionError, ExpressionErrors, IndexErrors, IndexGenerationError, KeyGenerationError, OperationError, OperationErrors, TransactionError, TransactionErrors, ValidationError, ValidationErrors, extractRequiredAttributes, formatErrorContext, getAwsErrorCode, getAwsErrorMessage, getErrorSummary, isBatchError, isConditionalCheckFailed, isConfigurationError, isDynoTableError, isEntityError, isEntityValidationError, isExpressionError, isIndexGenerationError, isKeyGenerationError, isOperationError, isProvisionedThroughputExceeded, isRetryableError, isTransactionCanceled, isTransactionError, isValidationError, isValidationException };