@onify/flow-extensions 9.1.1 → 10.0.1

package/src/OnifyElementExtensions.js

@@ -1,34 +1,52 @@
 import { getExtensions } from './getExtensions.js';
 
 export class OnifyElementExtensions {
+  /**
+   * @param {import('bpmn-elements').Activity} activity
+   * @param {import('bpmn-elements').ContextInstance} context
+   */
   constructor(activity, context) {
     this.activity = activity;
     this.context = context;
     this.formatQ = activity.broker.getQueue('format-run-q');
     this._asyncFormatOnEnter = this._asyncFormatOnEnter.bind(this);
 
-    const { Service } = (this.extensions = getExtensions(activity, context));
+    const { Service, format, properties, io, form } = (this.extensions = getExtensions(activity, context));
     if (Service) {
       activity.behaviour.Service = Service;
     }
+
+    this._formatOnEnter = Boolean(format?.hasFormatting || properties || form || io?.input.length || io?.output.length);
+    this._formatOnEnd = Boolean(properties || io?.output.length || format?.resultVariable);
+  }
+  /**
+   * No camunda extension data to act on — the element runs without this extension
+   * @returns {boolean}
+   */
+  get isEmpty() {
+    return !this._formatOnEnter && !this._formatOnEnd && !this.extensions.listeners && !this.extensions.Service;
   }
   activate(message) {
     const activity = this.activity;
     const executionListeners = this.extensions.listeners;
 
-    if (message.fields.redelivered && message.fields.routingKey === 'run.start') {
-      activity.on('start', this._asyncFormatOnEnter, { consumerTag: '_onify-extension-on-enter' });
-    } else {
-      activity.on('enter', this._asyncFormatOnEnter, { consumerTag: '_onify-extension-on-enter' });
+    if (this._formatOnEnter) {
+      if (message.fields.redelivered && message.fields.routingKey === 'run.start') {
+        activity.on('start', this._asyncFormatOnEnter, { consumerTag: '_onify-extension-on-enter' });
+      } else {
+        activity.on('enter', this._asyncFormatOnEnter, { consumerTag: '_onify-extension-on-enter' });
+      }
     }
 
-    activity.on(
-      'activity.execution.completed',
-      (elementApi) => {
-        return this._onExecutionCompleted(elementApi);
-      },
-      { consumerTag: '_onify-extension-on-executed' }
-    );
+    if (this._formatOnEnd) {
+      activity.on(
+        'activity.execution.completed',
+        (elementApi) => {
+          return this._onExecutionCompleted(elementApi);
+        },
+        { consumerTag: '_onify-extension-on-executed' }
+      );
+    }
 
     if (executionListeners?.onStart) {
       activity.on(

package/src/OnifyProcessExtensions.js

@@ -2,6 +2,10 @@ import { FormatError } from './Errors.js';
 import { getExtensions } from './getExtensions.js';
 
 export class OnifyProcessExtensions {
+  /**
+   * @param {import('bpmn-elements').Process} bp
+   * @param {import('bpmn-elements').ContextInstance} context
+   */
   constructor(bp, context) {
     this.process = bp;
     this.context = context;

package/src/OnifySequenceFlow.js

@@ -2,30 +2,38 @@ import { SequenceFlow } from 'bpmn-elements';
 import { getExtensions } from './getExtensions.js';
 
 export class OnifySequenceFlow extends SequenceFlow {
+  /**
+   * @param {import('bpmn-elements').SequenceFlowDefinition} flowDef
+   * @param {import('bpmn-elements').ContextInstance} context
+   */
   constructor(flowDef, context) {
     super(flowDef, context);
     this.extensions = getExtensions(this, context);
-    this._activate();
+    this.#activate();
   }
-  _activate() {
+  #activate() {
     if (!this.extensions.listeners?.onTake) return;
 
     this.broker.subscribeTmp(
       'event',
       'flow.take',
       (_, msg) => {
-        this._executeListeners(msg);
+        this.#executeListeners(msg);
       },
       { noAck: true, consumerTag: '_onify-execution-listener' }
     );
   }
-  async _executeListeners(message) {
+  async #executeListeners(message) {
     try {
       await this.extensions.listeners.execute('take', message);
     } catch (err) {
       this.logger.error(`<${this.id}> execution listener error: ${err}`);
     }
   }
+  /**
+   * @param {import('bpmn-elements').ElementBrokerMessage} fromMessage
+   * @param {(err: Error | null, result?: boolean | unknown) => void} callback
+   */
   evaluate(fromMessage, callback) {
     const properties = this.extensions.properties;
     if (!properties) return super.evaluate(fromMessage, callback);

package/src/OnifySubProcessExtensions.js

@@ -1,43 +1,44 @@
 import { OnifyElementExtensions } from './OnifyElementExtensions.js';
 
 export class OnifySubProcessExtensions extends OnifyElementExtensions {
-  constructor(activity, context) {
-    super(activity, context);
-  }
   activate(runMessage) {
     const activity = this.activity;
     const broker = activity.broker;
     const executionListeners = this.extensions.listeners;
 
-    if (runMessage.fields.redelivered && runMessage.fields.routingKey === 'run.start') {
-      this._setupListener(
-        broker,
-        'activity.start',
-        (elementApi) => {
-          return this._asyncFormatOnEnter(elementApi);
-        },
-        '_onify-extension-on-enter'
-      );
-    } else {
+    if (this._formatOnEnter) {
+      if (runMessage.fields.redelivered && runMessage.fields.routingKey === 'run.start') {
+        this._setupListener(
+          broker,
+          'activity.start',
+          (elementApi) => {
+            return this._asyncFormatOnEnter(elementApi);
+          },
+          '_onify-extension-on-enter'
+        );
+      } else {
+        this._setupListener(
+          broker,
+          'activity.enter',
+          (elementApi) => {
+            return this._asyncFormatOnEnter(elementApi);
+          },
+          '_onify-extension-on-enter'
+        );
+      }
+    }
+
+    if (this._formatOnEnd) {
       this._setupListener(
         broker,
-        'activity.enter',
+        'activity.execution.completed',
         (elementApi) => {
-          return this._asyncFormatOnEnter(elementApi);
+          return this._onExecutionCompleted(elementApi);
         },
-        '_onify-extension-on-enter'
+        '_onify-extension-on-executed'
       );
     }
 
-    this._setupListener(
-      broker,
-      'activity.execution.completed',
-      (elementApi) => {
-        return this._onExecutionCompleted(elementApi);
-      },
-      '_onify-extension-on-executed'
-    );
-
     if (executionListeners?.onStart) {
       this._setupListener(
         broker,

package/src/OnifyTimerEventDefinition.js

@@ -2,12 +2,18 @@ import { Cron } from 'croner';
 import { TimerEventDefinition } from 'bpmn-elements';
 
 export class OnifyTimerEventDefinition extends TimerEventDefinition {
-  constructor(activity, def) {
-    super(activity, def);
-    Object.defineProperty(this, 'supports', {
-      value: ['cron', 'iso8601'],
-    });
+  /**
+   * Supported timeCycle formats
+   * @returns {string[]}
+   */
+  get supports() {
+    return ['cron', 'iso8601'];
   }
+  /**
+   * @param {import('bpmn-elements').TimerType} timerType
+   * @param {string} value
+   * @returns {import('bpmn-elements').parsedTimer}
+   */
   parse(timerType, value) {
     if (timerType === 'timeCycle') {
       try {
@@ -27,7 +33,7 @@ export class OnifyTimerEventDefinition extends TimerEventDefinition {
         this.logger.error(`<${this.activity?.id}> failed to parse timeCycle: ${rangeError.message}`);
         this.logger.error(`<${this.activity?.id}> failed to parse timeCycle as cron: ${err.message}`);
 
-        throw new RangeError(`Failed to parse timeCycle <${value?.substring(0, 255)}> as ISO 8601 interval or cron`);
+        throw new RangeError(`Failed to parse timeCycle <${value?.substring(0, 255)}> as ISO 8601 interval or cron`, { cause: err });
       }
     }
 

package/src/ServiceExpression.js

@@ -1,6 +1,6 @@
 import { NotImplemented } from './Errors.js';
 
-export default function ServiceExpression(activity) {
+export function ServiceExpression(activity) {
   if (!(this instanceof ServiceExpression)) return new ServiceExpression(activity);
   this.activity = activity;
   this.type = `${activity.type}:expression`;

package/src/formatters.js

@@ -1,4 +1,7 @@
 export class FormatActivity {
+  /**
+   * @param {import('bpmn-elements').Activity} activity
+   */
   constructor(activity) {
     this.activity = activity;
     this.resultVariable = activity.behaviour.resultVariable;
@@ -13,7 +16,20 @@ export 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;
@@ -36,6 +52,9 @@ export class FormatActivity {
 }
 
 export class FormatProcess {
+  /**
+   * @param {import('bpmn-elements').Process} bp
+   */
   constructor(bp) {
     this.process = bp;
     this._historyTTL = undefined;
@@ -43,6 +62,9 @@ export 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;
@@ -61,6 +83,11 @@ export class FormatProcess {
   }
 }
 
+/**
+ * @param {import('bpmn-elements').IApi<import('bpmn-elements').Activity>} elementApi
+ * @param {string} str
+ * @returns {string[] | undefined}
+ */
 function resolveAndSplit(elementApi, str) {
   if (Array.isArray(str)) return str.filter(Boolean);
   if (typeof str !== 'string') return;

package/src/getExtensions.js

@@ -1,12 +1,29 @@
 import { FormatActivity, FormatProcess } from './formatters.js';
 import { InputOutput } from './IO.js';
-import Connector from './Connector.js';
-import ExecutionListeners from './ExecutionListeners.js';
-import IOForm from './IOForm.js';
-import IOProperties from './IOProperties.js';
-import ServiceExpression from './ServiceExpression.js';
+import { Connector } from './Connector.js';
+import { ExecutionListeners } from './ExecutionListeners.js';
+import { IOForm } from './IOForm.js';
+import { IOProperties } from './IOProperties.js';
+import { ServiceExpression } from './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}
+ */
 export function getExtensions(element, context) {
+  /** @type {OnifyExtensions} */
   const result = {};
 
   switch (element.type) {
@@ -26,8 +43,9 @@ export function getExtensions(element, context) {
   if (expression) result.Service = 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(element, ext);

package/src/index.js

@@ -6,6 +6,12 @@ import { OnifySubProcessExtensions } from './OnifySubProcessExtensions.js';
 export { OnifySequenceFlow } from './OnifySequenceFlow.js';
 export { OnifyTimerEventDefinition } from './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 | undefined} undefined for an element without camunda extension data, letting bpmn-elements skip it (and e.g. attach its built-in `assignOutput` extension)
+ */
 export function extensions(element, context) {
   switch (element.type) {
     case 'bpmn:Process':
@@ -16,19 +22,25 @@ export function extensions(element, context) {
       return new OnifySubProcessExtensions(element, context);
     case 'bpmn:BoundaryEvent':
       return new OnifyBoundaryEventExtensions(element, context);
-    default:
-      return new OnifyElementExtensions(element, context);
+    default: {
+      const elementExtensions = new OnifyElementExtensions(element, context);
+      if (elementExtensions.isEmpty) return undefined;
+      return elementExtensions;
+    }
   }
 }
 
+/**
+ * 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
+ */
 export function extendFn(behaviour, context) {
   switch (behaviour.$type) {
     case 'bpmn:StartEvent': {
-      if (!behaviour.eventDefinitions) break;
+      if (!Array.isArray(behaviour.eventDefinitions)) break;
 
-      const timer = behaviour.eventDefinitions.find(
-        ({ type, behaviour: edBehaviour }) => edBehaviour && type === 'bpmn:TimerEventDefinition'
-      );
+      const timer = behaviour.eventDefinitions.find((ed) => ed?.behaviour && ed.type === 'bpmn:TimerEventDefinition');
       if (timer && timer.behaviour.timeCycle) Object.assign(behaviour, { scheduledStart: timer.behaviour.timeCycle });
 
       break;
@@ -50,6 +62,7 @@ export function extendFn(behaviour, context) {
 
   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);
@@ -64,16 +77,27 @@ export 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 = [] } = ioBehaviour;
-  for (const { $type, name, definition } of inputParameters.concat(outputParameters)) {
+  const { inputParameters, outputParameters } = ioBehaviour;
+  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,
@@ -85,6 +109,13 @@ 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, script } = listener;
   if (!script) return;
@@ -99,6 +130,9 @@ function registerListenerScript(parentId, context, type, listener, pos) {
   });
 }
 
+/**
+ * @param {{id:string, $type:string, historyTimeToLive?:string, [x:string]: any}} behaviour
+ */
 function getHistoryTimeToLiveTimer(behaviour) {
   const { id, $type: type, historyTimeToLive } = behaviour;