Collapsing Duplicate Requests Into One: A Reference-Counted Single-Flight Layer

Designing the key: what counts as "the same fetch"

The key is what decides how wide the folding reaches. Make it too broad and unrelated fetches get merged; too narrow and the folding never fires at all. The key turned out to sit closer to real incidents than the coalescer itself.

Sort query parameters before folding

The same fetch can arrive with its query in a different order depending on the caller. Treat ?limit=20&cursor=abc and ?cursor=abc&limit=20 as different keys and you get two identical requests side by side. Keep one function that builds keys and route every fetch through it.

export function buildKey(
  method: "GET" | "HEAD",
  path: string,
  query: Record<string, string | number | undefined> = {},
  subject = "anon",
): string {
  const pairs = Object.entries(query)
    .filter(([, v]) => v !== undefined && v !== "")
    .map(([k, v]) => `${k}=${encodeURIComponent(String(v))}`)
    .sort(); // absorb ordering differences here
  const qs = pairs.length ? `?${pairs.join("&")}` : "";
  return `${subject}|${method} ${path}${qs}`;
}

It is one sort() call. But back when keys were written inline at each call site, some screens folded and others did not, and it took a while to accept that the cause was a string rather than the logic.

Put the authenticated subject in the key

Paths that mean "the current user," like /me/entitlements, are the riskiest. Key on the path alone and, right after an account switch, the previous user's in-flight entry is handed out as is. For a value that branches the UI — subscription entitlement, say — a screen that should be free renders as subscribed for a moment.

That is why buildKey above puts subject (a user ID, or a hash of the token) first. Alongside it, drop every in-flight entry at sign-out.

// The entry shape with a controller is built in the next section
export function resetInflight(reason: string) {
  for (const [key, entry] of inflight) {
    entry.controller.abort(); // waiters receive an AbortError
    inflight.delete(key);
  }
  if (__DEV__) console.log(`[coalesce] reset: ${reason}`);
}

Where the entitlement itself comes from is a separate topic, but if you hold subscriptions on your own server, reading this beside Outgrowing RevenueCat: A Self-Hosted Guide to App Store Server Notifications V2 for Rork Apps makes it easier to decide what belongs in the key.

What must never go into the key

Conversely, mix in anything that changes on every call and the folding never happens once. These are the three I actually mixed in:

1. A cache buster built from Date.now()
2. A trace ID minted per request
3. A JSON.stringify of an options object that contained the AbortSignal

The third is the hardest to spot: request counts do not drop at all, yet the implementation looks correct. Keep keys short and human-readable so you can print them straight into a log.

With the key settled, the rest is just putting things into the Map and taking them out. The question is when to delete. That is where the first trap lives.

Trap one: handing out a failed promise forever

The code above never deletes anything. Whether the fetch succeeds or fails, its promise stays in inflight.

If it stays after success, the next caller receives the old result. That is effectively a cache with no expiry — an unintended freeze of freshness.

The failure case is nastier. Once the network drops and the promise rejects, that rejected promise sits in the Map. From then on, everyone calling with the same key gets this "already-failed" promise. Even after signal recovers, they keep seeing the same error until the app restarts. I personally burned half a day reproducing this behavior.

Intuitively you want to "cache the result." But single-flight's job is only to fold the in-flight moment together. Storing results belongs to a different layer, a TTL cache, kept separate. Drawing that line was the crux.

The fix is to delete the entry the instant it settles, whether it resolved or rejected.

const inflight = new Map<string, Promise<unknown>>();
 
function coalesce<T>(key: string, run: () => Promise<T>): Promise<T> {
  const existing = inflight.get(key);
  if (existing) return existing as Promise<T>;
 
  const promise = run().finally(() => {
    // Always delete, on success or failure alike.
    // Forget this and a settled-failed promise keeps being handed out.
    inflight.delete(key);
  });
  inflight.set(key, promise as Promise<unknown>);
  return promise;
}

Placing it in finally matters. Put it only in then and it never fires on reject. That "does not clear on reject" was precisely the shape of the incident.

Trap two: one caller's abort cancels everyone

In React, the convention is to abort an in-flight request when a component unmounts — use an AbortController and call abort() in the cleanup.

Combined with single-flight, the naive version bites. If you pass each caller's own AbortController into the one shared request, the moment the first component to unmount calls abort(), the fetch for everyone still waiting is cancelled too.

Flip tabs quickly and the remaining screen fills with "request aborted." That is a counter-intuitive way to break: aborting is each component's own business, yet the shared single request gets dragged along by it.

The solution is reference counting. Create exactly one AbortController for the shared request and count how many callers are waiting. Actually abort only when nobody is waiting anymore.

type Entry<T> = {
  promise: Promise<T>;
  controller: AbortController;
  refs: number;
};
 
const inflight = new Map<string, Entry<unknown>>();
 
export function coalesce<T>(
  key: string,
  run: (signal: AbortSignal) => Promise<T>,
): { promise: Promise<T>; release: () => void } {
  let entry = inflight.get(key) as Entry<T> | undefined;
 
  if (!entry) {
    const controller = new AbortController();
    const promise = run(controller.signal).finally(() => {
      inflight.delete(key); // trap-one fix: always delete on settle
    });
    entry = { promise, controller, refs: 0 };
    inflight.set(key, entry as Entry<unknown>);
  }
 
  entry.refs += 1;
 
  const release = () => {
    entry!.refs -= 1;
    // Abort only when no one is waiting AND we are still the current entry
    if (entry!.refs <= 0 && inflight.get(key) === entry) {
      entry!.controller.abort();
      inflight.delete(key);
    }
  };
 
  return { promise: entry.promise, release };
}

The inflight.get(key) === entry check is there so that an old entry's release does not mistakenly delete a newer entry created later. I dropped that one line once and lost time chasing a rare mix-up. It is unglamorous but non-negotiable.

Wiring it into React: useCoalescedQuery

With the coalescer in place, the hook just calls it. Fetch on mount, release on unmount, and swallow the abort that comes from your own release.

import { useEffect, useRef, useState } from "react";
import { coalesce } from "./request-coalescer";
 
type State<T> =
  | { status: "loading" }
  | { status: "success"; data: T }
  | { status: "error"; error: unknown };
 
export function useCoalescedQuery<T>(
  key: string | null,
  fetcher: (signal: AbortSignal) => Promise<T>,
): State<T> {
  const [state, setState] = useState<State<T>>({ status: "loading" });
  const fetcherRef = useRef(fetcher);
  fetcherRef.current = fetcher; // always the latest per render
 
  useEffect(() => {
    if (key === null) return;
    let alive = true;
    setState({ status: "loading" });
 
    const { promise, release } = coalesce(key, (signal) =>
      fetcherRef.current(signal),
    );
 
    promise.then(
      (data) => {
        if (alive) setState({ status: "success", data: data as T });
      },
      (error) => {
        // Ignore aborts that came from our own release
        if (alive && (error as { name?: string }).name !== "AbortError") {
          setState({ status: "error", error });
        }
      },
    );
 
    return () => {
      alive = false;
      release();
    };
  }, [key]);
 
  return state;
}

The fetcher takes the signal and passes it straight to fetch.

async function fetchEntitlements(signal: AbortSignal) {
  const res = await fetch(`${API}/me/entitlements`, {
    headers: { Authorization: `Bearer ${await getToken()}` },
    signal,
  });
  if (!res.ok) throw new Error(`entitlements ${res.status}`);
  return (await res.json()) as Entitlements;
}

Now, as long as you pass the same key, no matter how many components call it, the actual network request is folded to one.

Trap three: the request count doubles in development only

The morning after I added reference counting and called it done, I opened the inspector again and /me/entitlements was still listed twice. One of the two carried the abort marker. I had counting in place and still could not get to one request, and for a while I just sat there.

React StrictMode was behind it. In development builds, StrictMode runs every effect twice in the order setup → cleanup → setup. From the point of view of useCoalescedQuery, that means release is called once immediately after mount. Even with three screens asking for the same key, the moment all three of those first cleanups run, refs drops to zero, the in-flight request is aborted right there, and the second round of setups fires a fresh one.

I reproduced the same ordering locally and counted the fetches that actually ran, with three callers asking for one key.

StrictMode is off in release builds, so none of this doubling reaches your users. But if the number you look at during development is always twice the real one, your fold-rate instrument is wrong and so is every decision you draw from it. While I was rereading the coalescer convinced the implementation was broken, what was actually broken was the premise of the measurement. If any of this looks familiar, I may be missing a subtler cause in your case, but StrictMode is worth suspecting before the code is.

The fix is plain enough. Do not abort the instant refs hits zero — wait for one beat. If someone comes back during that beat, cancel the abort you scheduled.

type Entry<T> = {
  promise: Promise<T>;
  controller: AbortController;
  refs: number;
  pendingAbort: ReturnType<typeof setTimeout> | null;
};
 
const inflight = new Map<string, Entry<unknown>>();
const ABORT_GRACE_MS = 0; // one setTimeout tick is enough to span StrictMode's round trip
 
export function coalesce<T>(
  key: string,
  run: (signal: AbortSignal) => Promise<T>,
): { promise: Promise<T>; release: () => void } {
  let entry = inflight.get(key) as Entry<T> | undefined;
 
  if (!entry) {
    const controller = new AbortController();
    const promise = run(controller.signal).finally(() => {
      inflight.delete(key); // trap one: always delete on settle
    });
    entry = { promise, controller, refs: 0, pendingAbort: null };
    inflight.set(key, entry as Entry<unknown>);
  }
 
  // someone came back, so cancel the abort we scheduled
  if (entry.pendingAbort !== null) {
    clearTimeout(entry.pendingAbort);
    entry.pendingAbort = null;
  }
 
  entry.refs += 1;
 
  let released = false; // calling the same release twice must do nothing
  const release = () => {
    if (released) return;
    released = true;
    entry!.refs -= 1;
    if (entry!.refs > 0) return;
 
    entry!.pendingAbort = setTimeout(() => {
      if (entry!.refs <= 0 && inflight.get(key) === entry) {
        entry!.controller.abort();
        inflight.delete(key);
      }
    }, ABORT_GRACE_MS);
  };
 
  return { promise: entry.promise, release };
}

A grace of 0 is enough, because a single setTimeout already spans the gap between StrictMode's cleanup and its second setup. On tabs the user flips back and forth, stretching it to 50–100ms also saves the refetch when they return. The longer you make it, though, the longer a genuinely abandoned request keeps running. What worked for me was leaving the default at zero and raising it only on the few screens that see heavy back-and-forth.

The released flag earns its line too. As the conditions around a caller grow, cleanups really do run twice. Without the flag, refs goes negative and the abort fires while someone is still waiting. When I checked it locally, one of two callers calling release twice was enough to hand the other one — which had done nothing wrong — an AbortError.

The right to stop something shared belongs to the last person leaving, one beat after they are gone. I thought reference counting had already drawn that line, and StrictMode showed me it had not. Looking back, the hard part was never the counting itself but deciding when the counting is finished.

What you must not coalesce: writes

Coalescing works only for reads — where calling repeatedly yields the same result. Get this wrong and you lose data silently.

I once thought I could prevent a double-tapped submit button with single-flight, and wrote this.

// Do not do this
coalesce("POST /posts", (signal) => createPost(draft, signal));

The second tap receives the first tap's in-flight promise. It looks like duplicate creation was prevented. But the different draft the second tap was holding never got sent — it vanished. One of the user's actions was quietly thrown away.

Where you kill duplication depends on the layer, and each layer protects something different. I keep these three separate from the start.

Preventing duplicate writes belongs to idempotency keys, not to coalescing. That separation becomes clear when you set it beside the companion piece on hardening network calls, Hardening API Calls in a Rork App: Token Refresh, Retries, and Idempotency. Single-flight removes duplicate reads; idempotency keys neutralize duplicate writes. They protect fundamentally different things.

Calming the token-refresh thundering herd

The mysterious logouts at the start were exactly where this read-side folding helps. Several requests notice the expired token at once and each fires a refresh. A refresh looks like a write, but in the sense of "obtain one new access token from the same refresh token," folding the concurrent runs into one and sharing the result is the correct move.

Coalesce the refresh itself under a fixed key.

function refreshAccessToken() {
  const { promise } = coalesce("auth:refresh", async (signal) => {
    const res = await fetch(`${API}/auth/refresh`, {
      method: "POST",
      body: JSON.stringify({ refresh: getRefreshToken() }),
      signal,
    });
    if (!res.ok) throw new Error(`refresh ${res.status}`);
    return (await res.json()) as { access: string };
  });
  // Never call release here: we do not want a waiting caller to abort the
  // refresh. The finally on settle still cleans the entry up.
  return promise;
}

By not calling release, a waiting caller's whim can no longer cancel the refresh. Even with three overlapping 401s, exactly one refresh goes out. Everyone shares that single result and retries with the new token. Logouts from token mix-ups stopped happening after this.

Verify it with a count, not with your eyes

Stare at the network inspector, decide "it looks like fewer requests," and the next screen you add quietly undoes it. I prefer to land the instrument that counts the fold rate before migrating anything.

Counting calls and actual runs inside the coalescer is enough.

const stats = { calls: 0, runs: 0 };
 
export function coalesceStats() {
  const { calls, runs } = stats;
  return { calls, runs, foldRate: calls ? 1 - runs / calls : 0 };
}

Add stats.calls += 1 at the top of coalesce and stats.runs += 1 right before run() actually fires. Print the value five seconds after launch and the folding becomes visible at a glance. On my side the equivalent figure was 0 before, and settled around 0.4 to 0.5 right after launch once it was in. If it stays near 0, the likely cause is a key that changes every call, not the implementation.

To stop regressions, one test is enough. Call three times with the same key and assert the fetch runs once.

it("concurrent calls with the same key fold into one", async () => {
  let runs = 0;
  const run = () =>
    new Promise<number>((resolve) => {
      runs += 1;
      setTimeout(() => resolve(runs), 10);
    });
 
  const a = coalesce("GET /x", run);
  const b = coalesce("GET /x", run);
  const c = coalesce("GET /x", run);
 
  await Promise.all([a.promise, b.promise, c.promise]);
  expect(runs).toBe(1);
 
  // after settle, a fresh request runs (regression test for trap one)
  const d = coalesce("GET /x", run);
  await d.promise;
  expect(runs).toBe(2);
});

The last three lines are the ones that earn their keep. The day someone — usually me, six months later — moves the delete from finally into then, this is what fails. Having burned half a day reproducing that behavior once, those three lines are worth more to me than they look.

In production, the effect shows up in how launch feels more than in raw request counts. The setup I use to keep watching launch weight over time is written up separately in Rork × MetricKit — Building a Solo Diagnostics Pipeline for Crashes, Hangs, and Battery Drain.

The numbers I saw in production

I observed before and after on the one app with the most users out of the six. The averages are over 20 cold starts (launching from a fully terminated state).

More than the drop in request count, the last row mattered most to me. The hard-to-trace logouts were gone. A fault that had been happening out of the user's sight closed with a single move — folding requests together. I was quietly relieved.

Where to start

First, attach a network inspector right after launch and look for the same URL repeated. If it is, that is your first target. Entitlements, user profile, remote config — reads referenced from several screens are usually the candidates.

Remote config in particular is a strong candidate, since nearly every screen pulls it at launch. The distribution side of flags is covered in Making Feature Flags Survive Production: Kill Switches and Gradual Rollouts in Rork Max, and how the received values stack against defaults and user preferences in Resolving App Config in Three Layers: Merging Defaults, User, and Remote With Bounded Overrides. Keeping the layer that folds fetches separate from the layer that decides values lets you swap either one later without touching the other.

The coalescer fits in one file. You do not need to rewrite all existing fetch code at once. Swap only the reads that are firing in duplicate onto coalesce, and as long as you keep the three points — deleting in finally, the reference count, and the grace before aborting — it starts helping from the moment you swap it in.

I am still working on my own networking base. I hope this is of some use to anyone facing the same problem. Thank you for reading.