@byloth/core 2.0.0 → 2.0.1

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

@@ -3,6 +3,8 @@ 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.
  *
@@ -76,28 +78,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 +140,50 @@ 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 +192,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 +207,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 +218,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 +253,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 +283,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

package/src/models/exceptions/core.ts

@@ -26,6 +26,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 +39,8 @@ export default class Exception extends Error
      * }
      * ```
      *
+     * ---
+     *
      * @param error The caught error to convert.
      *
      * @returns An instance of the {@link Exception} class.
@@ -62,10 +67,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"`.
@@ -117,10 +127,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"`.
@@ -160,10 +175,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"`.

package/src/models/exceptions/index.ts

@@ -22,10 +22,15 @@ export class FileException extends Exception
     /**
      * Initializes a new instance of the {@link FileException} class.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * throw new FileException("An error occurred while trying to read the file.");
      * ```
      *
+     * ---
+     *
      * @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 `"FileException"`.
@@ -55,10 +60,15 @@ export class FileExistsException extends FileException
     /**
      * Initializes a new instance of the {@link FileExistsException} class.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * throw new FileExistsException("The file named 'data.json' already exists on the server.");
      * ```
      *
+     * ---
+     *
      * @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 `"FileExistsException"`.
@@ -88,10 +98,15 @@ export class FileNotFoundException extends FileException
     /**
      * Initializes a new instance of the {@link FileNotFoundException} class.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * throw new FileNotFoundException("The file named 'data.json' wasn't found on the server.");
      * ```
      *
+     * ---
+     *
      * @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 `"FileNotFoundException"`.
@@ -121,10 +136,15 @@ export class KeyException extends Exception
     /**
      * Initializes a new instance of the {@link KeyException} class.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * throw new KeyException("The 'id' key wasn't found in the dictionary.");
      * ```
      *
+     * ---
+     *
      * @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 `"KeyException"`.
@@ -162,10 +182,15 @@ export class NetworkException extends Exception
     /**
      * Initializes a new instance of the {@link NetworkException} class.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * throw new NetworkException("Couldn't connect to the server. Please, try again 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 `"NetworkException"`.
@@ -195,10 +220,15 @@ export class PermissionException extends Exception
     /**
      * Initializes a new instance of the {@link PermissionException} class.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * throw new PermissionException("You don't have permission to access this resource.");
      * ```
      *
+     * ---
+     *
      * @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 `"PermissionException"`.
@@ -228,10 +258,15 @@ export class ReferenceException extends Exception
     /**
      * Initializes a new instance of the {@link ReferenceException} class.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * throw new ReferenceException("The 'canvas' element wasn't found in the document.");
      * ```
      *
+     * ---
+     *
      * @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 `"ReferenceException"`.
@@ -263,10 +298,15 @@ export class RuntimeException extends Exception
     /**
      * Initializes a new instance of the {@link RuntimeException} class.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * throw new RuntimeException("The received input seems to be malformed or corrupted.");
      * ```
      *
+     * ---
+     *
      * @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 `"RuntimeException"`.
@@ -296,10 +336,15 @@ export class EnvironmentException extends RuntimeException
     /**
      * Initializes a new instance of the {@link EnvironmentException} class.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * throw new EnvironmentException("The required environment variable 'API_KEY' isn't set.");
      * ```
      *
+     * ---
+     *
      * @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 `"EnvironmentException"`.
@@ -328,10 +373,15 @@ export class TimeoutException extends Exception
     /**
      * Initializes a new instance of the {@link TimeoutException} class.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * throw new TimeoutException("The task took too long to complete.");
      * ```
      *
+     * ---
+     *
      * @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 `"TimeoutException"`.
@@ -363,10 +413,15 @@ export class TypeException extends Exception
     /**
      * Initializes a new instance of the {@link TypeException} class.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * throw new TypeException("The 'username' argument must be a valid string.");
      * ```
      *
+     * ---
+     *
      * @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 `"TypeException"`.
@@ -398,10 +453,15 @@ export class ValueException extends Exception
     /**
      * Initializes a new instance of the {@link ValueException} class.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * throw new ValueException("The 'grade' argument cannot be negative.");
      * ```
      *
+     * ---
+     *
      * @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 `"ValueException"`.
@@ -433,10 +493,15 @@ export class RangeException extends ValueException
     /**
      * Initializes a new instance of the {@link RangeException} class.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * throw new RangeException("The 'percentage' argument must be between 0 and 100.");
      * ```
      *
+     * ---
+     *
      * @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 `"RangeException"`.