prefetch<T> method

Future<void> prefetch<T>({
  1. required QueryKey key,
  2. required Future<T> queryFn(),
  3. Duration? staleTime,
})

Prefetch data and store in cache for later use.

This is useful for preloading data that will likely be needed soon, such as when hovering over a link.

// Prefetch on hover
onHover: () async {
  await queryClient.prefetch(
    key: ['user', userId],
    queryFn: () => api.getUser(userId),
  );
}

Implementation

Future<void> prefetch<T>({
  required QueryKey key,
  required Future<T> Function() queryFn,
  Duration? staleTime,
}) async {
  final keyStr = _serializeKey(key);
  final existing = _cache[keyStr];
  final effectiveStaleTime = staleTime ?? defaultStaleTime;

  // Skip if data exists and is fresh
  if (existing != null && !existing.isStale(effectiveStaleTime)) {
    return;
  }

  // Skip if already fetching
  if (_pending.containsKey(keyStr)) {
    await _pending[keyStr];
    return;
  }

  try {
    final future = queryFn();
    _pending[keyStr] = future;
    final data = await future;
    setQueryData(key, data);
  } catch (e) {
    // Silently fail for prefetch
  } finally {
    _pending.remove(keyStr);
  }
}