npm package: @letmein_by10/arc-debounce
Description: Debouncing utility for JavaScript/TypeScript
Author: pizle0210
Latest version: 1.0.2

# @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

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

## Quick Start

```typescript
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.

```typescript
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

```typescript
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

```typescript
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

```typescript
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:

```typescript
// 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](mailto:fajobiadedoyin@hotmail.com)