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