async-mutex

A Mutex (mutual exclusion) is a primitive used to synchronize asynchronous operations in JavaScript. While JavaScript is single-threaded, the asynchronous execution model allows for race conditions (e.g., when multiple async calls attempt to access or modify the same state during different event loop turns).

Locking a mutex returns a promise that resolves once the mutex becomes available. Once the protected async process is complete, the lock must be released to allow the next scheduled task to execute.

A Semaphore is a data structure initialized with an integer value that allows controlling access to multiple instances of a shared resource.

• As long as the semaphore value is positive, locking it decrements the value and allows execution to continue immediately.
• Once the value reaches zero, subsequent attempts to acquire a lock will be suspended until another process releases a lock, incrementing the value again.

Use a semaphore when you want to limit concurrency, such as limiting the number of parallel web crawler requests or worker processes.

Depending on your environment, use the appropriate import syntax. The library is written in TypeScript and requires no external typings for TypeScript (version >= 2).

// CommonJS
const {Mutex, Semaphore, withTimeout} = require('async-mutex');

// ES6
import {Mutex, Semaphore, withTimeout} from 'async-mutex';

// TypeScript
import {Mutex, MutexInterface, Semaphore, SemaphoreInterface, withTimeout} from 'async-mutex';

To use async-mutex in your project, install it using npm:

npm install async-mutex

Depending on your environment, import the necessary primitives and utility functions as follows:

CommonJS

const { Mutex, Semaphore, withTimeout, tryAcquire } = require('async-mutex');

ES6

import { Mutex, Semaphore, withTimeout, tryAcquire } from 'async-mutex';

TypeScript

import { 
  Mutex, MutexInterface, 
  Semaphore, SemaphoreInterface, 
  withTimeout, tryAcquire,
  E_TIMEOUT, E_ALREADY_LOCKED, E_CANCELED 
} from 'async-mutex';

// CommonJS
const { Mutex, Semaphore, withTimeout, tryAcquire } = require('async-mutex');

// ES6
import { Mutex, Semaphore, withTimeout, tryAcquire } from 'async-mutex';

// TypeScript
import { 
  Mutex, MutexInterface, 
  Semaphore, SemaphoreInterface, 
  withTimeout, tryAcquire,
  E_TIMEOUT, E_ALREADY_LOCKED, E_CANCELED 
} from 'async-mutex';

You can cancel all pending locks (locks that are waiting to be acquired) by calling mutex.cancel(). This causes the pending promises to reject with the E_CANCELED error.

Note that cancel() does not revoke a lock that is currently being held.

You can customize the error thrown by passing a different error to the Mutex constructor.

import {E_CANCELED} from 'async-mutex';

try {
    await mutex.runExclusive(() => {
        // ...
    });
} catch (e) {
    if (e === E_CANCELED) {
        // Handle cancellation
    }
}

Use the withTimeout decorator to prevent tasks from waiting indefinitely. If the timeout is exceeded, acquire and runExclusive will reject with E_TIMEOUT.

Arguments:

1. The Mutex or Semaphore instance.
2. timeout: Time in milliseconds.
3. customError (optional): A custom error to throw instead of the default E_TIMEOUT.

If you want to wait until the mutex is free without actually acquiring the lock, use waitForUnlock(). This returns a promise that resolves once the mutex is available.

Warning: This does not lock the mutex; there is no guarantee the mutex will still be available immediately after the promise resolves.

await mutex.waitForUnlock();
// ...

Use the tryAcquire decorator to attempt to acquire a lock without waiting. If the lock is already held, it will immediately throw E_ALREADY_LOCKED.

Arguments:

1. The Mutex or Semaphore instance.
2. customError (optional): A custom error to throw instead of the default E_ALREADY_LOCKED.

import {tryAcquire, E_ALREADY_LOCKED} from 'async-mutex';

try {
    await tryAcquire(semaphoreOrMutex).runExclusive(() => { /* ... */ });
} catch (e) {
    if (e === E_ALREADY_LOCKED) {
        // Handle the case where it was already locked
    }
}

You can cancel all currently queued (pending) locks by calling semaphore.cancel().

• All pending promises from acquire or runExclusive will reject with E_CANCELED.
• Note: Currently held locks are not revoked. The semaphore may still be unavailable immediately after calling cancel() if locks are still active.

import {E_CANCELED} from 'async-mutex';

try {
    await semaphore.runExclusive(() => { /* ... */ });
} catch (e) {
    if (e === E_CANCELED) {
        // Handle cancellation
    }
}