Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: README.md for @unkey/ratelimit #2164

Merged
merged 1 commit into from
Oct 3, 2024
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
91 changes: 91 additions & 0 deletions packages/ratelimit/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,91 @@
<div align="center">
<h1 align="center">@unkey/ratelimit</h1>
<h5>@unkey/ratelimit is a library for fast global ratelimiting in serverless functions.</h5>
</div>

<div align="center">
<a href="https://www.unkey.com/docs/libraries/ts/ratelimit">Documentation</a>
</div>
<br/>

## Installation

```bash
npm install @unkey/ratelimit
```

## Quickstart

1. Configure your ratelimiter:

```ts
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:

```ts
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:

```ts
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.

```ts
new Ratelimit(config: RatelimitConfig)
```

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

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

### Documentation

[Read the full documentation](https://www.unkey.com/docs/libraries/ts/ratelimit)
2 changes: 1 addition & 1 deletion packages/ratelimit/package.json
Original file line number Diff line number Diff line change
@@ -14,7 +14,7 @@
"url": "https://github.com/unkeyed/unkey/issues"
},
"homepage": "https://github.com/unkeyed/unkey#readme",
"files": ["./dist/**"],
"files": ["./dist/**","README.md"],
"author": "Andreas Thomas <andreas@unkey.dev>",
"scripts": {
"build": "tsup"