zignapi 0.1.0

package/README.md

@@ -0,0 +1,37 @@
+# zignapi
+
+The CLI for [zigbind](https://github.com/zigbind/zigbind): scaffold and build
+native Node.js addons written in Zig. Written in TypeScript, compiled to ESM with
+**zero runtime dependencies**, no `node-gyp`. Requires **Zig 0.16.0** on `PATH`
+and **Node >= 18**.
+
+```sh
+npm install -g zignapi   # installs the `zignapi` command
+```
+
+## Commands
+
+```sh
+zignapi new <name>          # scaffold ./<name> from the built-in template
+zignapi build [--release]   # run `zig build` in the cwd, emit ./<name>.node
+```
+
+- `new` copies the template tree (substituting the project name) and pins the
+  `zigbind` Zig dependency with `zig fetch --save`.
+- `build` runs `zig build` (adding `-Doptimize=ReleaseFast` with `--release`),
+  then copies the produced shared library to `./<name>.node`. If `build.zig.zon`
+  is missing a fingerprint, it fills in the value Zig suggests and retries.
+
+## Development
+
+The source is TypeScript under `src/` and compiles to `dist/` with `tsc`.
+TypeScript is a **workspace-root** devDependency (not installed in this package),
+so build through the workspace:
+
+```sh
+pnpm install                 # the root `prepare` script compiles the CLI
+pnpm --filter zignapi build  # or rebuild explicitly (runs tsc)
+```
+
+The `bin` points at the compiled `dist/cli.js`; the published package ships
+`dist/`, `templates/`, and a bundled copy of the Zig `native/` sources.

package/dist/build.js

@@ -0,0 +1,82 @@
+import { parseArgs } from "node:util";
+import { existsSync, copyFileSync, readdirSync } from "node:fs";
+import { join, basename, extname } from "node:path";
+import process from "node:process";
+import { runZig } from "./zig.js";
+const BUILD_HELP = `zignapi build — build the addon in the current directory
+
+Usage:
+  zignapi build [--release]
+
+Options:
+  --release   Optimize the build (-Doptimize=ReleaseFast)
+  -h, --help  Show this help
+
+Runs "zig build" in the current directory, then copies the resulting shared
+library to ./<name>.node (renaming a plain .dylib/.so/.dll if needed).
+`;
+export async function runBuild(argv) {
+    const { values } = parseArgs({
+        args: argv,
+        options: {
+            release: { type: "boolean", default: false },
+            help: { type: "boolean", short: "h", default: false },
+        },
+    });
+    if (values.help) {
+        process.stdout.write(BUILD_HELP);
+        return;
+    }
+    const cwd = process.cwd();
+    if (!existsSync(join(cwd, "build.zig"))) {
+        throw new Error("no build.zig found in the current directory");
+    }
+    const zigArgs = ["build"];
+    if (values.release)
+        zigArgs.push("-Doptimize=ReleaseFast");
+    runZig(cwd, zigArgs, { repairZon: join(cwd, "build.zig.zon") });
+    // Locate the freshly built addon and copy it to ./<name>.node.
+    const addon = findAddon(join(cwd, "zig-out"));
+    if (!addon) {
+        throw new Error("build succeeded but no addon (.node or shared library) was found under zig-out");
+    }
+    const dest = join(cwd, addonName(addon));
+    copyFileSync(addon, dest);
+    process.stdout.write(`✔ built ${basename(dest)}\n`);
+}
+/**
+ * Find the built addon under zig-out. Prefers an already-named `.node`,
+ * falling back to the first shared library it finds.
+ */
+function findAddon(dir) {
+    const nodes = [];
+    const libs = [];
+    const walk = (d) => {
+        if (!existsSync(d))
+            return;
+        for (const entry of readdirSync(d, { withFileTypes: true })) {
+            const p = join(d, entry.name);
+            if (entry.isDirectory()) {
+                walk(p);
+            }
+            else if (entry.isFile()) {
+                if (entry.name.endsWith(".node"))
+                    nodes.push(p);
+                else if (/\.(dylib|so|dll)$/.test(entry.name))
+                    libs.push(p);
+            }
+        }
+    };
+    walk(dir);
+    return nodes[0] ?? libs[0] ?? null;
+}
+/** The `<name>.node` filename to copy an addon to at the project root. */
+function addonName(addon) {
+    if (extname(addon) === ".node")
+        return basename(addon);
+    // libfoo.dylib -> foo.node
+    let name = basename(addon, extname(addon));
+    if (name.startsWith("lib"))
+        name = name.slice(3);
+    return `${name}.node`;
+}

package/dist/cli.js

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+import process from "node:process";
+import { runNew } from "./new.js";
+import { runBuild } from "./build.js";
+const HELP = `zignapi — write native Node.js addons in Zig
+
+Usage:
+  zignapi new <name>          Scaffold a new addon project into ./<name>
+  zignapi build [--release]   Build the addon in the current directory
+  zignapi --help              Show this help
+
+Run "zignapi <command> --help" for command-specific options.
+`;
+async function main() {
+    const [command, ...rest] = process.argv.slice(2);
+    switch (command) {
+        case "new":
+            return runNew(rest);
+        case "build":
+            return runBuild(rest);
+        case "-h":
+        case "--help":
+        case undefined:
+            process.stdout.write(HELP);
+            return;
+        default:
+            process.stderr.write(`zignapi: unknown command '${command}'\n\n${HELP}`);
+            process.exitCode = 1;
+    }
+}
+main().catch((err) => {
+    const message = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`zignapi: ${message}\n`);
+    process.exitCode = 1;
+});

package/dist/new.js

@@ -0,0 +1,118 @@
+import { parseArgs } from "node:util";
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import process from "node:process";
+import { releaseUrl, resolveZigbindSources, runZig } from "./zig.js";
+// The template tree lives at the package root (as `templates/`), so it resolves
+// the same whether we run from the compiled `dist/` or the source `src/`.
+const TEMPLATES_DIR = join(dirname(fileURLToPath(import.meta.url)), "..", "templates");
+const PLACEHOLDER = /__NAME__/g;
+const NEW_HELP = `zignapi new — scaffold a new addon project
+
+Usage:
+  zignapi new <name> [--local]
+
+Creates ./<name> from the built-in template, substituting the project name,
+then wires up the zigbind Zig dependency with "zig fetch --save" (pinned by
+content hash). By default it fetches the hosted release tarball, so the project
+is portable across machines/CI; if that's unreachable it falls back to the Zig
+sources bundled with the CLI.
+
+Options:
+  --local     Use the bundled Zig sources instead of the hosted release
+  -h, --help  Show this help
+
+<name> must be a valid Zig identifier (letters, digits, underscore; not
+starting with a digit).
+`;
+export async function runNew(argv) {
+    const { values, positionals } = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            local: { type: "boolean", default: false },
+            help: { type: "boolean", short: "h", default: false },
+        },
+    });
+    if (values.help || positionals.length === 0) {
+        process.stdout.write(NEW_HELP);
+        return;
+    }
+    const name = positionals[0];
+    validateName(name);
+    const target = join(process.cwd(), name);
+    if (existsSync(target)) {
+        throw new Error(`directory '${name}' already exists`);
+    }
+    copyTemplate(TEMPLATES_DIR, target, name);
+    addZigbindDependency(target, { local: values.local ?? false });
+    process.stdout.write(`✔ created ${name}/\n\n` +
+        `Next steps:\n` +
+        `  cd ${name}\n` +
+        `  zignapi build      # produces ${name}.node\n` +
+        `  node --test\n`);
+}
+/**
+ * Add the `zigbind` Zig dependency to the freshly scaffolded project via
+ * `zig fetch --save`, pinning it by content hash. Prefers the hosted release
+ * tarball (portable across machines) and falls back to the Zig sources bundled
+ * with the CLI if that's unreachable or `local` is set. Non-fatal: if Zig isn't
+ * available at all, tell the user how to finish the wiring later.
+ */
+function addZigbindDependency(target, { local }) {
+    const repairZon = join(target, "build.zig.zon");
+    if (!local) {
+        const url = releaseUrl();
+        try {
+            runZig(target, ["fetch", "--save=zigbind", url], { repairZon });
+            process.stdout.write(`✔ added zigbind dependency from ${url}\n`);
+            return;
+        }
+        catch (err) {
+            process.stderr.write(`note: could not fetch the hosted zigbind release (${errMessage(err)}); ` +
+                `falling back to the bundled sources.\n`);
+        }
+    }
+    let sources;
+    try {
+        sources = resolveZigbindSources();
+        runZig(target, ["fetch", "--save=zigbind", sources], { repairZon });
+        process.stdout.write("✔ added zigbind dependency from bundled sources\n");
+    }
+    catch (err) {
+        process.stderr.write(`warning: could not add the zigbind dependency automatically ` +
+            `(${errMessage(err)}).\nRun this inside the project once Zig 0.16.0 is ` +
+            `available:\n  zig fetch --save=zigbind ${sources ?? releaseUrl()}\n`);
+    }
+}
+/**
+ * Recursively copy the template tree, substituting the project name in both
+ * file contents and file/directory names. `dot-` prefixed template names are
+ * emitted as dotfiles (so e.g. `dot-gitignore` becomes `.gitignore`), which
+ * also sidesteps npm's habit of renaming a packaged `.gitignore`.
+ */
+function copyTemplate(srcDir, destDir, name) {
+    mkdirSync(destDir, { recursive: true });
+    for (const entry of readdirSync(srcDir, { withFileTypes: true })) {
+        const outName = entry.name.replace(PLACEHOLDER, name).replace(/^dot-/, ".");
+        const src = join(srcDir, entry.name);
+        const dest = join(destDir, outName);
+        if (entry.isDirectory()) {
+            copyTemplate(src, dest, name);
+        }
+        else {
+            const content = readFileSync(src, "utf8").replace(PLACEHOLDER, name);
+            writeFileSync(dest, content);
+        }
+    }
+}
+function validateName(name) {
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) {
+        throw new Error(`invalid project name '${name}' (use letters, digits and underscores; ` +
+            `must not start with a digit)`);
+    }
+}
+function errMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}

package/dist/zig.js

@@ -0,0 +1,80 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import process from "node:process";
+// From the compiled entry (dist/zig.js) or the source (src/zig.ts), one level
+// up is the package root.
+const PKG_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+/**
+ * The hosted release tarball of the zigbind Zig package, used as the default
+ * (portable, shareable) dependency source. Overridable via ZIGBIND_RELEASE_URL
+ * — handy for testing against a local `file://` tarball or a mirror. The
+ * version is taken from this CLI's package.json and must match the release tag.
+ */
+export function releaseUrl() {
+    const override = process.env.ZIGBIND_RELEASE_URL;
+    if (override)
+        return override;
+    const pkg = JSON.parse(readFileSync(join(PKG_ROOT, "package.json"), "utf8"));
+    const v = pkg.version;
+    return `https://github.com/zigbind/zigbind/releases/download/v${v}/zigbind-${v}.tar.gz`;
+}
+/**
+ * Locate the zigbind Zig sources (the `native/` directory) that ship with this
+ * CLI. Works both from the published npm package (bundled at `<pkg>/native`)
+ * and from the monorepo checkout (`packages/zigbind` -> `../../native`).
+ */
+export function resolveZigbindSources() {
+    const candidates = [
+        join(PKG_ROOT, "native"), // bundled inside the published package
+        join(PKG_ROOT, "..", "..", "native"), // monorepo layout
+    ];
+    for (const dir of candidates) {
+        if (existsSync(join(dir, "build.zig.zon")))
+            return dir;
+    }
+    throw new Error("could not locate the zigbind Zig sources (native/) shipped with the CLI");
+}
+/**
+ * Run `zig` with the given args in `cwd`. If the run fails because
+ * `build.zig.zon` is missing/has an invalid fingerprint and `repairZon` is
+ * given, patch in the value Zig suggests and retry once. On success, forwards
+ * zig's output; on failure, forwards it and throws.
+ */
+export function runZig(cwd, args, { repairZon } = {}) {
+    let res = spawnSync("zig", args, { cwd, encoding: "utf8" });
+    if (res.error) {
+        if (res.error.code === "ENOENT") {
+            throw new Error("could not find `zig` on PATH (Zig 0.16.0 is required)");
+        }
+        throw res.error;
+    }
+    if (res.status !== 0 && repairZon) {
+        const suggested = (res.stderr ?? "").match(/(?:suggested value|use this value): (0x[0-9a-fA-F]+)/);
+        if (suggested) {
+            patchFingerprint(repairZon, suggested[1]);
+            res = spawnSync("zig", args, { cwd, encoding: "utf8" });
+        }
+    }
+    process.stdout.write(res.stdout ?? "");
+    process.stderr.write(res.stderr ?? "");
+    if (res.status !== 0) {
+        throw new Error(`zig ${args[0] ?? ""} failed`);
+    }
+    return res;
+}
+/** Insert or replace the `.fingerprint` field in a build.zig.zon. */
+export function patchFingerprint(zonPath, value) {
+    if (!existsSync(zonPath))
+        return;
+    let src = readFileSync(zonPath, "utf8");
+    if (/\.fingerprint\s*=\s*0x[0-9a-fA-F]+/.test(src)) {
+        src = src.replace(/\.fingerprint\s*=\s*0x[0-9a-fA-F]+/, `.fingerprint = ${value}`);
+    }
+    else {
+        // Insert right after the `.name = ...,` line.
+        src = src.replace(/(\.name\s*=\s*[^\n]*,\n)/, `$1    .fingerprint = ${value},\n`);
+    }
+    writeFileSync(zonPath, src);
+}

package/native/build.zig

@@ -0,0 +1,58 @@
+const std = @import("std");
+
+/// Build script for the `zigbind` Zig library.
+///
+/// This is a Zig package, not an npm package. Its main product is the Zig
+/// module named "zigbind" (exposed via `b.addModule`), which addons import to
+/// register their functions with Node. Building here also runs two local
+/// checks so `zig build` in this directory validates the library on its own:
+///
+///   - a compile check (`src/_check.zig` built as an object) that exercises the
+///     full comptime pipeline for every supported type, and
+///   - `zig build test`, the pure-comptime unit tests in `src/convert.zig`.
+pub fn build(b: *std.Build) void {
+    const target = b.standardTargetOptions(.{});
+    const optimize = b.standardOptimizeOption(.{});
+
+    const headers = b.path("vendor/node-api-headers");
+
+    // The module consumers import as `@import("zigbind")`. It links libc (for
+    // the C allocator used to marshal string arguments, and to make the N-API
+    // headers available to `@cImport`). Target/optimize are left unset here so
+    // each consumer picks them; the include path travels with the module.
+    const mod = b.addModule("zigbind", .{
+        .root_source_file = b.path("src/zigbind.zig"),
+        .link_libc = true,
+    });
+    mod.addIncludePath(headers);
+
+    // Standalone compile check. Built as an object, so the still-undefined
+    // N-API symbols are fine (they resolve when a real addon links). Failing
+    // to compile any of the conversion/registration code fails `zig build`.
+    const check_mod = b.createModule(.{
+        .root_source_file = b.path("src/_check.zig"),
+        .target = target,
+        .optimize = optimize,
+        .link_libc = true,
+    });
+    check_mod.addIncludePath(headers);
+    const check_obj = b.addObject(.{
+        .name = "zigbind-check",
+        .root_module = check_mod,
+    });
+    b.getInstallStep().dependOn(&check_obj.step);
+
+    // Unit tests: only the pure-comptime conversions (no N-API runtime calls),
+    // so the test binary links without Node present.
+    const tests_mod = b.createModule(.{
+        .root_source_file = b.path("src/convert.zig"),
+        .target = target,
+        .optimize = optimize,
+        .link_libc = true,
+    });
+    tests_mod.addIncludePath(headers);
+    const unit_tests = b.addTest(.{ .root_module = tests_mod });
+    const run_tests = b.addRunArtifact(unit_tests);
+    const test_step = b.step("test", "Run zigbind unit tests");
+    test_step.dependOn(&run_tests.step);
+}

package/native/build.zig.zon

@@ -0,0 +1,13 @@
+.{
+    .name = .zigbind,
+    .version = "0.1.0",
+    .fingerprint = 0xb615899b08c4e528, // Changing this has security and trust implications.
+    .minimum_zig_version = "0.16.0",
+    .dependencies = .{},
+    .paths = .{
+        "build.zig",
+        "build.zig.zon",
+        "src",
+        "vendor",
+    },
+}

package/native/src/_check.zig

@@ -0,0 +1,45 @@
+//! Build-only compile check (never shipped to consumers, not imported by
+//! `zigbind.zig`). Building this as an *object* forces the whole comptime
+//! pipeline — `register` → the per-function callback trampolines → `convert`
+//! for every supported type, including an error union — to be analyzed, so
+//! `zig build` in `native/` fails loudly on any API or type mistake. The
+//! N-API symbols it references stay undefined in the object file; they are
+//! resolved when a real addon links, exactly as in production.
+
+const zigbind = @import("zigbind.zig");
+const napi = zigbind.napi;
+
+// Reference the concrete (non-generic) wrappers so they are compiled too.
+comptime {
+    _ = napi.check;
+    _ = napi.throwError;
+    _ = napi.getCallbackInfo;
+    _ = napi.setNamedProperty;
+    _ = napi.createFunction;
+}
+
+fn add(a: i32, b: i32) i32 {
+    return a + b;
+}
+fn negate(x: bool) bool {
+    return !x;
+}
+fn scale(x: f64) f64 {
+    return x * 2.0;
+}
+fn echo(s: []const u8) []const u8 {
+    return s;
+}
+fn checked(x: i32) !i32 {
+    return if (x < 0) error.MustBeNonNegative else x;
+}
+
+comptime {
+    zigbind.register(.{
+        .add = add,
+        .negate = negate,
+        .scale = scale,
+        .echo = echo,
+        .checked = checked,
+    });
+}

package/native/src/async.zig

@@ -0,0 +1,15 @@
+//! Async support — stub.
+//!
+//! TODO: wrap `napi_create_async_work` / `napi_queue_async_work` so that Zig
+//! functions returning something awaitable (or explicitly marked async) run on
+//! libuv's thread pool and resolve a JS `Promise` via `napi_create_promise` /
+//! `napi_resolve_deferred`. Nothing here is wired into `register.zig` yet;
+//! today every exported function runs synchronously on the JS thread.
+
+const std = @import("std");
+
+comptime {
+    // Keep this file referenced so it participates in compilation checks even
+    // while it is only a placeholder.
+    std.debug.assert(true);
+}

package/native/src/convert.zig

@@ -0,0 +1,119 @@
+//! Comptime conversions between Zig values and JavaScript values.
+//!
+//! Every function is generic over the Zig type and dispatches on `@typeInfo`
+//! at comptime, so a wrapper compiled for `fn (i32, i32) i32` only ever emits
+//! the `int32` code paths. Supported types: `i32`/`u32`/`i64`/... (any int),
+//! `f16`/`f32`/`f64` (any float), `bool`, and `[]const u8` (UTF-8 strings).
+
+const std = @import("std");
+const napi = @import("napi.zig");
+const c = napi.c;
+
+/// The JS-representable category a Zig type maps onto. Kept as a plain enum
+/// (rather than `@compileError` inline) so the classification is unit-testable
+/// at comptime without touching the N-API runtime.
+pub const Kind = enum { int, float, bool, string, unsupported };
+
+/// Classify a Zig type. `.unsupported` means there is no JS mapping for it.
+pub fn classify(comptime T: type) Kind {
+    return switch (@typeInfo(T)) {
+        .int => .int,
+        .float => .float,
+        .bool => .bool,
+        .pointer => |p| if (p.size == .slice and p.child == u8 and p.is_const)
+            .string
+        else
+            .unsupported,
+        else => .unsupported,
+    };
+}
+
+/// Compile-time guard that fails with a readable message for unsupported types.
+fn assertSupported(comptime T: type) void {
+    if (classify(T) == .unsupported) {
+        @compileError("zigbind: unsupported type '" ++ @typeName(T) ++
+            "' (supported: integers, floats, bool, []const u8)");
+    }
+}
+
+/// Read a JavaScript `value` into a Zig value of type `T`.
+///
+/// `allocator` is only used for `[]const u8` results (the bytes are copied out
+/// of V8). Callers own the returned slice's lifetime through that allocator.
+pub fn fromJs(comptime T: type, env: napi.Env, value: napi.Value, allocator: std.mem.Allocator) !T {
+    comptime assertSupported(T);
+    return switch (comptime classify(T)) {
+        .int => blk: {
+            const info = @typeInfo(T).int;
+            if (info.signedness == .unsigned and info.bits <= 32) {
+                var out: u32 = undefined;
+                try napi.check(c.napi_get_value_uint32(env, value, &out));
+                break :blk @intCast(out);
+            } else if (info.signedness == .signed and info.bits <= 32) {
+                var out: i32 = undefined;
+                try napi.check(c.napi_get_value_int32(env, value, &out));
+                break :blk @intCast(out);
+            } else {
+                var out: i64 = undefined;
+                try napi.check(c.napi_get_value_int64(env, value, &out));
+                break :blk @intCast(out);
+            }
+        },
+        .float => blk: {
+            var out: f64 = undefined;
+            try napi.check(c.napi_get_value_double(env, value, &out));
+            break :blk @floatCast(out);
+        },
+        .bool => blk: {
+            var out: bool = undefined;
+            try napi.check(c.napi_get_value_bool(env, value, &out));
+            break :blk out;
+        },
+        .string => blk: {
+            // First call with a null buffer to learn the byte length, then copy.
+            var len: usize = 0;
+            try napi.check(c.napi_get_value_string_utf8(env, value, null, 0, &len));
+            const buf = try allocator.alloc(u8, len + 1);
+            var written: usize = 0;
+            try napi.check(c.napi_get_value_string_utf8(env, value, buf.ptr, buf.len, &written));
+            break :blk buf[0..written];
+        },
+        .unsupported => unreachable,
+    };
+}
+
+/// Create a JavaScript value from a Zig value of type `T`.
+pub fn toJs(comptime T: type, env: napi.Env, value: T) !napi.Value {
+    comptime assertSupported(T);
+    var result: napi.Value = undefined;
+    switch (comptime classify(T)) {
+        .int => {
+            const info = @typeInfo(T).int;
+            if (info.signedness == .unsigned and info.bits <= 32) {
+                try napi.check(c.napi_create_uint32(env, @intCast(value), &result));
+            } else if (info.signedness == .signed and info.bits <= 32) {
+                try napi.check(c.napi_create_int32(env, @intCast(value), &result));
+            } else {
+                try napi.check(c.napi_create_int64(env, @intCast(value), &result));
+            }
+        },
+        .float => try napi.check(c.napi_create_double(env, @floatCast(value), &result)),
+        .bool => try napi.check(c.napi_get_boolean(env, value, &result)),
+        .string => try napi.check(c.napi_create_string_utf8(env, value.ptr, value.len, &result)),
+        .unsupported => unreachable,
+    }
+    return result;
+}
+
+test "classify maps Zig types to JS kinds" {
+    const expectEqual = std.testing.expectEqual;
+    try expectEqual(Kind.int, classify(i32));
+    try expectEqual(Kind.int, classify(u64));
+    try expectEqual(Kind.float, classify(f64));
+    try expectEqual(Kind.float, classify(f32));
+    try expectEqual(Kind.bool, classify(bool));
+    try expectEqual(Kind.string, classify([]const u8));
+    // A mutable slice is intentionally *not* treated as a JS string.
+    try expectEqual(Kind.unsupported, classify([]u8));
+    try expectEqual(Kind.unsupported, classify(struct { x: i32 }));
+}

package/native/src/napi.zig

@@ -0,0 +1,62 @@
+//! Raw N-API bindings and thin wrappers.
+//!
+//! The N-API C headers are vendored under `vendor/node-api-headers/` and pulled
+//! in here with `@cImport`. Everything the rest of the library needs from the C
+//! API is re-exported through `c`, plus a few ergonomic wrappers so the comptime
+//! machinery in `convert.zig` / `register.zig` doesn't have to spell out the raw
+//! `napi_status` dance every time.
+
+const std = @import("std");
+
+/// The imported N-API C API. We pin `NAPI_VERSION` to 8 (Node >= 18) so the
+/// headers expose exactly the surface we support.
+pub const c = @cImport({
+    @cDefine("NAPI_VERSION", "8");
+    @cInclude("node_api.h");
+});
+
+// Convenience aliases for the handful of opaque handles we pass around.
+pub const Env = c.napi_env;
+pub const Value = c.napi_value;
+pub const CallbackInfo = c.napi_callback_info;
+pub const Callback = c.napi_callback;
+pub const Status = c.napi_status;
+
+/// A call into the N-API C API returned a non-`napi_ok` status.
+pub const Error = error{NapiFailure};
+
+/// Turn a `napi_status` into a Zig error. `napi_ok` is `0`.
+pub fn check(status: Status) Error!void {
+    if (status != c.napi_ok) return Error.NapiFailure;
+}
+
+/// Throw a JavaScript `Error` with the given message and return control to JS.
+/// `msg` must be a null-terminated string. Used to surface Zig error unions.
+pub fn throwError(env: Env, msg: [:0]const u8) void {
+    _ = c.napi_throw_error(env, null, msg.ptr);
+}
+
+/// Read the arguments of the current call into `argv`, returning the actual
+/// argument count reported by N-API.
+pub fn getCallbackInfo(
+    env: Env,
+    info: CallbackInfo,
+    argv: []Value,
+) Error!usize {
+    var argc: usize = argv.len;
+    const argv_ptr: [*c]Value = if (argv.len == 0) null else argv.ptr;
+    try check(c.napi_get_cb_info(env, info, &argc, argv_ptr, null, null));
+    return argc;
+}
+
+/// Attach `value` to `object` under the (null-terminated) property `name`.
+pub fn setNamedProperty(env: Env, object: Value, name: [:0]const u8, value: Value) Error!void {
+    try check(c.napi_set_named_property(env, object, name.ptr, value));
+}
+
+/// Create a JS function backed by the native callback `cb`, named `name`.
+pub fn createFunction(env: Env, name: [:0]const u8, cb: Callback) Error!Value {
+    var result: Value = undefined;
+    try check(c.napi_create_function(env, name.ptr, name.len, cb, null, &result));
+    return result;
+}