imp: Properly implemented MapView & SetView classes.

Author: Byloth

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",
@@ -62,14 +62,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"
   },
-  "packageManager": "pnpm@10.8.1+sha512.c50088ba998c67b8ca8c99df8a5e02fd2ae2e2b29aaf238feaa9e124248d3f48f9fb6db2424949ff901cffbb5e0f0cc1ad6aedb602cd29450751d11c35023677"
+  "packageManager": "pnpm@10.9.0+sha512.0486e394640d3c1fb3c9d43d49cf92879ff74f8516959c235308f5a8f62e2e19528a65cdc2a3058f587cde71eba3d5b56327c8c33a97e4c4051ca48a10ca2d5f"
 }

pnpm-lock.yaml

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

src/index.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.
      *
      * ---
      *

src/models/callbacks/publisher.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.
  *
  * ---

src/models/callbacks/types.ts

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

src/models/collections/index.ts

@@ -1,53 +1,206 @@
 import Publisher from "../callbacks/publisher.js";
-import type { MapViewEventsMap } from "./types.js";
 
-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;
-}
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+import type SetView from "./set-view.js";
+import type { MapViewEventsMap } from "./types.js";
 
-export class MapView<K, V> extends Map<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}.
+ *
+ * ---
+ *
+ * @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(iterable);
+        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("key: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("key: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("map: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";
 }