@byloth/core 2.0.0 → 2.0.2

package/src/models/exceptions/index.ts

@@ -6,6 +6,9 @@ import Exception from "./core.js";
  *
  * It can also be used to catch all file-related exceptions at once.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * try { [...] }
  * catch (error)
@@ -22,10 +25,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"`.
@@ -41,6 +49,9 @@ export class FileException extends Exception
 /**
  * A class representing an exception that can be thrown when a file already exists.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * import { existsSync } from "node:fs";
  *
@@ -55,10 +66,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"`.
@@ -74,6 +90,9 @@ export class FileExistsException extends FileException
 /**
  * A class representing an exception that can be thrown when a file isn't found.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * import { existsSync } from "node:fs";
  *
@@ -88,10 +107,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"`.
@@ -108,6 +132,9 @@ export class FileNotFoundException extends FileException
  * 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...
  *
+ * ---
+ *
+ * @example
  * ```ts
  * const map = new Map<string, number>();
  * if (!map.has("hash"))
@@ -121,10 +148,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"`.
@@ -141,6 +173,9 @@ export class KeyException extends Exception
  * 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.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * import axios, { isAxiosError } from "axios";
  *
@@ -162,10 +197,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"`.
@@ -180,8 +220,11 @@ export class NetworkException extends Exception
 
 /**
  * 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.
+ * It's commonly used when an user tries to access a restricted resource or perform a forbidden action.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * const $user = useUserStore();
  * if (!$user.isAdmin)
@@ -195,10 +238,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"`.
@@ -215,6 +263,9 @@ export class PermissionException extends Exception
  * 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.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * const $el = document.getElementById("app");
  * if ($el === null)
@@ -228,10 +279,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"`.
@@ -248,6 +304,9 @@ export class ReferenceException extends Exception
  * 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.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * let status: "enabled" | "disabled" = "enabled";
  *
@@ -263,10 +322,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"`.
@@ -284,6 +348,9 @@ export class RuntimeException extends Exception
  * 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.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * if (!navigator.geolocation)
  * {
@@ -296,10 +363,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"`.
@@ -316,6 +388,9 @@ export class EnvironmentException extends RuntimeException
  * 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.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * const timeoutId = setTimeout(() => { throw new TimeoutException("The request timed out."); }, 5_000);
  * const response = await fetch("https://api.example.com/data");
@@ -328,10 +403,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"`.
@@ -348,6 +428,9 @@ export class TimeoutException extends Exception
  * 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.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * function greet(name: string): void
  * {
@@ -363,10 +446,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"`.
@@ -383,6 +471,9 @@ export class TypeException extends Exception
  * 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.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * function setVolume(value: number): void
  * {
@@ -398,10 +489,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"`.
@@ -418,6 +514,9 @@ export class ValueException extends Exception
  * 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.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * function setVolume(value: number): void
  * {
@@ -433,10 +532,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"`.