Rust crates

Overview

The bpmnkit-* crates are a Rust implementation of BPMN Kit’s core. They are the Rust twin of the TypeScript packages and are built next to them, not instead of them. JavaScript hosts (browser, Node, the editor) keep using @bpmnkit/*. Rust programs (CLIs, servers, the desktop app) use the crates natively, with no JS runtime.

The reebe engine (apps/reebe) runs on these crates. It parses BPMN and DMN and evaluates FEEL through them.

The bpmnkit crate is the front door: one dependency that re-exports the other crates as modules behind cargo features.

The guarantee

TypeScript is the oracle. About 3,300 conformance cases, recorded from the TypeScript packages and kept under conformance/ in the repository, must be reproduced exactly by the Rust crates. They cover models, serialized XML, lint findings, layout coordinates and FEEL results.

• CI runs the suite on every pull request.
• A nightly job fuzzes both implementations against each other and compares the answers (see Differential fuzzing).

Installation

cargo add bpmnkit                                    # feel, bpmn, dmn and form
cargo add bpmnkit --features full                    # every crate
cargo add bpmnkit --no-default-features --features feel   # FEEL only
cargo add bpmnkit --features lint,layout             # defaults plus lint and layout

Each crate is a module behind a feature of the same name (bpmnkit::feel, bpmnkit::bpmn, …). A feature turns on the crates it needs. For example text also builds bpmn, dmn and layout, but only the modules you name are re-exported.

You can also add a crate on its own, for example cargo add bpmnkit-feel. For a size-bound build (such as WebAssembly), depend on bpmnkit-feel or bpmnkit-dmn directly with default-features = false. That leaves out the IANA time zone table and the full regex engine.

Crates

Quick start

Parse and round-trip a BPMN file:

use bpmnkit::bpmn::{parse_bpmn, serialize_bpmn};

let xml = std::fs::read_to_string("order.bpmn")?;
let definitions = parse_bpmn(&xml)?;
println!("{} processes", definitions.processes.len());
// Unknown attributes, prefixes and extension elements survive the round trip.
std::fs::write("order.out.bpmn", serialize_bpmn(&definitions))?;

Evaluate FEEL:

use bpmnkit::feel::{evaluate, Context, Value};

let mut ctx = Context::new();
ctx.insert("x", Value::from(2));
assert_eq!(evaluate("x * 3 + 1", &ctx)?, Value::from(7));

Build a process (same output as Bpmn.createProcess in TypeScript). This needs the builder feature:

use bpmnkit::bpmn::serialize_bpmn;
use bpmnkit::builder::Bpmn;

let definitions = Bpmn::create_process("order")
    .start_event(Some("start"), None)
    .end_event(Some("end"), None)
    .build(None)?;
println!("{}", serialize_bpmn(&definitions));

Each crate’s README and its docs.rs page have more examples.

Performance vs TypeScript

The Rust crates are faster than the TypeScript packages in most areas, but not all. These figures are approximate. They were measured on a shared machine, as the minimum of interleaved runs over the conformance corpora, and they will vary with hardware and input. Treat them as an order of magnitude. The details and the bench commands are in the repository’s doc/progress.md.

Not everything is faster: DMN parsing is currently slower than TypeScript.

Requirements

• Rust 1.85 or later (MSRV). CI checks the crates on exactly that toolchain.
• Licence: MIT OR Apache-2.0.
• All crates share one version and are released together.

Where they are published

Releases go to crates.io. API docs are built on docs.rs. The source is in the crates/ directory of the repository.

How the Rust API maps to TypeScript

• One function or method per TS function, in snake_case: parseBpmn is parse_bpmn, applyAutoLayout is apply_auto_layout, .serviceTask() is .service_task().
• Option objects are structs that deserialize from the same camelCase JSON.
• Where TS throws, Rust returns Result with TS’s message. The builders keep the first error and return it from build().

Numbers

FEEL numbers are exact decimals in Rust (rust_decimal, 28 significant digits) and float64 in TypeScript. Results agree when compared to float64’s 15 significant digits: 0.1 + 0.2 is 0.3 in Rust and 0.30000000000000004 in TS. Beyond about 7.9 × 10²⁸ Rust has no number and returns null, where TS still has a (rounded) float. Values too small for 28 fraction digits round to 0 on both sides.

Differential fuzzing

crates/bpmnkit-fuzz generates random FEEL expressions, BPMN diagrams, DMN tables (parsed and evaluated), forms and process text, runs each through both implementations and compares the answers with the conformance suite’s rules. Disagreements are shrunk to a minimal input.

pnpm --filter @bpmnkit/feel --filter @bpmnkit/core --filter @bpmnkit/engine build
pnpm fuzz --target feel --seconds 300        # or --target all
pnpm fuzz --replay target/fuzz-mismatches/feel-42.json

Every real disagreement becomes a conformance case and a fix on both sides.

Versioning

The crates are versioned in lockstep, independently of the npm packages, and published manually from a GitHub workflow. Each release notes which @bpmnkit/core and @bpmnkit/feel versions its conformance corpus was recorded from.