@byloth/core 2.0.0-rc.9 → 2.0.1

package/src/models/timers/clock.ts

@@ -1,20 +1,60 @@
 import { TimeUnit } from "../../utils/date.js";
-import { RangeException, RuntimeException } from "../exceptions/index.js";
 
 import Publisher from "../callbacks/publisher.js";
-import GameLoop from "../game-loop.js";
+import { FatalErrorException, RangeException, RuntimeException } from "../exceptions/index.js";
+import type { Callback } from "../types.js";
+
+import GameLoop from "./game-loop.js";
 
 interface ClockEventMap
 {
     start: () => void;
     stop: () => void;
     tick: (elapsedTime: number) => void;
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    [key: string]: Callback<any[], any>;
 }
 
+/**
+ * A class representing a clock.
+ *
+ * It can be started, stopped and, when running, it ticks at a specific frame rate.  
+ * It's possible to subscribe to these events to receive notifications when they occur.
+ *
+ * ```ts
+ * const clock = new Clock();
+ *
+ * clock.onStart(() => { console.log("The clock has started."); });
+ * clock.onTick((elapsedTime) => { console.log(`The clock has ticked at ${elapsedTime}ms.`); });
+ * clock.onStop(() => { console.log("The clock has stopped."); });
+ *
+ * clock.start();
+ * ```
+ */
 export default class Clock extends GameLoop
 {
-    protected _publisher: Publisher<ClockEventMap>;
-
+    /**
+     * The {@link Publisher} object that will be used to publish the events of the clock.
+     */
+    protected override _publisher: Publisher<ClockEventMap>;
+
+    /**
+     * Initializes a new instance of the {@link Clock} class.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * const clock = new Clock();
+     * ```
+     *
+     * ---
+     *
+     * @param msIfNotBrowser
+     * The interval in milliseconds at which the clock will tick if the environment is not a browser.  
+     * `TimeUnit.Second` by default.
+     */
     public constructor(msIfNotBrowser: number = TimeUnit.Second)
     {
         super((elapsedTime) => this._publisher.publish("tick", elapsedTime), msIfNotBrowser);
@@ -22,33 +62,83 @@ export default class Clock extends GameLoop
         this._publisher = new Publisher();
     }
 
-    public start(elapsedTime = 0): void
+    /**
+     * Starts the execution of the clock.
+     *
+     * If the clock is already running, a {@link RuntimeException} will be thrown.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * clock.onStart(() => { [...] }); // This callback will be executed.
+     * clock.start();
+     * ```
+     *
+     * ---
+     *
+     * @param elapsedTime The elapsed time to set as default when the clock starts. Default is `0`.
+     */
+    public override start(elapsedTime = 0): void
     {
         if (this._isRunning) { throw new RuntimeException("The clock has already been started."); }
 
-        super.start(elapsedTime);
+        this._startTime = performance.now() - elapsedTime;
+        this._start();
+        this._isRunning = true;
 
         this._publisher.publish("start");
     }
 
-    public stop(): void
+    /**
+     * Stops the execution of the clock.
+     *
+     * If the clock hasn't yet started, a {@link RuntimeException} will be thrown.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * clock.onStop(() => { [...] }); // This callback will be executed.
+     * clock.stop();
+     * ```
+     */
+    public override stop(): void
     {
-        if (!(this._isRunning)) { throw new RuntimeException("The clock hadn't yet started."); }
+        if (!(this._isRunning)) { throw new RuntimeException("The clock had already stopped or hadn't yet started."); }
+        if (!(this._handle)) { throw new FatalErrorException(); }
 
-        super.stop();
+        this._stop();
+        this._handle = undefined;
+        this._isRunning = false;
 
         this._publisher.publish("stop");
     }
 
-    public onStart(callback: () => void): () => void
-    {
-        return this._publisher.subscribe("start", callback);
-    }
-    public onStop(callback: () => void): () => void
-    {
-        return this._publisher.subscribe("stop", callback);
-    }
-
+    /**
+     * Subscribes to the `tick` event of the clock.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * clock.onTick((elapsedTime) => { [...] }); // This callback will be executed.
+     * clock.start();
+     * ```
+     *
+     * ---
+     *
+     * @param callback The callback that will be executed when the clock ticks.
+     * @param tickStep
+     * The minimum time in milliseconds that must pass from the previous execution of the callback to the next one.
+     *
+     * - If it's a positive number, the callback will be executed only if the
+     * time passed from the previous execution is greater than this number.
+     * - If it's `0`, the callback will be executed every tick without even checking for the time.
+     * - If it's a negative number, a {@link RangeException} will be thrown.
+     *
+     * @returns A function that can be used to unsubscribe from the event.
+     */
     public onTick(callback: (elapsedTime: number) => void, tickStep = 0): () => void
     {
         if (tickStep < 0) { throw new RangeException("The tick step must be a non-negative number."); }
@@ -65,5 +155,5 @@ export default class Clock extends GameLoop
         });
     }
 
-    public readonly [Symbol.toStringTag]: string = "Clock";
+    public override readonly [Symbol.toStringTag]: string = "Clock";
 }

package/src/models/timers/countdown.ts

@@ -1,10 +1,11 @@
 import { TimeUnit } from "../../utils/date.js";
 
+import Publisher from "../callbacks/publisher.js";
 import { FatalErrorException, RangeException, RuntimeException } from "../exceptions/index.js";
 import { DeferredPromise, SmartPromise } from "../promises/index.js";
+import type { Callback } from "../types.js";
 
-import Publisher from "../callbacks/publisher.js";
-import GameLoop from "../game-loop.js";
+import GameLoop from "./game-loop.js";
 
 interface CountdownEventMap
 {
@@ -12,37 +13,100 @@ interface CountdownEventMap
     stop: (reason: unknown) => void;
     tick: (remainingTime: number) => void;
     expire: () => void;
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    [key: string]: Callback<any[], any>;
 }
 
+/**
+ * A class representing a countdown.
+ *
+ * It can be started, stopped, when running it ticks at a specific frame rate and it expires when the time's up.  
+ * It's possible to subscribe to these events to receive notifications when they occur.
+ *
+ * ```ts
+ * const countdown = new Countdown(10_000);
+ *
+ * countdown.onStart(() => { console.log("The countdown has started."); });
+ * countdown.onTick((remainingTime) => { console.log(`The countdown has ${remainingTime}ms remaining.`); });
+ * countdown.onStop((reason) => { console.log(`The countdown has stopped because of ${reason}.`); });
+ * countdown.onExpire(() => { console.log("The countdown has expired."); });
+ *
+ * countdown.start();
+ * ```
+ */
 export default class Countdown extends GameLoop
 {
-    protected _deferrer?: DeferredPromise<void>;
-    protected _publisher: Publisher<CountdownEventMap>;
+    /**
+     * The {@link Publisher} object that will be used to publish the events of the countdown.
+     */
+    protected override _publisher: Publisher<CountdownEventMap>;
 
+    /**
+     * The total duration of the countdown in milliseconds.
+     *
+     * This protected property is the only one that can be modified directly by the derived classes.  
+     * If you're looking for the public and readonly property, use the {@link Countdown.duration} getter instead.
+     */
     protected _duration: number;
+
+    /**
+     * The total duration of the countdown in milliseconds.
+     */
     public get duration(): number
     {
         return this._duration;
     }
 
+    /**
+     * The remaining time of the countdown in milliseconds.  
+     * It's calculated as the difference between the total duration and the elapsed time.
+     */
     public get remainingTime(): number
     {
         return this._duration - this.elapsedTime;
     }
 
+    /**
+     * The {@link DeferredPromise} that will be resolved or rejected when the countdown expires or stops.
+     */
+    protected _deferrer?: DeferredPromise<void>;
+
+    /**
+     * Initializes a new instance of the {@link Countdown} class.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * const countdown = new Countdown(10_000);
+     * ```
+     *
+     * ---
+     *
+     * @param duration
+     * The total duration of the countdown in milliseconds.
+     *
+     * @param msIfNotBrowser
+     * The interval in milliseconds at which the countdown will tick if the environment is not a browser.  
+     * `TimeUnit.Second` by default.
+     */
     public constructor(duration: number, msIfNotBrowser: number = TimeUnit.Second)
     {
         const callback = () =>
         {
             const remainingTime = this.remainingTime;
-            this._publisher.publish("tick", remainingTime);
-
             if (remainingTime <= 0)
             {
                 this._deferrerStop();
 
+                this._publisher.publish("tick", 0);
                 this._publisher.publish("expire");
             }
+            else
+            {
+                this._publisher.publish("tick", remainingTime);
+            }
         };
 
         super(callback, msIfNotBrowser);
@@ -51,12 +115,24 @@ export default class Countdown extends GameLoop
         this._duration = duration;
     }
 
+    /**
+     * The internal method actually responsible for stopping the
+     * countdown and resolving or rejecting the {@link Countdown._deferrer} promise.
+     *
+     * @param reason
+     * The reason why the countdown has stopped.
+     *
+     * - If it's `undefined`, the promise will be resolved.
+     * - If it's a value, the promise will be rejected with that value.
+     */
     protected _deferrerStop(reason?: unknown): void
     {
         if (!(this._isRunning)) { throw new RuntimeException("The countdown hadn't yet started."); }
         if (!(this._deferrer)) { throw new FatalErrorException(); }
 
-        super.stop();
+        this._stop();
+        this._handle = undefined;
+        this._isRunning = false;
 
         if (reason !== undefined) { this._deferrer.reject(reason); }
         else { this._deferrer.resolve(); }
@@ -64,9 +140,30 @@ export default class Countdown extends GameLoop
         this._deferrer = undefined;
     }
 
-    public start(remainingTime: number = this.duration): SmartPromise<void>
+    /**
+     * Starts the execution of the countdown.
+     *
+     * If the countdown is already running, a {@link RuntimeException} will be thrown.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * countdown.onStart(() => { [...] }); // This callback will be executed.
+     * countdown.start();
+     * ```
+     *
+     * ---
+     *
+     * @param remainingTime
+     * The remaining time to set as default when the countdown starts.  
+     * Default is the {@link Countdown.duration} itself.
+     *
+     * @returns A {@link SmartPromise} that will be resolved or rejected when the countdown expires or stops.
+     */
+    public override start(remainingTime: number = this.duration): SmartPromise<void>
     {
-        if (this._isRunning) { throw new RuntimeException("The countdown has already been started."); }
+        if (this._isRunning) { throw new RuntimeException("The countdown had already stopped or hadn't yet started."); }
         if (this._deferrer) { throw new FatalErrorException(); }
 
         this._deferrer = new DeferredPromise();
@@ -76,33 +173,91 @@ export default class Countdown extends GameLoop
 
         return this._deferrer;
     }
-    public stop(reason?: unknown): void
+
+    /**
+     * Stops the execution of the countdown.
+     *
+     * If the countdown hasn't yet started, a {@link RuntimeException} will be thrown.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * countdown.onStop(() => { [...] }); // This callback will be executed.
+     * countdown.stop();
+     * ```
+     *
+     * ---
+     *
+     * @param reason
+     * The reason why the countdown has stopped.
+     *
+     * - If it's `undefined`, the promise will be resolved.
+     * - If it's a value, the promise will be rejected with that value.
+     */
+    public override stop(reason?: unknown): void
     {
+        // TODO: Once solved Issues #6 & #10, make the `reason` parameter required.
+        //       - https://github.com/Byloth/core/issues/6
+        //       - https://github.com/Byloth/core/issues/10
+        //
         this._deferrerStop(reason);
 
         this._publisher.publish("stop", reason);
     }
 
+    /**
+     * Subscribes to the `expire` event of the countdown.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * countdown.onExpire(() => { [...] }); // This callback will be executed once the countdown has expired.
+     * countdown.start();
+     * ```
+     *
+     * ---
+     *
+     * @param callback The callback that will be executed when the countdown expires.
+     *
+     * @returns A function that can be used to unsubscribe from the event.
+     */
     public onExpire(callback: () => void): () => void
     {
         return this._publisher.subscribe("expire", callback);
     }
 
-    public onStart(callback: () => void): () => void
-    {
-        return this._publisher.subscribe("start", callback);
-    }
-    public onStop(callback: (reason?: unknown) => void): () => void
-    {
-        return this._publisher.subscribe("stop", callback);
-    }
-
+    /**
+     * Subscribes to the `tick` event of the countdown.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * countdown.onTick((remainingTime) => { [...] }); // This callback will be executed.
+     * countdown.start();
+     * ```
+     *
+     * ---
+     *
+     * @param callback The callback that will be executed when the countdown ticks.
+     * @param tickStep
+     * The minimum time in milliseconds that must pass from the previous execution of the callback to the next one.
+     *
+     * - If it's a positive number, the callback will be executed only if the
+     * time passed from the previous execution is greater than this number.
+     * - If it's `0`, the callback will be executed every tick without even checking for the time.
+     * - If it's a negative number, a {@link RangeException} will be thrown.
+     *
+     * @returns A function that can be used to unsubscribe from the event.
+     */
     public onTick(callback: (remainingTime: number) => void, tickStep = 0): () => void
     {
         if (tickStep < 0) { throw new RangeException("The tick step must be a non-negative number."); }
         if (tickStep === 0) { return this._publisher.subscribe("tick", callback); }
 
-        let lastTick = 0;
+        let lastTick = this.remainingTime;
 
         return this._publisher.subscribe("tick", (remainingTime: number) =>
         {
@@ -113,5 +268,5 @@ export default class Countdown extends GameLoop
         });
     }
 
-    public readonly [Symbol.toStringTag]: string = "Countdown";
+    public override readonly [Symbol.toStringTag]: string = "Countdown";
 }