Events

Every change to a document produces an event: an annotation created, a page rotated, a field filled in. Listen to them to keep your interface in sync without reading the document again.

const stop = doc.events.on('annotations.created', (event) => {
  addToSidebar(event.annotation);
});
 
// later
stop();

on() returns a function that stops listening. To hear every event, use subscribe():

const stop = doc.events.subscribe((event) => {
  console.log(event.type);
});

What an event contains#

An event carries exactly what the call that made the change returned, plus its type and where it came from (origin). The event for create() has the same annotation that create() resolved with:

doc.events.on('annotations.updated', ({ annotation, origin }) => {
  if (origin.kind === 'remote') showToast(`${annotation.author} changed a comment`);
});

An event fires after the change is saved, never before, and before the call’s promise resolves. By the time await page.annotations.create(…) returns, your listeners have run.

Every event#

Changes that touch one page (annotations) carry that page, so you can update only what’s on screen.

Which write an event came from#

Every write takes an opId in its options, a name for the write, and every event it fires carries it as origin.tx.id. Leave it out and the engine makes one up. That’s how you match an event to a change you made:

const opId = crypto.randomUUID();
doc.events.on('annotations.updated', ({ origin }) => {
  if (origin.tx?.id === opId) markSaved();
});
await page.annotations.update(ref, { contents: 'Seen' }, { opId });

An opId is 1 to 255 visible ASCII characters (what an HTTP header can carry), on every engine. On the cloud, a write retried with the same opId is applied once, and the retry gets the first answer. The cloud engine retries a write lost on the network itself, under the same opId, so use a fresh opId for every write. A change, and the annotation, form and metadata calls a change can hold, do the same on the local engine.

The opId is also how you undo a write: doc.apply({ undoOf: opId }). See Changes & undo.

Some calls make many changes at once. An import of 50 annotations fires 50 annotations.created events, one after the other, all with the same origin.tx:

doc.events.on('annotations.created', ({ annotation, origin }) => {
  addToSidebar(annotation);
  if (origin.tx && origin.tx.index === origin.tx.count - 1) redrawSidebar(); // the last of the batch
});

tx.id is the same for all of them, and tx.index counts from 0 to tx.count - 1. A write that makes one change fires one event, with tx.index 0 and tx.count 1.

Who hears what#

The local engine tells you about changes made through this engine. Two tabs with the same file are two separate copies: a change in one doesn’t reach the other.

Good to know#

• Each change arrives once. Your own changes aren’t sent back to you a second time.
• A listener that throws doesn’t stop the other listeners, and doesn’t make the call fail.
• origin.kind is about the open document, not the user. “Did I do this?” (undo, optimistic UI): check origin.kind. “Did this user do it?”: check origin.sub.