codehooks-js 1.3.8 → 1.3.10

package/index.js

@@ -1,7 +1,7 @@
 import {agg} from './aggregation/index.mjs';
 import {crudlify as crud} from './crudlify/index.mjs';
 import {serveStatic as ws, render as renderView} from './webserver.mjs';
-import {Steps as Workflow, StepsConfig as WorkflowConfig} from './workflow/index.mjs';
+import Workflow from './workflow/engine.mjs';
 
 function createRoute(str) {
   if(str instanceof RegExp) {
@@ -118,8 +118,9 @@ class Codehooks {
   }
   
   createWorkflow = (name, description, steps, options={}) => {
-    Workflow.register(this, name, description, steps, options);
-    return Workflow;
+    const wf = new Workflow(name, description, steps, options);
+    wf.register(this);
+    return wf;
   }
 
   init = (hook) => {
@@ -193,10 +194,8 @@ export const aggregation = agg;
 export const crudlify = crud;
 export const coho = _coho;
 export const app = _coho;
-export const workflowconfig = WorkflowConfig;
 export {
-  Workflow,
-  WorkflowConfig
+  Workflow
 };
 export const realtime = {
   createChannel: (path, ...hook) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codehooks-js",
-  "version": "1.3.8",
+  "version": "1.3.10",
   "type": "module",
   "description": "Codehooks.io official library - provides express.JS like syntax",
   "main": "index.js",

package/types/index.d.ts

@@ -1032,21 +1032,29 @@ export class Codehooks {
   };
   addListener: (observer: any) => void;
   /**
-   * Create a new steps workflow
-   * @param name - Unique identifier for the steps workflow
-   * @param description - Human-readable description of the steps workflow
+   * Create a new workflow
+   * @param name - Unique identifier for the workflow
+   * @param description - Human-readable description of the workflow
    * @param steps - Object containing step definitions
    * @param options - Optional configuration options
-   * @returns WorkflowEngine instance for managing the workflow
+   * @returns Workflow instance for managing the workflow
+   */
+  createWorkflow: (name: string, description: string, steps: WorkflowDefinition, options?: WorkflowConfig) => Workflow;
+  /**
+   * Register a workflow with the application
+   * @param name - Unique identifier for the workflow
+   * @param description - Human-readable description
+   * @param steps - Step definitions
+   * @returns Promise with the registered workflow name
    */
-  createWorkflow: (name: string, description: string, steps: StepsDefinition, options?: any) => WorkflowEngine;
+  registerWorkflow: (name: string, description: string, steps: WorkflowDefinition) => Promise<string>;
 }
 declare const _coho: Codehooks;
 
 /**
  * Events emitted by the workflow engine
  */
-export type StepsEvents = {
+export type WorkflowEvents = {
   /**
    * Emitted when a new workflow is registered
    * @event
@@ -1081,7 +1089,7 @@ export type StepsEvents = {
    * Emitted when a workflow instance is continued after waiting
    * @event
    */
-  'stepContinued': { workflowName: string; step: string; instanceId: string };
+  'workflowContinued': { workflowName: string; step: string; instanceId: string };
 
   /**
    * Emitted when a workflow instance is completed
@@ -1094,173 +1102,284 @@ export type StepsEvents = {
    * @event
    */
   'cancelled': { id: string };
+
+  /**
+   * Emitted when an error occurs
+   * @event
+   */
+  'error': { error: Error };
 };
 
 /**
- * Definition of steps in a workflow
+ * Definition of a workflow step function
  */
-export type StepsDefinition = Record<string, (state: any, goto: (step: string | string[] | null, state: any) => void) => void | Promise<void>>;
+export type WorkflowDefinition = Record<string, (state: any, callback: (nextStep: string | string[] | null, newState: any, options?: any) => void) => Promise<void>>;
 
 /**
- * Engine for managing step-based workflows
+ * Configuration options for a workflow step
  */
-export type StepsEngine = {
-  /**
-   * Configure the workflow engine
-   * @param options - Configuration options
-   */
-  configure: (options: any) => void;
-} & {
-  /**
-   * Get the singleton instance
-   */
-  getInstance: () => Steps;
+export type StepOptions = {
+  /** Timeout in milliseconds for this specific step */
+  timeout?: number;
+  /** Maximum number of retries for this step */
+  maxRetries?: number;
+};
+
+/**
+ * Configuration options for the Workflow engine
+ */
+export type WorkflowConfig = {
+  /** Collection name for storing workflow data */
+  collectionName?: string;
+  /** Queue prefix for workflow jobs */
+  queuePrefix?: string;
+  /** Global timeout in milliseconds for workflow steps */
+  timeout?: number;
+  /** Maximum number of times a step can be executed */
+  maxStepCount?: number;
+  /** Step-specific configuration options */
+  steps?: Record<string, StepOptions>;
 };
 
 /**
- * Engine for managing step-based workflows
- * @extends Steps
+ * Engine for managing workflow-based applications
+ * @extends Workflow
  */
-export type WorkflowEngine = Steps & {
+export type WorkflowEngine = Workflow & {
   /**
-   * Register a new steps workflow
+   * Register a new workflow
    * @param name - Unique identifier for the workflow
    * @param description - Human-readable description
    * @param steps - Step definitions
    */
-  register: (name: string, description: string, steps: StepsDefinition) => Promise<string>;
+  register: (name: string, description: string, steps: WorkflowDefinition) => Promise<string>;
 };
 
 /**
- * Steps workflow engine for managing step-based workflows
+ * Workflow engine for managing step-based applications
  * @extends EventEmitter
  */
-export type Steps = {
+export type Workflow = {
   /**
    * Configure the workflow engine
    * @param options - Configuration options
+   * @param options.collectionName - Collection name for storing workflow data
+   * @param options.queuePrefix - Queue prefix for workflow jobs
+   * @param options.timeout - Timeout in milliseconds for workflow steps
+   * @param options.maxStepCount - Maximum number of times a step can be executed
+   * @param options.steps - Workflow step configuration
+   * @example
+   * workflow.configure({
+   *   collectionName: 'workflows',
+   *   queuePrefix: 'workflow',
+   *   timeout: 30000,
+   *   maxStepCount: 3,
+   *   steps: {
+   *     stepName: {
+   *       timeout: 3000,
+   *       maxRetries: 3
+   *     }
+   *   }
+   * });
    */
-  configure: (options: any) => void;
+  configure: (options: WorkflowConfig) => void;
 
   /**
-   * Register a new steps workflow
+   * Register a new workflow
    * @param app - Codehooks application instance
-   * @param name - Unique identifier for the steps workflow
+   * @param name - Unique identifier for the workflow
    * @param description - Human-readable description
    * @param definition - Object containing step definitions
-   * @returns Promise with the registered steps name
+   * @returns Promise with the registered workflow name
    */
   register: (app: Codehooks, name: string, description: string, definition: Record<string, Function>) => Promise<string>;
   
   /**
-   * Start a new steps instance
-   * @param name - Name of the steps workflow to start
-   * @param initialState - Initial state for the steps instance
-   * @returns Promise with the steps instance ID
+   * Start a new workflow instance
+   * @param name - Name of the workflow to start
+   * @param initialState - Initial state for the workflow instance
+   * @returns Promise with the workflow instance ID
    */
   start: (name: string, initialState: any) => Promise<{ id: string }>;
   
   /**
-   * Update the state of a steps instance
-   * @param stepsName - Name of the steps workflow
-   * @param instanceId - ID of the steps instance
+   * Update the state of a workflow instance
+   * @param workflowName - Name of the workflow
+   * @param instanceId - ID of the workflow instance
    * @param state - New state to update with
-   * @param options - Options for the update, { continue: false } to avoid continuing the the step
+   * @param options - Options for the update, { continue: false } to avoid continuing the step
    * @returns Promise with the updated state
    */
-  updateState: (stepsName: string, instanceId: string, state: any, options?: any) => Promise<any>;
+  updateState: (workflowName: string, instanceId: string, state: any, options?: UpdateOptions) => Promise<any>;
   
   /**
-   * Continue a paused steps instance
-   * @param stepsName - Name of the steps workflow
-   * @param instanceId - ID of the steps instance
+   * Continue a paused workflow instance
+   * @param workflowName - Name of the workflow
+   * @param instanceId - ID of the workflow instance
+   * @param reset - Whether to reset all step counts (true) or just the current step (false)
    * @returns Promise with the queue ID for the continued step
    */
-  continue: (stepsName: string, instanceId: string) => Promise<{ qId: string }>;
+  continue: (workflowName: string, instanceId: string, reset?: boolean) => Promise<{ qId: string }>;
   
   /**
-   * Get the status of a steps instance
-   * @param id - ID of the steps instance
-   * @returns Promise with the steps status
+   * Get the status of a workflow instance
+   * @param id - ID of the workflow instance
+   * @returns Promise with the workflow status
    */
-  getStepsStatus: (id: string) => Promise<any>;
+  getWorkflowStatus: (id: string) => Promise<any>;
   
   /**
-   * Get all steps instances matching a filter
-   * @param filter - Filter criteria for steps workflows
-   * @returns Promise with list of steps instances
+   * Get all workflow instances matching a filter
+   * @param filter - Filter criteria for workflows
+   * @returns Promise with list of workflow instances
    */
   getInstances: (filter: any) => Promise<any[]>;
   
   /**
-   * Cancel a steps instance
-   * @param id - ID of the steps instance to cancel
+   * Cancel a workflow instance
+   * @param id - ID of the workflow instance to cancel
    * @returns Promise with the cancellation result
    */
-  cancelSteps: (id: string) => Promise<any>;
+  cancelWorkflow: (id: string) => Promise<any>;
 
   /**
    * Register an event listener
    * @param event - Name of the event to listen for
    * @param listener - Callback function to handle the event
    * @example
-   * Steps.on('stepStarted', ({ stepsName, step, state, instanceId }) => {
-   *   console.log(`Step ${step} started in workflow ${stepsName}`);
+   * workflow.on('stepStarted', ({ workflowName, step, state, instanceId }) => {
+   *   console.log(`Step ${step} started in workflow ${workflowName}`);
    * });
    */
-  on: (event: string, listener: (data: any) => void) => Steps;
+  on: (event: WorkflowEvent, listener: (data: WorkflowEventData) => void) => Workflow;
   
   /**
    * Register a one-time event listener
    * @param event - Name of the event to listen for
    * @param listener - Callback function to handle the event
    */
-  once: (event: string, listener: (data: any) => void) => Steps;
+  once: (event: WorkflowEvent, listener: (data: WorkflowEventData) => void) => Workflow;
   
   /**
    * Remove an event listener
    * @param event - Name of the event
    * @param listener - Callback function to remove
    */
-  off: (event: string, listener: (data: any) => void) => Steps;
+  off: (event: WorkflowEvent, listener: (data: WorkflowEventData) => void) => Workflow;
   
   /**
    * Emit an event
    * @param event - Name of the event to emit
    * @param data - Event data
    */
-  emit: (event: string, data: any) => boolean;
+  emit: (event: WorkflowEvent, data: WorkflowEventData) => boolean;
 
   /**
-   * Continue all timed out steps instances
-   * @returns {Promise<Array<{qId: string}>>} Array of results containing queue IDs for continued workflows
+   * Continue all timed out workflow instances
+   * @returns Promise with array of results containing queue IDs for continued workflows
    */
   continueAllTimedOut: () => Promise<Array<{qId: string}>>;
+
+  /**
+   * Check if a specific step in a workflow instance has timed out
+   * @param workflow - The workflow instance to check
+   * @returns Object containing timeout status and details
+   * @example
+   * const status = workflow.isStepTimedOut(workflowInstance);
+   * // Returns:
+   * // {
+   * //   isTimedOut: boolean,
+   * //   executionTime?: number,  // if step has finished
+   * //   runningTime?: number,    // if step is still running
+   * //   timeout: number,         // actual timeout value used
+   * //   step: string,           // name of the step checked
+   * //   startTime: string,      // ISO timestamp
+   * //   finishTime?: string,    // if step has finished
+   * //   currentTime?: string,   // if step is still running
+   * //   timeoutSource: 'stepConfig' | 'defaultOptions' | 'globalTimeout'
+   * // }
+   */
+  isStepTimedOut: (workflow: any) => {
+    isTimedOut: boolean;
+    executionTime?: number;
+    runningTime?: number;
+    timeout: number;
+    step: string;
+    startTime: string;
+    finishTime?: string;
+    currentTime?: string;
+    timeoutSource: 'stepConfig' | 'defaultOptions' | 'globalTimeout';
+    reason?: string;
+  };
+
+  /**
+   * Find all workflow instances with timed out steps
+   * @param filter - Optional filter criteria for workflows
+   * @returns Promise with array of workflow instances that have timed out steps
+   * @example
+   * const timedOutWorkflows = await workflow.findTimedOutSteps();
+   * // Returns array of workflows with timeout details:
+   * // [{
+   * //   workflowId: string,
+   * //   workflowName: string,
+   * //   isTimedOut: true,
+   * //   executionTime?: number,
+   * //   runningTime?: number,
+   * //   timeout: number,
+   * //   step: string,
+   * //   startTime: string,
+   * //   finishTime?: string,
+   * //   currentTime?: string,
+   * //   timeoutSource: string
+   * // }]
+   */
+  findTimedOutSteps: (filter?: any) => Promise<Array<{
+    workflowId: string;
+    workflowName: string;
+    isTimedOut: boolean;
+    executionTime?: number;
+    runningTime?: number;
+    timeout: number;
+    step: string;
+    startTime: string;
+    finishTime?: string;
+    currentTime?: string;
+    timeoutSource: 'stepConfig' | 'defaultOptions' | 'globalTimeout';
+  }>>;
 };
 
 /**
- * Configuration for the Steps workflow engine
+ * Options for updating workflow state
  */
-export type StepsConfig = {
-  /**
-   * Set the collection name for storing steps data
-   * @param name - Collection name
-   */
-  setCollectionName: (name: string) => void;
-  
-  /**
-   * Set the queue prefix for steps jobs
-   * @param prefix - Queue prefix
-   */
-  setQueuePrefix: (prefix: string) => void;
+export type UpdateOptions = {
+  /** Whether to continue to the next step after update */
+  continue?: boolean;
 };
 
-export const stepsconfig: StepsConfig;
+/**
+ * Workflow event types
+ */
+export type WorkflowEvent = 
+  | 'workflowCreated'
+  | 'workflowStarted'
+  | 'workflowContinued'
+  | 'stepStarted'
+  | 'stepEnqueued'
+  | 'stateUpdated'
+  | 'completed'
+  | 'cancelled'
+  | 'error';
 
 /**
- * Configure the workflow engine
- * @param options - Configuration options
+ * Data structure for workflow events
  */
-export function configure(options: any): void;
+export type WorkflowEventData = {
+  workflowName: string;
+  step?: string;
+  state?: any;
+  instanceId?: string;
+  error?: Error;
+  [key: string]: any;
+};
 
 //# sourceMappingURL=index.d.ts.map

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) => {
+            return 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,15 +282,19 @@ 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].previousStep = mergedState.previousStep || null;                           
                                 delete fresh._id;
-                                const updated = await connection.updateOne(StepsEngine.collectionName,
+                                const updated = await connection.updateOne(this.#collectionName,
                                     { _id: instanceId },
                                     { $set: { ...fresh, parallelSteps: fresh.parallelSteps } }); 
                                 //console.debug('updated', updated.parallelSteps);
@@ -237,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;
                             }
@@ -255,14 +339,14 @@ class StepsEngine extends EventEmitter {
                                     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,
@@ -272,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,
@@ -280,13 +364,14 @@ 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);
                             reject(error);
                         }
                     });
+                    resolve();
                 } catch (error) {
                     console.error('Error executing step function:', error);
                     reject(error);
@@ -299,36 +384,67 @@ 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);
+                            //console.debug('Worker qid', qid);
+                            //res.end();
                         } 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 {
+                            //console.debug('Worker res.end', stepName);
                             res.end();
                         }
                     });
@@ -339,7 +455,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;
     }
 
@@ -351,22 +479,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,
@@ -375,29 +531,29 @@ 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) {
-                await this.continue(stepsName, instanceId);
+                await this.continue(stepsName, instanceId, false);
             } 
             resolve({ ...doc });                       
         });
@@ -411,7 +567,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 });
     }
 
     /**
@@ -421,22 +577,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,
@@ -449,21 +612,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);
             }
@@ -479,7 +642,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);
         });
     }
@@ -492,8 +655,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);
         });
     }
@@ -504,21 +667,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;

package/workflow/index.mjs

@@ -1,16 +1,4 @@
-import StepsEngine, { setCollectionName, setQueuePrefix, Steps } from './engine.mjs';
-
-// Re-export the static methods
-export const StepsConfig = {
-    setCollectionName,
-    setQueuePrefix
-};
-
-// Re-export the configure method
-export const configure = StepsEngine.configure;
-
-// Re-export the workflow instance
-export { Steps };
+import Workflow from './engine.mjs';
 
 // Export the engine as default
-export default StepsEngine; 
+export default Workflow;