Lightweight rate limiter plugin for Elysia.js

bun add elysia-rate-limit

If you're using Bun v1.0.3 or lower, elysia-rate-limit v2.0.0 or higher will not be compatible. Please use elysia-rate-limit v1.3.0 instead.

As long as you're on the latest version of Bun, and Elysia. Using the latest version of elysia-rate-limit would works just fine. However, please refer to the following table to determine which version to use.

Check out full sample at example

import { Elysia } from 'elysia'
import { rateLimit } from 'elysia-rate-limit'

new Elysia().use(rateLimit()).listen(3000)

number

Default: 60000

Duration for requests to be remembered in milliseconds. Also used in the Retry-After header when the limit is reached.

number

Default: 10

Maximum of request to be allowed during 1 duration timeframe.

number

Default: 429

HTTP response code to be sent when the rate limit was reached. By default, it will return 429 Too Many Requests referring to RFC 6585 specification

any

Default: rate-limit reached

Message to be sent when the rate limit was reached

'global' | 'local'

Default: 'global'

Sometimes you may want to only apply rate limit plugin to curtain Elysia instance. This option will allow you to choose scope local apply to only current instance and descendant only. But by default, rate limit plugin will apply to all instances that apply the plugin.

<T extends object>(equest: Request, server: Server | null, derived: T) => MaybePromise<string>

Custom key generator to categorize client requests, return as a string. By default, this plugin will categorize client by their IP address via server.requestIP() function.

If you deploy your server behind a proxy (i.e. NGINX, Cloudflare), you may need to implement your own generator to get client's real IP address.

const cloudflareGenerator = (req, server) =>
  // get client ip via cloudflare header first
  req.headers.get('CF-Connecting-IP') ??
  // if not found, fallback to default generator
  server?.requestIP(req)?.address ??
  ''

There's a third argument where you can use derive values from external plugin within key generator as well. Only downsize is you have to definitely those types be yourself, please be sure to test those values before actually defining types manually.

import { ip } from 'elysia-ip'

import type { SocketAddress } from 'bun'
import type { Generator } from 'elysia-rate-limit'

const ipGenerator: Generator<{ ip: SocketAddress }> = (_req, _serv, { ip }) => {
  return ip
} 

boolean

Default: false

Should this plugin count rate-limit to user when request failed? By default, this plugin will refund request count to a client when onError lifecycle called. (Learn more in Lifecycle)

Context

Context for storing requests count for each client, if you want to implement your own Context you can write it to comply with Context protocol

import type { Context } from 'elysia-rate-limit'

export class CustomContext implements Context {
  // implementation here
}

By default, context implementation, caching will be an LRU cache with a maximum of 5,000 entries. If you prefer to use this cache implementation but with larger cache size, you can define a new context with preferred cache size as follows

import { DefaultContext } from 'elysia-rate-limit'

new Elysia()
  .use(
    rateLimit({
      // define max cache size to 10,000
      context: new DefaultContext(10_000),
    })
  )

(request: Request, key: string): boolean | Promise<boolean>

Default: (): false

A custom function to determine that should this request be counted into rate-limit or not based on information given by Request object (i.e., Skip counting rate-limit on some route) and the key of the given request, by default, this will always return false which means counted everything.