@nanobpm/workflow 0.8.2 → 0.9.0

package/dist/test-support/xml.js

@@ -0,0 +1,135 @@
+// A dependency-free XML reader, just enough to parse a BPMN 2.0 document into a
+// tree the normalizer can canonicalize. BPMN files this package emits (and the
+// hand-authored goldens) are plain XML — elements, attributes, text — with no
+// DTDs, processing instructions beyond the `<?xml …?>` prolog, or mixed-content
+// subtleties that would need a full parser. We keep prefixed names verbatim
+// (`bpmn:serviceTask`, `zeebe:taskDefinition`) so the normalizer can reason about
+// namespaces by local name.
+/** The local (un-prefixed) name of an element or attribute. */
+export function localName(qualified) {
+    const i = qualified.indexOf(":");
+    return i === -1 ? qualified : qualified.slice(i + 1);
+}
+function decodeEntities(s) {
+    return s.replace(/&(#x?[0-9a-fA-F]+|[a-zA-Z]+);/g, (m, body) => {
+        switch (body) {
+            case "lt":
+                return "<";
+            case "gt":
+                return ">";
+            case "amp":
+                return "&";
+            case "quot":
+                return '"';
+            case "apos":
+                return "'";
+        }
+        if (body[0] === "#") {
+            const code = body[1] === "x" || body[1] === "X" ? Number.parseInt(body.slice(2), 16) : Number.parseInt(body.slice(1), 10);
+            // Only decode a valid Unicode scalar value. `String.fromCodePoint` throws
+            // a `RangeError` for code points outside 0..0x10FFFF (e.g. `&#x110000;`),
+            // and surrogate halves (0xD800..0xDFFF) are not valid characters — treat
+            // any such reference as malformed and leave it verbatim rather than
+            // throwing an opaque exception out of `parseXml`.
+            const isScalar = Number.isInteger(code) && code >= 0 && code <= 0x10ffff && !(code >= 0xd800 && code <= 0xdfff);
+            return isScalar ? String.fromCodePoint(code) : m;
+        }
+        return m;
+    });
+}
+function parseAttrs(src) {
+    const attrs = {};
+    const re = /([^\s=/]+)\s*=\s*("([^"]*)"|'([^']*)')/g;
+    let m = re.exec(src);
+    while (m !== null) {
+        const value = m[3] !== undefined ? m[3] : (m[4] ?? "");
+        attrs[m[1]] = decodeEntities(value);
+        m = re.exec(src);
+    }
+    return attrs;
+}
+function appendText(el, chunk) {
+    if (chunk)
+        el.text = el.text ? `${el.text} ${chunk}` : chunk;
+}
+/** Parse an XML document into its root element. Throws on a malformed document
+ *  (unbalanced tags, no root, or more than one top-level element). Comments,
+ *  CDATA, the `<?xml?>` prolog and other processing instructions are handled;
+ *  CDATA content contributes to `text`. */
+export function parseXml(xml) {
+    const root = { name: "#root", attrs: {}, children: [], text: "" };
+    const stack = [root];
+    let i = 0;
+    const n = xml.length;
+    while (i < n) {
+        const lt = xml.indexOf("<", i);
+        if (lt === -1)
+            break;
+        if (lt > i)
+            appendText(stack[stack.length - 1], decodeEntities(xml.slice(i, lt)).trim());
+        if (xml.startsWith("<!--", lt)) {
+            const end = xml.indexOf("-->", lt + 4);
+            if (end === -1)
+                throw new Error("parseXml: unterminated comment");
+            i = end + 3;
+            continue;
+        }
+        if (xml.startsWith("<![CDATA[", lt)) {
+            const end = xml.indexOf("]]>", lt + 9);
+            if (end === -1)
+                throw new Error("parseXml: unterminated CDATA");
+            appendText(stack[stack.length - 1], xml.slice(lt + 9, end).trim());
+            i = end + 3;
+            continue;
+        }
+        if (xml.startsWith("<?", lt) || xml.startsWith("<!", lt)) {
+            const end = xml.indexOf(">", lt + 2);
+            if (end === -1)
+                throw new Error("parseXml: unterminated processing instruction / declaration");
+            i = end + 1;
+            continue;
+        }
+        const gt = xml.indexOf(">", lt);
+        if (gt === -1)
+            throw new Error("parseXml: unterminated tag");
+        let inner = xml.slice(lt + 1, gt);
+        if (inner.startsWith("/")) {
+            const closeName = inner.slice(1).trim();
+            if (stack.length <= 1)
+                throw new Error(`parseXml: unbalanced end tag </${closeName}>`);
+            const open = stack.pop();
+            if (open === undefined || open.name !== closeName) {
+                throw new Error(`parseXml: mismatched end tag </${closeName}> (expected </${open?.name ?? "#root"}>)`);
+            }
+            i = gt + 1;
+            continue;
+        }
+        const selfClosing = inner.endsWith("/");
+        if (selfClosing)
+            inner = inner.slice(0, -1);
+        const nameMatch = /^\s*(\S+)/.exec(inner);
+        if (!nameMatch)
+            throw new Error("parseXml: malformed start tag");
+        const name = nameMatch[1];
+        const attrs = parseAttrs(inner.slice(nameMatch[0].length));
+        const el = { name, attrs, children: [], text: "" };
+        stack[stack.length - 1].children.push(el);
+        if (!selfClosing)
+            stack.push(el);
+        i = gt + 1;
+    }
+    if (stack.length !== 1) {
+        const unclosed = stack
+            .slice(1)
+            .map((el) => `<${el.name}>`)
+            .join(", ");
+        throw new Error(`parseXml: unclosed tag(s): ${unclosed}`);
+    }
+    if (root.children.length === 0)
+        throw new Error("parseXml: no root element");
+    if (root.children.length > 1) {
+        const roots = root.children.map((el) => `<${el.name}>`).join(", ");
+        throw new Error(`parseXml: multiple root elements (${roots}) — a well-formed document has exactly one`);
+    }
+    return root.children[0];
+}

package/dist/types.d.ts

@@ -37,62 +37,26 @@ export type FlowContracts = Record<string, StepContract>;
 export type StepHandler<V extends JsonObject = JsonObject, R extends JsonObject = JsonObject> = {
     bivarianceHack(job: Job<V>): Promise<R | void> | R | void;
 }["bivarianceHack"];
-/** A node in a declarative flow tree. Leaf activities carry optional data
- *  envelopes (lifted to `nano:shape` + `dataEnvelope` in the model); structural
- *  combinators carry nested `FlowNode[]` bodies. */
-export type FlowNode = {
-    kind: "run";
-    name: string;
-    envelopes?: NodeEnvelopes;
-} | {
-    kind: "task";
-    name: string;
-    envelopes?: NodeEnvelopes;
-    jobType?: string;
-} | {
-    kind: "signal";
-    name: string;
-    correlationKey: string;
-    payload?: Envelope;
-} | ({
-    kind: "timer";
-    name: string;
-} & TimerAt) | {
-    kind: "switch";
-    subject: string;
-    cases: SwitchCase[];
-    default?: FlowNode[];
-} | {
-    kind: "branch";
-    condition: string;
-    then: FlowNode[];
-    else?: FlowNode[];
-} | {
-    kind: "loop";
-    body: FlowNode[];
-} | {
-    kind: "break";
-} | {
-    kind: "continue";
-} | {
-    kind: "parallel";
-    branches: FlowNode[][];
-} | {
-    kind: "forEach";
-    /** FEEL expression evaluating to the list to fan out over. */
-    collection: string;
-    /** Variable each item is bound to in the child's scope (`inputElement`). */
-    itemVar: string;
-    body: FlowNode[];
-    /** Run children one at a time (sequential MI) instead of all at once. */
-    sequential?: boolean;
-    /** List variable that each child's `outputElement` is collected into. */
-    outputCollection?: string;
-    /** FEEL expression producing each child's contribution to `outputCollection`. */
-    outputElement?: string;
-    /** FEEL boolean that, once true, completes the body early. */
-    completionCondition?: string;
-};
+/** The OPEN registry of flow-node kinds — the single extension seam for the
+ *  `FlowNode` union (epic #314, S0/#315). Each kind module under `src/nodes/`
+ *  declaration-merges ONE property into this interface (`kindName: NodeShape`),
+ *  so `FlowNode` grows without editing a central union here. The built-in kinds
+ *  register `run`/`task`/`signal`/`timer`/`switch`/`branch`/`loop`/`break`/
+ *  `continue`/`parallel`/`forEach` from their own modules through this same
+ *  mechanism — see `src/nodes/README.md`.
+ *
+ *  Invariant: every value type MUST be an object with a `kind` discriminant
+ *  equal to its key, so `FlowNode` stays a discriminated union.
+ *
+ *  This interface is intentionally empty here: it is the augmentation target the
+ *  per-kind modules declaration-merge their variant into. */
+export interface FlowNodeRegistry {
+}
+/** A node in a declarative flow tree, derived from the {@link FlowNodeRegistry}.
+ *  Leaf activities carry optional data envelopes (lifted to `nano:shape` +
+ *  `dataEnvelope` in the model); structural combinators carry nested
+ *  `FlowNode[]` bodies. */
+export type FlowNode = FlowNodeRegistry[keyof FlowNodeRegistry];
 /** A timer intermediate-catch definition: exactly one of `after` (an ISO-8601
  *  delay or FEEL expression) or `at` (an absolute instant or FEEL expression).
  *  Encoded as an XOR so downstream consumers can rely on exactly-one. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/workflow",
-  "version": "0.8.2",
+  "version": "0.9.0",
   "description": "Code-first durable orchestration for nanobpmn (ADR 0044/0045). Author a durable workflow as a declarative flow — `defineFlow(id, w => { w.run(...); w.signal(...); w.task(...) })` — and the SDK derives the executable BPMN model, the job types, and the message/correlation wiring, then hosts a generic worker. `w.run` is a local step, `w.signal` is a durable human-in-the-loop wait, `w.task` is a step serviced by an external worker. `defineFlow` is the single code-first surface; the imperative `defineWorkflow` replay function is experimental/internal, not a recommended API. No diagram, no task-type wiring, no correlation plumbing authored by hand — and you can optionally auto-generate a diagram (DI) for the derived model with `declarativeToLayoutedBpmn` via the optional `bpmn-auto-layout` peer dependency. Talks to a running nanobpmn gateway through @nanobpm/nano-sdk (the shared engine-transport spine — ADR 0055), which negotiates the Falcon protocol on a Nano server and REST elsewhere.",
   "type": "module",
   "license": "Apache-2.0",
@@ -17,6 +17,10 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
+    "./test-support": {
+      "types": "./dist/test-support/index.d.ts",
+      "default": "./dist/test-support/index.js"
+    },
     "./source": "./src/index.ts"
   },
   "files": [
@@ -26,13 +30,17 @@
   "engines": {
     "node": ">=22.6"
   },
-  "sideEffects": false,
+  "sideEffects": [
+    "./dist/nodes/*.js",
+    "./src/nodes/*.ts"
+  ],
   "dependencies": {
     "@nanobpm/nano-sdk": "^1.2.5"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.types.json",
+    "gen:nodes": "node scripts/gen-node-registry.mjs",
+    "build": "npm run gen:nodes && tsc -p tsconfig.json",
+    "typecheck": "npm run gen:nodes && tsc -p tsconfig.json --noEmit && tsc -p tsconfig.types.json",
     "test": "npm run build && npm run test:ci",
     "test:ci": "node --experimental-strip-types --test test/*.test.ts",
     "test:integration": "node --experimental-strip-types --test test/integration.test.ts",