@byloth/core 2.0.0 → 2.0.2

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,11 +48,14 @@ 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.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * const publisher = new Publisher();
      * ```
@@ -61,6 +68,9 @@ export default class Publisher<T extends { [K in keyof T]: Callback<any[], any>
     /**
      * Unsubscribes all the subscribers from all the events.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * publisher.subscribe("player:spawn", (evt) => { [...] });
      * publisher.subscribe("player:move", (coords) => { [...] });
@@ -83,6 +93,9 @@ export default class Publisher<T extends { [K in keyof T]: Callback<any[], any>
     /**
      * Publishes an event to all the subscribers.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * publisher.subscribe("player:move", (coords) => { [...] });
      * publisher.subscribe("player:move", ({ x, y }) => { [...] });
@@ -91,6 +104,8 @@ export default class Publisher<T extends { [K in keyof T]: Callback<any[], any>
      * publisher.publish("player:move", { x: 10, y: 20 });
      * ```
      *
+     * ---
+     *
      * @template K The key of the map containing the callback signature to publish.
      *
      * @param event The name of the event to publish.
@@ -98,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 []; }
@@ -110,6 +125,9 @@ export default class Publisher<T extends { [K in keyof T]: Callback<any[], any>
     /**
      * Subscribes a new subscriber to an event.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * let unsubscribe: () => void;
      * publisher.subscribe("player:death", unsubscribe);
@@ -119,6 +137,8 @@ export default class Publisher<T extends { [K in keyof T]: Callback<any[], any>
      * });
      * ```
      *
+     * ---
+     *
      * @template K The key of the map containing the callback signature to subscribe.
      *
      * @param event The name of the event to subscribe to.
@@ -126,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, []); }
 
@@ -149,6 +169,9 @@ export default class Publisher<T extends { [K in keyof T]: Callback<any[], any>
     /**
      * Unsubscribes a subscriber from an event.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * const onPlayerMove = ({ x, y }: Point) => { [...] };
      *
@@ -156,12 +179,14 @@ export default class Publisher<T extends { [K in keyof T]: Callback<any[], any>
      * publisher.subscribe("player:death", () => publisher.unsubscribe("player:move", onPlayerMove));
      * ```
      *
+     * ---
+     *
      * @template K The key of the map containing the callback signature to unsubscribe.
      *
      * @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

@@ -3,12 +3,17 @@ import { KeyException, NotImplementedException, RuntimeException } from "../exce
 import CallableObject from "./callable-object.js";
 import type { Callback } from "./types.js";
 
+const Disabler = () => { /* ... */ };
+
 /**
  * A class representing a callback that can be switched between multiple implementations.
  *
  * 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>();
  *
@@ -20,6 +25,8 @@ import type { Callback } from "./types.js";
  * 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
@@ -76,28 +83,60 @@ export default class SwitchableCallback<T extends Callback<any[], any> = Callbac
     /**
      * Initializes a new instance of the {@link SwitchableCallback} class.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * const onPointerMove = new SwitchableCallback<(evt: PointerEvent) => void>();
      * ```
      */
-    public constructor()
-    {
-        const _default = () =>
-        {
-            throw new NotImplementedException(
-                "The `SwitchableCallback` has no callback defined yet. " +
-                "Did you forget to call the `register` method?"
-            );
-        };
+    public constructor();
 
+    /**
+     * Initializes a new instance of the {@link SwitchableCallback}
+     * class with the specified callback enabled by default.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * const onPointerMove = new SwitchableCallback<(evt: PointerEvent) => void>((evt) => { [...] });
+     * ```
+     *
+     * ---
+     *
+     * @param callback The callback that will be executed when the object is invoked as a function by default.
+     * @param key The key that is associated by default to the given callback. Default is `default`.
+     */
+    public constructor(callback: T, key?: string);
+    public constructor(callback?: T, key = "default")
+    {
         super();
 
-        this._callback = ((_default) as unknown) as T;
         this._callbacks = new Map<string, T>();
-
         this._isEnabled = true;
-        this._key = "";
 
+        if (callback)
+        {
+            this._callbacks.set(key, callback);
+        }
+        else
+        {
+            key = "";
+
+            callback = ((() =>
+            {
+                throw new NotImplementedException(
+                    "The `SwitchableCallback` has no callback defined yet. " +
+                    "Did you forget to call the `register` method?"
+                );
+
+            }) as unknown) as T;
+        }
+
+        this._key = key;
+
+        this._callback = callback;
         this._invoke = (...args: Parameters<T>): ReturnType<T> => this._callback(...args);
     }
 
@@ -106,28 +145,52 @@ export default class SwitchableCallback<T extends Callback<any[], any> = Callbac
      *
      * Also note that:
      * - If any implementation has been registered yet, a {@link KeyException} will be thrown.  
+     * - If any key is given and it doesn't have any associated
+     * implementation yet, a {@link KeyException} will be thrown.
      * - If the callback is already enabled, a {@link RuntimeException} will be thrown.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * 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.
      */
-    public enable(): void
+    public enable(key?: string): void
     {
-        if (!(this._key))
+        if (key === undefined)
         {
-            throw new KeyException(
-                "The `SwitchableCallback` has no callback defined yet. " +
-                "Did you forget to call the `register` method?"
-            );
+            if (!(this._key))
+            {
+                throw new KeyException(
+                    "The `SwitchableCallback` has no callback defined yet. " +
+                    "Did you forget to call the `register` method?"
+                );
+            }
+
+            key = this._key;
         }
+        else if (!(key))
+        {
+            throw new KeyException("The key must be a non-empty string.");
+        }
+        else if (!(this._callbacks.has(key)))
+        {
+            throw new KeyException(`The key '${key}' doesn't yet have any associated callback.`);
+        }
+
         if (this._isEnabled)
         {
             throw new RuntimeException("The `SwitchableCallback` is already enabled.");
         }
 
-        this._callback = this._callbacks.get(this._key)!;
+        this._callback = this._callbacks.get(key)!;
         this._isEnabled = true;
     }
 
@@ -136,6 +199,9 @@ export default class SwitchableCallback<T extends Callback<any[], any> = Callbac
      *
      * If the callback is already disabled, a {@link RuntimeException} will be thrown.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * window.addEventListener("pointermove", onPointerMove);
      * window.addEventListener("pointerup", () => { onPointerMove.disable(); });
@@ -148,8 +214,7 @@ export default class SwitchableCallback<T extends Callback<any[], any> = Callbac
             throw new RuntimeException("The `SwitchableCallback` is already disabled.");
         }
 
-        // eslint-disable-next-line @typescript-eslint/no-empty-function
-        this._callback = (() => { }) as T;
+        this._callback = Disabler as T;
         this._isEnabled = false;
     }
 
@@ -160,11 +225,16 @@ export default class SwitchableCallback<T extends Callback<any[], any> = Callbac
      * - If the callback has no other implementation registered yet, this one will be selected as default.
      * - If the key has already been used for another implementation, a {@link KeyException} will be thrown.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * onPointerMove.register("pressed", () => { [...] });
      * onPointerMove.register("released", () => { [...] });
      * ```
      *
+     * ---
+     *
      * @param key The key that will be associated with the implementation.
      * @param callback The implementation to register.
      */
@@ -190,10 +260,15 @@ export default class SwitchableCallback<T extends Callback<any[], any> = Callbac
      * - If the key is the currently selected implementation, a {@link KeyException} will be thrown.
      * - If the key has no associated implementation yet, a {@link KeyException} will be thrown.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * onPointerMove.unregister("released");
      * ```
      *
+     * ---
+     *
      * @param key The key that is associated with the implementation to unregister.
      */
     public unregister(key: string): void
@@ -215,12 +290,17 @@ export default class SwitchableCallback<T extends Callback<any[], any> = Callbac
      *
      * If the key has no associated implementation yet, a {@link KeyException} will be thrown.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * window.addEventListener("pointerdown", () => { onPointerMove.switch("pressed"); });
      * window.addEventListener("pointermove", onPointerMove);
      * window.addEventListener("pointerup", () => { onPointerMove.switch("released"); });
      * ```
      *
+     * ---
+     *
      * @param key The key that is associated with the implementation to switch to.
      */
     public switch(key: string): void
@@ -230,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)
@@ -26,6 +29,9 @@ export default class Exception extends Error
     /**
      * A static method to convert a generic caught error, ensuring it's an instance of the {@link Exception} class.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * try { [...] }
      * catch (error)
@@ -36,6 +42,8 @@ export default class Exception extends Error
      * }
      * ```
      *
+     * ---
+     *
      * @param error The caught error to convert.
      *
      * @returns An instance of the {@link Exception} class.
@@ -62,10 +70,15 @@ export default class Exception extends Error
     /**
      * Initializes a new instance of the {@link Exception} class.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * throw new Exception("An error occurred while processing the request.");
      * ```
      *
+     * ---
+     *
      * @param message The message that describes the error.
      * @param cause The previous caught error that caused this one, if any.
      * @param name The name of the exception. Default is `"Exception"`.
@@ -99,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
  * {
@@ -117,10 +133,15 @@ export class FatalErrorException extends Exception
     /**
      * Initializes a new instance of the {@link FatalErrorException} class.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * throw new FatalErrorException("This error should never happen. Please, contact the support team.");
      * ```
      *
+     * ---
+     *
      * @param message The message that describes the error.
      * @param cause The previous caught error that caused this one, if any.
      * @param name The name of the exception. Default is `"FatalErrorException"`.
@@ -145,6 +166,9 @@ export class FatalErrorException extends Exception
  *
  * It provides a clear and friendly message by default.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * class Database
  * {
@@ -160,10 +184,15 @@ export class NotImplementedException extends FatalErrorException
     /**
      * Initializes a new instance of the {@link NotImplementedException} class.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * throw new NotImplementedException("This method hasn't been implemented yet. Check back later.");
      * ```
      *
+     * ---
+     *
      * @param message The message that describes the error.
      * @param cause The previous caught error that caused this one, if any.
      * @param name The name of the exception. Default is `"NotImplementedException"`.