bpmn-elements 17.3.0 → 18.0.0

package/dist/condition.js

@@ -5,11 +5,10 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.ExpressionCondition = ExpressionCondition;
 exports.ScriptCondition = ScriptCondition;
-var _ExecutionScope = _interopRequireDefault(require("./activity/ExecutionScope.js"));
-function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+var _ExecutionScope = require("./activity/ExecutionScope.js");
 /**
  * Script condition
- * @param {import('types').ElementBase} owner
+ * @param {import('#types').ElementBase} owner
  * @param {any} script
  * @param {string} language
  */
@@ -28,7 +27,7 @@ function ScriptCondition(owner, script, language) {
 ScriptCondition.prototype.execute = function execute(message, callback) {
   const owner = this._owner;
   try {
-    return this._script.execute((0, _ExecutionScope.default)(owner, message), callback);
+    return this._script.execute((0, _ExecutionScope.ExecutionScope)(owner, message), callback);
   } catch (err) {
     if (!callback) throw err;
     owner.logger.error(`<${owner.id}>`, err);
@@ -38,7 +37,7 @@ ScriptCondition.prototype.execute = function execute(message, callback) {
 
 /**
  * Expression condition
- * @param {import('types').ElementBase} owner
+ * @param {import('#types').ElementBase} owner
  * @param {string} expression
  */
 function ExpressionCondition(owner, expression) {
@@ -49,13 +48,20 @@ 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 = (0, _ExecutionScope.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/dist/constants.js

@@ -0,0 +1,21 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.K_TARGETS = exports.K_STOPPED = exports.K_STATUS = exports.K_STATE_MESSAGE = exports.K_REFERENCE_INFO = exports.K_REFERENCE_ELEMENT = exports.K_MESSAGE_Q = exports.K_MESSAGE_HANDLERS = exports.K_EXTENSIONS = exports.K_EXECUTION = exports.K_EXECUTE_MESSAGE = exports.K_COUNTERS = exports.K_CONSUMING = exports.K_COMPLETED = exports.K_ACTIVATED = void 0;
+const K_ACTIVATED = exports.K_ACTIVATED = Symbol.for('activated');
+const K_COMPLETED = exports.K_COMPLETED = Symbol.for('completed');
+const K_CONSUMING = exports.K_CONSUMING = Symbol.for('consuming');
+const K_COUNTERS = exports.K_COUNTERS = Symbol.for('counters');
+const K_EXECUTE_MESSAGE = exports.K_EXECUTE_MESSAGE = Symbol.for('executeMessage');
+const K_EXECUTION = exports.K_EXECUTION = Symbol.for('execution');
+const K_EXTENSIONS = exports.K_EXTENSIONS = Symbol.for('extensions');
+const K_MESSAGE_HANDLERS = exports.K_MESSAGE_HANDLERS = Symbol.for('messageHandlers');
+const K_MESSAGE_Q = exports.K_MESSAGE_Q = Symbol.for('messageQ');
+const K_REFERENCE_ELEMENT = exports.K_REFERENCE_ELEMENT = Symbol.for('referenceElement');
+const K_REFERENCE_INFO = exports.K_REFERENCE_INFO = Symbol.for('referenceInfo');
+const K_STATE_MESSAGE = exports.K_STATE_MESSAGE = Symbol.for('stateMessage');
+const K_STATUS = exports.K_STATUS = Symbol.for('status');
+const K_STOPPED = exports.K_STOPPED = Symbol.for('stopped');
+const K_TARGETS = exports.K_TARGETS = Symbol.for('targets');

package/dist/definition/Definition.js

@@ -4,25 +4,20 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.Definition = Definition;
-exports.default = void 0;
-var _DefinitionExecution = _interopRequireDefault(require("./DefinitionExecution.js"));
+var _DefinitionExecution = require("./DefinitionExecution.js");
 var _Api = require("../Api.js");
 var _EventBroker = require("../EventBroker.js");
 var _shared = require("../shared.js");
 var _Errors = require("../error/Errors.js");
 var _messageHelper = require("../messageHelper.js");
-function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
-const kConsuming = Symbol.for('consuming');
-const kCounters = Symbol.for('counters');
-const kExec = Symbol.for('execution');
-const kExecuteMessage = Symbol.for('executeMessage');
-const kMessageHandlers = Symbol.for('messageHandlers');
-const kStateMessage = Symbol.for('stateMessage');
-const kStatus = Symbol.for('status');
-const kStopped = Symbol.for('stopped');
-var _default = exports.default = Definition;
+var _constants = require("../constants.js");
+/**
+ * Top-level wrapper for an executable BPMN definition. Owns its DefinitionExecution and
+ * mediates inter-process messaging.
+ * @param {import('../Context.js').ContextInstance} context
+ * @param {import('#types').EnvironmentOptions} [options] When provided, environment is cloned and settings merged
+ */
 function Definition(context, options) {
-  if (!(this instanceof Definition)) return new Definition(context, options);
   if (!context) throw new Error('No context');
   const {
     id,
@@ -30,24 +25,27 @@ function Definition(context, options) {
     type = 'definition'
   } = context;
   this.id = id;
+  /** @type {string} */
   this.type = type;
   this.name = name;
-  let environment;
+
+  /** @type {import('../Environment.js').Environment} */
+  this.environment = undefined;
   if (options) {
-    environment = this.environment = context.environment.clone(options);
-    this.context = context.clone(environment);
+    this.environment = context.environment.clone(options).assignSettings(options.settings);
+    this.context = context.clone(this.environment);
   } else {
-    environment = this.environment = context.environment;
+    this.environment = context.environment;
     this.context = context;
   }
-  this[kCounters] = {
+  this[_constants.K_COUNTERS] = {
     completed: 0,
     discarded: 0
   };
-  this[kStopped] = false;
-  this[kExec] = new Map();
+  this[_constants.K_STOPPED] = false;
+  this[_constants.K_EXECUTION] = new Map();
   const onBrokerReturn = this._onBrokerReturnFn.bind(this);
-  this[kMessageHandlers] = {
+  this[_constants.K_MESSAGE_HANDLERS] = {
     onBrokerReturn,
     onApiMessage: this._onApiMessage.bind(this),
     onRunMessage: this._onRunMessage.bind(this),
@@ -67,49 +65,60 @@ function Definition(context, options) {
   this.waitFor = waitFor;
   this.emit = emit;
   this.emitFatal = emitFatal;
-  this.logger = environment.Logger(type.toLowerCase());
+
+  /** @type {import('#types').ILogger} */
+  this.logger = this.environment.Logger(type.toLowerCase());
 }
 Object.defineProperties(Definition.prototype, {
   counters: {
     get() {
       return {
-        ...this[kCounters]
+        ...this[_constants.K_COUNTERS]
       };
     }
   },
   execution: {
     get() {
-      return this[kExec].get('execution');
+      return this[_constants.K_EXECUTION].get('execution');
     }
   },
   executionId: {
     get() {
-      return this[kExec].get('executionId');
+      return this[_constants.K_EXECUTION].get('executionId');
     }
   },
   isRunning: {
     get() {
-      if (!this[kConsuming]) return false;
+      if (!this[_constants.K_CONSUMING]) return false;
       return !!this.status;
     }
   },
   status: {
     get() {
-      return this[kStatus];
+      return this[_constants.K_STATUS];
     }
   },
   stopped: {
     get() {
-      return this[kStopped];
+      return this[_constants.K_STOPPED];
     }
   },
   activityStatus: {
     get() {
-      const execution = this[kExec].get('execution');
+      const execution = this[_constants.K_EXECUTION].get('execution');
       return execution?.activityStatus || 'idle';
     }
   }
 });
+
+/**
+ * Start running the definition. Accepts run options, a callback, or both.
+ * The callback fires once on leave, stop, or error.
+ * @param {Record<string, any> | import('#types').runCallback} [optionsOrCallback]
+ * @param {import('#types').runCallback} [optionalCallback]
+ * @returns {this}
+ * @throws {Error} when already running and no callback is supplied
+ */
 Definition.prototype.run = function run(optionsOrCallback, optionalCallback) {
   const [runOptions, callback] = (0, _shared.getOptionsAndCallback)(optionsOrCallback, optionalCallback);
   if (this.isRunning) {
@@ -120,7 +129,7 @@ Definition.prototype.run = function run(optionsOrCallback, optionalCallback) {
   if (callback) {
     addConsumerCallbacks(this, callback);
   }
-  const exec = this[kExec];
+  const exec = this[_constants.K_EXECUTION];
   const executionId = (0, _shared.getUniqueId)(this.id);
   exec.set('executionId', executionId);
   const content = this._createMessage({
@@ -134,13 +143,20 @@ Definition.prototype.run = function run(optionsOrCallback, optionalCallback) {
   this._activateRunConsumers();
   return this;
 };
+
+/**
+ * Resume after recover by republishing the last run message. The callback fires once on
+ * leave, stop, or error.
+ * @param {import('#types').runCallback} [callback]
+ * @returns {this}
+ */
 Definition.prototype.resume = function resume(callback) {
   if (this.isRunning) {
     const err = new Error('cannot resume running definition');
     if (callback) return callback(err);
     throw err;
   }
-  this[kStopped] = false;
+  this[_constants.K_STOPPED] = false;
   if (!this.status) return this;
   if (callback) {
     addConsumerCallbacks(this, callback);
@@ -153,6 +169,11 @@ Definition.prototype.resume = function resume(callback) {
   this._activateRunConsumers();
   return this;
 };
+
+/**
+ * Snapshot definition state for recover.
+ * @returns {import('#types').DefinitionState}
+ */
 Definition.prototype.getState = function getState() {
   return this._createMessage({
     status: this.status,
@@ -163,27 +184,42 @@ Definition.prototype.getState = function getState() {
     broker: this.broker.getState(true)
   });
 };
+
+/**
+ * Restore definition state captured by getState.
+ * @param {import('#types').DefinitionState} [state]
+ * @returns {this}
+ * @throws {Error} when called on a running definition
+ */
 Definition.prototype.recover = function recover(state) {
   if (this.isRunning) throw new Error('cannot recover running definition');
   if (!state) return this;
-  this[kStopped] = !!state.stopped;
-  this[kStatus] = state.status;
-  const exec = this[kExec];
+  this[_constants.K_STOPPED] = !!state.stopped;
+  this[_constants.K_STATUS] = state.status;
+  const exec = this[_constants.K_EXECUTION];
   exec.set('executionId', state.executionId);
   if (state.counters) {
-    this[kCounters] = {
-      ...this[kCounters],
+    this[_constants.K_COUNTERS] = {
+      ...this[_constants.K_COUNTERS],
       ...state.counters
     };
   }
   this.environment.recover(state.environment);
   if (state.execution) {
-    exec.set('execution', new _DefinitionExecution.default(this, this.context).recover(state.execution));
+    exec.set('execution', new _DefinitionExecution.DefinitionExecution(this, this.context).recover(state.execution));
   }
   this.broker.recover(state.broker);
   return this;
 };
+
+/**
+ * Walk activity graphs to discover sequences. Limited to the activity's owning process
+ * when startId is given, otherwise all processes are shaken.
+ * @param {string} [startId]
+ * @returns {import('#types').ShakeResult | undefined}
+ */
 Definition.prototype.shake = function shake(startId) {
+  /** @type {import('#types').ShakeResult} */
   let result = {};
   let bps;
   if (startId) {
@@ -201,6 +237,8 @@ Definition.prototype.shake = function shake(startId) {
   });
   return result;
 };
+
+/** @internal */
 Definition.prototype._shakeProcess = function shakeProcess(shakeBp, startId) {
   let shovel;
   if (!shakeBp.isRunning) {
@@ -216,24 +254,45 @@ Definition.prototype._shakeProcess = function shakeProcess(shakeBp, startId) {
   if (shovel) shakeBp.broker.closeShovel('shaker');
   return shakeResult;
 };
+
+/**
+ * Get every process in the definition.
+ */
 Definition.prototype.getProcesses = function getProcesses() {
   const execution = this.execution;
   if (execution) return execution.getProcesses();
   return this.context.getProcesses();
 };
+
+/**
+ * Get processes flagged executable in the definition.
+ */
 Definition.prototype.getExecutableProcesses = function getExecutableProcesses() {
   const execution = this.execution;
   if (execution) return execution.getExecutableProcesses();
   return this.context.getExecutableProcesses();
 };
+
+/**
+ * Get processes that are currently running.
+ */
 Definition.prototype.getRunningProcesses = function getRunningProcesses() {
   const execution = this.execution;
   if (!execution) return [];
   return execution.getRunningProcesses();
 };
+
+/**
+ * @param {string} processId
+ */
 Definition.prototype.getProcessById = function getProcessById(processId) {
   return this.getProcesses().find(p => p.id === processId);
 };
+
+/**
+ * Find an activity by id across all processes in the definition.
+ * @param {string} childId
+ */
 Definition.prototype.getActivityById = function getActivityById(childId) {
   const bps = this.getProcesses();
   for (const bp of bps) {
@@ -242,31 +301,62 @@ Definition.prototype.getActivityById = function getActivityById(childId) {
   }
   return null;
 };
+
+/**
+ * Lookup any element (activity, flow, etc.) in the parsed definition by id.
+ * @param {string} elementId
+ */
 Definition.prototype.getElementById = function getElementById(elementId) {
   return this.context.getActivityById(elementId);
 };
+
+/**
+ * List currently postponed activities as Api wrappers.
+ * @param {import('#types').filterPostponed} [filterFn]
+ */
 Definition.prototype.getPostponed = function getPostponed(...args) {
-  const execution = this.execution;
-  if (!execution) return [];
-  return execution.getPostponed(...args);
+  return this.execution?.getPostponed(...args) || [];
 };
+
+/**
+ * Resolve a Definition Api wrapper, preferring the running execution if any.
+ * @param {import('#types').ElementBrokerMessage} [message]
+ * @returns {import('#types').IApi<this>}
+ * @throws {Error} when the definition is not running and no message is given
+ */
 Definition.prototype.getApi = function getApi(message) {
   const execution = this.execution;
   if (execution) return execution.getApi(message);
-  message = message || this[kStateMessage];
+  message = message || this[_constants.K_STATE_MESSAGE];
   if (!message) throw new Error('Definition is not running');
   return (0, _Api.DefinitionApi)(this.broker, message);
 };
+
+/**
+ * Send a delegated signal to the running definition.
+ * @param {import('#types').signalMessage} [message]
+ */
 Definition.prototype.signal = function signal(message) {
   return this.getApi().signal(message, {
     delegate: true
   });
 };
+
+/**
+ * Cancel a running activity inside the definition by delegated api message.
+ * @param {import('#types').signalMessage} [message]
+ */
 Definition.prototype.cancelActivity = function cancelActivity(message) {
   return this.getApi().cancel(message, {
     delegate: true
   });
 };
+
+/**
+ * Deliver a message to a referenced element. Resolves the message reference when the
+ * target element exposes a `resolve` method (e.g. message-, signal-, escalation events).
+ * @param {{ id?: string, [x: string]: any }} message
+ */
 Definition.prototype.sendMessage = function sendMessage(message) {
   const messageContent = {
     message
@@ -287,17 +377,23 @@ Definition.prototype.sendMessage = function sendMessage(message) {
     delegate: true
   });
 };
+
+/**
+ * Stop the definition if running.
+ */
 Definition.prototype.stop = function stop() {
   if (!this.isRunning) return;
   this.getApi().stop();
 };
+
+/** @internal */
 Definition.prototype._activateRunConsumers = function activateRunConsumers() {
-  this[kConsuming] = true;
+  this[_constants.K_CONSUMING] = true;
   const broker = this.broker;
   const {
     onApiMessage,
     onRunMessage
-  } = this[kMessageHandlers];
+  } = this[_constants.K_MESSAGE_HANDLERS];
   broker.subscribeTmp('api', `definition.*.${this.executionId}`, onApiMessage, {
     noAck: true,
     consumerTag: '_definition-api'
@@ -307,13 +403,17 @@ Definition.prototype._activateRunConsumers = function activateRunConsumers() {
     consumerTag: '_definition-run'
   });
 };
+
+/** @internal */
 Definition.prototype._deactivateRunConsumers = function deactivateRunConsumers() {
   const broker = this.broker;
   broker.cancel('_definition-api');
   broker.cancel('_definition-run');
   broker.cancel('_definition-execution');
-  this[kConsuming] = false;
+  this[_constants.K_CONSUMING] = false;
 };
+
+/** @internal */
 Definition.prototype._createMessage = function createMessage(override) {
   return {
     id: this.id,
@@ -323,6 +423,8 @@ Definition.prototype._createMessage = function createMessage(override) {
     ...override
   };
 };
+
+/** @internal */
 Definition.prototype._onRunMessage = function onRunMessage(routingKey, message) {
   const {
     content,
@@ -331,13 +433,13 @@ Definition.prototype._onRunMessage = function onRunMessage(routingKey, message)
   if (routingKey === 'run.resume') {
     return this._onResumeMessage(message);
   }
-  const exec = this[kExec];
-  this[kStateMessage] = message;
+  const exec = this[_constants.K_EXECUTION];
+  this[_constants.K_STATE_MESSAGE] = message;
   switch (routingKey) {
     case 'run.enter':
       {
         this.logger.debug(`<${this.executionId} (${this.id})> enter`);
-        this[kStatus] = 'entered';
+        this[_constants.K_STATUS] = 'entered';
         if (fields.redelivered) break;
         exec.delete('execution');
         this._publishEvent('enter', content);
@@ -346,25 +448,25 @@ Definition.prototype._onRunMessage = function onRunMessage(routingKey, message)
     case 'run.start':
       {
         this.logger.debug(`<${this.executionId} (${this.id})> start`);
-        this[kStatus] = 'start';
+        this[_constants.K_STATUS] = 'start';
         this._publishEvent('start', content);
         break;
       }
     case 'run.execute':
       {
-        this[kStatus] = 'executing';
+        this[_constants.K_STATUS] = 'executing';
         const executeMessage = (0, _messageHelper.cloneMessage)(message);
         let execution = exec.get('execution');
         if (fields.redelivered && !execution) {
           executeMessage.fields.redelivered = undefined;
         }
-        this[kExecuteMessage] = message;
-        this.broker.getQueue('execution-q').assertConsumer(this[kMessageHandlers].onExecutionMessage, {
+        this[_constants.K_EXECUTE_MESSAGE] = message;
+        this.broker.getQueue('execution-q').assertConsumer(this[_constants.K_MESSAGE_HANDLERS].onExecutionMessage, {
           exclusive: true,
           consumerTag: '_definition-execution'
         });
         if (!execution) {
-          execution = new _DefinitionExecution.default(this, this.context);
+          execution = new _DefinitionExecution.DefinitionExecution(this, this.context);
           exec.set('execution', execution);
         }
         if (executeMessage.fields.redelivered) {
@@ -374,10 +476,10 @@ Definition.prototype._onRunMessage = function onRunMessage(routingKey, message)
       }
     case 'run.end':
       {
-        if (this[kStatus] === 'end') break;
-        this[kCounters].completed++;
+        if (this[_constants.K_STATUS] === 'end') break;
+        this[_constants.K_COUNTERS].completed++;
         this.logger.debug(`<${this.executionId} (${this.id})> completed`);
-        this[kStatus] = 'end';
+        this[_constants.K_STATUS] = 'end';
         this.broker.publish('run', 'run.leave', content);
         this._publishEvent('end', content);
         break;
@@ -394,16 +496,16 @@ Definition.prototype._onRunMessage = function onRunMessage(routingKey, message)
       }
     case 'run.discarded':
       {
-        if (this[kStatus] === 'discarded') break;
-        this[kCounters].discarded++;
-        this[kStatus] = 'discarded';
+        if (this[_constants.K_STATUS] === 'discarded') break;
+        this[_constants.K_COUNTERS].discarded++;
+        this[_constants.K_STATUS] = 'discarded';
         this.broker.publish('run', 'run.leave', content);
         break;
       }
     case 'run.leave':
       {
         message.ack();
-        this[kStatus] = undefined;
+        this[_constants.K_STATUS] = undefined;
         this._deactivateRunConsumers();
         this._publishEvent('leave', this._createMessage());
         return;
@@ -411,9 +513,11 @@ Definition.prototype._onRunMessage = function onRunMessage(routingKey, message)
   }
   message.ack();
 };
+
+/** @internal */
 Definition.prototype._onResumeMessage = function onResumeMessage(message) {
   message.ack();
-  const stateMessage = this[kStateMessage];
+  const stateMessage = this[_constants.K_STATE_MESSAGE];
   switch (stateMessage.fields.routingKey) {
     case 'run.discarded':
     case 'run.end':
@@ -426,6 +530,8 @@ Definition.prototype._onResumeMessage = function onResumeMessage(message) {
   this._debug(`resume from ${this.status}`);
   return this.broker.publish('run', stateMessage.fields.routingKey, (0, _messageHelper.cloneContent)(stateMessage.content), stateMessage.properties);
 };
+
+/** @internal */
 Definition.prototype._onExecutionMessage = function onExecutionMessage(routingKey, message) {
   const {
     content,
@@ -449,10 +555,12 @@ Definition.prototype._onExecutionMessage = function onExecutionMessage(routingKe
         this.broker.publish('run', 'run.end', content);
       }
   }
-  const executeMessage = this[kExecuteMessage];
-  this[kExecuteMessage] = null;
+  const executeMessage = this[_constants.K_EXECUTE_MESSAGE];
+  this[_constants.K_EXECUTE_MESSAGE] = null;
   executeMessage.ack();
 };
+
+/** @internal */
 Definition.prototype._onApiMessage = function onApiMessage(routingKey, message) {
   if (message.properties.type === 'stop') {
     const execution = this.execution;
@@ -461,6 +569,8 @@ Definition.prototype._onApiMessage = function onApiMessage(routingKey, message)
     }
   }
 };
+
+/** @internal */
 Definition.prototype._publishEvent = function publishEvent(action, content, msgOpts) {
   const execution = this.execution;
   this.broker.publish('event', `definition.${action}`, execution ? execution._createMessage(content) : (0, _messageHelper.cloneContent)(content), {
@@ -468,11 +578,15 @@ Definition.prototype._publishEvent = function publishEvent(action, content, msgO
     ...msgOpts
   });
 };
+
+/** @internal */
 Definition.prototype._onStop = function onStop() {
-  this[kStopped] = true;
+  this[_constants.K_STOPPED] = true;
   this._deactivateRunConsumers();
   return this._publishEvent('stop', this._createMessage());
 };
+
+/** @internal */
 Definition.prototype._onBrokerReturnFn = function onBrokerReturn(message) {
   if (message.properties.type === 'error') {
     this._deactivateRunConsumers();
@@ -480,12 +594,16 @@ Definition.prototype._onBrokerReturnFn = function onBrokerReturn(message) {
     throw err;
   }
 };
+
+/** @internal */
 Definition.prototype._reset = function reset() {
-  this[kExec].delete('executionId');
+  this[_constants.K_EXECUTION].delete('executionId');
   this._deactivateRunConsumers();
   this.broker.purgeQueue('run-q');
   this.broker.purgeQueue('execution-q');
 };
+
+/** @internal */
 Definition.prototype._debug = function debug(msg) {
   this.logger.debug(`<${this.id}> ${msg}`);
 };