# promise-smart-throttle

> Smart throttle utility for Promise

Latest version **0.0.6** (published 2017-05-04) · ISC license · 0 weekly downloads

## Install

```sh
npm install promise-smart-throttle
pnpm add promise-smart-throttle
yarn add promise-smart-throttle
bun add promise-smart-throttle
```

## 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.0.6 |
| Published | 2017-05-04 |
| First published | 2016-09-06 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 3 |
| Author | Boris Okunskiy |
| Maintainers | inca |
| Keywords | promise, throttle, debounce, flow, control |

## Links

- npm: https://www.npmjs.com/package/promise-smart-throttle
- Repository: https://github.com/inca/promise-smart-throttle
- Homepage: https://github.com/inca/promise-smart-throttle#readme
- Issues: https://github.com/inca/promise-smart-throttle/issues
- npm.io page: https://npm.io/package/promise-smart-throttle

## Alternatives

- [promise-throttle](https://npm.io/package/promise-throttle.md) — 44.2K weekly downloads
- [@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

## Recent versions

- 0.0.6 (latest) — 2017-05-04
- 0.0.4 — 2017-05-03
- 0.0.3 — 2016-09-06
- 0.0.2 — 2016-09-06
- 0.0.1 — 2016-09-06

## README

# Promise Smart Throttle

## The Problem

Say you have a Promise-based API like this:

```es6
function searchBooks(q) {
  // performs XHR, returns a Promise
  return new Promise(...);
}
```

Say you have a Search input and you would like the results
to be be available as soon as possible.

Normally you would simply attach an `input` event listener:

```es6
input.addEventListener('input', ev => searchBooks(ev.target.value));
```

But now your server will receive too many requests
(one per user's keystroke).

In order to prevent this you would typically use `debounce` or `throttle`,
but these are only configured using static timeout:

* set it too high — say goodbye to "as soon as possible" requirement,
* set it too low — say hello to redundant requests.

Basically, you want the first request to be fired immediately, while
all subsequent keystrokes queued until the first request resolves —
and then you only want to fire _one more request_ with most recent query.

You could also give a try to concurrency limit libraries like
[throat](https://www.npmjs.com/package/throat),
but in this specific case you actually want intermediate requests
to be discarded, not queued and executed serially.

## The Solution

That's exactly what `promise-smart-throttle` is for.

You simply wrap your function:

```es6
const throttle = require('promise-smart-throttle');

const throttledSearchBooks = throttle(searchBooks);

// ...

input.addEventListener('input', ev => throttledSearchBooks(ev.target.value));
```

Now the requests will be fired exactly at the rate your server can handle.

## Bonus

You can even throw in a second argument:

```es6
const throttledSearchBooks = throttle(searchBooks, 100);
```

This will add a delay _after the active promise resolves_,
in case you also want to slow it down a bit
(like you do with regular throttle utils).

## Internals

Please observe the exact semantics of how it works
(and what resolves with what) by reading [test specs](test/throttle.test.js).

Specifically,

* "first call" always resolves ASAP (no delay added)
* all subsequent calls do not fire until (first call + delay) resolves
* intermediate calls are basically discarded and resolve to the same
  result as the last call

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