@thi.ng/wasm-api 0.4.0 → 0.7.0

package/api.d.ts

@@ -1,5 +1,6 @@
-import type { Fn, Fn2 } from "@thi.ng/api";
+import type { BigType, FloatType, Fn, Fn2 } from "@thi.ng/api";
 import type { WasmBridge } from "./bridge.js";
+export declare const PKG_NAME = "@thi.ng/wasm-api";
 export declare type BigIntArray = bigint[] | BigInt64Array | BigUint64Array;
 /**
  * Common interface for WASM/JS child APIs which will be used in combination
@@ -27,7 +28,8 @@ export interface IWasmAPI<T extends WasmExports = WasmExports> {
 }
 /**
  * Base interface of exports declared by the WASM module. At the very least, the
- * module needs to export its memory.
+ * module needs to export its memory and the functions defined in this
+ * interface.
  *
  * @remarks
  * This interface is supposed to be extended with the concrete exports defined
@@ -39,9 +41,42 @@ export interface IWasmAPI<T extends WasmExports = WasmExports> {
 export interface WasmExports {
     /**
      * The WASM module's linear memory buffer. The `WasmBridge` automatically
-     * creates various typed views of that memory.
+     * creates various typed views of that memory (i.e. u8, u16, u32, f32 etc.)
      */
     memory: WebAssembly.Memory;
+    /**
+     * Implementation specific memory allocation function (likely heap-based).
+     * If successful returns address of new memory block, or zero if
+     * unsuccessful.
+     *
+     * @remarks
+     * In the supplied Zig bindings (see `/zig/core.zig`), by default this is
+     * using the `std.heap.GeneralPurposeAllocator` (which also automatically
+     * handles growing the WASM memory), however as mentioned the underlying
+     * mechanism is purposefully left to the actual WASM-side implementation. In
+     * a C program, this would likely use `malloc()` or similar...
+     */
+    _wasm_allocate(numBytes: number): number;
+    /**
+     * Implementation specific function to free a previously allocated chunk of
+     * of WASM memory (allocated via {@link WasmExports._wasm_allocate}).
+     *
+     * @param addr
+     * @param numBytes
+     */
+    _wasm_free(addr: number, numBytes: number): void;
+}
+export interface WasmMemViews {
+    i8: Int8Array;
+    u8: Uint8Array;
+    i16: Int16Array;
+    u16: Uint16Array;
+    i32: Int32Array;
+    u32: Uint32Array;
+    i64: BigInt64Array;
+    u64: BigUint64Array;
+    f32: Float32Array;
+    f64: Float64Array;
 }
 /**
  * Core API of WASM imports defined by the {@link WasmBridge}. The same
@@ -76,4 +111,179 @@ export interface CoreAPI extends WebAssembly.ModuleImports {
     _printStr0: (addr: number) => void;
     _printStr: (addr: number, len: number) => void;
 }
+export interface WasmTypeBase {
+    /**
+     * Base address in linear WASM memory.
+     */
+    readonly __base: number;
+    /**
+     * Obtain as byte buffer
+     */
+    readonly __bytes: Uint8Array;
+}
+export interface WasmType<T> {
+    readonly align: number;
+    readonly size: number;
+    instance: Fn<number, T>;
+}
+export declare type WasmTypeConstructor<T> = Fn<WasmMemViews, WasmType<T>>;
+export declare type WasmInt = "i8" | "i16" | "i32" | "i64";
+export declare type WasmUint = "u8" | "u16" | "u32" | "u64";
+export declare type WasmFloat = FloatType;
+export declare type WasmPrim = WasmInt | WasmUint | WasmFloat;
+export declare type WasmPrim32 = Exclude<WasmPrim, BigType>;
+export declare type TypeColl = Record<string, TopLevelType>;
+export interface TypeInfo {
+    /**
+     * Auto-computed size (in bytes)
+     *
+     * @internal
+     */
+    __size?: number;
+    /**
+     * Auto-computed offset (in bytes) in parent struct
+     *
+     * @internal
+     */
+    __offset?: number;
+    /**
+     * Auto-computed alignment (in bytes)
+     *
+     * @internal
+     */
+    __align?: number;
+}
+export interface TopLevelType extends TypeInfo {
+    /**
+     * Type name
+     */
+    name: string;
+    /**
+     * Optional (multi-line) docstring for this type
+     */
+    doc?: string;
+    /**
+     * Type / kind
+     */
+    type: "struct" | "enum";
+}
+export interface Struct extends TopLevelType {
+    type: "struct";
+    /**
+     * List of struct fields (might be re-ordered if {@link Struct.auto} is
+     * enabled).
+     */
+    fields: StructField[];
+    /**
+     * If true, struct fields will be re-ordered in descending order based on
+     * their {@link TypeInfo.__align} size. This might result in overall smaller
+     * structs due to minimizing inter-field padding.
+     *
+     * @defaultValue false
+     */
+    auto?: boolean;
+}
+export interface StructField extends TypeInfo {
+    /**
+     * Field name (prefix: "__" is reserved)
+     */
+    name: string;
+    /**
+     * Field docstring (can be multiline, will be formatted)
+     */
+    doc?: string;
+    /**
+     * Field type tag/qualifier (note: `slice` & `vec` are only supported by Zig
+     * & TS).
+     *
+     * @remarks
+     * - Array & vector fields are statically sized (using
+     *   {@link StructField.len})
+     * - Pointers are emitted as single-value pointers (where this distinction
+     *   exist), i.e. even if they're pointing to multiple values, there's no
+     *   explicit length encoded/available
+     * - Zig slices are essentially a pointer w/ associated length
+     * - Zig vectors will be processed using SIMD (if enabled in WASM target)
+     *   and therefore will have stricter (larger) alignment requirements.
+     *
+     * @defaultValue "scalar"
+     */
+    tag?: "scalar" | "array" | "ptr" | "slice" | "vec";
+    /**
+     * Field base type. If not a {@link WasmPrim} or `opaque`, the value is
+     * interpreted as another type name in the {@link TypeColl}.
+     *
+     * TODO `opaque` currently unsupported.
+     * TODO add string support (see {@link StructField.sentinel})
+     */
+    type: WasmPrim | "opaque" | string;
+    /**
+     * TODO currently unsupported & ignored!
+     */
+    sentinel?: number;
+    /**
+     * Array or vector length (see {@link StructField.tag})
+     */
+    len?: number;
+    /**
+     * TODO currently unsupported & ignored!
+     */
+    default?: any;
+}
+export interface Enum extends TopLevelType {
+    type: "enum";
+    /**
+     * No i64/u64 support, due to Typescript not supporting bigint enum values
+     */
+    tag: Exclude<WasmPrim32, FloatType>;
+    /**
+     * List of possible values/IDs. Use {@link EnumValue}s for more detailed
+     * config.
+     */
+    values: (string | EnumValue)[];
+}
+export interface EnumValue {
+    /**
+     * Enum value name/ID
+     */
+    name: string;
+    /**
+     * Optional associated numeric value
+     */
+    value?: number;
+    /**
+     * Optional docstring for this value
+     */
+    doc?: string;
+}
+export interface ICodeGen {
+    /**
+     * Optional prelude source, to be prepended before any generated type defs.
+     */
+    pre?: string;
+    /**
+     * Optional source code to be appended after any generated type defs.
+     */
+    post?: string;
+    /**
+     * Docstring codegen
+     */
+    doc: (doc: string, indent: string, acc: string[], topLevel?: boolean) => void;
+    /**
+     * Codegen for enum types.
+     */
+    enum: (type: Enum, types: TypeColl, acc: string[]) => void;
+    /**
+     * Codegen for struct types.
+     */
+    struct: (type: Struct, types: TypeColl, acc: string[]) => void;
+}
+/**
+ * WASM usize type. Assuming wasm32 until wasm64 surfaces, then need an option.
+ */
+export declare const USIZE = "u32";
+/**
+ * Byte size of {@link USIZE}.
+ */
+export declare const USIZE_SIZE = 4;
 //# sourceMappingURL=api.d.ts.map

package/api.js

@@ -1 +1,9 @@
-export {};
+export const PKG_NAME = "@thi.ng/wasm-api";
+/**
+ * WASM usize type. Assuming wasm32 until wasm64 surfaces, then need an option.
+ */
+export const USIZE = "u32";
+/**
+ * Byte size of {@link USIZE}.
+ */
+export const USIZE_SIZE = 4;

package/bin/wasm-api

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+
+# https://stackoverflow.com/a/246128/294515
+SOURCE="${BASH_SOURCE[0]}"
+while [ -h "$SOURCE" ]; do
+  DIR="$( cd -P "$( dirname "$SOURCE" )" >/dev/null 2>&1 && pwd )"
+  SOURCE="$(readlink "$SOURCE")"
+  [[ $SOURCE != /* ]] && SOURCE="$DIR/$SOURCE"
+done
+DIR="$( cd -P "$( dirname "$SOURCE" )" >/dev/null 2>&1 && pwd )"
+
+/usr/bin/env node "$DIR/../cli.js" "$DIR" "$@"

package/bridge.d.ts

@@ -1,6 +1,17 @@
+/// <reference types="node" />
 import type { NumericArray } from "@thi.ng/api";
 import type { ILogger } from "@thi.ng/logger";
-import type { BigIntArray, CoreAPI, IWasmAPI, WasmExports } from "./api.js";
+import type { BigIntArray, CoreAPI, IWasmAPI, WasmExports, WasmMemViews } from "./api.js";
+export declare const OutOfMemoryError: {
+    new (msg?: string | undefined): {
+        name: string;
+        message: string;
+        stack?: string | undefined;
+    };
+    captureStackTrace(targetObject: object, constructorOpt?: Function | undefined): void;
+    prepareStackTrace?: ((err: Error, stackTraces: NodeJS.CallSite[]) => any) | undefined;
+    stackTraceLimit: number;
+};
 /**
  * The main interop API bridge between the JS host environment and a WebAssembly
  * module. This class provides a small core API with various typed accessors and
@@ -17,7 +28,7 @@ import type { BigIntArray, CoreAPI, IWasmAPI, WasmExports } from "./api.js";
  * 64bit integers are handled via JS `BigInt` and hence require the host env to
  * support it. No polyfill is provided.
  */
-export declare class WasmBridge<T extends WasmExports = WasmExports> {
+export declare class WasmBridge<T extends WasmExports = WasmExports> implements WasmMemViews {
     modules: Record<string, IWasmAPI<T>>;
     logger: ILogger;
     i8: Int8Array;
@@ -34,7 +45,7 @@ export declare class WasmBridge<T extends WasmExports = WasmExports> {
     utf8Encoder: TextEncoder;
     imports: WebAssembly.Imports;
     exports: T;
-    core: CoreAPI;
+    api: CoreAPI;
     constructor(modules?: Record<string, IWasmAPI<T>>, logger?: ILogger);
     /**
      * Instantiates WASM module from given `src` (and optional provided extra
@@ -58,6 +69,11 @@ export declare class WasmBridge<T extends WasmExports = WasmExports> {
      * @param exports
      */
     init(exports: T): Promise<boolean>;
+    /**
+     * Called automatically. Initializes and/or updates the various typed WASM
+     * memory views (e.g. after growing the WASM memory).
+     */
+    ensureMemory(): void;
     /**
      * Required use for WASM module instantiation to provide JS imports to the
      * module. Returns an object of all WASM imports declared by the bridge core
@@ -65,8 +81,9 @@ export declare class WasmBridge<T extends WasmExports = WasmExports> {
      *
      * @remarks
      * 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.
+     * object, named using the same key which was assigned to the module when
+     * creating the WASM bridge. The bridge's core API will be named `core` and
+     * is reserved.
      *
      * @example
      * The following creates a bridge with a fictional `custom` API module:
@@ -78,7 +95,7 @@ export declare class WasmBridge<T extends WasmExports = WasmExports> {
      * bridge.getImports();
      * {
      *   // imports defined by the core API of the bridge itself
-     *   core: { ... },
+     *   wasmapi: { ... },
      *   // imports defined by the CustomAPI module
      *   custom: { ... }
      * }
@@ -92,6 +109,38 @@ export declare class WasmBridge<T extends WasmExports = WasmExports> {
      * ```
      */
     getImports(): WebAssembly.Imports;
+    /**
+     * Attempts to grow the WASM memory by an additional `numPages` (64KB/page)
+     * and if successful updates all typed memory views to use the new
+     * underlying buffer.
+     *
+     * @param numPages
+     */
+    growMemory(numPages: number): void;
+    /**
+     * Attempts to allocate `numBytes` using the exported WASM core API function
+     * {@link WasmExports._wasm_allocate} (implementation specific) and returns
+     * start address of the new memory block. If unsuccessful, throws an
+     * {@link OutOfMemoryError}. If `clear` is true, the allocated region will
+     * be zero-filled.
+     *
+     * @remarks
+     * See {@link WasmExports._wasm_allocate} docs for further details.
+     *
+     * @param numBytes
+     * @param clear
+     */
+    allocate(numBytes: number, clear?: boolean): number;
+    /**
+     * Frees a previous allocated memory region using the exported WASM core API
+     * function {@link WasmExports._wasm_free} (implementation specific). The
+     * `numBytes` value must be the same as previously given to
+     * {@link WasmBridge.allocate}.
+     *
+     * @param addr
+     * @param numBytes
+     */
+    free(addr: number, numBytes: number): void;
     getI8(addr: number): number;
     getU8(addr: number): number;
     getI16(addr: number): number;
@@ -132,7 +181,30 @@ export declare class WasmBridge<T extends WasmExports = WasmExports> {
     setU64Array(addr: number, buf: BigIntArray): this;
     setF32Array(addr: number, buf: NumericArray): this;
     setF64Array(addr: number, buf: NumericArray): this;
+    /**
+     * Reads UTF-8 encoded string from given address and optional byte length.
+     * The default length is 0, which will be interpreted as a zero-terminated
+     * string. Returns string.
+     *
+     * @param addr
+     * @param len
+     */
     getString(addr: number, len?: number): string;
+    /**
+     * Encodes given string as UTF-8 and writes it to WASM memory starting at
+     * `addr`. By default the string will be zero-terminated and only `maxBytes`
+     * will be written. Returns the number of bytes written.
+     *
+     * @remarks
+     * An error will be thrown if the encoded string doesn't fully fit into the
+     * designated memory region (also note that there might need to be space for
+     * the additional sentinel/termination byte).
+     *
+     * @param str
+     * @param addr
+     * @param maxBytes
+     * @param terminate
+     */
     setString(str: string, addr: number, maxBytes: number, terminate?: boolean): number;
     getElementById(addr: number, len?: number): HTMLElement;
 }

package/bridge.js

@@ -1,7 +1,9 @@
+import { defError } from "@thi.ng/errors/deferror";
 import { illegalArgs } from "@thi.ng/errors/illegal-arguments";
 import { U16, U32, U64HL, U8 } from "@thi.ng/hex";
 import { ConsoleLogger } from "@thi.ng/logger/console";
 const B32 = BigInt(32);
+export const OutOfMemoryError = defError(() => "Out of memory");
 /**
  * The main interop API bridge between the JS host environment and a WebAssembly
  * module. This class provides a small core API with various typed accessors and
@@ -26,7 +28,7 @@ export class WasmBridge {
         this.utf8Encoder = new TextEncoder();
         const logN = (x) => this.logger.debug(x);
         const logA = (method) => (addr, len) => this.logger.debug(method(addr, len).join(", "));
-        this.core = {
+        this.api = {
             printI8: logN,
             printU8: logN,
             printU8Hex: (x) => this.logger.debug(`0x${U8(x)}`),
@@ -85,7 +87,23 @@ export class WasmBridge {
      */
     async init(exports) {
         this.exports = exports;
-        const buf = exports.memory.buffer;
+        this.ensureMemory();
+        for (let id in this.modules) {
+            this.logger.debug(`initializing API module: ${id}`);
+            const status = await this.modules[id].init(this);
+            if (!status)
+                return false;
+        }
+        return true;
+    }
+    /**
+     * Called automatically. Initializes and/or updates the various typed WASM
+     * memory views (e.g. after growing the WASM memory).
+     */
+    ensureMemory() {
+        const buf = this.exports.memory.buffer;
+        if (this.u8 && this.u8.buffer === buf)
+            return;
         this.i8 = new Int8Array(buf);
         this.u8 = new Uint8Array(buf);
         this.i16 = new Int16Array(buf);
@@ -96,13 +114,6 @@ export class WasmBridge {
         this.u64 = new BigUint64Array(buf);
         this.f32 = new Float32Array(buf);
         this.f64 = new Float64Array(buf);
-        for (let id in this.modules) {
-            this.logger.debug(`initializing API module: ${id}`);
-            const status = await this.modules[id].init(this);
-            if (!status)
-                return false;
-        }
-        return true;
     }
     /**
      * Required use for WASM module instantiation to provide JS imports to the
@@ -111,8 +122,9 @@ export class WasmBridge {
      *
      * @remarks
      * 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.
+     * object, named using the same key which was assigned to the module when
+     * creating the WASM bridge. The bridge's core API will be named `core` and
+     * is reserved.
      *
      * @example
      * The following creates a bridge with a fictional `custom` API module:
@@ -124,7 +136,7 @@ export class WasmBridge {
      * bridge.getImports();
      * {
      *   // imports defined by the core API of the bridge itself
-     *   core: { ... },
+     *   wasmapi: { ... },
      *   // imports defined by the CustomAPI module
      *   custom: { ... }
      * }
@@ -139,7 +151,7 @@ export class WasmBridge {
      */
     getImports() {
         if (!this.imports) {
-            this.imports = { core: this.core };
+            this.imports = { wasmapi: this.api };
             for (let id in this.modules) {
                 if (this.imports[id] !== undefined) {
                     illegalArgs(`attempt to redeclare API module ${id}`);
@@ -149,6 +161,52 @@ export class WasmBridge {
         }
         return this.imports;
     }
+    /**
+     * Attempts to grow the WASM memory by an additional `numPages` (64KB/page)
+     * and if successful updates all typed memory views to use the new
+     * underlying buffer.
+     *
+     * @param numPages
+     */
+    growMemory(numPages) {
+        this.exports.memory.grow(numPages);
+        this.ensureMemory();
+    }
+    /**
+     * Attempts to allocate `numBytes` using the exported WASM core API function
+     * {@link WasmExports._wasm_allocate} (implementation specific) and returns
+     * start address of the new memory block. If unsuccessful, throws an
+     * {@link OutOfMemoryError}. If `clear` is true, the allocated region will
+     * be zero-filled.
+     *
+     * @remarks
+     * See {@link WasmExports._wasm_allocate} docs for further details.
+     *
+     * @param numBytes
+     * @param clear
+     */
+    allocate(numBytes, clear = false) {
+        const addr = this.exports._wasm_allocate(numBytes);
+        if (!addr)
+            throw new OutOfMemoryError(`unable to allocate: ${numBytes}`);
+        this.logger.debug(`allocated ${numBytes} bytes @ 0x${U32(addr)}`);
+        this.ensureMemory();
+        clear && this.u8.fill(0, addr, addr + numBytes);
+        return addr;
+    }
+    /**
+     * Frees a previous allocated memory region using the exported WASM core API
+     * function {@link WasmExports._wasm_free} (implementation specific). The
+     * `numBytes` value must be the same as previously given to
+     * {@link WasmBridge.allocate}.
+     *
+     * @param addr
+     * @param numBytes
+     */
+    free(addr, numBytes) {
+        this.logger.debug(`freeing memory @ 0x${U32(addr)} .. 0x${U32(addr + numBytes - 1)}`);
+        this.exports._wasm_free(addr, numBytes);
+    }
     getI8(addr) {
         return this.i8[addr];
     }
@@ -297,13 +355,37 @@ export class WasmBridge {
         this.f64.set(buf, addr >> 3);
         return this;
     }
+    /**
+     * Reads UTF-8 encoded string from given address and optional byte length.
+     * The default length is 0, which will be interpreted as a zero-terminated
+     * string. Returns string.
+     *
+     * @param addr
+     * @param len
+     */
     getString(addr, len = 0) {
+        this.ensureMemory();
         return this.utf8Decoder.decode(this.u8.subarray(addr, len > 0 ? addr + len : this.u8.indexOf(0, addr)));
     }
+    /**
+     * Encodes given string as UTF-8 and writes it to WASM memory starting at
+     * `addr`. By default the string will be zero-terminated and only `maxBytes`
+     * will be written. Returns the number of bytes written.
+     *
+     * @remarks
+     * An error will be thrown if the encoded string doesn't fully fit into the
+     * designated memory region (also note that there might need to be space for
+     * the additional sentinel/termination byte).
+     *
+     * @param str
+     * @param addr
+     * @param maxBytes
+     * @param terminate
+     */
     setString(str, addr, maxBytes, terminate = true) {
         maxBytes = Math.min(maxBytes, this.u8.length - addr);
         const len = this.utf8Encoder.encodeInto(str, this.u8.subarray(addr, addr + maxBytes)).written;
-        if (len != null && len < maxBytes + (terminate ? 0 : 1)) {
+        if (len == null || len >= maxBytes + (terminate ? 0 : 1)) {
             illegalArgs(`error writing string to 0x${U32(addr)}`);
         }
         if (terminate) {

package/cli.d.ts

@@ -0,0 +1,5 @@
+export declare const INSTALL_DIR: string;
+export declare const PKG: any;
+export declare const APP_NAME: any;
+export declare const HEADER: string;
+//# sourceMappingURL=cli.d.ts.map