barrel-lite
A copy of a Barrel database in the browser. barrel-lite keeps an offline-first local store and syncs it with barrel_server over the replication wire.
What it solves
Web apps need to keep working offline and pick up changes made elsewhere. barrel-lite stores documents and attachments in the browser, runs BQL locally, and replicates with a server using the same version rules as the Erlang nodes, so conflicts are kept, not lost.
When to use it
- A web app must work offline and sync when it reconnects.
- You want local queries and local vector ranking over the data a user holds.
- Several tabs share one store: one tab syncs, the others go through it.
When not to
- You need full-text or ANN search in the browser: those run on the server (
searchText,searchVector). - You need signed requests or mTLS from the client: it sends bearer tokens only.
How it fits into Barrel
- Builds on
- No other Barrel library
- Used by
- No other Barrel library depends on it
- Other dependencies
- TypeScript, ESM, Node 20 or later to build; syncs with barrel_server over HTTP
- On its own
- The local store and local BQL work without a server. Sync, server search and remote queries need barrel_server.
Install
git clone https://github.com/barrel-db/barrel
cd barrel/clients/barrel-lite
npm install
npm run build
# then, in your app
npm install /path/to/barrel/clients/barrel-lite barrel-lite is not published on npm (the package is marked private). Build it from the repository.
Configuration
Database.open(name, opts)
| Key | Default | What it does |
|---|---|---|
remote | none | {url, db, token?, fetch?}; url may include a sub-path |
storage | OPFS, else memory | A storage adapter |
multiTab | false | One leader tab per origin (Web Locks and BroadcastChannel) |
onConflict | none | Callback for concurrent versions |
flushDebounceMs | 200 | Delay before local writes are flushed |
The most used keys only. For every option, see the configuration reference.
The API by task
Documents
| Task | Call | Returns |
|---|---|---|
| Open | Database.open(name, opts) | Promise<Database> |
| Write, read, delete | put(doc), get(id), remove(id) | {id, version}, the doc or undefined |
| List | allDocs(opts) | records |
| Conflicts | conflicts(id), resolve(id, body) | versions, {id, version} |
Query and search
| Task | Call | Returns |
|---|---|---|
| Local BQL | query(bql, {params}) | rows; table functions throw BqlServerOnlyError |
| Server BQL | queryRemote(bql, opts) | {rows, meta} |
| Local vector ranking | syncEmbeddings(), searchLocal(vector, {k, filter}) | [{id, score, doc}], brute-force cosine |
| Server search | searchVector(vector, {k}), searchText(q, {k, mode}) | server hits |
Files and sync
| Task | Call | Returns |
|---|---|---|
| Attachments | putAttachment, getAttachment, removeAttachment | {digest}, {bytes, info} |
| Sync once | push(), pull(), sync() | push and pull stats |
| Keep syncing | liveSync({continuous, vectors}) | {stop} |
| Events | onChange(fn), onStatus(fn) | an unsubscribe function |
Open, write, query, sync
From the package README. Not run for this page; the unit suite (31 files, 187 tests) passed against a fake server.
import { Database } from "barrel-lite";
const db = await Database.open("notes", {
remote: {
url: "https://edge.example:8080",
db: "notes",
token: "bsp_...",
},
multiTab: true,
});
await db.put({ id: "n1", title: "hello" });
const doc = await db.get("n1");
// the same BQL text runs locally on the synced set
const rows = await db.query(
"SELECT title FROM notes WHERE pinned = true");
db.onChange((c) => console.log("changed", c.id));
db.liveSync({ continuous: true });
await db.sync(); // push, then pull Limits to know
- Not on npm: build it from
clients/barrel-litein the repository. - Bearer tokens only, global or
bsp_capability tokens. No signed requests. - Local writes are flushed on a debounce; writes not yet flushed are lost on a crash. Durability comes from sync.
- No full-text search and no ANN index in the browser;
searchLocalranks synced vectors by brute force. - The
"offline"status exists in the type but is never emitted.