barrel-lite
Une copie d’une base Barrel dans le navigateur. barrel-lite garde un stockage local hors ligne d’abord et le synchronise avec barrel_server par le protocole de réplication.
Ce qu’elle résout
Les applications web doivent continuer à fonctionner hors ligne et récupérer les changements faits ailleurs. barrel-lite stocke documents et pièces jointes dans le navigateur, exécute BQL localement, et réplique avec un serveur selon les mêmes règles de version que les nœuds Erlang : les conflits sont conservés, pas perdus.
Quand l’utiliser
- Une application web doit fonctionner hors ligne et se synchroniser à la reconnexion.
- Vous voulez des requêtes locales et un classement vectoriel local sur les données d’un utilisateur.
- Plusieurs onglets partagent un même stockage : un onglet synchronise, les autres passent par lui.
Quand ne pas l’utiliser
- Vous avez besoin de recherche plein texte ou ANN dans le navigateur : elles tournent sur le serveur (
searchText,searchVector). - Vous avez besoin de requêtes signées ou de mTLS côté client : il n’envoie que des tokens bearer.
Sa place dans Barrel
- Repose sur
- Aucune autre bibliothèque Barrel
- Utilisée par
- Aucune autre bibliothèque Barrel n’en dépend
- Autres dépendances
- TypeScript, ESM, Node 20 ou plus récent pour le build ; se synchronise avec barrel_server sur HTTP
- Seule
- Le stockage local et BQL en local fonctionnent sans serveur. La synchronisation, la recherche côté serveur et les requêtes distantes demandent barrel_server.
Installation
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 n’est pas publié sur npm (le paquet est marqué privé). Construisez-le depuis le dépôt.
Configuration
Database.open(name, opts)
| Clé | Défaut | Rôle |
|---|---|---|
remote | aucun | {url, db, token?, fetch?} ; url peut contenir un sous-chemin |
storage | OPFS, sinon mémoire | Un adaptateur de stockage |
multiTab | false | Un onglet leader par origine (Web Locks et BroadcastChannel) |
onConflict | aucun | Callback appelée pour les versions concurrentes |
flushDebounceMs | 200 | Délai avant l’écriture sur disque des modifications locales |
Seulement les clés les plus utilisées. Pour toutes les options, voyez la référence de configuration.
L’API par tâche
Documents
| Tâche | Appel | Renvoie |
|---|---|---|
| Ouvrir | Database.open(name, opts) | Promise<Database> |
| Écrire, lire, supprimer | put(doc), get(id), remove(id) | {id, version}, le document ou undefined |
| Lister | allDocs(opts) | enregistrements |
| Conflits | conflicts(id), resolve(id, body) | versions, {id, version} |
Requêtes et recherche
| Tâche | Appel | Renvoie |
|---|---|---|
| BQL local | query(bql, {params}) | lignes ; les fonctions de table lèvent BqlServerOnlyError |
| BQL sur le serveur | queryRemote(bql, opts) | {rows, meta} |
| Classement vectoriel local | syncEmbeddings(), searchLocal(vector, {k, filter}) | [{id, score, doc}], cosinus en force brute |
| Recherche sur le serveur | searchVector(vector, {k}), searchText(q, {k, mode}) | résultats du serveur |
Fichiers et synchronisation
| Tâche | Appel | Renvoie |
|---|---|---|
| Pièces jointes | putAttachment, getAttachment, removeAttachment | {digest}, {bytes, info} |
| Synchroniser une fois | push(), pull(), sync() | statistiques d’envoi et de réception |
| Synchroniser en continu | liveSync({continuous, vectors}) | {stop} |
| Événements | onChange(fn), onStatus(fn) | une fonction de désabonnement |
Ouvrir, écrire, interroger, synchroniser
Tiré du README du paquet. Non exécuté pour cette page ; la suite unitaire (31 fichiers, 187 tests) passe contre un faux serveur.
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 Limites à connaître
- Absent de npm : construisez-le depuis
clients/barrel-litedans le dépôt. - Tokens bearer seulement, globaux ou jetons de capacité
bsp_. Pas de requêtes signées. - Les écritures locales sont écrites avec un délai ; celles qui ne le sont pas encore sont perdues en cas de plantage. La durabilité vient de la synchronisation.
- Ni recherche plein texte ni index ANN dans le navigateur ;
searchLocalclasse les vecteurs synchronisés en force brute. - Le statut
"offline"existe dans le type mais n’est jamais émis.