# task-execution-limiter

> Help you manage asynchronous tasks

Latest version **1.0.0** (published 2018-02-26) · ISC license · 0 weekly downloads

## Install

```sh
npm install task-execution-limiter
pnpm add task-execution-limiter
yarn add task-execution-limiter
bun add task-execution-limiter
```

## Health

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

Positive: no vulnerabilities.

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

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.0 |
| Published | 2018-02-26 |
| First published | 2018-01-16 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 118.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | chux0519 |
| Maintainers | chux0519 |

## Links

- npm: https://www.npmjs.com/package/task-execution-limiter
- Repository: https://github.com/chux0519/task-execution-limiter
- Homepage: https://github.com/chux0519/task-execution-limiter#readme
- Issues: https://github.com/chux0519/task-execution-limiter/issues
- npm.io page: https://npm.io/package/task-execution-limiter

## Recent versions

- 1.0.0 (latest) — 2018-02-26
- 0.2.1 (beta) — 2018-01-18
- 0.6.0 — 2018-02-07
- 0.5.1 — 2018-02-07
- 0.5.0 — 2018-02-07
- 0.4.0 — 2018-02-06
- 0.3.4 — 2018-01-23
- 0.3.2 — 2018-01-22
- 0.3.1 — 2018-01-22
- 0.2.0 — 2018-01-18
- 0.1.3 — 2018-01-17
- 0.1.2 — 2018-01-17
- 0.1.1 — 2018-01-17
- 0.1.0 — 2018-01-17
- 0.0.1 — 2018-01-16
- … 1 more at https://npm.io/package/task-execution-limiter/versions

## README

# Task Execution Limiter

[![Build Status](https://travis-ci.org/chux0519/task-execution-limiter.svg?branch=master)](https://travis-ci.org/chux0519/task-execution-limiter)
[![codecov](https://codecov.io/gh/chux0519/task-execution-limiter/branch/master/graph/badge.svg)](https://codecov.io/gh/chux0519/task-execution-limiter)

Help you manage asynchronous tasks

## Features

- Can limit the execution rate with interval and limitation
- Can limit the number of concurrent
- Can limit the queue length
- Can hook many lifecycle events
- Ability to customize the processing logic when task queue overflows
- Ability to change interval during run time, and it won't break the alignment of the interval

## Limitation

- Execution interval can not be greater than 2147483647ms or less than 1ms. See [setInterval](https://nodejs.org/api/timers.html#timers_setinterval_callback_delay_args)

## Install

> npm install --save task-execution-limiter
>
> yarn add task-execution-limiter

## Intro

> `task-execution-limiter` mainly exposes three interfaces, including `TaskExecutionLimiter`, `buildTaskExecutionLimiter` and `buildWithLimit`. You can use class `TaskExecutionLimiter`, or you can use the tool functions `buildTaskExecutionLimiter` and `buildWithLimit` to encapsulate higher-order functions.
>
> `task-execution-limiter` also exposes the `QueueOverflowError` class, which you can customize for other error types when you choose to implement a task queue overflow handler.

## Quick Start

see *[gist examples](https://gist.github.com/chux0519/c6ab2a4bde6061b0333a94c1b307a46a)*

- Using TaskExecutionLimiter class. [case1 and case2](https://gist.github.com/chux0519/c6ab2a4bde6061b0333a94c1b307a46a#file-task-execution-limiter-example-js-L4-L60)
  - schedule method
  - withLimit method

- Using functions. [case5 and case6](https://gist.github.com/chux0519/c6ab2a4bde6061b0333a94c1b307a46a#file-task-execution-limiter-example-js-L133-L184)
  - `buildTaskExecutionLimiter`
  > `buildTaskExecutionLimiter` is a simple encapsulation for `TaskExecutionLimiter.schedule`

  - `buildWithLimit`

  > `buildWithLimit` is a simple encapsulation for `TaskExecutionLimiter.withLimit`

- Using custom overflow handler. [case3 and case4](https://gist.github.com/chux0519/c6ab2a4bde6061b0333a94c1b307a46a#file-task-execution-limiter-example-js-L62-L131)

- Using limit with decimals. [case7](https://gist.github.com/chux0519/c6ab2a4bde6061b0333a94c1b307a46a#file-task-execution-limiter-example-js-L186-L227)

## API

### TaskExecutionLimiter

#### constructor(options) => limiter: TaskExecutionLimiter

- `options.interval`: Rate limit, representing the interval to the next tick. When interval is larger than 2147483647 or less than 1, the interval will be set to 1.[setInterval](https://nodejs.org/api/timers.html#timers_setinterval_callback_delay_args) *Default: `1`*
  - Number
- `options.minInterval`: Rate limit, representing the lower bound of interval. (Can be an integer or decimal). *Default: `1`*
  - Number
- `options.maxInterval`: Rate limit, representing the upper bound of interval. (Can be an integer or decimal). *Default: `2147483647`*
  - Number
- `options.limit`: Rate limit, representing the number of tasks that would be started each tick (Can be an integer or decimal). *Default: `Infinity`*
  - Number
- `options.concurrency`: Concurrent quantitative restrictions. *Default: `Infinity`*
  - Number
- `options.queueLength`: Task queue length. *Default: `Infinity`*
  - Number
- `options.queueOverflowHandler`: Handle function when task queue length overflows. By default, the last task is rejected, and an error will be thrown, you can refer to `QueueOverflowError` to custom error type. *see `lib/util.defaultQueueOverflowHandler`*
  - Function: (q: Array, item: Object<task, resolve, reject>) => newq: Array

#### schedule(task) => limitedTask: Promise

- `task`: Tasks to be processed.
  - Function: () => Promise
  - Function: () => Number, Array, Object...(primitive type)
  - Number, Array, Object...(primitive type)
- `limitedTask`: Wrapped promise.
  - Promise

#### withLimit(fn) => limitedFn: Function

- `fn`: Function to be processed.
  - Function: (...args) => any
- `limitedFn`: Function to be processed with limitation.
  - Function: (...args) => any

#### interval(setter)

You can change `interval` of `TaskExecutionLimiter`, and it won't break the alignment of the interval(through the delay in execution).

```javascript
const speedUp = () => { limiter.interval /= 2 }
const slowDown = () => { limiter.interval *= 2 }
```

#### willTick(setter)

Lifecycle event, called before interval `tick`. *Default: `noop`*

- fn: () => any

#### didTick(setter)

Lifecycle event, called after interval `tick`. *Default: `noop`*

- fn: () => any

#### willStart(setter)

Lifecycle event, called before limiter start running. *Default: `noop`*

- fn: () => any

#### didStart(setter)

Lifecycle event, called after limiter start running. *Default: `noop`*

- fn: () => any

#### willStop(setter)

Lifecycle event, called before limiter stop running. *Default: `noop`*

- fn: () => any

#### didStop(setter)

Lifecycle event, called after limiter stop running. *Default: `noop`*

- fn: () => any

### buildTaskExecutionLimiter(options) => limiter: Function

- `options`: The same as the constructor arguments of TaskExecutionLimiter.
- `limiter`: 
  - Function: (`task`) => `limitedTask`
    - `task`: Tasks to be processed.
      - Function: () => Promise
      - Function: () => Number, Array, Object...(primitive type)
      - Number, Array, Object...(primitive type)
    - `limitedTask`: Wrapped promise.
      - Promise

### buildWithLimit(options) => limitedFn: Function

- `options`: The same as the constructor arguments of TaskExecutionLimiter.
- `limitedFn`: Function to be processed with limitation.
  - Function: (...args) => any

### QueueOverflowError

You can extends this class when you choose to implement a task queue overflow handler.

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