@thi.ng/wasm-api 0.10.0 → 0.12.0

package/README.md

@@ -1,6 +1,6 @@
 <!-- This file is generated - DO NOT EDIT! -->
 
-# ![wasm-api](https://media.thi.ng/umbrella/banners/thing-wasm-api.svg?00b02dbd)
+# ![wasm-api](https://media.thi.ng/umbrella/banners-20220914/thing-wasm-api.svg?be328da7)
 
 [![npm version](https://img.shields.io/npm/v/@thi.ng/wasm-api.svg)](https://www.npmjs.com/package/@thi.ng/wasm-api)
 ![npm downloads](https://img.shields.io/npm/dm/@thi.ng/wasm-api.svg)
@@ -10,17 +10,19 @@ This project is part of the
 [@thi.ng/umbrella](https://github.com/thi-ng/umbrella/) monorepo.
 
 - [About](#about)
-  - [Custom API modules](#custom-api-modules)
   - [Data bindings & code generators](#data-bindings--code-generators)
     - [CLI generator](#cli-generator)
     - [Data type definitions](#data-type-definitions)
     - [Example usage](#example-usage)
   - [String handling](#string-handling)
   - [Memory allocations](#memory-allocations)
+  - [Custom API modules](#custom-api-modules)
   - [Object indices & handles](#object-indices--handles)
-  - [Status](#status)
+- [Status](#status)
+- [Support packages](#support-packages)
 - [Installation](#installation)
 - [Dependencies](#dependencies)
+- [Usage examples](#usage-examples)
 - [API](#api)
 - [Basic usage example](#basic-usage-example)
   - [Zig version](#zig-version)
@@ -30,7 +32,7 @@ This project is part of the
 
 ## About
 
-Generic, modular, extensible API bridge, glue code and bindings code generator for hybrid JS & WebAssembly projects.
+Generic, modular, extensible API bridge, polyglot glue code and bindings code generators for hybrid JS & WebAssembly projects.
 
 This package provides a the following:
 
@@ -38,117 +40,37 @@ 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 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.
+2. A minimal core API for debug output, string/pointer/typedarray accessors for
+8/16/32/64 bit (u)ints and 32/64 bit floats, memory allocation (optional).
+Additionally, a number of support modules for [DOM
+manipulation](https://github.com/thi-ng/umbrella/tree/develop/packages/wasm-api-dom/),
+WebGL, WebGPU, WebAudio etc. is being actively worked on.
 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
+   defining WASM imports of the extern 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.
+4. Extensible shared datatype code generators for (currently) C11, TypeScript &
+   [Zig](https://ziglang.org). 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 mentioned langs are included.
 5. [CLI frontend/utility](#cli-generator) to invoke the code generator(s)
 
-### Custom API modules
-
-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
-following example provides a brief overview:
-
-```ts
-import { IWasmAPI, WasmBridge } from "@thi.ng/wasm-api";
-
-export class CustomAPI implements IWasmAPI {
-	parent!: WasmBridge;
-
-	async init(parent: WasmBridge) {
-		this.parent = parent;
-		this.parent.logger.debug("initializing custom API");
-
-		// any other tasks you might need to do...
-
-		return true;
-	}
-
-	/**
-	 * Returns object of functions to import as externals into
-	 * the WASM module. These imports are merged into a larger
-	 * imports object alongside the bridge's core API...
-	 */
-	getImports(): WebAssembly.Imports {
-		return {
-			/**
-			 * Writes 2 random float32 numbers to given address
-			 */
-			randomVec2: (addr: number) => {
-				this.parent.f32.set(
-					[Math.random(), Math.random()],
-					addr >> 2
-				);
-			}
-		};
-	}
-}
-```
-
-Now we can supply this custom API when creating the main WASM bridge:
-
-```ts
-export const bridge = new WasmBridge({ custom: new CustomAPI() });
-```
-
-In Zig (or any other language of your choice) we can then utilize this custom
-API like so (Please also see /test/index.ts` & the example further below in this
-readme):
-
-```zig
-// Import JS core API
-const js = @import("wasmapi");
-
-/// JS external to fill vec2 w/ random values
-/// Note: Each API module uses a separate import object to avoid naming clashes
-/// Here we declare an external binding belonging to the "custom" import group
-extern "custom" fn randomVec2(addr: usize) void;
-
-export fn test_randomVec2() void {
-	var foo = [2]f32{ 0, 0 };
-
-	// print original
-	js.printF32Array(foo[0..]);
-
-	// populate foo with random numbers
-	randomVec2(@ptrToInt(&foo));
-
-	// print result
-	js.printF32Array(foo[0..]);
-}
-```
-
 ### 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.
+planned). A CLI wrapper is available too. See the
+[@thi.ng/wasm-api-dom](https://github.com/thi-ng/umbrella/tree/develop/packages/wasm-api-dom/)
+support package for a more thorough realworld example...
 
 #### 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
+to invoke the code generator(s) from JSON type definitions and to write the
 generated source code(s) to different files:
 
 ```text
@@ -156,7 +78,7 @@ $ npx @thi.ng/wasm-api
 
  █ █   █           │
 ██ █               │
- █ █ █ █   █ █ █ █ │ @thi.ng/wasm-api 0.6.0
+ █ █ █ █   █ █ █ █ │ @thi.ng/wasm-api 0.12.0
  █ █ █ █ █ █ █ █ █ │ Multi-language data bindings code generator
                  █ │
                █ █ │
@@ -171,18 +93,21 @@ Flags:
 
 Main:
 
+-a FILE, --analytics FILE       output file path for raw codegen analytics
 -c FILE, --config FILE          JSON config file with codegen options
--l ID[,..], --lang ID[,..]      [multiple] target language: "ts", "zig" (default: ["ts","zig"])
+-l ID[,..], --lang ID[,..]      [multiple] target language: "c11", "ts", "zig" (default: ["ts","zig"])
 -o FILE, --out FILE             [multiple] output file path
+-s TYPE, --string TYPE          Force string type implementation: "slice", "ptr"
 ```
 
-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
+By default, the CLI generates sources for 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 with this. An
 example invocation looks like:
 
 ```bash
-wasm-api --config codegen-opts.json \
+wasm-api \
+  --config codegen-opts.json \
   --lang ts -o src/generated.ts \
   --lang zig -o src.zig/generated.zig \
   typedefs.json
@@ -190,20 +115,34 @@ wasm-api --config codegen-opts.json \
 
 The structure of the config file is as follows (all optional):
 
-```text
+```json
 {
-	global: { ... },
-	ts: { ... },
-	zig: { ... },
+	"global": { ... },
+	"c11": { ... },
+	"ts": { ... },
+	"zig": { ... },
 }
 ```
 
 More details about possible
 [`global`](https://docs.thi.ng/umbrella/wasm-api/interfaces/CodeGenOpts.html),
+[`c`](https://docs.thi.ng/umbrella/wasm-api/interfaces/C11Opts.html) and
 [`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.
 
+All code generators have support for custom code prologues & epilogues which can
+be specified via the above options. These config options exist for both non-CLI
+& CLI usage. For the latter, these custom code sections can also be loaded from
+external files by specifying their file paths using `@` as prefix, e.g.
+
+```json
+{
+	"ts": { "pre": "@tpl/prelude.ts" },
+	"zig": { "pre": "@tpl/prelude.zig", "post": "@tpl/epilogue.zig" },
+}
+```
+
 #### Data type definitions
 
 Currently, the code generator supports structs and enums. See API docs for
@@ -262,42 +201,59 @@ codes:
 <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! */
+/**
+ * Generated by @thi.ng/wasm-api at 2022-10-03T15:32:12.339Z - DO NOT EDIT!
+ */
 
-import type { WasmTypeBase, WasmTypeConstructor } from "@thi.ng/wasm-api";
+// @ts-ignore possibly includes unused imports
+import { Pointer, WasmStringSlice, WasmTypeBase, WasmTypeConstructor } from "@thi.ng/wasm-api";
 
-/** Example struct */
+/**
+ * Example struct
+ */
 export interface Foo extends WasmTypeBase {
 	color: Float32Array;
 	bars: Bar[];
-	/** Unique ID */
+	/**
+	 * 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;
-		},
-	})
+	get align() {
+		return 16;
+	},
+	get size() {
+		return 48;
+	},
+	instance: (base) => {
+		return {
+			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 {
@@ -306,24 +262,34 @@ export interface Bar extends WasmTypeBase {
 }
 
 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;
-		},
-	})
+	get align() {
+		return 4;
+	},
+	get size() {
+		return 8;
+	},
+	instance: (base) => {
+		return {
+			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 {
@@ -337,7 +303,9 @@ export enum Kind {
 <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!
+//! Generated by @thi.ng/wasm-api at 2022-10-03T15:32:12.341Z - DO NOT EDIT!
+
+const std = @import("std");
 
 /// Example struct
 pub const Foo = struct {
@@ -353,9 +321,9 @@ pub const Bar = struct {
 };
 
 pub const Kind = enum(u16) {
-    unknown,
-    good = 100,
-    best = 1000,
+    UNKNOWN,
+    GOOD = 100,
+    BEST = 1000,
 };
 ```
 </details>
@@ -439,7 +407,9 @@ reference:
 Note: The provided Zig mechanism supports the idiomatic (Zig) pattern of working
 with multiple allocators in different parts of the application and supports
 dynamic assignments/swapping of the exposed allocator. See comments in source
-file for more details...
+file and
+[tests](https://github.com/thi-ng/umbrella/tree/develop/packages/wasm-api/test)
+for more details...
 
 ```ts
 try {
@@ -461,6 +431,95 @@ try {
 }
 ```
 
+### Custom API modules
+
+The
+[`WasmBridge`](https://docs.thi.ng/umbrella/wasm-api/classes/WasmBridge.html)
+can be extented 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
+following example provides a brief overview:
+
+```ts
+import { IWasmAPI, WasmBridge } from "@thi.ng/wasm-api";
+
+export class CustomAPI implements IWasmAPI {
+	parent!: WasmBridge;
+
+	async init(parent: WasmBridge) {
+		this.parent = parent;
+		this.parent.logger.debug("initializing custom API");
+
+		// any other tasks you might need to do...
+
+		return true;
+	}
+
+	/**
+	 * Returns object of functions to import as externals into the
+	 * WASM module during instantiation. These imports are merged
+	 * into a larger imports object alongside the bridge's core API...
+	 */
+	getImports(): WebAssembly.Imports {
+		return {
+			/**
+			 * Writes `num` random float32 numbers from given address
+			 */
+			fillRandom: (addr: number, num: number) => {
+				addr >>>= 2;
+				while(num-- > 0) this.parent.f32[addr++] = Math.random();
+			}
+		};
+	}
+}
+```
+
+Now we can supply this custom API when creating the main WASM bridge:
+
+```ts
+export const bridge = new WasmBridge({ custom: new CustomAPI() });
+```
+
+In Zig (or any other language of your choice) we can then utilize this custom
+API like so (Please also see
+[tests](https://github.com/thi-ng/umbrella/tree/develop/packages/wasm-api/test)
+& other examples in this readme):
+
+```zig
+//! custom.zig - extern definitions of custom JS API
+
+/// JS external to fill a slice w/ random values
+/// Note: Each API module uses a separate import object to avoid naming clashes
+/// Here we declare an external binding belonging to the "custom" import group
+///
+/// The bridge core API uses "wasmapi" as reserved import group name
+extern "custom" fn fillRandom(addr: usize, num: usize) void;
+```
+
+```zig
+// Import JS core API
+const js = @import("wasmapi");
+const custom = @import("custom.zig");
+
+export fn test_randomVec4() void {
+	var foo = [4]f32{ 1, 2, 3, 4 };
+
+	// print original
+	js.printF32Array(foo[0..]);
+
+	// populate foo with random numbers
+	custom.fillRandom(@ptrToInt(&foo), foo.len);
+
+	// print result
+	js.printF32Array(foo[0..]);
+}
+```
+
 ### Object indices & handles
 
 Since only numeric values can be exchanged between the WASM module and the JS
@@ -508,12 +567,16 @@ canvases.delete(0);
 // true
 ```
 
-### Status
+## Status
 
 **ALPHA** - bleeding edge / work-in-progress
 
 [Search or submit any issues for this package](https://github.com/thi-ng/umbrella/issues?q=%5Bwasm-api%5D+in%3Atitle)
 
+## Support packages
+
+- [@thi.ng/wasm-api-dom](https://github.com/thi-ng/umbrella/tree/develop/packages/wasm-api-dom) - Browser DOM bridge API for hybrid TypeScript & Zig applications
+
 ## Installation
 
 ```bash
@@ -537,11 +600,11 @@ node --experimental-repl-await
 > const wasmApi = await import("@thi.ng/wasm-api");
 ```
 
-Package sizes (gzipped, pre-treeshake): ESM: 4.48 KB
+Package sizes (gzipped, pre-treeshake): ESM: 6.29 KB
 
-**IMPORTANT:** The package includes various code generators and supporting
-functions which are NOT required during runtime. Hence the actual package size
-in production will be MUCH smaller!
+**IMPORTANT:** The package includes code generators for various languages which
+are **not** required for just using the API bridge. Hence, the usual package
+size in production will be MUCH smaller than what's stated here!
 
 ## Dependencies
 
@@ -556,6 +619,20 @@ in production will be MUCH smaller!
 - [@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)
+- [@thi.ng/paths](https://github.com/thi-ng/umbrella/tree/develop/packages/paths)
+- [@thi.ng/strings](https://github.com/thi-ng/umbrella/tree/develop/packages/strings)
+
+## Usage examples
+
+Several demos in this repo's
+[/examples](https://github.com/thi-ng/umbrella/tree/develop/examples)
+directory are using this package.
+
+A selection:
+
+| Screenshot                                                                                                        | Description                                 | Live demo                                        | Source                                                                        |
+|:------------------------------------------------------------------------------------------------------------------|:--------------------------------------------|:-------------------------------------------------|:------------------------------------------------------------------------------|
+| <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/zig-canvas.png" width="240"/> | Zig-based DOM creation & canvas drawing app | [Demo](https://demo.thi.ng/umbrella/zig-canvas/) | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/zig-canvas) |
 
 ## API
 
@@ -631,16 +708,16 @@ The resulting WASM:
  (type $none_=>_none (func))
  (type $i32_=>_i32 (func (param i32) (result i32)))
  (import "wasmapi" "_printStr" (func $fimport$0 (param i32 i32)))
- (global $global$0 (mut i32) (i32.const 65536))
- (memory $0 2)
- (data (i32.const 65536) "hello world!\00")
+ (global $global$0 (mut i32) (i32.const 1048576))
+ (memory $0 17)
+ (data (i32.const 1048576) "hello world!\00")
  (export "memory" (memory $0))
  (export "start" (func $0))
  (export "_wasm_allocate" (func $1))
  (export "_wasm_free" (func $2))
  (func $0
   (call $fimport$0
-   (i32.const 65536)
+   (i32.const 1048576)
    (i32.const 12)
   )
  )
@@ -667,7 +744,7 @@ void WASM_KEEP start() {
 Building the WASM module:
 
 ```bash
-emcc -Os -Inode_modules/@thi.ng/wasm-api/include -DWASMAPI_NO_MALLOC \
+emcc -Os -Inode_modules/@thi.ng/wasm-api/include \
   -sERROR_ON_UNDEFINED_SYMBOLS=0 --no-entry \
   -o hello.wasm hello.c
 ```
@@ -680,6 +757,7 @@ Resulting WASM:
  (type $none_=>_none (func))
  (type $i32_=>_i32 (func (param i32) (result i32)))
  (type $none_=>_i32 (func (result i32)))
+ (type $i32_i32_=>_none (func (param i32 i32)))
  (import "wasmapi" "_printStr0" (func $fimport$0 (param i32)))
  (global $global$0 (mut i32) (i32.const 5243936))
  (memory $0 256 256)
@@ -702,7 +780,7 @@ Resulting WASM:
  (func $1 (param $0 i32) (result i32)
   (i32.const 0)
  )
- (func $2 (param $0 i32)
+ (func $2 (param $0 i32) (param $1 i32)
   (nop)
  )
  (func $3