www.aleph1.co.uk Git - yaffs-website/blob - node_modules/node-sass/node_modules/lodash/throttle.js

   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;