sutram docs
All pages

Events

Commands are for intent: "please do this". Events are for facts: "this happened". They are optional.

import { getEvents } from "@d34dman/sutram/events";

const events = getEvents();
events.define("cart.changed", {
  description: "The cart changed",
  payload: {
    type: "object",
    properties: { count: { type: "integer" } },
    required: ["count"],
  },
});

events.emit("cart.changed", { count: 2 }, { source: "agent" });
events.on("cart.changed", (e) => render(), { as: "cart badge" });

Only declared events can be emitted, and payloads are checked against their schema.

For agents: wait, or poll

Agents cannot be notified, so they ask. Declaring events adds three commands:

  • events list: the events this page declares.
  • events recent --since=<id>: the events after an id.
  • events wait <name> --since=<id> --timeout=<seconds>: returns the first matching event after the id, at once when the page already keeps one, otherwise as soon as it is emitted. Without a name it takes any event; without --since it waits for the next one. It gives up after 10 seconds by default, 60 at most, and then fails (exit 1) with the line that keeps waiting without missing one.

events wait saves an agent the loop of asking events recent again and again after something that finishes later: a field the form loads, a list that reloads, a message after a save.

form submit node-article-form
events wait message.shown --since=12

In a batch, a wait that times out fails the batch like any other command.

In JavaScript, events.next(name, { since, timeout, signal }) does the same and resolves to the event, or to null (the timeout is in milliseconds there):

const event = await events.next("cart.changed", { timeout: 5000 });

The page keeps the last 50, and forgets older ones when Sutram starts again (a command calls reinitializes(), or the app calls registry.reinitialize(); see Annotations and the policy).

This page as MarkdownEdit on GitHub

PreviousFormats