@thi.ng/wasm-api 1.0.0 → 1.0.1

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2022-11-23T22:46:54Z
+- **Last updated**: 2022-11-24T12:23:48Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.

package/README.md

@@ -59,8 +59,7 @@ WebGL, WebGPU, WebAudio etc. is being actively worked on.
    for (currently) Zig & TypeScript and C11. For TS fully type checked and
 memory-mapped (zero-copy) accessors of WASM-side data are generated. In
 principle, all languages with a WASM target are supported, however currently
-only bindings for these mentioned langs are included. Other languages require
-custom bindings, e.g. based on the flexible primitives provided here.
+only bindings for these mentioned langs are included.
 8. [CLI
    frontend/utility](https://github.com/thi-ng/umbrella/blob/develop/packages/wasm-api-bindgen/README.md#cli-generator)
    for the code generator(s)
@@ -83,40 +82,40 @@ following example provides a brief overview:
 import { IWasmAPI, WasmBridge } from "@thi.ng/wasm-api";
 
 export class CustomAPI implements IWasmAPI {
-	// Unique API module identifier to group WASM imports,
-	// must match ID used by native code (see further below).
-	readonly id = "custom";
-	// optionally list IDs of other API modules this module depends on
-	// these are used to infer the correct initialization order
-	readonly dependencies = [];
-
-	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();
-			}
-		};
-	}
+    // Unique API module identifier to group WASM imports,
+    // must match ID used by native code (see further below).
+    readonly id = "custom";
+    // optionally list IDs of other API modules this module depends on
+    // these are used to infer the correct initialization order
+    readonly dependencies = [];
+
+    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();
+            }
+        };
+    }
 }
 ```
 
@@ -151,16 +150,16 @@ const js = @import("wasmapi");
 const custom = @import("custom.zig");
 
 export fn test_randomVec4() void {
-	var foo = [4]f32{ 1, 2, 3, 4 };
+    var foo = [4]f32{ 1, 2, 3, 4 };
 
-	// print original
-	js.printF32Array(foo[0..]);
+    // print original
+    js.printF32Array(foo[0..]);
 
-	// populate foo with random numbers
-	custom.fillRandom(&foo, foo.len);
+    // populate foo with random numbers
+    custom.fillRandom(&foo, foo.len);
 
-	// print result
-	js.printF32Array(foo[0..]);
+    // print result
+    js.printF32Array(foo[0..]);
 }
 ```
 
@@ -190,6 +189,15 @@ and
 [`setString()`](https://docs.thi.ng/umbrella/wasm-api/classes/WasmBridge.html#setString)
 for details.
 
+Furthermore, the package provides these string wrapper types:
+
+- [`WasmStringPtr`](https://docs.thi.ng/umbrella/wasm-api/classes/WasmStringPtr.html)
+- [`WasmStringSlice`](https://docs.thi.ng/umbrella/wasm-api/classes/WasmStringSlice.html)
+
+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
 
 If explicitly enabled on the WASM side, the `WasmBridge` includes support for
@@ -199,9 +207,9 @@ 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/lib.zig`](https://github.com/thi-ng/umbrella/blob/develop/packages/wasm-api/zig/lib.zig#L37-L71):
+- [`/zig/lib.zig`](https://github.com/thi-ng/umbrella/blob/develop/packages/wasm-api/zig/lib.zig#L34-L68):
   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#L20-L30):
+- [`/include/wasmapi.h`](https://github.com/thi-ng/umbrella/blob/develop/packages/wasm-api/include/wasmapi.h#L18-L28):
   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
@@ -217,22 +225,22 @@ for more details...
 
 ```ts
 try {
-	// allocate 256 bytes of memory for passing a string to WASM side
-	// the function returns a tuple of `[address, len]`
-	const [addr, len] = bridge.allocate(256);
+    // allocate 256 bytes of memory for passing a string to WASM side
+    // the function returns a tuple of `[address, len]`
+    const [addr, len] = bridge.allocate(256);
 
-	// write zero terminated string to reserved memory (max. `len` bytes)
-	// function returns number of bytes written (excl. sentinel)
-	const num = bridge.setString("hello WASM world!", addr, len, true);
+    // write zero terminated string to reserved memory (max. `len` bytes)
+    // function returns number of bytes written (excl. sentinel)
+    const num = bridge.setString("hello WASM world!", addr, len, true);
 
-	// call WASM function doing something w/ the string
-	bridge.exports.doSomethingWithString(addr, num);
+    // call WASM function doing something w/ the string
+    bridge.exports.doSomethingWithString(addr, num);
 
-	// cleanup
-	bridge.free([addr, len]);
+    // cleanup
+    bridge.free([addr, len]);
 } catch(e) {
-	// deal with allocation error
-	// ...
+    // deal with allocation error
+    // ...
 }
 ```
 
@@ -288,8 +296,8 @@ Since v0.15.0, the supplied Zig core bindings lib also includes a
 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/)
 &
-[@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.
+[@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.
 
 ## Status
 
@@ -364,21 +372,21 @@ import { readFileSync } from "fs";
 
 // WASM exports from our dummy module (below)
 interface App extends WasmExports {
-	start: () => void;
+    start: () => void;
 }
 
 (async () => {
-	// new API bridge with defaults
-	// (i.e. no child API modules and using console logger)
-	const bridge = new WasmBridge<App>();
+    // new API bridge with defaults
+    // (i.e. no child API modules and using console logger)
+    const bridge = new WasmBridge<App>();
 
-	// instantiate WASM module using imports provided by the bridge
-	// this also initializes any bindings & bridge child APIs (if any)
-	// (also accepts a fetch() `Response` as input)
-	await bridge.instantiate(readFileSync("hello.wasm"));
+    // instantiate WASM module using imports provided by the bridge
+    // this also initializes any bindings & bridge child APIs (if any)
+    // (also accepts a fetch() `Response` as input)
+    await bridge.instantiate(readFileSync("hello.wasm"));
 
-	// call an exported WASM function
-	bridge.exports.start();
+    // call an exported WASM function
+    bridge.exports.start();
 })();
 ```
 
@@ -386,19 +394,15 @@ interface App extends WasmExports {
 
 Requires [Zig](https://ziglang.org) to be installed:
 
-```zig
+```zig tangle:export/hello.zig
 //! Example Zig application (hello.zig)
 
 /// import externals
 /// see build command for configuration
 const js = @import("wasmapi");
-const std = @import("std");
-
-// set custom memory allocator (here to disable)
-pub const WASM_ALLOCATOR: ?std.mem.Allocator = null;
 
 export fn start() void {
-	js.printStr("hello world!");
+    js.printStr("hello world!");
 }
 ```
 
@@ -409,10 +413,10 @@ folder):
 ```bash
 # compile WASM binary
 zig build-lib \
-	--pkg-begin wasmapi node_modules/@thi.ng/wasm-api/zig/lib.zig --pkg-end \
-	-target wasm32-freestanding \
-	-O ReleaseSmall -dynamic --strip \
-	hello.zig
+    --pkg-begin wasmapi node_modules/@thi.ng/wasm-api/zig/lib.zig --pkg-end \
+    -target wasm32-freestanding \
+    -O ReleaseSmall -dynamic \
+    hello.zig
 
 # disassemble WASM
 wasm-dis -o hello.wast hello.wasm
@@ -451,11 +455,11 @@ The resulting WASM:
 
 Requires [Emscripten](https://emscripten.org/) to be installed:
 
-```c
+```c tangle:export/hello.c
 #include <wasmapi.h>
 
-void WASM_KEEP start() {
-	wasm_printStr0("hello world!");
+void WASMAPI_KEEP start() {
+    wasm_printStrZ("hello world!");
 }
 ```
 
@@ -467,73 +471,6 @@ emcc -Os -Inode_modules/@thi.ng/wasm-api/include \
   -o hello.wasm hello.c
 ```
 
-Resulting WASM:
-
-```wasm
-(module
- (type $i32_=>_none (func (param i32)))
- (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)
- (data (i32.const 1024) "hello world!")
- (table $0 2 2 funcref)
- (elem (i32.const 1) $0)
- (export "memory" (memory $0))
- (export "_wasm_allocate" (func $1))
- (export "_wasm_free" (func $2))
- (export "start" (func $3))
- (export "__indirect_function_table" (table $0))
- (export "_initialize" (func $0))
- (export "__errno_location" (func $7))
- (export "stackSave" (func $4))
- (export "stackRestore" (func $5))
- (export "stackAlloc" (func $6))
- (func $0
-  (nop)
- )
- (func $1 (param $0 i32) (result i32)
-  (i32.const 0)
- )
- (func $2 (param $0 i32) (param $1 i32)
-  (nop)
- )
- (func $3
-  (call $fimport$0
-   (i32.const 1024)
-  )
- )
- (func $4 (result i32)
-  (global.get $global$0)
- )
- (func $5 (param $0 i32)
-  (global.set $global$0
-   (local.get $0)
-  )
- )
- (func $6 (param $0 i32) (result i32)
-  (global.set $global$0
-   (local.tee $0
-    (i32.and
-     (i32.sub
-      (global.get $global$0)
-      (local.get $0)
-     )
-     (i32.const -16)
-    )
-   )
-  )
-  (local.get $0)
- )
- (func $7 (result i32)
-  (i32.const 1040)
- )
-)
-```
-
 ## Authors
 
 Karsten Schmidt

package/include/wasmapi.h

@@ -1,7 +1,5 @@
 #pragma once
 
-#include "wasmapi_types.h"
-
 #ifdef __cplusplus
 extern "C" {
 #endif

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/wasm-api",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Generic, modular, extensible API bridge and infrastructure for hybrid JS & WebAssembly projects",
   "type": "module",
   "module": "./index.js",
@@ -110,5 +110,5 @@
     "status": "alpha",
     "year": 2022
   },
-  "gitHead": "044ee6a3895720fc78e115032d4d831b63510929\n"
+  "gitHead": "8d59e559a576ecb3d2c2d13edf5c3146df95d6ac\n"
 }

package/zig/lib.zig

@@ -2,9 +2,6 @@
 
 const std = @import("std");
 const root = @import("root");
-const types = @import("types.zig");
-
-pub usingnamespace types;
 
 pub const ManagedIndex = @import("managed-index.zig").ManagedIndex;
 

package/include/wasmapi_types.h

@@ -1,35 +0,0 @@
-#pragma once
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-#include <stddef.h>
-
-typedef char* WASM_StringPtr;
-typedef const char* WASM_ConstStringPtr;
-
-typedef void* WASM_OpaquePtr;
-typedef const void* WASM_ConstOpaquePtr;
-
-// slice-based string
-typedef struct { WASM_StringPtr ptr; size_t len; } WASM_String;
-typedef struct { WASM_ConstStringPtr ptr; size_t len; } WASM_ConstString;
-
-// defines slice wrapper structs for given pointer types
-#define WASMAPI_SLICE(PREFIX, NAME, PTR, CONSTPTR) \
-  typedef struct { PTR* ptr; size_t len;  } PREFIX##NAME##Slice; \
-  typedef struct { CONSTPTR* ptr; size_t len; } PREFIX##Const##NAME##Slice;
-
-// slice of string slices
-WASMAPI_SLICE(WASM_, String, WASM_String, WASM_ConstString)
-
-// slice of string pointers
-WASMAPI_SLICE(WASM_, StringPtr, WASM_StringPtr, WASM_ConstStringPtr)
-
-// slice of opaque pointers
-WASMAPI_SLICE(WASM_, OpaquePtr, WASM_OpaquePtr, WASM_ConstOpaquePtr)
-
-#ifdef __cplusplus
-}
-#endif

package/zig/types.zig

@@ -1,52 +0,0 @@
-//! Common helper types used by the thi.ng/wasm-api code gen
-//! None of these type have any further dependencies on the main wasm-api package
-
-/// Higher-order generic slice wrapper for `extern struct` use cases
-/// S = slice type
-/// P = pointer type
-pub fn Slice(comptime S: type, comptime P: type) type {
-    return extern struct {
-        ptr: P = @as(S, &.{}).ptr,
-        len: usize = 0,
-
-        pub inline fn wrap(slice: S) @This() {
-            return .{
-                .ptr = @ptrCast(P, slice.ptr),
-                .len = slice.len,
-            };
-        }
-
-        pub inline fn toSlice(self: *@This()) S {
-            return @ptrCast(*S, self).*;
-        }
-    };
-}
-
-pub const StringPtr = [*:0]u8;
-pub const ConstStringPtr = [*:0]const u8;
-
-/// `[]u8` slice wrapper for `extern struct` use cases
-pub const String = Slice([]u8, StringPtr);
-/// `[]const u8` slice wrapper for `extern struct` use cases
-pub const ConstString = Slice([]const u8, ConstStringPtr);
-
-/// Slice of `String`s
-pub const StringSlice = Slice([]String, [*]String);
-pub const ConstStringSlice = Slice([]ConstString, [*]ConstString);
-
-/// Slice of `StringPtr`s
-pub const StringPtrSlice = Slice([]StringPtr, [*]StringPtr);
-pub const ConstStringPtrSlice = Slice([]ConstStringPtr, [*]ConstStringPtr);
-
-/// Alias for `*anyopaque`
-pub const OpaquePtr = *anyopaque;
-pub const ConstOpaquePtr = *const anyopaque;
-
-/// Slice of `OpaquePtr`s
-pub const OpaquePtrSlice = Slice([]OpaquePtr, [*]OpaquePtr);
-pub const ConstOpaquePtrSlice = Slice([]ConstOpaquePtr, [*]ConstOpaquePtr);
-
-/// Syntax sugar for `ConstString.wrap()`
-pub inline fn string(str: []const u8) ConstString {
-    return ConstString.wrap(str);
-}