@hummn/ratelimit

Hummn (pronouced Humming) Rate Limit

Hummn Rate Limit is designed to help you limit the number of requests your application receives.

It is useful for:

• Bun: It has first-class support for Bun Redis (Released in v1.3.0)
• Hono: Can be used with Hono in a node/bun environment. For serveless functions, we recommend using @upstash/ratelimit
• Node.js: It has first-class support for Node Redis
• Deno: Use the node adapter

Quick Start

Install

bun

bun add @hummn/ratelimit

npm

npm install @hummn/ratelimit redis

or

npm install @hummn/ratelimit @redis/client

Deno

import { Ratelimit } from "https://cdn.skypack.dev/@hummn/ratelimit@latest";

Create a database

Create a database using Docker or any other method you prefer.

Docker

docker run -d --name hummn-with-redis -p 6379:6379 redis:latest

Basic Usage

Bun

import { Ratelimit } from "@hummn/ratelimit";
import { RedisClient, type BunRequest } from "bun";

const ratelimit = new Ratelimit({
  redis: new RedisClient('redis://localhost:6379'),
  // fixedWindow and slidingWindow also supported.
  limiter: Ratelimit.tokenBucket(10, "20 s", 100),
  prefix: "@hummn/ratelimit",
});

Bun.serve({
  routes: {
    "/orgs/:orgId/repos/:repoId/settings": (
      req: BunRequest<"/orgs/:orgId/repos/:repoId/settings">,
    ) => {
      const { orgId, repoId } = req.params;
      // Use a constant string to limit all requests with a single ratelimit
      // Or use a userID, apiKey or ip address for individual limits.
      const identifier = `organization.${orgId}`;
      const { success } = await ratelimit.limit(identifier);
      if (!success) {
        // Set Headers
        return new Response("Woah! please slow down...", {status: 429})
      }

      return Response.json({ orgId, repoId });
    },
  },
});

Node

[Note] Make sure to install the required dependencies. npm install @redis/client or npm install redis

import { Ratelimit } from "@hummn/ratelimit"; // for deno: see above
import { createClient } from "@redis/client";
import { Hono } from 'hono'

const app = new Hono();

const ratelimit = new Ratelimit({
  redis: createClient({url: 'redis://localhost:6379'}),
  limiter: Ratelimit.slidingWindow(10, "10 s"),
  prefix: "@hummn/ratelimit",
});

const ratelimitMiddleware = () => {
  return createMiddleware(async (c, next) => {
    const userId = c.get('userId');
    const path = c.req.path;
    const identifier = `user.${userId}.${path}`
    const { success } = await ratelimit.limit(identifier);
    if(!success) {
      // Set Headers
      return c.json({message: 'Woah!!, please slow down...'}, 429)
    }

    await next()
  })
}

app.use(ratelimitMiddleware())

For more information on getting started, you can refer to our documentation.

Here's a complete Hono example

Documentation

See the documentation for more information details about this package.

Contributing

Running tests

Coming soon