@thi.ng/wasm-api 0.9.0 → 0.11.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2022-08-23T10:37:04Z
+- **Last updated**: 2022-09-21T21:37:59Z
 - **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.11.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/wasm-api@0.11.0) (2022-09-21)
+
+#### 🚀 Features
+
+- refactor CodeGenOpts, update CLI config handling ([fa2e30f](https://github.com/thi-ng/umbrella/commit/fa2e30f))
+  - extract CodeGenOptsBase interface for common pre/post config
+  - update CLI config loading to support loading pre/post contents
+    from separate files (if value given as `@path/to-file.ext`)
+- update/fix codegens & config ([87def23](https://github.com/thi-ng/umbrella/commit/87def23))
+  - add global `CodeGenOpts.uppercaseEnums` option (migrate from TSOpts)
+  - set `i32` as enum default tag (for C compatibility)
+  - update C11 codegen, add `typePrefix` option
+  - fix C11 enum codegen (use `typedef enum`)
+  - add internal enumName() helper
+  - minor updates Zig codegen
+- update codegen CLI ([435ad2b](https://github.com/thi-ng/umbrella/commit/435ad2b))
+  - add C11 support
+  - add support for padding fields (in `validateTypeRefs()`)
+  - add CLI arg for forcing string type impl
+  - update deps
+- add C11 support, update codegens & config ([590311e](https://github.com/thi-ng/umbrella/commit/590311e))
+  - add preliminary C11 codegen
+  - add optional `tag` field for structs (extern/packed)
+  - add support for auto-labeled padding fields
+    - i.e. defined via unnamed fields with `pad` value
+  - move debug config option to global `CodeGenOpts`
+- update TS codegen (array pointers) ([30360f2](https://github.com/thi-ng/umbrella/commit/30360f2))
+- update CodeGenOpts ([b9fd7ff](https://github.com/thi-ng/umbrella/commit/b9fd7ff))
+- major update codegens, string & pointer handling ([4f02295](https://github.com/thi-ng/umbrella/commit/4f02295))
+  - update/fix string wrappers (`WasmStringSlice/Ptr`)
+  - add generic `Pointer` wrapper
+  - add `const` field type support
+  - add applyIndents() formatter fn, simplify all codegens
+  - major update TS & Zig codegens
+- WasmString codegen integration ([97fc318](https://github.com/thi-ng/umbrella/commit/97fc318))
+  - update TS codegen to wrap strings using new `WasmString` or `WasmStringPtr`
+  - update global codegen options handling, now passed to each codegen
+  - update TSOpts & ZigOpts to include custom pre/post
+- add WasmString wrappers ([18d8fcb](https://github.com/thi-ng/umbrella/commit/18d8fcb))
+  - still unused (to be added to TS codegen)
+- update core API & bindings ([b185ea5](https://github.com/thi-ng/umbrella/commit/b185ea5))
+  - add _panic(), timer(), epoch() core API fns
+  - update printI/U64() fns to accept bigint
+  - update C & Zig bindings
+  - update tests
+  - add clang-format
+
+## [0.10.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/wasm-api@0.10.0) (2022-08-24)
+
+#### 🚀 Features
+
+- add events, update allocator handling ([89416b1](https://github.com/thi-ng/umbrella/commit/89416b1))
+  - add INotify impl for WasmBridge
+  - emit event when WASM memory has changed (e.g. to recreate user views)
+  - reverse logic so that NO allocator is used by default and instead must
+    be explicitly enabled (rather than disabled)
+  - update Zig & C bindings
+  - add/update docstrings
+
 ## [0.9.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/wasm-api@0.9.0) (2022-08-23)
 
 #### 🚀 Features

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?eb6dbc93)
 
 [![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,15 +10,15 @@ 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)
 - [Installation](#installation)
 - [Dependencies](#dependencies)
 - [API](#api)
@@ -30,7 +30,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 +38,34 @@ 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). 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
+   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
+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 few 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.
 
 #### 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 +73,7 @@ $ npx @thi.ng/wasm-api
 
  █ █   █           │
 ██ █               │
- █ █ █ █   █ █ █ █ │ @thi.ng/wasm-api 0.6.0
+ █ █ █ █   █ █ █ █ │ @thi.ng/wasm-api 0.11.0
  █ █ █ █ █ █ █ █ █ │ Multi-language data bindings code generator
                  █ │
                █ █ │
@@ -172,17 +89,19 @@ Flags:
 Main:
 
 -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 +109,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
@@ -418,12 +351,30 @@ 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
+If explicitly enabled on the WASM side, the `WasmBridge` includes support for
+malloc/free-style allocations (within the linear WASM memory) from the JS side
+(Note: This is a breaking change in v0.10.0, now using a more flexible approach
+& reverse logic of earlier alpha versions).
+
+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):
+  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):
+  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
+- [`WasmBridge.free()`](https://docs.thi.ng/umbrella/wasm-api/classes/WasmBridge.html#free):
+  freeing previously allocated memory from JS side
+
+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 and
+[tests](https://github.com/thi-ng/umbrella/tree/develop/packages/wasm-api/test)
+for more details...
 
 ```ts
 try {
@@ -431,7 +382,7 @@ try {
 	const addr = bridge.allocate(256);
 
 	// write string to reserved memory
-	// max. 256 bytes written, zero terminated
+	// max. 256 bytes, zero terminated
 	const num = bridge.setString("hello WASM world!", addr, 256, true);
 
 	// call WASM function doing something w/ the string
@@ -440,11 +391,100 @@ try {
 	// cleanup
 	bridge.free(addr, 256);
 } catch(e) {
-	// allocation error
+	// deal with allocation error
 	// ...
 }
 ```
 
+### 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
@@ -492,7 +532,7 @@ canvases.delete(0);
 // true
 ```
 
-### Status
+## Status
 
 **ALPHA** - bleeding edge / work-in-progress
 
@@ -521,11 +561,11 @@ node --experimental-repl-await
 > const wasmApi = await import("@thi.ng/wasm-api");
 ```
 
-Package sizes (gzipped, pre-treeshake): ESM: 4.34 KB
+Package sizes (gzipped, pre-treeshake): ESM: 6.05 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
 
@@ -540,6 +580,7 @@ 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)
 
 ## API
 
@@ -615,16 +656,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)
   )
  )
@@ -651,7 +692,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
 ```
@@ -664,6 +705,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)
@@ -686,7 +728,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