refactor(wasm-api): restructure/rename zig files, update readdme

- enforce uniform project structure for all `thi.ng/wasm-api-*` packages - rename /zig/wasmapi.zig => /zig/lib.zig - update readme w/ further info
thi-ng · Oct 30, 2022 · c63ca10 · c63ca10
1 parent 4e99c69
commit c63ca10
Show file tree

Hide file tree

Showing 4 changed files with 50 additions and 20 deletions.
diff --git a/packages/wasm-api/README.md b/packages/wasm-api/README.md
@@ -17,6 +17,7 @@ This project is part of the
   - [String handling](#string-handling)
   - [Memory allocations](#memory-allocations)
   - [Custom API modules](#custom-api-modules)
+  - [Building Zig projects with these hybrid API modules](#building-zig-projects-with-these-hybrid-api-modules)
   - [Object indices & handles](#object-indices--handles)
 - [Status](#status)
 - [Support packages](#support-packages)
@@ -450,7 +451,7 @@ The actual allocator is implementation specific and suitable generic mechanisms
 are defined for both the included Zig & C bindings. Please see for further
 reference:
 
-- [`/zig/wasmapi.zig`](https://github.com/thi-ng/umbrella/blob/develop/packages/wasm-api/zig/wasmapi.zig#L64):
+- [`/zig/lib.zig`](https://github.com/thi-ng/umbrella/blob/develop/packages/wasm-api/zig/lib.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#L18):
   comments about WASM-side allocator handling in C/C++
@@ -541,9 +542,8 @@ 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):
+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:
 
@@ -579,6 +579,19 @@ export fn test_randomVec4() void {
 }
 ```
 
+### Building Zig projects with these hybrid API modules
+
+Some example projects (see [list below](#usage-examples)) provide custom
+[`build.zig`](https://github.com/thi-ng/umbrella/blob/develop/examples/zig-canvas/build.zig)
+&
+[`npm.zig`](https://github.com/thi-ng/umbrella/blob/develop/examples/zig-canvas/npm.zig)
+build scripts to easily integrate these hybrid TS/Zig packages into users'
+development processes.
+
+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`...
+
 ### Object indices & handles
 
 Since only numeric values can be exchanged between the WASM module and the JS
@@ -630,7 +643,9 @@ 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.
+&
+[@thi.ng/wasm-api-timer](https://github.com/thi-ng/umbrella/blob/develop/packages/wasm-api-timer/)
+modules this is used to manage Zig event listeners.
 
 ## Status
 
@@ -640,7 +655,8 @@ module this is used to manage Zig event listeners.
 
 ## 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
+- [@thi.ng/wasm-api-dom](https://github.com/thi-ng/umbrella/tree/develop/packages/wasm-api-dom) - Browser DOM bridge API for hybrid TypeScript & WASM (Zig) applications
+- [@thi.ng/wasm-api-timer](https://github.com/thi-ng/umbrella/tree/develop/packages/wasm-api-timer) - Delayed & scheduled function execution (via setTimeout() etc.) for hybrid WASM apps
 
 ## Installation
 
@@ -667,8 +683,8 @@ node --experimental-repl-await
 
 Package sizes (gzipped, pre-treeshake): ESM: 7.06 KB
 
-**IMPORTANT:** The package includes code generators for various languages which
-are **not** required for just using the API bridge. Hence, the usual package
+**IMPORTANT:** The package includes multiple language code generators which are
+**not** required for normal use of the API bridge. Hence, the actual package
 size in production will be MUCH smaller than what's stated here!
 
 ## Dependencies
@@ -757,7 +773,7 @@ folder):
 ```bash
 # compile WASM binary
 zig build-lib \
-	--pkg-begin wasmapi node_modules/@thi.ng/wasm-api/zig/wasmapi.zig --pkg-end \
+	--pkg-begin wasmapi node_modules/@thi.ng/wasm-api/zig/lib.zig --pkg-end \
 	-target wasm32-freestanding \
 	-O ReleaseSmall -dynamic --strip \
 	hello.zig

diff --git a/packages/wasm-api/src/api.ts b/packages/wasm-api/src/api.ts
@@ -67,7 +67,7 @@ export interface WasmExports {
 	 * @remarks
 	 * #### Zig
 	 *
-	 * Using the supplied Zig bindings (see `/zig/wasmapi.zig`), it's the
+	 * Using the supplied Zig bindings (see `/zig/lib.zig`), it's the
 	 * user's responsibility to define a public `WASM_ALLOCATOR` in the root
 	 * source file to enable allocations, e.g. using the
 	 * [`std.heap.GeneralPurposeAllocator`](https://ziglang.org/documentation/master/#Choosing-an-Allocator)
@@ -189,12 +189,12 @@ export interface IWasmMemoryAccess {
 
 /**
  * Core API of WASM imports defined by the {@link WasmBridge}. The same
- * functions are declared as bindings in `/zig/wasmapi.zig`. **Also see this
+ * functions are declared as bindings in `/zig/lib.zig`. **Also see this
  * file for documentation of each function...**
  *
  * @remarks
  * Zig API:
- * https://github.com/thi-ng/umbrella/blob/develop/packages/wasm-api/zig/wasmapi.zig
+ * https://github.com/thi-ng/umbrella/blob/develop/packages/wasm-api/zig/lib.zig
  */
 export interface CoreAPI extends WebAssembly.ModuleImports {
 	printI8: Fn<number, void>;

diff --git a/packages/wasm-api/tpl.readme.md b/packages/wasm-api/tpl.readme.md
@@ -429,7 +429,7 @@ The actual allocator is implementation specific and suitable generic mechanisms
 are defined for both the included Zig & C bindings. Please see for further
 reference:
 
-- [`/zig/wasmapi.zig`](https://github.com/thi-ng/umbrella/blob/develop/packages/wasm-api/zig/wasmapi.zig#L64):
+- [`/zig/lib.zig`](https://github.com/thi-ng/umbrella/blob/develop/packages/wasm-api/zig/lib.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#L18):
   comments about WASM-side allocator handling in C/C++
@@ -520,9 +520,8 @@ 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):
+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:
 
@@ -558,6 +557,19 @@ export fn test_randomVec4() void {
 }
 ```
 
+### Building Zig projects with these hybrid API modules
+
+Some example projects (see [list below](#usage-examples)) provide custom
+[`build.zig`](https://github.com/thi-ng/umbrella/blob/develop/examples/zig-canvas/build.zig)
+&
+[`npm.zig`](https://github.com/thi-ng/umbrella/blob/develop/examples/zig-canvas/npm.zig)
+build scripts to easily integrate these hybrid TS/Zig packages into users'
+development processes.
+
+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`...
+
 ### Object indices & handles
 
 Since only numeric values can be exchanged between the WASM module and the JS
@@ -609,7 +621,9 @@ 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.
+&
+[@thi.ng/wasm-api-timer](https://github.com/thi-ng/umbrella/blob/develop/packages/wasm-api-timer/)
+modules this is used to manage Zig event listeners.
 
 ${status}
 
@@ -625,8 +639,8 @@ ${pkg.install}
 
 ${pkg.size}
 
-**IMPORTANT:** The package includes code generators for various languages which
-are **not** required for just using the API bridge. Hence, the usual package
+**IMPORTANT:** The package includes multiple language code generators which are
+**not** required for normal use of the API bridge. Hence, the actual package
 size in production will be MUCH smaller than what's stated here!
 
 ## Dependencies
@@ -692,7 +706,7 @@ folder):
 ```bash
 # compile WASM binary
 zig build-lib \
-	--pkg-begin wasmapi node_modules/@thi.ng/wasm-api/zig/wasmapi.zig --pkg-end \
+	--pkg-begin wasmapi node_modules/@thi.ng/wasm-api/zig/lib.zig --pkg-end \
 	-target wasm32-freestanding \
 	-O ReleaseSmall -dynamic --strip \
 	hello.zig

diff --git a/packages/wasm-api/zig/wasmapi.zig → packages/wasm-api/zig/lib.zig b/packages/wasm-api/zig/wasmapi.zig → packages/wasm-api/zig/lib.zig