@thi.ng/wasm-api 0.17.1 → 0.17.3

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2022-10-30T12:26:06Z
+- **Last updated**: 2022-10-31T09:19:33Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,15 @@ 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.17.3](https://github.com/thi-ng/umbrella/tree/@thi.ng/wasm-api@0.17.3) (2022-10-31)
+
+#### ♻️ Refactoring
+
+- restructure/rename zig files, update readdme ([c63ca10](https://github.com/thi-ng/umbrella/commit/c63ca10))
+  - enforce uniform project structure for all `[@thi.ng/wasm-api-](https://github.com/thi-ng/umbrella/tree/main/packages/wasm-api-)*` packages
+  - rename /zig/wasmapi.zig => /zig/lib.zig
+  - update readme w/ further info
+
 ### [0.17.1](https://github.com/thi-ng/umbrella/tree/@thi.ng/wasm-api@0.17.1) (2022-10-30)
 
 #### ♻️ Refactoring

package/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
 
@@ -665,10 +681,10 @@ node --experimental-repl-await
 > const wasmApi = await import("@thi.ng/wasm-api");
 ```
 
-Package sizes (gzipped, pre-treeshake): ESM: 6.84 KB
+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
@@ -695,9 +711,10 @@ directory are using this package.
 
 A selection:
 
-| Screenshot                                                                                                        | Description                                 | Live demo                                        | Source                                                                        |
-|:------------------------------------------------------------------------------------------------------------------|:--------------------------------------------|:-------------------------------------------------|:------------------------------------------------------------------------------|
-| <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/zig-canvas.png" width="240"/> | Zig-based DOM creation & canvas drawing app | [Demo](https://demo.thi.ng/umbrella/zig-canvas/) | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/zig-canvas) |
+| Screenshot                                                                                                         | Description                                 | Live demo                                         | Source                                                                         |
+|:-------------------------------------------------------------------------------------------------------------------|:--------------------------------------------|:--------------------------------------------------|:-------------------------------------------------------------------------------|
+| <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/zig-canvas.png" width="240"/>  | Zig-based DOM creation & canvas drawing app | [Demo](https://demo.thi.ng/umbrella/zig-canvas/)  | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/zig-canvas)  |
+| <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/zig-counter.png" width="240"/> | Simple Zig/WASM click counter DOM component | [Demo](https://demo.thi.ng/umbrella/zig-counter/) | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/zig-counter) |
 
 ## API
 
@@ -756,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

package/api.d.ts

@@ -53,7 +53,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)
@@ -161,12 +161,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>;
@@ -458,7 +458,11 @@ export interface CodeGenOpts extends CodeGenOptsBase {
      */
     stringType: "slice" | "ptr";
     /**
-     * If true (default), forces uppercase enum identifiers
+     * If true (default), forces uppercase enum identifiers.
+     *
+     * @remarks
+     * This option is ignored in {@link ZIG} since it's idiomatic for that
+     * language to only use lowercase/camelCase enum IDs.
      *
      * @defaultValue true
      */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/wasm-api",
-  "version": "0.17.1",
+  "version": "0.17.3",
   "description": "Generic, modular, extensible API bridge, polyglot glue code and bindings code generators for hybrid JS & WebAssembly projects",
   "type": "module",
   "module": "./index.js",
@@ -141,5 +141,5 @@
     "status": "alpha",
     "year": 2022
   },
-  "gitHead": "78682fcd936495fefa1345db5a8dfd709eace2c8\n"
+  "gitHead": "7c5c0cb37ff88c2fa5dd77dd78bf3a5ceb5c62c6\n"
 }

package/zig/{wasmapi.zig → lib.zig}

@@ -1,4 +1,4 @@
-//! JavaScript externals for https://thi.ng/wasm-api
+//! Zig API for https://thi.ng/wasm-api
 
 const std = @import("std");
 const root = @import("root");
@@ -72,7 +72,7 @@ pub fn panic(msg: []const u8, _: ?*std.builtin.StackTrace, _: ?usize) noreturn {
 /// Note: The type for this var is purposefully chosen as an optional,
 /// effectively disabling allocations from the WASM host side if no
 /// `WASM_ALLOCATOR` is set (or set to null).
-pub fn allocator() ?std.mem.Allocator {
+pub inline fn allocator() ?std.mem.Allocator {
     return if (@hasDecl(root, "WASM_ALLOCATOR")) root.WASM_ALLOCATOR else null;
 }