bpmn-engine 26.0.3 → 26.0.5

package/README.md

@@ -2,24 +2,31 @@
 
 [![Project Status: Active - The project has reached a stable, usable state and is being actively developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active)
 
-[![Build](https://github.com/paed01/bpmn-engine/actions/workflows/build.yaml/badge.svg)](https://github.com/paed01/bpmn-engine/actions/workflows/build.yaml)[![Build status](https://ci.appveyor.com/api/projects/status/670n39fivq1g3nu5/branch/master?svg=true)](https://ci.appveyor.com/project/paed01/bpmn-engine/branch/master)[![Coverage Status](https://coveralls.io/repos/github/paed01/bpmn-engine/badge.svg?branch=master)](https://coveralls.io/github/paed01/bpmn-engine?branch=master)
+[![Build](https://github.com/paed01/bpmn-engine/actions/workflows/build.yaml/badge.svg)](https://github.com/paed01/bpmn-engine/actions/workflows/build.yaml)[![Build (Windows)](https://github.com/paed01/bpmn-engine/actions/workflows/build-windows.yaml/badge.svg)](https://github.com/paed01/bpmn-engine/actions/workflows/build-windows.yaml)[![Coverage Status](https://coveralls.io/repos/github/paed01/bpmn-engine/badge.svg?branch=master)](https://coveralls.io/github/paed01/bpmn-engine?branch=master)
 
 # Introduction
 
 BPMN 2.0 execution engine. Open source javascript workflow engine.
 
+Documentation:
+
 - [API](/docs/API.md)
-- [Changelog](/CHANGELOG.md)
 - [Examples](/docs/Examples.md)
 - [Upgrade version](/docs/Upgrade.md)
-- [Peer dependencies](#peer-dependencies)
 - [bpmn-moddle 9 vs 10](/docs/bpmn-moddle.md)
+- [Changelog](/CHANGELOG.md)
+
+<!-- toc -->
+
+- [Peer dependencies](#peer-dependencies)
 - [Supported elements](#supported-elements)
 - [Extensions](#extensions)
 - [Debug](#debug)
-- [Example process](#a-pretty-image-of-a-process)
+- [A pretty image of a process](#a-pretty-image-of-a-process)
 - [Acknowledgments](#acknowledgments)
 
+<!-- /toc -->
+
 # Peer dependencies
 
 The runtime dependencies are declared as **peer dependencies**, so you install and pin them yourself and the engine reuses your single copy:
@@ -28,13 +35,13 @@ The runtime dependencies are declared as **peer dependencies**, so you install a
 npm install bpmn-engine bpmn-elements bpmn-moddle moddle-context-serializer debug smqp
 ```
 
-| Peer dependency                                                                    | Range     | Role                                              |
-| ---------------------------------------------------------------------------------- | --------- | ------------------------------------------------- |
-| [`bpmn-elements`](https://github.com/paed01/bpmn-elements)                         | `>=18`    | element behaviour functions                       |
-| [`bpmn-moddle`](https://github.com/bpmn-io/bpmn-moddle)                            | `>=9`     | BPMN XML parser ([9 vs 10](/docs/bpmn-moddle.md)) |
-| [`moddle-context-serializer`](https://github.com/paed01/moddle-context-serializer) | `>=6`     | persistable source context                        |
-| [`smqp`](https://github.com/paed01/smqp)                                           | `^13.0.1` | message broker driving execution                  |
-| [`debug`](https://github.com/debug-js/debug)                                       | `>=4`     | logging                                           |
+| Peer dependency                                                                    | Range       | Role                                              |
+| ---------------------------------------------------------------------------------- | ----------- | ------------------------------------------------- |
+| [`bpmn-elements`](https://github.com/paed01/bpmn-elements)                         | `>=18.0.25` | element behaviour functions                       |
+| [`bpmn-moddle`](https://github.com/bpmn-io/bpmn-moddle)                            | `>=9`       | BPMN XML parser ([9 vs 10](/docs/bpmn-moddle.md)) |
+| [`moddle-context-serializer`](https://github.com/paed01/moddle-context-serializer) | `>=6`       | persistable source context                        |
+| [`smqp`](https://github.com/paed01/smqp)                                           | `>=15`      | message broker driving execution                  |
+| [`debug`](https://github.com/debug-js/debug)                                       | `>=4`       | logging                                           |
 
 `bpmn-moddle` spans a major version on purpose — see [bpmn-moddle 9 vs 10](/docs/bpmn-moddle.md) for the import change and how persisted state stays compatible across the upgrade.
 

package/lib/index.cjs

@@ -412,7 +412,7 @@ Engine.prototype.getState = async function getState() {
 
 /**
  * @template R
- * @param {import('bpmn-engine').BpmnEngineEvent} eventName
+ * @param {import('bpmn-engine').BpmnEngineEvent | string} eventName
  * @returns {Promise<R>}
  */
 Engine.prototype.waitFor = function waitFor(eventName) {
@@ -481,7 +481,7 @@ Engine.prototype._getModdleContext = function getModdleContext(source) {
 
 /**
  * @param {Engine} engine
- * @param {any[]} definitions
+ * @param {import('bpmn-elements').Definition[]} definitions
  * @param {import('bpmn-engine').BpmnEngineExecuteOptions} [options]
  * @param {boolean} [isRecovered]
  */
@@ -820,7 +820,7 @@ Execution.prototype.cancelActivity = function cancelActivity(payload) {
 
 /**
  * @template T
- * @param {import('bpmn-engine').BpmnEngineEvent} eventName
+ * @param {import('bpmn-engine').BpmnEngineEvent | string} eventName
  * @returns {Promise<T>}
  */
 Execution.prototype.waitFor = function waitFor(...args) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "bpmn-engine",
   "description": "BPMN 2.0 execution engine. Open source javascript workflow engine.",
-  "version": "26.0.3",
+  "version": "26.0.5",
   "type": "module",
   "module": "./src/index.js",
   "main": "./lib/index.cjs",
@@ -34,10 +34,9 @@
     "test": "mocha -p -R @bonniernews/hot-bev",
     "posttest": "npm run lint && npm run toc && npm run dist && npm run test:md",
     "lint": "eslint . --cache && prettier . -c --cache",
-    "wintest": "mocha",
     "cov:html": "c8 -r html -r text mocha -p -R @bonniernews/hot-bev",
     "test:lcov": "c8 -r lcov mocha && npm run lint",
-    "toc": "node scripts/generate-api-toc ./docs/API.md,./docs/Examples.md",
+    "toc": "toc README.md docs/API.md docs/Examples.md docs/Upgrade.md",
     "test:md": "texample ./docs/API.md,./docs/Examples.md,./docs/Upgrade.md -c .mocharc.json",
     "dist": "rollup -c",
     "prepack": "npm run dist"
@@ -63,6 +62,7 @@
     }
   },
   "devDependencies": {
+    "@0dep/toc": "^1.0.1",
     "@bonniernews/hot-bev": "^0.4.0",
     "@eslint/js": "^10.0.1",
     "@rollup/plugin-commonjs": "^29.0.0",
@@ -71,11 +71,11 @@
     "@types/mocha": "^10.0.10",
     "@types/node": "^20.19.40",
     "bent": "^7.3.12",
-    "bpmn-elements": "^18.0.15",
+    "bpmn-elements": "^18.0.24",
     "bpmn-moddle": "^9.0.4",
     "bpmn-moddle-10": "npm:bpmn-moddle@^10.0.0",
     "c8": "^12.0.0",
-    "camunda-bpmn-moddle": "^7.0.1",
+    "camunda-bpmn-moddle": "^8.0.1",
     "chai": "^6.2.0",
     "chronokinesis": "^8.0.0",
     "debug": "^4.4.3",
@@ -91,10 +91,10 @@
     "typescript": "^7.0.2"
   },
   "peerDependencies": {
-    "bpmn-elements": ">=18",
+    "bpmn-elements": ">=18.0.25",
     "bpmn-moddle": ">=9",
     "debug": ">=4",
     "moddle-context-serializer": ">=6",
-    "smqp": "^13.0.1"
+    "smqp": ">=15"
   }
 }

package/src/index.js

@@ -265,7 +265,7 @@ Engine.prototype.getState = async function getState() {
 
 /**
  * @template R
- * @param {import('bpmn-engine').BpmnEngineEvent} eventName
+ * @param {import('bpmn-engine').BpmnEngineEvent | string} eventName
  * @returns {Promise<R>}
  */
 Engine.prototype.waitFor = function waitFor(eventName) {
@@ -334,7 +334,7 @@ Engine.prototype._getModdleContext = function getModdleContext(source) {
 
 /**
  * @param {Engine} engine
- * @param {any[]} definitions
+ * @param {import('bpmn-elements').Definition[]} definitions
  * @param {import('bpmn-engine').BpmnEngineExecuteOptions} [options]
  * @param {boolean} [isRecovered]
  */
@@ -673,7 +673,7 @@ Execution.prototype.cancelActivity = function cancelActivity(payload) {
 
 /**
  * @template T
- * @param {import('bpmn-engine').BpmnEngineEvent} eventName
+ * @param {import('bpmn-engine').BpmnEngineEvent | string} eventName
  * @returns {Promise<T>}
  */
 Execution.prototype.waitFor = function waitFor(...args) {

package/types/index.d.ts

@@ -16,20 +16,82 @@ declare module 'bpmn-engine' {
     Script,
   } from 'bpmn-elements';
 
-  export type BpmnEngineEvent = 'error' | 'stop' | 'end' | 'wait';
-
+  /**
+   * Engine events.
+   * - `error`: A non-recoverable error has occurred
+   * - `stop`: Execution was stopped
+   * - `end`: Execution completed
+   */
+  export type BpmnEngineEvent = 'error' | 'stop' | 'end';
+
+  /**
+   * Activity events emitted to the listener.
+   * - `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.timer`: A timer was started
+   * - `activity.timeout`: A timer timed out
+   * - `activity.signal`: The activity was signaled
+   * - `activity.catch`: The activity caught a message, signal, error, etc
+   * - `activity.discard`: The activity was discarded
+   * - `activity.cancel`: The activity was cancelled
+   * - `activity.end`: An activity has ended successfully
+   * - `activity.leave`: The execution left the activity
+   * - `activity.stop`: Activity run was stopped
+   * - `activity.throw`: A recoverable error was thrown
+   * - `activity.error`: A non-recoverable error has occurred
+   */
   export type BpmnActivityEvent =
     | 'activity.enter'
     | 'activity.start'
     | 'activity.wait'
     | 'wait'
+    | 'activity.timer'
+    | 'activity.timeout'
+    | 'activity.signal'
+    | 'activity.catch'
+    | 'activity.discard'
+    | 'activity.cancel'
     | 'activity.end'
     | 'activity.leave'
     | 'activity.stop'
     | 'activity.throw'
     | 'activity.error';
 
-  export type BpmnSequenceFlowEvent = 'flow.take' | 'flow.discard' | 'flow.looped';
+  /**
+   * Sequence flow events emitted to the listener.
+   * - `flow.take`: The sequence flow was taken
+   *
+   * Since bpmn-elements@18 non-selected sequence flows are no longer discarded, so
+   * `flow.discard` and `flow.looped` are never emitted during execution.
+   */
+  export type BpmnSequenceFlowEvent = 'flow.take';
+
+  /**
+   * Process events emitted to the listener.
+   */
+  export type BpmnProcessEvent =
+    'process.enter' | 'process.end' | 'process.leave' | 'process.error' | 'process.terminate' | 'process.discarded';
+
+  /**
+   * Definition events emitted to the listener.
+   */
+  export type BpmnDefinitionEvent = 'definition.leave' | 'definition.stop' | 'definition.error';
+
+  /**
+   * All events emitted to the listener. Every `definition.#`, `process.#`, `activity.#`, and `flow.#`
+   * routing key published by bpmn-elements is forwarded verbatim, the named unions are the documented ones.
+   */
+  export type BpmnListenerEvent =
+    | BpmnDefinitionEvent
+    | BpmnProcessEvent
+    | BpmnActivityEvent
+    | BpmnSequenceFlowEvent
+    | `definition.${string}`
+    | `process.${string}`
+    | `activity.${string}`
+    | `flow.${string}`;
 
   export type BpmnEngineRunningStatus = 'idle' | 'running' | 'stopped' | 'error';
 
@@ -40,7 +102,14 @@ declare module 'bpmn-engine' {
   }
 
   export interface IListenerEmitter {
-    emit(eventName: string, ...args: any[]): void;
+    /**
+     * Receive engine execution events
+     * @param eventName routing key of the event
+     * @param elementApi api of the element that emitted the event
+     * @param execution the engine execution
+     */
+    emit(eventName: BpmnListenerEvent, elementApi: IApi<ElementBase>, execution: Execution): unknown;
+    emit(eventName: string, ...args: any[]): unknown;
   }
 
   export interface BpmnEngineExecuteOptions extends EnvironmentOptions {
@@ -111,15 +180,9 @@ declare module 'bpmn-engine' {
 
     addSource(options?: { sourceContext: SerializableContext }): void;
 
-    waitFor<R>(eventName: BpmnEngineEvent): Promise<R>;
+    waitFor<R>(eventName: BpmnEngineEvent | string): 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;
@@ -141,7 +204,7 @@ declare module 'bpmn-engine' {
     signal(message?: BpmnMessage, options?: { ignoreSameDefinition?: boolean }): void;
     cancelActivity(message?: BpmnMessage): void;
 
-    waitFor<R>(eventName: BpmnEngineEvent): Promise<R>;
+    waitFor<R>(eventName: BpmnEngineEvent | string): Promise<R>;
   }
 
   export interface JavaScripts extends IScripts {