This code defines several classes and mixins for handling pagination, both synchronous and asynchronous.

Classes:

PaginationConfig: Configures retry logic, caching, etc.
    Constructors:
        PaginationConfig({retryAttempts = 3, retryDelay = 1 second, cacheTimeout = 5 minutes, autoCancelFetches = true, maxCacheSize = 100})
    Properties:
        retryAttempts (Type: int): Retry attempts on failure.
        retryDelay (Type: Duration): Delay between retries.
        cacheTimeout (Type: Duration): Cache expiration.
        autoCancelFetches (Type: bool): Cancel ongoing fetch before new one.
        maxCacheSize (Type: int)

PaginationException: Exception for pagination failures.
    Constructors:
      PaginationException(String message, {Object? originalError})
    Properties:
      message (Type: String)
      originalError (Type: Object?)

_CacheEntry<V>: (Internal) Cache entry.  Not part of public API.
    Constructors:
        _CacheEntry(V data)
    Properties:
      data (Type: V)
      createdAt (Type: DateTime)

IPaginator<T>: Interface for all paginators.
    Properties:
        pageSize (Type: int, get/set): Items per page.
        currentPage (Type: int): Current page number (starts at 1).
        hasNextPage (Type: FutureOr<bool>): True if next page exists.
        hasPreviousPage (Type: bool): True if previous page exists.
        isDisposed (Type: bool): True if disposed.
    Methods:
        goToPage(Input: int pageNumber): Jumps to page.
        nextPage() (Output: FutureOr<bool>):  Moves to next page, true if changed.
        previousPage() (Output: FutureOr<bool>): Moves to previous page, true if changed.
        reset(): Resets to initial state.
        currentPageItems (Output: FutureOr<List<T>>): Items for current page.

BasePaginator<T>: Base class, shared logic, debouncing, disposal.
    Constructors:
        BasePaginator({required int initialPageSize, PaginationConfig config = const PaginationConfig()})
    Properties:
      config (Type: PaginationConfig)
      lifecycleStream (Output: Stream<String>):  lifecycle events ("pageChanged", "reset").
      lastError (Type: Exception?)
      isDisposed (Type: bool)
    Methods:
      emitLifecycleEvent(Input: String eventName)
      onPageSizeChanged(Input: int newSize)
      onPageChanged(Input: int newPage)
      onReset()
      dispose(): MUST be called to free resources

PaginationAnalytics<T>: Mixin, provides analytics tracking.
    Properties:
        metrics (Output: Map<String, int>): Unmodifiable map of metrics.
    Methods:
        logPageLoad(): Increments page load count.
        logError(): Increments error count.
        logCacheHit(): Increments cache hit count.

Paginator<T>: Synchronous, in-memory paginator.
    Constructors:
      Paginator({required List<T> items, int pageSize = 10, PaginationConfig? config})
    Properties:
      items(Type: List<T>)
      pageInfo (Output: Map<String, dynamic>)
      totalItems (Output: int)
      totalPages (Output: int)
    Methods:
        _evictOldCacheEntries()
        clearTransforms(): Clears cached transformations.
        map<R>(Input: R Function(T) transform, Output: Paginator<R>): Creates new paginator, transformed items.
        where(Input: bool Function(T) predicate, {Object? cacheKey}, Output: Paginator<T>): Creates new paginator, filtered items.
        sort(Input: int Function(T a, T b) compare, {Object? cacheKey}, Output: Paginator<T>): Creates new paginator, sorted items.

AsyncPaginator<T>: Asynchronous paginator, fetches pages via fetchPage.
    Constructors:
        AsyncPaginator({required Future<List<T>> Function(int pageNumber, int pageSize) fetchPage, int pageSize = 10, PaginationConfig? config, Future<int> Function()? totalItemsFetcher})
    Properties:
        stateStream (Output: Stream<Map<String, dynamic>>): Stream of page state changes.
        isLoading (Output: bool): True if current page loading.
    Methods:
        getPageState(Input: int page, Output: PageState): Get state of a page
        clearCache(): Clears cached pages.

InfinitePaginator<T, C>: Infinite paginator, continuous loading.
    Constructors:
      InfinitePaginator._({required Future<List<T>> Function(int pageSize, dynamic paginationKey) fetchItems, required dynamic Function(List<T> items, dynamic currentKey) updatePaginationKey, required int pageSize, required dynamic initialKey, PaginationConfig config = const PaginationConfig(),})
      InfinitePaginator.pageBased({required Future<List<T>> Function(int pageSize, int pageNumber) fetchItems, int pageSize = 20, int initialPageNumber = 1, PaginationConfig? config,})
      InfinitePaginator.cursorBased({required Future<List<T>> Function(int pageSize, PaginationCursor<C> cursor) fetchItems, required PaginationCursor<C> Function(List<T> newItems) getNextCursor, int pageSize = 20, PaginationCursor<C>? initialCursor, PaginationConfig? config,})

    Properties:
      loadingStream (Output: Stream<bool>)
      items(Output: List<T>)
      isLoading (Output: bool)
      hasMoreItems(Output: bool)
      itemCount (Output: int)
      isDisposed (Output: bool)
      state (Output: Map<String, dynamic>)
    Methods:
      loadMoreItems()
      retry()
      reset()
      dispose()

PaginationCursor<T>: Generic cursor, cursor-based pagination.
    Constructors:
      const PaginationCursor(T value)
    Properties:
      value (Type: T)

Extension Methods:

AsyncPaginatorTransform<T> on AsyncPaginator<T>:
    map<R>(Input: R Function(T) transform, Output: AsyncPaginator<R>): new AsyncPaginator with transformed result.
    where(Input: bool Function(T) predicate, Output: AsyncPaginator<T>): new AsyncPaginator, fetched twice the [pageSize] and applies the filter.

PaginatorTesting<T> on IPaginator<T>:
    validate(): Validates paginator state.

Enums:
PageState:
    initial
    loading
    loaded
    error
