feat: add export method to init module directly from comptime value

Author: typesafe

README.md

@@ -1,11 +1,39 @@
-
 The `node-api` Zig package provides [Node-API](https://nodejs.org/api/n-api.html) bindings for writing idiomatic Zig addons for V8-based runtimes like Node.JS or Bun.
 Thanks to its conventions-based approach it bridges the gap seamlessly, with almost no Node-API specific code!
 
-![build-badge](https://img.shields.io/github/actions/workflow/status/typesafe/node-api-zig/ci.yml
-)
+![build-badge](https://img.shields.io/github/actions/workflow/status/typesafe/node-api-zig/ci.yml)
 ![test-badge](https://img.shields.io/endpoint?url=https%3A%2F%2Fgist.githubusercontent.com%2Ftypesafe%2F26882516c7ac38bf94a81784f966bd86%2Fraw%2Fnode-api-zig-test-badge.json)
 
+```zig
+const node_api = @import("node-api");
+const Options = @import("Options");
+
+comptime {
+    // or node_api.init(fn (node) NodeValue) for runtime values
+    node_api.@"export"(encrypt);
+}
+
+fn encrypt(value: []const u8, options: Options, allocator: std.mem.Allocator) ![]const u8 {
+    const res = allocator.alloc(u8, 123);
+    errdefer allocator.free(res);
+
+    // ...
+
+    return res; // freed by node-api
+}
+
+```
+
+```TypeScript
+import { createRequire } from "module";
+const require = createRequire(import.meta.url);
+
+const encrypt = require("zig-module.node");
+
+// call zig function
+const m = encrypt("secret", { salt: "..."});
+
+```
 
 TODO:
 
@@ -35,7 +63,6 @@ TODO:
 
 # Getting started
 
-
 TODO
 
 # Features
@@ -64,21 +91,23 @@ import fromZig from(zig-module.node);
 Struct types, functions, fields, parameters and return values are all converted by convention.
 Unsupported types result in compile errors.
 
-|Native type|Node type|Remarks|
-|-|-|-|
-|`type`|`Class` or `Function`|Returning or passing a struct `type` to JS, turns it into a class.<br>Returning or passing a `fn`, turns it into a JS-callable, well, function. |
-|`i32`,`i64`,`u32`|`number`| |
-|`u64`|`BigInt`| |
-|`[]const u8`, `[]u8`|`string`|UTF-8|
-|`[]const T`, `[]T`|`array`| |
-|`*T`|`Object`|Passing struct pointers to JS will wrap & track them.|
-|`NodeValue`|`any`|NodeValue can be used to access JS values by reference.|
+| Native type          | Node type             | Remarks                                                                                                                                         |
+| -------------------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `type`               | `Class` or `Function` | Returning or passing a struct `type` to JS, turns it into a class.<br>Returning or passing a `fn`, turns it into a JS-callable, well, function. |
+| `i32`,`i64`,`u32`    | `number`              |                                                                                                                                                 |
+| `u64`                | `BigInt`              |                                                                                                                                                 |
+| `[]const u8`, `[]u8` | `string`              | UTF-8                                                                                                                                           |
+| `[]const T`, `[]T`   | `array`               |                                                                                                                                                 |
+| `*T`                 | `Object`              | Passing struct pointers to JS will wrap & track them.                                                                                           |
+| `NodeValue`          | `any`                 | NodeValue can be used to access JS values by reference.                                                                                         |
 
 Function parameters and return types can be
+
 - native Zig types (unsupported types will result in compile time errors)
 - one of the NodeValue types to access values by reference.
 
 Native values and NodeValue instance can be converted using `Convert`:
+
 - `nativeFromNode(comptime T: type, value: NodeValue, allocator. Allocator) T`
 - `nodeFromNative(value: anytype) NodeValue`
 
@@ -93,16 +122,13 @@ Arguments can be of type:
 - optional
 - enum
 - NodeXxx values for references
-## Define async functions
 
+## Define async functions
 
 ## Define classes
 
 `node.defineClass` transforms a Zig struct to a JS-accessible class by convention:
 
-
-
-
 ```zig
 
 comptime {
@@ -134,7 +160,6 @@ const MyClass = struct {
 
 ```
 
-
 ### Contstructors
 
 `init` maps to `new`.
@@ -151,37 +176,35 @@ const MyClass = struct {
 
 ## Memory management
 
-
-
 - class instances are allocated and freed automatically
   - new-ing instance (from JS) will allocate memory (and update V8 stats)
   - GC finalizers will automatically free the memory (and update V8 stats)
 - Zig type arguments that require allocations are "owned by the instance"
   - when the are store as field values the will be freed as part of the finalization process
     - existing field values must be freed manually when they are overwritten!
 
-
-
-
-/*
+/\*
 
 Scenarios:
 
 native (wrapped) instance lifecycle:
+
 - new in JS -> finalize in Zig
 - create in Zig -> finalize in Zig
 
 external instance memory:
+
 - arena per instance?
 - managed by instance if instance has allocator field
 
 parameters and return values:
+
 - pointers to structs result in uwrapped values
 - parameters and return type memory
   - arena per function call
 
 setting field values
-- frees previous value, if any
 
+- frees previous value, if any
 
- */
+  \*/

src/Convert.zig

@@ -188,7 +188,11 @@ pub fn nativeFromNode(env: c.napi_env, comptime T: type, js_value: c.napi_value,
                 }
             } else {
                 switch (i.bits) {
-                    32 => try s2e(c.napi_get_value_uint32(env, js_value, &res)),
+                    0...32 => {
+                        var tmp: u32 = undefined;
+                        try s2e(c.napi_get_value_uint32(env, js_value, &tmp));
+                        return @intCast(tmp);
+                    },
                     64 => {
                         var b: bool = undefined;
                         try s2e(c.napi_get_value_bigint_uint64(env, js_value, &res, &b));

src/root.zig

@@ -3,21 +3,48 @@ const std = @import("std");
 const c = @import("c.zig").c;
 const Convert = @import("Convert.zig");
 const NodeValues = @import("node_values.zig");
-/// Represents a Node VM Context.
-pub const NodeContext = @import("Node.zig").NodeContext;
 
-/// Represents a Node value.
+pub const NodeContext = @import("Node.zig").NodeContext;
 pub const NodeValue = NodeValues.NodeValue;
 pub const NodeObject = NodeValues.NodeObject;
 pub const NodeArray = NodeValues.NodeArray;
 pub const NodeFunction = NodeValues.NodeFunction;
 
-/// The InitFunction to pass to the `register` method. The `ctx` parameter
-/// represents the Node context. The returned value becomes the `exports` value
-/// of the JS module.
-pub const InitFunction = fn (ctx: NodeContext) anyerror!?NodeValue;
+/// Exports the specified comptime value as a native Node-API module.
+///
+/// Example:
+///
+/// ```
+/// const std = @import("std");
+/// const node_api = @import("node-api");
+///
+/// comptime {
+///     node_api.@"export"(.{
+///         .fn = function,
+///         .Class = Class,
+///     });
+/// }
+/// ```
+pub fn @"export"(comptime value: anytype) void {
+    const module = opaque {
+        pub fn napi_register_module_v1(env: c.napi_env, _: c.napi_value) callconv(.c) c.napi_value {
+            const node = NodeContext.init(env);
 
-/// Initializes a native Node-API module. Example:
+            const exports = node.serialize(value) catch |err| {
+                node.handleError(err);
+                return null;
+            };
+
+            return exports.napi_value;
+        }
+    };
+
+    registerModule(&module.napi_register_module_v1);
+}
+
+/// Initializes a native Node-API module by returning a runtime-known value.
+///
+/// Example:
 ///
 /// ```
 /// const std = @import("std");
@@ -32,12 +59,12 @@ pub const InitFunction = fn (ctx: NodeContext) anyerror!?NodeValue;
 ///     return try node.createString("hello!");
 /// }
 /// ```
-pub fn register(comptime init_fn: InitFunction) void {
+pub fn init(comptime f: InitFunction) void {
     const module = opaque {
         pub fn napi_register_module_v1(env: c.napi_env, exp: c.napi_value) callconv(.c) c.napi_value {
-            const node = NodeContext{ .napi_env = env };
+            const node = NodeContext.init(env);
 
-            const exports = init_fn(node) catch |err| {
+            const exports = f(node) catch |err| {
                 node.handleError(err);
                 return null;
             };
@@ -46,5 +73,14 @@ pub fn register(comptime init_fn: InitFunction) void {
         }
     };
 
-    @export(&module.napi_register_module_v1, .{ .name = "napi_register_module_v1" });
+    registerModule(&module.napi_register_module_v1);
+}
+
+/// The InitFunction to pass to the `register` method. The `ctx` parameter
+/// represents the Node context. The returned value becomes the `exports` value
+/// of the JS module.
+pub const InitFunction = fn (ctx: NodeContext) anyerror!?NodeValue;
+
+inline fn registerModule(comptime ptr: *const anyopaque) void {
+    @export(ptr, .{ .name = "napi_register_module_v1" });
 }

tests/README.md

@@ -0,0 +1,22 @@
+{
+  "lockfileVersion": 1,
+  "workspaces": {
+    "": {
+      "name": "test",
+      "dependencies": {
+        "bun-types": "^1.3.0",
+      },
+    },
+  },
+  "packages": {
+    "@types/node": ["@types/[email protected]", "", { "dependencies": { "undici-types": "~7.16.0" } }, "sha512-QoiaXANRkSXK6p0Duvt56W208du4P9Uye9hWLWgGMDTEoKPhuenzNcC4vGUmrNkiOKTlIrBoyNQYNpSwfEZXSg=="],
+
+    "@types/react": ["@types/[email protected]", "", { "dependencies": { "csstype": "^3.0.2" } }, "sha512-6mDvHUFSjyT2B2yeNx2nUgMxh9LtOWvkhIU3uePn2I2oyNymUAX1NIsdgviM4CH+JSrp2D2hsMvJOkxY+0wNRA=="],
+
+    "bun-types": ["[email protected]", "", { "dependencies": { "@types/node": "*" }, "peerDependencies": { "@types/react": "^19" } }, "sha512-NMrcy7smratanWJ2mMXdpatalovtxVggkj11bScuWuiOoXTiKIu2eVS1/7qbyI/4yHedtsn175n4Sm4JcdHLXw=="],
+
+    "csstype": ["[email protected]", "", {}, "sha512-M1uQkMl8rQK/szD0LNhtqxIPLpimGm8sOBwU7lLnCpSbTyY3yeU1Vc7l4KT5zT4s/yOxHH5O7tIuuLOCnLADRw=="],
+
+    "undici-types": ["[email protected]", "", {}, "sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw=="],
+  }
+}

tests/bun.lock

@@ -0,0 +1,16 @@
+The `zig_modules` folder contains a folder per test zig module.
+
+`/tests/zig_modules/{mod}/src/root.zig`
+
+is compiled to
+
+`/test/zig_modules/{mod}.node`
+
+and can be imported in a test using:
+
+```TypeScript
+import requireTestModule from "../";
+
+const addon = requireTestModule("{mod}");
+
+```

tests/zig_modules/README.md

@@ -0,0 +1,10 @@
+import { describe, it, expect } from "bun:test";
+
+import requireTestModule from "../";
+const encrypt = requireTestModule("allocators");
+
+describe("allocator", () => {
+  it("should get allocator", () => {
+    expect(encrypt("secret", { char: 88 })).toEqual("XXXXXX");
+  });
+});

tests/zig_modules/allocators/index.spec.ts

@@ -0,0 +1,7 @@
+pub fn init() @This() {
+    return .{};
+}
+
+key: u32,
+
+pub fn deinit(_: @This()) !void {}

tests/zig_modules/allocators/src/Options.zig

@@ -0,0 +1,20 @@
+const std = @import("std");
+const node_api = @import("node-api");
+
+comptime {
+    node_api.@"export"(encrypt);
+}
+
+const Options = struct {
+    char: u8,
+};
+
+// allocator is "injected" by convention
+fn encrypt(value: []const u8, options: Options, allocator: std.mem.Allocator) ![]const u8 {
+    const result = try allocator.alloc(u8, value.len);
+    errdefer allocator.free(result);
+
+    @memset(result, options.char);
+
+    return result;
+}

tests/zig_modules/allocators/src/root.zig

@@ -0,0 +1,10 @@
+import { describe, it, expect } from "bun:test";
+
+import requireTestModule from "../";
+const addon = requireTestModule("export-object");
+
+describe("node_api.register(.{})", () => {
+  it("should return serialized value", () => {
+    expect(addon).toEqual({ foo: "foo", bar: 123 });
+  });
+});