Events API reference

import type * as events from './contracts/index.js';
/**
 * Typed in-process dispatcher for application and framework events.
 *
 * Event classes are runtime keys, so listeners infer the correct event shape
 * without requiring a global string-to-payload registry. Dispatch is
 * intentionally synchronous from the caller's perspective: listeners run in
 * registration order and asynchronous listeners are awaited.
 *
 * @example
 * const unsubscribe = app().events.listen(WebsiteCrawled, async event => {
 * 	await indexWebsite(event.websiteId);
 * });
 *
 * await app().events.dispatch(new WebsiteCrawled(websiteId));
 * unsubscribe();
 */
export declare class Events {
    #private;
    /**
     * Registers a listener for exactly one event class.
     *
     * Subclasses are independent event types and do not automatically invoke
     * listeners registered for a parent class.
     *
     * @param eventType - Event class used as the listener key.
     * @param listener - Consumer invoked for subsequent event instances.
     * @returns Idempotent function that removes this registration.
     */
    listen<TEvent extends object>(eventType: events.EventConstructor<TEvent>, listener: events.EventListener<TEvent>): events.EventUnsubscribe;
    /**
     * Registers a listener that removes itself before its first invocation.
     *
     * Removing the registration before calling the listener guarantees that
     * overlapping dispatches cannot invoke the one-shot listener twice.
     *
     * @param eventType - Event class used as the listener key.
     * @param listener - Consumer invoked at most once.
     * @returns Idempotent function that removes the pending registration.
     */
    once<TEvent extends object>(eventType: events.EventConstructor<TEvent>, listener: events.EventListener<TEvent>): events.EventUnsubscribe;
    /**
     * Dispatches one class instance to its current listeners.
     *
     * Listeners run sequentially in registration order. If a listener throws or
     * rejects, dispatch rejects immediately and later listeners are not invoked.
     * Callers therefore control whether listener completion is part of their
     * operation or should be delegated to a durable queued job.
     *
     * @param event - Class instance containing event data.
     */
    dispatch<TEvent extends object>(event: TEvent): Promise<void>;
    /**
     * Returns whether an event class currently has one or more listeners.
     *
     * @param eventType - Exact event class to inspect.
     * @returns True when at least one listener is registered.
     */
    hasListeners<TEvent extends object>(eventType: events.EventConstructor<TEvent>): boolean;
    /**
     * Removes every listener registered for one event class.
     *
     * @param eventType - Exact event class whose registrations should be removed.
     */
    forget<TEvent extends object>(eventType: events.EventConstructor<TEvent>): void;
    /**
     * Removes all listener registrations owned by this dispatcher.
     */
    clear(): void;
}

/**
 * Runtime class token used to register a listener for one event type.
 *
 * The constructor is used only as an identity key. Applications create and
 * dispatch their event instances themselves.
 */
export interface EventConstructor<TEvent extends object = object> {
    /** Human-readable class name used in diagnostics and tooling. */
    readonly name: string;
    /** Event instance shape represented by this class token. */
    readonly prototype: TEvent;
}

/**
 * Synchronous or asynchronous consumer of one application event type.
 *
 * @param event - Event instance dispatched by application or framework code.
 */
export type EventListener<TEvent extends object> = (event: TEvent) => void | Promise<void>;

/**
 * Idempotent function that removes one event listener registration.
 */
export type EventUnsubscribe = () => void;