diff --git a/README.md b/README.md index 8704600..801e07f 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ WebAssembly and SharedArrayBuffer IO. Pronounced "wassabee-yo". -## purpose +## Purpose `wasabio` offers several utility APIs with familiar interfaces, but implemented to work over a single SharedArrayBuffer and inside a TS-wrapped WASM module. @@ -12,7 +12,90 @@ browsers, enabling safe cross-worker communication and shared state. Currently `wasabio` provides: -- Node's FS API (implemented on top of an in-memory POSIX filesystem) +- Node's FileSystem API (implemented on top of an in-memory POSIX filesystem) - LocalStorage API (implemented on top of an in-memory key-value store) - Node's EventEmitter API (implemented on top of a SharedArrayBuffer) -- Low level Locks, Buses, and various other utilities +- Low level Locks, Buses, Channels, and various other utilities + +## Usage + +### API + +All APIs are spec-compatible with their original counterparts. + +> **note:** library needs to be initialized before use, see below. + +```typescript +import { + localStorage, // in-memory key-value store for cross worker state storage + EventEmitter, // lets you make named emitter for cross worker communication + readFile, + writeFile, + appendFile, + readFileSync, + writeFileSync, + appendFileSync, + // ... Node FS api +} from "wasabio"; +``` + +Some utility functions are also provided: + +```typescript +// return true if library is initialized +available(): boolean; +// serializes memory to a buffer, sets the thread counter to 0 +serialize(memory: WebAssembly.Memory): Uint8Array; +// deserializes buffer to memory, sets the correct buffer size +deserialize(buffer: Uint8Array): WebAssembly.Memory; +``` + +### Initialization + +#### From New Memory + +Initialize `wasabio` on the first thread (usually the main thread) like so: + +```typescript +// main.ts +import { initialize } from "wasabio"; +const mem = await initialize(); +// some time later +worker.postMessage(mem); +``` + +On other threads (workers, frames, etc.) initialize `wasabio` like so: + +```typescript +// worker.ts +import { initialize } from "wasabio"; +addEventListener("message", async ({ data }) => { + initialize(data, { sync: true }); // sync as an option +}); +``` + +#### From Existing Memory + +Initialize `wasabio` on the first thread (usually the main thread) like so: + +```typescript +// main.ts +import { initialize } from "wasabio"; +const cold = getSharedArrayBufferFromSomewhere(); +const hot = await initialize(cold, { reboot: true }); +// some time later +worker.postMessage(hot); +``` + +On other threads (workers, frames, etc.) initialize `wasabio` like so: + +```typescript +// worker.ts +import { initialize } from "wasabio"; +addEventListener("message", async ({ data }) => { + initialize(data, { reboot: false }); +}); +``` + +In this case, `reboot` signifies that the library is being initialized from cold +storage and thread-local state should be reset.