@thi.ng/wasm-api 0.14.0 → 0.16.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2022-10-17T12:08:09Z
+- **Last updated**: 2022-10-28T19:08:39Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,65 @@ 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.16.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/wasm-api@0.16.0) (2022-10-28)
+
+#### 🚀 Features
+
+- update TS docstring generator ([5a060b6](https://github.com/thi-ng/umbrella/commit/5a060b6))
+  - include native/WASM type in docstring (use Zig type sigs)
+  - update ensureLines() helper
+  - update test fixtures
+- update IWasmMemoryAccess & impls ([bb8a3ca](https://github.com/thi-ng/umbrella/commit/bb8a3ca))
+  - add MemorySlice tuple to describe a memory region
+  - update allocate() & free() to use MemorySlice, migrate to IWasmMemoryAccess
+  - migrate growMemory() to IWasmMemoryAccess
+  - add MemorySlice to default imports in TS codegen
+- update docstring & user code codegen config ([68694ba](https://github.com/thi-ng/umbrella/commit/68694ba))
+  - allow doc strings & user codes to be given as string array (lines)
+  - add InjectedBody type to support multiple injection sites
+    (e.g. TS interface declarations vs. wrapper impls)
+  - update TS & Zig codegens
+  - add internal ensureLines() helper
+
+#### 🩹 Bug fixes
+
+- fix ensureLines(), update tests & fixtures ([f8a4668](https://github.com/thi-ng/umbrella/commit/f8a4668))
+
+## [0.15.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/wasm-api@0.15.0) (2022-10-26)
+
+#### 🚀 Features
+
+- import ManagedIndex, migrate Zig API ([d8bb3ee](https://github.com/thi-ng/umbrella/commit/d8bb3ee))
+  - migrate ManagedIndex from [@thi.ng/wasm-api-dom](https://github.com/thi-ng/umbrella/tree/main/packages/wasm-api-dom)
+  - move all Zig sources from /include => /zig
+  - update pkg
+- add codegen support for union types ([bbc1f98](https://github.com/thi-ng/umbrella/commit/bbc1f98))
+  - add Union type, update TopLevelType
+  - update all codegens (C,TS,Zig)
+  - update alignOf(), sizeOf()
+  - update selectAlignment()
+- add/update codegen alignment logic ([9c19ad9](https://github.com/thi-ng/umbrella/commit/9c19ad9))
+  - add AlignmentStrategy & impls
+  - update alignOf(), sizeOf(), prepareType()
+  - extract DEFAULT_CODEGEN_OPTS
+  - add Struct.align config option
+- add WasmTarget codegen opt & usize support ([62c049b](https://github.com/thi-ng/umbrella/commit/62c049b))
+
+#### 🩹 Bug fixes
+
+- update CLI wrapper to allow unions ([904716c](https://github.com/thi-ng/umbrella/commit/904716c))
+- fix i64/u64 handling in sizeof() ([825add3](https://github.com/thi-ng/umbrella/commit/825add3))
+- fix padding in Zig packed structs ([8d70cf6](https://github.com/thi-ng/umbrella/commit/8d70cf6))
+  - since packed structs can't contain `[n]u8` types,
+    generate padding as potentially multiple `uXXX` fields
+
+#### ♻️ Refactoring
+
+- rename types, use predicates ([4148e1e](https://github.com/thi-ng/umbrella/commit/4148e1e))
+  - rename StructField => Field
+  - update codegens to use more predicates instead of inline checks
+- minor updates C & Zig codegens ([a94e1cc](https://github.com/thi-ng/umbrella/commit/a94e1cc))
+
 ## [0.14.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/wasm-api@0.14.0) (2022-10-17)
 
 #### 🚀 Features

package/README.md

@@ -45,24 +45,27 @@ applications.
 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 extern JS [core
+3. Include files for
+   [C11/C++](https://github.com/thi-ng/umbrella/tree/develop/packages/wasm-api/include)
+   and
+   [Zig](https://github.com/thi-ng/umbrella/tree/develop/packages/wasm-api/zig),
+   defining glue code for 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) 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.
+4. Extensible shared datatype code generators for (currently) C11, Zig &
+   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
+mentioned langs are included. Other languages require custom bindings, e.g.
+based on the flexible primitives provided here.
 5. [CLI frontend/utility](#cli-generator) to invoke the code generator(s)
 
 ### 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 available too. See the
+env. Currently, code generators for TypeScript, Zig and C11 are supplied. 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...
 
@@ -78,7 +81,7 @@ $ npx @thi.ng/wasm-api
 
  █ █   █           │
 ██ █               │
- █ █ █ █   █ █ █ █ │ @thi.ng/wasm-api 0.12.0
+ █ █ █ █   █ █ █ █ │ @thi.ng/wasm-api 0.15.0
  █ █ █ █ █ █ █ █ █ │ Multi-language data bindings code generator
                  █ │
                █ █ │
@@ -88,7 +91,7 @@ usage: wasm-api [OPTS] JSON-INPUT-FILE(S) ...
 
 Flags:
 
--d, --debug                     enable debug output
+-d, --debug                     enable debug output & functions
 --dry-run                       enable dry run (don't overwrite files)
 
 Main:
@@ -102,8 +105,8 @@ Main:
 
 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:
+as the target languages. It's recommended to be explicit with this. An example
+invocation looks like:
 
 ```bash
 wasm-api \
@@ -145,53 +148,62 @@ external files by specifying their file paths using `@` as prefix, e.g.
 
 #### Data type definitions
 
-Currently, the code generator supports structs and enums. See API docs for
+Currently, the code generator supports enums, structs and unions. 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)
+- [`EnumValue`](https://docs.thi.ng/umbrella/wasm-api/interfaces/EnumValue.html) (individual enum value spec)
+- [`Field`](https://docs.thi.ng/umbrella/wasm-api/interfaces/Field.html) (individual spec for values contained in structs/unions)
 - [`Struct`](https://docs.thi.ng/umbrella/wasm-api/interfaces/Struct.html)
-- [`StructField`](https://docs.thi.ng/umbrella/wasm-api/interfaces/StructField.html)
+- [`Union`](https://docs.thi.ng/umbrella/wasm-api/interfaces/Union.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:
+The following example defines 1x enum, 2x structs and 1x union. Shown here are
+the JSON type definitions and the resulting source codes:
 
 **⬇︎ CLICK TO EXPAND EACH CODE BLOCK ⬇︎**
 
 <details><summary>types.json (Type definitions)</summary>
 
-```json
+```json tangle:export/readme-types.json
 [
 	{
-		"name": "Foo",
+		"name": "EventType",
+		"type": "enum",
+		"tag": "u8",
+		"values": [
+			"unknown",
+			{ "name": "mouse", "value": 16 },
+			{ "name": "key", "value": 32 }
+		]
+	},
+	{
+		"name": "MouseEvent",
 		"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": "type", "type": "EventType" },
+			{ "name": "pos", "type": "u16", "tag": "vec", "len": 2 }
 		]
 	},
 	{
-		"name": "Bar",
+		"name": "KeyEvent",
 		"type": "struct",
+		"doc": "Example struct",
 		"fields": [
-			{ "name": "kind", "type": "Kind" },
-			{ "name": "flags", "type": "u32" }
+			{ "name": "type", "type": "EventType" },
+			{ "name": "key", "type": "string" },
+			{ "name": "modifiers", "type": "u8", "doc": "Bitmask of modifier keys" }
 		]
 	},
 	{
-		"name": "Kind",
-		"type": "enum",
-		"tag": "u16",
-		"values": [
-			"unknown",
-			{ "name": "good", "value": 100 },
-			{ "name": "best", "value": 1000 }
+		"name": "Event",
+		"type": "union",
+		"fields": [
+			{ "name": "mouse", "type": "MouseEvent" },
+			{ "name": "key", "type": "KeyEvent" }
 		]
 	}
 ]
@@ -202,71 +214,113 @@ codes:
 
 ```ts
 /**
- * Generated by @thi.ng/wasm-api at 2022-10-03T15:32:12.339Z - DO NOT EDIT!
+ * Generated by @thi.ng/wasm-api at 2022-10-26T08:36:16.825Z - DO NOT EDIT!
  */
 
 // @ts-ignore possibly includes unused imports
 import { Pointer, WasmStringSlice, WasmTypeBase, WasmTypeConstructor } from "@thi.ng/wasm-api";
 
+export enum EventType {
+	UNKNOWN,
+	MOUSE = 16,
+	KEY = 32,
+}
+
+/**
+ * Example struct
+ */
+export interface MouseEvent extends WasmTypeBase {
+	type: EventType;
+	pos: Uint16Array;
+}
+
+export const $MouseEvent: WasmTypeConstructor<MouseEvent> = (mem) => ({
+	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 type(): EventType {
+				return mem.u8[base];
+			},
+			set type(x: EventType) {
+				mem.u8[base] = x;
+			},
+			get pos(): Uint16Array {
+				const addr = (base + 4) >>> 1;
+				return mem.u16.subarray(addr, addr + 2);
+			},
+		};
+	}
+});
+
 /**
  * Example struct
  */
-export interface Foo extends WasmTypeBase {
-	color: Float32Array;
-	bars: Bar[];
+export interface KeyEvent extends WasmTypeBase {
+	type: EventType;
+	key: WasmStringSlice;
 	/**
-	 * Unique ID
+	 * Bitmask of modifier keys
 	 */
-	id: number;
+	modifiers: number;
 }
 
-export const $Foo: WasmTypeConstructor<Foo> = (mem) => ({
+export const $KeyEvent: WasmTypeConstructor<KeyEvent> = (mem) => ({
 	get align() {
-		return 16;
+		return 4;
 	},
 	get size() {
-		return 48;
+		return 16;
 	},
 	instance: (base) => {
+		let $key: WasmStringSlice | null = null;
 		return {
 			get __base() {
 				return base;
 			},
 			get __bytes() {
-				return mem.u8.subarray(base, base + 48);
+				return mem.u8.subarray(base, base + 16);
+			},
+			get type(): EventType {
+				return mem.u8[base];
 			},
-			get color(): Float32Array {
-				const addr = base >>> 2;
-				return mem.f32.subarray(addr, addr + 4);
+			set type(x: EventType) {
+				mem.u8[base] = x;
 			},
-			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 key(): WasmStringSlice {
+				return $key || ($key = new WasmStringSlice(mem, (base + 4), true));
 			},
-			get id(): number {
-				return mem.u8[(base + 40)];
+			get modifiers(): number {
+				return mem.u8[(base + 12)];
 			},
-			set id(x: number) {
-				mem.u8[(base + 40)] = x;
+			set modifiers(x: number) {
+				mem.u8[(base + 12)] = x;
 			},
 		};
 	}
 });
 
-export interface Bar extends WasmTypeBase {
-	kind: Kind;
-	flags: number;
+export interface Event extends WasmTypeBase {
+	mouse: MouseEvent;
+	key: KeyEvent;
 }
 
-export const $Bar: WasmTypeConstructor<Bar> = (mem) => ({
+export const $Event: WasmTypeConstructor<Event> = (mem) => ({
 	get align() {
 		return 4;
 	},
 	get size() {
-		return 8;
+		return 16;
 	},
 	instance: (base) => {
 		return {
@@ -274,91 +328,92 @@ export const $Bar: WasmTypeConstructor<Bar> = (mem) => ({
 				return base;
 			},
 			get __bytes() {
-				return mem.u8.subarray(base, base + 8);
+				return mem.u8.subarray(base, base + 16);
 			},
-			get kind(): Kind {
-				return mem.u16[base >>> 1];
+			get mouse(): MouseEvent {
+				return $MouseEvent(mem).instance(base);
 			},
-			set kind(x: Kind) {
-				mem.u16[base >>> 1] = x;
+			set mouse(x: MouseEvent) {
+				mem.u8.set(x.__bytes, base);
 			},
-			get flags(): number {
-				return mem.u32[(base + 4) >>> 2];
+			get key(): KeyEvent {
+				return $KeyEvent(mem).instance(base);
 			},
-			set flags(x: number) {
-				mem.u32[(base + 4) >>> 2] = x;
+			set key(x: KeyEvent) {
+				mem.u8.set(x.__bytes, base);
 			},
 		};
 	}
 });
-
-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-10-03T15:32:12.341Z - DO NOT EDIT!
+//! Generated by @thi.ng/wasm-api at 2022-10-26T08:36:16.827Z - DO NOT EDIT!
 
 const std = @import("std");
 
+pub const EventType = enum(u8) {
+    UNKNOWN,
+    MOUSE = 16,
+    KEY = 32,
+};
+
 /// Example struct
-pub const Foo = struct {
-    color: @Vector(4, f32),
-    bars: [3]Bar,
-    /// Unique ID
-    id: u8,
+pub const MouseEvent = struct {
+    type: EventType,
+    pos: @Vector(2, u16),
 };
 
-pub const Bar = struct {
-    kind: Kind,
-    flags: u32,
+/// Example struct
+pub const KeyEvent = struct {
+    type: EventType,
+    key: []const u8,
+    /// Bitmask of modifier keys
+    modifiers: u8,
 };
 
-pub const Kind = enum(u16) {
-    UNKNOWN,
-    GOOD = 100,
-    BEST = 1000,
+pub const Event = union {
+    mouse: MouseEvent,
+    key: KeyEvent,
 };
 ```
 </details>
 
-On the TypeScript/JS side, the memory-mapped wrappers (e.g. `$Foo` and `$Bar`)
+On the TypeScript/JS side, the memory-mapped wrappers (e.g. `$Event`)
 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";
+import { $Event, EventType } 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
+// and mapping a `Event` union from given address
 // (e.g. obtained from an exported WASM function/value)
-const foo = $Foo(bridge).instance(0x10000);
+const event = $Event(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;
+event.mouse.pos
+// Uint16Array(2) [100, 200]
 
 // IMPORTANT: any modifications like this are directly
 // applied to the underlying WASM memory...
+event.mouse.pos[0] = 300;
+
+event.mouse.type === EventType.MOUSE
+// true
 ```
 
-**IMPORTANT:** Struct field setters are currently only supported for single
-values, incl. enums, strings, structs. The latter 2 will always be copied by
+**IMPORTANT:** Field setters are currently only supported for single values,
+incl. enums, strings, structs, unions. The latter 2 will always be copied by
 value (mem copy). Arrays or slices of strings do not currently provide write
 access...
 
@@ -395,9 +450,9 @@ The actual allocator is implementation specific and suitable generic mechanisms
 are defined for both the included Zig & C bindings. Please see for further
 reference:
 
-- [`/include/wasmapi.zig`](https://github.com/thi-ng/umbrella/blob/develop/packages/wasm-api/include/wasmapi.zig#L6):
+- [`/zig/wasmapi.zig`](https://github.com/thi-ng/umbrella/blob/develop/packages/wasm-api/zig/wasmapi.zig#L64):
   comments about WASM-side allocator handling in Zig
-- [`/include/wasmapi.h`](https://github.com/thi-ng/umbrella/blob/develop/packages/wasm-api/include/wasmapi.h#L19):
+- [`/include/wasmapi.h`](https://github.com/thi-ng/umbrella/blob/develop/packages/wasm-api/include/wasmapi.h#L18):
   comments about WASM-side allocator handling in C/C++
 - [`WasmBridge.allocate()`](https://docs.thi.ng/umbrella/wasm-api/classes/WasmBridge.html#allocate):
   allocating memory from JS side
@@ -490,6 +545,8 @@ API like so (Please also see
 [tests](https://github.com/thi-ng/umbrella/tree/develop/packages/wasm-api/test)
 & other examples in this readme):
 
+Bindings file / lib:
+
 ```zig
 //! custom.zig - extern definitions of custom JS API
 
@@ -498,9 +555,11 @@ API like so (Please also see
 /// 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;
+extern "custom" fn fillRandom(addr: [*]f32, num: usize) void;
 ```
 
+Main Zig file:
+
 ```zig
 // Import JS core API
 const js = @import("wasmapi");
@@ -513,7 +572,7 @@ export fn test_randomVec4() void {
 	js.printF32Array(foo[0..]);
 
 	// populate foo with random numbers
-	custom.fillRandom(@ptrToInt(&foo), foo.len);
+	custom.fillRandom(&foo, foo.len);
 
 	// print result
 	js.printF32Array(foo[0..]);
@@ -567,6 +626,12 @@ canvases.delete(0);
 // true
 ```
 
+Since v0.15.0, the supplied Zig core bindings lib also includes a
+[`ManagedIndex`](https://github.com/thi-ng/umbrella/blob/develop/packages/wasm-api/zig/managed-index.zig)
+for similar dealings on the Zig side of the application. For example, in the
+[@thi.ng/wasm-api-dom](https://github.com/thi-ng/umbrella/blob/develop/packages/wasm-api-dom/)
+module this is used to manage Zig event listeners.
+
 ## Status
 
 **ALPHA** - bleeding edge / work-in-progress
@@ -600,7 +665,7 @@ node --experimental-repl-await
 > const wasmApi = await import("@thi.ng/wasm-api");
 ```
 
-Package sizes (gzipped, pre-treeshake): ESM: 6.29 KB
+Package sizes (gzipped, pre-treeshake): ESM: 6.84 KB
 
 **IMPORTANT:** The package includes code generators for various languages which
 are **not** required for just using the API bridge. Hence, the usual package
@@ -691,7 +756,7 @@ folder):
 ```bash
 # compile WASM binary
 zig build-lib \
-	--pkg-begin wasmapi node_modules/@thi.ng/wasm-api/include/wasmapi.zig --pkg-end \
+	--pkg-begin wasmapi node_modules/@thi.ng/wasm-api/zig/wasmapi.zig --pkg-end \
 	-target wasm32-freestanding \
 	-O ReleaseSmall -dynamic --strip \
 	hello.zig