refactor Serializer to Convert

typesafe · typesafe · commit 2fa9cd95f6ee · 2025-10-24T22:44:34.000+02:00
diff --git a/README.md b/README.md
@@ -57,13 +57,26 @@ import fromZig from(zig-module.node);
 
 ## Type Conversions
 
+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.|
+
 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 the NodeSerializer.
-- deserialize(comptime T: type, value: NodeValue, allocator. Allocator) T
-- serialize(value: anytype) NodeValue
+Native values and NodeValue instance can be converted using `Convert`:
+- `nativeFromNode(comptime T: type, value: NodeValue, allocator. Allocator) T`
+- `nodeFromNative(value: anytype) NodeValue`
 
 ## Define functions
 
diff --git a/src/Convert.zig b/src/Convert.zig
@@ -11,7 +11,7 @@ const NodeFunction = node_values.NodeFunction;
 const registry = @import("references.zig").Registry;
 
 /// Converts a Zig value to a Node-API value. Memory for the node value is allocated by V8.
-pub fn serialize(env: c.napi_env, value: anytype) !c.napi_value {
+pub fn nodeFromNative(env: c.napi_env, value: anytype) !c.napi_value {
     const T = @TypeOf(value);
 
     const node = NodeContext.init(env);
@@ -29,28 +29,28 @@ pub fn serialize(env: c.napi_env, value: anytype) !c.napi_value {
                 switch (@bitSizeOf(T)) {
                     0...32 => try s2e(c.napi_create_int32(env, value, &res)),
                     33...64 => try s2e(c.napi_create_int64(env, value, &res)),
-                    else => |s| @compileError(std.fmt.comptimePrint("Cannot serialize value of type {s}, unsupported bitsize {d}", .{ @typeName(T), s })),
+                    else => |s| @compileError(std.fmt.comptimePrint("Cannot convert value of type '{s}', unsupported bitsize {d}", .{ @typeName(T), s })),
                 }
             } else {
                 switch (@bitSizeOf(T)) {
                     0...32 => try s2e(c.napi_create_uint32(env, value, &res)),
                     33...64 => try s2e(c.napi_create_bigint_uint64(env, value, &res)),
-                    else => |s| @compileError(std.fmt.comptimePrint("Cannot serialize value of type {s}, unsupported bitsize {d}", .{ @typeName(T), s })),
+                    else => |s| @compileError(std.fmt.comptimePrint("Cannot convert value of type '{s}', unsupported bitsize {d}", .{ @typeName(T), s })),
                 }
             }
         },
         .int => |i| {
             if (i.signedness == .signed) {
                 switch (i.bits) {
-                    0...32 => try s2e(c.napi_create_int32(env, value, &res)),
-                    33...64 => try s2e(c.napi_create_int64(env, value, &res)),
-                    else => |s| @compileError(std.fmt.comptimePrint("Cannot serialize value of type {s}, unsupported bitsize {d}", .{ @typeName(T), s })),
+                    32 => try s2e(c.napi_create_int32(env, value, &res)),
+                    64 => try s2e(c.napi_create_int64(env, value, &res)),
+                    else => |s| @compileError(std.fmt.comptimePrint("Cannot convert value of type '{s}', unsupported bitsize {d}", .{ @typeName(T), s })),
                 }
             } else {
                 switch (i.bits) {
-                    0...32 => try s2e(c.napi_create_uint32(env, value, &res)),
-                    33...64 => try s2e(c.napi_create_bigint_uint64(env, value, &res)),
-                    else => |s| @compileError(std.fmt.comptimePrint("Cannot serialize value of type {s}, unsupported bitsize {d}", .{ @typeName(T), s })),
+                    32 => try s2e(c.napi_create_uint32(env, value, &res)),
+                    64 => try s2e(c.napi_create_bigint_uint64(env, value, &res)),
+                    else => |s| @compileError(std.fmt.comptimePrint("Cannot convert value of type '{s}', unsupported bitsize {d}", .{ @typeName(T), s })),
                 }
             }
         },
@@ -70,7 +70,7 @@ pub fn serialize(env: c.napi_env, value: anytype) !c.napi_value {
         },
         .optional => {
             if (value) |val| {
-                return serialize(env, val);
+                return nodeFromNative(env, val);
             } else {
                 try s2e(c.napi_get_null(env, &res));
             }
@@ -82,11 +82,7 @@ pub fn serialize(env: c.napi_env, value: anytype) !c.napi_value {
                         return v;
                     }
 
-                    // TODO: could be wrapped value, do we need this?
-                    // how do we know if the instance was already wrapped before?
-                    // hashset?
-
-                    return serialize(env, value.*);
+                    return nodeFromNative(env, value.*);
                 },
                 .slice => {
                     std.log.debug("serializing {s} of type {s}", .{ value, @typeName(T) });
@@ -96,13 +92,13 @@ pub fn serialize(env: c.napi_env, value: anytype) !c.napi_value {
                         try s2e(c.napi_create_array_with_length(env, value.len, &res));
 
                         for (value, 0..) |item, i| {
-                            const el = try serialize(env, item);
+                            const el = try nodeFromNative(env, item);
                             try s2e(c.napi_set_element(env, res, i, el));
                         }
                     }
                 },
                 .many, .c => {
-                    @compileError("Cannot serialize c-style pointer values, they are not supported.");
+                    @compileError("Cannot convert c-style pointer values, they are not supported.");
                 },
             }
         },
@@ -114,21 +110,19 @@ pub fn serialize(env: c.napi_env, value: anytype) !c.napi_value {
             if (!s.is_tuple) {
                 try s2e(c.napi_create_object(env, &res));
                 inline for (s.fields) |field| {
-                    // std.log.debug("tuple field: {any}", .{field});
                     if (field.type == void) continue;
 
                     const field_val = @field(value, field.name);
 
-                    try s2e(c.napi_set_property(env, res, try serialize(env, field.name), try serialize(env, field_val)));
+                    try s2e(c.napi_set_property(env, res, try nodeFromNative(env, field.name), try nodeFromNative(env, field_val)));
                 }
             } else {
                 try s2e(c.napi_create_array_with_length(env, s.fields.len, &res));
                 inline for (s.fields, 0..) |field, i| {
-                    // std.log.debug("field: {any}", .{field});
                     if (field.type == void) continue;
 
                     const field_val = @field(value, field.name);
-                    try s2e(c.napi_set_element(env, res, i, try serialize(env, field_val)));
+                    try s2e(c.napi_set_element(env, res, i, try nodeFromNative(env, field_val)));
                 }
             }
         },
@@ -140,7 +134,7 @@ pub fn serialize(env: c.napi_env, value: anytype) !c.napi_value {
                 try s2e(c.napi_create_array_with_length(env, value.len, &res));
 
                 for (value, 0..) |item, i| {
-                    const el = try serialize(env, item);
+                    const el = try nodeFromNative(env, item);
                     try s2e(c.napi_set_element(env, res, i, el));
                 }
             }
@@ -151,62 +145,47 @@ pub fn serialize(env: c.napi_env, value: anytype) !c.napi_value {
 
                 const tag = @as(Tag, value);
                 const tag_name = @tagName(tag);
-                try s2e(c.napi_set_property(env, res, try serialize(env, "type"), try serialize(env, tag_name)));
+                try s2e(c.napi_set_property(env, res, try nodeFromNative(env, "type"), try nodeFromNative(env, tag_name)));
 
                 inline for (u.fields) |f| {
                     if (std.mem.eql(u8, f.name, tag_name)) {
                         if (f.type == void) break;
-                        try s2e(c.napi_set_property(env, res, try serialize(env, "value"), try serialize(env, @field(value, f.name))));
+                        try s2e(c.napi_set_property(env, res, try nodeFromNative(env, "value"), try nodeFromNative(env, @field(value, f.name))));
                         break;
                     }
                 }
             } else {
-                @compileError(std.fmt.comptimePrint("Cannot serialize value of type {s}, untagged unions are not supported.", .{@typeName(T)}));
+                @compileError(std.fmt.comptimePrint("Cannot convert value of type '{s}', untagged unions are not supported.", .{@typeName(T)}));
             }
         },
 
-        else => @compileError(std.fmt.comptimePrint("Cannot serialize value of type {s}", .{@typeName(T)})),
+        else => @compileError(std.fmt.comptimePrint("Cannot convert value of type '{s}'", .{@typeName(T)})),
     }
 
     return res;
 }
 
 /// Converts a Node-API value to a native Zig value.
-pub fn deserialize(env: c.napi_env, comptime T: type, js_value: c.napi_value, allocator: std.mem.Allocator) !T {
+pub fn nativeFromNode(env: c.napi_env, comptime T: type, js_value: c.napi_value, allocator: std.mem.Allocator) !T {
     var res: T = undefined;
 
     switch (@typeInfo(T)) {
         .bool => try s2e(c.napi_get_value_bool(env, js_value, &res)),
         .int => |i| {
             if (i.signedness == .signed) {
                 switch (i.bits) {
-                    32 => {
-                        var tmp: i32 = undefined;
-                        try s2e(c.napi_get_value_int32(env, js_value, &tmp));
-                        // TODO: handle failing int casts
-                        return @intCast(tmp);
-                    },
-                    64 => {
-                        var tmp: i64 = undefined;
-                        try s2e(c.napi_get_value_int64(env, js_value, &tmp));
-                        return @intCast(tmp);
-                    },
-                    else => @compileError(std.fmt.comptimePrint("Cannot deserialize value of type {s}", .{@typeName(T)})),
+                    32 => try s2e(c.napi_get_value_int32(env, js_value, &res)),
+                    64 => try s2e(c.napi_get_value_int64(env, js_value, &res)),
+                    else => @compileError(std.fmt.comptimePrint("Cannot convert node value to '{s}'", .{@typeName(T)})),
                 }
             } else {
                 switch (i.bits) {
-                    0...32 => {
-                        var tmp: u32 = undefined;
-                        try s2e(c.napi_get_value_uint32(env, js_value, &tmp));
-                        return @intCast(tmp);
-                    },
-                    33...64 => {
-                        var tmp: u64 = undefined;
+                    32 => try s2e(c.napi_get_value_uint32(env, js_value, &res)),
+                    64 => {
                         var b: bool = undefined;
-                        try s2e(c.napi_get_value_bigint_uint64(env, js_value, &tmp, &b));
-                        return @intCast(tmp);
+                        try s2e(c.napi_get_value_bigint_uint64(env, js_value, &res, &b));
                     },
-                    else => @compileError(std.fmt.comptimePrint("Cannot deserialize value of type {s}", .{@typeName(T)})),
+                    else => @compileError(std.fmt.comptimePrint("Cannot convert node value to '{s}'", .{@typeName(T)})),
                 }
             }
         },
@@ -234,7 +213,7 @@ pub fn deserialize(env: c.napi_env, comptime T: type, js_value: c.napi_value, al
             try s2e(c.napi_typeof(env, js_value, &t));
             switch (t) {
                 c.napi_undefined, c.napi_null => return null,
-                else => return try deserialize(env, o.child, js_value, allocator),
+                else => return try nativeFromNode(env, o.child, js_value, allocator),
             }
         },
         .pointer => |p| {
@@ -261,7 +240,7 @@ pub fn deserialize(env: c.napi_env, comptime T: type, js_value: c.napi_value, al
                                 for (0..len) |i| {
                                     var elem: c.napi_value = undefined;
                                     try s2e(c.napi_get_element(env, js_value, i, &elem));
-                                    buf[i] = try deserialize(env, p.child, elem, allocator);
+                                    buf[i] = try nativeFromNode(env, p.child, elem, allocator);
                                 }
 
                                 return buf;
@@ -272,7 +251,7 @@ pub fn deserialize(env: c.napi_env, comptime T: type, js_value: c.napi_value, al
                     }
                 },
                 else => {
-                    @compileError("Cannot serialize c-style pointer values, they are not supported.");
+                    @compileError("Cannot convert c-style pointer values, they are not supported.");
                 },
             }
         },
@@ -288,13 +267,13 @@ pub fn deserialize(env: c.napi_env, comptime T: type, js_value: c.napi_value, al
             inline for (s.fields) |field| {
                 var v: c.napi_value = undefined;
                 try s2e(c.napi_get_named_property(env, js_value, field.name.ptr, &v));
-                @field(instance, field.name) = try deserialize(env, field.type, v, allocator);
+                @field(instance, field.name) = try nativeFromNode(env, field.type, v, allocator);
             }
 
             return instance;
         },
 
-        else => @compileError(std.fmt.comptimePrint("Cannot deserialize value of type {s}", .{@typeName(T)})),
+        else => @compileError(std.fmt.comptimePrint("Cannot convert node value to '{s}'", .{@typeName(T)})),
     }
 
     return res;
diff --git a/src/Node.zig b/src/Node.zig
@@ -5,7 +5,7 @@ const c = lib.c;
 const NodeApiError = lib.NodeApiError;
 const s2e = lib.statusToError;
 
-const Serializer = @import("Serializer.zig");
+const Convert = @import("Convert.zig");
 
 const NodeValues = @import("node_values.zig");
 const NodeValue = NodeValues.NodeValue;
@@ -504,12 +504,12 @@ pub const NodeContext = struct {
     pub fn serialize(self: Self, value: anytype) !NodeValue {
         return .{
             .napi_env = self.napi_env,
-            .napi_value = try Serializer.serialize(self.napi_env, value),
+            .napi_value = try Convert.nodeFromNative(self.napi_env, value),
         };
     }
 
     pub fn deserialize(self: Self, comptime T: type, value: NodeValue) !T {
-        return try Serializer.deserialize(self.napi_env, T, value.napi_value, std.heap.c_allocator);
+        return try Convert.nativeFromNode(self.napi_env, T, value.napi_value, std.heap.c_allocator);
     }
 
     pub fn handleError(self: Self, err: anyerror) void {
diff --git a/src/node_values.zig b/src/node_values.zig
@@ -3,7 +3,7 @@ const lib = @import("c.zig");
 const c = lib.c;
 const s2e = lib.statusToError;
 
-const Serializer = @import("Serializer.zig");
+const Convert = @import("Convert.zig");
 
 // https://nodejs.org/api/n-api.html#napi_valuetype
 pub const NodeValueType = enum {
@@ -179,7 +179,7 @@ pub fn NodeFunction(comptime F: anytype) type {
         pub fn call(self: Self, args: TupleTypeOf(f.params)) !f.return_type.? {
             var js_args: [f.params.len]c.napi_value = undefined;
             inline for (0..args.len) |i| {
-                js_args[i] = try Serializer.serialize(self.napi_env, args[i]);
+                js_args[i] = try Convert.nodeFromNative(self.napi_env, args[i]);
             }
             var res: c.napi_value = undefined;
 
@@ -191,7 +191,7 @@ pub fn NodeFunction(comptime F: anytype) type {
             var arena = std.heap.ArenaAllocator.init(std.heap.c_allocator);
             defer arena.deinit();
 
-            return try Serializer.deserialize(self.napi_env, f.return_type.?, res, arena.allocator());
+            return try Convert.nativeFromNode(self.napi_env, f.return_type.?, res, arena.allocator());
         }
     };
 }
diff --git a/src/root.zig b/src/root.zig
@@ -1,7 +1,7 @@
 const std = @import("std");
 
 const c = @import("c.zig").c;
-const Serializer = @import("Serializer.zig");
+const Convert = @import("Convert.zig");
 const NodeValues = @import("node_values.zig");
 /// Represents a Node VM Context.
 pub const NodeContext = @import("Node.zig").NodeContext;
diff --git a/tests/serialization.spec.ts b/tests/serialization.spec.ts
@@ -1,7 +1,7 @@
 import addon from "node-api-test-module";
 import { describe, it, expect } from "bun:test";
 
-describe("Serializer", () => {
+describe("Convert", () => {
   describe("serialize", () => {
     it("utf8 string", () => {
       expect(addon.serialization.serializeString()).toEqual("foo");
diff --git a/tests/zig/test-module.zig b/tests/zig/test-module.zig
@@ -38,7 +38,7 @@ fn init(node: node_api.NodeContext) !?node_api.NodeValue {
     });
 }
 
-fn getInt() i16 {
+fn getInt() i32 {
     return -456 + 45;
 }
 fn getUInt() u16 {

Original file line number	Diff line number	Diff line change
`@@ -38,7 +38,7 @@ fn init(node: node_api.NodeContext) !?node_api.NodeValue {`
`38`	`38`	`});`
`39`	`39`	`}`
`40`	`40`
`41`		`-fn getInt() i16 {`
	`41`	`+fn getInt() i32 {`
`42`	`42`	`return -456 + 45;`
`43`	`43`	`}`
`44`	`44`	`fn getUInt() u16 {`