@byloth/core 2.0.2 → 2.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byloth/core",
-  "version": "2.0.2",
+  "version": "2.1.1",
   "description": "An unopinionated collection of useful functions and classes that I use widely in all my projects. 🔧",
   "keywords": [
     "Core",
@@ -32,31 +32,33 @@
     "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"
       }
     }
   },
   "types": "src/index.ts",
   "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",
+    "@eslint/compat": "^1.2.9",
+    "@types/node": "^22.15.18",
+    "@vitest/coverage-v8": "^3.1.3",
+    "eslint": "^9.26.0",
     "husky": "^9.1.7",
     "jsdom": "^26.1.0",
     "typescript": "^5.8.3",
-    "vite": "^6.3.2",
-    "vitest": "^3.1.1"
+    "vite": "^6.3.5",
+    "vitest": "^3.1.3"
   },
   "scripts": {
     "dev": "vite",

package/src/core/types.ts

@@ -10,9 +10,14 @@
  *
  * const instance: MyObject = factory(MyObject);
  * ```
+ *
+ * ---
+ *
+ * @template T The type of the instance to create. Default is `object`.
+ * @template P The type of the constructor parameters. Default is `any[]`.
  */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-export type Constructor<T extends object, P extends unknown[] = any[]> = new (...args: P) => T;
+export type Constructor<T extends object = object, P extends unknown[] = any[]> = new (...args: P) => T;
 
 /**
  * A type that represents the return value of {@link setInterval} function,

package/src/index.ts

@@ -1,4 +1,4 @@
-export const VERSION = "2.0.2";
+export const VERSION = "2.1.1";
 
 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,13 @@ export type {
     PromiseExecutor,
     PromiseRejecter,
     PromiseResolver,
+    Publishable,
+    ReadonlyMapView,
+    ReadonlySetView,
     Reducer,
     RejectedHandler,
+    SetViewEventsMap,
+    Subscribable,
     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.
  *
  * ---
@@ -47,3 +50,110 @@ export type Callback<A extends unknown[] = [], R = void> = (...args: A) => R;
  */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export type CallbackMap<T = Record<string, Callback<unknown[], unknown>>> = { [K in keyof T]: Callback<any[], any> };
+
+/**
+ * An utility type that represents a {@link Publisher} object that can be published to.
+ * See also {@link Subscribable}.
+ *
+ * It can be used to prevent the user from modifying the publisher while
+ * still allowing them to subscribe to events and publish them.
+ *
+ * ---
+ *
+ * @template T
+ * A map containing the names of the emittable events and the
+ * related callback signatures that can be subscribed to them.  
+ * Default is `Record<string, (...args: unknown[]) => unknown>`.
+ */
+export interface Publishable<T extends CallbackMap<T> = CallbackMap>
+{
+    /**
+     * Publishes an event to all the subscribers.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * publisher.subscribe("player:move", (coords) => { [...] });
+     * publisher.subscribe("player:move", ({ x, y }) => { [...] });
+     * publisher.subscribe("player:move", (evt) => { [...] });
+     *
+     * publisher.publish("player:move", { x: 10, y: 20 });
+     * ```
+     *
+     * ---
+     *
+     * @template K The key of the map containing the callback signature to publish.
+     *
+     * @param event The name of the event to publish.
+     * @param args The arguments to pass to the subscribers.
+     *
+     * @returns An array containing the return values of all the subscribers.
+     */
+    publish<K extends keyof T>(event: K & string, ...args: Parameters<T[K]>): ReturnType<T[K]>[];
+}
+
+/**
+ * An utility type that represents a {@link Publisher} object that can be subscribed to.
+ * See also {@link Publishable}.
+ * 
+ * It can be used to prevent the user from modifying the publisher while
+ * still allowing them to subscribe to events and publish them.
+ *
+ * ---
+ *
+ * @template T
+ * A map containing the names of the emittable events and the
+ * related callback signatures that can be subscribed to them.  
+ * Default is `Record<string, (...args: unknown[]) => unknown>`.
+ */
+export interface Subscribable<T extends CallbackMap<T> = CallbackMap>
+{
+    /**
+     * Subscribes to an event and adds a subscriber to be executed when the event is published.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * let unsubscribe: () => void;
+     * publisher.subscribe("player:death", unsubscribe);
+     * publisher.subscribe("player:spawn", (evt) =>
+     * {
+     *     unsubscribe = publisher.subscribe("player:move", ({ x, y }) => { [...] });
+     * });
+     * ```
+     *
+     * ---
+     *
+     * @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 execute when the event is published.
+     *
+     * @returns A function that can be used to unsubscribe the subscriber from the event.
+     */
+    subscribe<K extends keyof T>(event: K & string, subscriber: T[K]): () => void;
+
+    /**
+     * Unsubscribes from an event and removes a subscriber from being executed when the event is published.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * const onPlayerMove = ({ x, y }: Point) => { [...] };
+     *
+     * publisher.subscribe("player:spawn", (evt) => publisher.subscribe("player:move", onPlayerMove));
+     * publisher.subscribe("player:death", () => publisher.unsubscribe("player:move", onPlayerMove));
+     * ```
+     *
+     * ---
+     *
+     * @template K The key of the map containing the callback signature to unsubscribe.
+     *
+     * @param event The name of the event to unsubscribe from.
+     * @param subscriber The subscriber to remove from the event.
+     */
+    unsubscribe<K extends keyof T>(event: K & string, subscriber: T[K]): void;
+}

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