For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /reference/promise/Semaphore.md.
Install massaman

    Semaphore es-toolkit

    Limits the number of asynchronous tasks that can execute simultaneously.

    const semaphore = new Semaphore(capacity);

    Usage

    Semaphore(capacity)

    Use Semaphore when you want to limit the number of asynchronous tasks that can execute concurrently. It's particularly useful in situations where you need to control resource usage, such as database connection pools, API call rate limiting, or file download limits.

    import { Semaphore } from 'es-toolkit';

const semaphore = new Semaphore(3);

// API call rate limiting example (maximum 3 concurrent executions)
async function callAPI(id: number) {
  await semaphore.acquire();
  try {
    console.log(`Starting API call: ${id}`);
    const response = await fetch(`/api/data/${id}`);
    return response.json();
  } finally {
    semaphore.release();
    console.log(`Completed API call: ${id}`);
  }
}

// File download limiting example
async function downloadFile(url: string) {
  await semaphore.acquire();
  try {
    console.log(`Starting download: ${url}`);
    // File download logic
    await fetch(url);
  } finally {
    semaphore.release();
    console.log(`Completed download: ${url}`);
  }
}

// Even if 5 tasks are called simultaneously, only 3 execute concurrently
callAPI(1);
callAPI(2);
callAPI(3);
callAPI(4); // Waits until one of the previous tasks completes
callAPI(5); // Waits until one of the previous tasks completes

    Parameters

    capacitynumberrequired

    The maximum number of tasks that can execute concurrently. Must be a positive integer.

    Properties

    • capacity (number): The maximum number of tasks that can execute concurrently.
    • available (number): The number of currently available permits. If 0, all permits are in use.

    Methods

    • acquire (() => Promise<void>): Acquires permission to execute an asynchronous task, or waits until permission is granted.
    • release (() => void): Returns permission so that the next waiting task can execute.
    Source: es-toolkit

    Re-exported verbatim from es-toolkit. Implementation, edge cases, and performance behavior are owned upstream. This page mirrors the documentation at the pinned version; the linked source is authoritative.