codehooks-js 1.3.15 → 1.3.17

package/package.json

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

package/types/index.d.ts

@@ -513,6 +513,10 @@ export type httpRequest = {
    * - JSON payload
    */
   body: any;
+  /**
+   * - Get the raw unparsed request body as a string
+   */
+  rawBody: string;
   /**
    * - Get the URL full path, e.g. /dev/myroute
    */
@@ -622,6 +626,11 @@ export type httpResponse = {
 
 export type nextFunction = (error?: string) => void;
 
+// Aliases for developers familiar with Express.js conventions
+export type Request = httpRequest;
+export type Response = httpResponse;
+export type NextFunction = nextFunction;
+
 export type Filesystem = {
   /**
    * - Get binary file input stream. Takes a path (string) to file (e.g. /static/logo.png) and an options object (Object) for future use. Returns a Promise resolving to a binary data stream emitter.
@@ -1309,6 +1318,27 @@ export type Workflow = {
    */
   cancelSteps: (id: string) => Promise<any>;
 
+  /**
+   * Get the status of a workflow instance (alias for getStepsStatus)
+   * @param id - ID of the workflow instance
+   * @returns Promise with the workflow status
+   */
+  getWorkflowStatus: (id: string) => Promise<any>;
+
+  /**
+   * Get the state of a workflow instance (alias for getStepsStatus)
+   * @param id - ID of the workflow instance
+   * @returns Promise with the workflow state
+   */
+  getState: (id: string) => Promise<any>;
+
+  /**
+   * Cancel a workflow instance (alias for cancelSteps)
+   * @param id - ID of the workflow instance to cancel
+   * @returns Promise with the cancellation result
+   */
+  cancelWorkflow: (id: string) => Promise<any>;
+
   /**
    * Register an event listener
    * @param event - Name of the event to listen for

package/types/workflow/engine.d.mts

@@ -117,5 +117,23 @@ declare class StepsEngine {
      * @returns {Promise<Object>} The cancellation result
      */
     cancelSteps(id: string): Promise<any>;
+    /**
+     * Get the status of a workflow instance (alias for getStepsStatus)
+     * @param {string} id - ID of the workflow instance
+     * @returns {Promise<Object>} The workflow status
+     */
+    getWorkflowStatus(id: string): Promise<any>;
+    /**
+     * Get the state of a workflow instance (alias for getStepsStatus)
+     * @param {string} id - ID of the workflow instance
+     * @returns {Promise<Object>} The workflow state
+     */
+    getState(id: string): Promise<any>;
+    /**
+     * Cancel a workflow instance (alias for cancelSteps)
+     * @param {string} id - ID of the workflow instance to cancel
+     * @returns {Promise<Object>} The cancellation result
+     */
+    cancelWorkflow(id: string): Promise<any>;
 }
 //# sourceMappingURL=engine.d.mts.map

package/workflow/engine.mjs

@@ -38,7 +38,7 @@ class Workflow extends EventEmitter {
         this.#definitions = new Map();
         this.#name = name;
         this.#description = description;
-        
+
         // Apply any configuration options
         if (options) {
             this.configure(options);
@@ -120,7 +120,7 @@ class Workflow extends EventEmitter {
      * @throws {Error} If maxStepCount is not a positive number
      */
     setMaxStepCount(maxStepCount) {
-        if (typeof maxStepCount !== 'number' || maxStepCount <= 0) {    
+        if (typeof maxStepCount !== 'number' || maxStepCount <= 0) {
             throw new Error('Maximum step count must be a positive number');
         }
         this.#maxStepCount = maxStepCount;
@@ -226,13 +226,13 @@ class Workflow extends EventEmitter {
      * @throws {Error} If step execution fails
      */
     async handleNextStep(stepsName, nextStep, newState, instanceId, options) {
-        
+
         // open the connection to the database
-        const connection = await DB.open();            
+        const connection = await DB.open();
 
         // Handle single next step
         this.emit('stepStarted', { workflowName: stepsName, step: nextStep, state: newState, instanceId });
-        
+
         // remove the _id from the newState
         delete newState._id;
         // increment the step count
@@ -247,9 +247,9 @@ class Workflow extends EventEmitter {
         newState = await connection.updateOne(this.#collectionName,
             { _id: instanceId },
             { $set: { ...newState, nextStep: nextStep, updatedAt: new Date().toISOString(), stepCount: newState.stepCount } });
-        
-        this.emit('stateUpdated', { workflowName: stepsName, state: newState, instanceId });    
-        
+
+        this.emit('stateUpdated', { workflowName: stepsName, state: newState, instanceId });
+
         try {
             // Get the next step function
             const func = this.getDefinition(stepsName, nextStep);
@@ -267,14 +267,14 @@ class Workflow extends EventEmitter {
                             console.debug('waiter', state);
                             await connection.updateOne(this.#collectionName,
                                 { _id: instanceId },
-                                { $set: { ...state, updatedAt: new Date().toISOString() } });                            
+                                { $set: { ...state, updatedAt: new Date().toISOString() } });
                             resolve();
                             return;
                         } else {
                             resolve(); // no state update
                         }
                     }
-                    await func({...newState, instanceId: newState._id}, async (nextStep, userState, options) => {
+                    await func({ ...newState, instanceId: newState._id }, async (nextStep, userState, options) => {
                         try {
                             // Protect system-level properties
                             const protectedState = {
@@ -288,7 +288,7 @@ class Workflow extends EventEmitter {
                                 parallelSteps: newState.parallelSteps,
                                 previousStep: newState.nextStep
                             };
-                            
+
                             // Merge states with userState taking precedence, but protecting system fields
                             const mergedState = {
                                 ...userState,
@@ -302,14 +302,14 @@ class Workflow extends EventEmitter {
                             // 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(this.#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(this.#collectionName,
                                     { _id: instanceId },
-                                    { $set: { ...fresh, parallelSteps: fresh.parallelSteps } }); 
+                                    { $set: { ...fresh, parallelSteps: fresh.parallelSteps } });
                                 //console.debug('updated', updated.parallelSteps);
                                 mergedState.parallelSteps = fresh.parallelSteps;
                                 // Check if all parallel steps are done
@@ -335,12 +335,12 @@ class Workflow extends EventEmitter {
                             if (nextStep === null) {
                                 delete mergedState._id;
                                 const completionTime = (new Date(mergedState.updatedAt) - new Date(mergedState.createdAt));
-                                
+
                                 const finalresult = await connection.updateOne(this.#collectionName,
                                     { _id: instanceId },
-                                    { $set: { ...mergedState, nextStep: null, updatedAt: new Date().toISOString(), totalTime: completionTime } });                            
+                                    { $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});
+                                this.emit('completed', { ...finalresult });
                                 resolve();
                                 return;
                             }
@@ -370,13 +370,13 @@ class Workflow extends EventEmitter {
                             } else {
                                 console.debug('enqueue step', nextStep, instanceId);
                                 await connection.enqueue(`${this.#queuePrefix}_${stepsName}_${nextStep}`, {
-                                stepsName: stepsName,
-                                goto: nextStep,
-                                state: mergedState,
-                                options: options,
-                                instanceId: instanceId
-                            });
-                            }                           
+                                    stepsName: stepsName,
+                                    goto: nextStep,
+                                    state: mergedState,
+                                    options: options,
+                                    instanceId: instanceId
+                                });
+                            }
                             this.emit('stepEnqueued', { workflowName: stepsName, step: nextStep, state: newState, instanceId });
                             resolve();
                         } catch (error) {
@@ -393,7 +393,7 @@ class Workflow extends EventEmitter {
         } catch (error) {
             console.error('error in handleNextStep outer', error.message);
             throw error;
-        }            
+        }
     }
 
     /**
@@ -424,15 +424,15 @@ class Workflow extends EventEmitter {
      * @private
      */
     async registerWithApp(app, name, description, definition) {
-        this.emit('workflowCreated', { name, description });        
+        this.emit('workflowCreated', { name, description });
 
         // Validate each step in the definition
         for (const [stepName, step] of Object.entries(definition)) {
             try {
                 if (stepName !== undefined) {
                     console.debug('registering queue for step', `${this.#queuePrefix}_${name}_${stepName}`);
-                    app.worker(`${this.#queuePrefix}_${name}_${stepName}`, async (req, res) => {                        
-                        try {                            
+                    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 this.handleNextStep(stepsName, goto, state, instanceId, options);
@@ -460,7 +460,7 @@ class Workflow extends EventEmitter {
         }
 
         // Store the definition
-        this.#definitions.set(name, definition);        
+        this.#definitions.set(name, definition);
 
         return name;
     }
@@ -472,13 +472,13 @@ class Workflow extends EventEmitter {
      * @throws {Error} If starting steps fails
      */
     async start(initialState) {
-        this.emit('workflowStarted', { name: this.#name, initialState });        
+        this.emit('workflowStarted', { name: this.#name, initialState });
 
         return new Promise(async (resolve, reject) => {
             try {
                 console.debug('Starting workflow', this.#name);
                 const funcs = this.#definitions.get(this.#name);
-                
+
                 if (!funcs) {
                     reject(new Error(`No workflow definition found for: ${this.#name}`));
                     return;
@@ -486,7 +486,7 @@ class Workflow extends EventEmitter {
 
                 const firstStepName = Object.keys(funcs)[0];
                 const firstStep = funcs[firstStepName];
-                
+
                 if (!firstStep) {
                     reject(new Error('No start step defined in workflow'));
                     return;
@@ -495,7 +495,7 @@ class Workflow extends EventEmitter {
                 const connection = await DB.open();
                 // Create a new workflow state in the database
                 const newState = await connection.insertOne(this.#collectionName,
-                    { ...initialState, nextStep: firstStepName, createdAt: new Date().toISOString(), workflowName: this.#name, stepCount: {  } });
+                    { ...initialState, nextStep: firstStepName, createdAt: new Date().toISOString(), workflowName: this.#name, stepCount: {} });
                 const { _id: ID } = await connection.enqueue(`${this.#queuePrefix}_${this.#name}_${firstStepName}`, {
                     stepsName: this.#name,
                     goto: firstStepName,
@@ -518,17 +518,17 @@ class Workflow extends EventEmitter {
      * @param {Object} options - Options for the update, { continue: false } to avoid continuing the the step
      * @returns {Promise<Object>} The updated state
      */
-    async updateState(instanceId, state, options={continue: true}) {
+    async updateState(instanceId, state, options = { continue: true }) {
         this.emit('stepsStateUpdating', { name: this.#name, instanceId, state });
         const connection = await DB.open();
         return new Promise(async (resolve, reject) => {
-            const doc = await connection.updateOne(this.#collectionName, 
-                { _id: instanceId }, 
+            const doc = await connection.updateOne(this.#collectionName,
+                { _id: instanceId },
                 { $set: { ...state, updatedAt: new Date().toISOString() } });
             if (options.continue) {
                 await this.continue(instanceId, false);
-            } 
-            resolve({ ...doc });                       
+            }
+            resolve({ ...doc });
         });
     }
 
@@ -549,7 +549,7 @@ class Workflow extends EventEmitter {
      * @returns {Promise<{qId: string}>} Queue ID for the continued step
      * @throws {Error} If steps instance not found
      */
-    async continue(instanceId, reset=false) {
+    async continue(instanceId, reset = false) {
         const connection = await DB.open();
         const state = await connection.findOne(this.#collectionName, { _id: instanceId });
         if (!state) {
@@ -565,10 +565,10 @@ class Workflow extends EventEmitter {
             // update the step count
             state.stepCount[state.nextStep] = { visits: 0, startTime: new Date().toISOString() };
         }
-        
+
         await connection.updateOne(this.#collectionName, { _id: instanceId }, { $set: { stepCount: state.stepCount } });
         console.debug('continue state', state);
-        this.emit('workflowContinued', { name: this.#name, step: state.nextStep, instanceId });                    
+        this.emit('workflowContinued', { name: this.#name, step: state.nextStep, instanceId });
 
         return new Promise(async (resolve, reject) => {
             const { _id: ID } = await connection.enqueue(`${this.#queuePrefix}_${this.#name}_${state.nextStep}`, {
@@ -589,7 +589,7 @@ class Workflow extends EventEmitter {
      */
     async continueAllTimedOut() {
         const db = await DB.open();
-        const timedOutWorkflows = await db.collection(this.#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) {
@@ -598,7 +598,7 @@ class Workflow extends EventEmitter {
             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._id, true);    
+                const result = await this.continue(workflow._id, true);
                 console.log('Continued:', result._id);
                 results.push(result);
             }
@@ -642,13 +642,40 @@ class Workflow extends EventEmitter {
         this.emit('cancelled', { id });
         return new Promise(async (resolve, reject) => {
             const connection = await DB.open();
-            const state = await connection.updateOne(this.#collectionName, 
-                { _id: id }, 
-                { $set: { status: 'cancelled' } });    
+            const state = await connection.updateOne(this.#collectionName,
+                { _id: id },
+                { $set: { status: 'cancelled' } });
             resolve(state);
         });
     }
 
+    /**
+     * Get the status of a workflow instance (alias for getStepsStatus)
+     * @param {string} id - ID of the workflow instance
+     * @returns {Promise<Object>} The workflow status
+     */
+    async getWorkflowStatus(id) {
+        return this.getStepsStatus(id);
+    }
+
+    /**
+     * Get the state of a workflow instance (alias for getStepsStatus)
+     * @param {string} id - ID of the workflow instance
+     * @returns {Promise<Object>} The workflow state
+     */
+    async getState(id) {
+        return this.getStepsStatus(id);
+    }
+
+    /**
+     * Cancel a workflow instance (alias for cancelSteps)
+     * @param {string} id - ID of the workflow instance to cancel
+     * @returns {Promise<Object>} The cancellation result
+     */
+    async cancelWorkflow(id) {
+        return this.cancelSteps(id);
+    }
+
     /**
      * Check if a specific step in a workflow instance has timed out
      * @param {Object} workflow - The workflow instance
@@ -658,7 +685,7 @@ class Workflow extends EventEmitter {
     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 {
@@ -669,12 +696,12 @@ class Workflow extends EventEmitter {
         }
 
         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) {
@@ -716,7 +743,7 @@ class Workflow extends EventEmitter {
      */
     async findTimedOutSteps(filter = {}) {
         const db = await DB.open();
-        const workflows = await db.getMany(this.#collectionName, {"nextStep": {$ne: null}}).toArray();
+        const workflows = await db.getMany(this.#collectionName, { "nextStep": { $ne: null } }).toArray();
         if (workflows.length > 0) {
             console.debug('TimedOutSteps', workflows.length);
         }