@onify/flow-extensions 9.1.0 → 10.0.0

package/dist/formatters.js

@@ -5,6 +5,9 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.FormatProcess = exports.FormatActivity = void 0;
 class FormatActivity {
+  /**
+   * @param {import('bpmn-elements').Activity} activity
+   */
   constructor(activity) {
     this.activity = activity;
     this.resultVariable = activity.behaviour.resultVariable;
@@ -18,7 +21,18 @@ class FormatActivity {
       }
     }
     this.timeCycles = timeCycles;
+    const {
+      documentation,
+      candidateUsers,
+      candidateGroups,
+      scheduledStart,
+      assignee
+    } = activity.behaviour;
+    this.hasFormatting = Boolean(this.resultVariable || candidateUsers || candidateGroups || assignee || documentation?.[0]?.text || scheduledStart && activity.parent?.type === 'bpmn:Process');
   }
+  /**
+   * @param {import('bpmn-elements').IApi<import('bpmn-elements').Activity>} elementApi
+   */
   resolve(elementApi) {
     let user, groups, assigneeValue, description;
     const activity = this.activity;
@@ -57,6 +71,9 @@ class FormatActivity {
 }
 exports.FormatActivity = FormatActivity;
 class FormatProcess {
+  /**
+   * @param {import('bpmn-elements').Process} bp
+   */
   constructor(bp) {
     this.process = bp;
     this._historyTTL = undefined;
@@ -64,6 +81,9 @@ class FormatProcess {
       this._historyTTL = bp.context.definitionContext.getTimersByElementId(bp.id).find(t => t.timer.type === 'historyTimeToLive');
     }
   }
+  /**
+   * @param {import('bpmn-elements').IApi<import('bpmn-elements').Process>} elementApi
+   */
   resolve(elementApi) {
     let user, groups, description;
     const bp = this.process;
@@ -91,6 +111,12 @@ class FormatProcess {
     };
   }
 }
+
+/**
+ * @param {import('bpmn-elements').IApi<import('bpmn-elements').Activity>} elementApi
+ * @param {string} str
+ * @returns {string[] | undefined}
+ */
 exports.FormatProcess = FormatProcess;
 function resolveAndSplit(elementApi, str) {
   if (Array.isArray(str)) return str.filter(Boolean);

package/dist/getExtensions.js

@@ -6,13 +6,29 @@ Object.defineProperty(exports, "__esModule", {
 exports.getExtensions = getExtensions;
 var _formatters = require("./formatters.js");
 var _IO = require("./IO.js");
-var _Connector = _interopRequireDefault(require("./Connector.js"));
-var _ExecutionListeners = _interopRequireDefault(require("./ExecutionListeners.js"));
-var _IOForm = _interopRequireDefault(require("./IOForm.js"));
-var _IOProperties = _interopRequireDefault(require("./IOProperties.js"));
-var _ServiceExpression = _interopRequireDefault(require("./ServiceExpression.js"));
-function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+var _Connector = require("./Connector.js");
+var _ExecutionListeners = require("./ExecutionListeners.js");
+var _IOForm = require("./IOForm.js");
+var _IOProperties = require("./IOProperties.js");
+var _ServiceExpression = require("./ServiceExpression.js");
+/**
+ * @typedef {object} OnifyExtensions assembled element extensions
+ * @property {FormatActivity | FormatProcess} [format] enter/end formatting
+ * @property {import('bpmn-elements').IActivityBehaviour} [Service] service factory
+ * @property {InputOutput} [io] camunda:InputOutput
+ * @property {IOProperties} [properties] camunda:Properties
+ * @property {IOForm} [form] camunda:FormData
+ * @property {ExecutionListeners} [listeners] camunda:ExecutionListener
+ */
+
+/**
+ * Assemble extensions for an element
+ * @param {import('bpmn-elements').Activity | import('bpmn-elements').Process} element
+ * @param {import('bpmn-elements').ContextInstance} context
+ * @returns {OnifyExtensions}
+ */
 function getExtensions(element, context) {
+  /** @type {OnifyExtensions} */
   const result = {};
   switch (element.type) {
     case 'bpmn:SequenceFlow':
@@ -24,21 +40,22 @@ function getExtensions(element, context) {
       result.format = new _formatters.FormatActivity(element);
   }
   let listenerPosition = 0;
-  const listeners = new _ExecutionListeners.default(element, context);
+  const listeners = new _ExecutionListeners.ExecutionListeners(element, context);
   const expression = element.behaviour.expression;
-  if (expression) result.Service = _ServiceExpression.default;
+  if (expression) result.Service = _ServiceExpression.ServiceExpression;
   const extensions = element.behaviour.extensionElements?.values;
-  if (extensions) {
+  if (Array.isArray(extensions)) {
     for (const ext of extensions) {
+      if (!ext) continue;
       switch (ext.$type) {
         case 'camunda:Properties':
-          if (ext.values?.length) result.properties = new _IOProperties.default(element, ext);
+          if (ext.values?.length) result.properties = new _IOProperties.IOProperties(element, ext);
           break;
         case 'camunda:InputOutput':
           result.io = new _IO.InputOutput(element.id, ext, context);
           break;
         case 'camunda:FormData':
-          if (ext.fields?.length) result.form = new _IOForm.default(element, ext);
+          if (ext.fields?.length) result.form = new _IOForm.IOForm(element, ext);
           break;
         case 'camunda:Connector':
           {
@@ -47,7 +64,7 @@ function getExtensions(element, context) {
               inputOutput
             } = ext;
             const io = inputOutput && new _IO.InputOutput(`${element.id}/${ext.$type.toLowerCase()}`, inputOutput, context);
-            result.Service = _Connector.default.bind(_Connector.default, connectorId, io);
+            result.Service = _Connector.Connector.bind(_Connector.Connector, connectorId, io);
             break;
           }
         case 'camunda:ExecutionListener':

package/dist/index.js

@@ -23,6 +23,12 @@ var _OnifyBoundaryEventExtensions = require("./OnifyBoundaryEventExtensions.js")
 var _OnifySubProcessExtensions = require("./OnifySubProcessExtensions.js");
 var _OnifySequenceFlow = require("./OnifySequenceFlow.js");
 var _OnifyTimerEventDefinition = require("./OnifyTimerEventDefinition.js");
+/**
+ * Onify flow extensions factory, pass to the engine as `extensions: { onify: extensions }`
+ * @param {import('bpmn-elements').ElementBase} element
+ * @param {import('bpmn-elements').ContextInstance} context
+ * @returns {import('bpmn-elements').IExtension}
+ */
 function extensions(element, context) {
   switch (element.type) {
     case 'bpmn:Process':
@@ -37,15 +43,18 @@ function extensions(element, context) {
       return new _OnifyElementExtensions.OnifyElementExtensions(element, context);
   }
 }
+
+/**
+ * Extend function for moddle-context-serializer, registers scripts and timers at serialize time
+ * @param {import('bpmn-moddle').BaseElement & Record<string, any>} behaviour
+ * @param {import('moddle-context-serializer').ExtendContext} context
+ */
 function extendFn(behaviour, context) {
   switch (behaviour.$type) {
     case 'bpmn:StartEvent':
       {
-        if (!behaviour.eventDefinitions) break;
-        const timer = behaviour.eventDefinitions.find(({
-          type,
-          behaviour: edBehaviour
-        }) => edBehaviour && type === 'bpmn:TimerEventDefinition');
+        if (!Array.isArray(behaviour.eventDefinitions)) break;
+        const timer = behaviour.eventDefinitions.find(ed => ed?.behaviour && ed.type === 'bpmn:TimerEventDefinition');
         if (timer && timer.behaviour.timeCycle) Object.assign(behaviour, {
           scheduledStart: timer.behaviour.timeCycle
         });
@@ -67,6 +76,7 @@ function extendFn(behaviour, context) {
   if (!Array.isArray(behaviour.extensionElements?.values)) return;
   let listener = 0;
   for (const extension of behaviour.extensionElements.values) {
+    if (!extension) continue;
     switch (extension.$type) {
       case 'camunda:InputOutput':
         registerIOScripts(behaviour.id, context, extension.$type, extension);
@@ -80,21 +90,26 @@ function extendFn(behaviour, context) {
     }
   }
 }
+
+/**
+ * @param {string} parentId
+ * @param {import('bpmn-elements').ContextInstance} context
+ * @param {string} type
+ * @param {{ inputParameters?: any[], outputParameters?: any[], [x:string]: any }} ioBehaviour
+ */
 function registerIOScripts(parentId, context, type, ioBehaviour) {
   if (!ioBehaviour) return;
   const {
-    inputParameters = [],
-    outputParameters = []
+    inputParameters,
+    outputParameters
   } = ioBehaviour;
-  for (const {
-    $type,
-    name,
-    definition
-  } of inputParameters.concat(outputParameters)) {
+  const parameters = [...(Array.isArray(inputParameters) ? inputParameters : []), ...(Array.isArray(outputParameters) ? outputParameters : [])];
+  for (const parm of parameters) {
+    const definition = parm?.definition;
     if (!definition) continue;
     if (definition.$type !== 'camunda:Script') continue;
-    const ioType = `${type}/${$type}`;
-    const filename = `${parentId}/${ioType}/${name}`;
+    const ioType = `${type}/${parm.$type}`;
+    const filename = `${parentId}/${ioType}/${parm.name}`;
     context.addScript(filename, {
       id: filename,
       scriptFormat: definition.scriptFormat,
@@ -108,6 +123,14 @@ function registerIOScripts(parentId, context, type, ioBehaviour) {
     });
   }
 }
+
+/**
+ * @param {string} parentId script parent id
+ * @param {import('bpmn-elements').ContextInstance} context
+ * @param {string} type
+ * @param {{event:string, script?: {scriptFormat:string, value?:string, resource?:string, [x:string]: any}, [x:string]: any}} listener
+ * @param {Number} pos
+ */
 function registerListenerScript(parentId, context, type, listener, pos) {
   const {
     event,
@@ -127,6 +150,10 @@ function registerListenerScript(parentId, context, type, listener, pos) {
     })
   });
 }
+
+/**
+ * @param {{id:string, $type:string, historyTimeToLive?:string, [x:string]: any}} behaviour
+ */
 function getHistoryTimeToLiveTimer(behaviour) {
   const {
     id,

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@onify/flow-extensions",
-  "version": "9.1.0",
+  "version": "10.0.0",
   "description": "Onify Flow extensions",
   "type": "module",
   "module": "src/index.js",
   "main": "dist/index.js",
-  "types": "./index.d.ts",
+  "types": "./types/index.d.ts",
   "sideEffects": false,
   "exports": {
     ".": {
@@ -21,10 +21,11 @@
   },
   "scripts": {
     "test": "mocha",
-    "posttest": "npm run lint && npm run dist && texample",
+    "posttest": "npm run lint && npm run types && npm run dist && texample",
     "lint": "eslint . --cache && prettier . --check --cache",
-    "prepare": "npm run dist",
+    "prepare": "npm run dist && npm run types",
     "dist": "babel src -d dist && babel test/helpers/FlowScripts.js -d dist",
+    "types": "dts-buddy types/index.d.ts -m @onify/flow-extensions:src/index.js -m @onify/flow-extensions/FlowScripts:test/helpers/FlowScripts.js",
     "test:lcov": "c8 -r lcov mocha && npm run lint",
     "cov:html": "c8 mocha && c8 report --reporter html"
   },
@@ -50,26 +51,33 @@
     "@babel/core": "^7.23.9",
     "@babel/preset-env": "^7.23.9",
     "@babel/register": "^7.23.7",
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^26.2.0",
+    "bpmn-elements": "^18.0.1",
+    "bpmn-elements-17": "npm:bpmn-elements@^17",
     "bpmn-elements-8-1": "npm:bpmn-elements@8.1",
-    "bpmn-engine": "^23.0.1",
-    "bpmn-engine-14": "npm:bpmn-engine@14",
+    "bpmn-engine": "^26.0.0",
+    "bpmn-engine-14": "npm:bpmn-engine@^14",
+    "bpmn-engine-25": "npm:bpmn-engine@^25",
     "bpmn-moddle": "^9.0.1",
-    "c8": "^10.1.2",
+    "c8": "^12.0.0",
     "camunda-bpmn-moddle": "^7.0.1",
-    "chai": "^5.0.3",
-    "chronokinesis": "^6.0.0",
+    "chai": "^6.2.1",
+    "chronokinesis": "^8.0.0",
     "debug": "^4.3.4",
-    "eslint": "^9.3.0",
+    "dts-buddy": "^0.8.3",
+    "eslint": "^10.5.0",
+    "globals": "^17.6.0",
     "mocha": "^11.0.1",
     "mocha-cakes-2": "^3.3.0",
-    "moddle-context-serializer": "^4.1.1",
-    "nock": "^14.0.1",
+    "moddle-context-serializer": "^6.0.1",
     "prettier": "^3.2.4",
-    "texample": "^0.0.8"
+    "texample": "^1.0.2",
+    "typescript": "^6.0.3"
   },
   "peerDependencies": {
     "@0dep/piso": ">=2",
-    "bpmn-elements": ">=14",
+    "bpmn-elements": ">=17",
     "croner": ">=9.0.0"
   },
   "files": [

package/src/Connector.js

@@ -1,6 +1,6 @@
 import { NotImplemented } from './Errors.js';
 
-export default function Connector(connectorId, io, activity, executionMessage) {
+export function Connector(connectorId, io, activity, executionMessage) {
   if (!(this instanceof Connector)) return new Connector(connectorId, io, activity, executionMessage);
   this.connectorId = connectorId;
   this.io = io;

package/src/ExecutionListeners.js

@@ -1,4 +1,9 @@
 class Listener {
+  /**
+   * @param {import('bpmn-elements').Activity | import('bpmn-elements').SequenceFlow} activity
+   * @param {import('bpmn-elements').ContextInstance} context
+   * @param {{$type:string, event:string, [x:string]: any}} extension
+   */
   constructor(activity, context, extension) {
     this.activity = activity;
     this.environment = this.activity.environment;
@@ -7,10 +12,21 @@ class Listener {
     this.type = extension.$type;
     this.event = extension.event;
   }
-  _getScope(message, extend) {
+  /**
+   * @param {import('bpmn-elements').IApi<any>} _api
+   * @returns {Promise<any>}
+   */
+  // eslint-disable-next-line no-unused-vars
+  execute(_api) {}
+  /**
+   * @internal
+   * @param {import('bpmn-elements').IApi<any>} api
+   * @param {Record<string, any>} [extend]
+   */
+  _getScope(api, extend) {
     const environment = this.environment;
 
-    const { fields, content, properties } = message;
+    const { fields, content, properties } = api;
     const scope = {
       ...extend,
       type: this.type,
@@ -29,6 +45,12 @@ class Listener {
 
     return scope;
   }
+  /**
+   * @internal
+   * @param {import('bpmn-elements').Environment} environment
+   * @param {any} scope
+   * @returns {Record<string, any>}
+   */
   _getFields(environment, scope) {
     const fields = this.extension.fields;
     if (!fields?.length) return;
@@ -41,6 +63,12 @@ class Listener {
 }
 
 class ScriptListener extends Listener {
+  /**
+   * @param {import('bpmn-elements').Activity | import('bpmn-elements').SequenceFlow} activity
+   * @param {import('bpmn-elements').ContextInstance} context
+   * @param {{script: {$type:string, [x:string]: any}, [x:string]: any}} extension
+   * @param {Number} pos execution listener position
+   */
   constructor(activity, context, extension, pos) {
     super(activity, context, extension);
     const id = (this.id = `${activity.id}/${extension.script.$type}/${this.event}/${pos}`);
@@ -85,16 +113,22 @@ class ScriptListener extends Listener {
 }
 
 class ExpressionListener extends Listener {
-  execute(message) {
-    const scope = this._getScope(message);
-    return { expression: this.environment.resolveExpression(this.extension.expression, scope) };
+  execute(api) {
+    const scope = this._getScope(api);
+    return Promise.resolve({ expression: this.environment.resolveExpression(this.extension.expression, scope) });
   }
 }
 
-export default class ExecutionListeners {
+export class ExecutionListeners {
+  /**
+   *
+   * @param {import('bpmn-elements').Activity | import('bpmn-elements').SequenceFlow} activity
+   * @param {import('bpmn-elements').ContextInstance} context
+   */
   constructor(activity, context) {
     this.activity = activity;
     this.context = context;
+    /** @type {(ScriptListener | ExpressionListener)[]} */
     this.listeners = [];
   }
   get length() {

package/src/IO.js

@@ -1,9 +1,17 @@
 export class IOBase {
   constructor(parm) {
+    /** @type {string} */
     this.name = parm.name;
+    /** @type {string} */
     this.type = (parm.definition && parm.definition.$type) || 'string';
+    /** @type {any} */
     this.behaviour = parm;
   }
+  /**
+   * @param {import('bpmn-elements').Activity} activity
+   * @param {import('bpmn-elements').ElementBrokerMessage} executionMessage
+   * @returns {Promise<{name: any}>}
+   */
   getValue(activity, executionMessage) {
     return {
       [this.name]: activity.environment.resolveExpression(this.behaviour.value, executionMessage),
@@ -12,9 +20,6 @@ export class IOBase {
 }
 
 class IOMap extends IOBase {
-  constructor(parm) {
-    super(parm);
-  }
   getValue(activity, executionMessage) {
     const name = this.name;
     const entries = this.behaviour.definition.entries;
@@ -110,28 +115,52 @@ export class IOScript extends IOBase {
 }
 
 export class InputOutput {
+  /**
+   * @param {string} parentId
+   * @param {any} behaviour
+   * @param {import('bpmn-elements').ContextInstance} context
+   */
   constructor(parentId, behaviour, context) {
     this.parentId = parentId;
     this.context = context;
-    const { inputParameters, outputParameters } = behaviour;
+    const { inputParameters, outputParameters } = behaviour ?? {};
     this.input = this._map(parentId, inputParameters, 'input', context);
     this.output = this._map(parentId, outputParameters, 'output', context);
   }
+  /**
+   * @param {import('bpmn-elements').Activity} activity
+   * @param {import('bpmn-elements').ElementBrokerMessage} executionMessage
+   * @returns {Promise<Record<string, any>}
+   */
   async getInput(activity, executionMessage) {
     const input = this.input;
     const values = await Promise.all(input.map((parm) => parm.getValue(activity, executionMessage)));
     return values.reduce((result, parm) => Object.assign(result, parm), {});
   }
+  /**
+   * @param {import('bpmn-elements').Activity} activity
+   * @param {import('bpmn-elements').ElementBrokerMessage} executionMessage
+   * @returns {Promise<Record<string, any>}
+   */
   async getOutput(activity, executionMessage) {
     const output = this.output;
     const values = await Promise.all(output.map((parm) => parm.getValue(activity, executionMessage)));
     return values.reduce((result, parm) => Object.assign(result, parm), {});
   }
+  /**
+   * @internal
+   * @param {string} parentId parent element id
+   * @param {any[]} list list of IO behaviours
+   * @param {string} ioType type of IO
+   * @param {import('bpmn-elements').ContextInstance} context
+   * @returns {IOBase[]}
+   */
   _map(parentId, list, ioType, context) {
     const mapped = [];
-    if (!list) return mapped;
+    if (!Array.isArray(list)) return mapped;
 
     for (const parm of list) {
+      if (!parm) continue;
       const definition = parm.definition;
       const type = definition && definition.$type;
       switch (type) {

package/src/IOForm.js

@@ -1,10 +1,14 @@
-import IOProperties from './IOProperties.js';
+import { IOProperties } from './IOProperties.js';
 
-export default class IOForm {
+export class IOForm {
   constructor(activity, behaviour) {
     this.activity = activity;
     this.behaviour = behaviour;
   }
+  /**
+   * @param {import('bpmn-elements').IApi<import('bpmn-elements').Activity>} elementApi
+   * @returns {Record<string, any>}
+   */
   resolve(elementApi) {
     const form = {};
     for (const field of this.behaviour.fields) {

package/src/IOProperties.js

@@ -1,8 +1,12 @@
-export default class IOProperties {
+export class IOProperties {
   constructor(activity, behaviour) {
     this.activity = activity;
     this.behaviour = behaviour;
   }
+  /**
+   * @param {elementApi: import('bpmn-elements').IApi<any>} elementApi
+   * @returns {Record<string, any>}
+   */
   resolve(elementApi) {
     const properties = {};
 

package/src/OnifyBoundaryEventExtensions.js

@@ -1,28 +1,33 @@
 import { OnifyElementExtensions } from './OnifyElementExtensions.js';
 
 export class OnifyBoundaryEventExtensions extends OnifyElementExtensions {
+  #syncFormatOnEnter;
   constructor(activity, context) {
     super(activity, context);
-    this._syncFormatOnEnter = this._syncFormatOnEnter.bind(this);
+    this.#syncFormatOnEnter = this._syncFormatOnEnter.bind(this);
   }
   activate(message) {
     const activity = this.activity;
     const formatQ = activity.broker.getQueue('format-run-q');
     const executionListeners = this.extensions.listeners;
 
-    if (message.fields.redelivered && message.fields.routingKey === 'run.start') {
-      activity.on('start', this._syncFormatOnEnter, { consumerTag: '_onify-extension-on-enter' });
-    } else {
-      activity.on('enter', this._syncFormatOnEnter, { consumerTag: '_onify-extension-on-enter' });
+    if (this._formatOnEnter) {
+      if (message.fields.redelivered && message.fields.routingKey === 'run.start') {
+        activity.on('start', this.#syncFormatOnEnter, { consumerTag: '_onify-extension-on-enter' });
+      } else {
+        activity.on('enter', this.#syncFormatOnEnter, { consumerTag: '_onify-extension-on-enter' });
+      }
     }
 
-    activity.on(
-      'activity.execution.completed',
-      (elementApi) => {
-        return this._onExecutionCompleted(elementApi, formatQ);
-      },
-      { consumerTag: '_onify-extension-on-executed' },
-    );
+    if (this._formatOnEnd) {
+      activity.on(
+        'activity.execution.completed',
+        (elementApi) => {
+          return this._onExecutionCompleted(elementApi, formatQ);
+        },
+        { consumerTag: '_onify-extension-on-executed' }
+      );
+    }
 
     if (executionListeners?.onStart) {
       activity.on(
@@ -34,7 +39,7 @@ export class OnifyBoundaryEventExtensions extends OnifyElementExtensions {
             return activity.logger.error(`<${activity.id}> execution listener error`, err);
           }
         },
-        { consumerTag: '_onify-extension-on-listenerstart' },
+        { consumerTag: '_onify-extension-on-listenerstart' }
       );
     }
     if (executionListeners?.onEnd) {
@@ -43,10 +48,15 @@ export class OnifyBoundaryEventExtensions extends OnifyElementExtensions {
         (elementApi) => {
           this._executeExecutionListener('end', elementApi, formatQ);
         },
-        { consumerTag: '_onify-extension-on-listenerend' },
+        { consumerTag: '_onify-extension-on-listenerend' }
       );
     }
   }
+  /**
+   * @internal
+   * @param {import('bpmn-elements').IApi<import('bpmn-elements').Activity>} elementApi
+   * @returns {void}
+   */
   _syncFormatOnEnter(elementApi) {
     try {
       var format = this._onEnterSync(elementApi);
@@ -56,6 +66,11 @@ export class OnifyBoundaryEventExtensions extends OnifyElementExtensions {
 
     elementApi.broker.publish('format', 'run.enter.complete', format, { persistent: false });
   }
+  /**
+   * @internal
+   * @param {import('bpmn-elements').IApi<import('bpmn-elements').Activity>} elementApi
+   * @returns {void}
+   */
   _onEnterSync(elementApi) {
     const { format, properties, io } = this.extensions;