/**
 * A generic interface for a poller that periodically executes a callback and
 * notifies subscribers of the result. The poller manages its lifecycle
 * automatically, ensuring that polling starts when the first subscriber
 * registers and stops when the last subscriber unsubscribes.
 *
 * The poller caches the most recent value from the callback and immediately
 * delivers it to any new subscriber without waiting for the next polling
 * cycle.
 *
 * Common use cases:
 * - Fetching real-time data updates (notifications, status changes)
 * - Monitoring background tasks or long-running operations
 * - Auto-refreshing dashboards and metrics
 * - Syncing state with server-side changes
 *
 * @example Basic subscription and cleanup
 * ```ts
 * import {
 *     PlatformServiceName,
 *     createLogger,
 * } from '@limetech/lime-web-components';
 *
 * const logger = createLogger('my-component');
 * const http = platform.get(PlatformServiceName.Http);
 *
 * const poller = platform
 *     .get(PlatformServiceName.PollerFactory)
 *     .create((): Promise<number> => http.get('my_addon/unread_count'), 60_000);
 *
 * const unsubscribe = poller.subscribe((unreadCount) => {
 *     logger.debug('Received data', { unreadCount });
 * });
 *
 * // Later, clean up
 * unsubscribe();
 * ```
 *
 * @beta
 * @group Poller
 */
export interface Poller<T> {
    /**
     * Subscribes a callback to receive updates from the poller.
     *
     * A new subscriber immediately receives the latest cached value, and all
     * subscribers are notified of subsequent polling results.
     *
     * The subscription is active until the returned unsubscribe function is
     * called. Unsubscribe during component cleanup (disconnectedCallback) to
     * prevent memory leaks and unnecessary polling when the component is
     * removed from the DOM.
     *
     * @param callback - A function that will be called with the latest value
     * from the poller callback. If no value is available yet, the callback will
     * receive `undefined`. The callback is invoked:
     * - Immediately upon subscription (with cached value or undefined)
     * - After each successful poll cycle
     * - When {@link trigger} is called manually
     * @returns A function to unsubscribe from the poller. Call this function
     * to stop receiving updates and clean up the subscription.
     *
     * @example Unsubscribe when the component is removed
     * ```ts
     * import { State } from '@stencil/core';
     * import {
     *     LimeWebComponentPlatform,
     *     PlatformServiceName,
     * } from '@limetech/lime-web-components';
     *
     * class MyComponent {
     *     public platform: LimeWebComponentPlatform;
     *
     *     @State()
     *     private taskCount: number;
     *
     *     private unsubscribe: () => void;
     *
     *     public connectedCallback() {
     *         const http = this.platform.get(PlatformServiceName.Http);
     *         const poller = this.platform
     *             .get(PlatformServiceName.PollerFactory)
     *             .create(
     *                 (): Promise<number> => http.get('my_addon/task_count'),
     *                 30_000
     *             );
     *
     *         this.unsubscribe = poller.subscribe((taskCount = 0) => {
     *             this.taskCount = taskCount;
     *         });
     *     }
     *
     *     public disconnectedCallback() {
     *         this.unsubscribe();
     *     }
     * }
     * ```
     */
    subscribe(callback: (value?: T) => void): () => void;
    /**
     * Immediately forces the poller to execute its callback.
     *
     * This method triggers an out-of-band poll, resetting the internal timer so
     * that the next regular poll happens at the full interval from now. The
     * trigger happens asynchronously, and all subscribers are notified with the
     * result once the poll completes.
     *
     * Useful for:
     * - Implementing manual refresh buttons
     * - Forcing an update after a user action
     * - Ensuring fresh data before a critical operation
     *
     * @example Refresh on demand
     * ```ts
     * import { PlatformServiceName } from '@limetech/lime-web-components';
     *
     * const http = platform.get(PlatformServiceName.Http);
     *
     * const poller = platform
     *     .get(PlatformServiceName.PollerFactory)
     *     .create(() => http.get('my_addon/import_status'), 60_000);
     *
     * // Refresh now instead of waiting for the next interval
     * poller.trigger();
     * ```
     */
    trigger(): void;
}