Merge pull request DefinitelyTyped#14025 from JoshuaKGoldberg/complet…

…e-lolex-types

Added lolex 1.5.2 types

lolex/index.d.ts

@@ -1,28 +1,187 @@
-// Type definitions for lolex 1.5.1
+// Type definitions for lolex 1.5
 // Project: https://github.com/sinonjs/lolex
-// Definitions by: Wim Looman <https://github.com/Nemo157>
+// Definitions by: Wim Looman <https://github.com/Nemo157>, Josh Goldberg <https://github.com/joshuakgoldberg>
 // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
 
+/**
+ * Timer object used in node.
+ */
+export interface NodeTimer {
+    /**
+     * Stub method call. Does nothing.
+     */
+    ref(): void;
 
-export interface Clock {
+    /**
+     * Stub method call. Does nothing.
+     */
+    unref(): void;
+}
+
+/**
+ * Timer identifier for clock scheduling.
+ */
+export type TimerId = number | NodeTimer;
+
+/**
+ * Lolex clock for a browser environment.
+ */
+type BrowserClock = LolexClock<number>;
+
+/**
+ * Lolex clock for a Node environment.
+ */
+type NodeClock = LolexClock<NodeTimer> & {
+    /**
+     * Mimicks process.hrtime().
+     * 
+     * @param prevTime   Previous system time to calculate time elapsed.
+     * @returns High resolution real time as [seconds, nanoseconds].
+     */
+    hrtime(prevTime?: [number, number]): [number, number];
+};
+
+/**
+ * Clock object created by lolex.
+ */
+type Clock = BrowserClock | NodeClock;
+
+/**
+ * Names of clock methods that may be faked by install.
+ */
+type FakeMethod = "setTimeout" | "clearTimeout" | "setImmediate" | "clearImmediate" | "setInterval" | "clearInterval" | "Date";
+
+/**
+ * Controls the flow of time.
+ */
+export interface LolexClock<TTimerId extends TimerId> {
+    /**
+     * Current clock time.
+     */
     now: number;
 
-    setTimeout(callback: () => any, timeout: number): number;
-    setInterval(callback: () => any, timeout: number): number;
-    setImmediate(callback: () => any): number;
+    /**
+     * Implements the Date object but using this clock to provide the correct time.
+     */
+    Date: typeof Date;
+
+    /**
+     * Schedules a callback to be fired once timeout milliseconds have ticked by.
+     * 
+     * @param callback   Callback to be fired.
+     * @param timeout   How many ticks to wait to run the callback.
+     * @returns Time identifier for cancellation.
+     */
+    setTimeout(callback: () => any, timeout: number): TTimerId;
+
+    /**
+     * Clears a timer, as long as it was created using setTimeout.
+     * 
+     * @param id   Timer ID or object.
+     */
+    clearTimeout(id: TTimerId): void;
 
-    clearTimeout(id: number): void;
-    clearInterval(id: number): void;
-    clearImmediate(id: number): void;
+    /**
+     * Schedules a callback to be fired every time timeout milliseconds have ticked by.
+     * 
+     * @param callback   Callback to be fired.
+     * @param timeout   How many ticks to wait between callbacks.
+     * @returns Time identifier for cancellation.
+     */
+    setInterval(callback: () => any, timeout: number): TTimerId;
 
-    setSystemTime(now: number): void;
-    setSystemTime(date: Date): void;
+    /**
+     * Clears a timer, as long as it was created using setInterval.
+     * 
+     * @param id   Timer ID or object.
+     */
+    clearInterval(id: TTimerId): void;
 
-    tick(ms: number): void;
+    /**
+     * Schedules the callback to be fired once 0 milliseconds have ticked by.
+     * 
+     * @param callback   Callback to be fired.
+     * @remarks You'll still have to call clock.tick() for the callback to fire.
+     * @remarks If called during a tick the callback won't fire until 1 millisecond has ticked by.
+     */
+    setImmediate(callback: () => any): TTimerId;
+
+    /**
+     * Clears a timer, as long as it was created using setImmediate.
+     * 
+     * @param id   Timer ID or object.
+     */
+    clearImmediate(id: TTimerId): void;
+
+    /**
+     * Advances the clock to the the moment of the first scheduled timer, firing it.
+     */
+    next(): void;
+
+    /**
+     * Advance the clock, firing callbacks if necessary.
+     * 
+     * @param time   How many ticks to advance by.
+     */
+    tick(time: number | string): void;
+
+    /**
+     * Runs all pending timers until there are none remaining.
+     * 
+     * @remarks  If new timers are added while it is executing they will be run as well.
+     */
+    runAll(): void;
+
+    /**
+     * Takes note of the last scheduled timer when it is run, and advances the clock to
+     * that time firing callbacks as necessary.
+     */
+    runToLast(): void;
+
+    /**
+     * Simulates a user changing the system clock.
+     * 
+     * @param now   New system time.
+     * @remarks This affects the current time but it does not in itself cause timers to fire.
+     */
+    setSystemTime(now?: number | Date): void;
+
+    /**
+     * Restores the original methods on the context that was passed to lolex.install,
+     * or the native timers if no context was given.
+     */
     uninstall(): void;
 }
 
-export declare function createClock(now?: number): Clock;
+/**
+ * Creates a clock.
+ * 
+ * @param now   Current time for the clock.
+ * @param loopLimit    Maximum number of timers that will be run when calling runAll()
+ *                     before assuming that we have an infinite loop and throwing an error
+ *                     (by default, 1000).
+ * @type TClock   Type of clock to create.
+ * @remarks The default epoch is 0.
+ */
+export declare function createClock<TClock extends Clock>(now?: number | Date, loopLimit?: number): TClock;
+
+/**
+ * Creates a clock and installs it globally.
+ * 
+ * @param now   Current time for the clock, as with lolex.createClock().
+ * @param toFake   Names of methods that should be faked.
+ * @type TClock   Type of clock to create.
+ * @usage lolex.install(["setTimeout", "clearTimeout"]);
+ */
+export declare function install<TClock extends Clock>(now?: number | Date, toFake?: FakeMethod[]): TClock;
 
-export declare function install(now?: number, toFake?: string[]): Clock;
-export declare function install(context?: any, now?: number, toFake?: string[]): Clock;
+/**
+ * Creates a clock and installs it onto the context object.
+ * 
+ * @param context   Context to install the clock onto.
+ * @param now   Current time for the clock, as with lolex.createClock().
+ * @param toFake   Names of methods that should be faked.
+ * @type TClock   Type of clock to create.
+ * @usage lolex.install(context, ["setTimeout", "clearTimeout"]);
+ */
+export declare function install<TClock extends Clock>(context?: any, now?: number | Date, toFake?: FakeMethod[]): TClock;

lolex/lolex-tests.ts

@@ -1,126 +1,84 @@
-
 import lolex = require("lolex");
 
-function a() {
-	var clock = lolex.createClock();
-
-	clock.setTimeout(function () {
-		console.log("The poblano is a mild chili pepper originating in the state of Puebla, Mexico.");
-	}, 15);
-
-	// ...
-
-	clock.tick(15);
-}
-
-function b() {
-	var clock = lolex.install(window);
-
-	window.setTimeout(() => {}, 15); // Schedules with clock.setTimeout
-
-	clock.uninstall();
-
-	// window.setTimeout is restored to the native implementation
-}
-
-function c() {
-	var clock = lolex.install();
-
-	// Equivalent to
-	// var clock = lolex.install(typeof global !== "undefined" ? global : window);
-}
-
-var clock: lolex.Clock;
-
-/**
- * var clock = lolex.createClock([now])
- */
-
-clock = lolex.createClock();
-clock = lolex.createClock(Date.now());
-
-
-/**
- * var clock = lolex.install([context[, now[, toFake]]])
- */
-
-clock = lolex.install();
-clock = lolex.install(window);
-clock = lolex.install(window, Date.now());
-clock = lolex.install(window, Date.now(), ['setTimeout', 'clearTimeout']);
-
-
-/**
- * var clock = lolex.install([now[, toFake]])
- */
-
-clock = lolex.install(Date.now());
-clock = lolex.install(Date.now(), ['setTimeout', 'clearTimeout']);
-
-/**
- * clock.now
- */
-var n: number = clock.now;
-
-
-var id: number;
-/**
- * var id = clock.setTimeout(callback, timeout)
- */
-
-id = clock.setTimeout(() => {}, 1000);
-
-
-/**
- * clock.clearTimeout(id)
- */
+let browserClock: lolex.BrowserClock = lolex.createClock() as lolex.BrowserClock;
+let nodeClock: lolex.NodeClock = lolex.createClock() as lolex.NodeClock;
 
-clock.clearTimeout(id);
+browserClock = lolex.createClock<lolex.BrowserClock>();
+nodeClock = lolex.createClock<lolex.NodeClock>();
 
+lolex.createClock<lolex.BrowserClock>(7);
+lolex.createClock<lolex.BrowserClock>(new Date());
+lolex.createClock<lolex.BrowserClock>(7, 9001);
+lolex.createClock<lolex.BrowserClock>(new Date(), 9001);
 
-/**
- * var id = clock.setInterval(callback, timeout)
- */
+lolex.createClock<lolex.NodeClock>(7);
+lolex.createClock<lolex.NodeClock>(new Date());
+lolex.createClock<lolex.NodeClock>(7, 9001);
+lolex.createClock<lolex.NodeClock>(new Date(), 9001);
 
-id = clock.setInterval(() => {}, 1000);
+lolex.install<lolex.BrowserClock>(7);
+lolex.install<lolex.BrowserClock>(new Date());
+lolex.install<lolex.BrowserClock>(7, ["setTimeout"]);
+lolex.install<lolex.BrowserClock>(new Date(), ["setTimeout"]);
 
+lolex.install<lolex.NodeClock>(7);
+lolex.install<lolex.NodeClock>(new Date());
+lolex.install<lolex.NodeClock>(7, ["setTimeout"]);
+lolex.install<lolex.NodeClock>(new Date(), ["setTimeout"]);
 
-/**
- * clock.clearInterval(id)
- */
+lolex.install<lolex.BrowserClock>({}, 7);
+lolex.install<lolex.BrowserClock>({}, new Date());
+lolex.install<lolex.BrowserClock>({}, 7, ["setTimeout"]);
+lolex.install<lolex.BrowserClock>({}, new Date(), ["setTimeout"]);
 
-clock.clearInterval(id);
+lolex.install<lolex.NodeClock>({}, 7);
+lolex.install<lolex.NodeClock>({}, new Date());
+lolex.install<lolex.NodeClock>({}, 7, ["setTimeout"]);
+lolex.install<lolex.NodeClock>({}, new Date(), ["setTimeout"]);
 
+const browserNow: number = browserClock.now;
+const browserDate: Date = new browserClock.Date();
 
-/**
- * var id = clock.setImmediate(callback)
- */
+const nodeNow: number = nodeClock.now;
+const nodeDate: Date = new nodeClock.Date();
 
-id = clock.setImmediate(() => {});
+const browserTimeout: number = browserClock.setTimeout(() => {}, 7);
+const browserInterval: number = browserClock.setInterval(() => {}, 7);
+const browserImmediate: number = browserClock.setImmediate(() => {});
+const nodeTimeout: lolex.NodeTimer = nodeClock.setTimeout(() => {}, 7);
+const nodeInterval: lolex.NodeTimer = nodeClock.setInterval(() => {}, 7);
+const nodeImmediate: lolex.NodeTimer = nodeClock.setImmediate(() => {});
 
+browserClock.clearTimeout(browserTimeout);
+browserClock.clearInterval(browserInterval);
+browserClock.clearImmediate(browserImmediate);
 
-/**
- * clock.clearImmediate(id)
- */
+nodeClock.clearTimeout(nodeTimeout);
+nodeClock.clearInterval(nodeInterval);
+nodeClock.clearImmediate(nodeImmediate);
 
-clock.clearImmediate(id);
+browserClock.tick(7);
+browserClock.tick("08");
 
-/**
- * clock.setSystemTime
- */
-clock.setSystemTime(0);
-clock.setSystemTime(new Date());
+nodeClock.tick(7);
+nodeClock.tick("08");
 
-/**
- * clock.tick(time)
- */
+browserClock.next();
+nodeClock.next();
 
-clock.tick(1000);
+browserClock.runAll();
+nodeClock.runAll();
 
+browserClock.runToLast();
+nodeClock.runToLast();
 
-/**
- * clock.uninstall()
- */
+browserClock.setSystemTime();
+browserClock.setSystemTime(7);
+browserClock.setSystemTime(new Date());
 
-clock.uninstall();
+nodeClock.setSystemTime();
+nodeClock.setSystemTime(7);
+nodeClock.setSystemTime(new Date());
 
+browserClock.uninstall();
+nodeClock.uninstall();