@thi.ng/wasm-api 1.6.7 → 2.0.1

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2024-08-10T15:03:07Z
+- **Last updated**: 2024-09-19T21:09:34Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,32 @@ 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.0.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/wasm-api@2.0.0) (2024-08-18)
+
+#### 🛑 Breaking changes
+
+- update WASM module dependency handling ([31f0358](https://github.com/thi-ng/umbrella/commit/31f0358))
+- BREAKING CHANGE: update WASM module dependency handling
+  - add `WasmModuleSpec` interface to declare WASM modules with their deps
+  - update `WasmBridge` ctor to accept array of module specs
+  - add buildModuleGraph() to process dependencies & init modules from specs
+  - add/update docstrings
+  - update tests
+
+#### 🚀 Features
+
+- add ObjectIndex.addUnique() ([e79275d](https://github.com/thi-ng/umbrella/commit/e79275d))
+- add MemoryView types ([b621adc](https://github.com/thi-ng/umbrella/commit/b621adc))
+- add internal memory view accessors ([6830337](https://github.com/thi-ng/umbrella/commit/6830337))
+  - these accessors are shared by various types generated via [@thi.ng/wasm-api-bindgen](https://github.com/thi-ng/umbrella/tree/main/packages/wasm-api-bindgen)
+    and help to drastically cut down filesize of generated code
+  - update pkg exports
+- update ObjectIndex ctor, make opts fully optional ([564e0f3](https://github.com/thi-ng/umbrella/commit/564e0f3))
+
+#### ♻️ Refactoring
+
+- update internal array mem accessors ([b442d92](https://github.com/thi-ng/umbrella/commit/b442d92))
+
 ## [1.6.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/wasm-api@1.6.0) (2024-06-21)
 
 #### 🚀 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 198 standalone projects, maintained as part
+> This is one of 199 standalone projects, maintained as part
 > of the [@thi.ng/umbrella](https://github.com/thi-ng/umbrella/) monorepo
 > and anti-framework.
 >
@@ -15,6 +15,7 @@
 > GitHub](https://github.com/sponsors/postspectacular). Thank you! ❤️
 
 - [About](#about)
+- [Polyglot bindings generator](#polyglot-bindings-generator)
 - [Custom API modules](#custom-api-modules)
 - [String handling](#string-handling)
 - [Memory allocations](#memory-allocations)
@@ -46,22 +47,24 @@ Generic, modular, extensible API bridge and infrastructure for hybrid JS & WebAs
 
 (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:
+This package form the core of a larger WASM toolkit which includes a polyglot
+bindings generator and a growing number of API modules to interop with different
+browser APIs. This core package provides the following:
 
 1. A small
 [`WasmBridge`](https://docs.thi.ng/umbrella/wasm-api/classes/WasmBridge.html)
-class as generic interop basis and much reduced boilerplate for hybrid JS/WebAssembly
-applications.
-2. A minimal core API for debug output, string/pointer/typedarray accessors for
+class as generic interop basis and much reduced boilerplate for hybrid
+JS/WebAssembly applications.
+2. Child WASM API modules with dependency graph resolution & initialization
+3. A minimal core API for debug output, string/pointer/typedarray accessors for
 8/16/32/64 bit (u)ints and 32/64 bit floats. Additionally, a number of support
 modules for [DOM
 manipulation](https://github.com/thi-ng/umbrella/tree/develop/packages/wasm-api-dom/),
 [scheduled function
 execution](https://github.com/thi-ng/umbrella/tree/develop/packages/wasm-api-schedule/),
 WebGL, WebGPU, WebAudio etc. is being actively worked on.
-3. Different types of memory-mapped (UTF-8) string abstractions (slice or pointer based)
+4. Different types of memory-mapped (UTF-8) string abstractions (slice or pointer based)
 5. Shared (opt-in) memory allocation mechanism, also accessible from JS/TS side
-4. Simple registration & dependency-order initialization for child WASM API modules
 6. Include files for
    [Zig](https://github.com/thi-ng/umbrella/tree/develop/packages/wasm-api/zig),
    and
@@ -71,46 +74,87 @@ WebGL, WebGPU, WebAudio etc. is being actively worked on.
    by this package
 7. [Zig build files](#using-the-zig-build-system) to simplify using hybrid
    TS/Zig packages with the built-in build system
-8. Extensible shared [datatype code generator
-   infrastructure](https://github.com/thi-ng/umbrella/tree/develop/packages/wasm-api-bindgen/)
-   for (currently) Zig & TypeScript and C11. For TS fully type checked and
-memory-mapped (zero-copy) accessors of WASM-side data are generated. In
-principle, all languages with a WASM target are supported, however currently
-only bindings for these mentioned langs are included.
-9. [CLI
-   frontend/utility](https://github.com/thi-ng/umbrella/blob/develop/packages/wasm-api-bindgen/README.md#cli-generator)
-   for the code generator(s)
+
+## Polyglot bindings generator
+
+The toolkit includes an extensible [code
+generator](https://github.com/thi-ng/umbrella/tree/develop/packages/wasm-api-bindgen/)
+for shared datatypes and (currently) supports Zig & TypeScript and C11. For TS
+fully type checked and memory-mapped (mostly zero-copy) accessors of WASM-side
+data are generated. In principle, all languages with a WASM target are
+supported, however currently only bindings for the languages mentioned are
+included. The codegen also includes a [CLI
+frontend/utility](https://github.com/thi-ng/umbrella/blob/develop/packages/wasm-api-bindgen/README.md#cli-generator).
 
 ## Custom API modules
 
 The
 [`WasmBridge`](https://docs.thi.ng/umbrella/wasm-api/classes/WasmBridge.html)
-can be extented via custom defined API modules. Such API extensions will consist
+can be extented via custom defined API modules. Such child modules will consist
 of a collection of JS/TS functions & variables, their related counterparts
 (import definitions) for the WASM target and (optionally) some shared data types
-([bindings for which _can_ be generated by this package
-too](#data-bindings--code-generators)).
+([bindings for which can be generated via
+thi.ng/wasm-api-bindgen](https://github.com/thi-ng/umbrella/blob/develop/packages/wasm-api-bindgen)).
 
-On the JS side, custom API modules can be easily integrated via the [`IWasmAPI`
-interface](https://docs.thi.ng/umbrella/wasm-api/interfaces/IWasmAPI.html). The
-following example provides a brief overview:
+On the JS side, custom API extensions can be easily integrated and exposed via
+the [`IWasmAPI`
+interface](https://docs.thi.ng/umbrella/wasm-api/interfaces/IWasmAPI.html) and
+their module descriptors via
+[`WasmModuleSpec`](https://docs.thi.ng/umbrella/wasm-api/interfaces/WasmModuleSpec.html).
+The following example provides a brief overview:
 
 ```ts
-import { IWasmAPI, WasmBridge } from "@thi.ng/wasm-api";
+import { WasmBridge, type IWasmAPI, type WasmModuleSpec } from "@thi.ng/wasm-api";
+import { WasmDomModule, type WasmDom, type WasmDomExports } from "@thi.ng/wasm-api-dom";
+
+export const CustomModule: WasmModuleSpec = {
+    // Unique API module identifier to group WASM imports, must match ID used
+    // by the native code (see further below).
+    id: "custom",
+    // Optional array of API modules this module depends on. This is used to
+    // infer the full dependency graph and correct initialization order.
+    // Note: Each of the wasm-api support packages includes a module spec...
+    depes: [WasmDomModule],
+    // Factory function to pre-instantiate the API module. Full initialization
+    // only happens at a later point via WasmBridge.instantiate() or
+    // WasmBridge.init() and each module's own init() method...
+    factory: () => new CustomAPI(),
+};
+
+// Optional declarations for JS-side functions which can be used from the WASM side.
+// Using an interface for this is useful to establish a contract.
+export interface CustomImports extends WebAssembly.ModuleImports {
+    /**
+     * Writes `num` random float32 numbers from given address
+     */
+    fillRandom(addr: number, num: number): void;
+}
 
-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 = [];
+// Optional (but likely used) interface declarations of functions exposed
+// by the WASM binary and callable from the JS side (i.e. the opposite of the above)
+//
+// Note: If your module has dependencies on other modules you should declare
+// your exports as extension of these other module's exports for better
+// downstream developer experience
+export interface CustomWasmExports extends WasmDomExports {
+    // ...
+}
 
+// Actual custom API extension implentation
+export class CustomAPI implements IWasmAPI<CustomWasmExports> {
     parent!: WasmBridge;
+    dom!: WasmDom;
 
+    /**
+     * Actual module initialization, called from the main WasmBridge which
+     * initializes all modules in dependency order...
+     */
     async init(parent: WasmBridge) {
         this.parent = parent;
         this.parent.logger.debug("initializing custom API");
+        // Store a direct reference to the DOM module for future ref
+        // (just shown as example, we're not actually using this module here...)
+        this.dom = <WasmDom>this.parent.modules[WasmDomModule.id];
 
         // any other tasks you might need to do...
 
@@ -118,15 +162,15 @@ export class CustomAPI implements IWasmAPI {
     }
 
     /**
-     * Returns object of functions to import as externals into the
-     * WASM module during instantiation. These imports are merged
-     * into a larger imports object alongside the bridge's core API...
+     * Returns object of functions/constants to import as externals into the
+     * WASM module during instantiation. These imports are merged into a
+     * larger imports object alongside the bridge's core API...
+     *
+     * Each module's imports will be grouped by its declared module ID, which
+     * also needs to be used to declare extern functions on the WASM side.
      */
-    getImports(): WebAssembly.Imports {
+    getImports(): CustomImports {
         return {
-            /**
-             * Writes `num` random float32 numbers from given address
-             */
             fillRandom: (addr: number, num: number) => {
                 addr >>>= 2;
                 while(num-- > 0) this.parent.f32[addr++] = Math.random();
@@ -136,13 +180,12 @@ export class CustomAPI implements IWasmAPI {
 }
 
 // now we can supply this custom API when creating the main WASM bridge:
-export const bridge = new WasmBridge([new CustomAPI()]);
+export const bridge = new WasmBridge([CustomModule]);
 ```
 
 In Zig (or any other language of your choice) we can then utilize this custom
-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):
+API like so (Please also see [example projects](#usage-examples) & other code
+snippets in this readme):
 
 Bindings file / lib:
 
@@ -155,26 +198,31 @@ Bindings file / lib:
 ///
 /// The bridge core API uses "wasmapi" as reserved import group name
 extern "custom" fn fillRandom(addr: [*]f32, num: usize) void;
+
+/// Syntax sugar for `fillRandom()`
+pub fn fillRandomSlice(slice: []f32) void {
+    fillRandom(slice.ptr, slice.len);
+}
 ```
 
 Main Zig file:
 
 ```zig
 // Import JS core API
-const js = @import("wasm-api");
+const wasm = @import("wasm-api");
 const custom = @import("custom.zig");
 
 export fn test_randomVec4() void {
     var foo = [4]f32{ 1, 2, 3, 4 };
 
     // print original
-    js.printF32Array(foo[0..]);
+    wasm.printF32Array(foo[0..]);
 
     // populate foo with random numbers
-    custom.fillRandom(&foo, foo.len);
+    custom.fillRandomSlice(foo[0..]);
 
     // print result
-    js.printF32Array(foo[0..]);
+    wasm.printF32Array(foo[0..]);
 }
 ```
 
@@ -257,32 +305,41 @@ etc.) use an auto-intialization hook related to the above `WASM_ALLOCATOR`
 mechanism: If that allocator is available, the WASM side of these modules will
 auto initialize and thus reduce boilerplate. However, if no such central
 allocator is defined and/or a custom allocator should be used, then these API
-modules will be have to be initialized manually.
+modules will have to be initialized manually.
 
 ## Object indices & handles
 
-Since only numeric values can be exchanged between the WASM module and the JS
-host, any JS native objects the WASM side might want to be working with must be
-managed manually in JS. For this purpose the [`ObjectIndex`
+Since only numeric values can be directly passed between the WASM module and the
+JS host, any JS native objects the WASM side might want to be working with must
+be managed manually in JS. For this purpose the [`ObjectIndex`
 class](https://docs.thi.ng/umbrella/wasm-api/classes/ObjectIndex.html) can be
-used by API modules to handle ID generation (incl. recycling, using
-[@thi.ng/idgen](https://github.com/thi-ng/umbrella/tree/develop/packages/idgen))
-and the indexing of different types of JS objects/values. Only the numeric IDs
-(handles) will then need to be exchanged with the WASM module...
+used by API modules to handle the indexing of different types of JS
+objects/values and their ID generation (incl. recycling of IDs, using
+[@thi.ng/idgen](https://github.com/thi-ng/umbrella/tree/develop/packages/idgen)).
+Using this approach, only the numeric IDs (handles) will then need to be
+exchanged with the WASM module...
 
 ```ts
 import { ObjectIndex } from "@thi.ng/wasm-api";
+import { ConsoleLogger } from "@thi.ng/logger";
 
+// create index (see API docs for options)
 const canvases = new ObjectIndex<HTMLCanvasElement>({ name: "canvas" });
 
 // index item and assign new ID
-canvases.add(document.createElement("canvas"));
+canvases.add(<HTMLCanvasElement>document.createElement("canvas"));
 // 0
 
 // look up item by ID
 canvases.get(0);
 // <canvas ...>
 
+// by default, items to be indexed are not checked for equality
+// but we can use the below to ensure double indexing is avoided...
+// (supports custom predicates to check for equality)
+canvases.addUnique(canvases.get(0));
+// 0 (returned already known ID)
+
 // work w/ retrieved item
 canvases.get(0).id = "foo";
 
@@ -326,8 +383,8 @@ built-in build system is as simple as:
 **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
+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))
 
 ```zig
@@ -359,8 +416,7 @@ pub fn build(b: *std.Build) void {
 ### Example projects
 
 All bundled example projects (see [list below](#usage-examples)) are being built
-via this script. **Please find more details/options in the commented source
-code:**
+via this script. **More details/options in the commented source code:**
 
 - [`/zig/build.zig`](https://github.com/thi-ng/umbrella/blob/develop/packages/wasm-api/zig/build.zig)
 
@@ -382,6 +438,7 @@ please also consult the information in
 - [@thi.ng/wasm-api-canvas](https://github.com/thi-ng/umbrella/tree/develop/packages/wasm-api-canvas) - HTML Canvas2D bridge API for hybrid TypeScript & WASM (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-schedule](https://github.com/thi-ng/umbrella/tree/develop/packages/wasm-api-schedule) - Delayed & scheduled function execution (via setTimeout() etc.) for hybrid WASM apps
+- [@thi.ng/wasm-api-webgl](https://github.com/thi-ng/umbrella/tree/develop/packages/wasm-api-webgl) - WebGL bridge API for hybrid TypeScript & WASM (Zig) applications
 
 ## Installation
 
@@ -403,7 +460,7 @@ Browser ESM import:
 
 [JSDelivr documentation](https://www.jsdelivr.com/)
 
-Package sizes (brotli'd, pre-treeshake): ESM: 2.69 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 3.00 KB
 
 ## Dependencies
 
@@ -419,7 +476,7 @@ Note: @thi.ng/api is in _most_ cases a type-only import (not used at runtime)
 
 ## Usage examples
 
-Four projects in this repo's
+Five projects in this repo's
 [/examples](https://github.com/thi-ng/umbrella/tree/develop/examples)
 directory are using this package:
 
@@ -429,6 +486,7 @@ directory are using this package:
 | <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/zig-cellular.jpg" width="240"/>  | Zig-based 2D multi-behavior cellular automata                      | [Demo](https://demo.thi.ng/umbrella/zig-cellular/)  | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/zig-cellular)  |
 | <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/zig-counter.png" width="240"/>   | Simple Zig/WASM click counter DOM component                        | [Demo](https://demo.thi.ng/umbrella/zig-counter/)   | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/zig-counter)   |
 | <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/zig-todo-list.png" width="240"/> | Zig-based To-Do list, DOM creation, local storage task persistence | [Demo](https://demo.thi.ng/umbrella/zig-todo-list/) | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/zig-todo-list) |
+| <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/zig-webgl.avif" width="240"/>    | Basic Zig/WebAssembly WebGL demo                                   | [Demo](https://demo.thi.ng/umbrella/zig-webgl/)     | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/zig-webgl)     |
 
 ## API
 

package/api.d.ts

@@ -1,4 +1,4 @@
-import type { EVENT_ALL, Fn, IDeref, ILength } from "@thi.ng/api";
+import type { BigTypedArray, EVENT_ALL, Fn, IDeref, ILength, TypedArray, Values } from "@thi.ng/api";
 import type { WasmBridge } from "./bridge.js";
 export declare const EVENT_MEMORY_CHANGED = "memory-changed";
 export declare const EVENT_PANIC = "panic";
@@ -52,18 +52,6 @@ export type WasmTypeConstructor<T> = Fn<IWasmMemoryAccess, WasmType<T>>;
  * 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
@@ -79,6 +67,31 @@ export interface IWasmAPI<T extends WasmExports = WasmExports> {
      */
     getImports(): WebAssembly.ModuleImports;
 }
+export interface WasmModuleSpec<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.
+     */
+    id: string;
+    /**
+     * Optional array of other {@link WasmModuleSpec}s which this module depends
+     * on (element order is irrelevant). Used to construct a module dependency
+     * graph and the correct initialization order of modules. The core module
+     * (defined via {@link WasmBridge} w/ unique ID: `wasmapi`) is always
+     * considered an implicit dependency, will be initialized first and MUST NOT
+     * be stated here.
+     */
+    deps?: WasmModuleSpec<T>[];
+    /**
+     * Factory function to pre-instantiate the API module.
+     *
+     * @remarks
+     * Note: All modules will only be fully initialized at a later point via
+     * {@link WasmBridge.instantiate} or {@link WasmBridge.init} and each
+     * modules own {@link IWasmAPI.init} method.
+     */
+    factory: Fn<WasmBridge<T>, IWasmAPI<T>>;
+}
 /**
  * Base interface of exports declared by the WASM module. At the very least, a
  * compatible module needs to export its memory and the functions defined in
@@ -133,6 +146,21 @@ export interface WasmExports {
     _wasm_free(addr: number, numBytes: number): void;
 }
 export type MemorySlice = [addr: number, len: number];
+export type MemoryViewType = "i8" | "u8" | "i16" | "u16" | "i32" | "u32" | "i64" | "u64" | "f32" | "f64";
+export interface MemoryViewTypeMap extends Record<MemoryViewType, TypedArray | BigTypedArray> {
+    u8: Uint8Array;
+    u8c: Uint8ClampedArray;
+    i8: Int8Array;
+    u16: Uint16Array;
+    i16: Int16Array;
+    u32: Uint32Array;
+    i32: Int32Array;
+    i64: BigInt64Array;
+    u64: BigUint64Array;
+    f32: Float32Array;
+    f64: Float64Array;
+}
+export type MemoryView = Values<MemoryViewTypeMap>;
 export interface IWasmMemoryAccess {
     i8: Int8Array;
     u8: Uint8Array;

package/bridge.d.ts

@@ -1,6 +1,6 @@
 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";
+import { type BigIntArray, type BridgeEventType, type CoreAPI, type IWasmAPI, type IWasmMemoryAccess, type MemorySlice, type WasmExports, type WasmModuleSpec } from "./api.js";
 export declare const Panic: {
     new (msg?: string | undefined): {
         origMessage: string;
@@ -60,7 +60,21 @@ export declare class WasmBridge<T extends WasmExports = WasmExports> implements
     exports: T;
     api: CoreAPI;
     modules: IObjectOf<IWasmAPI<T>>;
-    constructor(modules?: IWasmAPI<T>[], logger?: ILogger);
+    order: string[];
+    constructor(modules?: WasmModuleSpec<T>[], logger?: ILogger);
+    /**
+     * Takes array of root module specs, extracts all transitive dependencies,
+     * pre-computes their topological order, then calls
+     * {@link WasmModuleSpec.factory} for each module and stores all modules for
+     * future reference.
+     *
+     * @remarks
+     * Note: The pre-instantiated modules will only be fully initialized later
+     * via {@link WasmBridge.instantiate} or {@link WasmBridge.init}.
+     *
+     * @param specs
+     */
+    protected _buildModuleGraph(specs: WasmModuleSpec<T>[]): void;
     /**
      * Instantiates WASM module from given `src` (and optional provided extra
      * imports), then automatically calls {@link WasmBridge.init} with the

package/bridge.js

@@ -70,14 +70,7 @@ let WasmBridge = class {
       timer: () => performance.now(),
       epoch: () => BigInt(Date.now())
     };
-    this.modules = modules.reduce((acc, x) => {
-      assert(
-        acc[x.id] === void 0 && x.id !== this.id,
-        `duplicate API module ID: ${x.id}`
-      );
-      acc[x.id] = x;
-      return acc;
-    }, {});
+    this._buildModuleGraph(modules);
   }
   id = "wasmapi";
   i8;
@@ -96,6 +89,44 @@ let WasmBridge = class {
   exports;
   api;
   modules;
+  order;
+  /**
+   * Takes array of root module specs, extracts all transitive dependencies,
+   * pre-computes their topological order, then calls
+   * {@link WasmModuleSpec.factory} for each module and stores all modules for
+   * future reference.
+   *
+   * @remarks
+   * Note: The pre-instantiated modules will only be fully initialized later
+   * via {@link WasmBridge.instantiate} or {@link WasmBridge.init}.
+   *
+   * @param specs
+   */
+  _buildModuleGraph(specs) {
+    const unique = /* @__PURE__ */ new Set();
+    const queue = [...specs];
+    while (queue.length) {
+      const mod = queue.shift();
+      unique.add(mod);
+      if (!mod.deps) continue;
+      for (let d of mod.deps) {
+        if (!unique.has(d)) queue.push(d);
+      }
+    }
+    const graph = [...unique].reduce((acc, mod) => {
+      assert(
+        (acc[mod.id] === void 0 || acc[mod.id] === mod) && mod.id !== this.id,
+        `duplicate API module ID: ${mod.id}`
+      );
+      acc[mod.id] = mod;
+      return acc;
+    }, {});
+    this.order = topoSort(graph, (mod) => mod.deps?.map((x) => x.id));
+    this.modules = this.order.reduce((acc, id) => {
+      acc[id] = graph[id].factory(this);
+      return acc;
+    }, {});
+  }
   /**
    * Instantiates WASM module from given `src` (and optional provided extra
    * imports), then automatically calls {@link WasmBridge.init} with the
@@ -130,11 +161,7 @@ let WasmBridge = class {
   async init(exports) {
     this.exports = exports;
     this.ensureMemory(false);
-    for (let id of topoSort(
-      this.modules,
-      (module) => module.dependencies
-    )) {
-      assert(!!this.modules[id], `missing API module: ${id}`);
+    for (let id of this.order) {
       this.logger.debug(`initializing API module: ${id}`);
       const status = await this.modules[id].init(this);
       if (!status) return false;

package/index.d.ts

@@ -1,5 +1,6 @@
 export * from "./api.js";
 export * from "./bridge.js";
+export * from "./memory.js";
 export * from "./object-index.js";
 export * from "./pointer.js";
 export * from "./string.js";

package/index.js

@@ -1,5 +1,6 @@
 export * from "./api.js";
 export * from "./bridge.js";
+export * from "./memory.js";
 export * from "./object-index.js";
 export * from "./pointer.js";
 export * from "./string.js";

package/memory.d.ts

@@ -0,0 +1,14 @@
+import type { IWasmMemoryAccess, MemoryView, WasmType, WasmTypeConstructor } from "./api.js";
+/** @internal */
+export declare const __instanceArray: <T>(type: WasmType<T>, addr: number, num: number, size?: number) => T[];
+/** @internal */
+export declare const __array: <T>(mem: IWasmMemoryAccess, ctor: WasmTypeConstructor<T>, addr: number, len: number) => T[];
+/** @internal */
+export declare const __slice32: <T>(mem: IWasmMemoryAccess, ctor: WasmTypeConstructor<T>, offset: number) => T[];
+/** @internal */
+export declare const __slice64: <T>(mem: IWasmMemoryAccess, ctor: WasmTypeConstructor<T>, offset: number) => T[];
+/** @internal */
+export declare const __primslice32: <T extends MemoryView>(mem: IWasmMemoryAccess, view: T, offset: number, shift: number) => T;
+/** @internal */
+export declare const __primslice64: <T extends MemoryView>(mem: IWasmMemoryAccess, view: T, offset: number, shift: number) => T;
+//# sourceMappingURL=memory.d.ts.map

package/memory.js

@@ -0,0 +1,40 @@
+const __instanceArray = (type, addr, num, size = type.size) => {
+  const items = [];
+  for (; num-- > 0; addr += size) items.push(type.instance(addr));
+  return items;
+};
+const __array = (mem, ctor, addr, len) => __instanceArray(ctor(mem), addr, len);
+const __slice32 = (mem, ctor, offset) => {
+  return __array(
+    mem,
+    ctor,
+    mem.u32[offset >>> 2],
+    mem.u32[offset + 4 >>> 2]
+  );
+};
+const __slice64 = (mem, ctor, offset) => {
+  return __array(
+    mem,
+    ctor,
+    Number(mem.u64[offset >>> 3]),
+    Number(mem.u64[offset + 8 >>> 3])
+  );
+};
+const __primslice32 = (mem, view, offset, shift) => {
+  const addr = mem.u32[offset >>> 2] >>> shift;
+  const len = mem.u32[offset + 4 >>> 2];
+  return view.subarray(addr, addr + len);
+};
+const __primslice64 = (mem, view, offset, shift) => {
+  const addr = Number(mem.u64[offset >>> 3]) >>> shift;
+  const len = Number(mem.u64[offset + 8 >>> 3]);
+  return view.subarray(addr, addr + len);
+};
+export {
+  __array,
+  __instanceArray,
+  __primslice32,
+  __primslice64,
+  __slice32,
+  __slice64
+};

package/object-index.d.ts

@@ -9,20 +9,26 @@ export interface ObjectIndexOpts {
     /**
      * Optional logger instance
      */
-    logger?: ILogger;
+    logger: ILogger;
     /**
      * Number of bits for IDs, [1..32] range.
      *
      * @defaultValue 32
      */
-    bits?: Range1_32;
+    bits: Range1_32;
 }
+/**
+ * Object cache with numeric ID handle management.
+ *
+ * @remarks
+ * [Further reference](https://docs.thi.ng/umbrella/wasm-api/#md:object-indices--handles)
+ */
 export declare class ObjectIndex<T> {
     readonly name: string;
     logger?: ILogger;
     protected idgen: IDGen;
     protected items: T[];
-    constructor(opts: ObjectIndexOpts);
+    constructor(opts?: Partial<ObjectIndexOpts>);
     keys(): Generator<number, void, unknown>;
     values(): Generator<T, void, unknown>;
     /**
@@ -32,6 +38,19 @@ export declare class ObjectIndex<T> {
      * @param item
      */
     add(item: T): number;
+    /**
+     * Similar to {@link ObjectIndex.add}, but first checks if `item` has
+     * already been indexed and if so returns the ID of already indexed item
+     * without adding `item` to the index again. Uses `equiv` for checking item
+     * equality (by default: `===`).
+     *
+     * @remarks
+     * Currently an O(n) implementation.
+     *
+     * @param item
+     * @param equiv
+     */
+    addUnique(item: T, equiv?: Predicate<T>): number;
     /**
      * Returns true if the given `id` is valid/active.
      *

package/object-index.js

@@ -1,14 +1,15 @@
 import { assert } from "@thi.ng/errors/assert";
 import { IDGen } from "@thi.ng/idgen";
+let __nextID = 0;
 class ObjectIndex {
   name;
   logger;
   idgen;
   items = [];
   constructor(opts) {
-    this.name = opts.name;
-    this.logger = opts.logger;
-    this.idgen = new IDGen(opts.bits || 32, 0);
+    this.name = opts?.name ?? `idx-${__nextID++}`;
+    this.logger = opts?.logger;
+    this.idgen = new IDGen(opts?.bits ?? 32, 0);
   }
   keys() {
     return this.idgen[Symbol.iterator]();
@@ -30,6 +31,22 @@ class ObjectIndex {
     this.items[id] = item;
     return id;
   }
+  /**
+   * Similar to {@link ObjectIndex.add}, but first checks if `item` has
+   * already been indexed and if so returns the ID of already indexed item
+   * without adding `item` to the index again. Uses `equiv` for checking item
+   * equality (by default: `===`).
+   *
+   * @remarks
+   * Currently an O(n) implementation.
+   *
+   * @param item
+   * @param equiv
+   */
+  addUnique(item, equiv = (x) => x === item) {
+    const id = this.find(equiv, false);
+    return id === void 0 ? this.add(item) : id;
+  }
   /**
    * Returns true if the given `id` is valid/active.
    *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/wasm-api",
-  "version": "1.6.7",
+  "version": "2.0.1",
   "description": "Generic, modular, extensible API bridge and infrastructure for hybrid JS & WebAssembly projects",
   "type": "module",
   "module": "./index.js",
@@ -37,19 +37,19 @@
     "tool:tangle": "../../node_modules/.bin/tangle src/**/*.ts"
   },
   "dependencies": {
-    "@thi.ng/api": "^8.11.8",
-    "@thi.ng/arrays": "^2.9.14",
-    "@thi.ng/checks": "^3.6.10",
-    "@thi.ng/errors": "^2.5.14",
-    "@thi.ng/hex": "^2.3.52",
-    "@thi.ng/idgen": "^2.2.48",
-    "@thi.ng/logger": "^3.0.18"
+    "@thi.ng/api": "^8.11.10",
+    "@thi.ng/arrays": "^2.10.1",
+    "@thi.ng/checks": "^3.6.12",
+    "@thi.ng/errors": "^2.5.16",
+    "@thi.ng/hex": "^2.3.54",
+    "@thi.ng/idgen": "^2.2.50",
+    "@thi.ng/logger": "^3.0.20"
   },
   "devDependencies": {
-    "@microsoft/api-extractor": "^7.47.5",
-    "esbuild": "^0.23.0",
-    "typedoc": "^0.26.5",
-    "typescript": "^5.5.4"
+    "@microsoft/api-extractor": "^7.47.9",
+    "esbuild": "^0.23.1",
+    "typedoc": "^0.26.7",
+    "typescript": "^5.6.2"
   },
   "keywords": [
     "allocator",
@@ -102,6 +102,9 @@
     "./bridge": {
       "default": "./bridge.js"
     },
+    "./memory": {
+      "default": "./memory.js"
+    },
     "./object-index": {
       "default": "./object-index.js"
     },
@@ -116,5 +119,5 @@
     "status": "alpha",
     "year": 2022
   },
-  "gitHead": "ec78f98d015e4d214a0b840e72e497407807daf3\n"
+  "gitHead": "b52baa3750ddd1256892df966ab7ac9b4806a9ef\n"
 }

package/zig/zig-cache/o/20f8f8362ac39302905d03992fa818bc/dependencies.zig

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