@byloth/core 2.2.3 → 2.2.5

package/src/models/iterators/smart-iterator.ts

@@ -580,7 +580,7 @@ export default class SmartIterator<T, R = void, N = undefined> implements Iterat
      * const iterator = new SmartIterator<number>([-2, -1, 0, 1, 2]);
      * const result = iterator.take(3);
      *
-     * console.log(result.toArray()); // [-2, -1, 0]
+     * console.log(result.toArray());   // [-2, -1, 0]
      * console.log(iterator.toArray()); // [1, 2]
      * ```
      *

package/src/models/promises/smart-promise.ts

@@ -17,12 +17,12 @@ import type { FulfilledHandler, PromiseExecutor, RejectedHandler } from "./types
  *     setTimeout(() => resolve("Hello, World!"), 1_000);
  * });
  *
- * console.log(promise.isPending); // true
+ * console.log(promise.isPending);   // true
  * console.log(promise.isFulfilled); // false
  *
  * console.log(await promise); // "Hello, World!"
  *
- * console.log(promise.isPending); // false
+ * console.log(promise.isPending);   // false
  * console.log(promise.isFulfilled); // true
  * ```
  *
@@ -39,14 +39,14 @@ export default class SmartPromise<T = void> implements Promise<T>
      *
      * @example
      * ```ts
-     * const request = fetch("https://api.example.com/data");
-     * const smartRequest = SmartPromise.FromPromise(request);
+     * const response = fetch("https://api.example.com/data");
+     * const smartResponse = SmartPromise.FromPromise(response);
      *
-     * console.log(request.isPending); // Throws an error: `isPending` is not a property of `Promise`.
-     * console.log(smartRequest.isPending); // true
+     * console.log(response.isPending);      // Throws an error: `isPending` is not a property of `Promise`.
+     * console.log(smartResponse.isPending); // true
      *
-     * const response = await request;
-     * console.log(smartRequest.isFulfilled); // true
+     * const response = await response;
+     * console.log(smartResponse.isFulfilled); // true
      * ```
      *
      * ---
@@ -323,8 +323,8 @@ export default class SmartPromise<T = void> implements Promise<T>
      *
      *
      * promise
-     *     .then(() => console.log("OK!")) // Logs "OK!" if the promise is fulfilled.
-     *     .catch(() => console.log("KO!")) // Logs "KO!" if the promise is rejected.
+     *     .then(() => console.log("OK!"))       // Logs "OK!" if the promise is fulfilled.
+     *     .catch(() => console.log("KO!"))      // Logs "KO!" if the promise is rejected.
      *     .finally(() => console.log("Done!")); // Always logs "Done!".
      * ```
      *

package/src/models/promises/timed-promise.ts

@@ -20,7 +20,7 @@ import type { MaybePromise, PromiseExecutor } from "./types.js";
  * }, 5_000);
  *
  * promise
- *     .then((result) => console.log(result))  // "Hello, World!"
+ *     .then((result) => console.log(result))   // "Hello, World!"
  *     .catch((error) => console.error(error)); // "Uncaught TimeoutException: The operation has timed out."
  * ```
  *

package/src/utils/index.ts

@@ -5,5 +5,5 @@ export { delay, nextAnimationFrame, yieldToEventLoop } from "./async.js";
 export { dateDifference, dateRange, dateRound, getWeek, TimeUnit, WeekDay } from "./date.js";
 export { loadScript } from "./dom.js";
 export { chain, count, enumerate, range, shuffle, unique, zip } from "./iterator.js";
-export { average, hash, sum } from "./math.js";
+export { average, clamp, hash, sum } from "./math.js";
 export { capitalize } from "./string.js";

package/src/utils/math.ts

@@ -9,7 +9,7 @@ import { zip } from "./iterator.js";
  *
  * @example
  * ```ts
- * average([1, 2, 3, 4, 5]); // 3
+ * average([1, 2, 3, 4, 5]);        // 3
  * average([6, 8.5, 4], [3, 2, 1]); // 6.5
  * ```
  *
@@ -71,6 +71,39 @@ export function average<T extends number>(values: Iterable<T>, weights?: Iterabl
     return _sum / _count;
 }
 
+/**
+ * Clamps a given value between a minimum and a maximum bound.
+ *
+ * ---
+ *
+ * @example
+ * ```ts
+ * clamp(5, 0, 10);  // 5
+ * clamp(-3, 0, 10); // 0
+ * clamp(15, 0, 10); // 10
+ * ```
+ *
+ * ---
+ *
+ * @param value The value to clamp.
+ * @param min The minimum bound.
+ * @param max The maximum bound.
+ *
+ * @returns The clamped value between the specified bounds.
+ */
+export function clamp(value: number, min: number, max: number): number
+{
+    if (min > max)
+    {
+        throw new ValueException("The minimum bound must be less than or equal to the maximum bound.");
+    }
+
+    if (value < min) { return min; }
+    if (value > max) { return max; }
+
+    return value;
+}
+
 /**
  * An utility function to compute the hash of a given string.
  *
@@ -83,7 +116,7 @@ export function average<T extends number>(values: Iterable<T>, weights?: Iterabl
  * @example
  * ```ts
  * hash("Hello, world!"); // -1880044555
- * hash("How are you?"); // 1761539132
+ * hash("How are you?");  // 1761539132
  * ```
  *
  * ---

package/src/utils/random.ts

@@ -259,7 +259,7 @@ export default class Random
 
         if (weights === undefined)
         {
-            const pool = [...elements];
+            const pool = Array.from(elements);
             const result: T[] = new Array(count);
 
             for (let index = 0; index < count; index += 1)
@@ -300,6 +300,131 @@ export default class Random
         return result;
     }
 
+    static #Split(total: number, parts: number): number[]
+    {
+        const cuts: number[] = new Array(parts - 1);
+        for (let index = 0; index < cuts.length; index += 1)
+        {
+            cuts[index] = Math.random() * total;
+        }
+
+        cuts.sort((a, b) => (a - b));
+
+        const boundaries = [0, ...cuts, total];
+        const values: number[] = new Array(parts);
+
+        for (let index = 0; index < parts; index += 1)
+        {
+            values[index] = Math.floor(boundaries[index + 1] - boundaries[index]);
+        }
+
+        let remainder = total - values.reduce((sum, val) => (sum + val), 0);
+        while (remainder > 0)
+        {
+            values[this.Integer(parts)] += 1;
+
+            remainder -= 1;
+        }
+
+        return values;
+    }
+
+    /**
+     * Splits a total amount into a given number of randomly balanced integer parts that sum to the total.
+     *
+     * Uses random cut-points to generate a uniform distribution of parts.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * Random.Split(100, 3); // [28, 41, 31]
+     * Random.Split(10, 4);  // [3, 1, 4, 2]
+     * ```
+     *
+     * ---
+     *
+     * @param total
+     * The total amount to split.
+     *
+     * It must be non-negative. Otherwise, a {@link ValueException} will be thrown.
+     *
+     * @param parts
+     * The number of parts to split the total into.
+     *
+     * It must be at least `1`. Otherwise, a {@link ValueException} will be thrown.
+     *
+     * @returns An array of integers that sum to the given total.
+     */
+    public static Split(total: number, parts: number): number[];
+
+    /**
+     * Splits an iterable of elements into a given number of randomly balanced groups.
+     *
+     * The elements are distributed into groups whose sizes are
+     * determined by a random split of the total number of elements.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * Random.Split([1, 2, 3, 4, 5], 2); // [[1, 2], [3, 4, 5]]
+     * Random.Split([1, 2, 3, 4, 5], 2); // [[1, 2, 3, 4], [5]]
+     * Random.Split("abcdef", 3);        // [["a"], ["b", "c", "d"], ["e", "f"]]
+     * ```
+     *
+     * ---
+     *
+     * @template T The type of the elements in the iterable.
+     *
+     * @param elements
+     * The iterable of elements to split into groups.
+     *
+     * It must contain at least one element. Otherwise, a {@link ValueException} will be thrown.
+     *
+     * @param groups
+     * The number of groups to split the elements into.
+     *
+     * It must be between `1` and the number of elements.
+     * Otherwise, a {@link ValueException} will be thrown.
+     *
+     * @returns An array of arrays, each containing a subset of the original elements.
+     */
+    public static Split<T>(elements: Iterable<T>, groups: number): T[][];
+    public static Split<T>(totalOrElements: number | Iterable<T>, parts: number): number[] | T[][]
+    {
+        if (parts < 1) { throw new ValueException("The number of splits must be greater than zero."); }
+
+        if (typeof totalOrElements === "number")
+        {
+            if (totalOrElements < 0) { throw new ValueException("The total must be a non-negative number."); }
+
+            return this.#Split(totalOrElements, parts);
+        }
+
+        const elements = Array.from(totalOrElements);
+        const length = elements.length;
+
+        if (length === 0) { throw new ValueException("You must provide at least one element."); }
+        if (parts > length)
+        {
+            throw new ValueException("The number of splits cannot exceed the number of elements.");
+        }
+
+        const sizes = this.#Split(length, parts);
+        const groups: T[][] = new Array(parts);
+
+        let offset = 0;
+        for (let index = 0; index < parts; index += 1)
+        {
+            groups[index] = elements.slice(offset, offset + sizes[index]);
+
+            offset += sizes[index];
+        }
+
+        return groups;
+    }
+
     private constructor() { /* ... */ }
 
     public readonly [Symbol.toStringTag]: string = "Random";