throttle.js (2709B)
1 var debounce = require('./debounce'), 2 isObject = require('./isObject'); 3 4 /** Error message constants. */ 5 var FUNC_ERROR_TEXT = 'Expected a function'; 6 7 /** 8 * Creates a throttled function that only invokes `func` at most once per 9 * every `wait` milliseconds. The throttled function comes with a `cancel` 10 * method to cancel delayed `func` invocations and a `flush` method to 11 * immediately invoke them. Provide `options` to indicate whether `func` 12 * should be invoked on the leading and/or trailing edge of the `wait` 13 * timeout. The `func` is invoked with the last arguments provided to the 14 * throttled function. Subsequent calls to the throttled function return the 15 * result of the last `func` invocation. 16 * 17 * **Note:** If `leading` and `trailing` options are `true`, `func` is 18 * invoked on the trailing edge of the timeout only if the throttled function 19 * is invoked more than once during the `wait` timeout. 20 * 21 * If `wait` is `0` and `leading` is `false`, `func` invocation is deferred 22 * until to the next tick, similar to `setTimeout` with a timeout of `0`. 23 * 24 * See [David Corbacho's article](https://css-tricks.com/debouncing-throttling-explained-examples/) 25 * for details over the differences between `_.throttle` and `_.debounce`. 26 * 27 * @static 28 * @memberOf _ 29 * @since 0.1.0 30 * @category Function 31 * @param {Function} func The function to throttle. 32 * @param {number} [wait=0] The number of milliseconds to throttle invocations to. 33 * @param {Object} [options={}] The options object. 34 * @param {boolean} [options.leading=true] 35 * Specify invoking on the leading edge of the timeout. 36 * @param {boolean} [options.trailing=true] 37 * Specify invoking on the trailing edge of the timeout. 38 * @returns {Function} Returns the new throttled function. 39 * @example 40 * 41 * // Avoid excessively updating the position while scrolling. 42 * jQuery(window).on('scroll', _.throttle(updatePosition, 100)); 43 * 44 * // Invoke `renewToken` when the click event is fired, but not more than once every 5 minutes. 45 * var throttled = _.throttle(renewToken, 300000, { 'trailing': false }); 46 * jQuery(element).on('click', throttled); 47 * 48 * // Cancel the trailing throttled invocation. 49 * jQuery(window).on('popstate', throttled.cancel); 50 */ 51 function throttle(func, wait, options) { 52 var leading = true, 53 trailing = true; 54 55 if (typeof func != 'function') { 56 throw new TypeError(FUNC_ERROR_TEXT); 57 } 58 if (isObject(options)) { 59 leading = 'leading' in options ? !!options.leading : leading; 60 trailing = 'trailing' in options ? !!options.trailing : trailing; 61 } 62 return debounce(func, wait, { 63 'leading': leading, 64 'maxWait': wait, 65 'trailing': trailing 66 }); 67 } 68 69 module.exports = throttle;