1 | import isObject from './isObject';
|
2 | import now from './now';
|
3 | import toNumber from './toNumber';
|
4 |
|
5 | /** Used as the `TypeError` message for "Functions" methods. */
|
6 | var FUNC_ERROR_TEXT = 'Expected a function';
|
7 |
|
8 | /* Built-in method references for those with the same name as other `lodash` methods. */
|
9 | var nativeMax = Math.max,
|
10 | nativeMin = Math.min;
|
11 |
|
12 | /**
|
13 | * Creates a debounced function that delays invoking `func` until after `wait`
|
14 | * milliseconds have elapsed since the last time the debounced function was
|
15 | * invoked. The debounced function comes with a `cancel` method to cancel
|
16 | * delayed `func` invocations and a `flush` method to immediately invoke them.
|
17 | * Provide an options object to indicate whether `func` should be invoked on
|
18 | * the leading and/or trailing edge of the `wait` timeout. The `func` is invoked
|
19 | * with the last arguments provided to the debounced function. Subsequent calls
|
20 | * to the debounced function return the result of the last `func` invocation.
|
21 | *
|
22 | * **Note:** If `leading` and `trailing` options are `true`, `func` is invoked
|
23 | * on the trailing edge of the timeout only if the debounced function is
|
24 | * invoked more than once during the `wait` timeout.
|
25 | *
|
26 | * See [David Corbacho's article](https://css-tricks.com/debouncing-throttling-explained-examples/)
|
27 | * for details over the differences between `_.debounce` and `_.throttle`.
|
28 | *
|
29 | * @static
|
30 | * @memberOf _
|
31 | * @since 0.1.0
|
32 | * @category Function
|
33 | * @param {Function} func The function to debounce.
|
34 | * @param {number} [wait=0] The number of milliseconds to delay.
|
35 | * @param {Object} [options={}] The options object.
|
36 | * @param {boolean} [options.leading=false]
|
37 | * Specify invoking on the leading edge of the timeout.
|
38 | * @param {number} [options.maxWait]
|
39 | * The maximum time `func` is allowed to be delayed before it's invoked.
|
40 | * @param {boolean} [options.trailing=true]
|
41 | * Specify invoking on the trailing edge of the timeout.
|
42 | * @returns {Function} Returns the new debounced function.
|
43 | * @example
|
44 | *
|
45 | * // Avoid costly calculations while the window size is in flux.
|
46 | * jQuery(window).on('resize', _.debounce(calculateLayout, 150));
|
47 | *
|
48 | * // Invoke `sendMail` when clicked, debouncing subsequent calls.
|
49 | * jQuery(element).on('click', _.debounce(sendMail, 300, {
|
50 | * 'leading': true,
|
51 | * 'trailing': false
|
52 | * }));
|
53 | *
|
54 | * // Ensure `batchLog` is invoked once after 1 second of debounced calls.
|
55 | * var debounced = _.debounce(batchLog, 250, { 'maxWait': 1000 });
|
56 | * var source = new EventSource('/stream');
|
57 | * jQuery(source).on('message', debounced);
|
58 | *
|
59 | * // Cancel the trailing debounced invocation.
|
60 | * jQuery(window).on('popstate', debounced.cancel);
|
61 | */
|
62 | function debounce(func, wait, options) {
|
63 | var lastArgs,
|
64 | lastThis,
|
65 | result,
|
66 | timerId,
|
67 | lastCallTime = 0,
|
68 | lastInvokeTime = 0,
|
69 | leading = false,
|
70 | maxWait = false,
|
71 | trailing = true;
|
72 |
|
73 | if (typeof func != 'function') {
|
74 | throw new TypeError(FUNC_ERROR_TEXT);
|
75 | }
|
76 | wait = toNumber(wait) || 0;
|
77 | if (isObject(options)) {
|
78 | leading = !!options.leading;
|
79 | maxWait = 'maxWait' in options && nativeMax(toNumber(options.maxWait) || 0, wait);
|
80 | trailing = 'trailing' in options ? !!options.trailing : trailing;
|
81 | }
|
82 |
|
83 | function invokeFunc(time) {
|
84 | var args = lastArgs,
|
85 | thisArg = lastThis;
|
86 |
|
87 | lastArgs = lastThis = undefined;
|
88 | lastInvokeTime = time;
|
89 | result = func.apply(thisArg, args);
|
90 | return result;
|
91 | }
|
92 |
|
93 | function leadingEdge(time) {
|
94 | // Reset any `maxWait` timer.
|
95 | lastInvokeTime = time;
|
96 | // Start the timer for the trailing edge.
|
97 | timerId = setTimeout(timerExpired, wait);
|
98 | // Invoke the leading edge.
|
99 | return leading ? invokeFunc(time) : result;
|
100 | }
|
101 |
|
102 | function remainingWait(time) {
|
103 | var timeSinceLastCall = time - lastCallTime,
|
104 | timeSinceLastInvoke = time - lastInvokeTime,
|
105 | result = wait - timeSinceLastCall;
|
106 |
|
107 | return maxWait === false ? result : nativeMin(result, maxWait - timeSinceLastInvoke);
|
108 | }
|
109 |
|
110 | function shouldInvoke(time) {
|
111 | var timeSinceLastCall = time - lastCallTime,
|
112 | timeSinceLastInvoke = time - lastInvokeTime;
|
113 |
|
114 | // Either this is the first call, activity has stopped and we're at the
|
115 | // trailing edge, the system time has gone backwards and we're treating
|
116 | // it as the trailing edge, or we've hit the `maxWait` limit.
|
117 | return (!lastCallTime || (timeSinceLastCall >= wait) ||
|
118 | (timeSinceLastCall < 0) || (maxWait !== false && timeSinceLastInvoke >= maxWait));
|
119 | }
|
120 |
|
121 | function timerExpired() {
|
122 | var time = now();
|
123 | if (shouldInvoke(time)) {
|
124 | return trailingEdge(time);
|
125 | }
|
126 | // Restart the timer.
|
127 | timerId = setTimeout(timerExpired, remainingWait(time));
|
128 | }
|
129 |
|
130 | function trailingEdge(time) {
|
131 | clearTimeout(timerId);
|
132 | timerId = undefined;
|
133 |
|
134 | // Only invoke if we have `lastArgs` which means `func` has been
|
135 | // debounced at least once.
|
136 | if (trailing && lastArgs) {
|
137 | return invokeFunc(time);
|
138 | }
|
139 | lastArgs = lastThis = undefined;
|
140 | return result;
|
141 | }
|
142 |
|
143 | function cancel() {
|
144 | if (timerId !== undefined) {
|
145 | clearTimeout(timerId);
|
146 | }
|
147 | lastCallTime = lastInvokeTime = 0;
|
148 | lastArgs = lastThis = timerId = undefined;
|
149 | }
|
150 |
|
151 | function flush() {
|
152 | return timerId === undefined ? result : trailingEdge(now());
|
153 | }
|
154 |
|
155 | function debounced() {
|
156 | var time = now(),
|
157 | isInvoking = shouldInvoke(time);
|
158 |
|
159 | lastArgs = arguments;
|
160 | lastThis = this;
|
161 | lastCallTime = time;
|
162 |
|
163 | if (isInvoking) {
|
164 | if (timerId === undefined) {
|
165 | return leadingEdge(lastCallTime);
|
166 | }
|
167 | // Handle invocations in a tight loop.
|
168 | clearTimeout(timerId);
|
169 | timerId = setTimeout(timerExpired, wait);
|
170 | return invokeFunc(lastCallTime);
|
171 | }
|
172 | return result;
|
173 | }
|
174 | debounced.cancel = cancel;
|
175 | debounced.flush = flush;
|
176 | return debounced;
|
177 | }
|
178 |
|
179 | export default debounce;
|