token-bucket.ts

A simple, lightweight token bucket rate limiter for TypeScript/JavaScript.

Features

• Zero dependencies
• Continuous refill (lazy evaluation, no timers)
• Per-key buckets (rate limit by IP, user ID, etc.)
• Optional cooldown (minimum time between consumes)
• TypeScript with full type definitions
• Works in Node.js and browsers

Installation

npm install token-bucket.ts

You can also install with pnpm, yarn, or slnpm

Usage

import { TokenBucket } from 'token-bucket.ts'

// Create a bucket: 5 tokens capacity, refill 1 token per second
let bucket = new TokenBucket({
  capacity: 5, // max number of token for each key
  initial: 3, // can be different from capacity
  interval: 1000, // ms, refill interval for each token
  cooldown: 1000, // ms, minimum time between successful consumes,
})

// Consume a token
let { wait_time } = bucket.consume('user:123')
if (wait_time > 0) {
  // Rate limited - wait_time ms until a token is available
  throw new Error(`Rate limited. Try again in ${Math.ceil(wait_time / 1000)}s`)
}

// Check without consuming
let result = bucket.check('user:123')

// Consume multiple tokens
bucket.consume('user:123', 3)

// Reset a specific key, you don't need to reset it manually, but you can
bucket.reset('user:123')

// Reset all keys
bucket.reset_all()

// Get number of tracked buckets
console.log(bucket.size)

// Remove fully-recovered buckets to free memory
bucket.prune()

API

new TokenBucket(options)

Option	Type	Default	Description
capacity	number	required	Maximum tokens in bucket
interval	number	required	Refill interval in milliseconds
refill	number	1	Tokens to add per interval
initial	number	capacity	Starting tokens for new buckets
cooldown	number	0	Minimum time (ms) between successful consumes

Methods

Method	Description
check(key, amount?)	Check if tokens available (doesn't consume). amount defaults to 1, can be 0 to check only cooldown
consume(key, amount?)	Consume tokens if available. amount defaults to 1, must be > 0
reset(key)	Reset a specific key's bucket
reset_all()	Reset all buckets
prune()	Remove fully-recovered buckets. Returns number removed. Only works when initial >= capacity
size	Get number of tracked buckets

Key Type

Keys can be string or number. Numbers are converted to strings internally, so 123 and '123' refer to the same bucket.

Return Value

{
  wait_time: number
} // 0 = allowed, >0 = wait this many ms

Validation

Both check and consume throw errors for invalid amounts:

• amount must be a number - NaN provided
• amount must be >= 0 (check) or amount must be > 0 (consume)
• amount must be <= capacity - Cannot request more than bucket capacity

Examples

API Rate Limiting

let apiLimit = new TokenBucket({ capacity: 60, interval: 1000 })

function handleRequest(ip: string) {
  let { wait_time } = apiLimit.consume(ip)
  if (wait_time > 0) {
    return { status: 429, message: 'Too many requests' }
  }
  // Process request...
}

SMS Verification with Cooldown

let smsLimit = new TokenBucket({
  capacity: 5, // Allow burst of 5
  interval: 60000, // Refill 1 per minute
  cooldown: 60000, // Minimum 60s between sends
})

function sendSMS(phone: string) {
  let { wait_time } = smsLimit.consume(phone)
  if (wait_time > 0) {
    throw new Error(`Please wait ${Math.ceil(wait_time / 1000)} seconds`)
  }
  // Send SMS...
}

Gradual Trust (Lower Initial Tokens)

let newUserLimit = new TokenBucket({
  capacity: 10,
  interval: 1000,
  initial: 3, // New users start with fewer tokens
})

License

This project is licensed with BSD-2-Clause

This is free, libre, and open-source software. It comes down to four essential freedoms [ref]:

• The freedom to run the program as you wish, for any purpose
• The freedom to study how the program works, and change it so it does your computing as you wish
• The freedom to redistribute copies so you can help others
• The freedom to distribute copies of your modified versions to others