Skip to content

Commit 2daa5f9

Browse files
farhan-syahfarhan-syah
committed
chore: add WASM CI workflow and nodedb-lite-wasm README
Add a GitHub Actions workflow that runs `cargo check --workspace --target wasm32-unknown-unknown`, `wasm-pack build`, and `wasm-pack test --node` on every PR to keep the WASM target green. Add a README for `nodedb-lite-wasm` documenting supported engines, CRDT sync configuration, build targets, test commands, and known limitations of the WASM environment.
1 parent d39488d commit 2daa5f9

2 files changed

Lines changed: 197 additions & 0 deletions

File tree

‎.github/workflows/wasm.yml‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
name: WASM
2+
3+
on:
4+
pull_request:
5+
branches: [main]
6+
types: [opened, synchronize, reopened, ready_for_review]
7+
workflow_dispatch:
8+
9+
concurrency:
10+
group: wasm-${{ github.ref }}
11+
cancel-in-progress: true
12+
13+
permissions:
14+
contents: read
15+
16+
env:
17+
CARGO_TERM_COLOR: always
18+
19+
jobs:
20+
wasm-build:
21+
name: WASM Build and Test
22+
runs-on: ubuntu-latest
23+
steps:
24+
- uses: actions/checkout@v6
25+
26+
- name: Install Rust
27+
uses: dtolnay/rust-toolchain@stable
28+
with:
29+
targets: wasm32-unknown-unknown
30+
31+
- name: Restore cargo registry cache
32+
uses: Swatinem/rust-cache@v2
33+
with:
34+
prefix-key: wasm
35+
workspaces: nodedb-lite -> nodedb-lite/target
36+
37+
- name: Restore wasm-pack cache
38+
uses: actions/cache@v4
39+
with:
40+
path: ~/.cache/wasm-pack
41+
key: wasm-pack-${{ runner.os }}
42+
43+
- name: Install wasm-pack
44+
run: curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh
45+
46+
- name: Check workspace for wasm32 target
47+
working-directory: nodedb-lite
48+
run: cargo check --workspace --target wasm32-unknown-unknown
49+
50+
- name: Build WASM release
51+
working-directory: nodedb-lite
52+
run: wasm-pack build --target web --release nodedb-lite-wasm
53+
54+
- name: Run WASM tests
55+
working-directory: nodedb-lite
56+
run: wasm-pack test --node nodedb-lite-wasm

‎nodedb-lite-wasm/README.md‎

Lines changed: 141 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,141 @@
1+
# nodedb-lite-wasm
2+
3+
WebAssembly bindings for **NodeDB-Lite**, the embedded variant of NodeDB. Runs in browsers and Node.js. Exposes all eight Lite engines (Vector, Graph, Document schemaless, Document strict, Columnar/Timeseries/Spatial, KV, FTS, Array) through a single `NodeDb` API.
4+
5+
> **Lite only.** This crate is *not* a WASM build of the Origin server. The distributed Origin engine (Tokio Control Plane, io_uring Data Plane, QUIC cluster transport) does not target WebAssembly. To talk to an Origin cluster from the browser, run Lite-WASM locally and sync via WebSocket. See the [WASM deployment guide](../../nodedb/docs/wasm.md) for the full picture.
6+
7+
## Status
8+
9+
**Experimental / preview.** Build and basic engine usage work end-to-end. A WASM CI lane runs `cargo check --workspace --target wasm32-unknown-unknown`, a release build via `wasm-pack build`, and the `wasm-pack test --node` suite on every PR.
10+
11+
Outstanding items before this is considered stable:
12+
13+
- Published `npm` package
14+
15+
Until that lands, treat the WASM target as preview. File issues for anything that breaks.
16+
17+
## Install
18+
19+
Local development build:
20+
21+
```bash
22+
cd nodedb-lite/nodedb-lite-wasm
23+
wasm-pack build --target web --release
24+
```
25+
26+
Outputs go to `pkg/`. To consume from a sibling app:
27+
28+
```bash
29+
cd ../my-app
30+
npm link ../nodedb-lite-wasm/pkg
31+
```
32+
33+
A published npm package will be available once the project reaches stable status.
34+
35+
## Quick Start
36+
37+
```javascript
38+
import init, { NodeDbLite } from "nodedb-lite-wasm";
39+
40+
await init();
41+
const db = new NodeDbLite();
42+
43+
await db.sql("CREATE COLLECTION users");
44+
await db.sql("INSERT INTO users { name: 'Alice', age: 30 }");
45+
46+
const rows = await db.sql("SELECT * FROM users WHERE age > 25");
47+
console.log(rows);
48+
```
49+
50+
## Engines
51+
52+
All eight engines work in WASM with the same SQL surface as native Lite:
53+
54+
| Engine | DDL example |
55+
| ------------------ | -------------------------------------------------------------------- |
56+
| Document | `CREATE COLLECTION docs` |
57+
| Key-Value | `CREATE KV cache` |
58+
| Vector | `CREATE VECTOR INDEX idx ON docs METRIC cosine DIM 384` |
59+
| Full-text | `CREATE FTS INDEX idx ON docs FIELD body` |
60+
| Graph | `CREATE COLLECTION edges` + `GRAPH INSERT EDGE ...` |
61+
| Columnar | `CREATE COLLECTION events WITH (storage = 'columnar')` |
62+
| Timeseries | `CREATE COLLECTION metrics WITH (profile = 'timeseries', ...)` |
63+
| Spatial | `CREATE COLLECTION places WITH (profile = 'spatial', ...)` |
64+
| Array (NDArray) | `CREATE ARRAY grid DIMS (...) ATTRS (...) TILE_EXTENTS (...)` |
65+
66+
See the [query language reference](../../nodedb/docs/query-language.md).
67+
68+
## CRDT Sync to Origin
69+
70+
Writes are local-first. Configure sync to push deltas to an Origin cluster:
71+
72+
```javascript
73+
await db.sync_config({
74+
server_url: "wss://origin.example.com",
75+
auth_token: "...",
76+
auto_sync: true,
77+
sync_interval_ms: 5000,
78+
});
79+
```
80+
81+
Origin validates constraints and returns compensation hints on conflict. See [offline sync patterns](../../nodedb/docs/offline-sync-patterns.md).
82+
83+
## Build Targets
84+
85+
```bash
86+
# Browsers (ESM)
87+
wasm-pack build --target web --release
88+
89+
# Node.js
90+
wasm-pack build --target nodejs --release
91+
92+
# Bundlers (webpack, rollup, vite)
93+
wasm-pack build --target bundler --release
94+
```
95+
96+
## Testing
97+
98+
Tests run under Node.js via wasm-pack. From the `nodedb-lite/` workspace root:
99+
100+
```bash
101+
wasm-pack test --node nodedb-lite-wasm
102+
```
103+
104+
The `--node` flag is required (not `--web` or `--headless`) because the tests use
105+
`wasm_bindgen_test_configure!(run_in_node_experimental)` and rely on Node.js
106+
module resolution rather than a browser environment.
107+
108+
To verify the workspace compiles for the wasm32 target before running tests:
109+
110+
```bash
111+
cargo check --workspace --target wasm32-unknown-unknown
112+
```
113+
114+
This command must be run from the `nodedb-lite/` workspace directory.
115+
116+
## Limitations
117+
118+
- **In-memory only** — no native filesystem. Use IndexedDB/`localStorage` via a wrapper if persistence is needed across reloads.
119+
- **Single-threaded** — runs on the JS/WASM main thread; no thread-per-core, no parallelism.
120+
- **No io_uring, no native sockets** — storage and networking go through host APIs.
121+
- **No cluster role** — Lite-WASM cannot serve as a Raft member or vShard host. It is a client/edge node only.
122+
- **Bundle size** — measure your own build; gzip before serving.
123+
124+
## Size Optimization
125+
126+
```bash
127+
cargo install wasm-opt
128+
wasm-opt -O4 pkg/nodedb_lite_wasm_bg.wasm -o pkg/nodedb_lite_wasm_bg.wasm
129+
```
130+
131+
Measure before and after on your own build.
132+
133+
## License
134+
135+
Apache-2.0. See the workspace root `LICENSE` file.
136+
137+
## See Also
138+
139+
- [WASM deployment guide](../../nodedb/docs/wasm.md)
140+
- [NodeDB-Lite](../nodedb-lite/) — native embedded crate
141+
- [NodeDB-Lite FFI](../nodedb-lite-ffi/) — C/iOS/Android bindings

0 commit comments

Comments
 (0)