Flowlock is a lightweight, flexible utility library for debouncing and throttling functions. It offers advanced features like execution cancellation, immediate triggering, manual flushing, and full support for asynchronous functions.
- Debounce: Delay function execution until a pause in calls occurs.
- Throttle: Limit the execution of a function to at most once every specified delay.
- Cancelable: Cancel a pending debounce or throttle execution.
- Flush: Force immediate execution of a pending function.
- Async-ready: Supports both synchronous and asynchronous functions (Promises).
- Customizable: Control execution on the leading or trailing edge.
Install using npm:
npm install flowlockOr using yarn:
yarn add flowlockimport { debounce, throttle } from 'flowlock';Debounce delays function execution until a pause in calls occurs:
const log = () => console.log('Debounced log');
const debouncedLog = debounce(log, 1000);
debouncedLog(); // Waits 1s before execution
debouncedLog(); // Timer resetsImmediate execution:
const debouncedImmediate = debounce(log, 1000, true);
debouncedImmediate(); // Executes immediatelyCancel pending debounce:
debouncedLog.cancel(); // Cancels the pending executionFlush execution immediately:
debouncedLog.flush(); // Forces immediate executionThrottle ensures a function is executed at most once every specified delay:
const log = () => console.log('Throttled log');
const throttledLog = throttle(log, 2000);
throttledLog(); // Executes immediately
throttledLog(); // Ignored if called within 2 secondsLeading and trailing options:
const throttledCustom = throttle(log, 2000, { leading: false, trailing: true });
throttledCustom(); // Executes only at the end of the 2-second windowCancel and flush execution:
throttledCustom.cancel(); // Cancels pending execution
throttledCustom.flush(); // Forces immediate executionflowlock works seamlessly with asynchronous functions:
const fetchData = async () => {
await new Promise((resolve) => setTimeout(resolve, 500));
console.log('Async operation complete');
};
const debouncedFetch = debounce(fetchData, 1000);
debouncedFetch();
debouncedFetch.flush(); // Forces immediate execution| Parameter | Type | Description |
|---|---|---|
func |
(...args: any[]) => any |
The function to debounce. |
delay |
number |
Delay in milliseconds before execution. |
immediate |
boolean |
Trigger function on the leading edge. Default: false. |
Returns: A debounced function with:
cancel(): Cancels pending execution.flush(): Forces immediate execution.
| Parameter | Type | Description |
|---|---|---|
func |
(...args: any[]) => any |
The function to throttle. |
delay |
number |
Minimum time between executions (ms). |
options |
{ leading?, trailing? } |
Control execution on leading/trailing edge. |
Options:
leading: Run on the leading edge. Default:true.trailing: Run on the trailing edge. Default:true.
Returns: A throttled function with:
cancel(): Cancels pending execution.flush(): Forces immediate execution.
You can validate flowlock with Jest:
import { debounce, throttle } from 'flowlock';
jest.useFakeTimers();
describe('debounce', () => {
it('should delay function execution', () => {
const func = jest.fn();
const debounced = debounce(func, 1000);
debounced();
jest.advanceTimersByTime(500);
expect(func).not.toHaveBeenCalled();
jest.advanceTimersByTime(500);
expect(func).toHaveBeenCalledTimes(1);
});
});
describe('throttle', () => {
it('should limit function execution to once per delay', () => {
const func = jest.fn();
const throttled = throttle(func, 1000);
throttled();
throttled();
jest.advanceTimersByTime(1000);
expect(func).toHaveBeenCalledTimes(2);
});
});MIT
Simplify execution flow and manage your functions with precision – flowlock gives you the control you need. 🚀