Arcane.events

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

Syntax

Arcane.events

Member kind

Namespace

Description

Native event subscriptions and durable completion observation; see the event inventory for names, delivery, hosts, triggers, and payloads.

Overview

Arcane.events is the application-facing event hub for messages delivered by the bound Arcane host. It provides four synchronous subscription and observation methods:

Use a named subscription when the application knows the event it needs. A named listener receives that event's data payload directly. A wildcard subscription uses the event name "*" and receives an envelope shaped as { event, data }. Wildcard delivery is useful for bounded diagnostics, but it should not replace named subscriptions in application logic. Some event payloads can contain credentials or other sensitive values, so do not log wildcard data indiscriminately.

See the Arcane event catalog for event names, triggers, payloads, and host-specific availability.

Delivery and replay model

Ordinary events are live and future-only. They are not retained for a late subscriber. This includes progress, terminal streams, terminal exits, and appearance changes. on() and once() never replay an earlier ordinary event.

Only transport.ready and core.ready are designated durable completions. The first payload for each completion is snapshotted and frozen before listeners run. Later occurrences do not replace it. when() delivers a future first completion like a one-time subscription, or queues the stored first payload for asynchronous delivery when the completion already occurred.

transport.ready means that the document selected a callable Arcane transport. It does not prove that Core is healthy, that a method is admitted, or that a capability is granted. core.ready reports the host's readiness event; use the method-specific capability and status APIs for authorization and service state.

Listener safety and cleanup

Every subscription method returns an unsubscribe function. Retain it and call it when the component, view, or document no longer owns the listener. Calling an unsubscribe function again is harmless.

Listener exceptions are caught and logged so one listener cannot stop delivery to the remaining listeners. Handle expected failures inside the listener when the application needs to surface or recover from them; an exception thrown by a listener is not reported to the event producer.

Example

const events = globalThis.Arcane?.events;

if (!events?.on) {
    throw new Error('Arcane event delivery is unavailable in this document.');
}

const unsubscribe = [
    events.on('operation.progress', function reportOperationProgress(data) {
        console.log('Operation progress', data.progress, data.message);
    }),
    events.on('*', function reportObservedEvent({event}) {
        console.debug('Arcane event', event);
    })
];

function stopObserving() {
    for (const off of unsubscribe.splice(0)) {
        off();
    }
}

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

Members

• Arcane.events.on() — Subscribes to future deliveries from the event inventory. A named listener receives the event data; the wildcard listener receives {event, data}.
• Arcane.events.once() — Subscribes to the next matching delivery and removes the listener before invoking it. It does not replay an event that already occurred.
• Arcane.events.when() — Subscribes to a durable lifecycle completion. A late subscriber receives the first frozen completion payload asynchronously.
• Arcane.events.completed() — Synchronously reports whether this document has stored the designated durable completion.

Reference group

Namespace, constructor, and values