Module async

Asynchronous execution utilities.

Provides types and utilities for accepting possibly asynchronous values, suspending execution for a given duration, and pacing tasks with adaptive rate limiting and retries.

Possibly Asynchronous Values

Accept values supplied either directly or as promises:

import type { Awaitable } from '@metreeca/core/async';

async function label<T>(value: Awaitable<T>): Promise<string> {
  return String(await value); // Handles plain values and promises alike
}
Copy

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

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 behaviour:

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