fix FlowScript type declaration

Author: paed01

CHANGELOG.md

@@ -2,6 +2,11 @@
 
 # unreleased
 
+# 8.3.0
+
+- fix `FlowScripts` type declaration
+- throw `FlowResourceError` if failing to get script resource content
+
 # 8.2.2
 
 - bump [0dep/piso@2](https://www.npmjs.com/package/@0dep/piso)

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onify/flow-extensions",
-  "version": "8.2.2",
+  "version": "8.3.0",
   "description": "Onify Flow extensions",
   "type": "module",
   "module": "src/index.js",
@@ -52,7 +52,7 @@
     "@babel/register": "^7.23.7",
     "bpmn-elements": "^15.0.3",
     "bpmn-elements-8-1": "npm:[email protected]",
-    "bpmn-engine": "^21.1.0",
+    "bpmn-engine": "^22.0.2",
     "bpmn-engine-14": "npm:bpmn-engine@14",
     "bpmn-moddle": "^9.0.1",
     "c8": "^10.1.2",

test/features/scripts-feature.js

@@ -389,7 +389,8 @@ Feature('Flow scripts', () => {
 
     Then('an Error is thrown indicating input script failed', async () => {
       const err = await error;
-      expect(err.content.error.message).to.equal('command-definition/bpmn:ScriptTask/task: script resource ./io-sripts.js not found');
+      expect(err.content.error.message).to.match(/ENOENT/i);
+      expect(err.content.error.code).to.equal('EFLOW_SCRIPT');
     });
   });
 

test/helpers/FlowScripts.js

@@ -1,11 +1,11 @@
-import { join } from 'path';
-import { promises as fs } from 'fs';
-import { Script } from 'vm';
+import { join } from 'node:path';
+import { promises as fs } from 'node:fs';
+import { Script } from 'node:vm';
 
 const kSyntaxError = Symbol.for('syntax error');
 const kResources = Symbol.for('resources base');
 
-class FlowScriptError extends Error {
+export class FlowScriptError extends Error {
   constructor(fromErr) {
     super(fromErr.message);
     this.name = this.constructor.name;
@@ -23,11 +23,11 @@ class FlowScriptError extends Error {
     });
   }
   toString() {
-    return '[FlowScriptError] ' + this.message + '\n' + this.stack;
+    return '[' + this.name + '] ' + this.message + '\n' + this.stack;
   }
 }
 
-class FlowSyntaxError extends Error {
+export class FlowSyntaxError extends Error {
   constructor(fromErr) {
     super(fromErr.message);
     this.name = this.constructor.name;
@@ -45,17 +45,23 @@ class FlowSyntaxError extends Error {
     });
   }
   toString() {
-    return '[FlowSyntaxError] ' + this.message + '\n' + this.stack;
+    return '[' + this.name + '] ' + this.message + '\n' + this.stack;
   }
 }
 
-export { FlowScripts, JavaScript, JavaScriptResource };
+export class FlowResourceError extends FlowScriptError {
+  constructor(fromErr, filename) {
+    super(fromErr);
+    this.filename = filename;
+    this.inner = fromErr;
+  }
+}
 
-function FlowScripts(flowName, resourceBase, runContext, timeout = 60000) {
-  this._name = flowName;
-  this._scripts = {};
-  this._timeout = timeout;
-  this._runContext = runContext;
+export function FlowScripts(flowName, resourceBase, runContext, timeout = 60000) {
+  this.flowName = flowName;
+  this.scripts = new Map();
+  this.timeout = timeout;
+  this.runContext = runContext;
   this[kResources] = resourceBase;
 }
 
@@ -83,22 +89,33 @@ FlowScripts.prototype.register = function register({ id, type, behaviour }) {
 
   language = 'javascript';
 
-  const name = this._name;
-  const filename = `${name}/${type}/${id}`;
+  const flowName = this.flowName;
+  const filename = `${flowName}/${type}/${id}`;
   if (scriptBody) {
-    this._scripts[id] = new JavaScript(name, scriptBody, this._runContext, { filename, timeout: this._timeout });
+    this.scripts.set(id, new JavaScript(flowName, scriptBody, this.runContext, { filename, timeout: this.timeout }));
   } else if (resource) {
-    this._scripts[id] = new JavaScriptResource(name, resource, this[kResources], this._runContext, { filename, timeout: this._timeout });
+    this.scripts.set(
+      id,
+      new JavaScriptResource(flowName, resource, this[kResources], this.runContext, { filename, timeout: this.timeout }),
+    );
   }
 };
 
 FlowScripts.prototype.getScript = function getScript(scriptType, { id }) {
-  return this._scripts[id];
+  return this.scripts.get(id);
 };
 
-function JavaScript(flowName, scriptBody, runContext, options) {
+/**
+ * Java script
+ * @param {string} flowName
+ * @param {string|Buffer} scriptBody
+ * @param {any} [runContext]
+ * @param {import('node:vm').ScriptOptions} options
+ */
+export function JavaScript(flowName, scriptBody, runContext, options) {
   this.flowName = flowName;
-  this._runContext = runContext;
+  this.options = options;
+  this.runContext = runContext;
   this.timeout = options?.timeout;
 
   try {
@@ -124,7 +141,7 @@ JavaScript.prototype.execute = async function execute(executionContext, callback
           from: Buffer.from,
         },
         contextName: this.flowName,
-        ...this._runContext,
+        ...this.runContext,
         next,
       },
       {
@@ -143,28 +160,43 @@ JavaScript.prototype.execute = async function execute(executionContext, callback
   }
 };
 
-function JavaScriptResource(flowName, resource, resourceBase, runContext, options) {
+export function JavaScriptResource(flowName, resource, resourceBase, runContext, options) {
   this.flowName = flowName;
   this.resource = resource;
+  this.runContext = runContext;
   this.options = options;
-  this._runContext = runContext;
-  this[kResources] = resourceBase;
+  this.timeout = options?.timeout;
+  this.resourceBase = resourceBase;
 }
 
+/**
+ * Get javascript resource content
+ * @param {string} resourceBase Resource base
+ * @param {*} resource Resource name or path
+ * @returns {Promise<string|Buffer} Resource content
+ */
+JavaScriptResource.prototype.getResourceContent = function getResourceContent(resourceBase, resource) {
+  return fs.readFile(join(resourceBase, resource));
+};
+
 JavaScriptResource.prototype.execute = async function execute(executionContext, callback) {
   let resource;
   try {
     resource = executionContext.resolveExpression(this.resource);
-    var scriptBody = await fs.readFile(join(this[kResources], resource)); // eslint-disable-line no-var
+    var scriptBody = await this.getResourceContent(this.resourceBase, resource); // eslint-disable-line no-var
+    if (!scriptBody) throw new TypeError(`${this.options.filename}: script resource ${resource || this.resource} is empty`);
   } catch (err) {
     if (err instanceof SyntaxError) {
       return callback(err);
     }
-    const { filename } = this.options;
-    return callback(new Error(`${filename}: script resource ${resource || this.resource} not found`));
+    return callback(new FlowResourceError(err, this.options.filename));
+  }
+
+  if (!scriptBody) {
+    throw new FlowResourceError();
   }
 
-  const script = new JavaScript(this.flowName, scriptBody, this._runContext, {
+  const script = new JavaScript(this.flowName, scriptBody, this.runContext, {
     ...this.options,
     filename: `${this.options.filename}/${resource}`,
   });

test/helpers/factory.js

@@ -1,5 +1,5 @@
-import fs from 'fs';
-import path from 'path';
+import fs from 'node:fs';
+import path from 'node:path';
 
 export default {
   resource,

test/helpers/testHelpers.js

@@ -1,12 +1,13 @@
-import { Serializer, TypeResolver } from 'moddle-context-serializer';
+import fs from 'node:fs/promises';
+import BpmnModdle from 'bpmn-moddle';
+import Debug from 'debug';
 import { Engine } from 'bpmn-engine';
-import { extensions, extendFn } from '../../src/index.js';
-import { FlowScripts } from './FlowScripts.js';
-import { promises as fs } from 'fs';
+import { Serializer, TypeResolver } from 'moddle-context-serializer';
 import * as Elements from 'bpmn-elements';
 import * as expressions from '@aircall/expression-parser';
-import BpmnModdle from 'bpmn-moddle';
-import Debug from 'debug';
+
+import { FlowScripts } from './FlowScripts.js';
+import { extensions, extendFn } from '../../src/index.js';
 import { OnifyTimerEventDefinition as TimerEventDefinition } from '../../src/OnifyTimerEventDefinition.js';
 
 let exts;

types/index.d.ts

@@ -1,5 +1,5 @@
 declare module '@onify/flow-extensions' {
-  import { SequenceFlow, TimerEventDefinition, ElementBase, IExtension, ContextInstance } from 'bpmn-elements';
+  import { SequenceFlow, TimerEventDefinition, ElementBase, IExtension, ContextInstance, SequenceFlow } from 'bpmn-elements';
   import { extendFn as extendFunction } from 'moddle-context-serializer';
 
   export class OnifySequenceFlow extends SequenceFlow {}
@@ -11,6 +11,48 @@ declare module '@onify/flow-extensions' {
 }
 
 declare module '@onify/flow-extensions/FlowScripts' {
-  import { IScripts } from 'bpmn-elements';
-  export var FlowScripts: IScripts;
+  import { IScripts, Script, ExecutionScope } from 'bpmn-elements';
+  import { SerializableElement } from 'moddle-context-serializer';
+  import { ScriptOptions } from 'node:vm';
+
+  declare type registerArgument = SerializableElement | { id: string; type: string; behavior: any };
+
+  export interface FlowScriptOptions extends ScriptOptions {
+    timeout?: number;
+  }
+
+  export class FlowScripts implements IScripts {
+    /**
+     * @param flowName Flow name
+     * @param resourceBase External resource base
+     * @param runContext Optional script globals
+     * @param timeout Optional execution timeout in milliseconds, default 60000
+     */
+    constructor(flowName: string, resourceBase: string, runContext?: any, timeout?: number);
+    flowName: string;
+    timeout: number;
+    /** Registered scripts */
+    get scripts(): Map<string, Script | JavaScriptResource>;
+    /** Registered scripts */
+    register(element: registerArgument): Script | undefined;
+    getScript(language: string, identifier: { id: string; [x: string]: any }): Script;
+  }
+
+  export class JavaScript implements Script {
+    constructor(flowName: string, scriptBody: string | Buffer, runContext: any, options?: FlowScriptOptions);
+    get flowName(): string;
+    get runContext(): unknown;
+    get options(): FlowScriptOptions;
+    execute(executionContext: ExecutionScope, callback: CallableFunction): void;
+  }
+
+  export class JavaScriptResource extends JavaScript {
+    constructor(flowName: string, resource: string, resourceBase: string, runContext?: unknown, options?: FlowScriptOptions);
+    /**
+     * Get javascript resource content
+     * @param resourceBase Resource base
+     * @param resource Resolved resource name or path
+     */
+    getResourceContent(resourceBase: string, resource: string): Promise<string | Buffer>;
+  }
 }