@byloth/core 2.0.2 → 2.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byloth/core",
-  "version": "2.0.2",
+  "version": "2.1.0",
   "description": "An unopinionated collection of useful functions and classes that I use widely in all my projects. 🔧",
   "keywords": [
     "Core",
@@ -32,16 +32,18 @@
     "src"
   ],
   "main": "dist/core.umd.cjs",
-  "module": "dist/core.js",
+  "module": "dist/core.cjs",
+  "unpkg": "dist/core.global.js",
+  "jsdelivr": "dist/core.global.js",
   "exports": {
     ".": {
       "import": {
         "types": "./src/index.ts",
-        "default": "./dist/core.js"
+        "default": "./dist/core.esm.js"
       },
       "require": {
         "types": "./src/index.ts",
-        "default": "./dist/core.umd.cjs"
+        "default": "./dist/core.cjs"
       }
     }
   },
@@ -49,14 +51,14 @@
   "devDependencies": {
     "@byloth/eslint-config-typescript": "^3.1.0",
     "@eslint/compat": "^1.2.8",
-    "@types/node": "^22.14.1",
-    "@vitest/coverage-v8": "^3.1.1",
-    "eslint": "^9.25.0",
+    "@types/node": "^22.15.2",
+    "@vitest/coverage-v8": "^3.1.2",
+    "eslint": "^9.25.1",
     "husky": "^9.1.7",
     "jsdom": "^26.1.0",
     "typescript": "^5.8.3",
-    "vite": "^6.3.2",
-    "vitest": "^3.1.1"
+    "vite": "^6.3.3",
+    "vitest": "^3.1.2"
   },
   "scripts": {
     "dev": "vite",

package/src/index.ts

@@ -1,4 +1,4 @@
-export const VERSION = "2.0.2";
+export const VERSION = "2.1.0";
 
 export type { Constructor, Interval, Timeout, ValueOf } from "./core/types.js";
 
@@ -20,6 +20,7 @@ export {
     GameLoop,
     JSONStorage,
     KeyException,
+    MapView,
     NotImplementedException,
     NetworkException,
     PermissionException,
@@ -28,6 +29,7 @@ export {
     ReducedIterator,
     ReferenceException,
     RuntimeException,
+    SetView,
     SmartIterator,
     SmartAsyncIterator,
     SmartPromise,
@@ -58,6 +60,7 @@ export type {
     KeyedIteratee,
     KeyedReducer,
     KeyedTypeGuardPredicate,
+    MapViewEventsMap,
     MaybeAsyncKeyedIteratee,
     MaybeAsyncKeyedReducer,
     MaybeAsyncGeneratorFunction,
@@ -68,8 +71,11 @@ export type {
     PromiseExecutor,
     PromiseRejecter,
     PromiseResolver,
+    ReadonlyMapView,
+    ReadonlySetView,
     Reducer,
     RejectedHandler,
+    SetViewEventsMap,
     TypeGuardPredicate
 
 } from "./models/types.js";

package/src/models/callbacks/publisher.ts

@@ -123,7 +123,7 @@ export default class Publisher<T extends CallbackMap<T> = CallbackMap>
     }
 
     /**
-     * Subscribes a new subscriber to an event.
+     * Subscribes to an event and adds a subscriber to be executed when the event is published.
      *
      * ---
      *
@@ -142,9 +142,9 @@ export default class Publisher<T extends CallbackMap<T> = CallbackMap>
      * @template K The key of the map containing the callback signature to subscribe.
      *
      * @param event The name of the event to subscribe to.
-     * @param subscriber The subscriber to add to the event.
+     * @param subscriber The subscriber to execute when the event is published.
      *
-     * @returns A function that can be used to unsubscribe the subscriber.
+     * @returns A function that can be used to unsubscribe the subscriber from the event.
      */
     public subscribe<K extends keyof T>(event: K & string, subscriber: T[K]): () => void
     {
@@ -167,7 +167,7 @@ export default class Publisher<T extends CallbackMap<T> = CallbackMap>
     }
 
     /**
-     * Unsubscribes a subscriber from an event.
+     * Unsubscribes from an event and removes a subscriber from being executed when the event is published.
      *
      * ---
      *

package/src/models/callbacks/types.ts

@@ -1,3 +1,6 @@
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+import type Publisher from "./publisher.js";
+
 /**
  * A type that represents a generic function.
  *
@@ -24,7 +27,7 @@ export type Callback<A extends unknown[] = [], R = void> = (...args: A) => R;
 /**
  * An utility type that is required to represents a map of callbacks.
  *
- * It is used for type inheritance on the `Publisher` class signature.  
+ * It is used for type inheritance on the {@link Publisher} class signature.  
  * Whenever you'll need to extend that class, you may need to use this type too.
  *
  * ---

package/src/models/collections/index.ts

@@ -0,0 +1,4 @@
+import MapView from "./map-view.js";
+import SetView from "./set-view.js";
+
+export { MapView, SetView };

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,5 +1,5 @@
 /**
- * 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

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/json/json-storage.ts

@@ -4,7 +4,7 @@ import { EnvironmentException } from "../exceptions/index.js";
 import type { JSONValue } from "./types.js";
 
 /**
- * A wrapper around the `Storage` API to better store and easily retrieve
+ * A wrapper around the {@link Storage} API to better store and easily retrieve
  * typed JSON values using the classical key-value pair storage system.
  *
  * It allows to handle either the volatile {@link sessionStorage} or the persistent

package/src/models/types.ts

@@ -9,6 +9,7 @@ export type {
 
 } from "./aggregators/types.js";
 
+export type { MapViewEventsMap, ReadonlyMapView, SetViewEventsMap, ReadonlySetView } from "./collections/types.js";
 export type {
     GeneratorFunction,
     AsyncGeneratorFunction,
@@ -26,13 +27,7 @@ export type {
 
 } from "./iterators/types.js";
 
-export type {
-    JSONArray,
-    JSONObject,
-    JSONValue
-
-} from "./json/types.js";
-
+export type { JSONArray, JSONObject, JSONValue } from "./json/types.js";
 export type {
     MaybePromise,
     FulfilledHandler,

package/src/utils/iterator.ts

@@ -43,7 +43,7 @@ export function chain<T>(...iterables: readonly 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 isn't an {@link Array}, it will be consumed entirely in the process.
  * - If the iterable is an infinite generator, the function will never return.
  *
  * ---
@@ -213,8 +213,8 @@ export function range(start: number, end?: number, step = 1): SmartIterator<numb
  * 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 {@link Array}, it won't be modified since the shuffling isn't done in-place.
+ * - If the iterable isn't an {@link Array}, it will be consumed entirely in the process.
  * - If the iterable is an infinite generator, the function will never return.
  *
  * ---