⚡ express-fast-throttle

express-fast-throttle is a lightweight Express.js middleware designed to protect your server from spam and abuse. Unlike traditional rate limiters that block users, this package slows down users who send too many requests too quickly by introducing a calculated delay.

📦 Installation

To add express-fast-throttle to your project, use npm :

🚀 Basic UsageApply the middleware globally to your Express application. The value passed (1000 in this case) is the base wait time in milliseconds.JavaScriptimport express from "express";

npm install express-fast-throttle

import throttle from 'express-fast-throttle';

const app = express();

// Apply throttle middleware globally (Base wait time: 1000ms)
app.use(throttle(1000));

app.get('/', (req, res) => {
  res.send('Hello World');
});

app.listen(3000, () => {
  console.log('Server running on port 3000');
});

⚙️ API Syntax and Configuration

The middleware accepts a base delay time and an optional configuration object.

Syntax

throttle(waitTime, options)

Parameters

| Parameter | Type | Description | | --------- | ------ | --------------------------------------------------------------------------------------- | | waitTime | number | Required. The base delay time in milliseconds between requests from the same user (IP). |

Options (Optional)

Configure limits and cleanup behavior using the options object:

{
  maxDelay: number,
  cleanupInterval: number
}

| Option | Default | Description | | --------------- | ------- | ----------------------------------------------------------------------------------------------- | | maxDelay | 5000 | The maximum delay (in ms) that can ever be applied to a request, preventing excessive slowdown. | | cleanupInterval | 60000 | Time interval (in ms) to clean up unused IP addresses from the in-memory store. |

🔍 How Throttling Works

This package implements request delay rather than resource blocking.

Internal Behavior

• Each incoming request from a client IP is tracked.

Example IP Data Structure

IP: 192.168.1.10
- lastRequestTime: timestamp of the previous request
- delay: the current applied delay time

Request Flow

Request Arrives A client sends a request.

Check Speed The middleware compares the time since the lastRequestTime with the configured waitTime.

Outcome

If requests are slow (time >= waitTime) → No delay is added.

If requests are fast (time < waitTime) → A calculated delay is added before processing the route handler.

⏱️ Example Behavior

If you use throttle(1000) (expecting 1 second between requests):

| Request # | Client Time Between Requests | Delay Applied | Result | | --------- | ---------------------------- | ------------- | ------------------- | | 1 | N/A | No delay | Baseline | | 2 | N/A | No delay | Baseline | | 3 | ~100ms | 300ms delay | Starts slowing down | | 4 | ~100ms | 800ms delay | Speed decreases | | 5 | ~100ms | 1500ms delay | Gets much slower |

🔐 Route-Specific Protection

You can apply the throttle middleware to individual routes (like sensitive login endpoints) instead of globally.

app.post('/login', throttle(2000), (req, res) => {
  res.send('Login request received');
});

⚠️ Production and Scaling

This package uses in-memory storage for tracking.

Important: If your application runs on multiple servers (e.g., behind a load balancer), the in-memory store is isolated per instance. For consistent throttling across your entire deployment, you must integrate a shared store* like Redis.

Key Features

• Ease of Use: Simple setup with minimal configuration.
• Lightweight: Small footprint and high performance.
• Zero Dependencies: No external package dependencies required.
• Cleanup: Built-in memory cleanup for inactive IP tracking.
• IP-Based: Control is based on the client's IP address.