Barrel
EN GitHub

Local-first avec barrel-lite

Ce projet fait tourner deux clients TypeScript, un téléphone et un portable, chacun avec sa propre copie locale d’une même base, synchronisée avec un barrel_server. Le téléphone écrit et lit en local, se synchronise, passe hors ligne et continue de modifier, pendant que le portable modifie le même document. De retour en ligne, les deux versions sont conservées sous forme de conflit ; le téléphone le résout une fois et la résolution atteint le portable et le serveur. Utilisez-le quand une application doit continuer de fonctionner sans réseau.

Prérequis

  • Node 22.6 ou plus récent (cette exécution a utilisé Node 22.19). main.ts s’exécute avec le retrait des types de Node, sans étape de build.

  • Un barrel_server en marche (1.13 ou plus récent) sur BARREL_URL, par défaut http://localhost:8080, sans authentification. Voir le démarrage rapide du serveur.

  • barrel-lite, compilé depuis le dépôt barrel. Il n’est pas encore sur npm :

    cd /path/to/barrel/clients/barrel-lite
    npm install && npm run build
    cd -
    npm install
    npm install --no-save /path/to/barrel/clients/barrel-lite

Exécuter

BARREL_URL=http://localhost:8080 ./run.sh

run.sh vérifie les types de main.ts avec tsc --noEmit, puis l’exécute. Le programme supprime et recrée la base lf_groceries sur le serveur pour que chaque exécution parte de zéro.

Ce que montre l’exemple

  • Database.open(name, {remote, storage}) : dans Node, le stockage local est MemoryAdapter ; dans un navigateur, c’est OPFS par défaut.
  • put et get travaillent sur la copie locale, sans requête.
  • sync() envoie les changements locaux, puis récupère ceux du serveur.
  • Le hors ligne est simulé avec l’option remote.fetch : un fetch qui échoue fait lever par sync() une SyncError de code network ; les écritures locales attendent et partent à la synchronisation suivante.
  • Deux modifications concurrentes d’un document sont toutes deux conservées : get renvoie l’une, conflicts renvoie l’autre. resolve remplace les deux, ici et, après un envoi, partout.
  • query exécute du BQL en local sur la copie synchronisée.

Notes

  • Les données locales dans MemoryAdapter disparaissent à la fin du processus. Dans un navigateur, OPFS les conserve, écrites toutes les 200 ms ; c’est la synchronisation qui les rend durables.
  • Les exécutions dans le navigateur (OPFS, plusieurs onglets) sont couvertes par la suite Playwright de barrel-lite, pas par cet exemple.

Sortie attendue

Une ligne par étape. La sortie d’une exécution réelle se trouve dans expected.txt.

Télécharger Le dossier sur GitHub, avec tous les fichiers ci-dessous.

Code source

main.ts
// Local-first with barrel-lite: two clients keep a local copy of
// one database, edit offline, sync, and resolve a conflict.
import { Database, MemoryAdapter, SyncError } from "barrel-lite";

const URL = process.env.BARREL_URL ?? "http://localhost:8080";
const DB = "lf_groceries";

// A fetch we can switch off to simulate a lost connection.
let online = true;
const phoneFetch = (input: string, init?: RequestInit) =>
  online ? fetch(input, init) : Promise.reject(new TypeError("offline"));

// Start from an empty database on the server (REST).
await fetch(`${URL}/db/${DB}?purge=true`, { method: "DELETE" });
await fetch(`${URL}/db/${DB}`, { method: "PUT" });

// In Node the local store is in memory; in a browser it is OPFS.
const phone = await Database.open(DB, {
  remote: { url: URL, db: DB, fetch: phoneFetch },
  storage: new MemoryAdapter(),
});
const laptop = await Database.open(DB, {
  remote: { url: URL, db: DB },
  storage: new MemoryAdapter(),
});

// 1. Local writes and reads need no server.
await phone.put({ id: "list", title: "Groceries", items: ["milk"] });
const local = await phone.get("list");
console.log("phone local get:", local?.["items"]);

// 2. Sync: push the phone's copy, pull it on the laptop.
const first = await phone.sync();
console.log("phone sync: pushed", first.push.pushed);
const pulled = await laptop.pull();
console.log("laptop pull: applied", pulled.applied);
console.log("laptop get:", (await laptop.get("list"))?.["items"]);

// 3. The phone goes offline and keeps working.
online = false;
await phone.put({ id: "list", title: "Groceries",
                  items: ["milk", "eggs"] });
await phone.put({ id: "note", text: "store closes at 20:00" });
try {
  await phone.sync();
} catch (e) {
  if (!(e instanceof SyncError)) throw e;
  console.log("phone sync while offline:", e.code);
}
console.log("phone local docs:",
  (await phone.allDocs()).map((d) => d.id).sort());

// Meanwhile the laptop edits the same document and syncs.
await laptop.put({ id: "list", title: "Groceries",
                   items: ["milk", "bread"] });
await laptop.push();

// 4. Back online: the phone's edits go up, the laptop's come down.
online = true;
const back = await phone.sync();
console.log("phone sync back online: pushed", back.push.pushed,
            "applied", back.pull.applied);
const winner = await phone.get("list");
const others = await phone.conflicts("list");
console.log("phone list:", winner?.["items"]);
console.log("phone conflicts:", others.map((c) => c.body?.["items"]));

// 5. Resolve once: merge both edits, push the resolution.
const items = new Set<string>();
for (const body of [winner, ...others.map((c) => c.body)]) {
  for (const i of (body?.["items"] as string[] | undefined) ?? []) {
    items.add(i);
  }
}
await phone.resolve("list", { title: "Groceries",
                              items: [...items].sort() });
await phone.push();
await laptop.pull();
console.log("laptop list:", (await laptop.get("list"))?.["items"]);
console.log("laptop conflicts:", (await laptop.conflicts("list")).length);

// 6. Local BQL over the synced copy, and the server's view.
const rows = await laptop.query(
  "SELECT id, text FROM c WHERE text IS NOT NULL");
console.log("laptop query:", rows);
const res = await fetch(`${URL}/db/${DB}/doc/list`);
const server = (await res.json()) as { items: string[] };
console.log("server list:", server.items);

await phone.close();
await laptop.close();
package.json
{
  "name": "barrel-local-first-example",
  "private": true,
  "type": "module",
  "engines": { "node": ">=22.6" },
  "scripts": {
    "start": "node --experimental-strip-types main.ts",
    "typecheck": "tsc --noEmit"
  },
  "devDependencies": {
    "@types/node": "^22.10.0",
    "typescript": "^5.9.3"
  }
}
run.sh
#!/bin/sh
# Type-check, then run main.ts against BARREL_URL
# (default http://localhost:8080). barrel-lite must be installed:
#   npm install /path/to/barrel/clients/barrel-lite
set -e
cd "$(dirname "$0")"
[ -d node_modules/barrel-lite ] || {
  echo "install barrel-lite first (see README)" >&2; exit 1; }
npx tsc --noEmit >&2
exec node --experimental-strip-types --no-warnings main.ts

Sortie attendue

Le fichier expected.txt de l’exemple, issu d’une exécution réelle. Les révisions, identifiants, jetons et horodatages changent à chaque exécution ; scripts/verify-examples.sh les masque avant de comparer.

expected.txt
phone local get: [ 'milk' ]
phone sync: pushed 1
laptop pull: applied 1
laptop get: [ 'milk' ]
phone sync while offline: network
phone local docs: [ 'list', 'note' ]
phone sync back online: pushed 2 applied 1
phone list: [ 'milk', 'bread' ]
phone conflicts: [ [ 'milk', 'eggs' ] ]
laptop list: [ 'bread', 'eggs', 'milk' ]
laptop conflicts: 0
laptop query: [ { id: 'note', text: 'store closes at 20:00' } ]
server list: [ 'bread', 'eggs', 'milk' ]

Haut et bas pour se déplacerEntrée pour ouvrir