s3db.js 11.2.2 → 11.2.4

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

package/src/plugins/state-machine.errors.js

@@ -0,0 +1,47 @@
+import { S3dbError } from '../errors.js';
+
+/**
+ * StateMachineError - Errors related to state machine operations
+ *
+ * Used for state machine operations including:
+ * - State transitions
+ * - State validation
+ * - Transition conditions
+ * - State machine configuration
+ * - Workflow execution
+ *
+ * @extends S3dbError
+ */
+export class StateMachineError extends S3dbError {
+  constructor(message, details = {}) {
+    const { currentState, targetState, resourceName, operation = 'unknown', ...rest } = details;
+
+    let description = details.description;
+    if (!description) {
+      description = `
+State Machine Operation Error
+
+Operation: ${operation}
+${currentState ? `Current State: ${currentState}` : ''}
+${targetState ? `Target State: ${targetState}` : ''}
+${resourceName ? `Resource: ${resourceName}` : ''}
+
+Common causes:
+1. Invalid state transition
+2. State machine not configured
+3. Transition conditions not met
+4. State not defined in configuration
+5. Missing transition handler
+
+Solution:
+Check state machine configuration and valid transitions.
+
+Docs: https://github.com/forattini-dev/s3db.js/blob/main/docs/plugins/state-machine.md
+`.trim();
+    }
+
+    super(message, { ...rest, currentState, targetState, resourceName, operation, description });
+  }
+}
+
+export default StateMachineError;

package/src/plugins/state-machine.plugin.js

@@ -1,5 +1,6 @@
 import Plugin from "./plugin.class.js";
 import tryFn from "../concerns/try-fn.js";
+import { StateMachineError } from "./state-machine.errors.js";
 
 /**
  * StateMachinePlugin - Finite State Machine Management
@@ -120,20 +121,39 @@ export class StateMachinePlugin extends Plugin {
 
   _validateConfiguration() {
     if (!this.config.stateMachines || Object.keys(this.config.stateMachines).length === 0) {
-      throw new Error('StateMachinePlugin: At least one state machine must be defined');
+      throw new StateMachineError('At least one state machine must be defined', {
+        operation: 'validateConfiguration',
+        machineCount: 0,
+        suggestion: 'Provide at least one state machine in the stateMachines configuration'
+      });
     }
     
     for (const [machineName, machine] of Object.entries(this.config.stateMachines)) {
       if (!machine.states || Object.keys(machine.states).length === 0) {
-        throw new Error(`StateMachinePlugin: Machine '${machineName}' must have states defined`);
+        throw new StateMachineError(`Machine '${machineName}' must have states defined`, {
+          operation: 'validateConfiguration',
+          machineId: machineName,
+          suggestion: 'Define at least one state in the states configuration'
+        });
       }
-      
+
       if (!machine.initialState) {
-        throw new Error(`StateMachinePlugin: Machine '${machineName}' must have an initialState`);
+        throw new StateMachineError(`Machine '${machineName}' must have an initialState`, {
+          operation: 'validateConfiguration',
+          machineId: machineName,
+          availableStates: Object.keys(machine.states),
+          suggestion: 'Specify an initialState property matching one of the defined states'
+        });
       }
-      
+
       if (!machine.states[machine.initialState]) {
-        throw new Error(`StateMachinePlugin: Initial state '${machine.initialState}' not found in machine '${machineName}'`);
+        throw new StateMachineError(`Initial state '${machine.initialState}' not found in machine '${machineName}'`, {
+          operation: 'validateConfiguration',
+          machineId: machineName,
+          initialState: machine.initialState,
+          availableStates: Object.keys(machine.states),
+          suggestion: 'Set initialState to one of the defined states'
+        });
       }
     }
   }
@@ -200,14 +220,27 @@ export class StateMachinePlugin extends Plugin {
   async send(machineId, entityId, event, context = {}) {
     const machine = this.machines.get(machineId);
     if (!machine) {
-      throw new Error(`State machine '${machineId}' not found`);
+      throw new StateMachineError(`State machine '${machineId}' not found`, {
+        operation: 'send',
+        machineId,
+        availableMachines: Array.from(this.machines.keys()),
+        suggestion: 'Check machine ID or use getMachines() to list available machines'
+      });
     }
     
     const currentState = await this.getState(machineId, entityId);
     const stateConfig = machine.config.states[currentState];
-    
+
     if (!stateConfig || !stateConfig.on || !stateConfig.on[event]) {
-      throw new Error(`Event '${event}' not valid for state '${currentState}' in machine '${machineId}'`);
+      throw new StateMachineError(`Event '${event}' not valid for state '${currentState}' in machine '${machineId}'`, {
+        operation: 'send',
+        machineId,
+        entityId,
+        event,
+        currentState,
+        validEvents: stateConfig && stateConfig.on ? Object.keys(stateConfig.on) : [],
+        suggestion: 'Use getValidEvents() to check which events are valid for the current state'
+      });
     }
     
     const targetState = stateConfig.on[event];
@@ -218,12 +251,21 @@ export class StateMachinePlugin extends Plugin {
       const guard = this.config.guards[guardName];
       
       if (guard) {
-        const [guardOk, guardErr, guardResult] = await tryFn(() => 
+        const [guardOk, guardErr, guardResult] = await tryFn(() =>
           guard(context, event, { database: this.database, machineId, entityId })
         );
-        
+
         if (!guardOk || !guardResult) {
-          throw new Error(`Transition blocked by guard '${guardName}': ${guardErr?.message || 'Guard returned false'}`);
+          throw new StateMachineError(`Transition blocked by guard '${guardName}'`, {
+            operation: 'send',
+            machineId,
+            entityId,
+            event,
+            currentState,
+            guardName,
+            guardError: guardErr?.message || 'Guard returned false',
+            suggestion: 'Check guard conditions or modify the context to satisfy guard requirements'
+          });
         }
       }
     }
@@ -363,7 +405,12 @@ export class StateMachinePlugin extends Plugin {
   async getState(machineId, entityId) {
     const machine = this.machines.get(machineId);
     if (!machine) {
-      throw new Error(`State machine '${machineId}' not found`);
+      throw new StateMachineError(`State machine '${machineId}' not found`, {
+        operation: 'getState',
+        machineId,
+        availableMachines: Array.from(this.machines.keys()),
+        suggestion: 'Check machine ID or use getMachines() to list available machines'
+      });
     }
     
     // Check in-memory cache first
@@ -397,7 +444,12 @@ export class StateMachinePlugin extends Plugin {
   async getValidEvents(machineId, stateOrEntityId) {
     const machine = this.machines.get(machineId);
     if (!machine) {
-      throw new Error(`State machine '${machineId}' not found`);
+      throw new StateMachineError(`State machine '${machineId}' not found`, {
+        operation: 'getValidEvents',
+        machineId,
+        availableMachines: Array.from(this.machines.keys()),
+        suggestion: 'Check machine ID or use getMachines() to list available machines'
+      });
     }
 
     let state;
@@ -458,7 +510,12 @@ export class StateMachinePlugin extends Plugin {
   async initializeEntity(machineId, entityId, context = {}) {
     const machine = this.machines.get(machineId);
     if (!machine) {
-      throw new Error(`State machine '${machineId}' not found`);
+      throw new StateMachineError(`State machine '${machineId}' not found`, {
+        operation: 'initializeEntity',
+        machineId,
+        availableMachines: Array.from(this.machines.keys()),
+        suggestion: 'Check machine ID or use getMachines() to list available machines'
+      });
     }
 
     const initialState = machine.config.initialState;
@@ -483,7 +540,14 @@ export class StateMachinePlugin extends Plugin {
 
       // Only throw if error is NOT "already exists"
       if (!ok && err && !err.message?.includes('already exists')) {
-        throw new Error(`Failed to initialize entity state: ${err.message}`);
+        throw new StateMachineError('Failed to initialize entity state', {
+          operation: 'initializeEntity',
+          machineId,
+          entityId,
+          initialState,
+          original: err,
+          suggestion: 'Check state resource configuration and database permissions'
+        });
       }
     }
 
@@ -519,7 +583,12 @@ export class StateMachinePlugin extends Plugin {
   visualize(machineId) {
     const machine = this.machines.get(machineId);
     if (!machine) {
-      throw new Error(`State machine '${machineId}' not found`);
+      throw new StateMachineError(`State machine '${machineId}' not found`, {
+        operation: 'visualize',
+        machineId,
+        availableMachines: Array.from(this.machines.keys()),
+        suggestion: 'Check machine ID or use getMachines() to list available machines'
+      });
     }
     
     let dot = `digraph ${machineId} {\n`;

package/src/resource.class.js

@@ -134,6 +134,7 @@ export class Resource extends AsyncEventEmitter {
       idGenerator: customIdGenerator,
       idSize = 22,
       versioningEnabled = false,
+      strictValidation = true,
       events = {},
       asyncEvents = true,
       asyncPartitions = true,
@@ -149,6 +150,7 @@ export class Resource extends AsyncEventEmitter {
     this.parallelism = parallelism;
     this.passphrase = passphrase ?? 'secret';
     this.versioningEnabled = versioningEnabled;
+    this.strictValidation = strictValidation;
     
     // Configure async events mode
     this.setAsyncMode(asyncEvents);
@@ -476,9 +478,14 @@ export class Resource extends AsyncEventEmitter {
 
   /**
    * Validate that all partition fields exist in current resource attributes
-   * @throws {Error} If partition fields don't exist in current schema
+   * @throws {Error} If partition fields don't exist in current schema (only when strictValidation is true)
    */
   validatePartitions() {
+    // Skip validation if strictValidation is disabled
+    if (!this.strictValidation) {
+      return;
+    }
+
     if (!this.config.partitions) {
       return; // No partitions to validate
     }

package/src/stream/index.js

@@ -3,10 +3,15 @@ export * from "./resource-writer.class.js"
 export * from "./resource-ids-reader.class.js"
 export * from "./resource-ids-page-reader.class.js"
 
+import { StreamError } from '../errors.js';
+
 export function streamToString(stream) {
   return new Promise((resolve, reject) => {
     if (!stream) {
-      return reject(new Error('streamToString: stream is undefined'));
+      return reject(new StreamError('Stream is undefined', {
+        operation: 'streamToString',
+        suggestion: 'Ensure a valid stream is passed to streamToString()'
+      }));
     }
     const chunks = [];
     stream.on('data', (chunk) => chunks.push(chunk));

package/src/stream/resource-reader.class.js

@@ -4,13 +4,18 @@ import { PromisePool } from "@supercharge/promise-pool";
 
 import { ResourceIdsPageReader } from "./resource-ids-page-reader.class.js"
 import tryFn from "../concerns/try-fn.js";
+import { StreamError } from '../errors.js';
 
 export class ResourceReader extends EventEmitter {
   constructor({ resource, batchSize = 10, concurrency = 5 }) {
     super()
 
     if (!resource) {
-      throw new Error("Resource is required for ResourceReader");
+      throw new StreamError('Resource is required for ResourceReader', {
+        operation: 'constructor',
+        resource: resource?.name,
+        suggestion: 'Pass a valid Resource instance when creating ResourceReader'
+      });
     }
 
     this.resource = resource;