FFFF feat(browser): add BrowserDb async WASM façade with IndexedDB persistence by adityamukho · Pull Request #149 · project-minigraf/minigraf · GitHub
[go: up one dir, main page]

Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
20 commits
Select commit Hold shift + click to select a range
9461474
feat(browser): add browser feature flag and wasm target dependencies
adityamukho Apr 17, 2026
4d85176
feat(browser): add BrowserBufferBackend with dirty page tracking
adityamukho Apr 17, 2026
2d94ada
feat(browser): wire browser module into crate (cfg-gated)
adityamukho Apr 17, 2026
20a0cfd
feat(browser): add IndexedDbBackend open and load_all_pages
adityamukho Apr 17, 2026
d35b32c
fix(browser): silence clippy warnings - unused params and missing docs
adityamukho Apr 17, 2026
be866be
feat(browser): add IndexedDbBackend::write_pages
adityamukho Apr 17, 2026
8b6d4f4
feat(browser): add BrowserDb struct with open_in_memory and open cons…
adityamukho Apr 17, 2026
f7331c4
refactor(db): make materialize_transaction/retraction and VALID_FROM_…
adityamukho Apr 17, 2026
f3db9ae
feat(browser): add BrowserDb::execute() with read and write paths
adityamukho Apr 17, 2026
137def6
feat(browser): add checkpoint, export_graph, import_graph to BrowserDb
adityamukho Apr 17, 2026
35c2d2c
test(browser): add wasm-bindgen-test integration tests for BrowserDb
adityamukho Apr 17, 2026
cddec31
ci: add wasm-browser workflow for Chrome and Firefox headless tests
adityamukho Apr 17, 2026
7f37c64
docs(example): add browser WASM demo (examples/browser/)
adityamukho Apr 17, 2026
72153ab
style: apply cargo fmt to browser module and related files
adityamukho Apr 17, 2026
89bb12c
fix(browser): cfg-gate with_backend accessors to wasm32+browser to si…
adityamukho Apr 17, 2026
6b0be09
Merge branch 'main' into feature/phase-8-1a-browser-wasm
adityamukho Apr 17, 2026
4bc9cca
fix(browser): add cdylib crate-type required by wasm-pack build
adityamukho Apr 17, 2026
02596ba
fix(browser): enable bulk-memory for wasm-opt to fix wasm-validator m…
adityamukho Apr 17, 2026
4d9556e
fix(browser): use standalone binaryen wasm-opt with --enable-bulk-memory
adityamukho Apr 17, 2026
0f1a10a
fix(browser): remove wasm-opt CI step; wasm binary is correctly unopt…
adityamukho Apr 17, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
71 changes: 71 additions & 0 deletions .github/workflows/wasm-browser.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,71 @@
name: WASM Browser

on:
push:
branches: ["main"]
pull_request:
branches: ["main"]

env:
CARGO_TERM_COLOR: always

permissions:
contents: read

jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4

- uses: dtolnay/rust-toolchain@stable
with:
targets: wasm32-unknown-unknown

- name: Install wasm-pack
run: curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh

- name: Build (release)
run: wasm-pack build --target web --features browser

- name: Check gzipped binary size
run: |
SIZE=$(gzip -c pkg/minigraf_bg.wasm | wc -c)
echo "Gzipped WASM size: ${SIZE} bytes"
if [ "$SIZE" -gt 1048576 ]; then
echo "WARNING: exceeds 1 MB gzipped budget (${SIZE} bytes)"
fi

- name: Upload pkg artifact
uses: actions/upload-artifact@v4
with:
name: wasm-pkg
path: pkg/

test:
needs: build
runs-on: ubuntu-latest
strategy:
fail-fast: false
matrix:
browser: [chrome, firefox]
steps:
- uses: actions/checkout@v4

- uses: dtolnay/rust-toolchain@stable
with:
targets: wasm32-unknown-unknown

- name: Install wasm-pack
run: curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh

- name: Setup Chrome
if: matrix.browser == 'chrome'
uses: browser-actions/setup-chrome@v1

- name: Setup Firefox
if: matrix.browser == 'firefox'
uses: browser-actions/setup-firefox@v1

- name: Test (headless ${{ matrix.browser }})
run: wasm-pack test --headless --${{ matrix.browser }} --features browser
40 changes: 39 additions & 1 deletion Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,12 @@ categories = ["database-implementations", "embedded"]
readme = "README.md"
documentation = "https://docs.rs/minigraf"

[lib]
crate-type = ["cdylib", "rlib"]

[package.metadata.wasm-pack.profile.release]
wasm-opt = false

[package.metadata.docs.rs]
all-features = true
rustdoc-args = ["--cfg", "docsrs"]
Expand All @@ -23,19 +29,51 @@ anyhow = "1.0"
chrono = { version = "0.4", features = ["serde", "std"], default-features = false }
uuid = { version = "1.0", features = ["v4", "v5", "serde"] }
regex-lite = "0.1.9"
serde_json = { version = "1.0", optional = true }

[target.'cfg(target_arch = "wasm32")'.dependencies]
uuid = { version = "1.0", features = ["v4", "v5", "serde", "js"] }
wasm-bindgen = { version = "0.2", optional = true }
wasm-bindgen-futures = { version = "0.4", optional = true }
js-sys = { version = "0.3", optional = true }
web-sys = { version = "0.3", optional = true, features = [
"DomStringList",
"Event",
"IdbDatabase",
"IdbFactory",
"IdbIndex",
"IdbObjectStore",
"IdbOpenDbRequest",
"IdbRequest",
"IdbTransaction",
"IdbTransactionMode",
"Window",
] }

[dev-dependencies]
tempfile = "3"
serde_json = "1.0"

[target.'cfg(not(target_arch = "wasm32"))'.dev-dependencies]
temp 8000 file = "3"
criterion = { version = "0.8", features = ["html_reports"] }

[target.'cfg(target_arch = "wasm32")'.dev-dependencies]
wasm-bindgen-test = "0.3"

[[bench]]
name = "minigraf_bench"
harness = false

[features]
default = []
wasm = []
browser = [
"dep:wasm-bindgen",
"dep:wasm-bindgen-futures",
"dep:web-sys",
"dep:js-sys",
"dep:serde_json",
]

[profile.release]
panic = "abort"
Expand Down
38 changes: 38 additions & 0 deletions examples/browser/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
# Minigraf Browser Demo

Demonstrates `@minigraf/core` running in a plain browser page with no bundler.

## Build

From the repo root:

```bash
wasm-pack build --target web --features browser
```

This produces `pkg/` containing `minigraf.js`, `minigraf_bg.wasm`, and
`minigraf.d.ts`.

## Serve

```bash
# From the repo root (not the examples/browser/ directory):
python3 -m http.server 8080
```

Open `http://localhost:8080/examples/browser/` in Chrome or Firefox.

## What it does

- Opens an IndexedDB-backed database named `"minigraf-demo"`.
- Transacts facts about Alice and Bob.
- Queries Alice's friends with Datalog.
- Exports the `.graph` blob and imports it into a fresh in-memory database.
- Logs all results to the browser console (open with F12).

## Notes

- Data persists across page reloads (stored in IndexedDB).
- The `pkg/` directory is gitignored — rebuild after pulling changes.
- This package (`@minigraf/core`) is **browser-only**. For Node.js, use
`@minigraf/node` (Phase 8.3).
47 changes: 47 additions & 0 deletions examples/browser/app.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
// Minigraf browser demo — no bundler required.
// Build first: wasm-pack build --target web --features browser
// Then serve from repo root: python3 -m http.server 8080
// Open: http://localhost:8080/examples/browser/

import init, { BrowserDb } from "../../pkg/minigraf.js";

async function m 10000 ain() {
// Initialise the WASM module (loads minigraf_bg.wasm).
await init();

// Open a database backed by IndexedDB (persists across page reloads).
const db = await BrowserDb.open("minigraf-demo");

// Assert some facts.
await db.execute(`(transact [
[:alice :person/name "Alice"]
[:alice :person/age 30]
[:alice :friend :bob]
[:bob :person/name "Bob"]
])`);

// Query with Datalog.
const raw = await db.execute(`
(query [:find ?friend-name
:where [:alice :friend ?f]
[?f :person/name ?friend-name]])
`);
const result = JSON.parse(raw);
console.log("Alice's friends:", result.results.map(row => row[0]));
// Expected: ["Bob"]

// Export to a portable .graph blob.
const blob = db.exportGraph();
console.log(".graph blob size:", blob.byteLength, "bytes");

// Import into a fresh in-memory db.
const db2 = BrowserDb.openInMemory();
await db2.importGraph(blob);
const raw2 = await db2.execute(
`(query [:find ?name :where [?e :person/name ?name]])`
);
console.log("After import, names:", JSON.parse(raw2).results.map(r => r[0]));
// Expected: ["Alice", "Bob"] (order may vary)
}

main().catch(console.error);
12 changes: 12 additions & 0 deletions examples/browser/index.html
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<title>Minigraf Browser Demo</title>
</head>
<body>
<h1>Minigraf Browser Demo</h1>
<p>Open the browser console (F12) to see query results.</p>
<script type="module" src="app.js"></script>
</body>
</html>
7 changes: 7 additions & 0 deletions examples/memory_profile.rs
Original file line number Diff line number Diff line change
Expand Up @@ -5,9 +5,13 @@
//! Inserts <fact_count> `:eN :val N` facts into a checkpointed file-backed DB,
//! then runs a single point-entity query. Run under heaptrack to capture
//! peak heap and allocation counts.
//!
//! Not applicable on WASM targets (no filesystem, no heaptrack).

#[cfg(not(target_arch = "wasm32"))]
use minigraf::OpenOptions;

#[cfg(not(target_arch = "wasm32"))]
fn main() -> anyhow::Result<()> {
let n: usize = std::env::args()
.nth(1)
Expand Down Expand Up @@ -46,3 +50,6 @@ fn main() -> anyhow::Result<()> {
eprintln!("memory_profile: inserted and queried {} facts", n);
Ok(())
}

#[cfg(target_arch = "wasm32")]
fn main() {}
Loading
Loading
0