@thi.ng/wasm-api 1.5.3 → 1.6.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2024-04-25T19:44:55Z
+- **Last updated**: 2024-06-21T19:34:38Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,12 @@ 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.
 
+## [1.6.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/wasm-api@1.6.0) (2024-06-21)
+
+#### 🚀 Features
+
+- update build script & readme for Zig v0.13.0 ([cd401b2](https://github.com/thi-ng/umbrella/commit/cd401b2))
+
 ## [1.5.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/wasm-api@1.5.0) (2024-04-22)
 
 #### 🚀 Features

package/README.md

@@ -7,7 +7,7 @@
 [![Mastodon Follow](https://img.shields.io/mastodon/follow/109331703950160316?domain=https%3A%2F%2Fmastodon.thi.ng&style=social)](https://mastodon.thi.ng/@toxi)
 
 > [!NOTE]
-> This is one of 192 standalone projects, maintained as part
+> This is one of 193 standalone projects, maintained as part
 > of the [@thi.ng/umbrella](https://github.com/thi-ng/umbrella/) monorepo
 > and anti-framework.
 >
@@ -21,7 +21,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.12 or newer](#zig-v012-or-newer)
+  - [Zig v0.13 or newer](#zig-v013-or-newer)
   - [Example projects](#example-projects)
 - [Naming & structural conventions](#naming--structural-conventions)
 - [Status](#status)
@@ -40,6 +40,12 @@
 
 Generic, modular, extensible API bridge and infrastructure for hybrid JS & WebAssembly projects.
 
+| Quasiflock                                                                                                                                        | Danza                                                                                                                                            | S-TRACE                                                                                                                                             | Voxelscape                                                                                                                                                           |
+|---------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| <a href="https://www.fxhash.xyz/generative/6671"><img src="https://github.com/thi-ng/umbrella/raw/develop/assets/fxhash/quasiflock-240.jpg"/></a> | <a href="https://mastodon.thi.ng/@toxi/tagged/DANZA"><img src="https://github.com/thi-ng/umbrella/raw/develop/assets/fxhash/danza-240.jpg"/></a> | <a href="https://mastodon.thi.ng/@toxi/tagged/STRACE"><img src="https://github.com/thi-ng/umbrella/raw/develop/assets/fxhash/s-trace-240.jpg"/></a> | <a href="https://twitter.com/search?q=from%3A%40toxi+voxel+ziglang"><img src="https://github.com/thi-ng/umbrella/raw/develop/assets/fxhash/voxelscape-240.jpg"/></a> |
+
+(Screenshots of selected projects made with Zig & TypeScript using the interop features provided by this package. Images link to respective project info)
+
 This package provides the following:
 
 1. A small
@@ -315,12 +321,14 @@ 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.12 or newer
+### Zig v0.13 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), older Zig
-versions are not actively unsupported (however build files for v0.10 and v0.11
-are still included)
+**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), older Zig
+versions are not actively supported (however, [build files for older versions
+are still
+included](https://github.com/thi-ng/umbrella/blob/develop/packages/wasm-api/zig))
 
 ```zig
 const std = @import("std");

package/bridge.d.ts

@@ -1,4 +1,3 @@
-/// <reference types="node" />
 import type { Event, INotify, IObjectOf, Listener, NumericArray } from "@thi.ng/api";
 import type { ILogger } from "@thi.ng/logger";
 import { type BigIntArray, type BridgeEventType, type CoreAPI, type IWasmAPI, type IWasmMemoryAccess, type MemorySlice, type WasmExports } from "./api.js";
@@ -7,10 +6,10 @@ export declare const Panic: {
         origMessage: string;
         name: string;
         message: string;
-        stack?: string | undefined;
+        stack?: string;
         cause?: unknown;
     };
-    captureStackTrace(targetObject: object, constructorOpt?: Function | undefined): void;
+    captureStackTrace(targetObject: object, constructorOpt?: Function): void;
     prepareStackTrace?: ((err: Error, stackTraces: NodeJS.CallSite[]) => any) | undefined;
     stackTraceLimit: number;
 };
@@ -19,10 +18,10 @@ export declare const OutOfMemoryError: {
         origMessage: string;
         name: string;
         message: string;
-        stack?: string | undefined;
+        stack?: string;
         cause?: unknown;
     };
-    captureStackTrace(targetObject: object, constructorOpt?: Function | undefined): void;
+    captureStackTrace(targetObject: object, constructorOpt?: Function): void;
     prepareStackTrace?: ((err: Error, stackTraces: NodeJS.CallSite[]) => any) | undefined;
     stackTraceLimit: number;
 };

package/bridge.js

@@ -5,8 +5,7 @@ var __decorateClass = (decorators, target, key, kind) => {
   for (var i = decorators.length - 1, decorator; i >= 0; i--)
     if (decorator = decorators[i])
       result = (kind ? decorator(target, key, result) : decorator(result)) || result;
-  if (kind && result)
-    __defProp(target, key, result);
+  if (kind && result) __defProp(target, key, result);
   return result;
 };
 import { INotifyMixin } from "@thi.ng/api/mixins/inotify";
@@ -138,8 +137,7 @@ let WasmBridge = class {
       assert(!!this.modules[id], `missing API module: ${id}`);
       this.logger.debug(`initializing API module: ${id}`);
       const status = await this.modules[id].init(this);
-      if (!status)
-        return false;
+      if (!status) return false;
     }
     this.notify({ id: EVENT_MEMORY_CHANGED, value: this.exports.memory });
     return true;
@@ -155,8 +153,7 @@ let WasmBridge = class {
    */
   ensureMemory(notify = true) {
     const buf = this.exports.memory.buffer;
-    if (this.u8 && this.u8.buffer === buf)
-      return;
+    if (this.u8 && this.u8.buffer === buf) return;
     this.i8 = new Int8Array(buf);
     this.u8 = new Uint8Array(buf);
     this.i16 = new Int16Array(buf);

package/object-index.js

@@ -70,8 +70,7 @@ class ObjectIndex {
    */
   find(pred, ensure = true) {
     for (let id of this.idgen) {
-      if (pred(this.items[id]))
-        return id;
+      if (pred(this.items[id])) return id;
     }
     assert(!ensure, `given predicate matched no ${this.name}`);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/wasm-api",
-  "version": "1.5.3",
+  "version": "1.6.0",
   "description": "Generic, modular, extensible API bridge and infrastructure for hybrid JS & WebAssembly projects",
   "type": "module",
   "module": "./index.js",
@@ -10,7 +10,7 @@
     "type": "git",
     "url": "https://github.com/thi-ng/umbrella.git"
   },
-  "homepage": "https://github.com/thi-ng/umbrella/tree/develop/packages/wasm-api#readme",
+  "homepage": "https://thi.ng/wasm-api",
   "funding": [
     {
       "type": "github",
@@ -32,24 +32,24 @@
     "doc:ae": "mkdir -p .ae/doc .ae/temp && api-extractor run --local --verbose",
     "doc:readme": "bun ../../tools/src/module-stats.ts && bun ../../tools/src/readme.ts",
     "pub": "yarn npm publish --access public",
-    "test": "zig test zig/managed-index.zig && bun test",
+    "test": "zig test zig/tests.zig && bun test",
     "test:build-zig": "zig build-lib -O ReleaseSmall -target wasm32-freestanding -dynamic --strip --pkg-begin wasmapi zig/lib.zig --pkg-end test/custom.zig && wasm-dis -o custom.wast custom.wasm && cp custom.wasm test",
     "tool:tangle": "../../node_modules/.bin/tangle src/**/*.ts"
   },
   "dependencies": {
-    "@thi.ng/api": "^8.11.1",
-    "@thi.ng/arrays": "^2.9.5",
-    "@thi.ng/checks": "^3.6.3",
-    "@thi.ng/errors": "^2.5.6",
-    "@thi.ng/hex": "^2.3.45",
-    "@thi.ng/idgen": "^2.2.40",
-    "@thi.ng/logger": "^3.0.11"
+    "@thi.ng/api": "^8.11.3",
+    "@thi.ng/arrays": "^2.9.7",
+    "@thi.ng/checks": "^3.6.5",
+    "@thi.ng/errors": "^2.5.8",
+    "@thi.ng/hex": "^2.3.47",
+    "@thi.ng/idgen": "^2.2.42",
+    "@thi.ng/logger": "^3.0.13"
   },
   "devDependencies": {
-    "@microsoft/api-extractor": "^7.43.0",
-    "esbuild": "^0.20.2",
-    "typedoc": "^0.25.12",
-    "typescript": "^5.4.3"
+    "@microsoft/api-extractor": "^7.47.0",
+    "esbuild": "^0.21.5",
+    "typedoc": "^0.25.13",
+    "typescript": "^5.5.2"
   },
   "keywords": [
     "allocator",
@@ -115,5 +115,5 @@
     "status": "alpha",
     "year": 2022
   },
-  "gitHead": "aed3421c21044c005fbcb7cc37965ccf85a870d2\n"
+  "gitHead": "154c95cf9d6bab32174498ec3b5b5d87e42be7f9\n"
 }

package/string.js

@@ -50,8 +50,7 @@ class WasmStringSlice {
   set(str) {
     this.mem.ensureMemory();
     if (typeof str === "string") {
-      if (this.isConst)
-        unsupported("can't mutate const string");
+      if (this.isConst) unsupported("can't mutate const string");
       this.mem.u32[this.base + 4 >>> 2] = this.mem.setString(
         str,
         this.addr,
@@ -158,8 +157,7 @@ class WasmStringPtr {
   set(str) {
     const addr = this.addr;
     if (typeof str === "string") {
-      if (this.isConst)
-        unsupported("can't mutate const string");
+      if (this.isConst) unsupported("can't mutate const string");
       this.mem.ensureMemory();
       this.mem.setString(str, addr, this.mem.u8.byteLength - addr, true);
     } else {

package/zig/.zig-cache/o/a32fcfc0e475f08356ed8aef4020640b/dependencies.zig

@@ -0,0 +1,2 @@
+pub const packages = struct {};
+pub const root_deps: []const struct { []const u8, []const u8 } = &.{};

package/zig/build-v0.12.zig

@@ -0,0 +1,130 @@
+//! 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.12.0
+//!
+//! 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 = .{ .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 = modulePath(b.allocator, opts.base, "@thi.ng/wasm-api/zig/lib.zig"),
+        }),
+    );
+    _ = lib.root_module.addImport(
+        wasmbind,
+        b.createModule(.{
+            .root_source_file = 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 = 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) Build.LazyPath {
+    return .{ .path = std.fs.path.join(allocator, &.{ base, path }) catch unreachable };
+}

package/zig/build.zig

@@ -2,7 +2,7 @@
 //! Intended for use with https://thi.ng/wasm-api and support packages
 //!
 //! This version of the script is only compatible with:
-//! Zig v0.12.0 or newer
+//! Zig v0.13.0
 //!
 //! Use other build.zig files in this same directory for older Zig versions
 
@@ -53,7 +53,7 @@ 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 = .{ .path = opts.root },
+        .root_source_file = b.path(opts.root),
         .target = b.resolveTargetQuery(
             .{
                 .cpu_arch = .wasm32,
@@ -78,13 +78,13 @@ pub fn wasmLib(b: *Build, opts: WasmLibOpts) *Build.Step.Compile {
     _ = lib.root_module.addImport(
         wasmapi,
         b.createModule(.{
-            .root_source_file = modulePath(b.allocator, opts.base, "@thi.ng/wasm-api/zig/lib.zig"),
+            .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 = modulePath(b.allocator, opts.base, "@thi.ng/wasm-api-bindgen/zig/lib.zig"),
+            .root_source_file = b.path(modulePath(b.allocator, opts.base, "@thi.ng/wasm-api-bindgen/zig/lib.zig")),
         }),
     );
     if (opts.modules) |modules| {
@@ -113,7 +113,7 @@ pub fn register(lib: *Build.Step.Compile, mod: ModuleSpec, opts: WasmLibOpts) vo
         }
     }
     _ = lib.root_module.addImport(mod.name, lib.step.owner.createModule(.{
-        .root_source_file = modulePath(lib.step.owner.allocator, opts.base, mod.path),
+        .root_source_file = lib.step.owner.path(modulePath(lib.step.owner.allocator, opts.base, mod.path)),
         .imports = dpkgs[0..i],
     }));
 }
@@ -125,6 +125,6 @@ fn isDuplicateId(deps: []Build.Module.Import, name: []const u8) bool {
     return false;
 }
 
-fn modulePath(allocator: std.mem.Allocator, base: []const u8, path: []const u8) Build.LazyPath {
-    return .{ .path = std.fs.path.join(allocator, &.{ base, path }) catch unreachable };
+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/tests.zig

@@ -0,0 +1,4 @@
+test {
+    _ = @import("managed-index.zig");
+    _ = @import("lib.zig");
+}