s3db.js 11.2.2 → 11.2.4

package/src/errors.js

@@ -1,12 +1,12 @@
 export class BaseError extends Error {
-  constructor({ verbose, bucket, key, message, code, statusCode, requestId, awsMessage, original, commandName, commandInput, metadata, suggestion, ...rest }) {
+  constructor({ verbose, bucket, key, message, code, statusCode, requestId, awsMessage, original, commandName, commandInput, metadata, description, ...rest }) {
     if (verbose) message = message + `\n\nVerbose:\n\n${JSON.stringify(rest, null, 2)}`;
     super(message);
 
     if (typeof Error.captureStackTrace === 'function') {
       Error.captureStackTrace(this, this.constructor);
-    } else { 
-      this.stack = (new Error(message)).stack; 
+    } else {
+      this.stack = (new Error(message)).stack;
     }
 
     super.name = this.constructor.name;
@@ -22,7 +22,7 @@ export class BaseError extends Error {
     this.commandName = commandName;
     this.commandInput = commandInput;
     this.metadata = metadata;
-    this.suggestion = suggestion;
+    this.description = description;
     this.data = { bucket, key, ...rest, verbose, message };
   }
 
@@ -40,7 +40,7 @@ export class BaseError extends Error {
       commandName: this.commandName,
       commandInput: this.commandInput,
       metadata: this.metadata,
-      suggestion: this.suggestion,
+      description: this.description,
       data: this.data,
       original: this.original,
       stack: this.stack,
@@ -203,26 +203,26 @@ export function mapAwsError(err, context = {}) {
   const metadata = err.$metadata ? { ...err.$metadata } : undefined;
   const commandName = context.commandName;
   const commandInput = context.commandInput;
-  let suggestion;
+  let description;
   if (code === 'NoSuchKey' || code === 'NotFound') {
-    suggestion = 'Check if the key exists in the specified bucket and if your credentials have permission.';
-    return new NoSuchKey({ ...context, original: err, metadata, commandName, commandInput, suggestion });
+    description = 'The specified key does not exist in the bucket. Check if the key exists and if your credentials have permission to access it.';
+    return new NoSuchKey({ ...context, original: err, metadata, commandName, commandInput, description });
   }
   if (code === 'NoSuchBucket') {
-    suggestion = 'Check if the bucket exists and if your credentials have permission.';
-    return new NoSuchBucket({ ...context, original: err, metadata, commandName, commandInput, suggestion });
+    description = 'The specified bucket does not exist. Check if the bucket name is correct and if your credentials have permission to access it.';
+    return new NoSuchBucket({ ...context, original: err, metadata, commandName, commandInput, description });
   }
   if (code === 'AccessDenied' || (err.statusCode === 403) || code === 'Forbidden') {
-    suggestion = 'Check your credentials and bucket policy.';
-    return new PermissionError('Access denied', { ...context, original: err, metadata, commandName, commandInput, suggestion });
+    description = 'Access denied. Check your AWS credentials, IAM permissions, and bucket policy.';
+    return new PermissionError('Access denied', { ...context, original: err, metadata, commandName, commandInput, description });
   }
   if (code === 'ValidationError' || (err.statusCode === 400)) {
-    suggestion = 'Check the request parameters and payload.';
-    return new ValidationError('Validation error', { ...context, original: err, metadata, commandName, commandInput, suggestion });
+    description = 'Validation error. Check the request parameters and payload format.';
+    return new ValidationError('Validation error', { ...context, original: err, metadata, commandName, commandInput, description });
   }
   if (code === 'MissingMetadata') {
-    suggestion = 'Check if the object metadata is present and valid.';
-    return new MissingMetadata({ ...context, original: err, metadata, commandName, commandInput, suggestion });
+    description = 'Object metadata is missing or invalid. Check if the object was uploaded correctly.';
+    return new MissingMetadata({ ...context, original: err, metadata, commandName, commandInput, description });
   }
   // Outros mapeamentos podem ser adicionados aqui
   // Incluir detalhes do erro original para facilitar debug
@@ -232,38 +232,428 @@ export function mapAwsError(err, context = {}) {
     err.statusCode && `Status: ${err.statusCode}`,
     err.stack && `Stack: ${err.stack.split('\n')[0]}`,
   ].filter(Boolean).join(' | ');
-  
-  suggestion = `Check the error details and AWS documentation. Original error: ${err.message || err.toString()}`;
-  return new UnknownError(errorDetails, { ...context, original: err, metadata, commandName, commandInput, suggestion });
+
+  description = `Check the error details and AWS documentation. Original error: ${err.message || err.toString()}`;
+  return new UnknownError(errorDetails, { ...context, original: err, metadata, commandName, commandInput, description });
 }
 
 export class ConnectionStringError extends S3dbError {
   constructor(message, details = {}) {
-    super(message, { ...details, suggestion: 'Check the connection string format and credentials.' });
+    const description = details.description || 'Invalid connection string format. Check the connection string syntax and credentials.';
+    super(message, { ...details, description });
   }
 }
 
 export class CryptoError extends S3dbError {
   constructor(message, details = {}) {
-    super(message, { ...details, suggestion: 'Check if the crypto library is available and input is valid.' });
+    const description = details.description || 'Cryptography operation failed. Check if the crypto library is available and input is valid.';
+    super(message, { ...details, description });
   }
 }
 
 export class SchemaError extends S3dbError {
   constructor(message, details = {}) {
-    super(message, { ...details, suggestion: 'Check schema definition and input data.' });
+    const description = details.description || 'Schema validation failed. Check schema definition and input data format.';
+    super(message, { ...details, description });
   }
 }
 
 export class ResourceError extends S3dbError {
   constructor(message, details = {}) {
-    super(message, { ...details, suggestion: details.suggestion || 'Check resource configuration, attributes, and operation context.' });
+    const description = details.description || 'Resource operation failed. Check resource configuration, attributes, and operation context.';
+    super(message, { ...details, description });
     Object.assign(this, details);
   }
 }
 
 export class PartitionError extends S3dbError {
   constructor(message, details = {}) {
-    super(message, { ...details, suggestion: details.suggestion || 'Check partition definition, fields, and input values.' });
+    // Generate description if not provided
+    let description = details.description;
+    if (!description && details.resourceName && details.partitionName && details.fieldName) {
+      const { resourceName, partitionName, fieldName, availableFields = [] } = details;
+      description = `
+Partition Field Validation Error
+
+Resource: ${resourceName}
+Partition: ${partitionName}
+Missing Field: ${fieldName}
+
+Available fields in schema:
+${availableFields.map(f => `  • ${f}`).join('\n') || '  (no fields defined)'}
+
+Possible causes:
+1. Field was removed from schema but partition still references it
+2. Typo in partition field name
+3. Nested field path is incorrect (use dot notation like 'utm.source')
+
+Solution:
+${details.strictValidation === false
+  ? '  • Update partition definition to use existing fields'
+  : `  • Add missing field to schema, OR
+  • Update partition definition to use existing fields, OR
+  • Use strictValidation: false to skip this check during testing`}
+
+Docs: https://github.com/forattini-dev/s3db.js/blob/main/docs/README.md#partitions
+`.trim();
+    }
+
+    super(message, {
+      ...details,
+      description
+    });
+  }
+}
+
+export class AnalyticsNotEnabledError extends S3dbError {
+  constructor(details = {}) {
+    const {
+      pluginName = 'EventualConsistency',
+      resourceName = 'unknown',
+      field = 'unknown',
+      configuredResources = [],
+      registeredResources = [],
+      pluginInitialized = false,
+      ...rest
+    } = details;
+
+    const message = `Analytics not enabled for ${resourceName}.${field}`;
+
+    // Generate diagnostic description
+    const description = `
+Analytics Not Enabled
+
+Plugin: ${pluginName}
+Resource: ${resourceName}
+Field: ${field}
+
+Diagnostics:
+  • Plugin initialized: ${pluginInitialized ? '✓ Yes' : '✗ No'}
+  • Analytics resources created: ${registeredResources.length}/${configuredResources.length}
+${configuredResources.map(r => {
+  const exists = registeredResources.includes(r);
+  return `    ${exists ? '✓' : '✗'} ${r}${!exists ? ' (missing)' : ''}`;
+}).join('\n')}
+
+Possible causes:
+1. Resource not created yet - Analytics resources are created when db.createResource() is called
+2. Resource created before plugin initialization - Plugin must be initialized before resources
+3. Field not configured in analytics.resources config
+
+Correct initialization order:
+  1. Create database: const db = new Database({ ... })
+  2. Install plugins: await db.connect() (triggers plugin.install())
+  3. Create resources: await db.createResource({ name: '${resourceName}', ... })
+  4. Analytics resources are auto-created by plugin
+
+Example fix:
+  const db = new Database({
+    bucket: 'my-bucket',
+    plugins: [new EventualConsistencyPlugin({
+      resources: {
+        '${resourceName}': {
+          fields: {
+            '${field}': { type: 'counter', analytics: true }
+          }
+        }
+      }
+    })]
+  });
+
+  await db.connect();  // Plugin initialized here
+  await db.createResource({ name: '${resourceName}', ... });  // Analytics resource created here
+
+Docs: https://github.com/forattini-dev/s3db.js/blob/main/docs/plugins/eventual-consistency.md
+`.trim();
+
+    super(message, {
+      ...rest,
+      pluginName,
+      resourceName,
+      field,
+      configuredResources,
+      registeredResources,
+      pluginInitialized,
+      description
+    });
+  }
+}
+
+// Plugin errors
+export class PluginError extends S3dbError {
+  constructor(message, details = {}) {
+    const {
+      pluginName = 'Unknown',
+      operation = 'unknown',
+      ...rest
+    } = details;
+
+    let description = details.description;
+    if (!description) {
+      description = `
+Plugin Error
+
+Plugin: ${pluginName}
+Operation: ${operation}
+
+Possible causes:
+1. Plugin not properly initialized
+2. Plugin configuration is invalid
+3. Plugin dependencies not met
+4. Plugin method called before installation
+
+Solution:
+Ensure plugin is added to database and connect() is called before usage.
+
+Example:
+  const db = new Database({
+    bucket: 'my-bucket',
+    plugins: [new ${pluginName}({ /* config */ })]
+  });
+
+  await db.connect();  // Plugin installed here
+  // Now plugin methods are available
+
+Docs: https://github.com/forattini-dev/s3db.js/blob/main/docs/plugins/README.md
+`.trim();
+    }
+
+    super(message, {
+      ...rest,
+      pluginName,
+      operation,
+      description
+    });
+  }
+}
+
+// Plugin storage errors
+export class PluginStorageError extends S3dbError {
+  constructor(message, details = {}) {
+    const {
+      pluginSlug = 'unknown',
+      key = '',
+      operation = 'unknown',
+      ...rest
+    } = details;
+
+    let description = details.description;
+    if (!description) {
+      description = `
+Plugin Storage Error
+
+Plugin: ${pluginSlug}
+Key: ${key}
+Operation: ${operation}
+
+Possible causes:
+1. Storage not initialized (plugin not installed)
+2. Invalid key format
+3. S3 operation failed
+4. Permissions issue
+
+Solution:
+Ensure plugin has access to storage and key is valid.
+
+Docs: https://github.com/forattini-dev/s3db.js/blob/main/docs/plugins/README.md#plugin-storage
+`.trim();
+    }
+
+    super(message, {
+      ...rest,
+      pluginSlug,
+      key,
+      operation,
+      description
+    });
+  }
+}
+
+// Partition driver errors
+export class PartitionDriverError extends S3dbError {
+  constructor(message, details = {}) {
+    const {
+      driver = 'unknown',
+      operation = 'unknown',
+      queueSize,
+      maxQueueSize,
+      ...rest
+    } = details;
+
+    let description = details.description;
+    if (!description && queueSize !== undefined && maxQueueSize !== undefined) {
+      description = `
+Partition Driver Error
+
+Driver: ${driver}
+Operation: ${operation}
+Queue Status: ${queueSize}/${maxQueueSize}
+
+Possible causes:
+1. Queue is full (backpressure)
+2. Driver not properly configured
+3. SQS permissions issue (if using SQS driver)
+
+Solution:
+${queueSize >= maxQueueSize
+  ? 'Wait for queue to drain or increase maxQueueSize'
+  : 'Check driver configuration and permissions'}
+
+Docs: https://github.com/forattini-dev/s3db.js/blob/main/docs/README.md#partition-drivers
+`.trim();
+    } else if (!description) {
+      description = `
+Partition Driver Error
+
+Driver: ${driver}
+Operation: ${operation}
+
+Check driver configuration and permissions.
+
+Docs: https://github.com/forattini-dev/s3db.js/blob/main/docs/README.md#partition-drivers
+`.trim();
+    }
+
+    super(message, {
+      ...rest,
+      driver,
+      operation,
+      queueSize,
+      maxQueueSize,
+      description
+    });
+  }
+}
+
+// Behavior errors
+export class BehaviorError extends S3dbError {
+  constructor(message, details = {}) {
+    const {
+      behavior = 'unknown',
+      availableBehaviors = [],
+      ...rest
+    } = details;
+
+    let description = details.description;
+    if (!description) {
+      description = `
+Behavior Error
+
+Requested: ${behavior}
+Available: ${availableBehaviors.join(', ') || 'body-overflow, body-only, truncate-data, enforce-limits, user-managed'}
+
+Possible causes:
+1. Behavior name misspelled
+2. Custom behavior not registered
+
+Solution:
+Use one of the available behaviors or register custom behavior.
+
+Docs: https://github.com/forattini-dev/s3db.js/blob/main/docs/README.md#behaviors
+`.trim();
+    }
+
+    super(message, {
+      ...rest,
+      behavior,
+      availableBehaviors,
+      description
+    });
+  }
+}
+
+// Stream errors
+export class StreamError extends S3dbError {
+  constructor(message, details = {}) {
+    const {
+      operation = 'unknown',
+      resource,
+      ...rest
+    } = details;
+
+    let description = details.description;
+    if (!description) {
+      description = `
+Stream Error
+
+Operation: ${operation}
+${resource ? `Resource: ${resource}` : ''}
+
+Possible causes:
+1. Stream not properly initialized
+2. Resource not available
+3. Network error during streaming
+
+Solution:
+Check stream configuration and resource availability.
+
+Docs: https://github.com/forattini-dev/s3db.js/blob/main/docs/README.md#streaming
+`.trim();
+    }
+
+    super(message, {
+      ...rest,
+      operation,
+      resource,
+      description
+    });
+  }
+}
+
+// Metadata limit errors (specific for 2KB S3 limit)
+export class MetadataLimitError extends S3dbError {
+  constructor(message, details = {}) {
+    const {
+      totalSize,
+      effectiveLimit,
+      absoluteLimit = 2047,
+      excess,
+      resourceName,
+      operation,
+      ...rest
+    } = details;
+
+    let description = details.description;
+    if (!description && totalSize && effectiveLimit) {
+      description = `
+S3 Metadata Size Limit Exceeded
+
+Current Size: ${totalSize} bytes
+Effective Limit: ${effectiveLimit} bytes
+Absolute Limit: ${absoluteLimit} bytes
+${excess ? `Excess: ${excess} bytes` : ''}
+${resourceName ? `Resource: ${resourceName}` : ''}
+${operation ? `Operation: ${operation}` : ''}
+
+S3 has a hard limit of 2KB (2047 bytes) for object metadata.
+
+Solutions:
+1. Use 'body-overflow' behavior to store excess in body
+2. Use 'body-only' behavior to store everything in body
+3. Reduce number of fields
+4. Use shorter field values
+5. Enable advanced metadata encoding
+
+Example:
+  await db.createResource({
+    name: '${resourceName || 'myResource'}',
+    behavior: 'body-overflow',  // Automatically handles overflow
+    attributes: { ... }
+  });
+
+Docs: https://github.com/forattini-dev/s3db.js/blob/main/docs/README.md#metadata-size-limits
+`.trim();
+    }
+
+    super(message, {
+      ...rest,
+      totalSize,
+      effectiveLimit,
+      absoluteLimit,
+      excess,
+      resourceName,
+      operation,
+      description
+    });
   }
 }

package/src/partition-drivers/base-partition-driver.js

@@ -1,4 +1,5 @@
 import { EventEmitter } from 'events';
+import { PartitionDriverError } from '../errors.js';
 
 /**
  * Base class for all partition drivers
@@ -31,7 +32,11 @@ export class BasePartitionDriver extends EventEmitter {
    * @param {Object} operation.data - The data for the operation
    */
   async queue(operation) {
-    throw new Error('queue() must be implemented by subclass');
+    throw new PartitionDriverError('queue() must be implemented by subclass', {
+      driver: this.name || 'BasePartitionDriver',
+      operation: 'queue',
+      suggestion: 'Extend BasePartitionDriver and implement the queue() method'
+    });
   }
 
   /**
@@ -57,7 +62,12 @@ export class BasePartitionDriver extends EventEmitter {
           break;
           
         default:
-          throw new Error(`Unknown partition operation type: ${type}`);
+          throw new PartitionDriverError(`Unknown partition operation type: ${type}`, {
+            driver: this.name || 'BasePartitionDriver',
+            operation: type,
+            availableOperations: ['create', 'update', 'delete'],
+            suggestion: 'Use one of the supported partition operations: create, update, or delete'
+          });
       }
       
       this.stats.processed++;

package/src/partition-drivers/index.js

@@ -1,6 +1,7 @@
 import { SyncPartitionDriver } from './sync-partition-driver.js';
 import { MemoryPartitionDriver } from './memory-partition-driver.js';
 import { SQSPartitionDriver } from './sqs-partition-driver.js';
+import { PartitionDriverError } from '../errors.js';
 
 /**
  * Partition driver factory
@@ -29,7 +30,12 @@ export class PartitionDriverFactory {
     // Get driver class
     const DriverClass = this.drivers[driverName];
     if (!DriverClass) {
-      throw new Error(`Unknown partition driver: ${driverName}. Available: ${Object.keys(this.drivers).join(', ')}`);
+      throw new PartitionDriverError(`Unknown partition driver: ${driverName}`, {
+        driver: driverName,
+        operation: 'create',
+        availableDrivers: Object.keys(this.drivers),
+        suggestion: `Use one of the available drivers: ${Object.keys(this.drivers).join(', ')}, or register a custom driver`
+      });
     }
     
     // Create and initialize driver

package/src/partition-drivers/memory-partition-driver.js

@@ -1,5 +1,6 @@
 import { BasePartitionDriver } from './base-partition-driver.js';
 import { PromisePool } from '@supercharge/promise-pool';
+import { PartitionDriverError } from '../errors.js';
 
 /**
  * In-memory partition driver with background processing
@@ -36,13 +37,19 @@ export class MemoryPartitionDriver extends BasePartitionDriver {
   async queue(operation) {
     // Check queue size limit
     if (this.queue.length >= this.maxQueueSize) {
-      const error = new Error(`Memory queue full (${this.maxQueueSize} items)`);
+      const error = new PartitionDriverError('Memory queue full - backpressure detected', {
+        driver: 'memory',
+        operation: 'queue',
+        queueSize: this.queue.length,
+        maxQueueSize: this.maxQueueSize,
+        suggestion: 'Increase maxQueueSize, enable rejectOnFull, or reduce operation rate'
+      });
       this.emit('queueFull', { operation, queueSize: this.queue.length });
-      
+
       if (this.options.rejectOnFull) {
         throw error;
       }
-      
+
       // Wait for some space
       await this.waitForSpace();
     }
@@ -193,9 +200,17 @@ export class MemoryPartitionDriver extends BasePartitionDriver {
     
     while (this.queue.length >= this.maxQueueSize) {
       if (Date.now() - startTime > maxWait) {
-        throw new Error('Timeout waiting for queue space');
+        throw new PartitionDriverError('Timeout waiting for queue space', {
+          driver: 'memory',
+          operation: 'waitForSpace',
+          queueSize: this.queue.length,
+          maxQueueSize: this.maxQueueSize,
+          waitedMs: Date.now() - startTime,
+          maxWaitMs: maxWait,
+          suggestion: 'Queue is full and not draining fast enough. Increase maxQueueSize or concurrency'
+        });
       }
-      
+
       await new Promise(resolve => setTimeout(resolve, checkInterval));
     }
   }

package/src/partition-drivers/sqs-partition-driver.js

@@ -1,5 +1,6 @@
 import { BasePartitionDriver } from './base-partition-driver.js';
 import { SQSClient, SendMessageCommand, ReceiveMessageCommand, DeleteMessageCommand } from '@aws-sdk/client-sqs';
+import { PartitionDriverError } from '../errors.js';
 
 /**
  * SQS-based partition driver for distributed processing
@@ -14,7 +15,11 @@ export class SQSPartitionDriver extends BasePartitionDriver {
     // SQS Configuration
     this.queueUrl = options.queueUrl;
     if (!this.queueUrl) {
-      throw new Error('SQS queue URL is required for SQSPartitionDriver');
+      throw new PartitionDriverError('SQS queue URL is required', {
+        driver: 'sqs',
+        operation: 'constructor',
+        suggestion: 'Provide queueUrl in options: new SQSPartitionDriver({ queueUrl: "https://sqs.region.amazonaws.com/account/queue" })'
+      });
     }
     
     this.region = options.region || 'us-east-1';

package/src/plugins/audit.errors.js

@@ -0,0 +1,46 @@
+import { S3dbError } from '../errors.js';
+
+/**
+ * AuditError - Errors related to audit logging operations
+ *
+ * Used for audit operations including:
+ * - Audit log creation
+ * - Change tracking
+ * - Audit query and retrieval
+ * - Compliance logging
+ * - Event recording
+ *
+ * @extends S3dbError
+ */
+export class AuditError extends S3dbError {
+  constructor(message, details = {}) {
+    const { resourceName, operation = 'unknown', auditId, ...rest } = details;
+
+    let description = details.description;
+    if (!description) {
+      description = `
+Audit Operation Error
+
+Operation: ${operation}
+${resourceName ? `Resource: ${resourceName}` : ''}
+${auditId ? `Audit ID: ${auditId}` : ''}
+
+Common causes:
+1. Audit log storage not accessible
+2. Resource not configured for auditing
+3. Invalid audit log format
+4. Audit query failed
+5. Insufficient permissions
+
+Solution:
+Check audit plugin configuration and storage accessibility.
+
+Docs: https://github.com/forattini-dev/s3db.js/blob/main/docs/plugins/audit.md
+`.trim();
+    }
+
+    super(message, { ...rest, resourceName, operation, auditId, description });
+  }
+}
+
+export default AuditError;