dyno-table 2.3.3 → 2.4.0

package/dist/{chunk-M5Y6JQJN.js → chunk-U6MQGB6Y.js}

@@ -1,3 +1,4 @@
+import { EntityErrors, OperationErrors, DynoTableError, ValidationErrors, IndexErrors, ConfigurationErrors } from './chunk-FF7FYGDH.js';
 import { eq } from './chunk-2WIBY7PZ.js';
 
 // src/builders/entity-aware-builders.ts
@@ -112,9 +113,6 @@ var EntityAwareUpdateBuilder = class {
     if (typeof valuesOrPath === "object") {
       this.builder.set(valuesOrPath);
     } else {
-      if (value === void 0) {
-        throw new Error("Value is required when setting a single path");
-      }
       this.builder.set(valuesOrPath, value);
     }
     return this;
@@ -159,6 +157,136 @@ function createEntityAwareUpdateBuilder(builder, entityName) {
   return new EntityAwareUpdateBuilder(builder, entityName);
 }
 
+// src/utils/error-utils.ts
+function isConditionalCheckFailed(error) {
+  if (typeof error === "object" && error !== null && "name" in error) {
+    return error.name === "ConditionalCheckFailedException";
+  }
+  return false;
+}
+function isTransactionCanceled(error) {
+  if (typeof error === "object" && error !== null && "name" in error) {
+    return error.name === "TransactionCanceledException";
+  }
+  return false;
+}
+function isValidationException(error) {
+  if (typeof error === "object" && error !== null && "name" in error) {
+    return error.name === "ValidationException";
+  }
+  return false;
+}
+function isProvisionedThroughputExceeded(error) {
+  if (typeof error === "object" && error !== null && "name" in error) {
+    return error.name === "ProvisionedThroughputExceededException";
+  }
+  return false;
+}
+function isRetryableError(error) {
+  if (typeof error === "object" && error !== null && "name" in error) {
+    const errorName = error.name;
+    return errorName === "ProvisionedThroughputExceededException" || errorName === "ThrottlingException" || errorName === "RequestLimitExceeded" || errorName === "InternalServerError" || errorName === "ServiceUnavailable";
+  }
+  return false;
+}
+function getAwsErrorCode(error) {
+  if (typeof error === "object" && error !== null && "name" in error) {
+    return error.name;
+  }
+  return void 0;
+}
+function getAwsErrorMessage(error) {
+  if (error instanceof Error) {
+    return error.message;
+  }
+  if (typeof error === "object" && error !== null && "message" in error) {
+    return String(error.message);
+  }
+  return void 0;
+}
+function extractRequiredAttributes(error) {
+  const message = getAwsErrorMessage(error);
+  if (!message) return void 0;
+  const patterns = [
+    /(?:missing|required)\s+(?:attribute|field|property)(?:s)?[:\s]+([a-zA-Z0-9_,\s]+)/i,
+    /(?:attribute|field|property)[:\s]+([a-zA-Z0-9_]+)\s+is\s+(?:missing|required)/i,
+    /"([a-zA-Z0-9_]+)"\s+is\s+(?:missing|required)/i
+  ];
+  for (const pattern of patterns) {
+    const match = message.match(pattern);
+    if (match?.[1]) {
+      return match[1].split(",").map((attr) => attr.trim()).filter((attr) => attr.length > 0);
+    }
+  }
+  return void 0;
+}
+function formatErrorContext(context, indent = 0) {
+  const indentStr = "  ".repeat(indent);
+  const lines = [];
+  for (const [key, value] of Object.entries(context)) {
+    if (value === void 0 || value === null) {
+      lines.push(`${indentStr}${key}: ${value}`);
+    } else if (Array.isArray(value)) {
+      lines.push(`${indentStr}${key}: [${value.map((v) => JSON.stringify(v)).join(", ")}]`);
+    } else if (typeof value === "object") {
+      lines.push(`${indentStr}${key}:`);
+      lines.push(formatErrorContext(value, indent + 1));
+    } else if (typeof value === "string" && value.length > 100) {
+      lines.push(`${indentStr}${key}: ${value.substring(0, 100)}...`);
+    } else {
+      lines.push(`${indentStr}${key}: ${JSON.stringify(value)}`);
+    }
+  }
+  return lines.join("\n");
+}
+function getErrorSummary(error) {
+  const parts = [];
+  parts.push(`Error: ${error.name}`);
+  parts.push(`Code: ${error.code}`);
+  parts.push(`Message: ${error.message}`);
+  if (Object.keys(error.context).length > 0) {
+    parts.push("Context:");
+    parts.push(formatErrorContext(error.context, 1));
+  }
+  if (error.cause) {
+    parts.push(`Caused by: ${error.cause.name}: ${error.cause.message}`);
+  }
+  return parts.join("\n");
+}
+function isDynoTableError(error) {
+  return typeof error === "object" && error !== null && "code" in error && "context" in error && error instanceof Error;
+}
+function isValidationError(error) {
+  return error instanceof Error && error.name === "ValidationError";
+}
+function isOperationError(error) {
+  return error instanceof Error && error.name === "OperationError";
+}
+function isTransactionError(error) {
+  return error instanceof Error && error.name === "TransactionError";
+}
+function isBatchError(error) {
+  return error instanceof Error && error.name === "BatchError";
+}
+function isExpressionError(error) {
+  return error instanceof Error && error.name === "ExpressionError";
+}
+function isConfigurationError(error) {
+  return error instanceof Error && error.name === "ConfigurationError";
+}
+function isEntityError(error) {
+  return error instanceof Error && error.name === "EntityError";
+}
+function isKeyGenerationError(error) {
+  return error instanceof Error && error.name === "KeyGenerationError";
+}
+function isIndexGenerationError(error) {
+  return error instanceof Error && error.name === "IndexGenerationError";
+}
+function isEntityValidationError(error) {
+  return error instanceof Error && error.name === "EntityValidationError";
+}
+
 // src/entity/ddb-indexing.ts
 var IndexBuilder = class {
   /**
@@ -184,10 +312,26 @@ var IndexBuilder = class {
       if (options.excludeReadOnly && indexDef.isReadOnly) {
         continue;
       }
-      const key = indexDef.generateKey(item);
+      let key;
+      try {
+        key = indexDef.generateKey(item);
+        if (this.hasUndefinedValues(key)) {
+          throw IndexErrors.undefinedValues(indexName, "create", key, item);
+        }
+      } catch (error) {
+        if (error instanceof DynoTableError) throw error;
+        throw IndexErrors.generationFailed(
+          indexName,
+          "create",
+          item,
+          indexDef.partitionKey,
+          indexDef.sortKey,
+          error instanceof Error ? error : void 0
+        );
+      }
       const gsiConfig = this.table.gsis[indexName];
       if (!gsiConfig) {
-        throw new Error(`GSI configuration not found for index: ${indexName}`);
+        throw ConfigurationErrors.gsiNotFound(indexName, this.table.tableName, Object.keys(this.table.gsis));
       }
       if (key.pk) {
         attributes[gsiConfig.partitionKey] = key.pk;
@@ -212,9 +356,7 @@ var IndexBuilder = class {
     if (options.forceRebuildIndexes && options.forceRebuildIndexes.length > 0) {
       const invalidIndexes = options.forceRebuildIndexes.filter((indexName) => !this.indexes[indexName]);
       if (invalidIndexes.length > 0) {
-        throw new Error(
-          `Cannot force rebuild unknown indexes: ${invalidIndexes.join(", ")}. Available indexes: ${Object.keys(this.indexes).join(", ")}`
-        );
+        throw IndexErrors.notFound(invalidIndexes, Object.keys(this.indexes), void 0, this.table.tableName);
       }
     }
     for (const [indexName, indexDef] of Object.entries(this.indexes)) {
@@ -241,19 +383,22 @@ var IndexBuilder = class {
       try {
         key = indexDef.generateKey(updatedItem);
       } catch (error) {
-        if (error instanceof Error) {
-          throw new Error(`Missing attributes: ${error.message}`);
-        }
-        throw error;
+        if (error instanceof DynoTableError) throw error;
+        throw IndexErrors.missingAttributes(
+          indexName,
+          "update",
+          [],
+          // We don't know which specific attributes are missing from the error
+          updates,
+          indexDef.isReadOnly
+        );
       }
       if (this.hasUndefinedValues(key)) {
-        throw new Error(
-          `Missing attributes: Cannot update entity: insufficient data to regenerate index "${indexName}". All attributes required by the index must be provided in the update operation, or the index must be marked as readOnly.`
-        );
+        throw IndexErrors.undefinedValues(indexName, "update", key, updates);
       }
       const gsiConfig = this.table.gsis[indexName];
       if (!gsiConfig) {
-        throw new Error(`GSI configuration not found for index: ${indexName}`);
+        throw ConfigurationErrors.gsiNotFound(indexName, this.table.tableName, Object.keys(this.table.gsis));
       }
       if (key.pk) {
         attributes[gsiConfig.partitionKey] = key.pk;
@@ -340,13 +485,28 @@ function defineEntity(config) {
           const prepareValidatedItemAsync = async () => {
             const validatedData = await config.schema["~standard"].validate(data);
             if ("issues" in validatedData && validatedData.issues) {
-              throw new Error(`Validation failed: ${validatedData.issues.map((i) => i.message).join(", ")}`);
+              throw EntityErrors.validationFailed(config.name, "create", validatedData.issues, data);
             }
             const dataForKeyGeneration = {
               ...validatedData.value,
               ...generateTimestamps(["createdAt", "updatedAt"], validatedData.value)
             };
-            const primaryKey = config.primaryKey.generateKey(dataForKeyGeneration);
+            let primaryKey;
+            try {
+              primaryKey = config.primaryKey.generateKey(dataForKeyGeneration);
+              if (primaryKey.pk === void 0 || primaryKey.pk === null) {
+                throw EntityErrors.keyInvalidFormat(config.name, "create", dataForKeyGeneration, primaryKey);
+              }
+            } catch (error) {
+              if (error instanceof DynoTableError) throw error;
+              throw EntityErrors.keyGenerationFailed(
+                config.name,
+                "create",
+                dataForKeyGeneration,
+                extractRequiredAttributes(error),
+                error instanceof Error ? error : void 0
+              );
+            }
             const indexes = buildIndexes(dataForKeyGeneration, table, config.indexes, false);
             const validatedItem = {
               ...dataForKeyGeneration,
@@ -361,18 +521,31 @@ function defineEntity(config) {
           const prepareValidatedItemSync = () => {
             const validationResult = config.schema["~standard"].validate(data);
             if (validationResult instanceof Promise) {
-              throw new Error(
-                "Async validation is not supported in withBatch or withTransaction. The schema must support synchronous validation for compatibility."
-              );
+              throw EntityErrors.asyncValidationNotSupported(config.name, "create");
             }
             if ("issues" in validationResult && validationResult.issues) {
-              throw new Error(`Validation failed: ${validationResult.issues.map((i) => i.message).join(", ")}`);
+              throw EntityErrors.validationFailed(config.name, "create", validationResult.issues, data);
             }
             const dataForKeyGeneration = {
               ...validationResult.value,
               ...generateTimestamps(["createdAt", "updatedAt"], validationResult.value)
             };
-            const primaryKey = config.primaryKey.generateKey(dataForKeyGeneration);
+            let primaryKey;
+            try {
+              primaryKey = config.primaryKey.generateKey(dataForKeyGeneration);
+              if (primaryKey.pk === void 0 || primaryKey.pk === null) {
+                throw EntityErrors.keyInvalidFormat(config.name, "create", dataForKeyGeneration, primaryKey);
+              }
+            } catch (error) {
+              if (error instanceof DynoTableError) throw error;
+              throw EntityErrors.keyGenerationFailed(
+                config.name,
+                "create",
+                dataForKeyGeneration,
+                extractRequiredAttributes(error),
+                error instanceof Error ? error : void 0
+              );
+            }
             const indexes = buildIndexes(dataForKeyGeneration, table, config.indexes, false);
             const validatedItem = {
               ...dataForKeyGeneration,
@@ -408,13 +581,28 @@ function defineEntity(config) {
           const prepareValidatedItemAsync = async () => {
             const validatedData = await config.schema["~standard"].validate(data);
             if ("issues" in validatedData && validatedData.issues) {
-              throw new Error(`Validation failed: ${validatedData.issues.map((i) => i.message).join(", ")}`);
+              throw EntityErrors.validationFailed(config.name, "upsert", validatedData.issues, data);
             }
             const dataForKeyGeneration = {
               ...validatedData.value,
               ...generateTimestamps(["createdAt", "updatedAt"], validatedData.value)
             };
-            const primaryKey = config.primaryKey.generateKey(dataForKeyGeneration);
+            let primaryKey;
+            try {
+              primaryKey = config.primaryKey.generateKey(dataForKeyGeneration);
+              if (primaryKey.pk === void 0 || primaryKey.pk === null) {
+                throw EntityErrors.keyInvalidFormat(config.name, "upsert", dataForKeyGeneration, primaryKey);
+              }
+            } catch (error) {
+              if (error instanceof DynoTableError) throw error;
+              throw EntityErrors.keyGenerationFailed(
+                config.name,
+                "upsert",
+                dataForKeyGeneration,
+                extractRequiredAttributes(error),
+                error instanceof Error ? error : void 0
+              );
+            }
             const indexes = buildIndexes2(dataForKeyGeneration, table, false);
             const validatedItem = {
               [table.partitionKey]: primaryKey.pk,
@@ -429,18 +617,31 @@ function defineEntity(config) {
           const prepareValidatedItemSync = () => {
             const validationResult = config.schema["~standard"].validate(data);
             if (validationResult instanceof Promise) {
-              throw new Error(
-                "Async validation is not supported in withTransaction or withBatch. Use execute() instead."
-              );
+              throw EntityErrors.asyncValidationNotSupported(config.name, "upsert");
             }
             if ("issues" in validationResult && validationResult.issues) {
-              throw new Error(`Validation failed: ${validationResult.issues.map((i) => i.message).join(", ")}`);
+              throw EntityErrors.validationFailed(config.name, "upsert", validationResult.issues, data);
             }
             const dataForKeyGeneration = {
               ...validationResult.value,
               ...generateTimestamps(["createdAt", "updatedAt"], validationResult.value)
             };
-            const primaryKey = config.primaryKey.generateKey(dataForKeyGeneration);
+            let primaryKey;
+            try {
+              primaryKey = config.primaryKey.generateKey(dataForKeyGeneration);
+              if (primaryKey.pk === void 0 || primaryKey.pk === null) {
+                throw EntityErrors.keyInvalidFormat(config.name, "upsert", dataForKeyGeneration, primaryKey);
+              }
+            } catch (error) {
+              if (error instanceof DynoTableError) throw error;
+              throw EntityErrors.keyGenerationFailed(
+                config.name,
+                "upsert",
+                dataForKeyGeneration,
+                extractRequiredAttributes(error),
+                error instanceof Error ? error : void 0
+              );
+            }
             const indexes = buildIndexes(dataForKeyGeneration, table, config.indexes, false);
             const validatedItem = {
               [table.partitionKey]: primaryKey.pk,
@@ -457,7 +658,7 @@ function defineEntity(config) {
             await prepareValidatedItemAsync();
             const result = await originalExecute.call(builder);
             if (!result) {
-              throw new Error("Failed to upsert item");
+              throw OperationErrors.putFailed(config.name, {}, void 0);
             }
             return result;
           };
@@ -476,7 +677,8 @@ function defineEntity(config) {
           return createEntityAwarePutBuilder(builder, config.name);
         },
         get: (key) => {
-          return createEntityAwareGetBuilder(table.get(config.primaryKey.generateKey(key)), config.name);
+          const builder = table.get(config.primaryKey.generateKey(key));
+          return createEntityAwareGetBuilder(builder, config.name);
         },
         update: (key, data) => {
           const primaryKeyObj = config.primaryKey.generateKey(key);
@@ -522,15 +724,13 @@ function defineEntity(config) {
                     if (schema?.["~standard"]?.validate && typeof schema["~standard"].validate === "function") {
                       const validationResult = schema["~standard"].validate(input);
                       if ("issues" in validationResult && validationResult.issues) {
-                        throw new Error(
-                          `Validation failed: ${validationResult.issues.map((issue) => issue.message).join(", ")}`
-                        );
+                        throw EntityErrors.queryInputValidationFailed(config.name, key, validationResult.issues, input);
                       }
                     }
                   }
                   const result = await originalExecute.call(builder);
                   if (!result) {
-                    throw new Error("Failed to execute query");
+                    throw OperationErrors.queryFailed(config.name, { queryName: key }, void 0);
                   }
                   return result;
                 };
@@ -576,7 +776,7 @@ function createIndex() {
               generateKey: (item) => {
                 const data = schema["~standard"].validate(item);
                 if ("issues" in data && data.issues) {
-                  throw new Error(`Index validation failed: ${data.issues.map((i) => i.message).join(", ")}`);
+                  throw ValidationErrors.indexSchemaValidationFailed(data.issues, "both");
                 }
                 const validData = "value" in data ? data.value : item;
                 return { pk: pkFn(validData), sk: skFn(validData) };
@@ -597,7 +797,7 @@ function createIndex() {
               generateKey: (item) => {
                 const data = schema["~standard"].validate(item);
                 if ("issues" in data && data.issues) {
-                  throw new Error(`Index validation failed: ${data.issues.map((i) => i.message).join(", ")}`);
+                  throw ValidationErrors.indexSchemaValidationFailed(data.issues, "partition");
                 }
                 const validData = "value" in data ? data.value : item;
                 return { pk: pkFn(validData) };
@@ -618,4 +818,4 @@ function createIndex() {
   };
 }
 
-export { createIndex, createQueries, defineEntity };
+export { createIndex, createQueries, defineEntity, extractRequiredAttributes, formatErrorContext, getAwsErrorCode, getAwsErrorMessage, getErrorSummary, isBatchError, isConditionalCheckFailed, isConfigurationError, isDynoTableError, isEntityError, isEntityValidationError, isExpressionError, isIndexGenerationError, isKeyGenerationError, isOperationError, isProvisionedThroughputExceeded, isRetryableError, isTransactionCanceled, isTransactionError, isValidationError, isValidationException };