@avatijs/debounce

TypeScript Debounce

Introduction

TypeScript Debounce is an elegant, robust debounce utility that brings the power of controlled function execution to your TypeScript applications. It provides a clean, type-safe API for managing function call rates, preventing resource overuse, and improving application performance.

🌟 Why Another Debounce Library?

While there are many debounce implementations available, this library stands out by offering:

• Full TypeScript Support: Built from the ground up with TypeScript, providing complete type safety and excellent IDE integration
• Promise-Based API: Modern async/await support with proper error handling
• Configurable Execution: Control both leading and trailing edge execution
• Resource Management: Built-in cleanup and cancellation support
• Debug Support: Comprehensive logging for development troubleshooting
• Maximum Wait Time: Guarantee execution for long-running debounce periods
• Zero Dependencies: Lightweight and self-contained

🎯 When You Need This

Debouncing is crucial in many common development scenarios:

• Search Input Handling

  // Without debounce - Makes API call on every keystroke
  searchInput.addEventListener('input', async (e) => {
      const results = await searchAPI(e.target.value); // 🔴 Excessive API calls
  });
  
  // With debounce - Waits for user to stop typing
  const debouncedSearch = debounce(async (value: string) => {
      const results = await searchAPI(value);
  }, { wait: 300 }); // ✅ Single API call after typing stops
  

• Window Resize Handling

  // Without debounce - Recalculates layout on every resize event
  window.addEventListener('resize', () => {
      recalculateLayout(); // 🔴 Performance bottleneck
  });
  
  // With debounce - Controlled recalculation
  const debouncedResize = debounce(() => {
      recalculateLayout();
  }, { wait: 150 }); // ✅ Smooth performance
  

• Form Validation

  // Without debounce - Validates on every change
  input.addEventListener('input', async (e) => {
      await validateField(e.target.value); // 🔴 Excessive validation
  });
  
  // With debounce - Validates after user stops typing
  const debouncedValidate = debounce(async (value: string) => {
      await validateField(value);
  }, { wait: 400 }); // ✅ Efficient validation
  

• Real-time Saving

  // Without debounce - Saves on every change
  editor.on('change', async (content) => {
      await saveContent(content); // 🔴 Too many save operations
  });
  
  // With debounce - Intelligently batches saves
  const debouncedSave = debounce(async (content: string) => {
      await saveContent(content);
  }, { wait: 1000 }); // ✅ Optimized saving
  

🚀 Installation

npm install typescript-debounce
# or
yarn add typescript-debounce
# or
pnpm add typescript-debounce

📘 Quick Start

import { debounce } from '@avatijs/debounce';

// Create a debounced function
const debouncedFn = debounce(async (value: string) => {
    const result = await api.search(value);
    updateUI(result);
}, {
    wait: 300,                // Wait 300ms after last call
    leading: false,           // Don't execute on leading edge
    trailing: true,           // Execute on trailing edge
    maxWait: 1000,           // Maximum time to wait
    debug: true,             // Enable debug logging
    onError: console.error    // Error handling
});

// Use the debounced function
try {
    await debouncedFn('search term');
} catch (error) {
    handleError(error);
}

Features

• Type Safety: Full TypeScript support with intelligent type inference
• Promise Support: Built-in handling of async functions
• Cancellation: Support for AbortController and manual cancellation
• Maximum Wait: Configure maximum delay before forced execution
• Edge Control: Configure execution on leading and/or trailing edge
• Debug Mode: Comprehensive logging for development
• Error Handling: Robust error handling with custom callbacks
• Resource Management: Automatic cleanup of resources
• Memory Efficient: Proper cleanup and memory management

Demo

Checkout the Demo to see TypeScript Debounce in action.

Changelog

Please see CHANGELOG for more information what has changed recently.

Contributing

I welcome contributions from developers of all experience levels. If you have an idea, found a bug, or want to improve something, I encourage you to get involved!

How to Contribute

• Read Contributing Guide for details on how to get started.
• Fork the repository and make your changes.
• Submit a pull request, and we’ll review it as soon as possible.

License

Avati is open-source and distributed under the MIT License.