Arcane.events.on()

This focused page is derived from the mechanically checked full member inventory.

Syntax

Arcane.events.on(eventName, listener)

Parameters

eventName: event-name string or "*"; listener: callback

Return value

() => void unsubscribe function

Description

Subscribes to future deliveries from the event inventory. A named listener receives the event data; the wildcard listener receives {event, data}.

Overview

Arcane.events.on(eventName, listener) subscribes to every future matching event. It is synchronous and returns an unsubscribe function.

For a named event, the listener receives the event's data payload directly:

const off = Arcane.events.on('terminal.output', function logTerminalOutput(data) {
    console.log(data.sessionId, data.stream, data.data);
});

The special event name "*" subscribes to all future events. Its listener receives { event, data }, not the named event's data alone:

const off = Arcane.events.on('*', function logAnyArcaneEvent({event, data}) {
    console.debug(event, data);
});

Event names and payloads are defined in the Arcane event catalog.

Parameters and return value

The returned unsubscribe() function removes that listener. Retain it and call it during component or document teardown. Repeating the call is harmless.

Passing a non-function listener throws a synchronous TypeError. An unknown event name does not itself throw; it simply has no delivery unless the host later emits that exact name.

Delivery and failure behavior

on() is future-only. It does not replay ordinary events or an already observed durable completion. Use when() when a late subscriber must observe transport.ready or core.ready.

Listener exceptions are caught and logged. Delivery continues to the other listeners, and the exception is not sent back to the native event producer. Handle expected listener failures inside the callback when the application must surface them.

Example

const events = globalThis.Arcane?.events;

if (!events?.on) {
    throw new Error('Arcane events are unavailable.');
}

const offOutput = events.on('terminal.output', function writeTerminalOutput(payload) {
    const write = payload.stream === 'stderr' ? console.error : console.log;
    write(`[${payload.sessionId}] ${payload.data}`);
});

const offAll = events.on('*', function logObservedArcaneEvent({event}) {
    console.debug('Observed Arcane event', event);
});

function cleanup() {
    offOutput();
    offAll();
}

globalThis.addEventListener('pagehide', cleanup, {once: true});

Reference group

Core and events