Dev.to WebDev 🛠 Dev 👁 0 📖 7 min read

1,684 awaits in our codebase, 34 places that run in parallel, and not one allSettled

Concurrency in an application codebase is usually discussed as a technique and shipped as an accident. The question I wanted answered about ours is narrower and more useful: where is this code allowed to do two things at

Concurrency in an application codebase is usually discussed as a technique and shipped as an accident. The question I wanted answered about ours is narrower and more useful: where is this code allowed to do two things at once, and where has somebody decided it must not be?

That is countable. Here is the census.

The subject is Nakodo, 582 TypeScript files, 72,683 lines, Next 16 on Vercel with Postgres behind it.

The whole picture in nine numbers

async keywords            651
await expressions       1,684
Promise.all                34
Promise.allSettled          0
Promise.race                2
for await                   3
.map(async ...)             2
after() call sites         10
void fire-and-forget        3

2.6 awaits per async function, and 34 places in the entire codebase where two of those awaits overlap. Everything else is sequential, which is the default you get by writing the obvious thing, and in most of those cases the obvious thing is also correct: the second query needs the first query's row.

The 34 parallel sites

27 of the 34 pass a literal array, so their width is fixed and readable:

width 9  ×2      width 4  ×5
width 8  ×2      width 3  ×6
width 7  ×1      width 2  ×5
width 6  ×3
width 5  ×3

122 promises in total across those 27 sites. The remaining 7 pass a mapped array, so their width is however many items the caller has.

14 of the 34 are in route files: a page.tsx, a layout.tsx or a route handler. That is the shape of the policy nobody wrote down. Parallelism in this codebase is almost entirely a page load optimisation. A screen needs a campaign, its counters, its allowance, its proposal and four sorted lists, none of which depend on each other, so they go out together and the page waits once instead of nine times.

The widest fan-outs are a CSV export route and an outreach screen, both at nine. The narrowest useful one is on a public surface you can hit right now: the Open Graph image route reads three font files in parallel before drawing anything.

const [besley, archivo, plex] = await Promise.all([
  font("Besley-SemiBold.ttf"),
  font("Archivo-SemiBold.ttf"),
  font("IBMPlexMono-Medium.ttf"),
]);

That is nakodo.app/og/pricing, 37,922 bytes of PNG generated per request, and the card for how it works is the same three reads with a different title. Three parallel file reads is the entire concurrency story of our social cards.

Zero allSettled, which is a decision and also a bug

Not one Promise.allSettled in 72,683 lines. Every parallel site uses Promise.all, so if any one of nine reads rejects, the whole set rejects and the screen fails.

For most of those 14 route-level sites that is right. A campaign screen that renders with eight of its nine reads is a screen showing a number next to a number it does not match, and a page that fails honestly is better than a page that lies quietly. The error boundary catches it and the reader sees a retry rather than a wrong total.

But it is wrong in at least one place, and the census is how I noticed. The admin overview fans out to independent panels: counts of this, recent rows of that, a provider's status. Those panels are not an arithmetic whole, they are a wall of unrelated facts, and one failing provider lookup should blank one panel rather than the page. allSettled with a per-panel fallback is the correct shape there, and that is now on the list.

The rule worth writing down: Promise.all when the results are one answer, allSettled when they are several answers that happen to share a page.

Two races, both of them timeouts

export function withTimeout<T>(promise: Promise<T>, ms: number, error: () => Error): Promise<T> {
  let timer: ReturnType<typeof setTimeout>;
  return Promise.race([
    promise,
    new Promise<never>((_, reject) => { timer = setTimeout(() => reject(error()), ms); }),
  ]).finally(() => clearTimeout(timer));
}

That is one of the two. The other is the same pattern inlined at a call site that races a network check against a five second ceiling. Nothing in this codebase races two real pieces of work against each other to take the first answer, which is the use of race everybody learns first and almost nobody needs.

The important caveat is in the comment above that function in the repository: the losing promise is not cancelled, it is only ignored. I wrote about the whole 42-line concurrency library a while back, and that is the function whose name promises more than it does.

46 loops that are sequential on purpose

225 for (const ...) loops in the codebase, 46 of which contain an await. The common static analysis advice is that an await inside a loop is a performance bug. Here it is the design, and the distribution says why:

lib/pipeline    22
lib/outreach     7
lib/billing      4
lib/research     3
lib/contacts     3
everything else  7

Those are background jobs. Each iteration spends budget at an outside service, and several of those services permit a fixed number of requests per second or per day. A Promise.all over the list would turn a polite worker into a burst that gets refused, and the refusal costs more than the wait. Where the work genuinely can overlap, it goes through a helper with a concurrency limit rather than through Promise.all, so the width is a number somebody chose instead of however long the list happens to be.

This is the part of the census I would defend to a linter. no-await-in-loop as a blanket rule would flag 46 deliberate decisions and the fix for every one of them would be worse than the code. What the 46 do need, and currently do not have, is a one-line comment each saying which limit they are respecting, because the next person to read a sequential loop over a hundred items will reasonably assume it is an oversight.

Ten things that happen after the response

after() is the Next API for work that should not make the user wait. Ten call sites:

  • six after a campaign action, continuing the next step of a long job
  • two after a list page renders, filling in a brand logo that is missing
  • one after an inbound webhook is acknowledged, so the sender gets its 200 immediately
  • one in analytics, so an event never delays a render

The logo one is my favourite because it is the smallest possible example of the pattern: the page renders with what it has, and then, after the bytes have gone out, it fetches a thing off the open web and writes it to the database so the next render is better. You can see the finished version of that on a campaign screen after signing in at nakodo.app, but the public tell is simpler: pages never wait for anything they can repair later, which is part of why how it works answers from the cache before it has thought about anything.

And three void calls, all of them in a single client component that polls for changes, where the fire-and-forget is explicit so a reviewer does not have to wonder whether the missing await is a mistake.

Measurement traps

await is a word. A plain grep counts it in comments and in strings. On this codebase the difference turned out to be small, but any count of a keyword that also appears in prose has to be checked, and 13,660 of these lines are page copy.

Brace matching is the only way to ask about loop bodies. "Does this loop contain an await" needs the body, and the body ends at a matching brace that a regex cannot find. Thirty lines of Python with a depth counter does it, and it is also the step where the census would silently go wrong if a file used braces inside a template literal.

The blind spot I have not solved. Parallelism spelled as two stored promises awaited later is invisible to this census:

const rows = loadRows();        // not awaited yet
const total = countRows();      // also in flight
return { rows: await rows, total: await total };

That is a real pattern, it is a real parallel fan-out, and no grep for Promise.all will find it. If your own numbers come out suspiciously low, that is where to look. I do not believe we use it much, which is itself a claim I cannot currently measure.

What I take from this

  1. Write the two-line rule down. Promise.all for reads that make one answer, allSettled for independent panels, and a concurrency-limited helper for anything whose width comes from a list.
  2. Fix the admin overview. One failing provider lookup should not blank a page of unrelated facts.
  3. Comment the 46 sequential loops. Not to justify them to a linter, but to tell the next reader which outside limit is being respected.
  4. 34 parallel sites in 72,683 lines is a fine answer. Concurrency is where bugs come from, and a codebase that buys it deliberately, on screens, in 34 places, is easier to reason about than one that sprinkles it everywhere a profiler once pointed.

If you run this on your own repo, the number I would print first is not the Promise.all count. It is the allSettled count, because zero means nobody has yet had to decide whether a page is one answer or several.

📰 Read the original article on Dev.to WebDev

Originally published by Dev.to WebDev. Aggregated on AIWithGhost for educational purposes — full credit and traffic to the original publisher.