@byloth/core 2.0.1 → 2.0.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byloth/core",
-  "version": "2.0.1",
+  "version": "2.0.2",
   "description": "An unopinionated collection of useful functions and classes that I use widely in all my projects. 🔧",
   "keywords": [
     "Core",
@@ -48,14 +48,15 @@
   "types": "src/index.ts",
   "devDependencies": {
     "@byloth/eslint-config-typescript": "^3.1.0",
-    "@eslint/compat": "^1.2.7",
-    "@types/node": "^22.13.11",
-    "eslint": "^9.23.0",
+    "@eslint/compat": "^1.2.8",
+    "@types/node": "^22.14.1",
+    "@vitest/coverage-v8": "^3.1.1",
+    "eslint": "^9.25.0",
     "husky": "^9.1.7",
-    "jsdom": "^26.0.0",
-    "typescript": "^5.8.2",
-    "vite": "^6.2.2",
-    "vitest": "^3.0.9"
+    "jsdom": "^26.1.0",
+    "typescript": "^5.8.3",
+    "vite": "^6.3.2",
+    "vitest": "^3.1.1"
   },
   "scripts": {
     "dev": "vite",
@@ -64,6 +65,7 @@
     "typecheck": "tsc",
     "lint": "eslint .",
     "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
     "ci": "pnpm install --frozen-lockfile"
   }
 }

package/src/core/types.ts

@@ -1,7 +1,10 @@
 /**
- * A utility type that allows to define a class constructor of a specific type.  
- * Is the counterpart of the native `InstanceType` utility type.
+ * An utility type that allows to define a class constructor of a specific type.  
+ * Is the counterpart of the native {@link InstanceType} utility type.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * function factory<T extends object>(Factory: Constructor<T>): T { [...] }
  *
@@ -12,14 +15,17 @@
 export type Constructor<T extends object, P extends unknown[] = any[]> = new (...args: P) => T;
 
 /**
- * A type that represents the return value of `setInterval` function,
+ * A type that represents the return value of {@link setInterval} function,
  * indipendently from the platform it's currently running on.
  *
- * For instance, in a browser environment, it's a `number` value representing the interval ID.  
- * In a Node.js environment, on the other hand, it's an object of type `NodeJS.Timeout`.
+ * For instance, in a browser environment, it's a {@link Number} value representing the interval ID.  
+ * In a Node.js environment, on the other hand, it's an object of type {@link NodeJS.Timeout}.
+ *
+ * This allows to seamlessly use the same code in both environments, without having to deal with the differences.
  *
- * This allows to seamlessly use the same code in both environments, without having to deal with the differences:
+ * ---
  *
+ * @example
  * ```ts
  * const intervalId: Interval = setInterval(() => { [...] }, 1_000);
  *
@@ -29,14 +35,17 @@ export type Constructor<T extends object, P extends unknown[] = any[]> = new (..
 export type Interval = ReturnType<typeof setInterval>;
 
 /**
- * A type that represents the return value of `setTimeout` function,
+ * A type that represents the return value of {@link setTimeout} function,
  * indipendently from the platform it's currently running on.
  *
- * For instance, in a browser environment, it's a `number` value representing the timeout ID.  
- * In a Node.js environment, on the other hand, it's an object of type `NodeJS.Timeout`.
+ * For instance, in a browser environment, it's a {@link Number} value representing the timeout ID.  
+ * In a Node.js environment, on the other hand, it's an object of type {@link NodeJS.Timeout}.
  *
- * This allows to seamlessly use the same code in both environments, without having to deal with the differences:
+ * This allows to seamlessly use the same code in both environments, without having to deal with the differences.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * const timeoutId: Timeout = setTimeout(() => { [...] }, 1_000);
  *
@@ -44,3 +53,27 @@ export type Interval = ReturnType<typeof setInterval>;
  * ```
  */
 export type Timeout = ReturnType<typeof setTimeout>;
+
+/**
+ * An utility type that allows to extract the union of the values of a given type.
+ * It can be used to extract the values of all the properties of an object type.
+ *
+ * ---
+ *
+ * @example
+ * ```ts
+ * class MyObject
+ * {
+ *     protected secret = "Sssh! That's a secret!";
+ *     public answer = 42;
+ *     public greet() { console.log("Hello, world!"); }
+ * }
+ *
+ * type MyObjectProperties = ValueOf<MyObject>;  // number | (() => void)
+ * ```
+ *
+ * ---
+ *
+ * @template T The type to extract the values from.
+ */
+export type ValueOf<T> = T[keyof T];

package/src/index.ts

@@ -1,6 +1,6 @@
-export const VERSION = "2.0.1";
+export const VERSION = "2.0.2";
 
-export type { Constructor, Interval, Timeout } from "./core/types.js";
+export type { Constructor, Interval, Timeout, ValueOf } from "./core/types.js";
 
 export { isBrowser, isNode, isWorker } from "./helpers.js";
 
@@ -47,6 +47,7 @@ export type {
     AsyncKeyedReducer,
     AsyncReducer,
     Callback,
+    CallbackMap,
     FulfilledHandler,
     GeneratorFunction,
     Iteratee,

package/src/models/aggregators/aggregated-async-iterator.ts

@@ -30,6 +30,9 @@ import type { MaybeAsyncKeyedIteratee, MaybeAsyncKeyedReducer } from "./types.js
  * This is particularly useful when you need to group elements and
  * then perform specific operations on the groups themselves.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * const elements = fetch([...]); // Promise<[-3, -1, 0, 2, 3, 5, 6, 8]>;
  * const results = new SmartAsyncIterator(elements)
@@ -39,6 +42,8 @@ import type { MaybeAsyncKeyedIteratee, MaybeAsyncKeyedReducer } from "./types.js
  * console.log(await results.toObject()); // { odd: 4, even: 4 }
  * ```
  *
+ * ---
+ *
  * @template K The type of the keys used to group the elements.
  * @template T The type of the elements to aggregate.
  */

package/src/models/aggregators/aggregated-iterator.ts

@@ -22,6 +22,9 @@ import type { KeyedIteratee, KeyedTypeGuardPredicate, KeyedReducer } from "./typ
  * This is particularly useful when you need to group elements and
  * then perform specific operations on the groups themselves.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * const results = new SmartIterator<number>([-3, -1, 0, 2, 3, 5, 6, 8])
  *     .groupBy((value) => value % 2 === 0 ? "even" : "odd")
@@ -30,6 +33,8 @@ import type { KeyedIteratee, KeyedTypeGuardPredicate, KeyedReducer } from "./typ
  * console.log(results.toObject()); // { odd: 4, even: 4 }
  * ```
  *
+ * ---
+ *
  * @template K The type of the keys used to group the elements.
  * @template T The type of the elements to aggregate.
  */

package/src/models/aggregators/reduced-iterator.ts

@@ -24,6 +24,9 @@ import type { KeyedIteratee, KeyedReducer, KeyedTypeGuardPredicate } from "./typ
  * This is particularly useful when you have group elements and
  * need perform specific operations on the reduced elements.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * const results = new SmartIterator<number>([-3, -1, 0, 2, 3, 5, 6, 8])
  *     .groupBy((value) => value % 2 === 0 ? "even" : "odd")
@@ -32,6 +35,8 @@ import type { KeyedIteratee, KeyedReducer, KeyedTypeGuardPredicate } from "./typ
  * console.log(results.toObject()); // { odd: 4, even: 4 }
  * ```
  *
+ * ---
+ *
  * @template K The type of the key used to group the elements.
  * @template T The type of the elements in the iterator.
  */
@@ -508,7 +513,9 @@ export default class ReducedIterator<K extends PropertyKey, T>
      *
      * console.log(results.toObject()); // { even: [0, 2, 6, 8] }
      * ```
-     * 
+     *
+     * ---
+     *
      * @param count The number of elements to drop.
      *
      * @returns A new {@link ReducedIterator} containing the remaining elements.
@@ -597,9 +604,12 @@ export default class ReducedIterator<K extends PropertyKey, T>
      *     .groupBy((value) => value % 2 === 0 ? "even" : "odd")
      *     .reduce((key, accumulator, value) => accumulator + value)
      *     .find((key, value) => value > 0);
-     * 
+     *
      * console.log(results); // 16
-     * 
+     * ```
+     *
+     * ---
+     *
      * @param predicate The condition to check for each element of the iterator.
      *
      * @returns The first element that satisfies the condition, `undefined` otherwise.
@@ -628,8 +638,11 @@ export default class ReducedIterator<K extends PropertyKey, T>
      *     .groupBy((value) => Number(value) % 2 === 0 ? "even" : "odd")
      *     .reduce((key, accumulator, value) => accumulator + value)
      *     .find<number>((key, value) => typeof value === "number");
-     * 
+     *
      * console.log(results); // 16
+     * ```
+     *
+     * ---
      *
      * @template S
      * The type of the elements that satisfy the condition.  
@@ -771,7 +784,7 @@ export default class ReducedIterator<K extends PropertyKey, T>
      * const reduced = new SmartIterator<number>([-3, -1, 0, 2, 3, 5, 6, 8])
      *     .groupBy((value) => value % 2 === 0 ? "even" : "odd")
      *     .reduce((key, accumulator, value) => accumulator + value);
-     * 
+     *
      * reduced.forEach((key, value, index) =>
      * {
      *     console.log(`#${index} - ${key}: ${value}`); // "#0 - odd: 4", "#1 - even: 16"

package/src/models/aggregators/types.ts

@@ -5,6 +5,9 @@ import type { MaybePromise } from "../promises/types.js";
  * with the addition of a `key` parameter, compared to the JavaScript's standard ones.  
  * It can be used to transform the elements of an aggregated iterable.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * const iteratee: KeyedIteratee<string, number, string> = (key: string, value: number) => `${value}`;
  * const results = new SmartIterator<number>([-3, -1, 0, 2, 3, 5, 6, 8])
@@ -14,6 +17,8 @@ import type { MaybePromise } from "../promises/types.js";
  * console.log(results.toObject()); // { odd: ["-3", "-1", "3", "5"], even: ["0", "2", "6", "8"] }
  * ```
  *
+ * ---
+ *
  * @template K The type of the key used to aggregate elements in the iterable.
  * @template T The type of the elements in the iterable.
  * @template R The type of the return value of the iteratee. Default is `void`.
@@ -25,6 +30,9 @@ export type KeyedIteratee<K extends PropertyKey, T, R = void> = (key: K, value:
  * function with the addition of a `key` parameter.  
  * It can be used to transform the elements of an aggregated iterable asynchronously.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * const iteratee: AsyncKeyedIteratee<string, number, string> = async (key: string, value: number) => `${value}`;
  * const results = new SmartAsyncIterator<number>([-3, -1, 0, 2, 3, 5, 6, 8])
@@ -34,6 +42,8 @@ export type KeyedIteratee<K extends PropertyKey, T, R = void> = (key: K, value:
  * console.log(await results.toObject()); // { odd: ["-3", "-1", "3", "5"], even: ["0", "2", "6", "8"] }
  * ```
  *
+ * ---
+ *
  * @template K The type of the key used to aggregate elements in the iterable.
  * @template T The type of the elements in the iterable.
  * @template R The type of the return value of the iteratee. Default is `void`.
@@ -45,6 +55,9 @@ export type AsyncKeyedIteratee<K extends PropertyKey, T, R = void> = (key: K, va
  * with the addition of a `key` parameter that can be either synchronous or asynchronous.  
  * It can be used to transform the elements of an aggregated iterable.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * const iteratee: AsyncKeyedIteratee<string, number, string> = [async] (key: string, value: number) => `${value}`;
  * const results = new SmartAsyncIterator<number>([-3, -1, 0, 2, 3, 5, 6, 8])
@@ -54,6 +67,8 @@ export type AsyncKeyedIteratee<K extends PropertyKey, T, R = void> = (key: K, va
  * console.log(await results.toObject()); // { odd: ["-3", "-1", "3", "5"], even: ["0", "2", "6", "8"] }
  * ```
  *
+ * ---
+ *
  * @template K The type of the key used to aggregate elements in the iterable.
  * @template T The type of the elements in the iterable.
  * @template R The type of the return value of the iteratee. Default is `void`.
@@ -69,6 +84,9 @@ export type MaybeAsyncKeyedIteratee<K extends PropertyKey, T, R = void> =
  * It can be used to filter the elements of an aggregated iterable
  * while allowing the type-system to infer them correctly.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * const predicate: KeyedTypeGuardPredicate<string, number | string, string> =
  *     (key: string, value: number | string): value is string => typeof value === "string";
@@ -80,6 +98,8 @@ export type MaybeAsyncKeyedIteratee<K extends PropertyKey, T, R = void> =
  * console.log(results.toObject()); // { odd: ["0", "5", "8"], even: [] }
  * ```
  *
+ * ---
+ *
  * @template K The type of the key used to aggregate elements in the iterable.
  * @template T The type of the elements in the iterable.
  * @template R
@@ -100,6 +120,9 @@ export type KeyedTypeGuardPredicate<K extends PropertyKey, T, R extends T> =
  * An utility type that represents a reducer-like function.  
  * It can be used to reduce the elements of an aggregated iterable into a single value.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * const sum: KeyedReducer<string, number, number> =
  *     (key: string, accumulator: number, value: number) => accumulator + value;
@@ -111,6 +134,8 @@ export type KeyedTypeGuardPredicate<K extends PropertyKey, T, R extends T> =
  * console.log(results.toObject()); // { odd: 4, even: 16 }
  * ```
  *
+ * ---
+ *
  * @template K The type of the key used to aggregate elements in the iterable.
  * @template T The type of the elements in the iterable.
  * @template A The type of the accumulator.
@@ -121,6 +146,9 @@ export type KeyedReducer<K extends PropertyKey, T, A> = (key: K, accumulator: A,
  * An utility type that represents an asynchronous reducer-like function.  
  * It can be used to reduce the elements of an aggregated iterable into a single value.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * const sum: AsyncKeyedReducer<string, number, number> =
  *     async (key: string, accumulator: number, value: number) => accumulator + value;
@@ -132,6 +160,8 @@ export type KeyedReducer<K extends PropertyKey, T, A> = (key: K, accumulator: A,
  * console.log(await results.toObject()); // { odd: 4, even: 16 }
  * ```
  *
+ * ---
+ *
  * @template K The type of the key used to aggregate elements in the iterable.
  * @template T The type of the elements in the iterable.
  * @template A The type of the accumulator.
@@ -143,6 +173,9 @@ export type AsyncKeyedReducer<K extends PropertyKey, T, A> =
  * An utility type that represents a reducer-like function that can be either synchronous or asynchronous.  
  * It can be used to reduce the elements of an aggregated iterable into a single value.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * const sum: MaybeAsyncKeyedReducer<string, number, number> =
  *     [async] (key: string, accumulator: number, value: number) => accumulator + value;
@@ -154,6 +187,8 @@ export type AsyncKeyedReducer<K extends PropertyKey, T, A> =
  * console.log(await results.toObject()); // { odd: 4, even: 16 }
  * ```
  *
+ * ---
+ *
  * @template K The type of the key used to aggregate elements in the iterable.
  * @template T The type of the elements in the iterable.
  * @template A The type of the accumulator.

package/src/models/callbacks/callable-object.ts

@@ -8,6 +8,9 @@ const SmartFunction = (Function as unknown) as new<A extends unknown[] = [], R =
 /**
  * An abstract class that can be used to implement callable objects.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * class ActivableCallback extends CallableObject<(evt: PointerEvent) => void>
  * {
@@ -25,6 +28,8 @@ const SmartFunction = (Function as unknown) as new<A extends unknown[] = [], R =
  * window.addEventListener("pointerup", () => { callback.enabled = false; });
  * ```
  *
+ * ---
+ *
  * @template T
  * The type signature of the callback function.  
  * It must be a function. Default is `(...args: any[]) => any`.
@@ -49,6 +54,8 @@ export default abstract class CallableObject<T extends Callback<any[], any> = ()
      * The method that will be called when the object is invoked.  
      * It must be implemented by the derived classes.
      *
+     * ---
+     *
      * @param args The arguments that have been passed to the object.
      *
      * @returns The return value of the method.

package/src/models/callbacks/publisher.ts

@@ -1,6 +1,6 @@
 import { ReferenceException } from "../exceptions/index.js";
 
-import type { Callback } from "./types.js";
+import type { Callback, CallbackMap } from "./types.js";
 
 /**
  * A class implementing the
@@ -12,6 +12,9 @@ import type { Callback } from "./types.js";
  *
  * Using generics, it's also possible to define the type of the events and the callbacks that can be subscribed to them.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * interface EventsMap
  * {
@@ -30,13 +33,14 @@ import type { Callback } from "./types.js";
  * });
  * ```
  *
+ * ---
+ *
  * @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, () => void>`.
+ * Default is `Record<string, (...args: unknown[]) => unknown>`.
  */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export default class Publisher<T extends { [K in keyof T]: Callback<any[], any> } = Record<string, Callback>>
+export default class Publisher<T extends CallbackMap<T> = CallbackMap>
 {
     /**
      * A map containing all the subscribers for each event.
@@ -44,7 +48,7 @@ export default class Publisher<T extends { [K in keyof T]: Callback<any[], any>
      * The keys are the names of the events they are subscribed to.  
      * The values are the arrays of the subscribers themselves.
      */
-    protected _subscribers: Map<keyof T, Callback<unknown[], unknown>[]>;
+    protected _subscribers: Map<string, Callback<unknown[], unknown>[]>;
 
     /**
      * Initializes a new instance of the {@link Publisher} class.
@@ -109,7 +113,7 @@ export default class Publisher<T extends { [K in keyof T]: Callback<any[], any>
      *
      * @returns An array containing the return values of all the subscribers.
      */
-    public publish<K extends keyof T>(event: K, ...args: Parameters<T[K]>): ReturnType<T[K]>[]
+    public publish<K extends keyof T>(event: K & string, ...args: Parameters<T[K]>): ReturnType<T[K]>[]
     {
         const subscribers = this._subscribers.get(event);
         if (!(subscribers)) { return []; }
@@ -142,7 +146,7 @@ export default class Publisher<T extends { [K in keyof T]: Callback<any[], any>
      *
      * @returns A function that can be used to unsubscribe the subscriber.
      */
-    public subscribe<K extends keyof T>(event: K, subscriber: T[K]): () => void
+    public subscribe<K extends keyof T>(event: K & string, subscriber: T[K]): () => void
     {
         if (!(this._subscribers.has(event))) { this._subscribers.set(event, []); }
 
@@ -182,7 +186,7 @@ export default class Publisher<T extends { [K in keyof T]: Callback<any[], any>
      * @param event The name of the event to unsubscribe from.
      * @param subscriber The subscriber to remove from the event.
      */
-    public unsubscribe<K extends keyof T>(event: K, subscriber: T[K]): void
+    public unsubscribe<K extends keyof T>(event: K & string, subscriber: T[K]): void
     {
         const subscribers = this._subscribers.get(event);
         if (!(subscribers)) { return; }

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

@@ -11,6 +11,9 @@ const Disabler = () => { /* ... */ };
  * It can be used to implement different behaviors for the same event handler, allowing
  * it to respond to different states without incurring any overhead during execution.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * const onPointerMove = new SwitchableCallback<(evt: PointerEvent) => void>();
  *
@@ -22,6 +25,8 @@ const Disabler = () => { /* ... */ };
  * window.addEventListener("pointerup", () => { onPointerMove.switch("released"); });
  * ```
  *
+ * ---
+ *
  * @template T The type signature of the callback. Default is `(...args: any[]) => any`.
  */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -151,7 +156,9 @@ export default class SwitchableCallback<T extends Callback<any[], any> = Callbac
      * window.addEventListener("pointerdown", () => { onPointerMove.enable(); });
      * window.addEventListener("pointermove", onPointerMove);
      * ```
-     * 
+     *
+     * ---
+     *
      * @param key
      * The key that is associated with the implementation to enable. Default is the currently selected implementation.
      */
@@ -303,6 +310,7 @@ export default class SwitchableCallback<T extends Callback<any[], any> = Callbac
             throw new KeyException(`The key '${key}' doesn't yet have any associated callback.`);
         }
 
+        if (this._key === key) { return; }
         this._key = key;
 
         if (this._isEnabled)

package/src/models/callbacks/types.ts

@@ -4,10 +4,15 @@
  * It can be used to define the signature of a callback, a event handler or any other function.  
  * It's simply a shorthand for the `(...args: A) => R` function signature.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * const callback: Callback<[PointerEvent]> = (evt: PointerEvent): void => { [...] };
  * ```
  *
+ * ---
+ *
  * @template A
  * The type of the arguments that the function accepts.  
  * It must be an array of types, even if it's empty. Default is `[]`.
@@ -15,3 +20,30 @@
  * @template R The return type of the function. Default is `void`.
  */
 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.  
+ * Whenever you'll need to extend that class, you may need to use this type too.
+ *
+ * ---
+ *
+ * @example
+ * ```ts
+ * interface EventsMap
+ * {
+ *     "player:spawn": (evt: SpawnEvent) => void;
+ *     "player:move": ({ x, y }: Point) => void;
+ *     "player:death": () => void;
+ * }
+ *
+ * class EventManager<T extends CallbackMap<T> = { }> extends Publisher<T> { [...] }
+ * ```
+ *
+ * ---
+ *
+ * @template T The interface defining the map of callbacks. Default is `Record<string, Callback<unknown[], unknown>>`.
+ */
+// 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> };

package/src/models/exceptions/core.ts

@@ -5,6 +5,9 @@
  * It allows to chain exceptions together, tracking the initial cause of an error and
  * storing its stack trace while providing a clear and friendly message to the user.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * try { loadGameSaves(); }
  * catch (error)
@@ -109,6 +112,9 @@ export default class Exception extends Error
  *
  * It provides a clear and friendly message by default.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * function checkCase(value: "A" | "B" | "C"): 1 | 2 | 3
  * {
@@ -160,6 +166,9 @@ export class FatalErrorException extends Exception
  *
  * It provides a clear and friendly message by default.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * class Database
  * {