Module async

Primitives for asynchronous operations.

Provides utilities for coordinating concurrent operations and managing execution flow.

Asynchronous Delays

Pause execution for a specified duration:

import { sleep } from '@metreeca/core/async';

async function retry(task: () => Promise<void>) {
  for (let i = 0; i < 3; i++) {
    try {
      await task();
      break;
    } catch (error) {
      await sleep(1000 * Math.pow(2, i)); // Exponential backoff: 1s, 2s, 4s
    }
  }
}
Copy

Mutual Exclusion

Prevent race conditions in concurrent operations:

import { createMutex, sleep } from '@metreeca/core/async';

const mutex = createMutex();
let counter = 0;

async function increment() {
  await mutex.execute(async () => {
    const current = counter;
    await sleep(10);              // Simulate async read
    counter = current + 1;        // Safe write - no race condition
  });
}
Copy

Adaptive Rate Limiting

Control execution rate with automatic backoff:

import { createThrottle } from '@metreeca/core/async';

const throttle = createThrottle({
  minimum: 100,   // At least 100ms between requests
  backoff: 2.0,   // Double delay on failure
  recover: 0.5    // Halve delay on success
});

async function fetchData(url: string) {
  await throttle.queue(true);
  try {
    const response = await fetch(url);
    await throttle.adapt(true);  // Success - speed up
    return response;
  } catch (error) {
    await throttle.adapt(false); // Failure - slow down
    throw error;
  }
}
Copy

Automatic Retry Logic

Combine throttling with intelligent retry behavior:

const result = await throttle.retry(
  () => fetch('https://api.example.com/data'),
  {
    attempts: 5,
    recover: (error) => {
      // Retry on network errors, skip on 4xx client errors
      if (error instanceof TypeError) return 0; // Use default backoff
      if (error.status >= 500) return 1000;     // Retry after 1s
      return undefined;                         // Don't retry
    }
  }
);
Copy