@thi.ng/wasm-api 2.3.31 → 2.4.1

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2025-08-04T09:13:01Z
+- **Last updated**: 2025-09-02T13:15:31Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -11,6 +11,22 @@ See [Conventional Commits](https://conventionalcommits.org/) for commit guidelin
 **Note:** Unlisted _patch_ versions only involve non-code or otherwise excluded changes
 and/or version bumps of transitive dependencies.
 
+### [2.4.1](https://github.com/thi-ng/umbrella/tree/@thi.ng/wasm-api@2.4.1) (2025-09-02)
+
+#### ♻️ Refactoring
+
+- update zig `_wasm_allocate()`  & `ManagedIndex` ([3e8870c](https://github.com/thi-ng/umbrella/commit/3e8870c))
+  - store allocator in `ManagedIndex` due to Zig ArrayList defaulting to unmanaged in 0.15.1
+    and managed versions will be removed in future
+  - fix alignment param in `_wasm_allocate()`
+
+## [2.4.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/wasm-api@2.4.0) (2025-09-01)
+
+#### 🚀 Features
+
+- update Zig build file for Zig v0.15.1 ([ddb2402](https://github.com/thi-ng/umbrella/commit/ddb2402))
+  - set Zig workspace version to 0.15.1
+
 ### [2.3.12](https://github.com/thi-ng/umbrella/tree/@thi.ng/wasm-api@2.3.12) (2025-03-11)
 
 #### ♻️ Refactoring

package/README.md

@@ -22,7 +22,7 @@
   - [API module auto-initialization](#api-module-auto-initialization)
 - [Object indices & handles](#object-indices--handles)
 - [Using the Zig build system](#using-the-zig-build-system)
-  - [Zig v0.14 or newer](#zig-v014-or-newer)
+  - [Zig v0.15 or newer](#zig-v015-or-newer)
   - [Example projects](#example-projects)
 - [Naming & structural conventions](#naming--structural-conventions)
 - [Status](#status)
@@ -379,15 +379,13 @@ This package provides utilities to simplify using hybrid TS/Zig WASM API modules
 which are distributed as NPM packages. Using these utils, a build file for Zig's
 built-in build system is as simple as:
 
-### Zig v0.14 or newer
+### Zig v0.15 or newer
 
-**IMPORTANT:** Due to recent syntax & build system changes in Zig
-[v0.12.0](https://ziglang.org/download/0.12.0/release-notes.html),
-[v0.13.0](https://ziglang.org/download/0.13.0/release-notes.html) and
-[v0.14.0](https://ziglang.org/download/0.14.0/release-notes.html), older Zig
-versions are not actively supported anymore (however, [build files for older
-versions are still
-included](https://github.com/thi-ng/umbrella/blob/develop/packages/wasm-api/zig))
+**IMPORTANT:** Due to breaking syntax & build system changes in recent Zig
+versions, older Zig versions than
+[v0.15.1](https://ziglang.org/download/0.15.1/release-notes.html), are not
+actively supported anymore (however, [build files for older versions are still
+included](https://github.com/thi-ng/umbrella/blob/develop/packages/wasm-api/zig)).
 
 Please see [bundled examples](#usage-examples) for more details...
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/wasm-api",
-  "version": "2.3.31",
+  "version": "2.4.1",
   "description": "Generic, modular, extensible API bridge and infrastructure for hybrid JS & WebAssembly projects",
   "type": "module",
   "module": "./index.js",
@@ -42,17 +42,17 @@
     "tool:tangle": "../../node_modules/.bin/tangle src/**/*.ts"
   },
   "dependencies": {
-    "@thi.ng/api": "^8.12.1",
-    "@thi.ng/arrays": "^2.13.10",
-    "@thi.ng/checks": "^3.7.17",
-    "@thi.ng/errors": "^2.5.41",
-    "@thi.ng/hex": "^2.3.79",
-    "@thi.ng/idgen": "^2.2.75",
-    "@thi.ng/logger": "^3.1.16"
+    "@thi.ng/api": "^8.12.2",
+    "@thi.ng/arrays": "^2.13.11",
+    "@thi.ng/checks": "^3.7.18",
+    "@thi.ng/errors": "^2.5.42",
+    "@thi.ng/hex": "^2.3.80",
+    "@thi.ng/idgen": "^2.2.76",
+    "@thi.ng/logger": "^3.1.17"
   },
   "devDependencies": {
-    "esbuild": "^0.25.8",
-    "typedoc": "^0.28.9",
+    "esbuild": "^0.25.9",
+    "typedoc": "^0.28.12",
     "typescript": "^5.9.2"
   },
   "keywords": [
@@ -126,5 +126,5 @@
     "tag": "wasm",
     "year": 2022
   },
-  "gitHead": "f6ebc1302dc9211d588293aa0897173c6e54f4e5\n"
+  "gitHead": "4ebea5f30d4e2d28a12dfb01b39533fdfda0ab43\n"
 }

package/zig/build-v0.14.zig

@@ -0,0 +1,131 @@
+// SPDX-License-Identifier: Apache-2.0
+//! Build helpers for using modules/packages distributed via NPM
+//! Intended for use with https://thi.ng/wasm-api and support packages
+//!
+//! This version of the script is only compatible with:
+//! Zig v0.14.1
+//!
+//! Use other build.zig files in this same directory for older Zig versions
+
+const std = @import("std");
+const Build = std.Build;
+
+/// Config options
+pub const WasmLibOpts = struct {
+    /// Base path to common node_modules directory under which
+    /// all to be imported modules are located
+    base: []const u8 = "node_modules",
+    /// Relative path to root source file
+    root: []const u8 = "zig/main.zig",
+    /// Additional WASM API support modules.
+    /// Only need to specify custom/extra modules
+    /// `wasm-api` and `wasm-api-bindgen` are auto-added as dependency for all...
+    modules: ?[]const ModuleSpec = null,
+    /// Build mode override (else allows config via CLI args)
+    optimize: ?std.builtin.Mode = null,
+    /// Additional WASM target features, e.g. `.simd128` to enable SIMD
+    features: ?[]const std.Target.wasm.Feature = null,
+    /// Initial memory (in bytes, MUST be multiple of 0x10000)
+    initialMemory: ?u64 = null,
+    /// Max memory (in bytes, MUST be multiple of 0x10000)
+    maxMemory: ?u64 = null,
+    // If true, build will also generate docs
+    // docs: bool = false,
+};
+
+/// WASM API sub-module declaration
+pub const ModuleSpec = struct {
+    /// module import name/ID
+    name: []const u8,
+    /// Relative path to configured base path
+    path: []const u8,
+    /// Module IDs of other modules this module depends on
+    /// Only need to specify custom/extra modules
+    /// `wasm-api` and `wasm-api-bindgen` are auto-added as dependency for all...
+    dependencies: ?[]const []const u8 = null,
+};
+
+const wasmapi = "wasm-api";
+const wasmbind = "wasm-api-bindgen";
+
+/// Creates and returns a build step to build a dynamic WASM library, configured
+/// with given options and package declarations. The given package specs will be inserted
+pub fn wasmLib(b: *Build, opts: WasmLibOpts) *Build.Step.Compile {
+    const optimize = if (opts.optimize) |m| m else b.standardOptimizeOption(.{});
+    const lib = b.addExecutable(.{
+        .name = "main",
+        .root_source_file = b.path(opts.root),
+        .target = b.resolveTargetQuery(
+            .{
+                .cpu_arch = .wasm32,
+                .os_tag = .freestanding,
+                .cpu_features_add = if (opts.features) |features| std.Target.wasm.featureSet(features) else std.Target.Cpu.Feature.Set.empty,
+            },
+        ),
+        .optimize = optimize,
+        .strip = (optimize == .ReleaseSmall or optimize == .ReleaseFast),
+    });
+
+    // build flags
+    // https://github.com/ziglang/zig/pull/17815
+    lib.entry = .disabled;
+    lib.rdynamic = true;
+    lib.import_symbols = true;
+    lib.initial_memory = opts.initialMemory;
+    lib.max_memory = opts.maxMemory;
+
+    // add default dependencies
+    // https://ziggit.dev/t/what-happened-to-addmodule/2908/3
+    _ = lib.root_module.addImport(
+        wasmapi,
+        b.createModule(.{
+            .root_source_file = b.path(modulePath(b.allocator, opts.base, "@thi.ng/wasm-api/zig/lib.zig")),
+        }),
+    );
+    _ = lib.root_module.addImport(
+        wasmbind,
+        b.createModule(.{
+            .root_source_file = b.path(modulePath(b.allocator, opts.base, "@thi.ng/wasm-api-bindgen/zig/lib.zig")),
+        }),
+    );
+    if (opts.modules) |modules| {
+        for (modules) |mod| register(lib, mod, opts);
+    }
+    return lib;
+}
+
+/// Registers a single package and its deps (also injects core wasm-api deps)
+pub fn register(lib: *Build.Step.Compile, mod: ModuleSpec, opts: WasmLibOpts) void {
+    const num = if (mod.dependencies) |ids| ids.len else 0;
+    var dpkgs = lib.step.owner.allocator.alloc(Build.Module.Import, num + 2) catch unreachable;
+    dpkgs[0] = if (lib.root_module.import_table.get(wasmapi)) |m| .{ .name = wasmapi, .module = m } else unreachable;
+    dpkgs[1] = if (lib.root_module.import_table.get(wasmbind)) |m| .{ .name = wasmbind, .module = m } else unreachable;
+    var i: usize = 2;
+    if (mod.dependencies) |ids| {
+        for (ids) |id| {
+            if (lib.root_module.import_table.get(id)) |m| {
+                if (isDuplicateId(dpkgs[0..i], id)) {
+                    std.log.info("ignoring duplicate dependency: {s}", .{id});
+                    continue;
+                }
+                dpkgs[i] = .{ .name = id, .module = m };
+                i += 1;
+            } else @panic("unknown dependency");
+        }
+    }
+    _ = lib.root_module.addImport(mod.name, lib.step.owner.createModule(.{
+        .root_source_file = lib.step.owner.path(modulePath(lib.step.owner.allocator, opts.base, mod.path)),
+        .imports = dpkgs[0..i],
+    }));
+}
+
+fn isDuplicateId(deps: []Build.Module.Import, name: []const u8) bool {
+    for (deps) |d| {
+        if (std.mem.eql(u8, d.name, name)) return true;
+    }
+    return false;
+}
+
+fn modulePath(allocator: std.mem.Allocator, base: []const u8, path: []const u8) []u8 {
+    return std.fs.path.join(allocator, &.{ base, path }) catch unreachable;
+}

package/zig/build.zig

@@ -22,7 +22,7 @@ pub const WasmLibOpts = struct {
     /// `wasm-api` and `wasm-api-bindgen` are auto-added as dependency for all...
     modules: ?[]const ModuleSpec = null,
     /// Build mode override (else allows config via CLI args)
-    optimize: ?std.builtin.Mode = null,
+    optimize: ?std.builtin.OptimizeMode = null,
     /// Additional WASM target features, e.g. `.simd128` to enable SIMD
     features: ?[]const std.Target.wasm.Feature = null,
     /// Initial memory (in bytes, MUST be multiple of 0x10000)
@@ -54,16 +54,18 @@ pub fn wasmLib(b: *Build, opts: WasmLibOpts) *Build.Step.Compile {
     const optimize = if (opts.optimize) |m| m else b.standardOptimizeOption(.{});
     const lib = b.addExecutable(.{
         .name = "main",
-        .root_source_file = b.path(opts.root),
-        .target = b.resolveTargetQuery(
-            .{
-                .cpu_arch = .wasm32,
-                .os_tag = .freestanding,
-                .cpu_features_add = if (opts.features) |features| std.Target.wasm.featureSet(features) else std.Target.Cpu.Feature.Set.empty,
-            },
-        ),
-        .optimize = optimize,
-        .strip = (optimize == .ReleaseSmall or optimize == .ReleaseFast),
+        .root_module = b.createModule(.{
+            .root_source_file = b.path(opts.root),
+            .target = b.resolveTargetQuery(
+                .{
+                    .cpu_arch = .wasm32,
+                    .os_tag = .freestanding,
+                    .cpu_features_add = if (opts.features) |features| std.Target.wasm.featureSet(features) else std.Target.Cpu.Feature.Set.empty,
+                },
+            ),
+            .optimize = optimize,
+            .strip = (optimize == .ReleaseSmall or optimize == .ReleaseFast),
+        }),
     });
 
     // build flags

package/zig/lib.zig

@@ -52,7 +52,7 @@ pub inline fn allocator() ?std.mem.Allocator {
 /// Note: For SIMD compatibility all allocations are aligned to 16 bytes
 pub export fn _wasm_allocate(numBytes: usize) usize {
     if (allocator()) |alloc| {
-        const mem = alloc.alignedAlloc(u8, 16, numBytes) catch return 0;
+        const mem = alloc.alignedAlloc(u8, .@"16", numBytes) catch return 0;
         return @intFromPtr(mem.ptr);
     }
     return 0;

package/zig/managed-index.zig

@@ -24,6 +24,7 @@ pub fn ManagedIndex(comptime T: type, comptime I: type) type {
     };
 
     return struct {
+        allocator: Allocator,
         /// backing array list
         list: std.ArrayList(Item),
         /// Index of the head of the implicitly stored list of free slots
@@ -37,22 +38,24 @@ pub fn ManagedIndex(comptime T: type, comptime I: type) type {
         const Self = @This();
 
         /// Initializes the underlying array list
-        pub fn init(allocator: Allocator) Self {
+        pub fn init(alloc: Allocator) Self {
             return .{
-                .list = std.ArrayList(Item).init(allocator),
+                .allocator = alloc,
+                .list = std.ArrayList(Item).empty,
             };
         }
 
         /// Initializes the underlying array list with given initial capacity
-        pub fn initCapacity(allocator: Allocator, num: usize) !Self {
+        pub fn initCapacity(alloc: Allocator, num: usize) Allocator.Error!Self {
             return .{
-                .list = try std.ArrayList(Item).initCapacity(allocator, num),
+                .allocator = alloc,
+                .list = try std.ArrayList(Item).initCapacity(alloc, num),
             };
         }
 
         /// De-initializes the underlying array list
         pub fn deinit(self: *Self) void {
-            self.list.deinit();
+            self.list.deinit(self.allocator);
         }
 
         /// Clears, frees & resets this list and its backing array list.
@@ -72,7 +75,7 @@ pub fn ManagedIndex(comptime T: type, comptime I: type) type {
                 return @intCast(id);
             } else {
                 const id = self.list.items.len;
-                try self.list.append(.{ .value = item });
+                try self.list.append(self.allocator, .{ .value = item });
                 self.used += 1;
                 return @intCast(id);
             }
@@ -179,53 +182,53 @@ test "ManagedIndex" {
     const expect = std.testing.expect;
     const expectEqualSlices = std.testing.expectEqualSlices;
 
-    var list = ManagedIndex(f64, u8).init(allocator);
-    defer list.deinit();
-    try expect(try list.add(123) == 0);
-    try expect(try list.add(123) == 1);
+    var index = ManagedIndex(f64, u8).init(allocator);
+    defer index.deinit();
+    try expect(try index.add(123) == 0);
+    try expect(try index.add(123) == 1);
 
-    try expect(list.has(0));
-    try expect(list.has(1));
-    try expect(list.used == 2);
+    try expect(index.has(0));
+    try expect(index.has(1));
+    try expect(index.used == 2);
 
-    list.remove(0);
-    try expect(!list.has(0));
-    try expect(!list.has(2));
-    try expect(list.used == 1);
+    index.remove(0);
+    try expect(!index.has(0));
+    try expect(!index.has(2));
+    try expect(index.used == 1);
 
-    try expect(try list.add(123) == 0);
-    try expect(try list.add(123) == 2);
-    try expect(list.has(2));
-    try expect(list.used == 3);
+    try expect(try index.add(123) == 0);
+    try expect(try index.add(123) == 2);
+    try expect(index.has(2));
+    try expect(index.used == 3);
 
-    list.remove(1);
-    list.remove(2);
+    index.remove(1);
+    index.remove(2);
 
-    const ids = try list.freeIndicesAsSlice(allocator);
+    const ids = try index.freeIndicesAsSlice(allocator);
     defer allocator.free(ids);
     try expectEqualSlices(u8, &[_]u8{ 2, 1 }, ids);
 
-    try expect(try list.add(202) == 2);
-    list.remove(0);
-    try expect(try list.add(200) == 0);
-    try expect(try list.add(201) == 1);
-    try expect(list.freeID == null);
+    try expect(try index.add(202) == 2);
+    index.remove(0);
+    try expect(try index.add(200) == 0);
+    try expect(try index.add(201) == 1);
+    try expect(index.freeID == null);
 
-    var iter = list.values();
+    var iter = index.values();
     try expect(if (iter.next()) |v| v == 200 else false);
     try expect(if (iter.next()) |v| v == 201 else false);
     try expect(if (iter.next()) |v| v == 202 else false);
     try expect(iter.next() == null);
 
-    const slice = try list.valuesAsSlice(allocator);
+    const slice = try index.valuesAsSlice(allocator);
     defer allocator.free(slice);
     try expectEqualSlices(f64, &[_]f64{ 200, 201, 202 }, slice);
 
-    list.remove(0);
-    list.remove(2);
-    list.remove(1);
+    index.remove(0);
+    index.remove(2);
+    index.remove(1);
 
-    const ids2 = try list.freeIndicesAsSlice(allocator);
+    const ids2 = try index.freeIndicesAsSlice(allocator);
     defer allocator.free(ids2);
     try expectEqualSlices(u8, &[_]u8{ 1, 2, 0 }, ids2);
 }