barrel-lite (browser client)
barrel-lite is a TypeScript client that keeps an offline-first local
document store in the browser and syncs it to a barrel_server over the
/db/:db/_sync/* wire. It is a protocol client, not a WASM port: it
re-implements the HLC, version, and version-vector codecs byte-for-byte,
stamps local mutations with its own source id, and treats local data as a
cache (Safari evicts it) with sync as the durability story. Read this when you
want a web app to read and write a barrel database offline and converge with
the server. The package lives in the umbrella at clients/barrel-lite.
When to use it
- A web app needs local reads and writes that keep working offline.
- You want changes to converge with the server (and other tabs) automatically.
- You are past a single tab: one writer per origin, the rest follow.
Server setup
The browser needs two things the server does not enable by default: CORS, and
a token it can actually ship. Configure both in the barrel_server app env.
{barrel_server, [
{cors, #{origins => '*', %% or a list of origins
expose => [<<"x-barrel-hlc">>]}}, %% default; needed for the clock
{auth, #{tokens => [<<"global-token">>]}}
]}
A browser cannot ship the global token. Issue a per-space capability token
instead (see spaces); it authenticates only that space's /db
and /handoffs routes, with read covering the pull leg and write the push
leg.
$ curl -XPOST host:8080/spaces -H 'authorization: Bearer global-token' \
-H 'content-type: application/json' -d '{"label":"app"}'
# {"space":"sp_...", ...}
$ curl -XPOST host:8080/spaces/sp_.../grants -H 'authorization: Bearer global-token' \
-H 'content-type: application/json' -d '{"rights":["read","write"]}'
# {"token":"bsp_...", ...}
How (open, read, write)
import { Database } from "barrel-lite";
const db = await Database.open("notes", {
remote: { url: "https://edge.example:8080", db: "sp_...", token: "bsp_..." },
multiTab: true,
});
await db.put({ id: "n1", title: "hello" });
const doc = await db.get("n1"); // { id: "n1", title: "hello" }
await db.remove("n1");
db uses OPFS storage and the space id as the database name. Writes are local
and immediate; they reach the server on the next push.
How (sync)
await db.push(); // send local writes
await db.pull(); // apply server changes
await db.sync(); // push then pull (docs + attachments)
const handle = db.liveSync(); // adaptive polling
const live = db.liveSync({ continuous: true }); // hold an SSE stream
handle.stop();
continuous: true opens a GET /db/:db/changes?feed=continuous stream and
re-pulls on each change, falling back to polling if the stream drops. The
stream needs the server's continuous mode (built into barrel_server).
Pull with a filter to hold a subset (the filter joins the sync identity, so it keeps its own cursor):
await db.pull({ filter: { query: { where: [["path", ["type"], "note"]] } } });
await db.pull({ filter: { channel: "mobile" } }); // a declared channel
How (query)
Query the synced set locally with BQL; the same text runs on the server. The local executor matches the server's document subset (SELECT/WHERE/ORDER BY/ LIMIT/OFFSET, paths, UNNEST, IN/LIKE/IS NULL/IS MISSING/BETWEEN/CONTAINS).
const rows = await db.query(
"SELECT name, price FROM db WHERE kind = 'fruit' ORDER BY price DESC LIMIT 10",
);
const scoped = await db.query("SELECT * FROM db WHERE org = $org", {
params: { org: "acme" },
});
Vector and keyword search (vector_top_k, bm25_top_k, hybrid_top_k) and
SUBSCRIBE need the server; they throw BqlServerOnlyError locally. Send
those, or any heavy or global query, to the server:
const { rows, meta } = await db.queryRemote(
"SELECT * FROM bm25_top_k('outage', k => 20) AS s",
);
How (vector search)
Pull each document's embedding to the browser and rank the synced set by
cosine against a query vector you supply. Vectors ride a dedicated pass (they
never travel on the document feed), so pull them after a sync or fold them into
liveSync.
await db.syncEmbeddings(); // pull vectors for the docs you hold
db.liveSync({ vectors: true }); // or pull them each live cycle
const hits = await db.searchLocal(queryVector, { k: 10 });
// [{ id, score, doc }], sorted by descending cosine
const filtered = await db.searchLocal(queryVector, {
k: 10,
filter: "kind = 'note'", // a BQL WHERE narrows candidates first
});
searchLocal ranks the per-document emb vectors you have synced. That is a
different corpus from the server's ANN index, which is bound to the embedding
model's dimension; reach it with db.searchVector / db.searchText:
const vhits = await db.searchVector(queryVector, { k: 10 }); // server ANN
const thits = await db.searchText("outage", { k: 10, mode: "bm25" });
No model is bundled. To embed text in the browser, load a model yourself (for
example transformers.js) and pass the Float32Array to searchLocal; its
dimension must match the stored vectors. See examples/vector-search.html.
How (attachments)
Attachments are content-addressed blobs synced on their own feed, correlated to a document by name.
await db.putAttachment("doc1", "photo.jpg", bytes, { contentType: "image/jpeg" });
const got = await db.getAttachment("doc1", "photo.jpg"); // { bytes, info }
const info = await db.getAttachmentInfo("doc1", "photo.jpg"); // digest/length/type
await db.removeAttachment("doc1", "photo.jpg");
await db.gcAttachments(); // reclaim unreferenced blobs
Blobs stream over the _sync/att* endpoints, deduplicate by SHA-256 digest,
and resolve last-write-wins on an origin timestamp (no version vectors). A
server without an attachment feed degrades the phase to skipped.
How (events)
db.onChange((c) => render(c.id, c.deleted, c.source)); // local | remote
db.onStatus((s) => setBadge(s.state)); // idle | syncing | live | error
Both fire on every tab, whether that tab is the leader or a follower, so UI code is identical on either side.
How (conflicts)
When the device and another replica edit the same document before they sync, both versions are kept, on the device and on the server. Every replica shows the same winner (the highest version), and the other version is a conflict you can read and resolve:
const db = await Database.open("notes", {
remote,
onConflict: (e) => console.warn("local edit is now a conflict", e.id),
});
await db.sync();
const current = await db.get("note"); // the winner
const others = await db.conflicts("note"); // [{version, deleted, body}]
if (others.length > 0) {
await db.resolve("note", { text: mergeTexts(current, others) });
await db.push(); // replaces both everywhere
}
putreplaces the winner and leaves conflicts in place;resolvereplaces the winner and every conflict (passnullto resolve to a delete).- A server configured with a
conflict_resolverresolves conflicts itself; the resolution arrives on the next pull. - Against a server older than whole-state sync, the client falls back to one version at a time: a local edit that loses is then not kept locally (the server keeps it), as before.
Notes
- Storage is a cache. Anything not yet flushed is lost on a crash, and the browser may evict the whole store; the server copy is the source of truth. A flush always precedes a push, so anything the server was told is also on disk locally.
- Multi-tab: one tab holds a Web Lock and owns the store and sync; other tabs proxy reads and writes to it over BroadcastChannel and receive change and status events. When the leader tab closes, the next tab is promoted and reloads the store.
- The client keeps its checkpoints itself, so a pull-only deployment needs
only a
readgrant. It never writes server-side checkpoints. - Live sync polls
_sync/changes(500 ms after activity, backing off to 30 s when idle; a local write wakes it). Polling is the floor;continuous: trueadds a fetch-based SSE stream (which carries the bearer) that wakes the poller and degrades back to polling on drop. - The client mints and persists its own 16-hex source id. Do not clear browser storage expecting a clean slate mid-sync: a new source id changes the authorship of future writes.
- Local BQL matches the server's document subset, with two documented
divergences: JSON collapses
1and1.0(the CBOR-backed server keeps them distinct), and ORDER BY across mixed types follows a fixed total order (number, then boolean/null, then object, then array, then string). - Vector search runs in the browser:
searchLocalranks the synced per-doc vectors by brute-force cosine (pull them withsyncEmbeddings). Text and ANN queries delegate to the server viasearchText/searchVector. See the "How (vector search)" section above. - Live sync polls by default;
continuous: trueholds one SSE stream per database (leader-only) and consumes one of the origin's HTTP connections.