bpmn-elements 17.2.2 → 18.0.0

package/src/EventBroker.js

@@ -1,11 +1,21 @@
 import { Broker } from 'smqp';
 import { makeErrorFromMessage } from './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>}
+ */
 export 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>}
+ */
 export function ProcessBroker(owner) {
   const executionBroker = ExecutionBroker(owner, 'process');
   executionBroker.broker.assertQueue('api-q', { durable: false, autoDelete: false });
@@ -13,10 +23,21 @@ export function ProcessBroker(owner) {
   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>}
+ */
 export 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>}
+ */
 export function MessageFlowBroker(owner) {
   const eventBroker = new EventBroker(owner, { prefix: 'messageflow', autoDelete: false, durable: false });
   const broker = eventBroker.broker;
@@ -49,11 +70,17 @@ function ExecutionBroker(brokerOwner, prefix, onBrokerReturn) {
   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
+ */
 export function EventBroker(brokerOwner, options, onBrokerReturn) {
   this.options = options;
   this.eventPrefix = options.prefix;
 
-  const broker = (this.broker = Broker(brokerOwner));
+  const broker = (this.broker = new Broker(brokerOwner));
   broker.assertExchange('event', 'topic', options);
   broker.on('return', onBrokerReturn ? onBrokerReturn.bind(brokerOwner) : this._onBrokerReturnFn.bind(this));
 
@@ -64,6 +91,10 @@ export function EventBroker(brokerOwner, options, onBrokerReturn) {
   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 }) {
   const key = this._getEventRoutingKey(eventName);
 
@@ -76,10 +107,16 @@ EventBroker.prototype.on = function on(eventName, callback, eventOptions = { onc
   }
 };
 
+/**
+ * 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);
 
@@ -109,14 +146,21 @@ 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 }, { type: eventName, ...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, error }, { mandatory: true });
 };
 
+/** @internal */
 EventBroker.prototype._onBrokerReturnFn = function onBrokerReturnFn(message) {
   if (message.properties.type === 'error') {
     const err = makeErrorFromMessage(message);
@@ -124,6 +168,7 @@ EventBroker.prototype._onBrokerReturnFn = function onBrokerReturnFn(message) {
   }
 };
 
+/** @internal */
 EventBroker.prototype._getEventRoutingKey = function getEventRoutingKey(eventName) {
   if (eventName.indexOf('.') > -1) return eventName;
 

package/src/Expressions.js

@@ -1,9 +1,8 @@
-import getPropertyValue from './getPropertyValue.js';
-
+import { getPropertyValue } from './getPropertyValue.js';
 const isExpressionPattern = /^\${(.+?)}$/;
 const expressionPattern = /\${(.+?)}/;
 
-export default function Expressions() {
+export function Expressions() {
   return {
     resolveExpression,
     isExpression,

package/src/MessageFormatter.js

@@ -2,28 +2,31 @@ import { cloneMessage } from './messageHelper.js';
 import { getUniqueId } from './shared.js';
 import { ActivityError } from './error/Errors.js';
 import { getRoutingKeyPattern } from 'smqp';
+import { K_EXECUTION } from './constants.js';
 
-const kOnMessage = Symbol.for('onMessage');
-const kExecution = Symbol.for('execution');
+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
  */
 export function Formatter(element) {
   const { id, broker, logger } = 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 = getUniqueId(message.fields.routingKey));
@@ -32,7 +35,7 @@ Formatter.prototype.format = function format(message, callback) {
 
   broker.publish('format', EXEC_ROUTING_KEY, {}, { correlationId, persistent: false });
 
-  this[kExecution] = {
+  this[K_EXECUTION] = {
     correlationId,
     formatKey: message.fields.routingKey,
     runMessage: cloneMessage(message),
@@ -42,14 +45,15 @@ Formatter.prototype.format = function format(message, callback) {
     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];
+  const { formatKey, correlationId, pending, executeMessage } = this[K_EXECUTION];
   const asyncFormatting = pending.size;
 
   if (routingKey === EXEC_ROUTING_KEY) {
@@ -58,7 +62,7 @@ Formatter.prototype._onMessage = function onMessage(routingKey, message) {
     if (!asyncFormatting) {
       return this._complete(message);
     }
-    this[kExecution].executeMessage = message;
+    this[K_EXECUTION].executeMessage = message;
   } else {
     message.ack();
 
@@ -87,9 +91,10 @@ Formatter.prototype._onMessage = function onMessage(routingKey, message) {
   }
 };
 
+/** @internal */
 Formatter.prototype._complete = function complete(message, isError) {
-  const { runMessage, formatKey, callback, formatted, executeMessage } = this[kExecution];
-  this[kExecution] = null;
+  const { runMessage, formatKey, callback, formatted, executeMessage } = this[K_EXECUTION];
+  this[K_EXECUTION] = null;
   if (executeMessage) executeMessage.ack();
 
   this.broker.cancel(message.fields.consumerTag);
@@ -104,8 +109,9 @@ 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[K_EXECUTION].runMessage.content;
   for (const key in withContent) {
     switch (key) {
       case 'id':
@@ -122,12 +128,13 @@ Formatter.prototype._enrich = function enrich(withContent) {
         break;
       default: {
         content[key] = withContent[key];
-        this[kExecution].formatted = true;
+        this[K_EXECUTION].formatted = true;
       }
     }
   }
 };
 
+/** @internal */
 Formatter.prototype._popFormatStart = function popFormattingStart(pending, routingKey) {
   for (const msg of pending) {
     const { endRoutingKey, errorRoutingKey = '#.error' } = msg.content;
@@ -144,6 +151,7 @@ Formatter.prototype._popFormatStart = function popFormattingStart(pending, routi
   return {};
 };
 
+/** @internal */
 Formatter.prototype._debug = function debug(msg) {
   this.logger.debug(`<${this.id}> ${msg}`);
 };

package/src/Timers.js

@@ -1,8 +1,11 @@
-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
+ */
 export function Timers(options) {
   this.count = 0;
   this.options = {
@@ -10,14 +13,14 @@ export 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]];
   },
 });
 
@@ -30,7 +33,7 @@ Timers.prototype.setTimeout = function wrappedSetTimeout(callback, delay, ...arg
 };
 
 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;
   }
@@ -38,7 +41,7 @@ Timers.prototype.clearTimeout = function wrappedClearTimeout(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) {
@@ -57,19 +60,19 @@ Timers.prototype._getReference = function getReference(owner, callback, delay, a
 };
 
 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) {

package/src/Tracker.js

@@ -29,6 +29,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': {