chore: upgrade to Zig 0.16.0 by lodekeeper-z · Pull Request #9 · ChainSafe/zapi

lodekeeper-z · 2026-03-19T19:14:37Z

Upgrade to Zig 0.16.0-dev (master) — part of the lodestar-z Zig master upgrade effort.

Key changes:

std.io → std.Io migration
std.Io.Dir methods now require explicit io parameter
Build system changes for 0.16 compatibility

🤖 Generated with AI assistance

- Remove usingnamespace (removed in 0.15): c.zig now exports cImport as .c field - All imports updated: @import("c.zig") → @import("c.zig").c - callconv(.C) → callconv(.c) (lowercase) - napi module requires link_libc = true for @cImport - Example disabled (TODO: std.time.Timer/sleep moved to std.Io) 🤖 Generated with AI assistance

wemeetagain · 2026-03-23T19:45:30Z

@lodekeeper-z please refresh this PR based on the latest main branch

…ersion) 🤖 Generated with AI assistance

…r callbacks) Updates examples to match new wrap() signature from ChainSafe#10 (added ref parameter). 🤖 Generated with AI assistance

lodekeeper-z · 2026-03-25T02:24:16Z

Refreshed against latest main — merged in #10 (Ref refactor), #8 (raw variant functions), and #5 (safer callbacks). Updated the type_tag and hello_world examples to match the new wrap() signature (added ref parameter).

Note: the type_tag example has a linker issue (undefined NAPI symbols) that's pre-existing from upstream — it was introduced when #7 and #10 were merged without updating the example's wrap() call site. Our branch now fixes that compilation error, but the example still can't link standalone (needs to run as a Node addon).

nazarhussain · 2026-03-26T20:32:59Z

@lodekeeper-z please refresh this PR based on the latest main branch

🤖 Generated with AI assistance

lodekeeper-z · 2026-03-26T20:37:31Z

Refreshed — merged latest main (napi→zapi rename, CI workflows, type_tag example). hello_world example is still TODO due to std.time.Timer/std.Io migration in 0.16.

lodekeeper-z · 2026-03-26T20:37:35Z

Refreshed — merged latest main (napi→zapi rename, CI workflows, type_tag example). hello_world example is still TODO due to std.time.Timer/std.Io migration in 0.16.

- Replace std.time.Timer with local Timer using std.c.clock_gettime - Replace std.time.sleep with std.c.nanosleep - Restore hello_world module, library, and test in build.zig - Fix b.modules.put to use b.allocator (Zig 0.16 API change) - Update minimum_zig_version to 0.16.0 - Update CI setup-env to use Zig 0.16.0 - Remove duplicate .zig-cache/ in .gitignore

Replace std.c.clock_gettime/nanosleep with std.Io.Timestamp and std.Io.sleep, using Io.Threaded.init_single_threaded for the Io instance in the NAPI callback context.

Remove module-level var and getIo() helper. Use the stdlib-provided global_single_threaded instance directly.

Per Zig author recommendation, prefer explicit one-time initialization over global_single_threaded for dynamically-loaded NAPI libraries.

The custom Timer struct was an unnecessary wrapper around Io.Timestamp. Use Io.Timestamp directly in the NAPI callbacks.

Copilot

Pull request overview

Upgrades this Zig N-API wrapper to be compatible with Zig 0.16, including updates to C interop patterns, C ABI callconv annotations, and build/CI configuration. Also updates the hello_world example to use std.Io APIs in place of std.time.

Changes:

Switch C imports to @import("c.zig").c and update c.zig to expose pub const c = @cImport(...).
Replace callconv(.C) with callconv(.c) for C ABI callbacks.
Bump Zig toolchain requirements (build.zig.zon + GitHub Action) and adjust build script for Zig 0.16 API changes; update examples to std.Io.

Reviewed changes

Copilot reviewed 25 out of 26 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
src/value_types.zig	Update C import access via `.c`.
src/threadsafe_function.zig	Update C import access and C callconv to `.c`.
src/status.zig	Update C import access via `.c`.
src/root.zig	Re-export `c` as the `@cImport` result (`.c`).
src/module.zig	Update C import access and C callconv to `.c` for exported registration function.
src/finalize_callback.zig	Update C import access and finalize callback callconv to `.c`.
src/cleanup_hook.zig	Update C import access and hook callback callconv to `.c`.
src/callback_info.zig	Update C import access via `.c`.
src/callback.zig	Update C import access and callback callconv to `.c`.
src/c.zig	Change from `usingnamespace @cImport` to `pub const c = @cImport(...)`.
src/async_work.zig	Update C import access and async callbacks callconv to `.c`.
src/async_cleanup_hook.zig	Update C import access and cleanup hook callconv to `.c`.
src/args.zig	Update C import access via `.c`.
src/Value.zig	Update C import access via `.c`.
src/Ref.zig	Update C import access via `.c`.
src/NodeVersion.zig	Update C import access via `.c`.
src/HandleScope.zig	Update C import access via `.c`.
src/EscapableHandleScope.zig	Update C import access via `.c`.
src/Env.zig	Update C import access via `.c`.
src/Deferred.zig	Update C import access via `.c`.
src/AsyncContext.zig	Update C import access via `.c`.
examples/hello_world/mod.zig	Migrate time usage to `std.Io` (`Io.Timestamp`, `io().sleep`).
build.zig.zon	Bump `.minimum_zig_version` to 0.16.0.
build.zig	Update build definitions for Zig 0.16 (modules map API + link_libc for zapi module).
.gitignore	Ignore `zig-pkg/` directory.
.github/actions/setup-env/action.yml	Pin CI Zig version to 0.16.0.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Example modules reference NAPI symbols that are only available at runtime via Node.js. Running them as standalone zig tests causes linker errors. Keep them as individual test steps (test:example_hello_world, test:example_type_tag) but exclude from the global `zig build test`.

- Remove stale "generated by zbuild" comment from build.zig.zon - Update zbuild.zon minimum_zig_version to 0.16.0 - Add link_libc to zapi module in zbuild.zon for consistency with build.zig

Each thread (main, libuv worker, spawned) gets its own init_single_threaded instance, which is correct since init_single_threaded has no synchronization.

build.zig and build.zig.zon are generated by zbuild — keep the header so manual edits don't get silently overwritten on regeneration.

zapi only uses @cImport for NAPI C headers (stddef.h, stdint.h) which Zig provides natively. link_libc is only needed by the example dynamic libraries that load into Node.js at runtime.

Copilot

Pull request overview

Copilot reviewed 26 out of 27 changed files in this pull request and generated 2 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-04-17T07:23:20Z


    const run_test_example_hello_world = b.addRunArtifact(test_example_hello_world);
    const tls_run_test_example_hello_world = b.step("test:example_hello_world", "Run the example_hello_world test");
    tls_run_test_example_hello_world.dependOn(&run_test_example_hello_world.step);


The aggregate test step (tls_run_test) no longer depends on this example’s test run artifact, so zig build test will skip example_hello_world unless the dedicated test:example_hello_world step is invoked. Re-add tls_run_test.dependOn(&run_test_example_hello_world.step) so the top-level test step runs this test too.

Suggested change

tls_run_test_example_hello_world.dependOn(&run_test_example_hello_world.step);

tls_run_test_example_hello_world.dependOn(&run_test_example_hello_world.step);

tls_run_test.dependOn(&run_test_example_hello_world.step);

Copilot · 2026-04-17T07:23:21Z


    const run_test_example_type_tag = b.addRunArtifact(test_example_type_tag);
    const tls_run_test_example_type_tag = b.step("test:example_type_tag", "Run the example_type_tag test");
    tls_run_test_example_type_tag.dependOn(&run_test_example_type_tag.step);


The aggregate test step (tls_run_test) no longer depends on this example’s test run artifact, so zig build test will skip example_type_tag unless the dedicated test:example_type_tag step is invoked. Re-add tls_run_test.dependOn(&run_test_example_type_tag.step) so the top-level test step runs this test too.

Suggested change

tls_run_test_example_type_tag.dependOn(&run_test_example_type_tag.step);

tls_run_test_example_type_tag.dependOn(&run_test_example_type_tag.step);

tls_run_test.dependOn(&run_test_example_type_tag.step);

The threadlocal `init_single_threaded` instance was defensively scoped per thread on the theory that cross-thread sharing of a single-threaded Threaded could race. In practice stdlib already provides `std.Io.Threaded.global_single_threaded` for exactly this scenario: > In some cases such as debugging, it is desirable to hardcode a > reference to this `Io` implementation. It's a single process-wide instance, and — importantly — the only ops this example uses (`Timestamp.now`, `random`, etc.) bottom out in OS calls that don't touch the `Threaded` struct's internal mutable state, so one shared instance is safe for this use case. This removes the `threadlocal var` declaration entirely, matching the stdlib-recommended pattern for examples.

GrapeBaBa · 2026-04-20T12:52:17Z

@copilot resolve the merge conflicts in this pull request

# Conflicts: # .gitignore # src/root.zig

Four of the five Zig-0.16-upgrade PRs on our dependency forks have merged into ChainSafe upstream main: * ChainSafe/blst.zig#4 → 6ad139a * ChainSafe/hashtree-z#10 → 56e406f * ChainSafe/snappy.zig#5 → 7139424 * ChainSafe/zig-yaml#1 → b74f4e8 Switch from `lodekeeper-z/<repo>?ref=chore/zig-master` to the merged commit on `ChainSafe/<repo>` main for each. Content is identical so the existing `hash` fields stay valid. `zapi` (ChainSafe/zapi#9) is still open upstream — bump the `lodekeeper-z/zapi` commit pointer to the current PR head (fefb88ebf5c9) which includes the latest port/refactor work; TODO note to switch to ChainSafe/zapi once ChainSafe#9 merges.

The merge with main brought in the js_dsl feature (ChainSafe#11) and a refactor of `src/root.zig` (napi symbols moved to `src/napi.zig`, re-exported via `pub usingnamespace`). All of that was written for 0.14.1 and hits several 0.16 breaking changes: * `b.modules.put(key, value)` → `b.modules.put(allocator, key, value)`. Two call sites in `build.zig` were missed by the previous update pass (the `napi` module and the `example_js_dsl` module). * `src/napi.zig` exported `pub const c = @import("c.zig")`, but every internal file accesses napi types through the inner `.c` namespace. Restore the `.c` on the import. * `pub usingnamespace` was removed in Zig 0.16. Replace it in `src/root.zig` with explicit `pub const foo = napi.foo;` re-exports. * `callconv(.C)` → `callconv(.c)` (6 NAPI callback shims in `src/js/wrap_class.zig` and `src/js/wrap_function.zig`). * `std.Thread.Mutex` → `std.Io.Mutex`. The DSL's per-class registry in `src/js/class_runtime.zig` needs a 0.16-compatible mutex, which requires an `Io`. The `Io` is threaded in through the DSL's entry point rather than letting zapi carry global state: - `js.exportModule` gains an optional `.io = fn () std.Io` field in `options`. The generated `moduleInit` calls it after the user's `options.init` hook and passes the result down into `registerDecls` → `class_runtime.registerClass`. If `.io` is omitted, a DSL-local `init_single_threaded` fallback keeps zero-config modules compiling. - `registerClass` caches the resolved `Io` in per-`T` `state(T).io`; `getConstructor`, `materializeClassInstance`, and `cleanupHook` all read from this cache because they execute inside napi C callbacks that can't receive user-provided `Io`. - Normal paths (`registerClass`, `getConstructor`) use cancelable `try mutex.lock(io)` so caller cancellation can propagate. - `cleanupHook` (a napi C callback with a fixed `(*Entry)` signature that cannot return errors) uses `lockUncancelable` deliberately — unwinding on cancel would leak the entry and hand napi a dangling pointer. * `Env` gains a `fromRaw(raw_env)` constructor so the 19 napi C callback sites don't all hand-roll the `Env{ .env = ... }` literal. `Env` itself stays a pure `napi_env` wrapper — no `io` field. After this commit `zig build` succeeds, and `zig build test` runs the 42 regular tests green. `example_js_dsl` has a separate, pre-existing link issue in `zig build test` (undefined `_napi_wrap` and friends, resolved by Node at runtime when loading the `.node` file) — orthogonal to the 0.16 migration.

GrapeBaBa · 2026-04-21T10:09:14Z

@wemeetagain @nazarhussain @spiral-ladder need to check if current approach is good for injecting IO

nazarhussain

From the DSL point of view, let me rethink why we need io for a comptime layer. The only usage we have for class constructor list, might be avoided with some other pattern. I will get back to it.

nazarhussain · 2026-04-22T10:41:41Z

    const has_init = @hasField(@TypeOf(options), "init");
    const has_cleanup = @hasField(@TypeOf(options), "cleanup");
    const has_register = @hasField(@TypeOf(options), "register");
+    const has_io = @hasField(@TypeOf(options), "io");


As it's changing the public facing API, so should be considered a breaking change. Let's add a ! in PR title so release-please can handle rest.

nazarhussain · 2026-04-22T10:42:50Z

 /// ```zig
 /// comptime {
 ///     // Basic export of all `pub` functions, classes, and sub-namespaces
 ///     js.exportModule(@This());


We need to update all the examples, as io is a required attribute now.

nazarhussain · 2026-04-22T10:43:39Z

 /// The DSL internally manages an atomic refcount for module instances across
 /// different N-API environments.
 ///
 /// Usage Examples:


Along with these examples, need to update the examples in README as well.

nazarhussain · 2026-04-22T12:45:15Z

@GrapeBaBa @wemeetagain With this PR merged we will not have io dependency in the DSL, so no change would be needed.
#20

lodekeeper-z mentioned this pull request Mar 19, 2026

chore: upgrade to Zig 0.16.0-dev (master) ChainSafe/lodestar-z#252

Draft

wemeetagain marked this pull request as ready for review March 19, 2026 19:59

wemeetagain marked this pull request as draft March 19, 2026 19:59

lodekeeper-z added 3 commits March 23, 2026 21:12

chore: merge upstream main (type-tag-aware unwrap, safer integer conv…

a236788

…ersion) 🤖 Generated with AI assistance

Merge remote-tracking branch 'upstream/main' into chore/zig-master

650da13

chore: merge upstream main (Ref refactor, raw variant functions, safe…

880afd6

…r callbacks) Updates examples to match new wrap() signature from ChainSafe#10 (added ref parameter). 🤖 Generated with AI assistance

chore: merge upstream main (napi→zapi rename, CI, hello_world example)

0f6d617

🤖 Generated with AI assistance

GrapeBaBa added 5 commits April 17, 2026 10:09

refactor(examples): use std.Io instead of libc for timer and sleep

a5f5711

Replace std.c.clock_gettime/nanosleep with std.Io.Timestamp and std.Io.sleep, using Io.Threaded.init_single_threaded for the Io instance in the NAPI callback context.

refactor(examples): use Io.Threaded.global_single_threaded

24bb6d5

Remove module-level var and getIo() helper. Use the stdlib-provided global_single_threaded instance directly.

refactor(examples): use explicit Io.Threaded init instead of global

3272eb2

Per Zig author recommendation, prefer explicit one-time initialization over global_single_threaded for dynamically-loaded NAPI libraries.

refactor(examples): remove Timer wrapper, use Io.Timestamp directly

6face6a

The custom Timer struct was an unnecessary wrapper around Io.Timestamp. Use Io.Timestamp directly in the NAPI callbacks.

GrapeBaBa marked this pull request as ready for review April 17, 2026 05:00

Copilot AI review requested due to automatic review settings April 17, 2026 05:00

Copilot started reviewing on behalf of GrapeBaBa April 17, 2026 05:00 View session

Copilot AI reviewed Apr 17, 2026

View reviewed changes

Comment thread build.zig.zon

Comment thread build.zig

Comment thread .github/actions/setup-env/action.yml

Comment thread examples/hello_world/mod.zig Outdated

Comment thread build.zig

GrapeBaBa changed the title ~~chore: upgrade to Zig 0.16.0-dev (master)~~ chore: upgrade to Zig 0.16.0 Apr 17, 2026

GrapeBaBa added 5 commits April 17, 2026 13:14

fix: address PR review comments

91fca03

- Remove stale "generated by zbuild" comment from build.zig.zon - Update zbuild.zon minimum_zig_version to 0.16.0 - Add link_libc to zapi module in zbuild.zon for consistency with build.zig

fix: use threadlocal for Io.Threaded to avoid cross-thread sharing

05b18eb

Each thread (main, libuv worker, spawned) gets its own init_single_threaded instance, which is correct since init_single_threaded has no synchronization.

fix: restore zbuild generated-file headers

f18aab2

build.zig and build.zig.zon are generated by zbuild — keep the header so manual edits don't get silently overwritten on regeneration.

fix: remove unnecessary link_libc from zapi module

ef82c4c

zapi only uses @cImport for NAPI C headers (stddef.h, stdint.h) which Zig provides natively. link_libc is only needed by the example dynamic libraries that load into Node.js at runtime.

GrapeBaBa requested review from nazarhussain and wemeetagain April 17, 2026 07:10

GrapeBaBa requested review from Copilot and spiral-ladder April 17, 2026 07:10

Copilot started reviewing on behalf of GrapeBaBa April 17, 2026 07:20 View session

Copilot AI reviewed Apr 17, 2026

View reviewed changes

GrapeBaBa mentioned this pull request Apr 20, 2026

chore: upgrade to Zig 0.16 ChainSafe/lodestar-z#319

Open

Merge remote-tracking branch 'upstream/main' into chore/zig-master

a0312a4

# Conflicts: # .gitignore # src/root.zig

GrapeBaBa force-pushed the chore/zig-master branch 14 times, most recently from 4ccc9d8 to fefb88e Compare April 21, 2026 05:06

GrapeBaBa force-pushed the chore/zig-master branch from fefb88e to 76dae72 Compare April 21, 2026 06:46

nazarhussain requested changes Apr 22, 2026

View reviewed changes

nazarhussain mentioned this pull request Apr 22, 2026

fix: remove mutex/io dependency from the dsl #20

Open

	tls_run_test_example_hello_world.dependOn(&run_test_example_hello_world.step);
	tls_run_test_example_hello_world.dependOn(&run_test_example_hello_world.step);
	tls_run_test.dependOn(&run_test_example_hello_world.step);

	tls_run_test_example_type_tag.dependOn(&run_test_example_type_tag.step);
	tls_run_test_example_type_tag.dependOn(&run_test_example_type_tag.step);
	tls_run_test.dependOn(&run_test_example_type_tag.step);

Conversation

lodekeeper-z commented Mar 19, 2026

Uh oh!

wemeetagain commented Mar 23, 2026

Uh oh!

lodekeeper-z commented Mar 25, 2026

Uh oh!

nazarhussain commented Mar 26, 2026

Uh oh!

lodekeeper-z commented Mar 26, 2026

Uh oh!

lodekeeper-z commented Mar 26, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Apr 17, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 17, 2026

Choose a reason for hiding this comment

Uh oh!

GrapeBaBa commented Apr 20, 2026

Uh oh!

GrapeBaBa commented Apr 21, 2026

Uh oh!

nazarhussain left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nazarhussain Apr 22, 2026

Choose a reason for hiding this comment

Uh oh!

nazarhussain Apr 22, 2026

Choose a reason for hiding this comment

Uh oh!

nazarhussain Apr 22, 2026

Choose a reason for hiding this comment

Uh oh!

nazarhussain commented Apr 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

nazarhussain left a comment •

edited

Loading

nazarhussain commented Apr 22, 2026 •

edited

Loading