🚀 VectorFlux

Production-grade TypeScript rate limiting library with multiple algorithms, Redis Lua atomicity, and framework-agnostic middleware support.

VectorFlux provides high-performance, scalable, and distributed rate limiting with a clean, type-safe API.

✨ Features

• ⚡ Multiple rate limiting algorithms:

  • Token Bucket
  • Fixed Window Counter
  • Sliding Window Log

• 🧠 Multiple storage adapters:

  • In-memory storage
  • Redis storage

• 🔒 Redis Lua scripts for atomic operations

• 🚀 Distributed and concurrency-safe rate limiting

• 🌐 Framework middleware support:

  • Express
  • Fastify
  • Hono

• 📦 Fully written in TypeScript with complete type definitions

• 🧪 Comprehensive testing:

  • 45+ automated tests
  • Unit tests
  • Redis integration tests
  • Concurrency tests
  • Middleware tests

• 📊 Built-in benchmark suite

• 🔄 GitHub Actions CI/CD pipeline

Installation

Core

npm install vectorflux

Optional integrations

Redis

npm install ioredis

Express

npm install express

Fastify

npm install fastify

Hono

npm install hono

Quick Start

Token Bucket

import {
  VectorFlux,
  MemoryAdapter
} from "vectorflux";


const limiter = new VectorFlux({
  algorithm: "token-bucket",

  adapter: new MemoryAdapter(),

  limit: 10,

  refillRate: 1
});


const result = await limiter.check(
  "user:123"
);

console.log(result);

Response Format

{
  allowed: true,
  limit: 10,
  remaining: 9,
  resetAt: 1712345678900,
  retryAfter: 0
}

Available Algorithms

Token Bucket

Best for smooth traffic handling.

Use cases:

• Public APIs
• Authentication endpoints
• User request throttling

Fixed Window Counter

Simple and memory-efficient.

Use cases:

• Login limits
• Basic API throttling
• Admin panels

Sliding Window Log

Provides more accurate limiting over a rolling time window.

Use cases:

• Payment APIs
• Critical services
• High traffic endpoints

Redis Example

import Redis from "ioredis";

import {
  VectorFlux,
  RedisAdapter
} from "vectorflux";


const redis = new Redis();

const limiter = new VectorFlux({
  algorithm: "sliding-window",

  adapter: new RedisAdapter(redis),

  limit: 100,

  window: 60000
});

Middleware Examples

Express

app.use(
  rateLimit({
    limiter
  })
);

Fastify

app.addHook(
  "preHandler",
  fastifyRateLimit({
    limiter
  })
);

Hono

app.use(
  "*",
  honoRateLimit({
    limiter
  })
);

Why Redis Lua?

Traditional Redis operations can suffer from race conditions when multiple servers process requests simultaneously.

VectorFlux executes rate limiting operations using Redis Lua scripts, guaranteeing:

• Atomic execution
• Correct request counting
• Consistent distributed behavior
• Concurrency safety

Architecture

                    Application
                         |
                         v
                  VectorFlux Core
                         |
       ---------------------------------------
       |                                     |
       v                                     v
 Memory Adapter                       Redis Adapter
       |                                     |
 JavaScript Maps                    Redis Lua Scripts
       |                                     |
       ---------------------------------------
                         |
                         v
              Rate Limiting Algorithms

             • Token Bucket
             • Fixed Window
             • Sliding Window

Performance Benchmarks

Benchmarks were executed on an Apple Silicon MacBook Air using Node.js v25.

| Test | Result | | -------------------- | --------------------: | | Memory Fixed Window | ~4.9 million ops/sec | | Memory Token Bucket | ~4.0 million ops/sec | | Redis Token Bucket | ~10K ops/sec | | Redis Fixed Window | ~10K ops/sec | | Redis Sliding Window | ~9.8K ops/sec | | Redis Concurrency | 100K requests in 1.5s | | High Cardinality | 100K users in 49ms | | Burst Traffic | 10K requests in 107ms |

Detailed benchmark results are available in benchmarks/RESULTS.md.

Testing

Run the complete test suite:

npm test

Run type checks:

npm run typecheck

Build package:

npm run build

Roadmap

Future improvements:

• [ ] Redis Cluster support
• [ ] Additional adapters (MongoDB, PostgreSQL, etc.)
• [ ] Custom metrics and monitoring hooks
• [ ] Rate limit analytics dashboard
• [ ] Further Sliding Window memory optimizations

Contributing

Contributions, bug reports, and feature requests are welcome.

Feel free to open an issue or submit a pull request.

License

MIT License.

Built with ❤️ using TypeScript, Redis, and Lua.