@thi.ng/wasm-api 0.3.1 → 0.4.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2022-08-04T21:21:08Z
+- **Last updated**: 2022-08-07T15:28:01Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,15 @@ 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.4.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/wasm-api@0.4.0) (2022-08-07)
+
+#### 🚀 Features
+
+- use named import objects ([4965f20](https://github.com/thi-ng/umbrella/commit/4965f20))
+  - switch to name import objects to avoid merging into flat namespace
+  - update externs in core.zig
+  - update docstrings
+
 ## [0.3.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/wasm-api@0.3.0) (2022-08-04)
 
 #### 🚀 Features

package/README.md

@@ -57,15 +57,15 @@ export class CustomAPI implements IWasmAPI {
 
 	/**
 	 * Returns object of functions to import as externals into
-	 * the WASM module. These imports are merged with the bridge's
-	 * core API and hence should use naming prefixes...
+	 * the WASM module. These imports are merged into a larger
+	 * imports object alongside the bridge's core API...
 	 */
 	getImports(): WebAssembly.Imports {
 		return {
 			/**
 			 * Writes 2 random float32 numbers to given address
 			 */
-			custom_randomVec2: (addr: number) => {
+			randomVec2: (addr: number) => {
 				this.parent.f32.set(
 					[Math.random(), Math.random()],
 					addr >> 2
@@ -83,14 +83,17 @@ export const bridge = new WasmBridge({ custom: new CustomAPI() });
 ```
 
 In Zig (or any other language of your choice) we can then utilize this custom
-API like so (Please also see example further below in this readme):
+API like so (Please also see /test/index.ts` & the example further below in this
+readme):
 
 ```zig
 // Import JS core API
 const js = @import("wasmapi");
 
 /// JS external to fill vec2 w/ random values
-extern fn custom_randomVec2(addr: usize) void;
+/// Note: Each API module uses a separate import object to avoid naming clashes
+/// Here we declare an external binding belonging to the "custom" import group
+extern "custom" fn randomVec2(addr: usize) void;
 
 export fn test_randomVec2() void {
 	var foo = [2]f32{ 0, 0 };
@@ -99,7 +102,7 @@ export fn test_randomVec2() void {
 	js.printF32Array(foo[0..]);
 
 	// populate foo with random numbers
-	custom_randomVec2(@ptrToInt(&foo));
+	randomVec2(@ptrToInt(&foo));
 
 	// print result
 	js.printF32Array(foo[0..]);
@@ -182,7 +185,7 @@ node --experimental-repl-await
 > const wasmApi = await import("@thi.ng/wasm-api");
 ```
 
-Package sizes (gzipped, pre-treeshake): ESM: 1.63 KB
+Package sizes (gzipped, pre-treeshake): ESM: 1.61 KB
 
 ## Dependencies
 
@@ -212,6 +215,7 @@ interface App extends WasmExports {
 
 	// instantiate WASM module using imports provided by the bridge
 	// this also initializes any bindings & bridge child APIs (if any)
+	// (also accepts a fetch() `Response` as input)
 	await bridge.instantiate(readFileSync("hello.wasm"));
 
 	// call an exported WASM function
@@ -253,7 +257,7 @@ The resulting WASM:
 (module
  (type $i32_i32_=>_none (func (param i32 i32)))
  (type $none_=>_none (func))
- (import "env" "_printStr" (func $fimport$0 (param i32 i32)))
+ (import "core" "_printStr" (func $fimport$0 (param i32 i32)))
  (global $global$0 (mut i32) (i32.const 65536))
  (memory $0 2)
  (data (i32.const 65536) "hello world!\00")

package/api.d.ts

@@ -48,7 +48,7 @@ export interface WasmExports {
  * functions are declared as bindings in `/zig/core.zig`. Also see this file for
  * documentation of each function...
  */
-export interface CoreAPI {
+export interface CoreAPI extends WebAssembly.ModuleImports {
     printI8: Fn<number, void>;
     printU8: Fn<number, void>;
     printU8Hex: Fn<number, void>;

package/bridge.d.ts

@@ -32,8 +32,9 @@ export declare class WasmBridge<T extends WasmExports = WasmExports> {
     f64: Float64Array;
     utf8Decoder: TextDecoder;
     utf8Encoder: TextEncoder;
-    core: CoreAPI;
+    imports: WebAssembly.Imports;
     exports: T;
+    core: CoreAPI;
     constructor(modules?: Record<string, IWasmAPI<T>>, logger?: ILogger);
     /**
      * Instantiates WASM module from given `src` (and optional provided extra
@@ -63,9 +64,32 @@ export declare class WasmBridge<T extends WasmExports = WasmExports> {
      * API and any provided bridge API modules.
      *
      * @remarks
-     * Since all declared imports will be merged into a single flat namespace,
-     * it's recommended to use per-module naming prefixes to avoid clashes. If
-     * there're any naming clashes, this function will throw an error.
+     * Since v0.4.0 each API module's imports will be in their own WASM import
+     * table, named using the same key which was assigned to the module when
+     * creating the WASM bridge.
+     *
+     * @example
+     * The following creates a bridge with a fictional `custom` API module:
+     *
+     * ```ts
+     * const bridge = new WasmBridge({ custom: new CustomAPI() });
+     *
+     * // get combined imports object
+     * bridge.getImports();
+     * {
+     *   // imports defined by the core API of the bridge itself
+     *   core: { ... },
+     *   // imports defined by the CustomAPI module
+     *   custom: { ... }
+     * }
+     * ```
+     *
+     * Any related API bindings on the WASM (Zig) side then also need to refer
+     * to these custom import sections (also see `/zig/core.zig`):
+     *
+     * ```zig
+     * pub export "custom" fn foo(x: u32) void;
+     * ```
      */
     getImports(): WebAssembly.Imports;
     getI8(addr: number): number;

package/bridge.js

@@ -70,14 +70,10 @@ export class WasmBridge {
      */
     async instantiate(src, imports) {
         const $src = await src;
-        const $imports = { ...imports, ...this.getImports() };
-        let wasm;
-        if ($src instanceof Response) {
-            wasm = await WebAssembly.instantiateStreaming($src, $imports);
-        }
-        else {
-            wasm = await WebAssembly.instantiate($src, $imports);
-        }
+        const $imports = { ...this.getImports(), ...imports };
+        const wasm = await ($src instanceof Response
+            ? WebAssembly.instantiateStreaming($src, $imports)
+            : WebAssembly.instantiate($src, $imports));
         return this.init(wasm.instance.exports);
     }
     /**
@@ -114,23 +110,44 @@ export class WasmBridge {
      * API and any provided bridge API modules.
      *
      * @remarks
-     * Since all declared imports will be merged into a single flat namespace,
-     * it's recommended to use per-module naming prefixes to avoid clashes. If
-     * there're any naming clashes, this function will throw an error.
+     * Since v0.4.0 each API module's imports will be in their own WASM import
+     * table, named using the same key which was assigned to the module when
+     * creating the WASM bridge.
+     *
+     * @example
+     * The following creates a bridge with a fictional `custom` API module:
+     *
+     * ```ts
+     * const bridge = new WasmBridge({ custom: new CustomAPI() });
+     *
+     * // get combined imports object
+     * bridge.getImports();
+     * {
+     *   // imports defined by the core API of the bridge itself
+     *   core: { ... },
+     *   // imports defined by the CustomAPI module
+     *   custom: { ... }
+     * }
+     * ```
+     *
+     * Any related API bindings on the WASM (Zig) side then also need to refer
+     * to these custom import sections (also see `/zig/core.zig`):
+     *
+     * ```zig
+     * pub export "custom" fn foo(x: u32) void;
+     * ```
      */
     getImports() {
-        const env = { ...this.core };
-        for (let id in this.modules) {
-            const imports = this.modules[id].getImports();
-            // check for naming clashes
-            for (let k in imports) {
-                if (env[k] !== undefined) {
-                    illegalArgs(`attempt to redeclare import: ${k} by API module ${id}`);
+        if (!this.imports) {
+            this.imports = { core: this.core };
+            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();
             }
-            Object.assign(env, imports);
         }
-        return { env };
+        return this.imports;
     }
     getI8(addr) {
         return this.i8[addr];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/wasm-api",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Modular, extensible API bridge and generic glue code between JS & WebAssembly",
   "type": "module",
   "module": "./index.js",
@@ -92,5 +92,5 @@
     "status": "alpha",
     "year": 2022
   },
-  "gitHead": "01b7a47077d88c2aefe77650ce3340040bae00ee\n"
+  "gitHead": "0eeb5054111cea51f4714b013dda8700ade3cd54\n"
 }

package/test/custom.zig

@@ -2,11 +2,11 @@
 const js = @import("wasmapi");
 
 /// Fill vec2 with random values
-extern fn custom_setVec2(addr: usize) void;
+extern "custom" fn setVec2(addr: usize) void;
 
 export fn test_setVec2() void {
     var foo = [2]f32{ 0, 0 };
     js.printF32Array(foo[0..]);
-    custom_setVec2(@ptrToInt(&foo));
+    setVec2(@ptrToInt(&foo));
     js.printF32Array(foo[0..]);
 }

package/zig/core.zig

@@ -1,51 +1,51 @@
 //! JavaScript externals for https://thi.ng/wasm-api
 
 /// Prints number using configured JS logger
-pub extern fn printI8(x: i8) void;
+pub extern "core" fn printI8(x: i8) void;
 /// Prints number using configured JS logger
-pub extern fn printU8(x: u8) void;
+pub extern "core" fn printU8(x: u8) void;
 /// Prints hex number using configured JS logger
-pub extern fn printU8Hex(x: u8) void;
+pub extern "core" fn printU8Hex(x: u8) void;
 
 /// Prints number using configured JS logger
-pub extern fn printI16(x: i16) void;
+pub extern "core" fn printI16(x: i16) void;
 /// Prints number using configured JS logger
-pub extern fn printU16(x: u16) void;
+pub extern "core" fn printU16(x: u16) void;
 /// Prints hex number using configured JS logger
-pub extern fn printU16Hex(x: u16) void;
+pub extern "core" fn printU16Hex(x: u16) void;
 
 /// Prints number using configured JS logger
-pub extern fn printI32(x: i32) void;
+pub extern "core" fn printI32(x: i32) void;
 /// Prints number using configured JS logger
-pub extern fn printU32(x: u32) void;
+pub extern "core" fn printU32(x: u32) void;
 /// Prints hex number using configured JS logger
-pub extern fn printU32Hex(x: u32) void;
+pub extern "core" fn printU32Hex(x: u32) void;
 
 /// Prints decomposed i64 number using configured JS logger
-pub extern fn _printI64(hi: i32, lo: i32) void;
+pub extern "core" fn _printI64(hi: i32, lo: i32) void;
 /// Convenience wrapper for _printI64(), accepting an i64
 pub fn printI64(x: i64) void {
     _printI64(@truncate(i32, x >> 32), @truncate(i32, x));
 }
 
 /// Prints decomposed u64 number using configured JS logger
-pub extern fn _printU64(hi: u32, lo: u32) void;
+pub extern "core" fn _printU64(hi: u32, lo: u32) void;
 /// Convenience wrapper for _printU64(), accepting an u64
 pub fn printU64(x: u64) void {
     _printU64(@truncate(u32, x >> 32), @truncate(u32, x));
 }
 
 /// Prints decomposed u64 hex number using configured JS logger
-pub extern fn _printU64Hex(hi: u32, lo: u32) void;
+pub extern "core" fn _printU64Hex(hi: u32, lo: u32) void;
 /// Convenience wrapper for _printU64Hex(), accepting an u64
 pub fn printU64Hex(x: u64) void {
     _printU64Hex(@truncate(u32, x >> 32), @truncate(u32, x));
 }
 
 /// Prints number using configured JS logger
-pub extern fn printF32(x: f32) void;
+pub extern "core" fn printF32(x: f32) void;
 /// Prints number using configured JS logger
-pub extern fn printF64(x: f64) void;
+pub extern "core" fn printF64(x: f64) void;
 
 /// Prints pointer as hex number using configured JS logger
 pub fn printPtr(ptr: *const anyopaque) void {
@@ -53,25 +53,25 @@ pub fn printPtr(ptr: *const anyopaque) void {
 }
 
 /// Prints number array using configured JS logger
-pub extern fn _printI8Array(addr: usize, len: usize) void;
+pub extern "core" fn _printI8Array(addr: usize, len: usize) void;
 /// Prints number array using configured JS logger
-pub extern fn _printU8Array(addr: usize, len: usize) void;
+pub extern "core" fn _printU8Array(addr: usize, len: usize) void;
 /// Prints number array using configured JS logger
-pub extern fn _printI16Array(addr: usize, len: usize) void;
+pub extern "core" fn _printI16Array(addr: usize, len: usize) void;
 /// Prints number array using configured JS logger
-pub extern fn _printU16Array(addr: usize, len: usize) void;
+pub extern "core" fn _printU16Array(addr: usize, len: usize) void;
 /// Prints number array using configured JS logger
-pub extern fn _printI32Array(addr: usize, len: usize) void;
+pub extern "core" fn _printI32Array(addr: usize, len: usize) void;
 /// Prints number array using configured JS logger
-pub extern fn _printU32Array(addr: usize, len: usize) void;
+pub extern "core" fn _printU32Array(addr: usize, len: usize) void;
 /// Prints number array using configured JS logger
-pub extern fn _printI64Array(addr: usize, len: usize) void;
+pub extern "core" fn _printI64Array(addr: usize, len: usize) void;
 /// Prints number array using configured JS logger
-pub extern fn _printU64Array(addr: usize, len: usize) void;
+pub extern "core" fn _printU64Array(addr: usize, len: usize) void;
 /// Prints number array using configured JS logger
-pub extern fn _printF32Array(addr: usize, len: usize) void;
+pub extern "core" fn _printF32Array(addr: usize, len: usize) void;
 /// Prints number array using configured JS logger
-pub extern fn _printF64Array(addr: usize, len: usize) void;
+pub extern "core" fn _printF64Array(addr: usize, len: usize) void;
 
 /// Prints number array using configured JS logger
 pub fn printI8Array(buf: []const i8) void {
@@ -115,9 +115,9 @@ pub fn printF64Array(buf: []const f64) void {
 }
 
 /// Prints a zero-terminated string using configured JS logger
-extern fn _printStr0(addr: usize) void;
+pub extern "core" fn _printStr0(addr: usize) void;
 /// Prints a string of given length using configured JS logger
-extern fn _printStr(addr: usize, len: usize) void;
+pub extern "core" fn _printStr(addr: usize, len: usize) void;
 /// Convenience wrapper for _printStr, accepting a slice as arg
 pub fn printStr(msg: []const u8) void {
     _printStr(@ptrToInt(msg.ptr), msg.len);

package/dev/zig-cache/o/85202d15b9c43c8c66de01ab98d6eb2c/builtin.zig

@@ -1,39 +0,0 @@
-const std = @import("std");
-/// Zig version. When writing code that supports multiple versions of Zig, prefer
-/// feature detection (i.e. with `@hasDecl` or `@hasField`) over version checks.
-pub const zig_version = std.SemanticVersion.parse("0.10.0-dev.3034+6fab6c3e4") catch unreachable;
-pub const zig_backend = std.builtin.CompilerBackend.stage1;
-/// Temporary until self-hosted supports the `cpu.arch` value.
-pub const stage2_arch: std.Target.Cpu.Arch = .wasm32;
-
-pub const output_mode = std.builtin.OutputMode.Lib;
-pub const link_mode = std.builtin.LinkMode.Dynamic;
-pub const is_test = false;
-pub const single_threaded = true;
-pub const abi = std.Target.Abi.musl;
-pub const cpu: std.Target.Cpu = .{
-    .arch = .wasm32,
-    .model = &std.Target.wasm.cpu.generic,
-    .features = std.Target.wasm.featureSet(&[_]std.Target.wasm.Feature{
-    }),
-};
-pub const os = std.Target.Os{
-    .tag = .freestanding,
-    .version_range = .{ .none = {} },
-};
-pub const target = std.Target{
-    .cpu = cpu,
-    .os = os,
-    .abi = abi,
-};
-pub const object_format = std.Target.ObjectFormat.wasm;
-pub const mode = std.builtin.Mode.ReleaseSmall;
-pub const link_libc = false;
-pub const link_libcpp = false;
-pub const have_error_return_tracing = false;
-pub const valgrind_support = false;
-pub const sanitize_thread = false;
-pub const position_independent_code = true;
-pub const position_independent_executable = false;
-pub const strip_debug_info = true;
-pub const code_model = std.builtin.CodeModel.default;

package/dev/zig-cache/o/9e1187e9310422c9c2330ebceeaecce7/builtin.zig

@@ -1,39 +0,0 @@
-const std = @import("std");
-/// Zig version. When writing code that supports multiple versions of Zig, prefer
-/// feature detection (i.e. with `@hasDecl` or `@hasField`) over version checks.
-pub const zig_version = std.SemanticVersion.parse("0.10.0-dev.3034+6fab6c3e4") catch unreachable;
-pub const zig_backend = std.builtin.CompilerBackend.stage1;
-/// Temporary until self-hosted supports the `cpu.arch` value.
-pub const stage2_arch: std.Target.Cpu.Arch = .wasm32;
-
-pub const output_mode = std.builtin.OutputMode.Lib;
-pub const link_mode = std.builtin.LinkMode.Dynamic;
-pub const is_test = false;
-pub const single_threaded = true;
-pub const abi = std.Target.Abi.musl;
-pub const cpu: std.Target.Cpu = .{
-    .arch = .wasm32,
-    .model = &std.Target.wasm.cpu.generic,
-    .features = std.Target.wasm.featureSet(&[_]std.Target.wasm.Feature{
-    }),
-};
-pub const os = std.Target.Os{
-    .tag = .freestanding,
-    .version_range = .{ .none = {} },
-};
-pub const target = std.Target{
-    .cpu = cpu,
-    .os = os,
-    .abi = abi,
-};
-pub const object_format = std.Target.ObjectFormat.wasm;
-pub const mode = std.builtin.Mode.ReleaseSmall;
-pub const link_libc = false;
-pub const link_libcpp = false;
-pub const have_error_return_tracing = false;
-pub const valgrind_support = false;
-pub const sanitize_thread = false;
-pub const position_independent_code = true;
-pub const position_independent_executable = false;
-pub const strip_debug_info = true;
-pub const code_model = std.builtin.CodeModel.default;

package/dev/zig-cache/o/f647d1186cb589536c92b809f6e25f75/builtin.zig

@@ -1,39 +0,0 @@
-const std = @import("std");
-/// Zig version. When writing code that supports multiple versions of Zig, prefer
-/// feature detection (i.e. with `@hasDecl` or `@hasField`) over version checks.
-pub const zig_version = std.SemanticVersion.parse("0.10.0-dev.3034+6fab6c3e4") catch unreachable;
-pub const zig_backend = std.builtin.CompilerBackend.stage1;
-/// Temporary until self-hosted supports the `cpu.arch` value.
-pub const stage2_arch: std.Target.Cpu.Arch = .wasm32;
-
-pub const output_mode = std.builtin.OutputMode.Lib;
-pub const link_mode = std.builtin.LinkMode.Dynamic;
-pub const is_test = false;
-pub const single_threaded = true;
-pub const abi = std.Target.Abi.musl;
-pub const cpu: std.Target.Cpu = .{
-    .arch = .wasm32,
-    .model = &std.Target.wasm.cpu.generic,
-    .features = std.Target.wasm.featureSet(&[_]std.Target.wasm.Feature{
-    }),
-};
-pub const os = std.Target.Os{
-    .tag = .freestanding,
-    .version_range = .{ .none = {} },
-};
-pub const target = std.Target{
-    .cpu = cpu,
-    .os = os,
-    .abi = abi,
-};
-pub const object_format = std.Target.ObjectFormat.wasm;
-pub const mode = std.builtin.Mode.ReleaseSmall;
-pub const link_libc = false;
-pub const link_libcpp = false;
-pub const have_error_return_tracing = false;
-pub const valgrind_support = false;
-pub const sanitize_thread = false;
-pub const position_independent_code = true;
-pub const position_independent_executable = false;
-pub const strip_debug_info = true;
-pub const code_model = std.builtin.CodeModel.default;

package/test/zig-cache/o/117d44467ded6ce3864cde3c180ef73c/builtin.zig

@@ -1,39 +0,0 @@
-const std = @import("std");
-/// Zig version. When writing code that supports multiple versions of Zig, prefer
-/// feature detection (i.e. with `@hasDecl` or `@hasField`) over version checks.
-pub const zig_version = std.SemanticVersion.parse("0.10.0-dev.3034+6fab6c3e4") catch unreachable;
-pub const zig_backend = std.builtin.CompilerBackend.stage1;
-/// Temporary until self-hosted supports the `cpu.arch` value.
-pub const stage2_arch: std.Target.Cpu.Arch = .wasm32;
-
-pub const output_mode = std.builtin.OutputMode.Lib;
-pub const link_mode = std.builtin.LinkMode.Dynamic;
-pub const is_test = false;
-pub const single_threaded = true;
-pub const abi = std.Target.Abi.musl;
-pub const cpu: std.Target.Cpu = .{
-    .arch = .wasm32,
-    .model = &std.Target.wasm.cpu.generic,
-    .features = std.Target.wasm.featureSet(&[_]std.Target.wasm.Feature{
-    }),
-};
-pub const os = std.Target.Os{
-    .tag = .freestanding,
-    .version_range = .{ .none = {} },
-};
-pub const target = std.Target{
-    .cpu = cpu,
-    .os = os,
-    .abi = abi,
-};
-pub const object_format = std.Target.ObjectFormat.wasm;
-pub const mode = std.builtin.Mode.ReleaseSmall;
-pub const link_libc = false;
-pub const link_libcpp = false;
-pub const have_error_return_tracing = false;
-pub const valgrind_support = false;
-pub const sanitize_thread = false;
-pub const position_independent_code = true;
-pub const position_independent_executable = false;
-pub const strip_debug_info = true;
-pub const code_model = std.builtin.CodeModel.default;