file: extensions/stream_controller.dart
dependencies: import 'package:dart_helper_utils/dart_helper_utils.dart';

StreamControllerSafeExtensions: (Extension on `StreamController<T>`)
  Define: Provides safe methods for interacting with `StreamController` instances, handling closed controllers and errors.
  Methods:
    safeAdd(T event): Adds an event if the controller is not closed. Returns `true` on success, `false` otherwise.
    safeAddError(Object error, [StackTrace? stackTrace]): Adds an error if the controller is not closed.  Returns `true` on success, `false` otherwise.
    _handleDynamicOnError(dynamic error, dynamic stackTrace): *Private* Handles dynamic errors, converting them to `Object` and `StackTrace`.
    safeClose(): Closes the controller if it's not already closed. Returns a `Future` that completes when the controller is closed.
    safeAddAll(Iterable<T> events, {Duration? throttleDuration}): Adds multiple events, optionally throttling with a given duration between events. Returns a Future with count of added events.
    safeAddStream(Stream<T> sourceStream): Adds all events from a source stream to the controller.  Handles errors and cancellation. Returns a `Future` with count of added events.
    safeAddFuture(Future<T> future, {void Function(Object error, StackTrace stackTrace)? onError}): Adds the result of a `Future` to the controller when it completes. Handles errors.
    mergeStreams(List<Stream<T>> streams): Merges multiple streams into this controller. Returns a `Future` that completes when all source streams are done.
    asBroadcast(): Converts the controller to a broadcast controller if it isn't already.
    _isClosed(): (bool) *Private* Checks if the controller is closed (heuristic based on `hasListener` for non-broadcast streams).
  Operational Notes:
    Error Handling: `safeAddError` and internal error handling prevent exceptions from being thrown if the controller is closed.
    Cancellation: Handles cancellation of subscriptions when merging streams or adding from a stream if the controller is closed.
    Asynchronous: Many methods return `Future` to handle asynchronous operations.
    Dependencies:  `dart:async`.

StreamTransformations: (Extension on `Stream<T>`)
    Define: Provides additional stream transformations beyond the standard Dart library.
    Methods:
      bufferCount(int count): Buffers events into lists of size `count`.  Emits partial lists on stream completion.
      window(Duration windowDuration): Buffers events into lists based on time windows.
      rateLimit(int maxEvents, Duration duration): Limits event emission rate to `maxEvents` per `duration`.
      asPausable():  Returns a `PausableStream<T>` that allows pausing and resuming the stream.
      withLatestValue(): Returns a new stream that replays the latest emitted value to new subscribers (like a "behavior subject").
    Operational Notes:
        Assertions: Includes assertions to validate input parameters (e.g., `count` and `duration` must be positive).
        Cancellation:  Handles cancellation of internal subscriptions and timers.
        Dependencies: `dart:async`.

StreamErrorRecovery: (Extension on `Stream<T>`)
  Define: Provides error recovery and retry mechanisms for streams.
  Methods:
    retry({int retryCount = 3, Duration delayFactor = const Duration(seconds: 1), bool Function(Object error)? shouldRetry}):  Retries the stream subscription on error, with exponential backoff.
    replaceOnError({required T defaultValue}): Replaces an error event with a default value and then completes the stream.
    completeOnError(): Completes the stream immediately upon encountering an error.
  Operational Notes:
    Retry Logic: Implements exponential backoff for retries.
    Error Handling: Provides options to replace errors with a default value or to complete the stream on error.
    Dependencies: `dart:async`, `dart:math`.

PausableStream: (Class)
  Construct:  Creates a `PausableStream`.
  Parameters:
     _source: (Stream<T>) the stream instance to be wrapped.
  Fields:
    _source: (Stream<T>) - The source stream.
    _controller: (StreamController<T>) - Internal controller for managing the pausable stream.
    _subscription: (StreamSubscription<T>?) - Subscription to the source stream.
    _paused: (bool) - Indicates whether the stream is paused.
    _resumeCompleter: (Completer<void>?) - Completer used to manage resumption after pausing.
  Methods:
    _start(): Initializes and starts the stream subscription.
    pause(): Pauses the stream.
    resume(): Resumes the stream.
    _cancel(): Cancels the stream subscription.
 Getters:
    stream: (Stream<T>, get) - Returns a pausable stream.
  Operational Notes:
     Implements: pause/resume logic by buffering, using Completer.
