function: debounce

debounce(func: function, wait: number, options: Object): function

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 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`.

Example(s):

// 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.
const debounced = debounce(batchLog, 250, { 'maxWait': 1000 })
const source = new EventSource('/stream')
jQuery(source).on('message', debounced)

// Cancel the trailing debounced invocation.
jQuery(window).on('popstate', debounced.cancel)

Params:

Returns:

function

  {
    "comment": "/**\r\n * Creates a debounced function that delays invoking `func` until after `wait`\r\n * milliseconds have elapsed since the last time the debounced function was\r\n * invoked. The debounced function comes with a `cancel` method to cancel\r\n * delayed `func` invocations and a `flush` method to immediately invoke them.\r\n * Provide `options` to indicate whether `func` should be invoked on the\r\n * leading and/or trailing edge of the `wait` timeout. The `func` is invoked\r\n * with the last arguments provided to the debounced function. Subsequent\r\n * calls to the debounced function return the result of the last `func`\r\n * invocation.\r\n *\r\n * **Note:** If `leading` and `trailing` options are `true`, `func` is\r\n * invoked on the trailing edge of the timeout only if the debounced function\r\n * is invoked more than once during the `wait` timeout.\r\n *\r\n * If `wait` is `0` and `leading` is `false`, `func` invocation is deferred\r\n * until the next tick, similar to `setTimeout` with a timeout of `0`.\r\n *\r\n * See [David Corbacho's article](https://css-tricks.com/debouncing-throttling-explained-examples/)\r\n * for details over the differences between `debounce` and `throttle`.\r\n *\r\n * @since 0.1.0\r\n * @category Function\r\n * @param {Function} func The function to debounce.\r\n * @param {number} [wait=0] The number of milliseconds to delay.\r\n * @param {Object} [options={}] The options object.\r\n * @param {boolean} [options.leading=false]\r\n *  Specify invoking on the leading edge of the timeout.\r\n * @param {number} [options.maxWait]\r\n *  The maximum time `func` is allowed to be delayed before it's invoked.\r\n * @param {boolean} [options.trailing=true]\r\n *  Specify invoking on the trailing edge of the timeout.\r\n * @returns {Function} Returns the new debounced function.\r\n * @example\r\n *\r\n * // Avoid costly calculations while the window size is in flux.\r\n * jQuery(window).on('resize', debounce(calculateLayout, 150))\r\n *\r\n * // Invoke `sendMail` when clicked, debouncing subsequent calls.\r\n * jQuery(element).on('click', debounce(sendMail, 300, {\r\n *   'leading': true,\r\n *   'trailing': false\r\n * }))\r\n *\r\n * // Ensure `batchLog` is invoked once after 1 second of debounced calls.\r\n * const debounced = debounce(batchLog, 250, { 'maxWait': 1000 })\r\n * const source = new EventSource('/stream')\r\n * jQuery(source).on('message', debounced)\r\n *\r\n * // Cancel the trailing debounced invocation.\r\n * jQuery(window).on('popstate', debounced.cancel)\r\n */",
    "meta": {
        "range": [
            2491,
            5823
        ],
        "filename": "debounce.js",
        "lineno": 55,
        "path": "C:\\Users\\beaujeup\\projects\\jsdoc-template\\examples\\lodash\\lodash-repo",
        "code": {
            "id": "astnode100001085",
            "name": "debounce",
            "type": "FunctionDeclaration",
            "paramnames": [
                "func",
                "wait",
                "options"
            ]
        },
        "vars": {
            "lastArgs": "debounce~lastArgs",
            "lastThis": "debounce~lastThis",
            "maxWait": "debounce~maxWait",
            "result": "debounce~result",
            "timerId": "debounce~timerId",
            "lastCallTime": "debounce~lastCallTime",
            "lastInvokeTime": "debounce~lastInvokeTime",
            "leading": "debounce~leading",
            "maxing": "debounce~maxing",
            "trailing": "debounce~trailing",
            "wait": "debounce~wait",
            "invokeFunc": "debounce~invokeFunc",
            "leadingEdge": "debounce~leadingEdge",
            "remainingWait": "debounce~remainingWait",
            "shouldInvoke": "debounce~shouldInvoke",
            "timerExpired": "debounce~timerExpired",
            "trailingEdge": "debounce~trailingEdge",
            "cancel": "debounce~cancel",
            "flush": "debounce~flush",
            "debounced": "debounce~debounced",
            "debounced.cancel": "debounce~debounced.cancel",
            "debounced.flush": "debounce~debounced.flush"
        }
    },
    "description": "Creates a debounced function that delays invoking `func` until after `wait`\rmilliseconds have elapsed since the last time the debounced function was\rinvoked. The debounced function comes with a `cancel` method to cancel\rdelayed `func` invocations and a `flush` method to immediately invoke them.\rProvide `options` to indicate whether `func` should be invoked on the\rleading and/or trailing edge of the `wait` timeout. The `func` is invoked\rwith the last arguments provided to the debounced function. Subsequent\rcalls to the debounced function return the result of the last `func`\rinvocation.\r\r**Note:** If `leading` and `trailing` options are `true`, `func` is\rinvoked on the trailing edge of the timeout only if the debounced function\ris invoked more than once during the `wait` timeout.\r\rIf `wait` is `0` and `leading` is `false`, `func` invocation is deferred\runtil the next tick, similar to `setTimeout` with a timeout of `0`.\r\rSee [David Corbacho's article](https://css-tricks.com/debouncing-throttling-explained-examples/)\rfor details over the differences between `debounce` and `throttle`.",
    "since": "0.1.0",
    "tags": [
        {
            "originalTitle": "category",
            "title": "category",
            "text": "Function",
            "value": "Function"
        }
    ],
    "params": [
        {
            "type": {
                "names": [
                    "function"
                ]
            },
            "description": "The function to debounce.",
            "name": "func"
        },
        {
            "type": {
                "names": [
                    "number"
                ]
            },
            "optional": true,
            "defaultvalue": 0,
            "description": "The number of milliseconds to delay.",
            "name": "wait"
        },
        {
            "type": {
                "names": [
                    "Object"
                ]
            },
            "optional": true,
            "defaultvalue": "{}",
            "description": "The options object.",
            "name": "options"
        },
        {
            "type": {
                "names": [
                    "boolean"
                ]
            },
            "optional": true,
            "defaultvalue": false,
            "description": "Specify invoking on the leading edge of the timeout.",
            "name": "options.leading"
        },
        {
            "type": {
                "names": [
                    "number"
                ]
            },
            "optional": true,
            "description": "The maximum time `func` is allowed to be delayed before it's invoked.",
            "name": "options.maxWait"
        },
        {
            "type": {
                "names": [
                    "boolean"
                ]
            },
            "optional": true,
            "defaultvalue": true,
            "description": "Specify invoking on the trailing edge of the timeout.",
            "name": "options.trailing"
        }
    ],
    "returns": [
        {
            "type": {
                "names": [
                    "function"
                ]
            },
            "description": "Returns the new debounced function."
        }
    ],
    "examples": [
        "// Avoid costly calculations while the window size is in flux.\rjQuery(window).on('resize', debounce(calculateLayout, 150))\r\r// Invoke `sendMail` when clicked, debouncing subsequent calls.\rjQuery(element).on('click', debounce(sendMail, 300, {\r  'leading': true,\r  'trailing': false\r}))\r\r// Ensure `batchLog` is invoked once after 1 second of debounced calls.\rconst debounced = debounce(batchLog, 250, { 'maxWait': 1000 })\rconst source = new EventSource('/stream')\rjQuery(source).on('message', debounced)\r\r// Cancel the trailing debounced invocation.\rjQuery(window).on('popstate', debounced.cancel)"
    ],
    "name": "debounce",
    "longname": "debounce",
    "kind": "function",
    "scope": "global",
    "___id": "T000002R000114",
    "___s": true,
    "filepath": "debounce.js"
}