@thi.ng/wasm-api 0.6.0 → 0.9.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2022-08-15T15:40:55Z
+- **Last updated**: 2022-08-23T10:37:04Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,42 @@ 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.9.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/wasm-api@0.9.0) (2022-08-23)
+
+#### 🚀 Features
+
+- add debug() core API function ([ca01978](https://github.com/thi-ng/umbrella/commit/ca01978))
+
+#### 🩹 Bug fixes
+
+- update setString() return value ([116dd0b](https://github.com/thi-ng/umbrella/commit/116dd0b))
+  - always only return num bytes written w/o sentinel
+
+## [0.8.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/wasm-api@0.8.0) (2022-08-16)
+
+#### 🚀 Features
+
+- add preliminary string handling support ([3da4efe](https://github.com/thi-ng/umbrella/commit/3da4efe))
+  - update/rename IWasmMemoryAccess (add string getter/setter)
+  - update StructField.type (add `string`)
+  - add CodeGenOpts.stringType option
+  - update codegen fns
+  - update TS & Zig codegen impls
+
+## [0.7.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/wasm-api@0.7.0) (2022-08-15)
+
+#### 🚀 Features
+
+- add CLI wrapper for codegens ([683a560](https://github.com/thi-ng/umbrella/commit/683a560))
+- update TSOpts & TS codegen ([4f6bbbf](https://github.com/thi-ng/umbrella/commit/4f6bbbf))
+  - add `uppercaseEnum` option to force UC enum IDs
+- update helper predicates ([65b23d4](https://github.com/thi-ng/umbrella/commit/65b23d4))
+
+#### 🩹 Bug fixes
+
+- allow signed ints for enum tags ([78d0822](https://github.com/thi-ng/umbrella/commit/78d0822))
+- correct TS __mapArray codegen ([289b137](https://github.com/thi-ng/umbrella/commit/289b137))
+
 ## [0.6.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/wasm-api@0.6.0) (2022-08-15)
 
 #### 🚀 Features

package/README.md

@@ -11,11 +11,13 @@ This project is part of the
 
 - [About](#about)
   - [Custom API modules](#custom-api-modules)
-  - [Object indices & handles](#object-indices--handles)
   - [Data bindings & code generators](#data-bindings--code-generators)
+    - [CLI generator](#cli-generator)
     - [Data type definitions](#data-type-definitions)
-    - [Code generation](#code-generation)
     - [Example usage](#example-usage)
+  - [String handling](#string-handling)
+  - [Memory allocations](#memory-allocations)
+  - [Object indices & handles](#object-indices--handles)
   - [Status](#status)
 - [Installation](#installation)
 - [Dependencies](#dependencies)
@@ -36,23 +38,31 @@ This package provides a the following:
 [`WasmBridge`](https://docs.thi.ng/umbrella/wasm-api/classes/WasmBridge.html)
 class as interop basis and much reduced boilerplate for hybrid JS/WebAssembly
 applications.
-2. A minimal core API for debug output, string, pointer, typed array accessors
-(8/16/32/64 bit (u)ints, 32/64 bit floats). In the future we aim to also supply
-support modules for DOM manipulation, WebGL, WebGPU, WebAudio etc.
-3. Extensible shared datatype code generators for (currently)
-   [Zig](https://ziglang.org) & TypeScript. The latter also generates fully type
-   checked memory-mapped accessors of WASM-side data. In general, all languages
-with a WebAssembly target are supported, however currently only bindings for
-these few langs are included.
-4. Include files for C11 and Zig, defining imports for the JS core API defined
+2. A minimal core API for memory allocation (can be disabled), debug output,
+string/pointer/typedarray accessors for 8/16/32/64 bit (u)ints and 32/64 bit
+floats. In the future we aim to also supply support modules for DOM
+manipulation, WebGL, WebGPU, WebAudio etc.
+3. [Include files for C11/C++ and
+   Zig](https://github.com/thi-ng/umbrella/tree/develop/packages/wasm-api/include),
+   defining WASM imports of the JS [core
+   API](https://docs.thi.ng/umbrella/wasm-api/interfaces/CoreAPI.html) defined
    by this package
+4. Extensible shared datatype code generators for (currently)
+   [Zig](https://ziglang.org) & TypeScript. The latter also generates fully type
+   checked memory-mapped (zero-copy) accessors of WASM-side data. In general,
+all languages with a WebAssembly target are supported, however currently only
+bindings for these few langs are included.
+5. [CLI frontend/utility](#cli-generator) to invoke the code generator(s)
 
 ### Custom API modules
 
-The WasmBridge is extensible via custom defined API modules. Such API extensions
-will consist of a collection of JS/TS functions & variables, their related
-counterparts (import definitions) for the WASM target and (optionally) some
-shared data types (bindings for which _can_ be generated by this package too).
+The
+[`WasmBridge`](https://docs.thi.ng/umbrella/wasm-api/classes/WasmBridge.html) is
+extensible via custom defined API modules. Such API extensions will consist of a
+collection of JS/TS functions & variables, their related counterparts (import
+definitions) for the WASM target and (optionally) some shared data types
+([bindings for which _can_ be generated by this package
+too](#data-bindings--code-generators)).
 
 On the JS side, custom API modules can be easily integrated via the [`IWasmAPI`
 interface](https://docs.thi.ng/umbrella/wasm-api/interfaces/IWasmAPI.html). The
@@ -127,6 +137,314 @@ export fn test_randomVec2() void {
 }
 ```
 
+### Data bindings & code generators
+
+The package provides an extensible codegeneration framework to simplify the
+bilateral design & exchange of data structures shared between the WASM & JS host
+env. Currently, code generators for TypeScript & Zig are supplied (more are
+planned). A CLI wrapper is worked on too.
+
+#### CLI generator
+
+The package includes a [small CLI
+wrapper](https://github.com/thi-ng/umbrella/blob/develop/packages/wasm-api/src/cli.ts)
+to invoke the codegenerator(s) from JSON type definitions and to write the
+generated source code(s) to different files:
+
+```text
+$ npx @thi.ng/wasm-api
+
+ █ █   █           │
+██ █               │
+ █ █ █ █   █ █ █ █ │ @thi.ng/wasm-api 0.6.0
+ █ █ █ █ █ █ █ █ █ │ Multi-language data bindings code generator
+                 █ │
+               █ █ │
+
+usage: wasm-api [OPTS] JSON-INPUT-FILE(S) ...
+       wasm-api --help
+
+Flags:
+
+-d, --debug                     enable debug output
+--dry-run                       enable dry run (don't overwrite files)
+
+Main:
+
+-c FILE, --config FILE          JSON config file with codegen options
+-l ID[,..], --lang ID[,..]      [multiple] target language: "ts", "zig" (default: ["ts","zig"])
+-o FILE, --out FILE             [multiple] output file path
+```
+
+By default, the CLI generates sources for both TypeScript and Zig (in this
+order!). Order is important, since the output file paths must be given in the
+same order as the target languages. It's recommended to be more explicit. An
+example invocation looks like:
+
+```bash
+wasm-api --config codegen-opts.json \
+  --lang ts -o src/generated.ts \
+  --lang zig -o src.zig/generated.zig \
+  typedefs.json
+```
+
+The structure of the config file is as follows (all optional):
+
+```text
+{
+	global: { ... },
+	ts: { ... },
+	zig: { ... },
+}
+```
+
+More details about possible
+[`global`](https://docs.thi.ng/umbrella/wasm-api/interfaces/CodeGenOpts.html),
+[`ts`](https://docs.thi.ng/umbrella/wasm-api/interfaces/TSOpts.html) and
+[`zig`](https://docs.thi.ng/umbrella/wasm-api/interfaces/ZigOpts.html) config
+options & values.
+
+#### Data type definitions
+
+Currently, the code generator supports structs and enums. See API docs for
+further details:
+
+- [`Enum`](https://docs.thi.ng/umbrella/wasm-api/interfaces/Enum.html)
+- [`EnumValue`](https://docs.thi.ng/umbrella/wasm-api/interfaces/EnumValue.html)
+- [`Struct`](https://docs.thi.ng/umbrella/wasm-api/interfaces/Struct.html)
+- [`StructField`](https://docs.thi.ng/umbrella/wasm-api/interfaces/StructField.html)
+- [`TopLevelType`](https://docs.thi.ng/umbrella/wasm-api/interfaces/TopLevelType.html)
+
+#### Example usage
+
+Below is an example file with JSON type definitions and the resulting source
+codes:
+
+**⬇︎ CLICK TO EXPAND EACH CODE BLOCK ⬇︎**
+
+<details><summary>types.json (Type definitions)</summary>
+
+```json
+[
+	{
+		"name": "Foo",
+		"type": "struct",
+		"doc": "Example struct",
+		"auto": true,
+		"fields": [
+			{ "name": "id", "type": "u8", "doc": "Unique ID" },
+			{ "name": "bars", "type": "Bar", "tag": "array", "len": 3 },
+			{ "name": "color", "type": "f32", "tag": "vec", "len": 4 }
+		]
+	},
+	{
+		"name": "Bar",
+		"type": "struct",
+		"fields": [
+			{ "name": "kind", "type": "Kind" },
+			{ "name": "flags", "type": "u32" }
+		]
+	},
+	{
+		"name": "Kind",
+		"type": "enum",
+		"tag": "u16",
+		"values": [
+			"unknown",
+			{ "name": "good", "value": 100 },
+			{ "name": "best", "value": 1000 }
+		]
+	}
+]
+```
+</details>
+
+<details><summary>generated.ts (generated TypeScript source)</summary>
+
+```ts
+/** Generated by @thi.ng/wasm-api at 2022-08-15T22:32:21.189Z - DO NOT EDIT! */
+
+import type { WasmTypeBase, WasmTypeConstructor } from "@thi.ng/wasm-api";
+
+/** Example struct */
+export interface Foo extends WasmTypeBase {
+	color: Float32Array;
+	bars: Bar[];
+	/** Unique ID */
+	id: number;
+}
+
+export const $Foo: WasmTypeConstructor<Foo> = (mem) => ({
+	get align() { return 16; },
+	get size() { return 48; },
+	instance: (base) => ({
+		get __base() { return base; },
+		get __bytes() { return mem.u8.subarray(base, base + 48); },
+		get color(): Float32Array {
+			const addr = base >>> 2;
+			return mem.f32.subarray(addr, addr + 4);
+		},
+		get bars(): Bar[] {
+			const addr = (base + 16);
+			const inst = $Bar(mem);
+			const slice: Bar[] = [];
+			for(let i = 0; i < 3; i++) slice.push(inst.instance(addr + i * 24));
+			return slice;
+		},
+		get id(): number {
+			return mem.u8[(base + 40)];
+		},
+		set id(x: number) {
+			mem.u8[(base + 40)] = x;
+		},
+	})
+});
+
+export interface Bar extends WasmTypeBase {
+	kind: Kind;
+	flags: number;
+}
+
+export const $Bar: WasmTypeConstructor<Bar> = (mem) => ({
+	get align() { return 4; },
+	get size() { return 8; },
+	instance: (base) => ({
+		get __base() { return base; },
+		get __bytes() { return mem.u8.subarray(base, base + 8); },
+		get kind(): Kind {
+			return mem.u16[base >>> 1];
+		},
+		set kind(x: Kind) {
+			mem.u16[base >>> 1] = x;
+		},
+		get flags(): number {
+			return mem.u32[(base + 4) >>> 2];
+		},
+		set flags(x: number) {
+			mem.u32[(base + 4) >>> 2] = x;
+		},
+	})
+});
+
+export enum Kind {
+	UNKNOWN,
+	GOOD = 100,
+	BEST = 1000,
+}
+```
+</details>
+
+<details><summary>generated.zig (generated Zig source)</summary>
+
+```zig
+//! Generated by @thi.ng/wasm-api at 2022-08-15T22:32:21.191Z - DO NOT EDIT!
+
+/// Example struct
+pub const Foo = struct {
+    color: @Vector(4, f32),
+    bars: [3]Bar,
+    /// Unique ID
+    id: u8,
+};
+
+pub const Bar = struct {
+    kind: Kind,
+    flags: u32,
+};
+
+pub const Kind = enum(u16) {
+    unknown,
+    good = 100,
+    best = 1000,
+};
+```
+</details>
+
+On the TypeScript/JS side, the memory-mapped wrappers (e.g. `$Foo` and `$Bar`)
+can be used in combination with the `WasmBridge` to obtain fully typed views
+(according to the generated types) of the underlying WASM memory. Basic usage is
+like:
+
+```ts
+import { WasmBridge } from "@thi.ng/wasm-api";
+import { $Foo, Kind } from "./generated.ts";
+
+const bridge = new WasmBridge();
+// bridge initialization omitted here (see other examples below)
+// ...
+
+// Create an instance using the bridge's memory views
+// and mapping a `Foo` struct from given address
+// (e.g. obtained from an exported WASM function/value)
+const foo = $Foo(bridge).instance(0x10000);
+
+// then use like normal JS object
+foo.color
+// Float32Array(4) [0.1, 0.2, 0.3, 0.4]
+
+// this even applies to arrays using other types
+foo.bars[2].kind = Kind.BEST;
+
+// IMPORTANT: any modifications like this are directly
+// applied to the underlying WASM memory...
+```
+
+**IMPORTANT:** Struct field setters are currently only supported for single
+values, incl. enums, strings, structs. The latter 2 will always be copied by
+value (mem copy). Arrays or slices of strings do not currently provide write
+access...
+
+### String handling
+
+Most low-level languages deal with strings very differently and alas there's no
+general standard. Some have UTF-8/16 support, others don't. In some languages
+(incl. C & Zig), strings are stored as zero terminated, in others they aren't...
+It's outside the scope of this package to provide an allround out-of-the-box
+solution. The `WasmBridge` provides read & write accessors to obtain JS strings
+from UTF-8 encoded WASM memory. See
+[`getString()`](https://docs.thi.ng/umbrella/wasm-api/classes/WasmBridge.html#getString)
+and
+[`setString()`](https://docs.thi.ng/umbrella/wasm-api/classes/WasmBridge.html#setString)
+for details.
+
+The code generators too provide a global `stringType` option to
+interpret the `string` type of a struct field in different ways:
+
+- `slice` (default): Considers strings as Zig-style slices (i.e. pointer + length)
+- `ptr`: Considers strings as C-style raw `*char` pointer (without any length)
+
+Note: If setting this global option to `ptr`, it also has to be repeated for the
+TypeScript code generator explicitly.
+
+### Memory allocations
+
+The `WasmBridge` includes support for malloc/free-style allocations (within the
+linear WASM memory), _unless_ these are explicitly disabled on the WASM side. Please see for further reference:
+
+- [`/include/wasmapi.zig`](https://github.com/thi-ng/umbrella/blob/develop/packages/wasm-api/include/wasmapi.zig#L6) - comments about WASM-side allocator handling
+- [`WasmBridge.allocate()`](https://docs.thi.ng/umbrella/wasm-api/classes/WasmBridge.html#allocate) - allocating memory from JS side
+- [`WasmBridge.free()`](https://docs.thi.ng/umbrella/wasm-api/classes/WasmBridge.html#free) - freeing previously allocated memory
+
+```ts
+try {
+	// allocate 1KB of memory for passing a string to WASM side
+	const addr = bridge.allocate(256);
+
+	// write string to reserved memory
+	// max. 256 bytes written, zero terminated
+	const num = bridge.setString("hello WASM world!", addr, 256, true);
+
+	// call WASM function doing something w/ the string
+	bridge.exports.doSomethingWithString(addr, num);
+
+	// cleanup
+	bridge.free(addr, 256);
+} catch(e) {
+	// allocation error
+	// ...
+}
+```
+
 ### Object indices & handles
 
 Since only numeric values can be exchanged between the WASM module and the JS
@@ -174,29 +492,6 @@ canvases.delete(0);
 // true
 ```
 
-### Data bindings & code generators
-
-The package provides an extensible codegeneration framework to simplify the
-bilateral design & exchange of data structures shared between the WASM & JS host
-env. Currently, code generators for TypeScript & Zig are supplied (more are
-planned). A CLI wrapper is worked on too.
-
-#### Data type definitions
-
-TODO
-
-##### Struct
-
-##### Enum
-
-#### Code generation
-
-TODO
-
-#### Example usage
-
-TODO
-
 ### Status
 
 **ALPHA** - bleeding edge / work-in-progress
@@ -226,7 +521,7 @@ node --experimental-repl-await
 > const wasmApi = await import("@thi.ng/wasm-api");
 ```
 
-Package sizes (gzipped, pre-treeshake): ESM: 3.98 KB
+Package sizes (gzipped, pre-treeshake): ESM: 4.34 KB
 
 **IMPORTANT:** The package includes various code generators and supporting
 functions which are NOT required during runtime. Hence the actual package size
@@ -235,11 +530,13 @@ in production will be MUCH smaller!
 ## Dependencies
 
 - [@thi.ng/api](https://github.com/thi-ng/umbrella/tree/develop/packages/api)
+- [@thi.ng/args](https://github.com/thi-ng/umbrella/tree/develop/packages/args)
 - [@thi.ng/binary](https://github.com/thi-ng/umbrella/tree/develop/packages/binary)
 - [@thi.ng/checks](https://github.com/thi-ng/umbrella/tree/develop/packages/checks)
 - [@thi.ng/compare](https://github.com/thi-ng/umbrella/tree/develop/packages/compare)
 - [@thi.ng/defmulti](https://github.com/thi-ng/umbrella/tree/develop/packages/defmulti)
 - [@thi.ng/errors](https://github.com/thi-ng/umbrella/tree/develop/packages/errors)
+- [@thi.ng/file-io](https://github.com/thi-ng/umbrella/tree/develop/packages/file-io)
 - [@thi.ng/hex](https://github.com/thi-ng/umbrella/tree/develop/packages/hex)
 - [@thi.ng/idgen](https://github.com/thi-ng/umbrella/tree/develop/packages/idgen)
 - [@thi.ng/logger](https://github.com/thi-ng/umbrella/tree/develop/packages/logger)

package/api.d.ts

@@ -1,4 +1,4 @@
-import type { FloatType, 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;
@@ -66,7 +66,7 @@ export interface WasmExports {
      */
     _wasm_free(addr: number, numBytes: number): void;
 }
-export interface WasmMemViews {
+export interface IWasmMemoryAccess {
     i8: Int8Array;
     u8: Uint8Array;
     i16: Int16Array;
@@ -77,6 +77,31 @@ export interface WasmMemViews {
     u64: BigUint64Array;
     f32: Float32Array;
     f64: Float64Array;
+    /**
+     * 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;
 }
 /**
  * Core API of WASM imports defined by the {@link WasmBridge}. The same
@@ -110,6 +135,7 @@ export interface CoreAPI extends WebAssembly.ModuleImports {
     _printF64Array: (addr: number, len: number) => void;
     _printStr0: (addr: number) => void;
     _printStr: (addr: number, len: number) => void;
+    debug: () => void;
 }
 export interface WasmTypeBase {
     /**
@@ -126,11 +152,12 @@ export interface WasmType<T> {
     readonly size: number;
     instance: Fn<number, T>;
 }
-export declare type WasmTypeConstructor<T> = Fn<WasmMemViews, WasmType<T>>;
+export declare type WasmTypeConstructor<T> = Fn<IWasmMemoryAccess, 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 {
     /**
@@ -153,16 +180,30 @@ export interface TypeInfo {
     __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.
+     * their {@link TypeInfo.__align} size. This might result in overall smaller
+     * structs due to minimizing inter-field padding.
      *
      * @defaultValue false
      */
@@ -178,43 +219,70 @@ export interface StructField extends TypeInfo {
      */
     doc?: string;
     /**
-     * Field type tag/qualifier (note: `slice` & `vec` are only supported by
-     * Zig & TS)
+     * 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}.
+     * Field base type. If not a {@link WasmPrim}, `string` or `opaque`, the
+     * value is interpreted as another type name in the {@link TypeColl}.
+     *
+     * @remarks
+     * Please see {@link CodeGenOpts.stringType} and consult package readme for
+     * further details re: string handling.
      *
      * TODO `opaque` currently unsupported.
      */
-    type: WasmPrim | "opaque" | string;
+    type: WasmPrim | "string" | "opaque" | string;
     /**
-     * TODO currently unsupported!
+     * TODO currently unsupported & ignored!
      */
     sentinel?: number;
     /**
-     * Array or vector length
+     * Array or vector length (see {@link StructField.tag})
      */
     len?: number;
     /**
-     * TODO currently unsupported!
+     * TODO currently unsupported & ignored!
      */
     default?: any;
 }
 export interface Enum extends TopLevelType {
     type: "enum";
     /**
-     * No u64 support, due to Typescript not supporting bigint enum values
+     * 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.
      */
-    tag: Exclude<WasmUint, "u64">;
     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 {
@@ -226,8 +294,17 @@ export interface ICodeGen {
      * 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;
 }
 /**

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" "$@"