limitly

Distributed, Redis-powered rate limiting for Express, Fastify, Hono, Koa, Bun, and NestJS.

Express-rate-limit, but distributed, Redis-powered, and production ready.

Install

npm install limitly ioredis

# Memcached backend
npm install limitly memcached

# OpenTelemetry
npm install limitly ioredis @opentelemetry/api

# Prometheus
npm install limitly ioredis prom-client

# NestJS
npm install limitly ioredis @nestjs/common @nestjs/core

Framework-specific subpath imports are available for tree-shaking:

import { createExpressMiddleware } from "limitly/express";
import { createFastifyPlugin } from "limitly/fastify";
import { createHonoMiddleware } from "limitly/hono";
import { createKoaMiddleware } from "limitly/koa";
import { createBunMiddleware } from "limitly/bun";

Quick Start

Express

import express from "express";
import Redis from "ioredis";
import { createLimiter } from "limitly";

const app = express();
const redis = new Redis();
const limiter = createLimiter({ redis });

app.use(limiter.middleware({ key: (req) => req.ip }));

Fastify

import Fastify from "fastify";
import Redis from "ioredis";
import { createLimiter } from "limitly";

const fastify = Fastify();
const limiter = createLimiter({ redis: new Redis() });

await fastify.register(limiter.fastifyPlugin, {
  algorithm: "token-bucket",
  capacity: 50,
  refillRate: 10,
  key: (req) => req.ip,
});

Hono

import { Hono } from "hono";
import Redis from "ioredis";
import { createLimiter } from "limitly";

const app = new Hono();
const limiter = createLimiter({ redis: new Redis() });

app.use("*", limiter.honoMiddleware({ key: (c) => c.req.header("x-api-key") }));

Koa

import Koa from "koa";
import Redis from "ioredis";
import { createLimiter } from "limitly";

const app = new Koa();
const limiter = createLimiter({ redis: new Redis() });

app.use(limiter.koaMiddleware({ key: (ctx) => ctx.ip }));

Bun

import Redis from "ioredis";
import { composeBunHandler, createLimiter } from "limitly";

const limiter = createLimiter({ redis: new Redis() });

const rateLimit = limiter.bunMiddleware({
  key: (req) => req.headers.get("x-api-key"),
});

const fetch = composeBunHandler(
  [rateLimit],
  () => Response.json({ message: "Hello Bun!" })
);

Bun.serve({ port: 3000, fetch });

NestJS

import { Module } from "@nestjs/common";
import { APP_GUARD } from "@nestjs/core";
import Redis from "ioredis";
import { createLimiter } from "limitly";
import { RateLimit } from "limitly/nest";

const limiter = createLimiter({ redis: new Redis() });
const NestGuard = limiter.nestGuard({
  limit: 100,
  window: 60,
  key: (req) => req.ip,
});

@Module({
  providers: [{ provide: APP_GUARD, useClass: NestGuard }],
})
export class AppModule {}

Per-route limits with @RateLimit():

import { Controller, Get } from "@nestjs/common";
import { RateLimit } from "limitly/nest";

@Controller("api")
export class ApiController {
  @Get()
  @RateLimit({ limit: 10, window: 60 })
  findAll() {
    return { ok: true };
  }
}

Module helper (like redisLimitPlugin for Fastify):

import { limitlyNestModule } from "limitly/nest";

@Module({
  imports: [
    limitlyNestModule({
      limiter,
      algorithm: "token-bucket",
      capacity: 50,
      refillRate: 10,
      global: true,
    }),
  ],
})
export class AppModule {}

Default Algorithm

If you omit algorithm options, limitly uses GCRA with limit: 100 and window: 60:

const limiter = createLimiter({ redis: new Redis() });

app.use(limiter.middleware({ key: (req) => req.ip }));

// equivalent to:
app.use(
  limiter.middleware({
    algorithm: "gcra",
    limit: 100,
    window: 60,
    key: (req) => req.ip,
  })
);

Set limiter-wide defaults:

const limiter = createLimiter({
  redis: new Redis(),
  default: { limit: 50, window: 30 },
});

app.use(limiter.middleware({ key: (req) => req.ip }));

Programmatic Checks

Use limiter.check() outside middleware — useful for login guards, background jobs, or custom response handling:

const result = await limiter.check(req.ip ?? "unknown", {
  limit: 5,
  window: 10,
});

if (!result.allowed) {
  return res.status(429).json({
    error: "Too many attempts",
    retryAfter: result.retryAfter,
  });
}

check() respects limiter-wide defaults, failOpen, and global onMetrics hooks.

Algorithms

GCRA (default)

Generic Cell Rate Algorithm — smooth rate limiting with controlled bursts. Uses a single TAT (theoretical arrival time) per key, so it's memory-efficient compared to sliding window:

limiter.middleware({
  limit: 100,
  window: 60, // seconds — algorithm defaults to gcra
  key: (req) => req.ip,
});

GCRA enforces an average rate of limit / window while allowing short bursts up to limit. Ideal when you want token-bucket-like behavior with predictable storage costs.

Sliding Window

Uses Redis Sorted Sets (or Memcached counters) for rate limiting over a rolling time window.

limiter.middleware({
  algorithm: "sliding-window",
  limit: 100,
  window: 60, // seconds
});

Token Bucket

Supports burst traffic with configurable refill rate.

limiter.middleware({
  algorithm: "token-bucket",
  capacity: 100,
  refillRate: 10, // tokens per second
});

Concurrency

Limits simultaneous in-flight requests per key. Slots are acquired on entry and released when the response finishes (middleware handles this automatically):

limiter.middleware({
  algorithm: "concurrency",
  limit: 10, // max concurrent requests
  ttl: 300, // lease TTL in seconds for stale slot cleanup
  key: (req) => req.ip,
});

For manual acquire/release outside middleware:

const acquired = await limiter.acquire("job-42", {
  algorithm: "concurrency",
  limit: 5,
  ttl: 120,
});

if (!acquired.allowed) {
  throw new Error("Too many concurrent jobs");
}

try {
  await runJob();
} finally {
  await limiter.release("job-42", acquired.slotId!, {
    algorithm: "concurrency",
    limit: 5,
    ttl: 120,
  });
}

Storage keys use the cc: prefix: {keyPrefix}:cc:{id}.

Storage Backends

limitly supports Redis, Valkey, DragonflyDB (Redis-compatible), and Memcached.

Redis / Valkey / DragonflyDB

Redis-compatible backends use atomic Lua scripts (sorted sets + hashes). Connect with ioredis:

import Redis from "ioredis";

// Redis
createLimiter({ redis: new Redis() });

// Valkey
createLimiter({ store: "valkey", redis: "redis://localhost:6379" });

// DragonflyDB
createLimiter({ store: "dragonfly", redis: { host: "localhost", port: 6379 } });

// Cluster (auto-pipelining, script warmup, master reads)
createLimiter({
  store: "redis",
  redis: {
    nodes: [
      { host: "127.0.0.1", port: 7000 },
      { host: "127.0.0.1", port: 7001 },
    ],
    options: {
      redisOptions: { password: "secret" },
    },
  },
});

// Optional: pin all keys to one slot (use only when you need co-location)
createLimiter({
  redis: { nodes: [{ host: "127.0.0.1", port: 7000 }] },
  hashTag: "limitly",
});

Cluster optimizations built into limitly:

ioredis defineCommand — Lua scripts are registered cluster-aware, avoiding per-node NOSCRIPT fallbacks
Script warmup — scripts are preloaded on all master nodes at startup (disable with warmupScripts: false)
Auto-pipelining — enabled by default for higher throughput under concurrent load
Hash tags — optional hashTag for slot pinning; leave unset to spread keys across slots (recommended)
Master reads — scaleReads: "master" by default so checks always hit the authoritative node

Memcached

Memcached uses counter-based sliding window and CAS token bucket (no Lua required):

import Memcached from "memcached";

createLimiter({
  store: "memcached",
  memcached: "localhost:11211",
});

// Or pass an existing client
createLimiter({ memcached: new Memcached(["localhost:11211"]) });

Memcached sliding window uses a weighted two-window counter (high accuracy, no sorted sets). Token bucket uses gets/cas for atomic updates.

Key Extraction

The key option identifies who is being rate limited (per request):

// IP-based
key: (req) => req.ip;

// API Key
key: (req) => req.headers["x-api-key"];

// User ID
key: (req) => req.user.id;

Storage Key Prefix

The keyPrefix option controls where counters are stored in Redis/Memcached. Default is limitly:

createLimiter({ redis: new Redis() });
// stores keys like: limitly:sw:203.0.113.1

createLimiter({
  redis: new Redis(),
  keyPrefix: "myapp:prod",
});
// stores keys like: myapp:prod:sw:203.0.113.1

Key format:

{keyPrefix}:sw:{id}   — sliding window
{keyPrefix}:tb:{id}   — token bucket
{keyPrefix}:gcra:{id} — GCRA
{keyPrefix}:cc:{id}   — concurrency

Response Headers

Standard rate limit headers are set by default:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1710000000
Retry-After: 15

Disable with headers: false.

Retry-After Jitter

When many clients hit a limit at once, they can all retry at the same Retry-After and cause a thundering herd. Add jitter to spread retries out:

limiter.middleware({
  limit: 100,
  window: 60,
  retryAfterJitter: 5, // add 0-5 extra seconds (default: 0)
});

Jitter is applied to blocked responses only. Metrics still report the underlying store result.

Custom Limit Response

limiter.middleware({
  onLimitReached(req, res) {
    res.status(429).json({ code: "RATE_LIMITED" });
  },
});

Metrics

Emit observability events via the onMetrics hook. Set it globally on the limiter or per middleware/route:

const limiter = createLimiter({
  redis: new Redis(),
  onMetrics: (event) => {
    console.log(event.type, event.key, `${event.durationMs.toFixed(2)}ms`);
  },
});

// Per-route override
limiter.middleware({
  onMetrics: (event) => metrics.increment(`ratelimit.${event.type}`),
});

Event types:

Type	When
`allowed`	Request passed the rate limit check
`blocked`	Request exceeded the limit
`error`	Store operation failed
`fail_open`	Store failed but `failOpen: true` allowed traffic through

Each event includes key, algorithm, durationMs, and optionally store, context (the request object), and result or error depending on type.

Multiple hooks are supported:

onMetrics: [logToConsole, sendToDatadog]

limiter.check() and all framework middleware use the same metrics pipeline.

OpenTelemetry

Use the limitly/otel helpers to emit OTEL metrics and traces. Only @opentelemetry/api is required — bring your own SDK/exporter:

import Redis from "ioredis";
import { createLimiter } from "limitly";
import { createOpenTelemetryInstrumentation } from "limitly/otel";

const otel = createOpenTelemetryInstrumentation();

const limiter = createLimiter({
  redis: new Redis(),
  tracer: otel.tracer,
  onMetrics: otel.onMetrics,
});

app.use(limiter.middleware({ key: (req) => req.ip }));

createOpenTelemetryInstrumentation() returns:

tracer — creates limitly.check spans with limitly.algorithm, limitly.store, limitly.outcome, limitly.limit, and limitly.remaining attributes
onMetrics — records limitly.check.total (counter) and limitly.check.duration (histogram, ms)

Use the pieces independently when needed:

import {
  createOpenTelemetryMetricsHook,
  createOpenTelemetryTracer,
} from "limitly/otel";

const limiter = createLimiter({
  redis: new Redis(),
  tracer: createOpenTelemetryTracer(),
  onMetrics: createOpenTelemetryMetricsHook({ includeKey: false }),
});

Combine with custom hooks:

onMetrics: [otel.onMetrics, customHook]

Prometheus

Use limitly/prometheus to expose rate limit metrics for scraping:

import express from "express";
import Redis from "ioredis";
import { createLimiter } from "limitly";
import {
  createPrometheusExporter,
  createPrometheusHandler,
} from "limitly/prometheus";

const app = express();
const prometheus = createPrometheusExporter();

const limiter = createLimiter({
  redis: new Redis(),
  onMetrics: prometheus.onMetrics,
});

app.use(limiter.middleware({ key: (req) => req.ip }));
app.get("/metrics", createPrometheusHandler(prometheus));

Metrics exposed:

Metric	Type	Labels
`limitly_check_total`	Counter	`algorithm`, `outcome`, `store`
`limitly_check_duration_seconds`	Histogram	`algorithm`, `outcome`, `store`

outcome is one of allowed, blocked, error, or fail_open.

Options:

Option	Default	Description
`register`	new `Registry`	Prometheus registry
`prefix`	`"limitly"`	Metric name prefix
`includeKey`	`false`	Add rate limit key as a label (high cardinality)
`durationBuckets`	`[0.001, 0.005, 0.01, …, 1]`	Histogram buckets (seconds)

Use a shared registry with your existing metrics:

import { Registry } from "prom-client";

const register = new Registry();
const prometheus = createPrometheusExporter({ register });

onMetrics: [prometheus.onMetrics, otherHook];

Scrape manually without HTTP middleware:

const body = await prometheus.getMetrics();

Use createPrometheusMetricsHook when you only need the onMetrics hook without the HTTP handler:

import { createPrometheusMetricsHook } from "limitly/prometheus";

const limiter = createLimiter({
  redis: new Redis(),
  onMetrics: createPrometheusMetricsHook({ prefix: "api" }),
});

Fail Open / Closed

When Redis is unavailable:

createLimiter({
  redis: new Redis(),
  failOpen: true, // allow traffic (default)
  // failOpen: false, // block with 503
});

Extensibility

Implement custom algorithms with the RateLimitStrategy interface:

interface RateLimitStrategy {
  consume(key: string): Promise<RateLimitResult>;
  release?(key: string, slotId: string): Promise<void>;
}

release is optional — only needed for concurrency-style strategies that hold a slot until the response finishes.

Performance

Atomic operations via Lua scripts (EVALSHA)
Automatic key cleanup with EXPIRE
P95 < 5ms per check (excluding network latency)
20,000+ checks/sec on a single Redis node

License

MIT

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
examples		examples
src		src
test		test
.gitignore		.gitignore
.npmignore		.npmignore
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Navigation Menu

Repository files navigation

limitly

Install

Quick Start

Express

Fastify

Hono

Koa

Bun

NestJS

Default Algorithm

Programmatic Checks

Algorithms

GCRA (default)

Sliding Window

Token Bucket

Concurrency

Storage Backends

Redis / Valkey / DragonflyDB

Memcached

Key Extraction

Storage Key Prefix

Response Headers

Retry-After Jitter

Custom Limit Response

Metrics

OpenTelemetry

Prometheus

Fail Open / Closed

Extensibility

Performance

License

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

limitly

Install

Quick Start

Express

Fastify

Hono

Koa

Bun

NestJS

Default Algorithm

Programmatic Checks

Algorithms

GCRA (default)

Sliding Window

Token Bucket

Concurrency

Storage Backends

Redis / Valkey / DragonflyDB

Memcached

Key Extraction

Storage Key Prefix

Response Headers

Retry-After Jitter

Custom Limit Response

Metrics

OpenTelemetry

Prometheus

Fail Open / Closed

Extensibility

Performance

License

About

Resources

Code of conduct

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages