@thi.ng/wasm-api 0.10.0 → 0.12.0

package/codegen.d.ts

@@ -1,26 +1,4 @@
-import { ICodeGen, TypeColl } from "./api.js";
-/**
- * Global/shared code generator options.
- */
-export interface CodeGenOpts {
-    /**
-     * Optional string to be injected before generated type defs (but after
-     * codegen's own prelude, if any)
-     */
-    pre: string;
-    /**
-     * Optional string to be injected after generated type defs (but before
-     * codegen's own epilogue, if any)
-     */
-    post: string;
-    /**
-     * Identifier how strings are stored on WASM side, e.g. in Zig string
-     * literals are slices (8 bytes), in C just plain pointers (4 bytes).
-     *
-     * @defaultValue "slice"
-     */
-    stringType: "slice" | "ptr";
-}
+import { CodeGenOpts, ICodeGen, TypeColl } from "./api.js";
 /**
  * Takes a type collection and analyzes each analyzed to compute individual
  * alignments and sizes.

package/codegen.js

@@ -4,12 +4,17 @@ import { ceilPow2 } from "@thi.ng/binary/pow";
 import { compareByKey } from "@thi.ng/compare/keys";
 import { compareNumDesc } from "@thi.ng/compare/numeric";
 import { DEFAULT, defmulti } from "@thi.ng/defmulti/defmulti";
+import { illegalArgs } from "@thi.ng/errors/illegal-arguments";
 import { PKG_NAME, USIZE_SIZE, } from "./api.js";
 import { isNumeric, isWasmString } from "./codegen/utils.js";
 const sizeOf = defmulti((x) => x.type, {}, {
     [DEFAULT]: (field, types, opts) => {
         if (field.__size)
             return field.__size;
+        if (field.pad != null) {
+            field.pad < 1 && illegalArgs(`pad size must be > 0`);
+            return (field.__size = field.pad);
+        }
         let size = 0;
         if (field.tag === "ptr") {
             size = USIZE_SIZE;
@@ -25,6 +30,9 @@ const sizeOf = defmulti((x) => x.type, {}, {
                     : sizeOf(types[field.type], types, opts);
             if (field.tag == "array" || field.tag === "vec") {
                 size *= field.len;
+                if (field.sentinel !== undefined && field.tag === "array") {
+                    size += SIZEOF[field.type];
+                }
             }
         }
         return (field.__size = align(size, field.__align));
@@ -51,6 +59,8 @@ const alignOf = defmulti((x) => x.type, {}, {
     [DEFAULT]: (field, types) => {
         if (field.__align)
             return field.__align;
+        if (field.pad)
+            return (field.__align = 1);
         let align = isNumeric(field.type)
             ? SIZEOF[field.type]
             : isWasmString(field.type)
@@ -62,7 +72,10 @@ const alignOf = defmulti((x) => x.type, {}, {
         field.__align = align;
         return align;
     },
-    enum: (e) => {
+    enum: (type) => {
+        const e = type;
+        if (!e.tag)
+            e.tag = "i32";
         return (e.__align = SIZEOF[e.tag]);
     },
     struct: (type, types) => {
@@ -130,19 +143,33 @@ export const prepareTypes = (types, opts) => {
  * @param opts
  */
 export const generateTypes = (types, codegen, opts = {}) => {
-    const $opts = { stringType: "slice", ...opts };
+    const $opts = {
+        header: true,
+        stringType: "slice",
+        uppercaseEnums: true,
+        lineWidth: 80,
+        ...opts,
+    };
     prepareTypes(types, $opts);
     const res = [];
-    codegen.doc(`Generated by ${PKG_NAME} at ${new Date().toISOString()} - DO NOT EDIT!`, "", res, true);
-    res.push("");
-    codegen.pre && res.push(codegen.pre, "");
+    if ($opts.header) {
+        codegen.doc(`Generated by ${PKG_NAME} at ${new Date().toISOString()} - DO NOT EDIT!`, res, $opts, true);
+        res.push("");
+    }
+    if (codegen.pre) {
+        const pre = codegen.pre($opts);
+        pre && res.push(pre, "");
+    }
     $opts.pre && res.push($opts.pre, "");
     for (let id in types) {
         const type = types[id];
-        type.doc && codegen.doc(type.doc, "", res);
-        codegen[type.type](type, types, res);
+        type.doc && codegen.doc(type.doc, res, $opts);
+        codegen[type.type](type, types, res, $opts);
     }
     $opts.post && res.push("", $opts.post);
-    codegen.post && res.push("", codegen.post);
+    if (codegen.post) {
+        const post = codegen.post($opts);
+        post && res.push("", post);
+    }
     return res.join("\n");
 };

package/include/wasmapi.h

@@ -9,9 +9,8 @@ extern "C" {
 
 // Declares an imported symbol from named import module
 // The prefix is only used for the C side, NOT for exported name
-#define WASM_IMPORT(MODULE, TYPE, NAME, PREFIX)                     \
-  extern __attribute__((import_module(MODULE), import_name(#NAME))) \
-  TYPE PREFIX##NAME
+#define WASM_IMPORT(MODULE, TYPE, NAME, PREFIX) \
+  extern __attribute__((import_module(MODULE), import_name(#NAME))) TYPE PREFIX##NAME
 
 // Same as EMSCRIPTEN_KEEP_ALIVE, ensures symbol will be exported
 #define WASM_KEEP __attribute__((used))
@@ -19,15 +18,24 @@ extern "C" {
 // Generate malloc/free wrappers only if explicitly enabled by defining this
 // symbol. If undefined some function stubs are exported.
 #ifdef WASMAPI_MALLOC
+
 #include <stdlib.h>
 size_t WASM_KEEP _wasm_allocate(size_t numBytes) {
   return (size_t)malloc(numBytes);
 }
-void WASM_KEEP _wasm_free(size_t addr) { free((void*)addr); }
+void WASM_KEEP _wasm_free(size_t addr, size_t numBytes) {
+  free((void*)addr);
+}
+
 #else
-size_t WASM_KEEP _wasm_allocate(size_t num_bytes) { return 0; }
-void WASM_KEEP _wasm_free(size_t addr) {}
-#endif
+
+size_t WASM_KEEP _wasm_allocate(size_t numBytes) {
+  return 0;
+}
+void WASM_KEEP _wasm_free(size_t addr, size_t numBytes) {
+}
+
+#endif  // WASMAPI_MALLOC
 
 WASM_IMPORT("wasmapi", void, printI8, wasm_)(int8_t x);
 WASM_IMPORT("wasmapi", void, printU8, wasm_)(uint8_t x);
@@ -44,23 +52,29 @@ WASM_IMPORT("wasmapi", void, printU64Hex, wasm_)(uint64_t x);
 WASM_IMPORT("wasmapi", void, printF32, wasm_)(float x);
 WASM_IMPORT("wasmapi", void, printF64, wasm_)(double x);
 
-WASM_IMPORT("wasmapi", void, _printI8Array, wasm)(void* addr, size_t len);
-WASM_IMPORT("wasmapi", void, _printU8Array, wasm)(void* addr, size_t len);
-WASM_IMPORT("wasmapi", void, _printI16Array, wasm)(void* addr, size_t len);
-WASM_IMPORT("wasmapi", void, _printU16Array, wasm)(void* addr, size_t len);
-WASM_IMPORT("wasmapi", void, _printI32Array, wasm)(void* addr, size_t len);
-WASM_IMPORT("wasmapi", void, _printU32Array, wasm)(void* addr, size_t len);
-WASM_IMPORT("wasmapi", void, _printI64Array, wasm)(void* addr, size_t len);
-WASM_IMPORT("wasmapi", void, _printU64Array, wasm)(void* addr, size_t len);
-WASM_IMPORT("wasmapi", void, _printF32Array, wasm)(void* addr, size_t len);
-WASM_IMPORT("wasmapi", void, _printF64Array, wasm)(void* addr, size_t len);
+WASM_IMPORT("wasmapi", void, _printI8Array, wasm)(const int8_t* addr, size_t len);
+WASM_IMPORT("wasmapi", void, _printU8Array, wasm)(const uint8_t* addr, size_t len);
+WASM_IMPORT("wasmapi", void, _printI16Array, wasm)(const int16_t* addr, size_t len);
+WASM_IMPORT("wasmapi", void, _printU16Array, wasm)(const uint16_t* addr, size_t len);
+WASM_IMPORT("wasmapi", void, _printI32Array, wasm)(const int32_t* addr, size_t len);
+WASM_IMPORT("wasmapi", void, _printU32Array, wasm)(const uint32_t* addr, size_t len);
+WASM_IMPORT("wasmapi", void, _printI64Array, wasm)(const int64_t* addr, size_t len);
+WASM_IMPORT("wasmapi", void, _printU64Array, wasm)(const uint64_t* addr, size_t len);
+WASM_IMPORT("wasmapi", void, _printF32Array, wasm)(const float* addr, size_t len);
+WASM_IMPORT("wasmapi", void, _printF64Array, wasm)(const double* addr, size_t len);
 
-WASM_IMPORT("wasmapi", void, _printStr0, wasm)(void* addr);
-WASM_IMPORT("wasmapi", void, _printStr, wasm)(void* addr, size_t len);
+WASM_IMPORT("wasmapi", void, _printStr0, wasm)(const char* addr);
+WASM_IMPORT("wasmapi", void, _printStr, wasm)(const char* addr, size_t len);
 
 WASM_IMPORT("wasmapi", void, debug, wasm_)(void);
+WASM_IMPORT("wasmapi", void, panic, wasm_)(const char*, size_t len);
 
-void wasm_printPtr(void* ptr) { wasm_printU32Hex((size_t)ptr); }
+WASM_IMPORT("wasmapi", double, timer, wasm_)(void);
+WASM_IMPORT("wasmapi", uint64_t, epoch, wasm_)(void);
+
+void wasm_printPtr(const void* ptr) {
+  wasm_printU32Hex((size_t)ptr);
+}
 
 #ifdef __cplusplus
 }

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, _: ?usize) 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.12.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,27 @@
     "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.3",
+    "@thi.ng/args": "^2.2.3",
+    "@thi.ng/binary": "^3.3.6",
+    "@thi.ng/checks": "^3.2.6",
+    "@thi.ng/compare": "^2.1.13",
+    "@thi.ng/defmulti": "^2.1.15",
+    "@thi.ng/errors": "^2.2.1",
+    "@thi.ng/file-io": "^0.3.12",
+    "@thi.ng/hex": "^2.2.1",
+    "@thi.ng/idgen": "^2.1.14",
+    "@thi.ng/logger": "^1.3.1",
+    "@thi.ng/paths": "^5.1.16",
+    "@thi.ng/strings": "^3.3.13"
   },
   "devDependencies": {
-    "@microsoft/api-extractor": "^7.25.0",
-    "@thi.ng/testament": "^0.2.12",
+    "@microsoft/api-extractor": "^7.31.1",
+    "@thi.ng/testament": "^0.3.1",
     "rimraf": "^3.0.2",
     "tools": "^0.0.1",
     "typedoc": "^0.22.17",
-    "typescript": "^4.7.4"
+    "typescript": "^4.8.3"
   },
   "keywords": [
     "allocator",
@@ -62,10 +64,12 @@
     "bindings",
     "c",
     "codegen",
+    "enum",
     "event",
     "id",
     "logger",
     "memory",
+    "polyglot",
     "string",
     "struct",
     "typedarray",
@@ -103,8 +107,8 @@
     "./bridge": {
       "default": "./bridge.js"
     },
-    "./codegen": {
-      "default": "./codegen.js"
+    "./codegen/c11": {
+      "default": "./codegen/c11.js"
     },
     "./codegen/typescript": {
       "default": "./codegen/typescript.js"
@@ -115,13 +119,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": "8600007d81a7dc92634a1d54e2c32b14ab30ba80\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,96 @@
+import type { IWasmMemoryAccess, ReadonlyWasmString } 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 ReadonlyWasmString {
+    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 ReadonlyWasmString {
+    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