awaitly 2.0.0 → 3.0.0

package/dist/reliability.d.ts

@@ -0,0 +1,1442 @@
+export { PolicyDelay, PolicyFn, RetryPolicyOptions, fallback, retry, timeout } from './run.js';
+import { R as Result, A as AsyncResult, j as StepOptions, d as RetryOptions, T as TimeoutOptions } from './index-Cv4K_3sZ.js';
+import { D as Duration } from './duration-BjVn3QpB.js';
+import './result.js';
+import './errors-sDSeaZBO.js';
+
+/**
+ * Circuit Breaker for Steps
+ *
+ * Prevents cascading failures by tracking step failure rates and
+ * short-circuiting calls when a threshold is exceeded.
+ *
+ * Uses the circuit breaker pattern with three states:
+ * - CLOSED: Normal operation (steps executing)
+ * - OPEN: Fast-fail mode (steps blocked)
+ * - HALF_OPEN: Testing if service recovered
+ *
+ * @example
+ * ```typescript
+ * import { createCircuitBreaker } from 'awaitly';
+ *
+ * const breaker = createCircuitBreaker({
+ *   failureThreshold: 5,
+ *   resetTimeout: 30000,
+ *   halfOpenMax: 3,
+ * });
+ *
+ * const result = await workflow(async ({ step }) => {
+ *   const data = await breaker.execute(
+ *     () => step(() => callExternalApi()),
+ *     { name: 'external-api' }
+ *   );
+ *   return data;
+ * });
+ * ```
+ */
+
+/**
+ * Circuit breaker state.
+ */
+type CircuitState = "CLOSED" | "OPEN" | "HALF_OPEN";
+/**
+ * Configuration for circuit breaker behavior.
+ */
+interface CircuitBreakerConfig {
+    /**
+     * Number of failures within the window before opening the circuit.
+     * @default 5
+     */
+    failureThreshold: number;
+    /**
+     * Time in ms to wait before transitioning from OPEN to HALF_OPEN.
+     * @default 30000 (30 seconds)
+     */
+    resetTimeout: number;
+    /**
+     * Time window in ms for counting failures.
+     * Failures older than this are discarded.
+     * @default 60000 (1 minute)
+     */
+    windowSize: number;
+    /**
+     * Maximum number of test requests allowed in HALF_OPEN state.
+     * If all succeed, circuit closes. If any fail, circuit reopens.
+     * @default 3
+     */
+    halfOpenMax: number;
+    /**
+     * Optional callback when circuit state changes.
+     */
+    onStateChange?: (from: CircuitState, to: CircuitState, name?: string) => void;
+}
+/**
+ * Error thrown when the circuit is open and calls are blocked.
+ */
+declare class CircuitOpenError extends Error {
+    readonly type: "CIRCUIT_OPEN";
+    readonly circuitName: string;
+    readonly state: CircuitState;
+    readonly retryAfterMs: number;
+    constructor(options: {
+        circuitName: string;
+        state: CircuitState;
+        retryAfterMs: number;
+        message?: string;
+    });
+}
+/**
+ * Type guard for CircuitOpenError.
+ */
+declare function isCircuitOpenError(error: unknown): error is CircuitOpenError;
+/**
+ * Circuit breaker statistics.
+ */
+interface CircuitBreakerStats {
+    state: CircuitState;
+    failureCount: number;
+    successCount: number;
+    lastFailureTime: number | null;
+    lastSuccessTime: number | null;
+    halfOpenSuccesses: number;
+}
+/**
+ * Circuit breaker instance for protecting external calls.
+ */
+interface CircuitBreaker {
+    /**
+     * Execute an operation with circuit breaker protection.
+     * Throws CircuitOpenError if the circuit is open.
+     *
+     * @param operation - The operation to execute
+     * @param options - Optional name for logging/metrics
+     * @returns The operation result
+     * @throws CircuitOpenError if circuit is open
+     */
+    execute<T>(operation: () => T | Promise<T>, options?: {
+        name?: string;
+    }): Promise<T>;
+    /**
+     * Execute a Result-returning operation with circuit breaker protection.
+     * Returns a CircuitOpenError result instead of throwing.
+     *
+     * @param operation - The operation returning a Result
+     * @param options - Optional name for logging/metrics
+     * @returns Result with the value or CircuitOpenError
+     */
+    executeResult<T, E>(operation: () => Result<T, E> | AsyncResult<T, E>, options?: {
+        name?: string;
+    }): AsyncResult<T, E | CircuitOpenError>;
+    /**
+     * Get current circuit state.
+     */
+    getState(): CircuitState;
+    /**
+     * Get circuit breaker statistics.
+     */
+    getStats(): CircuitBreakerStats;
+    /**
+     * Manually reset the circuit breaker to CLOSED state.
+     */
+    reset(): void;
+    /**
+     * Manually open the circuit (for testing or manual intervention).
+     */
+    forceOpen(): void;
+    /**
+     * Record a manual success (useful for health checks).
+     */
+    recordSuccess(): void;
+    /**
+     * Record a manual failure (useful for health checks).
+     */
+    recordFailure(error?: unknown): void;
+}
+/**
+ * Create a circuit breaker instance.
+ *
+ * @param name - Name for this circuit breaker (used in errors and logging)
+ * @param config - Configuration options
+ * @returns A CircuitBreaker instance
+ *
+ * @example
+ * ```typescript
+ * const apiBreaker = createCircuitBreaker('external-api', {
+ *   failureThreshold: 5,
+ *   resetTimeout: 30000,
+ * });
+ *
+ * // In workflow
+ * const data = await apiBreaker.execute(() =>
+ *   step(() => fetchFromApi(id))
+ * );
+ * ```
+ */
+declare function createCircuitBreaker(name: string, config?: Partial<CircuitBreakerConfig>): CircuitBreaker;
+/**
+ * Preset configurations for common use cases.
+ */
+declare const circuitBreakerPresets: {
+    /**
+     * Aggressive circuit breaker for critical paths.
+     * Opens quickly (3 failures) and recovers slowly (60s).
+     */
+    readonly critical: {
+        failureThreshold: number;
+        resetTimeout: number;
+        windowSize: number;
+        halfOpenMax: number;
+    };
+    /**
+     * Standard circuit breaker for typical API calls.
+     * Balanced between stability and availability.
+     */
+    readonly standard: {
+        failureThreshold: number;
+        resetTimeout: number;
+        windowSize: number;
+        halfOpenMax: number;
+    };
+    /**
+     * Lenient circuit breaker for non-critical operations.
+     * Opens slowly (10 failures) and recovers quickly (15s).
+     */
+    readonly lenient: {
+        failureThreshold: number;
+        resetTimeout: number;
+        windowSize: number;
+        halfOpenMax: number;
+    };
+};
+
+/**
+ * Rate Limiting / Concurrency Control
+ *
+ * Control throughput for steps that hit rate-limited APIs or shared resources.
+ *
+ * @example
+ * ```typescript
+ * import { createRateLimiter, createConcurrencyLimiter } from 'awaitly';
+ *
+ * // Rate limiting (requests per second)
+ * const rateLimiter = createRateLimiter({ maxPerSecond: 10 });
+ *
+ * // Concurrency limiting (max concurrent)
+ * const concurrencyLimiter = createConcurrencyLimiter({ maxConcurrent: 5 });
+ *
+ * const result = await workflow(async ({ step }) => {
+ *   // Wrap operations with rate limiting
+ *   const data = await rateLimiter.execute(() =>
+ *     step(() => callRateLimitedApi())
+ *   );
+ *
+ *   // Wrap batch operations with concurrency control
+ *   const results = await concurrencyLimiter.executeAll(
+ *     ids.map(id => () => step(() => fetchItem(id)))
+ *   );
+ *
+ *   return { data, results };
+ * });
+ * ```
+ */
+
+/**
+ * Configuration for rate limiter.
+ */
+interface RateLimiterConfig {
+    /**
+     * Maximum operations per second.
+     */
+    maxPerSecond: number;
+    /**
+     * Burst capacity - allows brief spikes above the rate.
+     * @default maxPerSecond * 2
+     */
+    burstCapacity?: number;
+    /**
+     * Strategy when rate limit is exceeded.
+     * - 'wait': Wait until a slot is available (default)
+     * - 'reject': Reject immediately with error
+     * @default 'wait'
+     */
+    strategy?: "wait" | "reject";
+}
+/**
+ * Configuration for concurrency limiter.
+ */
+interface ConcurrencyLimiterConfig {
+    /**
+     * Maximum concurrent operations.
+     */
+    maxConcurrent: number;
+    /**
+     * Strategy when limit is reached.
+     * - 'queue': Queue and wait (default)
+     * - 'reject': Reject immediately
+     * @default 'queue'
+     */
+    strategy?: "queue" | "reject";
+    /**
+     * Maximum queue size (only for 'queue' strategy).
+     * @default Infinity
+     */
+    maxQueueSize?: number;
+}
+/**
+ * Error when rate/concurrency limit is exceeded and strategy is 'reject'.
+ */
+interface RateLimitExceededError {
+    type: "RATE_LIMIT_EXCEEDED";
+    limiterName: string;
+    retryAfterMs?: number;
+}
+/**
+ * Error when concurrency limit queue is full.
+ */
+interface QueueFullError {
+    type: "QUEUE_FULL";
+    limiterName: string;
+    queueSize: number;
+    maxQueueSize: number;
+}
+/**
+ * Type guard for RateLimitExceededError.
+ */
+declare function isRateLimitExceededError(error: unknown): error is RateLimitExceededError;
+/**
+ * Type guard for QueueFullError.
+ */
+declare function isQueueFullError(error: unknown): error is QueueFullError;
+/**
+ * Statistics for rate limiter.
+ */
+interface RateLimiterStats {
+    availableTokens: number;
+    maxTokens: number;
+    tokensPerSecond: number;
+    waitingCount: number;
+}
+/**
+ * Statistics for concurrency limiter.
+ */
+interface ConcurrencyLimiterStats {
+    activeCount: number;
+    maxConcurrent: number;
+    queueSize: number;
+    maxQueueSize: number;
+}
+/**
+ * Rate limiter interface.
+ */
+interface RateLimiter {
+    /**
+     * Execute an operation with rate limiting.
+     * @param operation - The operation to execute
+     * @returns The operation result
+     */
+    execute<T>(operation: () => T | Promise<T>): Promise<T>;
+    /**
+     * Execute a Result-returning operation with rate limiting.
+     */
+    executeResult<T, E>(operation: () => Result<T, E> | AsyncResult<T, E>): AsyncResult<T, E | RateLimitExceededError>;
+    /**
+     * Get current statistics.
+     */
+    getStats(): RateLimiterStats;
+    /**
+     * Reset the rate limiter.
+     */
+    reset(): void;
+}
+/**
+ * Create a token bucket rate limiter.
+ *
+ * @param name - Name for the limiter (used in errors)
+ * @param config - Rate limiter configuration
+ * @returns A RateLimiter instance
+ *
+ * @example
+ * ```typescript
+ * const limiter = createRateLimiter('api-calls', {
+ *   maxPerSecond: 10,
+ *   burstCapacity: 20,
+ * });
+ *
+ * // In workflow
+ * const data = await limiter.execute(() =>
+ *   step(() => callApi())
+ * );
+ * ```
+ */
+declare function createRateLimiter(name: string, config: RateLimiterConfig): RateLimiter;
+/**
+ * Concurrency limiter interface.
+ */
+interface ConcurrencyLimiter {
+    /**
+     * Execute an operation with concurrency limiting.
+     * @param operation - The operation to execute
+     * @returns The operation result
+     */
+    execute<T>(operation: () => T | Promise<T>): Promise<T>;
+    /**
+     * Execute multiple operations with concurrency control.
+     * @param operations - Array of operation factories
+     * @returns Array of results (in order)
+     */
+    executeAll<T>(operations: Array<() => T | Promise<T>>): Promise<T[]>;
+    /**
+     * Execute a Result-returning operation with concurrency limiting.
+     */
+    executeResult<T, E>(operation: () => Result<T, E> | AsyncResult<T, E>): AsyncResult<T, E | QueueFullError>;
+    /**
+     * Get current statistics.
+     */
+    getStats(): ConcurrencyLimiterStats;
+    /**
+     * Reset the concurrency limiter.
+     */
+    reset(): void;
+}
+/**
+ * Create a concurrency limiter.
+ *
+ * @param name - Name for the limiter (used in errors)
+ * @param config - Concurrency limiter configuration
+ * @returns A ConcurrencyLimiter instance
+ *
+ * @example
+ * ```typescript
+ * const limiter = createConcurrencyLimiter('db-pool', {
+ *   maxConcurrent: 10,
+ * });
+ *
+ * // Execute with concurrency control
+ * const results = await limiter.executeAll(
+ *   ids.map(id => () => fetchItem(id))
+ * );
+ * ```
+ */
+declare function createConcurrencyLimiter(name: string, config: ConcurrencyLimiterConfig): ConcurrencyLimiter;
+/**
+ * Configuration for combined rate + concurrency limiter.
+ */
+interface CombinedLimiterConfig {
+    /**
+     * Rate limiting configuration.
+     */
+    rate?: RateLimiterConfig;
+    /**
+     * Concurrency limiting configuration.
+     */
+    concurrency?: ConcurrencyLimiterConfig;
+}
+/**
+ * Create a combined rate + concurrency limiter.
+ *
+ * Operations are first rate-limited, then concurrency-limited.
+ *
+ * @param name - Name for the limiter
+ * @param config - Combined limiter configuration
+ * @returns An object with both limiters and a combined execute function
+ *
+ * @example
+ * ```typescript
+ * const limiter = createCombinedLimiter('api', {
+ *   rate: { maxPerSecond: 10 },
+ *   concurrency: { maxConcurrent: 5 },
+ * });
+ *
+ * const result = await limiter.execute(() => callApi());
+ * ```
+ */
+declare function createCombinedLimiter(name: string, config: CombinedLimiterConfig): {
+    rate?: RateLimiter;
+    concurrency?: ConcurrencyLimiter;
+    execute: <T>(operation: () => T | Promise<T>) => Promise<T>;
+};
+/**
+ * Configuration for fixed window rate limiter.
+ */
+interface FixedWindowLimiterConfig {
+    /**
+     * Maximum requests allowed per window.
+     */
+    limit: number;
+    /**
+     * Window duration in milliseconds.
+     * @default 1000 (1 second)
+     */
+    windowMs?: number;
+    /**
+     * Strategy when rate limit is exceeded.
+     * - 'wait': Wait until window resets (default)
+     * - 'reject': Reject immediately with error
+     * @default 'wait'
+     */
+    strategy?: "wait" | "reject";
+}
+/**
+ * Statistics for fixed window rate limiter.
+ */
+interface FixedWindowLimiterStats {
+    /** Requests made in current window */
+    requestCount: number;
+    /** Maximum requests allowed per window */
+    limit: number;
+    /** Window duration in milliseconds */
+    windowMs: number;
+    /** Time remaining until window reset (ms) */
+    remainingMs: number;
+    /** Number of requests waiting for next window */
+    waitingCount: number;
+}
+/**
+ * Fixed window rate limiter interface.
+ */
+interface FixedWindowLimiter {
+    /**
+     * Execute an operation with rate limiting.
+     * @param operation - The operation to execute
+     * @param cost - Optional cost for this operation (default: 1)
+     * @returns The operation result
+     */
+    execute<T>(operation: () => T | Promise<T>, cost?: number): Promise<T>;
+    /**
+     * Execute a Result-returning operation with rate limiting.
+     * @param operation - The operation to execute
+     * @param cost - Optional cost for this operation (default: 1)
+     */
+    executeResult<T, E>(operation: () => Result<T, E> | AsyncResult<T, E>, cost?: number): AsyncResult<T, E | RateLimitExceededError>;
+    /**
+     * Get current statistics.
+     */
+    getStats(): FixedWindowLimiterStats;
+    /**
+     * Reset the rate limiter.
+     */
+    reset(): void;
+}
+/**
+ * Create a fixed window rate limiter.
+ *
+ * Unlike token bucket, fixed window resets at fixed intervals.
+ * Simpler to reason about but can allow bursts at window boundaries.
+ *
+ * @param name - Name for the limiter (used in errors)
+ * @param config - Rate limiter configuration
+ * @returns A FixedWindowLimiter instance
+ *
+ * @example
+ * ```typescript
+ * const limiter = createFixedWindowLimiter('api-calls', {
+ *   limit: 100,       // 100 requests
+ *   windowMs: 60000,  // per minute
+ * });
+ *
+ * // In workflow
+ * const data = await limiter.execute(() => callApi());
+ *
+ * // Cost-based limiting (e.g., batch operations cost more)
+ * const batchData = await limiter.execute(() => callBatchApi(), 10);
+ * ```
+ */
+declare function createFixedWindowLimiter(name: string, config: FixedWindowLimiterConfig): FixedWindowLimiter;
+/**
+ * Configuration for cost-based rate limiter.
+ */
+interface CostBasedRateLimiterConfig {
+    /**
+     * Maximum tokens (credits) per second refill rate.
+     */
+    tokensPerSecond: number;
+    /**
+     * Maximum token capacity (burst capacity).
+     * @default tokensPerSecond * 2
+     */
+    maxTokens?: number;
+    /**
+     * Strategy when rate limit is exceeded.
+     * - 'wait': Wait until tokens are available (default)
+     * - 'reject': Reject immediately with error
+     * @default 'wait'
+     */
+    strategy?: "wait" | "reject";
+}
+/**
+ * Statistics for cost-based rate limiter.
+ */
+interface CostBasedRateLimiterStats {
+    /** Available tokens (can be fractional) */
+    availableTokens: number;
+    /** Maximum token capacity */
+    maxTokens: number;
+    /** Token refill rate per second */
+    tokensPerSecond: number;
+    /** Number of operations waiting */
+    waitingCount: number;
+}
+/**
+ * Cost-based rate limiter interface.
+ */
+interface CostBasedRateLimiter {
+    /**
+     * Execute an operation with cost-based rate limiting.
+     * @param operation - The operation to execute
+     * @param cost - Token cost for this operation (default: 1)
+     * @returns The operation result
+     */
+    execute<T>(operation: () => T | Promise<T>, cost?: number): Promise<T>;
+    /**
+     * Execute a Result-returning operation with cost-based rate limiting.
+     * @param operation - The operation to execute
+     * @param cost - Token cost for this operation (default: 1)
+     */
+    executeResult<T, E>(operation: () => Result<T, E> | AsyncResult<T, E>, cost?: number): AsyncResult<T, E | RateLimitExceededError>;
+    /**
+     * Get current statistics.
+     */
+    getStats(): CostBasedRateLimiterStats;
+    /**
+     * Reset the rate limiter.
+     */
+    reset(): void;
+}
+/**
+ * Create a cost-based token bucket rate limiter.
+ *
+ * Different operations can have different costs, allowing fine-grained
+ * control over resource usage. For example, a batch API call might cost
+ * 10 tokens while a simple query costs 1.
+ *
+ * @param name - Name for the limiter (used in errors)
+ * @param config - Rate limiter configuration
+ * @returns A CostBasedRateLimiter instance
+ *
+ * @example
+ * ```typescript
+ * const limiter = createCostBasedRateLimiter('api', {
+ *   tokensPerSecond: 100,  // 100 tokens/second refill
+ *   maxTokens: 200,        // Can burst up to 200 tokens
+ * });
+ *
+ * // Simple query costs 1 token
+ * await limiter.execute(() => simpleQuery());
+ *
+ * // Batch operation costs 10 tokens
+ * await limiter.execute(() => batchOperation(), 10);
+ *
+ * // Heavy export costs 50 tokens
+ * await limiter.execute(() => exportData(), 50);
+ * ```
+ */
+declare function createCostBasedRateLimiter(name: string, config: CostBasedRateLimiterConfig): CostBasedRateLimiter;
+/**
+ * Preset configurations for common use cases.
+ */
+declare const rateLimiterPresets: {
+    /**
+     * Typical API rate limit (10 req/s).
+     */
+    readonly api: {
+        maxPerSecond: number;
+        burstCapacity: number;
+        strategy: "wait";
+    };
+    /**
+     * Database pool limit (concurrent connections).
+     */
+    readonly database: {
+        maxConcurrent: number;
+        strategy: "queue";
+        maxQueueSize: number;
+    };
+    /**
+     * Aggressive rate limit for external APIs (5 req/s).
+     */
+    readonly external: {
+        maxPerSecond: number;
+        burstCapacity: number;
+        strategy: "wait";
+    };
+};
+
+/**
+ * awaitly/cache
+ *
+ * Caching utilities for memoization and deduplication.
+ * Inspired by Effect.js caching patterns.
+ *
+ * @example
+ * ```typescript
+ * import { cached, cachedWithTTL, cachedFunction, once } from 'awaitly';
+ *
+ * // Compute once, reuse forever
+ * const getConfig = cached(() => loadConfig());
+ *
+ * // Expire after duration
+ * const getUser = cachedWithTTL(() => fetchUser(id), { ttl: '5m' });
+ *
+ * // Memoize by arguments
+ * const fetchUserMemo = cachedFunction((id: string) => fetchUser(id));
+ *
+ * // Execute exactly once (for initialization)
+ * const initDb = once(() => connectToDatabase());
+ * ```
+ */
+
+/**
+ * Duration input type - supports Duration objects or string shorthand.
+ */
+type DurationInput = Duration | string;
+/**
+ * Cache entry with metadata.
+ */
+interface CacheEntry<T> {
+    value: T;
+    timestamp: number;
+    expiresAt?: number;
+}
+/**
+ * Cache options.
+ */
+interface CacheOptions {
+    /**
+     * Time-to-live for cached values.
+     * Accepts Duration or string shorthand like "5m", "1h", "30s".
+     */
+    ttl?: DurationInput;
+}
+/**
+ * Cached function options.
+ */
+interface CachedFunctionOptions<Args extends unknown[]> {
+    /**
+     * Custom key generator for arguments.
+     * Default: JSON.stringify(args)
+     */
+    keyFn?: (...args: Args) => string;
+    /**
+     * Time-to-live for cached values.
+     */
+    ttl?: DurationInput;
+    /**
+     * Maximum cache size. When exceeded, oldest entries are evicted.
+     * @default Infinity
+     */
+    maxSize?: number;
+}
+/**
+ * Cache statistics.
+ */
+interface CacheStats {
+    hits: number;
+    misses: number;
+    size: number;
+}
+/**
+ * Create a cached computation that executes once and reuses the result.
+ *
+ * The function is called at most once, even with concurrent calls.
+ * Subsequent calls return the cached value immediately.
+ *
+ * @param fn - Function to compute the cached value
+ * @returns Function that returns the cached value
+ *
+ * @example
+ * ```typescript
+ * const getConfig = cached(async () => {
+ *   console.log('Loading config...');
+ *   return await loadConfigFromFile();
+ * });
+ *
+ * // First call executes the function
+ * const config1 = await getConfig(); // "Loading config..."
+ *
+ * // Subsequent calls return cached value
+ * const config2 = await getConfig(); // No log, instant return
+ * const config3 = await getConfig(); // No log, instant return
+ * ```
+ */
+declare function cached<T>(fn: () => T | Promise<T>): () => Promise<T>;
+/**
+ * Create a cached computation that expires after a duration.
+ *
+ * The function is re-executed when the TTL expires.
+ * Concurrent calls while computing share the same promise.
+ *
+ * @param fn - Function to compute the cached value
+ * @param options - Cache options including TTL
+ * @returns Function that returns the cached value
+ *
+ * @example
+ * ```typescript
+ * const getUser = cachedWithTTL(
+ *   async () => await fetchUser(userId),
+ *   { ttl: '5m' }  // Cache for 5 minutes
+ * );
+ *
+ * const user1 = await getUser(); // Fetches from API
+ * const user2 = await getUser(); // Returns cached (within 5 min)
+ *
+ * // After 5 minutes...
+ * const user3 = await getUser(); // Fetches again
+ * ```
+ */
+declare function cachedWithTTL<T>(fn: () => T | Promise<T>, options: {
+    ttl: DurationInput;
+}): () => Promise<T>;
+/**
+ * Memoized function interface.
+ */
+interface MemoizedFunction<Args extends unknown[], T> {
+    (...args: Args): Promise<T>;
+    /** Clear the entire cache */
+    clear(): void;
+    /** Clear a specific cache entry */
+    delete(...args: Args): boolean;
+    /** Check if an entry exists */
+    has(...args: Args): boolean;
+    /** Get cache statistics */
+    getStats(): CacheStats;
+}
+/**
+ * Create a memoized function that caches results by arguments.
+ *
+ * Each unique set of arguments produces a cached result.
+ * Supports TTL and max size limits.
+ *
+ * @param fn - Function to memoize
+ * @param options - Memoization options
+ * @returns Memoized function with cache control methods
+ *
+ * @example
+ * ```typescript
+ * const fetchUserMemo = cachedFunction(
+ *   async (id: string) => await fetchUser(id),
+ *   { ttl: '5m', maxSize: 100 }
+ * );
+ *
+ * const user1 = await fetchUserMemo('user-1'); // Fetches
+ * const user2 = await fetchUserMemo('user-2'); // Fetches
+ * const user1Again = await fetchUserMemo('user-1'); // Cached!
+ *
+ * // Cache control
+ * fetchUserMemo.delete('user-1'); // Remove specific entry
+ * fetchUserMemo.clear(); // Clear all
+ * console.log(fetchUserMemo.getStats()); // { hits: 1, misses: 2, size: 0 }
+ * ```
+ */
+declare function cachedFunction<Args extends unknown[], T>(fn: (...args: Args) => T | Promise<T>, options?: CachedFunctionOptions<Args>): MemoizedFunction<Args, T>;
+/**
+ * Once-executed function interface.
+ */
+interface OnceFunction<T> {
+    (): Promise<T>;
+    /** Check if the function has been called */
+    called: boolean;
+    /** Check if execution completed successfully */
+    completed: boolean;
+    /** Check if execution failed */
+    failed: boolean;
+    /** Reset to allow re-execution */
+    reset(): void;
+}
+/**
+ * Create a function that executes exactly once.
+ *
+ * Useful for initialization code that should only run once.
+ * Subsequent calls return the same result or re-throw the same error.
+ *
+ * @param fn - Function to execute once
+ * @returns Function that executes once and returns the result
+ *
+ * @example
+ * ```typescript
+ * const initDb = once(async () => {
+ *   console.log('Connecting to database...');
+ *   const conn = await createConnection();
+ *   return conn;
+ * });
+ *
+ * // First call executes
+ * const db1 = await initDb(); // "Connecting to database..."
+ *
+ * // Subsequent calls return cached result
+ * const db2 = await initDb(); // Instant, same connection
+ * const db3 = await initDb(); // Instant, same connection
+ *
+ * console.log(initDb.called); // true
+ * console.log(initDb.completed); // true
+ * ```
+ */
+declare function once<T>(fn: () => T | Promise<T>): OnceFunction<T>;
+/**
+ * General purpose cache interface.
+ */
+interface Cache<K, V> {
+    /** Get a value from the cache */
+    get(key: K): V | undefined;
+    /** Set a value in the cache */
+    set(key: K, value: V, options?: {
+        ttl?: DurationInput;
+    }): void;
+    /** Check if a key exists */
+    has(key: K): boolean;
+    /** Delete a key from the cache */
+    delete(key: K): boolean;
+    /** Clear the entire cache */
+    clear(): void;
+    /** Get the cache size */
+    size: number;
+    /** Get cache statistics */
+    getStats(): CacheStats;
+}
+/**
+ * Cache configuration.
+ */
+interface CacheConfig {
+    /**
+     * Default TTL for all entries.
+     */
+    defaultTTL?: DurationInput;
+    /**
+     * Maximum cache size.
+     * @default Infinity
+     */
+    maxSize?: number;
+}
+/**
+ * Create a general-purpose cache with TTL and size limits.
+ *
+ * @param config - Cache configuration
+ * @returns A Cache instance
+ *
+ * @example
+ * ```typescript
+ * const cache = createCache<string, User>({
+ *   defaultTTL: '5m',
+ *   maxSize: 1000,
+ * });
+ *
+ * cache.set('user:1', user);
+ * cache.set('user:2', user2, { ttl: '1h' }); // Override TTL
+ *
+ * const user = cache.get('user:1');
+ * ```
+ */
+declare function createCache<K, V>(config?: CacheConfig): Cache<K, V>;
+
+/**
+ * awaitly/singleflight
+ *
+ * Request coalescing - dedupe concurrent identical requests.
+ * Multiple concurrent calls with the same key share one in-flight request.
+ *
+ * @example
+ * ```typescript
+ * import { singleflight } from 'awaitly';
+ *
+ * const fetchUserOnce = singleflight(
+ *   (id: string) => fetchUser(id),
+ *   { key: (id) => `user:${id}` }
+ * );
+ *
+ * // All concurrent calls share one request
+ * const [user1, user2] = await Promise.all([
+ *   fetchUserOnce('1'),
+ *   fetchUserOnce('1'),  // Same key - shares request
+ * ]);
+ * ```
+ */
+
+/**
+ * Options for the singleflight wrapper.
+ */
+type SingleflightOptions<Args extends unknown[]> = {
+    /**
+     * Extract cache key from arguments.
+     * Calls with the same key will share one in-flight request.
+     */
+    key: (...args: Args) => string;
+    /**
+     * Optional TTL in milliseconds to cache successful results.
+     * After TTL expires, next call will trigger a fresh request.
+     * @default 0 (no caching after completion - only dedupes in-flight requests)
+     */
+    ttl?: number;
+};
+/**
+ * Create a singleflight-wrapped function.
+ * Concurrent calls with the same key share one in-flight request.
+ *
+ * ## How It Works
+ *
+ * 1. First caller with a key starts the operation
+ * 2. Subsequent callers with the same key get the same Promise
+ * 3. When operation completes, all callers receive the same Result
+ * 4. Key is removed from in-flight tracking (unless TTL is set)
+ *
+ * ## Use Cases
+ *
+ * - **Prevent thundering herd**: Multiple requests for the same user
+ * - **API deduplication**: Avoid duplicate network calls
+ * - **Expensive operations**: Share computation across callers
+ *
+ * @param operation - The async operation that returns an AsyncResult
+ * @param options - Configuration with key extraction function
+ * @returns A wrapped function that deduplicates concurrent calls
+ *
+ * @example
+ * ```typescript
+ * import { singleflight } from 'awaitly';
+ * import { ok, err, type AsyncResult } from 'awaitly';
+ *
+ * const fetchUser = async (id: string): AsyncResult<User, 'NOT_FOUND'> =>
+ *   id !== '0' ? ok({ id, name: `User ${id}` }) : err('NOT_FOUND');
+ *
+ * const fetchUserOnce = singleflight(fetchUser, {
+ *   key: (id) => `user:${id}`,
+ * });
+ *
+ * // Concurrent calls share one request
+ * const [a, b, c] = await Promise.all([
+ *   fetchUserOnce('1'),  // Triggers fetch
+ *   fetchUserOnce('1'),  // Joins existing fetch
+ *   fetchUserOnce('2'),  // Different key - new fetch
+ * ]);
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With TTL for result caching
+ * const fetchUserCached = singleflight(fetchUser, {
+ *   key: (id) => `user:${id}`,
+ *   ttl: 5000,  // Cache successful results for 5 seconds
+ * });
+ *
+ * const user1 = await fetchUserCached('1');  // Fetches
+ * const user2 = await fetchUserCached('1');  // Returns cached (within TTL)
+ * // After 5 seconds...
+ * const user3 = await fetchUserCached('1');  // Fetches again
+ * ```
+ */
+declare function singleflight<Args extends unknown[], T, E, C = unknown>(operation: (...args: Args) => AsyncResult<T, E, C>, options: SingleflightOptions<Args>): (...args: Args) => AsyncResult<T, E, C>;
+/**
+ * Create a singleflight group with manual key management.
+ * More flexible but lower-level API than the `singleflight` wrapper.
+ *
+ * @returns A group object with execute, isInflight, and clear methods
+ *
+ * @example
+ * ```typescript
+ * import { createSingleflightGroup } from 'awaitly';
+ *
+ * const group = createSingleflightGroup<User, 'NOT_FOUND'>();
+ *
+ * // Execute with manual key
+ * const user1 = await group.execute('user:1', () => fetchUser('1'));
+ * const user2 = await group.execute('user:1', () => fetchUser('1')); // Shares request
+ *
+ * // Check if request is in-flight
+ * if (group.isInflight('user:1')) {
+ *   console.log('Request pending');
+ * }
+ *
+ * // Clear all in-flight requests
+ * group.clear();
+ * ```
+ */
+declare function createSingleflightGroup<T, E, C = unknown>(): {
+    /**
+     * Execute or join an in-flight request for the given key.
+     */
+    execute: (key: string, operation: () => AsyncResult<T, E, C>) => AsyncResult<T, E, C>;
+    /**
+     * Check if a request is currently in-flight for the key.
+     */
+    isInflight: (key: string) => boolean;
+    /**
+     * Get the number of in-flight requests.
+     */
+    size: () => number;
+    /**
+     * Clear all in-flight tracking (does not cancel operations).
+     */
+    clear: () => void;
+};
+
+/**
+ * awaitly/policies
+ *
+ * Policy-Driven Step Middleware - Reusable bundles of StepOptions
+ * that can be composed and applied per-workflow or per-step.
+ */
+
+/**
+ * A policy is a partial StepOptions that can be merged with other policies.
+ */
+type Policy = Partial<StepOptions>;
+/**
+ * A policy factory that creates policies based on context.
+ */
+type PolicyFactory<T = void> = T extends void ? () => Policy : (context: T) => Policy;
+/**
+ * Named policy with metadata.
+ */
+interface NamedPolicy {
+    name: string;
+    policy: Policy;
+    description?: string;
+}
+/**
+ * Merge multiple policies into a single StepOptions object.
+ * Later policies override earlier ones for conflicting properties.
+ * Retry and timeout options are deep-merged.
+ *
+ * @param policies - Policies to merge (in order of precedence)
+ * @returns Merged StepOptions
+ *
+ * @example
+ * ```typescript
+ * const merged = mergePolicies(
+ *   timeoutPolicies.api,      // timeout: 5000ms
+ *   retryPolicies.transient,  // retry: 3 attempts
+ *   { name: 'fetch-user' }    // name override
+ * );
+ * ```
+ */
+declare function mergePolicies(...policies: Policy[]): StepOptions;
+/**
+ * Create a policy applier that merges base policies with step-specific options.
+ *
+ * @param basePolicies - Base policies to apply to all steps
+ * @returns A function that applies policies to step options
+ *
+ * @example
+ * ```typescript
+ * const applyPolicy = createPolicyApplier(
+ *   timeoutPolicies.api,
+ *   retryPolicies.transient
+ * );
+ *
+ * // In workflow
+ * const user = await step(
+ *   'fetch-user',
+ *   () => fetchUser(id),
+ *   applyPolicy({ key: 'user:' + id })
+ * );
+ * ```
+ */
+declare function createPolicyApplier(...basePolicies: Policy[]): (stepOptions?: StepOptions) => StepOptions;
+/**
+ * Create a named policy bundle for reuse across workflows.
+ *
+ * @param name - Policy bundle name
+ * @param policies - Policies to include in the bundle
+ * @returns Named policy object
+ */
+declare function createPolicyBundle(name: string, ...policies: Policy[]): NamedPolicy;
+/**
+ * Create a retry policy with the given options.
+ */
+declare function retryPolicy(options: RetryOptions): Policy;
+/**
+ * Pre-built retry policies for common scenarios.
+ */
+declare const retryPolicies: {
+    /**
+     * No retry - fail immediately on error.
+     */
+    readonly none: Partial<StepOptions>;
+    /**
+     * Quick retry for transient errors (3 attempts, fast backoff).
+     */
+    readonly transient: Partial<StepOptions>;
+    /**
+     * Standard retry for API calls (3 attempts, moderate backoff).
+     */
+    readonly standard: Partial<StepOptions>;
+    /**
+     * Aggressive retry for critical operations (5 attempts, longer backoff).
+     */
+    readonly aggressive: Partial<StepOptions>;
+    /**
+     * Fixed interval retry (useful for polling).
+     */
+    readonly fixed: (attempts: number, delayMs: number) => Policy;
+    /**
+     * Linear backoff retry.
+     */
+    readonly linear: (attempts: number, initialDelay: number) => Policy;
+    /**
+     * Custom retry policy builder.
+     */
+    readonly custom: (options: Partial<RetryOptions> & {
+        attempts: number;
+    }) => Policy;
+};
+/**
+ * Create a timeout policy with the given options.
+ */
+declare function timeoutPolicy(options: TimeoutOptions): Policy;
+/**
+ * Pre-built timeout policies for common scenarios.
+ */
+declare const timeoutPolicies: {
+    /**
+     * No timeout.
+     */
+    readonly none: Policy;
+    /**
+     * Fast timeout for quick operations (1 second).
+     */
+    readonly fast: Partial<StepOptions>;
+    /**
+     * Standard API timeout (5 seconds).
+     */
+    readonly api: Partial<StepOptions>;
+    /**
+     * Extended timeout for slower operations (30 seconds).
+     */
+    readonly extended: Partial<StepOptions>;
+    /**
+     * Long timeout for batch operations (2 minutes).
+     */
+    readonly long: Partial<StepOptions>;
+    /**
+     * Custom timeout in milliseconds.
+     */
+    readonly ms: (ms: number) => Policy;
+    /**
+     * Custom timeout in seconds.
+     */
+    readonly seconds: (seconds: number) => Policy;
+    /**
+     * Timeout with custom error.
+     */
+    readonly withError: <E>(ms: number, error: E) => Policy;
+    /**
+     * Timeout with AbortSignal support.
+     */
+    readonly withSignal: (ms: number) => Policy;
+};
+/**
+ * Pre-built combined policies for common service patterns.
+ */
+declare const servicePolicies: {
+    /**
+     * Policy for external HTTP APIs.
+     * - 5 second timeout
+     * - 3 retries with exponential backoff
+     */
+    readonly httpApi: StepOptions;
+    /**
+     * Policy for database operations.
+     * - 30 second timeout
+     * - 2 retries for transient errors
+     */
+    readonly database: StepOptions;
+    /**
+     * Policy for cache operations.
+     * - 1 second timeout
+     * - No retry (cache misses are not errors)
+     */
+    readonly cache: StepOptions;
+    /**
+     * Policy for message queue operations.
+     * - 30 second timeout
+     * - 5 retries with longer backoff
+     */
+    readonly messageQueue: StepOptions;
+    /**
+     * Policy for file operations.
+     * - 2 minute timeout
+     * - 3 retries
+     */
+    readonly fileSystem: StepOptions;
+    /**
+     * Policy for third-party services with rate limits.
+     * - 10 second timeout
+     * - 5 retries with linear backoff
+     */
+    readonly rateLimited: StepOptions;
+};
+/**
+ * Options for withPolicies workflow wrapper.
+ */
+interface WithPoliciesOptions {
+    /**
+     * Base policies applied to all steps.
+     */
+    policies: Policy[];
+    /**
+     * Step-specific policy overrides by name or key pattern.
+     */
+    overrides?: Record<string, Policy>;
+}
+/**
+ * Create step options with policies applied.
+ * This is a helper for applying policies inline.
+ *
+ * @param policies - Policies to apply
+ * @param stepOptions - Step-specific options
+ * @returns Merged StepOptions
+ *
+ * @example
+ * ```typescript
+ * const user = await step(
+ *   () => fetchUser(id),
+ *   withPolicy(servicePolicies.httpApi, { name: 'fetch-user' })
+ * );
+ * ```
+ */
+declare function withPolicy(policy: Policy, stepOptions?: StepOptions): StepOptions;
+/**
+ * Create step options with multiple policies applied.
+ *
+ * @param policies - Policies to apply (in order)
+ * @param stepOptions - Step-specific options
+ * @returns Merged StepOptions
+ *
+ * @example
+ * ```typescript
+ * const user = await step(
+ *   'fetch-user',
+ *   () => fetchUser(id),
+ *   withPolicies([timeoutPolicies.api, retryPolicies.standard])
+ * );
+ * ```
+ */
+declare function withPolicies(policies: Policy[], stepOptions?: StepOptions): StepOptions;
+/**
+ * Create a policy that applies conditionally.
+ *
+ * @param condition - Condition to check
+ * @param policy - Policy to apply if condition is true
+ * @param elsePolicy - Policy to apply if condition is false (optional)
+ * @returns The selected policy
+ *
+ * @example
+ * ```typescript
+ * const policy = conditionalPolicy(
+ *   isProduction,
+ *   servicePolicies.httpApi,     // Use in production
+ *   retryPolicies.none           // Skip in development
+ * );
+ * ```
+ */
+declare function conditionalPolicy(condition: boolean, policy: Policy, elsePolicy?: Policy): Policy;
+/**
+ * Create a policy based on environment.
+ *
+ * @param envPolicies - Map of environment names to policies
+ * @param currentEnv - Current environment (defaults to NODE_ENV)
+ * @param defaultPolicy - Default policy if environment not found
+ * @returns The selected policy
+ *
+ * @example
+ * ```typescript
+ * const policy = envPolicy({
+ *   production: servicePolicies.httpApi,
+ *   development: retryPolicies.none,
+ *   test: retryPolicies.none,
+ * });
+ * ```
+ */
+declare function envPolicy(envPolicies: Record<string, Policy>, currentEnv?: string, defaultPolicy?: Policy): Policy;
+/**
+ * A registry for managing named policies.
+ */
+interface PolicyRegistry {
+    /**
+     * Register a named policy.
+     */
+    register(name: string, policy: Policy): void;
+    /**
+     * Get a policy by name.
+     */
+    get(name: string): Policy | undefined;
+    /**
+     * Check if a policy exists.
+     */
+    has(name: string): boolean;
+    /**
+     * Get all registered policy names.
+     */
+    names(): string[];
+    /**
+     * Create step options using a registered policy.
+     */
+    apply(policyName: string, stepOptions?: StepOptions): StepOptions;
+}
+/**
+ * Create a policy registry for managing named policies.
+ *
+ * @returns PolicyRegistry instance
+ *
+ * @example
+ * ```typescript
+ * const registry = createPolicyRegistry();
+ *
+ * // Register policies
+ * registry.register('api', servicePolicies.httpApi);
+ * registry.register('db', servicePolicies.database);
+ *
+ * // Use in workflow
+ * const user = await step(
+ *   'fetch-user',
+ *   () => fetchUser(id),
+ *   registry.apply('api')
+ * );
+ * ```
+ */
+declare function createPolicyRegistry(): PolicyRegistry;
+/**
+ * Fluent builder for constructing step options.
+ */
+interface StepOptionsBuilder {
+    /**
+     * Set step key for caching.
+     */
+    key(key: string): StepOptionsBuilder;
+    /**
+     * Apply a policy.
+     */
+    policy(policy: Policy): StepOptionsBuilder;
+    /**
+     * Set timeout in milliseconds.
+     */
+    timeout(ms: number): StepOptionsBuilder;
+    /**
+     * Set retry options.
+     */
+    retry(options: RetryOptions): StepOptionsBuilder;
+    /**
+     * Set retry attempts (with default exponential backoff).
+     */
+    retries(attempts: number): StepOptionsBuilder;
+    /**
+     * Build the final StepOptions.
+     */
+    build(): StepOptions;
+}
+/**
+ * Create a fluent builder for step options.
+ *
+ * @returns StepOptionsBuilder instance
+ *
+ * @example
+ * ```typescript
+ * const options = stepOptions()
+ *   .key('user:123')
+ *   .timeout(5000)
+ *   .retries(3)
+ *   .build();
+ *
+ * const user = await step('fetch-user', () => fetchUser(id), options);
+ * ```
+ */
+declare function stepOptions(): StepOptionsBuilder;
+
+export { type Cache, type CacheConfig, type CacheEntry, type CacheOptions, type CacheStats, type CachedFunctionOptions, type CircuitBreaker, type CircuitBreakerConfig, type CircuitBreakerStats, CircuitOpenError, type CircuitState, type CombinedLimiterConfig, type ConcurrencyLimiter, type ConcurrencyLimiterConfig, type ConcurrencyLimiterStats, type CostBasedRateLimiter, type CostBasedRateLimiterConfig, type CostBasedRateLimiterStats, type DurationInput, type FixedWindowLimiter, type FixedWindowLimiterConfig, type FixedWindowLimiterStats, type MemoizedFunction, type NamedPolicy, type OnceFunction, type Policy, type PolicyFactory, type PolicyRegistry, type QueueFullError, type RateLimitExceededError, type RateLimiter, type RateLimiterConfig, type RateLimiterStats, type SingleflightOptions, type StepOptionsBuilder, type WithPoliciesOptions, cached, cachedFunction, cachedWithTTL, circuitBreakerPresets, conditionalPolicy, createCache, createCircuitBreaker, createCombinedLimiter, createConcurrencyLimiter, createCostBasedRateLimiter, createFixedWindowLimiter, createPolicyApplier, createPolicyBundle, createPolicyRegistry, createRateLimiter, createSingleflightGroup, envPolicy, isCircuitOpenError, isQueueFullError, isRateLimitExceededError, mergePolicies, once, rateLimiterPresets, retryPolicies, retryPolicy, servicePolicies, singleflight, stepOptions, timeoutPolicies, timeoutPolicy, withPolicies, withPolicy };