Twilic Benchmark

TypeScript benchmark harness for @twilic/core (twilic/runtimes/javascript local package).

Setup

bun install

@twilic/core is consumed from ../twilic/runtimes/javascript via a local file dependency. If the native/WASM artifacts are stale, rebuild it first:

bun --cwd ../twilic/runtimes/javascript run build

Run benchmark

bun run bench
bun run bench:msgpack
bun run bench:max

Optional flags:

• --backend napi|wasm (default: napi)
• --time-ms <number> (default: 1000)
• --warmup-ms <number> (default: 250)
• --mode full|max (default: full)
• --twilic-vs-msgpack-only (hide JSON rows and JSON benchmark tasks)

Examples:

bun run bench -- --backend napi
bun run bench -- --twilic-vs-msgpack-only
bun run bench -- --mode max --backend napi
bun run bench -- --backend wasm --time-ms 2000 --warmup-ms 500

What is measured

• Twilic encode/decode for a single record
• Twilic encode/decode for a 256-record batch
• MessagePack encode/decode baselines for single and batched payloads
• Twilic session patch encode (encodePatch)
• Raw transport-json fast path (encodeTransportJson, encodeBatchTransportJson, decodeToTransportJson)
• JSON stringify/parse baseline for a comparable payload
• Encoded payload size comparison (twilic vs MessagePack vs CBOR vs BSON vs JSON)
• Schema-shared size comparison (BOUND_STREAM / SCHEMA_BATCH vs Protobuf vs Avro raw streams)
• Pretty CLI tables for size and throughput output (cli-table3)

The schema comparison uses the same 256 UserRecord values for all formats. Schemas are assumed to be shared out of band, so Avro object-container headers and Protobuf length-prefix framing are deliberately excluded. Twilic measures encodeBoundStream and encodeBatchWithSchema (not per-message encodeWithSchema).

Pinned website numbers live in results/pinned-snapshot.json. Regenerate with:

bun run bench -- --backend napi --time-ms 1500 --warmup-ms 500 --json-out results/pinned-snapshot.json

Max speed tips

• Use --backend napi on Node.js
• Prefer Node.js 24+ (project baseline)
• Increase run windows for stability (--time-ms 3000 --warmup-ms 1000)
• For hot paths, pre-serialize once with transport-json APIs and use raw encode methods