beamdb 0.10.0 → 0.17.0

package/README.md

@@ -23,6 +23,7 @@
 - [Wire Protocol](#wire-protocol)
 - [Configuration](#configuration)
 - [Testing](#testing)
+- [Benchmarks](#benchmarks)
 - [Features](#features)
 - [Security](#security)
 - [Contributing](#contributing)
@@ -45,7 +46,7 @@ BEAM is a maintained fork of [rod](https://github.com/mmalmi/rod) — a from-scr
 - **Real-time** — `on()` subscriptions deliver updates as they propagate through the mesh
 - **Eventually consistent** — last-write-wins conflict resolution via timestamps (matching Gun.js)
 - **Encrypted** — SEA layer provides Ed25519 signing, X25519 ECDH, and AES-256-GCM encryption
-- **Persistent** — `redb` embedded database for disk-backed storage, or `Persy` for high-concurrency workloads, or in-memory for ephemeral use
+- **Persistent** — `redb` embedded database (default), `fjall` LSM-tree (recommended for multi-node), `Persy` for high-concurrency, or in-memory for ephemeral use
 - **Multi-transport** — WebSocket (relay), UDP multicast (LAN discovery), WebRTC (direct P2P)
 - **Browser-ready** — compiles to WebAssembly via `wasm-pack`; same engine, same wire protocol, IndexedDB persistence
 
@@ -55,7 +56,7 @@ BEAM is a maintained fork of [rod](https://github.com/mmalmi/rod) — a from-scr
 
 ```toml
 [dependencies]
-beamdb = "0.8"
+beamdb = "0.16"
 ```
 
 Or via the CLI:
@@ -64,14 +65,17 @@ Or via the CLI:
 cargo add beamdb
 ```
 
-Feature flags (both off by default):
+Feature flags (all off by default):
 
 ```toml
 # WebRTC direct P2P support
-beamdb = { version = "0.8", features = ["webrtc"] }
+beamdb = { version = "0.16", features = ["webrtc"] }
+
+# Fjall LSM-tree storage backend (recommended for multi-node deployments)
+beamdb = { version = "0.16", features = ["fjall"] }
 
 # Persy storage backend (for high-concurrency workloads)
-beamdb = { version = "0.8", features = ["persy"] }
+beamdb = { version = "0.16", features = ["persy"] }
 ```
 
 ---
@@ -111,7 +115,8 @@ await init();
 
 // Create a BEAM node
 const beam = new Beam();                        // in-memory (lost on reload)
-// or: const beam = Beam.new_persistent();   // IndexedDB (survives reload)
+// or: const beam = Beam.new_persistent();      // IndexedDB (survives reload)
+// or: const beam = Beam.new_with_opfs();       // OPFS (survives reload, faster)
 
 // Connect to a relay server
 beam.connect("wss://relay.example.com/ws");
@@ -222,17 +227,26 @@ compatible WebSocket peer.
 | Backend | Persistent | Browser API | Use Case |
 |---------|-----------|-------------|----------|
 | `MemoryStorage` | No (lost on reload) | Default | Ephemeral data, testing |
-| `WasmIdbStorage` | Yes (IndexedDB) | Opt-in | Production browser apps |
+| `WasmIdbStorage` | Yes (IndexedDB) | Opt-in via `new_persistent()` | Production browser apps |
+| `WasmOpfsStorage` | Yes (OPFS) | Opt-in via `new_with_opfs()` | Modern browsers (Chrome 102+, Firefox 111+, Safari 15.2+) |
+| `WasmNodeFsStorage` | Yes (Node.js fs) | Node.js only (`--features node-fs`) | Server-side WASM, Electron |
 
-`WasmIdbStorage` uses a write-through cache: writes go to an in-memory `HashMap`
+**WasmIdbStorage** uses a write-through cache: writes go to an in-memory `HashMap`
 (fast reads) and are simultaneously written through to IndexedDB (persistence).
+Data is serialized as postcard bytes (base64-encoded for IDB string storage),
+with automatic JSON fallback for backward compatibility with pre-v0.17 databases.
 On page reload, data is read back from IndexedDB into the cache.
 
+**WasmOpfsStorage** uses the Origin Private File System for file-based persistence.
+Data is stored as postcard-serialized binary files in OPFS, offering better
+performance than IndexedDB for larger datasets. Requires a secure context
+(HTTPS or localhost).
+
 ### Browser Constraints
 
 - **Single-threaded** — all async work runs on the browser's main thread
 - **Client-only** — connects to relays, does not accept inbound connections
-- **No file system** — uses IndexedDB instead of redb/Persy
+- **No native file system** — uses IndexedDB or OPFS instead of redb/Persy
 - **WebSocket only** — no UDP multicast or WebRTC (browser sandbox limitations)
 
 ### Interop with Gun.js
@@ -381,7 +395,8 @@ BEAM is built on an actor model with a central router. Every component — stora
                     │             │ │             │ │            │
                     │ MemoryStorage│ │ WsServer    │ │ WebRtcPeer │
                     │ RedbStorage │ │ WsClient    │ │ (str0m)    │
-                    │ PersyStorage│ │ Multicast   │ │            │
+                    │ FjallStorage│ │ Multicast   │ │            │
+                    │ PersyStorage│ │             │ │            │
                     └─────────────┘ └─────────────┘ └────────────┘
 ```
 
@@ -411,6 +426,7 @@ BEAM is built on an actor model with a central router. Every component — stora
 | `sea/session/` | Session persistence: `MemorySessionStorage` (ephemeral) and `EncryptedFileSessionStorage` (disk, AES-GCM) |
 | `adapters/memory_storage.rs` | In-memory `HashMap` storage (ephemeral, default for `Node::new()`) |
 | `adapters/redb_storage.rs` | Persistent storage via `redb` embedded database — `BatchPut` atomic transactions, flush ack |
+| `adapters/fjall_storage.rs` | Persistent storage via `fjall` LSM-tree database — WAL journalling, LZ4 compression, recommended for multi-node (feature-gated) |
 | `adapters/persy_storage.rs` | Persistent storage via `Persy` segment store — high-concurrency writes, optional `background_ops` |
 | `adapters/ws_server.rs` | WebSocket server: accepts inbound connections, spawns `WsConn` per connection, optional TLS, web UI on port+1 |
 | `adapters/ws_client.rs` | `OutgoingWebsocketManager` — connects to remote WebSocket peers with retry |
@@ -628,11 +644,11 @@ When `allow_public_space=false`, the node rejects unsigned puts to public space
 
 ## Storage Backends
 
-BEAM supports two persistent storage backends for the embedded database layer. Both implement the same `Storage` trait, so the rest of the codebase is unaware of which one is active. The wire protocol is backend-agnostic — nodes with different storage choices converge via the standard mesh.
+BEAM supports three persistent storage backends for the embedded database layer. All implement the same `Actor` trait, so the rest of the codebase is unaware of which one is active. The wire protocol is backend-agnostic — nodes with different storage choices converge via the standard mesh.
 
 ### redb (Default)
 
-**What**: Embedded ACID database, single-writer, fsync on every Put.
+**What**: Embedded ACID B+tree database, single-writer, fsync on every Put.
 
 **When to use**:
 - Single-node deployments
@@ -642,16 +658,45 @@ BEAM supports two persistent storage backends for the embedded database layer. B
 
 **Trade-offs**:
 - ✅ Battle-tested, single-crate, well-understood
-- ✅ fsync before ack = bulletproof durability
+- ✅ fsync before ack = bulletproof durability — data survives power loss
+- ✅ Best read performance (mmap'd B+tree = direct memory access)
 - ❌ Single-writer serialization limits concurrent write throughput
 - ❌ Not ideal for high-fanout mesh workloads
+- ❌ Every Put = fsync (milliseconds, blocking)
+
+### fjall (Recommended for Multi-Node)
+
+**What**: Embedded LSM-tree (RocksDB-like) database in 100% safe Rust. WAL journalling with background compaction and built-in LZ4 compression.
+
+**When to use**:
+- Multi-node P2P deployments with high write fanout
+- Workloads where peers flood puts during resync
+- You want maximum write throughput
+
+**Trade-offs**:
+- ✅ 3–4× faster writes than redb (journal append vs fsync per write)
+- ✅ Built-in LZ4 compression (free, SSTable-level)
+- ✅ WriteBatch — single journal entry for atomic multi-put
+- ✅ 100% safe Rust, no unsafe blocks
+- ❌ ~1.4× slower random reads than redb (multi-level LSM lookup vs B+tree)
+- ❌ Not fsync'd per write — data is crash-safe (WAL) but a power loss may lose recent un-fsync'd writes
+- ❌ Background compaction causes read latency variance
+
+**Durability model**: fjall's default matches RocksDB — writes are crash-safe via WAL (survive process crash), but not fsync'd to disk until explicit `persist()`. For a P2P database where peers hold copies of the data, this is the correct trade-off: if one node loses its WAL on power failure, peers resync it. `Flush` triggers `persist(SyncAll)` for full durability.
+
+**Benchmarks** (see [`bench/RESULTS.md`](bench/RESULTS.md)):
+
+| Benchmark | redb | fjall |
+|---|---|---|
+| write_storm (sequential) | ~977 elem/s | ~3,000 elem/s |
+| concurrent_write_storm (4 tasks) | ~1,195 elem/s | ~4,836 elem/s |
+| read_storm (random) | ~610 elem/s | ~447 elem/s |
 
 ### Persy (Opt-In)
 
 **What**: Embedded segment-based store with per-transaction isolation and optional `background_ops` fsync offloading.
 
 **When to use**:
-- Multi-node meshes with high concurrent write fanout
 - Workloads where many writers hit disjoint keys simultaneously
 - You're benchmarking and Persy shows wins on your data
 
@@ -659,41 +704,82 @@ BEAM supports two persistent storage backends for the embedded database layer. B
 - ✅ Multiple writers proceed in parallel on disjoint keys
 - ✅ Optional `background_ops` for fsync offloading
 - ❌ Younger ecosystem, fewer Stack Overflow answers
-- ❌ Requires more careful substrate reading when debugging
+- ❌ Author has acknowledged crash-safety issues; development has slowed
+- ❌ No WASM path (native-only)
 - ❌ Performance characteristics need your own benchmarks
 
+### Comparison Summary
+
+| | redb | fjall | Persy |
+|---|---|---|---|
+| **Structure** | B+tree | LSM-tree | Segment store |
+| **Write path** | fsync per Put | WAL journal append | Per-tx isolation |
+| **Durability** | Bulletproof (fsync) | Crash-safe (WAL), not power-safe | Per-tx |
+| **Read speed** | Fastest (mmap) | Slower (multi-level) | Moderate |
+| **Write speed** | Slowest (fsync) | Fastest (journal) | Moderate |
+| **Concurrency** | Single-writer | Multi-writer | Multi-writer |
+| **Compression** | None | LZ4 (free) | None |
+| **WASM** | No | No | No |
+| **Maturity** | Most mature | Active dev | Slowing dev |
+| **Best for** | Single-node | Multi-node P2P | High-concurrency |
+
 ### Selection
 
-Persy is a **build-time** feature, not a runtime flag. Build with `--features persy` to enable Persy support in the migration subcommand:
+Storage backends are **build-time** features, not runtime flags:
 
 ```bash
 # Default build — redb only
 cargo build --release --bin beam
 
-# With Persy support (enables migration subcommand)
+# With fjall support
+cargo build --release --bin beam --features fjall
+
+# With Persy and/or fjall support (enables migration subcommand)
 cargo build --release --bin beam --features persy
+cargo build --release --bin beam --features fjall
 
 # Run with redb (default)
-cargo run --release --bin beam -- --port 4944
+cargo run --release --bin beam -- start --port 4944
 
 # In-memory only (no persistence)
-cargo run --release --bin beam -- --port 4944 --memory-storage true
+cargo run --release --bin beam -- start --port 4944 --memory-storage true
+```
+
+**Library usage** — use any backend programmatically (requires corresponding feature flags):
+
+```rust,ignore
+use beam::adapters::{FjallStorage, RedbStorage, MemoryStorage};
+
+// fjall (recommended for multi-node, requires --features fjall)
+let storage = FjallStorage::new_with_config(Config::default(), "beam.fjall");
+
+// redb (default, best for single-node)
+let storage = RedbStorage::new_with_config(Config::default(), "beam.redb", None);
+
+// in-memory (ephemeral)
+let storage = MemoryStorage::new();
 ```
 
 ### Migration Between Backends
 
-The `beam migrate` subcommand converts between formats (requires `--features persy` for Persy support):
+The `beam migrate` subcommand converts between all supported storage formats (requires `--features persy` and/or `--features fjall`):
 
 ```bash
 # Preview without writing
 beam migrate --from redb --to persy --source ./data.redb --target ./data.persy --dry-run
 
-# Execute migration
+# redb ↔ persy
 beam migrate --from redb --to persy --source ./data.redb --target ./data.persy
-
-# Reverse direction
 beam migrate --from persy --to redb --source ./data.persy --target ./data.redb
 
+# redb ↔ fjall (fjall uses a directory path, not a file)
+beam migrate --from redb --to fjall --source ./data.redb --target ./data.fjall
+beam migrate --from fjall --to redb --source ./data.fjall --target ./data.redb
+
+# fjall ↔ persy
+beam migrate --from fjall --to persy --source ./data.fjall --target ./data.persy
+beam migrate --from persy --to fjall --source ./data.persy --target ./data.fjall
+
 # Overwrite existing target
 beam migrate --from redb --to persy --source ./data.redb --target ./data.persy --force
 
@@ -701,11 +787,11 @@ beam migrate --from redb --to persy --source ./data.redb --target ./data.persy -
 beam migrate --from redb --to persy --source ./data.redb --target ./data.persy --batch-size 5000
 ```
 
-Migration uses single-transaction-per-batch for safety and includes checksum verification. See `docs/migrations/migration-guide.md` for the full procedure including rollback.
+Migration uses a reader/writer architecture with a canonical intermediate format — each backend has one reader and one writer. Adding a new storage backend requires only two functions, not N² pairwise paths. See `docs/migrations/migration-guide.md` for the full procedure including rollback.
 
 ### Mixed Meshes
 
-Nodes with different storage backends interoperate transparently. A redb node, a Persy node, and an in-memory node form a valid mesh. The wire protocol carries the data; storage is a local choice.
+Nodes with different storage backends interoperate transparently. A redb node, a fjall node, a Persy node, and an in-memory node form a valid mesh. The wire protocol carries the data; storage is a local choice.
 
 **Cross-backend mesh verified** by `tests/cross_backend_mesh_e2e.rs`: 2 redb nodes + 1 Persy node converge correctly under the standard Put/Get protocol.
 
@@ -713,6 +799,7 @@ Nodes with different storage backends interoperate transparently. A redb node, a
 
 - The `beam_meta_v1` metadata table from redb (last-write timestamps) is not preserved when migrating redb → Persy. This metadata is not currently used by the actor framework, so the loss is cosmetic.
 - The migration tool is single-threaded per batch. For datasets larger than ~100k records, run during a maintenance window.
+- fjall uses a directory path for storage (LSM-tree), while redb and Persy use single files. Migration involving fjall creates a directory at the target path.
 
 ---
 
@@ -785,10 +872,10 @@ BEAM uses Gun.js's JSON wire format. Messages are JSON objects with these fields
 
 | Flag | Required | Description |
 |------|----------|-------------|
-| `--from` | Yes | Source backend: `redb` or `persy` |
-| `--to` | Yes | Target backend: `redb` or `persy` |
-| `--source` | Yes | Path to source database file |
-| `--target` | Yes | Path to target database file (will be created) |
+| `--from` | Yes | Source backend: `redb`, `persy`, or `fjall` |
+| `--to` | Yes | Target backend: `redb`, `persy`, or `fjall` |
+| `--source` | Yes | Path to source database (file for redb/persy, directory for fjall) |
+| `--target` | Yes | Path to target database (file for redb/persy, directory for fjall) |
 | `--batch-size` | No | Records per batch (default: 1000) |
 | `--force` | No | Overwrite target if it already exists |
 | `--dry-run` | No | Preview without writing |
@@ -803,6 +890,9 @@ let config = Config {
     my_pub: Some("x.y".into()),
     broadcast_buffer_size: 4096,
     ice_servers: vec!["stun:stun.l.google.com:19302".into()],
+    dedup_capacity: 100_000,
+    mailbox_capacity: 65536,
+    child_mailbox_capacity: 256,
 };
 # }
 ```
@@ -870,13 +960,24 @@ cargo test
 # With WebRTC tests
 cargo test --features webrtc
 
+# With fjall storage tests
+cargo test --features fjall
+
+# With Persy tests (includes redb↔persy migration tests)
+cargo test --features persy
+
+# With fjall tests (includes redb↔fjall migration tests)
+cargo test --features fjall
+
+# With both (includes all migration path tests)
+cargo test --features fjall,persy
+
 # Lint (zero warnings required)
 cargo clippy -- -D warnings
 
 # Doctests only (verifies README code examples compile)
 cargo test --doc
 
-# Benchmarks
 cargo bench
 
 # Run a specific integration test
@@ -902,21 +1003,137 @@ cargo test --test wire_live -- --ignored  # Layer 3: live integration (needs Nod
 | `redb_storage_persists` | Data survives restart with redb storage |
 | `redb_storage_flush_returns_ok` | Flush ack protocol |
 | `cross_backend_mesh_e2e` | 2 redb + 1 Persy nodes converge correctly |
+| `fjall_e2e` | 6 fjall storage tests: put-get, sequential, nested, LWW, flush, isolation (`--features fjall`) |
 | `wire_tests` | 36 golden JSON fixtures — wire protocol spec as tests |
 | `wire_live` | Live BEAM ↔ Gun.js bidirectional sync (4 scenarios) |
 
 ---
 
+## Benchmarks
+
+BEAM includes a comprehensive benchmarking suite covering relay throughput,
+micro-benchmarks for hot-path components, and storage performance.
+
+### Local Put Throughput
+
+Local (non-relay) puts through the actor pipeline — measures the full
+`Node::handle → Router::route → MemoryStorage::apply` path with no network I/O:
+
+| Scenario | Messages | Throughput |
+|----------|----------|------------|
+| 1 sender × 10k | 10,000 | ~24,000–53,000 puts/sec |
+
+Throughput varies with system load. On a dedicated machine with no
+competing processes, expect 50,000+ puts/sec. The bottleneck is
+`Value` cloning for broadcast channels — further gains require
+`Arc<Value>` to make cloning a refcount bump.
+
+### Relay Throughput
+
+Real WebSocket connections through a memory-only relay (no disk I/O):
+
+| Scenario | Messages | Throughput |
+|----------|----------|------------|
+| 1 sender × 10k | 10,000 | ~5,300 msgs/sec |
+| 1 sender × 50k | 50,000 | ~10,600 msgs/sec |
+| 10 senders × 5k | 50,000 | ~11,400 msgs/sec |
+
+The relay's internal processing (parse + dedup + route + serialize) runs in
+microseconds — the bottleneck is client-side `put().await`, not the relay.
+
+### Micro-Benchmarks (Criterion)
+
+| Operation | Time |
+|-----------|------|
+| Parse small Put JSON | 1,067 ns |
+| Parse medium Put JSON | 2.00 µs |
+| Serialize small Put JSON | 69 ns |
+| Parse Get | 677 ns |
+| Dedup check (fresh) | 274 µs |
+| Dedup check (duplicate) | 41.8 µs |
+| Actor mailbox send+recv | 309 µs |
+
+### WASM Benchmarks (Node.js)
+
+| Operation | WASM | Native | Ratio |
+|-----------|------|--------|-------|
+| Parse small Put | 7.9 µs | 1,067 ns | ~7.4× |
+| Serialize small Put | 8.6 µs | 69 ns | ~125× |
+| Parse Get | 4.5 µs | 677 ns | ~6.7× |
+
+Run with: `wasm-pack test --node --no-default-features -- --nocapture`
+
+### WASM Relay Throughput (Browser-only)
+
+`web_sys::WebSocket` callbacks don't fire in Node.js `wasm-bindgen-test-runner`
+([known limitation](https://github.com/wasm-bindgen/wasm-bindgen/issues/4921)).
+Use the browser benchmark page to measure WASM relay throughput:
+
+```bash
+cargo run -- start --port 4944 --memory-storage true --redb-storage false
+python3 -m http.server 8080 -d examples/
+# Open http://localhost:8080/bench.html in a browser
+```
+
+Previous v0.11.0 browser results: ~115–651 msgs/sec depending on batch size.
+
+### Browser Benchmark
+
+An interactive benchmark page is available at `examples/bench.html`:
+
+```bash
+# Start a relay
+cargo run -- start --port 4944 --memory-storage true --redb-storage false
+
+# Serve the benchmark page
+python3 -m http.server 8080 -d examples/
+
+# Open in browser
+open http://localhost:8080/bench.html
+```
+
+The browser benchmark measures:
+- **Relay TPS**: end-to-end throughput through a real relay
+- **Put throughput**: local WASM API fire-and-forget puts
+- **Get throughput**: local WASM API promise resolution
+- **Put→Get round-trip**: full local cycle
+
+### Running Benchmarks
+
+```bash
+# Relay throughput (release mode required)
+cargo test --release --test relay_throughput_bench -- --ignored --nocapture
+
+# Micro-benchmarks (hot-path components)
+cargo bench --bench my_benchmark -- "wire_|dup_check|actor_mailbox"
+
+# Storage benchmarks (redb only by default)
+cargo bench --bench my_benchmark -- "write_storm|read_storm|mixed"
+
+# Storage benchmarks with fjall (head-to-head comparison)
+cargo bench --features fjall --bench my_benchmark -- "write_storm|read_storm|mixed"
+
+# Storage benchmarks with persy
+cargo bench --features persy --bench my_benchmark -- "write_storm|read_storm|mixed"
+
+# Live metrics endpoint (while relay is running)
+curl http://localhost:8080/metrics
+```
+
+See [`benches/RESULTS.md`](benches/RESULTS.md) for full results with
+methodology and analysis.
+
 ## Features
 
 | Feature | Default | Enables |
 |---------|---------|---------|
 | `webrtc` | No | `dep:str0m`, `dep:stun` — direct P2P connections via WebRTC data channels |
+| `fjall` | No | `dep:fjall` — LSM-tree storage backend (recommended for multi-node deployments) |
 | `persy` | No | `dep:persy` — Persy storage backend for high-concurrency workloads |
 
-Without `webrtc`, the `stun` module and `WebRtcPeer` adapter are stubbed out (functions return `None`). Without `persy`, the `PersyStorage` adapter is not compiled in and migration to/from Persy is unavailable.
+Without `webrtc`, the `stun` module and `WebRtcPeer` adapter are stubbed out (functions return `None`). Without `persy`, the `PersyStorage` adapter is not compiled in and migration to/from Persy is unavailable. Without `fjall`, the `FjallStorage` adapter is not compiled in and migration to/from fjall is unavailable. Migration requires at least one of `persy` or `fjall` features.
 
-**WASM**: When targeting `wasm32-unknown-unknown`, native-only modules (redb, Persy, tokio-tungstenite, multicast) are cfg-gated out. Browser adapters (`wasm_ws`, `wasm_idb`) are compiled in. Timer functions (`sleep`, `timeout`, `interval`) are provided by `tokio_with_wasm` via the `tokio_time` shim module instead of tokio's `time` feature (which panics on WASM). The `wasm.rs` module provides `#[wasm_bindgen]` JavaScript bindings. Build with `wasm-pack build --target web --release`.
+**WASM**: When targeting `wasm32-unknown-unknown`, native-only modules (redb, fjall, Persy, tokio-tungstenite, multicast) are cfg-gated out. Browser adapters (`wasm_ws`, `wasm_idb`) are compiled in. Timer functions (`sleep`, `timeout`, `interval`) are provided by `tokio_with_wasm` via the `tokio_time` shim module instead of tokio's `time` feature (which panics on WASM). The `wasm.rs` module provides `#[wasm_bindgen]` JavaScript bindings. Build with `wasm-pack build --target web --release`.
 
 ---
 

package/beam.d.ts

@@ -49,6 +49,35 @@ export class Beam {
      * then flushed automatically.
      */
     static new_persistent(): Beam;
+    /**
+     * Creates a new BEAM node with OPFS (Origin Private File System) persistent storage.
+     *
+     * Data is stored as postcard-serialized files in the browser's OPFS
+     * and survives page reloads and browser restarts. Requires a secure
+     * context (HTTPS or localhost). OPFS is available in all modern browsers
+     * (Chrome 102+, Firefox 111+, Safari 15.2+).
+     *
+     * The OPFS directory opens asynchronously — writes are buffered until
+     * the directory is ready, then flushed automatically.
+     *
+     * ```js
+     * import init, { Beam } from "./beam.js";
+     * await init();
+     * const beam = Beam.new_with_opfs();
+     * beam.connect("ws://relay.example.com");
+     * beam.put("chat.001", "hello");
+     * // Reload page — data is still there.
+     * ```
+     */
+    static new_with_opfs(): Beam;
+    /**
+     * Creates a new BEAM node with OPFS storage at a custom directory name.
+     *
+     * ```js
+     * const beam = Beam.new_with_opfs_name("myapp_data");
+     * ```
+     */
+    static new_with_opfs_name(name: string): Beam;
     /**
      * Subscribes to child updates at the given path.
      *
@@ -108,6 +137,8 @@ export interface InitOutput {
     readonly beam_get: (a: number, b: number, c: number) => number;
     readonly beam_new: () => number;
     readonly beam_new_persistent: () => number;
+    readonly beam_new_with_opfs: () => number;
+    readonly beam_new_with_opfs_name: (a: number, b: number) => number;
     readonly beam_on: (a: number, b: number, c: number, d: number) => void;
     readonly beam_put: (a: number, b: number, c: number, d: number, e: number) => void;
     readonly beam_put_bool: (a: number, b: number, c: number, d: number) => void;
@@ -115,11 +146,11 @@ export interface InitOutput {
     readonly beam_put_num: (a: number, b: number, c: number, d: number) => void;
     readonly beam_stop: (a: number) => void;
     readonly task_worker_entry_point: (a: number, b: number) => void;
-    readonly __wasm_bindgen_func_elem_1101: (a: number, b: number, c: number, d: number) => void;
-    readonly __wasm_bindgen_func_elem_1115: (a: number, b: number, c: number, d: number) => void;
-    readonly __wasm_bindgen_func_elem_234: (a: number, b: number, c: number) => void;
-    readonly __wasm_bindgen_func_elem_234_2: (a: number, b: number, c: number) => void;
-    readonly __wasm_bindgen_func_elem_234_3: (a: number, b: number, c: number) => void;
+    readonly __wasm_bindgen_func_elem_1218: (a: number, b: number, c: number, d: number) => void;
+    readonly __wasm_bindgen_func_elem_1232: (a: number, b: number, c: number, d: number) => void;
+    readonly __wasm_bindgen_func_elem_252: (a: number, b: number, c: number) => void;
+    readonly __wasm_bindgen_func_elem_252_2: (a: number, b: number, c: number) => void;
+    readonly __wasm_bindgen_func_elem_252_3: (a: number, b: number, c: number) => void;
     readonly __wbindgen_export: (a: number, b: number) => number;
     readonly __wbindgen_export2: (a: number, b: number, c: number, d: number) => number;
     readonly __wbindgen_export3: (a: number) => void;

package/beam.js

@@ -83,6 +83,46 @@ export class Beam {
         const ret = wasm.beam_new_persistent();
         return Beam.__wrap(ret);
     }
+    /**
+     * Creates a new BEAM node with OPFS (Origin Private File System) persistent storage.
+     *
+     * Data is stored as postcard-serialized files in the browser's OPFS
+     * and survives page reloads and browser restarts. Requires a secure
+     * context (HTTPS or localhost). OPFS is available in all modern browsers
+     * (Chrome 102+, Firefox 111+, Safari 15.2+).
+     *
+     * The OPFS directory opens asynchronously — writes are buffered until
+     * the directory is ready, then flushed automatically.
+     *
+     * ```js
+     * import init, { Beam } from "./beam.js";
+     * await init();
+     * const beam = Beam.new_with_opfs();
+     * beam.connect("ws://relay.example.com");
+     * beam.put("chat.001", "hello");
+     * // Reload page — data is still there.
+     * ```
+     * @returns {Beam}
+     */
+    static new_with_opfs() {
+        const ret = wasm.beam_new_with_opfs();
+        return Beam.__wrap(ret);
+    }
+    /**
+     * Creates a new BEAM node with OPFS storage at a custom directory name.
+     *
+     * ```js
+     * const beam = Beam.new_with_opfs_name("myapp_data");
+     * ```
+     * @param {string} name
+     * @returns {Beam}
+     */
+    static new_with_opfs_name(name) {
+        const ptr0 = passStringToWasm0(name, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.beam_new_with_opfs_name(ptr0, len0);
+        return Beam.__wrap(ret);
+    }
     /**
      * Subscribes to child updates at the given path.
      *
@@ -215,6 +255,10 @@ function __wbg_get_imports() {
         __wbg__wbg_cb_unref_be22cc64ae6946a0: function(arg0) {
             getObject(arg0)._wbg_cb_unref();
         },
+        __wbg_arrayBuffer_393639d72165e90f: function(arg0) {
+            const ret = getObject(arg0).arrayBuffer();
+            return addHeapObject(ret);
+        },
         __wbg_call_35dba3c747ad7521: function() { return handleError(function (arg0, arg1, arg2) {
             const ret = getObject(arg0).call(getObject(arg1), getObject(arg2));
             return addHeapObject(ret);
@@ -222,10 +266,18 @@ function __wbg_get_imports() {
         __wbg_close_b857478a8d4c1a16: function() { return handleError(function (arg0) {
             getObject(arg0).close();
         }, arguments); },
+        __wbg_close_bff888804a3b665e: function(arg0) {
+            const ret = getObject(arg0).close();
+            return addHeapObject(ret);
+        },
         __wbg_createObjectStore_d3884936b845900f: function() { return handleError(function (arg0, arg1, arg2) {
             const ret = getObject(arg0).createObjectStore(getStringFromWasm0(arg1, arg2));
             return addHeapObject(ret);
         }, arguments); },
+        __wbg_createWritable_376a22cc9862fab6: function(arg0) {
+            const ret = getObject(arg0).createWritable();
+            return addHeapObject(ret);
+        },
         __wbg_data_57d8ce4eb5f0a433: function(arg0) {
             const ret = getObject(arg0).data;
             return addHeapObject(ret);
@@ -247,6 +299,26 @@ function __wbg_get_imports() {
         __wbg_error_dd408a7b3cb542dd: function(arg0) {
             console.error(getObject(arg0));
         },
+        __wbg_getDirectoryHandle_3b6e6ec9cd618b74: function(arg0, arg1, arg2, arg3) {
+            const ret = getObject(arg0).getDirectoryHandle(getStringFromWasm0(arg1, arg2), getObject(arg3));
+            return addHeapObject(ret);
+        },
+        __wbg_getDirectory_2cc7169b6007ef84: function(arg0) {
+            const ret = getObject(arg0).getDirectory();
+            return addHeapObject(ret);
+        },
+        __wbg_getFileHandle_275e470e839818da: function(arg0, arg1, arg2) {
+            const ret = getObject(arg0).getFileHandle(getStringFromWasm0(arg1, arg2));
+            return addHeapObject(ret);
+        },
+        __wbg_getFileHandle_ba98be7045eab758: function(arg0, arg1, arg2, arg3) {
+            const ret = getObject(arg0).getFileHandle(getStringFromWasm0(arg1, arg2), getObject(arg3));
+            return addHeapObject(ret);
+        },
+        __wbg_getFile_f042da3b150a3230: function(arg0) {
+            const ret = getObject(arg0).getFile();
+            return addHeapObject(ret);
+        },
         __wbg_getRandomValues_a608c4436c19407a: function() { return handleError(function (arg0, arg1) {
             globalThis.crypto.getRandomValues(getArrayU8FromWasm0(arg0, arg1));
         }, arguments); },
@@ -272,9 +344,17 @@ function __wbg_get_imports() {
             const ret = result;
             return ret;
         },
+        __wbg_length_36bd29c6848c2144: function(arg0) {
+            const ret = getObject(arg0).length;
+            return ret;
+        },
         __wbg_log_e6372b4fbfc9f81e: function(arg0) {
             console.log(getObject(arg0));
         },
+        __wbg_navigator_6cfdd5fa246d910f: function(arg0) {
+            const ret = getObject(arg0).navigator;
+            return addHeapObject(ret);
+        },
         __wbg_new_20a7c62e9b30cbf7: function() { return handleError(function (arg0, arg1) {
             const ret = new WebSocket(getStringFromWasm0(arg0, arg1));
             return addHeapObject(ret);
@@ -290,7 +370,7 @@ function __wbg_get_imports() {
                     const a = state0.a;
                     state0.a = 0;
                     try {
-                        return __wasm_bindgen_func_elem_1115(a, state0.b, arg0, arg1);
+                        return __wasm_bindgen_func_elem_1232(a, state0.b, arg0, arg1);
                     } finally {
                         state0.a = a;
                     }
@@ -301,6 +381,14 @@ function __wbg_get_imports() {
                 state0.a = 0;
             }
         },
+        __wbg_new_77cc4f4f472aeb81: function(arg0) {
+            const ret = new Uint8Array(getObject(arg0));
+            return addHeapObject(ret);
+        },
+        __wbg_new_ebe3e0f6837f0879: function() {
+            const ret = new Object();
+            return addHeapObject(ret);
+        },
         __wbg_new_typed_cceaf62d8d95e9f2: function(arg0, arg1) {
             try {
                 var state0 = {a: arg0, b: arg1};
@@ -308,7 +396,7 @@ function __wbg_get_imports() {
                     const a = state0.a;
                     state0.a = 0;
                     try {
-                        return __wasm_bindgen_func_elem_1115(a, state0.b, arg0, arg1);
+                        return __wasm_bindgen_func_elem_1232(a, state0.b, arg0, arg1);
                     } finally {
                         state0.a = a;
                     }
@@ -342,6 +430,9 @@ function __wbg_get_imports() {
         __wbg_postMessage_6dcc1574fef77104: function() { return handleError(function (arg0, arg1) {
             getObject(arg0).postMessage(getObject(arg1));
         }, arguments); },
+        __wbg_prototypesetcall_de8e0d9553586985: function(arg0, arg1, arg2) {
+            Uint8Array.prototype.set.call(getArrayU8FromWasm0(arg0, arg1), getObject(arg2));
+        },
         __wbg_put_5e0ae8c80bb952a7: function() { return handleError(function (arg0, arg1, arg2) {
             const ret = getObject(arg0).put(getObject(arg1), getObject(arg2));
             return addHeapObject(ret);
@@ -353,10 +444,6 @@ function __wbg_get_imports() {
             const ret = getObject(arg0).queueMicrotask;
             return addHeapObject(ret);
         },
-        __wbg_readyState_fe79161592fd15ce: function(arg0) {
-            const ret = getObject(arg0).readyState;
-            return ret;
-        },
         __wbg_resolve_020f95d838c6ef25: function(arg0) {
             const ret = Promise.resolve(getObject(arg0));
             return addHeapObject(ret);
@@ -371,6 +458,12 @@ function __wbg_get_imports() {
         __wbg_setTimeout_593504220b42c5a5: function(arg0, arg1) {
             globalThis.setTimeout(getObject(arg0), arg1);
         },
+        __wbg_set_create_7df81b728041e33b: function(arg0, arg1) {
+            getObject(arg0).create = arg1 !== 0;
+        },
+        __wbg_set_create_c415df73c1fec0ca: function(arg0, arg1) {
+            getObject(arg0).create = arg1 !== 0;
+        },
         __wbg_set_onclose_cb71fea4ad9056fc: function(arg0, arg1) {
             getObject(arg0).onclose = getObject(arg1);
         },
@@ -415,6 +508,10 @@ function __wbg_get_imports() {
             const ret = typeof window === 'undefined' ? null : window;
             return isLikeNone(ret) ? 0 : addHeapObject(ret);
         },
+        __wbg_storage_9c75a59b053f787c: function(arg0) {
+            const ret = getObject(arg0).storage;
+            return addHeapObject(ret);
+        },
         __wbg_target_13424fe1cdc436ac: function(arg0) {
             const ret = getObject(arg0).target;
             return isLikeNone(ret) ? 0 : addHeapObject(ret);
@@ -431,24 +528,28 @@ function __wbg_get_imports() {
             const ret = getObject(arg0).transaction(getStringFromWasm0(arg1, arg2), __wbindgen_enum_IdbTransactionMode[arg3]);
             return addHeapObject(ret);
         }, arguments); },
+        __wbg_write_6c58d60c26aaeef5: function() { return handleError(function (arg0, arg1, arg2) {
+            const ret = getObject(arg0).write(getArrayU8FromWasm0(arg1, arg2));
+            return addHeapObject(ret);
+        }, arguments); },
         __wbindgen_cast_0000000000000001: function(arg0, arg1) {
-            // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [Externref], shim_idx: 12, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
-            const ret = makeMutClosure(arg0, arg1, __wasm_bindgen_func_elem_234);
+            // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [Externref], shim_idx: 15, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
+            const ret = makeMutClosure(arg0, arg1, __wasm_bindgen_func_elem_252);
             return addHeapObject(ret);
         },
         __wbindgen_cast_0000000000000002: function(arg0, arg1) {
-            // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [Externref], shim_idx: 269, ret: Result(Unit), inner_ret: Some(Result(Unit)) }, mutable: true }) -> Externref`.
-            const ret = makeMutClosure(arg0, arg1, __wasm_bindgen_func_elem_1101);
+            // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [Externref], shim_idx: 290, ret: Result(Unit), inner_ret: Some(Result(Unit)) }, mutable: true }) -> Externref`.
+            const ret = makeMutClosure(arg0, arg1, __wasm_bindgen_func_elem_1218);
             return addHeapObject(ret);
         },
         __wbindgen_cast_0000000000000003: function(arg0, arg1) {
-            // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [NamedExternref("IDBVersionChangeEvent")], shim_idx: 12, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
-            const ret = makeMutClosure(arg0, arg1, __wasm_bindgen_func_elem_234_2);
+            // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [NamedExternref("IDBVersionChangeEvent")], shim_idx: 15, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
+            const ret = makeMutClosure(arg0, arg1, __wasm_bindgen_func_elem_252_2);
             return addHeapObject(ret);
         },
         __wbindgen_cast_0000000000000004: function(arg0, arg1) {
-            // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [NamedExternref("MessageEvent")], shim_idx: 12, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
-            const ret = makeMutClosure(arg0, arg1, __wasm_bindgen_func_elem_234_3);
+            // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [NamedExternref("MessageEvent")], shim_idx: 15, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
+            const ret = makeMutClosure(arg0, arg1, __wasm_bindgen_func_elem_252_3);
             return addHeapObject(ret);
         },
         __wbindgen_cast_0000000000000005: function(arg0) {
@@ -475,22 +576,22 @@ function __wbg_get_imports() {
     };
 }
 
-function __wasm_bindgen_func_elem_234(arg0, arg1, arg2) {
-    wasm.__wasm_bindgen_func_elem_234(arg0, arg1, addHeapObject(arg2));
+function __wasm_bindgen_func_elem_252(arg0, arg1, arg2) {
+    wasm.__wasm_bindgen_func_elem_252(arg0, arg1, addHeapObject(arg2));
 }
 
-function __wasm_bindgen_func_elem_234_2(arg0, arg1, arg2) {
-    wasm.__wasm_bindgen_func_elem_234_2(arg0, arg1, addHeapObject(arg2));
+function __wasm_bindgen_func_elem_252_2(arg0, arg1, arg2) {
+    wasm.__wasm_bindgen_func_elem_252_2(arg0, arg1, addHeapObject(arg2));
 }
 
-function __wasm_bindgen_func_elem_234_3(arg0, arg1, arg2) {
-    wasm.__wasm_bindgen_func_elem_234_3(arg0, arg1, addHeapObject(arg2));
+function __wasm_bindgen_func_elem_252_3(arg0, arg1, arg2) {
+    wasm.__wasm_bindgen_func_elem_252_3(arg0, arg1, addHeapObject(arg2));
 }
 
-function __wasm_bindgen_func_elem_1101(arg0, arg1, arg2) {
+function __wasm_bindgen_func_elem_1218(arg0, arg1, arg2) {
     try {
         const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
-        wasm.__wasm_bindgen_func_elem_1101(retptr, arg0, arg1, addHeapObject(arg2));
+        wasm.__wasm_bindgen_func_elem_1218(retptr, arg0, arg1, addHeapObject(arg2));
         var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
         var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
         if (r1) {
@@ -501,8 +602,8 @@ function __wasm_bindgen_func_elem_1101(arg0, arg1, arg2) {
     }
 }
 
-function __wasm_bindgen_func_elem_1115(arg0, arg1, arg2, arg3) {
-    wasm.__wasm_bindgen_func_elem_1115(arg0, arg1, addHeapObject(arg2), addHeapObject(arg3));
+function __wasm_bindgen_func_elem_1232(arg0, arg1, arg2, arg3) {
+    wasm.__wasm_bindgen_func_elem_1232(arg0, arg1, addHeapObject(arg2), addHeapObject(arg3));
 }
 
 

package/package.json

@@ -6,7 +6,7 @@
     "David Newman <david.r.newman@proton.me>"
   ],
   "description": "BEAM — distributed graph database syncing over WebSocket, WebRTC, and multicast. Successor to rod.",
-  "version": "0.10.0",
+  "version": "0.17.0",
   "license": "MIT",
   "repository": {
     "type": "git",