Is an async mutex library a valid alternative to a shared Promise?

Yes. Any in-process mutex, semaphore, or async-lock library that serializes the refresh-and-persist section achieves the same correctness guarantee as the shared-Promise pattern. The shared Promise is just the lightest implementation — it has zero dependencies and leverages the JavaScript event loop's single-threaded nature to make the check-and-set atomic. Both approaches are correct; the choice is style and dependency preference.

Is single-flight enough on its own, or do I also need rotation-merge?

For the in-process concurrency case, single-flight plus rotation-merge is the complete fix — you don't need a lock file. Rotation-merge is the rule that, when the refresh response omits a refresh_token field (Google does this), you keep the previous refresh_token instead of overwriting it with undefined. Without rotation-merge you'll eventually erase your refresh token and force a re-consent even though single-flight is working correctly. Both are small and go together.

Concurrent token refresh: single-flight pattern for OAuth (JavaScript)

Q: What is single-flight for concurrent token refresh?

Single-flight is a concurrency pattern where the first caller to detect an expired access token starts the refresh and stores the in-flight Promise in a shared variable. Every other caller that arrives while the refresh is running awaits that same Promise instead of starting a new refresh. When the one refresh completes, all waiters receive the same result. This guarantees exactly one refresh per expiry event within a single process, regardless of how many concurrent callers exist.

Q: Why must I clear the in-flight Promise in a finally block?

If you clear the Promise in a then handler instead of finally, a failed refresh leaves a rejected Promise wedged in the shared variable forever. Every subsequent caller awaits the stale rejected Promise and immediately re-rejects with the old error, even though the token may have been refreshed by another path or the user may have re-authenticated. Using finally ensures the shared variable is cleared on both success and failure, so the next expiry event can start a fresh refresh.

Q: Does single-flight fix concurrent refresh across multiple processes?

No. Single-flight only coalesces concurrent callers within one process and its event loop. Two separate OS processes each have their own memory and their own in-flight Promise variable, so they cannot see each other's in-progress refresh. If two CLIs, two workers, or two containers share the same credential file, they can still race. For that case you need an inter-process lock — a lock file opened with O_CREAT|O_EXCL, or flock — plus a re-read of the stored token after acquiring the lock.

TL;DR

Store the in-flight refresh as a shared Promise (let inflight = null).
The first caller that sees expiry starts the refresh and assigns to inflight.
Every other caller awaits inflight instead of starting its own refresh.
Clear in finally — not then — so a failed refresh doesn't wedge a stale rejected Promise.
Assign the Promise synchronously (before the first await) so a second caller on the next microtask sees it.

The pattern with code

JavaScript's single-threaded event loop makes the check-and-set atomic: no other code runs between the if (!inflight) check and the inflight = ... assignment. That's why this works without any additional lock.

let inflight = null;            // null when idle, Promise when a refresh is running
let creds = await loadCreds();  // { access_token, refresh_token, expires_at } from your store
const SKEW_MS = 60_000;         // treat token as expired 60s early

function isValid(c) {
  return c?.access_token && c.expires_at - SKEW_MS > Date.now();
}

async function getValidToken() {
  if (isValid(creds)) return creds.access_token;   // fast path — no refresh needed

  // SINGLE-FLIGHT: if a refresh is already running, await THAT one, not a new one
  if (!inflight) {
    inflight = doRefresh(creds)
      .then(next => { creds = next; return next; })
      .finally(() => { inflight = null; });         // clear on both success AND failure
  }
  const refreshed = await inflight;                 // all concurrent callers wait here
  return refreshed.access_token;
}

async function doRefresh(prev) {
  const res = await fetch(TOKEN_URL, { method: "POST", body: form(prev.refresh_token) });
  if (!res.ok) throw new Error(`refresh failed: ${res.status}`);
  const body = await res.json();
  return await persistAtomic(mergeRotation(prev, body));  // see below
}

With 100 concurrent callers hitting getValidToken() on an expired token, exactly one doRefresh runs. The other 99 await its Promise and get the result when it resolves.

Two details that are easy to get wrong

1. Clear in finally, not then. If you write .then(next => { inflight = null; return next; }), a rejected refresh leaves inflight pointing at a rejected Promise. Every caller that arrives after the rejection immediately re-rejects with the stale error. finally clears it on both success and failure so the next call tries a fresh refresh.

2. Assign inflight synchronously before the first await. inflight = doRefresh(creds).then(...).finally(...) is all synchronous expression evaluation (the assignment happens before any microtask yields). A second caller arriving on the very next microtask will see inflight !== null and correctly awaits it. If you assigned inside an await, there would be a window where two callers both see inflight === null and both start a refresh.

Add rotation-merge (required for correctness)

Single-flight handles concurrency; rotation-merge handles persistence. Google's refresh response omits refresh_token entirely; if you overwrite your stored credentials with the response as-is, you lose the refresh token and force a re-consent. The rule: if the response omits refresh_token, keep the old one.

function mergeRotation(prev, res) {
  const merged = { ...res };
  if (!merged.refresh_token && prev?.refresh_token) {
    merged.refresh_token = prev.refresh_token;  // Google: keep the old one
  }
  if (merged.expires_in && !merged.expires_at) {
    merged.expires_at = Date.now() + merged.expires_in * 1000;
  }
  return merged;
}

Proactive refresh reduces the race window

A SKEW_MS of 30–60 seconds treats the token as expired slightly before it actually is. This means callers hit the single-flight path before the real expiry cliff, so instead of 100 requests all discovering expiry at exactly t=0, they discover it at t=−60s — still all funneled through single-flight, but with more headroom for the refresh to complete before any real 401 is possible.

When single-flight is NOT enough

Single-flight only covers one process. If you have:

Multiple CLI invocations running simultaneously against the same ~/.config/app/creds.json
A worker pool with several Node processes each reading a shared credential file
Multiple containers on the same host with a mounted credential volume

… you need to also add a cross-process lock — an exclusive lock file (O_CREAT|O_EXCL) around the refresh-and-persist cycle, with a re-read of the token after acquiring the lock. Single-flight and a cross-process lock solve different problems; use both when credentials are shared across processes.

Using a library

The pattern is small enough to copy from this page. If you'd rather not own it, refresh-guard ships single-flight, rotation-merge, and atomic file persistence as a zero-dependency MIT primitive.

npm i refresh-guard

import { createTokenManager, fileStore } from "refresh-guard";
const tokens = createTokenManager({
  store: fileStore("~/.myapp/creds.json"),
  refresh: async (prev) => fetchNewToken(prev.refresh_token)
});
const access = await tokens.getValidToken();  // single-flight + rotation-merge built in

refresh-guard is by the same team as this guide. Source on GitHub · npm i refresh-guard.

FAQ

What is single-flight for concurrent token refresh?

The first caller to detect an expired access token starts the refresh and stores the in-flight Promise in a shared variable. Every other in-process caller awaits that same Promise. When the single refresh completes, all waiters receive the result. Exactly one refresh per expiry event, regardless of concurrency.

Why must I clear the in-flight Promise in a finally block?

If a refresh fails and you clear inflight only in the success branch (then), the rejected Promise remains wedged in inflight forever. Every subsequent caller immediately re-rejects with the stale error. finally runs on both success and failure, so the next call can start a fresh refresh.

Does single-flight fix concurrent refresh across multiple processes?

No. Single-flight only works within one process and event loop. Multiple OS processes each have their own inflight variable and cannot see each other's in-progress refresh. Add an inter-process lock for the multi-process case.

Is an async mutex library equivalent to a shared Promise?

Yes, for in-process concurrency. Any serializing primitive (mutex, semaphore, async-lock) that wraps the refresh-and-persist section achieves the same result. The shared Promise is just the lightest option — zero dependencies, leverages JavaScript's single-threaded event loop.

Is single-flight alone sufficient, or do I also need rotation-merge?

You need both. Single-flight prevents concurrent refreshes; rotation-merge prevents losing the refresh token on providers (like Google) that omit it from refresh responses. Without rotation-merge, you'll eventually overwrite the refresh token with undefined and force a re-consent.

Concurrent token refresh with single-flight

TL;DR

The pattern with code

Two details that are easy to get wrong

Add rotation-merge (required for correctness)

Proactive refresh reduces the race window

When single-flight is NOT enough

Using a library

FAQ

Further reading