refreshSilently method

Future<void> refreshSilently()

Refreshes the first page while keeping the currently visible items.

Unlike refresh, this does not clear loaded pages. Existing items stay on screen behind a PageableStatus.REFRESHING status and are replaced when the fresh first page arrives. If the fetch fails, the existing items are preserved and the error is reported.

Implementation

Future<void> refreshSilently() async {
  if (useSafeMode && !mounted) return;

  trackOperation('refreshSilently');
  debugAssertNotDisposed();

  // Prevent multiple simultaneous refresh operations
  if (isFetching) {
    _log('Refresh already in progress, waiting...');
    final inFlight = _currentFetchCompleter;
    if (inFlight != null && !inFlight.isCompleted) {
      await inFlight.future;
    }
    return;
  }

  // Cancel any ongoing operations
  _debounceTimer?.cancel();
  _fetchingPages.clear();
  _log('Refreshing data silently');
  final fetchCompleter = _beginFetchOperation();
  final requestId = ++_requestId;

  try {
    final firstPageKey = _firstPageKey;
    _fetchingPages.add(firstPageKey);

    // Update status to REFRESHING
    value = value.copyWith(
      status: PageableStatus.REFRESHING,
      clearError: true,
    );

    final items = await _fetchPageWithRetry(firstPageKey, operation: 'refreshSilently');

    if (requestId != _requestId) {
      _log('refreshSilently result ignored because a newer operation superseded it');
      return;
    }
    if (useSafeMode && !mounted) {
      _log('refreshSilently result ignored because controller is disposed');
      return;
    }
    debugAssertNotDisposed();

    _log('Data refreshed: ${items.length} items');

    // Create new page result
    final pageResult = PageResult<PageKey, Item>(
      pageKey: firstPageKey,
      items: items,
    );

    // Determine the new status
    PageableStatus newStatus;
    PageKey? nextPageKey;
    PageKey? prevPageKey;

    if (items.isEmpty) {
      newStatus = PageableStatus.NO_ITEMS_FOUND;
      _log('No items found after refresh');
    } else {
      final isLastPage = _isLastPage(items);
      if (isLastPage) {
        newStatus = PageableStatus.COMPLETED;
        _log('Refresh completed - no more pages');
      } else {
        newStatus = PageableStatus.LOADED_PAGE;
        _log('Refresh completed - more pages available');
        if (_nextPageKeyGenerator != null) {
          nextPageKey = _nextPageKeyGenerator(firstPageKey, items, items.length);
        }
      }
      if (_prevPageKeyGenerator != null) {
        prevPageKey = _prevPageKeyGenerator(firstPageKey, items, items.length);
      }
    }

    value = PageableView<PageKey, Item>(
      pages: [pageResult],
      status: newStatus,
      nextPageKey: nextPageKey,
      prevPageKey: prevPageKey,
      showLog: value.showLog,
      pageSize: value.pageSize,
    );
    await _persistCache();

  } catch (error, stackTrace) {
    if (requestId != _requestId) return;
    if (useSafeMode && !mounted) return;
    debugAssertNotDisposed();

    _log('Error REFRESHING data: $error');
    value = value.copyWith(
      status: value.hasData ? PageableStatus.LOADED_PAGE : PageableStatus.FIRST_PAGE_ERROR,
      error: error,
      stackTrace: stackTrace,
    );
  } finally {
    _fetchingPages.remove(_firstPageKey);
    _endFetchOperation(fetchCompleter);
  }
}