s3db.js 11.2.3 → 11.2.4

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/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;