bpmn-elements 17.2.2 → 18.0.0

package/src/Context.js

@@ -1,25 +1,41 @@
-import BpmnIO from './io/BpmnIO.js';
-import Environment from './Environment.js';
+import { BpmnIO } from './io/BpmnIO.js';
+import { Environment } from './Environment.js';
 import { getUniqueId } from './shared.js';
+import { K_ACTIVATED } from './constants.js';
 
-const kOwner = Symbol.for('owner');
-const kActivated = Symbol.for('activated');
+const K_OWNER = Symbol.for('owner');
 
-export default function Context(definitionContext, environment) {
+/**
+ * Build a runtime Context from a parsed BPMN definition.
+ * @param {import('moddle-context-serializer').SerializableContext} definitionContext
+ * @param {import('#types').Environment} [environment] Existing environment to clone; a fresh one is created when omitted
+ */
+export function Context(definitionContext, environment) {
   environment = environment ? environment.clone() : new Environment();
   return new ContextInstance(definitionContext, environment);
 }
 
-function ContextInstance(definitionContext, environment, owner) {
+/**
+ * Per-execution registry that lazily upserts activities, flows, and processes from the parsed BPMN definition.
+ * @param {import('moddle-context-serializer').SerializableContext} definitionContext
+ * @param {import('#types').Environment} environment
+ * @param {import('#types').Process | import('#types').Activity} [owner] Process or sub-process activity that owns this context
+ * @param {Map<string, any>} [peersCache] Shared converging parallel gateway peer cache; created at the root and propagated to every clone
+ */
+export function ContextInstance(definitionContext, environment, owner, peersCache) {
   const { id = 'Def', name, type = 'context' } = definitionContext;
-  const sid = getUniqueId(id);
   this.id = id;
   this.name = name;
   this.type = type;
-  this.sid = sid;
+  /** Unique instance id */
+  this.sid = getUniqueId(id);
   this.definitionContext = definitionContext;
   this.environment = environment;
+  /** Discovered parallel gateway peers, keyed by gateway id, shared with all clones. Runtime-only, not serialized. */
+  this.peersCache = peersCache || new Map();
+  /** @type {import('#types').IExtensionsMapper}  */
   this.extensionsMapper = new ExtensionsMapper(this);
+  /** @private */
   this.refs = new Map([
     ['activityRefs', new Map()],
     ['sequenceFlowRefs', new Map()],
@@ -29,15 +45,21 @@ function ContextInstance(definitionContext, environment, owner) {
     ['dataObjectRefs', new Map()],
     ['dataStoreRefs', new Map()],
   ]);
-  this[kOwner] = owner;
+  this[K_OWNER] = owner;
 }
 
 Object.defineProperty(ContextInstance.prototype, 'owner', {
+  /** @returns {import('#types').Process | import('#types').Activity | undefined} Process or sub-process activity that owns this context */
   get() {
-    return this[kOwner];
+    return this[K_OWNER];
   },
 });
 
+/**
+ * Get or create the activity instance for the given id.
+ * @param {string} activityId
+ * @returns {import('./activity/Activity.js').Activity | null}
+ */
 ContextInstance.prototype.getActivityById = function getActivityById(activityId) {
   const activityInstance = this.refs.get('activityRefs').get(activityId);
   if (activityInstance) return activityInstance;
@@ -46,6 +68,11 @@ ContextInstance.prototype.getActivityById = function getActivityById(activityId)
   return this.upsertActivity(activity);
 };
 
+/**
+ * Return the cached activity instance, instantiating it the first time it is referenced.
+ * @param {import('moddle-context-serializer').SerializableElement} activityDef
+ * @returns {import('./activity/Activity.js').Activity}
+ */
 ContextInstance.prototype.upsertActivity = function upsertActivity(activityDef) {
   let activityInstance = this.refs.get('activityRefs').get(activityDef.id);
   if (activityInstance) return activityInstance;
@@ -56,6 +83,11 @@ ContextInstance.prototype.upsertActivity = function upsertActivity(activityDef)
   return activityInstance;
 };
 
+/**
+ * Get or create the sequence flow instance for the given id.
+ * @param {string} sequenceFlowId
+ * @returns {import('./flows/SequenceFlow.js').SequenceFlow | null}
+ */
 ContextInstance.prototype.getSequenceFlowById = function getSequenceFlowById(sequenceFlowId) {
   const flowInstance = this.refs.get('sequenceFlowRefs').get(sequenceFlowId);
   if (flowInstance) return flowInstance;
@@ -65,30 +97,55 @@ ContextInstance.prototype.getSequenceFlowById = function getSequenceFlowById(seq
   return this.upsertSequenceFlow(flowDef);
 };
 
+/**
+ * @param {string} activityId
+ */
 ContextInstance.prototype.getInboundSequenceFlows = function getInboundSequenceFlows(activityId) {
   return (this.definitionContext.getInboundSequenceFlows(activityId) || []).map((flow) => this.upsertSequenceFlow(flow));
 };
 
+/**
+ * @param {string} activityId
+ */
 ContextInstance.prototype.getOutboundSequenceFlows = function getOutboundSequenceFlows(activityId) {
   return (this.definitionContext.getOutboundSequenceFlows(activityId) || []).map((flow) => this.upsertSequenceFlow(flow));
 };
 
+/**
+ * @param {string} activityId
+ */
 ContextInstance.prototype.getInboundAssociations = function getInboundAssociations(activityId) {
   return (this.definitionContext.getInboundAssociations(activityId) || []).map((association) => this.upsertAssociation(association));
 };
 
+/**
+ * @param {string} activityId
+ */
 ContextInstance.prototype.getOutboundAssociations = function getOutboundAssociations(activityId) {
   return (this.definitionContext.getOutboundAssociations(activityId) || []).map((association) => this.upsertAssociation(association));
 };
 
+/**
+ * Get every activity in the definition, optionally narrowed to a parent scope.
+ * @param {string} [scopeId] Process or sub-process id
+ */
 ContextInstance.prototype.getActivities = function getActivities(scopeId) {
   return (this.definitionContext.getActivities(scopeId) || []).map((activityDef) => this.upsertActivity(activityDef));
 };
 
+/**
+ * Get every sequence flow in the definition, optionally narrowed to a parent scope.
+ * @param {string} [scopeId] Process or sub-process id
+ */
 ContextInstance.prototype.getSequenceFlows = function getSequenceFlows(scopeId) {
   return (this.definitionContext.getSequenceFlows(scopeId) || []).map((flow) => this.upsertSequenceFlow(flow));
 };
 
+/**
+ * Return the cached sequence flow, instantiating it the first time it is referenced.
+ * @param {import('moddle-context-serializer').SerializableElement} flowDefinition
+ * @returns {import('./flows/SequenceFlow.js').SequenceFlow}
+ */
 ContextInstance.prototype.upsertSequenceFlow = function upsertSequenceFlow(flowDefinition) {
   const sequenceFlowRefs = this.refs.get('sequenceFlowRefs');
   let flowInstance = sequenceFlowRefs.get(flowDefinition.id);
@@ -100,10 +157,18 @@ ContextInstance.prototype.upsertSequenceFlow = function upsertSequenceFlow(flowD
   return flowInstance;
 };
 
+/**
+ * Get association flows
+ * @param {string} [scopeId] Process or sub-process id
+ */
 ContextInstance.prototype.getAssociations = function getAssociations(scopeId) {
   return (this.definitionContext.getAssociations(scopeId) || []).map((association) => this.upsertAssociation(association));
 };
 
+/**
+ * @param {import('moddle-context-serializer').SerializableElement} associationDefinition
+ * @returns {import('./flows/Association.js').Association}
+ */
 ContextInstance.prototype.upsertAssociation = function upsertAssociation(associationDefinition) {
   const associationRefs = this.refs.get('associationRefs');
   let instance = associationRefs.get(associationDefinition.id);
@@ -116,10 +181,38 @@ ContextInstance.prototype.upsertAssociation = function upsertAssociation(associa
   return instance;
 };
 
+/**
+ * Create a new context that shares the parsed definition but optionally swaps environment and owner.
+ * @param {import('#types').Environment} [newEnvironment]
+ * @param {import('#types').Process | import('#types').Activity} [newOwner]
+ */
 ContextInstance.prototype.clone = function clone(newEnvironment, newOwner) {
-  return new ContextInstance(this.definitionContext, newEnvironment || this.environment, newOwner);
+  return new ContextInstance(this.definitionContext, newEnvironment || this.environment, newOwner, this.peersCache);
 };
 
+/**
+ * Cached converging parallel gateway peers discovered by an earlier shake.
+ * @param {string} gatewayId
+ * @returns {Array<[string, string[]]> | undefined}
+ */
+ContextInstance.prototype.getShakenPeers = function getShakenPeers(gatewayId) {
+  return this.peersCache.get(gatewayId);
+};
+
+/**
+ * Store converging parallel gateway peers so subsequent runs can skip the graph shake.
+ * @param {string} gatewayId
+ * @param {Array<[string, string[]]>} peers
+ */
+ContextInstance.prototype.setShakenPeers = function setShakenPeers(gatewayId, peers) {
+  this.peersCache.set(gatewayId, peers);
+};
+
+/**
+ * Get or create the process instance for the given id. Each process gets its own cloned environment.
+ * @param {string} processId
+ * @returns {import('#types').Process | null}
+ */
 ContextInstance.prototype.getProcessById = function getProcessById(processId) {
   const processRefs = this.refs.get('processRefs');
   let bp = processRefs.get(processId);
@@ -131,30 +224,48 @@ ContextInstance.prototype.getProcessById = function getProcessById(processId) {
   const bpContext = this.clone(this.environment.clone());
   bp = new processDefinition.Behaviour(processDefinition, bpContext);
   processRefs.set(processId, bp);
-  bpContext[kOwner] = bp;
+  bpContext[K_OWNER] = bp;
 
   return bp;
 };
 
+/**
+ * Build a fresh, uncached process instance for the given id. Used by call activities.
+ * @param {string} processId
+ * @returns {import('#types').Process | null}
+ */
 ContextInstance.prototype.getNewProcessById = function getNewProcessById(processId) {
   if (!this.getProcessById(processId)) return null;
   const bpDef = this.definitionContext.getProcessById(processId);
 
   const bpContext = this.clone(this.environment.clone());
   const bp = new bpDef.Behaviour(bpDef, bpContext);
-  bpContext[kOwner] = bp;
+  bpContext[K_OWNER] = bp;
 
   return bp;
 };
 
+/**
+ * Get every process in the definition.
+ * @returns {import('#types').Process[]}
+ */
 ContextInstance.prototype.getProcesses = function getProcesses() {
   return this.definitionContext.getProcesses().map(({ id: processId }) => this.getProcessById(processId));
 };
 
+/**
+ * Get processes flagged executable in the definition.
+ * @returns {import('#types').Process[]}
+ */
 ContextInstance.prototype.getExecutableProcesses = function getExecutableProcesses() {
   return this.definitionContext.getExecutableProcesses().map(({ id: processId }) => this.getProcessById(processId));
 };
 
+/**
+ * Get message flows that originate from the given process id.
+ * @param {string} sourceId Source process id
+ * @returns {import('./flows/MessageFlow.js').MessageFlow[]}
+ */
 ContextInstance.prototype.getMessageFlows = function getMessageFlows(sourceId) {
   const messageFlowRefs = this.refs.get('messageFlows');
 
@@ -176,6 +287,11 @@ ContextInstance.prototype.getMessageFlows = function getMessageFlows(sourceId) {
   return result;
 };
 
+/**
+ * Get or create a data object instance for the given reference id.
+ * @param {string} referenceId
+ * @return {import('#types').IIOData | undefined}
+ */
 ContextInstance.prototype.getDataObjectById = function getDataObjectById(referenceId) {
   const dataObjectRefs = this.refs.get('dataObjectRefs');
   let dataObject;
@@ -190,6 +306,11 @@ ContextInstance.prototype.getDataObjectById = function getDataObjectById(referen
   return dataObject;
 };
 
+/**
+ * Get or create a data store instance for the given reference id.
+ * @param {string} referenceId
+ * @return {import('#types').IIOData | undefined}
+ */
 ContextInstance.prototype.getDataStoreById = function getDataStoreById(referenceId) {
   const dataStoreRefs = this.refs.get('dataStoreRefs');
   let dataStore;
@@ -205,6 +326,11 @@ ContextInstance.prototype.getDataStoreById = function getDataStoreById(reference
   return dataStore;
 };
 
+/**
+ * Get start activities, optionally filtered by referenced event definition or restricted to a parent scope.
+ * @param {import('#types').startActivityFilterOptions} [filterOptions]
+ * @param {string} [scopeId] Process or sub-process id
+ */
 ContextInstance.prototype.getStartActivities = function getStartActivities(filterOptions, scopeId) {
   const referenceId = filterOptions?.referenceId;
   const referenceType = filterOptions?.referenceType || 'unknown';
@@ -227,6 +353,56 @@ ContextInstance.prototype.getStartActivities = function getStartActivities(filte
   return result;
 };
 
+/**
+ * Inspect an activity def for link event definitions.
+ * @param {import('moddle-context-serializer').Activity} activityDef
+ * @returns {{ linkBehaviour?: Function, linkNames?: string[] }}
+ */
+ContextInstance.prototype.getLinkEventDefinitionInfo = function getLinkEventDefinitionInfo(activityDef) {
+  const eds = activityDef.behaviour?.eventDefinitions;
+  if (!eds) return {};
+  let linkBehaviour;
+  const names = new Set();
+  for (const ed of eds) {
+    if (linkBehaviour ? ed.Behaviour === linkBehaviour : ed.type?.endsWith('LinkEventDefinition')) {
+      if (!linkBehaviour) linkBehaviour = ed.Behaviour;
+      if (ed.behaviour?.name) names.add(ed.behaviour.name);
+    }
+  }
+  if (!linkBehaviour || !names.size) return {};
+  return { linkBehaviour, linkNames: [...names] };
+};
+
+/**
+ * Get activities whose event definitions include the given Behaviour with a matching name.
+ * @param {Function} Behaviour Behaviour constructor to match against `ed.Behaviour`
+ * @param {string[] | Iterable<string>} names
+ * @param {string} [scopeId] Process or sub-process id
+ */
+ContextInstance.prototype.getActivitiesByEventDefinitionBehaviour = function getActivitiesByEventDefinitionBehaviour(
+  Behaviour,
+  names,
+  scopeId
+) {
+  const wanted = new Set(names);
+  if (!Behaviour || !wanted.size) return [];
+  const result = [];
+  const rawDefs = this.definitionContext.getActivities(scopeId) || [];
+  for (const rawDef of rawDefs) {
+    const eds = rawDef.behaviour?.eventDefinitions;
+    if (!eds) continue;
+    if (!eds.some((ed) => ed.Behaviour === Behaviour && wanted.has(ed.behaviour?.name))) continue;
+    result.push(this.upsertActivity(rawDef));
+  }
+  return result;
+};
+
+/**
+ * Resolve user-registered extensions and the built-in BpmnIO extension for an activity.
+ * Returns undefined when the activity has no extensions to attach.
+ * @param {import('#types').ElementBase} activity
+ * @returns {import('#types').IExtension | undefined}
+ */
 ContextInstance.prototype.loadExtensions = function loadExtensions(activity) {
   const io = new BpmnIO(activity, this);
   const extensions = this.extensionsMapper.get(activity);
@@ -235,8 +411,12 @@ ContextInstance.prototype.loadExtensions = function loadExtensions(activity) {
   return extensions;
 };
 
+/**
+ * Resolve the parent process or sub-process activity that owns the given activity.
+ * @param {string} activityId
+ */
 ContextInstance.prototype.getActivityParentById = function getActivityParentById(activityId) {
-  const owner = this[kOwner];
+  const owner = this[K_OWNER];
   if (owner) return owner;
   const activity = this.getActivityById(activityId);
   const parentId = activity.parent.id;
@@ -251,6 +431,7 @@ ExtensionsMapper.prototype.get = function get(activity) {
   return new Extensions(activity, this.context, this._getExtensions());
 };
 
+/** @internal */
 ExtensionsMapper.prototype._getExtensions = function getExtensions() {
   let extensions;
   if (!(extensions = this.context.environment.extensions)) return [];
@@ -263,7 +444,7 @@ function Extensions(activity, context, extensions) {
     const extension = Extension(activity, context);
     if (extension) result.push(extension);
   }
-  this[kActivated] = false;
+  this[K_ACTIVATED] = false;
 }
 
 Object.defineProperty(Extensions.prototype, 'count', {
@@ -273,13 +454,13 @@ Object.defineProperty(Extensions.prototype, 'count', {
 });
 
 Extensions.prototype.activate = function activate(message) {
-  if (this[kActivated]) return;
-  this[kActivated] = true;
+  if (this[K_ACTIVATED]) return;
+  this[K_ACTIVATED] = true;
   for (const extension of this.extensions) extension.activate(message);
 };
 
 Extensions.prototype.deactivate = function deactivate(message) {
-  if (!this[kActivated]) return;
-  this[kActivated] = false;
+  if (!this[K_ACTIVATED]) return;
+  this[K_ACTIVATED] = false;
   for (const extension of this.extensions) extension.deactivate(message);
 };

package/src/Environment.js

@@ -1,69 +1,96 @@
-import Expressions from './Expressions.js';
+import { Expressions } from './Expressions.js';
 import { Scripts } from './Scripts.js';
 import { Timers } from './Timers.js';
 
-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']);
 
-export default function Environment(options = {}) {
+/**
+ * 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]
+ */
+export function Environment(options = {}) {
   this.options = validateOptions(options);
 
+  /** @type {import('#types').IExpressions} */
   this.expressions = options.expressions || Expressions();
   this.extensions = options.extensions;
   this.output = options.output || {};
+  /** @type {import('#types').IScripts} */
   this.scripts = options.scripts || new Scripts();
+  /** @type {import('#types').ITimers} */
   this.timers = options.timers || new 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];
   },
-  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);
-    },
+});
+
+Object.defineProperty(Environment.prototype, 'services', {
+  /** @returns {Record<string, CallableFunction>} */
+  get() {
+    return this[K_SERVICES];
+  },
+  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] },
+    variables: { ...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] },
+    variables: { ...this[K_VARIABLES] },
     Logger: this.Logger,
     extensions: this.extensions,
     scripts: this.scripts,
@@ -79,36 +106,66 @@ 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,10 +175,19 @@ 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) {
@@ -151,6 +217,9 @@ function validateOptions(input) {
   return options;
 }
 
+/**
+ * @returns {import('#types').ILogger}
+ */
 function DummyLogger() {
   return {
     debug,