Semaphore middlewares

Initial configuration

To begin using the semaphore middlewares, you'll need to create and configure a SemaphoreFactory instance:

./samples/semaphore.ts

import { SemaphoreFactory } from "eridu-tech/semaphore";
import { MemorySemaphoreAdapter } from "eridu-tech/semaphore/memory-semaphore-adapter";

export const semaphoreFactory = new SemaphoreFactory({
    adapter: new MemorySemaphoreAdapter(),
});

withSemaphoreFactory middleware

The Semaphore middleware wraps function calls with a distributed semaphore, limiting the number of concurrent executions across processes. Before executing the wrapped function, a slot is acquired on a key derived from the function's arguments. If the maximum number of concurrent slots (limit) has already been reached, the call waits (or fails immediately for non-blocking semaphores) until a slot becomes available.

Usage

./samples/with-semaphore.ts

import { withSemaphoreFactory } from "eridu-tech/semaphore/middlewares";
import { use } from "eridu-tech/middleware";
import { semaphoreFactory } from "./semaphore.js";

const withSemaphore = withSemaphoreFactory(semaphoreFactory);

const processFile = async (filePath: string): Promise<void> => {
    // Process file — limited concurrency
    // ... process the file
};

// Wrap with semaphore — max 3 concurrent file processes
const throttledProcess = use(
    processFile,
    withSemaphore({
        key: ([filePath]) => `file-path:${filePath}`,
        limit: 3,
    }),
);

// These will run up to 3 at a time
await Promise.all([
    throttledProcess("/data/file1.json"),
    throttledProcess("/data/file2.json"),
    throttledProcess("/data/file3.json"),
    throttledProcess("/data/file4.json"), // Waits for a slot
]);

info

Here is a complete list of settings for the withSemaphore function.

Settings

Option	Type	Description
key	Invocable<TParameters, string>	A function that produces the semaphore key from the wrapped function's arguments. All consumers using the same key share the same semaphore limit
limit	number	Maximum number of concurrent slots (consumers) allowed for the semaphore key
slotId	Invocable<TParameters, string>	Optional function that produces a unique slot identifier for the current acquisition attempt. Defaults to a UUID (v4)
ttl	ITimeSpan | null	Time-to-live for each acquired slot. null means slots never expire automatically; if omitted the factory's default TTL is used

Further information

For further information refer to eridu-tech/semaphore API docs.