@thi.ng/wasm-api 0.17.3 → 0.18.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2022-10-31T09:19:33Z
+- **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,17 @@ 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

package/README.md

@@ -505,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) {
@@ -538,7 +545,7 @@ 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
@@ -681,7 +688,7 @@ 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 multiple language code generators which are
 **not** required for normal use of the API bridge. Hence, the actual package
@@ -691,6 +698,7 @@ size in production will be MUCH smaller than what's stated here!
 
 - [@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)

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

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.3",
+  "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": "7c5c0cb37ff88c2fa5dd77dd78bf3a5ceb5c62c6\n"
+  "gitHead": "7eff3051eb395f460421727b8cf5ef79f09faaa9\n"
 }