# awaitn

> Await promises yielded by a generator function with at most N outstanding at a given time. Pptionally handles rate limiting.

Latest version **0.0.6** (published 2019-04-11) · MIT license · 0 weekly downloads

## Install

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

## 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 | 2019-04-11 |
| First published | 2017-11-25 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 8.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Cliff Hammerschmidt |
| Maintainers | tanglebones |
| Keywords | await, javascript |

## Links

- npm: https://www.npmjs.com/package/awaitn
- Repository: http://git@gitlab.com/tanglebones/awaitn
- Homepage: https://gitlab.com/tanglebones/awaitn#README
- Issues: https://gitlab.com/tanglebones/awaitn/issues
- npm.io page: https://npm.io/package/awaitn

## 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

- 0.0.6 (latest) — 2019-04-11
- 0.0.5 — 2019-04-11
- 0.0.4 — 2019-04-11
- 0.0.3 — 2017-11-25
- 0.0.2 — 2017-11-25
- 0.0.1 — 2017-11-25

## README

This is alpha quality, needs more tests.

Provides:
```
async function awaitn(n, generator, [onResolve, onReject, maxPerPeriod, timePeriodInMilliseconds])
```

Takes a generator the produces promises and windows at most N to be waited on calling `onResolve` and `onReject` for each promise.
If either of `onResolve` or `onRejected` return a value `awaitn` will resolve to that value and stop.

This is mainly useful for limiting async code that talks to other services to ensure at most `n` conversations are occuring at a
time; e.g. you can avoid swamping your db with lots of requests or an external API with too many requests.

Optionally takes `maxPerPeriod` and `timePeriodMilliseconds` (defaults to 1000) to rate limit the pulling of the promises
from the generator.

# Rate limiting

It is (usually) better to lower the `timePeriodInMilliseconds` and keep `maxPerPeriod` at 1, as that will spread out the requests.

Also, the time based limitation is based on initiating the requests, not on the completion of the requests. So [1, 200]
would create at most 1 request every 200ms, and [5, 1000] would create 5 requests (immediately) and another batch of 5
requests are 1 second (assuming it didn't exceed `n` requests in flight).

# Deferred vs Direct generation of promises

Since a generator only returns done when trying to read the next element if we directly return promises we have to wait out the
rate limiter before calling the generator to determine if there are more promises to process. (Since the promise is scheduled
immediately.)

We can move the rate limiter to after calling the generator by having the generator return a function to produce the promise
(defer its generation) and only waiting if there is another promise to be processed.

# Example Usage

```
// replace with actual request data
const requestsToMake = [ 'a', 'b', 'c', 'd', 'e', 'f', 'g' ];

// replace with actual function to process the requests
async function doRequest(r) { return Date.now() + ' r: ' + r; }

// converts an iterable to a deferred stream of applications of a function
function* dgmap(iterable, f) {
  for (const n of iterable) {
    yield () => f(n); // defer running f to the callers discretion
  }
} 

// at most 4 in flight at a time, max 1 request every 200ms.
awaitn(4, dgmap(requestsToMake, doRequest), console.log, console.error, 1, 200);
```

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