# ratelimiter

> abstract rate limiter backed by redis

Latest version **3.4.1** (published 2020-02-24) · MIT license · 0 weekly downloads

## Install

```sh
npm install ratelimiter
pnpm add ratelimiter
yarn add ratelimiter
bun add ratelimiter
```

## Health

**Score 23/100 (F)** — status: abandoned.

Positive: has types package; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 3.4.1 |
| Published | 2020-02-24 |
| First published | 2013-11-13 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | separate (@types/ratelimiter) |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 16.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 721 |
| Maintainers | noamshemesh, tjholowaychuk |
| Keywords | rate, ratelimit, limiter, limit |

## Links

- npm: https://www.npmjs.com/package/ratelimiter
- Repository: https://github.com/visionmedia/node-ratelimiter
- Homepage: https://github.com/visionmedia/node-ratelimiter#readme
- Issues: https://github.com/visionmedia/node-ratelimiter/issues
- npm.io page: https://npm.io/package/ratelimiter

## Alternatives

- [@commercetools/sync-actions](https://npm.io/package/@commercetools/sync-actions.md) — 25.1K weekly downloads
- [cwait](https://npm.io/package/cwait.md) — 21.4K weekly downloads
- [@ledgerhq/hw-app-cosmos](https://npm.io/package/@ledgerhq/hw-app-cosmos.md) — 4.2K weekly downloads
- [@financial-times/o-loading](https://npm.io/package/@financial-times/o-loading.md) — 2.8K weekly downloads
- [fa](https://npm.io/package/fa.md) — 185 weekly downloads

## Recent versions

- 3.4.1 (latest) — 2020-02-24
- 3.4.0 — 2019-10-21
- 3.3.1 — 2019-08-16
- 3.3.0 — 2019-03-02
- 3.2.0 — 2018-07-21
- 3.1.0 — 2018-06-22
- 3.0.3 — 2017-03-31
- 3.0.2 — 2017-02-27
- 2.2.0 — 2017-02-11
- 2.1.3 — 2016-04-11
- 2.1.2 — 2015-12-21
- 2.1.1 — 2015-10-21
- 2.1.0 — 2015-10-12
- 2.0.1 — 2015-01-10
- 2.0.0 — 2014-10-27
- … 4 more at https://npm.io/package/ratelimiter/versions

## README

# ratelimiter

Rate limiter for Node.js backed by Redis.
  
> **NOTE**: Promise version available at [async-ratelimiter](https://github.com/microlinkhq/async-ratelimiter).

[![Build Status](https://travis-ci.org/tj/node-ratelimiter.svg)](https://travis-ci.org/tj/node-ratelimiter)

## Release Notes
[v3.4.1](https://github.com/tj/node-ratelimiter/tree/v3.4.1) - [#55](/../../issues/55) by [@barwin](https://github.com/barwin) - Remove splice operation.

[v3.3.1](https://github.com/tj/node-ratelimiter/tree/v3.3.1) - [#51](/../../issues/51) - Remove tidy option as it's always true.

[v3.3.0](https://github.com/tj/node-ratelimiter/tree/v3.3.0) - [#47](/../../pull/47) by [@penghap](https://github.com/penghap) - Add tidy option to clean old records upon saving new records. Drop support in node 4.

[v3.2.0](https://github.com/tj/node-ratelimiter/tree/v3.2.0) - [#44](/../../pull/44) by [@xdmnl](https://github.com/xdmnl) - Return accurate reset time for each limited call.

[v3.1.0](https://github.com/tj/node-ratelimiter/tree/v3.1.0) - [#40](/../../pull/40) by [@ronjouch](https://github.com/ronjouch) - Add reset milliseconds to the result object.

[v3.0.2](https://github.com/tj/node-ratelimiter/tree/v3.0.0) - [#33](/../../pull/33) by [@promag](https://github.com/promag) - Use sorted set to limit with moving window.

[v2.2.0](https://github.com/tj/node-ratelimiter/tree/v2.2.0) - [#30](/../../pull/30) by [@kp96](https://github.com/kp96) - Race condition when using `async.times`.

[v2.1.3](https://github.com/tj/node-ratelimiter/tree/v2.1.3) - [#22](/../../pull/22) by [@coderhaoxin](https://github.com/coderhaoxin) - Dev dependencies versions bump.

[v2.1.2](https://github.com/tj/node-ratelimiter/tree/v2.1.2) - [#17](/../../pull/17) by [@waleedsamy](https://github.com/waleedsamy) - Add Travis CI support.

[v2.1.1](https://github.com/tj/node-ratelimiter/tree/v2.1.1) - [#13](/../../pull/13) by [@kwizzn](https://github.com/kwizzn) - Fixes out-of-sync TTLs after running decr().

[v2.1.0](https://github.com/tj/node-ratelimiter/tree/v2.1.0) - [#12](/../../pull/12) by [@luin](https://github.com/luin) - Adding support for ioredis.

[v2.0.1](https://github.com/tj/node-ratelimiter/tree/v2.0.1) - [#9](/../../pull/9) by [@ruimarinho](https://github.com/ruimarinho) - Update redis commands to use array notation.

[v2.0.0](https://github.com/tj/node-ratelimiter/tree/v2.0.0) - **API CHANGE** - Change `remaining` to include current call instead of decreasing it. Decreasing caused an off-by-one problem and caller could not distinguish between last legit call and a rejected call.

## Requirements

- Redis 2.6.12+
- Node 8.0.0+

## Installation

```
$ npm install ratelimiter
```

## Example

 Example Connect middleware implementation limiting against a `user._id`:

```js
var id = req.user._id;
var limit = new Limiter({ id: id, db: db });
limit.get(function(err, limit){
  if (err) return next(err);

  res.set('X-RateLimit-Limit', limit.total);
  res.set('X-RateLimit-Remaining', limit.remaining - 1);
  res.set('X-RateLimit-Reset', limit.reset);

  // all good
  debug('remaining %s/%s %s', limit.remaining - 1, limit.total, id);
  if (limit.remaining) return next();

  // not good
  var delta = (limit.reset * 1000) - Date.now() | 0;
  var after = limit.reset - (Date.now() / 1000) | 0;
  res.set('Retry-After', after);
  res.send(429, 'Rate limit exceeded, retry in ' + ms(delta, { long: true }));
});
```

## Result Object
 - `total` - `max` value
 - `remaining` - number of calls left in current `duration` without decreasing current `get`
 - `reset` - time since epoch in seconds at which the rate limiting period will end (or already ended)
 - `resetMs` - time since epoch in milliseconds at which the rate limiting period will end (or already ended)

## Options

 - `id` - the identifier to limit against (typically a user id)
 - `db` - redis connection instance
 - `max` - max requests within `duration` [2500]
 - `duration` - of limit in milliseconds [3600000]

# License

  MIT

---
_Source: https://npm.io/package/ratelimiter · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._