{"id":14990790,"url":"https://github.com/nelipuu/zbind","last_synced_at":"2025-04-05T00:06:08.696Z","repository":{"id":222195899,"uuid":"755293768","full_name":"nelipuu/zbind","owner":"nelipuu","description":"Zig-TypeScript binding generator 🟦 🦎","archived":false,"fork":false,"pushed_at":"2025-01-25T14:28:15.000Z","size":110,"stargazers_count":131,"open_issues_count":1,"forks_count":3,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-28T23:04:12.421Z","etag":null,"topics":["bun","javascript","node","typescript","wasm","zig","ziglang"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"0bsd","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nelipuu.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-02-09T20:35:47.000Z","updated_at":"2025-03-24T07:44:52.000Z","dependencies_parsed_at":"2024-02-25T00:25:34.506Z","dependency_job_id":"c0fe7f40-0777-40a3-9f09-24a07fcb1bf8","html_url":"https://github.com/nelipuu/zbind","commit_stats":{"total_commits":41,"total_committers":1,"mean_commits":41.0,"dds":0.0,"last_synced_commit":"70c23cb7240055b672675eb19cf97cf9c02640c5"},"previous_names":["nelipuu/zbind"],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nelipuu%2Fzbind","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nelipuu%2Fzbind/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nelipuu%2Fzbind/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nelipuu%2Fzbind/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nelipuu","download_url":"https://codeload.github.com/nelipuu/zbind/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247266563,"owners_count":20910836,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bun","javascript","node","typescript","wasm","zig","ziglang"],"created_at":"2024-09-24T14:20:51.112Z","updated_at":"2025-04-05T00:06:08.664Z","avatar_url":"https://github.com/nelipuu.png","language":"TypeScript","readme":"![zbind](https://github.com/nelipuu/zbind/assets/778781/302eee21-1ff4-4e13-868b-05a71532fac9)\n\n# zbind\n\n`zbind` generates TypeScript bindings for calling Zig code compiled to native code or Wasm, in Node.js or Bun or browsers.\n\nSupported Zig versions are 0.11.0 - 0.13.0 (and at least some 0.14.0 dev versions as well).\nZig 0.13.0 seems to have an issue linking with C++ code when targeting Wasm, that has been fixed in later development versions.\n\nExample Zig code [`lib/main.zig`](example/lib/main.zig):\n\n```Zig\nconst std = @import(\"std\");\nconst zbind = @import(\"zbind\");\n\npub fn hello(name: []const u8) void {\n    std.debug.print(\"Hello, {s}!\\n\", .{ name });\n}\n\ncomptime {\n    zbind.init(@This());\n}\n```\n\nIt exports a Zig function `hello`, callable from TypeScript. A wrapper function will be exported that receives a string pointer and length in memory shared between Zig and the JavaScript engine.\n\nExample TypeScript code [`src/index.ts`](example/src/index.ts) to call it:\n\n```TypeScript\nimport { hello } from './greet.js';\n\nhello('World');\n```\n\nThe automatically generated TypeScript function will encode the string as UTF-8 in a buffer directly accessible by both languages.\n\nThe Zig code requires a [`build.zig`](example/build.zig) script to compile it:\n\n```Zig\nconst std = @import(\"std\");\nconst zbind = @import(\"node_modules/zbind/zbind.zig\");\n\npub fn build(builder: *std.Build) !void {\n    const lib = try zbind.build(.{ //\n        .builder = builder,\n        .main = \"lib/main.zig\",\n        .out = \"dist/addon\"\n    });\n\n    lib.linkLibC();\n}\n```\n\nThe `zbind.build` call returns a `*std.Build.Step.Compile` object for linking with other libraries if needed.\n\nRun these shell commands to compile the code and generate TypeScript bindings:\n\n```bash\nnpm install --save zbind\nnpm install --save-dev node-api-headers\n\n# For native\nzig build -Doptimize=ReleaseFast\nnpx zbind dist/addon.node src/greet.ts\n\n# For Wasm\nzig build -Doptimize=ReleaseSmall -Dtarget=wasm32-wasi\nnpx zbind dist/addon.wasm src/greet.ts\n```\n\nThe commands compile the Zig code to a native or Wasm binary and then call a TypeScript-based tool to inspect it and generate wrapper functions in `src/greet.ts` with matching types and necessary marshalling.\n\nTo install Zig from NPM you can do:\n\n```\nnpm install --save-dev @oven/zig\n```\n\n## Supported data types\n\n| Zig          | TypeScript          | Notes |\n|--------------|---------------------|-------|\n| `bool`       | `boolean`           |       |\n| `u8` - `u32` | `number`            | Conversion from `number` rounds down, throws if outside range. |\n| `i8` - `i32` | `number`            | Conversion from `number` rounds towards 0, throws if outside range. |\n| `f32`, `f64` | `number`            |       |\n| `u64`, `i64` | `bigint`            |       |\n| `[]u8`       | `Slice`, `string`   | `Slice` of `u8` has a `toString` method for automatic coercion.\u003cbr\u003eStrings are passed through a stack. |\n| `struct`     | `OpaqueStruct`      | TypeScript takes ownership of opaque structs passed by value\u003cbr\u003esuch as `std.mem.Allocator` |\n| `?`any above | any above `\\| null` |       |\n\nSupport is planned for more slice types, pointers, error unions, callbacks and accessing struct fields and methods.\n\n## Architecture\n\nGenerated TypeScript bindings are identical for Wasm and Node-API. Values are marshalled using a separate one-megabyte stack mostly accessed through a `[]f64` / `Float64Array`. Since `f64` can represent 53-bit integers, it fits pointers to memory as well. `null` is passed as a special NaN bit pattern.\n\nWhen compiled, `zbind.zig` analyzes argument and return types of Zig functions at comptime, stores the metadata in a compact binary representation and defines special endpoints for querying functions and types. It generates Zig wrapper functions for Zig methods to handle type marshalling and reports a list of pointers to those functions when initialized.\n\nThe `zbind` command line tool loads the compiled binary and queries its metadata endpoints to generate a TypeScript wrapper for each Zig function which calls it automatically converting types. The tool writes out TypeScript source code defining and exporting the wrapper functions.\n\nAfter importing the generated file in your own TypeScript code and making the first call to Zig code through it, the bindings load the compiled binary.\n\n# License\n\n0BSD, which means use as you wish and no need to mention this project or its author. Consider it public domain in practice.\n","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnelipuu%2Fzbind","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnelipuu%2Fzbind","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnelipuu%2Fzbind/lists"}