refreshSilently method
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);
}
}