@byloth/core 2.0.0-rc.9 → 2.0.1

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

@@ -3,58 +3,203 @@ 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.
+ *
+ * ```ts
+ * const onPointerMove = new SwitchableCallback<(evt: PointerEvent) => void>();
+ *
+ * onPointerMove.register("released", () => { [...] });
+ * onPointerMove.register("pressed", () => { [...] });
+ *
+ * window.addEventListener("pointerdown", () => { onPointerMove.switch("pressed"); });
+ * window.addEventListener("pointermove", onPointerMove);
+ * 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
 export default class SwitchableCallback<T extends Callback<any[], any> = Callback> extends CallableObject<T>
 {
+    /**
+     * The currently selected implementation of the callback.
+     */
     protected _callback: T;
+
+    /**
+     * All the implementations that have been registered for the callback.
+     *
+     * The keys are the names of the implementations they were registered with.  
+     * The values are the implementations themselves.
+     */
     protected _callbacks: Map<string, T>;
 
+    /**
+     * A flag indicating whether the callback is enabled or not.
+     *
+     * This protected property is the only one that can be modified directly by the derived classes.  
+     * If you're looking for the public and readonly property, use
+     * the {@link SwitchableCallback.isEnabled} getter instead.
+     */
     protected _isEnabled: boolean;
+
+    /**
+     * A flag indicating whether the callback is enabled or not.
+     *
+     * It indicates whether the callback is currently able to execute the currently selected implementation.  
+     * If it's disabled, the callback will be invoked without executing anything.
+     */
     public get isEnabled(): boolean { return this._isEnabled; }
 
+    /**
+     * The key that is associated with the currently selected implementation.
+     *
+     * This protected property is the only one that can be modified directly by the derived classes.  
+     * If you're looking for the public and readonly property, use the {@link SwitchableCallback.key} getter instead.
+     */
     protected _key: string;
+
+    /**
+     * The key that is associated with the currently selected implementation.
+     */
     public get key(): string { return this._key; }
 
-    public readonly invoke: (...args: Parameters<T>) => ReturnType<T>;
+    /**
+     * The function that will be called by the extended class when the object is invoked as a function.
+     */
+    protected readonly _invoke: (...args: Parameters<T>) => ReturnType<T>;
 
-    public constructor()
-    {
-        const _default = () =>
-        {
-            throw new NotImplementedException(
-                "The `SwitchableCallback` has no callback defined yet. " +
-                "Did you forget to call the `register` method?"
-            );
-        };
+    /**
+     * Initializes a new instance of the {@link SwitchableCallback} class.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * const onPointerMove = new SwitchableCallback<(evt: PointerEvent) => void>();
+     * ```
+     */
+    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._isEnabled = false;
-        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.invoke = (...args: Parameters<T>): ReturnType<T> => this._callback(...args);
+        this._key = key;
+
+        this._callback = callback;
+        this._invoke = (...args: Parameters<T>): ReturnType<T> => this._callback(...args);
     }
 
-    public enable(): void
+    /**
+     * Enables the callback, allowing it to execute the currently selected implementation.
+     *
+     * 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(key?: string): void
     {
-        if (!(this._key))
+        if (key === undefined)
+        {
+            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 `SwitchableCallback` has no callback defined yet. " +
-                "Did you forget to call the `register` method?"
-            );
+            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;
     }
+
+    /**
+     * Disables the callback, allowing it to be invoked without executing any implementation.
+     *
+     * If the callback is already disabled, a {@link RuntimeException} will be thrown.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * window.addEventListener("pointermove", onPointerMove);
+     * window.addEventListener("pointerup", () => { onPointerMove.disable(); });
+     * ```
+     */
     public disable(): void
     {
         if (!(this._isEnabled))
@@ -62,11 +207,30 @@ 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;
     }
 
+    /**
+     * Registers a new implementation for the callback.
+     *
+     * Also note that:
+     * - 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.
+     */
     public register(key: string, callback: T): void
     {
         if (this._callbacks.size === 0)
@@ -81,8 +245,31 @@ export default class SwitchableCallback<T extends Callback<any[], any> = Callbac
 
         this._callbacks.set(key, callback);
     }
+
+    /**
+     * Unregisters an implementation for the callback.
+     *
+     * Also note that:
+     * - 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
     {
+        if (this._key === key)
+        {
+            throw new KeyException("Unable to unregister the currently selected callback.");
+        }
         if (!(this._callbacks.has(key)))
         {
             throw new KeyException(`The key '${key}' doesn't yet have any associated callback.`);
@@ -91,6 +278,24 @@ export default class SwitchableCallback<T extends Callback<any[], any> = Callbac
         this._callbacks.delete(key);
     }
 
+    /**
+     * Switches the callback to the implementation associated with the given key.
+     *
+     * 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
     {
         if (!(this._callbacks.has(key)))
@@ -105,4 +310,6 @@ export default class SwitchableCallback<T extends Callback<any[], any> = Callbac
             this._callback = this._callbacks.get(key)!;
         }
     }
+
+    public override readonly [Symbol.toStringTag]: string = "SwitchableCallback";
 }

package/src/models/callbacks/types.ts

@@ -1 +1,17 @@
+/**
+ * A type that represents a generic function.
+ *
+ * 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.
+ *
+ * ```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 `[]`.
+ *
+ * @template R The return type of the function. Default is `void`.
+ */
 export type Callback<A extends unknown[] = [], R = void> = (...args: A) => R;

package/src/models/exceptions/core.ts

@@ -1,5 +1,50 @@
+/**
+ * A class representing an exception, subclass of the native `Error` class.  
+ * It's the base class for any other further exception.
+ *
+ * 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.
+ *
+ * ```ts
+ * try { loadGameSaves(); }
+ * catch (error)
+ * {
+ *     throw new Exception("The game saves may be corrupted. Try to restart the game.", error);
+ *     // 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
+ *     //     at /src/models/saves.ts:47:17
+ *     //     at /src/game/index.ts:12:9
+ *     //     at /src/main.ts:23:17
+ * }
+ * ```
+ */
 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)
+     * {
+     *     const exc = Exception.FromUnknown(error);
+     *
+     *     [...]
+     * }
+     * ```
+     *
+     * ---
+     *
+     * @param error The caught error to convert.
+     *
+     * @returns An instance of the {@link Exception} class.
+     */
     public static FromUnknown(error: unknown): Exception
     {
         if (error instanceof Exception)
@@ -19,6 +64,22 @@ export default class Exception extends Error
         return new Exception(`${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"`.
+     */
     public constructor(message: string, cause?: unknown, name = "Exception")
     {
         super(message);
@@ -42,8 +103,43 @@ export default class Exception extends Error
     public readonly [Symbol.toStringTag]: string = "Exception";
 }
 
+/**
+ * An utility class representing that kind of situation where the program should never reach.  
+ * Also commonly used to satisfy the type-system, but not part of a real feasible scenario.
+ *
+ * It provides a clear and friendly message by default.
+ *
+ * ```ts
+ * function checkCase(value: "A" | "B" | "C"): 1 | 2 | 3
+ * {
+ *     switch (value)
+ *     {
+ *         case "A": return 1;
+ *         case "B": return 2;
+ *         case "C": return 3;
+ *         default: throw new FatalErrorException();
+ *     }
+ * }
+ * ```
+ */
 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"`.
+     */
     public constructor(message?: string, cause?: unknown, name = "FatalErrorException")
     {
         if (message === undefined)
@@ -55,19 +151,52 @@ export class FatalErrorException extends Exception
         super(message, cause, name);
     }
 
-    public readonly [Symbol.toStringTag]: string = "FatalErrorException";
+    public override readonly [Symbol.toStringTag]: string = "FatalErrorException";
 }
+
+/**
+ * An utility class representing a situation where a feature isn't implemented yet.  
+ * It's commonly used as a placeholder for future implementations.
+ *
+ * It provides a clear and friendly message by default.
+ *
+ * ```ts
+ * class Database
+ * {
+ *     public async connect(): Promise<void>
+ *     {
+ *         throw new NotImplementedException();
+ *     }
+ * }
+ * ```
+ */
 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"`.
+     */
     public constructor(message?: string, cause?: unknown, name = "NotImplementedException")
     {
         if (message === undefined)
         {
-            message = "This feature is not implemented yet. Please, try again later.";
+            message = "This feature isn't implemented yet. Please, try again later.";
         }
 
         super(message, cause, name);
     }
 
-    public readonly [Symbol.toStringTag]: string = "NotImplementedException";
+    public override readonly [Symbol.toStringTag]: string = "NotImplementedException";
 }