hono-rate-limiter

When using the Redis store, you must provide an Options object. The configuration includes the Redis client, an optional key prefix, and an expiry reset setting.

• client: An object implementing the RedisClient interface (required).
• prefix: A string prepended to all keys stored in Redis (optional).
• resetExpiryOnChange: A boolean that determines whether the key's expiry is reset every time the hit count changes (optional).

const options: Options = {
  client: myRedisClient,
  prefix: 'rate-limit:',
  resetExpiryOnChange: true
};

When instantiating UnstorageStore, you can provide the following configuration options in the constructor:

const store = new UnstorageStore({
  storage: myStorage,
  prefix: 'custom-prefix:'
});

When instantiating RedisStore, you can provide the following options:

const store = new RedisStore({
  client: redisClient,
  prefix: 'custom-prefix:',
  resetExpiryOnChange: true
});

When using the standard Hono rate limiter, you can provide a HonoConfigType object. Key configuration options include:

• windowMs: Duration (in ms) to track requests. Defaults to 60000 (1 minute).
• limit: Maximum connections allowed in the window. Can be a number or a function (c) => Promisify<number>.
• standardHeaders: Enables standardized rate limit headers. Supports true, false, `

The UnstorageStore class allows you to use Unstorage as the backend for hono-rate-limiter. This is useful if you want to persist rate limit data across different storage engines (like Redis, Cloudflare KV, or memory) using the Unstorage API.

To use it, you must provide an object that implements the UnstorageInstance interface, which requires get, set, and remove methods.

import { UnstorageStore, type UnstorageInstance } from 'hono-rate-limiter';

// 1. Define your Unstorage-compatible instance
const myStorage: UnstorageInstance = {
  get: async (key) => { /* implementation */ },
  set: async (key, value) => { /* implementation */ },
  remove: async (key) => { /* implementation */ },
};

// 2. Initialize the store
const store = new UnstorageStore({
  storage: myStorage,
  prefix: 'my-app-rl:', // Optional: defaults to 'hrl:'
});

The RedisStore class provides the following methods for managing rate limit state:

• init(options: RateLimitConfiguration<E, P, I>): void: Initializes the store with the rate limiter's configuration (e.g., setting windowMs).
• get(key: string): Promise<ClientRateLimitInfo | undefined>: Fetches the current hit count and resetTime for a specific key.
• increment(key: string): Promise<ClientRateLimitInfo>: Atomically increments the hit count for a key and returns the updated ClientRateLimitInfo.
• decrement(key: string): Promise<void>: Decrements the hit count for a key using the Redis DECR command.
• resetKey(key: string): Promise<void>: Deletes the key from Redis, effectively resetting the rate limit for that identifier.

Use setRetryAfterHeader to set the standard Retry-After header on a Hono response. This informs the client how many seconds to wait before retrying the request.

The header value is calculated based on the resetTime provided in the RateLimitInfo object or the windowMs duration.

import { setRetryAfterHeader } from "hono-rate-limiter";

// Inside a Hono handler:
setRetryAfterHeader(context, info, windowMs);