bpmn-elements 17.2.2 → 18.0.0

package/dist/Environment.js

@@ -3,75 +3,105 @@
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.default = Environment;
-var _Expressions = _interopRequireDefault(require("./Expressions.js"));
+exports.Environment = Environment;
+var _Expressions = require("./Expressions.js");
 var _Scripts = require("./Scripts.js");
 var _Timers = require("./Timers.js");
-function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
-const kServices = Symbol.for('services');
-const kVariables = Symbol.for('variables');
+const K_SERVICES = Symbol.for('services');
+const K_VARIABLES = Symbol.for('variables');
 const defaultOptions = new Set(['expressions', 'extensions', 'Logger', 'output', 'scripts', 'services', 'settings', 'timers', 'variables']);
+
+/**
+ * Holds global execution config: variables, injected services, timers, scripts engine,
+ * expressions, Logger factory, and settings such as `batchSize`. Cloned and merged per Definition.
+ * @param {import('#types').EnvironmentOptions} [options]
+ */
 function Environment(options = {}) {
   this.options = validateOptions(options);
-  this.expressions = options.expressions || (0, _Expressions.default)();
+
+  /** @type {import('#types').IExpressions} */
+  this.expressions = options.expressions || (0, _Expressions.Expressions)();
   this.extensions = options.extensions;
   this.output = options.output || {};
+  /** @type {import('#types').IScripts} */
   this.scripts = options.scripts || new _Scripts.Scripts();
+  /** @type {import('#types').ITimers} */
   this.timers = options.timers || new _Timers.Timers();
+  /** @type {import('#types').EnvironmentSettings} */
   this.settings = {
     ...options.settings
   };
+  /** @type {import('#types').LoggerFactory} */
   this.Logger = options.Logger || DummyLogger;
-  this[kServices] = options.services || {};
-  this[kVariables] = options.variables || {};
+  this[K_SERVICES] = options.services || {};
+  this[K_VARIABLES] = options.variables || {};
 }
-Object.defineProperties(Environment.prototype, {
-  variables: {
-    get() {
-      return this[kVariables];
-    }
+Object.defineProperty(Environment.prototype, 'variables', {
+  /** @returns {Record<string, any>} */
+  get() {
+    return this[K_VARIABLES];
+  }
+});
+Object.defineProperty(Environment.prototype, 'services', {
+  /** @returns {Record<string, CallableFunction>} */
+  get() {
+    return this[K_SERVICES];
   },
-  services: {
-    get() {
-      return this[kServices];
-    },
-    set(value) {
-      const services = this[kServices];
-      for (const name in services) {
-        if (!(name in value)) delete services[name];
-      }
-      Object.assign(services, value);
+  set(value) {
+    const services = this[K_SERVICES];
+    for (const name in services) {
+      if (!(name in value)) delete services[name];
     }
+    Object.assign(services, value);
   }
 });
+
+/**
+ * Snapshot environment state for recover.
+ * @returns {import('#types').EnvironmentState}
+ */
 Environment.prototype.getState = function getState() {
   return {
     settings: {
       ...this.settings
     },
     variables: {
-      ...this[kVariables]
+      ...this[K_VARIABLES]
     },
     output: {
       ...this.output
     }
   };
 };
+
+/**
+ * Restore environment state captured by getState. Merges into the existing settings,
+ * variables, and output rather than replacing them.
+ * @param {import('#types').EnvironmentState} [state]
+ * @returns {this}
+ */
 Environment.prototype.recover = function recover(state) {
   if (!state) return this;
   if (state.settings) Object.assign(this.settings, state.settings);
-  if (state.variables) Object.assign(this[kVariables], state.variables);
+  if (state.variables) Object.assign(this[K_VARIABLES], state.variables);
   if (state.output) Object.assign(this.output, state.output);
   return this;
 };
+
+/**
+ * Clone the environment, optionally overriding options. Services are merged when
+ * `overrideOptions.services` is supplied.
+ * @param {import('#types').EnvironmentOptions} [overrideOptions]
+ * @returns {Environment}
+ */
 Environment.prototype.clone = function clone(overrideOptions) {
-  const services = this[kServices];
+  const services = this[K_SERVICES];
   const newOptions = {
     settings: {
       ...this.settings
     },
     variables: {
-      ...this[kVariables]
+      ...this[K_VARIABLES]
     },
     Logger: this.Logger,
     extensions: this.extensions,
@@ -88,29 +118,64 @@ Environment.prototype.clone = function clone(overrideOptions) {
   };
   return new this.constructor(newOptions);
 };
+
+/**
+ * Merge variables into the environment. Non-objects are ignored.
+ * @param {Record<string, any>} newVars
+ */
 Environment.prototype.assignVariables = function assignVariables(newVars) {
   if (!newVars || typeof newVars !== 'object') return;
-  this[kVariables] = {
+  this[K_VARIABLES] = {
     ...this.variables,
     ...newVars
   };
 };
+
+/**
+ * Merge settings into the environment. Non-objects are ignored.
+ * @param {import('#types').EnvironmentSettings} newSettings
+ * @returns {this}
+ */
 Environment.prototype.assignSettings = function assignSettings(newSettings) {
-  if (!newSettings || typeof newSettings !== 'object') return;
+  if (!newSettings || typeof newSettings !== 'object') return this;
   this.settings = {
     ...this.settings,
     ...newSettings
   };
+  return this;
 };
+
+/**
+ * Resolve a registered script by language and identifier.
+ * @param {string} language
+ * @param {{ id: string, [x: string]: any }} identifier
+ */
 Environment.prototype.getScript = function getScript(...args) {
   return this.scripts.getScript(...args);
 };
+
+/**
+ * Register a script for an activity, delegating to the configured scripts engine.
+ * @param {any} activity
+ */
 Environment.prototype.registerScript = function registerScript(...args) {
   return this.scripts.register(...args);
 };
+
+/**
+ * Lookup a registered service by name.
+ * @param {string} serviceName
+ */
 Environment.prototype.getServiceByName = function getServiceByName(serviceName) {
-  return this[kServices][serviceName];
+  return this[K_SERVICES][serviceName];
 };
+
+/**
+ * Resolve an expression with the environment as scope, optionally extended by an element message.
+ * @param {string} expression
+ * @param {import('#types').ElementBrokerMessage} [message] Element message merged onto the resolution scope
+ * @param {any} [expressionFnContext]
+ */
 Environment.prototype.resolveExpression = function resolveExpression(expression, message, expressionFnContext) {
   const from = {
     environment: this,
@@ -118,9 +183,20 @@ Environment.prototype.resolveExpression = function resolveExpression(expression,
   };
   return this.expressions.resolveExpression(expression, from, expressionFnContext);
 };
+
+/**
+ * Register a service callable by name.
+ * @param {string} name service function name
+ * @param {CallableFunction} fn service function
+ */
 Environment.prototype.addService = function addService(name, fn) {
-  this[kServices][name] = fn;
+  this[K_SERVICES][name] = fn;
 };
+
+/**
+ * @param {import('#types').EnvironmentOptions} input
+ * @returns {import('#types').EnvironmentOptions} validated options
+ */
 function validateOptions(input) {
   const options = {};
   for (const key in input) {
@@ -145,6 +221,10 @@ function validateOptions(input) {
   }
   return options;
 }
+
+/**
+ * @returns {import('#types').ILogger}
+ */
 function DummyLogger() {
   return {
     debug,

package/dist/EventBroker.js

@@ -10,10 +10,21 @@ exports.MessageFlowBroker = MessageFlowBroker;
 exports.ProcessBroker = ProcessBroker;
 var _smqp = require("smqp");
 var _Errors = require("./error/Errors.js");
+/**
+ * Build the broker for an activity, including run/format/execution/api exchanges and queues.
+ * @param {import('#types').Activity} activity
+ * @returns {import('#types').EventBroker<import('#types').Activity>}
+ */
 function ActivityBroker(activity) {
   const executionBroker = ExecutionBroker(activity, 'activity');
   return executionBroker;
 }
+
+/**
+ * Build the broker for a process, with an additional api-q bound to all api routing keys.
+ * @param {import('#types').Process} owner
+ * @returns {import('#types').EventBroker<import('#types').Process>}
+ */
 function ProcessBroker(owner) {
   const executionBroker = ExecutionBroker(owner, 'process');
   executionBroker.broker.assertQueue('api-q', {
@@ -23,9 +34,22 @@ function ProcessBroker(owner) {
   executionBroker.broker.bindQueue('api-q', 'api', '#');
   return executionBroker;
 }
+
+/**
+ * Build the broker for a definition. Optionally registers a custom return-message handler.
+ * @param {import('#types').Definition} owner
+ * @param {(message: import('#types').ElementBrokerMessage) => void} [onBrokerReturn]
+ * @returns {import('#types').EventBroker<import('#types').Definition>}
+ */
 function DefinitionBroker(owner, onBrokerReturn) {
   return ExecutionBroker(owner, 'definition', onBrokerReturn);
 }
+
+/**
+ * Build the broker for a message flow with a durable message exchange and message-q.
+ * @param {import('./flows/MessageFlow.js').MessageFlow} owner
+ * @returns {import('#types').EventBroker<import('./flows/MessageFlow.js').MessageFlow>}
+ */
 function MessageFlowBroker(owner) {
   const eventBroker = new EventBroker(owner, {
     prefix: 'messageflow',
@@ -85,10 +109,17 @@ function ExecutionBroker(brokerOwner, prefix, onBrokerReturn) {
   broker.bindQueue(executionQ.name, 'execution', 'execution.#');
   return eventBroker;
 }
+
+/**
+ * Owns an smqp Broker on behalf of the calling element and exposes prefixed event helpers.
+ * @param {any} brokerOwner Element that owns the broker, accessed as `broker.owner`
+ * @param {{ prefix: string, autoDelete?: boolean, durable?: boolean }} options
+ * @param {(message: import('#types').ElementBrokerMessage) => void} [onBrokerReturn] Override for unrouted return messages
+ */
 function EventBroker(brokerOwner, options, onBrokerReturn) {
   this.options = options;
   this.eventPrefix = options.prefix;
-  const broker = this.broker = (0, _smqp.Broker)(brokerOwner);
+  const broker = this.broker = new _smqp.Broker(brokerOwner);
   broker.assertExchange('event', 'topic', options);
   broker.on('return', onBrokerReturn ? onBrokerReturn.bind(brokerOwner) : this._onBrokerReturnFn.bind(this));
   this.on = this.on.bind(this);
@@ -97,6 +128,11 @@ function EventBroker(brokerOwner, options, onBrokerReturn) {
   this.emit = this.emit.bind(this);
   this.emitFatal = this.emitFatal.bind(this);
 }
+
+/**
+ * Subscribe to a prefixed event. Errors are unwrapped via `makeErrorFromMessage`,
+ * other events resolve to the owner's Api wrapper.
+ */
 EventBroker.prototype.on = function on(eventName, callback, eventOptions = {
   once: false
 }) {
@@ -111,12 +147,20 @@ EventBroker.prototype.on = function on(eventName, callback, eventOptions = {
     callback(owner.getApi(message));
   }
 };
+
+/**
+ * Subscribe to the next occurrence of an event.
+ */
 EventBroker.prototype.once = function once(eventName, callback, eventOptions) {
   return this.on(eventName, callback, {
     ...eventOptions,
     once: true
   });
 };
+
+/**
+ * Promise-style wait for an event. Rejects on a mandatory `*.error` message.
+ */
 EventBroker.prototype.waitFor = function waitFor(eventName, onMessage) {
   const key = this._getEventRoutingKey(eventName);
   return new Promise((resolve, reject) => {
@@ -142,6 +186,10 @@ EventBroker.prototype.waitFor = function waitFor(eventName, onMessage) {
     }
   });
 };
+
+/**
+ * Publish a prefixed event message.
+ */
 EventBroker.prototype.emit = function emit(eventName, content, props) {
   this.broker.publish('event', `${this.eventPrefix}.${eventName}`, {
     ...content
@@ -150,6 +198,10 @@ EventBroker.prototype.emit = function emit(eventName, content, props) {
     ...props
   });
 };
+
+/**
+ * Emit a mandatory error event. Surfaces via `on('error', ...)` or causes a return message to throw.
+ */
 EventBroker.prototype.emitFatal = function emitFatal(error, content) {
   this.emit('error', {
     ...content,
@@ -158,12 +210,16 @@ EventBroker.prototype.emitFatal = function emitFatal(error, content) {
     mandatory: true
   });
 };
+
+/** @internal */
 EventBroker.prototype._onBrokerReturnFn = function onBrokerReturnFn(message) {
   if (message.properties.type === 'error') {
     const err = (0, _Errors.makeErrorFromMessage)(message);
     throw err;
   }
 };
+
+/** @internal */
 EventBroker.prototype._getEventRoutingKey = function getEventRoutingKey(eventName) {
   if (eventName.indexOf('.') > -1) return eventName;
   switch (eventName) {

package/dist/Expressions.js

@@ -3,9 +3,8 @@
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.default = Expressions;
-var _getPropertyValue = _interopRequireDefault(require("./getPropertyValue.js"));
-function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+exports.Expressions = Expressions;
+var _getPropertyValue = require("./getPropertyValue.js");
 const isExpressionPattern = /^\${(.+?)}$/;
 const expressionPattern = /\${(.+?)}/;
 function Expressions() {
@@ -30,7 +29,7 @@ function resolveExpression(templatedString, context, expressionFnContext) {
       const n = Number(innerProperty);
       if (!isNaN(n)) return n;
     }
-    const contextValue = (0, _getPropertyValue.default)(context, innerProperty, expressionFnContext);
+    const contextValue = (0, _getPropertyValue.getPropertyValue)(context, innerProperty, expressionFnContext);
     if (expressionMatch.input === expressionMatch[0]) {
       return contextValue;
     }

package/dist/MessageFormatter.js

@@ -8,13 +8,15 @@ var _messageHelper = require("./messageHelper.js");
 var _shared = require("./shared.js");
 var _Errors = require("./error/Errors.js");
 var _smqp = require("smqp");
-const kOnMessage = Symbol.for('onMessage');
-const kExecution = Symbol.for('execution');
+var _constants = require("./constants.js");
+const K_ON_MESSAGE = Symbol.for('onMessage');
 const EXEC_ROUTING_KEY = 'run._formatting.exec';
 
 /**
- * Message formatter used to enrich an element run message before continuing to the next run message
- * @param {import('types').ElementBase} element
+ * Enriches an element run message via async format start/end messages on the `format` exchange
+ * before the run message is continued. Handlers publish enrichment by responding to a start
+ * message with a matching end (or error) routing key.
+ * @param {import('#types').ElementBase} element
  */
 function Formatter(element) {
   const {
@@ -25,13 +27,14 @@ function Formatter(element) {
   this.id = id;
   this.broker = broker;
   this.logger = logger;
-  this[kOnMessage] = this._onMessage.bind(this);
+  this[K_ON_MESSAGE] = this._onMessage.bind(this);
 }
 
 /**
- * Format message
- * @param {import('types').ElementBrokerMessage} message
- * @param {CallableFunction} callback
+ * Format the given run message. Callback fires with `(err, content, formatted)` once
+ * formatting completes; `formatted` is true when content was actually enriched.
+ * @param {import('#types').ElementBrokerMessage} message
+ * @param {(err: Error | null, content?: import('#types').ElementMessageContent, formatted?: boolean) => void} callback
  */
 Formatter.prototype.format = function format(message, callback) {
   const correlationId = this._runId = (0, _shared.getUniqueId)(message.fields.routingKey);
@@ -41,7 +44,7 @@ Formatter.prototype.format = function format(message, callback) {
     correlationId,
     persistent: false
   });
-  this[kExecution] = {
+  this[_constants.K_EXECUTION] = {
     correlationId,
     formatKey: message.fields.routingKey,
     runMessage: (0, _messageHelper.cloneMessage)(message),
@@ -50,18 +53,20 @@ Formatter.prototype.format = function format(message, callback) {
     formatted: false,
     executeMessage: null
   };
-  broker.consume('format-run-q', this[kOnMessage], {
+  broker.consume('format-run-q', this[K_ON_MESSAGE], {
     consumerTag,
     prefetch: 100
   });
 };
+
+/** @internal */
 Formatter.prototype._onMessage = function onMessage(routingKey, message) {
   const {
     formatKey,
     correlationId,
     pending,
     executeMessage
-  } = this[kExecution];
+  } = this[_constants.K_EXECUTION];
   const asyncFormatting = pending.size;
   if (routingKey === EXEC_ROUTING_KEY) {
     if (message.properties.correlationId !== correlationId) return message.ack();
@@ -69,7 +74,7 @@ Formatter.prototype._onMessage = function onMessage(routingKey, message) {
     if (!asyncFormatting) {
       return this._complete(message);
     }
-    this[kExecution].executeMessage = message;
+    this[_constants.K_EXECUTION].executeMessage = message;
   } else {
     message.ack();
     const endRoutingKey = message.content?.endRoutingKey;
@@ -91,6 +96,8 @@ Formatter.prototype._onMessage = function onMessage(routingKey, message) {
     }
   }
 };
+
+/** @internal */
 Formatter.prototype._complete = function complete(message, isError) {
   const {
     runMessage,
@@ -98,8 +105,8 @@ Formatter.prototype._complete = function complete(message, isError) {
     callback,
     formatted,
     executeMessage
-  } = this[kExecution];
-  this[kExecution] = null;
+  } = this[_constants.K_EXECUTION];
+  this[_constants.K_EXECUTION] = null;
   if (executeMessage) executeMessage.ack();
   this.broker.cancel(message.fields.consumerTag);
   if (isError) {
@@ -110,8 +117,10 @@ Formatter.prototype._complete = function complete(message, isError) {
   }
   return callback(null, runMessage.content, formatted);
 };
+
+/** @internal */
 Formatter.prototype._enrich = function enrich(withContent) {
-  const content = this[kExecution].runMessage.content;
+  const content = this[_constants.K_EXECUTION].runMessage.content;
   for (const key in withContent) {
     switch (key) {
       case 'id':
@@ -129,11 +138,13 @@ Formatter.prototype._enrich = function enrich(withContent) {
       default:
         {
           content[key] = withContent[key];
-          this[kExecution].formatted = true;
+          this[_constants.K_EXECUTION].formatted = true;
         }
     }
   }
 };
+
+/** @internal */
 Formatter.prototype._popFormatStart = function popFormattingStart(pending, routingKey) {
   for (const msg of pending) {
     const {
@@ -156,6 +167,8 @@ Formatter.prototype._popFormatStart = function popFormattingStart(pending, routi
   }
   return {};
 };
+
+/** @internal */
 Formatter.prototype._debug = function debug(msg) {
   this.logger.debug(`<${this.id}> ${msg}`);
 };

package/dist/Timers.js

@@ -4,9 +4,13 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.Timers = Timers;
-const kExecuting = Symbol.for('executing');
-const kTimerApi = Symbol.for('timers api');
+const K_EXECUTING = Symbol.for('executing');
+const K_TIMER_API = Symbol.for('timers api');
 const MAX_DELAY = 2147483647;
+
+/**
+ * @param {import('#types').TimersOptions} options
+ */
 function Timers(options) {
   this.count = 0;
   this.options = {
@@ -14,13 +18,13 @@ function Timers(options) {
     clearTimeout,
     ...options
   };
-  this[kExecuting] = new Set();
+  this[K_EXECUTING] = new Set();
   this.setTimeout = this.setTimeout.bind(this);
   this.clearTimeout = this.clearTimeout.bind(this);
 }
 Object.defineProperty(Timers.prototype, 'executing', {
   get() {
-    return [...this[kExecuting]];
+    return [...this[K_EXECUTING]];
   }
 });
 Timers.prototype.register = function register(owner) {
@@ -30,14 +34,14 @@ Timers.prototype.setTimeout = function wrappedSetTimeout(callback, delay, ...arg
   return this._setTimeout(null, callback, delay, ...args);
 };
 Timers.prototype.clearTimeout = function wrappedClearTimeout(ref) {
-  if (this[kExecuting].delete(ref)) {
+  if (this[K_EXECUTING].delete(ref)) {
     ref.timerRef = this.options.clearTimeout(ref.timerRef);
     return;
   }
   return this.options.clearTimeout(ref);
 };
 Timers.prototype._setTimeout = function setTimeout(owner, callback, delay, ...args) {
-  const executing = this[kExecuting];
+  const executing = this[K_EXECUTING];
   const ref = this._getReference(owner, callback, delay, args);
   executing.add(ref);
   if (delay < MAX_DELAY) {
@@ -53,17 +57,17 @@ Timers.prototype._getReference = function getReference(owner, callback, delay, a
   return new Timer(owner, `timer_${this.count++}`, callback, delay, args);
 };
 function RegisteredTimers(timersApi, owner) {
-  this[kTimerApi] = timersApi;
+  this[K_TIMER_API] = timersApi;
   this.owner = owner;
   this.setTimeout = this.setTimeout.bind(this);
   this.clearTimeout = this.clearTimeout.bind(this);
 }
 RegisteredTimers.prototype.setTimeout = function registeredSetTimeout(callback, delay, ...args) {
-  const timersApi = this[kTimerApi];
+  const timersApi = this[K_TIMER_API];
   return timersApi._setTimeout(this.owner, callback, delay, ...args);
 };
 RegisteredTimers.prototype.clearTimeout = function registeredClearTimeout(ref) {
-  this[kTimerApi].clearTimeout(ref);
+  this[K_TIMER_API].clearTimeout(ref);
 };
 function Timer(owner, timerId, callback, delay, args) {
   this.callback = callback;

package/dist/Tracker.js

@@ -36,6 +36,7 @@ ActivityTracker.prototype.track = function track(routingKey, message) {
       this._executing(executionId);
       break;
     case 'activity.execution.outbound.take':
+    case 'activity.converge':
     case 'activity.detach':
     case 'activity.call':
     case 'activity.wait':