@byloth/core 2.1.8 → 2.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byloth/core",
-  "version": "2.1.8",
+  "version": "2.2.1",
   "description": "An unopinionated collection of useful functions and classes that I use widely in all my projects. 🔧",
   "keywords": [
     "Core",
@@ -52,13 +52,13 @@
     "@byloth/eslint-config-typescript": "^3.2.2",
     "@eslint/compat": "^1.4.1",
     "@types/node": "^22.19.0",
-    "@vitest/coverage-v8": "^3.2.4",
+    "@vitest/coverage-v8": "^4.0.8",
     "eslint": "^9.39.1",
     "husky": "^9.1.7",
     "jsdom": "^27.1.0",
     "typescript": "^5.9.3",
-    "vite": "^7.2.1",
-    "vitest": "^3.2.4"
+    "vite": "^7.2.2",
+    "vitest": "^4.0.8"
   },
   "scripts": {
     "dev": "vite",

package/src/index.ts

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

package/src/models/callbacks/callback-chain.ts

@@ -0,0 +1,163 @@
+import CallableObject from "./callable-object.js";
+import type { Callback } from "./types.js";
+
+/**
+ * A class that collects multiple functions or callbacks and executes them sequentially when invoked.
+ *
+ * This is particularly useful for managing multiple cleanup operations, such as
+ * collecting unsubscribe callbacks from event subscriptions and calling them all at once.
+ *
+ * ---
+ *
+ * @example
+ * ```ts
+ * const unsubscribeAll = new CallbackChain<() => void>()
+ *     .add(() => console.log("Doing something..."))
+ *     .add(() => console.log("Doing something else..."))
+ *     .add(() => console.log("Doing yet another thing..."));
+ *
+ * unsubscribeAll();  // Doing something...
+ *                    // Doing something else...
+ *                    // Doing yet another thing...
+ * ```
+ *
+ * ---
+ *
+ * @template T
+ * The type signature of the functions in the chain.  
+ * All functions must share the same signature. Default is `() => void`.
+ */
+export default class CallbackChain<
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    T extends Callback<any[], any> = Callback,
+    P extends Parameters<T> = Parameters<T>,
+    R extends ReturnType<T> = ReturnType<T>
+> extends CallableObject<Callback<P, R[]>>
+{
+    /**
+     * The array containing all the functions in the chain.
+     */
+    protected readonly _callbacks: T[];
+
+    /**
+     * Gets the number of functions currently in the chain.
+     */
+    public get size(): number
+    {
+        return this._callbacks.length;
+    }
+
+    /**
+     * Initializes a new instance of the {@link CallbackChain} class.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * const chain = new CallbackChain();
+     * ```
+     *
+     * ---
+     *
+     * @param callback Optional initial functions to add to the chain.
+     */
+    public constructor(...callback: T[])
+    {
+        super();
+
+        this._callbacks = callback;
+    }
+
+    /**
+     * Executes all functions in the chain sequentially with the provided arguments.
+     *
+     * ---
+     *
+     * @param args The arguments to pass to each function in the chain.
+     *
+     * @returns An array containing the return values of all functions.
+     */
+    protected override _invoke(...args: Parameters<T>): ReturnType<T>[]
+    {
+        return this._callbacks.map((callback) => callback(...args)) as ReturnType<T>[];
+    }
+
+    /**
+     * Adds a function to the chain.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * const chain = new CallbackChain();
+     * const cleanup = () => console.log("Cleaning up..."));
+     *
+     * chain.add(cleanup);
+     * ```
+     *
+     * ---
+     *
+     * @param callback The function to add to the chain.
+     *
+     * @returns The current instance for method chaining.
+     */
+    public add(callback: T): this
+    {
+        this._callbacks.push(callback);
+
+        return this;
+    }
+
+    /**
+     * Removes a specific function from the chain.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * const chain = new CallbackChain();
+     * const cleanup = () => console.log("Cleaning up..."));
+     *
+     * chain.add(cleanup);
+     * chain.remove(cleanup);
+     * ```
+     *
+     * ---
+     *
+     * @param callback The function to remove from the chain.
+     *
+     * @returns `true` if the function was found and removed, `false` otherwise.
+     */
+    public remove(callback: T): boolean
+    {
+        const index = this._callbacks.indexOf(callback);
+        if (index < 0) { return false; }
+
+        this._callbacks.splice(index, 1);
+
+        return true;
+    }
+
+    /**
+     * Removes all functions from the chain.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * const chain = new CallbackChain();
+     *
+     * chain.add(() => console.log("Doing something..."));
+     * chain.add(() => console.log("Doing something else..."));
+     * chain.add(() => console.log("Doing yet another thing..."));
+     *
+     * chain.clear();
+     * ```
+     */
+    public clear(): void
+    {
+        this._callbacks.length = 0;
+    }
+
+    public override readonly [Symbol.toStringTag]: string = "CallbackChain";
+}

package/src/models/callbacks/index.ts

@@ -1,5 +1,6 @@
 import CallableObject from "./callable-object.js";
+import CallbackChain from "./callback-chain.js";
 import Publisher from "./publisher.js";
 import SwitchableCallback from "./switchable-callback.js";
 
-export { CallableObject, Publisher, SwitchableCallback };
+export { CallableObject, CallbackChain, Publisher, SwitchableCallback };

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