async-primitives

A collection of primitive functions for asynchronous operations in TypeScript/JavaScript.

(For Japanese language/日本語はこちら)

Please note that this English version of the document was machine-translated and then partially edited, so it may contain inaccuracies. We welcome pull requests to correct any errors in the text.

What is this?

If you are interested in performing additional calculations on Promise<T>, you may find this small library useful. Mutex, producer-consumer separation (side-effect operation), signaling (flag control), logical context, iterator chaining operators and more.

• Works in both browser and Node.js environments (16 or later, tested only 24).
• No external dependencies.

Primitives:

| Function | Description | | :---------------------------- | :-------------------------------------------------------- | | delay() | Promise-based delay function | | defer() | Schedule callback for next event loop | | onAbort() | Register safer abort signal hooks with cleanup | | createMutex() | Promise-based mutex lock for critical sections | | createSemaphore() | Promise-based semaphore for limiting concurrent access | | createReaderWriterLock() | Read-write lock for multiple readers/single writer | | createDeferred() | External control of Promise resolution/rejection | | createDeferredGenerator() | External control of async generator with queue management | | createConditional() | Automatic conditional trigger (one-waiter per trigger) | | createManuallyConditional() | Manual conditional control (raise/drop state) |

Iterator operations:

| Function | Description | | :------- | :-------------------------------------------- | | from() | Chainable operators for iterable async values |

Advanced features:

| Function | Description | | :------------------- | :------------------------------------------- | | createAsyncLocal() | Asynchronous context storage | | LogicalContext | Low-level async execution context management |

• The implementations previously known symbol as AsyncLock and Signal have been changed to Mutex and Conditional. Although these symbol names can still be used, please note that they are marked as deprecated. They may be removed in future versions.

Installation

npm install async-primitives

Usage

Each functions are independent and does not require knowledge of each other's assumptions.

delay()

Provides a delay that can be awaited with Promise<void>, with support for cancellation via AbortSignal.

import { delay } from 'async-primitives';

// Use delay
await delay(1000); // Wait for 1 second

// With AbortSignal
const c = new AbortController();
await delay(1000, c.signal); // Wait for 1 second

defer()

Schedules a callback to be executed asynchronously on the next event loop iteration.

import { defer } from 'async-primitives';

// Use defer (Schedule callback for next event loop)
defer(() => {
  console.log('Executes asynchronously');
});

onAbort()

Registers a hook function to AbortSignal abort events, enabling cleanup processing. Also supports early release.

import { onAbort } from 'async-primitives';

// Use onAbort (Abort signal hooking)
const controller = new AbortController();

const releaseHandle = onAbort(controller.signal, (error: Error) => {
  console.log('Operation was aborted!');
  // (Will automatically cleanup when exit)
});

// (Cleanup early if needed)
releaseHandle.release();

createMutex()

Provides Promise based mutex functionality to implement critical sections that prevent race conditions in asynchronous operations.

import { createMutex } from 'async-primitives';

// Use Mutex
const locker = createMutex();

// Lock Mutex
const handler = await locker.lock();
try {
  // Critical section, avoid race condition.
} finally {
  // Release Mutex
  handler.release();
}

// With AbortSignal
const handler = await locker.lock(c.signal);

createDeferred()

Creates a Deferred<T> object that allows external control of Promise<T> resolution or rejection. Useful for separating producers and consumers in asynchronous processing.

import { createDeferred } from 'async-primitives';

// Use Deferred
const deferred = createDeferred<number>();

deferred.resolve(123); // (Produce result value)
deferred.reject(new Error()); // (Produce an error)

// (Consumer)
const value = await deferred.promise;

// With AbortSignal support
const controller = new AbortController();
const abortableDeferred = createDeferred<number>(controller.signal);

createDeferredGenerator()

Creates a DeferredGenerator<T> object that allows external control of async generator AsyncGenerator<T, ...> yielding, returning and throwing operations. Useful for separating producers and consumers in streaming data patterns.

import { createDeferredGenerator } from 'async-primitives';

// Basic usage - streaming data
const deferredGen = createDeferredGenerator<string>();

// Consumer - iterate over values as they arrive
const consumer = async () => {
  for await (const value of deferredGen.generator) {
    console.log('Received:', value);
  }
  console.log('Stream completed');
};

// Start consuming
consumer();

// Producer - send values externally (now returns Promise<void>)
await deferredGen.yield('First value');
await deferredGen.yield('Second value');
await deferredGen.yield('Third value');
await deferredGen.return(); // Complete the stream

Can insert an error when yielding:

// With error handling
const errorGen = createDeferredGenerator<number>();

const errorConsumer = async () => {
  try {
    for await (const value of errorGen.generator) {
      console.log('Number:', value);
    }
  } catch (error) {
    console.log('Error occurred:', error.message);
  }
};

errorConsumer();
await errorGen.yield(1);
await errorGen.yield(2);
await errorGen.throw(new Error('Something went wrong'));

Queue Size Management

Control the maximum number of items that can be queued using the maxItemReserved option:

// Limit queue to 3 items maximum
const limitedGen = createDeferredGenerator<string>({ maxItemReserved: 3 });

// When queue is full, yield operations will wait for space
await limitedGen.yield('item1');
await limitedGen.yield('item2');
await limitedGen.yield('item3'); // Queue is now full

// This will wait until consumer processes some items
await limitedGen.yield('item4'); // Waits for queue space

createConditional()

Creates an automatically or manually controlled signal that can be raise and drop. Multiple waiters can await for the same signal, and all will be resolved when the signal is raise.

The Conditional (automatic conditional) is "trigger" automatically raise-and-drop to release only one-waiter:

import { createConditional } from 'async-primitives';

// Create an automatic conditional
const signal = createConditional();

// Start multiple waiters
const waiter1 = signal.wait();
const waiter2 = signal.wait();

// Trigger the signal - only one waiter will resolve per trigger
signal.trigger(); // waiter1 resolves

await waiter1;
console.log('First waiter resolved');

// Second waiter is still waiting
signal.trigger(); // waiter2 resolves

await waiter2;
console.log('Second waiter resolved');

// Wait with AbortSignal support
const controller = new AbortController();
try {
  const waitPromise = signal.wait(controller.signal);
  // Abort the wait operation
  controller.abort();
  await waitPromise;
} catch (error) {
  console.log('Wait was aborted');
}

createManuallyConditional()

The ManuallyConditional is manually controlled raise and drop state, and trigger action is optional.

import { createManuallyConditional } from 'async-primitives';

// Create a manually conditional
const signal = createManuallyConditional();

// Start multiple waiters
const waiter1 = signal.wait();
const waiter2 = signal.wait();

// Raise the signal - all waiters will resolve
signal.raise();

// Or, you can release only one-waiter
//signal.trigger();　　// waiter1 resolves

await Promise.all([waiter1, waiter2]);
console.log('All waiters resolved');

// Drop the signal
signal.drop();

// Wait with AbortSignal support
const controller = new AbortController();
try {
  await signal.wait(controller.signal);
} catch (error) {
  console.log('Wait was aborted');
}

createSemaphore()

Creates a Semaphore that limits the number of concurrent operations to a specified count. Useful for rate limiting, resource pooling, and controlling concurrent access to limited resources.

import { createSemaphore } from 'async-primitives';

// Create a semaphore with max 3 concurrent operations
const semaphore = createSemaphore(3);

// Acquire a resource
const handle = await semaphore.acquire();
try {
  // Critical section - only 3 operations can run concurrently
  await performExpensiveOperation();
} finally {
  // Release the resource
  handle.release();
}

// Check available resources
console.log(`Available: ${semaphore.availableCount}`);
console.log(`Waiting: ${semaphore.pendingCount}`);

Rate limiting example for API calls:

// Limit to 5 concurrent API calls
const apiSemaphore = createSemaphore(5);

const rateLimitedFetch = async (url: string) => {
  const handle = await apiSemaphore.acquire();
  try {
    return await fetch(url);
  } finally {
    handle.release();
  }
};

// Process many URLs with controlled concurrency
const urls = ['url1', 'url2' /* ... many more ... */];
const promises = urls.map((url) => rateLimitedFetch(url));
const results = await Promise.all(promises);
// Only 5 requests will be in-flight at any time

// With AbortSignal support
const controller = new AbortController();
try {
  const handle = await semaphore.acquire(controller.signal);

  // Use the resource
  handle.release();
} catch (error) {
  console.log('Semaphore acquisition was aborted');
}

createReaderWriterLock()

Creates a ReaderWriterLock that allows multiple concurrent readers but only one exclusive writer.

Lock policies:

• write-preferring (default): When a writer is waiting, new readers must wait until the writer completes
• read-preferring: New readers can acquire the lock even when writers are waiting

import { createReaderWriterLock } from 'async-primitives';

// Create a reader-writer lock (default: write-preferring)
const rwLock = createReaderWriterLock();

// With specific policy
const readPreferringLock = createReaderWriterLock({
  policy: 'read-preferring',
});

// Backward compatible with legacy API
const rwLockLegacy = createReaderWriterLock(10); // maxConsecutiveCalls

// Multiple readers can access concurrently
const readData = async () => {
  const handle = await rwLock.readLock();
  try {
    // Multiple threads can read simultaneously
    const data = await readFromSharedResource();
    return data;
  } finally {
    handle.release();
  }
};

// Writers have exclusive access
const writeData = async (newData: any) => {
  const handle = await rwLock.writeLock();
  try {
    // Exclusive access - no readers or other writers
    await writeToSharedResource(newData);
  } finally {
    handle.release();
  }
};

// Check lock state
console.log(`Current readers: ${rwLock.currentReaders}`);
console.log(`Has writer: ${rwLock.hasWriter}`);
console.log(`Pending readers: ${rwLock.pendingReadersCount}`);
console.log(`Pending writers: ${rwLock.pendingWritersCount}`);

Cache implementation example:

const cacheLock = createReaderWriterLock();
const cache = new Map();

// Read from cache (multiple concurrent reads allowed)
const getCached = async (key: string) => {
  const handle = await cacheLock.readLock();
  try {
    return cache.get(key);
  } finally {
    handle.release();
  }
};

// Update cache (exclusive write access)
const updateCache = async (key: string, value: any) => {
  const handle = await cacheLock.writeLock();
  try {
    cache.set(key, value);
  } finally {
    handle.release();
  }
};

// Clear cache (exclusive write access)
const clearCache = async () => {
  const handle = await cacheLock.writeLock();
  try {
    cache.clear();
  } finally {
    handle.release();
  }
};

// With AbortSignal support
const controller = new AbortController();
try {
  const readHandle = await rwLock.readLock(controller.signal);

  // Read operations...
  readHandle.release();
} catch (error) {
  console.log('Lock acquisition was aborted');
}

from()

Creates an AsyncOperator<T> from an Iterable or AsyncIterable of values or promises, allowing lazy and sequential operator chaining. It’s helpful to think of functions like Array.map() as being applicable to asynchronous iterators as well.

import { from } from 'async-primitives';

// Processing promise elements with operators
const values = await from([Promise.resolve(1), 2, Promise.resolve(3)])
  .map(async (value) => value * 2)
  .filter((value) => value > 2)
  .flatMap((value) => [value, value + 100])
  .toArray();

console.log(values); // [4, 104, 6, 106]

AsyncOperator<T> is also an AsyncIterable<T>, so it can be consumed directly with for await.

// Consume directly as AsyncIterable<T>
for await (const value of from(iterable).map((value) => value * 2)) {
  console.log(value);
}

You can also pass in an AsyncIterable<T> (which is typically generated by "asynchronous generators"):

// AsyncIterable<T> sources are also supported
const asyncIterable = (async function* () {
  yield 1;
  yield 2;
  yield 3;
})();

const values = await from(asyncIterable).toArray();

Some sources are one-shot, such as async generator instances. If the same source cannot be enumerated again, calling multiple terminal operations on the same AsyncOperator may produce different results on the second and later enumerations.

Intermediate operators:

| Operator | Description | | :-------------- | :------------------------------------------------------------------------- | | map() | Projects each resolved value into another value | | flatMap() | Projects each resolved value into an iterable and flattens it by one level | | filter() | Keeps only values whose predicate result is truthy | | concat() | Appends values from additional iterables or async iterables | | choose() | Projects each resolved value and omits null and undefined results | | slice() | Returns a subrange using Array.prototype.slice() semantics | | distinct() | Removes duplicate values | | distinctBy() | Removes duplicate values by projected key | | skip() | Skips the specified number of values | | skipWhile() | Skips values while the predicate returns true | | take() | Takes the specified number of values | | takeWhile() | Takes values while the predicate returns true | | pairwise() | Produces adjacent pairs | | zip() | Combines values with another iterable element by element | | scan() | Produces intermediate accumulator states, including the initial value | | union() | Produces distinct values from this sequence followed by another sequence | | unionBy() | Produces distinct values by projected key across two sequences | | intersect() | Produces distinct values that appear in both sequences | | intersectBy() | Produces distinct values by projected key that appear in both sequences | | except() | Produces distinct values that do not appear in another sequence | | exceptBy() | Produces distinct values by projected key not found in another sequence | | chunkBySize() | Groups values into arrays of a fixed maximum size | | windowed() | Produces sliding windows of a fixed size | | flat() | Flattens nested arrays using Array.prototype.flat() semantics | | reverse() | Returns the sequence in reverse order | | toReversed() | Returns a reversed copy of the sequence | | sort() | Returns the sequence sorted with Array.prototype.sort() semantics | | toSorted() | Returns a sorted copy with Array.prototype.toSorted() semantics |

Terminal operators:

| Operator | Description | | :---------------- | :------------------------------------------------------------------------------------- | | forEach() | Executes an action for each value | | reduce() | Reduces the sequence to a single value | | reduceRight() | Reduces the sequence from right to left | | some() | Returns true when any value satisfies the predicate | | every() | Returns true when all values satisfy the predicate | | find() | Returns the first value that satisfies the predicate | | findIndex() | Returns the index of the first value that satisfies the predicate | | at() | Returns the value at the specified index, matching Array.prototype.at() | | includes() | Returns true when the value is present, matching Array.prototype.includes() | | indexOf() | Returns the first matching index, matching Array.prototype.indexOf() | | lastIndexOf() | Returns the last matching index, matching Array.prototype.lastIndexOf() | | findLast() | Returns the last value that satisfies the predicate | | findLastIndex() | Returns the index of the last value that satisfies the predicate | | min() | Returns the minimum value, or undefined for an empty sequence | | minBy() | Returns the value with the minimum projected key, or undefined for an empty sequence | | max() | Returns the maximum value, or undefined for an empty sequence | | maxBy() | Returns the value with the maximum projected key, or undefined for an empty sequence | | groupBy() | Collects values into a Map grouped by projected key | | countBy() | Counts values into a Map grouped by projected key | | join() | Concatenates the values into a string, matching Array.prototype.join() | | toArray() | Materializes the resulting values into an array |

Index-based operators such as slice(), at(), includes(), indexOf(), and lastIndexOf() follow the corresponding Array semantics. Negative indexes or negative fromIndex values may require consuming the source before the result is known.

Materializing operators such as flat(), reverse(), toReversed(), sort(), toSorted(), and reduceRight() consume the entire source before they can produce results.

ES2022+ using statement

Use with using statement (requires ES2022+ or equivalent polyfill)

const locker = createMutex();

{
  using handler = await locker.lock();

  // (Auto release when exit the scope.)
}

{
  using handle = onAbort(controller.signal, () => {
    console.log('Cleanup on aborts');
  });

  // (Auto release when exit the scope.)
}

// Semaphore with using statement
const semaphore = createSemaphore(3);

{
  using handle = await semaphore.acquire();

  // Perform rate-limited operation
  await performOperation();

  // (Auto release when exit the scope.)
}

// ReaderWriterLock with using statement
const rwLock = createReaderWriterLock();

{
  // Reader scope
  using readHandle = await rwLock.readLock();

  const data = await readSharedData();

  // (Auto release when exit the scope.)
}

{
  // Writer scope
  using writeHandle = await rwLock.writeLock();

  await writeSharedData(newData);

  // (Auto release when exit the scope.)
}

Advanced Topic

createAsyncLocal()

Provides asynchronous context storage similar to thread-local storage, but separated by asynchronous context instead of threads. Values are maintained across asynchronous boundaries like setTimeout, await, and Promise chains within the same logical context.

import { createAsyncLocal } from 'async-primitives';

// Create an AsyncLocal instance
const asyncLocal = createAsyncLocal<string>();

// Set a value in the current context
asyncLocal.setValue('context value');

// Value is maintained across setTimeout
setTimeout(() => {
  console.log(asyncLocal.getValue()); // 'context value'
}, 100);

// Value is maintained across await boundaries
const example = async () => {
  asyncLocal.setValue('before await');

  await delay(100);

  console.log(asyncLocal.getValue()); // 'before await'
};

// Value is maintained in Promise chains
Promise.resolve()
  .then(() => {
    asyncLocal.setValue('in promise');
    return asyncLocal.getValue();
  })
  .then((value) => {
    console.log(value); // 'in promise'
  });

NOTE: The above example is no different than using a variable in the global scope. In fact, to isolate the "asynchronous context" and observe different results, you must use LogicalContext below section.

LogicalContext Operations

LogicalContext provides low-level APIs for managing asynchronous execution contexts. These are automatically used by createAsyncLocal() but can also be used directly for advanced scenarios.

import {
  setLogicalContextValue,
  getLogicalContextValue,
  runOnNewLogicalContext,
  getCurrentLogicalContextId,
} from 'async-primitives';

// Direct context value manipulation
const key = Symbol('my-context-key');
setLogicalContextValue(key, 'some value');
const value = getLogicalContextValue<string>(key); // 'some value'

// Get current context ID
const contextId = getCurrentLogicalContextId();
console.log(`Current context: ${contextId.toString()}`);

// Execute code in a new isolated context
const result = runOnNewLogicalContext('my-operation', () => {
  // This runs in a completely new context
  const isolatedValue = getLogicalContextValue<string>(key); // undefined

  setLogicalContextValue(key, 'isolated value');
  return getLogicalContextValue<string>(key); // 'isolated value'
});

// Back to original context
const originalValue = getLogicalContextValue<string>(key); // 'some value'

When using LogicalContext for the first time, hooks are inserted into various runtime functions and definitions in JavaScript to maintain the context correctly. Note that these create some overhead.

| Target | Purpose | | :----------------------------- | :-------------------------------------------------------------- | | setTimeout | Maintains context across timer callbacks | | setInterval | Maintains context across interval callbacks | | queueMicrotask | Preserves context in microtask queue | | setImmediate | Preserves context in immediate queue (Node.js only) | | process.nextTick | Preserves context in next tick queue (Node.js only) | | Promise | Captures context for then(), catch() and finally() chains | | EventTarget.addEventListener | Maintains context in all EventTarget event handlers | | Element.addEventListener | Maintains context in DOM event handlers | | requestAnimationFrame | Preserves context in animation callbacks | | XMLHttpRequest | Maintains context in XHR event handlers and callbacks | | WebSocket | Maintains context in WebSocket event handlers and callbacks | | MutationObserver | Preserves context in DOM mutation observer callbacks | | ResizeObserver | Preserves context in element resize observer callbacks | | IntersectionObserver | Preserves context in intersection observer callbacks | | Worker | Maintains context in Web Worker event handlers | | MessagePort | Maintains context in MessagePort communication handlers |

NOTE: LogicalContext values are isolated between different contexts but maintained across asynchronous boundaries within the same context. This enables proper context isolation in complex asynchronous applications.

createMutex() Parameter Details

In createMutex(maxConsecutiveCalls?: number), you can specify the maxConsecutiveCalls parameter (default value: 20).

This value sets the limit for consecutive executions when processing the lock's waiting queue:

• Small values (e.g., 1-5)

  • Returns control to the event loop more frequently
  • Minimizes impact on other asynchronous operations
  • May slightly reduce lock processing throughput

• Large values (e.g., 50-100)

  • Executes more lock processes consecutively
  • Improves lock processing throughput
  • May block other asynchronous operations for longer periods

• Recommended settings

  • Default value (20) is suitable for most use cases
  • For UI responsiveness priority: lower values (3-7)
  • For high throughput needs like batch processing: higher values (20-100)

// Prioritize UI responsiveness
const uiLocker = createMutex(5);

// High throughput processing
const batchLocker = createMutex(50);

Benchmark results

These results do not introduce hooks by LogicalContext. See benchmarks/suites/.

You can run all benchmark suites with:

npm run benchmark

You can also run only the AsyncOperator benchmarks:

npm run benchmark -- --suite=async-operator

For machine-readable output:

npm run --silent benchmark:json -- --suite=async-operator

The benchmark table below is generated by ./run_benchmark.sh. Values depend on the machine and runtime environment.

| Benchmark | Operations/sec | Avg Time (ms) | Median Time (ms) | Std Dev (ms) | Total Time (ms) | | ------------------------------------------------------------------------ | -------------- | ------------- | ---------------- | ------------ | --------------- | | delay(0) | 1,074 | 1.083 | 1.078 | 0.076 | 1000.76 | | delay(1) | 1,082 | 1.086 | 1.079 | 0.091 | 1000.59 | | Mutex acquire/release | 259,111 | 0.005 | 0.003 | 0.076 | 1000.87 | | Semaphore(1) acquire/release | 295,582 | 0.004 | 0.003 | 0.069 | 1000 | | Semaphore(2) acquire/release | 287,243 | 0.005 | 0.003 | 0.081 | 1000 | | Semaphore(5) acquire/release | 292,272 | 0.004 | 0.003 | 0.08 | 1000 | | Semaphore(10) acquire/release | 285,535 | 0.005 | 0.003 | 0.074 | 1000 | | Semaphore(1) sequential (100x) | 11,351 | 0.102 | 0.084 | 0.287 | 1000.04 | | Semaphore(5) sequential (100x) | 11,316 | 0.103 | 0.084 | 0.297 | 1000.16 | | Semaphore(1) concurrent (10x) | 65,322 | 0.02 | 0.014 | 0.237 | 1000.02 | | Semaphore(2) concurrent (10x) | 60,323 | 0.021 | 0.014 | 0.101 | 1000.01 | | Semaphore(5) concurrent (10x) | 62,271 | 0.021 | 0.014 | 0.229 | 1000.6 | | Semaphore(2) high contention (20x) | 33,628 | 0.037 | 0.027 | 0.127 | 1000.02 | | Semaphore(5) high contention (50x) | 15,884 | 0.075 | 0.061 | 0.476 | 1000.01 | | Semaphore(5) maxCalls=10 sequential (100x) | 11,353 | 0.1 | 0.087 | 0.268 | 1001.04 | | Semaphore(5) maxCalls=50 sequential (100x) | 11,368 | 0.11 | 0.086 | 0.915 | 1036.13 | | Semaphore(5) maxCalls=100 sequential (100x) | 11,465 | 0.098 | 0.085 | 0.254 | 1000.03 | | ReaderWriterLock readLock acquire/release (write-preferring) | 211,300 | 0.006 | 0.005 | 0.125 | 1003.45 | | ReaderWriterLock writeLock acquire/release (write-preferring) | 210,102 | 0.007 | 0.005 | 0.451 | 1000 | | ReaderWriterLock readLock acquire/release (read-preferring) | 202,592 | 0.007 | 0.005 | 0.234 | 1000 | | ReaderWriterLock writeLock acquire/release (read-preferring) | 206,635 | 0.006 | 0.005 | 0.109 | 1000 | | ReaderWriterLock sequential reads (100x, write-preferring) | 10,950 | 0.106 | 0.087 | 0.273 | 1000.09 | | ReaderWriterLock sequential writes (100x, write-preferring) | 10,040 | 0.143 | 0.09 | 1.523 | 1000.08 | | ReaderWriterLock sequential reads (100x, read-preferring) | 10,966 | 0.106 | 0.086 | 0.259 | 1000.07 | | ReaderWriterLock sequential writes (100x, read-preferring) | 11,171 | 0.102 | 0.086 | 0.265 | 1000.08 | | ReaderWriterLock concurrent readers (10x, write-preferring) | 64,896 | 0.018 | 0.015 | 0.109 | 1000.01 | | ReaderWriterLock concurrent readers (20x, write-preferring) | 38,968 | 0.03 | 0.025 | 0.146 | 1000.02 | | ReaderWriterLock concurrent readers (10x, read-preferring) | 65,577 | 0.021 | 0.015 | 0.655 | 1000 | | ReaderWriterLock concurrent readers (20x, read-preferring) | 39,536 | 0.029 | 0.025 | 0.14 | 1000.01 | | ReaderWriterLock read-heavy (100 ops, write-preferring) | 7,753 | 0.158 | 0.115 | 0.228 | 1000.01 | | ReaderWriterLock read-heavy (100 ops, read-preferring) | 8,052 | 0.147 | 0.117 | 0.218 | 1000.38 | | ReaderWriterLock write-heavy (100 ops, write-preferring) | 7,698 | 0.152 | 0.126 | 0.764 | 1000.11 | | ReaderWriterLock write-heavy (100 ops, read-preferring) | 7,582 | 0.15 | 0.129 | 0.236 | 1000.11 | | ReaderWriterLock balanced (100 ops, write-preferring) | 7,237 | 0.17 | 0.126 | 0.265 | 1001.98 | | ReaderWriterLock balanced (100 ops, read-preferring) | 8,158 | 0.145 | 0.116 | 0.266 | 1000.02 | | ReaderWriterLock maxCalls=10 mixed (100 ops, write-preferring) | 8,268 | 0.137 | 0.116 | 0.204 | 1000.09 | | ReaderWriterLock maxCalls=50 mixed (100 ops, write-preferring) | 8,911 | 0.125 | 0.109 | 0.209 | 1000.06 | | ReaderWriterLock maxCalls=10 mixed (100 ops, read-preferring) | 8,361 | 0.134 | 0.117 | 0.199 | 1000.07 | | ReaderWriterLock maxCalls=50 mixed (100 ops, read-preferring) | 8,953 | 0.124 | 0.108 | 0.207 | 1000.01 | | ReaderWriterLock write-preference test (50 ops) | 15,933 | 0.074 | 0.06 | 0.155 | 1000.03 | | ReaderWriterLock read-preference test (50 ops) | 15,473 | 0.074 | 0.061 | 0.144 | 1000.01 | | Deferred resolve | 1,003,856 | 0.001 | 0.001 | 0.004 | 1000 | | Deferred reject/catch | 133,475 | 0.008 | 0.007 | 0.051 | 1000 | | defer callback | 609,937 | 0.002 | 0.002 | 0.002 | 1000 | | defer [setTimeout(0)] | 1,182 | 1.081 | 1.077 | 0.182 | 1001.06 | | onAbort setup/cleanup | 775,586 | 0.001 | 0.001 | 0.001 | 1000 | | Mutex Sequential (1000x) - maxCalls: 1 | 828 | 1.581 | 1.092 | 2.062 | 1000.84 | | Mutex Sequential (1000x) - maxCalls: 5 | 821 | 1.544 | 1.073 | 1.654 | 1000.65 | | Mutex Sequential (1000x) - maxCalls: 10 | 866 | 1.329 | 1.067 | 0.902 | 1000.9 | | Mutex Sequential (1000x) - maxCalls: 20 | 895 | 1.24 | 1.068 | 0.765 | 1000.68 | | Mutex Sequential (1000x) - maxCalls: 50 | 846 | 1.403 | 1.055 | 0.941 | 1001.77 | | Mutex Sequential (1000x) - maxCalls: 100 | 894 | 1.258 | 1.045 | 0.777 | 1000.46 | | Mutex Sequential (1000x) - maxCalls: 1000 | 920 | 1.267 | 1.044 | 2.515 | 1000.92 | | Mutex High-freq (500x) - maxCalls: 1 | 1,716 | 0.719 | 0.552 | 1.152 | 1000.42 | | Mutex High-freq (500x) - maxCalls: 5 | 1,712 | 0.691 | 0.539 | 0.696 | 1000.49 | | Mutex High-freq (500x) - maxCalls: 10 | 1,780 | 0.637 | 0.538 | 0.578 | 1000.3 | | Mutex High-freq (500x) - maxCalls: 20 | 1,815 | 0.679 | 0.537 | 2.953 | 1000.1 | | Mutex High-freq (500x) - maxCalls: 50 | 1,819 | 0.603 | 0.537 | 0.515 | 1000.39 | | Mutex High-freq (500x) - maxCalls: 100 | 1,813 | 0.602 | 0.536 | 0.491 | 1000.13 | | Mutex High-freq (500x) - maxCalls: 1000 | 1,834 | 0.595 | 0.535 | 0.479 | 1000.35 | | Mutex Concurrent (20x) - maxCalls: 1 | 16,719 | 0.071 | 0.058 | 0.831 | 1000.04 | | Mutex Concurrent (20x) - maxCalls: 5 | 30,918 | 0.037 | 0.031 | 0.106 | 1000.02 | | Mutex Concurrent (20x) - maxCalls: 10 | 35,457 | 0.032 | 0.028 | 0.112 | 1000 | | Mutex Concurrent (20x) - maxCalls: 20 | 38,797 | 0.031 | 0.025 | 0.315 | 1000 | | Mutex Concurrent (20x) - maxCalls: 50 | 39,698 | 0.028 | 0.025 | 0.107 | 1000.02 | | Mutex Concurrent (20x) - maxCalls: 100 | 39,646 | 0.03 | 0.025 | 0.331 | 1000.01 | | Mutex Concurrent (20x) - maxCalls: 1000 | 39,152 | 0.029 | 0.025 | 0.113 | 1000.02 | | Mutex Ultra-high-freq (2000x) - maxCalls: 1 | 429 | 2.988 | 2.155 | 4.031 | 1003.9 | | Mutex Ultra-high-freq (2000x) - maxCalls: 5 | 450 | 2.43 | 2.108 | 1.233 | 1000.97 | | Mutex Ultra-high-freq (2000x) - maxCalls: 10 | 455 | 2.376 | 2.105 | 1.093 | 1000.12 | | Mutex Ultra-high-freq (2000x) - maxCalls: 20 | 454 | 2.546 | 2.094 | 3.739 | 1000.65 | | Mutex Ultra-high-freq (2000x) - maxCalls: 50 | 458 | 2.333 | 2.095 | 0.956 | 1000.79 | | Mutex Ultra-high-freq (2000x) - maxCalls: 100 | 456 | 2.348 | 2.078 | 0.973 | 1000.44 | | Mutex Ultra-high-freq (2000x) - maxCalls: 1000 | 457 | 2.339 | 2.102 | 0.97 | 1000.91 | | Conditional trigger/wait | 525,765 | 0.002 | 0.002 | 0.006 | 1000 | | Conditional trigger reaction time | 485,457 | 0.002 | 0.002 | 0.024 | 1000 | | Conditional multiple waiters with trigger | 86,356 | 0.012 | 0.011 | 0.041 | 1000 | | ManuallyConditional raise/wait | 375,703 | 0.003 | 0.003 | 0.005 | 1000 | | ManuallyConditional raise reaction time | 366,014 | 0.003 | 0.003 | 0.014 | 1000 | | ManuallyConditional trigger/wait | 382,759 | 0.003 | 0.003 | 0.027 | 1000 | | ManuallyConditional trigger reaction time | 355,576 | 0.003 | 0.003 | 0.01 | 1000 | | ManuallyConditional multiple waiters with raise | 81,321 | 0.013 | 0.012 | 0.025 | 1000 | | ManuallyConditional multiple waiters with trigger | 78,183 | 0.013 | 0.012 | 0.017 | 1000 | | Conditional vs ManuallyConditional - single waiter (Conditional) | 540,861 | 0.002 | 0.002 | 0.004 | 1000 | | Conditional vs ManuallyConditional - single waiter (ManuallyConditional) | 372,273 | 0.003 | 0.003 | 0.006 | 1000 | | Conditional vs ManuallyConditional - batch waiters (Conditional) | 146,693 | 0.007 | 0.007 | 0.004 | 1000.01 | | Conditional vs ManuallyConditional - batch waiters (ManuallyConditional) | 130,035 | 0.008 | 0.007 | 0.029 | 1000.01 | | [Comparison] Mutex single acquire/release | 259,708 | 0.006 | 0.003 | 0.562 | 1000 | | [Comparison] Semaphore(1) single acquire/release | 299,682 | 0.004 | 0.003 | 0.075 | 1000 | | [Comparison] Mutex sequential (50x) | 17,488 | 0.074 | 0.054 | 0.849 | 1000.06 | | [Comparison] Semaphore(1) sequential (50x) | 21,430 | 0.056 | 0.044 | 0.197 | 1000.03 | | [Comparison] RWLock write-only sequential (50x) | 19,596 | 0.063 | 0.047 | 0.205 | 1000.01 | | [Comparison] Mutex concurrent (20x) | 36,904 | 0.032 | 0.026 | 0.122 | 1003.5 | | [Comparison] Semaphore(1) concurrent (20x) | 30,608 | 0.042 | 0.028 | 0.124 | 1000.06 | | [Comparison] RWLock write-only concurrent (20x) | 32,133 | 0.04 | 0.028 | 0.126 | 1000 | | [Comparison] Semaphore(5) for pool (20 requests) | 38,564 | 0.036 | 0.025 | 1.094 | 1000.01 | | [Comparison] 5 Mutexes round-robin (20 requests) | 24,071 | 0.053 | 0.037 | 0.201 | 1000.01 | | [Comparison] RWLock read-mostly (90% read) | 17,228 | 0.066 | 0.056 | 0.172 | 1000.05 | | [Comparison] Mutex for read-mostly (simulated) | 16,288 | 0.076 | 0.06 | 0.825 | 1000.04 | | [Scenario] Connection Pool - Semaphore(3) | 72,053 | 0.016 | 0.014 | 0.1 | 1000.01 | | [Scenario] Cache - RWLock (70% read, 30% write) | 26,320 | 0.044 | 0.037 | 0.173 | 1000.02 | | [Scenario] Critical Section - Mutex | 49,951 | 0.024 | 0.02 | 0.132 | 1005.46 | | [HighContention] Mutex (50 concurrent) | 15,432 | 0.073 | 0.064 | 0.192 | 1000 | | [HighContention] Semaphore(1) (50 concurrent) | 15,239 | 0.075 | 0.064 | 0.199 | 1000.05 | | [HighContention] Semaphore(10) (50 concurrent) | 16,618 | 0.071 | 0.058 | 0.228 | 1000.02 | | [HighContention] RWLock writes (50 concurrent) | 15,253 | 0.076 | 0.064 | 0.252 | 1001.12 | | [HighContention] RWLock reads (50 concurrent) | 18,199 | 0.063 | 0.052 | 0.18 | 1000.04 | | [AsyncOperator] toArray() | 36,727 | 0.028 | 0.026 | 0.024 | 1000.02 | | [AsyncOperator] toArray() on AsyncIterable | 9,192 | 0.112 | 0.106 | 0.045 | 1000.06 | | [AsyncOperator] map() -> toArray() | 17,498 | 0.06 | 0.055 | 0.047 | 1000 | | [AsyncOperator] map() -> toArray() on AsyncIterable | 5,140 | 0.226 | 0.174 | 0.136 | 1000.44 | | [AsyncOperator] map(async) -> toArray() | 13,518 | 0.081 | 0.069 | 0.06 | 1000.01 | | [AsyncOperator] flatMap() -> toArray() | 7,272 | 0.157 | 0.125 | 0.129 | 1000.11 | | [AsyncOperator] flatMap(async) -> toArray() | 6,951 | 0.148 | 0.14 | 0.058 | 1000.06 | | [AsyncOperator] filter() -> toArray() | 15,020 | 0.071 | 0.063 | 0.048 | 1000.07 | | [AsyncOperator] filter() -> toArray() on AsyncIterable | 6,363 | 0.173 | 0.146 | 0.093 | 1000.11 | | [AsyncOperator] filter(async) -> toArray() | 11,990 | 0.09 | 0.078 | 0.055 | 1000.12 | | [AsyncOperator] concat() -> toArray() | 18,289 | 0.058 | 0.053 | 0.069 | 1000.02 | | [AsyncOperator] choose() -> toArray() | 14,735 | 0.074 | 0.064 | 0.052 | 1000.88 | | [AsyncOperator] slice() -> toArray() | 15,938 | 0.066 | 0.061 | 0.045 | 1000.05 | | [AsyncOperator] distinct() -> toArray() | 16,856 | 0.063 | 0.056 | 0.047 | 1000.05 | | [AsyncOperator] distinctBy() -> toArray() | 15,943 | 0.067 | 0.059 | 0.067 | 1000.01 | | [AsyncOperator] skip() -> toArray() | 7,711 | 0.144 | 0.12 | 0.086 | 1000.1 | | [AsyncOperator] skipWhile() -> toArray() | 14,753 | 0.074 | 0.064 | 0.054 | 1000.05 | | [AsyncOperator] take() -> toArray() | 15,713 | 0.068 | 0.06 | 0.048 | 1000.01 | | [AsyncOperator] takeWhile() -> toArray() | 15,307 | 0.072 | 0.06 | 0.053 | 1000.14 | | [AsyncOperator] pairwise() -> toArray() | 9,951 | 0.115 | 0.091 | 0.084 | 1000.01 | | [AsyncOperator] zip() -> toArray() | 10,099 | 0.105 | 0.095 | 0.056 | 1000.08 | | [AsyncOperator] scan() -> toArray() | 11,857 | 0.087 | 0.082 | 0.047 | 1000 | | [AsyncOperator] union() -> toArray() | 10,105 | 0.102 | 0.096 | 0.047 | 1000.04 | | [AsyncOperator] unionBy() -> toArray() | 8,533 | 0.132 | 0.107 | 0.079 | 1000.08 | | [AsyncOperator] intersect() -> toArray() | 12,073 | 0.085 | 0.08 | 0.043 | 1000.03 | | [AsyncOperator] intersectBy() -> toArray() | 10,865 | 0.095 | 0.091 | 0.048 | 1000.05 | | [AsyncOperator] except() -> toArray() | 12,935 | 0.083 | 0.074 | 0.066 | 1000.01 | | [AsyncOperator] exceptBy() -> toArray() | 12,592 | 0.081 | 0.078 | 0.044 | 1000.07 | | [AsyncOperator] chunkBySize() -> toArray() | 19,965 | 0.052 | 0.049 | 0.041 | 1000.01 | | [AsyncOperator] windowed() -> toArray() | 9,945 | 0.104 | 0.097 | 0.048 | 1000.09 | | [AsyncOperator] flat() -> toArray() | 10,781 | 0.097 | 0.089 | 0.051 | 1000.02 | | [AsyncOperator] reverse() -> toArray() | 11,057 | 0.094 | 0.089 | 0.048 | 1000.05 | | [AsyncOperator] toReversed() -> toArray() | 11,107 | 0.094 | 0.088 | 0.078 | 1000.05 | | [AsyncOperator] sort() -> toArray() | 8,306 | 0.123 | 0.117 | 0.048 | 1000.11 | | [AsyncOperator] toSorted() -> toArray() | 8,700 | 0.12 | 0.11 | 0.055 | 1000.03 | | [AsyncOperator] forEach() | 41,074 | 0.025 | 0.024 | 0.009 | 1000.02 | | [AsyncOperator] reduce() | 39,909 | 0.025 | 0.024 | 0.008 | 1000.02 | | [AsyncOperator] reduceRight() | 33,283 | 0.03 | 0.029 | 0.014 | 1000.02 | | [AsyncOperator] some() | 40,059 | 0.025 | 0.024 | 0.008 | 1000.02 | | [AsyncOperator] every() | 40,837 | 0.025 | 0.024 | 0.011 | 1000.02 | | [AsyncOperator] find() | 40,632 | 0.025 | 0.024 | 0.008 | 1000.01 | | [AsyncOperator] findIndex() | 39,717 | 0.026 | 0.024 | 0.011 | 1000.01 | | [AsyncOperator] at() | 46,189 | 0.022 | 0.021 | 0.009 | 1000 | | [AsyncOperator] includes() | 41,313 | 0.025 | 0.024 | 0.011 | 1000.01 | | [AsyncOperator] indexOf() | 41,459 | 0.024 | 0.024 | 0.008 | 1000.01 | | [AsyncOperator] lastIndexOf() | 37,385 | 0.027 | 0.026 | 0.009 | 1000.01 | | [AsyncOperator] findLast() | 40,993 | 0.025 | 0.024 | 0.008 | 1000.01 | | [AsyncOperator] findLastIndex() | 41,058 | 0.025 | 0.024 | 0.008 | 1000.02 | | [AsyncOperator] min() | 38,433 | 0.026 | 0.025 | 0.008 | 1000.02 | | [AsyncOperator] minBy() | 36,195 | 0.029 | 0.026 | 0.015 | 1000.02 | | [AsyncOperator] max() | 35,691 | 0.031 | 0.026 | 0.019 | 1000.01 | | [AsyncOperator] maxBy() | 34,688 | 0.031 | 0.027 | 0.017 | 1000.02 | | [AsyncOperator] groupBy() | 30,537 | 0.035 | 0.031 | 0.017 | 1000.03 | | [AsyncOperator] countBy() | 30,991 | 0.034 | 0.031 | 0.014 | 1000.02 | | [AsyncOperator] join() | 35,589 | 0.029 | 0.027 | 0.01 | 1000 | | [AsyncOperator] linear chain(depth=5) -> toArray() | 6,558 | 0.156 | 0.151 | 0.057 | 1000.07 | | [AsyncOperator] linear chain(depth=5, async callbacks) -> toArray() | 5,525 | 0.186 | 0.176 | 0.069 | 1000.13 |

Test Environment: Node.js v24.11.1, linux x64
CPU: Intel(R) Core(TM) i9-9980XE CPU @ 3.00GHz
Memory: 62GB
Last Updated: 2026-04-02

License

Under MIT.