Quickstart: browser
barrel-lite is a TypeScript
client that keeps a copy of a Barrel database in the browser. Reads and
writes are local, so the app answers at once and keeps working offline;
sync sends local writes to a barrel_server and brings back the changes
made by other copies. In this quickstart you build a small notes app that
runs on two devices, a laptop and a phone: you give the browser a scoped
token, write a note, sync it to the second device, then edit it on both
at once and resolve the conflict. Use this path when a web app must keep
working without a network.
What you will do
- Build barrel-lite and add it to a web app
- Give the browser a token limited to one space
- Write and read documents locally
- Sync two copies through barrel_server
- Resolve a conflict between two edits
Before you start
- A
barrel_serveryou can reach. See Quickstart: server. - Node.js 20 or later and npm.
1. Get barrel-lite
You build the client from the Barrel source because barrel-lite 0.1.0
is not on npm. Build it from the umbrella and install
it into your app from that directory:
cd barrel/clients/barrel-lite
npm ci
npm run build
cd /path/to/your-app
npm install /path/to/barrel/clients/barrel-lite
2. Let the browser in
A web page runs on its own origin and anyone can read its code, so the
server must allow cross-origin requests (CORS) and the page must carry a
token that grants as little as possible. Add CORS and a global admin
token to the server's sys.config and restart it:
[{barrel_server, [
{http_port, 8080},
{cors, #{origins => '*',
expose => [<<"x-barrel-hlc">>]}},
{auth, #{tokens => [<<"global-token">>]}}]}]. Never put the global token in a web page: it opens every database. Instead, create a space, a database created through Barrel's agent layer that you can share, and issue a capability token for it. A capability token grants named rights on one space only, and you can revoke it. The space id is the database name the browser uses:
curl -X POST localhost:8080/spaces \
-H 'authorization: Bearer global-token' \
-H 'content-type: application/json' -d '{"label":"app"}'
curl -X POST localhost:8080/spaces/sp_7uitvqeved3z7seu/grants \
-H 'authorization: Bearer global-token' \
-H 'content-type: application/json' \
-d '{"rights":["read","write"]}'
{"ok":true,"space":"sp_7uitvqeved3z7seu"}
{"token":
"bsp_alrw6fxiqga5r47x_odwpp27li6m754pfsuhbwd2n2vxek3ox44hj3zxv",
"grant":{"rights":["read","write"],
"space":"sp_7uitvqeved3z7seu", ...}} The first call created the space sp_7uitvqeved3z7seu. The second issued
a bsp_... token with read and write on that space and nothing else.
The token is shown once, since the server stores only a hash of it; copy
it now. read covers pulls, write covers pushes.
3. Open, write, read
Database.open creates the local copy and remembers which server
database it syncs with. You then write and read as if the database were
local, because it is.
import { Database } from "barrel-lite";
const remote = {
url: "http://localhost:8080",
db: "sp_7uitvqeved3z7seu",
token: "bsp_alrw6fxiqga5r47x_...",
};
const laptop = await Database.open("notes", { remote });
await laptop.put({ id: "n1", title: "hello" });
await laptop.get("n1");
{"id":"n1",
"version":"000001a1ba4159ea00000000@wd31d29e133c6788f"}
{"title":"hello","id":"n1"} put answered with the document id and its version, the
revision token of this write, the
same token the server calls _rev. get read the note back from the
local store. Nothing has reached the server yet.
Writes go to the local store at once. In a browser the store is OPFS; where OPFS is missing (Node, for example) it is in memory.
4. Sync
Sync is how copies catch up with each other. A push sends local writes to
the server, a pull applies the changes the server has from other copies,
and sync() does both.
await laptop.sync(); // push, then pull
const live = laptop.liveSync(); // keep syncing
live.stop();
Open a second copy the same way, on another device or in another browser. Its first sync brings the document in, and local BQL reads it:
const phone = await Database.open("notes", { remote });
await phone.sync();
await phone.get("n1");
await phone.query(
"SELECT id, title FROM db WHERE title = 'hello'");
{"push":{"pushed":1,"skipped":0,"conflicts":0},
"pull":{"scanned":1,"applied":0}}
{"push":{"pushed":0,"skipped":0,"conflicts":0},
"pull":{"scanned":1,"applied":1}}
{"id":"n1","title":"hello"}
[{"id":"n1","title":"hello"}] The first line is the laptop's sync(): its push sent one document
(pushed: 1), and its pull saw one change on the server, its own, so
there was nothing to apply. The second line is the phone's: it had
nothing to push and applied one change, the note. The phone then reads
the note locally, by id and with BQL.
5. Resolve a conflict
Offline copies can change the same note at the same time. Barrel does not drop either edit: both versions are kept, every copy picks the same winner, and the other version is kept as a conflict for you to resolve. Edit the note on both copies before they sync, then sync:
await laptop.put({ id: "n1", title: "hello from the laptop" });
await phone.put({ id: "n1", title: "hello from the phone" });
await laptop.sync(); await phone.sync(); await laptop.sync();
await laptop.get("n1");
await phone.get("n1");
await laptop.conflicts("n1");
{"id":"n1","title":"hello from the phone"}
{"id":"n1","title":"hello from the phone"}
[{"version":"000001a1ba415a1600000001@wd31d29e133c6788f",
"deleted":false,
"body":{"id":"n1","title":"hello from the laptop"}}] Both copies show the phone's edit: the winner is the version with the
highest token, so every copy reaches the same answer without talking to
each other. This is convergence.
The laptop's edit is not lost: conflicts returns it with its version
and body.
resolve replaces the winner and every conflict with one body. Push it,
and the other copy gets the resolution on its next pull:
await laptop.resolve("n1", { title: "hello from both" });
await laptop.push();
await phone.pull();
await phone.get("n1");
await phone.conflicts("n1");
{"id":"n1","title":"hello from both"}
[] The phone now reads the resolved body, and its conflict list is empty: the resolution replaced both versions on every copy that pulled it.
put on a document in conflict replaces only the winner; the conflicts
stay. Pass null to resolve to resolve to a delete.
Notes
The local store is a cache. Writes not yet flushed are lost on a crash, and the browser may evict the whole store. The server copy is the source of truth, so sync often.
- Vector, keyword and hybrid search (
vector_top_k,bm25_top_k,hybrid_top_k) andSUBSCRIBErun on the server only; usedb.queryRemote. Locally they throwBqlServerOnlyError. - barrel-lite authenticates with bearer tokens only, global or capability. It does not sign requests.
- With
multiTab: trueone tab syncs and the others go through it. - The full client is described in barrel-lite.