codehooks-js 1.3.7 → 1.3.9

package/workflow/engine.mjs

@@ -1,40 +1,76 @@
 /*
-Implements a steps engine that uses Codehooks.io as the state storage and queues for persistent workers.
-The engine manages step transitions, state persistence, and event handling for step-based workflows.
+Implements a workflow engine that uses Codehooks.io as the state storage and queues for persistent workers.
+The engine manages step transitions, state persistence, and event handling for workflow-based applications.
 */
 
 import { EventEmitter } from 'events';
 
 /**
- * StepsEngine class that manages step-based workflows
+ * Workflow class that manages step-based workflows
  * @extends EventEmitter
  */
-class StepsEngine extends EventEmitter {
+class Workflow extends EventEmitter {
+
+    // Protected instance variables
+    #collectionName = 'workflowdata'; // collection name for storing workflow data
+    #queuePrefix = 'workflowqueue'; // queue prefix for storing workflow data
+    #timeout = 30000; // timeout for a workflow instance
+    #maxStepCount = 3; // maximum number of steps to execute
+    #steps = {}; // workflowsteps configuration
+    #definitions = null; // workflow definition map
+    #name = null; // workflow name
+    #description = null; // workflow description
+    #defaultStepOptions = { // default step options
+        timeout: 30000, // timeout for a step
+        maxRetries: 3 // maximum number of retries for a step
+    };
 
-    constructor() {
+    /**
+     * Create a new workflow instance
+     * @param {string} name - Unique identifier for the workflow
+     * @param {string} description - Human-readable description
+     * @param {Object} definition - Object containing step definitions
+     * @param {Object} options - Optional configuration options
+     */
+    constructor(name, description, definition, options = {}) {
         super();
-        this.definitions = new Map();
-    }
+        this.#definitions = new Map();
+        this.#name = name;
+        this.#description = description;
+        
+        // Apply any configuration options
+        if (options) {
+            this.configure(options);
+        }
 
-    // Singleton instance
-    static instance = null;
-    
-    // Configuration
-    static collectionName = 'workflowdata';
-    static queuePrefix = 'workflowqueue';
-    static timeout = 30000;
-    static maxStepCount = 3;
+        // Store the initial definition if provided
+        if (definition) {
+            this.#definitions.set(name, definition);
+            console.debug('Initial workflow definition stored:', {
+                name,
+                stepNames: Object.keys(definition)
+            });
+        }
+    }
 
     /**
      * Set the collection name for storing steps data
      * @param {string} name - Collection name
      * @throws {Error} If name is not a non-empty string
      */
-    static setCollectionName(name) {
+    setCollectionName(name) {
         if (typeof name !== 'string' || !name.trim()) {
             throw new Error('Collection name must be a non-empty string');
         }
-        StepsEngine.collectionName = name.trim();
+        this.#collectionName = name.trim();
+    }
+
+    /**
+     * Get the collection name
+     * @returns {string} The collection name
+     */
+    getCollectionName() {
+        return this.#collectionName;
     }
 
     /**
@@ -42,11 +78,19 @@ class StepsEngine extends EventEmitter {
      * @param {string} prefix - Queue prefix
      * @throws {Error} If prefix is not a non-empty string
      */
-    static setQueuePrefix(prefix) {
+    setQueuePrefix(prefix) {
         if (typeof prefix !== 'string' || !prefix.trim()) {
             throw new Error('Queue prefix must be a non-empty string');
         }
-        StepsEngine.queuePrefix = prefix.trim();
+        this.#queuePrefix = prefix.trim();
+    }
+
+    /**
+     * Get the queue prefix
+     * @returns {string} The queue prefix
+     */
+    getQueuePrefix() {
+        return this.#queuePrefix;
     }
 
     /**
@@ -54,11 +98,19 @@ class StepsEngine extends EventEmitter {
      * @param {number} timeout - Timeout in milliseconds
      * @throws {Error} If timeout is not a positive number
      */
-    static setTimeout(timeout) {
+    setTimeout(timeout) {
         if (typeof timeout !== 'number' || timeout <= 0) {
             throw new Error('Timeout must be a positive number');
         }
-        StepsEngine.timeout = timeout;
+        this.#timeout = timeout;
+    }
+
+    /**
+     * Get the timeout
+     * @returns {number} The timeout in milliseconds
+     */
+    getTimeout() {
+        return this.#timeout;
     }
 
     /**
@@ -66,11 +118,39 @@ class StepsEngine extends EventEmitter {
      * @param {number} maxStepCount - Maximum step count
      * @throws {Error} If maxStepCount is not a positive number
      */
-    static setMaxStepCount(maxStepCount) {
+    setMaxStepCount(maxStepCount) {
         if (typeof maxStepCount !== 'number' || maxStepCount <= 0) {    
             throw new Error('Maximum step count must be a positive number');
         }
-        StepsEngine.maxStepCount = maxStepCount;
+        this.#maxStepCount = maxStepCount;
+    }
+
+    /**
+     * Get the maximum step count
+     * @returns {number} The maximum step count
+     */
+    getMaxStepCount() {
+        return this.#maxStepCount;
+    }
+
+    /**
+     * Set the steps configuration
+     * @param {Object} steps - Steps configuration
+     * @throws {Error} If steps is not an object or is null
+     */
+    setStepsConfig(steps) {
+        if (typeof steps !== 'object' || steps === null) {
+            throw new Error('Steps must be an object');
+        }
+        this.#steps = steps;
+    }
+
+    /**
+     * Get the steps configuration
+     * @returns {Object} The steps configuration
+     */
+    getStepsConfig() {
+        return this.#steps;
     }
 
     /**
@@ -79,33 +159,27 @@ class StepsEngine extends EventEmitter {
      * @param {string} config.collectionName - Collection name
      * @param {string} config.queuePrefix - Queue prefix
      * @param {number} config.timeout - Timeout in milliseconds
+     * @param {number} config.maxStepCount - Maximum step count
+     * @param {Object} config.steps - Steps configuration
      */
     configure(config) {
         if (config.collectionName) {
-            StepsEngine.setCollectionName(config.collectionName);
+            this.setCollectionName(config.collectionName);
         }
         if (config.queuePrefix) {
-            StepsEngine.setQueuePrefix(config.queuePrefix);
+            this.setQueuePrefix(config.queuePrefix);
         }
         if (config.timeout) {
-            StepsEngine.setTimeout(config.timeout);
+            this.setTimeout(config.timeout);
         }
         if (config.maxStepCount) {
-            StepsEngine.setMaxStepCount(config.maxStepCount);
+            this.setMaxStepCount(config.maxStepCount);
         }
-    }
-
-    /**
-     * Get the singleton instance of StepsEngine
-     * @returns {StepsEngine} The singleton instance
-     */
-    static getInstance() {
-        if (!StepsEngine.instance) {
-            StepsEngine.instance = new StepsEngine();
+        if (config.steps) {
+            this.setStepsConfig(config.steps);
         }
-        return StepsEngine.instance;
     }
-    
+
     /**
      * Get the step definition for a specific step
      * @param {string} stepsName - Name of the steps workflow
@@ -114,7 +188,7 @@ class StepsEngine extends EventEmitter {
      * @throws {Error} If steps definition or step function not found
      */
     getDefinition(stepsName, stepName) {
-        const stepsDef = this.definitions.get(stepsName);
+        const stepsDef = this.#definitions.get(stepsName);
         if (!stepsDef) {
             throw new Error(`No Steps definition found for: ${stepsName}`);
         }
@@ -156,28 +230,34 @@ class StepsEngine extends EventEmitter {
         const connection = await Datastore.open();            
 
         // Handle single next step
-        StepsEngine.getInstance().emit('stepStarted', { workflowName: stepsName, step: nextStep, state: newState, instanceId });
+        this.emit('stepStarted', { workflowName: stepsName, step: nextStep, state: newState, instanceId });
         
         // remove the _id from the newState
         delete newState._id;
         // increment the step count
-        newState.stepCount[nextStep] = (newState.stepCount[nextStep] || 0) + 1;
+        if (!newState.stepCount) {
+            newState.stepCount = {};
+        }
+        if (!newState.stepCount[nextStep]) {
+            newState.stepCount[nextStep] = { visits: 0, startTime: new Date().toISOString(), totalTime: 0 };
+        }
+        newState.stepCount[nextStep].visits += 1;
         // Update the existing steps state in the database
-        newState = await connection.updateOne(StepsEngine.collectionName,
+        newState = await connection.updateOne(this.#collectionName,
             { _id: instanceId },
             { $set: { ...newState, nextStep: nextStep, updatedAt: new Date().toISOString(), stepCount: newState.stepCount } });
         
-        StepsEngine.getInstance().emit('stateUpdated', { workflowName: stepsName, state: newState, instanceId });    
+        this.emit('stateUpdated', { workflowName: stepsName, state: newState, instanceId });    
         
         try {
             // Get the next step function
-            const func = StepsEngine.getInstance().getDefinition(stepsName, nextStep);
+            const func = this.getDefinition(stepsName, nextStep);
 
             // Wrap the callback in a Promise to ensure proper async handling
             await new Promise(async (resolve, reject) => {
                 // check if the step count is greater than the max step count
-                if (newState.stepCount[nextStep] > StepsEngine.maxStepCount) {
-                    reject(new Error(`Step ${nextStep} has been executed ${newState.stepCount[nextStep]} times, which is greater than the maximum step count of ${StepsEngine.maxStepCount}`));
+                if (newState.stepCount[nextStep].visits > this.getMaxStepCount()) {
+                    reject(new Error(`Step ${nextStep} has been executed ${newState.stepCount[nextStep].visits} times, which is greater than the maximum step count of ${this.getMaxStepCount()}`));
                     return;
                 }
                 try {
@@ -202,16 +282,23 @@ class StepsEngine extends EventEmitter {
                                 ...protectedState
                             };
 
+                            // set step finish time
+                            mergedState.stepCount[mergedState.nextStep].finishTime = new Date().toISOString();
+                            mergedState.stepCount[mergedState.nextStep].totalTime = (new Date(mergedState.stepCount[mergedState.nextStep].finishTime) - new Date(mergedState.stepCount[mergedState.nextStep].startTime));
+
                             // update the parallel steps metadata
                             if (mergedState.parallelSteps && mergedState.parallelSteps[mergedState.nextStep]) {
                                 // get a fresh copy of the parallel steps
-                                const fresh = await connection.findOne(StepsEngine.collectionName, { _id: instanceId });                                
+                                const fresh = await connection.findOne(this.#collectionName, { _id: instanceId });                                
                                 fresh.parallelSteps[mergedState.nextStep].done = true;
-                                fresh.parallelSteps[mergedState.nextStep].nextStep = nextStep;                           
+                                fresh.parallelSteps[mergedState.nextStep].nextStep = nextStep;
+                                //fresh.parallelSteps[mergedState.nextStep].previousStep = mergedState.previousStep || null;                           
                                 delete fresh._id;
-                                await connection.updateOne(StepsEngine.collectionName,
+                                const updated = await connection.updateOne(this.#collectionName,
                                     { _id: instanceId },
                                     { $set: { ...fresh, parallelSteps: fresh.parallelSteps } }); 
+                                //console.debug('updated', updated.parallelSteps);
+                                mergedState.parallelSteps = fresh.parallelSteps;
                                 // Check if all parallel steps are done
                                 const allStepsDone = Object.values(fresh.parallelSteps).every(step => step.done);
                                 if (!allStepsDone) {
@@ -219,6 +306,14 @@ class StepsEngine extends EventEmitter {
                                     resolve();
                                     return;
                                 } else {
+                                    // validate that all parallel steps have the same next step
+                                    const nextSteps = Object.values(fresh.parallelSteps).map(step => step.nextStep);
+                                    const uniqueNextSteps = [...new Set(nextSteps)];
+                                    if (uniqueNextSteps.length > 1) {
+                                        throw new Error('Parallel steps must join to the same next step');
+                                    }
+                                    // reset the parallel steps
+                                    mergedState.parallelSteps = {};
                                     console.debug('All parallel steps are done');
                                 }
                             }
@@ -226,13 +321,13 @@ class StepsEngine extends EventEmitter {
                             // If there is no next step, the workflow is completed
                             if (nextStep === null) {
                                 delete mergedState._id;
-                                const completionTime = (new Date(mergedState.updatedAt) - new Date(mergedState.createdAt)) / 1000;
+                                const completionTime = (new Date(mergedState.updatedAt) - new Date(mergedState.createdAt));
                                 
-                                const finalresult = await connection.updateOne(StepsEngine.collectionName,
+                                const finalresult = await connection.updateOne(this.#collectionName,
                                     { _id: instanceId },
-                                    { $set: { ...mergedState, nextStep: null, updatedAt: new Date().toISOString() } });                            
-                                console.log(`Workflow ${stepsName} ${instanceId} is completed in time: ${completionTime}s 🎉`);
-                                StepsEngine.getInstance().emit('completed', { ...finalresult});
+                                    { $set: { ...mergedState, nextStep: null, updatedAt: new Date().toISOString(), totalTime: completionTime } });                            
+                                console.log(`Workflow ${stepsName} ${instanceId} is completed in time: ${completionTime / 1000}s 🎉`);
+                                this.emit('completed', { ...finalresult});
                                 resolve();
                                 return;
                             }
@@ -241,17 +336,17 @@ class StepsEngine extends EventEmitter {
                             if (Array.isArray(nextStep)) {
                                 const now = new Date().toISOString();
                                 const metadata = nextStep.reduce((acc, step) => {
-                                    acc[step] = { done: false, startTime: now };
+                                    acc[step] = { done: false, startTime: now, previousStep: mergedState.previousStep };
                                     return acc;
                                 }, {});
-                                const metadataDoc = await connection.updateOne(StepsEngine.collectionName,
+                                const metadataDoc = await connection.updateOne(this.#collectionName,
                                     { _id: instanceId },
                                     { $set: { parallelSteps: metadata } });
                                 //console.log('metadataDoc', metadataDoc);
                                 // enqueue all steps in parallel
                                 for (const step of nextStep) {
                                     console.debug('enqueue step', step, instanceId);
-                                    await connection.enqueue(`${StepsEngine.queuePrefix}_${stepsName}_${step}`, {
+                                    await connection.enqueue(`${this.#queuePrefix}_${stepsName}_${step}`, {
                                         stepsName: stepsName,
                                         goto: step,
                                         state: mergedState,
@@ -261,7 +356,7 @@ class StepsEngine extends EventEmitter {
                                 }
                             } else {
                                 console.debug('enqueue step', nextStep, instanceId);
-                                await connection.enqueue(`${StepsEngine.queuePrefix}_${stepsName}_${nextStep}`, {
+                                await connection.enqueue(`${this.#queuePrefix}_${stepsName}_${nextStep}`, {
                                 stepsName: stepsName,
                                 goto: nextStep,
                                 state: mergedState,
@@ -269,7 +364,7 @@ class StepsEngine extends EventEmitter {
                                 instanceId: instanceId
                             });
                             }                           
-                            StepsEngine.getInstance().emit('stepEnqueued', { workflowName: stepsName, step: nextStep, state: newState, instanceId });
+                            this.emit('stepEnqueued', { workflowName: stepsName, step: nextStep, state: newState, instanceId });
                             resolve();
                         } catch (error) {
                             console.error('error', error.message);
@@ -288,35 +383,63 @@ class StepsEngine extends EventEmitter {
     }
 
     /**
-     * Register a new steps workflow
+     * Register the workflow with a Codehooks application
+     * @param {Codehooks} app - Codehooks application instance
+     * @returns {Promise<string>} The registered workflow name
+     */
+    async register(app) {
+        if (!this.#name || !this.#description) {
+            throw new Error('Workflow name and description must be set before registration');
+        }
+
+        const definition = this.#definitions.get(this.#name);
+        if (!definition) {
+            throw new Error(`No workflow definition found for: ${this.#name}`);
+        }
+
+        return this.registerWithApp(app, this.#name, this.#description, definition);
+    }
+
+    /**
+     * Register a new workflow with a Codehooks application
      * @param {Codehooks} app - Codehooks application instance
-     * @param {string} name - Unique identifier for the steps workflow
+     * @param {string} name - Unique identifier for the workflow
      * @param {string} description - Human-readable description
      * @param {Object} definition - Object containing step definitions
-     * @returns {Promise<string>} The registered steps name
-     * @throws {Error} If step definition is invalid
+     * @returns {Promise<string>} The registered workflow name
+     * @private
      */
-    async register(app, name, description, definition) {
-        StepsEngine.getInstance().emit('workflowCreated', { name, description });
+    async registerWithApp(app, name, description, definition) {
+        this.emit('workflowCreated', { name, description });
+
+        // Log initial state of definitions Map
+        console.debug('Before registration - Current definitions Map:', {
+            size: this.#definitions.size,
+            keys: Array.from(this.#definitions.keys()),
+            entries: Array.from(this.#definitions.entries()).map(([key, value]) => ({
+                key,
+                stepNames: Object.keys(value)
+            }))
+        });
 
         // Validate each step in the definition
         for (const [stepName, step] of Object.entries(definition)) {
             try {
                 if (stepName !== undefined) {
-                    //console.log('registering queue for step', `${StepsEngine.queuePrefix}_${name}_${stepName}`);
-                    app.worker(`${StepsEngine.queuePrefix}_${name}_${stepName}`, async function(req, res) {                        
+                    console.debug('registering queue for step', `${this.#queuePrefix}_${name}_${stepName}`);
+                    app.worker(`${this.#queuePrefix}_${name}_${stepName}`, async (req, res) => {                        
                         try {                            
                             const { stepsName, goto, state, instanceId, options } = req.body.payload;
                             console.debug('dequeue step', stepName, instanceId);
-                            const qid = await StepsEngine.getInstance().handleNextStep(stepsName, goto, state, instanceId, options);
+                            const qid = await this.handleNextStep(stepsName, goto, state, instanceId, options);
                         } catch (error) {
                             const { stepsName, goto, state, instanceId, options } = req.body.payload;
                             const connection = await Datastore.open();
-                            await connection.updateOne(StepsEngine.collectionName,
+                            await connection.updateOne(this.#collectionName,
                                 { _id: instanceId },
                                 { $set: { lastError: error, updatedAt: new Date().toISOString() } });
                             console.error('Error in function: ' + stepName, error);
-                            StepsEngine.getInstance().emit('error', error);
+                            this.emit('error', error);
                         } finally {
                             res.end();
                         }
@@ -328,7 +451,19 @@ class StepsEngine extends EventEmitter {
             }
         }
 
-        this.definitions.set(name, definition);
+        // Store the definition
+        this.#definitions.set(name, definition);
+        
+        // Log state after registration
+        console.debug('After registration - Updated definitions Map:', {
+            size: this.#definitions.size,
+            keys: Array.from(this.#definitions.keys()),
+            entries: Array.from(this.#definitions.entries()).map(([key, value]) => ({
+                key,
+                stepNames: Object.keys(value)
+            }))
+        });
+
         return name;
     }
 
@@ -340,22 +475,50 @@ class StepsEngine extends EventEmitter {
      * @throws {Error} If starting steps fails
      */
     async start(name, initialState) {
-        StepsEngine.getInstance().emit('workflowStarted', { name, initialState });
+        this.emit('workflowStarted', { name, initialState });
+
+        // Log definitions Map state at start
+        console.debug('At workflow start - Current definitions Map:', {
+            size: this.#definitions.size,
+            keys: Array.from(this.#definitions.keys()),
+            entries: Array.from(this.#definitions.entries()).map(([key, value]) => ({
+                key,
+                stepNames: Object.keys(value)
+            }))
+        });
 
         return new Promise(async (resolve, reject) => {
             try {
-                const funcs = this.definitions.get(name);
+                console.debug('Starting workflow', name);
+                const funcs = this.#definitions.get(name);
+                console.debug('Retrieved workflow definition:', {
+                    exists: !!funcs,
+                    stepNames: funcs ? Object.keys(funcs) : []
+                });
+
+                if (!funcs) {
+                    reject(new Error(`No workflow definition found for: ${name}`));
+                    return;
+                }
+
                 const firstStepName = Object.keys(funcs)[0];
                 const firstStep = funcs[firstStepName];
+                console.debug('First step details:', {
+                    name: firstStepName,
+                    exists: !!firstStep,
+                    type: firstStep ? typeof firstStep : 'undefined'
+                });
+
                 if (!firstStep) {
-                    reject(new Error('No start step defined in steps'));
+                    reject(new Error('No start step defined in workflow'));
                     return;
                 }
+
                 const connection = await Datastore.open();
-                // Create a new steps state in the database
-                const newState = await connection.insertOne(StepsEngine.collectionName,
-                    { ...initialState, nextStep: firstStepName, createdAt: new Date().toISOString(), workflowName: name, stepCount: {} });
-                const { _id: ID } = await connection.enqueue(`${StepsEngine.queuePrefix}_${name}_${firstStepName}`, {
+                // Create a new workflow state in the database
+                const newState = await connection.insertOne(this.#collectionName,
+                    { ...initialState, nextStep: firstStepName, createdAt: new Date().toISOString(), workflowName: name, stepCount: {  } });
+                const { _id: ID } = await connection.enqueue(`${this.#queuePrefix}_${name}_${firstStepName}`, {
                     stepsName: name,
                     goto: firstStepName,
                     state: newState,
@@ -364,25 +527,25 @@ class StepsEngine extends EventEmitter {
                 });
                 resolve(newState);
             } catch (error) {
-                console.error('Error starting steps:', error.message);
+                console.error('Error starting workflow:', error.message);
                 reject(error);
             }
         });
     }
 
     /**
-     * Update the state of a steps instance
-     * @param {string} stepsName - Name of the steps workflow
-     * @param {string} instanceId - ID of the steps instance
+     * Update the state of a workflow instance
+     * @param {string} stepsName - Name of the workflow
+     * @param {string} instanceId - ID of the workflow instance
      * @param {Object} state - New state to update with
      * @param {Object} options - Options for the update, { continue: false } to avoid continuing the the step
      * @returns {Promise<Object>} The updated state
      */
     async updateState(stepsName, instanceId, state, options={continue: true}) {
-        StepsEngine.getInstance().emit('stepsStateUpdating', { stepsName, instanceId, state });
+        this.emit('stepsStateUpdating', { stepsName, instanceId, state });
         const connection = await Datastore.open();
         return new Promise(async (resolve, reject) => {
-            const doc = await connection.updateOne(StepsEngine.collectionName, 
+            const doc = await connection.updateOne(this.#collectionName, 
                 { _id: instanceId }, 
                 { $set: { ...state, updatedAt: new Date().toISOString() } });
             if (options.continue) {
@@ -400,7 +563,7 @@ class StepsEngine extends EventEmitter {
      */
     async setState(instanceId, { _id, state }) {
         const connection = await Datastore.open();
-        await connection.replaceOne(StepsEngine.collectionName, { _id: _id }, { ...state });
+        await connection.replaceOne(this.#collectionName, { _id: _id }, { ...state });
     }
 
     /**
@@ -410,22 +573,29 @@ class StepsEngine extends EventEmitter {
      * @returns {Promise<{qId: string}>} Queue ID for the continued step
      * @throws {Error} If steps instance not found
      */
-    async continue(stepsName, instanceId) {
+    async continue(stepsName, instanceId, reset=false) {
         const connection = await Datastore.open();
-        const state = await connection.findOne(StepsEngine.collectionName, { _id: instanceId });
+        const state = await connection.findOne(this.#collectionName, { _id: instanceId });
         if (!state) {
             throw new Error(`No steps found with instanceId: ${instanceId}`);
         }
-        // update all step counts to 0  
-        for (const step in state.stepCount) {
-            state.stepCount[step] = 0;
+        if (reset) {
+            // reset the step count
+            // update all step counts to 0  
+            for (const step in state.stepCount) {
+                state.stepCount[step] = { visits: 0, startTime: new Date().toISOString() };
+            }
+        } else {
+            // update the step count
+            state.stepCount[state.nextStep] = { visits: 0, startTime: new Date().toISOString() };
         }
-        await connection.updateOne(StepsEngine.collectionName, { _id: instanceId }, { $set: { stepCount: state.stepCount } });
+        
+        await connection.updateOne(this.#collectionName, { _id: instanceId }, { $set: { stepCount: state.stepCount } });
         console.debug('continue state', state);
-        StepsEngine.getInstance().emit('workflowContinued', { stepsName, step: state.nextStep, instanceId });                    
+        this.emit('workflowContinued', { stepsName, step: state.nextStep, instanceId });                    
 
         return new Promise(async (resolve, reject) => {
-            const { _id: ID } = await connection.enqueue(`${StepsEngine.queuePrefix}_${stepsName}_${state.nextStep}`, {
+            const { _id: ID } = await connection.enqueue(`${this.#queuePrefix}_${stepsName}_${state.nextStep}`, {
                 stepsName,
                 goto: state.nextStep,
                 state: state,
@@ -438,21 +608,21 @@ class StepsEngine extends EventEmitter {
     }
 
     /**
-     * Continue all timed out steps instances
+     * Continue all timed out workflows instances
      * @returns {Promise<Array<{qId: string}>>} Array of results containing queue IDs for continued workflows
      */
     async continueAllTimedOut() {
         const db = await Datastore.open();
-        const timedOutWorkflows = await db.collection(StepsEngine.collectionName).find({nextStep: {$ne: null}}).toArray();
+        const timedOutWorkflows = await db.collection(this.#collectionName).find({nextStep: {$ne: null}}).toArray();
         const now = new Date();
         const results = [];
         for (const workflow of timedOutWorkflows) {
             const createdAt = new Date(workflow.createdAt);
             const diffMillis = now.getTime() - createdAt.getTime();
-            if (diffMillis > StepsEngine.timeout) {
+            if (diffMillis > this.#timeout) {
                 const diffMinutes = diffMillis / (1000 * 60);
                 console.log('Timed out:', workflow._id, workflow.nextStep, `(${diffMinutes.toFixed(1)} minutes old)`);
-                const result = await this.continue(workflow.workflowName, workflow._id);    
+                const result = await this.continue(workflow.workflowName, workflow._id, true);    
                 console.log('Continued:', result._id);
                 results.push(result);
             }
@@ -468,7 +638,7 @@ class StepsEngine extends EventEmitter {
     async getStepsStatus(id) {
         return new Promise(async (resolve, reject) => {
             const connection = await Datastore.open();
-            const state = await connection.findOne(StepsEngine.collectionName, { _id: id });
+            const state = await connection.findOne(this.#collectionName, { _id: id });
             resolve(state);
         });
     }
@@ -481,8 +651,8 @@ class StepsEngine extends EventEmitter {
     async getInstances(filter) {
         return new Promise(async (resolve, reject) => {
             const connection = await Datastore.open();
-            const states = await connection.find(StepsEngine.collectionName, filter).toArray();
-            console.debug('listSteps', StepsEngine.collectionName, filter, states.length);
+            const states = await connection.find(this.#collectionName, filter).toArray();
+            console.debug('listSteps', this.#collectionName, filter, states.length);
             resolve(states);
         });
     }
@@ -493,21 +663,104 @@ class StepsEngine extends EventEmitter {
      * @returns {Promise<Object>} The cancellation result
      */
     async cancelSteps(id) {
-        StepsEngine.getInstance().emit('cancelled', { id });
+        this.emit('cancelled', { id });
         return new Promise(async (resolve, reject) => {
             const connection = await Datastore.open();
-            const state = await connection.updateOne(StepsEngine.collectionName, 
+            const state = await connection.updateOne(this.#collectionName, 
                 { _id: id }, 
                 { $set: { status: 'cancelled' } });    
             resolve(state);
         });
     }
-}
 
-// Export the static methods directly
-export const setCollectionName = StepsEngine.setCollectionName.bind(StepsEngine);
-export const setQueuePrefix = StepsEngine.setQueuePrefix.bind(StepsEngine);
+    /**
+     * Check if a specific step in a workflow instance has timed out
+     * @param {Object} workflow - The workflow instance
+     * @param {string} stepName - The name of the step to check (defaults to previousStep)
+     * @returns {Object} Object containing timeout status and details
+     */
+    isStepTimedOut(workflow) {
+        // Use previousStep if no stepName provided
+        const stepToCheck = workflow.nextStep;
+        
+        if (!stepToCheck || !workflow.stepCount || !workflow.stepCount[stepToCheck]) {
+            console.debug('no step', stepToCheck, workflow.stepCount);
+            return {
+                isTimedOut: false,
+                reason: 'Step not found in workflow',
+                step: stepToCheck
+            };
+        }
+
+        const step = workflow.stepCount[stepToCheck];
+        
+        // Get the timeout value for this step
+        // First try step-specific config, then default options, finally fallback to global timeout
+        const stepConfig = this.#steps[stepToCheck];
+        const stepTimeout = stepConfig?.timeout ?? this.#defaultStepOptions.timeout ?? this.#timeout;
+        
+        // If the step hasn't finished, check if it's been running too long
+        console.debug('isStepTimedOut', stepToCheck, stepTimeout);
+        if (!step.finishTime) {
+            const startTime = new Date(step.startTime);
+            const now = new Date();
+            const runningTime = now.getTime() - startTime.getTime();
+            console.debug('runningTime', runningTime, stepTimeout);
+            return {
+                isTimedOut: runningTime > stepTimeout,
+                runningTime,
+                timeout: stepTimeout,
+                step: stepToCheck,
+                startTime: step.startTime,
+                currentTime: now.toISOString(),
+                timeoutSource: stepConfig ? 'stepConfig' : (this.#defaultStepOptions.timeout ? 'defaultOptions' : 'globalTimeout')
+            };
+        }
+
+        // If the step has finished, check if it took too long
+        const startTime = new Date(step.startTime);
+        const finishTime = new Date(step.finishTime);
+        const executionTime = finishTime.getTime() - startTime.getTime();
+        console.debug('executionTime', executionTime, stepTimeout);
+        return {
+            isTimedOut: executionTime > stepTimeout,
+            executionTime,
+            timeout: stepTimeout,
+            step: stepToCheck,
+            startTime: step.startTime,
+            finishTime: step.finishTime,
+            timeoutSource: stepConfig ? 'stepConfig' : (this.#defaultStepOptions.timeout ? 'defaultOptions' : 'globalTimeout')
+        };
+    }
+
+    /**
+     * Find all workflow instances with timed out steps
+     * @param {Object} filter - Optional filter criteria for workflows
+     * @returns {Promise<Array<Object>>} Array of workflow instances with timed out steps
+     */
+    async findTimedOutSteps(filter = {}) {
+        const db = await Datastore.open();
+        const workflows = await db.getMany(this.#collectionName, {"nextStep": {$ne: null}}).toArray();
+        if (workflows.length > 0) {
+            console.debug('TimedOutSteps', workflows.length);
+        }
+        const timedOutWorkflows = workflows.map(workflow => {
+            console.debug('isStepTimedOut', workflow.nextStep);
+            const timeoutStatus = this.isStepTimedOut(workflow);
+            if (timeoutStatus.isTimedOut) {
+                return {
+                    workflowId: workflow._id,
+                    workflowName: workflow.workflowName,
+                    ...timeoutStatus
+                };
+            }
+            return null;
+        }).filter(Boolean);
+
+        return timedOutWorkflows;
+    }
+}
 
-// Export the singleton instance
-export const Steps = StepsEngine.getInstance();
-export default StepsEngine.getInstance();
+// Export the class directly instead of a singleton instance
+export { Workflow };
+export default Workflow;