@byloth/core 2.0.0-rc.9 → 2.0.0

package/src/models/exceptions/core.ts

@@ -1,5 +1,45 @@
+/**
+ * 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.
+     *
+     * ```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 +59,17 @@ export default class Exception extends Error
         return new Exception(`${error}`);
     }
 
+    /**
+     * Initializes a new instance of the {@link Exception} class.
+     *
+     * ```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 +93,38 @@ 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.
+     *
+     * ```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 +136,47 @@ 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.
+     *
+     * ```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";
 }

package/src/models/exceptions/index.ts

@@ -1,125 +1,452 @@
 import Exception from "./core.js";
 
+/**
+ * A class representing a generic exception that can be thrown when a file
+ * operation fails, such as reading, writing, copying, moving, deleting, etc...
+ *
+ * It can also be used to catch all file-related exceptions at once.
+ *
+ * ```ts
+ * try { [...] }
+ * catch (error)
+ * {
+ *     if (error instanceof FileException)
+ *     {
+ *         // A file-related exception occurred. Handle it...
+ *     }
+ * }
+ * ```
+ */
 export class FileException extends Exception
 {
+    /**
+     * Initializes a new instance of the {@link FileException} class.
+     *
+     * ```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"`.
+     */
     public constructor(message: string, cause?: unknown, name = "FileException")
     {
         super(message, cause, name);
     }
 
-    public readonly [Symbol.toStringTag]: string = "FileException";
+    public override readonly [Symbol.toStringTag]: string = "FileException";
 }
+
+/**
+ * A class representing an exception that can be thrown when a file already exists.
+ *
+ * ```ts
+ * import { existsSync } from "node:fs";
+ *
+ * if (existsSync("file.txt"))
+ * {
+ *     throw new FileExistsException("The file named 'file.txt' already exists.");
+ * }
+ * ```
+ */
 export class FileExistsException extends FileException
 {
+    /**
+     * Initializes a new instance of the {@link FileExistsException} class.
+     *
+     * ```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"`.
+     */
     public constructor(message: string, cause?: unknown, name = "FileExistsException")
     {
         super(message, cause, name);
     }
 
-    public readonly [Symbol.toStringTag]: string = "FileExistsException";
+    public override readonly [Symbol.toStringTag]: string = "FileExistsException";
 }
+
+/**
+ * A class representing an exception that can be thrown when a file isn't found.
+ *
+ * ```ts
+ * import { existsSync } from "node:fs";
+ *
+ * if (!existsSync("file.txt"))
+ * {
+ *     throw new FileNotFoundException("The file named 'file.txt' wasn't found.");
+ * }
+ * ```
+ */
 export class FileNotFoundException extends FileException
 {
+    /**
+     * Initializes a new instance of the {@link FileNotFoundException} class.
+     *
+     * ```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"`.
+     */
     public constructor(message: string, cause?: unknown, name = "FileNotFoundException")
     {
         super(message, cause, name);
     }
 
-    public readonly [Symbol.toStringTag]: string = "FileNotFoundException";
+    public override readonly [Symbol.toStringTag]: string = "FileNotFoundException";
 }
 
+/**
+ * A class representing an exception that can be thrown when a key is invalid or not found.  
+ * It's commonly used when working with dictionaries, maps, objects, sets, etc...
+ *
+ * ```ts
+ * const map = new Map<string, number>();
+ * if (!map.has("hash"))
+ * {
+ *     throw new KeyException("The key 'hash' wasn't found in the collection.");
+ * }
+ * ```
+ */
 export class KeyException extends Exception
 {
+    /**
+     * Initializes a new instance of the {@link KeyException} class.
+     *
+     * ```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"`.
+     */
     public constructor(message: string, cause?: unknown, name = "KeyException")
     {
         super(message, cause, name);
     }
 
-    public readonly [Symbol.toStringTag]: string = "KeyException";
+    public override readonly [Symbol.toStringTag]: string = "KeyException";
 }
+
+/**
+ * A class representing an exception that can be thrown when a network operation fails.  
+ * It's commonly used when it's unable to connect to a server or when a request times out.
+ *
+ * ```ts
+ * import axios, { isAxiosError } from "axios";
+ *
+ * try { await axios.get("https://api.example.com/data"); }
+ * catch (error)
+ * {
+ *     if (isAxiosError(error) && !error.response)
+ *     {
+ *         throw new NetworkException(
+ *             "Unable to establish a connection to the server. " +
+ *             "Please, check your internet connection and try again."
+ *         );
+ *     }
+ * }
+ * ```
+ */
 export class NetworkException extends Exception
 {
+    /**
+     * Initializes a new instance of the {@link NetworkException} class.
+     *
+     * ```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"`.
+     */
     public constructor(message: string, cause?: unknown, name = "NetworkException")
     {
         super(message, cause, name);
     }
 
-    public readonly [Symbol.toStringTag]: string = "NetworkException";
+    public override readonly [Symbol.toStringTag]: string = "NetworkException";
 }
+
+/**
+ * A class representing an exception that can be thrown when a permission is denied.  
+ * It's commonly used when a user tries to access a restricted resource or perform a forbidden action.
+ *
+ * ```ts
+ * const $user = useUserStore();
+ * if (!$user.isAdmin)
+ * {
+ *     throw new PermissionException("You don't have permission to perform this action.");
+ * }
+ * ```
+ */
 export class PermissionException extends Exception
 {
+    /**
+     * Initializes a new instance of the {@link PermissionException} class.
+     *
+     * ```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"`.
+     */
     public constructor(message: string, cause?: unknown, name = "PermissionException")
     {
         super(message, cause, name);
     }
 
-    public readonly [Symbol.toStringTag]: string = "PermissionException";
+    public override readonly [Symbol.toStringTag]: string = "PermissionException";
 }
+
+/**
+ * A class representing an exception that can be thrown when a reference is invalid or not found.  
+ * It's commonly used when a variable is `null`, `undefined` or when an object doesn't exist.
+ *
+ * ```ts
+ * const $el = document.getElementById("app");
+ * if ($el === null)
+ * {
+ *     throw new ReferenceException("The element with the ID 'app' wasn't found in the document.");
+ * }
+ * ```
+ */
 export class ReferenceException extends Exception
 {
+    /**
+     * Initializes a new instance of the {@link ReferenceException} class.
+     *
+     * ```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"`.
+     */
     public constructor(message: string, cause?: unknown, name = "ReferenceException")
     {
         super(message, cause, name);
     }
 
-    public readonly [Symbol.toStringTag]: string = "ReferenceException";
+    public override readonly [Symbol.toStringTag]: string = "ReferenceException";
 }
 
+/**
+ * A class representing an exception that can be thrown when a runtime error occurs.  
+ * It's commonly used when an unexpected condition is encountered during the execution of a program.
+ *
+ * ```ts
+ * let status: "enabled" | "disabled" = "enabled";
+ *
+ * function enable(): void
+ * {
+ *     if (status === "enabled") { throw new RuntimeException("The feature is already enabled."); }
+ *     status = "enabled";
+ * }
+ * ```
+ */
 export class RuntimeException extends Exception
 {
+    /**
+     * Initializes a new instance of the {@link RuntimeException} class.
+     *
+     * ```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"`.
+     */
     public constructor(message: string, cause?: unknown, name = "RuntimeException")
     {
         super(message, cause, name);
     }
 
-    public readonly [Symbol.toStringTag]: string = "RuntimeException";
+    public override readonly [Symbol.toStringTag]: string = "RuntimeException";
 }
+
+/**
+ * A class representing an exception that can be thrown when an environment
+ * isn't properly configured or when a required variable isn't set.  
+ * It can also be used when the environment on which the program is running is unsupported.
+ *
+ * ```ts
+ * if (!navigator.geolocation)
+ * {
+ *     throw new EnvironmentException("The Geolocation API isn't supported in this environment.");
+ * }
+ * ```
+ */
 export class EnvironmentException extends RuntimeException
 {
+    /**
+     * Initializes a new instance of the {@link EnvironmentException} class.
+     *
+     * ```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"`.
+     */
     public constructor(message: string, cause?: unknown, name = "EnvironmentException")
     {
         super(message, cause, name);
     }
 
-    public readonly [Symbol.toStringTag]: string = "EnvironmentException";
+    public override readonly [Symbol.toStringTag]: string = "EnvironmentException";
 }
 
+/**
+ * A class representing an exception that can be thrown when a timeout occurs.  
+ * It's commonly used when a task takes too long to complete or when a request times out.
+ *
+ * ```ts
+ * const timeoutId = setTimeout(() => { throw new TimeoutException("The request timed out."); }, 5_000);
+ * const response = await fetch("https://api.example.com/data");
+ *
+ * clearTimeout(timeoutId);
+ * ```
+ */
 export class TimeoutException extends Exception
 {
+    /**
+     * Initializes a new instance of the {@link TimeoutException} class.
+     *
+     * ```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"`.
+     */
     public constructor(message: string, cause?: unknown, name = "TimeoutException")
     {
         super(message, cause, name);
     }
 
-    public readonly [Symbol.toStringTag]: string = "TimeoutException";
+    public override readonly [Symbol.toStringTag]: string = "TimeoutException";
 }
+
+/**
+ * A class representing an exception that can be thrown when a type is invalid or not supported.  
+ * It's commonly used when a function receives an unexpected type of argument.
+ *
+ * ```ts
+ * function greet(name: string): void
+ * {
+ *     if (typeof name !== "string")
+ *     {
+ *         throw new TypeException("The 'name' argument must be a valid string.");
+ *     }
+ * }
+ * ```
+ */
 export class TypeException extends Exception
 {
+    /**
+     * Initializes a new instance of the {@link TypeException} class.
+     *
+     * ```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"`.
+     */
     public constructor(message: string, cause?: unknown, name = "TypeException")
     {
         super(message, cause, name);
     }
 
-    public readonly [Symbol.toStringTag]: string = "TypeException";
+    public override readonly [Symbol.toStringTag]: string = "TypeException";
 }
 
+/**
+ * A class representing an exception that can be thrown when a value is invalid.  
+ * It's commonly used when a function receives an unexpected value as an argument.
+ *
+ * ```ts
+ * function setVolume(value: number): void
+ * {
+ *     if (value < 0)
+ *     {
+ *         throw new ValueException("The 'value' argument must be greater than or equal to 0.");
+ *     }
+ * }
+ * ```
+ */
 export class ValueException extends Exception
 {
+    /**
+     * Initializes a new instance of the {@link ValueException} class.
+     *
+     * ```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"`.
+     */
     public constructor(message: string, cause?: unknown, name = "ValueException")
     {
         super(message, cause, name);
     }
 
-    public readonly [Symbol.toStringTag]: string = "ValueException";
+    public override readonly [Symbol.toStringTag]: string = "ValueException";
 }
+
+/**
+ * A class representing an exception that can be thrown when a value is out of range.  
+ * It's commonly used when a function receives an unexpected value as an argument.
+ *
+ * ```ts
+ * function setVolume(value: number): void
+ * {
+ *     if ((value < 0) || (value > 100))
+ *     {
+ *         throw new RangeException("The 'value' argument must be between 0 and 100.");
+ *     }
+ * }
+ * ```
+ */
 export class RangeException extends ValueException
 {
+    /**
+     * Initializes a new instance of the {@link RangeException} class.
+     *
+     * ```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"`.
+     */
     public constructor(message: string, cause?: unknown, name = "RangeException")
     {
         super(message, cause, name);
     }
 
-    public readonly [Symbol.toStringTag]: string = "RangeException";
+    public override readonly [Symbol.toStringTag]: string = "RangeException";
 }
 
 export { Exception };

package/src/models/index.ts

@@ -5,11 +5,12 @@ export {
 
 } from "./aggregators/index.js";
 
-export { CallableObject, Publisher, SmartFunction, SwitchableCallback } from "./callbacks/index.js";
+export { CallableObject, Publisher, SwitchableCallback } from "./callbacks/index.js";
 export {
     Exception,
     FatalErrorException,
     NotImplementedException,
+    EnvironmentException,
     FileException,
     FileExistsException,
     FileNotFoundException,
@@ -25,12 +26,7 @@ export {
 
 } from "./exceptions/index.js";
 
-import GameLoop from "./game-loop.js";
-
 export { SmartIterator, SmartAsyncIterator } from "./iterators/index.js";
 export { JSONStorage } from "./json/index.js";
-export { DeferredPromise, LongRunningTask, SmartPromise, Thenable, TimedPromise } from "./promises/index.js";
-
-export { Clock, Countdown } from "./timers/index.js";
-
-export { GameLoop };
+export { DeferredPromise, SmartPromise, TimedPromise } from "./promises/index.js";
+export { Clock, Countdown, GameLoop } from "./timers/index.js";