perf: Remove reliance on useEffect in React

refactor: rename getCache to getCacheEntry for clarity and update related references
fix: update tests to reflect changes in cache management functions and improve accuracy
feat: add onComplete utility for benchmark results logging

Author: MattCCC

src/cache-manager.ts

@@ -168,7 +168,7 @@ function isCacheExpired(timestamp: number, maxStaleTime?: number): boolean {
  * @param {number|undefined} cacheTime - Maximum time to cache entry in seconds. 0 or -1 means no expiration.
  * @returns {CacheEntry<T> | null} - The cache entry if it exists and is not expired, null otherwise.
  */
-export function getCache<T>(
+export function getCacheEntry<T>(
   key: string,
   cacheTime?: number,
 ): CacheEntry<T> | null {
@@ -246,7 +246,7 @@ export async function mutate<
     return null;
   }
 
-  const cachedResponse = getCache<ResponseData>(key);
+  const cachedResponse = getCacheEntry<ResponseData>(key);
 
   if (!cachedResponse) {
     return null;
@@ -306,10 +306,28 @@ export function getCachedResponse<
   }
 
   // Retrieve the cached entry
-  const cachedEntry = getCache<
+  const cachedEntry = getCacheEntry<
     FetchResponse<ResponseData, RequestBody, QueryParams, PathParams>
   >(cacheKey, cacheTime);
 
   // If no cached entry or it is expired, return null
   return cachedEntry ? cachedEntry.data : null;
 }
+
+/**
+ * Retrieves a cached response from the internal cache using the provided key.
+ *
+ * @param key - The unique key identifying the cached entry. If null, returns null.
+ * @returns The cached {@link FetchResponse} if found, otherwise null.
+ */
+export function getCache<ResponseData, RequestBody, QueryParams, PathParams>(
+  key: string | null,
+): FetchResponse<ResponseData, RequestBody, QueryParams, PathParams> | null {
+  if (!key) {
+    return null;
+  }
+
+  const entry = _cache.get(key);
+
+  return entry ? entry.data : null;
+}

src/index.ts

@@ -16,7 +16,8 @@ export {
 /** Cache management utilities */
 export {
   generateCacheKey, // Generate cache key from URL and config
-  getCachedResponse, // Get cached response for a key
+  getCache, // Get cached response for a key
+  getCachedResponse, // Get cached response with revalidation
   mutate, // Update cache and notify subscribers
   setCache, // Set cache entry directly
   deleteCache, // Delete cache entry

src/react/index.ts

@@ -1,19 +1,13 @@
-import {
-  useEffect,
-  useCallback,
-  useSyncExternalStore,
-  useMemo,
-  useRef,
-} from 'react';
+import { useCallback, useSyncExternalStore, useMemo, useRef } from 'react';
 import {
   fetchf,
   subscribe,
   buildConfig,
   mutate as globalMutate,
-  setCache,
   generateCacheKey,
   getCachedResponse,
   getInFlightPromise,
+  getCache,
 } from 'fetchff';
 import type {
   DefaultParams,
@@ -28,6 +22,7 @@ import type { UseFetcherResult } from '../types/react-hooks';
 import {
   decrementRef,
   DEFAULT_DEDUPE_TIME_MS,
+  getRefCount,
   incrementRef,
   INFINITE_CACHE_TIME,
 } from './cache-ref';
@@ -131,31 +126,57 @@ export function useFetcher<
 
   // Attempt to get the cached response immediately and if not available, return null
   const getSnapshot = useCallback(() => {
-    const cached = getCachedResponse(
+    const cached = getCache<ResponseData, RequestBody, QueryParams, PathParams>(
       cacheKey,
-      // Stale-While-Revalidate Pattern: By setting -1 always return cached data if available (even if stale)
-      INFINITE_CACHE_TIME,
-      config,
     );
 
+    // Only throw for Suspense if we're in 'reject' mode and have no data
+    if (
+      cacheKey &&
+      config.strategy === 'reject' &&
+      (!cached || (!cached.data && !cached.error))
+    ) {
+      const pendingPromise = getInFlightPromise(cacheKey, dedupeTime);
+
+      if (pendingPromise) {
+        throw pendingPromise;
+      }
+    }
+
     return cached;
-  }, [cacheKey, cacheTime]);
+  }, [cacheKey]);
 
   // Subscribe to cache updates for the specific cache key
   const doSubscribe = useCallback(
     (cb: () => void) => {
-      const unsubscribe = subscribe(cacheKey, (data: FetchResponse | null) => {
-        // Optimistic Updates: Reflect that a fetch is happening, so to catch "fetching" state. This can help with UI updates (e.g., showing loading spinners).
-        if (cacheKey && data && data.isFetching) {
-          setCache(cacheKey, data);
+      incrementRef(cacheKey);
+      const shouldFetch =
+        shouldTriggerOnMount && url && cacheKey && getRefCount(cacheKey) === 1; // Check if no existing refs
+
+      // Initial fetch logic
+      if (shouldFetch) {
+        // Stale-While-Revalidate Pattern: By setting -1 always return cached data if available (even if stale)
+        const cached = getCachedResponse(cacheKey, INFINITE_CACHE_TIME, config);
+
+        if (!cached) {
+          // When the component mounts, we want to fetch data if:
+          // 1. URL is provided
+          // 2. shouldTriggerOnMount is true (so the "immediate" isn't specified or is true)
+          // 3. There is no cached data
+          // 4. There is no error
+          // 5. There is no ongoing fetch operation
+          refetch(false);
         }
+      }
 
-        return cb();
-      });
+      const unsubscribe = subscribe(cacheKey, cb);
 
-      return unsubscribe;
+      return () => {
+        decrementRef(cacheKey, cacheTime, dedupeTime, url);
+        unsubscribe();
+      };
     },
-    [cacheKey],
+    [cacheKey, shouldTriggerOnMount, url, dedupeTime, cacheTime],
   );
 
   const state =
@@ -172,18 +193,6 @@ export function useFetcher<
       PathParams
     >);
 
-  const isUnresolved = !state.data && !state.error;
-  const isFetching = state.isFetching || false;
-
-  // Handle Suspense outside the snapshot function
-  if (isUnresolved && config.strategy === 'reject') {
-    const pendingPromise = getInFlightPromise(cacheKey, dedupeTime);
-
-    if (pendingPromise) {
-      throw pendingPromise;
-    }
-  }
-
   const refetch = useCallback(
     async (forceRefresh = true) => {
       const [currUrl, currConfig, currCacheKey] = currentValuesRef.current;
@@ -222,31 +231,6 @@ export function useFetcher<
     [cacheTime, dedupeTime],
   );
 
-  useEffect(() => {
-    // Load the initial data if not already cached and not currently fetching
-    if (
-      shouldTriggerOnMount &&
-      url &&
-      !state.data &&
-      !state.error &&
-      !state.isFetching
-    ) {
-      // When the component mounts, we want to fetch data if:
-      // 1. URL is provided
-      // 2. shouldTriggerOnMount is true (so the "immediate" isn't specified or is true)
-      // 3. There is no cached data
-      // 4. There is no error
-      // 5. There is no ongoing fetch operation
-      refetch(false);
-    }
-
-    incrementRef(cacheKey);
-
-    return () => {
-      decrementRef(cacheKey, cacheTime, dedupeTime, url);
-    };
-  }, [url, shouldTriggerOnMount, cacheKey, cacheTime]);
-
   const mutate = useCallback<
     UseFetcherResult<
       ResponseData,
@@ -261,15 +245,20 @@ export function useFetcher<
     [cacheKey],
   );
 
+  const isUnresolved = !state.data && !state.error;
+  const isFetching = state.isFetching || false;
+  const isLoading =
+    !!url && (isFetching || (isUnresolved && shouldTriggerOnMount));
+
   // Consumers always destructure the return value and use the fields directly, so
   // memoizing the object doesn't change rerender behavior nor improve any performance here
   return {
     data: state.data,
     error: state.error,
     config: state.config,
     headers: state.headers,
-    isValidating: isFetching,
-    isLoading: !!url && (isFetching || (isUnresolved && shouldTriggerOnMount)),
+    isFetching,
+    isLoading,
     mutate,
     refetch,
   };

src/request-handler.ts

@@ -20,7 +20,12 @@ import {
 } from './inflight-manager';
 import { ABORT_ERROR, CANCELLED_ERROR, FUNCTION, REJECT } from './constants';
 import { prepareResponse, parseResponseData } from './response-parser';
-import { generateCacheKey, getCachedResponse, setCache } from './cache-manager';
+import {
+  deleteCache,
+  generateCacheKey,
+  getCachedResponse,
+  setCache,
+} from './cache-manager';
 import { buildConfig, defaultConfig, mergeConfigs } from './config-handler';
 import { getRetryAfterMs } from './retry-handler';
 import { withPolling } from './polling-handler';
@@ -251,6 +256,8 @@ export async function request<
               ))
           ) {
             setCache(_cacheKey, output);
+          } else {
+            deleteCache(_cacheKey);
           }
 
           notifySubscribers(_cacheKey, output);
@@ -393,11 +400,16 @@ export async function request<
   // If cache key is specified, wrap the request with in-flight management
   const doRequestWithInFlight = _cacheKey
     ? async () => {
-        notifySubscribers(_cacheKey, {
+        // Optimistic Updates: Reflect that a fetch is happening, so to catch "fetching" state. This can help e.g. with UI updates (e.g., showing loading spinners).
+        const inFlightResponse = {
           isFetching: true,
           data: null,
           error: null,
-        });
+          headers: null,
+        };
+        setCache(_cacheKey, inFlightResponse);
+
+        notifySubscribers(_cacheKey, inFlightResponse);
 
         return doRequestOnce();
       }

src/types/react-hooks.ts

@@ -47,7 +47,7 @@ export interface UseFetcherResult<
    * Indicates if the request is currently validating or fetching data.
    * This is true when the request is in progress, including revalidations.
    */
-  isValidating: boolean;
+  isFetching: boolean;
   /**
    * Indicates if the request is currently loading data.
    * This is true when the request is in progress, including initial fetches.

test/benchmarks/utils.ts

@@ -0,0 +1,39 @@
+import chalk from 'chalk';
+
+function onComplete() {
+  // @ts-expect-error this is a Benchmark.js context
+  const results = this.map((bench) => ({
+    name: bench.name,
+    hz: bench.hz,
+    rme: bench.stats.rme,
+    samples: bench.stats.sample.length,
+  }));
+
+  // @ts-expect-error this is a Benchmark.js context
+  results.sort((a, b) => b.hz - a.hz);
+
+  console.log(chalk.bold('\nBenchmark results:'));
+  // @ts-expect-error this is a Benchmark.js context
+  results.forEach((r) => {
+    const name = chalk.yellow(r.name);
+    const ops = chalk.green(`${r.hz.toFixed(2)} ops/sec`);
+    const error = chalk.red(`±${r.rme.toFixed(2)}%`);
+    const samples = chalk.blue(`(${r.samples} runs sampled)`);
+
+    console.log(`${name}: ${ops} ${error} ${samples}`);
+  });
+
+  const fastest = results[0];
+  console.log(chalk.bold.green(`\nFastest is ${fastest.name}`));
+
+  // @ts-expect-error this is a Benchmark.js context
+  results.slice(1).forEach((r) => {
+    const pctSlower = ((fastest.hz - r.hz) / fastest.hz) * 100;
+    const slowerText = chalk.red(`${pctSlower.toFixed(2)}% slower`);
+    console.log(
+      `${chalk.yellow(r.name)} is ${slowerText} than ${chalk.green(fastest.name)}`,
+    );
+  });
+}
+
+export { onComplete };