{"id":17796,"library":"metal-throttle","title":"Metal Throttle Utility","description":"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.","status":"active","version":"3.0.1","language":"javascript","source_language":"en","source_url":null,"tags":["javascript","metal"],"install":[{"cmd":"npm install metal-throttle","lang":"bash","label":"npm"},{"cmd":"yarn add metal-throttle","lang":"bash","label":"yarn"},{"cmd":"pnpm add metal-throttle","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"For modern JavaScript environments (ESM), use named import. CommonJS `require` might return an object, requiring `.throttle` access.","wrong":"const throttle = require('metal-throttle');","symbol":"throttle","correct":"import { throttle } from 'metal-throttle';"},{"note":"For CommonJS environments, use destructuring assignment from `require()`. A default import is not typically provided for this utility.","wrong":"import throttle from 'metal-throttle';","symbol":"throttle","correct":"const { throttle } = require('metal-throttle');"}],"quickstart":{"code":"import { throttle } from 'metal-throttle';\n\n// Example 1: Throttling a scroll event handler\nfunction handleScroll() {\n  const scrollPosition = window.scrollY;\n  console.log(`Scrolling: Current position is ${scrollPosition}px at ${Date.now()}`);\n  // In a real app, you might update UI based on scroll position\n}\n\n// Throttled version of handleScroll, runs at most once every 200ms\nconst throttledScrollHandler = throttle(handleScroll, 200);\n\n// Attach the throttled handler to the scroll event\nwindow.addEventListener('scroll', throttledScrollHandler);\n\nconsole.log(\"Scroll down rapidly to see the effect of throttling in the console (output will be limited).\");\n\n// Example 2: Throttling a button click handler\nlet clickCount = 0;\nconst button = document.createElement('button');\nbutton.textContent = 'Click me (throttled)';\ndocument.body.appendChild(button);\n\nfunction handleClick() {\n  clickCount++;\n  console.log(`Button clicked! Total clicks: ${clickCount} at ${Date.now()}`);\n}\n\n// Throttled version of handleClick, runs at most once every 1000ms (1 second)\nconst throttledClickHandler = throttle(handleClick, 1000);\n\nbutton.addEventListener('click', throttledClickHandler);\n\nconsole.log(\"A button has been added to the page. Click it rapidly to observe how the console output is throttled.\");\n\n// Cleanup (optional, for demonstration purposes)\nsetTimeout(() => {\n  window.removeEventListener('scroll', throttledScrollHandler);\n  button.removeEventListener('click', throttledClickHandler);\n  button.remove();\n  console.log(\"Demonstration complete. Event listeners removed.\");\n}, 10000);\n","lang":"javascript","description":"Demonstrates how to import and use the `throttle` function with both scroll and click events to limit their execution rate over time."},"warnings":[{"fix":"Consult the `metal-throttle` v3 migration guide or changelog. Update function signatures and usage patterns according to the new API specification.","message":"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.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Use an arrow function (if defining the throttled function inline) or explicitly `bind` the function: `throttle(myMethod.bind(this), delay)`.","message":"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.","severity":"gotcha","affected_versions":">=0.12.0"},{"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);`","message":"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);`.","severity":"gotcha","affected_versions":">=0.12.0"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"fix":"For ESM, use `import { throttle } from 'metal-throttle';`. For CommonJS, use `const { throttle } = require('metal-throttle');`.","cause":"Incorrect import statement, often when mixing CommonJS `require` with ESM `import` syntax or attempting to use a default import for a named export.","error":"TypeError: (0 , _metalThrottle.throttle) is not a function"},{"fix":"Add the correct import statement at the top of your file: `import { throttle } from 'metal-throttle';` or `const { throttle } = require('metal-throttle');`.","cause":"The `throttle` function was used without being imported or correctly made available in the current scope.","error":"throttle is not defined"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}