Barrel
EN GitHub

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

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 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éfautRô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âcheAppelRenvoie
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âcheAppelRenvoie
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âcheAppelRenvoie
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.

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

Limites à connaître

  • Absent de npm : construisez-le depuis clients/barrel-lite dans 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 ; searchLocal classe les vecteurs synchronisés en force brute.
  • Le statut "offline" existe dans le type mais n’est jamais émis.

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