@byloth/core 2.0.0-rc.9 → 2.0.1

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

@@ -0,0 +1,266 @@
+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.
+     *
+     * ---
+     *
+     * @example
+     * ```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.
+     *
+     * ---
+     *
+     * @example
+     * ```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.
+     *
+     * ---
+     *
+     * @example
+     * ```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.
+     *
+     * ---
+     *
+     * @example
+     * ```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.
+     *
+     * ---
+     *
+     * @example
+     * ```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,

package/src/utils/async.ts

@@ -1,13 +1,56 @@
+/**
+ * Returns a promise that resolves after a certain number of milliseconds.  
+ * It can be used to pause or delay the execution of an asynchronous function.
+ *
+ * ```ts
+ * doSomething();
+ * await delay(1_000);
+ * doSomethingElse();
+ * ```
+ *
+ * @param milliseconds The number of milliseconds to wait before resolving the promise.
+ *
+ * @returns A {@link Promise} that resolves after the specified number of milliseconds.
+ */
 export function delay(milliseconds: number): Promise<void>
 {
     return new Promise((resolve) => setTimeout(resolve, milliseconds));
 }
 
+/**
+ * Returns a promise that resolves on the next animation frame.  
+ * It can be used to synchronize operations with the browser's rendering cycle.
+ *
+ * ```ts
+ * const $el = document.querySelector(".element");
+ *
+ * $el.classList.add("animate");
+ * await nextAnimationFrame();
+ * $el.style.opacity = "1";
+ * ```
+ *
+ * @returns A {@link Promise} that resolves on the next animation frame.
+ */
 export function nextAnimationFrame(): Promise<void>
 {
     return new Promise((resolve) => requestAnimationFrame(() => resolve()));
 }
 
+/**
+ * Returns a promise that resolves on the next microtask.  
+ * It can be used to yield to the event loop in long-running operations to prevent blocking the main thread.
+ *
+ * ```ts
+ * for (let i = 0; i < 100_000_000; i += 1)
+ * {
+ *     doSomething(i);
+ *
+ *     if (i % 100 === 0) await yieldToEventLoop();
+ * }
+ * ```
+ *
+ * @returns A {@link Promise} that resolves on the next microtask.
+ */
 export function yieldToEventLoop(): Promise<void>
 {
     return new Promise((resolve) => setTimeout(resolve));

package/src/utils/curve.ts

@@ -0,0 +1,85 @@
+import { SmartIterator, ValueException } from "../models/index.js";
+
+/**
+ * A utility class that provides a set of methods to generate sequences of numbers following specific curves.  
+ * It can be used to generate sequences of values that can be
+ * used in animations, transitions and other different scenarios.
+ *
+ * It cannot be instantiated directly.
+ */
+export default class Curve
+{
+    /**
+     * Generates a given number of values following a linear curve.  
+     * The values are equally spaced and normalized between 0 and 1.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * for (const value of Curve.Linear(5))
+     * {
+     *     console.log(value); // 0, 0.25, 0.5, 0.75, 1
+     * }
+     * ```
+     *
+     * ---
+     *
+     * @param values The number of values to generate.
+     *
+     * @returns A {@link SmartIterator} object that generates the values following a linear curve.
+     */
+    public static Linear(values: number): SmartIterator<number>
+    {
+        const steps = (values - 1);
+
+        return new SmartIterator<number>(function* ()
+        {
+            for (let index = 0; index < values; index += 1) { yield index / steps; }
+        });
+    }
+
+    /**
+     * Generates a given number of values following an exponential curve.  
+     * The values are equally spaced and normalized between 0 and 1.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * for (const value of Curve.Exponential(6))
+     * {
+     *     console.log(value); // 0, 0.04, 0.16, 0.36, 0.64, 1
+     * }
+     * ```
+     *
+     * ---
+     *
+     * @param values The number of values to generate.
+     * @param base
+     * The base of the exponential curve. Default is `2`.
+     *
+     * Also note that:
+     * - If it's equal to `1`, the curve will be linear.
+     * - If it's included between `0` and `1`, the curve will be logarithmic.
+     *
+     * The base cannot be negative. If so, a {@link ValueException} will be thrown.
+     *
+     * @returns A {@link SmartIterator} object that generates the values following an exponential curve.
+     */
+    public static Exponential(values: number, base = 2): SmartIterator<number>
+    {
+        if (base < 0) { throw new ValueException("The base of the exponential curve cannot be negative."); }
+
+        const steps = (values - 1);
+
+        return new SmartIterator<number>(function* ()
+        {
+            for (let index = 0; index < values; index += 1) { yield Math.pow(index / steps, base); }
+        });
+    }
+
+    private constructor() { /* ... */ }
+
+    public readonly [Symbol.toStringTag]: string = "Curve";
+}

package/src/utils/date.ts

@@ -1,50 +1,244 @@
 
-import { SmartIterator } from "../models/index.js";
+import { RangeException, SmartIterator } from "../models/index.js";
 
+/**
+ * An enumeration that represents the time units and their conversion factors.  
+ * It can be used as utility to express time values in a more
+ * readable way or to convert time values between different units.
+ *
+ * ```ts
+ * setTimeout(() => { [...] }, 5 * TimeUnit.Minute);
+ * ```
+ */
 export enum TimeUnit
 {
     /* eslint-disable @typescript-eslint/prefer-literal-enum-member */
 
+    /**
+     * A millisecond: the base time unit.
+     */
     Millisecond = 1,
-    Second = 1000,
+
+    /**
+     * A second: 1000 milliseconds.
+     */
+    Second = 1_000,
+
+    /**
+     * A minute: 60 seconds.
+     */
     Minute = 60 * Second,
+
+    /**
+     * An hour: 60 minutes.
+     */
     Hour = 60 * Minute,
+
+    /**
+     * A day: 24 hours.
+     */
     Day = 24 * Hour,
+
+    /**
+     * A week: 7 days.
+     */
     Week = 7 * Day,
+
+    /**
+     * A month: 30 days.
+     */
     Month = 30 * Day,
+
+    /**
+     * A year: 365 days.
+     */
     Year = 365 * Day
 }
 
+/**
+ * An enumeration that represents the days of the week.  
+ * It can be used as utility to identify the days of the week when working with dates.
+ *
+ * ```ts
+ * const today = new Date();
+ * if (today.getUTCDay() === WeekDay.Sunday)
+ * {
+ *     // Today is Sunday. Do something...
+ * }
+ * ```
+ */
+export enum WeekDay
+{
+    /**
+     * Sunday
+     */
+    Sunday = 0,
+
+    /**
+     * Monday
+     */
+    Monday = 1,
+
+    /**
+     * Tuesday
+     */
+    Tuesday = 2,
+
+    /**
+     * Wednesday
+     */
+    Wednesday = 3,
+
+    /**
+     * Thursday
+     */
+    Thursday = 4,
+
+    /**
+     * Friday
+     */
+    Friday = 5,
+
+    /**
+     * Saturday
+     */
+    Saturday = 6
+}
+
+/**
+ * An utility function that calculates the difference between two dates.  
+ * The difference can be expressed in different time units.
+ *
+ * ```ts
+ * const start = new Date("2025-01-01");
+ * const end = new Date("2025-01-31");
+ *
+ * dateDifference(start, end, TimeUnit.Minute); // 43200
+ * ```
+ *
+ * @param start The start date.
+ * @param end The end date.
+ * @param unit The time unit to express the difference. `TimeUnit.Day` by default.
+ *
+ * @returns The difference between the two dates in the specified time unit.
+ */
 export function dateDifference(start: string | Date, end: string | Date, unit = TimeUnit.Day): number
 {
+    let _round: (value: number) => number;
+
     start = new Date(start);
     end = new Date(end);
 
-    return Math.floor((end.getTime() - start.getTime()) / unit);
+    if (start < end) { _round = Math.floor; }
+    else { _round = Math.ceil; }
+
+    return _round((end.getTime() - start.getTime()) / unit);
 }
 
-export function dateRange(start: string | Date, end: string | Date, offset = TimeUnit.Day): SmartIterator<Date>
+/**
+ * An utility function that generates an iterator over a range of dates.  
+ * The step between the dates can be expressed in different time units.
+ *
+ * ```ts
+ * const start = new Date("2025-01-01");
+ * const end = new Date("2025-01-31");
+ *
+ * for (const date of dateRange(start, end, TimeUnit.Week))
+ * {
+ *     date.toISOString().slice(8, 10); // "01", "08", "15", "22", "29"
+ * }
+ * ```
+ *
+ * @param start The start date (included).
+ * @param end
+ * The end date (excluded).
+ *
+ * Must be greater than the start date. Otherwise, a {@link RangeException} will be thrown.
+ *
+ * @param step The time unit to express the step between the dates. `TimeUnit.Day` by default.
+ *
+ * @returns A {@link SmartIterator} object that generates the dates in the range.
+ */
+export function dateRange(start: string | Date, end: string | Date, step = TimeUnit.Day): SmartIterator<Date>
 {
-    start = new Date(start);
-    end = new Date(end);
+    if (start >= end) { throw new RangeException("The end date must be greater than the start date."); }
 
     return new SmartIterator<Date>(function* ()
     {
-        const endTime = end.getTime();
+        const endTime = new Date(end).getTime();
 
-        let unixTime: number = start.getTime();
+        let unixTime: number = new Date(start).getTime();
         while (unixTime < endTime)
         {
             yield new Date(unixTime);
 
-            unixTime += offset;
+            unixTime += step;
         }
     });
 }
 
+/**
+ * An utility function that rounds a date to the nearest time unit.  
+ * The rounding can be expressed in different time units.
+ *
+ * ```ts
+ * const date = new Date("2025-01-01T12:34:56.789Z");
+ *
+ * dateRound(date, TimeUnit.Hour); // 2025-01-01T12:00:00.000Z
+ * ```
+ *
+ * @param date The date to round.
+ * @param unit
+ * The time unit to express the rounding. `TimeUnit.Day` by default.
+ *
+ * Must be greater than a millisecond and less than or equal to a day.  
+ * Otherwise, a {@link RangeException} will be thrown.
+ *
+ * @returns The rounded date.
+ */
 export function dateRound(date: string | Date, unit = TimeUnit.Day): Date
 {
-    date = new Date(date);
+    if (unit <= TimeUnit.Millisecond)
+    {
+        throw new RangeException(
+            "Rounding a timestamp by milliseconds or less makes no sense." +
+            "Use the timestamp value directly instead."
+        );
+    }
+    if (unit > TimeUnit.Day)
+    {
+        throw new RangeException(
+            "Rounding by more than a day leads to unexpected results. " +
+            "Consider using other methods to round dates by weeks, months or years."
+        );
+    }
 
+    date = new Date(date);
     return new Date(Math.floor(date.getTime() / unit) * unit);
 }
+
+/**
+ * An utility function that gets the week of a date.  
+ * The first day of the week can be optionally specified.
+ *
+ * ```ts
+ * const date = new Date("2025-01-01");
+ *
+ * getWeek(date, WeekDay.Monday); // 2024-12-30
+ * ```
+ *
+ * @param date The date to get the week of.
+ * @param firstDay The first day of the week. `WeekDay.Sunday` by default.
+ *
+ * @returns The first day of the week of the specified date.
+ */
+export function getWeek(date: string | Date, firstDay = WeekDay.Sunday): Date
+{
+    date = new Date(date);
+
+    const startCorrector = 7 - firstDay;
+    const weekDayIndex = (date.getUTCDay() + startCorrector) % 7;
+    const firstDayTime = date.getTime() - (TimeUnit.Day * weekDayIndex);
+
+    return dateRound(new Date(firstDayTime));
+}