import { type Destroyable } from '../lifecycle';
import { type Maybe } from '../value/maybe.type';
import { type Milliseconds } from './date';
import { BaseError } from 'make-error';
/**
 * Returns the number of invocations that have occurred since the period started.
 *
 * When a new period has started, returns 0.
 */
export type TimePeriodCounter = (() => number) & {
    readonly _timePeriodLength: Milliseconds;
    readonly _timePeriodCount: number;
    readonly _lastTimePeriodStart: Date;
    readonly _nextTimePeriodEnd: Date;
    /**
     * Resets the counter.
     *
     * @returns the new period end time.
     */
    readonly _reset: (start?: Date) => Date;
};
/**
 * Creates a counter that tracks invocations within fixed time periods.
 * Returns the number of invocations since the current period started.
 * When a new period begins, the counter resets to 0.
 *
 * @param timePeriodLength - Length of each time period in milliseconds
 * @param lastTimePeriodStart - Optional starting point for the first period
 * @returns A callable counter function with metadata properties
 */
export declare function timePeriodCounter(timePeriodLength: number, lastTimePeriodStart?: Maybe<Date>): TimePeriodCounter;
export type TimerState = 'running' | 'paused' | 'complete' | 'cancelled';
/**
 * Timer object that counts down a fixed duration amount.
 *
 * The timer is not required to start immediately.
 *
 * Once the timer has complete it cannot be reset.
 */
export interface Timer extends Destroyable {
    /**
     * Promise that resolves once the timer is complete, or throws an error if the timer is destroyed before it completes.
     */
    readonly promise: Promise<void>;
    /**
     * Current timer state.
     */
    readonly state: TimerState;
    /**
     * The time the Timer was created originally.
     */
    readonly createdAt: Date;
    /**
     * The last time the timer was paused.
     */
    readonly pausedAt?: Maybe<Date>;
    /**
     * The last started at date, if applicable.
     */
    readonly startedAt?: Maybe<Date>;
    /**
     * The configured duration.
     */
    readonly duration: Milliseconds;
    /**
     * The number of ms remaining.
     *
     * If the timer is paused, this returns null.
     *
     * If the timer is complete, this returns 0.
     */
    readonly durationRemaining: Maybe<Milliseconds>;
    /**
     * Completes the timer immediately.
     */
    completeNow(): void;
    /**
     * Starts the timer if it was not running. Does nothing if already running.
     */
    start(): void;
    /**
     * Stops the timer if it was running. Does nothing if already complete.
     */
    stop(): void;
    /**
     * Resets the timer to start now. If the timer is already complete then this does nothing.
     */
    reset(): void;
    /**
     * Sets a new duration on the timer. IF the timer is already complete this does nothing.
     *
     * If the new duration is less than the remaining duration it stops immediately.
     *
     * @param duration
     */
    setDuration(duration: Milliseconds): void;
}
/**
 * Error thrown when the timer is destroyed before it was completed.
 */
export declare class TimerCancelledError extends BaseError {
    constructor();
}
/**
 * Creates a new Timer from the input duration.
 *
 * @param duration - The duration of the timer.
 * @param startImmediately - Whether the timer should start immediately. Defaults to true.
 * @returns The new Timer.
 */
export declare function makeTimer(duration: Milliseconds, startImmediately?: boolean): Timer;
/**
 * Toggles the input Timer's running state between running and stopped.
 *
 * @param timer - The timer to toggle
 * @param toggleRun - If provided, forces the timer to run (true) or stop (false). Otherwise toggles the current state.
 */
export declare function toggleTimerRunning(timer: Timer, toggleRun?: boolean): void;
/**
 * Returns the approximate end date of the given timer. If a timer is already complete, it returns the time for now.
 *
 * @param timer - the timer whose end date to approximate
 * @returns a Date representing the estimated end time, or null if no duration remains
 */
export declare function approximateTimerEndDate(timer: Timer): Maybe<Date>;