typescript 46 lines · 6 steps

Building an async Semaphore in TypeScript

A counting semaphore that limits how many async tasks run at once by parking excess callers as pending promises.

Explained by highlit

Advanced concurrency async-await promises backpressure rate-limiting

1export class Semaphore {
private available: number;
private readonly waiters: Array<() => void> = [];
4 
constructor(permits: number) {
  if (permits < 1) throw new RangeError("permits must be >= 1");
  this.available = permits;
}
9 
async acquire(): Promise<void> {
  if (this.available > 0) {
    this.available--;
    return;
  }
  await new Promise<void>((resolve) => this.waiters.push(resolve));
}
17 
release(): void {
  const next = this.waiters.shift();
  if (next) {
    next();
  } else {
    this.available++;
  }
}
26 
async run<T>(task: () => Promise<T>): Promise<T> {
  await this.acquire();
  try {
    return await task();
  } finally {
    this.release();
  }
}
35}
36 
37export async function mapWithLimit<T, R>(
items: readonly T[],
limit: number,
fn: (item: T, index: number) => Promise<R>,
41): Promise<R[]> {
const semaphore = new Semaphore(limit);
return Promise.all(
  items.map((item, index) => semaphore.run(() => fn(item, index))),
);
46}

01 / 01

STEP 01

Walkthrough

Space play ←→ step click any line

Three takeaways

1A resolve function captured from a Promise can be stored and called later to unblock an awaiting caller.
2Counting permits plus a FIFO waiter queue is enough to bound concurrency without threads or locks.
3Wrapping work in acquire/finally-release guarantees a permit is always returned, even when the task throws.

Related explainers

java

public class SlidingLogRateLimiter {
 
    private final int maxRequests;
    private final long windowMillis;

How a sliding-log rate limiter works

rate-limiting concurrency sliding-window

Advanced 8 steps

typescript

import { Injectable, UnauthorizedException } from '@nestjs/common';
import { PassportStrategy } from '@nestjs/passport';
import { ExtractJwt, Strategy } from 'passport-jwt';
import { ConfigService } from '@nestjs/config';

How a JWT strategy authenticates in NestJS

authentication jwt passport

Intermediate 7 steps

package theme
 
import (
	"fmt"

Per-tenant HTML templates with Gin's renderer

multi-tenancy concurrency html-templates

Advanced 8 steps

python

import time
import threading
from enum import Enum
from functools import wraps

Building a circuit breaker in Python

circuit-breaker resilience decorators

Advanced 7 steps

typescript

import { Injectable } from '@angular/core';
import { HttpInterceptor, HttpRequest, HttpHandler, HttpEvent, HttpErrorResponse } from '@angular/common/http';
import { BehaviorSubject, Observable, throwError } from 'rxjs';
import { catchError, filter, take, switchMap } from 'rxjs/operators';