HORIZON PROJECT

var isObject = require('./isObject'),

    now = require('./now'),

    toNumber = require('./toNumber');

/** Error message constants. */

var FUNC_ERROR_TEXT = 'Expected a function';

/* Built-in method references for those with the same name as other `lodash` methods. */

var nativeMax = Math.max,

    nativeMin = Math.min;

/**

 * Creates a debounced function that delays invoking `func` until after `wait`

 * milliseconds have elapsed since the last time the debounced function was

 * invoked. The debounced function comes with a `cancel` method to cancel

 * delayed `func` invocations and a `flush` method to immediately invoke them.

 * Provide `options` to indicate whether `func` should be invoked on the

 * leading and/or trailing edge of the `wait` timeout. The `func` is invoked

 * with the last arguments provided to the debounced function. Subsequent

 * calls to the debounced function return the result of the last `func`

 * invocation.

 *

 * **Note:** If `leading` and `trailing` options are `true`, `func` is

 * invoked on the trailing edge of the timeout only if the debounced function

 * is invoked more than once during the `wait` timeout.

 *

 * If `wait` is `0` and `leading` is `false`, `func` invocation is deferred

 * until to the next tick, similar to `setTimeout` with a timeout of `0`.

 *

 * See [David Corbacho's article](https://css-tricks.com/debouncing-throttling-explained-examples/)

 * for details over the differences between `_.debounce` and `_.throttle`.

 *

 * @static

 * @memberOf _

 * @since 0.1.0

 * @category Function

 * @param {Function} func The function to debounce.

 * @param {number} [wait=0] The number of milliseconds to delay.

 * @param {Object} [options={}] The options object.

 * @param {boolean} [options.leading=false]

 *  Specify invoking on the leading edge of the timeout.

 * @param {number} [options.maxWait]

 *  The maximum time `func` is allowed to be delayed before it's invoked.

 * @param {boolean} [options.trailing=true]

 *  Specify invoking on the trailing edge of the timeout.

 * @returns {Function} Returns the new debounced function.

 * @example

 *

 * // Avoid costly calculations while the window size is in flux.

 * jQuery(window).on('resize', _.debounce(calculateLayout, 150));

 *

 * // Invoke `sendMail` when clicked, debouncing subsequent calls.

 * jQuery(element).on('click', _.debounce(sendMail, 300, {

 *   'leading': true,

 *   'trailing': false

 * }));

 *

 * // Ensure `batchLog` is invoked once after 1 second of debounced calls.

 * var debounced = _.debounce(batchLog, 250, { 'maxWait': 1000 });

 * var source = new EventSource('/stream');

 * jQuery(source).on('message', debounced);

 *

 * // Cancel the trailing debounced invocation.

 * jQuery(window).on('popstate', debounced.cancel);

 */

function debounce(func, wait, options) {

  var lastArgs,

      lastThis,

      maxWait,

      result,

      timerId,

      lastCallTime,

      lastInvokeTime = 0,

      leading = false,

      maxing = false,

      trailing = true;

  if (typeof func != 'function') {

    throw new TypeError(FUNC_ERROR_TEXT);

  }

  wait = toNumber(wait) || 0;

  if (isObject(options)) {

    leading = !!options.leading;

    maxing = 'maxWait' in options;

    maxWait = maxing ? nativeMax(toNumber(options.maxWait) || 0, wait) : maxWait;

    trailing = 'trailing' in options ? !!options.trailing : trailing;

  }

  function invokeFunc(time) {

    var args = lastArgs,

        thisArg = lastThis;

    lastArgs = lastThis = undefined;

    lastInvokeTime = time;

    result = func.apply(thisArg, args);

    return result;

  }

  function leadingEdge(time) {

    // Reset any `maxWait` timer.

    lastInvokeTime = time;

    // Start the timer for the trailing edge.

    timerId = setTimeout(timerExpired, wait);

    // Invoke the leading edge.

    return leading ? invokeFunc(time) : result;

  }

  function remainingWait(time) {

    var timeSinceLastCall = time - lastCallTime,

        timeSinceLastInvoke = time - lastInvokeTime,

        timeWaiting = wait - timeSinceLastCall;

    return maxing

      ? nativeMin(timeWaiting, maxWait - timeSinceLastInvoke)

      : timeWaiting;

  }

  function shouldInvoke(time) {

    var timeSinceLastCall = time - lastCallTime,

        timeSinceLastInvoke = time - lastInvokeTime;

    // Either this is the first call, activity has stopped and we're at the

    // trailing edge, the system time has gone backwards and we're treating

    // it as the trailing edge, or we've hit the `maxWait` limit.

    return (lastCallTime === undefined || (timeSinceLastCall >= wait) ||

      (timeSinceLastCall < 0) || (maxing && timeSinceLastInvoke >= maxWait));

  }

  function timerExpired() {

    var time = now();

    if (shouldInvoke(time)) {

      return trailingEdge(time);

    }

    // Restart the timer.

    timerId = setTimeout(timerExpired, remainingWait(time));

  }

  function trailingEdge(time) {

    timerId = undefined;

    // Only invoke if we have `lastArgs` which means `func` has been

    // debounced at least once.

    if (trailing && lastArgs) {

      return invokeFunc(time);

    }

    lastArgs = lastThis = undefined;

    return result;

  }

  function cancel() {

    if (timerId !== undefined) {

      clearTimeout(timerId);

    }

    lastInvokeTime = 0;

    lastArgs = lastCallTime = lastThis = timerId = undefined;

  }

  function flush() {

    return timerId === undefined ? result : trailingEdge(now());

  }

  function debounced() {

    var time = now(),

        isInvoking = shouldInvoke(time);

    lastArgs = arguments;

    lastThis = this;

    lastCallTime = time;

    if (isInvoking) {

      if (timerId === undefined) {

        return leadingEdge(lastCallTime);

      }

      if (maxing) {

        // Handle invocations in a tight loop.

        timerId = setTimeout(timerExpired, wait);

        return invokeFunc(lastCallTime);

      }

    }

    if (timerId === undefined) {

      timerId = setTimeout(timerExpired, wait);

    }

    return result;

  }

  debounced.cancel = cancel;

  debounced.flush = flush;

  return debounced;

}

module.exports = debounce;