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.16x | — | — |
| independent steady contexts | 8 | 9 / 10 | 1.79x | 3.86x | 4.73x |
| independent cold lifecycles | 8 | 9 / 10 | 1.95x | 4.04x | 4.75x |
| shared realm, no GIL | 8 | no public-JSC equivalent | — | 3.85x | — |
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: age-three policy is 0.96–1.01x the age-one control across accepted single-mutator rows; shared no-GIL minor pause max 0.39 ms with 0 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.
- PR-249 reference tail: 3 files remain blocked on shell/JIT evidence; 6 JSC-private or incompatible premises have terminal dispositions (inventory · scan).
- Open release gates: automatic shared/mid-script compaction evidence; moving nursery for the multi-age GC; optimizing-JIT backend/differential evidence (matrix).
The release matrix tracks #134; removal of this section is gated by #246.
- 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).
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.