import { ThrowableError, AsyncIteratorClass } from '@orpc/shared';

interface PublisherOptions {
    /**
     * Maximum number of events to buffer for async iterator subscribers.
     *
     * If the buffer exceeds this limit, the oldest event is dropped.
     * This prevents unbounded memory growth if consumers process events slowly.
     *
     * Set to:
     * - `0`: Disable buffering. Events must be consumed before the next one arrives.
     * - `1`: Only keep the latest event. Useful for real-time updates where only the most recent value matters.
     * - `Infinity`: Keep all events. Ensures no data loss, but may lead to high memory usage.
     *
     * @default 100
     */
    maxBufferedEvents?: number;
}
interface PublisherSubscribeListenerOptions {
    /**
     * Resume from a specific event ID
     */
    lastEventId?: string | undefined;
    /**
     * Triggered when an error occur
     */
    onError?: (error: ThrowableError) => void;
}
interface PublisherSubscribeIteratorOptions extends Pick<PublisherSubscribeListenerOptions, 'lastEventId'>, Pick<PublisherOptions, 'maxBufferedEvents'> {
    /**
     * Abort signal, automatically unsubscribes on abort
     */
    signal?: AbortSignal | undefined | null;
}
declare abstract class Publisher<T extends Record<string, object>> {
    private readonly maxBufferedEvents;
    constructor(options?: PublisherOptions);
    /**
     * Publish an event to subscribers
     */
    abstract publish<K extends keyof T & string>(event: K, payload: T[K]): Promise<void>;
    /**
     * Subscribes to a specific event using a callback function.
     * Returns an unsubscribe function to remove the listener.
     *
     * @remarks
     * This method should be protected to avoid conflicts with `subscribe` method
     */
    protected abstract subscribeListener<K extends keyof T & string>(event: K, listener: (payload: T[K]) => void, options?: PublisherSubscribeListenerOptions): Promise<() => Promise<void>>;
    /**
     * Subscribes to a specific event using a callback function.
     * Returns an unsubscribe function to remove the listener.
     *
     * @example
     * ```ts
     * const unsubscribe = publisher.subscribe('event', (payload) => {
     *   console.log(payload)
     * }, {
     *   lastEventId,
     *   onError: (error) => {
     *     // handle error (consider unsubscribe if error can't be recovered)
     *   }
     * })
     *
     * // Later
     * unsubscribe()
     * ```
     */
    subscribe<K extends keyof T & string>(event: K, listener: (payload: T[K]) => void, options?: PublisherSubscribeListenerOptions): Promise<() => Promise<void>>;
    /**
     * Subscribes to a specific event using an async iterator.
     * Useful for `for await...of` loops with optional buffering and abort support.
     *
     * @example
     * ```ts
     * for await (const payload of publisher.subscribe('event', { signal, lastEventId })) {
     *   console.log(payload)
     * }
     * ```
     */
    subscribe<K extends keyof T & string>(event: K, options?: PublisherSubscribeIteratorOptions): AsyncIteratorClass<T[K], void, void>;
}

export { Publisher };
export type { PublisherOptions, PublisherSubscribeIteratorOptions, PublisherSubscribeListenerOptions };