1 | // Type definitions for lolex 5.1
|
2 | // Project: https://github.com/sinonjs/lolex
|
3 | // Definitions by: Wim Looman <https://github.com/Nemo157>
|
4 | // Rogier Schouten <https://github.com/rogierschouten>
|
5 | // Yishai Zehavi <https://github.com/zyishai>
|
6 | // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
|
7 | // TypeScript Version: 2.3
|
8 |
|
9 | /**
|
10 | * Names of clock methods that may be faked by install.
|
11 | */
|
12 | type FakeMethod =
|
13 | | 'setTimeout'
|
14 | | 'clearTimeout'
|
15 | | 'setImmediate'
|
16 | | 'clearImmediate'
|
17 | | 'setInterval'
|
18 | | 'clearInterval'
|
19 | | 'Date'
|
20 | | 'nextTick'
|
21 | | 'hrtime'
|
22 | | 'requestAnimationFrame'
|
23 | | 'cancelAnimationFrame'
|
24 | | 'requestIdleCallback'
|
25 | | 'cancelIdleCallback';
|
26 |
|
27 | /**
|
28 | * Global methods avaliable to every clock and also as standalone methods (inside `timers` global object).
|
29 | */
|
30 | export interface GlobalTimers<TTimerId extends TimerId> {
|
31 | /**
|
32 | * Schedules a callback to be fired once timeout milliseconds have ticked by.
|
33 | *
|
34 | * @param callback Callback to be fired.
|
35 | * @param timeout How many ticks to wait to run the callback.
|
36 | * @param args Any extra arguments to pass to the callback.
|
37 | * @returns Time identifier for cancellation.
|
38 | */
|
39 | setTimeout: (callback: () => void, timeout: number, ...args: any[]) => TTimerId;
|
40 |
|
41 | /**
|
42 | * Clears a timer, as long as it was created using setTimeout.
|
43 | *
|
44 | * @param id Timer ID or object.
|
45 | */
|
46 | clearTimeout: (id: TimerId) => void;
|
47 |
|
48 | /**
|
49 | * Schedules a callback to be fired every time timeout milliseconds have ticked by.
|
50 | *
|
51 | * @param callback Callback to be fired.
|
52 | * @param timeout How many ticks to wait between callbacks.
|
53 | * @param args Any extra arguments to pass to the callback.
|
54 | * @returns Time identifier for cancellation.
|
55 | */
|
56 | setInterval: (callback: () => void, timeout: number, ...args: any[]) => TTimerId;
|
57 |
|
58 | /**
|
59 | * Clears a timer, as long as it was created using setInterval.
|
60 | *
|
61 | * @param id Timer ID or object.
|
62 | */
|
63 | clearInterval: (id: TTimerId) => void;
|
64 |
|
65 | /**
|
66 | * Schedules the callback to be fired once 0 milliseconds have ticked by.
|
67 | *
|
68 | * @param callback Callback to be fired.
|
69 | * @remarks You'll still have to call clock.tick() for the callback to fire.
|
70 | * @remarks If called during a tick the callback won't fire until 1 millisecond has ticked by.
|
71 | */
|
72 | setImmediate: (callback: () => void) => TTimerId;
|
73 |
|
74 | /**
|
75 | * Clears a timer, as long as it was created using setImmediate.
|
76 | *
|
77 | * @param id Timer ID or object.
|
78 | */
|
79 | clearImmediate: (id: TTimerId) => void;
|
80 |
|
81 | /**
|
82 | * Implements the Date object but using this clock to provide the correct time.
|
83 | */
|
84 | Date: typeof Date;
|
85 | }
|
86 |
|
87 | /**
|
88 | * Timer object used in node.
|
89 | */
|
90 | export interface NodeTimer {
|
91 | /**
|
92 | * Stub method call. Does nothing.
|
93 | */
|
94 | ref(): void;
|
95 |
|
96 | /**
|
97 | * Stub method call. Does nothing.
|
98 | */
|
99 | unref(): void;
|
100 | }
|
101 |
|
102 | /**
|
103 | * Timer identifier for clock scheduling.
|
104 | */
|
105 | export type TimerId = number | NodeTimer;
|
106 |
|
107 | /**
|
108 | * Controls the flow of time.
|
109 | */
|
110 | export interface LolexClock<TTimerId extends TimerId> extends GlobalTimers<TTimerId> {
|
111 | /**
|
112 | * Current clock time.
|
113 | */
|
114 | now: number;
|
115 |
|
116 | /**
|
117 | * Don't know what this prop is for, but it was included in the clocks that `createClock` or
|
118 | * `install` return (it is never used in the code, for now).
|
119 | */
|
120 | timeouts: {};
|
121 |
|
122 | /**
|
123 | * Maximum number of timers that will be run when calling runAll().
|
124 | */
|
125 | loopLimit: number;
|
126 |
|
127 | /**
|
128 | * Schedule callback to run in the next animation frame.
|
129 | *
|
130 | * @param callback Callback to be fired.
|
131 | * @returns Request id.
|
132 | */
|
133 | requestAnimationFrame: (callback: (time: number) => void) => TTimerId;
|
134 |
|
135 | /**
|
136 | * Cancel animation frame request.
|
137 | *
|
138 | * @param id The id returned from requestAnimationFrame method.
|
139 | */
|
140 | cancelAnimationFrame: (id: TTimerId) => void;
|
141 |
|
142 | /**
|
143 | * Queues the callback to be fired during idle periods to perform background and low priority work on the main event loop.
|
144 | *
|
145 | * @param callback Callback to be fired.
|
146 | * @param timeout The maximum number of ticks before the callback must be fired.
|
147 | * @remarks Callbacks which have a timeout option will be fired no later than time in milliseconds.
|
148 | */
|
149 | requestIdleCallback: (callback: () => void, timeout?: number) => TTimerId;
|
150 |
|
151 | /**
|
152 | * Clears a timer, as long as it was created using requestIdleCallback.
|
153 | *
|
154 | * @param id Timer ID or object.
|
155 | */
|
156 | cancelIdleCallback: (id: TTimerId) => void;
|
157 |
|
158 | /**
|
159 | * Get the number of waiting timers.
|
160 | *
|
161 | * @returns number of waiting timers.
|
162 | */
|
163 | countTimers: () => number;
|
164 |
|
165 | /**
|
166 | * Advances the clock to the the moment of the first scheduled timer, firing it.
|
167 | */
|
168 | next: () => void;
|
169 |
|
170 | /**
|
171 | * Advances the clock to the the moment of the first scheduled timer, firing it.
|
172 | *
|
173 | * Also breaks the event loop, allowing any scheduled promise callbacks to execute _before_ running the timers.
|
174 | */
|
175 | nextAsync: () => Promise<void>;
|
176 |
|
177 | /**
|
178 | * Advance the clock, firing callbacks if necessary.
|
179 | *
|
180 | * @param time How many ticks to advance by.
|
181 | */
|
182 | tick: (time: number | string) => void;
|
183 |
|
184 | /**
|
185 | * Advance the clock, firing callbacks if necessary.
|
186 | *
|
187 | * Also breaks the event loop, allowing any scheduled promise callbacks to execute _before_ running the timers.
|
188 | *
|
189 | * @param time How many ticks to advance by.
|
190 | */
|
191 | tickAsync: (time: number | string) => Promise<void>;
|
192 |
|
193 | /**
|
194 | * Removes all timers and tick without firing them and restore now to its original value.
|
195 | */
|
196 | reset: () => void;
|
197 |
|
198 | /**
|
199 | * Runs all pending timers until there are none remaining.
|
200 | *
|
201 | * @remarks If new timers are added while it is executing they will be run as well.
|
202 | */
|
203 | runAll: () => void;
|
204 |
|
205 | /**
|
206 | * Runs all pending timers until there are none remaining.
|
207 | *
|
208 | * Also breaks the event loop, allowing any scheduled promise callbacks to execute _before_ running the timers.
|
209 | *
|
210 | * @remarks If new timers are added while it is executing they will be run as well.
|
211 | */
|
212 | runAllAsync: () => Promise<void>;
|
213 |
|
214 | /**
|
215 | * Advanced the clock to the next animation frame while firing all scheduled callbacks.
|
216 | */
|
217 | runToFrame: () => void;
|
218 |
|
219 | /**
|
220 | * Takes note of the last scheduled timer when it is run, and advances the clock to
|
221 | * that time firing callbacks as necessary.
|
222 | */
|
223 | runToLast: () => void;
|
224 |
|
225 | /**
|
226 | * Takes note of the last scheduled timer when it is run, and advances the clock to
|
227 | * that time firing callbacks as necessary.
|
228 | *
|
229 | * Also breaks the event loop, allowing any scheduled promise callbacks to execute _before_ running the timers.
|
230 | */
|
231 | runToLastAsync: () => Promise<void>;
|
232 |
|
233 | /**
|
234 | * Simulates a user changing the system clock.
|
235 | *
|
236 | * @param now New system time.
|
237 | * @remarks This affects the current time but it does not in itself cause timers to fire.
|
238 | */
|
239 | setSystemTime: (now?: number | Date) => void;
|
240 | }
|
241 |
|
242 | /**
|
243 | * Lolex clock for a browser environment.
|
244 | */
|
245 | type BrowserClock = LolexClock<number> & {
|
246 | /**
|
247 | * Mimics performance.now().
|
248 | */
|
249 | performance: {
|
250 | now: () => number;
|
251 | };
|
252 | };
|
253 |
|
254 | /**
|
255 | * Lolex clock for a Node environment.
|
256 | */
|
257 | type NodeClock = LolexClock<NodeTimer> & {
|
258 | /**
|
259 | * Mimicks process.hrtime().
|
260 | *
|
261 | * @param prevTime Previous system time to calculate time elapsed.
|
262 | * @returns High resolution real time as [seconds, nanoseconds].
|
263 | */
|
264 | hrtime(prevTime?: [number, number]): [number, number];
|
265 |
|
266 | /**
|
267 | * Mimics process.nextTick() explicitly dropping additional arguments.
|
268 | */
|
269 | queueMicrotask: (callback: () => void) => void;
|
270 |
|
271 | /**
|
272 | * Simulates process.nextTick().
|
273 | */
|
274 | nextTick: (callback: () => void) => void;
|
275 |
|
276 | /**
|
277 | * Run all pending microtasks scheduled with nextTick.
|
278 | */
|
279 | runMicrotasks: () => void;
|
280 | };
|
281 |
|
282 | /**
|
283 | * Clock object created by lolex.
|
284 | */
|
285 | type Clock = BrowserClock | NodeClock;
|
286 |
|
287 | /**
|
288 | * Additional methods that installed clock have.
|
289 | */
|
290 | type InstalledMethods = {
|
291 | /**
|
292 | * Restores the original methods on the context that was passed to lolex.install,
|
293 | * or the native timers if no context was given.
|
294 | */
|
295 | uninstall: () => void;
|
296 |
|
297 | methods: FakeMethod[];
|
298 | };
|
299 |
|
300 | /**
|
301 | * Clock object created by calling `install();`.
|
302 | *
|
303 | * @typeparam {TClock} type of base clock (e.g BrowserClock).
|
304 | */
|
305 | type InstalledClock<TClock extends Clock = Clock> = TClock & InstalledMethods;
|
306 |
|
307 | /**
|
308 | * Creates a clock.
|
309 | *
|
310 | * @param now Current time for the clock.
|
311 | * @param loopLimit Maximum number of timers that will be run when calling runAll()
|
312 | * before assuming that we have an infinite loop and throwing an error
|
313 | * (by default, 1000).
|
314 | * @typeparam {TClock} Type of clock to create.
|
315 | * @remarks The default epoch is 0.
|
316 | */
|
317 | export declare function createClock<TClock extends Clock = Clock>(now?: number | Date, loopLimit?: number): TClock;
|
318 |
|
319 | export interface LolexInstallOpts {
|
320 | /**
|
321 | * Installs lolex onto the specified target context (default: global)
|
322 | */
|
323 | target?: any;
|
324 |
|
325 | /**
|
326 | * Installs lolex with the specified unix epoch (default: 0)
|
327 | */
|
328 | now?: number | Date | undefined;
|
329 |
|
330 | /**
|
331 | * An array with explicit function names to hijack. When not set, lolex will automatically fake all methods except nextTick
|
332 | * e.g., lolex.install({ toFake: ["setTimeout", "nextTick"]}) will fake only setTimeout and nextTick
|
333 | */
|
334 | toFake?: FakeMethod[] | undefined;
|
335 |
|
336 | /**
|
337 | * The maximum number of timers that will be run when calling runAll() (default: 1000)
|
338 | */
|
339 | loopLimit?: number | undefined;
|
340 |
|
341 | /**
|
342 | * Tells lolex to increment mocked time automatically based on the real system time shift (e.g. the mocked time will be incremented by
|
343 | * 20ms for every 20ms change in the real system time) (default: false)
|
344 | */
|
345 | shouldAdvanceTime?: boolean | undefined;
|
346 |
|
347 | /**
|
348 | * Relevant only when using with shouldAdvanceTime: true. increment mocked time by advanceTimeDelta ms every advanceTimeDelta ms change
|
349 | * in the real system time (default: 20)
|
350 | */
|
351 | advanceTimeDelta?: number | undefined;
|
352 | }
|
353 |
|
354 | /**
|
355 | * Creates a clock and installs it globally.
|
356 | *
|
357 | * @param now Current time for the clock, as with lolex.createClock().
|
358 | * @param toFake Names of methods that should be faked.
|
359 | * @typeparam {TClock} Type of clock to create.
|
360 | */
|
361 | export declare function install<TClock extends Clock = Clock>(opts?: LolexInstallOpts): InstalledClock<TClock>;
|
362 |
|
363 | export interface LolexWithContext {
|
364 | timers: GlobalTimers<TimerId>;
|
365 | createClock: <TClock extends Clock = Clock>(now?: number | Date, loopLimit?: number) => TClock;
|
366 | install: <TClock extends Clock = Clock>(opts?: LolexInstallOpts) => InstalledClock<TClock>;
|
367 | withGlobal: (global: Object) => LolexWithContext;
|
368 | }
|
369 |
|
370 | /**
|
371 | * Apply new context to lolex.
|
372 | *
|
373 | * @param global New context to apply like `window` (in browsers) or `global` (in node).
|
374 | */
|
375 | export declare function withGlobal(global: Object): LolexWithContext;
|
376 |
|
377 | export declare const timers: GlobalTimers<TimerId>;
|