TypeScript Debounce Decorator

0.0.18 · active · verified Sun Apr 19

typescript-debounce-decorator provides a lightweight and dependency-free TypeScript decorator for debouncing class methods. It enables developers to control the execution frequency of functions, preventing rapid, successive calls. The current stable version is 0.0.18, and while release cadence isn't explicitly stated, the version number suggests a mature, low-churn utility. Key differentiators include its minimal footprint (1KB after compression) and zero external dependencies, making it an ideal choice for projects prioritizing bundle size and avoiding dependency bloat. It supports both leading and trailing edge debouncing and offers a `cancel` function to abort pending debounced calls. A notable characteristic is that the return values of decorated methods are inherently discarded.

Common errors

```
Decorators are not enabled. To enable them, set the 'experimentalDecorators' option to 'true' in your 'tsconfig.json' file.
```
cause The TypeScript compiler option `experimentalDecorators` is not enabled.

fix Add `"experimentalDecorators": true` to the `compilerOptions` section of your `tsconfig.json`.
```
Cannot find name 'debounce'.
```
cause The `debounce` symbol has not been imported or the import path is incorrect.

fix Ensure you have `import { debounce } from 'typescript-debounce-decorator';` at the top of your TypeScript file.
```
ReferenceError: Reflect is not defined OR Error: Reflect.metadata is not a function
```
cause The TypeScript compiler option `emitDecoratorMetadata` is enabled, but the `reflect-metadata` polyfill is not loaded at runtime.

fix Install `reflect-metadata` (`npm install reflect-metadata`) and add `import 'reflect-metadata';` once at the entry point of your application (e.g., `main.ts` or `index.ts`).

Warnings

breaking The `leading` option for the `@debounce` decorator changed its default value from `true` to `false` in version 0.0.18.
Fix: If your application relies on leading-edge debouncing behavior, you must explicitly set `{ leading: true }` in the decorator options: `@debounce(1000, { leading: true })`.
gotcha Methods decorated with `@debounce` will have their return values 'eaten' (discarded). The decorator intercepts the method call and does not propagate the return value.
Fix: Design your decorated methods to perform side effects rather than returning values, or refactor your logic to avoid debouncing methods whose return values are critical for subsequent operations.
gotcha TypeScript decorators require specific compiler options to be enabled. Without them, you will encounter compilation errors.
Fix: Ensure that `"experimentalDecorators": true` and `"emitDecoratorMetadata": true` are set under `"compilerOptions"` in your `tsconfig.json`.

Install

npm install typescript-debounce-decorator npm
yarn add typescript-debounce-decorator yarn
pnpm add typescript-debounce-decorator pnpm

Imports

debounce
wrong:
```
import debounce from 'typescript-debounce-decorator';
```
correct:
```
import { debounce } from 'typescript-debounce-decorator';
```
The `debounce` decorator is a named export, not a default export. Ensure you destructure it correctly.
cancel
wrong:
```
const cancel = require('typescript-debounce-decorator').cancel;
```
correct:
```
import { cancel } from 'typescript-debounce-decorator';
```
The `cancel` function is also a named export for clearing pending debounced calls. CommonJS `require` syntax is not directly supported.
@debounce
wrong:
```
class MyClass { @debounce myMethod() {} } // Missing parenthesis, if no options are passed
```
correct:
```
class MyClass { @debounce(1000) myMethod() {} }
```
When using the decorator without any arguments (e.g., just `@debounce`), the parentheses are still required, i.e., `@debounce()` or `@debounce` followed by an argument like `@debounce(1000)`.

Quickstart

This quickstart demonstrates how to apply the `@debounce` decorator to a class method, configure it for leading-edge execution, and use the `cancel` function to prevent pending debounced calls from firing.

import { debounce, cancel } from "typescript-debounce-decorator";

class MyService {
  private count: number = 0;

  constructor() {
    // Simulate user interaction
    setInterval(() => {
      console.log(`Calling increment by interval... current count: ${this.count}`);
      this.increment();
    }, 200);

    // Schedule a cancellation after some time
    setTimeout(() => {
      console.log("Attempting to cancel pending increments...");
      this.clearPending();
    }, 1500);
  }

  @debounce(1000, { leading: true }) // Debounce for 1 second, fire on leading edge
  increment() {
    this.count++;
    console.log(`Incremented! New count: ${this.count}`);
  }

  clearPending() {
    cancel(this.increment);
    console.log("Cancellation command issued.");
  }
}

new MyService();

view raw JSON →