@thi.ng/wasm-api 2.4.22 → 2.4.23
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +48 -47
- package/api.d.ts +1 -1
- package/package.json +10 -10
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
<!-- This file is generated - DO NOT EDIT! -->
|
|
2
|
-
<!-- Please see: https://
|
|
3
|
-
# 
|
|
4
4
|
|
|
5
5
|
[](https://www.npmjs.com/package/@thi.ng/wasm-api)
|
|
6
6
|
|
|
@@ -8,11 +8,12 @@
|
|
|
8
8
|
|
|
9
9
|
> [!NOTE]
|
|
10
10
|
> This is one of 214 standalone projects, maintained as part
|
|
11
|
-
> of the [@thi.ng/umbrella](https://
|
|
11
|
+
> of the [@thi.ng/umbrella](https://codeberg.org/thi.ng/umbrella/) ecosystem
|
|
12
12
|
> and anti-framework.
|
|
13
13
|
>
|
|
14
|
-
> 🚀 Please help me to work full-time on these projects by [sponsoring
|
|
15
|
-
>
|
|
14
|
+
> 🚀 Please help me to work full-time on these projects by [sponsoring
|
|
15
|
+
> me](https://codeberg.org/thi.ng/umbrella/src/branch/develop/CONTRIBUTING.md#donations).
|
|
16
|
+
> Thank you! ❤️
|
|
16
17
|
|
|
17
18
|
- [About](#about)
|
|
18
19
|
- [Polyglot bindings generator](#polyglot-bindings-generator)
|
|
@@ -44,7 +45,7 @@ Generic, modular, extensible API bridge and infrastructure for hybrid JS & WebAs
|
|
|
44
45
|
|
|
45
46
|
| Quasiflock | Danza | S-TRACE | Voxelscape |
|
|
46
47
|
|---------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
|
47
|
-
| <a href="https://www.fxhash.xyz/generative/6671"><img src="https://
|
|
48
|
+
| <a href="https://www.fxhash.xyz/generative/6671"><img src="https://codeberg.org/thi.ng/umbrella/media/branch/develop/assets/fxhash/quasiflock-240.jpg"/></a> | <a href="https://mastodon.thi.ng/@toxi/tagged/DANZA"><img src="https://codeberg.org/thi.ng/umbrella/media/branch/develop/assets/fxhash/danza-240.jpg"/></a> | <a href="https://mastodon.thi.ng/@toxi/tagged/STRACE"><img src="https://codeberg.org/thi.ng/umbrella/media/branch/develop/assets/fxhash/s-trace-240.jpg"/></a> | <a href="https://twitter.com/search?q=from%3A%40toxi+voxel+ziglang"><img src="https://codeberg.org/thi.ng/umbrella/media/branch/develop/assets/fxhash/voxelscape-240.jpg"/></a> |
|
|
48
49
|
|
|
49
50
|
(Screenshots of selected projects made with Zig & TypeScript using the interop features provided by this package. Images link to respective project info)
|
|
50
51
|
|
|
@@ -60,16 +61,16 @@ JS/WebAssembly applications.
|
|
|
60
61
|
3. A minimal core API for debug output, string/pointer/typedarray accessors for
|
|
61
62
|
8/16/32/64 bit (u)ints and 32/64 bit floats. Additionally, a number of support
|
|
62
63
|
modules for [DOM
|
|
63
|
-
manipulation](https://
|
|
64
|
+
manipulation](https://codeberg.org/thi.ng/umbrella/src/branch/develop/packages/wasm-api-dom/),
|
|
64
65
|
[scheduled function
|
|
65
|
-
execution](https://
|
|
66
|
+
execution](https://codeberg.org/thi.ng/umbrella/src/branch/develop/packages/wasm-api-schedule/),
|
|
66
67
|
WebGL, WebGPU, WebAudio etc. is being actively worked on.
|
|
67
68
|
4. Different types of memory-mapped (UTF-8) string abstractions (slice or pointer based)
|
|
68
69
|
5. Shared (opt-in) memory allocation mechanism, also accessible from JS/TS side
|
|
69
70
|
6. Include files for
|
|
70
|
-
[Zig](https://
|
|
71
|
+
[Zig](https://codeberg.org/thi.ng/umbrella/src/branch/develop/packages/wasm-api/zig),
|
|
71
72
|
and
|
|
72
|
-
[C/C++](https://
|
|
73
|
+
[C/C++](https://codeberg.org/thi.ng/umbrella/src/branch/develop/packages/wasm-api/include)
|
|
73
74
|
defining glue code for the TypeScript [core
|
|
74
75
|
API](https://docs.thi.ng/umbrella/wasm-api/interfaces/CoreAPI.html) defined
|
|
75
76
|
by this package
|
|
@@ -79,13 +80,13 @@ WebGL, WebGPU, WebAudio etc. is being actively worked on.
|
|
|
79
80
|
## Polyglot bindings generator
|
|
80
81
|
|
|
81
82
|
The toolkit includes an extensible [code
|
|
82
|
-
generator](https://
|
|
83
|
+
generator](https://codeberg.org/thi.ng/umbrella/src/branch/develop/packages/wasm-api-bindgen/)
|
|
83
84
|
for shared datatypes and (currently) supports Zig & TypeScript and C11. For TS
|
|
84
85
|
fully type checked and memory-mapped (mostly zero-copy) accessors of WASM-side
|
|
85
86
|
data are generated. In principle, all languages with a WASM target are
|
|
86
87
|
supported, however currently only bindings for the languages mentioned are
|
|
87
88
|
included. The codegen also includes a [CLI
|
|
88
|
-
frontend/utility](https://
|
|
89
|
+
frontend/utility](https://codeberg.org/thi.ng/umbrella/src/branch/develop/packages/wasm-api-bindgen/README.md#cli-generator).
|
|
89
90
|
|
|
90
91
|
## Custom API modules
|
|
91
92
|
|
|
@@ -95,7 +96,7 @@ can be extented via custom defined API modules. Such child modules will consist
|
|
|
95
96
|
of a collection of JS/TS functions & variables, their related counterparts
|
|
96
97
|
(import definitions) for the WASM target and (optionally) some shared data types
|
|
97
98
|
([bindings for which can be generated via
|
|
98
|
-
thi.ng/wasm-api-bindgen](https://
|
|
99
|
+
thi.ng/wasm-api-bindgen](https://codeberg.org/thi.ng/umbrella/src/branch/develop/packages/wasm-api-bindgen)).
|
|
99
100
|
|
|
100
101
|
On the JS side, custom API extensions can be easily integrated and exposed via
|
|
101
102
|
the [`IWasmAPI`
|
|
@@ -246,7 +247,7 @@ Furthermore, the package provides these string wrapper types:
|
|
|
246
247
|
- [`WasmStringSlice`](https://docs.thi.ng/umbrella/wasm-api/classes/WasmStringSlice.html)
|
|
247
248
|
|
|
248
249
|
Finally, see more information in the
|
|
249
|
-
[@thi.ng/wasm-api-bindgen](https://
|
|
250
|
+
[@thi.ng/wasm-api-bindgen](https://codeberg.org/thi.ng/umbrella/src/branch/develop/packages/wasm-api-bindgen/README.md#string-handling)
|
|
250
251
|
package readme.
|
|
251
252
|
|
|
252
253
|
## Memory allocations
|
|
@@ -258,9 +259,9 @@ The actual allocator is implementation specific and suitable generic mechanisms
|
|
|
258
259
|
are defined for both the included Zig & C bindings. Please see for further
|
|
259
260
|
reference:
|
|
260
261
|
|
|
261
|
-
- [`/zig/lib.zig`](https://
|
|
262
|
+
- [`/zig/lib.zig`](https://codeberg.org/thi.ng/umbrella/src/branch/develop/packages/wasm-api/zig/lib.zig#L34-L68):
|
|
262
263
|
comments about WASM-side allocator handling in Zig
|
|
263
|
-
- [`/include/wasmapi.h`](https://
|
|
264
|
+
- [`/include/wasmapi.h`](https://codeberg.org/thi.ng/umbrella/src/branch/develop/packages/wasm-api/include/wasmapi.h#L18-L28):
|
|
264
265
|
comments about WASM-side allocator handling in C/C++
|
|
265
266
|
- [`WasmBridge.allocate()`](https://docs.thi.ng/umbrella/wasm-api/classes/WasmBridge.html#allocate):
|
|
266
267
|
allocating memory from JS side
|
|
@@ -271,7 +272,7 @@ Note: The provided Zig library supports the idiomatic (Zig) pattern of working
|
|
|
271
272
|
with multiple allocators in different parts of the application and supports
|
|
272
273
|
dynamic assignments/swapping of the exposed allocator. See comments in source
|
|
273
274
|
file and
|
|
274
|
-
[tests](https://
|
|
275
|
+
[tests](https://codeberg.org/thi.ng/umbrella/src/branch/develop/packages/wasm-api/test)
|
|
275
276
|
for more details...
|
|
276
277
|
|
|
277
278
|
```ts
|
|
@@ -300,8 +301,8 @@ try {
|
|
|
300
301
|
### API module auto-initialization
|
|
301
302
|
|
|
302
303
|
The supplied child APIs
|
|
303
|
-
([wasm-api-dom](https://
|
|
304
|
-
[wasm-api-schedule](https://
|
|
304
|
+
([wasm-api-dom](https://codeberg.org/thi.ng/umbrella/src/branch/develop/packages/wasm-api-dom),
|
|
305
|
+
[wasm-api-schedule](https://codeberg.org/thi.ng/umbrella/src/branch/develop/packages/wasm-api-schedule)
|
|
305
306
|
etc.) use an auto-intialization hook related to the above `WASM_ALLOCATOR`
|
|
306
307
|
mechanism: If that allocator is available, the WASM side of these modules will
|
|
307
308
|
auto initialize and thus reduce boilerplate. However, if no such central
|
|
@@ -316,7 +317,7 @@ be managed manually in JS. For this purpose the [`ObjectIndex`
|
|
|
316
317
|
class](https://docs.thi.ng/umbrella/wasm-api/classes/ObjectIndex.html) can be
|
|
317
318
|
used by API modules to handle the indexing of different types of JS
|
|
318
319
|
objects/values and their ID generation (incl. recycling of IDs, using
|
|
319
|
-
[@thi.ng/idgen](https://
|
|
320
|
+
[@thi.ng/idgen](https://codeberg.org/thi.ng/umbrella/src/branch/develop/packages/idgen)).
|
|
320
321
|
Using this approach, only the numeric IDs (handles) will then need to be
|
|
321
322
|
exchanged with the WASM module...
|
|
322
323
|
|
|
@@ -365,12 +366,12 @@ canvases.delete(0);
|
|
|
365
366
|
```
|
|
366
367
|
|
|
367
368
|
The supplied Zig core library also includes a
|
|
368
|
-
[`ManagedIndex`](https://
|
|
369
|
+
[`ManagedIndex`](https://codeberg.org/thi.ng/umbrella/src/branch/develop/packages/wasm-api/zig/managed-index.zig)
|
|
369
370
|
for similar resource management on the Zig side of the application. For example,
|
|
370
371
|
in the
|
|
371
|
-
[@thi.ng/wasm-api-dom](https://
|
|
372
|
+
[@thi.ng/wasm-api-dom](https://codeberg.org/thi.ng/umbrella/src/branch/develop/packages/wasm-api-dom/)
|
|
372
373
|
&
|
|
373
|
-
[@thi.ng/wasm-api-schedule](https://
|
|
374
|
+
[@thi.ng/wasm-api-schedule](https://codeberg.org/thi.ng/umbrella/src/branch/develop/packages/wasm-api-schedule/)
|
|
374
375
|
packages this is used to manage Zig-side event listeners.
|
|
375
376
|
|
|
376
377
|
## Using the Zig build system
|
|
@@ -385,7 +386,7 @@ built-in build system is as simple as:
|
|
|
385
386
|
versions, older Zig versions than
|
|
386
387
|
[v0.15.1](https://ziglang.org/download/0.15.1/release-notes.html), are not
|
|
387
388
|
actively supported anymore (however, [build files for older versions are still
|
|
388
|
-
included](https://
|
|
389
|
+
included](https://codeberg.org/thi.ng/umbrella/src/branch/develop/packages/wasm-api/zig)).
|
|
389
390
|
|
|
390
391
|
Please see [bundled examples](#usage-examples) for more details...
|
|
391
392
|
|
|
@@ -420,27 +421,27 @@ pub fn build(b: *std.Build) void {
|
|
|
420
421
|
All bundled example projects (see [list below](#usage-examples)) are being built
|
|
421
422
|
via this script. **More details/options in the commented source code:**
|
|
422
423
|
|
|
423
|
-
- [`/zig/build.zig`](https://
|
|
424
|
+
- [`/zig/build.zig`](https://codeberg.org/thi.ng/umbrella/src/branch/develop/packages/wasm-api/zig/build.zig)
|
|
424
425
|
|
|
425
426
|
## Naming & structural conventions
|
|
426
427
|
|
|
427
428
|
To avoid guesswork about the internals of any of the supplied WASM API modules,
|
|
428
429
|
please also consult the information in
|
|
429
|
-
[#368](https://
|
|
430
|
+
[#368](https://codeberg.org/thi.ng/umbrella/issues/368).
|
|
430
431
|
|
|
431
432
|
## Status
|
|
432
433
|
|
|
433
434
|
**ALPHA** - bleeding edge / work-in-progress
|
|
434
435
|
|
|
435
|
-
[Search or submit any issues for this package](https://
|
|
436
|
+
[Search or submit any issues for this package](https://codeberg.org/thi.ng/umbrella/issues?q=%5Bwasm-api%5D)
|
|
436
437
|
|
|
437
438
|
## Support packages
|
|
438
439
|
|
|
439
|
-
- [@thi.ng/wasm-api-bindgen](https://
|
|
440
|
-
- [@thi.ng/wasm-api-canvas](https://
|
|
441
|
-
- [@thi.ng/wasm-api-dom](https://
|
|
442
|
-
- [@thi.ng/wasm-api-schedule](https://
|
|
443
|
-
- [@thi.ng/wasm-api-webgl](https://
|
|
440
|
+
- [@thi.ng/wasm-api-bindgen](https://codeberg.org/thi.ng/umbrella/src/branch/develop/packages/wasm-api-bindgen) - Polyglot bindings code generators (TS/JS, Zig, C11) for hybrid WebAssembly projects
|
|
441
|
+
- [@thi.ng/wasm-api-canvas](https://codeberg.org/thi.ng/umbrella/src/branch/develop/packages/wasm-api-canvas) - HTML Canvas2D bridge API for hybrid TypeScript & WASM (Zig) applications
|
|
442
|
+
- [@thi.ng/wasm-api-dom](https://codeberg.org/thi.ng/umbrella/src/branch/develop/packages/wasm-api-dom) - Browser DOM bridge API for hybrid TypeScript & WASM (Zig) applications
|
|
443
|
+
- [@thi.ng/wasm-api-schedule](https://codeberg.org/thi.ng/umbrella/src/branch/develop/packages/wasm-api-schedule) - Delayed & scheduled function execution (via setTimeout() etc.) for hybrid WASM apps
|
|
444
|
+
- [@thi.ng/wasm-api-webgl](https://codeberg.org/thi.ng/umbrella/src/branch/develop/packages/wasm-api-webgl) - WebGL bridge API for hybrid TypeScript & WASM (Zig) applications
|
|
444
445
|
|
|
445
446
|
### Third party modules
|
|
446
447
|
|
|
@@ -470,29 +471,29 @@ Package sizes (brotli'd, pre-treeshake): ESM: 3.13 KB
|
|
|
470
471
|
|
|
471
472
|
## Dependencies
|
|
472
473
|
|
|
473
|
-
- [@thi.ng/api](https://
|
|
474
|
-
- [@thi.ng/arrays](https://
|
|
475
|
-
- [@thi.ng/checks](https://
|
|
476
|
-
- [@thi.ng/errors](https://
|
|
477
|
-
- [@thi.ng/hex](https://
|
|
478
|
-
- [@thi.ng/idgen](https://
|
|
479
|
-
- [@thi.ng/logger](https://
|
|
474
|
+
- [@thi.ng/api](https://codeberg.org/thi.ng/umbrella/src/branch/develop/packages/api)
|
|
475
|
+
- [@thi.ng/arrays](https://codeberg.org/thi.ng/umbrella/src/branch/develop/packages/arrays)
|
|
476
|
+
- [@thi.ng/checks](https://codeberg.org/thi.ng/umbrella/src/branch/develop/packages/checks)
|
|
477
|
+
- [@thi.ng/errors](https://codeberg.org/thi.ng/umbrella/src/branch/develop/packages/errors)
|
|
478
|
+
- [@thi.ng/hex](https://codeberg.org/thi.ng/umbrella/src/branch/develop/packages/hex)
|
|
479
|
+
- [@thi.ng/idgen](https://codeberg.org/thi.ng/umbrella/src/branch/develop/packages/idgen)
|
|
480
|
+
- [@thi.ng/logger](https://codeberg.org/thi.ng/umbrella/src/branch/develop/packages/logger)
|
|
480
481
|
|
|
481
482
|
Note: @thi.ng/api is in _most_ cases a type-only import (not used at runtime)
|
|
482
483
|
|
|
483
484
|
## Usage examples
|
|
484
485
|
|
|
485
486
|
Five projects in this repo's
|
|
486
|
-
[/examples](https://
|
|
487
|
+
[/examples](https://codeberg.org/thi.ng/umbrella/src/branch/develop/examples)
|
|
487
488
|
directory are using this package:
|
|
488
489
|
|
|
489
|
-
| Screenshot | Description | Live demo | Source
|
|
490
|
-
|
|
491
|
-
| <img src="https://
|
|
492
|
-
| <img src="https://
|
|
493
|
-
| <img src="https://
|
|
494
|
-
| <img src="https://
|
|
495
|
-
| <img src="https://
|
|
490
|
+
| Screenshot | Description | Live demo | Source |
|
|
491
|
+
|:---------------------------------------------------------------------------------------------------------------------|:-------------------------------------------------------------------|:----------------------------------------------------|:-----------------------------------------------------------------------------------------|
|
|
492
|
+
| <img src="https://codeberg.org/thi.ng/umbrella/media/branch/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://codeberg.org/thi.ng/umbrella/src/branch/develop/examples/zig-canvas) |
|
|
493
|
+
| <img src="https://codeberg.org/thi.ng/umbrella/media/branch/develop/assets/examples/zig-cellular.jpg" width="240"/> | Zig-based 2D multi-behavior cellular automata | [Demo](https://demo.thi.ng/umbrella/zig-cellular/) | [Source](https://codeberg.org/thi.ng/umbrella/src/branch/develop/examples/zig-cellular) |
|
|
494
|
+
| <img src="https://codeberg.org/thi.ng/umbrella/media/branch/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://codeberg.org/thi.ng/umbrella/src/branch/develop/examples/zig-counter) |
|
|
495
|
+
| <img src="https://codeberg.org/thi.ng/umbrella/media/branch/develop/assets/examples/zig-todo-list.png" width="240"/> | Zig-based To-Do list, DOM creation, local storage task persistence | [Demo](https://demo.thi.ng/umbrella/zig-todo-list/) | [Source](https://codeberg.org/thi.ng/umbrella/src/branch/develop/examples/zig-todo-list) |
|
|
496
|
+
| <img src="https://codeberg.org/thi.ng/umbrella/media/branch/develop/assets/examples/zig-webgl.avif" width="240"/> | Basic Zig/WebAssembly WebGL demo | [Demo](https://demo.thi.ng/umbrella/zig-webgl/) | [Source](https://codeberg.org/thi.ng/umbrella/src/branch/develop/examples/zig-webgl) |
|
|
496
497
|
|
|
497
498
|
## API
|
|
498
499
|
|
package/api.d.ts
CHANGED
|
@@ -251,7 +251,7 @@ export interface IWasmMemoryAccess {
|
|
|
251
251
|
*
|
|
252
252
|
* @remarks
|
|
253
253
|
* Zig API:
|
|
254
|
-
* https://
|
|
254
|
+
* https://codeberg.org/thi.ng/umbrella/src/branch/develop/packages/wasm-api/zig/lib.zig
|
|
255
255
|
*/
|
|
256
256
|
export interface CoreAPI extends WebAssembly.ModuleImports {
|
|
257
257
|
printI8: Fn<number, void>;
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@thi.ng/wasm-api",
|
|
3
|
-
"version": "2.4.
|
|
3
|
+
"version": "2.4.23",
|
|
4
4
|
"description": "Generic, modular, extensible API bridge and infrastructure for hybrid JS & WebAssembly projects",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"module": "./index.js",
|
|
@@ -8,7 +8,7 @@
|
|
|
8
8
|
"sideEffects": false,
|
|
9
9
|
"repository": {
|
|
10
10
|
"type": "git",
|
|
11
|
-
"url": "git+https://
|
|
11
|
+
"url": "git+https://codeberg.org/thi.ng/umbrella.git",
|
|
12
12
|
"directory": "packages/wasm-api"
|
|
13
13
|
},
|
|
14
14
|
"homepage": "https://thi.ng/wasm-api",
|
|
@@ -43,13 +43,13 @@
|
|
|
43
43
|
"tool:tangle": "../../node_modules/.bin/tangle src/**/*.ts"
|
|
44
44
|
},
|
|
45
45
|
"dependencies": {
|
|
46
|
-
"@thi.ng/api": "^8.12.
|
|
47
|
-
"@thi.ng/arrays": "^2.14.
|
|
48
|
-
"@thi.ng/checks": "^3.8.
|
|
49
|
-
"@thi.ng/errors": "^2.6.
|
|
50
|
-
"@thi.ng/hex": "^2.4.
|
|
51
|
-
"@thi.ng/idgen": "^2.2.
|
|
52
|
-
"@thi.ng/logger": "^3.3.
|
|
46
|
+
"@thi.ng/api": "^8.12.18",
|
|
47
|
+
"@thi.ng/arrays": "^2.14.14",
|
|
48
|
+
"@thi.ng/checks": "^3.8.8",
|
|
49
|
+
"@thi.ng/errors": "^2.6.7",
|
|
50
|
+
"@thi.ng/hex": "^2.4.10",
|
|
51
|
+
"@thi.ng/idgen": "^2.2.92",
|
|
52
|
+
"@thi.ng/logger": "^3.3.1"
|
|
53
53
|
},
|
|
54
54
|
"devDependencies": {
|
|
55
55
|
"esbuild": "^0.27.2",
|
|
@@ -127,5 +127,5 @@
|
|
|
127
127
|
"tag": "wasm",
|
|
128
128
|
"year": 2022
|
|
129
129
|
},
|
|
130
|
-
"gitHead": "
|
|
130
|
+
"gitHead": "8ddf86ea0a1e658ddbf19cc645b29d0c176e29c4\n"
|
|
131
131
|
}
|