Waits for permission to execute a task, respecting throttling constraints.
Blocks (asynchronously) until the throttle determines it's safe to proceed based on current load and timing. Uses randomized sleep intervals to avoid thundering herd effects.
Optionaladapt: booleanIf true, increments the queue counter and expects completion feedback through the Throttle.adapt method. Defaults to false.
A promise that resolves with the time elapsed since the last task execution in milliseconds
Applies throttling to a value by waiting without affecting the queue counter.
This allows the throttle to be used in functional programming contexts where rate limiting is needed. The value is passed through unchanged after the throttling delay.
Warning: This overload does NOT handle undefined or boolean values.
Those are handled by (adapt?: boolean) instead, which returns
elapsed time rather than passing through the value.
The input value to pass through (must not be undefined or boolean)
A promise that resolves with the same value after applying throttling delay
Adapts throttling parameters based on task completion status.
Decrements the queue counter and adjusts the baseline delay:
The delay is always clamped between minimum and maximum bounds, with retry delays taking precedence when specified. After a failure, the throttle restricts new tasks until the current one succeeds.
True if the task completed successfully, false if it failed
A promise that resolves to the new baseline delay in milliseconds
Executes a function with retry logic using this throttle.
Function to execute (synchronous or asynchronous)
Optionaloptions: {Configuration options for retry behavior
Optionalattempts?: numberMaximum retry attempts (0 = unlimited retries, default: 0)
Optionalrecover?: (error: unknown) => number | undefinedCallback to determine if an error is retryable and extract API-specified delay.
Returns undefined for non-retryable errors, or a delay in milliseconds for retryable
errors
(0 = use default backoff, >0 = use API-specified delay)
Optionalmonitor?: (attempt: number, attempts: number, elapsed: number | undefined) => voidOptional callback invoked before each attempt with current attempt (zero-indexed),
maximum attempts, and elapsed time since retry started.
Elapsed time is undefined when task fails (non-retryable error or max attempts
exhausted), or time in milliseconds when task is about to execute or will retry after error
Promise resolving to the result of the executed task
Re-throws the error from task when retrying stops, either because recover returns
undefined (non-retryable error) or maximum retry attempts are exceeded
Warning: Setting attempts = 0 creates an infinite retry loop that only terminates
when the task succeeds or a non-retryable error occurs (when recover returns undefined).
Use with caution in production code.
Note: Attempt numbers are zero-indexed. The first execution is attempt 0,
the second is attempt 1, and so on. When attempts = N, the loop runs attempts 0 through N-1.
Adaptive throttle for rate-limiting concurrent task execution.
Provides an intelligent throttling mechanism that dynamically adjusts execution rates based on system load and task success/failure patterns. Implements exponential backoff on failures, recovery on successes, and queue-based delay scaling to prevent overload.