Barrel
FR GitHub

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

Shell
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)

KeyDefaultWhat 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

TaskCallReturns
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

TaskCallReturns
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

TaskCallReturns
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.

TypeScript
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-lite in 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; searchLocal ranks synced vectors by brute force.
  • The "offline" status exists in the type but is never emitted.

Up and down to moveEnter to open