KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#typescript #ai-agents #cli #claude-code #codex #developer-tools #ai #dsh-plugin #ai-agent #mcp #deepseek-harness #windows

zig-js

★ 28 Open GitHub ↗

A JavaScript engine in pure Zig.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# zig-js

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.

```zig
const js = @import("js");

const ctx = try js.Context.create(allocator);
defer ctx.destroy();

const value = try ctx.evaluate("let x = 40; x + 2");
```

## Status

| profile | result | evidence |
| --- | ---: | --- |
| configured test262 | **53,175 / 53,175** | [run](docs/.data/test262-run-2026-07-27.txt) · [data](docs/.data/test262.json) |
| ten-profile WebAssembly matrix | **151,802 / 151,802 applicable** | Core 3: 63,964/63,964 · [matrix](docs/.data/wasm-conformance-matrix.json) · [upstream-main shadow](docs/.data/wasm-core-main-shadow-inventory.json) · [reproduce](docs/wasm.md) |
| pinned private ABI | **Home 447/447 · Bun 437/437** | [inventories, provider audit, precise lifecycle, and exact reproduction](docs/abi/README.md) |

## Performance

### zig-js vs JavaScriptCore

Latest accepted [report](docs/.data/benchmark-comparison-2026-07-29-precise-nursery.md) · [1,540 raw samples](docs/.data/benchmark-comparison-2026-07-29-precise-nursery.tsv). 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.

### WebAssembly

- **SIMD:** 3.67–4.58x eight-lane scaling; 0.10–0.14x JSC throughput ([report](docs/.data/wasm-simd-benchmark-2026-07-18.md) · [samples](docs/.data/wasm-simd-benchmark-2026-07-18.tsv)).
- **Threads:** 17.23 M/s contended adds and 287,444 wait/notify handoffs/s at eight workers ([report](docs/.data/wasm-threads-benchmark-2026-07-18.md) · [samples](docs/.data/wasm-threads-benchmark-2026-07-18.tsv)).

### Garbage collection

- **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](docs/.data/gc-generation-2026-07-29.md) · [samples](docs/.data/gc-generation-2026-07-29.tsv)).


- **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](docs/.data/gc-compaction-2026-07-19.md) · [samples](docs/.data/gc-compaction-2026-07-19.tsv)).

Full methodology and results: [Performance benchmarks](docs/benchmarks.md).

## Use

`zig build` installs `libzig-js.a` and compatible headers under `zig-out/`. See the [Zig API](src/root.zig), [C API](docs/api.md), [timers](docs/timers.md), [WebAssembly and direct-chunk streaming compilation](docs/wasm.md), [threads/GC](docs/threads/index.md).

## Build And Test

Requires Zig 0.17.0-dev.

```sh
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.

## Documentation

- [Features](docs/features/index.md) — language, built-ins, Intl/Temporal, binary data, concurrency, WebAssembly.
- [Advanced](docs/advanced/index.md) — embedding, memory and GC, execution tiers, debugging, verification.
- [Architecture](docs/architecture.md) · [Conformance](docs/conformance.md) · [Benchmarks](docs/benchmarks.md) · [Threads](docs/threads/index.md)

## Contributing

See [CONTRIBUTING.md](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](CLAUDE.md) (symlinked as `AGENTS.md`).

The fail-closed [dependency ownership policy](docs/dependencies.md) classifies
local packages, platform interfaces, oracle-only tools/corpora, acquisition
inputs, and explicit migration targets. Validate it with
`zig build dependency-audit`.

## Community

For help, discussion about best practices, or any other conversation that would benefit from being searchable:

[Discussions on GitHub](https://github.com/zig-utils/zig-js/discussions)

For casual chit-chat with others using this package:

[Join the zig-utils Discord Server](https://discord.gg/f7wBym6JF2)

## License

MIT — see [LICENSE](LICENSE).

zig-js

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README