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.tss’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éfauthttp://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 estMemoryAdapter; dans un navigateur, c’est OPFS par défaut.putetgettravaillent 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 parsync()uneSyncErrorde codenetwork; les écritures locales attendent et partent à la synchronisation suivante. - Deux modifications concurrentes d’un document sont toutes deux
conservées :
getrenvoie l’une,conflictsrenvoie l’autre.resolveremplace les deux, ici et, après un envoi, partout. queryexécute du BQL en local sur la copie synchronisée.
Notes
- Les données locales dans
MemoryAdapterdisparaissent à 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
// 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(); {
"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"
}
} #!/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.
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' ]