@letmein_by10/arc-debounce

A comprehensive TypeScript/JavaScript utility library for debouncing, throttling, and timing control functions. Built with modern TypeScript and optimized for both Node.js and browser environments.

Features

• ✨ Debounce Functions: Delay execution until after calls have stopped
• ⚡ Throttle Functions: Limit execution to once per time period
• 🔄 Rate Limiting: Control maximum calls per time window
• ⏰ Timing Utilities: Sleep, delay, and once functions
• 🎯 TypeScript First: Full type safety with generic support
• 🌐 Universal: Works in Node.js and browsers
• 🚀 Zero Dependencies: Lightweight and fast
• 📦 Tree Shakeable: Import only what you need

Installation

npm install @letmein_by10/arc-debounce
# or
yarn add @letmein_by10/arc-debounce
# or  
pnpm add @letmein_by10/arc-debounce

Quick Start

import { debounce, throttle, once, delay, sleep, rateLimit } from '@letmein_by10/arc-debounce';

// Debounce a search function
const debouncedSearch = debounce((query: string) => {
  console.log('Searching for:', query);
}, 300);

// Throttle a scroll handler
const throttledScroll = throttle(() => {
  console.log('Scroll event');
}, 100);

// Rate limit API calls
const limitedAPI = rateLimit(apiCall, 10, 60000); // Max 10 calls per minute

API Reference

debounce(func, delay, options?)

Creates a debounced function that delays invoking func until after delay milliseconds have elapsed since the last time the debounced function was invoked.

Parameters:

• func: The function to debounce
• delay: The number of milliseconds to delay
• options: Optional configuration object
  • immediate: Execute function immediately on first call
  • maxWait: Maximum time to wait before forcing execution

Returns: A debounced function with additional methods:

• cancel(): Cancel pending function execution
• flush(): Execute the function immediately
• pending(): Check if function execution is pending

throttle(func, wait, options?)

Creates a throttled function that only invokes func at most once per every wait milliseconds.

once(func)

Creates a function that is restricted to invoking func once. Repeat calls return the value of the first invocation.

delay(func, delay, maxInterval)

Creates a function that delays invoking func with debouncing but ensures execution at least once every maxInterval milliseconds.

sleep(ms)

Utility function to wait for a specified amount of time.

await sleep(1000); // Wait 1 second

rateLimit(func, maxCalls, windowMs)

Creates a function that will call the original function with rate limiting.

Examples

Debouncing User Input

import { debounce } from '@letmein_by10/arc-debounce';

const searchInput = document.getElementById('search') as HTMLInputElement;
const debouncedSearch = debounce((query: string) => {
  // API call here
  fetch(`/api/search?q=${query}`)
    .then(response => response.json())
    .then(data => console.log(data));
}, 300);

searchInput.addEventListener('input', (e) => {
  debouncedSearch((e.target as HTMLInputElement).value);
});

Throttling Scroll Events

import { throttle } from '@letmein_by10/arc-debounce';

const throttledScroll = throttle(() => {
  const scrollY = window.scrollY;
  console.log('Current scroll position:', scrollY);
}, 100);

window.addEventListener('scroll', throttledScroll);

Rate Limiting API Calls

import { rateLimit } from '@letmein_by10/arc-debounce';

const apiCall = async (data: any) => {
  return fetch('/api/data', {
    method: 'POST',
    body: JSON.stringify(data),
    headers: { 'Content-Type': 'application/json' }
  });
};

const limitedAPI = rateLimit(apiCall, 10, 60000); // Max 10 calls per minute

// Usage
const result = limitedAPI({ message: 'Hello' });
if (result === undefined) {
  console.log('Rate limit exceeded');
}

TypeScript Support

This package is built with TypeScript and provides full type safety:

// Generic function support
const debouncedFn = debounce(<T>(value: T): T => {
  return value;
}, 300);

// Type inference works automatically
const result: string = debouncedFn('hello'); // ✅ Type safe

License

MIT © pizle0210