`trpc-rate-limiter`

Rate limiting function for tRPC. For defining in the trpc middleware which producers should be limited and at what rate.

This library currently only works for the Hono backend framework. Please create an issue if you wish it for another framework.

Installation

# Using npm/yarn/pnpm/bun
npm add @trpc-rate-limiter/hono

Usage

Rest APIs

import { AppRouter } from "./router";
import { trpcRateLimiter } from "@trpc-rate-limiter/hono";

// You can define tiers for reuse
export const RateLimitTier = {
  BASIC: { windowMs: 60_000, limit: 5 },
  STANDARD: { windowMs: 15 * 60 * 1000, limit: 10 },
  PREMIUM: { windowMs: 60 * 60 * 1000, limit: 30 },
};

// // Time constants for better readability
const MINUTE_IN_MS = 60 * 1000;
const HOUR_IN_MS = 60 * MINUTE_IN_MS;

// Create a tRPC middleware
const rateLimiterMiddleware = t.middleware(async ({ ctx, next }) => {
  // Extract the Hono Context
  // Make sure that you have created a tRPC context (https://trpc.io/docs/server/context)
  // and have passed the Hono context so that it can be extracted here
  const { c } = ctx;

  // Pass the type of your tRPC router for type safety
  await trpcRateLimiter<AppRouter>({
    config: {
      "auth.signUp": {
        windowMs: 15 * MINUTE_IN_MS, // 15m
        limit: 5,
      },
      "auth.signIn": {
        windowMs: 5 * MINUTE_IN_MS, // 5m
        limit: 5,
      },
      "auth.requestPasswordReset": {
        windowMs: 1 * HOUR_IN_MS, // 1h
        limit: 3,
      },
      // Default tier applied to all other procedures
      default: RateLimitTier.BASIC,
    },
    // Custom key generator function
    // If not provided, it defaults to using the procedure path and IP
    // You can customize this to use any identifier you prefer
    keyGenerator: (c, path) => `${path}:${<userId>}`,
  })(c);

  return next();
});

Data Stores

By default, MemoryStore is used. However, in order to synchronize the hit counts across instances, an external storage should be used.

If you deploy your service serverless or with multiple process or servers, then you need an external storage to store the hit counts.

The following stores are supported:

Name	Description
MemoryStore	(default) Simple in-memory option. Does not share state when the app has multiple processes or servers.
@trpc-rate-limiter/cloudflare	A Cloudflare-backed store, used with Durable Object and WorkersKV.
@hono-rate-limiter/redis	A Redis-backed store, used with `@vercel/kv` and `@upstash/redis` .
rate-limit-redis	A Redis-backed store, more suitable for large or demanding deployments.
rate-limit-postgresql	A PostgreSQL-backed store.
rate-limit-memcached	A Memcached-backed store.
cluster-memory-store	A memory-store wrapper that shares state across all processes on a single server via the node:cluster module. Does not share state across multiple servers.
precise-memory-rate-limit	A memory store similar to the built-in one, except that it stores a distinct timestamp for each key.
typeorm-rate-limit-store	Supports a variety of databases via TypeORM: MySQL, MariaDB, CockroachDB, SQLite, Microsoft SQL Server, Oracle, SAP Hana, and more.
@rlimit/storage	A distributed rlimit store, ideal for multi-regional deployments.

Take a look at this guide if you wish to create your own store.

Notes

The keyGenerator function determines what to limit a request on, it should represent a unique characteristic of a user or class of user that you wish to rate limit. Good choices include API keys in Authorization headers, URL paths or routes, specific query parameters used by your application, and/or user IDs.
It is not recommended to use IP addresses (since these can be shared by many users in many valid cases) or locations (the same), as you may find yourself unintentionally rate limiting a wider group of users than you intended.

Credits

The trpc-rate-limiter project is a fork of hono-rate-limiter, adapted for tRPC integration. The original hono-rate-limiter project was inspired by express-rate-limit.