bpmn-engine 25.0.0 → 26.0.0

package/lib/index.cjs

@@ -8,7 +8,7 @@ var node_url = require('node:url');
 var BpmnModdle = require('bpmn-moddle');
 var Elements = require('bpmn-elements');
 var smqp = require('smqp');
-var serializer = require('moddle-context-serializer');
+var moddleContextSerializer = require('moddle-context-serializer');
 var Debug = require('debug');
 var node_vm = require('node:vm');
 
@@ -175,6 +175,10 @@ const kState = Symbol.for('state');
 const kStopped = Symbol.for('stopped');
 const kTypeResolver = Symbol.for('type resolver');
 
+/**
+ * BPMN 2.0 execution engine.
+ * @param {import('types').BpmnEngineOptions} [options]
+ */
 function Engine(options) {
   if (!(this instanceof Engine)) return new Engine(options);
 
@@ -188,7 +192,7 @@ function Engine(options) {
 
   this.logger = opts.Logger('engine');
 
-  this[kTypeResolver] = serializer.TypeResolver(
+  this[kTypeResolver] = moddleContextSerializer.TypeResolver(
     {
       ...Elements__namespace,
       ...opts.elements,
@@ -260,6 +264,12 @@ Object.defineProperties(Engine.prototype, {
   },
 });
 
+/**
+ * Execute the loaded definitions.
+ * @param {import('types').BpmnEngineExecuteOptions | ((err: Error, execution?: Execution) => void)} [optionsOrCallback]
+ * @param {(err: Error, execution?: Execution) => void} [callback]
+ * @returns {Promise<Execution>}
+ */
 Engine.prototype.execute = async function execute(...args) {
   const [executeOptions, callback] = getOptionsAndCallback(...args);
   try {
@@ -273,12 +283,19 @@ Engine.prototype.execute = async function execute(...args) {
   return execution._execute(executeOptions, callback);
 };
 
+/** @returns {Promise<void>} */
 Engine.prototype.stop = function stop() {
   const execution = this.execution;
   if (!execution) return;
   return execution.stop();
 };
 
+/**
+ * Recover engine from saved state.
+ * @param {import('types').BpmnEngineExecutionState | null} savedState
+ * @param {import('types').BpmnEngineOptions} [recoverOptions]
+ * @returns {Engine}
+ */
 Engine.prototype.recover = function recover(savedState, recoverOptions) {
   if (this[kExecution]?.isRunning) {
     throw new Error('cannot recover a running engine');
@@ -306,7 +323,7 @@ Engine.prototype.recover = function recover(savedState, recoverOptions) {
   const typeResolver = this[kTypeResolver];
   const loadedDefinitions = (this[kLoadedDefinitions] = savedState.definitions.map((dState) => {
     let source;
-    if (dState.source) source = serializer.deserialize(JSON.parse(dState.source), typeResolver);
+    if (dState.source) source = moddleContextSerializer.deserialize(JSON.parse(dState.source), typeResolver);
     else source = preSources.find((s) => s.id === dState.id);
 
     pendingSources.add(source);
@@ -324,6 +341,12 @@ Engine.prototype.recover = function recover(savedState, recoverOptions) {
   return this;
 };
 
+/**
+ * Resume execution from a previously recovered state.
+ * @param {import('types').BpmnEngineExecuteOptions | ((err: Error, execution?: Execution) => void)} [optionsOrCallback]
+ * @param {(err: Error, execution?: Execution) => void} [callback]
+ * @returns {Promise<Execution>}
+ */
 Engine.prototype.resume = async function resume(...args) {
   const [resumeOptions, callback] = getOptionsAndCallback(...args);
 
@@ -345,6 +368,10 @@ Engine.prototype.resume = async function resume(...args) {
   return execution._resume(resumeOptions, callback);
 };
 
+/**
+ * Add a pre-serialized source context to the engine.
+ * @param {{ sourceContext: import('types').SerializableContext }} [options]
+ */
 Engine.prototype.addSource = function addSource(options) {
   if (!options?.sourceContext) return;
   const loadedDefinitions = this[kLoadedDefinitions];
@@ -352,16 +379,25 @@ Engine.prototype.addSource = function addSource(options) {
   this[kPendingSources].add(options.sourceContext);
 };
 
+/**
+ * @param {import('types').BpmnEngineExecuteOptions} [executeOptions]
+ * @returns {Promise<import('bpmn-elements').Definition[]>}
+ */
 Engine.prototype.getDefinitions = function getDefinitions(executeOptions) {
   const loadedDefinitions = this[kLoadedDefinitions];
   if (loadedDefinitions?.length) return Promise.resolve(loadedDefinitions);
   return this._loadDefinitions(executeOptions);
 };
 
+/**
+ * @param {string} id
+ * @returns {Promise<import('bpmn-elements').Definition>}
+ */
 Engine.prototype.getDefinitionById = async function getDefinitionById(id) {
   return (await this.getDefinitions()).find((d) => d.id === id);
 };
 
+/** @returns {Promise<import('types').BpmnEngineExecutionState>} */
 Engine.prototype.getState = async function getState() {
   const execution = this.execution;
   if (execution) return execution.getState();
@@ -370,6 +406,11 @@ Engine.prototype.getState = async function getState() {
   return new Execution(this, definitions, this.options).getState();
 };
 
+/**
+ * @template R
+ * @param {import('types').BpmnEngineEvent} eventName
+ * @returns {Promise<R>}
+ */
 Engine.prototype.waitFor = function waitFor(eventName) {
   const self = this;
   return new Promise((resolve, reject) => {
@@ -387,12 +428,14 @@ Engine.prototype.waitFor = function waitFor(eventName) {
   });
 };
 
+/** @internal */
 Engine.prototype._loadDefinitions = async function loadDefinitions(executeOptions) {
   const runSources = await Promise.all(this[kPendingSources]);
   const loadedDefinitions = (this[kLoadedDefinitions] = runSources.map((source) => this._loadDefinition(source, executeOptions)));
   return loadedDefinitions;
 };
 
+/** @internal */
 Engine.prototype._loadDefinition = function loadDefinition(serializedContext, executeOptions) {
   const environment = this.environment;
   const context = new Elements__namespace.Context(
@@ -415,20 +458,29 @@ Engine.prototype._loadDefinition = function loadDefinition(serializedContext, ex
   return new Elements__namespace.Definition(context);
 };
 
+/** @internal */
 Engine.prototype._serializeSource = async function serializeSource(source) {
   const moddleContext = await this._getModdleContext(source);
   return this._serializeModdleContext(moddleContext);
 };
 
+/** @internal */
 Engine.prototype._serializeModdleContext = function serializeModdleContext(moddleContext) {
-  return serializer(moddleContext, this[kTypeResolver], this.options.extendFn);
+  return moddleContextSerializer.Serializer(moddleContext, this[kTypeResolver], this.options.extendFn);
 };
 
+/** @internal */
 Engine.prototype._getModdleContext = function getModdleContext(source) {
   const bpmnModdle = new BpmnModdle(this.options.moddleOptions);
   return bpmnModdle.fromXML(Buffer.isBuffer(source) ? source.toString() : source.trim());
 };
 
+/**
+ * @param {Engine} engine
+ * @param {any[]} definitions
+ * @param {import('types').BpmnEngineExecuteOptions} [options]
+ * @param {boolean} [isRecovered]
+ */
 function Execution(engine, definitions, options, isRecovered = false) {
   this.name = engine.name;
   this.options = options;
@@ -478,6 +530,7 @@ Object.defineProperties(Execution.prototype, {
   },
 });
 
+/** @internal */
 Execution.prototype._execute = function execute(executeOptions, callback) {
   this._setup(executeOptions);
   this[kStopped] = false;
@@ -499,6 +552,7 @@ Execution.prototype._execute = function execute(executeOptions, callback) {
   return this;
 };
 
+/** @internal */
 Execution.prototype._resume = function resume(resumeOptions, callback) {
   this._setup(resumeOptions);
 
@@ -512,6 +566,7 @@ Execution.prototype._resume = function resume(resumeOptions, callback) {
   return this;
 };
 
+/** @internal */
 Execution.prototype._addConsumerCallbacks = function addConsumerCallbacks(callback) {
   if (!callback) return;
 
@@ -562,6 +617,7 @@ Execution.prototype._addConsumerCallbacks = function addConsumerCallbacks(callba
   }
 };
 
+/** @returns {Promise<any>} */
 Execution.prototype.stop = async function stop() {
   const engine = this[kEngine];
   const prom = engine.waitFor('stop');
@@ -579,6 +635,7 @@ Execution.prototype.stop = async function stop() {
   return result;
 };
 
+/** @internal */
 Execution.prototype._setup = function setup(setupOptions) {
   const listener = setupOptions?.listener || this.options.listener;
   if (listener && typeof listener.emit !== 'function') throw new Error('listener.emit is not a function');
@@ -598,6 +655,7 @@ Execution.prototype._setup = function setup(setupOptions) {
   }
 };
 
+/** @internal */
 Execution.prototype._onChildMessage = function onChildMessage(routingKey, message, owner) {
   const { environment: ownerEnvironment } = owner;
   const listener = ownerEnvironment.options?.listener;
@@ -667,6 +725,7 @@ Execution.prototype._onChildMessage = function onChildMessage(routingKey, messag
   }
 };
 
+/** @internal */
 Execution.prototype._complete = function complete(eventType, content, messageProperties) {
   const timers = this.environment.timers;
   timers.executing.slice().forEach((ref) => timers.clearTimeout(ref));
@@ -674,11 +733,13 @@ Execution.prototype._complete = function complete(eventType, content, messagePro
   return eventType !== 'error' && this[kEngine].emit(eventType, this);
 };
 
+/** @internal */
 Execution.prototype._teardownDefinition = function teardownDefinition(definition) {
   this[kExecuting].delete(definition);
   definition.broker.cancel('_engine_definition');
 };
 
+/** @internal */
 Execution.prototype._saveOutput = function saveOutput(output) {
   if (!output || typeof output !== 'object') return;
 
@@ -694,6 +755,7 @@ Execution.prototype._saveOutput = function saveOutput(output) {
   }
 };
 
+/** @returns {import('types').BpmnEngineExecutionState} */
 Execution.prototype.getState = function getState() {
   const definitions = [];
   for (const definition of this.definitions) {
@@ -713,6 +775,10 @@ Execution.prototype.getState = function getState() {
   };
 };
 
+/**
+ * @param {string} activityId
+ * @returns {any}
+ */
 Execution.prototype.getActivityById = function getActivityById(activityId) {
   for (const definition of this.definitions) {
     const activity = definition.getActivityById(activityId);
@@ -720,6 +786,7 @@ Execution.prototype.getActivityById = function getActivityById(activityId) {
   }
 };
 
+/** @returns {any[]} */
 Execution.prototype.getPostponed = function getPostponed() {
   const definitions = this.stopped ? this.definitions : this[kExecuting];
   let result = [];
@@ -729,6 +796,10 @@ Execution.prototype.getPostponed = function getPostponed() {
   return result;
 };
 
+/**
+ * @param {import('types').BpmnMessage} [payload]
+ * @param {{ ignoreSameDefinition?: boolean }} [signalOptions]
+ */
 Execution.prototype.signal = function signal(payload, signalOptions) {
   for (const definition of this[kExecuting]) {
     if (signalOptions?.ignoreSameDefinition && payload?.parent?.id === definition.id) continue;
@@ -736,26 +807,35 @@ Execution.prototype.signal = function signal(payload, signalOptions) {
   }
 };
 
+/** @param {import('types').BpmnMessage} [payload] */
 Execution.prototype.cancelActivity = function cancelActivity(payload) {
   for (const definition of this[kExecuting]) {
     definition.cancelActivity(payload);
   }
 };
 
+/**
+ * @template T
+ * @param {import('types').BpmnEngineEvent} eventName
+ * @returns {Promise<T>}
+ */
 Execution.prototype.waitFor = function waitFor(...args) {
   return this[kEngine].waitFor(...args);
 };
 
+/** @internal */
 Execution.prototype._onBrokerReturn = function onBrokerReturn(message) {
   if (message.properties.type === 'error') {
     this[kEngine].emit('error', message.content);
   }
 };
 
+/** @internal */
 Execution.prototype._debug = function debug(msg) {
   this[kEngine].logger.debug(`<${this.name}> ${msg}`);
 };
 
+/** @internal */
 Execution.prototype._getActivityStatus = function getActivityStatus() {
   let status = 'idle';
   const executing = this[kExecuting];

package/package.json

@@ -1,12 +1,19 @@
 {
   "name": "bpmn-engine",
   "description": "BPMN 2.0 execution engine. Open source javascript workflow engine.",
-  "version": "25.0.0",
+  "version": "26.0.0",
   "type": "module",
   "module": "./src/index.js",
   "main": "./lib/index.cjs",
-  "types": "./types/bpmn-engine.d.ts",
+  "types": "./types/index.d.ts",
   "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "require": "./lib/index.cjs",
+      "import": "./src/index.js"
+    }
+  },
   "repository": {
     "type": "git",
     "url": "git://github.com/paed01/bpmn-engine.git"
@@ -50,31 +57,40 @@
       "url": "https://github.com/paed01/bpmn-engine/master/LICENSE"
     }
   ],
+  "overrides": {
+    "c8": {
+      "yargs": "^18.0.0"
+    },
+    "mocha": {
+      "yargs": "^18.0.0"
+    }
+  },
   "devDependencies": {
     "@bonniernews/hot-bev": "^0.4.0",
-    "@rollup/plugin-commonjs": "^28.0.0",
-    "@types/bpmn-moddle": "^5.1.6",
-    "@types/node": "^18.19.31",
+    "@eslint/js": "^10.0.1",
+    "@rollup/plugin-commonjs": "^29.0.0",
+    "@types/bpmn-moddle": "^10.0.0",
+    "@types/node": "^20.19.40",
     "bent": "^7.3.12",
-    "c8": "^10.0.0",
+    "c8": "^11.0.0",
     "camunda-bpmn-moddle": "^7.0.1",
-    "chai": "^5.1.0",
-    "chronokinesis": "^6.0.0",
-    "eslint": "^9.10.0",
-    "markdown-toc": "^1.2.0",
+    "chai": "^6.2.0",
+    "chronokinesis": "^8.0.0",
+    "eslint": "^10.5.0",
+    "globals": "^17.6.0",
     "mocha": "^11.0.1",
     "mocha-cakes-2": "^3.3.0",
     "prettier": "^3.2.5",
     "rollup": "^4.10.0",
-    "texample": "^0.0.7"
+    "texample": "^1.0.2"
   },
   "dependencies": {
-    "bpmn-elements": "^17.0.0",
-    "bpmn-moddle": "^9.0.1",
-    "debug": "^4.3.7",
-    "moddle-context-serializer": "^4.3.0"
+    "bpmn-elements": "^18.0.0",
+    "bpmn-moddle": "^9.0.4",
+    "debug": "^4.4.3",
+    "moddle-context-serializer": "^6.0.0"
   },
   "peerDependencies": {
-    "smqp": ">=9"
+    "smqp": "^13.0.1"
   }
 }

package/src/index.js

@@ -5,7 +5,7 @@ import { fileURLToPath } from 'node:url';
 import BpmnModdle from 'bpmn-moddle';
 import * as Elements from 'bpmn-elements';
 import { Broker } from 'smqp';
-import serializer, { deserialize, TypeResolver } from 'moddle-context-serializer';
+import { Serializer, deserialize, TypeResolver } from 'moddle-context-serializer';
 
 import DebugLogger from './Logger.js';
 import JavaScripts from './JavaScripts.js';
@@ -29,6 +29,10 @@ const kTypeResolver = Symbol.for('type resolver');
 export default Engine;
 export { JavaScripts };
 
+/**
+ * BPMN 2.0 execution engine.
+ * @param {import('types').BpmnEngineOptions} [options]
+ */
 export function Engine(options) {
   if (!(this instanceof Engine)) return new Engine(options);
 
@@ -114,6 +118,12 @@ Object.defineProperties(Engine.prototype, {
   },
 });
 
+/**
+ * Execute the loaded definitions.
+ * @param {import('types').BpmnEngineExecuteOptions | ((err: Error, execution?: Execution) => void)} [optionsOrCallback]
+ * @param {(err: Error, execution?: Execution) => void} [callback]
+ * @returns {Promise<Execution>}
+ */
 Engine.prototype.execute = async function execute(...args) {
   const [executeOptions, callback] = getOptionsAndCallback(...args);
   try {
@@ -127,12 +137,19 @@ Engine.prototype.execute = async function execute(...args) {
   return execution._execute(executeOptions, callback);
 };
 
+/** @returns {Promise<void>} */
 Engine.prototype.stop = function stop() {
   const execution = this.execution;
   if (!execution) return;
   return execution.stop();
 };
 
+/**
+ * Recover engine from saved state.
+ * @param {import('types').BpmnEngineExecutionState | null} savedState
+ * @param {import('types').BpmnEngineOptions} [recoverOptions]
+ * @returns {Engine}
+ */
 Engine.prototype.recover = function recover(savedState, recoverOptions) {
   if (this[kExecution]?.isRunning) {
     throw new Error('cannot recover a running engine');
@@ -178,6 +195,12 @@ Engine.prototype.recover = function recover(savedState, recoverOptions) {
   return this;
 };
 
+/**
+ * Resume execution from a previously recovered state.
+ * @param {import('types').BpmnEngineExecuteOptions | ((err: Error, execution?: Execution) => void)} [optionsOrCallback]
+ * @param {(err: Error, execution?: Execution) => void} [callback]
+ * @returns {Promise<Execution>}
+ */
 Engine.prototype.resume = async function resume(...args) {
   const [resumeOptions, callback] = getOptionsAndCallback(...args);
 
@@ -199,6 +222,10 @@ Engine.prototype.resume = async function resume(...args) {
   return execution._resume(resumeOptions, callback);
 };
 
+/**
+ * Add a pre-serialized source context to the engine.
+ * @param {{ sourceContext: import('types').SerializableContext }} [options]
+ */
 Engine.prototype.addSource = function addSource(options) {
   if (!options?.sourceContext) return;
   const loadedDefinitions = this[kLoadedDefinitions];
@@ -206,16 +233,25 @@ Engine.prototype.addSource = function addSource(options) {
   this[kPendingSources].add(options.sourceContext);
 };
 
+/**
+ * @param {import('types').BpmnEngineExecuteOptions} [executeOptions]
+ * @returns {Promise<import('bpmn-elements').Definition[]>}
+ */
 Engine.prototype.getDefinitions = function getDefinitions(executeOptions) {
   const loadedDefinitions = this[kLoadedDefinitions];
   if (loadedDefinitions?.length) return Promise.resolve(loadedDefinitions);
   return this._loadDefinitions(executeOptions);
 };
 
+/**
+ * @param {string} id
+ * @returns {Promise<import('bpmn-elements').Definition>}
+ */
 Engine.prototype.getDefinitionById = async function getDefinitionById(id) {
   return (await this.getDefinitions()).find((d) => d.id === id);
 };
 
+/** @returns {Promise<import('types').BpmnEngineExecutionState>} */
 Engine.prototype.getState = async function getState() {
   const execution = this.execution;
   if (execution) return execution.getState();
@@ -224,6 +260,11 @@ Engine.prototype.getState = async function getState() {
   return new Execution(this, definitions, this.options).getState();
 };
 
+/**
+ * @template R
+ * @param {import('types').BpmnEngineEvent} eventName
+ * @returns {Promise<R>}
+ */
 Engine.prototype.waitFor = function waitFor(eventName) {
   const self = this;
   return new Promise((resolve, reject) => {
@@ -241,12 +282,14 @@ Engine.prototype.waitFor = function waitFor(eventName) {
   });
 };
 
+/** @internal */
 Engine.prototype._loadDefinitions = async function loadDefinitions(executeOptions) {
   const runSources = await Promise.all(this[kPendingSources]);
   const loadedDefinitions = (this[kLoadedDefinitions] = runSources.map((source) => this._loadDefinition(source, executeOptions)));
   return loadedDefinitions;
 };
 
+/** @internal */
 Engine.prototype._loadDefinition = function loadDefinition(serializedContext, executeOptions) {
   const environment = this.environment;
   const context = new Elements.Context(
@@ -269,20 +312,29 @@ Engine.prototype._loadDefinition = function loadDefinition(serializedContext, ex
   return new Elements.Definition(context);
 };
 
+/** @internal */
 Engine.prototype._serializeSource = async function serializeSource(source) {
   const moddleContext = await this._getModdleContext(source);
   return this._serializeModdleContext(moddleContext);
 };
 
+/** @internal */
 Engine.prototype._serializeModdleContext = function serializeModdleContext(moddleContext) {
-  return serializer(moddleContext, this[kTypeResolver], this.options.extendFn);
+  return Serializer(moddleContext, this[kTypeResolver], this.options.extendFn);
 };
 
+/** @internal */
 Engine.prototype._getModdleContext = function getModdleContext(source) {
   const bpmnModdle = new BpmnModdle(this.options.moddleOptions);
   return bpmnModdle.fromXML(Buffer.isBuffer(source) ? source.toString() : source.trim());
 };
 
+/**
+ * @param {Engine} engine
+ * @param {any[]} definitions
+ * @param {import('types').BpmnEngineExecuteOptions} [options]
+ * @param {boolean} [isRecovered]
+ */
 export function Execution(engine, definitions, options, isRecovered = false) {
   this.name = engine.name;
   this.options = options;
@@ -332,6 +384,7 @@ Object.defineProperties(Execution.prototype, {
   },
 });
 
+/** @internal */
 Execution.prototype._execute = function execute(executeOptions, callback) {
   this._setup(executeOptions);
   this[kStopped] = false;
@@ -353,6 +406,7 @@ Execution.prototype._execute = function execute(executeOptions, callback) {
   return this;
 };
 
+/** @internal */
 Execution.prototype._resume = function resume(resumeOptions, callback) {
   this._setup(resumeOptions);
 
@@ -366,6 +420,7 @@ Execution.prototype._resume = function resume(resumeOptions, callback) {
   return this;
 };
 
+/** @internal */
 Execution.prototype._addConsumerCallbacks = function addConsumerCallbacks(callback) {
   if (!callback) return;
 
@@ -416,6 +471,7 @@ Execution.prototype._addConsumerCallbacks = function addConsumerCallbacks(callba
   }
 };
 
+/** @returns {Promise<any>} */
 Execution.prototype.stop = async function stop() {
   const engine = this[kEngine];
   const prom = engine.waitFor('stop');
@@ -433,6 +489,7 @@ Execution.prototype.stop = async function stop() {
   return result;
 };
 
+/** @internal */
 Execution.prototype._setup = function setup(setupOptions) {
   const listener = setupOptions?.listener || this.options.listener;
   if (listener && typeof listener.emit !== 'function') throw new Error('listener.emit is not a function');
@@ -452,6 +509,7 @@ Execution.prototype._setup = function setup(setupOptions) {
   }
 };
 
+/** @internal */
 Execution.prototype._onChildMessage = function onChildMessage(routingKey, message, owner) {
   const { environment: ownerEnvironment } = owner;
   const listener = ownerEnvironment.options?.listener;
@@ -521,6 +579,7 @@ Execution.prototype._onChildMessage = function onChildMessage(routingKey, messag
   }
 };
 
+/** @internal */
 Execution.prototype._complete = function complete(eventType, content, messageProperties) {
   const timers = this.environment.timers;
   timers.executing.slice().forEach((ref) => timers.clearTimeout(ref));
@@ -528,11 +587,13 @@ Execution.prototype._complete = function complete(eventType, content, messagePro
   return eventType !== 'error' && this[kEngine].emit(eventType, this);
 };
 
+/** @internal */
 Execution.prototype._teardownDefinition = function teardownDefinition(definition) {
   this[kExecuting].delete(definition);
   definition.broker.cancel('_engine_definition');
 };
 
+/** @internal */
 Execution.prototype._saveOutput = function saveOutput(output) {
   if (!output || typeof output !== 'object') return;
 
@@ -548,6 +609,7 @@ Execution.prototype._saveOutput = function saveOutput(output) {
   }
 };
 
+/** @returns {import('types').BpmnEngineExecutionState} */
 Execution.prototype.getState = function getState() {
   const definitions = [];
   for (const definition of this.definitions) {
@@ -567,6 +629,10 @@ Execution.prototype.getState = function getState() {
   };
 };
 
+/**
+ * @param {string} activityId
+ * @returns {any}
+ */
 Execution.prototype.getActivityById = function getActivityById(activityId) {
   for (const definition of this.definitions) {
     const activity = definition.getActivityById(activityId);
@@ -574,6 +640,7 @@ Execution.prototype.getActivityById = function getActivityById(activityId) {
   }
 };
 
+/** @returns {any[]} */
 Execution.prototype.getPostponed = function getPostponed() {
   const definitions = this.stopped ? this.definitions : this[kExecuting];
   let result = [];
@@ -583,6 +650,10 @@ Execution.prototype.getPostponed = function getPostponed() {
   return result;
 };
 
+/**
+ * @param {import('types').BpmnMessage} [payload]
+ * @param {{ ignoreSameDefinition?: boolean }} [signalOptions]
+ */
 Execution.prototype.signal = function signal(payload, signalOptions) {
   for (const definition of this[kExecuting]) {
     if (signalOptions?.ignoreSameDefinition && payload?.parent?.id === definition.id) continue;
@@ -590,26 +661,35 @@ Execution.prototype.signal = function signal(payload, signalOptions) {
   }
 };
 
+/** @param {import('types').BpmnMessage} [payload] */
 Execution.prototype.cancelActivity = function cancelActivity(payload) {
   for (const definition of this[kExecuting]) {
     definition.cancelActivity(payload);
   }
 };
 
+/**
+ * @template T
+ * @param {import('types').BpmnEngineEvent} eventName
+ * @returns {Promise<T>}
+ */
 Execution.prototype.waitFor = function waitFor(...args) {
   return this[kEngine].waitFor(...args);
 };
 
+/** @internal */
 Execution.prototype._onBrokerReturn = function onBrokerReturn(message) {
   if (message.properties.type === 'error') {
     this[kEngine].emit('error', message.content);
   }
 };
 
+/** @internal */
 Execution.prototype._debug = function debug(msg) {
   this[kEngine].logger.debug(`<${this.name}> ${msg}`);
 };
 
+/** @internal */
 Execution.prototype._getActivityStatus = function getActivityStatus() {
   let status = 'idle';
   const executing = this[kExecuting];

package/types/index.d.ts

@@ -0,0 +1,153 @@
+declare module 'bpmn-engine' {
+  import type { EventEmitter } from 'node:events';
+  import type { Broker } from 'smqp';
+  import type { Definitions as BpmnModdleDefinitions } from 'bpmn-moddle';
+  import type { ExtendFn, SerializableContext, ResolverFn } from 'moddle-context-serializer';
+  import type {
+    ActivityStatus,
+    Definition,
+    ElementBase,
+    Environment,
+    EnvironmentOptions,
+    EnvironmentState,
+    IApi,
+    ILogger,
+    IScripts,
+    Script,
+  } from 'bpmn-elements';
+
+  export type BpmnEngineEvent = 'error' | 'stop' | 'end';
+
+  export type BpmnActivityEvent =
+    | 'activity.enter'
+    | 'activity.start'
+    | 'activity.wait'
+    | 'wait'
+    | 'activity.end'
+    | 'activity.leave'
+    | 'activity.stop'
+    | 'activity.throw'
+    | 'activity.error';
+
+  export type BpmnSequenceFlowEvent = 'flow.take' | 'flow.discard' | 'flow.looped';
+
+  export type BpmnEngineRunningStatus = 'idle' | 'running' | 'stopped' | 'error';
+
+  export interface BpmnMessage {
+    id?: string;
+    executionId?: string;
+    [name: string]: any;
+  }
+
+  export interface IListenerEmitter {
+    emit(eventName: string, ...args: any[]): void;
+  }
+
+  export interface BpmnEngineExecuteOptions extends EnvironmentOptions {
+    listener?: EventEmitter | IListenerEmitter;
+  }
+
+  export interface BpmnEngineOptions extends BpmnEngineExecuteOptions {
+    name?: string;
+    source?: string;
+    sourceContext?: SerializableContext;
+    elements?: Record<string, any>;
+    typeResolver?: ResolverFn;
+    extendFn?: ExtendFn;
+    moddleOptions?: any;
+    moddleContext?: BpmnModdleDefinitions;
+    Logger?: (scope: string) => ILogger;
+    scripts?: IScripts;
+    disableDummyScript?: boolean;
+    [x: string]: any;
+  }
+
+  export interface BpmnEngineDefinitionState {
+    state: string;
+    source?: string;
+    [x: string]: any;
+  }
+
+  export interface BpmnEngineExecutionState {
+    name: string;
+    engineVersion: string;
+    state: BpmnEngineRunningStatus;
+    stopped: boolean;
+    environment: EnvironmentState;
+    definitions: BpmnEngineDefinitionState[];
+  }
+
+  export function Engine(options?: BpmnEngineOptions): Engine;
+  export class Engine extends EventEmitter {
+    constructor(options?: BpmnEngineOptions);
+    options: BpmnEngineOptions;
+    readonly name: string;
+    readonly broker: Broker;
+    readonly logger: ILogger;
+    readonly environment: Environment;
+    readonly state: BpmnEngineRunningStatus;
+    readonly stopped: boolean;
+    readonly execution: Execution | null;
+    readonly activityStatus: ActivityStatus;
+
+    execute(): Promise<Execution>;
+    execute(options: BpmnEngineExecuteOptions): Promise<Execution>;
+    execute(options: BpmnEngineExecuteOptions, callback: (err: Error | null, execution?: Execution) => void): Promise<Execution>;
+    execute(callback: (err: Error | null, execution?: Execution) => void): Promise<Execution>;
+
+    getDefinitionById(id: string): Promise<Definition | undefined>;
+    getDefinitions(executeOptions?: BpmnEngineExecuteOptions): Promise<Definition[]>;
+    getState(): Promise<BpmnEngineExecutionState>;
+
+    recover(savedState: BpmnEngineExecutionState | null, recoverOptions?: BpmnEngineOptions): Engine;
+
+    resume(): Promise<Execution>;
+    resume(options: BpmnEngineExecuteOptions): Promise<Execution>;
+    resume(options: BpmnEngineExecuteOptions, callback: (err: Error | null, execution?: Execution) => void): Promise<Execution>;
+    resume(callback: (err: Error | null, execution?: Execution) => void): Promise<Execution>;
+
+    stop(): Promise<void> | undefined;
+
+    addSource(options?: { sourceContext: SerializableContext }): void;
+
+    waitFor<R>(eventName: BpmnEngineEvent): Promise<R>;
+  }
+
+  export function Execution(
+    engine: Engine,
+    definitions: Definition[],
+    options?: BpmnEngineExecuteOptions,
+    isRecovered?: boolean
+  ): Execution;
+  export class Execution {
+    constructor(engine: Engine, definitions: Definition[], options?: BpmnEngineExecuteOptions, isRecovered?: boolean);
+    options: BpmnEngineExecuteOptions;
+    readonly name: string;
+    readonly definitions: Definition[];
+    readonly broker: Broker;
+    readonly environment: Environment;
+    readonly state: BpmnEngineRunningStatus;
+    readonly stopped: boolean;
+    readonly isRunning: boolean;
+    readonly activityStatus: ActivityStatus;
+
+    getActivityById(activityId: string): ElementBase | undefined;
+    getActivityById<R>(activityId: string): R | undefined;
+    getPostponed(): IApi<ElementBase>[];
+    getState(): BpmnEngineExecutionState;
+    stop(): Promise<void>;
+
+    signal(message?: BpmnMessage, options?: { ignoreSameDefinition?: boolean }): void;
+    cancelActivity(message?: BpmnMessage): void;
+
+    waitFor<R>(eventName: BpmnEngineEvent): Promise<R>;
+  }
+
+  export class JavaScripts implements IScripts {
+    constructor(disableDummy?: boolean);
+    register(activity: any): Script | undefined;
+    getScript(language: string, identifier: { id: string; [x: string]: any }): Script;
+  }
+
+  export default Engine;
+}

package/types/interfaces.d.ts

@@ -0,0 +1,80 @@
+import type { EventEmitter } from 'node:events';
+import type { Definitions as BpmnModdleDefinitions } from 'bpmn-moddle';
+import type { ExtendFn, SerializableContext, ResolverFn } from 'moddle-context-serializer';
+import type { ActivityStatus, ElementBroker, EnvironmentOptions, EnvironmentState, IScripts, Script, ILogger } from 'bpmn-elements';
+
+export type { SerializableContext };
+
+export type BpmnEngineEvent = 'error' | 'stop' | 'end';
+
+export type BpmnActivityEvent =
+  | 'activity.enter'
+  | 'activity.start'
+  | 'activity.wait'
+  | 'wait'
+  | 'activity.end'
+  | 'activity.leave'
+  | 'activity.stop'
+  | 'activity.throw'
+  | 'activity.error';
+
+export type BpmnSequenceFlowEvent = 'flow.take' | 'flow.discard' | 'flow.looped';
+
+export type BpmnEngineRunningStatus = 'idle' | 'running' | 'stopped' | 'error';
+
+export interface BpmnMessage {
+  id?: string;
+  executionId?: string;
+  [name: string]: any;
+}
+
+export interface IListenerEmitter {
+  emit(eventName: string, ...args: any[]): void;
+}
+
+export interface BpmnEngineExecuteOptions extends EnvironmentOptions {
+  listener?: EventEmitter | IListenerEmitter;
+}
+
+export interface BpmnEngineOptions extends BpmnEngineExecuteOptions {
+  name?: string;
+  source?: string;
+  sourceContext?: SerializableContext;
+  elements?: Record<string, any>;
+  typeResolver?: ResolverFn;
+  extendFn?: ExtendFn;
+  moddleOptions?: any;
+  moddleContext?: BpmnModdleDefinitions;
+  Logger?: (scope: string) => ILogger;
+  scripts?: IScripts;
+  disableDummyScript?: boolean;
+  [x: string]: any;
+}
+
+export interface BpmnEngineDefinitionState {
+  state: string;
+  source?: string;
+  [x: string]: any;
+}
+
+export interface BpmnEngineExecutionState {
+  name: string;
+  engineVersion: string;
+  state: BpmnEngineRunningStatus;
+  stopped: boolean;
+  environment: EnvironmentState;
+  definitions: BpmnEngineDefinitionState[];
+}
+
+export type {
+  ActivityStatus,
+  BpmnModdleDefinitions,
+  ElementBroker,
+  EnvironmentOptions,
+  EnvironmentState,
+  ExtendFn,
+  ILogger,
+  IScripts,
+  ResolverFn,
+  Script,
+};

package/types/bpmn-engine.d.ts

@@ -1,334 +0,0 @@
-// Author : Saeed Tabrizi
-// Refactored by : Pål Edman
-
-import { EventEmitter } from 'node:events';
-import { Definitions as BpmnModdleDefinitions } from 'bpmn-moddle';
-import { extendFn, SerializableContext, TypeResolver } from 'moddle-context-serializer';
-import {
-  ActivityStatus,
-  ElementBroker,
-  EnvironmentOptions,
-  Definition,
-  DefinitionState,
-  Environment,
-  Api,
-  ElementBase,
-  ILogger,
-  EnvironmentState,
-  IScripts,
-  Script,
-} from 'bpmn-elements';
-
-declare module 'bpmn-engine' {
-  /**
-   * Engine emits the following events:
-
-      error: An non-recoverable error has occurred
-      stop: Executions was stopped
-      end: Execution completed
-   */
-  export type BpmnEngineEvent = 'error' | 'stop' | 'end';
-  /**
-   * Each activity and flow emits events when changing state.
-
-      activity.enter: An activity is entered
-      activity.start: An activity is started
-      activity.wait: The activity is postponed for some reason, e.g. a user task is waiting to be signaled or a message is expected
-      wait: Same as above
-      activity.end: An activity has ended successfully
-      activity.leave: The execution left the activity
-      activity.stop: Activity run was stopped
-      activity.throw: An recoverable error was thrown
-      activity.error: An non-recoverable error has occurred
-   */
-  export type BpmnActivityEvent =
-    | 'activity.enter'
-    | 'activity.start'
-    | 'activity.wait'
-    | 'wait'
-    | 'activity.end'
-    | 'activity.leave'
-    | 'activity.stop'
-    | 'activity.throw'
-    | 'activity.error';
-  /**
-   * Sequence flow events
-        flow.take: The sequence flow was taken
-        flow.discard: The sequence flow was discarded
-        flow.looped: The sequence is looped
-   */
-  export type BpmnSequenceFlowEvent = 'flow.take' | 'flow.discard' | 'flow.looped';
-
-  export interface BpmnMessage {
-    id?: string;
-    executionId?: string;
-    [name: string]: any;
-  }
-
-  export interface IListenerEmitter {
-    emit(eventName: string, ...args: any[]): void;
-  }
-
-  export interface BpmnEngineExecuteOptions extends EnvironmentOptions {
-    listener?: EventEmitter | IListenerEmitter;
-  }
-
-  export interface BpmnEngineOptions extends BpmnEngineExecuteOptions {
-    /**
-     * optional name of engine,
-     */
-    name?: string;
-    /**
-     * optional BPMN 2.0 definition source as string
-     */
-    source?: string;
-    /**
-     * optional serialized context supplied by moddle-context-serializer
-     */
-    sourceContext?: SerializableContext;
-    /**
-     * optional override of BPMN Elements behaviors, defaults to bpmn-elements
-     */
-    elements?: Record<string, any>;
-    /**
-     * Passed to moddle-context-serializer as TypeResolver
-     */
-    typeResolver?: typeof TypeResolver;
-    /**
-     * Passed to moddle-context-serializer as extendFn
-     */
-    extendFn?: extendFn;
-    /**
-     * optional bpmn-moddle options to be passed to bpmn-moddle
-     */
-    moddleOptions?: any;
-    moddleContext?: BpmnModdleDefinitions;
-    [x: string]: any;
-  }
-
-  const enum BpmnEngineRunningStatus {
-    /**
-     * Engine is not executing
-     */
-    Idle = 'idle',
-    /**
-     * Engine is executing
-     */
-    Running = 'running',
-    /**
-     * Engine execution is stopped
-     */
-    Stopped = 'stopped',
-    /**
-     * Engine execution has errored
-     */
-    Error = 'error',
-  }
-
-  export function Engine(options?: BpmnEngineOptions): Engine;
-  export class Engine extends EventEmitter {
-    constructor(options?: BpmnEngineOptions);
-    /**
-     * engine name
-     */
-    readonly name: string;
-    /**
-     * engine broker
-     */
-    broker: ElementBroker<Engine>;
-    /**
-     * engine state
-     */
-    readonly state: BpmnEngineRunningStatus;
-    /**
-     * boolean stopped
-     */
-    readonly stopped: boolean;
-    /**
-     * current engine execution
-     */
-    readonly execution: Execution;
-    /**
-     * engine environment
-     */
-    readonly environment: Environment;
-    /**
-     *  engine logger
-     */
-    readonly logger: ILogger;
-    get activityStatus(): ActivityStatus;
-
-    /**
-     * execute definition
-     * @param options Optional object with options to override the initial engine options
-     * @param cb Callback called before the throw
-     * @summary Execute options overrides the initial options passed to the engine before executing the definition.
-     */
-    execute(): Promise<Execution>;
-    execute(options: BpmnEngineExecuteOptions): Promise<Execution>;
-    execute(options: BpmnEngineExecuteOptions, cb: (err: Error, execution?: Execution) => void): Promise<Execution>;
-    execute(cb: (err: Error) => void): Promise<Execution>;
-
-    /**
-     * get definition by id
-     * @param id id of definition
-     */
-    getDefinitionById(id: string): Promise<Definition>;
-
-    /**
-     * get all definitions
-     */
-    getDefinitions(): Promise<Definition[]>;
-
-    /**
-     * get execution serialized state
-     */
-    getState(): Promise<BpmnEngineExecutionState>;
-
-    /**
-     * Recover engine from state
-     * @param state engine state
-     * @param recoverOptions  optional object with options that will completely override the options passed to the engine at init
-     */
-    recover(state: any, recoverOptions?: BpmnEngineOptions): Engine;
-
-    /**
-     * Resume execution function with previously saved engine state.
-     * @param options
-     * @param callback
-     */
-    resume(options?: BpmnEngineExecuteOptions, callback?: (err: Error, execution?: Execution) => void): Promise<Execution>;
-
-    /**
-     * Stop execution. The instance is terminated.
-     */
-    stop(): Promise<void>;
-
-    waitFor<R>(eventName: BpmnEngineEvent): Promise<R>;
-
-    /**
-     * Add definition source by source context.
-     * @param options
-     */
-    addSource(options?: { sourceContext: any }): void;
-  }
-
-  interface BpmnEngineDefinitionState extends DefinitionState {
-    /**
-     * Serialized moddle-context-serializer context
-     */
-    source?: string;
-  }
-
-  export interface BpmnEngineExecutionState {
-    name: string;
-    engineVersion: string;
-    state: BpmnEngineRunningStatus;
-    stopped: boolean;
-    environment: EnvironmentState;
-    definitions: BpmnEngineDefinitionState[];
-  }
-
-  export interface Execution {
-    /**
-     * engine name
-     *
-     * @type {string}
-     * @
-     */
-    readonly name: string;
-    /**
-     * state of execution, i.e running or idle
-     *
-     * @type {("running"| "idle")}
-     *
-     */
-    readonly state: 'running' | 'idle';
-    /**
-     * is the execution stopped
-     *
-     * @type {boolean}
-     *
-     */
-    readonly stopped: boolean;
-    /**
-     * engine environment
-     *
-     * @type {Environment}
-     *
-     */
-    readonly environment: Environment;
-
-    /**
-     * executing definitions
-     *
-     * @type {Definition}
-     *
-     */
-    readonly definitions: Definition[];
-    get activityStatus(): ActivityStatus;
-    /**
-     * Are any definition running
-     */
-    get isRunning(): boolean;
-
-    /**
-     * Get activity/element by id. Loops the definitions and returns the first found activity with id.
-     * @param activityId Activity or element id
-     */
-    getActivityById(activityId: string): ElementBase;
-    getActivityById<R>(activityId: string): R;
-
-    /**
-     * get execution serializable state
-     *
-     * @returns {BpmnEngineExecutionState}
-     *
-     */
-    getState(): BpmnEngineExecutionState;
-
-    /**
-     * stop execution
-     *
-     *
-     */
-    stop(): Promise<void>;
-
-    /**
-     * get activities in a postponed state
-     *
-     *
-     */
-    getPostponed(): Api<ElementBase>[];
-
-    /**
-     * send signal to execution, distributed to all definitions
-     * Delegate a signal message to all interested parties, usually MessageEventDefinition, SignalEventDefinition, SignalTask (user, manual), ReceiveTask, or a StartEvent that has a form.
-     * @param message {BpmnMessage}
-     * @param options
-     */
-    signal(message?: BpmnMessage, options?: { ignoreSameDefinition?: boolean }): void;
-
-    /**
-     * send cancel activity to execution, distributed to all definitions
-     * Delegate a cancel message to all interested parties, perhaps a stalled TimerEventDefinition.
-     * @param message
-     */
-    cancelActivity(message?: BpmnMessage): void;
-
-    /**
-     *
-     * @param event
-     */
-    waitFor<T>(event: BpmnEngineEvent): Promise<T>;
-  }
-
-  export class JavaScripts implements IScripts {
-    /**
-     * @param disableDummy Disable returning dummy scripts if script is not found. Dummy script will immediately call next function without error or return value
-     */
-    constructor(disableDummy?: boolean);
-    register(activity: any): Script | undefined;
-    getScript(language: string, identifier: { id: string; [x: string]: any }): Script;
-  }
-}