@thi.ng/wasm-api 0.10.0 → 0.11.0

package/include/wasmapi.zig

@@ -3,9 +3,24 @@
 const std = @import("std");
 const root = @import("root");
 
+/// JS external part of the custom panic handler
+/// Prints message using configured JS logger and then throws JS error
+pub extern "wasmapi" fn _panic(addr: [*]const u8, len: usize) noreturn;
+
+/// Custom panic handler which prints given message using configured JS logger
+/// To use this handler, add the following line to your **root** source file:
+///
+/// ```
+/// pub const panic = @import("wasmapi").panic;
+/// ```
+pub fn panic(msg: []const u8, _: ?*std.builtin.StackTrace) noreturn {
+    _panic(msg.ptr, msg.len);
+    unreachable;
+}
+
 /// Obtains the allocator to be exposed to the WASM host env
 /// (via `_wasm_allocate()` and `_wasm_free()`).
-/// If the user defines a public `WASM_ALLOCATOR` in their root file
+/// If the user defines a public `WASM_ALLOCATOR` in their **root** file
 /// then this allocator will be used, otherwise the implementations
 /// of the two mentioned functions are no-ops.
 /// The `WASM_ALLOCATOR` can be changed and/or enabled/disabled dynamically
@@ -32,9 +47,9 @@ pub export fn _wasm_allocate(numBytes: usize) usize {
 /// Frees chunk of heap memory (previously allocated using `_wasm_allocate()`)
 /// starting at given address and of given byte length.
 /// Note: This is a no-op if no allocator is configured (see `allocator()`)
-pub export fn _wasm_free(addr: usize, numBytes: usize) void {
+pub export fn _wasm_free(addr: [*]u8, numBytes: usize) void {
     if (allocator()) |alloc| {
-        var mem = [2]usize{ addr, numBytes };
+        var mem = [2]usize{ @ptrToInt(addr), numBytes };
         alloc.free(@ptrCast(*[]u8, &mem).*);
     }
 }
@@ -60,26 +75,12 @@ pub extern "wasmapi" fn printU32(x: u32) void;
 /// Prints hex number using configured JS logger
 pub extern "wasmapi" fn printU32Hex(x: u32) void;
 
-/// Prints decomposed i64 number using configured JS logger
-pub extern "wasmapi" 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 "wasmapi" 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 "wasmapi" 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 i64 number using configured JS logger
+pub extern "wasmapi" fn printI64(x: i64) void;
+/// Prints u64 number using configured JS logger
+pub extern "wasmapi" fn printU64(x: u64) void;
+/// Prints u64 hex number using configured JS logger
+pub extern "wasmapi" fn printU64Hex(x: u64) void;
 
 /// Prints number using configured JS logger
 pub extern "wasmapi" fn printF32(x: f32) void;
@@ -92,74 +93,74 @@ pub fn printPtr(ptr: *const anyopaque) void {
 }
 
 /// Prints number array using configured JS logger
-pub extern "wasmapi" fn _printI8Array(addr: usize, len: usize) void;
+pub extern "wasmapi" fn _printI8Array(addr: [*]const i8, len: usize) void;
 /// Prints number array using configured JS logger
-pub extern "wasmapi" fn _printU8Array(addr: usize, len: usize) void;
+pub extern "wasmapi" fn _printU8Array(addr: [*]const u8, len: usize) void;
 /// Prints number array using configured JS logger
-pub extern "wasmapi" fn _printI16Array(addr: usize, len: usize) void;
+pub extern "wasmapi" fn _printI16Array(addr: [*]const i16, len: usize) void;
 /// Prints number array using configured JS logger
-pub extern "wasmapi" fn _printU16Array(addr: usize, len: usize) void;
+pub extern "wasmapi" fn _printU16Array(addr: [*]const u16, len: usize) void;
 /// Prints number array using configured JS logger
-pub extern "wasmapi" fn _printI32Array(addr: usize, len: usize) void;
+pub extern "wasmapi" fn _printI32Array(addr: [*]const i32, len: usize) void;
 /// Prints number array using configured JS logger
-pub extern "wasmapi" fn _printU32Array(addr: usize, len: usize) void;
+pub extern "wasmapi" fn _printU32Array(addr: [*]const u32, len: usize) void;
 /// Prints number array using configured JS logger
-pub extern "wasmapi" fn _printI64Array(addr: usize, len: usize) void;
+pub extern "wasmapi" fn _printI64Array(addr: [*]const i64, len: usize) void;
 /// Prints number array using configured JS logger
-pub extern "wasmapi" fn _printU64Array(addr: usize, len: usize) void;
+pub extern "wasmapi" fn _printU64Array(addr: [*]const u64, len: usize) void;
 /// Prints number array using configured JS logger
-pub extern "wasmapi" fn _printF32Array(addr: usize, len: usize) void;
+pub extern "wasmapi" fn _printF32Array(addr: [*]const f32, len: usize) void;
 /// Prints number array using configured JS logger
-pub extern "wasmapi" fn _printF64Array(addr: usize, len: usize) void;
+pub extern "wasmapi" fn _printF64Array(addr: [*]const f64, len: usize) void;
 
 /// Prints number array using configured JS logger
 pub fn printI8Array(buf: []const i8) void {
-    _printI8Array(@ptrToInt(buf.ptr), buf.len);
+    _printI8Array(buf.ptr, buf.len);
 }
 /// Prints number array using configured JS logger
 pub fn printU8Array(buf: []const u8) void {
-    _printU8Array(@ptrToInt(buf.ptr), buf.len);
+    _printU8Array(buf.ptr, buf.len);
 }
 /// Prints number array using configured JS logger
 pub fn printI16Array(buf: []const i16) void {
-    _printI16Array(@ptrToInt(buf.ptr), buf.len);
+    _printI16Array(buf.ptr, buf.len);
 }
 /// Prints number array using configured JS logger
 pub fn printU16Array(buf: []const u16) void {
-    _printU16Array(@ptrToInt(buf.ptr), buf.len);
+    _printU16Array(buf.ptr, buf.len);
 }
 /// Prints number array using configured JS logger
 pub fn printI32Array(buf: []const i32) void {
-    _printI32Array(@ptrToInt(buf.ptr), buf.len);
+    _printI32Array(buf.ptr, buf.len);
 }
 /// Prints number array using configured JS logger
 pub fn printU32Array(buf: []const u32) void {
-    _printU32Array(@ptrToInt(buf.ptr), buf.len);
+    _printU32Array(buf.ptr, buf.len);
 }
 /// Prints number array using configured JS logger
 pub fn printI64Array(buf: []const i64) void {
-    _printI64Array(@ptrToInt(buf.ptr), buf.len);
+    _printI64Array(buf.ptr, buf.len);
 }
 /// Prints number array using configured JS logger
 pub fn printU64Array(buf: []const u64) void {
-    _printU64Array(@ptrToInt(buf.ptr), buf.len);
+    _printU64Array(buf.ptr, buf.len);
 }
 /// Prints number array using configured JS logger
 pub fn printF32Array(buf: []const f32) void {
-    _printF32Array(@ptrToInt(buf.ptr), buf.len);
+    _printF32Array(buf.ptr, buf.len);
 }
 /// Prints number array using configured JS logger
 pub fn printF64Array(buf: []const f64) void {
-    _printF64Array(@ptrToInt(buf.ptr), buf.len);
+    _printF64Array(buf.ptr, buf.len);
 }
 
 /// Prints a zero-terminated string using configured JS logger
-pub extern "wasmapi" fn _printStr0(addr: usize) void;
+pub extern "wasmapi" fn _printStr0(addr: [*]const u8) void;
 /// Prints a string of given length using configured JS logger
-pub extern "wasmapi" fn _printStr(addr: usize, len: usize) void;
+pub extern "wasmapi" fn _printStr(addr: [*]const u8, 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);
+    _printStr(msg.ptr, msg.len);
 }
 
 /// Calls std.fmt.allocPrint to format given string, then calls `printStr()`
@@ -175,3 +176,9 @@ pub fn printFmt(comptime fmt: []const u8, args: anytype) void {
 
 /// Triggers the JS/browser debugger
 pub extern "wasmapi" fn debug() void;
+
+/// Returns a JS/browser highres timer value (via `performance.now()`)
+pub extern "wasmapi" fn timer() f64;
+
+/// Returns a JS/browser Unix epoch (via `Date.now()`)
+pub extern "wasmapi" fn epoch() u64;

package/index.d.ts

@@ -1,8 +1,11 @@
 export * from "./api.js";
 export * from "./bridge.js";
 export * from "./codegen.js";
+export * from "./codegen/c11.js";
 export * from "./codegen/typescript.js";
 export * from "./codegen/utils.js";
 export * from "./codegen/zig.js";
 export * from "./object-index.js";
+export * from "./pointer.js";
+export * from "./string.js";
 //# sourceMappingURL=index.d.ts.map

package/index.js

@@ -1,7 +1,10 @@
 export * from "./api.js";
 export * from "./bridge.js";
 export * from "./codegen.js";
+export * from "./codegen/c11.js";
 export * from "./codegen/typescript.js";
 export * from "./codegen/utils.js";
 export * from "./codegen/zig.js";
 export * from "./object-index.js";
+export * from "./pointer.js";
+export * from "./string.js";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@thi.ng/wasm-api",
-  "version": "0.10.0",
-  "description": "Generic, modular, extensible API bridge, glue code and bindings code generator for hybrid JS & WebAssembly projects",
+  "version": "0.11.0",
+  "description": "Generic, modular, extensible API bridge, polyglot glue code and bindings code generators for hybrid JS & WebAssembly projects",
   "type": "module",
   "module": "./index.js",
   "typings": "./index.d.ts",
@@ -36,25 +36,26 @@
     "test:build-zig": "zig build-lib -O ReleaseSmall -target wasm32-freestanding -dynamic --strip --pkg-begin wasmapi include/wasmapi.zig --pkg-end test/custom.zig && wasm-dis -o custom.wast custom.wasm && cp custom.wasm test"
   },
   "dependencies": {
-    "@thi.ng/api": "^8.4.1",
-    "@thi.ng/args": "^2.2.1",
-    "@thi.ng/binary": "^3.3.4",
-    "@thi.ng/checks": "^3.2.4",
-    "@thi.ng/compare": "^2.1.11",
-    "@thi.ng/defmulti": "^2.1.13",
-    "@thi.ng/errors": "^2.1.10",
-    "@thi.ng/file-io": "^0.3.10",
-    "@thi.ng/hex": "^2.1.9",
-    "@thi.ng/idgen": "^2.1.12",
-    "@thi.ng/logger": "^1.2.1"
+    "@thi.ng/api": "^8.4.2",
+    "@thi.ng/args": "^2.2.2",
+    "@thi.ng/binary": "^3.3.5",
+    "@thi.ng/checks": "^3.2.5",
+    "@thi.ng/compare": "^2.1.12",
+    "@thi.ng/defmulti": "^2.1.14",
+    "@thi.ng/errors": "^2.2.0",
+    "@thi.ng/file-io": "^0.3.11",
+    "@thi.ng/hex": "^2.2.0",
+    "@thi.ng/idgen": "^2.1.13",
+    "@thi.ng/logger": "^1.3.0",
+    "@thi.ng/paths": "^5.1.15"
   },
   "devDependencies": {
-    "@microsoft/api-extractor": "^7.25.0",
-    "@thi.ng/testament": "^0.2.12",
+    "@microsoft/api-extractor": "^7.31.1",
+    "@thi.ng/testament": "^0.3.0",
     "rimraf": "^3.0.2",
     "tools": "^0.0.1",
     "typedoc": "^0.22.17",
-    "typescript": "^4.7.4"
+    "typescript": "^4.8.3"
   },
   "keywords": [
     "allocator",
@@ -62,10 +63,12 @@
     "bindings",
     "c",
     "codegen",
+    "enum",
     "event",
     "id",
     "logger",
     "memory",
+    "polyglot",
     "string",
     "struct",
     "typedarray",
@@ -103,8 +106,8 @@
     "./bridge": {
       "default": "./bridge.js"
     },
-    "./codegen": {
-      "default": "./codegen.js"
+    "./codegen/c11": {
+      "default": "./codegen/c11.js"
     },
     "./codegen/typescript": {
       "default": "./codegen/typescript.js"
@@ -115,13 +118,22 @@
     "./codegen/zig": {
       "default": "./codegen/zig.js"
     },
+    "./codegen": {
+      "default": "./codegen.js"
+    },
     "./object-index": {
       "default": "./object-index.js"
+    },
+    "./pointer": {
+      "default": "./pointer.js"
+    },
+    "./string": {
+      "default": "./string.js"
     }
   },
   "thi.ng": {
     "status": "alpha",
     "year": 2022
   },
-  "gitHead": "4264b91052b8c1f74db9fd51dc48c830dc0d5829\n"
+  "gitHead": "973139c5aa3b50081020f4cc726a7cc330f77fc7\n"
 }

package/pointer.d.ts

@@ -0,0 +1,23 @@
+import type { Fn, IDeref } from "@thi.ng/api";
+import type { IWasmMemoryAccess } from "./api.js";
+/**
+ * Generic pointer facility which on {@link Pointer.deref()} calls wrapper
+ * function (provided as ctor arg) to realise the pointer's target value. The
+ * pointer's target address can be accessed via {@link Pointer.addr}
+ * (read/write).
+ *
+ * @remarks
+ * The pointer always behaves like `volatile`, i.e. memoization of target values
+ * is purposfully avoided and the wrapper function is executed anew _each_ time
+ * the pointer is deref'd.
+ */
+export declare class Pointer<T> implements IDeref<T> {
+    readonly mem: IWasmMemoryAccess;
+    readonly base: number;
+    readonly fn: Fn<number, T>;
+    constructor(mem: IWasmMemoryAccess, base: number, fn: Fn<number, T>);
+    get addr(): number;
+    set addr(addr: number);
+    deref(): T;
+}
+//# sourceMappingURL=pointer.d.ts.map

package/pointer.js

@@ -0,0 +1,27 @@
+/**
+ * Generic pointer facility which on {@link Pointer.deref()} calls wrapper
+ * function (provided as ctor arg) to realise the pointer's target value. The
+ * pointer's target address can be accessed via {@link Pointer.addr}
+ * (read/write).
+ *
+ * @remarks
+ * The pointer always behaves like `volatile`, i.e. memoization of target values
+ * is purposfully avoided and the wrapper function is executed anew _each_ time
+ * the pointer is deref'd.
+ */
+export class Pointer {
+    constructor(mem, base, fn) {
+        this.mem = mem;
+        this.base = base;
+        this.fn = fn;
+    }
+    get addr() {
+        return this.mem.u32[this.base >>> 2];
+    }
+    set addr(addr) {
+        this.mem.u32[this.base >>> 2] = addr;
+    }
+    deref() {
+        return this.fn(this.addr);
+    }
+}

package/string.d.ts

@@ -0,0 +1,97 @@
+import type { IDeref } from "@thi.ng/api";
+import type { IWasmMemoryAccess } from "./api.js";
+/**
+ * Memory mapped string wrapper for Zig-style UTF-8 encoded byte slices (aka
+ * pointer & length pair). The actual JS string can be obtained via
+ * {@link WasmStringSlice.deref} and mutated via {@link WasmStringSlice.set}.
+ */
+export declare class WasmStringSlice implements IDeref<string> {
+    readonly mem: IWasmMemoryAccess;
+    readonly base: number;
+    readonly isConst: boolean;
+    readonly max: number;
+    constructor(mem: IWasmMemoryAccess, base: number, isConst?: boolean);
+    /**
+     * Returns string start address (deref'd pointer).
+     */
+    get addr(): number;
+    /**
+     * Returns string length (read from memory)
+     */
+    get length(): number;
+    /**
+     * Returns memory as JS string (aka wrapper for
+     * {@link WasmBridge.getString}).
+     */
+    deref(): string;
+    /**
+     * If given a JS string as arg (and if **not** a const slice), attempts to
+     * overwrite this wrapped string's memory with bytes from given string. If
+     * given another {@link WasmStringSlice} as arg, only the slice pointer &
+     * new length will be updated (always succeeds).
+     *
+     * @remarks
+     * When copying bytes from a JS string, an error will be thrown if the new
+     * string is longer than the _original_ length of the slice (i.e. from when
+     * this `WasmStringSlice` wrapper instance was created). Also updates the
+     * slice's length field to new string length.
+     *
+     * Passing a `WasmString` instance as arg is faster than JS string since
+     * only the slice definition itself will be updated.
+     *
+     * @param str
+     */
+    set(str: string | WasmStringSlice): void;
+    toJSON(): string;
+    toString(): string;
+    valueOf(): string;
+}
+/**
+ * Memory mapped string wrapper for C-style UTF-8 encoded and zero-terminated
+ * char pointers. The actual JS string can be obtained via
+ * {@link WasmStringSlice.deref} and mutated via {@link WasmStringSlice.set}.
+ */
+export declare class WasmStringPtr implements IDeref<string> {
+    readonly mem: IWasmMemoryAccess;
+    readonly base: number;
+    readonly isConst: boolean;
+    constructor(mem: IWasmMemoryAccess, base: number, isConst?: boolean);
+    /**
+     * Returns string start address (deref'd pointer).
+     */
+    get addr(): number;
+    set addr(addr: number);
+    /**
+     * Returns computed string length (scanning memory for zero sentinel)
+     */
+    get length(): number;
+    /**
+     * Returns memory as JS string (aka wrapper for
+     * {@link WasmBridge.getString}).
+     */
+    deref(): string;
+    /**
+     * If given a JS string as arg (and if not a const pointer), attempts to
+     * overwrite this wrapped string's memory with bytes from given string. If
+     * given another {@link WasmStringPtr}, it merely overrides the pointer to
+     * the new one (always succeeds).
+     *
+     * @remarks
+     * Unlike with {@link WasmStringSlice.set} this implementation which
+     * performs bounds checking when copying bytes from a JS string, this method
+     * only throws an error if the new string is longer than the available
+     * memory (from the start address until the end of the WASM memory).
+     * **Therefore, this is as (un)safe as a C pointer and should be used with
+     * caution!**
+     *
+     * Passing a `WasmStringPtr` instance as arg is faster than JS string since
+     * only the pointer itself will be updated.
+     *
+     * @param str
+     */
+    set(str: string | WasmStringPtr): void;
+    toJSON(): string;
+    toString(): string;
+    valueOf(): string;
+}
+//# sourceMappingURL=string.d.ts.map

package/string.js

@@ -0,0 +1,145 @@
+import { unsupported } from "@thi.ng/errors/unsupported";
+/**
+ * Memory mapped string wrapper for Zig-style UTF-8 encoded byte slices (aka
+ * pointer & length pair). The actual JS string can be obtained via
+ * {@link WasmStringSlice.deref} and mutated via {@link WasmStringSlice.set}.
+ */
+export class WasmStringSlice {
+    constructor(mem, base, isConst = true) {
+        this.mem = mem;
+        this.base = base;
+        this.isConst = isConst;
+        this.max = this.length;
+    }
+    /**
+     * Returns string start address (deref'd pointer).
+     */
+    get addr() {
+        return this.mem.u32[this.base >>> 2];
+    }
+    /**
+     * Returns string length (read from memory)
+     */
+    get length() {
+        return this.mem.u32[(this.base + 4) >>> 2];
+    }
+    /**
+     * Returns memory as JS string (aka wrapper for
+     * {@link WasmBridge.getString}).
+     */
+    deref() {
+        return this.mem.getString(this.addr, this.length);
+    }
+    /**
+     * If given a JS string as arg (and if **not** a const slice), attempts to
+     * overwrite this wrapped string's memory with bytes from given string. If
+     * given another {@link WasmStringSlice} as arg, only the slice pointer &
+     * new length will be updated (always succeeds).
+     *
+     * @remarks
+     * When copying bytes from a JS string, an error will be thrown if the new
+     * string is longer than the _original_ length of the slice (i.e. from when
+     * this `WasmStringSlice` wrapper instance was created). Also updates the
+     * slice's length field to new string length.
+     *
+     * Passing a `WasmString` instance as arg is faster than JS string since
+     * only the slice definition itself will be updated.
+     *
+     * @param str
+     */
+    set(str) {
+        if (typeof str === "string") {
+            if (this.isConst)
+                unsupported("can't mutate const string");
+            this.mem.u32[(this.base + 4) >>> 2] = this.mem.setString(str, this.addr, this.max + 1, true);
+        }
+        else {
+            this.mem.u32[this.base >>> 2] = str.addr;
+            this.mem.u32[(this.base + 4) >>> 2] = str.length;
+        }
+    }
+    toJSON() {
+        return this.deref();
+    }
+    toString() {
+        return this.deref();
+    }
+    valueOf() {
+        return this.deref();
+    }
+}
+/**
+ * Memory mapped string wrapper for C-style UTF-8 encoded and zero-terminated
+ * char pointers. The actual JS string can be obtained via
+ * {@link WasmStringSlice.deref} and mutated via {@link WasmStringSlice.set}.
+ */
+export class WasmStringPtr {
+    constructor(mem, base, isConst = true) {
+        this.mem = mem;
+        this.base = base;
+        this.isConst = isConst;
+    }
+    /**
+     * Returns string start address (deref'd pointer).
+     */
+    get addr() {
+        return this.mem.u32[this.base >>> 2];
+    }
+    set addr(addr) {
+        this.mem.u32[this.base >>> 2] = addr;
+    }
+    /**
+     * Returns computed string length (scanning memory for zero sentinel)
+     */
+    get length() {
+        const addr = this.addr;
+        const idx = this.mem.u8.indexOf(0, addr);
+        return idx >= 0 ? idx - addr : 0;
+    }
+    /**
+     * Returns memory as JS string (aka wrapper for
+     * {@link WasmBridge.getString}).
+     */
+    deref() {
+        return this.mem.getString(this.addr, this.length);
+    }
+    /**
+     * If given a JS string as arg (and if not a const pointer), attempts to
+     * overwrite this wrapped string's memory with bytes from given string. If
+     * given another {@link WasmStringPtr}, it merely overrides the pointer to
+     * the new one (always succeeds).
+     *
+     * @remarks
+     * Unlike with {@link WasmStringSlice.set} this implementation which
+     * performs bounds checking when copying bytes from a JS string, this method
+     * only throws an error if the new string is longer than the available
+     * memory (from the start address until the end of the WASM memory).
+     * **Therefore, this is as (un)safe as a C pointer and should be used with
+     * caution!**
+     *
+     * Passing a `WasmStringPtr` instance as arg is faster than JS string since
+     * only the pointer itself will be updated.
+     *
+     * @param str
+     */
+    set(str) {
+        const addr = this.addr;
+        if (typeof str === "string") {
+            if (this.isConst)
+                unsupported("can't mutate const string");
+            this.mem.setString(str, addr, this.mem.u8.byteLength - addr, true);
+        }
+        else {
+            this.addr = str.addr;
+        }
+    }
+    toJSON() {
+        return this.deref();
+    }
+    toString() {
+        return this.deref();
+    }
+    valueOf() {
+        return this.deref();
+    }
+}