zignapi 0.1.1 → 0.3.0

package/dist/build.js

@@ -1,8 +1,9 @@
 import { parseArgs } from "node:util";
-import { existsSync, copyFileSync, readdirSync } from "node:fs";
+import { existsSync, copyFileSync, readdirSync, writeFileSync } from "node:fs";
 import { join, basename, extname } from "node:path";
+import { createRequire } from "node:module";
 import process from "node:process";
-import { runZig } from "./zig.js";
+import { runZig, errMessage } from "./zig.js";
 const BUILD_HELP = `zignapi build — build the addon in the current directory
 
 Usage:
@@ -12,8 +13,9 @@ 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).
+Runs "zig build" in the current directory, copies the resulting shared library
+to ./<name>.node (renaming a plain .dylib/.so/.dll if needed), then generates
+index.js and index.d.ts from the addon's embedded type declarations.
 `;
 export async function runBuild(argv) {
     const { values } = parseArgs({
@@ -36,13 +38,42 @@ export async function runBuild(argv) {
         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) {
+    const addonPath = findAddon(join(cwd, "zig-out"));
+    if (!addonPath) {
         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`);
+    const nodeFile = addonName(addonPath);
+    copyFileSync(addonPath, join(cwd, nodeFile));
+    process.stdout.write(`✔ built ${nodeFile}\n`);
+    generateBindings(cwd, nodeFile);
+}
+/**
+ * Emit `index.js` (a loader that re-exports the addon) and `index.d.ts` (the
+ * TypeScript declarations) from the type info the addon embeds as
+ * `__zignapi_dts__`. Non-fatal: a build that can't be introspected still counts
+ * as a successful build.
+ */
+function generateBindings(cwd, nodeFile) {
+    const require = createRequire(import.meta.url);
+    let addon;
+    try {
+        addon = require(join(cwd, nodeFile));
+    }
+    catch (err) {
+        process.stderr.write(`note: skipped type generation (could not load ${nodeFile}: ${errMessage(err)})\n`);
+        return;
+    }
+    const dts = addon.__zignapi_dts__;
+    if (typeof dts !== "string" || dts.length === 0) {
+        process.stderr.write("note: addon has no embedded type info; skipping index.d.ts\n");
+        return;
+    }
+    writeFileSync(join(cwd, "index.d.ts"), `// Generated by zignapi — do not edit.\n\n${dts}`);
+    writeFileSync(join(cwd, "index.js"), `"use strict";\n` +
+        `const addon = require("./${nodeFile}");\n` +
+        `const { __zignapi_dts__, ...api } = addon;\n` +
+        `module.exports = api;\n`);
+    process.stdout.write("✔ generated index.js + index.d.ts\n");
 }
 /**
  * Find the built addon under zig-out. Prefers an already-named `.node`,

package/dist/new.js

@@ -3,7 +3,7 @@ import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, } from
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import process from "node:process";
-import { releaseUrl, resolveZignapiSources, runZig } from "./zig.js";
+import { releaseUrl, resolveZignapiSources, runZig, errMessage } 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");
@@ -113,6 +113,3 @@ function validateName(name) {
             `must not start with a digit)`);
     }
 }
-function errMessage(err) {
-    return err instanceof Error ? err.message : String(err);
-}

package/dist/zig.js

@@ -64,6 +64,10 @@ export function runZig(cwd, args, { repairZon } = {}) {
     }
     return res;
 }
+/** Extract a human-readable message from an unknown thrown value. */
+export function errMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
 /** Insert or replace the `.fingerprint` field in a build.zig.zon. */
 export function patchFingerprint(zonPath, value) {
     if (!existsSync(zonPath))

package/native/build.zig

@@ -42,17 +42,18 @@ pub fn build(b: *std.Build) void {
     });
     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);
+    // Unit tests: only pure-comptime code (no N-API runtime calls), so the test
+    // binaries link without Node present.
     const test_step = b.step("test", "Run zignapi unit tests");
-    test_step.dependOn(&run_tests.step);
+    for ([_][]const u8{ "src/convert.zig", "src/typedefs.zig" }) |root| {
+        const tests_mod = b.createModule(.{
+            .root_source_file = b.path(root),
+            .target = target,
+            .optimize = optimize,
+            .link_libc = true,
+        });
+        tests_mod.addIncludePath(headers);
+        const unit_tests = b.addTest(.{ .root_module = tests_mod });
+        test_step.dependOn(&b.addRunArtifact(unit_tests).step);
+    }
 }

package/native/build.zig.zon

@@ -1,6 +1,6 @@
 .{
     .name = .zignapi,
-    .version = "0.1.1",
+    .version = "0.3.0",
     .fingerprint = 0x582024f92c57df77, // Changing this has security and trust implications.
     .minimum_zig_version = "0.16.0",
     .dependencies = .{},

package/native/src/_check.zig

@@ -16,6 +16,9 @@ comptime {
     _ = napi.getCallbackInfo;
     _ = napi.setNamedProperty;
     _ = napi.createFunction;
+    _ = napi.createString;
+    _ = napi.getUndefined;
+    _ = napi.createError;
 }
 
 fn add(a: i32, b: i32) i32 {
@@ -34,6 +37,21 @@ fn checked(x: i32) !i32 {
     return if (x < 0) error.MustBeNonNegative else x;
 }
 
+// Async: runs on the thread pool, returns a Promise.
+fn heavy(a: i32, b: i32) i32 {
+    return a * b;
+}
+fn heavyChecked(x: i32) !i32 {
+    return if (x < 0) error.MustBeNonNegative else x;
+}
+
+// Raw passthrough: `napi.Env` / `napi.Value` params + a threadsafe function.
+fn onEvent(env: napi.Env, callback: napi.Value) void {
+    const tsfn = zignapi.ThreadsafeFunction(i32).create(env, callback) catch return;
+    tsfn.call(1) catch {};
+    tsfn.release();
+}
+
 comptime {
     zignapi.register(.{
         .add = add,
@@ -41,5 +59,8 @@ comptime {
         .scale = scale,
         .echo = echo,
         .checked = checked,
+        .heavy = zignapi.asyncFn(heavy),
+        .heavyChecked = zignapi.asyncFn(heavyChecked),
+        .onEvent = onEvent,
     });
 }

package/native/src/async.zig

@@ -1,15 +1,209 @@
-//! Async support — stub.
+//! Async support: run a Zig function on libuv's thread pool and resolve a JS
+//! `Promise`, plus a threadsafe-function primitive for calling JS from any
+//! thread.
 //!
-//! 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.
+//! ## Async functions
+//!
+//! Wrap a function with `asyncFn` when registering it. Its arguments are
+//! converted on the JS thread, the function body runs on a worker thread (so it
+//! must NOT touch JS / N-API), and the result (or a thrown error) settles the
+//! promise back on the JS thread:
+//!
+//! ```zig
+//! fn heavy(a: i32, b: i32) i32 { return a * b; }
+//! comptime { zignapi.register(.{ .heavy = zignapi.asyncFn(heavy) }); }
+//! // JS: await addon.heavy(6, 7) === 42
+//! ```
+//!
+//! ## Threadsafe functions
+//!
+//! `ThreadsafeFunction(T)` lets native code call a JS callback from any thread.
+//! Create it on the JS thread from a callback the addon received as a raw
+//! `napi.Value`, hand it to a worker thread, `call` it, then `release` it.
 
 const std = @import("std");
+const napi = @import("napi.zig");
+const convert = @import("convert.zig");
+const c = napi.c;
+
+/// Mark a function as async when registering it (runs on the thread pool and
+/// returns a `Promise`). See the module docs.
+pub fn asyncFn(comptime f: anytype) AsyncMarker(f) {
+    return .{};
+}
+
+fn AsyncMarker(comptime f: anytype) type {
+    return struct {
+        pub const zignapi_async_task = true;
+        pub const func = f;
+    };
+}
+
+/// Whether a `register` field value's type is an `asyncFn(...)` marker.
+pub fn isAsyncMarker(comptime FieldT: type) bool {
+    return switch (@typeInfo(FieldT)) {
+        .@"struct" => @hasDecl(FieldT, "zignapi_async_task"),
+        else => false,
+    };
+}
+
+/// Build the `napi_callback` trampoline for an async function: it returns a
+/// Promise immediately and does the work on a libuv worker thread.
+pub fn AsyncWrap(comptime func: anytype) type {
+    const fn_info = @typeInfo(@TypeOf(func)).@"fn";
+    const RetType = fn_info.return_type.?;
+    const Payload = switch (@typeInfo(RetType)) {
+        .error_union => |eu| eu.payload,
+        else => RetType,
+    };
+
+    const Task = struct {
+        args: std.meta.ArgsTuple(@TypeOf(func)),
+        arena: std.heap.ArenaAllocator,
+        deferred: c.napi_deferred,
+        work: c.napi_async_work,
+        payload: Payload,
+        err_name: ?[:0]const u8,
+    };
+
+    return struct {
+        pub fn callback(env: napi.Env, info: napi.CallbackInfo) callconv(.c) napi.Value {
+            var argv: [fn_info.params.len]napi.Value = undefined;
+            _ = napi.getCallbackInfo(env, info, &argv) catch {
+                napi.throwError(env, "zignapi: failed to read arguments");
+                return null;
+            };
+
+            const task = std.heap.c_allocator.create(Task) catch {
+                napi.throwError(env, "zignapi: out of memory");
+                return null;
+            };
+            task.arena = std.heap.ArenaAllocator.init(std.heap.c_allocator);
+            task.err_name = null;
+
+            // Convert arguments on the JS thread (N-API access is valid here).
+            const allocator = task.arena.allocator();
+            inline for (fn_info.params, 0..) |param, i| {
+                task.args[i] = convert.fromJs(param.type.?, env, argv[i], allocator) catch
+                    return abort(task, env, "zignapi: failed to convert argument");
+            }
+
+            var promise: napi.Value = undefined;
+            if (c.napi_create_promise(env, &task.deferred, &promise) != c.napi_ok)
+                return abort(task, env, "zignapi: failed to create promise");
+
+            const name = napi.createString(env, "zignapi_async_task") catch
+                return abort(task, env, "zignapi: failed to create async work");
+
+            _ = c.napi_create_async_work(env, null, name, execute, complete, task, &task.work);
+            _ = c.napi_queue_async_work(env, task.work);
+            return promise;
+        }
+
+        /// Free a partially-initialised task, throw, and return null (on the JS
+        /// thread, before the work is queued).
+        fn abort(task: *Task, env: napi.Env, msg: [:0]const u8) napi.Value {
+            task.arena.deinit();
+            std.heap.c_allocator.destroy(task);
+            napi.throwError(env, msg);
+            return null;
+        }
+
+        /// Worker thread — no N-API / JS access allowed.
+        fn execute(env: napi.Env, data: ?*anyopaque) callconv(.c) void {
+            _ = env;
+            const task: *Task = @ptrCast(@alignCast(data.?));
+            switch (@typeInfo(RetType)) {
+                .error_union => task.payload = @call(.auto, func, task.args) catch |err| {
+                    task.err_name = @errorName(err);
+                    return;
+                },
+                else => task.payload = @call(.auto, func, task.args),
+            }
+        }
+
+        /// JS thread — settle the promise with the result or the error.
+        fn complete(env: napi.Env, status: c.napi_status, data: ?*anyopaque) callconv(.c) void {
+            const task: *Task = @ptrCast(@alignCast(data.?));
+            defer {
+                task.arena.deinit();
+                _ = c.napi_delete_async_work(env, task.work);
+                std.heap.c_allocator.destroy(task);
+            }
+
+            if (status != c.napi_ok) return reject(env, task.deferred, "zignapi: async work cancelled");
+            if (task.err_name) |name| return reject(env, task.deferred, name);
+
+            const resolution = if (Payload == void)
+                (napi.getUndefined(env) catch return reject(env, task.deferred, "zignapi: internal error"))
+            else
+                (convert.toJs(Payload, env, task.payload) catch
+                    return reject(env, task.deferred, "zignapi: failed to convert result"));
+            _ = c.napi_resolve_deferred(env, task.deferred, resolution);
+        }
+    };
+}
+
+fn reject(env: napi.Env, deferred: c.napi_deferred, msg: []const u8) void {
+    const err = napi.createError(env, msg) catch return;
+    _ = c.napi_reject_deferred(env, deferred, err);
+}
+
+/// A threadsafe function: a JS callback that native code can invoke from any
+/// thread. `T` is the Zig type of the single argument passed to the callback
+/// (converted to JS via `convert`). Create it on the JS thread, use it from
+/// worker threads, and `release` it when done.
+pub fn ThreadsafeFunction(comptime T: type) type {
+    return struct {
+        const Self = @This();
+
+        handle: c.napi_threadsafe_function,
+
+        /// Create from a JS callback value. Call on the JS thread.
+        pub fn create(env: napi.Env, js_callback: napi.Value) napi.Error!Self {
+            const name = try napi.createString(env, "zignapi_tsfn");
+            var handle: c.napi_threadsafe_function = undefined;
+            try napi.check(c.napi_create_threadsafe_function(
+                env,
+                js_callback,
+                null, // async_resource
+                name,
+                0, // max_queue_size: unlimited
+                1, // initial_thread_count
+                null, // thread_finalize_data
+                null, // thread_finalize_cb
+                null, // context
+                callJs,
+                &handle,
+            ));
+            return .{ .handle = handle };
+        }
+
+        /// Queue a call to the JS callback with `value`. Safe from any thread.
+        pub fn call(self: Self, value: T) napi.Error!void {
+            const boxed = std.heap.c_allocator.create(T) catch return napi.Error.NapiFailure;
+            boxed.* = value;
+            if (c.napi_call_threadsafe_function(self.handle, boxed, c.napi_tsfn_blocking) != c.napi_ok) {
+                std.heap.c_allocator.destroy(boxed);
+                return napi.Error.NapiFailure;
+            }
+        }
+
+        /// Release the reference so Node can tear the function down. Any thread.
+        pub fn release(self: Self) void {
+            _ = c.napi_release_threadsafe_function(self.handle, c.napi_tsfn_release);
+        }
 
-comptime {
-    // Keep this file referenced so it participates in compilation checks even
-    // while it is only a placeholder.
-    std.debug.assert(true);
+        /// JS thread — convert the queued value and invoke the callback.
+        fn callJs(env: napi.Env, js_cb: napi.Value, context: ?*anyopaque, data: ?*anyopaque) callconv(.c) void {
+            _ = context;
+            const boxed: *T = @ptrCast(@alignCast(data.?));
+            defer std.heap.c_allocator.destroy(boxed);
+            if (env == null) return; // the environment is tearing down
+            const arg = convert.toJs(T, env, boxed.*) catch return;
+            const recv = napi.getUndefined(env) catch return;
+            var argv = [_]napi.Value{arg};
+            _ = c.napi_call_function(env, recv, js_cb, argv.len, &argv, null);
+        }
+    };
 }

package/native/src/napi.zig

@@ -60,3 +60,25 @@ pub fn createFunction(env: Env, name: [:0]const u8, cb: Callback) Error!Value {
     try check(c.napi_create_function(env, name.ptr, name.len, cb, null, &result));
     return result;
 }
+
+/// Create a JS UTF-8 string from a Zig slice.
+pub fn createString(env: Env, s: []const u8) Error!Value {
+    var result: Value = undefined;
+    try check(c.napi_create_string_utf8(env, s.ptr, s.len, &result));
+    return result;
+}
+
+/// The JS `undefined` value.
+pub fn getUndefined(env: Env) Error!Value {
+    var result: Value = undefined;
+    try check(c.napi_get_undefined(env, &result));
+    return result;
+}
+
+/// Create a JS `Error` object carrying `msg` (used to reject promises).
+pub fn createError(env: Env, msg: []const u8) Error!Value {
+    const message = try createString(env, msg);
+    var result: Value = undefined;
+    try check(c.napi_create_error(env, null, message, &result));
+    return result;
+}

package/native/src/register.zig

@@ -12,6 +12,8 @@
 const std = @import("std");
 const napi = @import("napi.zig");
 const convert = @import("convert.zig");
+const typedefs = @import("typedefs.zig");
+const asyncwork = @import("async.zig");
 const c = napi.c;
 
 /// Export `napi_register_module_v1` for the given set of functions.
@@ -27,15 +29,23 @@ pub fn register(comptime defs: anytype) void {
         else => @compileError("zignapi.register expects a struct literal, e.g. .{ .add = add }"),
     }
 
+    // TypeScript declarations for this module, generated at comptime and
+    // embedded so `zignapi build` can emit `index.d.ts` / `index.js`.
+    const dts = typedefs.declarations(defs);
+
     const Registrar = struct {
         fn entry(env: napi.Env, exports: napi.Value) callconv(.c) napi.Value {
             inline for (@typeInfo(Defs).@"struct".fields) |field| {
-                const func = @field(defs, field.name);
-                registerOne(env, exports, field.name, func) catch {
+                registerField(env, exports, field.name, @field(defs, field.name)) catch {
                     napi.throwError(env, "zignapi: failed to register '" ++ field.name ++ "'");
                     return null;
                 };
             }
+            // Best-effort: attach the type declarations. Failure here must not
+            // break a working module, so ignore errors.
+            if (napi.createString(env, dts)) |v| {
+                napi.setNamedProperty(env, exports, "__zignapi_dts__", v) catch {};
+            } else |_| {}
             return exports;
         }
     };
@@ -43,17 +53,27 @@ pub fn register(comptime defs: anytype) void {
     @export(&Registrar.entry, .{ .name = "napi_register_module_v1", .linkage = .strong });
 }
 
-/// Bind a single function onto `exports` under `name`.
-fn registerOne(
+/// Bind a single field onto `exports` under `name`. The field is either a plain
+/// function (registered synchronously) or an `asyncFn(...)` marker (registered
+/// as an async, promise-returning function).
+fn registerField(
     env: napi.Env,
     exports: napi.Value,
     comptime name: [:0]const u8,
-    comptime func: anytype,
+    comptime field_val: anytype,
 ) !void {
-    const fn_value = try napi.createFunction(env, name, Wrap(func).callback);
+    const fn_value = try napi.createFunction(env, name, callbackFor(field_val));
     try napi.setNamedProperty(env, exports, name, fn_value);
 }
 
+fn callbackFor(comptime field_val: anytype) napi.Callback {
+    const FieldT = @TypeOf(field_val);
+    if (comptime asyncwork.isAsyncMarker(FieldT)) {
+        return asyncwork.AsyncWrap(FieldT.func).callback;
+    }
+    return Wrap(field_val).callback;
+}
+
 /// Build the `napi_callback` trampoline for a specific Zig function.
 ///
 /// Each distinct `func` produces its own type (and therefore its own callback),
@@ -77,13 +97,25 @@ fn Wrap(comptime func: anytype) type {
             defer arena.deinit();
             const allocator = arena.allocator();
 
-            // Convert each argument from JS into its Zig type.
+            // Convert each argument from JS into its Zig type. `napi.Env` and
+            // `napi.Value` parameters are passed through raw and don't consume a
+            // JS argument (like napi-rs's `Env`), so track the JS index separately.
             var args: std.meta.ArgsTuple(@TypeOf(func)) = undefined;
+            comptime var js_arg: usize = 0;
             inline for (fn_info.params, 0..) |param, i| {
-                args[i] = convert.fromJs(param.type.?, env, argv[i], allocator) catch {
-                    napi.throwError(env, "zignapi: failed to convert argument");
-                    return null;
-                };
+                const P = param.type.?;
+                if (P == napi.Env) {
+                    args[i] = env;
+                } else if (P == napi.Value) {
+                    args[i] = argv[js_arg];
+                    js_arg += 1;
+                } else {
+                    args[i] = convert.fromJs(P, env, argv[js_arg], allocator) catch {
+                        napi.throwError(env, "zignapi: failed to convert argument");
+                        return null;
+                    };
+                    js_arg += 1;
+                }
             }
 
             const result = @call(.auto, func, args);

package/native/src/typedefs.zig

@@ -0,0 +1,89 @@
+//! Comptime generation of TypeScript declarations for the registered functions.
+//!
+//! The mapping reuses `convert.classify`, so the `.d.ts` and the runtime
+//! conversions can never drift apart. `register.zig` embeds the produced string
+//! in the addon (as the `__zignapi_dts__` export); `zignapi build` reads it back
+//! and writes `index.d.ts` / `index.js`.
+
+const std = @import("std");
+const napi = @import("napi.zig");
+const convert = @import("convert.zig");
+const asyncwork = @import("async.zig");
+
+/// The TypeScript type string for a Zig type. `napi.Value` (a raw JS handle,
+/// e.g. a callback) maps to `any`; error unions map to their payload (Zig
+/// errors surface as thrown JS exceptions); `void` maps to `void`.
+pub fn tsType(comptime T: type) []const u8 {
+    if (T == napi.Value) return "any";
+    return switch (@typeInfo(T)) {
+        .void => "void",
+        .error_union => |eu| tsType(eu.payload),
+        else => switch (convert.classify(T)) {
+            .int, .float => "number",
+            .bool => "boolean",
+            .string => "string",
+            .unsupported => @compileError(
+                "zignapi: no TypeScript mapping for '" ++ @typeName(T) ++ "'",
+            ),
+        },
+    };
+}
+
+/// Build the `.d.ts` body: one `export function` line per registered function.
+/// `napi.Env` parameters are skipped (they aren't JS arguments); `asyncFn`
+/// functions return `Promise<T>`. Parameter names are `arg0`, `arg1`, …
+pub fn declarations(comptime defs: anytype) []const u8 {
+    comptime var out: []const u8 = "";
+    inline for (@typeInfo(@TypeOf(defs)).@"struct".fields) |field| {
+        const field_val = @field(defs, field.name);
+        const is_async = asyncwork.isAsyncMarker(@TypeOf(field_val));
+        const func = if (is_async) @TypeOf(field_val).func else field_val;
+        const fn_info = @typeInfo(@TypeOf(func)).@"fn";
+
+        comptime var params: []const u8 = "";
+        comptime var js_i: usize = 0;
+        inline for (fn_info.params) |param| {
+            const P = param.type.?;
+            if (P == napi.Env) continue; // not a JS argument
+            const sep = if (js_i == 0) "" else ", ";
+            params = params ++ sep ++ std.fmt.comptimePrint("arg{d}: {s}", .{ js_i, tsType(P) });
+            js_i += 1;
+        }
+
+        const ret = tsType(fn_info.return_type.?);
+        const ret_str = if (is_async) "Promise<" ++ ret ++ ">" else ret;
+        out = out ++ "export function " ++ field.name ++ "(" ++ params ++ "): " ++ ret_str ++ ";\n";
+    }
+    return out;
+}
+
+test "declarations render sync, async and passthrough signatures" {
+    const S = struct {
+        fn add(a: i32, b: i32) i32 {
+            return a + b;
+        }
+        fn greet(name: []const u8) []const u8 {
+            return name;
+        }
+        fn heavy(a: i32, b: i32) i32 {
+            return a * b;
+        }
+        fn onEvent(env: napi.Env, cb: napi.Value) void {
+            _ = env;
+            _ = cb;
+        }
+    };
+    const dts = comptime declarations(.{
+        .add = S.add,
+        .greet = S.greet,
+        .heavy = asyncwork.asyncFn(S.heavy),
+        .onEvent = S.onEvent,
+    });
+    try std.testing.expectEqualStrings(
+        \\export function add(arg0: number, arg1: number): number;
+        \\export function greet(arg0: string): string;
+        \\export function heavy(arg0: number, arg1: number): Promise<number>;
+        \\export function onEvent(arg0: any): void;
+        \\
+    , dts);
+}

package/native/src/zignapi.zig

@@ -12,11 +12,18 @@ const std = @import("std");
 
 pub const napi = @import("napi.zig");
 pub const convert = @import("convert.zig");
+pub const typedefs = @import("typedefs.zig");
 pub const async_ = @import("async.zig");
 
 /// Register Zig functions as a Node addon. See `register.zig`.
 pub const register = @import("register.zig").register;
 
+/// Mark a function as async (runs on libuv's thread pool, returns a `Promise`).
+pub const asyncFn = async_.asyncFn;
+
+/// A JS callback callable from any thread. See `async.zig`.
+pub const ThreadsafeFunction = async_.ThreadsafeFunction;
+
 /// The raw imported N-API C API (`napi_*` functions and types).
 pub const c = napi.c;
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zignapi",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "CLI to scaffold and build native Node.js addons written in Zig (the `zignapi` command)",
   "keywords": [
     "zig",

package/templates/dot-gitignore

@@ -2,3 +2,7 @@ node_modules/
 zig-out/
 .zig-cache/
 *.node
+
+# Generated by `zignapi build`
+index.js
+index.d.ts

package/templates/package.json

@@ -2,6 +2,8 @@
   "name": "__NAME__",
   "version": "0.1.0",
   "private": true,
+  "main": "index.js",
+  "types": "index.d.ts",
   "scripts": {
     "build": "zignapi build",
     "test": "node --test"

package/templates/src/main.zig

@@ -11,11 +11,18 @@ pub fn greet(name: []const u8) []const u8 {
     return "hello from Zig";
 }
 
+/// Async — `zignapi.asyncFn` runs it on a worker thread and returns a
+/// `Promise`. The body must not touch JS (it runs off the JS thread).
+fn slowSquare(x: i32) i32 {
+    return x * x;
+}
+
 // Emits `napi_register_module_v1`. Each field becomes a property on the addon's
 // `exports`. Add your own Zig functions here.
 comptime {
     zignapi.register(.{
         .add = add,
         .greet = greet,
+        .slowSquare = zignapi.asyncFn(slowSquare),
     });
 }

package/templates/test.js

@@ -1,7 +1,10 @@
 const test = require("node:test");
 const assert = require("node:assert");
+const fs = require("node:fs");
 
-const addon = require("./zig-out/lib/__NAME__.node");
+// The generated loader (index.js) re-exports the addon; index.d.ts gives it types.
+// Both are produced by `zignapi build`, so build before running the tests.
+const addon = require("./index.js");
 
 test("add(2, 3) === 5", () => {
   assert.strictEqual(addon.add(2, 3), 5);
@@ -10,3 +13,14 @@ test("add(2, 3) === 5", () => {
 test("greet returns a string", () => {
   assert.strictEqual(addon.greet("world"), "hello from Zig");
 });
+
+test("slowSquare resolves a Promise", async () => {
+  assert.strictEqual(await addon.slowSquare(8), 64);
+});
+
+test("index.d.ts declares the exports", () => {
+  const dts = fs.readFileSync("./index.d.ts", "utf8");
+  assert.match(dts, /export function add\(arg0: number, arg1: number\): number;/);
+  assert.match(dts, /export function greet\(arg0: string\): string;/);
+  assert.match(dts, /export function slowSquare\(arg0: number\): Promise<number>;/);
+});