# call-rate-limiter

> Limit the execution rate of async function

Latest version **0.1.0** (published 2018-10-23) · MIT license · 0 weekly downloads

## Install

```sh
npm install call-rate-limiter
pnpm add call-rate-limiter
yarn add call-rate-limiter
bun add call-rate-limiter
```

## Health

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

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.1.0 |
| Published | 2018-10-23 |
| First published | 2018-10-23 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 11 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 98 |
| Author | Eugene Pshenichnyy |
| Maintainers | ujenjt |
| Keywords | rate, limit, function, api, rate-limit, request, call |

## Links

- npm: https://www.npmjs.com/package/call-rate-limiter
- Repository: https://github.com/ujenjt/call-rate-limiter
- Homepage: https://github.com/ujenjt/call-rate-limiter#readme
- Issues: https://github.com/ujenjt/call-rate-limiter/issues
- npm.io page: https://npm.io/package/call-rate-limiter

## Alternatives

- [launchdarkly-js-client-sdk](https://npm.io/package/launchdarkly-js-client-sdk.md) — 2.5M weekly downloads
- [@elastic/elasticsearch](https://npm.io/package/@elastic/elasticsearch.md) — 2.1M weekly downloads
- [@c8y/client](https://npm.io/package/@c8y/client.md) — 15.3K weekly downloads
- [@signaldb/maverickjs](https://npm.io/package/@signaldb/maverickjs.md) — 1.7K weekly downloads
- [@bbc/http-transport-cache](https://npm.io/package/@bbc/http-transport-cache.md) — 1.2K weekly downloads

## Recent versions

- 0.1.0 (latest) — 2018-10-23

## README

# Call Rate Limiter

Limit the execution rate of any function by wrapping it with a function that returns `Promise`. Module uses sliding window rate limiter under the hood. For implementation details check out "How it works" section.

## Install

```bash
npm install --save call-rate-limiter
```

## Usage
### Rate Limited Function

Te basic use case is when you ninteracting with REST api and want to repspect rate limits upfront to prevent be banned by the server.

`rateLimit` takes `limitCount`, `limitInterval` and `fn` as arguments and returns rate limited function which should be called instead of the function passed as `fn`.

This means if you call `rateLimitedFunc` 150 times and only 100 can be called in time, the next 50 calls will be postponed and executed later to respect given rate limits.

```javascript

import {rateLimit} from 'call-rate-limiter'

const rateLimitedFunc = rateLimit(
  1200,
  60 * 1000,
  id => fetch('https://swapi.co/api/starships/${id}/').then(res => res.json())
)

/*
  fetch Death Star specs, rateLimitedFunc
  transparently passes args to wrapped function
*/
const deathStar = await rateLimitedFunc('9')
```

### Rate Limited API

Suppose, you have a bunch of api calls specified somewhere that you want to call under the same rate limits. It can be easily done with `objectRateLimit`:

```javascript
const basePath = 'https://swapi.co/api/'

function character(id) {
  return fetch(`${basePath}/people/${id}`).then(res => res.json())
}

function planet(id) {
  return fetch(`${basePath}/planet/${id}`).then(res => res.json())
}

module.exports = {
  character: character,
  planet: planet
}
```

`objectRateLimit` takes `object` as last argument and return new object with rate-limited functions assigned for same keys:

```javascript
import {objectRateLimit} from 'call-rate-limiter'
import api from './api'

const rateLimitedApi = objectRateLimit(1200, 60 * 1000, api)

// trying to enumerate all planets in a galaxy far away
let i = 0
while(i < 100000) {
  console.log(await rateLimitedApi.planet(i))
  i++
}
```

## Preventing bursting

Quite often, it is necessary to check not only compliance with the rate limits but also to avoid bursting. We want the function to be called no more than once each `N` milliseconds. To obtain this wrap your function with `throttle` than with `rateLimit`.

```javascript
import {yourFunction} from 'your-module'

import {rateLimit} from 'call-rate-limiter'
import throttle from 'lodash.throttle'

const waitBetweenCalls = 100 // 100ms
const limitCount = 30 // max 30 calls per minute
const limitInterval = 60 * 1000 // one minute

const rateLimitedNoBurstingFunc = rateLimit(
  limitCount,
  limitInterval,
  throttle(yourFunction, waitBetweenCalls)
)
```

## How it works

TODO: implement

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