@byloth/core 2.0.0-rc.9 → 2.0.0

package/src/utils/iterator.ts

@@ -1,6 +1,29 @@
-import { SmartIterator } from "../models/index.js";
+import { RangeException, SmartIterator } from "../models/index.js";
 
-export function chain<T>(...iterables: Iterable<T>[]): SmartIterator<T>
+/**
+ * An utility function that chains multiple iterables into a single one.
+ *
+ * Since the iterator is lazy, the chaining process will be
+ * executed only once the resulting iterator is materialized.
+ *
+ * A new iterator will be created, holding the reference to the original one.  
+ * This means that the original iterator won't be consumed until the
+ * new one is and that consuming one of them will consume the other as well.
+ *
+ * ```ts
+ * for (const value of chain([1, 2, 3], [4, 5, 6], [7, 8, 9]))
+ * {
+ *     console.log(value); // 1, 2, 3, 4, 5, 6, 7, 8, 9
+ * }
+ * ```
+ *
+ * @template T The type of elements in the iterables.
+ *
+ * @param iterables The list of iterables to chain.
+ *
+ * @returns A new {@link SmartIterator} object that chains the iterables into a single one.
+ */
+export function chain<T>(...iterables: readonly Iterable<T>[]): SmartIterator<T>
 {
     return new SmartIterator<T>(function* ()
     {
@@ -11,9 +34,26 @@ export function chain<T>(...iterables: Iterable<T>[]): SmartIterator<T>
     });
 }
 
+/**
+ * An utility function that counts the number of elements in an iterable.
+ *
+ * Also note that:
+ * - If the iterable isn't an `Array`, it will be consumed entirely in the process.
+ * - If the iterable is an infinite generator, the function will never return.
+ *
+ * ```ts
+ * count([0, 1, 2, 3, 4, 5, 6, 7, 8, 9]); // 10
+ * ```
+ *
+ * @template T The type of elements in the iterable.
+ *
+ * @param elements The iterable to count.
+ *
+ * @returns The number of elements in the iterable.
+ */
 export function count<T>(elements: Iterable<T>): number
 {
-    if (Array.isArray(elements)) { return elements.length; }
+    if (elements instanceof Array) { return elements.length; }
 
     let _count = 0;
     for (const _ of elements) { _count += 1; }
@@ -21,12 +61,35 @@ export function count<T>(elements: Iterable<T>): number
     return _count;
 }
 
+/**
+ * An utility function that enumerates the elements of an iterable.  
+ * Each element is paired with its index in a new iterator.
+ *
+ * Since the iterator is lazy, the enumeration process will
+ * be executed once the resulting iterator is materialized.
+ *
+ * A new iterator will be created, holding the reference to the original one.  
+ * This means that the original iterator won't be consumed until the
+ * new one is and that consuming one of them will consume the other as well.
+ *
+ * ```ts
+ * for (const [index, value] of enumerate(["A", "M", "N", "Z"]))
+ * {
+ *     console.log(`${index}: ${value}`); // "0: A", "1: M", "2: N", "3: Z"
+ * }
+ * ```
+ *
+ * @template T The type of elements in the iterable.
+ *
+ * @param elements The iterable to enumerate.
+ *
+ * @returns A new {@link SmartIterator} object containing the enumerated elements.
+ */
 export function enumerate<T>(elements: Iterable<T>): SmartIterator<[number, T]>
 {
     return new SmartIterator<[number, T]>(function* ()
     {
         let index = 0;
-
         for (const element of elements)
         {
             yield [index, element];
@@ -36,25 +99,109 @@ export function enumerate<T>(elements: Iterable<T>): SmartIterator<[number, T]>
     });
 }
 
+/**
+ * An utility function that generates an iterator over a range of numbers.  
+ * The values are included between `0` (included) and `end` (excluded).
+ *
+ * The default step between the numbers is `1`.
+ *
+ * ```ts
+ * for (const number of range(5))
+ * {
+ *    console.log(number); // 0, 1, 2, 3, 4
+ * }
+ * ```
+ *
+ * @param end
+ * The end value (excluded).
+ *
+ * If the `end` value is negative, the step will be `-1` leading to generate the numbers in reverse order.
+ *
+ * @returns A {@link SmartIterator} object that generates the numbers in the range.
+ */
 export function range(end: number): SmartIterator<number>;
-export function range(start: number, end: number): SmartIterator<number>;
-export function range(start: number, end: number, step: number): SmartIterator<number>;
+
+/**
+ * An utility function that generates an iterator over a range of numbers.  
+ * The values are included between `start` (included) and `end` (excluded).
+ *
+ * The step between the numbers can be specified with a custom value. Default is `1`.
+ *
+ * ```ts
+ * for (const number of range(2, 7))
+ * {
+ *    console.log(number); // 2, 3, 4, 5, 6
+ * }
+ * ```
+ *
+ * @param start
+ * The start value (included).
+ *
+ * If the `start` value is greater than the `end` value, the iterator will generate the numbers in reverse order.
+ *
+ * @param end
+ * The end value (excluded).
+ *
+ * If the `end` value is less than the `start` value, the iterator will generate the numbers in reverse order.
+ *
+ * @param step
+ * The step between the numbers. Default is `1`.
+ *
+ * Must be a positive number. Otherwise, a {@link RangeError} will be thrown.
+ *
+ * @returns A {@link SmartIterator} object that generates the numbers in the range.
+ */
+export function range(start: number, end: number, step?: number): SmartIterator<number>;
 export function range(start: number, end?: number, step = 1): SmartIterator<number>
 {
-    return new SmartIterator<number>(function* ()
+    if (step <= 0)
     {
-        if (end === undefined)
-        {
-            end = start;
-            start = 0;
-        }
+        throw new RangeException(
+            "Step must be always a positive number, even when generating numbers in reverse order."
+        );
+    }
 
-        if (start > end) { step = step ?? -1; }
+    if (end === undefined)
+    {
+        end = start;
+        start = 0;
+    }
 
+    if (start > end)
+    {
+        return new SmartIterator<number>(function* ()
+        {
+            for (let index = start; index > end; index -= step) { yield index; }
+        });
+    }
+
+    return new SmartIterator<number>(function* ()
+    {
         for (let index = start; index < end; index += step) { yield index; }
     });
 }
 
+/**
+ * An utility function shuffles the elements of a given iterable.
+ *
+ * The function uses the {@link https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle|Fisher-Yates}
+ * algorithm to shuffle the elements.
+ *
+ * Also note that:
+ * - If the iterable is an `Array`, it won't be modified since the shuffling isn't done in-place.
+ * - If the iterable isn't an `Array`, it will be consumed entirely in the process.
+ * - If the iterable is an infinite generator, the function will never return.
+ *
+ * ```ts
+ * shuffle([1, 2, 3, 4, 5]); // [3, 1, 5, 2, 4]
+ * ```
+ *
+ * @template T The type of elements in the iterable.
+ *
+ * @param iterable The iterable to shuffle.
+ *
+ * @returns A new `Array` containing the shuffled elements of the given iterable.
+ */
 export function shuffle<T>(iterable: Iterable<T>): T[]
 {
     const array = Array.from(iterable);
@@ -69,12 +216,27 @@ export function shuffle<T>(iterable: Iterable<T>): T[]
     return array;
 }
 
+/**
+ * An utility function that filters the elements of an iterable ensuring that they are all unique.
+ *
+ * ```ts
+ * for (const value of unique([1, 1, 2, 3, 2, 3, 4, 5, 5, 4]))
+ * {
+ *     console.log(value); // 1, 2, 3, 4, 5
+ * }
+ * ```
+ *
+ * @template T The type of elements in the iterable.
+ *
+ * @param elements The iterable to filter.
+ *
+ * @returns A {@link SmartIterator} object that iterates over the unique elements of the given iterable.
+ */
 export function unique<T>(elements: Iterable<T>): SmartIterator<T>
 {
     return new SmartIterator<T>(function* ()
     {
         const values = new Set<T>();
-
         for (const element of elements)
         {
             if (values.has(element)) { continue; }
@@ -86,13 +248,34 @@ export function unique<T>(elements: Iterable<T>): SmartIterator<T>
     });
 }
 
+/**
+ * An utility function that zips two iterables into a single one.  
+ * The resulting iterable will contain the elements of the two iterables paired together.
+ *
+ * The function will stop when one of the two iterables is exhausted.
+ *
+ * ```ts
+ * for (const [number, char] of zip([1, 2, 3, 4], ["A", "M", "N" "Z"]))
+ * {
+ *     console.log(`${number} - ${char}`); // "1 - A", "2 - M", "3 - N", "4 - Z"
+ * }
+ * ```
+ *
+ * @template T The type of elements in the first iterable.
+ * @template U The type of elements in the second iterable.
+ *
+ * @param first The first iterable to zip.
+ * @param second The second iterable to zip.
+ *
+ * @returns A {@link SmartIterator} object that iterates over the zipped elements of the two given iterables.
+ */
 export function zip<T, U>(first: Iterable<T>, second: Iterable<U>): SmartIterator<[T, U]>
 {
+    const firstIterator = first[Symbol.iterator]();
+    const secondIterator = second[Symbol.iterator]();
+
     return new SmartIterator<[T, U]>(function* ()
     {
-        const firstIterator = first[Symbol.iterator]();
-        const secondIterator = second[Symbol.iterator]();
-
         while (true)
         {
             const firstResult = firstIterator.next();

package/src/utils/math.ts

@@ -1,8 +1,31 @@
 import { ValueException } from "../models/exceptions/index.js";
 import { zip } from "./iterator.js";
 
-export function average<T extends number>(values: Iterable<T>): number;
-export function average<T extends number>(values: Iterable<T>, weights: Iterable<number>): number;
+/**
+ * Computes the average of a given list of values.  
+ * The values can be weighted using an additional list of weights.
+ *
+ * ```ts
+ * average([1, 2, 3, 4, 5]); // 3
+ * average([6, 8.5, 4], [3, 2, 1]); // 6.5
+ * ```
+ *
+ * @template T The type of the values in the list. It must be or extend a `number` object.
+ *
+ * @param values
+ * The list of values to compute the average.
+ *
+ * It must contain at least one element. Otherwise, a {@link ValueException} will be thrown.
+ *
+ * @param weights
+ * The list of weights to apply to the values.  
+ * It should contain the same number of elements as the values list or
+ * the smaller number of elements between the two lists will be considered.
+ *
+ * The sum of the weights must be greater than zero. Otherwise, a {@link ValueException} will be thrown.
+ *
+ * @returns The average of the specified values.
+ */
 export function average<T extends number>(values: Iterable<T>, weights?: Iterable<number>): number
 {
     if (weights === undefined)
@@ -38,11 +61,27 @@ export function average<T extends number>(values: Iterable<T>, weights?: Iterabl
     }
 
     if (_index === 0) { throw new ValueException("You must provide at least one value and weight."); }
-    if (_count > 0) { throw new ValueException("The sum of weights must be greater than zero."); }
+    if (_count <= 0) { throw new ValueException("The sum of weights must be greater than zero."); }
 
     return _sum / _count;
 }
 
+/**
+ * An utility function to compute the hash of a given string.
+ *
+ * The hash is computed using a simple variation of the
+ * {@link http://www.cse.yorku.ca/~oz/hash.html#djb2|djb2} algorithm.  
+ * However, the hash is garanteed to be a 32-bit signed integer.
+ *
+ * ```ts
+ * hash("Hello, world!"); // -1880044555
+ * hash("How are you?"); // 1761539132
+ * ```
+ *
+ * @param value The string to hash.
+ *
+ * @returns The hash of the specified string.
+ */
 export function hash(value: string): number
 {
     let hashedValue = 0;
@@ -57,6 +96,19 @@ export function hash(value: string): number
     return hashedValue;
 }
 
+/**
+ * Sums all the values of a given list.
+ *
+ * ```ts
+ * sum([1, 2, 3, 4, 5]); // 15
+ * ```
+ *
+ * @template T The type of the values in the list. It must be or extend a `number` object.
+ *
+ * @param values The list of values to sum.
+ *
+ * @returns The sum of the specified values.
+ */
 export function sum<T extends number>(values: Iterable<T>): number
 {
     let _sum = 0;

package/src/utils/random.ts

@@ -1,13 +1,61 @@
 import { ValueException } from "../models/index.js";
 
+/**
+ * A wrapper class around the native {@link Math.random} function that
+ * provides a set of methods to generate random values more easily.  
+ * It can be used to generate random numbers, booleans and other different values.
+ *
+ * It cannot be instantiated directly.
+ */
 export default class Random
 {
+    /**
+     * Generates a random boolean value.
+     *
+     * ```ts
+     * if (Random.Boolean())
+     * {
+     *    // Do something...
+     * }
+     * ```
+     *
+     * @param ratio
+     * The probability of generating `true`.
+     *
+     * It must be included between `0` and `1`. Default is `0.5`.
+     *
+     * @returns A random boolean value.
+     */
     public static Boolean(ratio = 0.5): boolean
     {
         return (Math.random() < ratio);
     }
 
+    /**
+     * Generates a random integer value between `0` (included) and `max` (excluded).
+     *
+     * ```ts
+     * Random.Integer(5); // 0, 1, 2, 3, 4
+     * ```
+     *
+     * @param max The maximum value (excluded).
+     *
+     * @returns A random integer value.
+     */
     public static Integer(max: number): number;
+
+    /**
+     * Generates a random integer value between `min` (included) and `max` (excluded).
+     *
+     * ```ts
+     * Random.Integer(2, 7); // 2, 3, 4, 5, 6
+     * ```
+     *
+     * @param min The minimum value (included).
+     * @param max The maximum value (excluded).
+     *
+     * @returns A random integer value.
+     */
     public static Integer(min: number, max: number): number;
     public static Integer(min: number, max?: number): number
     {
@@ -16,8 +64,42 @@ export default class Random
         return Math.floor(Math.random() * (max - min) + min);
     }
 
+    /**
+     * Generates a random decimal value between `0` (included) and `1` (excluded).
+     *
+     * ```ts
+     * Random.Decimal(); // 0.123456789
+     * ```
+     *
+     * @returns A random decimal value.
+     */
     public static Decimal(): number;
+
+    /**
+     * Generates a random decimal value between `0` (included) and `max` (excluded).
+     *
+     * ```ts
+     * Random.Decimal(5); // 2.3456789
+     * ```
+     *
+     * @param max The maximum value (excluded).
+     *
+     * @returns A random decimal value.
+     */
     public static Decimal(max: number): number;
+
+    /**
+     * Generates a random decimal value between `min` (included) and `max` (excluded).
+     *
+     * ```ts
+     * Random.Decimal(2, 7); // 4.56789
+     * ```
+     *
+     * @param min The minimum value (included).
+     * @param max The maximum value (excluded).
+     *
+     * @returns A random decimal value
+     */
     public static Decimal(min: number, max: number): number;
     public static Decimal(min?: number, max?: number): number
     {
@@ -27,13 +109,38 @@ export default class Random
         return (Math.random() * (max - min) + min);
     }
 
-    public static Index<T>(elements: T[]): number
+    /**
+     * Picks a random valid index from a given array of elements.
+     *
+     * @template T The type of the elements in the array.
+     *
+     * @param elements
+     * The array of elements to pick from.
+     *
+     * It must contain at least one element. Otherwise, a {@link ValueException} will be thrown.
+     *
+     * @returns A valid random index from the given array.
+     */
+    public static Index<T>(elements: readonly T[]): number
     {
         if (elements.length === 0) { throw new ValueException("You must provide at least one element."); }
 
         return this.Integer(elements.length);
     }
-    public static Choice<T>(elements: T[]): T
+
+    /**
+     * Picks a random element from a given array of elements.
+     *
+     * @template T The type of the elements in the array.
+     *
+     * @param elements
+     * The array of elements to pick from.
+     *
+     * It must contain at least one element. Otherwise, a {@link ValueException} will be thrown.
+     *
+     * @returns A random element from the given array.
+     */
+    public static Choice<T>(elements: readonly T[]): T
     {
         return elements[Random.Index(elements)];
     }

package/src/utils/string.ts

@@ -1,3 +1,14 @@
+/**
+ * Capitalize the first letter of a string.
+ *
+ * ```ts
+ * capitalize('hello'); // 'Hello'
+ * ```
+ *
+ * @param value The string to capitalize.
+ *
+ * @returns The capitalized string.
+ */
 export function capitalize(value: string): string
 {
     return `${value.charAt(0).toUpperCase()}${value.slice(1)}`;

package/src/models/game-loop.ts

@@ -1,83 +0,0 @@
-import type { Interval } from "../core/types.js";
-import { isBrowser } from "../helpers.js";
-
-import { FatalErrorException, RuntimeException } from "./exceptions/index.js";
-
-export default class GameLoop
-{
-    protected _handle?: number | Interval;
-
-    protected _startTime: number;
-    public get startTime(): number
-    {
-        return this._startTime;
-    }
-
-    protected _isRunning: boolean;
-    public get isRunning(): boolean
-    {
-        return this._isRunning;
-    }
-
-    public get elapsedTime(): number
-    {
-        return performance.now() - this._startTime;
-    }
-
-    protected _start: () => void;
-    protected _stop: () => void;
-
-    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);
-        }
-    }
-
-    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;
-    }
-
-    public stop(): void
-    {
-        if (!(this._isRunning)) { throw new RuntimeException("The game loop hadn't yet started."); }
-        if (!(this._handle)) { throw new FatalErrorException(); }
-
-        this._stop();
-        this._handle = undefined;
-        this._isRunning = false;
-    }
-
-    public readonly [Symbol.toStringTag]: string = "GameLoop";
-}