import type { Duration } from '@alwatr/parse-duration';
/**
 * A highly optimized utility module to handle asynchronous flow control,
 * microtask batching, and reactive scheduling gates within the Alwatr ecosystem.
 *
 * Provides promise-based waiting utilities for timeouts, animation frames,
 * idle callbacks, DOM events, and event loop cycles.
 */
export declare const delay: {
    /**
     * Pauses the execution flow for a specified duration.
     *
     * Supports both milliseconds (as a number) and duration string formats (e.g., `'1.5s'`, `'10m'`).
     *
     * @param duration - The duration to wait. Can be a number in milliseconds or a string duration (e.g., `'500ms'`, `'2s'`).
     * @returns A Promise that resolves after the specified duration.
     *
     * @example
     * ```ts
     * await delay.by(100); // Wait for 100 milliseconds
     * await delay.by('2s'); // Wait for 2 seconds
     * ```
     */
    readonly by: (duration: Duration) => Promise<void>;
    /**
     * Suspends execution flow sequentially until the next browser repaint.
     *
     * Useful for synchronizing animations and DOM updates with the browser's rendering cycle.
     * Resolves with the high-resolution timestamp of the frame.
     *
     * @returns A Promise that resolves with a `DOMHighResTimeStamp`.
     *
     * @example
     * ```ts
     * const timestamp = await delay.animationFrame();
     * updateDOM();
     * ```
     */
    readonly animationFrame: () => Promise<DOMHighResTimeStamp>;
    /**
     * Suspends execution flow until the next two consecutive animation frames have occurred.
     *
     * Ensures that any pending DOM updates have been rendered before resuming execution.
     * Resolves after the second animation frame, providing a safe point to perform post-render calculations.
     *
     * @returns A Promise that resolves after two animation frames.
     *
     * @example
     * ```ts
     * await delay.nextRender();
     * performPostRenderCalculations();
     * ```
     */
    readonly nextRender: () => Promise<DOMHighResTimeStamp>;
    /**
     * Postpones execution until the browser's event loop becomes idle.
     *
     * Ideal for scheduling non-critical background tasks without impacting UI responsiveness.
     *
     * @param options - Optional configuration options for the idle callback (e.g., `timeout`).
     * @returns A Promise that resolves with an `IdleDeadline` object.
     *
     * @example
     * ```ts
     * const deadline = await delay.idleCallback({ timeout: 1000 });
     * if (deadline.timeRemaining() > 0) {
     *   performBackgroundWork();
     * }
     * ```
     */
    readonly idleCallback: (options?: IdleRequestOptions) => Promise<IdleDeadline>;
    /**
     * Pauses the execution flow until a specific DOM event fires on an HTMLElement.
     *
     * Automatically removes the event listener once the event fires to prevent memory leaks.
     *
     * @param element - The target HTMLElement to listen on.
     * @param eventName - The name of the event to wait for (e.g., `'click'`).
     * @param options - Optional event listener options. Defaults to `{ passive: true }`.
     * @returns A Promise that resolves with the fired event object.
     *
     * @example
     * ```ts
     * const clickEvent = await delay.domEvent(button, 'click');
     * console.log('Button clicked!', clickEvent);
     * ```
     */
    readonly domEvent: <T extends keyof HTMLElementEventMap>(element: HTMLElement, eventName: T, options?: AddEventListenerOptions) => Promise<HTMLElementEventMap[T]>;
    /**
     * Pauses execution flow until a specific event fires on any EventTarget.
     *
     * A generic version of `domEvent`. Automatically removes the event listener
     * once the event fires to prevent memory leaks.
     *
     * @param target - The target object to listen on (e.g., `window`, `document`, or custom EventTarget).
     * @param eventName - The name of the event to wait for.
     * @param options - Optional event listener options. Defaults to `{ passive: true }`.
     * @returns A Promise that resolves with the fired event object.
     *
     * @example
     * ```ts
     * await delay.event(window, 'resize');
     * console.log('Window was resized');
     * ```
     */
    readonly event: (target: EventTarget, eventName: string, options?: AddEventListenerOptions) => Promise<Event>;
    /**
     * Schedules a task on the absolute earliest boundary of the next event loop cycle.
     *
     * Bypasses the HTML-standard 4ms minimum nesting delay penalty of `setTimeout(..., 0)`
     * by utilizing a private `MessageChannel` connection.
     *
     * @returns A Promise that resolves in the next macrotask.
     *
     * @example
     * ```ts
     * console.log('Current task');
     * await delay.nextMacrotask();
     * console.log('Next macrotask');
     * ```
     */
    readonly nextMacrotask: () => Promise<void>;
    /**
     * Queues a task on the microtask queue.
     *
     * Pushes the task straight to the native microtask queue, which is guaranteed to
     * run before the browser repaints or any sibling macrotasks intercept control.
     *
     * @returns A Promise that resolves in the next microtask.
     *
     * @example
     * ```ts
     * console.log('Current task');
     * await delay.nextMicrotask();
     * console.log('Next microtask (before repaints and macrotasks)');
     * ```
     */
    readonly nextMicrotask: () => Promise<void>;
    /**
     * Schedules a batch of tasks to run during the browser's idle periods.
     *
     * Allows you to group multiple non-urgent tasks together, which will execute when the browser is idle.
     * This can help improve performance by reducing the number of individual idle callbacks and minimizing overhead.
     */
    readonly scheduleIdleBatch: (options?: IdleRequestOptions) => Promise<void>;
};
//# sourceMappingURL=delay.d.ts.map