Registry / web-framework / ts-debounce

ts-debounce

JSON →
library5.0.0jsnpmunverified

This package provides a robust TypeScript implementation of the debounce function, designed to limit the rate at which a function can be called. It is currently at version 5.0.0 and sees releases driven by feature enhancements and necessary fixes, rather than a strict schedule. Key features include full TypeScript support with improved type inference, cancellation functionality, an optional `maxWait` parameter to force execution after a maximum delay, and comprehensive Promise integration, allowing debouncing of promise-returning functions and returning promises from debounced calls. It differentiates itself by being TypeScript-first, directly addressing common debounce use cases with strong typing, and offering flexibility similar to popular utility libraries like Lodash but with a smaller footprint and modern ESM support.

web-frameworkhttp-networking
npm install ts-debounce
github ↗package ↗
INSTALL
IMPORT
SIG · TS-DEBOUNCE
T
ts-debounce
web-frameworkjavascriptv5.0.0
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

debounce
✓ import { debounce } from 'ts-debounce';
The primary `debounce` utility is a named export. This is the standard way to import in modern JavaScript/TypeScript.
debounce
✓
✗ import debounce from 'ts-debounce';
The library does not provide a default export. Attempting a default import will result in an undefined value.
debounce
✓ const { debounce } = require('ts-debounce');
✗ const debounce = require('ts-debounce');
For CommonJS environments, `debounce` must be destructured from the `require` call as it is a named export. Directly assigning `require('ts-debounce')` will not yield the function itself.
DebouncedFunction
✓ import type { DebouncedFunction } from 'ts-debounce';
For type-only imports, explicitly use `import type` to ensure correct tree-shaking and to avoid accidental runtime imports.

Demonstrates basic function debouncing for a synchronous logger and advanced usage involving asynchronous functions with Promise support and the cancellation mechanism.

import { debounce } from 'ts-debounce'; // Example 1: Basic debouncing for input handling function logInput(value: string) { console.log('Debounced input:', value); } const debouncedLog = debounce(logInput, 500); // Simulate rapid input events debouncedLog('a'); debouncedLog('ap'); debouncedLog('app'); // This call will execute 500ms after the last 'app' call setTimeout(() => debouncedLog('apple'), 600); // Example 2: Debouncing an asynchronous function with cancellation const fetchUserData = async (userId: string): Promise<string> => { console.log(`Fetching data for ${userId}...`); return new Promise(resolve => setTimeout(() => resolve(`Data for ${userId}`), 1000)); }; const debouncedFetch = debounce(fetchUserData, 300); async function testAsyncDebounce() { console.log("Calling async debounced function rapidly..."); const p1 = debouncedFetch('user1'); const p2 = debouncedFetch('user2'); const p3 = debouncedFetch('user3'); // This will be the one that gets executed if not cancelled setTimeout(() => { debouncedFetch.cancel(); // Cancel the pending 'user3' call console.log("Debounced fetch cancelled."); }, 400); // This will happen before 'user3' would execute try { // p1 and p2 will reject if the final call is cancelled await Promise.allSettled([p1, p2, p3]); console.log("Promises settled (some may be rejected due to cancellation)."); } catch (e: any) { console.warn("An unexpected error occurred during async debounce test:", e.message); } } testAsyncDebounce();
Debug
Known issues
breakingVersion 5.0.0 introduces the use of the `Awaited` type to prevent `Promise<Promise<T>>` in promise-returning debounced functions. While an improvement, this change might subtly alter the inferred return types, potentially causing existing type checks to break if they were expecting less specific types.
fix
Review and update type annotations for functions debounced in version 5.0.0, especially those returning promises, to align with the stricter `Awaited` inference. Adjust expectations for `Promise` return types to `Promise<T>` instead of `Promise<Promise<T>>`.
affects: >=5.0.0
breakingVersion 4.0.0 significantly improved type inference for arguments passed to the debounced function. This means types that were previously inferred as `any` (e.g., event objects in event listeners) are now much more specific. If your existing code relied on the looser `any` type, it might now trigger TypeScript compilation errors.
fix
Update your function signatures and event handlers to correctly type the arguments based on the improved inference (e.g., `(event: Event)` instead of `(event: any)`). This generally leads to more robust and safer code.
affects: >=4.0.0
gotchaStarting from version 3.0.0, `ts-debounce` introduced Promise support. This functionality relies on the global `Promise` object being available in the execution environment. In older browser environments or Node.js versions, a global `Promise` polyfill might be required.
fix
Ensure that your target execution environment provides a global `Promise` implementation, or include a polyfill (e.g., `core-js`) if targeting older environments.
affects: >=3.0.0
gotchaThe `isImmediate` option, when set to `true`, causes the `originalFunction` to be invoked immediately on the first call, and subsequent calls are debounced. If not fully understood, this can lead to unexpected immediate executions when the intention was a delayed one.
fix
Carefully consider the interaction of `isImmediate` with `waitMilliseconds`. If you always want a delay before the first execution, do not set `isImmediate` to `true`. Read the documentation thoroughly to understand its behavior.
affects: >=2.0.0
Errors
Common errors & fixes
Argument of type 'any' is not assignable to parameter of type 'Event'.
Improved type inference in `ts-debounce` v4.0.0 and above now provides more specific types for function arguments, removing reliance on `any`.
fix
Update the type signature of your debounced function's arguments to match the expected specific type (e.g., `(event: Event)`). For example, `debounce((event: Event) => { /* ... */ }, 300);`
TypeError: Cannot read property 'debounce' of undefined
This typically occurs in CommonJS environments when attempting to `require('ts-debounce')` and expecting a default export, or attempting to use `const debounce = require('ts-debounce')` instead of destructuring.
fix
Ensure you are destructuring the named export: `const { debounce } = require('ts-debounce');`. If using ES Modules, prefer `import { debounce } from 'ts-debounce';`.
ReferenceError: Promise is not defined
Running `ts-debounce` v3.0.0 or higher in a JavaScript environment that lacks a global `Promise` object (e.g., older browsers or Node.js without a polyfill).
fix
Include a `Promise` polyfill (e.g., from `core-js` or `es6-promise`) in your application bundle to provide the necessary global `Promise` implementation.
Upgrade
Version history
5.0.0latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
7 hits · last 30 days
node
6
OpenAI (training)
1
Resources
githubhttps://github.com/chodorowicz/ts-debounce ↗
packagehttps://www.npmjs.com/package/ts-debounce ↗
ts-debounce — npm install ts-debounce · libregistry