Stopwatch refactoring

src/utils/diagnostics/stopwatch.ts

@@ -1,66 +1,140 @@
+/**
+ * A callback type for when a {@link Stopwatch} is started.
+ */
 interface StartCallback {
-    (currentDate: Date, stopwatch: Stopwatch): void;
+    /**
+     * @param date - The date when the {@link Stopwatch} was started.
+     * @param stopwatch - The {@link Stopwatch} instance.
+     */
+    (date: Date, stopwatch: Stopwatch): void;
 }
 
+/**
+ * A callback type for when a {@link Stopwatch} is stopped.
+ */
 interface StopCallback {
-    (elapsedMilliseconds: number, currentDate: Date, stopwatch: Stopwatch): void;
+    /**
+     * @param elapsedTime - The elapsed time in milliseconds.
+     * @param date - The date when the {@link Stopwatch} was stopped.
+     * @param stopwatch - The {@link Stopwatch} instance.
+     */
+    (elapsedTime: number, date: Date, stopwatch: Stopwatch): void;
 }
 
-export default class Stopwatch {
-    #initialDate = 0;
-    #isRunning = false;
-    #elapsedMilliseconds = 0;
-    #onStart: StartCallback = null;
-    #onStop: StopCallback = null;
+/**
+ * A class for measuring elapsed time.
+ */
+export class Stopwatch {
+    /**
+     * Indicates whether the stopwatch is currently running.
+     */
+    private _isRunning: boolean;
 
-    public constructor(onStart?: StartCallback, onStop?: StopCallback) {
-        this.#onStart = onStart;
-        this.#onStop = onStop;
+    /**
+     * The time when stopwatch was started.
+     */
+    private _startTime: number;
+
+    /**
+     * The elapsed time in milliseconds since the stopwatch was started.
+     */
+    private _elapsedTime: number;
+
+    /**
+     * A callback function that will be called when the stopwatch is started.
+     */
+    private readonly _onStart?: StartCallback;
+
+    /**
+     * A callback function that will be called when the stopwatch is stopped.
+     */
+    private readonly _onStop?: StopCallback;
+
+    /**
+     * Creates a new instance of {@link Stopwatch}.
+     *
+     * @param onStart - A callback function that will be called when the stopwatch is started.
+     * @param onStop - A callback function that will be called when the stopwatch is stopped.
+     */
+    constructor(onStart?: StartCallback, onStop?: StopCallback) {
+        this._isRunning = false;
+        this._startTime = 0;
+        this._elapsedTime = 0;
+        this._onStart = onStart;
+        this._onStop = onStop;
     }
 
-    public get elapsedMilliseconds(): number {
-        return this.#isRunning
-            ? (this.#elapsedMilliseconds + new Date().valueOf() - this.#initialDate)
-            : this.#elapsedMilliseconds;
+    /**
+     * Gets the elapsed time in milliseconds since the stopwatch was started.
+     */
+    get elapsedMilliseconds(): number {
+        return this._elapsedTime + (this._isRunning ? Date.now() - this._startTime : 0);
     }
 
-    public get isRunning(): boolean {
-        return this.#isRunning;
+    /**
+     * Gets a value indicating whether the stopwatch is currently running.
+     */
+    get isRunning(): boolean {
+        return this._isRunning;
     }
 
-    public start(): boolean {
-        if (!this.#isRunning) {
-            const currentDate = new Date();
-            this.#initialDate = currentDate.valueOf();
-            this.#isRunning = true;
-            this.#onStart?.(currentDate, this);
-            return true;
+    /**
+     * Starts the stopwatch.
+     *
+     * @returns `true` if the stopwatch was successfully started; `false` if it was already running.
+     */
+    start(): boolean {
+        if (this._isRunning) {
+            return false;
         }
-        return false;
+
+        this._startTime = Date.now();
+        this._isRunning = true;
+        this._onStart?.(new Date(), this);
+        return true;
     }
 
-    public stop(): boolean {
-        if (this.#isRunning) {
-            const currentDate = new Date();
-            this.#elapsedMilliseconds += currentDate.valueOf() - this.#initialDate;
-            this.#isRunning = false;
-            this.#onStop?.(this.#elapsedMilliseconds, currentDate, this);
-            return true;
+    /**
+     * Stops the stopwatch.
+     *
+     * @returns `true` if the stopwatch was successfully stopped; `false` if it was already stopped.
+     */
+    stop(): boolean {
+        if (!this._isRunning) {
+            return false;
         }
-        return false;
+
+        this._elapsedTime += Date.now() - this._startTime;
+        this._isRunning = false;
+        this._onStop?.(this._elapsedTime, new Date(), this);
+        return true;
     }
 
-    public reset(): void {
+    /**
+     * Resets the stopwatch.
+     */
+    reset(): void {
         this.stop();
-        this.#elapsedMilliseconds = 0;
+        this._elapsedTime = 0;
     }
 
-    public restart(): void {
+    /**
+     * Restarts the stopwatch.
+     */
+    restart(): void {
         this.reset();
         this.start();
     }
 
-    public static startNew(onStart?: StartCallback, onStop?: StopCallback): Stopwatch {
+    /**
+     * Creates a new instance of {@link Stopwatch} and starts it.
+     *
+     * @param onStart - A callback function that will be called when the stopwatch is started.
+     * @param onStop - A callback function that will be called when the stopwatch is stopped.
+     *
+     * @returns The newly created and started stopwatch.
+     */
+    static startNew(onStart?: StartCallback, onStop?: StopCallback): Stopwatch {
         const stopwatch = new Stopwatch(onStart, onStop);
         stopwatch.start();
         return stopwatch;

tests/unit/utils/diagnostics/stopwatch.spec.ts

@@ -0,0 +1,179 @@
+import { Stopwatch } from "@/utils/diagnostics/stopwatch";
+
+describe("Stopwatch", () => {
+    beforeEach(() => {
+        jest.useFakeTimers();
+        jest.setSystemTime(0);
+    });
+
+    afterEach(() => {
+        jest.useRealTimers();
+    });
+
+    describe("constructor", () => {
+        test("initializes with default values", () => {
+            const stopwatch = new Stopwatch();
+
+            expect(stopwatch.isRunning).toBe(false);
+            expect(stopwatch.elapsedMilliseconds).toBe(0);
+        });
+    });
+
+    describe("start", () => {
+        test("starts stopwatch", () => {
+            const onStart = jest.fn();
+            const onStop = jest.fn();
+            const stopwatch = new Stopwatch(onStart, onStop);
+
+            expect(stopwatch.start()).toBe(true);
+            expect(stopwatch.isRunning).toBe(true);
+            expect(onStart).toHaveBeenCalledTimes(1);
+            expect(onStart).toHaveBeenCalledWith(new Date(0), stopwatch);
+            expect(onStop).not.toHaveBeenCalled();
+        });
+
+        test("doesn't start if stopwatch is already running", () => {
+            const onStart = jest.fn();
+            const stopwatch = Stopwatch.startNew(onStart);
+
+            expect(stopwatch.start()).toBe(false);
+            expect(onStart).toHaveBeenCalledTimes(1);
+        });
+    });
+
+    describe("stop", () => {
+        test("stops stopwatch", () => {
+            const onStart = jest.fn();
+            const onStop = jest.fn();
+            const stopwatch = Stopwatch.startNew(onStart, onStop);
+
+            jest.advanceTimersByTime(1000);
+
+            expect(stopwatch.stop()).toBe(true);
+            expect(stopwatch.isRunning).toBe(false);
+            expect(onStart).toHaveBeenCalledTimes(1);
+            expect(onStart).toHaveBeenCalledWith(new Date(0), stopwatch);
+            expect(onStop).toHaveBeenCalledTimes(1);
+            expect(onStop).toHaveBeenCalledWith(1000, new Date(1000), stopwatch);
+        });
+
+        test("doesn't stop if stopwatch is already stopped", () => {
+            const onStop = jest.fn();
+            const stopwatch = new Stopwatch(undefined, onStop);
+
+            expect(stopwatch.stop()).toBe(false);
+            expect(onStop).not.toBeCalled();
+        });
+    });
+
+    describe("elapsedMilliseconds", () => {
+        test("measures elapsed time while stopwatch is running", () => {
+            const stopwatch = Stopwatch.startNew();
+
+            expect(stopwatch.elapsedMilliseconds).toBe(0);
+
+            jest.advanceTimersByTime(1000);
+            expect(stopwatch.elapsedMilliseconds).toBe(1000);
+
+            jest.advanceTimersByTime(1000);
+            expect(stopwatch.elapsedMilliseconds).toBe(2000);
+        });
+
+        test("measures elapsed time correctly when stopwatch is stopped", () => {
+            const stopwatch = Stopwatch.startNew();
+
+            expect(stopwatch.elapsedMilliseconds).toBe(0);
+
+            jest.advanceTimersByTime(1000);
+            expect(stopwatch.elapsedMilliseconds).toBe(1000);
+
+            jest.advanceTimersByTime(1000);
+            expect(stopwatch.elapsedMilliseconds).toBe(2000);
+
+            stopwatch.stop();
+            jest.advanceTimersByTime(1000);
+            expect(stopwatch.elapsedMilliseconds).toBe(2000);
+        });
+
+        test("returns 0 if the stopwatch was never started", () => {
+            const stopwatch = new Stopwatch();
+
+            expect(stopwatch.elapsedMilliseconds).toBe(0);
+        });
+    });
+
+    describe("reset", () => {
+        test("resets stopwatch correctly while it's running", () => {
+            const stopwatch = Stopwatch.startNew();
+
+            jest.advanceTimersByTime(1000);
+            stopwatch.reset();
+
+            expect(stopwatch.elapsedMilliseconds).toBe(0);
+            expect(stopwatch.isRunning).toBe(false);
+        });
+
+        test("resets stopwatch correctly when it's stopped", () => {
+            const stopwatch = Stopwatch.startNew();
+
+            jest.advanceTimersByTime(1000);
+            stopwatch.stop();
+            stopwatch.reset();
+
+            expect(stopwatch.elapsedMilliseconds).toBe(0);
+            expect(stopwatch.isRunning).toBe(false);
+        });
+
+        test("does nothing if the stopwatch was never started", () => {
+            const stopwatch = new Stopwatch();
+            stopwatch.reset();
+
+            expect(stopwatch.elapsedMilliseconds).toBe(0);
+            expect(stopwatch.isRunning).toBe(false);
+        });
+    });
+
+    describe("restart", () => {
+        test("restarts stopwatch correctly while it's running", () => {
+            const stopwatch = Stopwatch.startNew();
+
+            jest.advanceTimersByTime(1000);
+            stopwatch.restart();
+
+            expect(stopwatch.elapsedMilliseconds).toBe(0);
+            expect(stopwatch.isRunning).toBe(true);
+        });
+
+        test("restarts stopwatch correctly when it's stopped", () => {
+            const stopwatch = Stopwatch.startNew();
+
+            jest.advanceTimersByTime(1000);
+            stopwatch.stop();
+            stopwatch.restart();
+
+            expect(stopwatch.elapsedMilliseconds).toBe(0);
+            expect(stopwatch.isRunning).toBe(true);
+        });
+
+        test("starts the stopwatch if it was never started", () => {
+            const stopwatch = new Stopwatch();
+            stopwatch.restart();
+
+            expect(stopwatch.elapsedMilliseconds).toBe(0);
+            expect(stopwatch.isRunning).toBe(true);
+        });
+    });
+
+    describe("startNew", () => {
+        test("starts new stopwatch correctly", () => {
+            const onStart = jest.fn();
+            const onStop = jest.fn();
+            const stopwatch = Stopwatch.startNew(onStart, onStop);
+
+            expect(stopwatch.isRunning).toBe(true);
+            expect(onStart).toHaveBeenCalledTimes(1);
+            expect(onStart).toHaveBeenCalledWith(new Date(0), stopwatch);
+            expect(onStop).not.toHaveBeenCalled();
+        });
+    });
+});