Private ReadonlyintervalPrivatelastPrivatetokensPrivate ReadonlytokensReturns the number of tokens currently available in the bucket.
Triggers a refill calculation based on elapsed time before returning the value, so the result reflects the current real-time availability.
Current token count (may be fractional; floor before display)
Returns a typed status snapshot for health checks and monitoring.
Triggers a refill calculation so the snapshot reflects real-time bucket
state. Useful for /health endpoints and Prometheus exporters.
Current RateLimiterStatus snapshot with availableTokens,
maxTokens, and utilizationPercent (0–100)
PrivaterefillRefill tokens based on elapsed time
Attempts to consume count tokens from the bucket, waiting asynchronously
until tokens are available or the timeout expires.
Refills the bucket based on elapsed time before each check. If sufficient
tokens are available they are consumed immediately. Otherwise the method
sleeps until the bucket has enough tokens and retries. If the required wait
would exceed options.timeoutMs (default 5000 ms) the call returns
immediately with allowed: false and a retryAfterMs hint. The timeout
is enforced as a hard deadline: even if a sleep fires slightly late due to
event-loop delay, tokens are never consumed after the deadline has elapsed.
Number of tokens to consume (must be a finite integer ≥ 1 and ≤ tokensPerInterval); throws for invalid values
Optionaloptions: { timeoutMs?: number }OptionaltimeoutMs?: numberMaximum time to wait in milliseconds (default 5000); non-finite or negative values are coerced to 0, meaning the call never blocks and returns allowed: false immediately if tokens are unavailable
Promise resolving to a RateLimitResult. allowed is true
when tokens were consumed, false when the timeout was reached.
remainingTokens is always a non-negative integer (Math.floor of the
internal fractional bucket state); it may differ from
RateLimiter.getAvailableTokens which returns the raw fractional value.
const result = await rateLimiter.removeTokens(1);
if (!result.allowed) {
console.warn(`Rate limited – retry after ${result.retryAfterMs}ms`);
} else {
const data = await fetchFromEPAPI('/meps');
}
Attempts to consume count tokens without throwing on failure.
Synchronous alternative to removeTokens that returns false
instead of waiting when the bucket lacks tokens. Useful in hot paths
where callers want to branch on availability rather than await a refill.
Note: This method still throws for invalid count arguments (non-integer,
< 1, or exceeding bucket capacity). It only avoids throwing when there are
insufficient tokens in the bucket at the time of the call.
Number of tokens to consume (must be a finite integer ≥ 1 and ≤ tokensPerInterval); throws for invalid values
true if tokens were successfully consumed, false if the
bucket did not have enough tokens (bucket is left unchanged)
Private StaticresolveCoerce an optional timeoutMs value to a safe finite number >= 0.
Token bucket rate limiter implementation