@unkey/ratelimit

@unkey/ratelimit is a library for fast global ratelimiting in serverless functions.

Documentation

Installation

npm install @unkey/ratelimit

Quickstart

1. Configure your ratelimiter:

import { Ratelimit } from "@unkey/ratelimit";

const unkey = new Ratelimit({
  rootKey: process.env.UNKEY_ROOT_KEY,
  namespace: "my-app",
  limit: 10,
  duration: "30s",
  async: true,
});

2. Use it:

async function handler(request) {
  const identifier = request.getUserId(); // or IP or anything else you want

  const ratelimit = await unkey.limit(identifier);
  if (!ratelimit.success) {
    return new Response("try again later", { status: 429 });
  }

  // handle the request here
}

Making it Bullet Proof

To ensure reliability, you can configure timeout and error handling:

import { Ratelimit } from "@unkey/ratelimit";

const fallback = (identifier: string) => ({
  success: true,
  limit: 0,
  reset: 0,
  remaining: 0,
});

const unkey = new Ratelimit({
  // ... standard configuration
  timeout: {
    ms: 3000, // only wait 3s at most before returning the fallback
    fallback,
  },
  onError: (err, identifier) => {
    console.error(`${identifier} - ${err.message}`);
    return fallback(identifier);
  },
});

API Overview

Create a new instance for ratelimiting by providing the necessary configuration.

new Ratelimit(config: RatelimitConfig)

Check whether a specific identifier is currently allowed to do something or if they have currently exceeded their limit.

.limit(identifier: string, opts: LimitOptions): Promise<RatelimitResponse>

Documentation

Read the full documentation