function: throttle

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

Creates a throttled function that only invokes `func` at most once per every `wait` milliseconds. The throttled 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 throttled function. Subsequent calls to the throttled 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 throttled 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 `throttle` and `debounce`.

Example(s):

// Avoid excessively updating the position while scrolling.
jQuery(window).on('scroll', throttle(updatePosition, 100))

// Invoke `renewToken` when the click event is fired, but not more than once every 5 minutes.
const throttled = throttle(renewToken, 300000, { 'trailing': false })
jQuery(element).on('click', throttled)

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

Params:

Returns:

function

  {
    "comment": "/**\r\n * Creates a throttled function that only invokes `func` at most once per\r\n * every `wait` milliseconds. The throttled function comes with a `cancel`\r\n * method to cancel delayed `func` invocations and a `flush` method to\r\n * immediately invoke them. Provide `options` to indicate whether `func`\r\n * should be invoked on the leading and/or trailing edge of the `wait`\r\n * timeout. The `func` is invoked with the last arguments provided to the\r\n * throttled function. Subsequent calls to the throttled function return the\r\n * result of the last `func` 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 throttled 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 to 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 `throttle` and `debounce`.\r\n *\r\n * @since 0.1.0\r\n * @category Function\r\n * @param {Function} func The function to throttle.\r\n * @param {number} [wait=0] The number of milliseconds to throttle invocations to.\r\n * @param {Object} [options={}] The options object.\r\n * @param {boolean} [options.leading=true]\r\n *  Specify invoking on the leading edge of the timeout.\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 throttled function.\r\n * @example\r\n *\r\n * // Avoid excessively updating the position while scrolling.\r\n * jQuery(window).on('scroll', throttle(updatePosition, 100))\r\n *\r\n * // Invoke `renewToken` when the click event is fired, but not more than once every 5 minutes.\r\n * const throttled = throttle(renewToken, 300000, { 'trailing': false })\r\n * jQuery(element).on('click', throttled)\r\n *\r\n * // Cancel the trailing throttled invocation.\r\n * jQuery(window).on('popstate', throttled.cancel)\r\n */",
    "meta": {
        "range": [
            2165,
            2625
        ],
        "filename": "throttle.js",
        "lineno": 46,
        "path": "C:\\Users\\beaujeup\\projects\\jsdoc-template\\examples\\lodash\\lodash-repo",
        "code": {
            "id": "astnode100009542",
            "name": "throttle",
            "type": "FunctionDeclaration",
            "paramnames": [
                "func",
                "wait",
                "options"
            ]
        },
        "vars": {
            "leading": "throttle~leading",
            "trailing": "throttle~trailing"
        }
    },
    "description": "Creates a throttled function that only invokes `func` at most once per\revery `wait` milliseconds. The throttled function comes with a `cancel`\rmethod to cancel delayed `func` invocations and a `flush` method to\rimmediately invoke them. Provide `options` to indicate whether `func`\rshould be invoked on the leading and/or trailing edge of the `wait`\rtimeout. The `func` is invoked with the last arguments provided to the\rthrottled function. Subsequent calls to the throttled function return the\rresult of the last `func` invocation.\r\r**Note:** If `leading` and `trailing` options are `true`, `func` is\rinvoked on the trailing edge of the timeout only if the throttled function\ris invoked more than once during the `wait` timeout.\r\rIf `wait` is `0` and `leading` is `false`, `func` invocation is deferred\runtil to 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 `throttle` and `debounce`.",
    "since": "0.1.0",
    "tags": [
        {
            "originalTitle": "category",
            "title": "category",
            "text": "Function",
            "value": "Function"
        }
    ],
    "params": [
        {
            "type": {
                "names": [
                    "function"
                ]
            },
            "description": "The function to throttle.",
            "name": "func"
        },
        {
            "type": {
                "names": [
                    "number"
                ]
            },
            "optional": true,
            "defaultvalue": 0,
            "description": "The number of milliseconds to throttle invocations to.",
            "name": "wait"
        },
        {
            "type": {
                "names": [
                    "Object"
                ]
            },
            "optional": true,
            "defaultvalue": "{}",
            "description": "The options object.",
            "name": "options"
        },
        {
            "type": {
                "names": [
                    "boolean"
                ]
            },
            "optional": true,
            "defaultvalue": true,
            "description": "Specify invoking on the leading edge of the timeout.",
            "name": "options.leading"
        },
        {
            "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 throttled function."
        }
    ],
    "examples": [
        "// Avoid excessively updating the position while scrolling.\rjQuery(window).on('scroll', throttle(updatePosition, 100))\r\r// Invoke `renewToken` when the click event is fired, but not more than once every 5 minutes.\rconst throttled = throttle(renewToken, 300000, { 'trailing': false })\rjQuery(element).on('click', throttled)\r\r// Cancel the trailing throttled invocation.\rjQuery(window).on('popstate', throttled.cancel)"
    ],
    "name": "throttle",
    "longname": "throttle",
    "kind": "function",
    "scope": "global",
    "___id": "T000002R000875",
    "___s": true,
    "filepath": "throttle.js"
}