Core engine and importable js module code are Zig; the static library exports JavaScriptCore-shaped C headers/symbols, with macOS Objective-C bridge glue in src/objc_bridge.m. The package depends on zig-regex and zig-gc, not bundled JSC/V8; system JavaScriptCore is used only by explicit differential and benchmark targets. APIs are pre-stabilization.
const js = @import("js"); const ctx = try js.Context.create(allocator); defer ctx.destroy(); const value = try ctx.evaluate("let x = 40; x + 2");
| profile | result | evidence |
|---|---|---|
| configured test262 | 53,175 / 53,175 | run · data |
| ten-profile WebAssembly matrix | 151,802 / 151,802 applicable | Core 3: 63,964/63,964 · matrix · upstream-main shadow · reproduce |
| pinned private ABI | Home 447/447 · Bun 437/437 | inventories, provider audit, precise lifecycle, and exact reproduction |
Latest accepted report · 1,540 raw samples. Equal-work checks, alternating order, dispersion limits, and a 50 ms timing floor are enforced by the harness.
| mode | lanes | wins vs JSC | zig-js / JSC throughput | zig-js scaling | JSC scaling |
|---|---|---|---|---|---|
| direct warmed context | 1 | 10 / 10 | 2.32x | — | — |
| independent steady contexts | 8 | 10 / 10 | 2.53x | 5.35x | 4.96x |
| independent cold lifecycles | 8 | 10 / 10 | 2.52x | 5.67x | 4.97x |
| shared realm, no GIL | 8 | no public-JSC equivalent | — | 4.84x | — |
Ratios above 1.00x favor zig-js. JSC has no public shared-realm embedding equivalent.
- SIMD: 3.67–4.58x eight-lane scaling; 0.10–0.14x JSC throughput (report · samples).
- Threads: 17.23 M/s contended adds and 287,444 wait/notify handoffs/s at eight workers (report · samples).
- Generational GC: moving age-three is 0.63–1.01x its exact non-moving parents and 0.84–1.02x moving age-one across accepted single-mutator rows; 480.42 MiB copied in the recorded moving age-three rows; shared no-GIL minor pause max 110.56 ms with 12 timeouts (report · samples).
- Explicit compaction: 90.8% less retained fragmented backing (8.81 → 0.81 MiB) with a 0.99 ms median pause and unchanged post-action throughput (report · samples).
Debug and dependency-level diagnostics measured on Apple M2 Pro with Zig 0.17.0-dev.1441. These are narrow controls, not engine/JSC scorecard rows:
| scope | result | evidence |
|---|---|---|
| repeated immutable RegExp compilation, fresh-literal replace | 186.58 → 12.78 MiB median peak footprint | dated report · 56 raw samples and corpus receipts |
| 32,768 distinct RegExp programs, construction / first match | 301.64 → 73.34 MiB / 531.52 → 108.28 MiB peak RSS | dated report · raw matrix and gate receipts |
| zig-regex bounded-repeat capture cost, four controls | 0.987–1.002× candidate / exact-parent elapsed time | dated report · 56 raw samples |
For the retention rows, lower means less retained memory: the #989 hoisted and unique-pattern controls and the #990 source-string control were unchanged at displayed precision. For the cost row, lower means less elapsed time. None is a general memory or speed claim.
Apple M2 Pro, Zig 0.17.0-dev.1770 Debug, default arena mode (GC off), seven alternating exact-parent pairs per workload. These measure whole-process CPU work, not production/JSC throughput:
| scope | median retired instructions | evidence |
|---|---|---|
| long strings with a sparse escape | 51.7% fewer; unescaped control -0.08% | report · raw samples |
| arrays of short integers | 27.5% fewer; fractional control +0.41% | report · raw samples |
The later production JSON/JIT pass uses ReleaseFast, the real precise collector, exact binaries and seven order-balanced pairs:
| scope | result | evidence |
|---|---|---|
| native-loop exact-parent A/B | String-length rows retire 6.74%/6.72% fewer instructions; guarded bit-and removes another 0.96%/0.53%; controls stay within ±0.11% | dated report · #1017 raw base · #1018 raw base |
| JIT versus required VM | 0.990x / 0.992x elapsed on the frozen base/variant, exact checksum |
report · 28 raw samples |
| current system-JSC diagnostic | JSC is 4.05x / 4.04x faster on the frozen base/variant; no parity claim |
report · 84 raw samples |
Full methodology and results: Performance benchmarks.
zig build installs libzig-js.a and compatible headers under zig-out/. See the Zig API, C API, timers, WebAssembly and direct-chunk streaming compilation, threads/GC.
Requires Zig 0.18.0-dev.
zig build # library and headers zig build test # main test root zig build test262 # configured tc39/test262 corpus zig build test-c-api # C and C++ embedding fixtures zig build benchmark-comparison # zig-js single/multithread vs JSC
Run zig build --help for the full command list.
- Features — language, built-ins, Intl/Temporal, binary data, concurrency, WebAssembly.
- Advanced — embedding, memory and GC, execution tiers, debugging, verification.
- Architecture · Conformance · Benchmarks · Threads
See CONTRIBUTING.md for toolchain setup and pinned zig-regex / zig-gc dependencies, how to run each suite, the CI gates, and the commit conventions. Coding agents should start from CLAUDE.md (symlinked as AGENTS.md).
The fail-closed dependency ownership policy classifies
local packages, platform interfaces, oracle-only tools/corpora, acquisition
inputs, and explicit migration targets. Validate it with
zig build dependency-audit.
For help, discussion about best practices, or any other conversation that would benefit from being searchable:
For casual chit-chat with others using this package:
Join the zig-utils Discord Server
MIT — see LICENSE.