Function Throttling with TypeScript

1.1.0 · active · verified Sun Apr 19

The `throttle-typescript` package provides a lightweight, TypeScript-first utility for function throttling. It enables developers to limit the rate at which a given function can be invoked, which is crucial for performance optimization in applications dealing with high-frequency events like window resizing, scrolling, or user input. The current stable version is 1.1.0, featuring an updated return value mechanism that now provides the result of the last successful function execution, alongside refined TypeScript type definitions. The library's core differentiator is its native inclusion of TypeScript types, eliminating the need for separate `@types/` packages and ensuring a smooth development experience within TypeScript projects. While the release cadence appears stable rather than rapid, it indicates a focus on robustness and type correctness. This package is ideal for scenarios where continuous event handling needs to be managed efficiently to prevent UI jank and improve overall responsiveness. It contrasts with debouncing by ensuring periodic execution rather than waiting for an idle period.

Common errors

```
TypeError: Cannot read properties of undefined (reading 'myMethod')
```
cause The `this` context was lost when throttling an object method without binding it.

fix Bind the method to its `this` context: `window.addEventListener('scroll', throttle(this.myMethod.bind(this), 100));` or use an arrow function: `window.addEventListener('scroll', throttle(() => this.myMethod(), 100));`
```
Module '"throttle-typescript"' has no exported member 'default'.
```
cause Attempting to import the `throttle` function as a default import when it is a named export.

fix Use a named import: `import { throttle } from 'throttle-typescript';`
```
Cannot find module 'throttle-typescript' or its corresponding type declarations.
```
cause The package has not been installed, or there is a typo in the import path. For TypeScript, it can also indicate an issue with `tsconfig.json` or module resolution.

fix Ensure the package is installed: `npm install throttle-typescript` or `yarn add throttle-typescript`. Double-check the import statement for typos: `import { throttle } from 'throttle-typescript';`

Warnings

gotcha The return value of the throttled function changed in v1.1.0. It now reflects the result of the last actual execution of the underlying function. Previously, the return value behavior was less explicitly defined.
Fix: If your code relies on the return value of the throttled function, ensure it correctly handles this new behavior. Verify that any assignments or conditional logic based on the throttled function's output are still valid.
gotcha When throttling an object method (e.g., `this.myMethod`), the `this` context can be lost within the throttled function, leading to `TypeError: Cannot read properties of undefined`.
Fix: Preserve the `this` context by binding the method or using an arrow function: `throttle(this.myMethod.bind(this), 100)` or `throttle(() => this.myMethod(), 100)`.
gotcha This package implements 'throttling', which ensures a function executes at most once per a specified time interval. It is not 'debouncing', which executes a function only after a period of inactivity.
Fix: Confirm that throttling is the correct pattern for your use case. If you need to respond to an event only once activity has ceased (e.g., searching after a user stops typing), you should use a 'debounce' utility instead.

Install

npm install throttle-typescript npm
yarn add throttle-typescript yarn
pnpm add throttle-typescript pnpm

Imports

throttle
wrong:
```
const throttle = require('throttle-typescript');
```
correct:
```
import { throttle } from 'throttle-typescript';
```
The package is primarily designed for ES Modules and ships with TypeScript types. While CommonJS `require` might work in some environments, ES module import is the recommended approach for modern JavaScript and TypeScript.

Quickstart

Demonstrates how to install `throttle-typescript` and use the `throttle` function to limit the execution rate of an event handler (e.g., `window.resize`) and direct function calls, showcasing its behavior.

import { throttle } from 'throttle-typescript';

// A function that simulates some expensive operation, like a complex UI update
let executionCount = 0;
function handleExpensiveOperation() {
    executionCount++;
    const timestamp = new Date().toLocaleTimeString();
    console.log(`[${timestamp}] Heavy operation executed! Count: ${executionCount}`);
    // In a real application, this might involve DOM manipulation, recalculations, network requests, etc.
}

// Create a throttled version of the function
// It will run at most once every 200 milliseconds.
const throttledHandler = throttle(handleExpensiveOperation, 200);

// Attach the throttled function to a common high-frequency event, like window resize
window.addEventListener('resize', throttledHandler);

// You can also call it directly, and it will respect the throttle limit
let intervalCalls = 0;
const intervalId = setInterval(() => {
    if (intervalCalls >= 10) {
        clearInterval(intervalId);
        console.log('Stopped interval calls.');
        return;
    }
    console.log(`Calling throttledHandler from interval (call ${intervalCalls + 1})...`);
    throttledHandler();
    intervalCalls++;
}, 50);

console.log("Setup complete. Try resizing your browser window or observe the interval calls in the console.");

view raw JSON →