typescript 45 lines · 7 steps

How a token bucket rate limiter works

A token bucket refills over time and only allows an action when enough tokens remain.

Explained by highlit
Intermediate rate-limiting token-bucket lazy-evaluation higher-order-functions generics
1interface TokenBucketOptions {
2 capacity: number;
3 refillPerSecond: number;
4}
5 
6export class TokenBucket {
7 private tokens: number;
8 private lastRefill: number;
9 
10 constructor(private readonly options: TokenBucketOptions) {
11 this.tokens = options.capacity;
12 this.lastRefill = Date.now();
13 }
14 
15 private refill(): void {
16 const now = Date.now();
17 const elapsedSeconds = (now - this.lastRefill) / 1000;
18 if (elapsedSeconds <= 0) return;
19 this.tokens = Math.min(
20 this.options.capacity,
21 this.tokens + elapsedSeconds * this.options.refillPerSecond,
22 );
23 this.lastRefill = now;
24 }
25 
26 tryRemove(count = 1): boolean {
27 this.refill();
28 if (this.tokens < count) return false;
29 this.tokens -= count;
30 return true;
31 }
32}
33 
34export function rateLimit<Args extends unknown[], R>(
35 fn: (...args: Args) => R,
36 options: TokenBucketOptions,
37): (...args: Args) => R {
38 const bucket = new TokenBucket(options);
39 return (...args: Args): R => {
40 if (!bucket.tryRemove()) {
41 throw new Error("Rate limit exceeded");
42 }
43 return fn(...args);
44 };
45}
01 / 01
STEP 01

Walkthrough

Space play ←→ step click any line
Three takeaways
  1. 1Lazy refill on each access avoids needing a background timer to replenish tokens.
  2. 2Clamping with Math.min keeps accumulated tokens from exceeding the bucket's capacity.
  3. 3Wrapping a function in a higher-order limiter cleanly separates throttling from business logic.

Related explainers

typescript 
import { NestFactory } from '@nestjs/core';
import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger';
import { ValidationPipe } from '@nestjs/common';
import { ApiProperty } from '@nestjs/swagger';

Wiring validation and Swagger docs in NestJS

validation openapi decorators
Intermediate 8 steps
typescript 
import { Component, Input } from '@angular/core';
 
interface Order {
  id: string;

How Angular ICU plurals localize an order summary

i18n pluralization standalone-component
Intermediate 8 steps
typescript 
import { Injectable, NestInterceptor, ExecutionContext, CallHandler } from '@nestjs/common';
import { Observable, catchError, concatMap, finalize } from 'rxjs';
import { DataSource, QueryRunner } from 'typeorm';
 

Wrapping requests in a transaction with NestJS

interceptors transactions rxjs
Advanced 7 steps
typescript 
type CsvColumn<T> = {
  header: string;
  value: (row: T) => string | number | boolean | null | undefined;
};

Building a type-safe CSV writer in TypeScript

generics serialization escaping
Intermediate 7 steps
ruby 
class Api::MessagesController < ApiController
  before_action :authenticate_api_key!
 
  rate_limit to: 100,

Layered API rate limiting in Rails

rate-limiting api-authentication throttling
Intermediate 9 steps
typescript 
import { parsePhoneNumberFromString, CountryCode } from 'libphonenumber-js';
 
export interface NormalizedPhone {
  e164: string;

Normalizing phone numbers to E.164 in TypeScript

validation normalization error-handling
Intermediate 7 steps

Share this explainer

Here's the card — post it anywhere.

How a token bucket rate limiter works — share card
Made with highlit — turn any snippet into a walkthrough like this in about a minute.
Explain your code