@avatijs/debounce 0.1.1 → 0.1.3

package/README.md

@@ -1,242 +1,160 @@
-# Advanced TypeScript Debounce Utility
-
-A highly configurable debounce utility with TypeScript support, providing features like leading/trailing edge execution, cancellation, immediate flush, maximum wait time, and proper Promise handling.
-
-## Features
-
-- 🎯 Configurable leading/trailing edge execution
-- 🚫 Cancelable debounced functions
-- ⚡ Immediate flush capability
-- ⏱️ Maximum wait time option
-- 🔄 Promise-based return values
-- 🎭 AbortController support
-- 🐞 Debug mode
-- 📝 Comprehensive TypeScript types
-- 🧹 Proper cleanup utilities
-
-## Installation
+# TypeScript Debounce
+
+[![npm version](https://badge.fury.io/js/@avatijs%2Fdebounce.svg)](https://badge.fury.io/js/@avatijs%2Fdebounce)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0-blue.svg)](https://www.typescriptlang.org/)
+[![License](https://img.shields.io/npm/l/@avatijs%2Fdebounce.svg)](https://github.com/KhaledSMQ/avati/blob/master/LICENSE)
+
+## 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:
+
+1. **Search Input Handling**
+   ```typescript
+   // 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
+   ```
+
+2. **Window Resize Handling**
+   ```typescript
+   // 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
+   ```
+
+3. **Form Validation**
+   ```typescript
+   // 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
+   ```
+
+4. **Real-time Saving**
+   ```typescript
+   // 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
 
 ```bash
-npm install @avatijs/debounce
+npm install typescript-debounce
+# or
+yarn add typescript-debounce
+# or
+pnpm add typescript-debounce
 ```
 
-## Basic Usage
+## 📘 Quick Start
 
 ```typescript
-import { debounce } from '@your-org/debounce-utility';
-
-// Simple debounce
-const debouncedFn = debounce(async (x: number) => x * 2, { 
-  wait: 1000 
-});
-
-// Call the debounced function
-await debouncedFn(5); // Will execute after 1000ms
-
-// With debug logging
-const debuggedFn = debounce(async (x: number) => x * 2, {
-  wait: 1000,
-  debug: true
+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
 });
 
-// With abort controller
-const controller = new AbortController();
-const abortableFn = debounce(async (x: number) => x * 2, {
-  wait: 1000,
-  signal: controller.signal
-});
-
-// Cleanup when done
-debouncedFn.cleanup();
-```
-
-## API Reference
-
-### `debounce<T>(func: T, options?: DebounceOptions): DebouncedFunction<T>`
-
-Creates a debounced version of the provided function.
-
-#### Parameters
-
-##### `func: T`
-The function to debounce. Can be synchronous or asynchronous.
-
-##### `options: DebounceOptions`
-Configuration options for the debounced function.
-
-```typescript
-interface DebounceOptions {
-  readonly wait?: number;      // Delay in milliseconds (default: 0)
-  readonly leading?: boolean;  // Execute on leading edge (default: false)
-  readonly trailing?: boolean; // Execute on trailing edge (default: true)
-  readonly maxWait?: number;   // Maximum time to wait
-  readonly debug?: boolean;    // Enable debug logging (default: false)
-  readonly signal?: AbortSignal; // AbortController signal
-}
-```
-
-#### Returns
-
-Returns a debounced function with the following interface:
-
-```typescript
-interface DebouncedFunction<T> {
-  (...args: Parameters<T>): Promise<Awaited<ReturnType<T>>>;
-  readonly cancel: () => void;
-  readonly flush: (...args: Parameters<T>) => Promise<Awaited<ReturnType<T>>>;
-  readonly pending: () => boolean;
-  readonly cleanup: () => void;
+// Use the debounced function
+try {
+    await debouncedFn('search term');
+} catch (error) {
+    handleError(error);
 }
 ```
 
-## Advanced Usage Examples
-
-### Leading Edge Execution
-
-```typescript
-const leadingDebounce = debounce(
-  (value: string) => console.log(value),
-  { 
-    wait: 1000, 
-    leading: true,
-    trailing: false 
-  }
-);
-
-// Executes immediately, then ignores calls for 1000ms
-leadingDebounce("First");
-leadingDebounce("Second"); // Ignored
-leadingDebounce("Third");  // Ignored
-```
-
-### Maximum Wait Time
-
-```typescript
-const maxWaitDebounce = debounce(
-  (value: string) => console.log(value),
-  { 
-    wait: 1000, 
-    maxWait: 5000 
-  }
-);
-
-// Will execute after 5000ms maximum, even if called continuously
-const interval = setInterval(() => maxWaitDebounce("test"), 100);
-```
-
-### With AbortController
-
-```typescript
-const controller = new AbortController();
-
-const abortableDebounce = debounce(
-  async (value: string) => {
-    await someAsyncOperation(value);
-  },
-  { 
-    wait: 1000,
-    signal: controller.signal 
-  }
-);
-
-// Later, abort all pending operations
-controller.abort();
-```
-
-### Debug Mode
-
-```typescript
-const debugDebounce = debounce(
-  (value: string) => console.log(value),
-  { 
-    wait: 1000,
-    debug: true 
-  }
-);
-
-// Will log detailed information about internal state
-debugDebounce("test");
-```
-
-### Handling Return Values
-
-```typescript
-const asyncDebounce = debounce(
-  async (x: number): Promise<number> => {
-    await delay(100);
-    return x * 2;
-  },
-  { wait: 1000 }
-);
-
-// Get the result
-const result = await asyncDebounce(5);
-console.log(result); // 10
-```
-
-### Cleanup
-
-```typescript
-const debouncedFn = debounce((x: number) => x * 2, { wait: 1000 });
-
-// Use the function
-debouncedFn(5);
-
-// Clean up when done
-debouncedFn.cleanup();
-```
-
-## Best Practices
-
-1. **Always Clean Up**: Call `cleanup()` when you're done with the debounced function to prevent memory leaks:
+## Features
 
-```typescript
-const debouncedFn = debounce(myFunc, { wait: 1000 });
+- **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
 
-// When done:
-debouncedFn.cleanup();
-```
+## Demo
 
-2. **Error Handling**: Always handle potential errors in async operations:
+Checkout the [Demo](https://codepen.io/khaledsmq/pen/wvVVYYe) to see TypeScript Debounce in action.
 
-```typescript
-const debouncedFn = debounce(async () => {
-  try {
-    await debouncedOperation();
-  } catch (error) {
-    // Handle error
-  }
-});
-```
+## Changelog
 
-3. **TypeScript Usage**: Leverage TypeScript's type system:
+Please see [CHANGELOG](./CHANGELOG.md) for more information what has changed recently.
 
-```typescript
-interface MyFuncParams {
-  id: number;
-  name: string;
-}
+## Contributing
 
-const typedDebounce = debounce(
-  (params: MyFuncParams) => console.log(params),
-  { wait: 1000 }
-);
+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!
 
-// TypeScript will enforce correct parameter types
-typedDebounce({ id: 1, name: "test" });
-```
+### How to Contribute
+1. Read [Contributing Guide](https://github.com/KhaledSMQ/avati/blob/master/Contributing.md) for details on how to get started.
+2. Fork the repository and make your changes.
+3. Submit a pull request, and we’ll review it as soon as possible.
 
-## Common Gotchas
+## License
 
-1. **Memory Leaks**: Not calling `cleanup()` when done can lead to memory leaks.
-2. **Shared State**: Be careful with shared state in debounced functions.
-3. **Error Handling**: Always handle potential errors in async operations.
-4. **Maximum Wait Time**: Setting `maxWait` less than `wait` will throw an error.
+[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/KhaledSMQ/avati/blob/master/LICENSE)
 
-## Contributing
+Avati is open-source and distributed under the [MIT License](https://github.com/KhaledSMQ/avati/blob/master/LICENSE).
 
-Contributions are welcome! Please read our [contributing guide](CONTRIBUTING.md) for details on our code of conduct and the process for submitting pull requests.
+---
+<div align="center">
 
-## License
+[![Follow on Twitter](https://img.shields.io/twitter/follow/KhaledSMQ.svg?style=social)](https://x.com/khaledsmq_)
+[![Follow on LinkedIn](https://img.shields.io/badge/LinkedIn-Connect-blue.svg)](https://www.linkedin.com/in/khaledsmq/)
+[![Follow on Medium](https://img.shields.io/badge/Medium-Follow-black.svg)](https://medium.com/@khaled.smq)
+[![Made with ❤️](https://img.shields.io/badge/Made%20with-❤️-red.svg)](https://github.com/KhaledSMQ)
+[![Star on GitHub](https://img.shields.io/github/stars/KhaledSMQ/avati.svg?style=social)](https://github.com/KhaledSMQ/avati/stargazers)
+[![Follow on GitHub](https://img.shields.io/github/followers/KhaledSMQ.svg?style=social&label=Follow)](https://github.com/KhaledSMQ)
 
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+</div>