docs: update readmes

thi-ng · Oct 3, 2022 · 86a3489 · 86a3489
1 parent bab4e0c
commit 86a3489
Show file tree

Hide file tree

Showing 4 changed files with 179 additions and 113 deletions.
diff --git a/packages/hiccup-html/README.md b/packages/hiccup-html/README.md
@@ -189,7 +189,7 @@ node --experimental-repl-await
 > const hiccupHtml = await import("@thi.ng/hiccup-html");
 ```
 
-Package sizes (gzipped, pre-treeshake): ESM: 1.68 KB
+Package sizes (gzipped, pre-treeshake): ESM: 1.66 KB
 
 ## Dependencies
 

diff --git a/packages/wasm-api-dom/README.md b/packages/wasm-api-dom/README.md
@@ -51,7 +51,7 @@ node --experimental-repl-await
 > const wasmApiDom = await import("@thi.ng/wasm-api-dom");
 ```
 
-Package sizes (gzipped, pre-treeshake): ESM: 1.62 KB
+Package sizes (gzipped, pre-treeshake): ESM: 2.13 KB
 
 ## Dependencies
 

diff --git a/packages/wasm-api/README.md b/packages/wasm-api/README.md
@@ -41,9 +41,10 @@ This package provides a the following:
 class as interop basis and much reduced boilerplate for hybrid JS/WebAssembly
 applications.
 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). In
-the future we aim to also supply support modules for DOM manipulation, WebGL,
-WebGPU, WebAudio etc.
+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 extern JS [core
@@ -53,15 +54,17 @@ WebGPU, WebAudio etc.
    [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 few langs are included.
+bindings for these mentioned langs are included.
 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.
+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
 
@@ -75,7 +78,7 @@ $ npx @thi.ng/wasm-api
 
  █ █   █           │
 ██ █               │
- █ █ █ █   █ █ █ █ │ @thi.ng/wasm-api 0.11.0
+ █ █ █ █   █ █ █ █ │ @thi.ng/wasm-api 0.12.0
  █ █ █ █ █ █ █ █ █ │ Multi-language data bindings code generator
                  █ │
                █ █ │
@@ -90,6 +93,7 @@ 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: "c11", "ts", "zig" (default: ["ts","zig"])
 -o FILE, --out FILE             [multiple] output file path
@@ -197,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 {
@@ -241,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 {
@@ -272,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 {
@@ -288,9 +321,9 @@ pub const Bar = struct {
 };
 
 pub const Kind = enum(u16) {
-    unknown,
-    good = 100,
-    best = 1000,
+    UNKNOWN,
+    GOOD = 100,
+    BEST = 1000,
 };
 ```
 </details>
@@ -567,7 +600,7 @@ node --experimental-repl-await
 > const wasmApi = await import("@thi.ng/wasm-api");
 ```
 
-Package sizes (gzipped, pre-treeshake): ESM: 6.13 KB
+Package sizes (gzipped, pre-treeshake): ESM: 6.29 KB
 
 **IMPORTANT:** The package includes code generators for various languages which
 are **not** required for just using the API bridge. Hence, the usual package