@danielhaim/debouncify

Debouncify

Debouncify is a lightweight and versatile JavaScript library that provides an improved debouncing functionality. It allows you to easily control the frequency of function calls in response to high-frequency events, such as scroll, resize, or input events, and thus helps you optimize the performance and responsiveness of your applications.

Demo

Installation

You can install Debouncify via npm:

npm install debouncify

Usage

import { debouncify } from 'debouncify';

const myFunction = () => {
  console.log('My function called!');
};

// Debounce myFunction for 500ms
const debouncedFunction = debouncify(myFunction, 500);

Options

import { debouncify } from 'debouncify';

const myFunction = () => {
  console.log('My function called!');
};

// Debounce myFunction for 500ms and execute it on the leading edge
const debouncedFunction = debouncify(myFunction, 500, { leading: true });

// Call debouncedFunction multiple times in quick succession
debouncedFunction();
debouncedFunction();
debouncedFunction();

// The first call to debouncedFunction will execute immediately, and only subsequent calls will be debounced

// Only the last call to debouncedFunction will execute after 500ms

This function creates a debounced version of a function passed as an argument. The debounced function delays invoking the original function until after a certain amount of time has passed since the last time the debounced function was invoked.

methodDebounce(func, wait, immediate = false, context = null)

The function takes the following parameters:

• func: The function to be debounced.
• wait: The number of milliseconds to wait before invoking the function.
• immediate: (optional) Whether to invoke the function on the leading edge (true) or trailing edge (false) of the wait interval. Defaults to false.
• context: (optional) The execution context to use for the function. Defaults to null.

The function returns a new function, which is the debounced version of the original function. This debounced function can be called like any other function, but it will only execute after the specified wait time has passed since the last time it was called. If the immediate parameter is set to true, the function will be executed immediately on the first call, and then will be debounced.

Methods

The debounced function has two additional properties:

• debounced.cancel(): a method that can be called to cancel the debounced function execution.
• debounced.result(): a method that returns the result of the last execution of the debounced function.

Example:

const debouncedFunc = methodDebounce(myFunction, 1000);
debouncedFunc(); // Executes after 1000ms
debouncedFunc.cancel(); // Cancels execution if 1000ms haven't elapsed yet

Basic Examples

// Basic functionality
const func1 = () => console.log('Function 1 called');
const debouncedFunc1 = debouncify(func1, 100);

debouncedFunc1(); // function should not be called yet

setTimeout(() => {
  debouncedFunc1(); // function should be called once
}, 200);

// Immediate execution
const func2 = () => console.log('Function 2 called');
const debouncedFunc2 = debouncify(func2, 100, true);

debouncedFunc2(); // function should be called immediately

// Custom execution context
const context = { foo: 'bar' };
const func3 = function() { console.log(this.foo); };
const debouncedFunc3 = debouncify(func3, 100, false, context);

debouncedFunc3(); // function should log 'bar'

// Canceling debounced function
const func4 = () => console.log('Function 4 called');
const debouncedFunc4 = debouncify(func4, 100);

debouncedFunc4();
debouncedFunc4.cancel(); // function should not be called

// Asynchronous function support
const asyncFunc = () => new Promise(resolve => setTimeout(() => {
  console.log('Function 5 called');
  resolve('test');
}, 100));
const debouncedFunc5 = debouncify(asyncFunc, 100);

debouncedFunc5(); // function should be called once after 100ms

Examples (Window Events)

// Test debounced window resize event
window.addEventListener('resize', debouncify(() => {
  console.log('Window resized!');
}, 100));

// Test debounced window scroll event
window.addEventListener('scroll', debouncify(() => {
  console.log('Window scrolled!');
}, 100));

// Test debounced window mousemove event
window.addEventListener('mousemove', debouncify((event) => {
  console.log(`Mouse moved to (${event.clientX}, ${event.clientY})!`);
}, 100));

// Test debounced window click event
window.addEventListener('click', debouncify((event) => {
  console.log(`Clicked at (${event.clientX}, ${event.clientY})!`);
}, 100));

Resources

The Debouncing and Throttling Explained article on the CSS-Tricks website The Underscore.js documentation on the debounce function The Lodash documentation on the debounce function

Report Bugs

If you encounter any bugs while using Debouncify, please report them to the GitHub issue tracker. When submitting a bug report, please include as much information as possible, including:

• A description of the issue
• Steps to reproduce the issue
• The expected behavior
• The actual behavior
• Any error messages or console output
• The version of Debouncify you are using
• The environment in which the bug occurs (e.g., browser, Node.js)

Providing this information will help us to diagnose and fix the issue more quickly. I appreciate your help in making the web as stable and reliable as possible.