Metal Debounce Utility

2.0.2 · abandoned · verified Sun Apr 19

metal-debounce is a utility library providing a debounce function, originally part of the deprecated Metal.js framework. It delays the execution of a function until a specified time has elapsed since its last invocation, a common pattern for optimizing event handlers (e.g., input, resize, scroll) by preventing excessive calls. The current stable version is 2.0.2, last published approximately seven years ago. As the Metal.js framework itself is no longer actively maintained for open-source releases, this package should be considered abandoned. It likely targets older JavaScript environments and CommonJS modules, lacking modern features like native ESM support or TypeScript definitions. Alternatives like `lodash.debounce` or `debounce-fn` offer more robust and actively maintained solutions.

Common errors

```
TypeError: debounce is not a function
```
cause Attempting to destructure a CommonJS module that exports a single function directly, or incorrect import syntax.

fix Ensure you are using `const debounce = require('metal-debounce');` to correctly import the function, as it's a direct export.
```
SyntaxError: Cannot use import statement outside a module
```
cause Attempting to use ES module `import` syntax in a CommonJS-only environment (e.g., an older Node.js project or without proper transpilation/configuration).

fix Change your import statement to `const debounce = require('metal-debounce');`. If your project requires ESM, you must migrate to a different, actively maintained debounce library that explicitly supports ESM.

Warnings

breaking The `metal-debounce` package, along with its parent Metal.js framework, is officially deprecated and abandoned. No further active development, new features, or maintenance is expected.
Fix: Migrate to a currently maintained debounce utility like `lodash.debounce`, `debounce-fn`, or a modern framework's built-in debounce. These offer better support, performance, and often ESM compatibility.
gotcha This package is designed for CommonJS environments and does not natively support ES Modules (`import`/`export` syntax). Attempting to use ESM imports will result in runtime errors.
Fix: Always use `require('metal-debounce')` to import the utility. For modern projects requiring ESM, consider alternative, actively maintained debounce libraries.
gotcha The package's age (last updated 7 years ago) means it likely lacks TypeScript definitions, modern JavaScript syntax (ES6+), and might not be optimized for current Node.js or browser environments.
Fix: While functional for basic debounce needs in older environments, developers should be aware of potential compatibility issues or the need for manual type declarations in TypeScript projects. Prefer modern alternatives for new development.

Install

npm install metal-debounce npm
yarn add metal-debounce yarn
pnpm add metal-debounce pnpm

Imports

debounce

wrong:

import debounce from 'metal-debounce';

correct:

const debounce = require('metal-debounce');

This package is CJS-only. ESM imports are not supported.

debounce function

const debounce = require('metal-debounce');
const debouncedFunction = debounce(() => console.log('Action!'), 200);

The `require` call directly provides the debounce function.

Quickstart

Demonstrates basic usage of the `debounce` function to limit repeated calls, such as from rapid user input.

const debounce = require('metal-debounce');

function logActivity(message) {
  console.log(`Activity: ${message} at ${new Date().toLocaleTimeString()}`);
}

// Create a debounced version of logActivity that waits 500ms
const debouncedLog = debounce(logActivity, 500);

console.log('Simulating rapid events...');
debouncedLog('Event 1');
debouncedLog('Event 2');
debouncedLog('Event 3');

setTimeout(() => {
  console.log('Waiting 600ms after last debounced call...');
  debouncedLog('Event 4 (should trigger)');
}, 600);

setTimeout(() => {
  console.log('Simulating more rapid events after initial trigger...');
  debouncedLog('Event 5');
  debouncedLog('Event 6');
}, 1200);

setTimeout(() => {
  console.log('Final wait...');
}, 2000);

view raw JSON →