docs: update readmes

thi-ng · Nov 28, 2022 · 878012c · 878012c
1 parent bc7a0dc
commit 878012c
Show file tree

Hide file tree

Showing 6 changed files with 57 additions and 34 deletions.
diff --git a/README.md b/README.md
@@ -162,16 +162,12 @@ feature or `develop` branches)
 
 ### Latest updates
 
-As of: 2022-11-24
-
-| Status                                            | Project                                                     | Version                                                                                                                           | Changelog                                              |
-|---------------------------------------------------|-------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------|
-| ![](https://img.shields.io/badge/-feat-green)     | [`@thi.ng/colored-noise`](./packages/colored-noise)         | [![version](https://img.shields.io/npm/v/@thi.ng/colored-noise.svg)](https://www.npmjs.com/package/@thi.ng/colored-noise)         | [changelog](./packages/colored-noise/CHANGELOG.md)     |
-| ![](https://img.shields.io/badge/-feat-green)     | [`@thi.ng/hex`](./packages/hex)                             | [![version](https://img.shields.io/npm/v/@thi.ng/hex.svg)](https://www.npmjs.com/package/@thi.ng/hex)                             | [changelog](./packages/hex/CHANGELOG.md)               |
-| ![](https://img.shields.io/badge/-feat-green)     | [`@thi.ng/wasm-api`](./packages/wasm-api)                   | [![version](https://img.shields.io/npm/v/@thi.ng/wasm-api.svg)](https://www.npmjs.com/package/@thi.ng/wasm-api)                   | [changelog](./packages/wasm-api/CHANGELOG.md)          |
-| ![](https://img.shields.io/badge/-new-cyan)       | [`@thi.ng/wasm-api-bindgen`](./packages/wasm-api-bindgen)   | [![version](https://img.shields.io/npm/v/@thi.ng/wasm-api-bindgen.svg)](https://www.npmjs.com/package/@thi.ng/wasm-api-bindgen)   | [changelog](./packages/wasm-api-bindgen/CHANGELOG.md)  |
-| ![](https://img.shields.io/badge/-feat-green)     | [`@thi.ng/wasm-api-dom`](./packages/wasm-api-dom)           | [![version](https://img.shields.io/npm/v/@thi.ng/wasm-api-dom.svg)](https://www.npmjs.com/package/@thi.ng/wasm-api-dom)           | [changelog](./packages/wasm-api-dom/CHANGELOG.md)      |
-| ![](https://img.shields.io/badge/-refactor-green) | [`@thi.ng/wasm-api-schedule`](./packages/wasm-api-schedule) | [![version](https://img.shields.io/npm/v/@thi.ng/wasm-api-schedule.svg)](https://www.npmjs.com/package/@thi.ng/wasm-api-schedule) | [changelog](./packages/wasm-api-schedule/CHANGELOG.md) |
+As of: 2022-11-28
+
+| Status                                        | Project                         | Version                                                                                               | Changelog                                |
+|-----------------------------------------------|---------------------------------|-------------------------------------------------------------------------------------------------------|------------------------------------------|
+| ![](https://img.shields.io/badge/-feat-green) | [`@thi.ng/api`](./packages/api) | [![version](https://img.shields.io/npm/v/@thi.ng/api.svg)](https://www.npmjs.com/package/@thi.ng/api) | [changelog](./packages/api/CHANGELOG.md) |
+| ![](https://img.shields.io/badge/-feat-green) | [`@thi.ng/wasm-api`](./packages/wasm-api) | [![version](https://img.shields.io/npm/v/@thi.ng/wasm-api.svg)](https://www.npmjs.com/package/@thi.ng/wasm-api)                   |
 
 <!--
 ![](https://img.shields.io/badge/-feat-green)

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

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

diff --git a/packages/wasm-api-schedule/README.md b/packages/wasm-api-schedule/README.md
@@ -102,7 +102,7 @@ node --experimental-repl-await
 > const wasmApiSchedule = await import("@thi.ng/wasm-api-schedule");
 ```
 
-Package sizes (gzipped, pre-treeshake): ESM: 437 bytes
+Package sizes (gzipped, pre-treeshake): ESM: 479 bytes
 
 ## Dependencies
 

diff --git a/packages/wasm-api/README.md b/packages/wasm-api/README.md
@@ -10,11 +10,12 @@ This project is part of the
 [@thi.ng/umbrella](https://github.com/thi-ng/umbrella/) monorepo.
 
 - [About](#about)
-  - [Custom API modules](#custom-api-modules)
+- [Custom API modules](#custom-api-modules)
   - [Building Zig projects with these hybrid API modules](#building-zig-projects-with-these-hybrid-api-modules)
-  - [String handling](#string-handling)
-  - [Memory allocations](#memory-allocations)
-  - [Object indices & handles](#object-indices--handles)
+- [String handling](#string-handling)
+- [Memory allocations](#memory-allocations)
+  - [API module auto-initialization](#api-module-auto-initialization)
+- [Object indices & handles](#object-indices--handles)
 - [Status](#status)
 - [Support packages](#support-packages)
 - [Installation](#installation)
@@ -64,7 +65,7 @@ only bindings for these mentioned langs are included.
    frontend/utility](https://github.com/thi-ng/umbrella/blob/develop/packages/wasm-api-bindgen/README.md#cli-generator)
    for the code generator(s)
 
-### Custom API modules
+## Custom API modules
 
 The
 [`WasmBridge`](https://docs.thi.ng/umbrella/wasm-api/classes/WasmBridge.html)
@@ -126,7 +127,8 @@ export const bridge = new WasmBridge([new CustomAPI()]);
 ```
 
 In Zig (or any other language of your choice) we can then utilize this custom
-API like so (Please also see [example projects](https://github.com/thi-ng/umbrella/tree/develop/examples/zig-canvas/)
+API like so (Please also see [example
+projects](https://github.com/thi-ng/umbrella/tree/develop/examples/zig-canvas/)
 & other example snippets in this readme):
 
 Bindings file / lib:
@@ -176,7 +178,7 @@ To avoid guesswork about the internals of these API modules, all of them are
 using an overall uniform structure, with the main Zig entry point in
 `/zig/lib.zig`...
 
-### String handling
+## 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
@@ -198,7 +200,7 @@ Finally, see more information in the
 [@thi.ng/wasm-api-bindgen](https://github.com/thi-ng/umbrella/blob/develop/packages/wasm-api-bindgen/README.md#string-handling)
 package readme.
 
-### Memory allocations
+## Memory allocations
 
 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.
@@ -244,7 +246,18 @@ try {
 }
 ```
 
-### Object indices & handles
+### API module auto-initialization
+
+The supplied child APIs
+([wasm-api-dom](https://github.com/thi-ng/umbrella/tree/develop/packages/wasm-api-dom),
+[wasm-api-schedule](https://github.com/thi-ng/umbrella/tree/develop/packages/wasm-api-schedule)
+etc.) use an auto-intialization hook related to the above `WASM_ALLOCATOR`
+mechanism: If that allocator is available, the WASM side of these modules will
+auto initialize and thus reduce boilerplate. However, if no such central
+allocator is defined and/or a custom allocator should be used, then these API
+modules will be have to be initialized manually.
+
+## Object indices & handles
 
 Since only numeric values can be exchanged between the WASM module and the JS
 host, any JS native objects the WASM side might want to be working with must be
@@ -291,13 +304,14 @@ canvases.delete(0);
 // true
 ```
 
-Since v0.15.0, the supplied Zig core bindings lib also includes a
+The supplied Zig core library 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
+for similar resource management 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/)
 &
 [@thi.ng/wasm-api-schedule](https://github.com/thi-ng/umbrella/blob/develop/packages/wasm-api-schedule/)
-packages this is used to manage Zig event listeners.
+packages this is used to manage Zig-side event listeners.
 
 ## Status
 
@@ -334,7 +348,7 @@ node --experimental-repl-await
 > const wasmApi = await import("@thi.ng/wasm-api");
 ```
 
-Package sizes (gzipped, pre-treeshake): ESM: 2.70 KB
+Package sizes (gzipped, pre-treeshake): ESM: 2.73 KB
 
 ## Dependencies
 

diff --git a/packages/wasm-api/tpl.readme.md b/packages/wasm-api/tpl.readme.md
@@ -46,7 +46,7 @@ only bindings for these mentioned langs are included.
    frontend/utility](https://github.com/thi-ng/umbrella/blob/develop/packages/wasm-api-bindgen/README.md#cli-generator)
    for the code generator(s)
 
-### Custom API modules
+## Custom API modules
 
 The
 [`WasmBridge`](https://docs.thi.ng/umbrella/wasm-api/classes/WasmBridge.html)
@@ -108,7 +108,8 @@ export const bridge = new WasmBridge([new CustomAPI()]);
 ```
 
 In Zig (or any other language of your choice) we can then utilize this custom
-API like so (Please also see [example projects](https://github.com/thi-ng/umbrella/tree/develop/examples/zig-canvas/)
+API like so (Please also see [example
+projects](https://github.com/thi-ng/umbrella/tree/develop/examples/zig-canvas/)
 & other example snippets in this readme):
 
 Bindings file / lib:
@@ -158,7 +159,7 @@ To avoid guesswork about the internals of these API modules, all of them are
 using an overall uniform structure, with the main Zig entry point in
 `/zig/lib.zig`...
 
-### String handling
+## 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
@@ -180,7 +181,7 @@ Finally, see more information in the
 [@thi.ng/wasm-api-bindgen](https://github.com/thi-ng/umbrella/blob/develop/packages/wasm-api-bindgen/README.md#string-handling)
 package readme.
 
-### Memory allocations
+## Memory allocations
 
 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.
@@ -226,7 +227,18 @@ try {
 }
 ```
 
-### Object indices & handles
+### API module auto-initialization
+
+The supplied child APIs
+([wasm-api-dom](https://github.com/thi-ng/umbrella/tree/develop/packages/wasm-api-dom),
+[wasm-api-schedule](https://github.com/thi-ng/umbrella/tree/develop/packages/wasm-api-schedule)
+etc.) use an auto-intialization hook related to the above `WASM_ALLOCATOR`
+mechanism: If that allocator is available, the WASM side of these modules will
+auto initialize and thus reduce boilerplate. However, if no such central
+allocator is defined and/or a custom allocator should be used, then these API
+modules will be have to be initialized manually.
+
+## Object indices & handles
 
 Since only numeric values can be exchanged between the WASM module and the JS
 host, any JS native objects the WASM side might want to be working with must be
@@ -273,13 +285,14 @@ canvases.delete(0);
 // true
 ```
 
-Since v0.15.0, the supplied Zig core bindings lib also includes a
+The supplied Zig core library 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
+for similar resource management 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/)
 &
 [@thi.ng/wasm-api-schedule](https://github.com/thi-ng/umbrella/blob/develop/packages/wasm-api-schedule/)
-packages this is used to manage Zig event listeners.
+packages this is used to manage Zig-side event listeners.
 
 ${status}