Arcane.events.once()

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

Syntax

Arcane.events.once(eventName, listener)

Parameters

eventName: event-name string; listener: callback

Return value

() => void unsubscribe function

Description

Subscribes to the next matching delivery and removes the listener before invoking it. It does not replay an event that already occurred.

Overview

Arcane.events.once(eventName, listener) subscribes to the next future matching event. The subscription removes itself before invoking the listener, so at most one future delivery reaches that callback. It returns an unsubscribe function that can cancel the subscription before the event occurs.

once() is future-only for every event, including transport.ready and core.ready. It never replays a completion that occurred before registration. Use when() for durable completion observation. Event names and payloads are in the Arcane event catalog.

Parameters and return value

The result is an unsubscribe() function. Call it when the owner is disposed or when the application no longer needs to wait.

The listener must be callable. Unlike on() and when(), the current once() surface does not synchronously validate the original listener. A non-function listener therefore fails inside guarded event delivery and is logged rather than producing a useful registration-time TypeError. Treat a non-function listener as invalid input and always pass a function.

Listener exceptions are otherwise isolated in the same way as on() listener exceptions: they are logged and do not interrupt other event subscribers.

Example

const events = globalThis.Arcane?.events;

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

let timeout = null;
const cancelExitWait = events.once('terminal.exit', function reportNextTerminalExit(payload) {
    clearTimeout(timeout);
    console.log(
        `Session ${payload.sessionId} exited`,
        payload.exitCode,
        payload.signal
    );
});

timeout = setTimeout(function cancelTimedOutExitWait() {
    cancelExitWait();
    console.warn('Stopped waiting for the next terminal exit.');
}, 30_000);

globalThis.addEventListener('pagehide', function cleanupExitWait() {
    clearTimeout(timeout);
    cancelExitWait();
}, {once: true});

Reference group

Core and events