Event Reference

Every state change in StateMesh emits an event. Events use a discriminated union — TypeScript narrows the shape based on the type field.

Event Types

Type	When
state.changed	Any state change
state.reset	mesh.reset() called
action.started	Action handler begins
action.completed	Action handler finishes
action.error	Action handler throws
transaction.started	Transaction begins
transaction.optimistic	Optimistic update applied
transaction.completed	Transaction commits
transaction.error	Transaction fails
transaction.rollback	Transaction rolls back
transaction.retry	Transaction retries
resource.fetch	Resource fetch starts
resource.success	Resource fetch succeeds
resource.error	Resource fetch fails
resource.invalidated	Resource cache invalidated
mutation.started	Mutation begins
mutation.completed	Mutation succeeds
mutation.error	Mutation fails
form.submitted	Form submitted
form.validated	Form validated
form.autosaved	Form autosaved
url.changed	URL state changed
persist.loaded	Persistence loaded
persist.saved	Persistence saved
sync.received	Cross-tab message received
sync.sent	Cross-tab message sent

Event Shape

interface MeshEvent {
  type: string;          // Event type (discriminator)
  name?: string;         // Action/transaction/resource/mutation name
  timestamp: number;     // Date.now()
  metadata?: Record<string, unknown>;  // Event-specific data
}

Subscribe to Events

// All events
mesh.subscribe((state) => state, (state) => { /* ... */ });

// Specific event type
mesh.on({ type: "action.completed" }, (event) => {
  console.log(event.name);
});

// Wildcard
mesh.on({ type: "resource.*" }, (event) => {
  console.log(event.type);
});

// RegExp
mesh.on({ type: /error$/ }, (event) => {
  console.error(event);
});

Important Notes

TIP

Events are fire-and-forget. Listeners are error-isolated — they never break state mutations.