Arcane.events.when()

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

Syntax

Arcane.events.when(eventName, listener)

Parameters

eventName: "transport.ready" or "core.ready"; listener: callback

Return value

() => void unsubscribe function

Description

Subscribes to a durable lifecycle completion. A late subscriber receives the first frozen completion payload asynchronously.

Overview

Arcane.events.when(eventName, listener) observes a designated durable completion. Exactly two event names are durable:

If the completion has not occurred, when() behaves as a one-time future subscription. If it already occurred, when() queues the stored first payload for asynchronous listener delivery. The callback never runs in the same call stack as a late when() registration.

The first completion payload is snapshotted and recursively frozen before live callbacks run. Repeated events with the same durable name do not replace the stored value. Wildcard subscriptions can observe the original live completion, but they do not receive historical replays triggered by when().

See the Arcane event catalog for both completion payloads and their limits.

Parameters and return value

The return value is an unsubscribe function. For a queued late replay, calling it before the next microtask prevents callback delivery.

Passing an event other than transport.ready or core.ready throws a synchronous TypeError. Passing a non-function listener for a valid durable event also throws a synchronous TypeError.

transport.ready alone does not prove host health, application authority, capability grants, publisher trust, or service readiness. Use the relevant API for each of those facts.

Example

const events = globalThis.Arcane?.events;

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

const offTransport = events.when('transport.ready', function reportTransportReady(payload) {
    console.log('Transport selected', payload.protocol, payload.transport);
});

const offCore = events.when('core.ready', function reportCoreReady(payload) {
    console.log('Core ready', payload.version, payload.app, payload.platform);
});

globalThis.addEventListener('pagehide', function cleanupReadinessSubscriptions() {
    offTransport();
    offCore();
}, {once: true});

Reference group

Core and events