or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-lodash--throttle

The lodash method `_.throttle` exported as a module.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/lodash.throttle@4.1.x

To install, run

npx @tessl/cli install tessl/npm-lodash--throttle@4.1.0

index.mddocs/

Lodash Throttle

Lodash Throttle provides the _.throttle method as a standalone npm module for rate-limiting function calls. It creates throttled functions that only invoke the original function at most once per specified wait period, with configurable leading and trailing edge execution control.

Package Information

  • Package Name: lodash.throttle
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install lodash.throttle

Core Imports

var throttle = require('lodash.throttle');

For ES modules environments:

import throttle from 'lodash.throttle';

Basic Usage

var throttle = require('lodash.throttle');

// Basic throttling - limits function calls to once per 100ms
var throttledUpdate = throttle(function(value) {
  console.log('Update called with:', value);
}, 100);

// Call multiple times quickly - only executes once per 100ms
throttledUpdate('a');
throttledUpdate('b'); 
throttledUpdate('c');

// With options for leading/trailing edge control
var scrollHandler = throttle(updatePosition, 100, {
  leading: true,
  trailing: false
});

window.addEventListener('scroll', scrollHandler);

// Cancel pending invocations
scrollHandler.cancel();

// Immediately execute pending invocation
scrollHandler.flush();

Architecture

Lodash Throttle is built on top of the debounce implementation with specific configuration to create true throttling behavior:

  • Internal Implementation: Uses debounce with maxWait set equal to the wait parameter, ensuring function execution at least once per wait period
  • Edge Control: Configurable leading and trailing edge execution through options
  • Timer Management: Maintains internal timer state with automatic cleanup and reset mechanisms
  • Method Attachment: Dynamically attaches cancel and flush control methods to the returned throttled function
  • Argument Preservation: Preserves the most recent arguments and this context for delayed invocations

Capabilities

Throttle Function

Creates a throttled function that only invokes the provided function at most once per every wait milliseconds.

/**
 * Creates a throttled function that only invokes `func` at most once per
 * every `wait` milliseconds.
 * @param {Function} func The function to throttle.
 * @param {number} [wait=0] The number of milliseconds to throttle invocations to.
 * @param {Object} [options={}] The options object.
 * @param {boolean} [options.leading=true] Specify invoking on the leading edge of the timeout.
 * @param {boolean} [options.trailing=true] Specify invoking on the trailing edge of the timeout.
 * @returns {Function} Returns the new throttled function.
 */
function throttle(func, wait, options);

Parameters:

  • func (Function): The function to throttle
  • wait (number, optional): The number of milliseconds to throttle invocations to. Defaults to 0
  • options (Object, optional): The options object with the following properties:
    • leading (boolean, optional): Specify invoking on the leading edge of the timeout. Defaults to true
    • trailing (boolean, optional): Specify invoking on the trailing edge of the timeout. Defaults to true

Returns: Function - The new throttled function with attached cancel and flush methods

Usage Examples:

var throttle = require('lodash.throttle');

// Throttle scroll events to improve performance
var onScroll = throttle(function() {
  console.log('Scroll event processed');
}, 100);

window.addEventListener('scroll', onScroll);

// Throttle API calls - only leading edge execution
var saveData = throttle(function(data) {
  api.save(data);
}, 1000, { trailing: false });

// Throttle with both leading and trailing execution (default behavior)
var updatePosition = throttle(function(x, y) {
  element.style.left = x + 'px';
  element.style.top = y + 'px';
}, 50);

Cancel Method

Cancels delayed function invocations.

/**
 * Cancels delayed function invocations
 * @returns {void}
 */
throttledFunction.cancel();

The cancel method is attached to every throttled function returned by throttle(). It clears any pending invocations that would have been executed on the trailing edge.

Usage Example:

var throttled = throttle(expensiveOperation, 1000);

// Queue some calls
throttled();
throttled();

// Cancel any pending trailing execution
throttled.cancel();

Flush Method

Immediately invokes pending function invocations.

/**
 * Immediately invokes pending function invocations
 * @returns {*} Returns the result of the last func invocation
 */
throttledFunction.flush();

The flush method is attached to every throttled function returned by throttle(). It immediately executes any pending invocation that would have been executed on the trailing edge.

Usage Example:

var result;
var throttled = throttle(function(value) {
  result = value * 2;
  return result;
}, 1000);

throttled(5);
throttled(10);

// Immediately execute with the last arguments (10)
var flushResult = throttled.flush();
console.log(flushResult); // 20
console.log(result); // 20

Types

/**
 * Options object for throttle function
 */
interface ThrottleOptions {
  /** Specify invoking on the leading edge of the timeout */
  leading?: boolean;
  /** Specify invoking on the trailing edge of the timeout */
  trailing?: boolean;
}

/**
 * Throttled function with cancel and flush methods
 */
interface ThrottledFunction<T extends (...args: any[]) => any> {
  /** Call the throttled function */
  (...args: Parameters<T>): ReturnType<T>;
  /** Cancel delayed function invocations */
  cancel(): void;
  /** Immediately invoke pending function invocations */
  flush(): ReturnType<T>;
}

Error Handling

The throttle function throws a TypeError if the first argument is not a function:

try {
  var invalid = throttle('not a function', 100);
} catch (error) {
  console.log(error.message); // "Expected a function"
}

Performance Considerations

  • Leading vs Trailing: Use leading: true, trailing: false for immediate response to user input
  • Trailing only: Use leading: false, trailing: true for batching operations
  • Wait time: Choose appropriate wait times based on use case:
    • UI events (scroll, resize): 16-100ms
    • API calls: 300-1000ms
    • User input validation: 300-500ms

Common Use Cases

var throttle = require('lodash.throttle');

// 1. Scroll event optimization
var onScroll = throttle(function() {
  updateScrollPosition();
}, 16); // ~60fps

// 2. Window resize handling
var onResize = throttle(function() {
  recalculateLayout();
}, 100);

// 3. API request rate limiting
var searchAPI = throttle(function(query) {
  fetch('/api/search?q=' + query)
    .then(handleResults);
}, 300, { leading: false });

// 4. Mouse move tracking with immediate feedback
var onMouseMove = throttle(function(event) {
  updateCursor(event.clientX, event.clientY);
}, 16, { trailing: false });