What is this?

An object, restrain, containing three restrictive Promise-based functions: debounce, throttle and iteration. Debounce and Throttle utilize setTimeout and clearTimeout too restrict rapid function execution.

Install

Use npm to install restrain.

> npm i bjork_restrain

Usage

In essence, throttle creates ripples of function executions, contrasting debounce which cancels them until left idle. Additionally, Iteration count and executes on every given number.

import restrain from 'bjork_restrain'
const { debounce, throttle, iteration } = restrain

debounce(func, delay, cancel)
throttle(func, delay, options?)
iteration(func, delay, options?)

//---------- or ----------\\

// (for example, debounce)

import Debounce from 'bjork_restrain/modules/Debounce'

const debounce = (new Debounce()).process

debounce(func, delay, cancel)

Debounce

Delay execution of func until idle for the duration of delay (ms).

Cancel In addition to func and delay a third param, cancel [boolean], can be passed. Resulting in the debouncing function func never being executed.

Promise After a successful execution or cancelation, debounce resolves with a corresponding message.

Test

The testEnvironment simulates a static spamming situation. Here is the test intact.

// In testEnvironment: debounce(() => arr.push('execution'), 15)
test('unconfigured', async() => {
	expect(
		await testEnvironment()
	).toBe(
		'1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 execution'
	)
})

Throttle

Restrain execution of func to one every delay (ms).

Promise After successfully executing func, throttle resolves with a message.

Options In addition to func and delay a third param, options [object], can be passed. options?: { cancel?: boolean; init?: boolean; idleResetDelay?: number; }

• cancel [boolean]: Cancels current timeout, allowing param exchange of throttle.
• init [boolean]: Toggles initial execution (@default true).
• idleResetDelay (ms): Configure delay of state reset to idle (@defualt delay*1.5)

Test

The testEnvironment simulates a static spamming situation. Here is the test intact.

test('unconfigured', async() => {
	expect(
		await testEnvironment()
	).toBe(
		'1 execution 2 3 4 5 6 7 8 9 10 11 12 13 14 execution 15 16 17 18 19 20 21 22 23 24 25 26 27 28 execution 29 30'
	)
})

Iteration

Restrain execution of func to every delay:nth iteration.

Promise After successfully executing func, iteration resolves with a message.

Options In addition to func and delay a third param, options [object], can be passed. options?: { cancel?: boolean; init?: boolean; startFrom?: number; idleResetDelay?: number; }

• cancel [boolean]: Cancels current iteration count, effectivly reseting iteration.
• init [boolean]: Toggles initial execution (@default true).
• startFrom [number]: Configure initial starting iteration (@defualt 0)
• idleResetDelay (ms): Configure delay of state reset to idle (@defualt 500)

Test

The testEnvironment simulates a static spamming situation. Here is the test intact.

test('unconfigured', async() => {
	expect(
		await testEnvironment()
	).toBe(
		'1 execution 2 3 4 5 execution 6 7 8 9 10 execution 11 12 13 14 15 execution 16 17 18 19 20 execution'
	)
})

Contribution

Pull requests are welcome. For any considerable changes, please open an issue first to discuss what you would like to change. Please make sure to update the tests as appropriate.

Licence

MIT