awaitly 1.35.0 → 2.0.0

package/dist/ratelimit.d.cts

@@ -1,458 +0,0 @@
-import { R as Result, c as AsyncResult } from './run-entry-DGs0tySr.cjs';
-import './errors.cjs';
-import './tagged-error.cjs';
-import './slugs.cjs';
-
-/**
- * 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";
-    };
-};
-
-export { type CombinedLimiterConfig, type ConcurrencyLimiter, type ConcurrencyLimiterConfig, type ConcurrencyLimiterStats, type CostBasedRateLimiter, type CostBasedRateLimiterConfig, type CostBasedRateLimiterStats, type FixedWindowLimiter, type FixedWindowLimiterConfig, type FixedWindowLimiterStats, type QueueFullError, type RateLimitExceededError, type RateLimiter, type RateLimiterConfig, type RateLimiterStats, createCombinedLimiter, createConcurrencyLimiter, createCostBasedRateLimiter, createFixedWindowLimiter, createRateLimiter, isQueueFullError, isRateLimitExceededError, rateLimiterPresets };