@bpmnkit/core 0.1.2 → 0.2.0

package/dist/layout/semantic/route.js

@@ -13,6 +13,49 @@ const DETOUR_PENALTY = 0;
 const CORRIDOR_SPACING = 20;
 /** How many lanes deep a corridor may stack before routes are allowed to share. */
 const CORRIDOR_LANES = 4;
+/** Width of one bucket in the x-axis indexes below. */
+const INDEX_CELL = 128;
+/**
+ * Items bucketed by the x-range they cover, so a query for a segment's x-span
+ * visits only the shapes and routes near it instead of every one in the
+ * diagram. Orthogonal routes are mostly short, so this turns the per-edge
+ * obstacle and crossing checks from O(n) into near-constant work.
+ */
+class XIndex {
+    cells = new Map();
+    stamp = 0;
+    insert(minX, maxX, item) {
+        const entry = { item, stamp: 0 };
+        const lo = Math.floor(Math.min(minX, maxX) / INDEX_CELL);
+        const hi = Math.floor(Math.max(minX, maxX) / INDEX_CELL);
+        for (let c = lo; c <= hi; c++) {
+            const cell = this.cells.get(c);
+            if (cell)
+                cell.push(entry);
+            else
+                this.cells.set(c, [entry]);
+        }
+    }
+    /** Visit every item whose x-range may overlap [minX, maxX]; stop early when `visit` returns true. */
+    query(minX, maxX, visit) {
+        const stamp = ++this.stamp;
+        const lo = Math.floor(Math.min(minX, maxX) / INDEX_CELL);
+        const hi = Math.floor(Math.max(minX, maxX) / INDEX_CELL);
+        for (let c = lo; c <= hi; c++) {
+            const cell = this.cells.get(c);
+            if (!cell)
+                continue;
+            for (const entry of cell) {
+                if (entry.stamp === stamp)
+                    continue;
+                entry.stamp = stamp;
+                if (visit(entry.item))
+                    return true;
+            }
+        }
+        return false;
+    }
+}
 function centre(b) {
     return { x: b.x + b.width / 2, y: b.y + b.height / 2 };
 }
@@ -25,7 +68,17 @@ function centre(b) {
  * the empty gutter in front of the target's column as the general fallback.
  */
 export function routeFlows(graph, flows, bounds, bandLayout, gutterX) {
-    const ctx = { graph, bounds, gutterX, reserved: [], routed: [] };
+    const obstacles = new XIndex();
+    for (const [id, b] of bounds)
+        obstacles.insert(b.x, b.x + b.width, { id, b });
+    const ctx = {
+        graph,
+        bounds,
+        obstacles,
+        gutterX,
+        reserved: [],
+        routed: new XIndex(),
+    };
     const routed = new Map();
     const pending = [];
     for (const flow of flows) {
@@ -65,7 +118,7 @@ export function routeFlows(graph, flows, bounds, bandLayout, gutterX) {
         const around = detour(ctx, item.source, item.target, item.sourceRank, item.targetRank, item.below, item.flow.sourceRef, item.flow.targetRef);
         // Going around costs bends and length, so it has to save more than one
         // crossing to be worth taking.
-        const cost = crossingCount(around, ctx.routed) + DETOUR_PENALTY;
+        const cost = crossingCount(around, ctx) + DETOUR_PENALTY;
         const waypoints = item.direct && item.direct.crossings <= cost ? item.direct.waypoints : around;
         commit(ctx, routed, item.flow.id, waypoints);
     }
@@ -94,7 +147,7 @@ function commit(ctx, routed, id, waypoints) {
         const a = waypoints[i];
         const b = waypoints[i + 1];
         if (a && b)
-            ctx.routed.push([a, b]);
+            ctx.routed.insert(Math.min(a.x, b.x), Math.max(a.x, b.x), [a, b]);
     }
 }
 function hostOf(graph, eventId) {
@@ -106,18 +159,13 @@ function hostOf(graph, eventId) {
 }
 /** First candidate that crosses no shape other than its own endpoints. */
 function pick(candidates, ctx, sourceId, targetId) {
-    const obstacles = [];
-    for (const [id, b] of ctx.bounds) {
-        if (id === sourceId || id === targetId)
-            continue;
-        // An expanded container legitimately holds its children's routes.
-        obstacles.push(b);
-    }
     let best = null;
     for (const candidate of candidates) {
-        if (blocked(candidate, obstacles))
+        // An expanded container legitimately holds its children's routes, so only
+        // the two endpoints are exempt from the obstacle check.
+        if (blocked(ctx, candidate, sourceId, targetId))
             continue;
-        const crossings = crossingCount(candidate, ctx.routed);
+        const crossings = crossingCount(candidate, ctx);
         if (crossings === 0)
             return { waypoints: candidate, crossings };
         if (!best || crossings < best.crossings)
@@ -131,44 +179,59 @@ function intersects(p, q, r, t) {
     return side(p, q, r) !== side(p, q, t) && side(r, t, p) !== side(r, t, q);
 }
 /** How many already-routed edges a candidate would cut across. */
-function crossingCount(waypoints, routed) {
+function crossingCount(waypoints, ctx) {
     let count = 0;
     for (let i = 0; i + 1 < waypoints.length; i++) {
         const a = waypoints[i];
         const b = waypoints[i + 1];
         if (!a || !b)
             continue;
-        for (const [c, d] of routed)
+        ctx.routed.query(Math.min(a.x, b.x), Math.max(a.x, b.x), ([c, d]) => {
             if (intersects(a, b, c, d))
                 count++;
+            return false;
+        });
     }
     return count;
 }
-/** How many shapes a route passes through. */
-function hitCount(waypoints, obstacles) {
-    let count = 0;
-    for (const o of obstacles)
-        if (blocked(waypoints, [o]))
-            count++;
-    return count;
+/** True when the segment a→b passes through `o`, grazing allowed up to HIT_TOLERANCE. */
+function segmentHits(a, b, o) {
+    const minX = Math.min(a.x, b.x) + HIT_TOLERANCE;
+    const maxX = Math.max(a.x, b.x) - HIT_TOLERANCE;
+    const minY = Math.min(a.y, b.y) + HIT_TOLERANCE;
+    const maxY = Math.max(a.y, b.y) - HIT_TOLERANCE;
+    if (maxX <= o.x || o.x + o.width <= minX)
+        return false;
+    if (maxY <= o.y || o.y + o.height <= minY)
+        return false;
+    return true;
 }
-function blocked(waypoints, obstacles) {
+/** How many shapes a route passes through, its own endpoints excepted. */
+function hitCount(ctx, waypoints, sourceId, targetId) {
+    const hit = new Set();
     for (let i = 0; i + 1 < waypoints.length; i++) {
         const a = waypoints[i];
         const b = waypoints[i + 1];
         if (!a || !b)
             continue;
-        const minX = Math.min(a.x, b.x) + HIT_TOLERANCE;
-        const maxX = Math.max(a.x, b.x) - HIT_TOLERANCE;
-        const minY = Math.min(a.y, b.y) + HIT_TOLERANCE;
-        const maxY = Math.max(a.y, b.y) - HIT_TOLERANCE;
-        for (const o of obstacles) {
-            if (maxX <= o.x || o.x + o.width <= minX)
-                continue;
-            if (maxY <= o.y || o.y + o.height <= minY)
-                continue;
+        ctx.obstacles.query(Math.min(a.x, b.x), Math.max(a.x, b.x), (o) => {
+            if (o.id !== sourceId && o.id !== targetId && segmentHits(a, b, o.b))
+                hit.add(o);
+            return false;
+        });
+    }
+    return hit.size;
+}
+/** True when any segment of the route passes through a shape other than its endpoints. */
+function blocked(ctx, waypoints, sourceId, targetId) {
+    for (let i = 0; i + 1 < waypoints.length; i++) {
+        const a = waypoints[i];
+        const b = waypoints[i + 1];
+        if (!a || !b)
+            continue;
+        const hit = ctx.obstacles.query(Math.min(a.x, b.x), Math.max(a.x, b.x), (o) => o.id !== sourceId && o.id !== targetId && segmentHits(a, b, o.b));
+        if (hit)
             return true;
-        }
     }
     return false;
 }
@@ -310,7 +373,7 @@ isLoop = false, sourceId = "", targetId = "") {
             const crossings = crossingCount([
                 { x: left, y: option },
                 { x: right, y: option },
-            ], ctx.routed);
+            ], ctx);
             if (crossings < fewest) {
                 fewest = crossings;
                 base = option;
@@ -342,12 +405,8 @@ isLoop = false, sourceId = "", targetId = "") {
     if (chosen)
         return chosen.waypoints;
     // Neither is clear: keep whichever grazes fewer shapes.
-    const obstacles = [];
-    for (const [id, b] of ctx.bounds) {
-        if (id !== sourceId && id !== targetId)
-            obstacles.push(b);
-    }
-    return hitCount(straightOut, obstacles) <= hitCount(viaGutter, obstacles)
+    return hitCount(ctx, straightOut, sourceId, targetId) <=
+        hitCount(ctx, viaGutter, sourceId, targetId)
         ? straightOut
         : viaGutter;
 }
@@ -356,7 +415,7 @@ isLoop = false, sourceId = "", targetId = "") {
  * corridor is free, so two long routes stack instead of merging into one line.
  */
 function reserve(ctx, left, right, base, direction) {
-    const hitsShape = (candidate) => [...ctx.bounds.values()].some((b) => b.x + b.width > left &&
+    const hitsShape = (candidate) => ctx.obstacles.query(left, right, ({ b }) => b.x + b.width > left &&
         b.x < right &&
         b.y - HIT_TOLERANCE < candidate &&
         candidate < b.y + b.height + HIT_TOLERANCE);
@@ -389,11 +448,12 @@ floor,
 /** Only consider corridors above this line. */
 ceiling) {
     const spans = [];
-    for (const b of ctx.bounds.values()) {
+    ctx.obstacles.query(left, right, ({ b }) => {
         if (b.x + b.width > left && b.x < right) {
             spans.push([b.y - ROUTING_MARGIN, b.y + b.height + ROUTING_MARGIN]);
         }
-    }
+        return false;
+    });
     if (spans.length === 0)
         return preferredY;
     spans.sort((a, b) => a[0] - b[0]);

package/dist/node/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Node-only entry point.
+ *
+ * Everything here touches the filesystem, so it lives behind the
+ * `@bpmnkit/core/node` subpath. Importing `@bpmnkit/core` itself stays free of
+ * `node:` builtins and keeps working in browsers, workers and edge runtimes.
+ */
+export { writeBpmn } from "./write.js";
+export type { WriteBpmnOptions, WriteBpmnResult } from "./write.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/node/index.js

@@ -0,0 +1,9 @@
+/**
+ * Node-only entry point.
+ *
+ * Everything here touches the filesystem, so it lives behind the
+ * `@bpmnkit/core/node` subpath. Importing `@bpmnkit/core` itself stays free of
+ * `node:` builtins and keeps working in browsers, workers and edge runtimes.
+ */
+export { writeBpmn } from "./write.js";
+//# sourceMappingURL=index.js.map

package/dist/node/write.d.ts

@@ -0,0 +1,81 @@
+import type { BpmnDefinitions } from "../bpmn/bpmn-model.js";
+import { type SemanticDiff } from "../bpmn/semantic-hash.js";
+/**
+ * The only place in this package that writes a BPMN file, and the only one that
+ * checks what it wrote.
+ *
+ * Node-only — it is reached through the `@bpmnkit/core/node` subpath so that
+ * importing `@bpmnkit/core` in a browser never pulls `node:fs` in.
+ *
+ * **What the verification does and does not cover.** Before anything reaches
+ * disk, the model is serialised, parsed back, and the two semantic hashes are
+ * compared. That catches the serialiser dropping or mangling something. It
+ * cannot catch the *parser* dropping something on the way in: content the
+ * parser never saw is absent from both sides and the hashes agree. Guarding
+ * that is the round-trip corpus gate's job (`tests/roundtrip-corpus.test.ts`),
+ * not this function's.
+ *
+ * There is deliberately no option to skip verification. Turning it off would
+ * only ever be used to get past the bug it exists to report; callers who want
+ * unchecked serialisation can still use `Bpmn.export()` and write it
+ * themselves.
+ */
+export interface WriteBpmnOptions {
+    /** Path to write to. */
+    output: string;
+    /**
+     * Replace `output` if it already exists. Default `false`, which refuses
+     * rather than overwrite.
+     */
+    force?: boolean;
+    /**
+     * `"preserve"` (default) writes the diagram the model already carries.
+     * `"auto"` regenerates it first — the model is unchanged either way, which
+     * the verification step proves.
+     */
+    layout?: "preserve" | "auto";
+}
+export interface WriteBpmnResult {
+    /** Absolute path written. */
+    destination: string;
+    /** Size of the written file in bytes. */
+    bytes: number;
+    /** SHA-256 of the exact bytes written. */
+    outputSha256: string;
+    /** Semantic hash of the model, as verified after reading it back. */
+    semanticHash: string;
+    /**
+     * What this write changed about the file that was already there, or
+     * `undefined` when the destination was newly created or the previous
+     * contents could not be parsed.
+     */
+    changes?: SemanticDiff;
+}
+/**
+ * Serialises a model, verifies it survives a round trip, and writes it
+ * atomically.
+ *
+ * The file appears complete or not at all: the contents go to a temporary file
+ * in the destination's own directory and are then renamed into place, so an
+ * interrupted write cannot leave a half-written model behind. Without `force`
+ * the final step is a hard link, which fails if the destination appeared in the
+ * meantime rather than silently replacing it.
+ *
+ * @param definitions - The model to write.
+ * @param options - Destination and write behaviour.
+ * @returns Where it went, what it hashes to, and what it changed.
+ * @throws {WriteVerificationError} If reading the output back does not
+ *   reproduce the model. Nothing is written.
+ * @throws {WriteError} If the destination exists and `force` was not given, or
+ *   the filesystem refused the write.
+ *
+ * @example
+ * ```typescript
+ * import { writeBpmn } from "@bpmnkit/core/node"
+ *
+ * const result = await writeBpmn(definitions, { output: "flow.bpmn" })
+ * console.log(result.semanticHash, result.changes?.changed.length ?? 0)
+ * ```
+ */
+export declare function writeBpmn(definitions: BpmnDefinitions, options: WriteBpmnOptions): Promise<WriteBpmnResult>;
+//# sourceMappingURL=write.d.ts.map

package/dist/node/write.js

@@ -0,0 +1,167 @@
+import { randomUUID } from "node:crypto";
+import { chmod, link, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import { basename, dirname, resolve } from "node:path";
+import { applyAutoLayout } from "../bpmn/auto-layout.js";
+import { parseBpmn } from "../bpmn/bpmn-parser.js";
+import { serializeBpmn } from "../bpmn/bpmn-serializer.js";
+import { diffSemantics, semanticHash } from "../bpmn/semantic-hash.js";
+import { sha256Hex } from "../bpmn/sha256.js";
+import { WriteError, WriteVerificationError } from "../errors.js";
+async function pathExists(path) {
+    try {
+        await stat(path);
+        return true;
+    }
+    catch (error) {
+        if (isErrnoCode(error, "ENOENT"))
+            return false;
+        throw error;
+    }
+}
+function isErrnoCode(error, code) {
+    return error instanceof Error && "code" in error && error.code === code;
+}
+/** Codes returned by filesystems that cannot make a hard link. */
+const NO_HARD_LINKS = new Set(["ENOTSUP", "EOPNOTSUPP", "EPERM", "EXDEV", "EMLINK"]);
+/**
+ * Serialises a model, verifies it survives a round trip, and writes it
+ * atomically.
+ *
+ * The file appears complete or not at all: the contents go to a temporary file
+ * in the destination's own directory and are then renamed into place, so an
+ * interrupted write cannot leave a half-written model behind. Without `force`
+ * the final step is a hard link, which fails if the destination appeared in the
+ * meantime rather than silently replacing it.
+ *
+ * @param definitions - The model to write.
+ * @param options - Destination and write behaviour.
+ * @returns Where it went, what it hashes to, and what it changed.
+ * @throws {WriteVerificationError} If reading the output back does not
+ *   reproduce the model. Nothing is written.
+ * @throws {WriteError} If the destination exists and `force` was not given, or
+ *   the filesystem refused the write.
+ *
+ * @example
+ * ```typescript
+ * import { writeBpmn } from "@bpmnkit/core/node"
+ *
+ * const result = await writeBpmn(definitions, { output: "flow.bpmn" })
+ * console.log(result.semanticHash, result.changes?.changed.length ?? 0)
+ * ```
+ */
+export async function writeBpmn(definitions, options) {
+    const destination = resolve(options.output);
+    const force = options.force === true;
+    const exists = await pathExists(destination);
+    // Fail before doing the work, not after it.
+    if (exists && !force) {
+        throw new WriteError(`Refusing to overwrite ${options.output}. Pass force: true to replace it.`);
+    }
+    // applyAutoLayout returns a new model, so the caller's stays untouched.
+    const model = options.layout === "auto" ? applyAutoLayout(definitions) : definitions;
+    const expected = semanticHash(model);
+    const xml = serializeBpmn(model);
+    let reparsed;
+    try {
+        reparsed = parseBpmn(xml);
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        throw new WriteVerificationError(`Serialising the model produced BPMN that cannot be parsed back: ${reason}`, { added: [], removed: [], changed: [] });
+    }
+    const actual = semanticHash(reparsed);
+    if (actual !== expected) {
+        const changes = diffSemantics(model, reparsed);
+        throw new WriteVerificationError([
+            "Serialising the model did not reproduce it, so nothing was written.",
+            `Lost: ${changes.removed.join(", ") || "none"}.`,
+            `Added: ${changes.added.join(", ") || "none"}.`,
+            `Altered: ${changes.changed.map((entry) => entry.id).join(", ") || "none"}.`,
+        ].join(" "), changes);
+    }
+    const changes = exists ? await changesAgainst(destination, reparsed) : undefined;
+    await writeAtomically(destination, xml, force);
+    return {
+        destination,
+        bytes: Buffer.byteLength(xml, "utf-8"),
+        outputSha256: sha256Hex(xml),
+        semanticHash: actual,
+        changes,
+    };
+}
+/**
+ * Diffs the model about to be written against the one already on disk. A
+ * previous file that cannot be read or parsed yields no report rather than
+ * failing the write — the old contents are being replaced either way.
+ */
+async function changesAgainst(destination, next) {
+    try {
+        return diffSemantics(parseBpmn(await readFile(destination, "utf-8")), next);
+    }
+    catch {
+        return undefined;
+    }
+}
+async function writeAtomically(destination, contents, force) {
+    const temporary = resolve(dirname(destination), `.${basename(destination)}.${randomUUID()}.tmp`);
+    try {
+        await writeFile(temporary, contents, { encoding: "utf-8", flag: "wx" });
+        if (force) {
+            // Keep the permissions the file already had; a rename would otherwise
+            // hand it whatever the temporary file was created with.
+            const mode = await modeOf(destination);
+            if (mode !== undefined)
+                await chmod(temporary, mode);
+            await rename(temporary, destination);
+            return;
+        }
+        await linkOrCreateExclusively(temporary, destination, contents);
+    }
+    catch (error) {
+        if (error instanceof WriteError)
+            throw error;
+        if (isErrnoCode(error, "EEXIST")) {
+            throw new WriteError(`Refusing to overwrite ${destination}: it appeared while writing. Pass force: true to replace it.`);
+        }
+        const reason = error instanceof Error ? error.message : String(error);
+        throw new WriteError(`Unable to write ${destination}: ${reason}`);
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+}
+/**
+ * Creates the destination without replacing anything. `link` fails with EEXIST
+ * if the destination is taken, which `rename` would not, and it publishes the
+ * already-complete temporary file in one step.
+ *
+ * Filesystems without hard links fall back to an exclusive create, which is
+ * still safe against replacing an existing file but writes in place rather than
+ * atomically — an interrupted write there can leave a partial file.
+ */
+async function linkOrCreateExclusively(temporary, destination, contents) {
+    try {
+        await link(temporary, destination);
+    }
+    catch (error) {
+        if (!isErrnoCode(error, "EEXIST") && isNoHardLinkSupport(error)) {
+            await writeFile(destination, contents, { encoding: "utf-8", flag: "wx" });
+            return;
+        }
+        throw error;
+    }
+}
+function isNoHardLinkSupport(error) {
+    return (error instanceof Error &&
+        "code" in error &&
+        NO_HARD_LINKS.has(error.code ?? ""));
+}
+async function modeOf(path) {
+    try {
+        return (await stat(path)).mode;
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=write.js.map

package/dist/types/id-generator.js

@@ -1,12 +1,20 @@
 const ALPHABET = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789";
 const ID_SIZE = 8;
+// Random bytes are drawn in batches: one getRandomValues call per id is
+// dominated by the crypto call overhead, not by the bytes it returns.
+const POOL_SIZE = 1024;
+const pool = new Uint8Array(POOL_SIZE);
+let poolOffset = POOL_SIZE;
 function nanoId() {
-    const bytes = new Uint8Array(ID_SIZE);
-    crypto.getRandomValues(bytes);
+    if (poolOffset + ID_SIZE > POOL_SIZE) {
+        crypto.getRandomValues(pool);
+        poolOffset = 0;
+    }
     let id = "";
     for (let i = 0; i < ID_SIZE; i++) {
-        id += ALPHABET[bytes[i] % ALPHABET.length];
+        id += ALPHABET[pool[poolOffset + i] % ALPHABET.length];
     }
+    poolOffset += ID_SIZE;
     return id;
 }
 // Counter used only in deterministic test mode (activated by resetIdCounter())

package/dist/xml/index.d.ts

@@ -1,2 +1,4 @@
-export { parseXml, serializeXml } from "./xml-parser.js";
+export { parseXml, scanXml, serializeXml } from "./xml-parser.js";
+export { Visit } from "./xml-parser.js";
+export type { XmlSink } from "./xml-parser.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/xml/index.js

@@ -1,2 +1,3 @@
-export { parseXml, serializeXml } from "./xml-parser.js";
+export { parseXml, scanXml, serializeXml } from "./xml-parser.js";
+export { Visit } from "./xml-parser.js";
 //# sourceMappingURL=index.js.map

package/dist/xml/xml-parser.d.ts

@@ -1,4 +1,36 @@
 import type { XmlElement } from "../types/xml-element.js";
+/** What a sink wants the scanner to do with an element after its start tag. */
+export declare const Visit: {
+    /** Report child elements and character data. */
+    readonly All: 0;
+    /**
+     * Skip the element's content: the scanner fast-forwards past the matching
+     * end tag without building attributes or decoding text for anything inside,
+     * and `end` is not called for it.
+     */
+    readonly Skip: 1;
+    /** Report child elements but drop character data without decoding it. */
+    readonly ElementsOnly: 2;
+};
+export type Visit = (typeof Visit)[keyof typeof Visit];
+/** Receives the events of one XML document from {@link scanXml}. */
+export interface XmlSink {
+    /**
+     * @param name qualified name, e.g. "bpmn:task"
+     * @param local name without its prefix, e.g. "task" (same string as `name` when unprefixed)
+     * @param selfClosing true for `<a/>`; `end` follows immediately
+     */
+    start(name: string, local: string, attributes: Record<string, string>, selfClosing: boolean): Visit;
+    /** Character data or CDATA directly inside the current element, entities decoded. */
+    text(text: string): void;
+    end(name: string): void;
+}
+/**
+ * Scan an XML document, reporting the root element and everything inside it to
+ * `sink`. Returns false when the document has no root element. Content after
+ * the root element is ignored.
+ */
+export declare function scanXml(xml: string, sink: XmlSink): boolean;
 /**
  * Parse an XML string into an XmlElement tree.
  * Returns the root element with all namespace prefixes preserved.