kontroll

kontroll ("control") is a tiny, dead-simple package for function behavior controls like debounce, countdown, throttle (limit).

Features

• 100% coverage!
• Self-explained: for real, every functions and options have TSDoc comments to explain their behavior plus examples at a hover (based on your IDE), apart from the already intuitive logic path.
  • 
• Clearable: you can stop pending timers by calling the returned clearer function or use the clear(key) function.
• Promise aware: avoid duplicated call if your promise haven't settled.

Usage

Install package:

# npm
npm install kontroll

# yarn
yarn add kontroll

# pnpm (recommended)
pnpm install kontroll

Import and use:

// This package exports ESM only.
import {
  clear,
  countdown, // Can be understand as throttle no leading (execute at end of throttle instead of lead)
  debounce,
  getInstance,
  throttle,
} from 'kontroll'

const doSum = (...numbers) => console.log(numbers.reduce((acc, cur) => acc + cur, 0))
const createDoSum = (...numbers) => () => doSum(numbers)

const clearCountdown = countdown(1000, createDoSum(1, 2), { key: 'defined', replace: false })
const clearDebounce = debounce(1000, createDoSum(3, 4), { key: 34, leading: false })
const resetThrottle = throttle(1000, createDoSum(5, 6), { trailing: false })

const debounceInstance = getInstance(34) // { timer: Timeout, callback: <fn>, finishing: false }

Notice

key behavior

Kontroll follows a key-first strategy, as long as things share the same key, they share the same timer.

If a options.key is not present, key are taken as callback.toString().

While kontroll supports a key-less usage, its recommended to set your key for production code, for better performance and expected behavior.

The following cases are debounced as their callback body is the same:

// * Case 1, (arrow) function with unchanged/variable-only body
debounce(1000, () => console.log(variable))

// * Case 2, callback / function returned by a function
const sumOneTwo = createDoSum(1, 2)
debounce(1000, sumOneTwo) // All this
debounce(1000, createDoSum(3, 4)) // 3 lines are
debounce(1000, createDoSum(5, 6)) // same key

Be notice, for something like

debounce(1000, () => console.log('hi'))
debounce(1000, () => console.log('hello'))

The automated key are different for the two calls (because they have different callback body), so they are timed separately.

In you wish them to have the same timer, you can manually set options.key like: debounce(1000, () => {}, { key: 'KEY' })

Note: the storage to check the key is set globally, if you use kontroll in your library, you should prefix the key with your package name.

License

MIT License © 2024 NamesMT