Metal Throttle Utility

3.0.1 verified Thu Apr 23 auth: no javascript

The `metal-throttle` package provides a utility function to limit the rate at which a function can be called. This is essential for optimizing performance in web applications by preventing excessive execution of handlers for frequent events like scrolling, resizing, or rapid clicks. It ensures a function executes at most once within a specified time window, discarding subsequent calls until the timeout expires. As part of the broader Metal.js ecosystem, it aims to offer a reliable and efficient throttling mechanism. Currently at version `3.0.1`, it is a stable utility. Without more specific release information, its cadence is generally aligned with the Metal.js project. Key differentiators typically revolve around its integration within the Metal.js framework, potentially offering optimizations or API consistency tailored for that environment, though basic throttling logic is common across many libraries.

Common errors

error TypeError: (0 , _metalThrottle.throttle) is not a function ↓

cause Incorrect import statement, often when mixing CommonJS `require` with ESM `import` syntax or attempting to use a default import for a named export.

fix

For ESM, use import { throttle } from 'metal-throttle';. For CommonJS, use const { throttle } = require('metal-throttle');.

error throttle is not defined ↓

cause The `throttle` function was used without being imported or correctly made available in the current scope.

fix

Add the correct import statement at the top of your file: import { throttle } from 'metal-throttle'; or const { throttle } = require('metal-throttle');.

Warnings

breaking Major versions (like 3.0.0) typically introduce breaking changes. Always review the release notes or changelog when upgrading from an earlier major version to ensure compatibility with API changes, argument order, or return values. ↓

fix Consult the `metal-throttle` v3 migration guide or changelog. Update function signatures and usage patterns according to the new API specification.

gotcha The `this` context inside a throttled function can be lost if not explicitly bound or managed. This is a common JavaScript pitfall, not specific to `metal-throttle`, but important when working with class methods or object methods. ↓

fix Use an arrow function (if defining the throttled function inline) or explicitly `bind` the function: `throttle(myMethod.bind(this), delay)`.

gotcha When using `throttle` with event listeners, ensure that you store a reference to the *throttled* function to correctly remove the event listener later. Removing `window.removeEventListener('scroll', handleScroll);` will not work if `handleScroll` was attached via `window.addEventListener('scroll', throttledHandleScroll);`. ↓

fix Always use the same throttled function reference for both `addEventListener` and `removeEventListener`: `const throttledFn = throttle(myFn, delay); element.addEventListener('event', throttledFn); element.removeEventListener('event', throttledFn);`

Install

npm install metal-throttle

yarn add metal-throttle

pnpm add metal-throttle

Imports

throttle
wrong
```
const throttle = require('metal-throttle');
```
correct
```
import { throttle } from 'metal-throttle';
```
For modern JavaScript environments (ESM), use named import. CommonJS `require` might return an object, requiring `.throttle` access.
throttle
wrong
```
import throttle from 'metal-throttle';
```
correct
```
const { throttle } = require('metal-throttle');
```
For CommonJS environments, use destructuring assignment from `require()`. A default import is not typically provided for this utility.

Quickstart

Demonstrates how to import and use the `throttle` function with both scroll and click events to limit their execution rate over time.

import { throttle } from 'metal-throttle';

// Example 1: Throttling a scroll event handler
function handleScroll() {
  const scrollPosition = window.scrollY;
  console.log(`Scrolling: Current position is ${scrollPosition}px at ${Date.now()}`);
  // In a real app, you might update UI based on scroll position
}

// Throttled version of handleScroll, runs at most once every 200ms
const throttledScrollHandler = throttle(handleScroll, 200);

// Attach the throttled handler to the scroll event
window.addEventListener('scroll', throttledScrollHandler);

console.log("Scroll down rapidly to see the effect of throttling in the console (output will be limited).");

// Example 2: Throttling a button click handler
let clickCount = 0;
const button = document.createElement('button');
button.textContent = 'Click me (throttled)';
document.body.appendChild(button);

function handleClick() {
  clickCount++;
  console.log(`Button clicked! Total clicks: ${clickCount} at ${Date.now()}`);
}

// Throttled version of handleClick, runs at most once every 1000ms (1 second)
const throttledClickHandler = throttle(handleClick, 1000);

button.addEventListener('click', throttledClickHandler);

console.log("A button has been added to the page. Click it rapidly to observe how the console output is throttled.");

// Cleanup (optional, for demonstration purposes)
setTimeout(() => {
  window.removeEventListener('scroll', throttledScrollHandler);
  button.removeEventListener('click', throttledClickHandler);
  button.remove();
  console.log("Demonstration complete. Event listeners removed.");
}, 10000);