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).
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.17.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 JSCRun 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 (including the sibling zig-regex / zig-gc checkouts), 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.