@byloth/core 2.2.0 → 2.2.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byloth/core",
-  "version": "2.2.0",
+  "version": "2.2.2",
   "description": "An unopinionated collection of useful functions and classes that I use widely in all my projects. 🔧",
   "keywords": [
     "Core",
@@ -50,15 +50,15 @@
   "types": "src/index.ts",
   "devDependencies": {
     "@byloth/eslint-config-typescript": "^3.2.2",
-    "@eslint/compat": "^1.4.1",
-    "@types/node": "^22.19.0",
-    "@vitest/coverage-v8": "^3.2.4",
+    "@eslint/compat": "^2.0.0",
+    "@types/node": "^22.19.1",
+    "@vitest/coverage-v8": "^4.0.12",
     "eslint": "^9.39.1",
     "husky": "^9.1.7",
-    "jsdom": "^27.1.0",
+    "jsdom": "^27.2.0",
     "typescript": "^5.9.3",
-    "vite": "^7.2.1",
-    "vitest": "^3.2.4"
+    "vite": "^7.2.4",
+    "vitest": "^4.0.12"
   },
   "scripts": {
     "dev": "vite",

package/src/index.ts

@@ -1,4 +1,4 @@
-export const VERSION = "2.2.0";
+export const VERSION = "2.2.2";
 
 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/exceptions/core.ts

@@ -16,8 +16,7 @@
  *     // Uncaught Exception: The game saves may be corrupted. Try to restart the game.
  *     //     at /src/game/index.ts:37:15
  *     //     at /src/main.ts:23:17
- *     //
- *     // Caused by SyntaxError: Unexpected end of JSON input
+ *     // Caused by: SyntaxError: Unexpected end of JSON input
  *     //     at /src/models/saves.ts:47:17
  *     //     at /src/game/index.ts:12:9
  *     //     at /src/main.ts:23:17
@@ -59,6 +58,7 @@ export default class Exception extends Error
             const exc = new Exception(error.message);
 
             exc.stack = error.stack;
+            exc.cause = error.cause;
             exc.name = error.name;
 
             return exc;
@@ -89,18 +89,6 @@ export default class Exception extends Error
 
         this.cause = cause;
         this.name = name;
-
-        if (cause)
-        {
-            if (cause instanceof Error)
-            {
-                this.stack += `\n\nCaused by ${cause.stack}`;
-            }
-            else
-            {
-                this.stack += `\n\nCaused by ${cause}`;
-            }
-        }
     }
 
     public readonly [Symbol.toStringTag]: string = "Exception";

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,

package/src/models/iterators/smart-async-iterator.ts

@@ -1066,7 +1066,7 @@ export default class SmartAsyncIterator<T, R = void, N = undefined> implements A
      * {
      *     try
      *     {
-     *         if (value > 5) { throw new Error("The index is too high."); }
+     *         if (value > 5) { throw new Exception("The index is too high."); }
      *
      *         console.log(value); // 1, 2, 3, 4, 5
      *     }

package/src/models/iterators/smart-iterator.ts

@@ -939,7 +939,7 @@ export default class SmartIterator<T, R = void, N = undefined> implements Iterat
      * {
      *     try
      *     {
-     *         if (value > 5) { throw new Error("The index is too high."); }
+     *         if (value > 5) { throw new Exception("The index is too high."); }
      *
      *         console.log(value); // 1, 2, 3, 4, 5
      *     }

package/src/models/promises/smart-promise.ts

@@ -261,10 +261,10 @@ export default class SmartPromise<T = void> implements Promise<T>
      * ```ts
      * const promise = new SmartPromise((resolve, reject) =>
      * {
-     *     setTimeout(() => reject(new Error("An unknown error occurred.")), 1_000);
+     *     setTimeout(() => reject(new Exception("An unknown error occurred.")), 1_000);
      * });
      *
-     * promise.catch(); // Uncaught Error: An unknown error occurred.
+     * promise.catch(); // "Uncaught Exception: An unknown error occurred."
      * ```
      *
      * ---
@@ -288,10 +288,10 @@ export default class SmartPromise<T = void> implements Promise<T>
      * ```ts
      * const promise = new SmartPromise((resolve, reject) =>
      * {
-     *     setTimeout(() => reject(new Error("An unknown error occurred.")), 1_000);
+     *     setTimeout(() => reject(new Exception("An unknown error occurred.")), 1_000);
      * });
      *
-     * promise.catch((reason) => console.error(reason)); // "Error: An unknown error occurred."
+     * promise.catch((reason) => console.error(reason)); // "Uncaught Exception: An unknown error occurred."
      * ```
      *
      * ---

package/src/models/promises/timed-promise.ts

@@ -21,7 +21,7 @@ import type { MaybePromise, PromiseExecutor } from "./types.js";
  *
  * promise
  *     .then((result) => console.log(result))  // "Hello, World!"
- *     .catch((error) => console.error(error)); // TimeoutException: The operation has timed out.
+ *     .catch((error) => console.error(error)); // "Uncaught TimeoutException: The operation has timed out."
  * ```
  *
  * ---