/**
 * @license
 * Copyright 2022-2024 Matter.js Authors
 * SPDX-License-Identifier: Apache-2.0
 */
import "../polyfills/disposable.js";
import { MaybePromise } from "./Promises.js";
/**
 * A callback function for observables.
 *
 * The observer return value effects how an {@link Observable} emits:
 *
 *   - If an observer returns undefined the {@link Observable} invokes the next observer immediately.
 *
 *   - If an observer returns a {@link Promise}, the {@link Observable} awaits the return value then continues as
 *     described here.  The emitter must then await the {@link Promise} returned by {@link Observable.emit}.
 *
 *   - Any other return value is returned by {@link Observable.emit} and subsequent observers do not see emission.
 *
 * @param payload a list of arguments to be emitted
 */
export interface Observer<T extends any[] = any[], R = void> {
    (...payload: T): MaybePromise<R | undefined>;
    [observant]?: boolean;
}
/**
 * A discrete event that may be monitored via callback.  Could call it "event" but that could be confused with Matter
 * cluster events and/or DOM events.
 *
 * @param T arguments, should be a named tuple
 */
export interface Observable<T extends any[] = any[], R = void> extends AsyncIterable<T>, PromiseLike<T> {
    /**
     * Notify observers.
     */
    emit(...args: T): R | undefined;
    /**
     * Add an observer.
     */
    on(observer: Observer<T, R>): void;
    /**
     * Remove an observer.
     */
    off(observer: Observer<T, R>): void;
    /**
     * Add an observer that emits once then is unregistered.
     */
    once(observer: Observer<T, R>): void;
    /**
     * True if there is at least one observer registered.
     */
    isObserved: boolean;
    /**
     * Determine whether an observer is registered.
     */
    isObservedBy(observer: Observer<T, R>): boolean;
    /**
     * This flag indicates whether the observable is asynchronous.  Any observable that accepts promise returns may
     * be asynchronous but this information is not available at runtime unless you specify here, typically via
     * {@link AsyncObservable}.
     */
    isAsync?: boolean;
    /**
     * Observable supports standard "for await (const value of observable").
     *
     * Using an observer in this manner limits your listener to the first parameter normally emitted and your observer
     * cannot return a value.
     */
    [Symbol.asyncIterator](): AsyncIterator<T[0]>;
    /**
     * Release resources associated with the observable.
     */
    [Symbol.dispose](): void;
}
/**
 * An observer may designate itself as "not observant" for the purposes of {@link Observable.isObserved} by returning
 * false from this field.
 */
export declare const observant: unique symbol;
/**
 * An {@link Observable} that explicitly supports asynchronous observers.
 */
export interface AsyncObservable<T extends any[] = any[], R = void> extends Observable<T, MaybePromise<R>> {
    isAsync: true;
}
export type ObserverErrorHandler = (error: Error, observer: Observer<any[], any>) => void;
/**
 * A concrete {@link Observable} implementation.
 */
export declare class BasicObservable<T extends any[] = any[], R = void> implements Observable<T, R> {
    #private;
    constructor(errorHandler?: ObserverErrorHandler, isAsync?: boolean);
    [Symbol.dispose](): void;
    get isAsync(): boolean | undefined;
    set isAsync(isAsync: boolean | undefined);
    get isObserved(): boolean;
    isObservedBy(observer: Observer<T, R>): boolean;
    emit(...payload: T): R | undefined;
    on(observer: Observer<T, R>): void;
    off(observer: Observer<T, R>): void;
    once(observer: Observer<T, R>): void;
    then<TResult1 = T, TResult2 = never>(onfulfilled?: ((value: T) => TResult1 | PromiseLike<TResult1>) | undefined | null, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | undefined | null): PromiseLike<TResult1 | TResult2>;
    [Symbol.asyncIterator](): AsyncIterator<T[0]>;
}
/**
 * Create an {@link Observable}.
 */
export declare const Observable: {
    new <T extends any[], R = void>(errorHandler?: ObserverErrorHandler): Observable<T, R>;
    <T extends any[], R = void>(errorHandler?: ObserverErrorHandler): Observable<T, R>;
};
/**
 * Create an {@link AsyncObservable} that explicitly supports asynchronous results
 */
export declare const AsyncObservable: {
    new <T extends any[], R = void>(errorHandler?: ObserverErrorHandler): AsyncObservable<T, R>;
    <T extends any[], R = void>(errorHandler?: ObserverErrorHandler): AsyncObservable<T, R>;
};
/**
 * A set of observables.  You can bind events using individual observables or the methods emulating a subset Node's
 * EventEmitter.
 *
 * To maintain type safety, implementers define events as observable child properties.
 */
export declare class EventEmitter {
    emit<This, N extends EventEmitter.NamesOf<This>>(this: This, name: N, ...payload: EventEmitter.PayloadOf<This, N>): void;
    addListener<This, N extends EventEmitter.NamesOf<This>>(this: This, name: N, handler: EventEmitter.ObserverOf<This, N>): void;
    removeListener<This, N extends EventEmitter.NamesOf<This>>(this: This, name: N, handler: EventEmitter.ObserverOf<This, N>): void;
    get eventNames(): string[];
    [Symbol.dispose](): void;
}
export declare namespace EventEmitter {
    /**
     * Legal event names.  If there are no events defined, assume this is an
     * untyped instance and allow any argument.
     */
    type NamesOf<This> = [EventNames<This>] extends [never] ? string : EventNames<This>;
    type EventNames<This> = string & keyof {
        [K in keyof This as This[K] extends Observable ? K : never]: true;
    };
    /**
     * Arguments for an event.  If there are no events defined, assume this is
     * an untyped emitter and allow any argument.
     */
    type PayloadOf<This, E extends string> = [EventPayload<This, E>] extends [never] ? any[] : EventPayload<This, E>;
    type EventPayload<This, E extends string> = This extends {
        [K in E]: Observable<infer T extends any[]>;
    } ? T : never;
    type ObserverOf<This, E extends string> = Observable<PayloadOf<This, E>>;
}
/**
 * An {@link Observable} that proxies to another {@link Observable}.
 *
 * Emits emitted here instead emit on the target {@link Observable}.  Events emitted on the target emit locally via
 * a listener installed by the proxy.
 *
 * This is useful for managing a subset of {@link Observer}s for an {@link Observable}.
 *
 * Note that this "proxy" acts as a proxy but is not a JS {@link Proxy}.
 */
export declare class ObservableProxy extends BasicObservable {
    #private;
    constructor(target: Observable);
    [Symbol.dispose](): void;
    get isAsync(): boolean | undefined;
    get isObserved(): boolean;
    emit: (...payload: any) => any | undefined;
}
//# sourceMappingURL=Observable.d.ts.map