obsidian-dev-utils/dist/lib/esm/AsyncEvents.d.mts

This is the collection of useful functions that you can use for your Obsidian plugin development

/**
 * @packageDocumentation
 *
 * Async event emitter.
 */
import type { Promisable } from 'type-fest';
/**
 * Async event reference.
 */
export interface AsyncEventRef {
    /**
     * An event emitter.
     */
    asyncEvents: AsyncEvents;
    /**
     * A callback to call when the event is triggered.
     */
    callback: GenericCallback;
    /**
     * A name of the event.
     */
    name: string;
    /**
     * A context passed as `this` to the `callback`.
     */
    thisArg: unknown;
}
type GenericCallback = (...args: unknown[]) => Promisable<void>;
/**
 * Async event emitter implementation
 */
export declare class AsyncEvents {
    private readonly eventRefsMap;
    /**
     * Remove an event listener.
     *
     * @param name - The name of the event.
     * @param callback - The callback to remove.
     *
     * @example
     * ```ts
     * events.off('my-event', myListener);
     * ```
     *
     * @public
     */
    off<Args extends unknown[]>(name: string, callback: (...args: Args) => Promisable<void>): void;
    /**
     * Remove an event listener by reference.
     *
     * @param eventRef - The reference to the event listener.
     *
     * @example
     * ```ts
     * events.offref(myRef);
     * ```
     *
     * @public
     */
    offref(eventRef: AsyncEventRef): void;
    /**
     * Add an event listener.
     *
     * @param name - The name of the event.
     * @param callback - The callback to call when the event is triggered.
     * @param thisArg - The context passed as `this` to the `callback`.
     * @returns A reference to the event listener.
     *
     * @example
     * ```ts
     * events.on('my-event', async (arg1, arg2) => {
     *     await sleep(100);
     *     console.log(arg1, arg2);
     * });
     * ```
     *
     * @public
     */
    on<Args extends unknown[]>(name: string, callback: (...args: Args) => Promisable<void>, thisArg?: unknown): AsyncEventRef;
    /**
     * Add an event listener that will be triggered only once.
     *
     * @param name - The name of the event.
     * @param callback - The callback to call when the event is triggered.
     * @param thisArg - The context passed as `this` to the `callback`.
     * @returns A reference to the event listener.
     *
     * @example
     * ```ts
     * events.once('my-event', async (arg1, arg2) => {
     *     await sleep(100);
     *     console.log(arg1, arg2);
     * });
     * ```
     *
     * @public
     */
    once<Args extends unknown[]>(name: string, callback: (...args: Args) => Promisable<void>, thisArg?: unknown): AsyncEventRef;
    /**
     * Trigger an event, executing all the listeners in order even if some of them throw an error.
     *
     * @param name - The name of the event.
     * @param args - The data to pass to the event listeners.
     *
     * @example
     * ```ts
     * events.trigger('my-event', 'arg1', 'arg2');
     * ```
     *
     * @public
     */
    trigger<Args extends unknown[]>(name: string, ...args: Args): void;
    /**
     * Trigger an event asynchronously, executing all the listeners in order even if some of them throw an error.
     *
     * @param name - The name of the event.
     * @param args - The data to pass to the event listeners.
     *
     * @public
     */
    triggerAsync<Args extends unknown[]>(name: string, ...args: Args): Promise<void>;
    /**
     * Try to trigger an event, executing all the listeners in order even if some of them throw an error.
     *
     * @param eventRef - The event reference.
     * @param args - The data to pass to the event listeners.
     *
     * @example
     * ```ts
     * events.tryTrigger(myRef, ['arg1', 'arg2']);
     * ```
     *
     * @public
     */
    tryTrigger<Args extends unknown[]>(eventRef: AsyncEventRef, args: Args): void;
    /**
     * Try to trigger an event asynchronously, executing all the listeners in order even if some of them throw an error.
     *
     * @param eventRef - The event reference.
     * @param args - The data to pass to the event listeners.
     *
     * @public
     */
    tryTriggerAsync<Args extends unknown[]>(eventRef: AsyncEventRef, args: Args): Promise<void>;
}
export {};