zignapi 0.2.0 → 0.3.0

package/native/build.zig.zon

@@ -1,6 +1,6 @@
 .{
     .name = .zignapi,
-    .version = "0.2.0",
+    .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

@@ -67,3 +67,18 @@ pub fn createString(env: Env, s: []const u8) Error!Value {
     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

@@ -13,6 +13,7 @@ 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.
@@ -35,8 +36,7 @@ pub fn register(comptime defs: anytype) void {
     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;
                 };
@@ -53,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),
@@ -87,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

@@ -6,12 +6,15 @@
 //! 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. Error unions map to their payload
-/// (Zig errors surface as thrown JS exceptions, which don't appear in the type);
-/// `void` maps to `void`.
+/// 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),
@@ -27,26 +30,34 @@ pub fn tsType(comptime T: type) []const u8 {
 }
 
 /// Build the `.d.ts` body: one `export function` line per registered function.
-/// Parameter names aren't available from `@typeInfo`, so they're `arg0`, `arg1`, …
+/// `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 fn_info = @typeInfo(@TypeOf(@field(defs, field.name))).@"fn";
+        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 = "";
-        inline for (fn_info.params, 0..) |param, i| {
-            const sep = if (i == 0) "" else ", ";
-            params = params ++ sep ++ std.fmt.comptimePrint(
-                "arg{d}: {s}",
-                .{ i, tsType(param.type.?) },
-            );
+        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;
         }
-        out = out ++ "export function " ++ field.name ++ "(" ++ params ++
-            "): " ++ tsType(fn_info.return_type.?) ++ ";\n";
+
+        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 one export per function" {
+test "declarations render sync, async and passthrough signatures" {
     const S = struct {
         fn add(a: i32, b: i32) i32 {
             return a + b;
@@ -54,24 +65,25 @@ test "declarations render one export per function" {
         fn greet(name: []const u8) []const u8 {
             return name;
         }
-        fn toggle(x: bool) bool {
-            return !x;
+        fn heavy(a: i32, b: i32) i32 {
+            return a * b;
         }
-        fn checked(x: i32) !i32 {
-            return x;
+        fn onEvent(env: napi.Env, cb: napi.Value) void {
+            _ = env;
+            _ = cb;
         }
     };
     const dts = comptime declarations(.{
         .add = S.add,
         .greet = S.greet,
-        .toggle = S.toggle,
-        .checked = S.checked,
+        .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 toggle(arg0: boolean): boolean;
-        \\export function checked(arg0: number): number;
+        \\export function heavy(arg0: number, arg1: number): Promise<number>;
+        \\export function onEvent(arg0: any): void;
         \\
     , dts);
 }

package/native/src/zignapi.zig

@@ -18,6 +18,12 @@ 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.2.0",
+  "version": "0.3.0",
   "description": "CLI to scaffold and build native Node.js addons written in Zig (the `zignapi` command)",
   "keywords": [
     "zig",

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

@@ -14,8 +14,13 @@ 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>;/);
 });