@byloth/core 2.2.3 → 2.2.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byloth/core",
-  "version": "2.2.3",
+  "version": "2.2.5",
   "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": "^9.39.2",
+    "@eslint/compat": "^2.0.3",
+    "@types/node": "^22.19.15",
+    "@vitest/coverage-v8": "^4.0.18",
+    "eslint": "^9.39.4",
     "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.5";
 
 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,
@@ -85,6 +87,7 @@ export type {
 
 export {
     average,
+    clamp,
     capitalize,
     chain,
     count,

package/src/models/callbacks/callback-chain.ts

@@ -16,9 +16,9 @@ import type { Callback } from "./types.js";
  *     .add(() => console.log("Doing something else..."))
  *     .add(() => console.log("Doing yet another thing..."));
  *
- * unsubscribeAll();  // Doing something...
- *                    // Doing something else...
- *                    // Doing yet another thing...
+ * unsubscribeAll(); // Doing something...
+ *                   // Doing something else...
+ *                   // Doing yet another thing...
  * ```
  *
  * ---

package/src/models/callbacks/publisher.ts

@@ -87,7 +87,7 @@ export default class Publisher<T extends CallbackMap<T> = CallbackMap>
      * context.subscribe("player:spawn", () => console.log("Player has spawned."));
      *
      * publisher.publish("player:spawn"); // "Player has spawned."
-     * context.publish("player:death"); // * no output *
+     * context.publish("player:death");   // * no output *
      * ```
      *
      * ---

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); }
         }
     }
 
@@ -160,7 +162,7 @@ export default class MapView<K, V> extends Map<K, V>
      * ```ts
      * map.onAdd((key, value) => console.log(`Added ${key}: ${value}`));
      *
-     * map.set("key1", 2); // "Added key1: 2"
+     * map.set("key1", 2);    // "Added key1: 2"
      * map.set("answer", 42); // "Added answer: 42"
      * ```
      *
@@ -184,7 +186,7 @@ export default class MapView<K, V> extends Map<K, V>
      * ```ts
      * map.onRemove((key, value) => console.log(`Removed ${key}: ${value}`));
      *
-     * map.delete("key1"); // "Removed key1: 2"
+     * map.delete("key1");   // "Removed key1: 2"
      * map.delete("answer"); // "Removed answer: 42"
      * ```
      *

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 }
      * ```
      *
      * ---
@@ -104,7 +106,7 @@ export default class SetView<T> extends Set<T>
      * @example
      * ```ts
      * const set = new SetView<number>([2, 4, 8]);
-     * set.delete(4); // true
+     * set.delete(4);  // true
      * set.delete(16); // false
      *
      * console.log(set); // SetView(2) { 2, 8 }
@@ -154,7 +156,7 @@ export default class SetView<T> extends Set<T>
      * ```ts
      * set.onAdd((value) => console.log(`Added ${value}`));
      *
-     * set.add(2); // "Added 2"
+     * set.add(2);  // "Added 2"
      * set.add(42); // "Added 42"
      * ```
      *
@@ -178,7 +180,7 @@ export default class SetView<T> extends Set<T>
      * ```ts
      * set.onRemove((value) => console.log(`Removed ${value}`));
      *
-     * set.delete(2); // "Removed 2"
+     * set.delete(2);  // "Removed 2"
      * set.delete(42); // "Removed 42"
      * ```
      *

package/src/models/collections/types.ts

@@ -29,7 +29,7 @@ export interface ReadonlyMapView<K, V> extends ReadonlyMap<K, V>
      * ```ts
      * map.onAdd((key, value) => console.log(`Added ${key}: ${value}`));
      *
-     * map.set("key1", 2); // "Added key1: 2"
+     * map.set("key1", 2);    // "Added key1: 2"
      * map.set("answer", 42); // "Added answer: 42"
      * ```
      *
@@ -50,7 +50,7 @@ export interface ReadonlyMapView<K, V> extends ReadonlyMap<K, V>
      * ```ts
      * map.onRemove((key, value) => console.log(`Removed ${key}: ${value}`));
      *
-     * map.delete("key1"); // "Removed key1: 2"
+     * map.delete("key1");   // "Removed key1: 2"
      * map.delete("answer"); // "Removed answer: 42"
      * ```
      *
@@ -104,7 +104,7 @@ export interface ReadonlySetView<T> extends ReadonlySet<T>
      * ```ts
      * set.onAdd((value) => console.log(`Added ${value}`));
      *
-     * set.add(2); // "Added 2"
+     * set.add(2);  // "Added 2"
      * set.add(42); // "Added 42"
      * ```
      *
@@ -125,7 +125,7 @@ export interface ReadonlySetView<T> extends ReadonlySet<T>
      * ```ts
      * set.onRemove((value) => console.log(`Removed ${value}`));
      *
-     * set.delete(2); // "Removed 2"
+     * set.delete(2);  // "Removed 2"
      * set.delete(42); // "Removed 42"
      * ```
      *

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/models/iterators/smart-async-iterator.ts

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