@0dep/bpmn-extensions 0.0.4 → 0.0.6

package/README.md

@@ -1,6 +1,6 @@
 # @0dep/bpmn-extensions
 
-[![Built latest](https://github.com/zerodep/bpmn-extensions/actions/workflows/build-latest.yaml/badge.svg)](https://github.com/zerodep/bpmn-extensions/actions/workflows/build-latest.yaml)[![Coverage Status](https://coveralls.io/repos/github/zerodep/bpmn-extensions/badge.svg?branch=main)](https://coveralls.io/github/zerodep/bpmn-extensions?branch=main)[![npm version](https://img.shields.io/npm/v/@0dep/bpmn-extensions)](https://www.npmjs.com/package/@0dep/bpmn-extensions)
+[![Built latest](https://github.com/zerodep/bpmn-extensions/actions/workflows/build-latest.yaml/badge.svg)](https://github.com/zerodep/bpmn-extensions/actions/workflows/build-latest.yaml)[![Coverage Status](https://coveralls.io/repos/github/zerodep/bpmn-extensions/badge.svg?branch=main)](https://coveralls.io/github/zerodep/bpmn-extensions?branch=main)
 
 Flow extensions for [bpmn-elements](https://github.com/paed01/bpmn-elements) with
 [FEEL](https://www.omg.org/dmn/) expression support.
@@ -12,10 +12,11 @@ which covers the older `camunda:*` extension elements.
 ## Install
 
 ```sh
-npm install @0dep/bpmn-extensions bpmn-elements
+npm install @0dep/bpmn-extensions bpmn-elements croner
 ```
 
-`bpmn-elements` (>= 18) is a peer dependency. Requires Node.js >= 22.
+`bpmn-elements` (>= 18) and [`croner`](https://www.npmjs.com/package/croner) (cron timer cycles) are
+peer dependencies. Requires Node.js >= 22.
 
 ## What it does
 
@@ -38,6 +39,9 @@ npm install @0dep/bpmn-extensions bpmn-elements
   process's input becomes variables local to its children.
 - **`zeebe:taskHeaders`** / **`zeebe:properties`** — exposed on the element content.
 - **`zeebe:assignmentDefinition`** — assignee / candidate users / groups for user tasks.
+- **`zeebe:priorityDefinition`** / **`zeebe:taskSchedule`** — a user task's `priority` and
+  `dueDate` / `followUpDate` resolved onto the element content for a task list to order and
+  remind by; FEEL date results are exposed as ISO 8601 strings.
 - **`zeebe:formDefinition`** — resolves a user task's form (`formId` / `formKey` / `externalReference`,
   `bindingType`) onto the element content for a task list to render.
 - **`zeebe:executionListeners`** — blocking start/end job workers around an element, called as
@@ -46,6 +50,10 @@ npm install @0dep/bpmn-extensions bpmn-elements
 - **`zeebe:calledElement`** — call activity target process id.
 - **`zeebe:loopCharacteristics`** — collection-based multi-instance (`inputCollection` / `inputElement`),
   sequential or parallel, with `outputElement` aggregated into the `outputCollection` array in input order.
+- **Timer start events with cron** — a `TimerEventDefinition` that also parses a **cron** `timeCycle`
+  (`0 0 * * *`, as Camunda 8 schedules timer start events) besides ISO 8601 intervals. A top-level
+  timer start event's cycle is lifted onto its behaviour as `scheduledStart` by `extendFn` and exposed
+  on the start event content, so a scheduler can find the flows to start without running them.
 - **`zeebe:subscription`** — the referenced message's `correlationKey` is resolved when the catching
   element (receive task, message event) starts waiting, and exposed on its content as
   `subscription: { message, correlationKey }` — route an incoming message by matching it against the
@@ -54,8 +62,14 @@ npm install @0dep/bpmn-extensions bpmn-elements
 ## API
 
 - `extensions(element, context)` — the flow extensions factory; pass it as an environment extension.
+  Elements that carry no zeebe extension data (and nothing else to format) get no extension attached
+  at all and run untouched; call activities and processes are always attached, since they propagate
+  io across process boundaries.
 - `extendFn(behaviour)` — moddle-context-serializer behaviour extender (lifts the extension data
-  bpmn-elements expects on the behaviour: call activity process id and multi-instance collection).
+  bpmn-elements expects on the behaviour: call activity process id, multi-instance collection, and a
+  timer start event's cycle as `scheduledStart`).
+- `TimerEventDefinition` — a bpmn-elements timer event definition that accepts cron `timeCycle`s;
+  install it through the type resolver: `TypeResolver({ ...elements, TimerEventDefinition })`.
 - `FeelExpressions()` — a bpmn-elements `IExpressions` implementation backed by FEEL.
 - `FeelScripts()` — a bpmn-elements `scripts` implementation that runs `zeebe:script` FEEL expressions.
 - FEEL helpers: `isFeelExpression`, `stripFeel`, `evaluateFeel`, `evaluateFeelUnaryTest`, `resolveValue`,
@@ -69,7 +83,7 @@ Wire it into a bpmn-elements definition (see `test/helpers/testHelpers.js` for t
 ```javascript
 import { createRequire } from 'node:module';
 import { strict as assert } from 'node:assert';
-import BpmnModdle from 'bpmn-moddle';
+import { BpmnModdle } from 'bpmn-moddle';
 import * as elements from 'bpmn-elements';
 import { Serializer, TypeResolver } from 'moddle-context-serializer';
 import { extensions, extendFn, FeelExpressions, FeelScripts } from '@0dep/bpmn-extensions';
@@ -124,6 +138,60 @@ A service task's `zeebe:taskDefinition type="charge-card"` is dispatched to the
 service named `charge-card`. Its callback result is the job's variables, which `zeebe:ioMapping`
 output parameters map back into the process.
 
+## Extract timers
+
+List the timers of a definition without running it — e.g. to schedule flows by their timer start
+event. The serializer collects every timer event definition; `extendFn` marks a timer start event's
+cycle as `scheduledStart`, and the cron-capable `TimerEventDefinition` parses each one to its next
+expiry:
+
+```javascript
+import { createRequire } from 'node:module';
+import { strict as assert } from 'node:assert';
+import { BpmnModdle } from 'bpmn-moddle';
+import * as elements from 'bpmn-elements';
+import { Serializer, TypeResolver } from 'moddle-context-serializer';
+import { extendFn, TimerEventDefinition } from '@0dep/bpmn-extensions';
+
+const require = createRequire(import.meta.url);
+const moddle = new BpmnModdle({ zeebe: require('zeebe-bpmn-moddle/resources/zeebe.json') });
+
+const source = `<?xml version="1.0" encoding="UTF-8"?>
+<definitions xmlns="http://www.omg.org/spec/BPMN/20100524/MODEL" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" id="def">
+  <process id="nightly" isExecutable="true">
+    <startEvent id="start">
+      <timerEventDefinition>
+        <timeCycle xsi:type="tFormalExpression">0 1 * * *</timeCycle>
+      </timerEventDefinition>
+    </startEvent>
+    <sequenceFlow id="to-task" sourceRef="start" targetRef="task" />
+    <userTask id="task" />
+    <boundaryEvent id="reminder" cancelActivity="false" attachedToRef="task">
+      <timerEventDefinition>
+        <timeDuration xsi:type="tFormalExpression">R3/PT1M</timeDuration>
+      </timerEventDefinition>
+    </boundaryEvent>
+  </process>
+</definitions>`;
+
+const moddleContext = await moddle.fromXML(source);
+const serializer = Serializer(moddleContext, TypeResolver({ ...elements, TimerEventDefinition }), extendFn);
+
+const dummyActivity = { id: 'dummy', broker: {}, environment: { Logger() {} } };
+const timers = serializer.getTimers().map((t) => ({
+  ...t,
+  parsed: new TimerEventDefinition(dummyActivity, { type: t.timer.type, behaviour: t.timer }).parse(t.timer.timerType, t.timer.value),
+}));
+
+console.log(timers.map((t) => [t.parent.id, t.timer.timerType, t.timer.value, t.parsed.expireAt]));
+assert.equal(timers.length, 2);
+assert.equal(timers[0].parent.id, 'start');
+assert.ok(timers[0].parsed.expireAt instanceof Date);
+
+// A timer start event is a schedule: the cycle is lifted onto the behaviour
+assert.equal(serializer.getActivityById('start').behaviour.scheduledStart, '0 1 * * *');
+```
+
 ## Development
 
 ```sh
@@ -141,6 +209,7 @@ the engine's `Logger` to the [`debug`](https://www.npmjs.com/package/debug) pack
 
 # Ecosystem
 
+- [0dep.se/run](https://0dep.se/run) — Run a BPMN diagram in the browser: `bpmn-elements` wired with `@0dep/bpmn-extensions`, drawn with bpmn-js; step through, signal waiting tasks, and drop DMN files for business rule tasks.
 - [bpmn-engine](https://github.com/paed01/bpmn-engine) — BPMN 2.0 execution engine wrapping `bpmn-elements`; the batteries-included way to run, stop, resume, and recover flows.
 - [bpmn-middleware](https://github.com/zerodep/bpmn-middleware) — Express middleware exposing the engine over HTTP, with pluggable state storage.
 - [@onify/flow-extensions](https://github.com/onify/flow-extensions) — Onify Flow extensions for `bpmn-elements`.

package/dist/index.js

@@ -1,5 +1,8 @@
 'use strict';
 
+var croner = require('croner');
+var bpmnElements = require('bpmn-elements');
+
 // these aren't really private, but nor are they really useful to document
 
 /**
@@ -11609,9 +11612,9 @@ function getSpecializer(spec) {
  *
  * @return {T[]}
  */
-const nativeHasOwnProperty$1 = Object.prototype.hasOwnProperty;
+const nativeHasOwnProperty = Object.prototype.hasOwnProperty;
 
-function isNil$2(obj) {
+function isNil$1(obj) {
   return obj == null;
 }
 
@@ -11623,8 +11626,8 @@ function isNil$2(obj) {
  *
  * @return {Boolean}
  */
-function has$1(target, key) {
-  return !isNil$2(target) && nativeHasOwnProperty$1.call(target, key);
+function has(target, key) {
+  return !isNil$1(target) && nativeHasOwnProperty.call(target, key);
 }
 
 let nextTagID = 0;
@@ -13107,7 +13110,7 @@ class VariableContext {
         continue;
       }
 
-      if (has$1(merged, key)) {
+      if (has(merged, key)) {
 
         // deep merge nested contexts
         merged[key] = this.__merge(merged[key], value);
@@ -13241,7 +13244,7 @@ class Variables {
         return null;
       }
 
-      if (!isNil$2(scope.value)) {
+      if (!isNil$1(scope.value)) {
         return scope.value;
       }
     }
@@ -13871,33 +13874,6 @@ const parser = LRParser.deserialize({
   tokenPrec: 2660
 });
 
-/**
- * Flatten array, one level deep.
- *
- * @template T
- *
- * @param {T[][] | T[] | null} [arr]
- *
- * @return {T[]}
- */
-const nativeHasOwnProperty = Object.prototype.hasOwnProperty;
-
-function isNil$1(obj) {
-  return obj == null;
-}
-
-/**
- * Return true, if target owns a property with the given key.
- *
- * @param {Object} target
- * @param {String} key
- *
- * @return {Boolean}
- */
-function has(target, key) {
-  return !isNil$1(target) && nativeHasOwnProperty.call(target, key);
-}
-
 function isNil(e) {
     return e === null || e === undefined;
 }
@@ -16238,17 +16214,22 @@ function getFeelScope(environment, localVariables) {
 }
 
 /**
- * Format an activity on enter from its behaviour and extensions: documentation and,
- * for user tasks, the `zeebe:assignmentDefinition` (assignee, candidate users/groups).
+ * Format an activity on enter from its behaviour and extensions: documentation, a top-level
+ * timer start event's `scheduledStart` (lifted by `extendFn`) and, for user tasks, the `zeebe:assignmentDefinition` (assignee, candidate users/groups),
+ * `zeebe:priorityDefinition` (priority), and `zeebe:taskSchedule` (due/follow-up date).
  */
 class FormatActivity {
   /**
    * @param {import('bpmn-elements').Activity} activity
    * @param {any} assignmentDefinition
+   * @param {any} [priorityDefinition]
+   * @param {any} [taskSchedule]
    */
-  constructor(activity, assignmentDefinition) {
+  constructor(activity, assignmentDefinition, priorityDefinition, taskSchedule) {
     this.activity = activity;
     this.assignmentDefinition = assignmentDefinition;
+    this.priorityDefinition = priorityDefinition;
+    this.taskSchedule = taskSchedule;
   }
   /**
    * @param {import('bpmn-elements').IApi<import('bpmn-elements').Activity>} elementApi
@@ -16260,9 +16241,14 @@ class FormatActivity {
     const documentation = this.activity.behaviour.documentation;
     if (documentation && !elementApi.content.description) {
       const text = documentation[0]?.text;
-      if (text) result.description = resolveValue(text, scope);
+      if (text) result.description = /** @type {string} */ (resolveValue(text, scope));
     }
 
+    // A timer start event's cycle is only a schedule when it starts the process itself — a
+    // sub-process start event runs whenever its parent does.
+    const scheduledStart = this.activity.behaviour.scheduledStart;
+    if (scheduledStart && this.activity.parent?.type === 'bpmn:Process') result.scheduledStart = scheduledStart;
+
     const assignment = this.assignmentDefinition;
     if (assignment) {
       const { assignee, candidateUsers, candidateGroups } = assignment;
@@ -16273,6 +16259,22 @@ class FormatActivity {
       if (groups) result.candidateGroups = groups;
     }
 
+    const priority = this.priorityDefinition?.priority;
+    if (priority !== undefined) {
+      const resolved = resolveValue(priority, scope);
+      // A static attribute value is a string — expose a numeric one as a number (like retries).
+      const num = Number(resolved);
+      /** @type {Number | string | undefined} */
+      result.priority = typeof resolved === 'string' && resolved.trim() !== '' && Number.isFinite(num) ? num : resolved;
+    }
+
+    const schedule = this.taskSchedule;
+    if (schedule) {
+      const { dueDate, followUpDate } = schedule;
+      if (dueDate !== undefined) result.dueDate = resolveDate(dueDate, scope);
+      if (followUpDate !== undefined) result.followUpDate = resolveDate(followUpDate, scope);
+    }
+
     return result;
   }
 }
@@ -16295,15 +16297,33 @@ class FormatProcess {
     const documentation = this.process.behaviour.documentation;
     if (documentation && !elementApi.content.description) {
       const text = documentation[0]?.text;
-      if (text) result.description = resolveValue(text, getFeelScope(elementApi.environment));
+      if (text) result.description = /** @type {string} */ (resolveValue(text, getFeelScope(elementApi.environment)));
     }
     return result;
   }
 }
 
+/**
+ * Resolve a due/follow-up date to an ISO 8601 string. A FEEL temporal result (a luxon
+ * DateTime) or a Date is ISO-stringified — content is JSON-serialized on `getState()`, so a
+ * string is the shape that survives a recover round trip. Anything else passes through as-is.
+ * @param {any} value
+ * @param {any} scope
+ * @returns {string | undefined} Date as iso string
+ */
+function resolveDate(value, scope) {
+  const resolved = resolveValue(value, scope);
+  if (typeof resolved?.toISO === 'function') return resolved.toISO();
+  if (resolved instanceof Date) return resolved.toISOString();
+  return resolved;
+}
+
 /**
  * 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.
+ * @param {any} value
+ * @param {any} scope
+ * @returns {string[] | undefined}
  */
 function resolveList(value, scope) {
   if (!value) return undefined;
@@ -16652,6 +16672,7 @@ class Subscription {
  * @property {any} [calledDecision]
  * @property {Function} [Service]
  * @property {Subscription} [subscription]
+ * @property {boolean} [isEmpty] no zeebe extension data found and nothing to format — the element needs no extension
  */
 
 /**
@@ -16664,10 +16685,15 @@ function getExtensions(element, context) {
   const result = {};
   const isProcess = element.type === 'bpmn:Process';
 
-  let assignmentDefinition;
+  let assignmentDefinition, priorityDefinition, taskSchedule;
+  let foundZeebe = false;
   const values = element.behaviour.extensionElements?.values;
   if (values) {
     for (const ext of values) {
+      // Any zeebe-namespaced extension element counts as found — including ones with no
+      // handler (e.g. the bare `zeebe:userTask` marker), which keep the element extension
+      // loaded so e.g. a native user task's completion payload is merged.
+      if (ext.$type.startsWith('zeebe:')) foundZeebe = true;
       switch (ext.$type) {
         case 'zeebe:IoMapping':
           result.io = new IoMapping(element, ext);
@@ -16681,6 +16707,12 @@ function getExtensions(element, context) {
         case 'zeebe:AssignmentDefinition':
           assignmentDefinition = ext;
           break;
+        case 'zeebe:PriorityDefinition':
+          priorityDefinition = ext;
+          break;
+        case 'zeebe:TaskSchedule':
+          taskSchedule = ext;
+          break;
         case 'zeebe:ExecutionListeners':
           if (ext.listeners?.length) result.listeners = new ExecutionListeners(element, ext);
           break;
@@ -16722,7 +16754,22 @@ function getExtensions(element, context) {
   );
   if (loopExtension?.outputCollection) result.loop = new LoopCharacteristics(loopExtension);
 
-  result.format = isProcess ? new FormatProcess(element) : new FormatActivity(element, assignmentDefinition);
+  // Nothing zeebe-flavoured and nothing to format (documentation, a process-level timer start
+  // event's `scheduledStart`) — the element needs no extension. A call
+  // activity is never inert: its output unwrap/merge is type-driven (the standard BPMN
+  // `calledElement` attribute needs no zeebe elements). Ignored for processes — a called
+  // process always needs its inbound input promoted, whatever it carries itself.
+  result.isEmpty =
+    !foundZeebe &&
+    !result.subscription &&
+    !loopExtension &&
+    !element.behaviour.documentation &&
+    !(element.behaviour.scheduledStart && element.parent?.type === 'bpmn:Process') &&
+    element.type !== 'bpmn:CallActivity';
+
+  result.format = isProcess
+    ? new FormatProcess(element)
+    : new FormatActivity(element, assignmentDefinition, priorityDefinition, taskSchedule);
 
   return result;
 }
@@ -17090,6 +17137,50 @@ function getScriptExpression(activity) {
   return script?.expression;
 }
 
+/**
+ * bpmn-elements timer event definition that also accepts a **cron** `timeCycle` (Camunda 8
+ * timer start events schedule with cron, e.g. `0 0 * * *`). An ISO 8601 interval is tried
+ * first; on failure the value is parsed as cron and the next run is the expiry.
+ *
+ * Install it via the type resolver so it replaces the bpmn-elements default:
+ * `TypeResolver({ ...elements, TimerEventDefinition })`.
+ */
+class TimerEventDefinition extends bpmnElements.TimerEventDefinition {
+  /**
+   * Supported timeCycle formats
+   * @returns {string[]}
+   */
+  get supports() {
+    return ['cron', 'iso8601'];
+  }
+  /**
+   * @param {import('bpmn-elements').TimerType} timerType
+   * @param {string} value
+   * @returns {import('bpmn-elements').parsedTimer}
+   */
+  parse(timerType, value) {
+    if (timerType !== 'timeCycle') return super.parse(timerType, value);
+
+    /** @type {any} */
+    let isoError;
+    try {
+      return super.parse(timerType, value);
+    } catch (err) {
+      isoError = err;
+    }
+
+    try {
+      const expireAt = new croner.Cron(value).nextRun();
+      if (!expireAt) throw new RangeError('cron has no next run');
+      return { expireAt, delay: expireAt.getTime() - Date.now() };
+    } catch (/** @type {any} */ err) {
+      this.logger.error(`<${this.activity?.id}> failed to parse timeCycle: ${isoError.message}`);
+      this.logger.error(`<${this.activity?.id}> failed to parse timeCycle as cron: ${err.message}`);
+      throw new RangeError(`Failed to parse timeCycle <${value?.substring(0, 255)}> as ISO 8601 interval or cron`, { cause: err });
+    }
+  }
+}
+
 /**
  * A flow extension activated by bpmn-elements around an element's run.
  * @typedef {object} FlowExtension
@@ -17099,20 +17190,32 @@ function getScriptExpression(activity) {
 
 /**
  * Flow extensions factory. Pass it to the engine via the environment `extensions` option.
+ *
+ * Returns undefined for an element that carries no zeebe extension data and nothing else to
+ * format (no documentation, not a call activity) — bpmn-elements skips falsy extensions, so
+ * plain elements run untouched, with no broker subscriptions or format-queue traffic.
  * @param {import('bpmn-elements').Activity | import('bpmn-elements').Process} element
  * @param {import('bpmn-elements').ContextInstance} context
- * @returns {FlowExtension}
+ * @returns {FlowExtension | undefined}
  */
 function extensions(element, context) {
   switch (element.type) {
     case 'bpmn:Process':
+      // A process is always attached: a called process needs its inbound input promoted
+      // even when it carries no zeebe extension data of its own.
       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);
+    case 'bpmn:Transaction': {
+      const subProcessExtensions = new SubProcessExtensions(element, context);
+      if (subProcessExtensions.extensions.isEmpty) return undefined;
+      return subProcessExtensions;
+    }
+    default: {
+      const elementExtensions = new ElementExtensions(element, context);
+      if (elementExtensions.extensions.isEmpty) return undefined;
+      return elementExtensions;
+    }
   }
 }
 
@@ -17121,10 +17224,17 @@ function extensions(element, context) {
  *
  * 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`).
+ * input collection/element (`zeebe:loopCharacteristics`). A timer start event's `timeCycle`
+ * (ISO 8601 or cron) is lifted as `scheduledStart`, so a scheduler can find it without running
+ * the flow.
  * @param {any} behaviour
  */
 function extendFn(behaviour) {
+  if (behaviour.$type === 'bpmn:StartEvent' && Array.isArray(behaviour.eventDefinitions)) {
+    const timer = behaviour.eventDefinitions.find((ed) => ed?.type === 'bpmn:TimerEventDefinition' && ed.behaviour?.timeCycle);
+    if (timer) behaviour.scheduledStart = timer.behaviour.timeCycle;
+  }
+
   const values = behaviour.extensionElements?.values;
   if (Array.isArray(values)) {
     for (const ext of values) {
@@ -17152,6 +17262,7 @@ exports.JobService = JobService;
 exports.ProcessExtensions = ProcessExtensions;
 exports.ServiceError = ServiceError;
 exports.SubProcessExtensions = SubProcessExtensions;
+exports.TimerEventDefinition = TimerEventDefinition;
 exports.evaluateFeel = evaluateFeel;
 exports.evaluateFeelUnaryTest = evaluateFeelUnaryTest;
 exports.extendFn = extendFn;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@0dep/bpmn-extensions",
-  "version": "0.0.4",
+  "version": "0.0.6",
   "description": "Flow extensions for bpmn-elements: FEEL expressions and the zeebe-namespace BPMN extension elements",
   "type": "module",
   "module": "src/index.js",
@@ -51,7 +51,8 @@
     "access": "public"
   },
   "peerDependencies": {
-    "bpmn-elements": ">=18.0.12"
+    "bpmn-elements": ">=18.0.12",
+    "croner": ">=9"
   },
   "dependencies": {
     "feelin": "^7.0.1"
@@ -69,9 +70,10 @@
     "@types/mocha": "^10.0.10",
     "@types/node": "^26.1.1",
     "bpmn-elements": "^18.0.12",
-    "bpmn-moddle": "^9.0.1",
+    "bpmn-moddle": "^10.1.0",
     "c8": "^12.0.0",
     "chai": "^6.2.2",
+    "croner": "^10.0.1",
     "debug": "^4.4.3",
     "dts-buddy": "^0.8.2",
     "eslint": "^10.6.0",
@@ -83,7 +85,7 @@
     "rollup": "^4.62.2",
     "texample": "^1.0.2",
     "typescript": "^6.0.3",
-    "zeebe-bpmn-moddle": "^1.15.0"
+    "zeebe-bpmn-moddle": "^2.0.0"
   },
   "files": [
     "src",

package/src/TimerEventDefinition.js

@@ -0,0 +1,46 @@
+import { Cron } from 'croner';
+import { TimerEventDefinition as BaseTimerEventDefinition } from 'bpmn-elements';
+
+/**
+ * bpmn-elements timer event definition that also accepts a **cron** `timeCycle` (Camunda 8
+ * timer start events schedule with cron, e.g. `0 0 * * *`). An ISO 8601 interval is tried
+ * first; on failure the value is parsed as cron and the next run is the expiry.
+ *
+ * Install it via the type resolver so it replaces the bpmn-elements default:
+ * `TypeResolver({ ...elements, TimerEventDefinition })`.
+ */
+export class TimerEventDefinition extends BaseTimerEventDefinition {
+  /**
+   * Supported timeCycle formats
+   * @returns {string[]}
+   */
+  get supports() {
+    return ['cron', 'iso8601'];
+  }
+  /**
+   * @param {import('bpmn-elements').TimerType} timerType
+   * @param {string} value
+   * @returns {import('bpmn-elements').parsedTimer}
+   */
+  parse(timerType, value) {
+    if (timerType !== 'timeCycle') return super.parse(timerType, value);
+
+    /** @type {any} */
+    let isoError;
+    try {
+      return super.parse(timerType, value);
+    } catch (err) {
+      isoError = err;
+    }
+
+    try {
+      const expireAt = new Cron(value).nextRun();
+      if (!expireAt) throw new RangeError('cron has no next run');
+      return { expireAt, delay: expireAt.getTime() - Date.now() };
+    } catch (/** @type {any} */ err) {
+      this.logger.error(`<${this.activity?.id}> failed to parse timeCycle: ${isoError.message}`);
+      this.logger.error(`<${this.activity?.id}> failed to parse timeCycle as cron: ${err.message}`);
+      throw new RangeError(`Failed to parse timeCycle <${value?.substring(0, 255)}> as ISO 8601 interval or cron`, { cause: err });
+    }
+  }
+}

package/src/extensions/formatters.js

@@ -1,17 +1,22 @@
 import { resolveValue, getFeelScope } 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).
+ * Format an activity on enter from its behaviour and extensions: documentation, a top-level
+ * timer start event's `scheduledStart` (lifted by `extendFn`) and, for user tasks, the `zeebe:assignmentDefinition` (assignee, candidate users/groups),
+ * `zeebe:priorityDefinition` (priority), and `zeebe:taskSchedule` (due/follow-up date).
  */
 export class FormatActivity {
   /**
    * @param {import('bpmn-elements').Activity} activity
    * @param {any} assignmentDefinition
+   * @param {any} [priorityDefinition]
+   * @param {any} [taskSchedule]
    */
-  constructor(activity, assignmentDefinition) {
+  constructor(activity, assignmentDefinition, priorityDefinition, taskSchedule) {
     this.activity = activity;
     this.assignmentDefinition = assignmentDefinition;
+    this.priorityDefinition = priorityDefinition;
+    this.taskSchedule = taskSchedule;
   }
   /**
    * @param {import('bpmn-elements').IApi<import('bpmn-elements').Activity>} elementApi
@@ -23,9 +28,14 @@ export class FormatActivity {
     const documentation = this.activity.behaviour.documentation;
     if (documentation && !elementApi.content.description) {
       const text = documentation[0]?.text;
-      if (text) result.description = resolveValue(text, scope);
+      if (text) result.description = /** @type {string} */ (resolveValue(text, scope));
     }
 
+    // A timer start event's cycle is only a schedule when it starts the process itself — a
+    // sub-process start event runs whenever its parent does.
+    const scheduledStart = this.activity.behaviour.scheduledStart;
+    if (scheduledStart && this.activity.parent?.type === 'bpmn:Process') result.scheduledStart = scheduledStart;
+
     const assignment = this.assignmentDefinition;
     if (assignment) {
       const { assignee, candidateUsers, candidateGroups } = assignment;
@@ -36,6 +46,22 @@ export class FormatActivity {
       if (groups) result.candidateGroups = groups;
     }
 
+    const priority = this.priorityDefinition?.priority;
+    if (priority !== undefined) {
+      const resolved = resolveValue(priority, scope);
+      // A static attribute value is a string — expose a numeric one as a number (like retries).
+      const num = Number(resolved);
+      /** @type {Number | string | undefined} */
+      result.priority = typeof resolved === 'string' && resolved.trim() !== '' && Number.isFinite(num) ? num : resolved;
+    }
+
+    const schedule = this.taskSchedule;
+    if (schedule) {
+      const { dueDate, followUpDate } = schedule;
+      if (dueDate !== undefined) result.dueDate = resolveDate(dueDate, scope);
+      if (followUpDate !== undefined) result.followUpDate = resolveDate(followUpDate, scope);
+    }
+
     return result;
   }
 }
@@ -58,15 +84,33 @@ export class FormatProcess {
     const documentation = this.process.behaviour.documentation;
     if (documentation && !elementApi.content.description) {
       const text = documentation[0]?.text;
-      if (text) result.description = resolveValue(text, getFeelScope(elementApi.environment));
+      if (text) result.description = /** @type {string} */ (resolveValue(text, getFeelScope(elementApi.environment)));
     }
     return result;
   }
 }
 
+/**
+ * Resolve a due/follow-up date to an ISO 8601 string. A FEEL temporal result (a luxon
+ * DateTime) or a Date is ISO-stringified — content is JSON-serialized on `getState()`, so a
+ * string is the shape that survives a recover round trip. Anything else passes through as-is.
+ * @param {any} value
+ * @param {any} scope
+ * @returns {string | undefined} Date as iso string
+ */
+function resolveDate(value, scope) {
+  const resolved = resolveValue(value, scope);
+  if (typeof resolved?.toISO === 'function') return resolved.toISO();
+  if (resolved instanceof Date) return resolved.toISOString();
+  return resolved;
+}
+
 /**
  * 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.
+ * @param {any} value
+ * @param {any} scope
+ * @returns {string[] | undefined}
  */
 function resolveList(value, scope) {
   if (!value) return undefined;

package/src/getExtensions.js

@@ -22,6 +22,7 @@ import { Subscription } from './extensions/Subscription.js';
  * @property {any} [calledDecision]
  * @property {Function} [Service]
  * @property {Subscription} [subscription]
+ * @property {boolean} [isEmpty] no zeebe extension data found and nothing to format — the element needs no extension
  */
 
 /**
@@ -34,10 +35,15 @@ export function getExtensions(element, context) {
   const result = {};
   const isProcess = element.type === 'bpmn:Process';
 
-  let assignmentDefinition;
+  let assignmentDefinition, priorityDefinition, taskSchedule;
+  let foundZeebe = false;
   const values = element.behaviour.extensionElements?.values;
   if (values) {
     for (const ext of values) {
+      // Any zeebe-namespaced extension element counts as found — including ones with no
+      // handler (e.g. the bare `zeebe:userTask` marker), which keep the element extension
+      // loaded so e.g. a native user task's completion payload is merged.
+      if (ext.$type.startsWith('zeebe:')) foundZeebe = true;
       switch (ext.$type) {
         case 'zeebe:IoMapping':
           result.io = new IoMapping(element, ext);
@@ -51,6 +57,12 @@ export function getExtensions(element, context) {
         case 'zeebe:AssignmentDefinition':
           assignmentDefinition = ext;
           break;
+        case 'zeebe:PriorityDefinition':
+          priorityDefinition = ext;
+          break;
+        case 'zeebe:TaskSchedule':
+          taskSchedule = ext;
+          break;
         case 'zeebe:ExecutionListeners':
           if (ext.listeners?.length) result.listeners = new ExecutionListeners(element, ext);
           break;
@@ -92,7 +104,22 @@ export function getExtensions(element, context) {
   );
   if (loopExtension?.outputCollection) result.loop = new LoopCharacteristics(loopExtension);
 
-  result.format = isProcess ? new FormatProcess(element) : new FormatActivity(element, assignmentDefinition);
+  // Nothing zeebe-flavoured and nothing to format (documentation, a process-level timer start
+  // event's `scheduledStart`) — the element needs no extension. A call
+  // activity is never inert: its output unwrap/merge is type-driven (the standard BPMN
+  // `calledElement` attribute needs no zeebe elements). Ignored for processes — a called
+  // process always needs its inbound input promoted, whatever it carries itself.
+  result.isEmpty =
+    !foundZeebe &&
+    !result.subscription &&
+    !loopExtension &&
+    !element.behaviour.documentation &&
+    !(element.behaviour.scheduledStart && element.parent?.type === 'bpmn:Process') &&
+    element.type !== 'bpmn:CallActivity';
+
+  result.format = isProcess
+    ? new FormatProcess(element)
+    : new FormatActivity(element, assignmentDefinition, priorityDefinition, taskSchedule);
 
   return result;
 }

package/src/index.js

@@ -5,6 +5,7 @@ import { SubProcessExtensions } from './SubProcessExtensions.js';
 export { ElementExtensions, ProcessExtensions, SubProcessExtensions };
 export { FeelExpressions } from './Expressions.js';
 export { FeelScripts } from './extensions/FeelScripts.js';
+export { TimerEventDefinition } from './TimerEventDefinition.js';
 export { isFeelExpression, stripFeel, evaluateFeel, evaluateFeelUnaryTest, resolveValue, getFeelScope } from './feel.js';
 export { JobService } from './extensions/TaskDefinition.js';
 export { ServiceError, FormatError } from './Errors.js';
@@ -18,20 +19,32 @@ export { ServiceError, FormatError } from './Errors.js';
 
 /**
  * Flow extensions factory. Pass it to the engine via the environment `extensions` option.
+ *
+ * Returns undefined for an element that carries no zeebe extension data and nothing else to
+ * format (no documentation, not a call activity) — bpmn-elements skips falsy extensions, so
+ * plain elements run untouched, with no broker subscriptions or format-queue traffic.
  * @param {import('bpmn-elements').Activity | import('bpmn-elements').Process} element
  * @param {import('bpmn-elements').ContextInstance} context
- * @returns {FlowExtension}
+ * @returns {FlowExtension | undefined}
  */
 export function extensions(element, context) {
   switch (element.type) {
     case 'bpmn:Process':
+      // A process is always attached: a called process needs its inbound input promoted
+      // even when it carries no zeebe extension data of its own.
       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);
+    case 'bpmn:Transaction': {
+      const subProcessExtensions = new SubProcessExtensions(element, context);
+      if (subProcessExtensions.extensions.isEmpty) return undefined;
+      return subProcessExtensions;
+    }
+    default: {
+      const elementExtensions = new ElementExtensions(element, context);
+      if (elementExtensions.extensions.isEmpty) return undefined;
+      return elementExtensions;
+    }
   }
 }
 
@@ -40,10 +53,17 @@ export function extensions(element, context) {
  *
  * 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`).
+ * input collection/element (`zeebe:loopCharacteristics`). A timer start event's `timeCycle`
+ * (ISO 8601 or cron) is lifted as `scheduledStart`, so a scheduler can find it without running
+ * the flow.
  * @param {any} behaviour
  */
 export function extendFn(behaviour) {
+  if (behaviour.$type === 'bpmn:StartEvent' && Array.isArray(behaviour.eventDefinitions)) {
+    const timer = behaviour.eventDefinitions.find((ed) => ed?.type === 'bpmn:TimerEventDefinition' && ed.behaviour?.timeCycle);
+    if (timer) behaviour.scheduledStart = timer.behaviour.timeCycle;
+  }
+
   const values = behaviour.extensionElements?.values;
   if (Array.isArray(values)) {
     for (const ext of values) {

package/types/index.d.ts

@@ -1,17 +1,24 @@
 declare module '@0dep/bpmn-extensions' {
+	import type { TimerEventDefinition as BaseTimerEventDefinition } from 'bpmn-elements';
 	/**
 	 * 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.
+	 *
+	 * Returns undefined for an element that carries no zeebe extension data and nothing else to
+	 * format (no documentation, not a call activity) — bpmn-elements skips falsy extensions, so
+	 * plain elements run untouched, with no broker subscriptions or format-queue traffic.
 	 * */
-	export function extensions(element: import("bpmn-elements").Activity | import("bpmn-elements").Process, context: import("bpmn-elements").ContextInstance): FlowExtension;
+	export function extensions(element: import("bpmn-elements").Activity | import("bpmn-elements").Process, context: import("bpmn-elements").ContextInstance): FlowExtension | undefined;
 	/**
 	 * 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`).
+	 * input collection/element (`zeebe:loopCharacteristics`). A timer start event's `timeCycle`
+	 * (ISO 8601 or cron) is lifted as `scheduledStart`, so a scheduler can find it without running
+	 * the flow.
 	 * */
 	export function extendFn(behaviour: any): void;
 	/**
@@ -44,6 +51,20 @@ declare module '@0dep/bpmn-extensions' {
 	 *
 	 * */
 	export function FeelScripts(): import("bpmn-elements").IScripts;
+	/**
+	 * bpmn-elements timer event definition that also accepts a **cron** `timeCycle` (Camunda 8
+	 * timer start events schedule with cron, e.g. `0 0 * * *`). An ISO 8601 interval is tried
+	 * first; on failure the value is parsed as cron and the next run is the expiry.
+	 *
+	 * Install it via the type resolver so it replaces the bpmn-elements default:
+	 * `TypeResolver({ ...elements, TimerEventDefinition })`.
+	 */
+	export class TimerEventDefinition extends BaseTimerEventDefinition {
+		/**
+		 * Supported timeCycle formats
+		 * */
+		get supports(): string[];
+	}
 	/**
 	 * `zeebe:taskDefinition`.
 	 *
@@ -210,22 +231,34 @@ declare module '@0dep/bpmn-extensions' {
 		calledDecision?: any;
 		Service?: Function | undefined;
 		subscription?: Subscription | undefined;
+		/**
+		 * no zeebe extension data found and nothing to format — the element needs no extension
+		 */
+		isEmpty?: boolean | undefined;
 	};
 	/**
-	 * Format an activity on enter from its behaviour and extensions: documentation and,
-	 * for user tasks, the `zeebe:assignmentDefinition` (assignee, candidate users/groups).
+	 * Format an activity on enter from its behaviour and extensions: documentation, a top-level
+	 * timer start event's `scheduledStart` (lifted by `extendFn`) and, for user tasks, the `zeebe:assignmentDefinition` (assignee, candidate users/groups),
+	 * `zeebe:priorityDefinition` (priority), and `zeebe:taskSchedule` (due/follow-up date).
 	 */
 	class FormatActivity {
 		
-		constructor(activity: import("bpmn-elements").Activity, assignmentDefinition: any);
+		constructor(activity: import("bpmn-elements").Activity, assignmentDefinition: any, priorityDefinition?: any, taskSchedule?: any);
 		activity: import("bpmn-elements").Activity;
 		assignmentDefinition: any;
+		priorityDefinition: any;
+		taskSchedule: any;
 		
 		resolve(elementApi: import("bpmn-elements").IApi<import("bpmn-elements").Activity>): {
-			description: any;
+			description: string;
+			scheduledStart: any;
 			assignee: any;
-			candidateUsers: any[];
-			candidateGroups: any[];
+			candidateUsers: string[];
+			candidateGroups: string[];
+			
+			priority: number | string | undefined;
+			dueDate: string | undefined;
+			followUpDate: string | undefined;
 		};
 	}
 	/**
@@ -237,7 +270,7 @@ declare module '@0dep/bpmn-extensions' {
 		process: import("bpmn-elements").Process;
 		
 		resolve(elementApi: import("bpmn-elements").IApi<import("bpmn-elements").Process>): {
-			description: any;
+			description: string;
 		};
 	}
 	/**

package/types/index.d.ts.map

@@ -6,6 +6,7 @@
 		"extendFn",
 		"FeelExpressions",
 		"FeelScripts",
+		"TimerEventDefinition",
 		"JobService",
 		"ElementExtensions",
 		"ProcessExtensions",
@@ -32,6 +33,7 @@
 		"../src/index.js",
 		"../src/Expressions.js",
 		"../src/extensions/FeelScripts.js",
+		"../src/TimerEventDefinition.js",
 		"../src/extensions/TaskDefinition.js",
 		"../src/ElementExtensions.js",
 		"../src/ProcessExtensions.js",
@@ -64,8 +66,9 @@
 		null,
 		null,
 		null,
+		null,
 		null
 	],
-	"mappings": ";;;;;;;iBAwBgBA,UAAUA;;;;;;;;iBAqBVC,QAAQA;;;;;;;;;;;;;;;;iBClCRC,eAAeA;;;;;;;;;;;;;;iBCEfC,WAAWA;;;;;;;;;;;;;;;iBCIXC,UAAUA;cAAVA,UAAUA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cCEbC,iBAAiBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cCZjBC,iBAAiBA;;;;;;;;;;;;;;;;;;;cCIjBC,oBAAoBA;;;;;;;iBCEjBC,gBAAgBA;;;;iBAShBC,SAASA;;;;;;iBAUTC,YAAYA;;;;;;;;iBAYZC,qBAAqBA;;;;;;iBAYrBC,YAAYA;;;;;;;;;;iBAgBZC,YAAYA;cCxEfC,YAAYA;;;;;;;cAQZC,WAAWA;;;;;;;;;;;;;;;;;;;;;;;;;;;OCFXC,cAAcA;;;;;;;;;;;;;;;;OAuCdC,aAAaA;;;;;;;;;;;;;;;;;;;;OChCbC,SAASA;;;;;;;;;;;;;;;;;;;;;;;OCPTC,WAAWA;;;;;;;;;;;OCEXC,UAAUA;;;;;;;;;;;;;;;OCIVC,kBAAkBA;;;;;;;;;;;;;;;;;;;OCFlBC,IAAIA;;;;;;;;;;;;;;;;;;;;;;OCGJC,mBAAmBA;;;;;;;;;;;;;;;;;;;OCHnBC,YAAYA",
+	"mappings": ";;;;;;;;;;;;iBA6BgBA,UAAUA;;;;;;;;;;iBA+BVC,QAAQA;;;;;;;;;;;;;;;;iBCjDRC,eAAeA;;;;;;;;;;;;;;iBCEfC,WAAWA;;;;;;;;;cCFdC,oBAAoBA;;;;;;;;;;;;;;;;;;;;iBCMjBC,UAAUA;cAAVA,UAAUA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cCEbC,iBAAiBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cCZjBC,iBAAiBA;;;;;;;;;;;;;;;;;;;cCIjBC,oBAAoBA;;;;;;;iBCEjBC,gBAAgBA;;;;iBAShBC,SAASA;;;;;;iBAUTC,YAAYA;;;;;;;;iBAYZC,qBAAqBA;;;;;;iBAYrBC,YAAYA;;;;;;;;;;iBAgBZC,YAAYA;cCxEfC,YAAYA;;;;;;;cAQZC,WAAWA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OCDXC,cAAcA;;;;;;;;;;;;;;;;;;;;;;;OAgEdC,aAAaA;;;;;;;;;;;;;;;;;;;;OC1DbC,SAASA;;;;;;;;;;;;;;;;;;;;;;;OCPTC,WAAWA;;;;;;;;;;;OCEXC,UAAUA;;;;;;;;;;;;;;;OCIVC,kBAAkBA;;;;;;;;;;;;;;;;;;;OCFlBC,IAAIA;;;;;;;;;;;;;;;;;;;;;;OCGJC,mBAAmBA;;;;;;;;;;;;;;;;;;;OCHnBC,YAAYA",
 	"ignoreList": []
 }