bpmn-elements 17.2.2 → 18.0.0

package/src/activity/ActivityExecution.js

@@ -1,49 +1,57 @@
 import { ActivityApi } from '../Api.js';
 import { cloneContent, cloneMessage } from '../messageHelper.js';
-
-const kCompleted = Symbol.for('completed');
-const kExecuteQ = Symbol.for('executeQ');
-const kExecuteMessage = Symbol.for('executeMessage');
-const kMessageHandlers = Symbol.for('messageHandlers');
-const kPostponed = Symbol.for('postponed');
-
-export default ActivityExecution;
-
-function ActivityExecution(activity, context) {
+import { K_COMPLETED, K_EXECUTE_MESSAGE, K_MESSAGE_HANDLERS } from '../constants.js';
+
+const K_EXECUTE_Q = Symbol.for('executeQ');
+const K_POSTPONED = Symbol.for('postponed');
+
+/**
+ * Per-run execution orchestrator for an Activity. Instantiates the element-specific behaviour
+ * and drives the execute message flow over the activity broker.
+ * @param {import('./Activity.js').Activity} activity
+ * @param {import('../Context.js').ContextInstance} context
+ */
+export function ActivityExecution(activity, context) {
   this.activity = activity;
   this.context = context;
   this.id = activity.id;
   this.broker = activity.broker;
-  this[kPostponed] = new Set();
-  this[kCompleted] = false;
-  this[kExecuteQ] = this.broker.assertQueue('execute-q', { durable: true, autoDelete: false });
+  this[K_POSTPONED] = new Set();
+  this[K_COMPLETED] = false;
+  this[K_EXECUTE_Q] = this.broker.assertQueue('execute-q', { durable: true, autoDelete: false });
 
-  this[kMessageHandlers] = {
+  this[K_MESSAGE_HANDLERS] = {
     onParentApiMessage: this._onParentApiMessage.bind(this),
     onExecuteMessage: this._onExecuteMessage.bind(this),
   };
 }
 
 Object.defineProperty(ActivityExecution.prototype, 'completed', {
+  /** @returns {boolean} */
   get() {
-    return this[kCompleted];
+    return this[K_COMPLETED];
   },
 });
 
+/**
+ * Begin executing the activity behaviour. Resumes if the message is redelivered.
+ * @param {import('#types').ElementBrokerMessage} executeMessage
+ * @throws {Error} when message or executionId is missing
+ */
 ActivityExecution.prototype.execute = function execute(executeMessage) {
   if (!executeMessage) throw new Error('Execution requires message');
   const executionId = executeMessage.content?.executionId;
   if (!executionId) throw new Error('Execution requires execution id');
 
   this.executionId = executionId;
-  const initMessage = (this[kExecuteMessage] = cloneMessage(executeMessage, {
+  const initMessage = (this[K_EXECUTE_MESSAGE] = cloneMessage(executeMessage, {
     executionId,
     state: 'start',
     isRootScope: true,
   }));
 
   if (executeMessage.fields.redelivered) {
-    this[kPostponed].clear();
+    this[K_POSTPONED].clear();
     this._debug('resume execution');
 
     if (!this.source) this.source = new this.activity.Behaviour(this.activity, this.context);
@@ -58,22 +66,25 @@ ActivityExecution.prototype.execute = function execute(executeMessage) {
   this.broker.publish('execution', 'execute.start', cloneContent(initMessage.content));
 };
 
+/**
+ * Bind the execute queue and start consuming execute and api messages.
+ */
 ActivityExecution.prototype.activate = function activate() {
-  if (this[kCompleted]) return;
+  if (this[K_COMPLETED]) return;
 
   const broker = this.broker;
   const batchSize = this.activity.environment.settings.batchSize || 50;
   broker.bindQueue('execute-q', 'execution', 'execute.#', { priority: 100 });
 
-  const { onExecuteMessage, onParentApiMessage } = this[kMessageHandlers];
-  this[kExecuteQ].assertConsumer(onExecuteMessage, {
+  const { onExecuteMessage, onParentApiMessage } = this[K_MESSAGE_HANDLERS];
+  this[K_EXECUTE_Q].assertConsumer(onExecuteMessage, {
     exclusive: true,
     prefetch: batchSize * 2,
     priority: 100,
     consumerTag: '_activity-execute',
   });
 
-  if (this[kCompleted]) return this.deactivate();
+  if (this[K_COMPLETED]) return this.deactivate();
 
   broker.subscribeTmp('api', `activity.*.${this.executionId}`, onParentApiMessage, {
     noAck: true,
@@ -82,6 +93,9 @@ ActivityExecution.prototype.activate = function activate() {
   });
 };
 
+/**
+ * Cancel execute and api consumers and unbind the execute queue.
+ */
 ActivityExecution.prototype.deactivate = function deactivate() {
   const broker = this.broker;
   broker.cancel('_activity-api-execution');
@@ -89,16 +103,24 @@ ActivityExecution.prototype.deactivate = function deactivate() {
   broker.unbindQueue('execute-q', 'execution', 'execute.#');
 };
 
+/**
+ * Discard the running execution.
+ */
 ActivityExecution.prototype.discard = function discard() {
-  if (this[kCompleted]) return;
-  const initMessage = this[kExecuteMessage];
+  if (this[K_COMPLETED]) return;
+  const initMessage = this[K_EXECUTE_MESSAGE];
   if (!initMessage) return this.activity.logger.warn(`<${this.id}> is not executing`);
   this.getApi(initMessage).discard();
 };
 
+/**
+ * Resolve an Api wrapper, preferring a behaviour-specific Api when the source exposes one.
+ * @param {import('#types').ElementBrokerMessage} [apiMessage]
+ * @returns {import('#types').IApi<import('./Activity.js').Activity>}
+ */
 ActivityExecution.prototype.getApi = function getApi(apiMessage) {
   const self = this;
-  if (!apiMessage) apiMessage = this[kExecuteMessage];
+  if (!apiMessage) apiMessage = this[K_EXECUTE_MESSAGE];
 
   if (self.source.getApi) {
     const sourceApi = self.source.getApi(apiMessage);
@@ -109,7 +131,7 @@ ActivityExecution.prototype.getApi = function getApi(apiMessage) {
 
   api.getExecuting = function getExecuting() {
     const result = [];
-    for (const msg of self[kPostponed]) {
+    for (const msg of self[K_POSTPONED]) {
       if (msg.content.executionId === apiMessage.content.executionId) continue;
       result.push(self.getApi(msg));
     }
@@ -119,14 +141,22 @@ ActivityExecution.prototype.getApi = function getApi(apiMessage) {
   return api;
 };
 
+/**
+ * Pass an execute message straight to the behaviour, executing first if no source is set up yet.
+ * @param {import('#types').ElementBrokerMessage} executeMessage
+ * @returns {void}
+ */
 ActivityExecution.prototype.passthrough = function passthrough(executeMessage) {
   if (!this.source) return this.execute(executeMessage);
   return this._sourceExecute(executeMessage);
 };
 
+/**
+ * List currently postponed executions as Api wrappers, including those from sub-process behaviours.
+ */
 ActivityExecution.prototype.getPostponed = function getPostponed() {
   let apis = [];
-  for (const msg of this[kPostponed]) {
+  for (const msg of this[K_POSTPONED]) {
     apis.push(this.getApi(msg));
   }
   if (!this.activity.isSubProcess || !this.source) return apis;
@@ -134,19 +164,28 @@ ActivityExecution.prototype.getPostponed = function getPostponed() {
   return apis;
 };
 
+/**
+ * Snapshot execution state, merging behaviour-specific state when the source provides it.
+ * @returns {import('#types').ActivityExecutionState}
+ */
 ActivityExecution.prototype.getState = function getState() {
-  const result = { completed: this[kCompleted] };
+  const result = { completed: this[K_COMPLETED] };
   const source = this.source;
 
   if (!source || !source.getState) return result;
   return { ...result, ...source.getState() };
 };
 
+/**
+ * Restore execution state captured by getState.
+ * @param {import('#types').ActivityExecutionState} [state]
+ * @returns {this}
+ */
 ActivityExecution.prototype.recover = function recover(state) {
-  this[kPostponed].clear();
+  this[K_POSTPONED].clear();
 
   if (!state) return this;
-  if ('completed' in state) this[kCompleted] = state.completed;
+  if ('completed' in state) this[K_COMPLETED] = state.completed;
 
   const source = (this.source = new this.activity.Behaviour(this.activity, this.context));
   if (source.recover) {
@@ -156,12 +195,16 @@ ActivityExecution.prototype.recover = function recover(state) {
   return this;
 };
 
+/**
+ * Stop the execution via the activity api.
+ */
 ActivityExecution.prototype.stop = function stop() {
-  const executeMessage = this[kExecuteMessage];
+  const executeMessage = this[K_EXECUTE_MESSAGE];
   if (!executeMessage) return;
   this.getApi(executeMessage).stop();
 };
 
+/** @internal */
 ActivityExecution.prototype._sourceExecute = function sourceExecute(executeMessage) {
   try {
     return this.source.execute(executeMessage);
@@ -170,6 +213,7 @@ ActivityExecution.prototype._sourceExecute = function sourceExecute(executeMessa
   }
 };
 
+/** @internal */
 ActivityExecution.prototype._onExecuteMessage = function onExecuteMessage(routingKey, message) {
   const { fields, content, properties } = message;
   const isRedelivered = fields.redelivered;
@@ -178,7 +222,7 @@ ActivityExecution.prototype._onExecuteMessage = function onExecuteMessage(routin
 
   switch (routingKey) {
     case 'execute.resume.execution': {
-      if (!this[kPostponed].size) return this.broker.publish('execution', 'execute.start', cloneContent(this[kExecuteMessage].content));
+      if (!this[K_POSTPONED].size) return this.broker.publish('execution', 'execute.start', cloneContent(this[K_EXECUTE_MESSAGE].content));
       break;
     }
     case 'execute.cancel':
@@ -216,9 +260,10 @@ ActivityExecution.prototype._onExecuteMessage = function onExecuteMessage(routin
   }
 };
 
+/** @internal */
 ActivityExecution.prototype._onStateChangeMessage = function onStateChangeMessage(message) {
   const { ignoreIfExecuting, executionId } = message.content;
-  const postponed = this[kPostponed];
+  const postponed = this[K_POSTPONED];
 
   let previousMsg;
   for (const msg of postponed) {
@@ -242,14 +287,15 @@ ActivityExecution.prototype._onStateChangeMessage = function onStateChangeMessag
   }
 };
 
+/** @internal */
 ActivityExecution.prototype._onExecutionCompleted = function onExecutionCompleted(message) {
   const postponedMsg = this._ackPostponed(message);
   if (!postponedMsg) return;
-  const postponed = this[kPostponed];
+  const postponed = this[K_POSTPONED];
 
   const { executionId, keep, isRootScope } = message.content;
   if (!isRootScope) {
-    this._debug('completed sub execution');
+    this._debug('completed sub execution', executionId);
     if (!keep) message.ack();
     if (postponed.size === 1) {
       const onlyMessage = postponed.values().next().value;
@@ -261,7 +307,7 @@ ActivityExecution.prototype._onExecutionCompleted = function onExecutionComplete
   }
 
   this._debug('completed execution', executionId);
-  this[kCompleted] = true;
+  this[K_COMPLETED] = true;
 
   message.ack(true);
 
@@ -274,12 +320,13 @@ ActivityExecution.prototype._onExecutionCompleted = function onExecutionComplete
   this._publishExecutionCompleted('completed', { ...postponedMsg.content, ...message.content }, message.properties.correlationId);
 };
 
+/** @internal */
 ActivityExecution.prototype._onExecutionDiscarded = function onExecutionDiscarded(discardType, message) {
   const postponedMsg = this._ackPostponed(message);
   const { isRootScope, error } = message.content;
   if (!isRootScope && !postponedMsg) return;
 
-  const postponed = this[kPostponed];
+  const postponed = this[K_POSTPONED];
   const correlationId = message.properties.correlationId;
   if (!error && !isRootScope) {
     message.ack();
@@ -303,12 +350,13 @@ ActivityExecution.prototype._onExecutionDiscarded = function onExecutionDiscarde
   this._publishExecutionCompleted(discardType, cloneContent(message.content), correlationId);
 };
 
+/** @internal */
 ActivityExecution.prototype._publishExecutionCompleted = function publishExecutionCompleted(
   completionType,
   completeContent,
   correlationId
 ) {
-  this[kCompleted] = true;
+  this[K_COMPLETED] = true;
 
   this.broker.publish(
     'execution',
@@ -321,10 +369,11 @@ ActivityExecution.prototype._publishExecutionCompleted = function publishExecuti
   );
 };
 
+/** @internal */
 ActivityExecution.prototype._ackPostponed = function ackPostponed(completeMessage) {
   const { executionId: eid } = completeMessage.content;
 
-  const postponed = this[kPostponed];
+  const postponed = this[K_POSTPONED];
   for (const msg of postponed) {
     if (msg.content.executionId === eid) {
       postponed.delete(msg);
@@ -334,18 +383,20 @@ ActivityExecution.prototype._ackPostponed = function ackPostponed(completeMessag
   }
 };
 
+/** @internal */
 ActivityExecution.prototype._onParentApiMessage = function onParentApiMessage(routingKey, message) {
   switch (message.properties.type) {
     case 'error':
-      return this[kExecuteQ].queueMessage({ routingKey: 'execute.error' }, { error: message.content.error });
+      return this[K_EXECUTE_Q].queueMessage({ routingKey: 'execute.error' }, { error: message.content.error });
     case 'discard':
-      return this[kExecuteQ].queueMessage({ routingKey: 'execute.discard' }, cloneContent(this[kExecuteMessage].content));
+      return this[K_EXECUTE_Q].queueMessage({ routingKey: 'execute.discard' }, cloneContent(this[K_EXECUTE_MESSAGE].content));
     case 'stop': {
       return this._onStop(message);
     }
   }
 };
 
+/** @internal */
 ActivityExecution.prototype._onStop = function onStop(message) {
   const stoppedId = message?.content?.executionId;
   const running = this.getPostponed();
@@ -359,15 +410,15 @@ ActivityExecution.prototype._onStop = function onStop(message) {
   this.broker.cancel('_activity-api-execution');
 };
 
+/** @internal */
 ActivityExecution.prototype._debug = function debug(logMessage, executionId) {
   executionId = executionId || this.executionId;
   this.activity.logger.debug(`<${executionId} (${this.id})> ${logMessage}`);
 };
 
 function getExecuteMessage(message) {
-  const result = cloneMessage(message, {
+  return cloneMessage(message, {
     ...(message.fields.redelivered && { isRecovered: true }),
     ignoreIfExecuting: undefined,
   });
-  return result;
 }

package/src/activity/Dummy.js

@@ -1,6 +1,11 @@
 import { cloneParent } from '../messageHelper.js';
 
-export default function DummyActivity(activityDef) {
+/**
+ * Placeholder activity for non-executable elements (text annotations, groups, categories).
+ * @param {import('moddle-context-serializer').Activity} activityDef
+ * @returns {{ id: string, type: string, name: string | undefined, behaviour: Record<string, any>, parent: import('#types').ElementParent, placeholder: true }}
+ */
+export function DummyActivity(activityDef) {
   const { id, type = 'dummy', name, parent, behaviour } = activityDef;
   return {
     id,

package/src/activity/Escalation.js

@@ -1,23 +1,30 @@
-export default function Escalation(signalDef, context) {
-  const { id, type, name, parent: originalParent } = signalDef;
-  const { environment } = context;
-  const parent = { ...originalParent };
+/**
+ * Escalation reference element. Resolves the escalation name expression against the execution message.
+ * @param {import('moddle-context-serializer').SerializableElement} escalationDef
+ * @param {import('#types').ContextInstance} context
+ */
+export function Escalation(escalationDef, context) {
+  if (!(this instanceof Escalation)) return new Escalation(escalationDef, context);
+  const { id, type, name, parent } = escalationDef;
+  this.id = id;
+  this.type = type;
+  this.name = name;
+  /** @type {import('#types').ElementParent} */
+  this.parent = { ...parent };
+  this.environment = context.environment;
+}
 
+/**
+ * Resolve escalation reference for the given execution message.
+ * @param {import('#types').ElementBrokerMessage} executionMessage
+ */
+Escalation.prototype.resolve = function resolve(executionMessage) {
+  const { id, type, name, parent } = this;
   return {
     id,
     type,
-    name,
-    parent,
-    resolve,
+    messageType: 'escalation',
+    name: name && this.environment.resolveExpression(name, executionMessage),
+    parent: { ...parent },
   };
-
-  function resolve(executionMessage) {
-    return {
-      id,
-      type,
-      messageType: 'escalation',
-      name: name && environment.resolveExpression(name, executionMessage),
-      parent: { ...parent },
-    };
-  }
-}
+};

package/src/activity/ExecutionScope.js

@@ -1,7 +1,7 @@
 import { cloneMessage } from '../messageHelper.js';
 import { ActivityError, BpmnError } from '../error/Errors.js';
 
-export default function ExecutionScope(activity, initMessage) {
+export function ExecutionScope(activity, initMessage) {
   const { id, type, environment, logger } = activity;
 
   const { fields, content, properties } = cloneMessage(initMessage);

package/src/activity/Message.js

@@ -1,23 +1,30 @@
-export default function Message(messageDef, context) {
-  const { id, type, name, parent: originalParent } = messageDef;
-  const { environment } = context;
-  const parent = { ...originalParent };
+/**
+ * Message reference element. Resolves the message name expression against the execution message.
+ * @param {import('moddle-context-serializer').SerializableElement} messageDef
+ * @param {import('#types').ContextInstance} context
+ */
+export function Message(messageDef, context) {
+  if (!(this instanceof Message)) return new Message(messageDef, context);
+  const { id, type, name, parent } = messageDef;
+  this.id = id;
+  this.type = type;
+  this.name = name;
+  /** @type {import('#types').ElementParent} */
+  this.parent = { ...parent };
+  this.environment = context.environment;
+}
 
+/**
+ * Resolve message reference for the given execution message.
+ * @param {import('#types').ElementBrokerMessage} executionMessage
+ */
+Message.prototype.resolve = function resolve(executionMessage) {
+  const { id, type, name, parent } = this;
   return {
     id,
     type,
-    name,
-    parent,
-    resolve,
+    messageType: 'message',
+    ...(name && { name: this.environment.resolveExpression(name, executionMessage) }),
+    parent: { ...parent },
   };
-
-  function resolve(executionMessage) {
-    return {
-      id,
-      type,
-      messageType: 'message',
-      ...(name && { name: environment.resolveExpression(name, executionMessage) }),
-      parent: { ...parent },
-    };
-  }
-}
+};

package/src/activity/Signal.js

@@ -1,23 +1,30 @@
-export default function Signal(signalDef, context) {
-  const { id, type = 'Signal', name, parent: originalParent } = signalDef;
-  const { environment } = context;
-  const parent = { ...originalParent };
+/**
+ * Signal reference element. Resolves the signal name expression against the execution message.
+ * @param {import('moddle-context-serializer').SerializableElement} signalDef
+ * @param {import('#types').ContextInstance} context
+ */
+export function Signal(signalDef, context) {
+  if (!(this instanceof Signal)) return new Signal(signalDef, context);
+  const { id, type = 'Signal', name, parent } = signalDef;
+  this.id = id;
+  this.type = type;
+  this.name = name;
+  /** @type {import('#types').ElementParent} */
+  this.parent = { ...parent };
+  this.environment = context.environment;
+}
 
+/**
+ * Resolve signal reference for the given execution message.
+ * @param {import('#types').ElementBrokerMessage} executionMessage
+ */
+Signal.prototype.resolve = function resolve(executionMessage) {
+  const { id, type, name, parent } = this;
   return {
     id,
     type,
-    name,
-    parent,
-    resolve,
+    messageType: 'signal',
+    ...(name && { name: this.environment.resolveExpression(name, executionMessage) }),
+    parent: { ...parent },
   };
-
-  function resolve(executionMessage) {
-    return {
-      id,
-      type,
-      messageType: 'signal',
-      ...(name && { name: environment.resolveExpression(name, executionMessage) }),
-      parent: { ...parent },
-    };
-  }
-}
+};

package/src/activity/outbound-evaluator.js

@@ -99,7 +99,7 @@ OutboundEvaluator.prototype.completed = function completed(err) {
 
   if (err) return callback(err);
 
-  if (!takenCount && this.outboundFlows.length) {
+  if (!takenCount && this.outboundFlows.length && fromMessage.content.requireOutbound) {
     const nonTakenError = new ActivityError(`<${this.activity.id}> no conditional flow taken`, fromMessage);
     return callback(nonTakenError);
   }

package/src/condition.js

@@ -1,8 +1,7 @@
-import ExecutionScope from './activity/ExecutionScope.js';
-
+import { ExecutionScope } from './activity/ExecutionScope.js';
 /**
  * Script condition
- * @param {import('types').ElementBase} owner
+ * @param {import('#types').ElementBase} owner
  * @param {any} script
  * @param {string} language
  */
@@ -31,7 +30,7 @@ ScriptCondition.prototype.execute = function execute(message, callback) {
 
 /**
  * Expression condition
- * @param {import('types').ElementBase} owner
+ * @param {import('#types').ElementBase} owner
  * @param {string} expression
  */
 export function ExpressionCondition(owner, expression) {
@@ -42,13 +41,20 @@ export function ExpressionCondition(owner, expression) {
 
 /**
  * Execute
- * @param {any} message
+ * @param {import('#types').ElementBrokerMessage} message
  * @param {CallableFunction} callback
  */
 ExpressionCondition.prototype.execute = function execute(message, callback) {
   const owner = this._owner;
   try {
     const result = owner.environment.resolveExpression(this.expression, message);
+    if (typeof result === 'function') {
+      const scope = ExecutionScope(owner, message);
+      if (callback && result.length > 1) return result.call(owner, scope, callback);
+      const conditionResult = result.call(owner, scope);
+      if (callback) return callback(null, conditionResult);
+      return conditionResult;
+    }
     if (callback) return callback(null, result);
     return result;
   } catch (err) {

package/src/constants.js

@@ -0,0 +1,15 @@
+export const K_ACTIVATED = Symbol.for('activated');
+export const K_COMPLETED = Symbol.for('completed');
+export const K_CONSUMING = Symbol.for('consuming');
+export const K_COUNTERS = Symbol.for('counters');
+export const K_EXECUTE_MESSAGE = Symbol.for('executeMessage');
+export const K_EXECUTION = Symbol.for('execution');
+export const K_EXTENSIONS = Symbol.for('extensions');
+export const K_MESSAGE_HANDLERS = Symbol.for('messageHandlers');
+export const K_MESSAGE_Q = Symbol.for('messageQ');
+export const K_REFERENCE_ELEMENT = Symbol.for('referenceElement');
+export const K_REFERENCE_INFO = Symbol.for('referenceInfo');
+export const K_STATE_MESSAGE = Symbol.for('stateMessage');
+export const K_STATUS = Symbol.for('status');
+export const K_STOPPED = Symbol.for('stopped');
+export const K_TARGETS = Symbol.for('targets');