;\n```\n\n#### Parameters\n\n- `callback` (`T`): The function to throttle.\n- `limit` (`number`, optional): The time interval in milliseconds to throttle executions to. Defaults to `250` ms.\n- `options` (`ThrottleOptions`, optional):\n - `leading` (`boolean`, default `true`): Specify if the function should be invoked on the leading edge of the timeout.\n - `trailing` (`boolean`, default `true`): Specify if the function should be invoked on the trailing edge of the timeout.\n - `onError` (`(error: any) => void`, optional): Callback to handle errors thrown by the throttled function.\n\n#### Returns\n\nA throttled version of the input function with additional methods:\n\n- `cancel()`: Cancels any pending executions and resets the throttle state.\n- `flush()`: Immediately invokes the pending execution of the throttled function.\n\n## Methods\n\n### `cancel`\n\nCancels any pending executions and resets the throttle state.\n\n#### Usage\n\n```typescript\nthrottledFunction.cancel();\n```\n\n### `flush`\n\nImmediately invokes the pending execution of the throttled function.\n\n#### Usage\n\n```typescript\nthrottledFunction.flush();\n```\n\n## Best Use Cases\n\nThrottling is an excellent technique to optimize performance by limiting the frequency of function executions. Here are some ideal scenarios where using the throttle function can be highly beneficial:\n\n### 1. **Event Handling**\n\n- **Scroll Events**: Handling scroll events can be performance-intensive, especially when updating UI elements based on scroll position. Throttling ensures the handler executes at manageable intervals.\n\n ```typescript\n const handleScroll = () => {\n console.log('Scrolling...');\n };\n \n const throttledScroll = throttle(handleScroll, 200);\n window.addEventListener('scroll', throttledScroll);\n ```\n\n- **Resize Events**: Similar to scroll events, window resize events can trigger numerous rapid executions. Throttling helps in updating layout or performing calculations efficiently.\n\n ```typescript\n const handleResize = () => {\n console.log('Window resized');\n };\n \n const throttledResize = throttle(handleResize, 300);\n window.addEventListener('resize', throttledResize);\n ```\n\n### 2. **API Calls**\n\n- **Search Input**: When implementing a search-as-you-type feature, throttling API calls prevents overwhelming the server with requests for every keystroke.\n\n ```typescript\n const search = (query: string) => {\n fetch(`/api/search?q=${query}`)\n .then(response => response.json())\n .then(data => console.log(data));\n };\n \n const throttledSearch = throttle(search, 500);\n \n const handleInput = (event: Event) => {\n const input = event.target as HTMLInputElement;\n throttledSearch(input.value);\n };\n \n const searchInput = document.getElementById('search') as HTMLInputElement;\n searchInput.addEventListener('input', handleInput);\n ```\n\n### 3. **Animations and Transitions**\n\n- **Scroll-Based Animations**: Throttling can be used to control the frequency of animation updates based on scroll position, ensuring smooth performance without unnecessary computations.\n\n ```typescript\n const animateOnScroll = () => {\n // Animation logic\n };\n \n const throttledAnimate = throttle(animateOnScroll, 100);\n window.addEventListener('scroll', throttledAnimate);\n ```\n\n### 4. **Button Clicks**\n\n- **Preventing Rapid Clicks**: Throttling button click handlers can prevent multiple rapid submissions or unintended repeated actions.\n\n ```typescript\n const handleClick = () => {\n console.log('Button clicked');\n };\n \n const throttledClick = throttle(handleClick, 1000, { leading: true, trailing: false });\n const button = document.getElementById('submit-btn') as HTMLButtonElement;\n button.addEventListener('click', throttledClick);\n ```\n\n### 5. **Logging and Analytics**\n\n- **Performance Monitoring**: Throttling logging functions ensures that performance metrics or user interactions are recorded without affecting application performance.\n\n ```typescript\n const logEvent = (event: string) => {\n console.log(`Event: ${event}`);\n };\n \n const throttledLog = throttle(logEvent, 1000);\n \n const trackUserAction = (action: string) => {\n throttledLog(action);\n };\n \n // Example usage\n trackUserAction('click');\n trackUserAction('scroll');\n ```\n\n## When to Avoid\n\nWhile throttling is a powerful tool for optimizing performance, it's not always the appropriate choice. Here are some scenarios where using throttling might be counterproductive or unnecessary:\n\n### 1. **Immediate Execution Required**\n\n- **Critical Actions**: If a function needs to execute immediately and reliably every time an event occurs, throttling can introduce unwanted delays or missed executions.\n\n **Example**: Real-time form validation where each input needs to be validated instantly.\n\n ```typescript\n const validateInput = (input: string) => {\n // Validation logic\n };\n \n // Avoid throttling\n const handleInput = (event: Event) => {\n const input = event.target as HTMLInputElement;\n validateInput(input.value);\n };\n \n inputElement.addEventListener('input', handleInput);\n ```\n\n### 2. **Non-Performance-Critical Functions**\n\n- **Simple Logic**: For functions that are lightweight and don't impact performance, throttling adds unnecessary complexity without significant benefits.\n\n **Example**: Updating a non-visual counter or simple state updates.\n\n ```typescript\n let counter = 0;\n \n const incrementCounter = () => {\n counter += 1;\n console.log(counter);\n };\n \n // No need to throttle\n button.addEventListener('click', incrementCounter);\n ```\n\n### 3. **Debounce Requirements**\n\n- **Waiting for Inactivity**: If the desired behavior is to execute a function only after a period of inactivity (e.g., waiting for the user to stop typing), debouncing is more appropriate than throttling.\n\n **Example**: Autocomplete search where the search is triggered only after the user stops typing.\n\n ```typescript\n const debounce = (func: Function, wait: number) => { /* debounce implementation */ };\n \n const search = (query: string) => {\n // Search logic\n };\n \n const debouncedSearch = debounce(search, 300);\n \n const handleInput = (event: Event) => {\n const input = event.target as HTMLInputElement;\n debouncedSearch(input.value);\n };\n \n inputElement.addEventListener('input', handleInput);\n ```\n\n### 4. **Sequential Dependencies**\n\n- **Dependent Operations**: When function executions depend on the completion of previous calls, throttling can disrupt the sequence and lead to inconsistent states.\n\n **Example**: Sequential data processing where each step relies on the previous one.\n\n ```typescript\n const processData = async (data: any) => {\n // Processing logic\n };\n \n // Avoid throttling\n const handleData = (data: any) => {\n processData(data);\n };\n \n dataEmitter.on('data', handleData);\n ```\n\n### 5. **Single-Execution Functions**\n\n- **One-Time Actions**: For functions that are intended to execute only once (e.g., initialization tasks), throttling is unnecessary.\n\n **Example**: Initializing a third-party library on page load.\n\n ```typescript\n const initializeLibrary = () => {\n // Initialization logic\n };\n \n // No need to throttle\n window.addEventListener('load', initializeLibrary);\n ```\n\n### 6. **High-Frequency Data Streams**\n\n- **Data Integrity**: In scenarios where every piece of data is crucial (e.g., financial transactions, real-time data feeds), throttling can result in loss of important information.\n\n **Example**: Processing real-time stock price updates where each update is significant.\n\n ```typescript\n const handleStockUpdate = (price: number) => {\n console.log(`New price: ${price}`);\n };\n \n // Avoid throttling\n stockPriceEmitter.on('update', handleStockUpdate);\n ```\n\n## Error Handling\n\nErrors thrown by the throttled function are caught and can be handled using the `onError` option. If `onError` is not provided, errors will be rethrown.\n\n### Example\n\n```typescript\nconst handleClick = () => {\n throw new Error('Test error');\n};\n\nconst throttledClick = throttle(handleClick, 1000, {\n onError: (error) => console.error('Throttle error:', error),\n});\n\nthrottledClick(); // Logs: Throttle error: Error: Test error\n```\n## Recommended Limits\n\nThe best limit for a throttle function depends on the specific use case and the desired balance between responsiveness and performance.\n\n### 1. **Frequent UI Events (e.g., `scroll`, `mousemove`, `resize`)**\n- **Recommended Limit:** `36ms - 100ms`\n- **Why:** These events can fire dozens of times per second. Throttling to 50-100ms reduces the number of function calls while maintaining smooth user experience.\n\n### 2. **Input Fields (e.g., `keyup`, `input`)**\n- **Recommended Limit:** `300ms - 500ms`\n- **Why:** When users type, you typically want to update suggestions, validate input, or perform searches without lag. A slightly higher limit allows you to reduce the load on your system while still responding in near real-time.\n\n### 3. **API Calls (e.g., Search Suggestions, Autosave)**\n- **Recommended Limit:** `500ms - 1000ms`\n- **Why:** These operations are often more resource-intensive, and limiting them reduces the load on your backend while providing timely feedback.\n\n### 4. **Animation/Rendering (e.g., game loops or dynamic canvas updates)**\n- **Recommended Limit:** `16ms`\n- **Why:** This is equivalent to ~60fps, the standard for smooth animations. If performance is a concern, consider using `requestAnimationFrame` instead.\n\n### 5. **Debounced-like Scenarios (where minimal calls are preferred)**\n- **Recommended Limit:** `1000ms` or more\n- **Why:** In situations like window resize or orientation change, you may only need updates occasionally to prevent excessive calculations.\n\n### Choosing the Right Limit:\n- **Test and Adjust:** Start with a conservative value and adjust based on user feedback and performance metrics.\n- **Device Capabilities:** On slower devices, increase the limit to prevent performance issues.\n- **Event Type:** Match the limit to the event’s natural frequency.\n\nWould you like help implementing a throttle function with a specific limit?\n\n\n___\n\n## Changelog\n\nPlease see [CHANGELOG](./CHANGELOG.md) for more information what has changed recently.\n\n## Contributing\n\nI 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!\n\n### How to Contribute\n1. Read [Contributing Guide](https://github.com/KhaledSMQ/avati/blob/master/Contributing.md) for details on how to get started.\n2. Fork the repository and make your changes.\n3. Submit a pull request, and we’ll review it as soon as possible.\n\n## License\n\n[](https://github.com/KhaledSMQ/avati/blob/master/LICENSE)\n\nAvati is open-source and distributed under the [MIT License](https://github.com/KhaledSMQ/avati/blob/master/LICENSE).\n\n---\n\n\n[](https://x.com/khaledsmq_)\n[](https://www.linkedin.com/in/khaledsmq/)\n[](https://medium.com/@khaled.smq)\n[](https://github.com/KhaledSMQ)\n[](https://github.com/KhaledSMQ/avati/stargazers)\n[](https://github.com/KhaledSMQ)\n\n
\n","readmeFilename":"README.md"}