Skip to content
tavern logoTavernUtilities
Table sessions over mesh: host-owned state replication with guest command forwarding
Version
v26.11.20
Size
2.1 KB gzip
BrowserNode ≥22
hostTavernjoinTavernTavernCommandTavernCommandsTavernSubject View all 15 exports

Why Tavern? ​

Peer-to-peer apps share one arrangement problem: the canonical state of something: a document, a dashboard, a record: lives on exactly one device, while every other participant should see it and be able to change it from their own. Tavern turns that arrangement into a session: one host owns the canonical state, guests mirror it, and every guest command is forwarded through the host's own command table, so remote actions follow exactly the same code path as local ones.

ts
// Before: hand-rolled session orchestration: pairing, protocol validation,
// command routing, snapshot broadcasting, notice relaying, presence tracking.
const host = createMeshHost({
  /* ... */
});
host.on('command', ({ peerId, payload }) => {
  const command = mySchema.safeParse(payload);
  if (!command.success) {
    host.send(peerId, 'rejected', {
      /* ... */
    });
    return;
  }
  try {
    applySubjectCommand(command.data.name, subject, command.data.args);
  } catch (error) {
    host.send(peerId, 'rejected', {
      /* ... */
    });
  }
});
bus.on('subject:updated', () => {
  host.broadcast('snapshot', snapshotFor(subject));
});
// ... 40+ more lines of plumbing

// After: tavern owns the protocol, the validation, the broadcasting.
const host = hostTavern({
  commands: { rename: (args) => store.rename(docId, args[0] as string) },
  subject: {
    onChanged: (listener) => store.onUpdated(docId, listener),
    onRemoved: (listener) => store.onRemoved(docId, listener),
    snapshot: () => store.read(docId),
  },
});
FeatureTavernRaw meshSocket.io rooms
Bundle size2.1 KB5.9 KBN/A
Zero dependencies
Host-authoritative commands: same table as local UI: wire it yourself: wire it yourself
Snapshot replication: microtask-coalesced
Out-of-band pairing (QR / copy-paste): needs a server
Notice relaying: consumer-defined wire shape: server-mediated

Use Tavern when one device should own the canonical state of something: a shared document, a live dashboard, a record under review, and every other device should mirror it and send commands back through the host's own command table, which stays the single validation path.

Consider raw @vielzeug/mesh when you need P2P messaging without the host-authoritative replication model: chat, whiteboards, or custom topologies. Mesh carries bounded typed messages (capped by maxMessageBytes, 65 536 by default) with no chunking or acknowledgements: file transfer needs app-level chunking and acknowledgements built on top.

Installation ​

sh
pnpm add @vielzeug/tavern
sh
npm install @vielzeug/tavern
sh
yarn add @vielzeug/tavern

Quick Start ​

ts
import { hostTavern, joinTavern } from '@vielzeug/tavern';

// Host: wire the command table and snapshot access for the shared subject.
const host = hostTavern({
  commands: {
    rename: (args) => myStore.rename(docId, args[0] as string),
    append: (args) => myStore.append(docId, args[0] as string),
  },
  subject: {
    onChanged: (listener) => myStore.onUpdated(docId, listener),
    onRemoved: (listener) => myStore.onRemoved(docId, listener),
    snapshot: () => myStore.read(docId),
  },
});

// Produce a single-use invitation code; deliver it out-of-band (QR, copy/paste).
const invitationCode = await host.createInvitationCode();

// Guest: consume the invitation code, produce an answer code for the host.
const { answerCode, guest, ready } = await joinTavern({
  invitationCode,
  mount: (snapshot) => parseAndMount(snapshot),
  name: 'Alex',
});
await host.acceptAnswerCode(answerCode);

// `ready` settles once the first snapshot arrives and mounts: the mirror is live.
await ready;

// The guest's commands run through the host's own table; their effect
// arrives with the next snapshot, so a successful command needs no ack.
guest.sendCommand('rename', ['Quarterly report']);

// Cleanup: hosting ends for every guest; onEnded fires exactly once on both sides.
host.dispose();
guest.dispose();

Features ​

  • hostTavern: host one subject: pairing, protocol validation, command application, coalesced snapshot broadcasts
  • joinTavern: join as a guest: consume the invitation code, produce the answer code, mirror the host's snapshots
  • TavernCommands: the host's command table as a plain record of handlers: the same functions the host's own UI calls, so remote actions cannot bypass validation
  • ready promise: the join lifecycle is awaitable: ready resolves with the mounted mirror or rejects with why the session never came up
  • Coalesced snapshots: bursts of local changes ship one snapshot per microtask, not one per change
  • onEnded fires exactly once: on both handles: channel drops, subject removal, and explicit disposal share a single idempotent cleanup path
  • Typed errors: TavernPairingError covers every unusable pasted code with the mesh failure chained as cause

Documentation ​

See Also ​

  • Mesh: the P2P transport underneath: WebRTC pairing, data channels, QR-optimized codecs.
  • Ledger: undo/redo history for the commands the host applies.
  • Herald: typed event bus for the local notice stream tavern relays.