@thi.ng/wasm-api 0.17.2 → 0.18.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2022-10-30T13:56:23Z
+- **Last updated**: 2022-10-31T23:01:45Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,26 @@ 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.
 
+## [0.18.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/wasm-api@0.18.0) (2022-10-31)
+
+#### 🚀 Features
+
+- update WasmBridge & child API module specs ([6773494](https://github.com/thi-ng/umbrella/commit/6773494))
+  - update IWasmAPI interface to declare import ID & module dependencies
+  - update WasmBridge ctor (array instead of object of sub-modules)
+  - update WasmBridge.init() to initialize modules in dependency order
+  - replace illegalArgs() with assert()
+  - add [@thi.ng/arrays](https://github.com/thi-ng/umbrella/tree/main/packages/arrays) as dependency, update pkg
+
+### [0.17.3](https://github.com/thi-ng/umbrella/tree/@thi.ng/wasm-api@0.17.3) (2022-10-31)
+
+#### ♻️ Refactoring
+
+- restructure/rename zig files, update readdme ([c63ca10](https://github.com/thi-ng/umbrella/commit/c63ca10))
+  - enforce uniform project structure for all `[@thi.ng/wasm-api-](https://github.com/thi-ng/umbrella/tree/main/packages/wasm-api-)*` packages
+  - rename /zig/wasmapi.zig => /zig/lib.zig
+  - update readme w/ further info
+
 ### [0.17.1](https://github.com/thi-ng/umbrella/tree/@thi.ng/wasm-api@0.17.1) (2022-10-30)
 
 #### ♻️ Refactoring

package/README.md

@@ -17,6 +17,7 @@ This project is part of the
   - [String handling](#string-handling)
   - [Memory allocations](#memory-allocations)
   - [Custom API modules](#custom-api-modules)
+  - [Building Zig projects with these hybrid API modules](#building-zig-projects-with-these-hybrid-api-modules)
   - [Object indices & handles](#object-indices--handles)
 - [Status](#status)
 - [Support packages](#support-packages)
@@ -450,7 +451,7 @@ The actual allocator is implementation specific and suitable generic mechanisms
 are defined for both the included Zig & C bindings. Please see for further
 reference:
 
-- [`/zig/wasmapi.zig`](https://github.com/thi-ng/umbrella/blob/develop/packages/wasm-api/zig/wasmapi.zig#L64):
+- [`/zig/lib.zig`](https://github.com/thi-ng/umbrella/blob/develop/packages/wasm-api/zig/lib.zig#L64):
   comments about WASM-side allocator handling in Zig
 - [`/include/wasmapi.h`](https://github.com/thi-ng/umbrella/blob/develop/packages/wasm-api/include/wasmapi.h#L18):
   comments about WASM-side allocator handling in C/C++
@@ -504,6 +505,13 @@ following example provides a brief overview:
 import { IWasmAPI, WasmBridge } from "@thi.ng/wasm-api";
 
 export class CustomAPI implements IWasmAPI {
+	// Unique API module identifier to group WASM imports,
+	// must match ID used by native code (see further below).
+	readonly id = "custom";
+	// optionally list IDs of other API modules this module depends on
+	// these are used to infer the correct initialization order
+	readonly dependencies = [];
+
 	parent!: WasmBridge;
 
 	async init(parent: WasmBridge) {
@@ -537,13 +545,12 @@ export class CustomAPI implements IWasmAPI {
 Now we can supply this custom API when creating the main WASM bridge:
 
 ```ts
-export const bridge = new WasmBridge({ custom: new CustomAPI() });
+export const bridge = new WasmBridge([new CustomAPI()]);
 ```
 
 In Zig (or any other language of your choice) we can then utilize this custom
-API like so (Please also see
-[tests](https://github.com/thi-ng/umbrella/tree/develop/packages/wasm-api/test)
-& other examples in this readme):
+API like so (Please also see [example projects](https://github.com/thi-ng/umbrella/tree/develop/examples/zig-canvas/)
+& other example snippets in this readme):
 
 Bindings file / lib:
 
@@ -579,6 +586,19 @@ export fn test_randomVec4() void {
 }
 ```
 
+### Building Zig projects with these hybrid API modules
+
+Some example projects (see [list below](#usage-examples)) provide custom
+[`build.zig`](https://github.com/thi-ng/umbrella/blob/develop/examples/zig-canvas/build.zig)
+&
+[`npm.zig`](https://github.com/thi-ng/umbrella/blob/develop/examples/zig-canvas/npm.zig)
+build scripts to easily integrate these hybrid TS/Zig packages into users'
+development processes.
+
+To avoid guesswork about the internals of these API modules, all of them are
+using an overall uniform structure, with the main Zig entry point in
+`/zig/lib.zig`...
+
 ### Object indices & handles
 
 Since only numeric values can be exchanged between the WASM module and the JS
@@ -630,7 +650,9 @@ Since v0.15.0, the supplied Zig core bindings lib also includes a
 [`ManagedIndex`](https://github.com/thi-ng/umbrella/blob/develop/packages/wasm-api/zig/managed-index.zig)
 for similar dealings on the Zig side of the application. For example, in the
 [@thi.ng/wasm-api-dom](https://github.com/thi-ng/umbrella/blob/develop/packages/wasm-api-dom/)
-module this is used to manage Zig event listeners.
+&
+[@thi.ng/wasm-api-timer](https://github.com/thi-ng/umbrella/blob/develop/packages/wasm-api-timer/)
+modules this is used to manage Zig event listeners.
 
 ## Status
 
@@ -640,7 +662,8 @@ module this is used to manage Zig event listeners.
 
 ## Support packages
 
-- [@thi.ng/wasm-api-dom](https://github.com/thi-ng/umbrella/tree/develop/packages/wasm-api-dom) - Browser DOM bridge API for hybrid TypeScript & Zig applications
+- [@thi.ng/wasm-api-dom](https://github.com/thi-ng/umbrella/tree/develop/packages/wasm-api-dom) - Browser DOM bridge API for hybrid TypeScript & WASM (Zig) applications
+- [@thi.ng/wasm-api-timer](https://github.com/thi-ng/umbrella/tree/develop/packages/wasm-api-timer) - Delayed & scheduled function execution (via setTimeout() etc.) for hybrid WASM apps
 
 ## Installation
 
@@ -665,16 +688,17 @@ node --experimental-repl-await
 > const wasmApi = await import("@thi.ng/wasm-api");
 ```
 
-Package sizes (gzipped, pre-treeshake): ESM: 7.06 KB
+Package sizes (gzipped, pre-treeshake): ESM: 7.13 KB
 
-**IMPORTANT:** The package includes code generators for various languages which
-are **not** required for just using the API bridge. Hence, the usual package
+**IMPORTANT:** The package includes multiple language code generators which are
+**not** required for normal use of the API bridge. Hence, the actual package
 size in production will be MUCH smaller than what's stated here!
 
 ## Dependencies
 
 - [@thi.ng/api](https://github.com/thi-ng/umbrella/tree/develop/packages/api)
 - [@thi.ng/args](https://github.com/thi-ng/umbrella/tree/develop/packages/args)
+- [@thi.ng/arrays](https://github.com/thi-ng/umbrella/tree/develop/packages/arrays)
 - [@thi.ng/binary](https://github.com/thi-ng/umbrella/tree/develop/packages/binary)
 - [@thi.ng/checks](https://github.com/thi-ng/umbrella/tree/develop/packages/checks)
 - [@thi.ng/compare](https://github.com/thi-ng/umbrella/tree/develop/packages/compare)
@@ -757,7 +781,7 @@ folder):
 ```bash
 # compile WASM binary
 zig build-lib \
-	--pkg-begin wasmapi node_modules/@thi.ng/wasm-api/zig/wasmapi.zig --pkg-end \
+	--pkg-begin wasmapi node_modules/@thi.ng/wasm-api/zig/lib.zig --pkg-end \
 	-target wasm32-freestanding \
 	-O ReleaseSmall -dynamic --strip \
 	hello.zig

package/api.d.ts

@@ -13,6 +13,18 @@ export declare type BigIntArray = bigint[] | BigInt64Array | BigUint64Array;
  * certain exports declared by WASM module.
  */
 export interface IWasmAPI<T extends WasmExports = WasmExports> {
+    /**
+     * The unique ID for grouping the WASM imports of this module. MUST be the
+     * same as used by the native side of the module.
+     */
+    readonly id: string;
+    /**
+     * IDs of other WASM API modules which this module depends on. Used to infer
+     * correct initialization order. The core module (w/ unique ID: `wasmapi`)
+     * is always considered an implicit dependency, will be initialized first
+     * and MUST NOT be stated here.
+     */
+    readonly dependencies?: string[];
     /**
      * Called by {@link WasmBridge.init} to initialize all child APIs (async)
      * after the WASM module has been instantiated. If the method returns false
@@ -53,7 +65,7 @@ export interface WasmExports {
      * @remarks
      * #### Zig
      *
-     * Using the supplied Zig bindings (see `/zig/wasmapi.zig`), it's the
+     * Using the supplied Zig bindings (see `/zig/lib.zig`), it's the
      * user's responsibility to define a public `WASM_ALLOCATOR` in the root
      * source file to enable allocations, e.g. using the
      * [`std.heap.GeneralPurposeAllocator`](https://ziglang.org/documentation/master/#Choosing-an-Allocator)
@@ -161,12 +173,12 @@ export interface IWasmMemoryAccess {
 }
 /**
  * Core API of WASM imports defined by the {@link WasmBridge}. The same
- * functions are declared as bindings in `/zig/wasmapi.zig`. **Also see this
+ * functions are declared as bindings in `/zig/lib.zig`. **Also see this
  * file for documentation of each function...**
  *
  * @remarks
  * Zig API:
- * https://github.com/thi-ng/umbrella/blob/develop/packages/wasm-api/zig/wasmapi.zig
+ * https://github.com/thi-ng/umbrella/blob/develop/packages/wasm-api/zig/lib.zig
  */
 export interface CoreAPI extends WebAssembly.ModuleImports {
     printI8: Fn<number, void>;
@@ -458,7 +470,11 @@ export interface CodeGenOpts extends CodeGenOptsBase {
      */
     stringType: "slice" | "ptr";
     /**
-     * If true (default), forces uppercase enum identifiers
+     * If true (default), forces uppercase enum identifiers.
+     *
+     * @remarks
+     * This option is ignored in {@link ZIG} since it's idiomatic for that
+     * language to only use lowercase/camelCase enum IDs.
      *
      * @defaultValue true
      */

package/bridge.d.ts

@@ -1,5 +1,5 @@
 /// <reference types="node" />
-import type { Event, INotify, Listener, NumericArray } from "@thi.ng/api";
+import type { Event, INotify, IObjectOf, Listener, NumericArray } from "@thi.ng/api";
 import type { ILogger } from "@thi.ng/logger";
 import { BigIntArray, CoreAPI, IWasmAPI, IWasmMemoryAccess, MemorySlice, WasmExports } from "./api.js";
 export declare const Panic: {
@@ -36,11 +36,11 @@ export declare const OutOfMemoryError: {
  * mechanisms like JS `DataView`...
  *
  * 64bit integers are handled via JS `BigInt` and hence require the host env to
- * support it. No polyfill is provided.
+ * support it. No polyfills are provided.
  */
 export declare class WasmBridge<T extends WasmExports = WasmExports> implements IWasmMemoryAccess, INotify {
-    modules: Record<string, IWasmAPI<T>>;
     logger: ILogger;
+    readonly id = "wasmapi";
     i8: Int8Array;
     u8: Uint8Array;
     i16: Int16Array;
@@ -56,7 +56,8 @@ export declare class WasmBridge<T extends WasmExports = WasmExports> implements
     imports: WebAssembly.Imports;
     exports: T;
     api: CoreAPI;
-    constructor(modules?: Record<string, IWasmAPI<T>>, logger?: ILogger);
+    modules: IObjectOf<IWasmAPI<T>>;
+    constructor(modules?: IWasmAPI<T>[], logger?: ILogger);
     /**
      * Instantiates WASM module from given `src` (and optional provided extra
      * imports), then automatically calls {@link WasmBridge.init} with the
@@ -72,9 +73,10 @@ export declare class WasmBridge<T extends WasmExports = WasmExports> implements
      */
     instantiate(src: Response | BufferSource | PromiseLike<Response | BufferSource>, imports?: WebAssembly.Imports): Promise<boolean>;
     /**
-     * Receives the WASM module's exports, stores the for future reference and
-     * then initializes all declared bridge child API modules. Returns false if
-     * any of the module initializations failed.
+     * Receives the WASM module's combined exports, stores them for future
+     * reference and then initializes all declared bridge child API modules in
+     * their stated dependency order. Returns false if any of the module
+     * initializations failed.
      *
      * @remarks
      * Emits the {@link EVENT_MEMORY_CHANGED} event just before returning (and
@@ -84,11 +86,11 @@ export declare class WasmBridge<T extends WasmExports = WasmExports> implements
      */
     init(exports: T): Promise<boolean>;
     /**
-     * Called automatically during initialization. Initializes and/or updates
-     * the various typed WASM memory views (e.g. after growing the WASM memory
-     * and the previous buffer becoming detached). Unless `notify` is false,
-     * the {@link EVENT_MEMORY_CHANGED} event will be emitted if the memory
-     * views had to be updated.
+     * Called automatically during initialization and from other memory
+     * accessors. Initializes and/or updates the various typed WASM memory views
+     * (e.g. after growing the WASM memory and the previous buffer becoming
+     * detached). Unless `notify` is false, the {@link EVENT_MEMORY_CHANGED}
+     * event will be emitted if the memory views had to be updated.
      *
      * @param notify
      */
@@ -99,16 +101,16 @@ export declare class WasmBridge<T extends WasmExports = WasmExports> implements
      * API and any provided bridge API modules.
      *
      * @remarks
-     * Since v0.4.0 each API module's imports will be in their own WASM import
-     * object, named using the same key which was assigned to the module when
-     * creating the WASM bridge. The bridge's core API will be named `core` and
-     * is reserved.
+     * Each API module's imports will be in their own WASM import object/table,
+     * named using the same key which is defined by the JS side of the module
+     * via {@link IWasmAPI.id}. The bridge's core API is named `wasmapi` and is
+     * reserved.
      *
      * @example
      * The following creates a bridge with a fictional `custom` API module:
      *
      * ```ts
-     * const bridge = new WasmBridge({ custom: new CustomAPI() });
+     * const bridge = new WasmBridge([new CustomAPI()]);
      *
      * // get combined imports object
      * bridge.getImports();

package/bridge.js

@@ -1,7 +1,8 @@
 import { __decorate } from "tslib";
 import { INotifyMixin } from "@thi.ng/api/mixins/inotify";
+import { topoSort } from "@thi.ng/arrays/topo-sort";
+import { assert } from "@thi.ng/errors/assert";
 import { defError } from "@thi.ng/errors/deferror";
-import { illegalArgs } from "@thi.ng/errors/illegal-arguments";
 import { U16, U32, U64BIG, U8 } from "@thi.ng/hex";
 import { ConsoleLogger } from "@thi.ng/logger/console";
 import { EVENT_MEMORY_CHANGED, } from "./api.js";
@@ -21,12 +22,12 @@ export const OutOfMemoryError = defError(() => "Out of memory");
  * mechanisms like JS `DataView`...
  *
  * 64bit integers are handled via JS `BigInt` and hence require the host env to
- * support it. No polyfill is provided.
+ * support it. No polyfills are provided.
  */
 let WasmBridge = class WasmBridge {
-    constructor(modules = {}, logger = new ConsoleLogger("wasm")) {
-        this.modules = modules;
+    constructor(modules = [], logger = new ConsoleLogger("wasm")) {
         this.logger = logger;
+        this.id = "wasmapi";
         this.utf8Decoder = new TextDecoder();
         this.utf8Encoder = new TextEncoder();
         const logN = (x) => this.logger.debug(x);
@@ -67,6 +68,11 @@ let WasmBridge = class WasmBridge {
             timer: () => performance.now(),
             epoch: () => BigInt(Date.now()),
         };
+        this.modules = modules.reduce((acc, x) => {
+            assert(acc[x.id] === undefined && x.id !== this.id, `duplicate API module ID: ${x.id}`);
+            acc[x.id] = x;
+            return acc;
+        }, {});
     }
     /**
      * Instantiates WASM module from given `src` (and optional provided extra
@@ -90,9 +96,10 @@ let WasmBridge = class WasmBridge {
         return this.init(wasm.instance.exports);
     }
     /**
-     * Receives the WASM module's exports, stores the for future reference and
-     * then initializes all declared bridge child API modules. Returns false if
-     * any of the module initializations failed.
+     * Receives the WASM module's combined exports, stores them for future
+     * reference and then initializes all declared bridge child API modules in
+     * their stated dependency order. Returns false if any of the module
+     * initializations failed.
      *
      * @remarks
      * Emits the {@link EVENT_MEMORY_CHANGED} event just before returning (and
@@ -103,7 +110,8 @@ let WasmBridge = class WasmBridge {
     async init(exports) {
         this.exports = exports;
         this.ensureMemory(false);
-        for (let id in this.modules) {
+        for (let id of topoSort(this.modules, (module) => module.dependencies)) {
+            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)
@@ -113,11 +121,11 @@ let WasmBridge = class WasmBridge {
         return true;
     }
     /**
-     * Called automatically during initialization. Initializes and/or updates
-     * the various typed WASM memory views (e.g. after growing the WASM memory
-     * and the previous buffer becoming detached). Unless `notify` is false,
-     * the {@link EVENT_MEMORY_CHANGED} event will be emitted if the memory
-     * views had to be updated.
+     * Called automatically during initialization and from other memory
+     * accessors. Initializes and/or updates the various typed WASM memory views
+     * (e.g. after growing the WASM memory and the previous buffer becoming
+     * detached). Unless `notify` is false, the {@link EVENT_MEMORY_CHANGED}
+     * event will be emitted if the memory views had to be updated.
      *
      * @param notify
      */
@@ -147,16 +155,16 @@ let WasmBridge = class WasmBridge {
      * API and any provided bridge API modules.
      *
      * @remarks
-     * Since v0.4.0 each API module's imports will be in their own WASM import
-     * object, named using the same key which was assigned to the module when
-     * creating the WASM bridge. The bridge's core API will be named `core` and
-     * is reserved.
+     * Each API module's imports will be in their own WASM import object/table,
+     * named using the same key which is defined by the JS side of the module
+     * via {@link IWasmAPI.id}. The bridge's core API is named `wasmapi` and is
+     * reserved.
      *
      * @example
      * The following creates a bridge with a fictional `custom` API module:
      *
      * ```ts
-     * const bridge = new WasmBridge({ custom: new CustomAPI() });
+     * const bridge = new WasmBridge([new CustomAPI()]);
      *
      * // get combined imports object
      * bridge.getImports();
@@ -177,11 +185,8 @@ let WasmBridge = class WasmBridge {
      */
     getImports() {
         if (!this.imports) {
-            this.imports = { wasmapi: this.api };
+            this.imports = { [this.id]: this.api };
             for (let id in this.modules) {
-                if (this.imports[id] !== undefined) {
-                    illegalArgs(`attempt to redeclare API module ${id}`);
-                }
                 this.imports[id] = this.modules[id].getImports();
             }
         }
@@ -391,9 +396,7 @@ let WasmBridge = class WasmBridge {
         this.ensureMemory();
         maxBytes = Math.min(maxBytes, this.u8.length - addr);
         const len = this.utf8Encoder.encodeInto(str, this.u8.subarray(addr, addr + maxBytes)).written;
-        if (len == null || len >= maxBytes + (terminate ? 0 : 1)) {
-            illegalArgs(`error writing string to 0x${U32(addr)} (max. ${maxBytes} bytes, got at least ${str.length})`);
-        }
+        assert(len != null && len < maxBytes + (terminate ? 0 : 1), `error writing string to 0x${U32(addr)} (max. ${maxBytes} bytes, got at least ${str.length})`);
         if (terminate) {
             this.u8[addr + len] = 0;
         }
@@ -402,7 +405,7 @@ let WasmBridge = class WasmBridge {
     getElementById(addr, len = 0) {
         const id = this.getString(addr, len);
         const el = document.getElementById(id);
-        el == null && illegalArgs(`missing DOM element #${id}`);
+        assert(!!el, `missing DOM element #${id}`);
         return el;
     }
     /** {@inheritDoc @thi.ng/api#INotify.addListener} */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/wasm-api",
-  "version": "0.17.2",
+  "version": "0.18.0",
   "description": "Generic, modular, extensible API bridge, polyglot glue code and bindings code generators for hybrid JS & WebAssembly projects",
   "type": "module",
   "module": "./index.js",
@@ -38,6 +38,7 @@
   "dependencies": {
     "@thi.ng/api": "^8.4.4",
     "@thi.ng/args": "^2.2.7",
+    "@thi.ng/arrays": "^2.4.0",
     "@thi.ng/binary": "^3.3.8",
     "@thi.ng/checks": "^3.3.2",
     "@thi.ng/compare": "^2.1.14",
@@ -141,5 +142,5 @@
     "status": "alpha",
     "year": 2022
   },
-  "gitHead": "ce7be1988e43f620b90a751f056d1a2326306ee4\n"
+  "gitHead": "7eff3051eb395f460421727b8cf5ef79f09faaa9\n"
 }

package/zig/{wasmapi.zig → lib.zig}

@@ -1,4 +1,4 @@
-//! JavaScript externals for https://thi.ng/wasm-api
+//! Zig API for https://thi.ng/wasm-api
 
 const std = @import("std");
 const root = @import("root");
@@ -72,7 +72,7 @@ pub fn panic(msg: []const u8, _: ?*std.builtin.StackTrace, _: ?usize) noreturn {
 /// Note: The type for this var is purposefully chosen as an optional,
 /// effectively disabling allocations from the WASM host side if no
 /// `WASM_ALLOCATOR` is set (or set to null).
-pub fn allocator() ?std.mem.Allocator {
+pub inline fn allocator() ?std.mem.Allocator {
     return if (@hasDecl(root, "WASM_ALLOCATOR")) root.WASM_ALLOCATOR else null;
 }