Tavern Migration
Observability callbacks moved to tap()
The host's onPeerJoined, onPeerLeft, onPeersChanged, and onWarning options and the guest's onRejected and onWarning options are gone. They are observability, and observability goes through tap() with the typed TavernHostEvent / TavernGuestEvent unions. Lifecycle callbacks (onEnded, onJoined, onFailed) stay: they fire while joinTavern is still resolving, before a tapper could exist.
// Before
const host = hostTavern({
onPeerJoined: (peer) => toast(`${peer.name} joined`),
onPeerLeft: (peer) => toast(`${peer.name} left`),
onPeersChanged: (peers) => updatePeerList(peers),
onWarning: (message) => log.warn(message),
/* ... */
});
// After
const host = hostTavern({
/* ... */
});
host.tap((event) => {
if (event.type === 'peer-joined') toast(`${event.peer.name} joined`);
if (event.type === 'peer-left') toast(`${event.peer.name} left`);
if (event.type === 'warning') log.warn(event.message, event.error); // the error itself, not just text
updatePeerList(host.peers); // the live peer list is a getter
});// Before
const { guest } = await joinTavern({ onRejected: (message) => toast(message) /* ... */ });
// After
const { guest } = await joinTavern({
/* ... */
});
guest.tap((event) => {
if (event.type === 'rejected') toast(event.message); // event.commandId names the command it answers
});Post-dispose use throws TavernDisposedError
kick, createInvitationText, and acceptAnswerText on a disposed host, and sendCommand on an ended guest, now throw TavernDisposedError (a TavernError subtype) instead of silently no-oping or surfacing a bare TavernError/mesh error. relayNotice stays silent: a notice relayed to a closed session is ephemeral state with no audience left.
import { TavernDisposedError } from '@vielzeug/tavern';
try {
guest.sendCommand('doc-1', 'rename', ['x']);
} catch (error) {
if (error instanceof TavernDisposedError) {
// wiring outlived the session
}
}One session, one subject
A tavern session always carries exactly one subject, so the subjectId routing key was removed everywhere: the subjectId option is gone, the wire command no longer names a subject, and sendCommand(name, args) takes two arguments instead of three. Commands targeting "another" subject were never expressible: the host rejected them, and that rejection path is gone with the key.
// Before
guest.sendCommand('doc-1', 'rename', ['Quarterly report']);
// After
guest.sendCommand('rename', ['Quarterly report']);A later release reintroduced an optional third argument for a different purpose. Declaring subject.id on the hosted subject makes the session named: every command must pass that id as sendCommand(name, args, target), and a missing or mismatched target rejects before the table runs. On a named session the argument is mandatory, not optional: calling sendCommand(name, args) against a host that declares an id rejects every command. See "Name the Subject to Guard Command Targets" in usage.md.
The command table is a plain record
TavernCommands was a { has, apply } seam you hand-wired over your own dispatch: now it is the dispatch itself, a Record<string, (args) => void>. A missing name rejects the guest the same way has returning false used to; a throwing handler rejects with its message. Omit commands entirely for a read-only session.
// Before
const host = hostTavern({
commands: { apply: (name, args) => myStore.apply(name, args), has: (name) => name in myStore },
subjectId: 'doc-1',
subjects: {
onChanged: (l) => myStore.onUpdated('doc-1', l),
onRemoved: (l) => myStore.onRemoved('doc-1', l),
snapshot: () => myStore.read('doc-1'),
},
/* ... */
});
// After
const host = hostTavern({
commands: { rename: (args) => myStore.rename(docId, args[0] as string) },
subject: {
onChanged: (l) => myStore.onUpdated(docId, l),
onRemoved: (l) => myStore.onRemoved(docId, l),
snapshot: () => myStore.read(docId),
},
/* ... */
});The subject seam is singular (subjects is now subject), and the notice seam was split by the role that actually uses each half: the host gets serializeNotice, the guest gets onNotice, and TavernNotices is gone.
Join lifecycle: ready replaces onJoined and onFailed
Both callbacks existed because they fired while joinTavern was still resolving, before a tapper could exist. A promise is the race-free shape of exactly that: ready resolves with the mounted subject when the first snapshot mounts and rejects with a TavernError (channel failed or closed) or TavernDisposedError (the guest left early) otherwise. Its rejection is pre-handled, so ignoring ready is safe.
// Before
const { answerText, guest } = await joinTavern({
onJoined: (subject) => mountMirror(subject),
onFailed: (reason) => showError(reason),
/* ... */
});
// After
const { answerCode, guest, ready } = await joinTavern({
/* ... */
});
try {
mountMirror(await ready);
} catch (error) {
showError((error as Error).message);
}onEnded stays: it is a lifecycle transition long after the handle exists, on both handles.
Pairing vocabulary: codes, not texts
createInvitationText is createInvitationCode, acceptAnswerText is acceptAnswerCode, the guest option invitationText is invitationCode, and the join result's answerText is answerCode: the API now speaks the same word the docs and pairing errors do. Both event unions also gained a final { type: 'dispose' } event, matching the rest of the monorepo.