Three Components, One Request: Designing a Shared Frontend Cache

Consider a dashboard layout where three separate components mount on the initial page load:

┌────────────────────────────────────────────────────────┐
│                   App Shell Header                     │
│  [User Avatar] (Requests: GET /api/user/me)            │
└────────────────────────────────────────────────────────┘
┌───────────────────────────┬────────────────────────────┐
│    Billing Card           │     Team Activity Card     │
│  (Requests:               │   (Requests:               │
│   GET /api/user/me)       │    GET /api/user/me)       │
└───────────────────────────┴────────────────────────────┘

Each component owns its data requirements. When they mount, each component initiates an asynchronous fetch for /api/user/me.

If you rely solely on naive completed-result caching—storing the response only after it arrives—you encounter an immediate problem: all three components trigger before the first request finishes.

Because the cache is empty at the moment each component checks it, all three dispatch duplicate HTTP requests to the backend. While modern HTTP/2 and HTTP/3 allow multiple requests to share a connection (multiplexing streams over TCP or QUIC), you still waste server CPU, redundant database reads, and client memory.

To solve this, a frontend data layer must coordinate in-flight pending requests alongside stored results.

1. What Makes Two Requests Equivalent?

Before writing a single line of caching logic, you must decide what constitutes a cache key.

In a trivial prototype, developers often key by URL:

const cacheKey = "/api/user/me";

In a real application, raw string matching creates subtle bugs and collisions:

1. 1.Authentication and Session Scope: If user A logs out and user B logs in without a full page reload, a key of "/api/user/me" risks serving user A's cached profile to user B. Keys for user-scoped data must incorporate the active tenant or user identifier.
2. 2.Delimiter Collisions: A naive string join like ${scope}:${endpoint} collides when delimiters appear inside values. For example, ["a:b", "c"] and ["a", "b:c"] produce the exact same joined string "a:b:c".
3. 3.Query Parameter Ordering: /api/search?page=1&sort=name and /api/search?sort=name&page=1 represent the same resource, but un-normalized query strings treat them as distinct cache misses.
4. 4.GraphQL and POST Requests: For GraphQL, an operation name and variables are not sufficient: you must also include the document query string (or query hash) and distinguish queries from mutations. Never automatically deduplicate arbitrary POST operations, as POST requests are typically stateful mutations rather than idempotent reads.

To prevent delimiter collisions and order dependency, serialize keys using a JSON array structure with recursive property sorting:

function canonicalize(value: unknown): unknown {
  if (value === null || typeof value !== "object") {
    return value;
  }
  if (Array.isArray(value)) {
    return value.map(canonicalize);
  }
  const sortedObj: Record<string, unknown> = {};
  for (const key of Object.keys(value as Record<string, unknown>).sort()) {
    sortedObj[key] = canonicalize((value as Record<string, unknown>)[key]);
  }
  return sortedObj;
}

export function serializeKey(
  scope: string,
  endpoint: string,
  params?: Record<string, unknown>
): string {
  // A JSON array tuple preserves boundaries and prevents delimiter collisions.
  // canonicalize() recursively sorts nested object keys.
  return JSON.stringify([scope, endpoint, params ? canonicalize(params) : null]);
}

2. A Minimal In-Flight Deduplicator

To prevent duplicate concurrent requests, the cache stores the running Promise in an active registry map. Subsequent callers request the same key, see an active Promise, and subscribe to it directly.

However, naive implementations of this pattern often harbor critical bugs:

• Synchronous errors in `fetcher`: If fetcher() throws synchronously, execution must not settle before the promise is registered, otherwise the rejected promise could be stored permanently and prevent retries.
• Cache clearing while a request is in flight: Calling clear() or invalidate() should prevent an older pending request from repopulating the cache after it settles.
• Old requests settling after replacement: When a request is superseded or invalidated, its finally block must not delete a newer replacement request's entry from the registry map.
• Per-Key Invalidation: Invalidating one key must detach its pending request and invalidate its cache without suppressing writes for other, unrelated in-flight requests.

Here is a minimal teaching implementation in TypeScript demonstrating how to handle these lifecycle edge cases:

type CacheEntry<T> = {
  data: T;
  timestamp: number;
  generation: number;
};

export class RequestDeduplicator<T> {
  private cache = new Map<string, CacheEntry<T>>();
  private inFlight = new Map<string, Promise<T>>();
  private keyGenerations = new Map<string, number>();
  private globalGeneration = 0;
  private ttlMs: number;

  constructor(ttlMs: number = 60_000) {
    this.ttlMs = ttlMs;
  }

  private getGeneration(key: string): number {
    return (this.keyGenerations.get(key) ?? 0) + this.globalGeneration;
  }

  async fetch(key: string, fetcher: () => Promise<T>): Promise<T> {
    // 1. Check existing fresh cache
    const cached = this.cache.get(key);
    if (cached && Date.now() - cached.timestamp < this.ttlMs) {
      return cached.data;
    }

    // 2. Return active in-flight promise if one is already running
    const pending = this.inFlight.get(key);
    if (pending) {
      return pending;
    }

    // 3. Snapshot the current generation for this specific key
    const currentGen = this.getGeneration(key);

    // 4. Defer execution with Promise.resolve().then() to ensure registration
    // completes synchronously before fetcher() can throw, even if fetcher throws synchronously.
    const executionPromise = Promise.resolve()
      .then(() => fetcher())
      .then((data) => {
        // Write to cache only if this key's generation has not been invalidated
        if (this.getGeneration(key) === currentGen) {
          this.cache.set(key, {
            data,
            timestamp: Date.now(),
            generation: currentGen,
          });
        }
        return data;
      })
      .finally(() => {
        // Identity check: only delete if THIS promise is still the active one.
        // Prevents an older settled request from deleting a newer replacement's entry.
        if (this.inFlight.get(key) === executionPromise) {
          this.inFlight.delete(key);
        }
      });

    this.inFlight.set(key, executionPromise);
    return executionPromise;
  }

  invalidate(key: string): void {
    this.cache.delete(key);
    // Detach from in-flight registry so the next fetch starts a fresh request
    this.inFlight.delete(key);
    // Increment generation specifically for this key so the detached request
    // cannot repopulate the cache when it eventually settles.
    this.keyGenerations.set(key, (this.keyGenerations.get(key) ?? 0) + 1);
  }

  clear(): void {
    this.cache.clear();
    this.inFlight.clear();
    this.keyGenerations.clear();
    this.globalGeneration++;
  }
}

Key Mechanics to Notice

1. 1.Deferred Execution via `Promise.resolve().then()`: This guarantees that executionPromise is registered in this.inFlight before any part of fetcher() executes. If fetcher() throws synchronously, the error is handled as a microtask rejection; finally runs after registration, safely cleans up via the identity check, and allows subsequent calls to retry.
2. 2.Per-Key Generation Guards: invalidate(key) increments this.keyGenerations for that key only. Any callers who were already awaiting the older in-flight request will still receive their promise result, but the request will be blocked from repopulating the cache. Crucially, in-flight requests for other keys continue undisturbed.
3. 3.Identity Check on Cleanup: In finally, this.inFlight.get(key) === executionPromise ensures that if invalidate() was called and a replacement request was launched, the older settling request does not inadvertently delete the replacement request from inFlight.

3. Failure Handling and HTTP Status Codes

When writing a fetcher for use with a deduplicator, remember that the standard browser fetch() API does not reject on HTTP 4xx or 5xx status codes. It only rejects on low-level network failures, DNS lookup failures, or explicit request abortions.

If your fetcher does not check response.ok, an HTTP 500 error will resolve successfully, and the error response body will be committed into your cache as valid data!

// Correct fetcher pattern:
async function fetchUserProfile(signal?: AbortSignal): Promise<UserProfile> {
  const response = await fetch("/api/user/me", { signal });
  
  if (!response.ok) {
    // Explicitly throw so the deduplicator knows this request failed
    throw new Error(`HTTP ${response.status}: Failed to load profile`);
  }
  
  return response.json();
}

When fetcher() rejects, the finally block cleans up the inFlight map via the identity check, and the error propagates to all components that subscribed to that shared Promise. The next time a component asks for that key, the cache will see a miss and retry the network call.

4. Shared Cancellation and Reference Counting

What happens if Component A initiates the shared request, but unmounts while the request is still in flight?

If Component A attaches its own AbortController and calls controller.abort() on unmount, it will abort the network request for Component B and Component C as well.

To support safe cancellation across shared callers, the deduplicator must manage the AbortController internally and maintain a subscriber reference count:

type InFlightNode<T> = {
  promise: Promise<T>;
  controller: AbortController;
  subscribers: Set<string>; // Set of unique subscriber IDs
};

export class RefCountedDeduplicator<T> {
  private inFlight = new Map<string, InFlightNode<T>>();

  async subscribe(
    key: string,
    subscriberId: string,
    fetcher: (signal: AbortSignal) => Promise<T>
  ): Promise<T> {
    let node = this.inFlight.get(key);

    if (!node) {
      const controller = new AbortController();
      const subscribers = new Set<string>([subscriberId]);

      let nodeRef: InFlightNode<T>;

      // Defer execution to ensure node registration completes first
      const promise = Promise.resolve()
        .then(() => fetcher(controller.signal))
        .finally(() => {
          // Identity check to avoid deleting a replacement node
          if (this.inFlight.get(key) === nodeRef) {
            this.inFlight.delete(key);
          }
        });

      nodeRef = { promise, controller, subscribers };
      this.inFlight.set(key, nodeRef);
      return promise;
    }

    node.subscribers.add(subscriberId);
    return node.promise;
  }

  unsubscribe(key: string, subscriberId: string): void {
    const node = this.inFlight.get(key);
    if (!node) return;

    node.subscribers.delete(subscriberId);

    // Only abort the underlying network call if NO components remain interested
    if (node.subscribers.size === 0) {
      node.controller.abort();
      this.inFlight.delete(key);
    }
  }
}

The Architectural Trade-Off

Aborting an upstream network request when subscribers.size === 0 saves bandwidth if a user navigates away. However, if your application experiences rapid tab switching, aborting can be counterproductive: letting the request finish and populating the cache means the next tab switch 200ms later is an instant cache hit rather than another cold fetch.

5. Freshness vs. Retention: SWR and Memory Lifecycles

In client-side caching discussions, two concepts are often conflated:

1. 1.Freshness (`staleTime`): How long cached data is considered fresh. In libraries like TanStack Query, staleTime expiration does not immediately schedule a background network request. Instead, it transitions the cached data into a "stale" state. Stale data remains in the cache and can continue to be rendered immediately; background revalidations are triggered by configured user interactions or lifecycle events—such as component remounting, window refocus, or network reconnect.
2. 2.Retention (`gcTime` or idle time): How long unreferenced cached data remains in memory after all components displaying it have unmounted. When this timer expires, data is garbage collected.

Appropriate Use of Cache Strategies

6. Bridging to the UI: Subscriptions and Reactive State

A Promise resolves once. But in a real web interface, data changes over time: background revalidations arrive, mutations invalidate keys, and tabs regain focus.

Sharing a Promise solves the initial mounting race, but it does not provide an ongoing reactive subscription. Once promise.then() executes, the component has no way to know if another component subsequently updated the cache.

To connect this cache to React or other UI frameworks, production libraries implement an Observer/Listener pattern:

┌────────────────────────────────────────────────────────┐
│                   Shared QueryCache                    │
│   Stores: data, status, timestamp, observers Set       │
└───────────────────────────┬────────────────────────────┘
                            │
            Notifies listeners on cache change
                            │
     ┌──────────────────────┼──────────────────────┐
     ▼                      ▼                      ▼
[Component A]          [Component B]          [Component C]
(useSyncExternalStore) (useSyncExternalStore) (useSyncExternalStore)

In modern React (18 and 19), this is built using useSyncExternalStore, which subscribes directly to the cache's change event bus and re-renders components synchronously when cache contents update.

7. Putting It Into Practice: TanStack Query

Rather than hand-rolling a custom cache engine with subscriber buses and garbage collection in production, modern frontend teams use proven libraries like TanStack Query.

Here is how all the principles discussed—scoped keys, checked fetchers, abort signals, freshness, and retention—come together in practice:

import { useQuery } from "@tanstack/react-query";

interface UserProfile {
  id: string;
  name: string;
  email: string;
}

async function fetchUserProfile(
  userId: string,
  signal?: AbortSignal
): Promise<UserProfile> {
  const response = await fetch(`/api/users/${userId}/profile`, { signal });
  
  if (!response.ok) {
    throw new Error(`HTTP ${response.status}: Failed to load user profile`);
  }
  
  return response.json();
}

export function useUserProfile(tenantId: string, userId: string) {
  return useQuery({
    // 1. Scoped, structured key preventing collisions across tenants/users
    queryKey: ["tenant", tenantId, "user", userId, "profile"],

    // 2. Checked fetcher receiving AbortSignal from QueryFunctionContext
    queryFn: ({ signal }) => fetchUserProfile(userId, signal),

    // 3. Freshness: Data is fresh for 2 minutes before being marked stale
    staleTime: 2 * 60 * 1000,

    // 4. Retention: Unused cache entries stay in memory for 10 minutes before eviction
    gcTime: 10 * 60 * 1000,
  });
}

8. Questions Your Design Should Answer

When designing or evaluating a client-side data layer, use this checklist of questions:

• [ ] Request Equivalency: Does your cache key account for user authentication ID, tenant context, and query parameter ordering without delimiter collisions?
• [ ] In-Flight Deduplication: If three components mount simultaneously, does your code share the pending Promise rather than dispatching three requests?
• [ ] Failure Resilience: Does your fetcher check response.ok before returning? Does the in-flight registry clean up properly on both synchronous errors and rejections?
• [ ] Superseded Requests: If an old request settles after an invalidation or after a newer request has started, does your code prevent the old request from overwriting newer cache data?
• [ ] Targeted Invalidation: Does invalidating one key detach its pending request without suppressing cache writes for other, unrelated in-flight requests?
• [ ] Safe Cancellation: If one component unmounts and aborts, does your architecture preserve the in-flight request for other mounted subscribers?
• [ ] Freshness vs. Retention: Does your design distinguish between when data is stale (staleTime) versus when unused memory should be garbage collected (gcTime)?
• [ ] Server Authoritativeness: Do you avoid treating cached offline data as authoritative approval for transactions or access control?