@0dep/bpmn-extensions 0.0.1

package/src/extensions/TaskDefinition.js

@@ -0,0 +1,40 @@
+import { ServiceError } from '../Errors.js';
+import { resolveValue } from '../feel.js';
+
+/**
+ * `zeebe:taskDefinition`.
+ *
+ * A job worker subscribed to the task `type` executes the activity. Here the
+ * `type` is mapped to an environment service of the same name: the job worker is a service
+ * function `(executionMessage, callback) => void` registered under the job type.
+ *
+ * The service receives the task headers and resolved io input on the execution message
+ * content, and its result (the second callback argument) becomes the job variables that
+ * output mapping operates on.
+ *
+ * Bind the task type to use as the activity `Service`:
+ *   activity.behaviour.Service = JobService.bind(JobService, taskType);
+ */
+export function JobService(taskType, activity) {
+  if (!(this instanceof JobService)) return new JobService(taskType, activity);
+  this.type = `${activity.type}:taskDefinition`;
+  this.taskType = taskType;
+  this.activity = activity;
+}
+
+JobService.prototype.execute = function execute(executionMessage, callback) {
+  const activity = this.activity;
+  const environment = activity.environment;
+
+  let jobType;
+  try {
+    jobType = resolveValue(this.taskType, environment.variables);
+  } catch (err) {
+    return callback(err);
+  }
+
+  const serviceFn = environment.services[jobType];
+  if (typeof serviceFn !== 'function') return callback(new ServiceError(jobType));
+
+  return serviceFn.call(activity, executionMessage, (err, result) => callback(err, result));
+};

package/src/extensions/TaskHeaders.js

@@ -0,0 +1,19 @@
+/**
+ * `zeebe:taskHeaders`.
+ *
+ * Static key/value metadata passed to the job worker. Resolved to a plain object and made
+ * available on the element content as `headers`.
+ */
+export class TaskHeaders {
+  constructor(taskHeaders) {
+    this.values = taskHeaders.values || [];
+  }
+  resolve() {
+    const result = {};
+    for (const { key, value } of this.values) {
+      if (key === undefined) continue;
+      result[key] = value;
+    }
+    return result;
+  }
+}

package/src/extensions/formatters.js

@@ -0,0 +1,67 @@
+import { resolveValue } from '../feel.js';
+
+/**
+ * Format an activity on enter from its behaviour and extensions: documentation and,
+ * for user tasks, the `zeebe:assignmentDefinition` (assignee, candidate users/groups).
+ */
+export class FormatActivity {
+  constructor(activity, assignmentDefinition) {
+    this.activity = activity;
+    this.assignmentDefinition = assignmentDefinition;
+  }
+  resolve(elementApi) {
+    const scope = elementApi.environment.variables;
+    const result = {};
+
+    const documentation = this.activity.behaviour.documentation;
+    if (documentation && !elementApi.content.description) {
+      const text = documentation[0]?.text;
+      if (text) result.description = resolveValue(text, scope);
+    }
+
+    const assignment = this.assignmentDefinition;
+    if (assignment) {
+      const { assignee, candidateUsers, candidateGroups } = assignment;
+      if (assignee) result.assignee = resolveValue(assignee, scope);
+      const users = resolveList(candidateUsers, scope);
+      if (users) result.candidateUsers = users;
+      const groups = resolveList(candidateGroups, scope);
+      if (groups) result.candidateGroups = groups;
+    }
+
+    return result;
+  }
+}
+
+/**
+ * Format a process on enter: documentation.
+ */
+export class FormatProcess {
+  constructor(bp) {
+    this.process = bp;
+  }
+  resolve(elementApi) {
+    const result = {};
+    const documentation = this.process.behaviour.documentation;
+    if (documentation && !elementApi.content.description) {
+      const text = documentation[0]?.text;
+      if (text) result.description = resolveValue(text, elementApi.environment.variables);
+    }
+    return result;
+  }
+}
+
+/**
+ * Resolve a candidate users/groups value to a string array. A FEEL expression may yield an
+ * array directly, otherwise a comma-separated string is split.
+ */
+function resolveList(value, scope) {
+  if (!value) return undefined;
+  const resolved = resolveValue(value, scope);
+  if (Array.isArray(resolved)) return resolved.filter((v) => v !== null && v !== undefined);
+  if (typeof resolved !== 'string') return undefined;
+  return resolved
+    .split(',')
+    .map((v) => v.trim())
+    .filter(Boolean);
+}

package/src/feel.js

@@ -0,0 +1,60 @@
+import { evaluate, unaryTest } from 'feelin';
+
+/**
+ * A value is a FEEL expression when it is a string prefixed with `=`.
+ * Anything else is a static literal.
+ */
+const FEEL_PREFIX = /^\s*=/;
+
+/**
+ * Is the value a FEEL expression, i.e. a string starting with `=`?
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+export function isFeelExpression(value) {
+  return typeof value === 'string' && FEEL_PREFIX.test(value);
+}
+
+/**
+ * Strip the leading `=` from a FEEL expression.
+ * @param {string} expression
+ * @returns {string}
+ */
+export function stripFeel(expression) {
+  return expression.replace(FEEL_PREFIX, '');
+}
+
+/**
+ * Evaluate a FEEL expression against a context (the variables in scope).
+ * @param {string} expression FEEL expression, with or without the leading `=`
+ * @param {Record<string, any>} [context] Variables in scope
+ * @returns {any}
+ */
+export function evaluateFeel(expression, context) {
+  const { value } = evaluate(stripFeel(expression), context || {});
+  return value;
+}
+
+/**
+ * Evaluate a FEEL unary test, e.g. `> 100` or `1, 2, 3`, against an input value.
+ * @param {string} expression FEEL unary test
+ * @param {any} input The value being tested, available as `?` in the test
+ * @param {Record<string, any>} [context] Additional variables in scope
+ * @returns {boolean}
+ */
+export function evaluateFeelUnaryTest(expression, input, context) {
+  const { value } = unaryTest(stripFeel(expression), { ...(context || {}), '?': input });
+  return value;
+}
+
+/**
+ * Resolve a value: evaluate it as FEEL when it starts with `=`, otherwise
+ * return the static literal untouched.
+ * @param {any} value
+ * @param {Record<string, any>} [context] Variables in scope for FEEL evaluation
+ * @returns {any}
+ */
+export function resolveValue(value, context) {
+  if (isFeelExpression(value)) return evaluateFeel(value, context);
+  return value;
+}

package/src/getExtensions.js

@@ -0,0 +1,70 @@
+import { FormatActivity, FormatProcess } from './extensions/formatters.js';
+import { IoMapping } from './extensions/IoMapping.js';
+import { TaskHeaders } from './extensions/TaskHeaders.js';
+import { Properties } from './extensions/Properties.js';
+import { ExecutionListeners } from './extensions/ExecutionListeners.js';
+import { Form } from './extensions/Form.js';
+import { LoopCharacteristics } from './extensions/LoopCharacteristics.js';
+import { JobService } from './extensions/TaskDefinition.js';
+
+/**
+ * Inspect an element's extension elements and assemble the extension handlers it needs.
+ * @param {import('bpmn-elements').Activity | import('bpmn-elements').Process} element
+ * @returns {{
+ *   format: FormatActivity | FormatProcess,
+ *   io?: IoMapping,
+ *   headers?: TaskHeaders,
+ *   properties?: Properties,
+ *   listeners?: ExecutionListeners,
+ *   form?: Form,
+ *   loop?: LoopCharacteristics,
+ *   Service?: Function,
+ * }}
+ */
+export function getExtensions(element) {
+  const result = {};
+  const isProcess = element.type === 'bpmn:Process';
+
+  let assignmentDefinition;
+  const values = element.behaviour.extensionElements?.values;
+  if (values) {
+    for (const ext of values) {
+      switch (ext.$type) {
+        case 'zeebe:IoMapping':
+          result.io = new IoMapping(element, ext);
+          break;
+        case 'zeebe:TaskHeaders':
+          if (ext.values?.length) result.headers = new TaskHeaders(ext);
+          break;
+        case 'zeebe:Properties':
+          if (ext.properties?.length) result.properties = new Properties(ext);
+          break;
+        case 'zeebe:AssignmentDefinition':
+          assignmentDefinition = ext;
+          break;
+        case 'zeebe:ExecutionListeners':
+          if (ext.listeners?.length) result.listeners = new ExecutionListeners(element, ext);
+          break;
+        case 'zeebe:TaskDefinition':
+          result.Service = JobService.bind(JobService, ext.type);
+          break;
+        case 'zeebe:Script':
+          result.script = ext;
+          break;
+        case 'zeebe:FormDefinition':
+          result.form = new Form(ext);
+          break;
+      }
+    }
+  }
+
+  // Output side of a multi-instance `zeebe:loopCharacteristics` (the input side is lifted by extendFn).
+  const loopExtension = element.behaviour.loopCharacteristics?.behaviour?.extensionElements?.values?.find(
+    (v) => v.$type === 'zeebe:LoopCharacteristics'
+  );
+  if (loopExtension?.outputCollection) result.loop = new LoopCharacteristics(loopExtension);
+
+  result.format = isProcess ? new FormatProcess(element) : new FormatActivity(element, assignmentDefinition);
+
+  return result;
+}

package/src/index.js

@@ -0,0 +1,64 @@
+import { ElementExtensions } from './ElementExtensions.js';
+import { ProcessExtensions } from './ProcessExtensions.js';
+import { SubProcessExtensions } from './SubProcessExtensions.js';
+
+export { ElementExtensions, ProcessExtensions, SubProcessExtensions };
+export { FeelExpressions } from './Expressions.js';
+export { FeelScripts } from './extensions/FeelScripts.js';
+export { isFeelExpression, stripFeel, evaluateFeel, evaluateFeelUnaryTest, resolveValue } from './feel.js';
+export { JobService } from './extensions/TaskDefinition.js';
+export { ServiceError, FormatError } from './Errors.js';
+
+/**
+ * A flow extension activated by bpmn-elements around an element's run.
+ * @typedef {object} FlowExtension
+ * @property {(message: any) => void} activate
+ * @property {(message?: any) => void} deactivate
+ */
+
+/**
+ * Flow extensions factory. Pass it to the engine via the environment `extensions` option.
+ * @param {import('bpmn-elements').Activity | import('bpmn-elements').Process} element
+ * @param {import('bpmn-elements').ContextInstance} context
+ * @returns {FlowExtension}
+ */
+export function extensions(element, context) {
+  switch (element.type) {
+    case 'bpmn:Process':
+      return new ProcessExtensions(element, context);
+    case 'bpmn:SubProcess':
+    case 'bpmn:AdHocSubProcess':
+    case 'bpmn:Transaction':
+      return new SubProcessExtensions(element, context);
+    default:
+      return new ElementExtensions(element, context);
+  }
+}
+
+/**
+ * Behaviour extend function for moddle-context-serializer.
+ *
+ * Lifts extension data onto the places bpmn-elements expects to find it on the element
+ * behaviour: the call activity's called process id (`zeebe:calledElement`) and the multi-instance
+ * input collection/element (`zeebe:loopCharacteristics`).
+ * @param {any} behaviour
+ */
+export function extendFn(behaviour) {
+  const values = behaviour.extensionElements?.values;
+  if (Array.isArray(values)) {
+    for (const ext of values) {
+      if (ext.$type === 'zeebe:CalledElement' && ext.processId) {
+        behaviour.calledElement = ext.processId;
+      }
+    }
+  }
+
+  // Map zeebe:loopCharacteristics (nested in the multi-instance loop) onto the bpmn-elements
+  // multi-instance behaviour: `inputCollection` -> `collection`, `inputElement` -> `elementVariable`.
+  const loop = behaviour.loopCharacteristics?.behaviour;
+  const loopExtension = loop?.extensionElements?.values?.find((v) => v.$type === 'zeebe:LoopCharacteristics');
+  if (loopExtension) {
+    if (loopExtension.inputCollection) loop.collection = loopExtension.inputCollection;
+    if (loopExtension.inputElement) loop.elementVariable = loopExtension.inputElement;
+  }
+}

package/types/index.d.ts

@@ -0,0 +1,326 @@
+declare module '@0dep/bpmn-extensions' {
+	/**
+	 * A flow extension activated by bpmn-elements around an element's run.
+	 * */
+	/**
+	 * Flow extensions factory. Pass it to the engine via the environment `extensions` option.
+	 * */
+	export function extensions(element: import("bpmn-elements").Activity | import("bpmn-elements").Process, context: import("bpmn-elements").ContextInstance): FlowExtension;
+	/**
+	 * Behaviour extend function for moddle-context-serializer.
+	 *
+	 * Lifts extension data onto the places bpmn-elements expects to find it on the element
+	 * behaviour: the call activity's called process id (`zeebe:calledElement`) and the multi-instance
+	 * input collection/element (`zeebe:loopCharacteristics`).
+	 * */
+	export function extendFn(behaviour: any): void;
+	/**
+	 * A flow extension activated by bpmn-elements around an element's run.
+	 */
+	export type FlowExtension = {
+		activate: (message: any) => void;
+		deactivate: (message?: any) => void;
+	};
+	/**
+	 * FEEL-aware expressions implementation for bpmn-elements.
+	 *
+	 * Plug it into the engine via the environment `expressions` option so that the whole
+	 * definition resolves FEEL expressions (`= ...`) instead of the default
+	 * `${...}` template expressions.
+	 *
+	 * */
+	export function FeelExpressions(): import("bpmn-elements").IExpressions;
+	/**
+	 * A bpmn-elements `scripts` implementation for script tasks.
+	 *
+	 * A script task carries a `zeebe:script` extension with a FEEL `expression` (and a
+	 * `resultVariable`). There is no embedded script body and no `scriptFormat` attribute, so this
+	 * registry ignores the script format and reads the expression straight off the element.
+	 *
+	 * Install it on the environment via the `scripts` option, alongside `FeelExpressions()`.
+	 *
+	 * */
+	export function FeelScripts(): import("bpmn-elements").IScripts;
+	/**
+	 * `zeebe:taskDefinition`.
+	 *
+	 * A job worker subscribed to the task `type` executes the activity. Here the
+	 * `type` is mapped to an environment service of the same name: the job worker is a service
+	 * function `(executionMessage, callback) => void` registered under the job type.
+	 *
+	 * The service receives the task headers and resolved io input on the execution message
+	 * content, and its result (the second callback argument) becomes the job variables that
+	 * output mapping operates on.
+	 *
+	 * Bind the task type to use as the activity `Service`:
+	 *   activity.behaviour.Service = JobService.bind(JobService, taskType);
+	 */
+	export function JobService(taskType: any, activity: any): JobService;
+	export class JobService {
+		/**
+		 * `zeebe:taskDefinition`.
+		 *
+		 * A job worker subscribed to the task `type` executes the activity. Here the
+		 * `type` is mapped to an environment service of the same name: the job worker is a service
+		 * function `(executionMessage, callback) => void` registered under the job type.
+		 *
+		 * The service receives the task headers and resolved io input on the execution message
+		 * content, and its result (the second callback argument) becomes the job variables that
+		 * output mapping operates on.
+		 *
+		 * Bind the task type to use as the activity `Service`:
+		 *   activity.behaviour.Service = JobService.bind(JobService, taskType);
+		 */
+		constructor(taskType: any, activity: any);
+		type: string | undefined;
+		taskType: any;
+		activity: any;
+		execute(executionMessage: any, callback: any): any;
+	}
+	/**
+	 * Activity-level extensions.
+	 *
+	 * Formatting and io/listener side effects are injected through the activity's `format-run-q`
+	 * queue so the activity waits for them (including async execution listeners) before
+	 * proceeding — the same mechanism bpmn-elements uses for extension formatting.
+	 */
+	export class ElementExtensions {
+		constructor(activity: any);
+		activity: any;
+		formatQ: any;
+		extensions: {
+			format: FormatActivity | FormatProcess;
+			io?: IoMapping;
+			headers?: TaskHeaders;
+			properties?: Properties;
+			listeners?: ExecutionListeners;
+			form?: Form;
+			loop?: LoopCharacteristics;
+			Service?: Function;
+		};
+		activate(message: any): void;
+		deactivate(): void;
+		/** @internal Shared with SubProcessExtensions. */
+		_onEnter(elementApi: any): Promise<void>;
+		/** @internal Shared with SubProcessExtensions. */
+		_onExecuted(elementApi: any): Promise<void>;
+		/** @internal Shared with SubProcessExtensions. */
+		_onListener(eventType: any, elementApi: any): Promise<void>;
+		#private;
+	}
+	/**
+	 * Process-level extensions. Formats the process on enter (documentation) and assigns
+	 * the result to the process variables.
+	 */
+	export class ProcessExtensions {
+		constructor(bp: any);
+		process: any;
+		extensions: {
+			format: FormatActivity | FormatProcess;
+			io?: IoMapping;
+			headers?: TaskHeaders;
+			properties?: Properties;
+			listeners?: ExecutionListeners;
+			form?: Form;
+			loop?: LoopCharacteristics;
+			Service?: Function;
+		};
+		activate(): void;
+		deactivate(): void;
+		#private;
+	}
+	/**
+	 * Sub-process extensions.
+	 *
+	 * A sub-process shares its broker with the child activities it contains, so their
+	 * `activity.*` events bubble through it. Subscribing with `activity.on(...)` (as a leaf
+	 * element does) would therefore fire the extension handlers for every child and spam the
+	 * sub-process format queue, stalling it. Instead, subscribe on the broker and filter to the
+	 * sub-process's own id.
+	 */
+	export class SubProcessExtensions extends ElementExtensions {
+		#private;
+	}
+	/**
+	 * Is the value a FEEL expression, i.e. a string starting with `=`?
+	 * */
+	export function isFeelExpression(value: unknown): boolean;
+	/**
+	 * Strip the leading `=` from a FEEL expression.
+	 * */
+	export function stripFeel(expression: string): string;
+	/**
+	 * Evaluate a FEEL expression against a context (the variables in scope).
+	 * @param expression FEEL expression, with or without the leading `=`
+	 * @param context Variables in scope
+	 * */
+	export function evaluateFeel(expression: string, context?: Record<string, any>): any;
+	/**
+	 * Evaluate a FEEL unary test, e.g. `> 100` or `1, 2, 3`, against an input value.
+	 * @param expression FEEL unary test
+	 * @param input The value being tested, available as `?` in the test
+	 * @param context Additional variables in scope
+	 * */
+	export function evaluateFeelUnaryTest(expression: string, input: any, context?: Record<string, any>): boolean;
+	/**
+	 * Resolve a value: evaluate it as FEEL when it starts with `=`, otherwise
+	 * return the static literal untouched.
+	 * @param context Variables in scope for FEEL evaluation
+	 * */
+	export function resolveValue(value: any, context?: Record<string, any>): any;
+	export class ServiceError extends Error {
+		constructor(jobType: any);
+		code: string;
+		output: {
+			statusCode: number;
+		};
+	}
+	export class FormatError extends Error {
+		constructor(elementId: any, err: any);
+		code: string;
+		output: {
+			statusCode: number;
+		};
+	}
+	/**
+	 * Format an activity on enter from its behaviour and extensions: documentation and,
+	 * for user tasks, the `zeebe:assignmentDefinition` (assignee, candidate users/groups).
+	 */
+	class FormatActivity {
+		constructor(activity: any, assignmentDefinition: any);
+		activity: any;
+		assignmentDefinition: any;
+		resolve(elementApi: any): {
+			description: any;
+			assignee: any;
+			candidateUsers: any[];
+			candidateGroups: any[];
+		};
+	}
+	/**
+	 * Format a process on enter: documentation.
+	 */
+	class FormatProcess {
+		constructor(bp: any);
+		process: any;
+		resolve(elementApi: any): {
+			description: any;
+		};
+	}
+	/**
+	 * `zeebe:ioMapping`.
+	 *
+	 * Input parameters are evaluated in the parent (process) scope when the element is entered,
+	 * producing the local variables the job runs with. Output parameters are evaluated in the
+	 * job-result scope when the element completes, merging the result back into the process
+	 * variables.
+	 *
+	 * Each parameter has a `source` (a FEEL expression or static value) and a `target`
+	 * (a, possibly dotted, variable name).
+	 */
+	class IoMapping {
+		constructor(activity: any, ioMapping: any);
+		activity: any;
+		inputParameters: any;
+		outputParameters: any;
+		get hasInput(): boolean;
+		get hasOutput(): boolean;
+		/**
+		 * Resolve input parameters against the current process variables.
+		 * */
+		getInput(elementApi: import("bpmn-elements").IApi<any>): {};
+		/**
+		 * Resolve output parameters against the job result overlaid on the process variables.
+		 * @param jobResult Variables produced by the job
+		 */
+		getOutput(elementApi: import("bpmn-elements").IApi<any>, jobResult?: Record<string, any>): {};
+	}
+	/**
+	 * `zeebe:taskHeaders`.
+	 *
+	 * Static key/value metadata passed to the job worker. Resolved to a plain object and made
+	 * available on the element content as `headers`.
+	 */
+	class TaskHeaders {
+		constructor(taskHeaders: any);
+		values: any;
+		resolve(): {};
+	}
+	/**
+	 * `zeebe:properties`.
+	 *
+	 * Named properties whose values may be FEEL expressions. Resolved to a plain object and made
+	 * available on the element content as `properties`.
+	 */
+	class Properties {
+		constructor(properties: any);
+		properties: any;
+		resolve(elementApi: any): {};
+	}
+	/**
+	 * `zeebe:executionListeners`.
+	 *
+	 * Each listener invokes a job worker (an environment service named by the listener `type`)
+	 * either before the element runs (`eventType: "start"`) or after it completes
+	 * (`eventType: "end"`). A listener is called as `(elementApi, { retries, headers }, callback)` and
+	 * may either call the callback or return a promise — either way the element blocks until it
+	 * settles. `retries` and `headers` are only present when the listener declares them (no defaults
+	 * are invented).
+	 */
+	class ExecutionListeners {
+		constructor(activity: any, executionListeners: any);
+		activity: any;
+		listeners: any;
+		get onStart(): any;
+		get onEnd(): any;
+		/**
+		 * Execute all listeners registered for an event type, in order.
+		 * */
+		execute(eventType: "start" | "end", elementApi: import("bpmn-elements").IApi<any>): Promise<void>;
+	}
+	/**
+	 * `zeebe:formDefinition`.
+	 *
+	 * User tasks (and form-bearing start events) reference their form here: a linked
+	 * form (`formId`), a deprecated form key (`formKey`), or an external form
+	 * (`externalReference`, which may be a FEEL expression). Resolved to a plain object and made
+	 * available on the element content as `form` so a task list can render it.
+	 */
+	class Form {
+		constructor(formDefinition: any);
+		formDefinition: any;
+		resolve(elementApi: any): {
+			versionTag?: any;
+			bindingType?: any;
+			externalReference?: any;
+			formKey?: any;
+			formId?: any;
+		};
+	}
+	/**
+	 * Output side of `zeebe:loopCharacteristics`.
+	 *
+	 * A multi-instance is aggregated into an `outputCollection` array: for each instance the
+	 * `outputElement` FEEL expression is evaluated in that instance's result scope and collected, in
+	 * input order, into the named collection variable.
+	 *
+	 * bpmn-elements collects instance outputs into an index-keyed object on the activity content
+	 * (`{ 0: <out>, 1: <out>, ... }`, where a call activity instance wraps its result as
+	 * `{ executionId, output }`). This reduces that to the output-collection array.
+	 */
+	class LoopCharacteristics {
+		constructor(loopCharacteristics: any);
+		outputCollection: any;
+		outputElement: any;
+		get hasOutputCollection(): boolean;
+		/**
+		 * @param indexedOutput bpmn-elements index-keyed instance outputs
+		 * @param baseScope process variables in scope for `outputElement`
+		 * */
+		aggregate(indexedOutput: Record<string, any> | undefined, baseScope: Record<string, any>): any[];
+	}
+
+	export {};
+}
+
+//# sourceMappingURL=index.d.ts.map