@byloth/core 2.0.0-rc.9 → 2.0.0

package/src/models/timers/clock.ts

@@ -1,20 +1,55 @@
 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.
+     *
+     * ```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 +57,70 @@ 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.
+     *
+     * ```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.
+     *
+     * ```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.
+     *
+     * ```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 +137,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,95 @@ 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.
+     *
+     * ```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 +110,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 +135,25 @@ 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.
+     *
+     * ```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 +163,76 @@ 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.
+     *
+     * ```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.
+     *
+     * ```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.
+     *
+     * ```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 +243,5 @@ export default class Countdown extends GameLoop
         });
     }
 
-    public readonly [Symbol.toStringTag]: string = "Countdown";
+    public override readonly [Symbol.toStringTag]: string = "Countdown";
 }

package/src/models/timers/game-loop.ts

@@ -0,0 +1,243 @@
+import type { Interval } from "../../core/types.js";
+import { isBrowser } from "../../helpers.js";
+
+import Publisher from "../callbacks/publisher.js";
+import { FatalErrorException, RuntimeException } from "../exceptions/index.js";
+import type { Callback } from "../types.js";
+
+interface GameLoopEventMap
+{
+    start: () => void;
+    stop: () => void;
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    [key: string]: Callback<any[], any>;
+}
+
+/**
+ * A class representing a {@link https://en.wikipedia.org/wiki/Video_game_programming#Game_structure|game loop} pattern
+ * that allows to run a function at a specific frame rate.
+ *
+ * In a browser environment, it uses the native {@link requestAnimationFrame}
+ * function to run the callback at the refresh rate of the screen.  
+ * In a non-browser environment, however, it uses the {@link setInterval}
+ * function to run the callback at the specified fixed interval of time.
+ *
+ * Every time the callback is executed, it receives the
+ * elapsed time since the start of the game loop.  
+ * It's also possible to subscribe to the `start` & `stop` events to receive notifications when they occur.
+ *
+ * ```ts
+ * const loop = new GameLoop((elapsedTime: number) =>
+ * {
+ *     console.log(`The game loop has been running for ${elapsedTime}ms.`);
+ * });
+ *
+ * loop.onStart(() => { console.log("The game loop has started."); });
+ * loop.onStop(() => { console.log("The game loop has stopped."); });
+ *
+ * loop.start();
+ * ```
+ */
+export default class GameLoop
+{
+    /**
+     * The handle of the interval or the animation frame, depending on the environment.  
+     * It's used to stop the game loop when the {@link GameLoop._stop} method is called.
+     */
+    protected _handle?: number | Interval;
+
+    /**
+     * The time when the game loop has started.  
+     * In addition to indicating the {@link https://en.wikipedia.org/wiki/Unix_time|Unix timestamp}
+     * of the start of the game loop, it's also used to calculate the elapsed time.
+     *
+     * 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 GameLoop.startTime} getter instead.
+     */
+    protected _startTime: number;
+
+    /**
+     * The time when the game loop has started.  
+     * In addition to indicating the {@link https://en.wikipedia.org/wiki/Unix_time|Unix timestamp}
+     * of the start of the game loop, it's also used to calculate the elapsed time.
+     */
+    public get startTime(): number
+    {
+        return this._startTime;
+    }
+
+    /**
+     * A flag indicating whether the game loop is currently running or not.
+     *
+     * 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 GameLoop.isRunning} getter instead.
+     */
+    protected _isRunning: boolean;
+
+    /**
+     * A flag indicating whether the game loop is currently running or not.
+     */
+    public get isRunning(): boolean
+    {
+        return this._isRunning;
+    }
+
+    /**
+     * The elapsed time since the start of the game loop.  
+     * It's calculated as the difference between the current time and the {@link GameLoop.startTime}.
+     */
+    public get elapsedTime(): number
+    {
+        return performance.now() - this._startTime;
+    }
+
+    /**
+     * The {@link Publisher} object that will be used to publish the events of the game loop.
+     */
+    protected _publisher: Publisher<GameLoopEventMap>;
+
+    /**
+     * The internal method actually responsible for starting the game loop.
+     *
+     * Depending on the current environment, it could use the
+     * {@link requestAnimationFrame} or the {@link setInterval} function.
+     */
+    protected _start: () => void;
+
+    /**
+     * The internal method actually responsible for stopping the game loop.
+     *
+     * Depending on the current environment, it could use the
+     * {@link cancelAnimationFrame} or the {@link clearInterval} function.
+     */
+    protected _stop: () => void;
+
+    /**
+     * Initializes a new instance of the {@link GameLoop} class.
+     *
+     * ```ts
+     * const loop = new GameLoop((elapsedTime: number) => { [...] });
+     * ```
+     *
+     * @param callback The function that will be executed at each iteration of the game loop.
+     * @param msIfNotBrowser
+     * The interval in milliseconds that will be used if the current environment isn't a browser. Default is `40`.
+     */
+    public constructor(callback: FrameRequestCallback, msIfNotBrowser = 40)
+    {
+        this._startTime = 0;
+        this._isRunning = false;
+
+        if (isBrowser)
+        {
+            this._start = () =>
+            {
+                callback(this.elapsedTime);
+
+                this._handle = window.requestAnimationFrame(this._start);
+            };
+
+            this._stop = () => window.cancelAnimationFrame(this._handle as number);
+        }
+        else
+        {
+            // eslint-disable-next-line no-console
+            console.warn(
+                "Not a browser environment detected. " +
+                `Using setInterval@${msIfNotBrowser}ms instead of requestAnimationFrame...`
+            );
+
+            this._start = () =>
+            {
+                this._handle = setInterval(() => callback(this.elapsedTime), msIfNotBrowser);
+            };
+
+            this._stop = () => clearInterval(this._handle as Interval);
+        }
+
+        this._publisher = new Publisher();
+    }
+
+    /**
+     * Starts the execution of the game loop.
+     *
+     * If the game loop is already running, a {@link RuntimeException} will be thrown.
+     *
+     * ```ts
+     * loop.onStart(() => { [...] }); // This callback will be executed.
+     * loop.start();
+     * ```
+     *
+     * @param elapsedTime The elapsed time to set as default when the game loop starts. Default is `0`.
+     */
+    public start(elapsedTime = 0): void
+    {
+        if (this._isRunning) { throw new RuntimeException("The game loop has already been started."); }
+
+        this._startTime = performance.now() - elapsedTime;
+        this._start();
+        this._isRunning = true;
+
+        this._publisher.publish("start");
+    }
+
+    /**
+     * Stops the execution of the game loop.
+     *
+     * If the game loop hasn't yet started, a {@link RuntimeException} will be thrown.
+     *
+     * ```ts
+     * loop.onStop(() => { [...] }); // This callback will be executed.
+     * loop.stop();
+     * ```
+     */
+    public stop(): void
+    {
+        if (!(this._isRunning))
+        {
+            throw new RuntimeException("The game loop had already stopped or hadn't yet started.");
+        }
+        if (!(this._handle)) { throw new FatalErrorException(); }
+
+        this._stop();
+        this._handle = undefined;
+        this._isRunning = false;
+
+        this._publisher.publish("stop");
+    }
+
+    /**
+     * Subscribes to the `start` event of the game loop.
+     *
+     * ```ts
+     * loop.onStart(() => { console.log("The game loop has started."); });
+     * ```
+     *
+     * @param callback The function that will be executed when the game loop starts.
+     *
+     * @returns A function that can be used to unsubscribe from the event.
+     */
+    public onStart(callback: () => void): () => void
+    {
+        return this._publisher.subscribe("start", callback);
+    }
+
+    /**
+     * Subscribes to the `stop` event of the game loop.
+     *
+     * ```ts
+     * loop.onStop(() => { console.log("The game loop has stopped."); });
+     * ```
+     *
+     * @param callback The function that will be executed when the game loop stops.
+     *
+     * @returns A function that can be used to unsubscribe from the event.
+     */
+    public onStop(callback: () => void): () => void
+    {
+        return this._publisher.subscribe("stop", callback);
+    }
+
+    public readonly [Symbol.toStringTag]: string = "GameLoop";
+}

package/src/models/timers/index.ts

@@ -1,4 +1,5 @@
 import Clock from "./clock.js";
 import Countdown from "./countdown.js";
+import GameLoop from "./game-loop.js";
 
-export { Clock, Countdown };
+export { Clock, Countdown, GameLoop };

package/src/models/types.ts

@@ -1,9 +1,10 @@
 export type {
     KeyedIteratee,
+    AsyncKeyedIteratee,
     MaybeAsyncKeyedIteratee,
-    KeyedTypeGuardIteratee,
-    MaybeAsyncKeyedTypeGuardIteratee,
+    KeyedTypeGuardPredicate,
     KeyedReducer,
+    AsyncKeyedReducer,
     MaybeAsyncKeyedReducer
 
 } from "./aggregators/types.js";
@@ -13,10 +14,11 @@ export type {
     AsyncGeneratorFunction,
     MaybeAsyncGeneratorFunction,
     Iteratee,
+    AsyncIteratee,
     MaybeAsyncIteratee,
-    TypeGuardIteratee,
-    MaybeAsyncTypeGuardIteratee,
+    TypeGuardPredicate,
     Reducer,
+    AsyncReducer,
     MaybeAsyncReducer,
     IteratorLike,
     AsyncIteratorLike,
@@ -32,7 +34,6 @@ export type {
 } from "./json/types.js";
 
 export type {
-    LongRunningTaskOptions,
     MaybePromise,
     FulfilledHandler,
     RejectedHandler,