bpmn-elements 17.3.0 → 18.0.0

package/dist/activity/ActivityExecution.js

@@ -3,48 +3,59 @@
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.default = void 0;
+exports.ActivityExecution = ActivityExecution;
 var _Api = require("../Api.js");
 var _messageHelper = require("../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');
-var _default = exports.default = ActivityExecution;
+var _constants = require("../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
+ */
 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', {
+  this[K_POSTPONED] = new Set();
+  this[_constants.K_COMPLETED] = false;
+  this[K_EXECUTE_Q] = this.broker.assertQueue('execute-q', {
     durable: true,
     autoDelete: false
   });
-  this[kMessageHandlers] = {
+  this[_constants.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[_constants.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] = (0, _messageHelper.cloneMessage)(executeMessage, {
+  const initMessage = this[_constants.K_EXECUTE_MESSAGE] = (0, _messageHelper.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);
     this.activate();
@@ -57,8 +68,12 @@ ActivityExecution.prototype.execute = function execute(executeMessage) {
   this.source = new this.activity.Behaviour(this.activity, this.context);
   this.broker.publish('execution', 'execute.start', (0, _messageHelper.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[_constants.K_COMPLETED]) return;
   const broker = this.broker;
   const batchSize = this.activity.environment.settings.batchSize || 50;
   broker.bindQueue('execute-q', 'execution', 'execute.#', {
@@ -67,35 +82,49 @@ ActivityExecution.prototype.activate = function activate() {
   const {
     onExecuteMessage,
     onParentApiMessage
-  } = this[kMessageHandlers];
-  this[kExecuteQ].assertConsumer(onExecuteMessage, {
+  } = this[_constants.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[_constants.K_COMPLETED]) return this.deactivate();
   broker.subscribeTmp('api', `activity.*.${this.executionId}`, onParentApiMessage, {
     noAck: true,
     consumerTag: '_activity-api-execution',
     priority: 200
   });
 };
+
+/**
+ * Cancel execute and api consumers and unbind the execute queue.
+ */
 ActivityExecution.prototype.deactivate = function deactivate() {
   const broker = this.broker;
   broker.cancel('_activity-api-execution');
   broker.cancel('_activity-execute');
   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[_constants.K_COMPLETED]) return;
+  const initMessage = this[_constants.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[_constants.K_EXECUTE_MESSAGE];
   if (self.source.getApi) {
     const sourceApi = self.source.getApi(apiMessage);
     if (sourceApi) return sourceApi;
@@ -103,7 +132,7 @@ ActivityExecution.prototype.getApi = function getApi(apiMessage) {
   const api = (0, _Api.ActivityApi)(self.broker, 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));
     }
@@ -111,22 +140,37 @@ 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;
   apis = apis.concat(this.source.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]
+    completed: this[_constants.K_COMPLETED]
   };
   const source = this.source;
   if (!source || !source.getState) return result;
@@ -135,21 +179,33 @@ ActivityExecution.prototype.getState = function getState() {
     ...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[_constants.K_COMPLETED] = state.completed;
   const source = this.source = new this.activity.Behaviour(this.activity, this.context);
   if (source.recover) {
     source.recover(state);
   }
   return this;
 };
+
+/**
+ * Stop the execution via the activity api.
+ */
 ActivityExecution.prototype.stop = function stop() {
-  const executeMessage = this[kExecuteMessage];
+  const executeMessage = this[_constants.K_EXECUTE_MESSAGE];
   if (!executeMessage) return;
   this.getApi(executeMessage).stop();
 };
+
+/** @internal */
 ActivityExecution.prototype._sourceExecute = function sourceExecute(executeMessage) {
   try {
     return this.source.execute(executeMessage);
@@ -159,6 +215,8 @@ ActivityExecution.prototype._sourceExecute = function sourceExecute(executeMessa
     }));
   }
 };
+
+/** @internal */
 ActivityExecution.prototype._onExecuteMessage = function onExecuteMessage(routingKey, message) {
   const {
     fields,
@@ -170,7 +228,7 @@ ActivityExecution.prototype._onExecuteMessage = function onExecuteMessage(routin
   switch (routingKey) {
     case 'execute.resume.execution':
       {
-        if (!this[kPostponed].size) return this.broker.publish('execution', 'execute.start', (0, _messageHelper.cloneContent)(this[kExecuteMessage].content));
+        if (!this[K_POSTPONED].size) return this.broker.publish('execution', 'execute.start', (0, _messageHelper.cloneContent)(this[_constants.K_EXECUTE_MESSAGE].content));
         break;
       }
     case 'execute.cancel':
@@ -212,12 +270,14 @@ 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) {
     if (msg.content.executionId === executionId) previousMsg = msg;
@@ -236,17 +296,19 @@ ActivityExecution.prototype._onStateChangeMessage = function onStateChangeMessag
     return true;
   }
 };
+
+/** @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;
@@ -257,7 +319,7 @@ ActivityExecution.prototype._onExecutionCompleted = function onExecutionComplete
     return;
   }
   this._debug('completed execution', executionId);
-  this[kCompleted] = true;
+  this[_constants.K_COMPLETED] = true;
   message.ack(true);
   this.deactivate();
   const subApis = this.getPostponed();
@@ -268,6 +330,8 @@ ActivityExecution.prototype._onExecutionCompleted = function onExecutionComplete
     ...message.content
   }, message.properties.correlationId);
 };
+
+/** @internal */
 ActivityExecution.prototype._onExecutionDiscarded = function onExecutionDiscarded(discardType, message) {
   const postponedMsg = this._ackPostponed(message);
   const {
@@ -275,7 +339,7 @@ ActivityExecution.prototype._onExecutionDiscarded = function onExecutionDiscarde
     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();
@@ -296,8 +360,10 @@ ActivityExecution.prototype._onExecutionDiscarded = function onExecutionDiscarde
   for (const api of subApis) api.discard();
   this._publishExecutionCompleted(discardType, (0, _messageHelper.cloneContent)(message.content), correlationId);
 };
+
+/** @internal */
 ActivityExecution.prototype._publishExecutionCompleted = function publishExecutionCompleted(completionType, completeContent, correlationId) {
-  this[kCompleted] = true;
+  this[_constants.K_COMPLETED] = true;
   this.broker.publish('execution', `execution.${completionType}`, {
     ...completeContent,
     state: completionType
@@ -306,11 +372,13 @@ ActivityExecution.prototype._publishExecutionCompleted = function publishExecuti
     correlationId
   });
 };
+
+/** @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);
@@ -319,24 +387,28 @@ ActivityExecution.prototype._ackPostponed = function ackPostponed(completeMessag
     }
   }
 };
+
+/** @internal */
 ActivityExecution.prototype._onParentApiMessage = function onParentApiMessage(routingKey, message) {
   switch (message.properties.type) {
     case 'error':
-      return this[kExecuteQ].queueMessage({
+      return this[K_EXECUTE_Q].queueMessage({
         routingKey: 'execute.error'
       }, {
         error: message.content.error
       });
     case 'discard':
-      return this[kExecuteQ].queueMessage({
+      return this[K_EXECUTE_Q].queueMessage({
         routingKey: 'execute.discard'
-      }, (0, _messageHelper.cloneContent)(this[kExecuteMessage].content));
+      }, (0, _messageHelper.cloneContent)(this[_constants.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();
@@ -348,16 +420,17 @@ ActivityExecution.prototype._onStop = function onStop(message) {
   this.broker.cancel('_activity-execute');
   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 = (0, _messageHelper.cloneMessage)(message, {
+  return (0, _messageHelper.cloneMessage)(message, {
     ...(message.fields.redelivered && {
       isRecovered: true
     }),
     ignoreIfExecuting: undefined
   });
-  return result;
 }

package/dist/activity/Dummy.js

@@ -3,8 +3,13 @@
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.default = DummyActivity;
+exports.DummyActivity = DummyActivity;
 var _messageHelper = require("../messageHelper.js");
+/**
+ * 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 }}
+ */
 function DummyActivity(activityDef) {
   const {
     id,

package/dist/activity/Escalation.js

@@ -3,36 +3,48 @@
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.default = Escalation;
-function Escalation(signalDef, context) {
+exports.Escalation = Escalation;
+/**
+ * Escalation reference element. Resolves the escalation name expression against the execution message.
+ * @param {import('moddle-context-serializer').SerializableElement} escalationDef
+ * @param {import('#types').ContextInstance} context
+ */
+function Escalation(escalationDef, context) {
+  if (!(this instanceof Escalation)) return new Escalation(escalationDef, context);
   const {
     id,
     type,
     name,
-    parent: originalParent
-  } = signalDef;
-  const {
-    environment
-  } = context;
-  const parent = {
-    ...originalParent
+    parent
+  } = escalationDef;
+  this.id = id;
+  this.type = type;
+  this.name = name;
+  /** @type {import('#types').ElementParent} */
+  this.parent = {
+    ...parent
   };
-  return {
+  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,
-    resolve
+    parent
+  } = this;
+  return {
+    id,
+    type,
+    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/dist/activity/ExecutionScope.js

@@ -3,7 +3,7 @@
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.default = ExecutionScope;
+exports.ExecutionScope = ExecutionScope;
 var _messageHelper = require("../messageHelper.js");
 var _Errors = require("../error/Errors.js");
 function ExecutionScope(activity, initMessage) {

package/dist/activity/Message.js

@@ -3,38 +3,50 @@
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.default = Message;
+exports.Message = Message;
+/**
+ * Message reference element. Resolves the message name expression against the execution message.
+ * @param {import('moddle-context-serializer').SerializableElement} messageDef
+ * @param {import('#types').ContextInstance} context
+ */
 function Message(messageDef, context) {
+  if (!(this instanceof Message)) return new Message(messageDef, context);
   const {
     id,
     type,
     name,
-    parent: originalParent
+    parent
   } = messageDef;
-  const {
-    environment
-  } = context;
-  const parent = {
-    ...originalParent
+  this.id = id;
+  this.type = type;
+  this.name = name;
+  /** @type {import('#types').ElementParent} */
+  this.parent = {
+    ...parent
   };
-  return {
+  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,
-    resolve
+    parent
+  } = this;
+  return {
+    id,
+    type,
+    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/dist/activity/Signal.js

@@ -3,38 +3,50 @@
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.default = Signal;
+exports.Signal = Signal;
+/**
+ * Signal reference element. Resolves the signal name expression against the execution message.
+ * @param {import('moddle-context-serializer').SerializableElement} signalDef
+ * @param {import('#types').ContextInstance} context
+ */
 function Signal(signalDef, context) {
+  if (!(this instanceof Signal)) return new Signal(signalDef, context);
   const {
     id,
     type = 'Signal',
     name,
-    parent: originalParent
+    parent
   } = signalDef;
-  const {
-    environment
-  } = context;
-  const parent = {
-    ...originalParent
+  this.id = id;
+  this.type = type;
+  this.name = name;
+  /** @type {import('#types').ElementParent} */
+  this.parent = {
+    ...parent
   };
-  return {
+  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,
-    resolve
+    parent
+  } = this;
+  return {
+    id,
+    type,
+    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/dist/activity/outbound-evaluator.js

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