@byloth/core 2.1.8 → 2.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byloth/core",
-  "version": "2.1.8",
+  "version": "2.2.0",
   "description": "An unopinionated collection of useful functions and classes that I use widely in all my projects. 🔧",
   "keywords": [
     "Core",

package/src/index.ts

@@ -1,4 +1,4 @@
-export const VERSION = "2.1.8";
+export const VERSION = "2.2.0";
 
 export type { Constructor, Interval, Timeout, ValueOf } from "./core/types.js";
 
@@ -61,7 +61,6 @@ export type {
     KeyedIteratee,
     KeyedReducer,
     KeyedTypeGuardPredicate,
-    MapViewEventsMap,
     MaybeAsyncKeyedIteratee,
     MaybeAsyncKeyedReducer,
     MaybeAsyncGeneratorFunction,
@@ -77,7 +76,6 @@ export type {
     ReadonlySetView,
     Reducer,
     RejectedHandler,
-    SetViewEventsMap,
     Subscribable,
     TypeGuardPredicate,
     WildcardEventsMap

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

@@ -1,9 +1,16 @@
 import Publisher from "../callbacks/publisher.js";
-import type { Callback, Subscribable } from "../types.js";
+import type { Callback } from "../types.js";
 
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
 import type SetView from "./set-view.js";
-import type { MapViewEventsMap } from "./types.js";
+
+interface MapViewEventsMap<K, V>
+{
+    "add": (key: K, value: V) => void;
+    "remove": (key: K, value: V) => void;
+
+    "clear": () => void;
+}
 
 /**
  * A wrapper class around the native {@link Map} class that provides additional functionality
@@ -17,7 +24,7 @@ import type { MapViewEventsMap } from "./types.js";
  * ```ts
  * const map = new MapView<string, number>();
  *
- * map.subscribe("entry:add", (key: string, value: number) => console.log(`Added ${key}: ${value}`));
+ * map.onAdd((key: string, value: number) => console.log(`Added ${key}: ${value}`));
  * map.set("answer", 42); // "Added answer: 42"
  * ```
  *
@@ -26,7 +33,7 @@ import type { MapViewEventsMap } from "./types.js";
  * @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> implements Subscribable<MapViewEventsMap<K, V>>
+export default class MapView<K, V> extends Map<K, V>
 {
     /**
      * The internal {@link Publisher} instance used to publish events.
@@ -86,7 +93,7 @@ export default class MapView<K, V> extends Map<K, V> implements Subscribable<Map
     {
         super.set(key, value);
 
-        this._publisher.publish("entry:add", key, value);
+        this._publisher.publish("add", key, value);
 
         return this;
     }
@@ -118,7 +125,7 @@ export default class MapView<K, V> extends Map<K, V> implements Subscribable<Map
 
         super.delete(key);
 
-        this._publisher.publish("entry:remove", key, value);
+        this._publisher.publish("remove", key, value);
 
         return true;
     }
@@ -141,74 +148,77 @@ export default class MapView<K, V> extends Map<K, V> implements Subscribable<Map
         const size = this.size;
 
         super.clear();
-        if (size > 0) { this._publisher.publish("collection:clear"); }
+        if (size > 0) { this._publisher.publish("clear"); }
     }
 
     /**
-     * Subscribes to an event and adds a callback to be executed when the event is published.
+     * Subscribes to the `add` event of the map with a callback that will be executed when an entry is added.
      *
      * ---
      *
      * @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.onAdd((key, value) => 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 subscriber The callback to execute when the event is published.
+     * @param callback The callback that will be executed when an entry is added to the map.
      *
-     * @returns A function that can be used to unsubscribe the callback from the event.
+     * @returns A function that can be used to unsubscribe from the event.
      */
-    public subscribe<T extends keyof MapViewEventsMap<K, V>>(
-        event: T & string, subscriber: MapViewEventsMap<K, V>[T]
-    ): Callback
+    public onAdd(callback: (key: K, value: V) => void): Callback
     {
-        return this._publisher.subscribe(event, subscriber);
+        return this._publisher.subscribe("add", callback);
     }
 
     /**
-     * Unsubscribes from an event and removes a callback from being executed when the event is published.
+     * Subscribes to the `remove` event of the map with a callback that will be executed when an entry is removed.
      *
      * ---
      *
      * @example
      * ```ts
-     * const callback = (key: string, value: number) => console.log(`Added ${key}: ${value}`);
-     * const map = new MapView<string, number>();
+     * map.onRemove((key, value) => console.log(`Removed ${key}: ${value}`));
      *
-     * map.subscribe("entry:add", callback);
-     * map.set("key1", 2); // "Added key1: 2"
+     * map.delete("key1"); // "Removed key1: 2"
+     * map.delete("answer"); // "Removed answer: 42"
+     * ```
+     *
+     * ---
      *
-     * map.unsubscribe("entry:add", callback);
-     * map.set("key2", 4);
+     * @param callback The callback that will be executed when an entry is removed from the map.
+     *
+     * @returns A function that can be used to unsubscribe from the event.
+     */
+    public onRemove(callback: (key: K, value: V) => void): Callback
+    {
+        return this._publisher.subscribe("remove", callback);
+    }
+
+    /**
+     * Subscribes to the `clear` event of the map with a callback that will be executed when the map is cleared.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * map.onClear(() => console.log("The map has all been cleared."));
+     * map.clear(); // "The map has all been cleared."
      * ```
      *
      * ---
      *
-     * @template T The key of the map containing the callback signature to unsubscribe.
+     * @param callback The callback that will be executed when the map is cleared.
      *
-     * @param event The name of the event to unsubscribe from.
-     * @param subscriber The callback to remove from the event.
+     * @returns A function that can be used to unsubscribe from the event.
      */
-    public unsubscribe<T extends keyof MapViewEventsMap<K, V>>(
-        event: T & string, subscriber: MapViewEventsMap<K, V>[T]
-    ): void
+    public onClear(callback: () => void): Callback
     {
-        this._publisher.unsubscribe(event, subscriber);
+        return this._publisher.subscribe("clear", callback);
     }
 
     public override readonly [Symbol.toStringTag]: string = "MapView";

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

@@ -1,9 +1,16 @@
 import Publisher from "../callbacks/publisher.js";
-import type { Callback, Subscribable } from "../types.js";
+import type { Callback } from "../types.js";
 
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
 import type MapView from "./map-view.js";
-import type { SetViewEventsMap } from "./types.js";
+
+interface SetViewEventsMap<T>
+{
+    "add": (value: T) => void;
+    "remove": (value: T) => void;
+
+    "clear": () => void;
+}
 
 /**
  * A wrapper class around the native {@link Set} class that provides additional functionality
@@ -17,7 +24,7 @@ import type { SetViewEventsMap } from "./types.js";
  * ```ts
  * const set = new SetView<number>();
  *
- * set.subscribe("entry:add", (value: number) => console.log(`Added ${value}`));
+ * set.onAdd((value: number) => console.log(`Added ${value}`));
  * set.add(42); // "Added 42"
  * ```
  *
@@ -25,7 +32,7 @@ import type { SetViewEventsMap } from "./types.js";
  *
  * @template T The type of the values in the set.
  */
-export default class SetView<T> extends Set<T> implements Subscribable<SetViewEventsMap<T>>
+export default class SetView<T> extends Set<T>
 {
     /**
      * The internal {@link Publisher} instance used to publish events.
@@ -84,7 +91,7 @@ export default class SetView<T> extends Set<T> implements Subscribable<SetViewEv
     {
         super.add(value);
 
-        this._publisher.publish("entry:add", value);
+        this._publisher.publish("add", value);
 
         return this;
     }
@@ -112,7 +119,7 @@ export default class SetView<T> extends Set<T> implements Subscribable<SetViewEv
     public override delete(value: T): boolean
     {
         const result = super.delete(value);
-        if (result) { this._publisher.publish("entry:remove", value); }
+        if (result) { this._publisher.publish("remove", value); }
 
         return result;
     }
@@ -135,72 +142,77 @@ export default class SetView<T> extends Set<T> implements Subscribable<SetViewEv
         const size = this.size;
 
         super.clear();
-        if (size > 0) { this._publisher.publish("collection:clear"); }
+        if (size > 0) { this._publisher.publish("clear"); }
     }
 
     /**
-     * Subscribes to an event and adds a callback to be executed when the event is published.
+     * Subscribes to the `add` event of the set with a callback that will be executed when a value is added.
      *
      * ---
      *
      * @example
      * ```ts
-     * const set = new SetView<number>();
-     * const unsubscribe = set.subscribe("entry:add", (value: number) =>
-     * {
-     *     if (value === 42) { unsubscribe(); }
-     *     console.log(`Added ${value}`);
-     * });
+     * set.onAdd((value) => 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 subscriber The callback to execute when the event is published.
+     * @param callback The callback that will be executed when a value is added to the set.
      *
-     * @returns A function that can be used to unsubscribe the callback from the event.
+     * @returns A function that can be used to unsubscribe from the event.
      */
-    public subscribe<K extends keyof SetViewEventsMap<T>>(
-        event: K & string, subscriber: SetViewEventsMap<T>[K]
-    ): Callback
+    public onAdd(callback: (value: T) => void): Callback
     {
-        return this._publisher.subscribe(event, subscriber);
+        return this._publisher.subscribe("add", callback);
     }
 
     /**
-     * Unsubscribes from an event and removes a callback from being executed when the event is published.
+     * Subscribes to the `remove` event of the set with a callback that will be executed when a value is removed.
      *
      * ---
      *
      * @example
      * ```ts
-     * const callback = (value: number) => console.log(`Added ${value}`);
-     * const set = new SetView<number>();
+     * set.onRemove((value) => console.log(`Removed ${value}`));
      *
-     * set.subscribe("entry:add", callback);
-     * set.add(2); // "Added 2"
+     * set.delete(2); // "Removed 2"
+     * set.delete(42); // "Removed 42"
+     * ```
+     *
+     * ---
      *
-     * set.unsubscribe("entry:add", callback);
-     * set.add(4);
+     * @param callback The callback that will be executed when a value is removed from the set.
+     *
+     * @returns A function that can be used to unsubscribe from the event.
+     */
+    public onRemove(callback: (value: T) => void): Callback
+    {
+        return this._publisher.subscribe("remove", callback);
+    }
+
+    /**
+     * Subscribes to the `clear` event of the set with a callback that will be executed when the set is cleared.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * set.onClear(() => console.log("The set has all been cleared."));
+     * set.clear(); // "The set has all been cleared."
      * ```
      *
      * ---
      *
-     * @template K The key of the map containing the callback signature to unsubscribe.
+     * @param callback The callback that will be executed when the set is cleared.
      *
-     * @param event The name of the event to unsubscribe from.
-     * @param subscriber The callback to remove from the event.
+     * @returns A function that can be used to unsubscribe from the event.
      */
-    public unsubscribe<K extends keyof SetViewEventsMap<T>>(event: K & string, subscriber: SetViewEventsMap<T>[K]): void
+    public onClear(callback: () => void): Callback
     {
-        this._publisher.unsubscribe(event, subscriber);
+        return this._publisher.subscribe("clear", callback);
     }
 
     public override readonly [Symbol.toStringTag]: string = "SetView";

package/src/models/collections/types.ts

@@ -6,25 +6,6 @@ import type MapView from "./map-view.js";
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
 import type SetView from "./set-view.js";
 
-/**
- * A type that represents the map of events published by a {@link MapView} object.
- * See also {@link SetViewEventsMap}.
- *
- * The keys of the map are the event names while the values are the callback function signatures.
- *
- * ---
- *
- * @template K The type of the keys in the map.
- * @template V The type of the values in the map.
- */
-export interface MapViewEventsMap<K, V>
-{
-    "entry:add": (key: K, value: V) => void;
-    "entry:remove": (key: K, value: V) => void;
-
-    "collection:clear": () => void;
-}
-
 /**
  * An utility type that represents a read-only {@link MapView} object.
  * See also {@link ReadonlySetView}.
@@ -40,79 +21,65 @@ export interface MapViewEventsMap<K, V>
 export interface ReadonlyMapView<K, V> extends ReadonlyMap<K, V>
 {
     /**
-     * Subscribes to an event and adds a callback to be executed when the event is published.
+     * Subscribes to the `add` event of the map with a callback that will be executed when an entry is added.
      *
      * ---
      *
      * @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.onAdd((key, value) => 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.
+     * @param callback The callback that will be executed when an entry is added to the map.
      *
-     * @returns A function that can be used to unsubscribe the callback from the event.
+     * @returns A function that can be used to unsubscribe from the event.
      */
-    subscribe<T extends keyof MapViewEventsMap<K, V>>(event: T & string, callback: MapViewEventsMap<K, V>[T]): Callback;
+    onAdd(callback: (key: K, value: V) => void): Callback;
 
     /**
-     * Unsubscribes from an event and removes a callback from being executed when the event is published.
+     * Subscribes to the `remove` event of the map with a callback that will be executed when an entry is removed.
      *
      * ---
      *
      * @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.onRemove((key, value) => console.log(`Removed ${key}: ${value}`));
      *
-     * map.unsubscribe("entry:add", callback);
-     * map.set("key2", 4);
+     * map.delete("key1"); // "Removed key1: 2"
+     * map.delete("answer"); // "Removed answer: 42"
      * ```
      *
      * ---
      *
-     * @template T The key of the map containing the callback signature to unsubscribe.
+     * @param callback The callback that will be executed when an entry is removed from the map.
      *
-     * @param event The name of the event to unsubscribe from.
-     * @param callback The callback to remove from the event.
+     * @returns A function that can be used to unsubscribe from the event.
      */
-    unsubscribe<T extends keyof MapViewEventsMap<K, V>>(event: T & string, callback: MapViewEventsMap<K, V>[T]): void;
-}
-
-/**
- * A type that represents the map of events published by a {@link SetView} object.
- * See also {@link MapViewEventsMap}.
- *
- * The keys of the map are the event names while the values are the callback function signatures.
- *
- * ---
- *
- * @template T The type of the values in the set.
- */
-export interface SetViewEventsMap<T>
-{
-    "entry:add": (value: T) => void;
-    "entry:remove": (value: T) => void;
+    onRemove(callback: (key: K, value: V) => void): Callback;
 
-    "collection:clear": () => void;
+    /**
+     * Subscribes to the `clear` event of the map with a callback that will be executed when the map is cleared.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * map.onClear(() => console.log("The map has all been cleared."));
+     * map.clear();
+     * ```
+     *
+     * ---
+     *
+     * @param callback The callback that will be executed when the map is cleared.
+     *
+     * @returns A function that can be used to unsubscribe from the event.
+     */
+    onClear(callback: () => void): Callback;
 }
 
 /**
@@ -129,59 +96,63 @@ export interface SetViewEventsMap<T>
 export interface ReadonlySetView<T> extends ReadonlySet<T>
 {
     /**
-     * Subscribes to an event and adds a callback to be executed when the event is published.
+     * Subscribes to the `add` event of the set with a callback that will be executed when a value is added.
      *
      * ---
      *
      * @example
      * ```ts
-     * const set = new SetView<number>();
-     * const unsubscribe = set.subscribe("entry:add", (value: number) =>
-     * {
-     *     if (value === 42) { unsubscribe(); }
-     *     console.log(`Added ${value}`);
-     * });
+     * set.onAdd((value) => 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.
+     * @param callback The callback that will be executed when a value is added to the set.
      *
-     * @returns A function that can be used to unsubscribe the callback from the event.
+     * @returns A function that can be used to unsubscribe from the event.
      */
-    subscribe<K extends keyof SetViewEventsMap<T>>(event: K & string, callback: SetViewEventsMap<T>[K]): Callback;
+    onAdd(callback: (value: T) => void): Callback;
 
     /**
-     * Unsubscribes from an event and removes a callback from being executed when the event is published.
+     * Subscribes to the `remove` event of the set with a callback that will be executed when a value is removed.
      *
      * ---
      *
      * @example
      * ```ts
-     * const callback = (value: number) => console.log(`Added ${value}`);
-     * const set = new SetView<number>();
+     * set.onRemove((value) => console.log(`Removed ${value}`));
      *
-     * set.subscribe("entry:add", callback);
-     * set.add(2); // "Added 2"
+     * set.delete(2); // "Removed 2"
+     * set.delete(42); // "Removed 42"
+     * ```
+     *
+     * ---
+     *
+     * @param callback The callback that will be executed when a value is removed from the set.
+     *
+     * @returns A function that can be used to unsubscribe from the event.
+     */
+    onRemove(callback: (value: T) => void): Callback;
+
+    /**
+     * Subscribes to the `clear` event of the set with a callback that will be executed when the set is cleared.
+     *
+     * ---
      *
-     * set.unsubscribe("entry:add", callback);
-     * set.add(4);
+     * @example
+     * ```ts
+     * set.onClear(() => console.log("The set has all been cleared."));
+     * set.clear(); // "The set has all been cleared."
      * ```
      *
      * ---
      *
-     * @template K The key of the map containing the callback signature to unsubscribe.
+     * @param callback The callback that will be executed when the set is cleared.
      *
-     * @param event The name of the event to unsubscribe from.
-     * @param callback The callback to remove from the event.
+     * @returns A function that can be used to unsubscribe from the event.
      */
-    unsubscribe<K extends keyof SetViewEventsMap<T>>(event: K & string, callback: SetViewEventsMap<T>[K]): void;
+    onClear(callback: () => void): Callback;
 }

package/src/models/timers/clock.ts

@@ -8,9 +8,9 @@ import GameLoop from "./game-loop.js";
 
 interface ClockEventsMap
 {
-    start: () => void;
-    stop: () => void;
-    tick: (elapsedTime: number) => void;
+    "start": () => void;
+    "stop": () => void;
+    "tick": (elapsedTime: number) => void;
 }
 
 /**

package/src/models/timers/countdown.ts

@@ -14,9 +14,6 @@ interface CountdownEventsMap
     stop: (reason: unknown) => void;
     tick: (remainingTime: number) => void;
     expire: () => void;
-
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    [key: string]: Callback<any[], any>;
 }
 
 /**
@@ -211,28 +208,6 @@ export default class Countdown extends GameLoop
         this._publisher.publish("stop", reason);
     }
 
-    /**
-     * Subscribes to the `expire` event of the countdown.
-     *
-     * ---
-     *
-     * @example
-     * ```ts
-     * countdown.onExpire(() => { [...] }); // This callback will be executed once the countdown has expired.
-     * countdown.start();
-     * ```
-     *
-     * ---
-     *
-     * @param callback The callback that will be executed when the countdown expires.
-     *
-     * @returns A function that can be used to unsubscribe from the event.
-     */
-    public onExpire(callback: Callback): Callback
-    {
-        return this._publisher.subscribe("expire", callback);
-    }
-
     /**
      * Subscribes to the `tick` event of the countdown.
      *
@@ -273,5 +248,27 @@ export default class Countdown extends GameLoop
         });
     }
 
+    /**
+     * Subscribes to the `expire` event of the countdown.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * countdown.onExpire(() => { [...] }); // This callback will be executed once the countdown has expired.
+     * countdown.start();
+     * ```
+     *
+     * ---
+     *
+     * @param callback The callback that will be executed when the countdown expires.
+     *
+     * @returns A function that can be used to unsubscribe from the event.
+     */
+    public onExpire(callback: Callback): Callback
+    {
+        return this._publisher.subscribe("expire", callback);
+    }
+
     public override readonly [Symbol.toStringTag]: string = "Countdown";
 }