@byloth/core 2.2.0 → 2.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byloth/core",
-  "version": "2.2.0",
+  "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.2.0";
+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,

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/index.ts

@@ -5,7 +5,7 @@ export {
 
 } from "./aggregators/index.js";
 
-export { CallableObject, Publisher, SwitchableCallback } from "./callbacks/index.js";
+export { CallableObject, CallbackChain, Publisher, SwitchableCallback } from "./callbacks/index.js";
 export { MapView, SetView } from "./collections/index.js";
 export {
     Exception,