bpmn-engine 26.0.3 → 26.0.4

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) {
@@ -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.4",
   "type": "module",
   "module": "./src/index.js",
   "main": "./lib/index.cjs",
@@ -75,7 +75,7 @@
     "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",
@@ -95,6 +95,6 @@
     "bpmn-moddle": ">=9",
     "debug": ">=4",
     "moddle-context-serializer": ">=6",
-    "smqp": "^13.0.1"
+    "smqp": ">=13"
   }
 }

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) {
@@ -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,7 +180,7 @@ 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(
@@ -141,7 +210,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 {