TokenBucketRateLimiter class

A token bucket: capacity tokens max, refilling at tokensPerSecond.

Starts full, so an initial burst up to capacity is allowed before the steady rate takes over.

Constructors

TokenBucketRateLimiter({required double tokensPerSecond, required int capacity, DateTime now()?})

Creates a limiter refilling at tokensPerSecond (> 0) up to capacity (≥ 1) tokens. now supplies the current time for refill accrual; it defaults to DateTime.now and can be overridden in tests to advance a virtual clock. Audited: 2026-06-12 11:26 EDT

Properties

capacity → int

Maximum tokens the bucket can hold — the largest single burst allowed.

final

hashCode → int

The hash code for this object.

no setter, inherited

runtimeType → Type

A representation of the runtime type of the object.

no setter, inherited

tokensPerSecond → double

Steady-state refill rate (tokens added per second of elapsed time).

final

Methods

availableTokens() → double

The tokens currently available (after accrual), as a fractional count. Audited: 2026-06-12 11:26 EDT

noSuchMethod(Invocation invocation) → dynamic

Invoked when a nonexistent method or property is accessed.

inherited

timeUntilAvailable([int tokens = 1]) → Duration

How long until tokens (default 1) would be available, or Duration.zero if they are available now. Pairs with tryAcquire so a caller can schedule a retry instead of busy-polling. Throws ArgumentError on an impossible request (see tryAcquire). Audited: 2026-06-12 11:26 EDT

toString() → String

A string representation of this object.

override

tryAcquire([int tokens = 1]) → bool

Tries to spend tokens (default 1). Returns true and deducts them if enough have accrued, false otherwise (no partial spend). Throws ArgumentError if tokens is below 1 or above capacity — a request larger than the bucket can ever hold is a programming error, not a denial. Audited: 2026-06-12 11:26 EDT

Operators

operator ==(Object other) → bool

The equality operator.

inherited