gcra-throttle

High-performance rate limiting library with GCRA algorithm for Bun and Node.js.

Features

• GCRA Algorithm - Generic Cell Rate Algorithm (ITU-T I.371 standard), more accurate than token bucket
• Multiple Adapters - Bun.RedisClient, npm
  redis
  , or in-memory
• Zero Required Dependencies - redis and elysia are optional peer dependencies
• Elysia Middleware - First-class support for Elysia framework
• WebSocket Support - Built-in throttler for WebSocket connections and messages
• IP Detection - Smart client IP detection with proxy header support
• Blacklist Support - Global and per-key blacklisting
• TypeScript - Full type safety with TypeScript declarations

Installation

Quick Start

Basic Usage (Memory Adapter)

With Bun.RedisClient

With npm redis (Node.js compatible)

Elysia Middleware

Option 1: Direct import (requires elysia)

Option 2: Dynamic import (lazy loading)

WebSocket Throttling

Presets

Built-in presets for common use cases:

Blacklist Management

Key Generation

IP Detection

Smart IP detection with support for common proxy headers:

GCRA Algorithm

This library uses the Generic Cell Rate Algorithm (GCRA), also known as the "virtual scheduling" algorithm. It's defined in ITU-T I.371 and provides:

• Single state value - Only stores TAT (Theoretical Arrival Time) per key
• Mathematically precise - No floating-point accumulation errors
• Smooth rate limiting - Prevents burst clustering at period boundaries
• Efficient - Single GET + SET operation per check

How it works

TAT (Theoretical Arrival Time) = time when bucket will be empty
T = emission interval = period / countPerPeriod
τ = tolerance = T × maxBurst

For each request:
  new_TAT = max(now, TAT) + T
  if new_TAT - now > τ:
    REJECT (request came too early)
  else:
    ALLOW and update TAT = new_TAT

API Reference

createThrottler(options)

Factory function to create a throttler instance.

ThrottleResult

Adapters

All adapters implement the

• MemoryAdapter
  - In-memory storage with TTL support
• BunRedisAdapter
  - Native Bun.RedisClient wrapper
• NodeRedisAdapter
  - npm
  redis
  package wrapper

Requirements

• Runtime: Bun 1.0+ or Node.js 18+
• Redis: 6.0+ (for Redis adapters)
• Optional: elysia 1.0+ (for Elysia middleware)

License

MIT