Async Execution-Shape Anti-Patterns — Find the Bug¶

Category: Async Anti-Patterns → Execution Shape — async control flow that runs differently than the code reads. Covers (collectively): await in a Loop · Promise Chain Hell / Callback Pyramid · Mixing Callbacks and Promises

This file is critical-reading practice. Each snippet below is a plausible chunk of real-world async code in JavaScript, TypeScript, or Python (asyncio). Read it the way a careful reviewer does and answer three questions:

What's the execution-shape problem? Is the impact performance or correctness? How would you fix it?

Execution-shape bugs are insidious because the code reads fine line by line. The defect is in the shape of the control flow — work that serializes when it could parallelize (a perf bug that quietly makes an endpoint 50× slower), or work the caller thinks it awaited but didn't (a correctness bug that ships incomplete data). Some snippets here crash; most don't. The dangerous ones return a plausible-looking result that is wrong, or return before the work is done.

One snippet is a trap: it looks like a needlessly serial loop you should "fix" with Promise.all, but it is correctly sequential and parallelizing it would break it. Spotting that is the same skill in reverse — read what the code depends on, not just its shape.

How to use this file: read each snippet and write your own diagnosis before expanding the collapsible. The skill you're training is seeing the execution shape, not recalling the name.

Table of Contents¶

1. The dashboard that got slow
2. Sending the welcome emails
3. Mapping users to profiles
4. Importing the whole catalog
5. The retry wrapper that fires twice
6. The order pipeline
7. Validating the migration, one row at a time
8. The cache loader
9. Fanning out the asyncio gather
10. The chained transform
11. The file processor that returns early
12. Promisifying the database driver
13. The pagination crawler
14. The reduce that lost its order

Snippet 1 — The dashboard that got slow¶

// JS — builds a dashboard payload; an HTTP handler under a 2s SLA
async function buildDashboard(userId) {
  const profile  = await getProfile(userId);        // ~120ms
  const orders   = await getRecentOrders(userId);   // ~140ms
  const messages = await getUnreadMessages(userId);  // ~110ms
  const billing  = await getBillingSummary(userId);  // ~160ms
  const feed     = await getActivityFeed(userId);    // ~200ms

  return { profile, orders, messages, billing, feed };
}

What's the execution-shape problem? Perf or correctness? How would you fix it?

async function buildDashboard(userId) {
  const [profile, orders, messages, billing, feed] = await Promise.all([
    getProfile(userId),
    getRecentOrders(userId),
    getUnreadMessages(userId),
    getBillingSummary(userId),
    getActivityFeed(userId),
  ]);
  return { profile, orders, messages, billing, feed };
}

Snippet 2 — Sending the welcome emails¶

// JS — onboard a batch of newly-imported users
async function onboard(users) {
  users.forEach(async (user) => {
    await createAccount(user);
    await sendWelcomeEmail(user);
  });

  console.log(`Onboarded ${users.length} users`);
  return { onboarded: users.length };
}

What's the execution-shape problem? Perf or correctness? How would you fix it?

// Concurrent — fastest, if the downstream can take the load:
async function onboard(users) {
  await Promise.all(users.map(async (user) => {
    await createAccount(user);
    await sendWelcomeEmail(user);
  }));
  console.log(`Onboarded ${users.length} users`);
  return { onboarded: users.length };
}

// Sequential — if order or rate-limiting matters:
//   for (const user of users) { await createAccount(user); await sendWelcomeEmail(user); }

Snippet 3 — Mapping users to profiles¶

// TS — assemble enriched profiles for a list of ids
async function enrich(ids: string[]): Promise<Profile[]> {
  const profiles = ids.map(async (id) => {
    const user = await getUser(id);
    const prefs = await getPrefs(id);
    return { ...user, prefs };
  });

  return profiles;   // TS: this returns Promise<Profile>[], not Profile[]
}

// caller:
const profiles = await enrich(ids);
console.log(profiles[0].prefs.theme);   // undefined — .prefs is on a Promise

What's the execution-shape problem? Perf or correctness? How would you fix it?

async function enrich(ids: string[]): Promise<Profile[]> {
  return Promise.all(
    ids.map(async (id) => {
      const [user, prefs] = await Promise.all([getUser(id), getPrefs(id)]);
      return { ...user, prefs };
    }),
  );
}

Snippet 4 — Importing the whole catalog¶

// JS — nightly job: re-index every product into the search engine
async function reindexAll() {
  const ids = await db.allProductIds();   // ~2,000,000 ids
  await Promise.all(
    ids.map((id) => indexProduct(id)),    // each does a DB read + an HTTP PUT
  );
  console.log("Reindex complete");
}

What's the execution-shape problem? Perf or correctness? How would you fix it?

import pLimit from "p-limit";

async function reindexAll() {
  const ids = await db.allProductIds();
  const limit = pLimit(20);   // at most 20 in flight at once
  await Promise.all(ids.map((id) => limit(() => indexProduct(id))));
  console.log("Reindex complete");
}

Snippet 5 — The retry wrapper that fires twice¶

// JS — wrap a Node-style callback API in a Promise, with one retry
function fetchWithRetry(key, callback) {
  store.get(key, (err, value) => {
    if (err) {
      store.get(key, (err2, value2) => {       // retry once
        if (err2) callback(err2);
        callback(null, value2);                // <-- no return
      });
    }
    callback(null, value);                     // <-- runs even on the error path
  });
}

// caller:
fetchWithRetry("config", (err, value) => {
  if (err) return console.error(err);
  applyConfig(value);                          // sometimes applied twice
});

What's the execution-shape problem? Perf or correctness? How would you fix it?

import { promisify } from "node:util";
const getAsync = promisify(store.get.bind(store));

async function fetchWithRetry(key) {
  try {
    return await getAsync(key);
  } catch {
    return await getAsync(key);   // exactly one retry; a single return path
  }
}

Snippet 6 — The order pipeline¶

// JS — process an order through validation, payment, fulfilment, receipt
function processOrder(order) {
  return validate(order)
    .then((valid) => {
      return charge(valid.customer, valid.total)
        .then((payment) => {
          return fulfil(valid.items)
            .then((shipment) => {
              return sendReceipt(valid.customer, payment, shipment)
                .then(() => {
                  return { orderId: valid.id, shipped: shipment.tracking };
                });
            });
        });
    });
}

What's the execution-shape problem? Perf or correctness? How would you fix it?

async function processOrder(order) {
  const valid    = await validate(order);
  const payment  = await charge(valid.customer, valid.total);
  const shipment = await fulfil(valid.items);
  await sendReceipt(valid.customer, payment, shipment);
  return { orderId: valid.id, shipped: shipment.tracking };
}

Snippet 7 — Validating the migration, one row at a time¶

# Python (asyncio) — verify each migrated record against the legacy system,
# stopping at the first mismatch so we can resume from there.
import asyncio

async def verify_migration(record_ids):
    last_verified = None
    for record_id in record_ids:                      # ids are in commit order
        new = await fetch_from_new_db(record_id)
        old = await fetch_from_legacy(record_id)
        if not records_match(new, old):
            raise MismatchError(record_id, last_verified)
        await mark_verified(record_id)                # persists a resume checkpoint
        last_verified = record_id
    return last_verified

What's the execution-shape problem? Perf or correctness? How would you fix it?

async def verify_migration(record_ids):
    last_verified = None
    for record_id in record_ids:
        new, old = await asyncio.gather(           # safe: independent within the row
            fetch_from_new_db(record_id),
            fetch_from_legacy(record_id),
        )
        if not records_match(new, old):
            raise MismatchError(record_id, last_verified)
        await mark_verified(record_id)
        last_verified = record_id
    return last_verified

Snippet 8 — The cache loader¶

// TS — lazily load and cache a config blob; mixes a Promise and a callback
class ConfigLoader {
  private cached?: Config;

  load(onReady: (cfg: Config) => void): Promise<Config> {
    if (this.cached) {
      onReady(this.cached);                 // sync callback
      return Promise.resolve(this.cached);
    }
    return fetchConfig().then((cfg) => {
      this.cached = cfg;
      onReady(cfg);                         // async callback
      return cfg;
    });
  }
}

// caller:
loader.load((cfg) => initFeatures(cfg));    // also: const c = await loader.load(...)

What's the execution-shape problem? Perf or correctness? How would you fix it?

class ConfigLoader {
  private cached?: Promise<Config>;

  load(): Promise<Config> {
    if (!this.cached) {
      this.cached = fetchConfig();   // cache the *promise* — also dedupes concurrent loads
    }
    return this.cached;              // always async, always one delivery channel
  }
}

// caller: const cfg = await loader.load(); initFeatures(cfg);

Snippet 9 — Fanning out the asyncio gather¶

# Python (asyncio) — scrape a list of URLs and return successful bodies
import asyncio, aiohttp

async def scrape_all(urls, session):
    tasks = [fetch(session, url) for url in urls]
    results = await asyncio.gather(*tasks)        # one bad URL kills the batch
    return [r for r in results if r is not None]

async def fetch(session, url):
    async with session.get(url) as resp:
        return await resp.text()

What's the execution-shape problem? Perf or correctness? How would you fix it?

async def scrape_all(urls, session, concurrency=20):
    sem = asyncio.Semaphore(concurrency)

    async def guarded(url):
        async with sem:                               # at most `concurrency` in flight
            try:
                return await fetch(session, url)
            except Exception:                         # degrade: skip the bad URL
                return None

    results = await asyncio.gather(*(guarded(u) for u in urls))
    return [r for r in results if r is not None]

Snippet 10 — The chained transform¶

// JS — fetch a record, transform it, save it; "modernised" from callbacks
function updateRecord(id, patch) {
  return load(id)
    .then((record) => {
      applyPatch(record, patch);        // mutates record, returns void
    })
    .then((record) => {
      return save(record);              // record is undefined here
    })
    .then(() => "ok");
}

What's the execution-shape problem? Perf or correctness? How would you fix it?

async function updateRecord(id, patch) {
  const record = await load(id);
  applyPatch(record, patch);   // mutation is fine when the variable persists
  await save(record);          // saves the real, patched record
  return "ok";
}

Snippet 11 — The file processor that returns early¶

// TS — process every uploaded file, then report how many bytes were written
async function processUploads(files: File[]): Promise<number> {
  let totalBytes = 0;

  files.map(async (file) => {
    const data = await readFile(file);
    const out = await transform(data);
    await writeOutput(file.name, out);
    totalBytes += out.byteLength;        // accumulates "later"
  });

  return totalBytes;                     // returns 0
}

What's the execution-shape problem? Perf or correctness? How would you fix it?

async function processUploads(files: File[]): Promise<number> {
  const sizes = await Promise.all(
    files.map(async (file) => {
      const data = await readFile(file);
      const out = await transform(data);
      await writeOutput(file.name, out);
      return out.byteLength;        // return the value, don't mutate outer state
    }),
  );
  return sizes.reduce((a, b) => a + b, 0);   // summed only after all complete
}

Snippet 12 — Promisifying the database driver¶

// JS — wrap a callback-based query API as a Promise, by hand
function query(sql, params) {
  return new Promise((resolve, reject) => {
    db.query(sql, params, (err, rows) => {
      if (err) reject(err);
      resolve(rows);                 // runs even after reject
    });
  });
}

// usage:
const rows = await query("SELECT * FROM users WHERE id = ?", [id]);

What's the execution-shape problem? Perf or correctness? How would you fix it?

import { promisify } from "node:util";
const query = promisify(db.query.bind(db));

const rows = await query("SELECT * FROM users WHERE id = ?", [id]);

Snippet 13 — The pagination crawler¶

# Python (asyncio) — pull every page of a paginated API into one list
import asyncio

async def fetch_all_pages(client, endpoint):
    pages = []
    cursor = None
    while True:
        resp = await client.get(endpoint, cursor=cursor)   # serial: each needs prev cursor
        pages.extend(resp.items)
        cursor = resp.next_cursor
        if cursor is None:
            break
    return pages

What's the execution-shape problem? Perf or correctness? How would you fix it?

async def iter_pages(client, endpoint):
    cursor = None
    while True:
        resp = await client.get(endpoint, cursor=cursor)
        yield resp.items                 # caller consumes as it goes
        cursor = resp.next_cursor
        if cursor is None:
            break

Snippet 14 — The reduce that lost its order¶

// JS — apply a sequence of async migrations to a document, in order
async function migrate(doc, steps) {
  const results = steps.map((step) => step.apply(doc));   // kicks them all off now
  const applied = await Promise.all(results);
  return applied[applied.length - 1];                     // "the final state"
}
// each step.apply mutates and returns the doc; steps MUST run in declared order

What's the execution-shape problem? Perf or correctness? How would you fix it?

async function migrate(doc, steps) {
  let state = doc;
  for (const step of steps) {
    state = await step.apply(state);   // step N+1 starts only after step N resolves
  }
  return state;
}

Summary — reading the execution shape¶

Execution-shape bugs don't announce themselves on a single line; you catch them by asking the right question about the shape of the async flow:

• "Are these iterations independent?" — the master question. If yes and they run sequentially (await in a loop / straight-line awaits), it's a perf bug: serialize → parallelize with Promise.all / asyncio.gather (Snippets 1, 3). If no — each step needs the previous result, or order/fail-fast/rate-limiting is part of the contract — sequential is correct, and parallelizing it is the bug (the traps: Snippets 7, 13, 14).
• "Did anything actually await this loop?" — array.forEach(async …) and a discarded array.map(async …) are fire-and-forget in disguise: the function returns before the work finishes, reporting success/zero while writes are still pending, and rejections become unhandled (Snippets 2, 11). forEach + async is essentially always a bug.
• "Is this .map(async …) result used?" — if so, there must be an await Promise.all around it, or you've returned an array of pending Promises and every field access is undefined (Snippet 3).
• "Is this Promise.all / gather bounded?" — fanning out over a huge list opens unbounded connections and OOMs or exhausts the pool; bound it with p-limit/a semaphore sized to the downstream capacity. Also remember gather/Promise.all is all-or-nothing on the first rejection unless you opt into return_exceptions / allSettled (Snippets 4, 9).
• "Does the callback fire exactly once?" — hand-rolled callback control flow and hand-promisified APIs leak missing returns, so the callback (or resolve/reject) runs twice, or never, or with both an error and a value. Promisify once at the boundary and stay in one model (Snippets 5, 12).
• "Does this API speak one async dialect?" — an API that takes a callback and returns a Promise, or that calls back synchronously on a cache hit and asynchronously on a miss (Zalgo), forces callers into inconsistent timing. Cache the promise, return one channel (Snippet 8).
• "Does each .then return the value the next step needs?" — in a Promise chain the return value is the only channel between steps; a block-bodied .then that forgets to return feeds undefined downstream and may persist garbage (Snippets 6, 10). async/await removes the plumbing — and the bug class — entirely.

The meta-lesson mirrors the structural file's: the shape lies. Code that reads parallel can run serial (slow), code that reads sequential can run concurrent (racy), and a loop that looks like a careless serial fetch may be the only correct ordering there is. Reach for Promise.all when iterations are independent; reach for a for...of loop when they aren't — and let the question, not the visual shape, decide.

Related Topics¶

• tasks.md — async programs to fix, building the same muscle from the writing side.
• Error-Handling Async Anti-Patterns — swallowed rejections and floating promises, the sibling find-bug file (the missing .catch() several snippets here also exhibit).
• Misuse Async Anti-Patterns — async without await, the Promise constructor anti-pattern.
• Concurrency Anti-Patterns — the multi-thread sibling chapter: real memory races vs. these event-loop shapes.
• Clean Code → Functions — small, single-purpose functions that make async shape obvious.
• Refactoring → Code Smells — the smell-level view of nested and tangled flow.
• Backend / Distributed Systems — fan-out, retry, and timeout patterns at the network layer (the positive side of bounded concurrency).