zignapi 0.1.1 → 0.2.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.2.0",
     .fingerprint = 0x582024f92c57df77, // Changing this has security and trust implications.
     .minimum_zig_version = "0.16.0",
     .dependencies = .{},

package/native/src/napi.zig

@@ -60,3 +60,10 @@ 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;
+}

package/native/src/register.zig

@@ -12,6 +12,7 @@
 const std = @import("std");
 const napi = @import("napi.zig");
 const convert = @import("convert.zig");
+const typedefs = @import("typedefs.zig");
 const c = napi.c;
 
 /// Export `napi_register_module_v1` for the given set of functions.
@@ -27,6 +28,10 @@ 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| {
@@ -36,6 +41,11 @@ pub fn register(comptime defs: anytype) void {
                     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;
         }
     };

package/native/src/typedefs.zig

@@ -0,0 +1,77 @@
+//! 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 convert = @import("convert.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`.
+pub fn tsType(comptime T: type) []const u8 {
+    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.
+/// Parameter names aren't available from `@typeInfo`, so they're `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";
+        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.?) },
+            );
+        }
+        out = out ++ "export function " ++ field.name ++ "(" ++ params ++
+            "): " ++ tsType(fn_info.return_type.?) ++ ";\n";
+    }
+    return out;
+}
+
+test "declarations render one export per function" {
+    const S = struct {
+        fn add(a: i32, b: i32) i32 {
+            return a + b;
+        }
+        fn greet(name: []const u8) []const u8 {
+            return name;
+        }
+        fn toggle(x: bool) bool {
+            return !x;
+        }
+        fn checked(x: i32) !i32 {
+            return x;
+        }
+    };
+    const dts = comptime declarations(.{
+        .add = S.add,
+        .greet = S.greet,
+        .toggle = S.toggle,
+        .checked = S.checked,
+    });
+    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;
+        \\
+    , dts);
+}

package/native/src/zignapi.zig

@@ -12,6 +12,7 @@ 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`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zignapi",
-  "version": "0.1.1",
+  "version": "0.2.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/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,9 @@ test("add(2, 3) === 5", () => {
 test("greet returns a string", () => {
   assert.strictEqual(addon.greet("world"), "hello from Zig");
 });
+
+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;/);
+});