@byloth/core 2.2.3 → 2.2.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byloth/core",
-  "version": "2.2.3",
+  "version": "2.2.4",
   "description": "An unopinionated collection of useful functions and classes that I use widely in all my projects. 🔧",
   "keywords": [
     "Core",
@@ -50,15 +50,15 @@
   "types": "src/index.ts",
   "devDependencies": {
     "@byloth/eslint-config-typescript": "^3.2.2",
-    "@eslint/compat": "^2.0.0",
-    "@types/node": "^22.19.3",
-    "@vitest/coverage-v8": "^4.0.16",
+    "@eslint/compat": "^2.0.2",
+    "@types/node": "^22.19.11",
+    "@vitest/coverage-v8": "^4.0.18",
     "eslint": "^9.39.2",
     "husky": "^9.1.7",
     "jsdom": "^27.4.0",
     "typescript": "^5.9.3",
-    "vite": "^7.3.0",
-    "vitest": "^4.0.16"
+    "vite": "^7.3.1",
+    "vitest": "^4.0.18"
   },
   "scripts": {
     "dev": "vite",

package/src/index.ts

@@ -1,4 +1,4 @@
-export const VERSION = "2.2.3";
+export const VERSION = "2.2.4";
 
 export type { Constructor, Interval, Timeout, ValueOf } from "./core/types.js";
 
@@ -6,6 +6,7 @@ export { isBrowser, isNode, isWorker } from "./helpers.js";
 export {
     AggregatedIterator,
     AggregatedAsyncIterator,
+    ArrayView,
     CallableObject,
     CallbackChain,
     Clock,
@@ -29,6 +30,7 @@ export {
     RangeException,
     ReducedIterator,
     ReferenceException,
+    ResponseException,
     RuntimeException,
     SetView,
     SmartIterator,

package/src/models/collections/array-view.ts

@@ -0,0 +1,348 @@
+import Publisher from "../callbacks/publisher.js";
+import type { Callback } from "../types.js";
+
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+import type MapView from "./map-view.js";
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+import type SetView from "./set-view.js";
+
+interface ArrayViewEventsMap<T>
+{
+    "add": (value: T, index: number) => void;
+    "remove": (value: T, index: number) => void;
+
+    "clear": () => void;
+}
+
+/**
+ * A wrapper class around the native {@link Array} class that provides additional functionality
+ * for publishing events when entries are added, removed or the collection is cleared.
+ * There are also complementary classes that work with the native `Map` and `Set` classes.
+ * See also {@link MapView} and {@link SetView}.
+ *
+ * ---
+ *
+ * @example
+ * ```ts
+ * const array = new ArrayView<number>();
+ *
+ * array.onAdd((value: number, index: number) => console.log(`Added ${value} at index ${index}`));
+ * array.push(42); // "Added 42 at index 0"
+ * ```
+ *
+ * ---
+ *
+ * @template T The type of the values in the array.
+ */
+export default class ArrayView<T> extends Array<T>
+{
+    /**
+     * The internal {@link Publisher} instance used to publish events.
+     */
+    protected readonly _publisher: Publisher<ArrayViewEventsMap<T>>;
+
+    /**
+     * Initializes a new instance of the {@link ArrayView} class.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * const array = new ArrayView<number>();
+     * ```
+     */
+    public constructor();
+
+    /**
+     * Initializes a new instance of the {@link ArrayView} class.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * const array = new ArrayView<number>(3);
+     * ```
+     *
+     * ---
+     *
+     * @param length The initial length of the {@link Array}.
+     */
+    public constructor(length: number);
+
+    /**
+     * Initializes a new instance of the {@link ArrayView} class.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * const array = new ArrayView<number>(2, 4, 8);
+     * ```
+     *
+     * ---
+     *
+     * @param items The items to initialize the {@link Array} with.
+     */
+    public constructor(...items: T[]);
+    public constructor(...items: T[])
+    {
+        super(...items);
+
+        this._publisher = new Publisher();
+    }
+
+    /**
+     * Appends new elements to the end of the {@link Array} and returns the new length of the array.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * const array = new ArrayView<number>();
+     * array.push(2, 4, 8);
+     *
+     * console.log(array); // ArrayView(3) [2, 4, 8]
+     * ```
+     *
+     * ---
+     *
+     * @param items New elements to add to the array.
+     *
+     * @returns The new length of the array.
+     */
+    public override push(...items: T[]): number
+    {
+        const startIndex = this.length;
+
+        const result = super.push(...items);
+        for (let i = 0; i < items.length; i += 1)
+        {
+            this._publisher.publish("add", items[i], startIndex + i);
+        }
+
+        return result;
+    }
+
+    /**
+     * Removes the last element from the {@link Array} and returns it.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * const array = new ArrayView<number>(2, 4, 8);
+     * array.pop(); // 8
+     *
+     * console.log(array); // ArrayView(2) [2, 4]
+     * ```
+     *
+     * ---
+     *
+     * @returns The removed element, or `undefined` if the array is empty.
+     */
+    public override pop(): T | undefined
+    {
+        const index = this.length - 1;
+        if (index < 0) { return undefined; }
+
+        const value = super.pop();
+        this._publisher.publish("remove", value!, index);
+
+        return value;
+    }
+
+    /**
+     * Removes the first element from the {@link Array} and returns it.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * const array = new ArrayView<number>(2, 4, 8);
+     * array.shift(); // 2
+     *
+     * console.log(array); // ArrayView(2) [4, 8]
+     * ```
+     *
+     * ---
+     *
+     * @returns The removed element, or `undefined` if the array is empty.
+     */
+    public override shift(): T | undefined
+    {
+        if (this.length === 0) { return undefined; }
+
+        const value = super.shift();
+        this._publisher.publish("remove", value!, 0);
+
+        return value;
+    }
+
+    /**
+     * Inserts new elements at the start of the {@link Array} and returns the new length of the array.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * const array = new ArrayView<number>(4, 8);
+     * array.unshift(2);
+     *
+     * console.log(array); // ArrayView(3) [2, 4, 8]
+     * ```
+     *
+     * ---
+     *
+     * @param items Elements to insert at the start of the array.
+     *
+     * @returns The new length of the array.
+     */
+    public override unshift(...items: T[]): number
+    {
+        const result = super.unshift(...items);
+        for (let i = 0; i < items.length; i += 1)
+        {
+            this._publisher.publish("add", items[i], i);
+        }
+
+        return result;
+    }
+
+    /**
+     * Removes elements from the {@link Array} and, if necessary, inserts new elements in their place,
+     * returning the deleted elements.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * const array = new ArrayView<number>(2, 4, 8, 16);
+     * array.splice(1, 2, 32, 64); // [4, 8]
+     *
+     * console.log(array); // ArrayView(4) [2, 32, 64, 16]
+     * ```
+     *
+     * ---
+     *
+     * @param start The zero-based location in the array from which to start removing elements.
+     * @param deleteCount The number of elements to remove.
+     * @param items Elements to insert into the array in place of the deleted elements.
+     *
+     * @returns An array containing the elements that were deleted.
+     */
+    public override splice(start: number, deleteCount?: number, ...items: T[]): T[]
+    {
+        const normalizedStart = start < 0 ? Math.max(this.length + start, 0) : Math.min(start, this.length);
+
+        const actualDeleteCount = deleteCount === undefined ?
+            this.length - normalizedStart :
+            Math.min(Math.max(deleteCount, 0), this.length - normalizedStart);
+
+        const removed = super.splice(start, actualDeleteCount, ...items);
+        for (let i = 0; i < removed.length; i += 1)
+        {
+            this._publisher.publish("remove", removed[i], normalizedStart + i);
+        }
+
+        for (let i = 0; i < items.length; i += 1)
+        {
+            this._publisher.publish("add", items[i], normalizedStart + i);
+        }
+
+        return removed;
+    }
+
+    /**
+     * Removes all elements from the {@link Array}.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * const array = new ArrayView<number>(2, 4, 8);
+     * array.clear();
+     *
+     * console.log(array); // ArrayView(0) []
+     * ```
+     */
+    public clear(): void
+    {
+        const length = this.length;
+        this.length = 0;
+
+        if (length > 0) { this._publisher.publish("clear"); }
+    }
+
+    /**
+     * Subscribes to the `add` event of the array with a callback that will be executed when an element is added.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * array.onAdd((value, index) => console.log(`Added ${value} at index ${index}`));
+     *
+     * array.push(2); // "Added 2 at index 0"
+     * array.push(42); // "Added 42 at index 1"
+     * ```
+     *
+     * ---
+     *
+     * @param callback The callback that will be executed when an element is added to the array.
+     *
+     * @returns A function that can be used to unsubscribe from the event.
+     */
+    public onAdd(callback: (value: T, index: number) => void): Callback
+    {
+        return this._publisher.subscribe("add", callback);
+    }
+
+    /**
+     * Subscribes to the `remove` event of the array with a callback that will be executed when an element is removed.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * array.onRemove((value, index) => console.log(`Removed ${value} at index ${index}`));
+     *
+     * array.pop(); // "Removed 8 at index 2"
+     * array.shift(); // "Removed 2 at index 0"
+     * ```
+     *
+     * ---
+     *
+     * @param callback The callback that will be executed when an element is removed from the array.
+     *
+     * @returns A function that can be used to unsubscribe from the event.
+     */
+    public onRemove(callback: (value: T, index: number) => void): Callback
+    {
+        return this._publisher.subscribe("remove", callback);
+    }
+
+    /**
+     * Subscribes to the `clear` event of the array with a callback that will be executed when the array is cleared.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * array.onClear(() => console.log("The array has been cleared."));
+     * array.clear(); // "The array has been cleared."
+     * ```
+     *
+     * ---
+     *
+     * @param callback The callback that will be executed when the array is cleared.
+     *
+     * @returns A function that can be used to unsubscribe from the event.
+     */
+    public onClear(callback: () => void): Callback
+    {
+        return this._publisher.subscribe("clear", callback);
+    }
+
+    public readonly [Symbol.toStringTag]: string = "ArrayView";
+    public static override readonly [Symbol.species]: typeof Array = Array;
+}

package/src/models/collections/index.ts

@@ -1,2 +1,3 @@
+export { default as ArrayView } from "./array-view.js";
 export { default as MapView } from "./map-view.js";
 export { default as SetView } from "./set-view.js";

package/src/models/collections/map-view.ts

@@ -1,6 +1,8 @@
 import Publisher from "../callbacks/publisher.js";
 import type { Callback } from "../types.js";
 
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+import type ArrayView from "./array-view.js";
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
 import type SetView from "./set-view.js";
 
@@ -15,8 +17,8 @@ interface MapViewEventsMap<K, V>
 /**
  * A wrapper class around the native {@link Map} class that provides additional functionality
  * for publishing events when entries are added, removed or the collection is cleared.  
- * There's also a complementary class that works with the native `Set` class.
- * See also {@link SetView}.
+ * There are also complementary classes that work with the native `Array` and `Set` classes.
+ * See also {@link ArrayView} and {@link SetView}.
  *
  * ---
  *
@@ -62,7 +64,7 @@ export default class MapView<K, V> extends Map<K, V>
 
         if (iterable)
         {
-            for (const [key, value] of iterable) { this.set(key, value); }
+            for (const [key, value] of iterable) { super.set(key, value); }
         }
     }
 

package/src/models/collections/set-view.ts

@@ -1,6 +1,8 @@
 import Publisher from "../callbacks/publisher.js";
 import type { Callback } from "../types.js";
 
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+import type ArrayView from "./array-view.js";
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
 import type MapView from "./map-view.js";
 
@@ -15,8 +17,8 @@ interface SetViewEventsMap<T>
 /**
  * A wrapper class around the native {@link Set} class that provides additional functionality
  * for publishing events when entries are added, removed or the collection is cleared.  
- * There's also a complementary class that works with the native `Map` class.
- * See also {@link MapView}.
+ * There are also complementary classes that work with the native `Array` and `Map` classes.
+ * See also {@link ArrayView} and {@link MapView}.
  *
  * ---
  *
@@ -61,7 +63,7 @@ export default class SetView<T> extends Set<T>
 
         if (iterable)
         {
-            for (const value of iterable) { this.add(value); }
+            for (const value of iterable) { super.add(value); }
         }
     }
 
@@ -78,7 +80,7 @@ export default class SetView<T> extends Set<T>
      *     .add(4)
      *     .add(8);
      *
-     * console.log(set); // SetView(4) { 2, 4, 8 }
+     * console.log(set); // SetView(3) { 2, 4, 8 }
      * ```
      *
      * ---

package/src/models/exceptions/index.ts

@@ -177,18 +177,14 @@ export class KeyException extends Exception
  *
  * @example
  * ```ts
- * import axios, { isAxiosError } from "axios";
- *
- * try { await axios.get("https://api.example.com/data"); }
+ * try { await fetch("https://api.example.com/data"); }
  * catch (error)
  * {
- *     if (isAxiosError(error) && !error.response)
- *     {
- *         throw new NetworkException(
- *             "Unable to establish a connection to the server. " +
- *             "Please, check your internet connection and try again."
- *         );
- *     }
+ *     throw new NetworkException(
+ *         "Unable to establish a connection to the server. " +
+ *         "Please, check your internet connection and try again.",
+ *         error
+ *     );
  * }
  * ```
  */
@@ -218,6 +214,51 @@ export class NetworkException extends Exception
     public override readonly [Symbol.toStringTag]: string = "NetworkException";
 }
 
+/**
+ * A class representing an exception that can be thrown when a response is not valid or fails.  
+ * It's commonly used when a request returns an error status code or when the response body is malformed.
+ *
+ * ---
+ *
+ * @example
+ * ```ts
+ * const response = await fetch("https://api.example.com/data");
+ * if (!response.ok)
+ * {
+ *     throw new ResponseException(response);
+ * }
+ * ```
+ */
+export class ResponseException extends NetworkException
+{
+    public readonly response: Response;
+
+    /**
+     * Initializes a new instance of the {@link ResponseException} class.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * throw new ResponseException(response);
+     * ```
+     *
+     * ---
+     *
+     * @param response The response that caused the error.
+     * @param cause The previous caught error that caused this one, if any.
+     * @param name The name of the exception. Default is `"ResponseException"`.
+     */
+    public constructor(response: Response, cause?: unknown, name = "ResponseException")
+    {
+        super(`The request failed with the status code ${response.status} (${response.statusText}).`, cause, name);
+
+        this.response = response;
+    }
+
+    public override readonly [Symbol.toStringTag]: string = "ResponseException";
+}
+
 /**
  * A class representing an exception that can be thrown when a permission is denied.  
  * It's commonly used when an user tries to access a restricted resource or perform a forbidden action.

package/src/models/index.ts

@@ -6,7 +6,7 @@ export {
 } from "./aggregators/index.js";
 
 export { CallableObject, CallbackChain, Publisher, SwitchableCallback } from "./callbacks/index.js";
-export { MapView, SetView } from "./collections/index.js";
+export { ArrayView, MapView, SetView } from "./collections/index.js";
 export {
     Exception,
     FatalErrorException,
@@ -20,6 +20,7 @@ export {
     PermissionException,
     RangeException,
     ReferenceException,
+    ResponseException,
     RuntimeException,
     TimeoutException,
     TypeException,

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";