Logos DX
    Preparing search index...

    Class RateLimitTokenBucket

    Token bucket implementation of rate limiting with optional persistence support.

    // Basic usage
    const bucket = new RateLimitTokenBucket({
        capacity: 10,
        refillIntervalMs: 1000
    });

    bucket.consume();
    bucket.consume();

    const rateLimited = async () => {
        // 0 ms if tokens are available
        // 1000 / 10 = 100 ms if tokens are not available
        await bucket.waitAndConsume();
        return 'success';
    }

    // With persistence (e.g., Redis backend)
    const bucket = new RateLimitTokenBucket({
        capacity: 100,
        refillIntervalMs: 60000,
        save: async (state) => {
            await redis.set('rate-limit:user:123', JSON.stringify(state));
        },
        load: async () => {
            const data = await redis.get('rate-limit:user:123');
            return data ? JSON.parse(data) : undefined;
        }
    });

    // Load state from backend before using
    await bucket.load();

    // Check and consume
    if (bucket.hasTokens()) {
        bucket.consume();
        await bucket.save();
    }
    Index

    Constructors

    constructor

    Properties

    capacity refillIntervalMs

    Accessors

    isSaveable snapshot state tokens

    Methods

    consume getNextAvailable getWaitTimeMs hasTokens load reset save waitAndConsume waitForToken

    Constructors

    Properties

    capacity: number
    refillIntervalMs: number

    Accessors

    • get isSaveable(): boolean

      Whether save and load functions are configured for persistence.

      Returns boolean

    • get snapshot(): {
          averageWaitTime: number;
          capacity: number;
          createdAt: number;
          currentTokens: number;
          refillIntervalMs: number;
          rejectedRequests: number;
          rejectionRate: number;
          successfulRequests: number;
          totalRequests: number;
          totalWaitTime: number;
          uptime: number;
          waitCount: number;
      }

      Get a snapshot of current statistics and state.

      Returns {
          averageWaitTime: number;
          capacity: number;
          createdAt: number;
          currentTokens: number;
          refillIntervalMs: number;
          rejectedRequests: number;
          rejectionRate: number;
          successfulRequests: number;
          totalRequests: number;
          totalWaitTime: number;
          uptime: number;
          waitCount: number;
      }

      Object containing usage statistics and current state

    • get tokens(): number

      Returns number

    Methods

    • Parameters

      • Optionalcount: number

      Returns boolean

    • Parameters

      • Optionalcount: number

      Returns Date

    • Parameters

      • Optionalcount: number

      Returns number

    • Check if there are enough tokens available without consuming them.

      Parameters

      • Optionalcount: number

        Number of tokens to check for (default: 1)

      Returns boolean

      true if tokens are available, false otherwise

      if (bucket.hasTokens()) {
          // We're within rate limit, proceed
          bucket.consume();
      }

    • Load state from the configured load function. If the load function returns undefined/null, the bucket state is not modified.

      Returns Promise<void>

      If no load function is configured

    • Returns void

    • Save the current state using the configured save function.

      Returns Promise<void>

      If no save function is configured

    • Waits for tokens to be available and consumes them atomically.

      Resolves true when tokens were consumed and false when the wait was abandoned because abortController fired — before, during, or after the wait. An aborted caller never consumes a token.

      Parameters

      • Optionalcount: number
      • Optionalopts: {
            abortController?: AbortController;
            jitterFactor?: number;
            onRateLimit?: (
                error: RateLimitError,
                nextAvailable: Date,
            ) => MaybePromise<void>;
        }

      Returns Promise<boolean>

      const bucket = new RateLimitTokenBucket({
          capacity: 10,
          refillIntervalMs: 1000
      });

      const acquired = await bucket.waitAndConsume(1, { abortController });

      if (acquired) {
          console.log('Token acquired and consumed');
      }

    • Waits for the next token to be available before allowing the caller to proceed.

      Resolves true when a token is available and false when the wait was abandoned because abortController fired. A false result means no token was secured — the caller must not consume().

      Parameters

      • Optionalcount: number
      • Optionalopts: {
            abortController?: AbortController;
            jitterFactor?: number;
            onRateLimit?: (
                error: RateLimitError,
                nextAvailable: Date,
            ) => MaybePromise<void>;
        }

      Returns Promise<boolean>

      const bucket = new RateLimitTokenBucket({
          capacity: 10,
          refillIntervalMs: 1000
      });

      const available = await bucket.waitForToken(1, { abortController });

      if (available) {
          bucket.consume();
      }

    Settings

    Member Visibility

    On This Page

    Constructors
    Properties
    Accessors
    Methods