Skip to main content

Documentation Index

Fetch the complete documentation index at: https://houseofdragon-079a8546.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

RateLimitermiddleware wraps limiter.check() as an Express middleware so you don’t have to write the check/reject logic in every route handler.

​
Usage

import express from "express";
import { RateLimiter, RateLimitermiddleware } from "@throttlr/sdk";

const limiter = new RateLimiter({
  apiKey: process.env.THROTTLR_API_KEY!,
  baseUrl: "https://api.throttlr.dev/sdk",
});

const app = express();

app.post(
  "/generate-report",
  RateLimitermiddleware({
    limiter,
    identifierFn: (req) => req.user.id,   // how to get the identifier
    rule: "generate_report",               // rule name from dashboard
  }),
  (req, res) => {
    // If you get here, the request was allowed
    res.json({ message: "Report generated", rateLimit: req.rateLimitResult });
  }
);

​
Options

OptionTypeRequiredDescription
limiterRateLimiter✅Your initialized RateLimiter instance
rulestring✅Rule name to enforce
identifierFn(req) => string✅Function to extract the identifier from the request

​
Accessing the Result in Your Handler

The middleware attaches the result to req.rateLimitResult: 
app.post(
  "/api/action",
  RateLimitermiddleware({ limiter, identifierFn: (req) => req.ip!, rule: "api_action" }),
  (req, res) => {
    console.log(req.rateLimitResult);
    // { allowed: true, count: 3, limit: 10, remaining: 7, ... }
    res.json({ success: true });
  }
);

​
Using IP as identifier

identifierFn: (req) => req.ip ?? "anonymous"

​
Using authenticated user ID

identifierFn: (req) => (req as any).user?.id ?? req.ip!

​
Automatic 429 Response

When the rate limit is exceeded, the middleware automatically responds with: 
HTTP 429 Too Many Requests

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded"
  }
}
Your route handler is not called when the request is blocked.

​
TypeScript: Extending Request type

To avoid TypeScript errors when accessing req.rateLimitResult, add a global type declaration: 
// types/express.d.ts
import { CheckResult } from "@throttlr/sdk";

declare global {
  namespace Express {
    interface Request {
      rateLimitResult?: CheckResult;
    }
  }
}