@byloth/core 2.0.1 → 2.1.0

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

@@ -0,0 +1,206 @@
+import Publisher from "../callbacks/publisher.js";
+
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+import type SetView from "./set-view.js";
+import type { MapViewEventsMap } from "./types.js";
+
+/**
+ * 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}.
+ *
+ * ---
+ *
+ * @example
+ * ```ts
+ * const map = new MapView<string, number>();
+ *
+ * map.subscribe("entry:add", (key: string, value: number) => console.log(`Added ${key}: ${value}`));
+ * map.set("answer", 42); // Added answer: 42
+ * ```
+ *
+ * ---
+ *
+ * @template K The type of the keys in the map.
+ * @template V The type of the values in the map.
+ */
+export default class MapView<K, V> extends Map<K, V>
+{
+    /**
+     * The internal {@link Publisher} instance used to publish events.
+     */
+    protected readonly _publisher: Publisher<MapViewEventsMap<K, V>>;
+
+    /**
+     * Initializes a new instance of the {@link MapView} class.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * const map = new MapView<string, number>([["key1", 2], ["key2", 4], ["key3", 8]]);
+     * ```
+     *
+     * ---
+     *
+     * @param iterable An optional iterable of key-value pairs to initialize the {@link Map} with.
+     */
+    public constructor(iterable?: Iterable<[K, V]> | null)
+    {
+        super();
+
+        this._publisher = new Publisher();
+
+        if (iterable)
+        {
+            for (const [key, value] of iterable) { this.set(key, value); }
+        }
+    }
+
+    /**
+     * Adds a new entry with a specified key and value to the {@link Map}.  
+     * If an entry with the same key already exists, the entry will be overwritten with the new value.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * const map = new MapView<string, number>();
+     * map.set("key1", 2)
+     *     .set("key2", 4)
+     *     .set("key3", 8);
+     *
+     * console.log(map); // MapView { "key1" => 2, "key2" => 4, "key3" => 8 }
+     * ```
+     *
+     * ---
+     *
+     * @param key The key of the entry to add.
+     * @param value The value of the entry to add.
+     *
+     * @returns The current instance of the {@link MapView} class.
+     */
+    public override set(key: K, value: V): this
+    {
+        super.set(key, value);
+
+        this._publisher.publish("entry:add", key, value);
+
+        return this;
+    }
+
+    /**
+     * Removes an entry with a specified key from the {@link Map}.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * const map = new MapView<string, number>([["key1", 2], ["key2", 4], ["key3", 8]]);
+     * map.delete("key2"); // true
+     * map.delete("key4"); // false
+     *
+     * console.log(map); // MapView { "key1" => 2, "key3" => 8 }
+     * ```
+     *
+     * ---
+     *
+     * @param key The key of the entry to remove.
+     *
+     * @returns `true` if the entry existed and has been removed; otherwise `false` if the entry doesn't exist.
+     */
+    public override delete(key: K): boolean
+    {
+        const result = super.delete(key);
+        if (result) { this._publisher.publish("entry:remove", key); }
+
+        return result;
+    }
+
+    /**
+     * Removes all entries from the {@link Map}.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * const map = new MapView<string, number>([["key1", 2], ["key2", 4], ["key3", 8]]);
+     * map.clear();
+     *
+     * console.log(map); // MapView { }
+     * ```
+     */
+    public override clear(): void
+    {
+        const size = this.size;
+
+        super.clear();
+        if (size > 0) { this._publisher.publish("collection:clear"); }
+    }
+
+    /**
+     * Subscribes to an event and adds a callback to be executed when the event is published.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * const map = new MapView<string, number>();
+     * const unsubscribe = map.subscribe("entry:add", (key: string, value: number) =>
+     * {
+     *     if (key === "answer") { unsubscribe(); }
+     *     console.log(`Added ${key}: ${value}`);
+     * });
+     *
+     * map.set("key1", 2); // Added key1: 2
+     * map.set("answer", 42); // Added answer: 42
+     * map.set("key2", 4);
+     * map.set("key3", 8);
+     * ```
+     *
+     * ---
+     *
+     * @template T The key of the map containing the callback signature to subscribe.
+     *
+     * @param event The name of the event to subscribe to.
+     * @param callback The callback to execute when the event is published.
+     *
+     * @returns A function that can be used to unsubscribe the callback from the event.
+     */
+    public subscribe<T extends keyof MapViewEventsMap<K, V>>(event: T, callback: MapViewEventsMap<K, V>[T]): () => void
+    {
+        return this._publisher.subscribe(event, callback);
+    }
+
+    /**
+     * Unsubscribes from an event and removes a callback from being executed when the event is published.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * const callback = (key: string, value: number) => console.log(`Added ${key}: ${value}`);
+     * const map = new MapView<string, number>();
+     *
+     * map.subscribe("entry:add", callback);
+     * map.set("key1", 2); // Added key1: 2
+     *
+     * map.unsubscribe("entry:add", callback);
+     * map.set("key2", 4);
+     * ```
+     *
+     * ---
+     *
+     * @template T The key of the map containing the callback signature to unsubscribe.
+     *
+     * @param event The name of the event to unsubscribe from.
+     * @param callback The callback to remove from the event.
+     */
+    public unsubscribe<T extends keyof MapViewEventsMap<K, V>>(event: T, callback: MapViewEventsMap<K, V>[T]): void
+    {
+        this._publisher.unsubscribe(event, callback);
+    }
+
+    public override readonly [Symbol.toStringTag]: string = "MapView";
+}

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

@@ -0,0 +1,204 @@
+import Publisher from "../callbacks/publisher.js";
+
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+import type MapView from "./map-view.js";
+import type { SetViewEventsMap } from "./types.js";
+
+/**
+ * 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}.
+ *
+ * ---
+ *
+ * @example
+ * ```ts
+ * const set = new SetView<number>();
+ *
+ * set.subscribe("entry:add", (value: number) => console.log(`Added ${value}`));
+ * set.add(42); // Added 42
+ * ```
+ *
+ * ---
+ *
+ * @template T The type of the values in the set.
+ */
+export default class SetView<T> extends Set<T>
+{
+    /**
+     * The internal {@link Publisher} instance used to publish events.
+     */
+    protected readonly _publisher: Publisher<SetViewEventsMap<T>>;
+
+    /**
+     * Initializes a new instance of the {@link SetView} class.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * const set = new SetView<number>([2, 4, 8]);
+     * ```
+     *
+     * ---
+     *
+     * @param iterable An optional iterable of values to initialize the {@link Set} with.
+     */
+    public constructor(iterable?: Iterable<T> | null)
+    {
+        super();
+
+        this._publisher = new Publisher();
+
+        if (iterable)
+        {
+            for (const value of iterable) { this.add(value); }
+        }
+    }
+
+    /**
+     * Appends a new element with a specified value to the end of the {@link Set}.  
+     * If the value already exists, it will not be added again.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * const set = new SetView<number>();
+     * set.add(2)
+     *     .add(4)
+     *     .add(8);
+     *
+     * console.log(set); // SetView(4) { 2, 4, 8 }
+     * ```
+     *
+     * ---
+     *
+     * @param value The value to add.
+     *
+     * @returns The current instance of the {@link SetView} class.
+     */
+    public override add(value: T): this
+    {
+        super.add(value);
+
+        this._publisher.publish("entry:add", value);
+
+        return this;
+    }
+
+    /**
+     * Removes the specified value from the {@link Set}.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * const set = new SetView<number>([2, 4, 8]);
+     * set.delete(4); // true
+     * set.delete(16); // false
+     *
+     * console.log(set); // SetView(2) { 2, 8 }
+     * ```
+     *
+     * ---
+     *
+     * @param value The value to remove.
+     *
+     * @returns `true` if the entry existed and has been removed; otherwise `false` if the entry doesn't exist.
+     */
+    public override delete(value: T): boolean
+    {
+        const result = super.delete(value);
+        if (result) { this._publisher.publish("entry:remove", value); }
+
+        return result;
+    }
+
+    /**
+     * Removes all entries from the {@link Set}.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * const set = new SetView<number>([2, 4, 8]);
+     * set.clear();
+     *
+     * console.log(set); // SetView(0) { }
+     * ```
+     */
+    public override clear(): void
+    {
+        const size = this.size;
+
+        super.clear();
+        if (size > 0) { this._publisher.publish("collection:clear"); }
+    }
+
+    /**
+     * Subscribes to an event and adds a callback to be executed when the event is published.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * const set = new SetView<number>();
+     * const unsubscribe = set.subscribe("entry:add", (value: number) =>
+     * {
+     *     if (value === 42) { unsubscribe(); }
+     *     console.log(`Added ${value}`);
+     * });
+     *
+     * set.add(2); // Added 2
+     * set.add(42); // Added 42
+     * set.add(4);
+     * set.add(8);
+     * ```
+     *
+     * ---
+     *
+     * @template K The key of the map containing the callback signature to subscribe.
+     *
+     * @param event The name of the event to subscribe to.
+     * @param callback The callback to execute when the event is published.
+     *
+     * @returns A function that can be used to unsubscribe the callback from the event.
+     */
+    public subscribe<K extends keyof SetViewEventsMap<T>>(event: K, callback: SetViewEventsMap<T>[K]): () => void
+    {
+        return this._publisher.subscribe(event, callback);
+    }
+
+    /**
+     * Unsubscribes from an event and removes a callback from being executed when the event is published.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * const callback = (value: number) => console.log(`Added ${value}`);
+     * const set = new SetView<number>();
+     *
+     * set.subscribe("entry:add", callback);
+     * set.add(2); // Added 2
+     *
+     * set.unsubscribe("entry:add", callback);
+     * set.add(4);
+     * ```
+     *
+     * ---
+     *
+     * @template K The key of the map containing the callback signature to unsubscribe.
+     *
+     * @param event The name of the event to unsubscribe from.
+     * @param callback The callback to remove from the event.
+     */
+    public unsubscribe<K extends keyof SetViewEventsMap<T>>(event: K, callback: SetViewEventsMap<T>[K]): void
+    {
+        this._publisher.unsubscribe(event, callback);
+    }
+
+    public override readonly [Symbol.toStringTag]: string = "SetView";
+}

package/src/models/collections/types.ts

@@ -0,0 +1,25 @@
+export interface MapViewEventsMap<K, V>
+{
+    "entry:add": (key: K, value: V) => void;
+    "entry:remove": (key: K) => void;
+
+    "collection:clear": () => void;
+}
+export interface ReadonlyMapView<K, V> extends ReadonlyMap<K, V>
+{
+    subscribe<T extends keyof MapViewEventsMap<K, V>>(event: T, callback: MapViewEventsMap<K, V>[T]): () => void;
+    unsubscribe<T extends keyof MapViewEventsMap<K, V>>(event: T, callback: MapViewEventsMap<K, V>[T]): void;
+}
+
+export interface SetViewEventsMap<T>
+{
+    "entry:add": (value: T) => void;
+    "entry:remove": (value: T) => void;
+
+    "collection:clear": () => void;
+}
+export interface ReadonlySetView<T> extends ReadonlySet<T>
+{
+    subscribe<K extends keyof SetViewEventsMap<T>>(event: K, callback: SetViewEventsMap<T>[K]): () => void;
+    unsubscribe<K extends keyof SetViewEventsMap<T>>(event: K, callback: SetViewEventsMap<T>[K]): void;
+}

package/src/models/exceptions/core.ts

@@ -1,10 +1,13 @@
 /**
- * A class representing an exception, subclass of the native `Error` class.  
+ * A class representing an exception, subclass of the native {@link Error} class.  
  * It's the base class for any other further exception.
  *
  * It allows to chain exceptions together, tracking the initial cause of an error and
  * storing its stack trace while providing a clear and friendly message to the user.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * try { loadGameSaves(); }
  * catch (error)
@@ -109,6 +112,9 @@ export default class Exception extends Error
  *
  * It provides a clear and friendly message by default.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * function checkCase(value: "A" | "B" | "C"): 1 | 2 | 3
  * {
@@ -160,6 +166,9 @@ export class FatalErrorException extends Exception
  *
  * It provides a clear and friendly message by default.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * class Database
  * {

package/src/models/exceptions/index.ts

@@ -6,6 +6,9 @@ import Exception from "./core.js";
  *
  * It can also be used to catch all file-related exceptions at once.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * try { [...] }
  * catch (error)
@@ -46,6 +49,9 @@ export class FileException extends Exception
 /**
  * A class representing an exception that can be thrown when a file already exists.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * import { existsSync } from "node:fs";
  *
@@ -84,6 +90,9 @@ export class FileExistsException extends FileException
 /**
  * A class representing an exception that can be thrown when a file isn't found.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * import { existsSync } from "node:fs";
  *
@@ -123,6 +132,9 @@ export class FileNotFoundException extends FileException
  * A class representing an exception that can be thrown when a key is invalid or not found.  
  * It's commonly used when working with dictionaries, maps, objects, sets, etc...
  *
+ * ---
+ *
+ * @example
  * ```ts
  * const map = new Map<string, number>();
  * if (!map.has("hash"))
@@ -161,6 +173,9 @@ export class KeyException extends Exception
  * A class representing an exception that can be thrown when a network operation fails.  
  * It's commonly used when it's unable to connect to a server or when a request times out.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * import axios, { isAxiosError } from "axios";
  *
@@ -205,8 +220,11 @@ export class NetworkException extends Exception
 
 /**
  * A class representing an exception that can be thrown when a permission is denied.  
- * It's commonly used when a user tries to access a restricted resource or perform a forbidden action.
+ * It's commonly used when an user tries to access a restricted resource or perform a forbidden action.
+ *
+ * ---
  *
+ * @example
  * ```ts
  * const $user = useUserStore();
  * if (!$user.isAdmin)
@@ -245,6 +263,9 @@ export class PermissionException extends Exception
  * A class representing an exception that can be thrown when a reference is invalid or not found.  
  * It's commonly used when a variable is `null`, `undefined` or when an object doesn't exist.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * const $el = document.getElementById("app");
  * if ($el === null)
@@ -283,6 +304,9 @@ export class ReferenceException extends Exception
  * A class representing an exception that can be thrown when a runtime error occurs.  
  * It's commonly used when an unexpected condition is encountered during the execution of a program.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * let status: "enabled" | "disabled" = "enabled";
  *
@@ -324,6 +348,9 @@ export class RuntimeException extends Exception
  * isn't properly configured or when a required variable isn't set.  
  * It can also be used when the environment on which the program is running is unsupported.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * if (!navigator.geolocation)
  * {
@@ -361,6 +388,9 @@ export class EnvironmentException extends RuntimeException
  * A class representing an exception that can be thrown when a timeout occurs.  
  * It's commonly used when a task takes too long to complete or when a request times out.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * const timeoutId = setTimeout(() => { throw new TimeoutException("The request timed out."); }, 5_000);
  * const response = await fetch("https://api.example.com/data");
@@ -398,6 +428,9 @@ export class TimeoutException extends Exception
  * A class representing an exception that can be thrown when a type is invalid or not supported.  
  * It's commonly used when a function receives an unexpected type of argument.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * function greet(name: string): void
  * {
@@ -438,6 +471,9 @@ export class TypeException extends Exception
  * A class representing an exception that can be thrown when a value is invalid.  
  * It's commonly used when a function receives an unexpected value as an argument.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * function setVolume(value: number): void
  * {
@@ -478,6 +514,9 @@ export class ValueException extends Exception
  * A class representing an exception that can be thrown when a value is out of range.  
  * It's commonly used when a function receives an unexpected value as an argument.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * function setVolume(value: number): void
  * {

package/src/models/index.ts

@@ -6,6 +6,7 @@ export {
 } from "./aggregators/index.js";
 
 export { CallableObject, Publisher, SwitchableCallback } from "./callbacks/index.js";
+export { MapView, SetView } from "./collections/index.js";
 export {
     Exception,
     FatalErrorException,

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

@@ -26,6 +26,9 @@ import type {
  * This allows to chain multiple transformations without
  * the need to iterate over the elements multiple times.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * const result = new SmartAsyncIterator<number>(["-5", "-4", "-3", "-2", "-1", "0", "1", "2", "3", "4", "5"])
  *     .map((value) => Number(value))
@@ -37,6 +40,8 @@ import type {
  * console.log(await result); // 31
  * ```
  *
+ * ---
+ *
  * @template T The type of elements in the iterator.
  * @template R The type of the final result of the iterator. Default is `void`.
  * @template N The type of the argument passed to the `next` method. Default is `undefined`.

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

@@ -17,6 +17,9 @@ import type { GeneratorFunction, Iteratee, TypeGuardPredicate, Reducer, Iterator
  * This allows to chain multiple transformations without
  * the need to iterate over the elements multiple times.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * const result = new SmartIterator<number>(["-5", "-4", "-3", "-2", "-1", "0", "1", "2", "3", "4", "5"])
  *     .map(Number)
@@ -28,6 +31,8 @@ import type { GeneratorFunction, Iteratee, TypeGuardPredicate, Reducer, Iterator
  * console.log(result); // 31
  * ```
  *
+ * ---
+ *
  * @template T The type of elements in the iterator.
  * @template R The type of the final result of the iterator. Default is `void`.
  * @template N The type of the argument required by the `next` method. Default is `undefined`.