Academy — Sanjib Sikder

The Gap Between async/await and Real Concurrency

async/await makes asynchronous code readable. It does not make it concurrent. If you await each operation in sequence, you are doing one thing at a time — the rest of the time the CPU is idle, waiting.

JavaScript

Ctrl+Enter to run

function fetchScore(id, delay) {
  return new Promise(resolve =>
    setTimeout(() => resolve({ id, score: 50 + id * 3 }), delay)
  );
}

async function sequential() {
console.log("Sequential:");
const t = Date.now();

const a = await fetchScore(1, 80);
const b = await fetchScore(2, 80);
const c = await fetchScore(3, 80);
const d = await fetchScore(4, 80);
const e = await fetchScore(5, 80);

console.log(` Results: ${[a,b,c,d,e].map(r => r.score)}`);
console.log(` Time: ~${Date.now() - t}ms (5 × 80ms = 400ms)`);
}

async function parallel() {
console.log("Parallel (Promise.all):");
const t = Date.now();

const results = await Promise.all([
fetchScore(1, 80), fetchScore(2, 80), fetchScore(3, 80),
fetchScore(4, 80), fetchScore(5, 80),
]);

console.log(` Results: ${results.map(r => r.score)}`);
console.log(` Time: ~${Date.now() - t}ms (~80ms total)`);
}

sequential().then(() => parallel());

Sequential: ~400ms. Parallel: ~80ms. Five times faster for the same work. But Promise.all with no limits fires everything simultaneously — fine for five requests, catastrophic for five hundred.

Promise Combinators — The Full Set

Promise.all is one of four combinators. Each answers a different question about a group of promises:

JavaScript

Ctrl+Enter to run

function task(id, delay, fail = false) {
  return new Promise((resolve, reject) =>
    setTimeout(() =>
      fail ? reject(new Error(`Task ${id} failed`)) : resolve(`Task ${id} done`),
      delay
    )
  );
}

// Promise.all — all must succeed; first rejection rejects the whole thing
Promise.all([task(1, 50), task(2, 30), task(3, 70)])
.then(results => console.log("all success:", results))
.catch(err => console.log("all failure:", err.message));

// Promise.allSettled — wait for all, report each outcome individually
Promise.allSettled([task(1, 50), task(2, 30, true), task(3, 70)])
.then(results => {
console.log("allSettled:");
results.forEach(r => {
if (r.status === "fulfilled") console.log(" ✓", r.value);
else console.log(" ✗", r.reason.message);
});
});

// Promise.race — first to settle wins (success or failure)
Promise.race([task(1, 100), task(2, 30), task(3, 70)])
.then(result => console.log("race winner:", result));

// Promise.any — first success wins; rejects only if ALL fail
Promise.any([task(1, 100, true), task(2, 30), task(3, 70)])
.then(result => console.log("any winner:", result))
.catch(err => console.log("any all failed"));

function task(id, delay, fail = false) {
  return new Promise((resolve, reject) =>
    setTimeout(() =>
      fail ? reject(new Error(`Task ${id} failed`)) : resolve(`Task ${id} done`),
      delay
    )
  );
}

// Promise.all — all must succeed; first rejection rejects the whole thing
Promise.all([task(1, 50), task(2, 30), task(3, 70)])
.then(results => console.log("all success:", results))
.catch(err => console.log("all failure:", err.message));

// Promise.allSettled — wait for all, report each outcome individually
Promise.allSettled([task(1, 50), task(2, 30, true), task(3, 70)])
.then(results => {
console.log("allSettled:");
results.forEach(r => {
if (r.status === "fulfilled") console.log(" ✓", r.value);
else console.log(" ✗", r.reason.message);
});
});

// Promise.race — first to settle wins (success or failure)
Promise.race([task(1, 100), task(2, 30), task(3, 70)])
.then(result => console.log("race winner:", result));

// Promise.any — first success wins; rejects only if ALL fail
Promise.any([task(1, 100, true), task(2, 30), task(3, 70)])
.then(result => console.log("any winner:", result))
.catch(err => console.log("any all failed"));

The decision tree: use all when every result is required, allSettled when you need every outcome regardless of failure, race for timeouts and first-response wins, any for redundant sources where one success is enough.

Semaphore — Limiting Concurrency

A semaphore is a concurrency primitive that allows at most N operations to run simultaneously. Every additional task waits until a slot opens:

JavaScript

Ctrl+Enter to run

class Semaphore {
  #capacity;
  #active = 0;
  #queue  = [];

constructor(capacity) { this.#capacity = capacity; }

acquire() {
return new Promise(resolve => {
if (this.#active < this.#capacity) {
this.#active++;
resolve();
} else {
this.#queue.push(resolve); // wait in line
}
});
}

release() {
if (this.#queue.length > 0) {
const next = this.#queue.shift();
next(); // hand the slot to the next waiter
} else {
this.#active--;
}
}

async run(fn) {
await this.acquire();
try { return await fn(); }
finally { this.release(); }
}

get active() { return this.#active; }
get waiting(){ return this.#queue.length; }
}

// Allow only 3 concurrent tasks at a time — out of 10 total
const sem = new Semaphore(3);
const tasks = Array.from({ length: 10 }, (_, i) => i + 1);

async function runAll() {
const t = Date.now();
const promises = tasks.map(id =>
sem.run(async () => {
console.log(` → start ${id} (active: ${sem.active})`);
await new Promise(r => setTimeout(r, 60));
console.log(` ← done ${id}`);
return id;
})
);
const results = await Promise.all(promises);
console.log(`All done: ${results} in ~${Date.now() - t}ms`);
}

runAll();

class Semaphore {
  #capacity;
  #active = 0;
  #queue  = [];

constructor(capacity) { this.#capacity = capacity; }

acquire() {
return new Promise(resolve => {
if (this.#active < this.#capacity) {
this.#active++;
resolve();
} else {
this.#queue.push(resolve); // wait in line
}
});
}

release() {
if (this.#queue.length > 0) {
const next = this.#queue.shift();
next(); // hand the slot to the next waiter
} else {
this.#active--;
}
}

async run(fn) {
await this.acquire();
try { return await fn(); }
finally { this.release(); }
}

get active() { return this.#active; }
get waiting(){ return this.#queue.length; }
}

// Allow only 3 concurrent tasks at a time — out of 10 total
const sem = new Semaphore(3);
const tasks = Array.from({ length: 10 }, (_, i) => i + 1);

async function runAll() {
const t = Date.now();
const promises = tasks.map(id =>
sem.run(async () => {
console.log(` → start ${id} (active: ${sem.active})`);
await new Promise(r => setTimeout(r, 60));
console.log(` ← done ${id}`);
return id;
})
);
const results = await Promise.all(promises);
console.log(`All done: ${results} in ~${Date.now() - t}ms`);
}

runAll();

Without the semaphore all 10 tasks would fire immediately. With it, at most 3 run at any moment. This is the correct pattern when hitting external APIs with rate limits, writing to a database connection pool, or processing files with limited I/O bandwidth.

Rate Limiter — Requests Per Time Window

A semaphore limits concurrency. A rate limiter limits throughput — N operations per unit of time, regardless of how fast each one completes:

JavaScript

Ctrl+Enter to run

class RateLimiter {
  #maxPerWindow;
  #windowMs;
  #timestamps = [];

constructor(maxPerWindow, windowMs) {
this.#maxPerWindow = maxPerWindow;
this.#windowMs = windowMs;
}

async throttle() {
while (true) {
const now = Date.now();
// Remove timestamps outside the current window
this.#timestamps = this.#timestamps.filter(t => now - t < this.#windowMs);

      if (this.#timestamps.length < this.#maxPerWindow) {
        this.#timestamps.push(now);
        return; // slot available — proceed
      }

      // Wait until the oldest timestamp expires
      const oldest   = this.#timestamps[0];
      const waitFor  = this.#windowMs - (now - oldest) + 1;
      await new Promise(r => setTimeout(r, waitFor));
    }

}

async run(fn) {
await this.throttle();
return fn();
}
}

// 5 requests per 200ms window
const limiter = new RateLimiter(5, 200);
const calls = Array.from({ length: 12 }, (_, i) => i + 1);
const t0 = Date.now();

async function runAll() {
const promises = calls.map(id =>
limiter.run(async () => {
const elapsed = Date.now() - t0;
console.log(`Request ${String(id).padStart(2)} dispatched at ${elapsed}ms`);
return id;
})
);
await Promise.all(promises);
console.log(`All 12 requests sent in ~${Date.now() - t0}ms`);
}

runAll();

class RateLimiter {
  #maxPerWindow;
  #windowMs;
  #timestamps = [];

constructor(maxPerWindow, windowMs) {
this.#maxPerWindow = maxPerWindow;
this.#windowMs = windowMs;
}

async throttle() {
while (true) {
const now = Date.now();
// Remove timestamps outside the current window
this.#timestamps = this.#timestamps.filter(t => now - t < this.#windowMs);

if (this.#timestamps.length < this.#maxPerWindow) {
        this.#timestamps.push(now);
        return; // slot available — proceed
      }

// Wait until the oldest timestamp expires
      const oldest   = this.#timestamps[0];
      const waitFor  = this.#windowMs - (now - oldest) + 1;
      await new Promise(r => setTimeout(r, waitFor));
    }

}

async run(fn) {
await this.throttle();
return fn();
}
}

// 5 requests per 200ms window
const limiter = new RateLimiter(5, 200);
const calls = Array.from({ length: 12 }, (_, i) => i + 1);
const t0 = Date.now();

async function runAll() {
const promises = calls.map(id =>
limiter.run(async () => {
const elapsed = Date.now() - t0;
console.log(`Request ${String(id).padStart(2)} dispatched at ${elapsed}ms`);
return id;
})
);
await Promise.all(promises);
console.log(`All 12 requests sent in ~${Date.now() - t0}ms`);
}

runAll();

Watch the output: the first 5 fire immediately, then the next batch waits for the window to slide. This is what you build in front of any third-party API with a documented rate limit (GitHub: 5000/hr, OpenAI: 60/min, etc.).

Task Queue — Ordered, Bounded, Drainable

A semaphore is stateless about what runs next. A task queue gives you control over ordering, priority, and backpressure:

JavaScript

Ctrl+Enter to run

class TaskQueue {
  #concurrency;
  #queue   = [];
  #active  = 0;
  #done    = 0;

constructor(concurrency) { this.#concurrency = concurrency; }

add(fn, priority = 0) {
return new Promise((resolve, reject) => {
this.#queue.push({ fn, resolve, reject, priority });
this.#queue.sort((a, b) => b.priority - a.priority); // highest first
this.#drain();
});
}

#drain() {
while (this.#active < this.#concurrency && this.#queue.length > 0) {
const { fn, resolve, reject } = this.#queue.shift();
this.#active++;
Promise.resolve()
.then(fn)
.then(result => { resolve(result); this.#finish(); })
.catch(err => { reject(err); this.#finish(); });
}
}

#finish() {
this.#active--;
this.#done++;
this.#drain();
}

get stats() {
return { active: this.#active, queued: this.#queue.length, done: this.#done };
}
}

const q = new TaskQueue(2); // 2 concurrent workers
const t = Date.now();

const jobs = [
{ id: "A", ms: 80, priority: 1 },
{ id: "B", ms: 40, priority: 5 }, // highest priority — runs first
{ id: "C", ms: 60, priority: 3 },
{ id: "D", ms: 50, priority: 2 },
{ id: "E", ms: 30, priority: 10 }, // highest priority — runs first
];

const promises = jobs.map(({ id, ms, priority }) =>
q.add(() => new Promise(r => setTimeout(() => {
console.log(` ✓ job ${id} (priority ${priority}) done at ${Date.now() - t}ms stats: ${JSON.stringify(q.stats)}`);
r(id);
}, ms)), priority)
);

Promise.all(promises).then(results => {
console.log(`Completed: ${results} in ~${Date.now() - t}ms`);
});

class TaskQueue {
  #concurrency;
  #queue   = [];
  #active  = 0;
  #done    = 0;

constructor(concurrency) { this.#concurrency = concurrency; }

add(fn, priority = 0) {
return new Promise((resolve, reject) => {
this.#queue.push({ fn, resolve, reject, priority });
this.#queue.sort((a, b) => b.priority - a.priority); // highest first
this.#drain();
});
}

#drain() {
while (this.#active < this.#concurrency && this.#queue.length > 0) {
const { fn, resolve, reject } = this.#queue.shift();
this.#active++;
Promise.resolve()
.then(fn)
.then(result => { resolve(result); this.#finish(); })
.catch(err => { reject(err); this.#finish(); });
}
}

#finish() {
this.#active--;
this.#done++;
this.#drain();
}

get stats() {
return { active: this.#active, queued: this.#queue.length, done: this.#done };
}
}

const q = new TaskQueue(2); // 2 concurrent workers
const t = Date.now();

const jobs = [
{ id: "A", ms: 80, priority: 1 },
{ id: "B", ms: 40, priority: 5 }, // highest priority — runs first
{ id: "C", ms: 60, priority: 3 },
{ id: "D", ms: 50, priority: 2 },
{ id: "E", ms: 30, priority: 10 }, // highest priority — runs first
];

Promise.all(promises).then(results => {
console.log(`Completed: ${results} in ~${Date.now() - t}ms`);
});

Priority queuing ensures high-importance work is never starved behind a pile of low-importance tasks. The stats call gives you live visibility into queue depth — useful for backpressure signalling.

Race Condition — The Classic Bug

A race condition occurs when two concurrent operations read and write shared state, and the outcome depends on which one wins the race:

JavaScript

Ctrl+Enter to run

// Classic race condition — unsynchronised read-modify-write
let balance = 1000;

async function withdraw(amount, label) {
const current = balance; // read
await new Promise(r => setTimeout(r, 10)); // async gap — danger zone
if (current >= amount) {
balance = current - amount; // write — based on stale read!
console.log(`${label}: withdrew ${amount}, balance = ${balance}`);
} else {
console.log(`${label}: insufficient funds (balance was ${current})`);
}
}

// Both see balance = 1000, both succeed — but 1000 - 800 - 900 < 0!
async function raceDemo() {
balance = 1000;
console.log("=== Racy (bad) ===");
await Promise.all([
withdraw(800, "Alice"),
withdraw(900, "Bob"),
]);
console.log("Final balance:", balance); // wrong — may go negative

// Fix: serialise access with a mutex (mutual exclusion lock)
balance = 1000;
console.log("\n=== Mutex (correct) ===");

class Mutex {
#locked = false;
#queue = [];
async lock() {
if (!this.#locked) { this.#locked = true; return; }
return new Promise(r => this.#queue.push(r));
}
unlock() {
if (this.#queue.length > 0) this.#queue.shift()();
else this.#locked = false;
}
}

const mutex = new Mutex();
async function safeWithdraw(amount, label) {
await mutex.lock();
try {
const current = balance;
await new Promise(r => setTimeout(r, 10));
if (current >= amount) {
balance = current - amount;
console.log(`${label}: withdrew ${amount}, balance = ${balance}`);
} else {
console.log(`${label}: insufficient funds (balance = ${current})`);
}
} finally { mutex.unlock(); }
}

await Promise.all([
safeWithdraw(800, "Alice"),
safeWithdraw(900, "Bob"),
]);
console.log("Final balance:", balance); // correct
}

raceDemo();

// Classic race condition — unsynchronised read-modify-write
let balance = 1000;

async function withdraw(amount, label) {
const current = balance; // read
await new Promise(r => setTimeout(r, 10)); // async gap — danger zone
if (current >= amount) {
balance = current - amount; // write — based on stale read!
console.log(`${label}: withdrew ${amount}, balance = ${balance}`);
} else {
console.log(`${label}: insufficient funds (balance was ${current})`);
}
}

// Both see balance = 1000, both succeed — but 1000 - 800 - 900 < 0!
async function raceDemo() {
balance = 1000;
console.log("=== Racy (bad) ===");
await Promise.all([
withdraw(800, "Alice"),
withdraw(900, "Bob"),
]);
console.log("Final balance:", balance); // wrong — may go negative

// Fix: serialise access with a mutex (mutual exclusion lock)
balance = 1000;
console.log("\n=== Mutex (correct) ===");

class Mutex {
#locked = false;
#queue = [];
async lock() {
if (!this.#locked) { this.#locked = true; return; }
return new Promise(r => this.#queue.push(r));
}
unlock() {
if (this.#queue.length > 0) this.#queue.shift()();
else this.#locked = false;
}
}

await Promise.all([
safeWithdraw(800, "Alice"),
safeWithdraw(900, "Bob"),
]);
console.log("Final balance:", balance); // correct
}

raceDemo();

The read-modify-write cycle must be atomic. The mutex serialises the critical section — only one withdrawal runs at a time through the danger zone, eliminating the race entirely.

Promise Pool — Controlled Parallel Iteration

Combining everything: process a large list with controlled concurrency, collecting all results, handling partial failures:

JavaScript

Ctrl+Enter to run

async function promisePool(items, concurrency, fn) {
  const results  = new Array(items.length);
  const errors   = [];
  let   index    = 0;

async function worker() {
while (index < items.length) {
const i = index++;
const item = items[i];
try {
results[i] = await fn(item, i);
} catch (err) {
errors.push({ index: i, item, error: err.message });
results[i] = null;
}
}
}

// Spawn exactly 'concurrency' workers — each grabs the next item when free
await Promise.all(Array.from({ length: concurrency }, worker));

return { results, errors };
}

// Simulated bulk operation: process 15 students, 4 at a time
const students = Array.from({ length: 15 }, (_, i) => ({
id: i + 1,
name: `Student ${i + 1}`,
marks: Math.floor(Math.random() * 60) + 40,
}));

async function processStudent(student) {
await new Promise(r => setTimeout(r, 20 + Math.random() * 40));
if (student.marks < 45) throw new Error("Below minimum threshold");
return { ...student, grade: student.marks >= 75 ? "A" : "B", processed: true };
}

const t = Date.now();

promisePool(students, 4, processStudent).then(({ results, errors }) => {
const passed = results.filter(Boolean);
console.log(`Processed ${passed.length} students in ~${Date.now() - t}ms`);
console.log(`Failed: ${errors.length}`);
errors.forEach(e => console.log(` ✗ ${e.item.name}: ${e.error}`));
passed.slice(0, 3).forEach(s =>
console.log(` ✓ ${s.name}: ${s.marks} [${s.grade}]`)
);
});

async function promisePool(items, concurrency, fn) {
  const results  = new Array(items.length);
  const errors   = [];
  let   index    = 0;

async function worker() {
while (index < items.length) {
const i = index++;
const item = items[i];
try {
results[i] = await fn(item, i);
} catch (err) {
errors.push({ index: i, item, error: err.message });
results[i] = null;
}
}
}

// Spawn exactly 'concurrency' workers — each grabs the next item when free
await Promise.all(Array.from({ length: concurrency }, worker));

return { results, errors };
}

// Simulated bulk operation: process 15 students, 4 at a time
const students = Array.from({ length: 15 }, (_, i) => ({
id: i + 1,
name: `Student ${i + 1}`,
marks: Math.floor(Math.random() * 60) + 40,
}));

async function processStudent(student) {
await new Promise(r => setTimeout(r, 20 + Math.random() * 40));
if (student.marks < 45) throw new Error("Below minimum threshold");
return { ...student, grade: student.marks >= 75 ? "A" : "B", processed: true };
}

const t = Date.now();

promisePool(students, 4, processStudent).then(({ results, errors }) => {
const passed = results.filter(Boolean);
console.log(`Processed ${passed.length} students in ~${Date.now() - t}ms`);
console.log(`Failed: ${errors.length}`);
errors.forEach(e => console.log(` ✗ ${e.item.name}: ${e.error}`));
passed.slice(0, 3).forEach(s =>
console.log(` ✓ ${s.name}: ${s.marks} [${s.grade}]`)
);
});

This pattern — fixed worker pool pulling from a shared index — is the correct foundation for bulk processing, import pipelines, web scrapers, and batch API calls. It is more efficient than slicing the array into chunks because workers self-balance: a slow item in one worker does not stall the others.

What You Have Learned

Concurrency is not just "use Promise.all". It is controlling how many things run, at what rate, in what order, and what happens when they conflict.

The key ideas:

await in sequence is serial — multiply your latency by the number of operations
Promise combinators: all (all must succeed), allSettled (report every outcome), race (first wins), any (first success wins)
Semaphore: limit simultaneous operations — the correct tool for connection pools and API concurrency limits
Rate limiter: limit throughput over time — N requests per window, regardless of completion speed
Task queue: ordered, prioritised, backpressure-aware — the foundation of job processing systems
Mutex: serialise the critical section of a read-modify-write cycle — eliminate race conditions
Promise pool: fixed worker count pulling from a shared list — self-balancing, partial-failure-safe bulk processing

In the next lesson: Design Patterns in JavaScript — Singleton, Observer, Strategy, Command, and the patterns that appear constantly in real codebases. Not as academic taxonomy but as solutions to problems you will actually encounter.

Concurrency Patterns

The Gap Between async/await and Real Concurrency

Promise Combinators — The Full Set

Semaphore — Limiting Concurrency

Rate Limiter — Requests Per Time Window

Task Queue — Ordered, Bounded, Drainable

Race Condition — The Classic Bug

Promise Pool — Controlled Parallel Iteration

What You Have Learned