s3db.js 11.2.3 → 11.2.4

package/src/plugins/metrics.errors.js

@@ -0,0 +1,46 @@
+import { S3dbError } from '../errors.js';
+
+/**
+ * MetricsError - Errors related to metrics operations
+ *
+ * Used for metrics operations including:
+ * - Metric collection and recording
+ * - Metric aggregation
+ * - Metric querying
+ * - Performance tracking
+ * - Statistics computation
+ *
+ * @extends S3dbError
+ */
+export class MetricsError extends S3dbError {
+  constructor(message, details = {}) {
+    const { metricName, operation = 'unknown', resourceName, ...rest } = details;
+
+    let description = details.description;
+    if (!description) {
+      description = `
+Metrics Operation Error
+
+Operation: ${operation}
+${metricName ? `Metric: ${metricName}` : ''}
+${resourceName ? `Resource: ${resourceName}` : ''}
+
+Common causes:
+1. Metric not configured
+2. Invalid metric value or type
+3. Metrics storage not accessible
+4. Aggregation function error
+5. Query parameters invalid
+
+Solution:
+Check metrics configuration and ensure proper initialization.
+
+Docs: https://github.com/forattini-dev/s3db.js/blob/main/docs/plugins/metrics.md
+`.trim();
+    }
+
+    super(message, { ...rest, metricName, operation, resourceName, description });
+  }
+}
+
+export default MetricsError;

package/src/plugins/queue-consumer.plugin.js

@@ -1,6 +1,7 @@
 import { Plugin } from './plugin.class.js';
 import { createConsumer } from './consumers/index.js';
 import tryFn from "../concerns/try-fn.js";
+import { QueueError } from "./queue.errors.js";
 
 // Example configuration for SQS:
 // const plugin = new QueueConsumerPlugin({
@@ -101,13 +102,32 @@ export class QueueConsumerPlugin extends Plugin {
 
     
     if (!resource) {
-      throw new Error('QueueConsumerPlugin: resource not found in message');
+      throw new QueueError('Resource not found in message', {
+        operation: 'handleMessage',
+        queueName: configuredResource,
+        messageBody: body,
+        suggestion: 'Ensure message includes a "resource" field specifying the target resource name'
+      });
     }
     if (!action) {
-      throw new Error('QueueConsumerPlugin: action not found in message');
+      throw new QueueError('Action not found in message', {
+        operation: 'handleMessage',
+        queueName: configuredResource,
+        resource,
+        messageBody: body,
+        suggestion: 'Ensure message includes an "action" field (insert, update, or delete)'
+      });
     }
     const resourceObj = this.database.resources[resource];
-    if (!resourceObj) throw new Error(`QueueConsumerPlugin: resource '${resource}' not found`);
+    if (!resourceObj) {
+      throw new QueueError(`Resource '${resource}' not found`, {
+        operation: 'handleMessage',
+        queueName: configuredResource,
+        resource,
+        availableResources: Object.keys(this.database.resources),
+        suggestion: 'Check resource name or ensure resource is created before consuming messages'
+      });
+    }
     
     let result;
     const [ok, err, res] = await tryFn(async () => {
@@ -119,7 +139,14 @@ export class QueueConsumerPlugin extends Plugin {
       } else if (action === 'delete') {
         result = await resourceObj.delete(data.id);
       } else {
-        throw new Error(`QueueConsumerPlugin: unsupported action '${action}'`);
+        throw new QueueError(`Unsupported action '${action}'`, {
+          operation: 'handleMessage',
+          queueName: configuredResource,
+          resource,
+          action,
+          supportedActions: ['insert', 'update', 'delete'],
+          suggestion: 'Use one of the supported actions: insert, update, or delete'
+        });
       }
       return result;
     });

package/src/plugins/queue.errors.js

@@ -0,0 +1,46 @@
+import { S3dbError } from '../errors.js';
+
+/**
+ * QueueError - Errors related to queue operations
+ *
+ * Used for queue operations including:
+ * - Message enqueueing and dequeueing
+ * - Queue consumer registration
+ * - Message processing
+ * - Dead letter queue handling
+ * - Queue configuration and management
+ *
+ * @extends S3dbError
+ */
+export class QueueError extends S3dbError {
+  constructor(message, details = {}) {
+    const { queueName, operation = 'unknown', messageId, ...rest } = details;
+
+    let description = details.description;
+    if (!description) {
+      description = `
+Queue Operation Error
+
+Operation: ${operation}
+${queueName ? `Queue: ${queueName}` : ''}
+${messageId ? `Message ID: ${messageId}` : ''}
+
+Common causes:
+1. Queue not properly configured
+2. Message handler not registered
+3. Queue resource not found
+4. SQS/RabbitMQ connection failed
+5. Message processing timeout
+
+Solution:
+Check queue configuration and message handler registration.
+
+Docs: https://github.com/forattini-dev/s3db.js/blob/main/docs/plugins/queue.md
+`.trim();
+    }
+
+    super(message, { ...rest, queueName, operation, messageId, description });
+  }
+}
+
+export default QueueError;

package/src/plugins/replicator.errors.js

@@ -0,0 +1,46 @@
+import { S3dbError } from '../errors.js';
+
+/**
+ * ReplicationError - Errors related to replication operations
+ *
+ * Used for replicator operations including:
+ * - Replicator initialization and setup
+ * - Data replication to target systems
+ * - Resource mapping and transformation
+ * - Connection management
+ * - Batch replication operations
+ *
+ * @extends S3dbError
+ */
+export class ReplicationError extends S3dbError {
+  constructor(message, details = {}) {
+    const { replicatorClass = 'unknown', operation = 'unknown', resourceName, ...rest } = details;
+
+    let description = details.description;
+    if (!description) {
+      description = `
+Replication Operation Error
+
+Replicator: ${replicatorClass}
+Operation: ${operation}
+${resourceName ? `Resource: ${resourceName}` : ''}
+
+Common causes:
+1. Invalid replicator configuration
+2. Target system not accessible
+3. Resource not configured for replication
+4. Invalid operation type
+5. Transformation function errors
+
+Solution:
+Check replicator configuration and ensure target system is accessible.
+
+Docs: https://github.com/forattini-dev/s3db.js/blob/main/docs/plugins/replicator.md
+`.trim();
+    }
+
+    super(message, { ...rest, replicatorClass, operation, resourceName, description });
+  }
+}
+
+export default ReplicationError;

package/src/plugins/replicator.plugin.js

@@ -1,6 +1,7 @@
 import Plugin from "./plugin.class.js";
 import tryFn from "../concerns/try-fn.js";
 import { createReplicator, validateReplicatorConfig } from "./replicators/index.js";
+import { ReplicationError } from "./replicator.errors.js";
 
 function normalizeResourceName(name) {
   return typeof name === 'string' ? name.trim().toLowerCase() : name;
@@ -120,12 +121,40 @@ export class ReplicatorPlugin extends Plugin {
     super();
     // Validation for config tests
     if (!options.replicators || !Array.isArray(options.replicators)) {
-      throw new Error('ReplicatorPlugin: replicators array is required');
+      throw new ReplicationError('ReplicatorPlugin requires replicators array', {
+        operation: 'constructor',
+        pluginName: 'ReplicatorPlugin',
+        providedOptions: Object.keys(options),
+        suggestion: 'Provide replicators array: new ReplicatorPlugin({ replicators: [{ driver: "s3db", resources: [...] }] })'
+      });
     }
     for (const rep of options.replicators) {
-      if (!rep.driver) throw new Error('ReplicatorPlugin: each replicator must have a driver');
-      if (!rep.resources || typeof rep.resources !== 'object') throw new Error('ReplicatorPlugin: each replicator must have resources config');
-      if (Object.keys(rep.resources).length === 0) throw new Error('ReplicatorPlugin: each replicator must have at least one resource configured');
+      if (!rep.driver) {
+        throw new ReplicationError('Each replicator must have a driver', {
+          operation: 'constructor',
+          pluginName: 'ReplicatorPlugin',
+          replicatorConfig: rep,
+          suggestion: 'Each replicator entry must specify a driver: { driver: "s3db", resources: {...} }'
+        });
+      }
+      if (!rep.resources || typeof rep.resources !== 'object') {
+        throw new ReplicationError('Each replicator must have resources config', {
+          operation: 'constructor',
+          pluginName: 'ReplicatorPlugin',
+          driver: rep.driver,
+          replicatorConfig: rep,
+          suggestion: 'Provide resources as object or array: { driver: "s3db", resources: ["users"] } or { resources: { users: "people" } }'
+        });
+      }
+      if (Object.keys(rep.resources).length === 0) {
+        throw new ReplicationError('Each replicator must have at least one resource configured', {
+          operation: 'constructor',
+          pluginName: 'ReplicatorPlugin',
+          driver: rep.driver,
+          replicatorConfig: rep,
+          suggestion: 'Add at least one resource to replicate: { driver: "s3db", resources: ["users"] }'
+        });
+      }
     }
     
     this.config = {
@@ -657,7 +686,13 @@ export class ReplicatorPlugin extends Plugin {
   async syncAllData(replicatorId) {
     const replicator = this.replicators.find(r => r.id === replicatorId);
     if (!replicator) {
-      throw new Error(`Replicator not found: ${replicatorId}`);
+      throw new ReplicationError('Replicator not found', {
+        operation: 'syncAllData',
+        pluginName: 'ReplicatorPlugin',
+        replicatorId,
+        availableReplicators: this.replicators.map(r => r.id),
+        suggestion: 'Check replicator ID or use getReplicatorStats() to list available replicators'
+      });
     }
 
     this.stats.lastSync = new Date().toISOString();

package/src/plugins/replicators/base-replicator.class.js

@@ -1,4 +1,5 @@
 import EventEmitter from 'events';
+import { ReplicationError } from '../replicator.errors.js';
 
 /**
  * Base class for all replicator drivers
@@ -31,7 +32,12 @@ export class BaseReplicator extends EventEmitter {
    * @returns {Promise<Object>} replicator result
    */
   async replicate(resourceName, operation, data, id) {
-    throw new Error(`replicate() method must be implemented by ${this.name}`);
+    throw new ReplicationError('replicate() method must be implemented by subclass', {
+      operation: 'replicate',
+      replicatorClass: this.name,
+      resourceName,
+      suggestion: 'Extend BaseReplicator and implement the replicate() method'
+    });
   }
 
   /**
@@ -41,7 +47,13 @@ export class BaseReplicator extends EventEmitter {
    * @returns {Promise<Object>} Batch replicator result
    */
   async replicateBatch(resourceName, records) {
-    throw new Error(`replicateBatch() method must be implemented by ${this.name}`);
+    throw new ReplicationError('replicateBatch() method must be implemented by subclass', {
+      operation: 'replicateBatch',
+      replicatorClass: this.name,
+      resourceName,
+      batchSize: records?.length,
+      suggestion: 'Extend BaseReplicator and implement the replicateBatch() method'
+    });
   }
 
   /**
@@ -49,7 +61,11 @@ export class BaseReplicator extends EventEmitter {
    * @returns {Promise<boolean>} True if connection is successful
    */
   async testConnection() {
-    throw new Error(`testConnection() method must be implemented by ${this.name}`);
+    throw new ReplicationError('testConnection() method must be implemented by subclass', {
+      operation: 'testConnection',
+      replicatorClass: this.name,
+      suggestion: 'Extend BaseReplicator and implement the testConnection() method'
+    });
   }
 
   /**

package/src/plugins/replicators/index.js

@@ -3,6 +3,7 @@ import BigqueryReplicator from './bigquery-replicator.class.js';
 import PostgresReplicator from './postgres-replicator.class.js';
 import S3dbReplicator from './s3db-replicator.class.js';
 import SqsReplicator from './sqs-replicator.class.js';
+import { ReplicationError } from '../replicator.errors.js';
 
 export { BaseReplicator, BigqueryReplicator, PostgresReplicator, S3dbReplicator, SqsReplicator };
 
@@ -24,11 +25,16 @@ export const REPLICATOR_DRIVERS = {
  */
 export function createReplicator(driver, config = {}, resources = [], client = null) {
   const ReplicatorClass = REPLICATOR_DRIVERS[driver];
-  
+
   if (!ReplicatorClass) {
-    throw new Error(`Unknown replicator driver: ${driver}. Available drivers: ${Object.keys(REPLICATOR_DRIVERS).join(', ')}`);
+    throw new ReplicationError(`Unknown replicator driver: ${driver}`, {
+      operation: 'createReplicator',
+      driver,
+      availableDrivers: Object.keys(REPLICATOR_DRIVERS),
+      suggestion: `Use one of the available drivers: ${Object.keys(REPLICATOR_DRIVERS).join(', ')}`
+    });
   }
-  
+
   return new ReplicatorClass(config, resources, client);
 }
 

package/src/plugins/replicators/s3db-replicator.class.js

@@ -1,6 +1,7 @@
 import tryFn from "#src/concerns/try-fn.js";
 import { S3db } from '#src/database.class.js';
 import BaseReplicator from './base-replicator.class.js';
+import { ReplicationError } from '../replicator.errors.js';
 
 function normalizeResourceName(name) {
   return typeof name === 'string' ? name.trim().toLowerCase() : name;
@@ -118,7 +119,11 @@ class S3dbReplicator extends BaseReplicator {
         this.targetDatabase = new S3db(targetConfig);
         await this.targetDatabase.connect();
       } else {
-        throw new Error('S3dbReplicator: No client or connectionString provided');
+        throw new ReplicationError('S3dbReplicator requires client or connectionString', {
+          operation: 'initialize',
+          replicatorClass: 'S3dbReplicator',
+          suggestion: 'Provide either a client instance or connectionString in config: { client: db } or { connectionString: "s3://..." }'
+        });
       }
       
       this.emit('connected', { 
@@ -155,9 +160,15 @@ class S3dbReplicator extends BaseReplicator {
     
     const normResource = normalizeResourceName(resource);
     const entry = this.resourcesMap[normResource];
-    
+
     if (!entry) {
-      throw new Error(`[S3dbReplicator] Resource not configured: ${resource}`);
+      throw new ReplicationError('Resource not configured for replication', {
+        operation: 'replicate',
+        replicatorClass: 'S3dbReplicator',
+        resourceName: resource,
+        configuredResources: Object.keys(this.resourcesMap),
+        suggestion: 'Add resource to replicator resources map: { resources: { [resourceName]: "destination" } }'
+      });
     }
 
     // Handle multi-destination arrays
@@ -242,7 +253,14 @@ class S3dbReplicator extends BaseReplicator {
     } else if (operation === 'delete') {
       result = await destResourceObj.delete(recordId);
     } else {
-      throw new Error(`Invalid operation: ${operation}. Supported operations are: insert, update, delete`);
+      throw new ReplicationError(`Invalid replication operation: ${operation}`, {
+        operation: 'replicate',
+        replicatorClass: 'S3dbReplicator',
+        invalidOperation: operation,
+        supportedOperations: ['insert', 'update', 'delete'],
+        resourceName: sourceResource,
+        suggestion: 'Use one of the supported operations: insert, update, delete'
+      });
     }
     
     return result;
@@ -333,7 +351,13 @@ class S3dbReplicator extends BaseReplicator {
     const norm = normalizeResourceName(resource);
     const found = available.find(r => normalizeResourceName(r) === norm);
     if (!found) {
-      throw new Error(`[S3dbReplicator] Destination resource not found: ${resource}. Available: ${available.join(', ')}`);
+      throw new ReplicationError('Destination resource not found in target database', {
+        operation: '_getDestResourceObj',
+        replicatorClass: 'S3dbReplicator',
+        destinationResource: resource,
+        availableResources: available,
+        suggestion: 'Create the resource in target database or check resource name spelling'
+      });
     }
     return db.resources[found];
   }
@@ -390,13 +414,19 @@ class S3dbReplicator extends BaseReplicator {
 
   async testConnection() {
     const [ok, err] = await tryFn(async () => {
-      if (!this.targetDatabase) throw new Error('No target database configured');
-      
+      if (!this.targetDatabase) {
+        throw new ReplicationError('No target database configured for connection test', {
+          operation: 'testConnection',
+          replicatorClass: 'S3dbReplicator',
+          suggestion: 'Initialize replicator with client or connectionString before testing connection'
+        });
+      }
+
       // Try to list resources to test connection
       if (typeof this.targetDatabase.connect === 'function') {
         await this.targetDatabase.connect();
       }
-      
+
       return true;
     });
     

package/src/plugins/scheduler.errors.js

@@ -0,0 +1,46 @@
+import { S3dbError } from '../errors.js';
+
+/**
+ * SchedulerError - Errors related to scheduler operations
+ *
+ * Used for scheduled task operations including:
+ * - Task creation and scheduling
+ * - Cron expression validation
+ * - Task execution and retries
+ * - Job queue management
+ * - Scheduler lifecycle management
+ *
+ * @extends S3dbError
+ */
+export class SchedulerError extends S3dbError {
+  constructor(message, details = {}) {
+    const { taskId, operation = 'unknown', cronExpression, ...rest } = details;
+
+    let description = details.description;
+    if (!description) {
+      description = `
+Scheduler Operation Error
+
+Operation: ${operation}
+${taskId ? `Task ID: ${taskId}` : ''}
+${cronExpression ? `Cron: ${cronExpression}` : ''}
+
+Common causes:
+1. Invalid cron expression format
+2. Task not found or already exists
+3. Scheduler not properly initialized
+4. Job execution failure
+5. Resource conflicts
+
+Solution:
+Check task configuration and ensure scheduler is properly initialized.
+
+Docs: https://github.com/forattini-dev/s3db.js/blob/main/docs/plugins/scheduler.md
+`.trim();
+    }
+
+    super(message, { ...rest, taskId, operation, cronExpression, description });
+  }
+}
+
+export default SchedulerError;

package/src/plugins/scheduler.plugin.js

@@ -1,6 +1,7 @@
 import Plugin from "./plugin.class.js";
 import tryFn from "../concerns/try-fn.js";
 import { idGenerator } from "../concerns/id.js";
+import { SchedulerError } from "./scheduler.errors.js";
 
 /**
  * SchedulerPlugin - Cron-based Task Scheduling System
@@ -183,21 +184,40 @@ export class SchedulerPlugin extends Plugin {
 
   _validateConfiguration() {
     if (Object.keys(this.config.jobs).length === 0) {
-      throw new Error('SchedulerPlugin: At least one job must be defined');
+      throw new SchedulerError('At least one job must be defined', {
+        operation: 'validateConfiguration',
+        jobCount: 0,
+        suggestion: 'Provide at least one job in the jobs configuration: { jobs: { myJob: { schedule: "* * * * *", action: async () => {...} } } }'
+      });
     }
-    
+
     for (const [jobName, job] of Object.entries(this.config.jobs)) {
       if (!job.schedule) {
-        throw new Error(`SchedulerPlugin: Job '${jobName}' must have a schedule`);
+        throw new SchedulerError(`Job '${jobName}' must have a schedule`, {
+          operation: 'validateConfiguration',
+          taskId: jobName,
+          providedConfig: Object.keys(job),
+          suggestion: 'Add a schedule property with a valid cron expression: { schedule: "0 * * * *", action: async () => {...} }'
+        });
       }
-      
+
       if (!job.action || typeof job.action !== 'function') {
-        throw new Error(`SchedulerPlugin: Job '${jobName}' must have an action function`);
+        throw new SchedulerError(`Job '${jobName}' must have an action function`, {
+          operation: 'validateConfiguration',
+          taskId: jobName,
+          actionType: typeof job.action,
+          suggestion: 'Provide an action function: { schedule: "...", action: async (db, ctx) => {...} }'
+        });
       }
-      
+
       // Validate cron expression
       if (!this._isValidCronExpression(job.schedule)) {
-        throw new Error(`SchedulerPlugin: Job '${jobName}' has invalid cron expression: ${job.schedule}`);
+        throw new SchedulerError(`Job '${jobName}' has invalid cron expression`, {
+          operation: 'validateConfiguration',
+          taskId: jobName,
+          cronExpression: job.schedule,
+          suggestion: 'Use valid cron format (5 fields: minute hour day month weekday) or shortcuts (@hourly, @daily, @weekly, @monthly, @yearly)'
+        });
       }
     }
   }
@@ -592,11 +612,21 @@ export class SchedulerPlugin extends Plugin {
   async runJob(jobName, context = {}) {
     const job = this.jobs.get(jobName);
     if (!job) {
-      throw new Error(`Job '${jobName}' not found`);
+      throw new SchedulerError(`Job '${jobName}' not found`, {
+        operation: 'runJob',
+        taskId: jobName,
+        availableJobs: Array.from(this.jobs.keys()),
+        suggestion: 'Check job name or use getAllJobsStatus() to list available jobs'
+      });
     }
 
     if (this.activeJobs.has(jobName)) {
-      throw new Error(`Job '${jobName}' is already running`);
+      throw new SchedulerError(`Job '${jobName}' is already running`, {
+        operation: 'runJob',
+        taskId: jobName,
+        executionId: this.activeJobs.get(jobName),
+        suggestion: 'Wait for current execution to complete or check job status with getJobStatus()'
+      });
     }
 
     await this._executeJob(jobName);
@@ -608,12 +638,17 @@ export class SchedulerPlugin extends Plugin {
   enableJob(jobName) {
     const job = this.jobs.get(jobName);
     if (!job) {
-      throw new Error(`Job '${jobName}' not found`);
+      throw new SchedulerError(`Job '${jobName}' not found`, {
+        operation: 'enableJob',
+        taskId: jobName,
+        availableJobs: Array.from(this.jobs.keys()),
+        suggestion: 'Check job name or use getAllJobsStatus() to list available jobs'
+      });
     }
-    
+
     job.enabled = true;
     this._scheduleNextExecution(jobName);
-    
+
     this.emit('job_enabled', { jobName });
   }
 
@@ -623,7 +658,12 @@ export class SchedulerPlugin extends Plugin {
   disableJob(jobName) {
     const job = this.jobs.get(jobName);
     if (!job) {
-      throw new Error(`Job '${jobName}' not found`);
+      throw new SchedulerError(`Job '${jobName}' not found`, {
+        operation: 'disableJob',
+        taskId: jobName,
+        availableJobs: Array.from(this.jobs.keys()),
+        suggestion: 'Check job name or use getAllJobsStatus() to list available jobs'
+      });
     }
     
     job.enabled = false;
@@ -743,16 +783,31 @@ export class SchedulerPlugin extends Plugin {
    */
   addJob(jobName, jobConfig) {
     if (this.jobs.has(jobName)) {
-      throw new Error(`Job '${jobName}' already exists`);
+      throw new SchedulerError(`Job '${jobName}' already exists`, {
+        operation: 'addJob',
+        taskId: jobName,
+        existingJobs: Array.from(this.jobs.keys()),
+        suggestion: 'Use a different job name or remove the existing job first with removeJob()'
+      });
     }
-    
+
     // Validate job configuration
     if (!jobConfig.schedule || !jobConfig.action) {
-      throw new Error('Job must have schedule and action');
+      throw new SchedulerError('Job must have schedule and action', {
+        operation: 'addJob',
+        taskId: jobName,
+        providedConfig: Object.keys(jobConfig),
+        suggestion: 'Provide both schedule and action: { schedule: "0 * * * *", action: async (db, ctx) => {...} }'
+      });
     }
-    
+
     if (!this._isValidCronExpression(jobConfig.schedule)) {
-      throw new Error(`Invalid cron expression: ${jobConfig.schedule}`);
+      throw new SchedulerError('Invalid cron expression', {
+        operation: 'addJob',
+        taskId: jobName,
+        cronExpression: jobConfig.schedule,
+        suggestion: 'Use valid cron format (5 fields) or shortcuts (@hourly, @daily, @weekly, @monthly, @yearly)'
+      });
     }
     
     const job = {
@@ -791,7 +846,12 @@ export class SchedulerPlugin extends Plugin {
   removeJob(jobName) {
     const job = this.jobs.get(jobName);
     if (!job) {
-      throw new Error(`Job '${jobName}' not found`);
+      throw new SchedulerError(`Job '${jobName}' not found`, {
+        operation: 'removeJob',
+        taskId: jobName,
+        availableJobs: Array.from(this.jobs.keys()),
+        suggestion: 'Check job name or use getAllJobsStatus() to list available jobs'
+      });
     }
     
     // Cancel scheduled execution