Debouncer: Consolidates rapid events, scheduling actions after a delay.

  Constructors:
    Debouncer(Input: Duration delay, Duration? maxWait, bool immediate = false, Function(Object, StackTrace)? onError, String? debugLabel, int maxHistorySize = 0, LoggerFunction? logger, TimerFactory? timerFactory)
      - delay (required, > 0): Sets wait time after last call before action execution.
      - maxWait (optional, > delay): Sets maximum wait time before forced execution.
      - immediate (default: false): If true, first call in a burst executes immediately, subsequent calls are debounced.
      - onError (optional): Callback for errors during action.
      - debugLabel (optional): String, used for any log message.
      - maxHistorySize(default 0, >=0): Sets how many past execution records to store.
      - logger (optional): Custom logging function.
      - timerFactory(optional): Provide custom timer creation. Default to [Timer].

  Types:
    - LoggerFunction: typedef void Function(String message)
    - TimerFactory: typedef Timer Function(Duration duration, void Function() callback)
    - AsyncAction: typedef FutureOr<void> Function()
    - DebouncerState: Immutable snapshot of Debouncer state, fields include isRunning, isDisposed, executionCount, lastExecutionTime, remainingTime, remainingMaxWait, isPaused.

  Properties:
    - stateStream (Output: Stream<DebouncerState>): Emits state updates.
    - executionCount (Output: int): Total action executions.
    - lastExecutionTime (Output: DateTime?): Last execution timestamp.
    - isRunning (Output: bool): True if action scheduled.
    - isDisposed (Output: bool): True if disposed.
    - isPaused (Output: bool): True if paused.
    - remainingTime (Output: Duration?): Remaining time until next execution.
    - remainingMaxWait (Output: Duration?): Time until maxWait forces execution.
    - timeSinceLastExecution (Output: Duration?): Duration since last execution.
    - averageExecutionTime (Output: Duration?): Mean execution time of successful actions.
    - executionHistory (Output: List<Map<String, dynamic>>): Past execution records.
    - currentState (Output: DebouncerState): Snapshot of current state.

  Methods:
    - run(Input: AsyncAction): Schedules action, immediate execution depends on 'immediate' flag.
    - flush(Output: Future<void>): Executes pending action, cancels timers.
    - tryFlush(Output: Future<bool>): Attempts to flush, returns true if action flushed.
    - runIfNotPending(Input: AsyncAction, Output: bool): Runs if no action pending, true if scheduled.
    - cancel(): Cancels pending action, resets timers.
    - reset(): Resets state, clears history/timers.
    - pause(): Pauses, cancels timers, pending action resumes on 'resume'.
    - resume(): Resumes, schedules pending actions.
    - dispose(): Disposes, cancels actions, closes state stream.
