From 61ee030edd12a3a30459d0cdc1d9128fdf714c5c Mon Sep 17 00:00:00 2001
From: Brad Murray <bradtgmurray@gmail.com>
Date: Fri, 15 Nov 2019 15:02:58 -0500
Subject: [PATCH] Update lolex types for new Async methods (#40282)

---
 types/lolex/index.d.ts     | 76 ++++++++++++++++++++++++++++++--------
 types/lolex/lolex-tests.ts | 15 ++++++++
 2 files changed, 76 insertions(+), 15 deletions(-)

diff --git a/types/lolex/index.d.ts b/types/lolex/index.d.ts
index 703b0b9809..7a5f9dd933 100644
--- a/types/lolex/index.d.ts
+++ b/types/lolex/index.d.ts
@@ -1,4 +1,4 @@
-// Type definitions for lolex 3.1
+// Type definitions for lolex 5.1
 // Project: https://github.com/sinonjs/lolex
 // Definitions by: Wim Looman <https://github.com/Nemo157>
 //                 Josh Goldberg <https://github.com/joshuakgoldberg>
@@ -10,7 +10,20 @@
 /**
  * Names of clock methods that may be faked by install.
  */
-type FakeMethod = "setTimeout" | "clearTimeout" | "setImmediate" | "clearImmediate" | "setInterval" | "clearInterval" | "Date" | "nextTick" | "hrtime" | "requestAnimationFrame" | "cancelAnimationFrame" | "requestIdleCallback" | "cancelIdleCallback";
+type FakeMethod =
+    | 'setTimeout'
+    | 'clearTimeout'
+    | 'setImmediate'
+    | 'clearImmediate'
+    | 'setInterval'
+    | 'clearInterval'
+    | 'Date'
+    | 'nextTick'
+    | 'hrtime'
+    | 'requestAnimationFrame'
+    | 'cancelAnimationFrame'
+    | 'requestIdleCallback'
+    | 'cancelIdleCallback';
 
 /**
  * Global methods avaliable to every clock and also as standalone methods (inside `timers` global object).
@@ -143,18 +156,25 @@ export interface LolexClock<TTimerId extends TimerId> extends GlobalTimers<TTime
      */
     cancelIdleCallback: (id: TTimerId) => void;
 
-	/**
-	 * Get the number of waiting timers.
-	 *
-	 * @returns number of waiting timers.
-	 */
-	countTimers: () => number;
+    /**
+     * Get the number of waiting timers.
+     *
+     * @returns number of waiting timers.
+     */
+    countTimers: () => number;
 
     /**
      * Advances the clock to the the moment of the first scheduled timer, firing it.
      */
     next: () => void;
 
+    /**
+     * Advances the clock to the the moment of the first scheduled timer, firing it.
+     *
+     * Also breaks the event loop, allowing any scheduled promise callbacks to execute _before_ running the timers.
+     */
+    nextAsync: () => Promise<void>;
+
     /**
      * Advance the clock, firing callbacks if necessary.
      *
@@ -162,6 +182,15 @@ export interface LolexClock<TTimerId extends TimerId> extends GlobalTimers<TTime
      */
     tick: (time: number | string) => void;
 
+    /**
+     * Advance the clock, firing callbacks if necessary.
+     *
+     * Also breaks the event loop, allowing any scheduled promise callbacks to execute _before_ running the timers.
+     *
+     * @param time   How many ticks to advance by.
+     */
+    tickAsync: (time: number | string) => Promise<void>;
+
     /**
      * Removes all timers and tick without firing them and restore now to its original value.
      */
@@ -174,10 +203,19 @@ export interface LolexClock<TTimerId extends TimerId> extends GlobalTimers<TTime
      */
     runAll: () => void;
 
-	/**
-	 * Advanced the clock to the next animation frame while firing all scheduled callbacks.
-	 */
-	runToFrame: () => void;
+    /**
+     * Runs all pending timers until there are none remaining.
+     *
+     * Also breaks the event loop, allowing any scheduled promise callbacks to execute _before_ running the timers.
+     *
+     * @remarks  If new timers are added while it is executing they will be run as well.
+     */
+    runAllAsync: () => Promise<void>;
+
+    /**
+     * Advanced the clock to the next animation frame while firing all scheduled callbacks.
+     */
+    runToFrame: () => void;
 
     /**
      * Takes note of the last scheduled timer when it is run, and advances the clock to
@@ -185,6 +223,14 @@ export interface LolexClock<TTimerId extends TimerId> extends GlobalTimers<TTime
      */
     runToLast: () => void;
 
+    /**
+     * Takes note of the last scheduled timer when it is run, and advances the clock to
+     * that time firing callbacks as necessary.
+     *
+     * Also breaks the event loop, allowing any scheduled promise callbacks to execute _before_ running the timers.
+     */
+    runToLastAsync: () => Promise<void>;
+
     /**
      * Simulates a user changing the system clock.
      *
@@ -203,7 +249,7 @@ type BrowserClock = LolexClock<number> & {
      */
     performance: {
         now: () => number;
-    }
+    };
 };
 
 /**
@@ -229,8 +275,8 @@ type NodeClock = LolexClock<NodeTimer> & {
     nextTick: (callback: () => void) => void;
 
     /**
-	 * Run all pending microtasks scheduled with nextTick.
-	 */
+     * Run all pending microtasks scheduled with nextTick.
+     */
     runMicrotasks: () => void;
 };
 
diff --git a/types/lolex/lolex-tests.ts b/types/lolex/lolex-tests.ts
index f808283e5b..9ea54d4b8e 100644
--- a/types/lolex/lolex-tests.ts
+++ b/types/lolex/lolex-tests.ts
@@ -91,15 +91,27 @@ browserClock.tick("08");
 nodeClock.tick(7);
 nodeClock.tick("08:03");
 
+browserClock.tickAsync(7).then(() => {});
+browserClock.tickAsync("08").then(() => {});
+
+nodeClock.tickAsync(7).then(() => {});
+nodeClock.tickAsync("08:03").then(() => {});
+
 browserClock.next();
 nodeClock.next();
 
+browserClock.nextAsync().then(() => {});
+nodeClock.nextAsync().then(() => {});
+
 browserClock.reset();
 nodeClock.reset();
 
 browserClock.runAll();
 nodeClock.runAll();
 
+browserClock.runAllAsync().then(() => {});
+nodeClock.runAllAsync().then(() => {});
+
 nodeClock.runMicrotasks();
 
 browserClock.runToFrame();
@@ -108,6 +120,9 @@ nodeClock.runToFrame();
 browserClock.runToLast();
 nodeClock.runToLast();
 
+browserClock.runToLastAsync().then(() => {});
+nodeClock.runToLastAsync().then(() => {});
+
 browserClock.setSystemTime();
 browserClock.setSystemTime(7);
 browserClock.setSystemTime(new Date());