function-performer
Version:
Performer providing API for debounce, throttle, deduplication and limiting functions
298 lines (206 loc) • 7.93 kB
Markdown
<div align="center">
# function-performer
[](https://github.com/oleg-putseiko/function-performer/releases)
[](https://www.npmjs.com/package/function-performer)
[](https://www.npmjs.com/package/function-performer)
[](https://github.com/oleg-putseiko/function-performer/blob/main/LICENSE.md)
</div>
Performer providing API for debounce, throttle, deduplication and limiting functions.
**Contents:**
- [Installation](#installation)
- [API](#api)
- [Constructor](#constructor)
- [Parameters](#parameters)
- [Example](#example)
- [debounce](#debounce)
- [Parameters](#parameters-1)
- [Example](#example-1)
- [throttle](#throttle)
- [Parameters](#parameters-2)
- [Example](#example-2)
- [deduplicate](#deduplicate)
- [Parameters](#parameters-3)
- [Example](#example-3)
- [limit](#limit)
- [Parameters](#parameters-4)
- [Example](#example-4)
## Installation
```bash
npm install function-performer
# or
pnpm install function-performer
# or
yarn add function-performer
```
## API
### Constructor
Type: `new (config?: PerformerConfig): Performer`
#### Parameters
- `config` — Optional parameter providing the performer configuration.
- `debounce` - An optional property that provides a debounce configuration.
- `interval` - The time in milliseconds during which the target function execution will be discarded. _(default value is `0`)_
- `throttle` - An optional property that provides a throttle configuration.
- `interval` - The time in milliseconds during which the target function execution will be blocked. _(default value is `0`)_
- `deduplicate` - An optional property that provides a deduplication configuration.
- `interval` - The time in milliseconds during which duplicate detection will occur after calling the target function. _(default value is `0`)_
- `limit` - An optional property that provides a limitation configuration.
- `max` - Maximum number of function calls. _(default value is `Infinity`)_
#### Example
```js
import { Performer } from 'function-performer';
const performer = new Performer({
debounce: { interval: 100 },
throttle: { interval: 100 },
deduplication: { interval: 100 },
limit: { max: 5 },
});
```
### debounce
Type: `(func: DebouncedFunction, ...args: unknown[]) => void`
Discards execution of operations performed within the specified interval.
#### Parameters
- `func` — A function whose call will be discarded.
- `...args` — A set of parameters for the function being performed.
#### Example
```js
import { Performer } from 'function-performer';
const performer = new Performer({ debounce: { interval: 100 } });
const func = (arg: number) => {
console.log(arg);
};
performer.debounce(func, 1); // will be discarded
performer.debounce(func, 2); // will be discarded
performer.debounce(func, 3); // logs `3`
setTimeout(() => {
performer.debounce(func, 4); // logs `4`
}, 2000);
```
To set a configuration for specific cases, pass it to the `debounce.with` function:
```js
import { Performer } from 'function-performer';
const performer = new Performer();
const debounce = performer.debounce.with({ interval: 100 });
const func = (arg: number) => {
console.log(arg);
};
debounce(func, 1); // will be discarded
debounce(func, 2); // will be discarded
debounce(func, 3); // logs `3`
setTimeout(() => {
debounce(func, 4); // logs `4`
}, 2000);
```
### throttle
Type: `(func: ThrottledFunction, ...args: unknown[]) => void`
Blocks execution of operations performed within the specified interval.
#### Parameters
- `func` — A function whose call will be blocked.
- `...args` — A set of parameters for the function being performed.
#### Example
```js
import { Performer } from 'function-performer';
const performer = new Performer({ throttle: { interval: 100 } });
const func = (arg: string) => {
console.log(arg);
};
let time = 0;
// Will be called every 10ms
const interval = setInterval(() => {
if(time < 1000) {
performer.throttle(func, `${time}ms`); // logs `0ms`, `100ms`, `200ms`, etc.
} else {
clearInterval(interval);
}
time += 10;
}, 10);
```
To set a configuration for specific cases, pass it to the `throttle.with` function:
```js
import { Performer } from 'function-performer';
const performer = new Performer();
const throttle = performer.throttle.with({ interval: 100 });
const func = (arg: string) => {
console.log(arg);
};
let time = 0;
// Will be called every 10ms
const interval = setInterval(() => {
if(time < 1000) {
throttle(func, `${time}ms`); // logs `0ms`, `100ms`, `200ms`, etc.
} else {
clearInterval(interval);
}
time += 10;
}, 10);
```
### deduplicate
Type: `(func: DeduplicatedFunction, ...args: unknown[]) => void`
Detects duplicate function calls and executes the function only once during the specified interval.
#### Parameters
- `func` — A function whose duplicate executions will be detected. The first parameter of the function should be the number of detected calls.
- `...args` — A set of parameters for the function being performed.
#### Example
```js
import { Performer } from 'function-performer';
const performer = new Performer({ deduplicate: { interval: 100 } });
const func1 = (count: number, arg: number) => {
console.log({ count, arg });
};
const func2 = (count: number, arg: object) => {
console.log({ count, arg });
};
performer.deduplicate(func1, 1); // will be blocked
performer.deduplicate(func1, 1); // logs `{ count: 2, arg: 1 }`
performer.deduplicate(func2, { foo: { bar: 'baz' } }); // will be blocked
performer.deduplicate(func2, { foo: { bar: 'baz' } }); // logs `{ count: 2, arg: { foo: { bar: 'baz' } } }`
performer.deduplicate(func2, { foo: { bar: 'qux' } }); // logs `{ count: 1, arg: { foo: { bar: 'qux' } } }`
setTimeout(() => {
performer.deduplicate(func2, { foo: { bar: 'baz' } }); // logs `{ count: 1, arg: { foo: { bar: 'baz' } } }`
}, 1000);
```
To set a configuration for specific cases, pass it to the `deduplicate.with` function:
```js
import { Performer } from 'function-performer';
const performer = new Performer();
const deduplicate = performer.deduplicate.with({ interval: 200 });
const func = (count: number, arg: number) => {
console.log({ count, arg });
};
deduplicate(func, 1); // will be blocked
deduplicate(func, 1); // logs `{ count: 2, arg: 1 }`
```
### limit
Type: `(func: LimitedFunction, ...args: unknown[]) => void`
Limits the maximum number of function calls.
#### Parameters
- `func` — A function whose number of calls will be limited.
- `...args` — A set of parameters for the function being performed.
#### Example
```js
import { Performer } from 'function-performer';
const performer = new Performer({ limit: { max: 3 } });
const func = (arg: number) => {
console.log(arg);
};
performer.limit(func, 1); // logs `1`
performer.limit(func, 2); // logs `2`
performer.limit(func, 3); // logs `3`
performer.limit(func, 4); // will be blocked
performer.limit(func, 5); // will be blocked
```
To set a configuration for specific cases, pass it to the `limit.with` function:
```js
import { Performer } from 'function-performer';
const performer = new Performer();
const once = performer.limit.with({ max: 1 });
const twice = performer.limit.with({ max: 2 });
const func = (arg: number) => {
console.log(arg);
};
once(func, 1); // logs `1`
once(func, 2); // will be blocked
once(func, 3); // will be blocked
twice(func, 1); // logs `1`
twice(func, 2); // logs `2`
twice(func, 3); // will be blocked
```