@thi.ng/wasm-api 0.9.0 → 0.11.0

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.9.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,35 +36,44 @@
     "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",
     "api",
     "bindings",
     "c",
     "codegen",
+    "enum",
+    "event",
     "id",
     "logger",
     "memory",
+    "polyglot",
+    "string",
+    "struct",
+    "typedarray",
     "typescript",
+    "utf8",
     "wasm",
     "webassembly",
     "wrapper",
@@ -97,8 +106,8 @@
     "./bridge": {
       "default": "./bridge.js"
     },
-    "./codegen": {
-      "default": "./codegen.js"
+    "./codegen/c11": {
+      "default": "./codegen/c11.js"
     },
     "./codegen/typescript": {
       "default": "./codegen/typescript.js"
@@ -109,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": "be8423e2019e95c14a096260a93b9762dde0c768\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();
+    }
+}