@arex95/vue-core 1.1.43 → 3.0.0

package/dist/index.mjs

@@ -1,24 +1,23 @@
-import axios from 'axios';
+import axios, { AxiosError } from 'axios';
 import { jwtDecode } from 'jwt-decode';
-import { useRouter } from 'vue-router';
 import { v4 } from 'uuid';
 import { useTimeoutFn, useBreakpoints, breakpointsTailwind, useWindowSize } from '@vueuse/core';
-import { useQuery } from '@tanstack/vue-query';
-import { ref, watch, onServerPrefetch, onMounted, computed } from 'vue';
+import { ref, watch, computed } from 'vue';
+import { $fetch } from 'ofetch';
 
 let tokensConfig = Object.freeze({
     ACCESS_TOKEN: "access_token",
     REFRESH_TOKEN: "refresh_token",
 });
 /**
- * Configures the global keys for access and refresh tokens.
- * Once set, they cannot be modified.
+ * Configures the global storage keys for the access and refresh tokens.
+ * This function should be called once at application startup to define the keys
+ * used for storing tokens in `localStorage` or `sessionStorage`. The configuration
+ * is frozen to prevent runtime changes.
  *
- * @param {TokenKeyConfig} config - An object containing the token keys.
- * @param {string} config.accessTokenKey - The name of the key for the access token.
- * @param {string} config.refreshTokenKey - The name of the key for the refresh token.
- *
- * @returns {void} Does not return anything, but freezes the token configuration object.
+ * @param {TokenKeyConfig} config - An object containing the token storage keys.
+ * @param {string} config.accessTokenKey - The key for the access token.
+ * @param {string} config.refreshTokenKey - The key for the refresh token.
  */
 function configTokenKeys(config) {
     tokensConfig = Object.freeze({
@@ -27,18 +26,19 @@ function configTokenKeys(config) {
     });
 }
 /**
- * Retrieves the current token configuration.
+ * Retrieves the configured storage keys for the access and refresh tokens.
  *
- * @returns {TokensConfig} The configuration of the access and refresh token keys.
+ * @returns {TokensConfig} A frozen object containing the `ACCESS_TOKEN` and `REFRESH_TOKEN` keys.
  */
 function getTokenConfig() {
     return tokensConfig;
 }
 
 /**
- * Converts an ArrayBuffer or Uint8Array to a hexadecimal string.
- * @param buffer The ArrayBuffer or Uint8Array to convert.
- * @returns The hexadecimal string.
+ * Converts an `ArrayBuffer` or `Uint8Array` into a hexadecimal string representation.
+ *
+ * @param {ArrayBuffer | Uint8Array} buffer - The buffer to convert.
+ * @returns {string} The resulting hexadecimal string.
  */
 function ab2hex(buffer) {
     return Array.from(new Uint8Array(buffer))
@@ -46,11 +46,12 @@ function ab2hex(buffer) {
         .join("");
 }
 /**
- * Converts a hexadecimal string to a Uint8Array.
- * @param hex The hexadecimal string to convert.
- * @returns The Uint8Array.
+ * Converts a hexadecimal string into a `Uint8Array`.
+ *
+ * @param {string} hex - The hexadecimal string to convert.
+ * @returns {Uint8Array} The resulting `Uint8Array`.
  * @throws {TypeError} If the input is not a string.
- * @throws {Error} If the hexadecimal string format is invalid or has an odd length.
+ * @throws {Error} If the hexadecimal string has an invalid format or an odd length.
  */
 function hex2ab(hex) {
     if (typeof hex !== "string") {
@@ -69,10 +70,12 @@ function hex2ab(hex) {
     return array;
 }
 /**
- * Derives an encryption key from a secret key.
- * @param secretKey The secret key in plain text.
- * @returns A promise that resolves with the derived CryptoKey.
- * @throws {Error} If the secretKey is null or empty.
+ * Derives a `CryptoKey` for AES-CBC encryption from a plain-text secret key.
+ * It uses SHA-256 to hash the secret key, ensuring a fixed-length key suitable for the Web Crypto API.
+ *
+ * @param {string} secretKey - The plain-text secret key.
+ * @returns {Promise<CryptoKey>} A promise that resolves with the derived `CryptoKey`.
+ * @throws {Error} If the `secretKey` is null or empty.
  */
 async function importKey(secretKey) {
     if (!secretKey) {
@@ -83,11 +86,13 @@ async function importKey(secretKey) {
     return crypto.subtle.importKey("raw", digest, { name: "AES-CBC", length: 256 }, false, ["encrypt", "decrypt"]);
 }
 /**
- * Encrypts a value with the provided secret key.
- * @param value The value to encrypt.
- * @param secretKey The secret key for encryption.
- * @returns A promise that resolves with the IV (hex) + ciphertext (hex) string.
- * @throws {Error} If the secretKey is null or empty (via importKey).
+ * Encrypts a plain-text value using AES-CBC with a given secret key.
+ * A random 16-byte initialization vector (IV) is generated for each encryption.
+ *
+ * @param {string} value - The plain-text string to encrypt.
+ * @param {string} secretKey - The secret key to use for encryption.
+ * @returns {Promise<string>} A promise that resolves with a concatenated hexadecimal string of the IV and the ciphertext.
+ * @throws {Error} If the `secretKey` is null or empty.
  */
 async function encrypt(value, secretKey) {
     const key = await importKey(secretKey);
@@ -97,14 +102,12 @@ async function encrypt(value, secretKey) {
     return ab2hex(iv) + ab2hex(new Uint8Array(ciphertext));
 }
 /**
- * Decrypts an encrypted value.
- * @param encryptedValue The encrypted string (IV_hex + ciphertext_hex).
- * @param secretKey The secret key for decryption.
- * @returns A promise that resolves with the decrypted value.
- * @throws {Error} If encryptedValue is null or empty, too short,
- * or if the IV/ciphertext have incorrect lengths after conversion.
- * @throws {Error} If the secretKey is null or empty (via importKey).
- * @throws {TypeError} If hex2ab receives an invalid input type.
+ * Decrypts a hexadecimal string (IV + ciphertext) using AES-CBC with a given secret key.
+ *
+ * @param {string} encryptedValue - The concatenated hexadecimal string of the IV and ciphertext.
+ * @param {string} secretKey - The secret key to use for decryption.
+ * @returns {Promise<string>} A promise that resolves with the decrypted plain-text string.
+ * @throws {Error} If the encrypted value is null, empty, or too short, or if the `secretKey` is invalid.
  */
 async function decrypt(encryptedValue, secretKey) {
     if (!encryptedValue) {
@@ -130,55 +133,172 @@ async function decrypt(encryptedValue, secretKey) {
     return new TextDecoder().decode(decryptedBuffer);
 }
 
-/**
- * Encrypts and stores an item in local or session storage.
- * Assumes the `window` environment is available.
- * @param key The key under which to store the value.
- * @param value The value to encrypt and store.
- * @param secretKey The secret key for encryption.
- * @param location Determines where the item is stored: 'local' for localStorage, 'session' for sessionStorage.
- * @returns A promise that resolves when the item is stored. Throws an error if it fails.
- */
-async function storeEncryptedItem(key, value, secretKey, location) {
-    if (typeof window === "undefined") {
-        throw new Error("Cannot access storage: window is not defined.");
+const isServer = typeof window === 'undefined';
+const isClient = typeof window !== 'undefined';
+function getStorage() {
+    if (isServer) {
+        return null;
+    }
+    return window.localStorage;
+}
+function getSessionStorage() {
+    if (isServer) {
+        return null;
     }
-    const storage = location === "local" ? window.localStorage : window.sessionStorage;
+    return window.sessionStorage;
+}
+function getCookieStorage() {
+    return {
+        getItem: (key) => {
+            if (isServer)
+                return null;
+            const cookies = document.cookie.split(';');
+            for (const cookie of cookies) {
+                const [name, value] = cookie.trim().split('=');
+                if (name === key) {
+                    return decodeURIComponent(value);
+                }
+            }
+            return null;
+        },
+        setItem: (key, value, options) => {
+            if (isServer)
+                return;
+            let cookie = `${key}=${encodeURIComponent(value)}`;
+            if (options?.expires) {
+                const date = new Date();
+                date.setTime(date.getTime() + options.expires * 24 * 60 * 60 * 1000);
+                cookie += `; expires=${date.toUTCString()}`;
+            }
+            cookie += `; path=${options?.path || '/'}`;
+            if (options?.domain) {
+                cookie += `; domain=${options.domain}`;
+            }
+            if (options?.secure !== false) {
+                const isSecure = options?.secure ?? (typeof window !== 'undefined' && window.location.protocol === 'https:');
+                if (isSecure) {
+                    cookie += '; Secure';
+                }
+            }
+            if (options?.sameSite) {
+                cookie += `; SameSite=${options.sameSite}`;
+            }
+            else {
+                cookie += '; SameSite=Lax';
+            }
+            if (options?.httpOnly) {
+                console.warn('HttpOnly cookies cannot be set from JavaScript. Use server-side code to set HttpOnly cookies.');
+            }
+            document.cookie = cookie;
+        },
+        removeItem: (key, options) => {
+            if (isServer)
+                return;
+            const path = options?.path || '/';
+            const domain = options?.domain ? `; domain=${options.domain}` : '';
+            document.cookie = `${key}=; expires=Thu, 01 Jan 1970 00:00:00 UTC; path=${path}${domain}`;
+        },
+    };
+}
+function getPreferredStorage() {
+    if (isServer) {
+        return getCookieStorage();
+    }
+    const storage = getStorage();
+    if (storage) {
+        return storage;
+    }
+    return getCookieStorage();
+}
+
+/**
+ * Encrypts and stores a key-value pair in either `localStorage`, `sessionStorage`, or cookies.
+ * Cookies are automatically used in SSR environments and can be explicitly requested.
+ * Cookies include security options: Secure (HTTPS only), SameSite (CSRF protection), and encryption.
+ *
+ * @param {string} key - The key for the storage item.
+ * @param {string} value - The string value to encrypt and store.
+ * @param {string} secretKey - The secret key to use for encryption.
+ * @param {LocationPreference} location - The storage location: 'local' for `localStorage`, 'session' for `sessionStorage`, 'cookie' for cookies, or 'any' for retrieval.
+ * @param {CookieOptions} [cookieOptions] - Optional cookie-specific options (only used when location is 'cookie').
+ * @returns {Promise<void>} A promise that resolves when the item has been stored.
+ */
+async function storeEncryptedItem(key, value, secretKey, location, cookieOptions) {
     const encryptedValue = await encrypt(value, secretKey);
-    storage.setItem(key, encryptedValue);
+    if (location === "cookie" || isServer) {
+        const cookieStorage = getCookieStorage();
+        const defaultCookieOptions = {
+            expires: location === 'local' || isServer ? 365 : undefined,
+            path: '/',
+            secure: undefined,
+            sameSite: 'Lax',
+            ...cookieOptions,
+        };
+        cookieStorage.setItem(key, encryptedValue, defaultCookieOptions);
+        return;
+    }
+    const storage = location === "local" ? getStorage() : getSessionStorage();
+    if (storage) {
+        storage.setItem(key, encryptedValue);
+    }
 }
 /**
- * Retrieves and decrypts a value from local or session storage.
- * Assumes the `window` environment is available.
- * @param key The key of the item to retrieve.
- * @param secretKey The secret key for decryption.
- * @param location Specifies where to search for the item: 'local' for localStorage, 'session' for sessionStorage, or 'any' to check both (session first).
- * @returns A promise that resolves with the decrypted value or null if not found or decryption fails.
+ * Retrieves and decrypts an item from `localStorage`, `sessionStorage`, or cookies.
+ * When location is 'any', checks in order: sessionStorage, localStorage, cookies.
+ * Cookies are automatically checked in SSR environments.
+ *
+ * @param {string} key - The key of the item to retrieve.
+ * @param {string} secretKey - The secret key to use for decryption.
+ * @param {LocationPreference} location - The storage location to search: 'local', 'session', 'cookie', or 'any' (checks session, local, cookie in that order).
+ * @returns {Promise<string | null>} A promise that resolves with the decrypted value, or `null` if the item is not found or decryption fails.
  */
 async function getDecryptedItem(key, secretKey, location) {
-    if (typeof window === "undefined") {
-        return null;
-    }
     let encryptedData = null;
-    if (location === "session" || location === "any") {
-        encryptedData = window.sessionStorage.getItem(key);
-    }
-    if (!encryptedData && (location === "local" || location === "any")) {
-        encryptedData = window.localStorage.getItem(key);
-    }
-    if (!encryptedData) {
-        return null;
+    if (location === "cookie" || isServer) {
+        const cookieStorage = getCookieStorage();
+        encryptedData = cookieStorage.getItem(key);
+        if (encryptedData) {
+            try {
+                return await decrypt(encryptedData, secretKey);
+            }
+            catch (error) {
+                return null;
+            }
+        }
+        if (location === "cookie") {
+            return null;
+        }
     }
-    try {
-        return await decrypt(encryptedData, secretKey);
+    if (location === "session" || location === "any") {
+        const sessionStorage = getSessionStorage();
+        encryptedData = sessionStorage?.getItem(key) || null;
+        if (encryptedData) {
+            try {
+                return await decrypt(encryptedData, secretKey);
+            }
+            catch (error) {
+                return null;
+            }
+        }
     }
-    catch (error) {
-        return null;
+    if (location === "local" || location === "any") {
+        const storage = getStorage();
+        encryptedData = storage?.getItem(key) || null;
+        if (encryptedData) {
+            try {
+                return await decrypt(encryptedData, secretKey);
+            }
+            catch (error) {
+                return null;
+            }
+        }
     }
+    return null;
 }
 
 /**
- * Enum defining available screen sizes.
+ * An enum that defines a set of standardized screen size labels, ranging from extra-small (XS) to extra-extra-large (XXL).
+ * These labels are used to create a consistent vocabulary for responsive design across the application.
  */
 var ScreenSize;
 (function (ScreenSize) {
@@ -190,8 +310,8 @@ var ScreenSize;
     ScreenSize["XXL"] = "XXL";
 })(ScreenSize || (ScreenSize = {}));
 /**
- * Enum defining breakpoints for design based on screen width.
- * Values are in pixels.
+ * An enum that establishes specific pixel values for screen width breakpoints, corresponding to the labels in `ScreenSize`.
+ * These values are used to implement responsive design changes at standard device widths.
  */
 var ScreenBreakpoint;
 (function (ScreenBreakpoint) {
@@ -203,7 +323,9 @@ var ScreenBreakpoint;
     ScreenBreakpoint[ScreenBreakpoint["XXL"] = 1600] = "XXL";
 })(ScreenBreakpoint || (ScreenBreakpoint = {}));
 /**
- * Map that associates each screen size defined in `ScreenSize` with its corresponding pixel value from `ScreenBreakpoint`.
+ * A map that associates the symbolic screen size names from the `ScreenSize` enum with their
+ * corresponding pixel values from the `ScreenBreakpoint` enum. This provides an easy way to
+ * look up the pixel width for a given screen size label.
  * @type {Map<ScreenSize, number>}
  */
 const screenMap = new Map();
@@ -215,7 +337,9 @@ screenMap.set(ScreenSize.XL, ScreenBreakpoint.XL);
 screenMap.set(ScreenSize.XXL, ScreenBreakpoint.XXL);
 
 /**
- * Enum representing all HTTP exception codes.
+ * An enum that defines a comprehensive set of HTTP status codes, organized by category
+ * (Informational, Success, Redirection, Client Errors, Server Errors). It also includes
+ * custom error codes for application-specific scenarios like network errors.
  * @readonly
  */
 var ExceptionEnum;
@@ -294,7 +418,7 @@ var ExceptionEnum;
 })(ExceptionEnum || (ExceptionEnum = {}));
 
 /**
- * Enum representing various MIME types for different file categories.
+ * An enum that defines MIME types for common image formats.
  * @readonly
  */
 var ImageTypes;
@@ -310,14 +434,26 @@ var ImageTypes;
     ImageTypes["WEBP"] = "image/webp";
     ImageTypes["XICON"] = "image/x-icon";
 })(ImageTypes || (ImageTypes = {}));
+/**
+ * An enum for generic audio MIME types.
+ * @readonly
+ */
 var AudioTypes;
 (function (AudioTypes) {
     AudioTypes["Audios"] = "audio/*";
 })(AudioTypes || (AudioTypes = {}));
+/**
+ * An enum for generic video MIME types.
+ * @readonly
+ */
 var VideoTypes;
 (function (VideoTypes) {
     VideoTypes["Videos"] = "video/*";
 })(VideoTypes || (VideoTypes = {}));
+/**
+ * An enum that defines MIME types for various text-based formats, including plain text, markup, and data serialization formats.
+ * @readonly
+ */
 var TextTypes;
 (function (TextTypes) {
     TextTypes["PlainText"] = "text/plain";
@@ -328,6 +464,10 @@ var TextTypes;
     TextTypes["JSON"] = "application/json";
     TextTypes["XML"] = "application/xml";
 })(TextTypes || (TextTypes = {}));
+/**
+ * An enum that defines MIME types for common document formats, such as PDFs and Microsoft Office files.
+ * @readonly
+ */
 var DocumentTypes;
 (function (DocumentTypes) {
     DocumentTypes["PDF"] = "application/pdf";
@@ -338,6 +478,10 @@ var DocumentTypes;
     DocumentTypes["PowerPoint"] = "application/vnd.ms-powerpoint";
     DocumentTypes["PowerPointOpenXML"] = "application/vnd.openxmlformats-officedocument.presentationml.presentation";
 })(DocumentTypes || (DocumentTypes = {}));
+/**
+ * An enum that defines MIME types for popular archive and compression formats.
+ * @readonly
+ */
 var ArchiveTypes;
 (function (ArchiveTypes) {
     ArchiveTypes["ZIP"] = "application/zip";
@@ -345,6 +489,10 @@ var ArchiveTypes;
     ArchiveTypes["TAR"] = "application/x-tar";
     ArchiveTypes["RAR"] = "application/x-rar-compressed";
 })(ArchiveTypes || (ArchiveTypes = {}));
+/**
+ * An enum that defines MIME types for different font file formats.
+ * @readonly
+ */
 var FontTypes;
 (function (FontTypes) {
     FontTypes["TrueType"] = "font/ttf";
@@ -352,12 +500,20 @@ var FontTypes;
     FontTypes["WebOpenFont"] = "font/woff";
     FontTypes["WebOpenFont2"] = "font/woff2";
 })(FontTypes || (FontTypes = {}));
+/**
+ * An enum that defines MIME types for application-specific formats, including executables and packages.
+ * @readonly
+ */
 var AppTypes;
 (function (AppTypes) {
     AppTypes["Executable"] = "application/octet-stream";
     AppTypes["AndroidAPK"] = "application/vnd.android.package-archive";
     AppTypes["Java"] = "application/java-archive";
 })(AppTypes || (AppTypes = {}));
+/**
+ * An enum for miscellaneous MIME types that do not fit into the other categories.
+ * @readonly
+ */
 var OtherTypes;
 (function (OtherTypes) {
     OtherTypes["JSONLD"] = "application/ld+json";
@@ -423,10 +579,8 @@ var ContentTypeEnum;
 })(ContentTypeEnum || (ContentTypeEnum = {}));
 
 /**
- * Enum for key codes used in keyboard events.
- * This object holds various key codes commonly used for handling keyboard events.
- * The keys defined here correspond to specific key codes that can be used to detect
- * user input in web applications.
+ * An enum that provides a comprehensive mapping of common keyboard keys to their corresponding key codes.
+ * This is useful for handling keyboard events in a readable and standardized way, avoiding the use of magic numbers.
  * @readonly
  * @enum {number}
  */
@@ -487,8 +641,8 @@ var KeyCodeEnum;
 })(KeyCodeEnum || (KeyCodeEnum = {}));
 
 /**
- * Enum for different storage keys used in the application.
- * This enum contains the keys for storing authentication token, locale information, user info, roles, and more.
+ * An enum that defines a standardized set of keys for accessing `localStorage` and `sessionStorage`.
+ * This helps to avoid magic strings and ensures consistency when managing data persistence in the browser.
  * @readonly
  * @enum {string}
  */
@@ -536,9 +690,9 @@ var StorageKeyEnum;
     StorageKeyEnum["APP_SESSION_CACHE_KEY"] = "COMMON__SESSION__KEY";
 })(StorageKeyEnum || (StorageKeyEnum = {}));
 /**
- * Enum defining types of storage.
+ * A frozen object that serves as an enum for storage types, distinguishing between `sessionStorage` and `localStorage`.
+ * Using this object provides a type-safe way to specify the desired storage mechanism.
  * @readonly
- * @enum {number}
  */
 const StorageTypeEnum = {
     /**
@@ -554,7 +708,9 @@ const StorageTypeEnum = {
 };
 
 /**
- * Enum representing different types of errors.
+ * An enum that defines a vocabulary of error types, covering a wide range of potential issues
+ * from validation and network problems to runtime and syntax errors. This provides a standardized
+ * way to classify errors throughout the application.
  * @readonly
  */
 var ErrorEnum;
@@ -575,28 +731,31 @@ var ErrorEnum;
     ErrorEnum["URI"] = "uri";
 })(ErrorEnum || (ErrorEnum = {}));
 /**
- * Enum representing different error messages.
+ * An enum that provides standardized, user-friendly messages for different error types.
+ * These messages are intended to be displayed to the user or used in logs.
  * @readonly
  */
 var ErrorMessages;
 (function (ErrorMessages) {
-    ErrorMessages["WARNING"] = "Algo no est\u00E1 del todo bien. Verifica y vuelve a intentar.";
-    ErrorMessages["ERROR"] = "Ocurri\u00F3 un error inesperado.";
-    ErrorMessages["CRITICAL"] = "Error cr\u00EDtico. Contacta al soporte t\u00E9cnico.";
-    ErrorMessages["VALIDATION"] = "Hay errores en el formulario. Revisa los campos.";
-    ErrorMessages["COMPONENT"] = "Error en la carga del componente. Intenta recargar.";
-    ErrorMessages["NETWORK"] = "Problema de conexi\u00F3n. Verifica tu internet.";
-    ErrorMessages["AUTHENTICATION"] = "No tienes permisos para realizar esta acci\u00F3n.";
-    ErrorMessages["RUNTIME"] = "Error de ejecuci\u00F3n. Intenta nuevamente.";
-    ErrorMessages["TYPE"] = "Tipo de error no identificado.";
-    ErrorMessages["REFERENCE"] = "Referencia no v\u00E1lida.";
-    ErrorMessages["SYNTAX"] = "Error de sintaxis en el c\u00F3digo.";
-    ErrorMessages["RANGE"] = "Error en el rango de valores.";
-    ErrorMessages["EVAL"] = "Error en la evaluaci\u00F3n.";
-    ErrorMessages["URI"] = "URI no v\u00E1lida.";
+    ErrorMessages["WARNING"] = "Something is not quite right. Please check and try again.";
+    ErrorMessages["ERROR"] = "An unexpected error occurred.";
+    ErrorMessages["CRITICAL"] = "Critical error. Please contact technical support.";
+    ErrorMessages["VALIDATION"] = "There are errors in the form. Please review the fields.";
+    ErrorMessages["COMPONENT"] = "Error loading the component. Try reloading.";
+    ErrorMessages["NETWORK"] = "Connection problem. Please check your internet.";
+    ErrorMessages["AUTHENTICATION"] = "You do not have permission to perform this action.";
+    ErrorMessages["RUNTIME"] = "Execution error. Please try again.";
+    ErrorMessages["TYPE"] = "Unidentified error type.";
+    ErrorMessages["REFERENCE"] = "Invalid reference.";
+    ErrorMessages["SYNTAX"] = "Syntax error in the code.";
+    ErrorMessages["RANGE"] = "Error in the range of values.";
+    ErrorMessages["EVAL"] = "Error in evaluation.";
+    ErrorMessages["URI"] = "Invalid URI.";
 })(ErrorMessages || (ErrorMessages = {}));
 /**
- * Enum representing different error styles.
+ * An enum that defines CSS styles for console log messages, corresponding to each error type in `ErrorEnum`.
+ * This allows for visually distinct, styled logging in the browser's console, making it easier to
+ * identify the severity and type of logged errors during development.
  * @readonly
  */
 var ErrorStyles;
@@ -617,7 +776,8 @@ var ErrorStyles;
     ErrorStyles["URI"] = "color: darkcyan; font-weight: bold;";
 })(ErrorStyles || (ErrorStyles = {}));
 /**
- * A record mapping ErrorEnum to their corresponding error messages.
+ * A frozen record that maps each `ErrorEnum` member to its corresponding user-friendly message from `ErrorMessages`.
+ * This provides a convenient, type-safe way to look up error messages.
  */
 const ERROR_MESSAGES = {
     [ErrorEnum.WARNING]: ErrorMessages.WARNING,
@@ -636,7 +796,8 @@ const ERROR_MESSAGES = {
     [ErrorEnum.URI]: ErrorMessages.URI,
 };
 /**
- * A record mapping ErrorEnum to their corresponding error styles.
+ * A frozen record that maps each `ErrorEnum` member to its corresponding CSS style string from `ErrorStyles`.
+ * This enables easy retrieval of the correct style for console logging based on the error type.
  */
 const ERROR_STYLES = {
     [ErrorEnum.WARNING]: ErrorStyles.WARNING,
@@ -655,42 +816,202 @@ const ERROR_STYLES = {
     [ErrorEnum.URI]: ErrorStyles.URI,
 };
 
+class BaseError extends Error {
+    timestamp;
+    context;
+    constructor(message, context) {
+        super(message);
+        this.name = this.constructor.name;
+        this.timestamp = new Date();
+        this.context = context;
+        Error.captureStackTrace?.(this, this.constructor);
+    }
+    toJSON() {
+        return {
+            name: this.name,
+            message: this.message,
+            code: this.code,
+            statusCode: this.statusCode,
+            timestamp: this.timestamp.toISOString(),
+            context: this.context,
+            stack: this.stack,
+        };
+    }
+}
+
+class NetworkError extends BaseError {
+    code = 'NETWORK_ERROR';
+    statusCode;
+    originalError;
+    constructor(message = 'Network request failed', statusCode, originalError, context) {
+        super(message, context);
+        this.statusCode = statusCode;
+        this.originalError = originalError;
+    }
+    static fromAxiosError(error) {
+        const statusCode = error.response?.status;
+        const message = error.response?.data?.message || error.message || 'Network request failed';
+        return new NetworkError(message, statusCode, error, {
+            url: error.config?.url,
+            method: error.config?.method,
+            responseData: error.response?.data,
+        });
+    }
+    static fromFetchError(error) {
+        return new NetworkError(error.message || 'Network request failed', undefined, error, {
+            cause: error.cause,
+        });
+    }
+}
+
+class AuthError extends BaseError {
+    code = 'AUTH_ERROR';
+    statusCode = 401;
+    constructor(message = 'Authentication failed', context) {
+        super(message, context);
+    }
+    static unauthorized(message) {
+        return new AuthError(message || 'Unauthorized access');
+    }
+    static tokenExpired() {
+        return new AuthError('Token has expired');
+    }
+    static tokenInvalid() {
+        return new AuthError('Invalid token');
+    }
+    static tokenMissing() {
+        return new AuthError('Authentication token is missing');
+    }
+}
+
+class ValidationError extends BaseError {
+    code = 'VALIDATION_ERROR';
+    statusCode = 422;
+    issues;
+    constructor(message = 'Validation failed', issues = [], context) {
+        super(message, context);
+        this.issues = issues;
+    }
+    static fromIssues(issues) {
+        return new ValidationError(`Validation failed: ${issues.length} issue(s)`, issues);
+    }
+    static fromField(field, message, value) {
+        return new ValidationError(`Validation failed for field "${field}"`, [{ field, message, value }]);
+    }
+}
+
+class ServerError extends BaseError {
+    code = 'SERVER_ERROR';
+    statusCode;
+    constructor(message = 'Server error occurred', statusCode = 500, context) {
+        super(message, context);
+        this.statusCode = statusCode;
+    }
+    static internal(message) {
+        return new ServerError(message || 'Internal server error', 500);
+    }
+    static badGateway(message) {
+        return new ServerError(message || 'Bad gateway', 502);
+    }
+    static serviceUnavailable(message) {
+        return new ServerError(message || 'Service unavailable', 503);
+    }
+    static gatewayTimeout(message) {
+        return new ServerError(message || 'Gateway timeout', 504);
+    }
+}
+
 /**
- * Maneja y registra errores en la consola, además de permitir redirecciones configurables.
- * @param error - Error capturado (string o Error)
- * @param redirect - `true` si se quiere redirigir a una página de error
- * @param route - Ruta personalizada para la página de error (por defecto: `/error`)
- * @param passMethod - Método para pasar el error a la ruta (`query`, `localStorage`, `sessionStorage`)
- * @returns Mensaje user-friendly del error
- */
-function handleError(error, redirect = false, route = '/error', passMethod = 'query') {
+ * Handles and logs errors to the console. Supports both standard Error objects and custom error classes
+ * (BaseError, NetworkError, etc.). It infers the error type, logs a styled message with detailed information,
+ * and returns structured error information for further handling.
+ *
+ * @param {unknown} error - The captured error, which can be a string, Error object, or custom error class.
+ * @returns {ErrorInfo | undefined} An object containing the error message, type, and additional error data,
+ *   or `undefined` if the error is not an Error instance.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await someOperation();
+ * } catch (error) {
+ *   const errorInfo = handleError(error);
+ *   if (errorInfo) {
+ *     // Use errorInfo.message, errorInfo.type, errorInfo.errorData
+ *     // Handle redirect or other actions as needed
+ *   }
+ * }
+ * ```
+ */
+function handleError(error) {
     if (!(error instanceof Error)) {
         console.error("Unrecognized error:", error);
-        return;
+        return undefined;
     }
-    const router = useRouter();
-    const type = inferErrorType(error);
-    const message = ERROR_MESSAGES[type] || 'Error desconocido.';
-    console.log(`%c[${type.toUpperCase()}] ${message}`, ERROR_STYLES[type]);
-    if (redirect) {
-        if (passMethod === 'query') {
-            router.push({ path: route, query: { errorMessage: encodeURIComponent(message) } });
+    let type;
+    let message;
+    let errorData = undefined;
+    if (error instanceof BaseError) {
+        type = inferErrorTypeFromBaseError(error);
+        message = error.message || ERROR_MESSAGES[type] || 'Error desconocido.';
+        errorData = {
+            code: error.code,
+            statusCode: error.statusCode,
+            context: error.context,
+            timestamp: error.timestamp,
+        };
+        if (error instanceof ValidationError && error.issues.length > 0) {
+            errorData.issues = error.issues;
         }
-        else if (passMethod === 'localStorage') {
-            localStorage.setItem('errorMessage', message);
-            router.push(route);
+    }
+    else {
+        type = inferErrorType(error);
+        message = ERROR_MESSAGES[type] || error.message || 'Error desconocido.';
+    }
+    const logMessage = `%c[${type.toUpperCase()}] ${message}`;
+    const logStyle = ERROR_STYLES[type] || ERROR_STYLES.error;
+    console.group(logMessage, logStyle);
+    console.error('Error details:', error);
+    if (errorData) {
+        console.error('Error data:', errorData);
+    }
+    if (error.stack) {
+        console.error('Stack trace:', error.stack);
+    }
+    console.groupEnd();
+    return {
+        message,
+        type,
+        ...(errorData && { errorData }),
+    };
+}
+function inferErrorTypeFromBaseError(error) {
+    if (error instanceof NetworkError) {
+        if (error.statusCode === 401 || error.statusCode === 403) {
+            return 'authentication';
         }
-        else if (passMethod === 'sessionStorage') {
-            sessionStorage.setItem('errorMessage', message);
-            router.push(route);
+        return 'network';
+    }
+    if (error instanceof AuthError) {
+        return 'authentication';
+    }
+    if (error instanceof ValidationError) {
+        return 'validation';
+    }
+    if (error instanceof ServerError) {
+        if (error.statusCode >= 500) {
+            return 'critical';
         }
+        return 'error';
     }
-    return message;
+    return 'error';
 }
 /**
- * Infiera el tipo de error basado en su mensaje o nombre.
- * @param error - El error que se desea analizar.
- * @returns El tipo de error determinado.
+ * Infers the `ErrorType` of an error by analyzing its name and message content.
+ * This helps in categorizing the error for standardized handling and logging.
+ *
+ * @param {string | Error} error - The error to analyze.
+ * @returns {ErrorType} The inferred error type.
  */
 function inferErrorType(error) {
     const msg = typeof error === 'string' ? error : error.message;
@@ -715,15 +1036,14 @@ let endpointsConfig = {
     LOGOUT: "/logout",
 };
 /**
- * Configures authentication endpoint URLs globally.
- * This function freezes the object to prevent further modifications.
- *
- * @param {EndpointConfig} config - An object containing the authentication endpoint URLs.
- * @param {string} config.loginEndpoint - URL of the login endpoint.
- * @param {string} config.refreshEndpoint - URL of the refresh token endpoint.
- * @param {string} config.logoutEndpoint - URL of the logout endpoint.
+ * Configures the global authentication endpoint URLs for the application.
+ * This function should be called once at startup to define the API endpoints for login,
+ * token refresh, and logout. The configuration is then frozen to prevent changes.
  *
- * @returns {void} Does not return anything but freezes the endpoint configuration object.
+ * @param {EndpointConfig} config - An object containing the URLs for the authentication endpoints.
+ * @param {string} config.loginEndpoint - The URL for the login endpoint.
+ * @param {string} config.refreshEndpoint - The URL for the token refresh endpoint.
+ * @param {string} config.logoutEndpoint - The URL for the logout endpoint.
  */
 function configEndpoints(config) {
     endpointsConfig = Object.freeze({
@@ -733,12 +1053,9 @@ function configEndpoints(config) {
     });
 }
 /**
- * Retrieves the configured authentication endpoint URLs.
+ * Retrieves the globally configured authentication endpoint URLs.
  *
- * @returns {EndpointsConfig} An object containing the configured authentication endpoints.
- * @property {string} LOGIN - URL of the login endpoint.
- * @property {string} REFRESH - URL of the refresh token endpoint.
- * @property {string} LOGOUT - URL of the logout endpoint.
+ * @returns {EndpointsConfig} A frozen object containing the configured `LOGIN`, `REFRESH`, and `LOGOUT` endpoints.
  */
 function getEndpointsConfig() {
     return endpointsConfig;
@@ -746,13 +1063,11 @@ function getEndpointsConfig() {
 
 let appKey = null;
 /**
- * Sets the main application encryption key.
- * This key is expected to be used for encryption purposes within the application.
+ * Sets the main application key, which is intended for use in encryption and signing operations.
+ * This function should be called once at application startup to configure the key.
  *
- * @param {AppKeyConfig} config - An object containing the application encryption key.
- * @param {string} config.key - The new application encryption key.
- *
- * @returns {void} Does not return anything, but updates the application key.
+ * @param {AppKeyConfig} config - An object containing the application key.
+ * @param {string} config.appKey - The application key.
  * @throws {Error} If the provided key is null, undefined, or an empty string.
  */
 function configAppKey(config) {
@@ -762,11 +1077,10 @@ function configAppKey(config) {
     appKey = config.appKey;
 }
 /**
- * Retrieves the current application encryption key.
- * Throws an error if the application key has not been configured.
+ * Retrieves the configured application key.
  *
- * @returns {string} The configured application encryption key.
- * @throws {Error} If the application encryption key has not been set.
+ * @returns {string} The configured application key.
+ * @throws {Error} If the application key has not been set by calling `configAppKey` first.
  */
 function getAppKey() {
     if (appKey === null) {
@@ -830,15 +1144,16 @@ async function loadSessionConfig() {
     }
 }
 /**
- * Configures the session identifier and/or data persistence preference
- * for the active browser session.
- *
- * This function is asynchronous because it will always attempt to load the current configuration
- * before applying changes and then saving them.
+ * Configures the session ID and persistence preference for the application.
+ * This function allows setting a custom session ID and specifying whether session-related
+ * data should be stored in `localStorage` or `sessionStorage`. The configuration is
+ * then encrypted and saved to the chosen storage.
  *
- * @param {SessionConfigObject} config - An object containing the unique session identifier and/or
- * the persistence preference.
- * @returns {Promise<void>} A promise that resolves when the session has been configured and saved.
+ * @param {SessionConfigObject} config - An object containing the session configuration.
+ * @param {string} [config.sessionId] - A unique identifier for the session. If not provided, the existing one is maintained.
+ * @param {LocationPreference} [config.persistencePreference] - The storage location ('local' or 'session').
+ *   If not provided, the existing preference is maintained.
+ * @returns {Promise<void>} A promise that resolves once the session has been configured and saved.
  */
 async function configSession(config) {
     if (config.sessionId) {
@@ -851,30 +1166,27 @@ async function configSession(config) {
     await saveSessionConfig();
 }
 /**
- * Retrieves the current session identifier.
- * Always attempts to load the configuration from storage. If it fails, it uses the internal state.
+ * Retrieves the current session identifier, loading it from storage if available.
  *
- * @returns {Promise<string>} A promise that resolves with the unique session identifier.
+ * @returns {Promise<string>} A promise that resolves with the session ID.
  */
 async function getSessionId() {
     await loadSessionConfig();
     return _sessionConfig.SESSION_ID;
 }
 /**
- * Retrieves the current data persistence preference.
- * Always attempts to load the configuration from storage. If it fails, it uses the internal state.
+ * Retrieves the current data persistence preference, loading it from storage if available.
  *
- * @returns {Promise<SessionPreference>} A promise that resolves with the configured persistence preference ('local' or 'session').
+ * @returns {Promise<LocationPreference>} A promise that resolves with the persistence preference ('local' or 'session').
  */
 async function getSessionPersistence() {
     await loadSessionConfig();
     return _sessionConfig.PERSISTENCE;
 }
 /**
- * Retrieves the complete session configuration.
- * Always attempts to load the configuration from storage. If it fails, it uses the internal state.
+ * Retrieves the complete session configuration object, loading it from storage if available.
  *
- * @returns {Promise<SessionConfig>} A promise that resolves with the session configuration object.
+ * @returns {Promise<SessionConfig>} A promise that resolves with the full session configuration.
  */
 async function getSessionConfig() {
     await loadSessionConfig();
@@ -890,14 +1202,12 @@ let refreshTokenPathsConfig = {
     refreshTokenPath: "data.refresh_token",
 };
 /**
- * Configures the paths for access and refresh tokens in the authentication response.
- * This function freezes the object to prevent further modifications.
+ * Configures the dot-notation paths for extracting access and refresh tokens from the initial login response.
+ * The configuration is frozen to prevent runtime changes.
  *
- * @param {TokenPathsConfig} config - An object containing the paths for access and refresh tokens.
- * @param {string} [config.accessTokenPath="data.access_token"] - Path to the access token in the response.
- * @param {string} [config.refreshTokenPath="data.refresh_token"] - Path to the refresh token in the response.
- *
- * @returns {void} Does not return anything but freezes the token paths configuration object.
+ * @param {TokenPathsConfig} config - An object containing the token paths.
+ * @param {string} [config.accessTokenPath="data.access_token"] - The path to the access token.
+ * @param {string} [config.refreshTokenPath="data.refresh_token"] - The path to the refresh token.
  */
 function configTokenPaths(config) {
     tokenPathsConfig = Object.freeze({
@@ -906,14 +1216,12 @@ function configTokenPaths(config) {
     });
 }
 /**
- * Configures the paths for access and refresh tokens in the refresh response.
- * This function freezes the object to prevent further modifications.
- *
- * @param {TokenPathsConfig} config - An object containing the paths for access and refresh tokens.
- * @param {string} [config.accessTokenPath="data.access_token"] - Path to the access token in the response.
- * @param {string} [config.refreshTokenPath="data.refresh_token"] - Path to the refresh token in the response.
+ * Configures the dot-notation paths for extracting access and refresh tokens from the token refresh response.
+ * The configuration is frozen to prevent runtime changes.
  *
- * @returns {void} Does not return anything but freezes the refresh token paths configuration object.
+ * @param {TokenPathsConfig} config - An object containing the token paths for the refresh response.
+ * @param {string} [config.accessTokenPath="data.access_token"] - The path to the new access token.
+ * @param {string} [config.refreshTokenPath="data.refresh_token"] - The path to the new refresh token.
  */
 function configRefreshTokenPaths(config) {
     refreshTokenPathsConfig = Object.freeze({
@@ -922,135 +1230,139 @@ function configRefreshTokenPaths(config) {
     });
 }
 /**
- * Retrieves the configured authentication token paths.
+ * Retrieves the configured token paths for the initial login response.
  *
- * @returns {AuthTokenPaths} An object containing the configured authentication token paths.
- * @property {string} accessTokenPath - Path to the access token in the response.
- * @property {string} refreshTokenPath - Path to the refresh token in the response.
+ * @returns {AuthTokenPaths} A frozen object containing the `accessTokenPath` and `refreshTokenPath`.
  */
 function getTokenPathsConfig() {
     return tokenPathsConfig;
 }
+/**
+ * Retrieves the configured token paths for the token refresh response.
+ *
+ * @returns {AuthTokenPaths} A frozen object containing the `accessTokenPath` and `refreshTokenPath` for the refresh response.
+ */
 function getRefreshTokenPathsConfig() {
     return refreshTokenPathsConfig;
 }
 
 /**
- * Clears all stored authentication data (access and refresh tokens)
- * from either sessionStorage, localStorage, or both based on the provided location preference.
+ * Removes all stored authentication credentials (access and refresh tokens) from the specified storage locations.
  *
- * @param {LocationPreference} location - The storage preference ('local' for localStorage, 'session' for sessionStorage, 'any' for both).
- * @returns {Promise<void>} A promise that resolves when all relevant storage items are removed.
+ * @param {LocationPreference} location - The storage location to clear. Can be 'local' for `localStorage`,
+ *   'session' for `sessionStorage`, 'cookie' for cookies, or 'any' to clear all.
+ * @returns {Promise<void>} A promise that resolves when the credentials have been cleared.
  */
 const cleanCredentials = async (location) => {
     const tokensConfig = getTokenConfig();
+    if (location === "cookie" || isServer) {
+        const cookieStorage = getCookieStorage();
+        Object.keys(tokensConfig).forEach((key) => {
+            cookieStorage.removeItem(tokensConfig[key], { path: '/' });
+        });
+        if (location === "cookie") {
+            return;
+        }
+    }
     Object.keys(tokensConfig).forEach((key) => {
         const itemKey = tokensConfig[key];
         if (location === "local" || location === "any") {
-            localStorage.removeItem(itemKey);
+            const storage = getStorage();
+            storage?.removeItem(itemKey);
         }
         if (location === "session" || location === "any") {
-            sessionStorage.removeItem(itemKey);
+            const sessionStorage = getSessionStorage();
+            sessionStorage?.removeItem(itemKey);
         }
     });
 };
 /**
- * Retrieves the authentication token (access token) from storage, decrypting it
- * using the provided secret key and based on the specified session preference.
+ * Retrieves and decrypts the access token from the specified storage location.
  *
- * @param {string} secretKey - The secret key used for decryption.
- * @param {SessionPreference} preference - The storage preference ('local' for localStorage, 'session' for sessionStorage).
- * @returns {Promise<string | null>} A promise that resolves with the decrypted access token, or null if not found.
+ * @param {string} secretKey - The secret key to use for decryption.
+ * @param {LocationPreference} location - The storage location to search ('local', 'session', 'cookie', or 'any').
+ * @returns {Promise<string | null>} A promise that resolves with the decrypted access token, or `null` if it's not found.
  */
 const getAuthToken = async (secretKey, location) => {
     const tokensConfig = getTokenConfig();
     return await getDecryptedItem(tokensConfig.ACCESS_TOKEN, secretKey, location);
 };
 /**
- * Retrieves the authentication refresh token from storage, decrypting it
- * using the provided secret key and based on the specified session preference.
+ * Retrieves and decrypts the refresh token from the specified storage location.
  *
- * @param {string} secretKey - The secret key used for decryption.
- * @param {SessionPreference} preference - The storage preference ('local' for localStorage, 'session' for sessionStorage).
- * @returns {Promise<string | null>} A promise that resolves with the decrypted refresh token, or null if not found.
+ * @param {string} secretKey - The secret key to use for decryption.
+ * @param {LocationPreference} location - The storage location to search ('local', 'session', 'cookie', or 'any').
+ * @returns {Promise<string | null>} A promise that resolves with the decrypted refresh token, or `null` if it's not found.
  */
 const getAuthRefreshToken = async (secretKey, location) => {
     const tokensConfig = getTokenConfig();
     return await getDecryptedItem(tokensConfig.REFRESH_TOKEN, secretKey, location);
 };
 /**
- * Stores the authentication token (access token) in storage after encrypting it,
- * based on the specified session preference.
+ * Encrypts and stores the access token in the specified storage location.
  *
  * @param {string} token - The access token to store.
- * @param {string} secretKey - The secret key used for encryption.
- * @param {SessionPreference} preference - The storage preference ('local' for localStorage, 'session' for sessionStorage).
- * @returns {Promise<void>} A promise that resolves when the token is successfully stored.
+ * @param {string} secretKey - The secret key to use for encryption.
+ * @param {LocationPreference} location - The storage location ('local', 'session', or 'cookie').
+ * @returns {Promise<void>} A promise that resolves when the token has been stored.
  */
 const storeAuthToken = async (token, secretKey, location) => {
     const tokensConfig = getTokenConfig();
     await storeEncryptedItem(tokensConfig.ACCESS_TOKEN, token, secretKey, location);
 };
 /**
- * Stores the authentication refresh token in storage after encrypting it,
- * based on the specified session preference.
+ * Encrypts and stores the refresh token in the specified storage location.
  *
  * @param {string} token - The refresh token to store.
- * @param {string} secretKey - The secret key used for encryption.
- * @param {SessionPreference} preference - The storage preference ('local' for localStorage, 'session' for sessionStorage).
- * @returns {Promise<void>} A promise that resolves when the token is successfully stored.
+ * @param {string} secretKey - The secret key to use for encryption.
+ * @param {LocationPreference} location - The storage location ('local', 'session', or 'cookie').
+ * @returns {Promise<void>} A promise that resolves when the token has been stored.
  */
 const storeAuthRefreshToken = async (token, secretKey, location) => {
     const tokensConfig = getTokenConfig();
     await storeEncryptedItem(tokensConfig.REFRESH_TOKEN, token, secretKey, location);
 };
 /**
- * Verifies the validity and expiration of the current authentication token.
- * If the token is missing, invalid, or expired, appropriate errors are thrown and credentials are cleaned.
+ * Verifies the current user's authentication status by checking for a valid, unexpired access token.
+ * It searches for the token in all storage locations (sessionStorage, localStorage, cookies).
+ * If the token is missing, malformed, or expired, it logs the issue, clears credentials, and returns `false`.
  *
- * @returns {Promise<boolean>} True if the token is valid and unexpired.
- * @throws {Error} "TOKEN_MISSING" if no token is found, "TOKEN_EXPIRED" if the token has expired,
- * "TOKEN_INVALID" if the token format is invalid.
+ * @returns {Promise<boolean>} A promise that resolves to `true` if the user is authenticated, and `false` otherwise.
  */
 const verifyAuth = async () => {
     const sessionPersistence = 'any';
     const handleAuthError = async (message, shouldClean = true) => {
-        handleError(message, false);
+        handleError(message);
         if (shouldClean) {
             await cleanCredentials(sessionPersistence);
         }
         return false;
     };
+    const token = await getAuthToken(getAppKey(), sessionPersistence);
+    if (!token) {
+        return handleAuthError("TOKEN_MISSING: No valid token found");
+    }
     try {
-        const token = await getAuthToken(getAppKey(), sessionPersistence);
-        if (!token) {
-            return await handleAuthError("TOKEN_MISSING: No valid token found");
-        }
-        let decoded;
-        try {
-            decoded = jwtDecode(token);
-        }
-        catch (decodeError) {
-            return await handleAuthError("TOKEN_INVALID: Invalid token format");
-        }
+        const decoded = jwtDecode(token);
         const currentTime = Date.now() / 1000;
         if (typeof decoded.exp !== "number") {
-            return await handleAuthError("TOKEN_INVALID: Invalid expiration format");
+            return handleAuthError("TOKEN_INVALID: Invalid expiration format");
         }
         if (decoded.exp <= currentTime) {
-            return await handleAuthError("TOKEN_EXPIRED: Token is expired");
+            return handleAuthError("TOKEN_EXPIRED: Token is expired");
         }
         return true;
     }
     catch (error) {
-        return await handleAuthError("AUTH_ERROR: An unexpected error occurred", true);
+        return handleAuthError("TOKEN_INVALID: Invalid token format");
     }
 };
 
 /**
- * Converts a Proxy object to a plain object.
- * @param {ProxyConstructor} proxy The Proxy object to convert.
- * @returns {Object} The plain object.
+ * Converts a Proxy object into a plain JavaScript object.
+ *
+ * @param {ProxyConstructor} proxy - The Proxy object to convert.
+ * @returns {any} A new object containing the properties of the Proxy.
  */
 function proxyToPlainObject(proxy) {
     if (!proxy)
@@ -1062,10 +1374,11 @@ function proxyToPlainObject(proxy) {
     return plainObject;
 }
 /**
- * Compares two objects to check if they have the same keys.
- * @param {Object} object1 The first object to compare.
- * @param {Object} object2 The second object to compare.
- * @returns {boolean} True if the objects have the same keys, otherwise false.
+ * Performs a shallow comparison to check if two objects have the same keys.
+ *
+ * @param {Record<string, any>} object1 - The first object.
+ * @param {Record<string, any>} object2 - The second object.
+ * @returns {boolean} `true` if both objects have the exact same set of keys, otherwise `false`.
  */
 function compareObject(object1, object2) {
     return Object.keys(object1).every(function (element) {
@@ -1073,10 +1386,11 @@ function compareObject(object1, object2) {
     });
 }
 /**
- * Deeply compares two objects to check if they are equal.
- * @param {Object} object1 The first object to compare.
- * @param {Object} object2 The second object to compare.
- * @returns {boolean} True if the objects are deeply equal, otherwise false.
+ * Performs a deep comparison between two objects to determine if they are structurally and value-wise equal.
+ *
+ * @param {Record<string, any>} object1 - The first object.
+ * @param {Record<string, any>} object2 - The second object.
+ * @returns {boolean} `true` if the objects are deeply equal, otherwise `false`.
  */
 function deepEqual(object1, object2) {
     if (object1 === object2)
@@ -1097,9 +1411,12 @@ function deepEqual(object1, object2) {
     return true;
 }
 /**
- * Deeply clones an object.
- * @param {Object} obj The object to clone.
- * @returns {Object} The cloned object.
+ * Creates a deep clone of a given object, including nested objects and arrays.
+ *
+ * @template T - The type of the object being cloned.
+ * @param {T} obj - The object to clone.
+ * @returns {T} A new object that is a deep clone of the original.
+ * @throws {Error} If the object contains a type that cannot be cloned.
  */
 function deepClone(obj) {
     if (obj === null || typeof obj !== 'object') {
@@ -1123,9 +1440,10 @@ function deepClone(obj) {
     throw new Error('Unable to clone object! Its type is not supported.');
 }
 /**
- * Converts an object to a query string.
- * @param {Object} obj The object to convert.
- * @returns {string} The query string.
+ * Converts a flat object into a URL query string.
+ *
+ * @param {Record<string, any>} obj - The object to convert.
+ * @returns {string} The resulting URL query string.
  */
 function objectToQueryString(obj) {
     return Object.keys(obj)
@@ -1135,10 +1453,11 @@ function objectToQueryString(obj) {
 // Example usage:
 // objectToQueryString({ name: 'John Doe', age: 30 }); // 'name=John%20Doe&age=30'
 /**
- * Gets the differences between two objects.
- * @param {Object} object1 The first object.
- * @param {Object} object2 The second object.
- * @returns {Object} An object containing the differences.
+ * Compares two objects and returns an object containing the keys where their values differ.
+ *
+ * @param {Record<string, any>} object1 - The first object.
+ * @param {Record<string, any>} object2 - The second object.
+ * @returns {Record<string, any>} An object where each key represents a difference, and the value contains the differing values from both objects.
  */
 function getObjectDifferences(object1, object2) {
     const differences = {};
@@ -1151,10 +1470,11 @@ function getObjectDifferences(object1, object2) {
     return differences;
 }
 /**
- * Filters an object by a list of keys.
- * @param {Object} obj The object to filter.
- * @param {Array<string>} keys The keys to keep.
- * @returns {Object} The filtered object.
+ * Creates a new object containing only the specified keys from the original object.
+ *
+ * @param {Record<string, any>} obj - The source object.
+ * @param {string[]} keys - An array of keys to include in the new object.
+ * @returns {Record<string, any>} A new object with the filtered properties.
  */
 function filterObjectByKeys(obj, keys) {
     const filteredObject = {};
@@ -1168,10 +1488,12 @@ function filterObjectByKeys(obj, keys) {
 // Example usage:
 // filterObjectByKeys({ name: 'John', age: 30, job: 'Developer' }, ['name', 'job']); // { name: 'John', job: 'Developer' }
 /**
- * Deeply merges two objects.
- * @param {Object} target The target object to merge into.
- * @param {Object} source The source object to merge from.
- * @returns {Object} The merged object.
+ * Recursively merges the properties of a source object into a target object.
+ *
+ * @template T - The type of the target object.
+ * @param {T} target - The object to merge properties into.
+ * @param {Partial<T>} source - The object from which to merge properties.
+ * @returns {T} The modified target object.
  */
 function deepMerge(target, source) {
     if (target === null || typeof target !== 'object' || typeof source !== 'object') {
@@ -1193,18 +1515,20 @@ function deepMerge(target, source) {
     return target;
 }
 /**
- * Checks if an object is empty.
- * @param {Object} obj The object to check.
- * @returns {boolean} True if the object is empty, otherwise false.
+ * Checks if an object has no own enumerable properties.
+ *
+ * @param {Record<string, any>} obj - The object to check.
+ * @returns {boolean} `true` if the object is empty, otherwise `false`.
  */
 function isEmptyObject(obj) {
     return Object.keys(obj).length === 0;
 }
 /**
- * Safely accesses nested properties in an object.
- * @param {Object} obj The object to access.
- * @param {Array<string>} keys The array of keys representing the path.
- * @returns {any} The value at the nested path, or undefined if not found.
+ * Safely retrieves a nested property from an object using an array of keys as the path.
+ *
+ * @param {Record<string, any>} obj - The object to query.
+ * @param {string[]} keys - An array of keys representing the path to the nested property.
+ * @returns {*} The value of the nested property, or `undefined` if the path is not valid.
  */
 function safeGet(obj, keys) {
     return keys.reduce((acc, key) => (acc && acc[key] !== undefined) ? acc[key] : undefined, obj);
@@ -1213,9 +1537,10 @@ function safeGet(obj, keys) {
 // safeGet({ a: { b: { c: 10 } } }, ['a', 'b', 'c']); // 10
 // safeGet({ a: { b: { c: 10 } } }, ['a', 'x', 'c']); // undefined
 /**
- * Removes empty properties (null, undefined, or empty string) from an object.
- * @param {Object} obj The object to clean.
- * @returns {Object} A new object without empty properties.
+ * Creates a new object with all properties that have `null`, `undefined`, or empty string values removed.
+ *
+ * @param {Record<string, any>} obj - The source object.
+ * @returns {Record<string, any>} A new object containing only the non-empty properties.
  */
 function removeEmptyProperties(obj) {
     return Object.keys(obj)
@@ -1228,9 +1553,10 @@ function removeEmptyProperties(obj) {
 // Example usage:
 // removeEmptyProperties({ a: null, b: 2, c: undefined, d: '', e: 'hello' }); // { b: 2, e: 'hello' }
 /**
- * Retrieves all keys of an object as an array.
- * @param {Object} obj The object to retrieve keys from.
- * @returns {Array<string>} The array of keys.
+ * Returns an array of an object's own enumerable property names.
+ *
+ * @param {Record<string, any>} obj - The object to get the keys from.
+ * @returns {string[]} An array of string keys.
  */
 function getObjectKeys(obj) {
     return Object.keys(obj);
@@ -1238,9 +1564,10 @@ function getObjectKeys(obj) {
 // Example usage:
 // getObjectKeys({ name: 'John', age: 30 }); // ['name', 'age']
 /**
- * Checks if an object has nested properties.
- * @param {Object} obj The object to check.
- * @returns {boolean} True if there are nested properties, false otherwise.
+ * Checks if any of the object's properties are themselves objects (and not null).
+ *
+ * @param {Record<string, any>} obj - The object to inspect.
+ * @returns {boolean} `true` if the object contains at least one nested object, otherwise `false`.
  */
 function hasNestedProperties(obj) {
     return Object.values(obj).some(value => typeof value === 'object' && value !== null);
@@ -1249,11 +1576,12 @@ function hasNestedProperties(obj) {
 // hasNestedProperties({ a: 1, b: { c: 2 } }); // true
 // hasNestedProperties({ a: 1, b: 2 }); // false
 /**
- * Converts an object to FormData, handling nested objects.
- * @param {Object} obj The object to convert.
- * @param {FormData} [formData] The FormData object to append to.
- * @param {string} [parentKey] The parent key for nested objects.
- * @returns {FormData} The FormData object.
+ * Recursively converts a nested object into a `FormData` object.
+ *
+ * @param {Record<string, any>} obj - The object to convert.
+ * @param {FormData} [formData=new FormData()] - An existing `FormData` object to append to.
+ * @param {string} [parentKey=''] - The base key for nested properties.
+ * @returns {FormData} The resulting `FormData` object.
  */
 function objectToFormDataEnhanced(obj, formData = new FormData(), parentKey = '') {
     Object.entries(obj).forEach(([key, value]) => {
@@ -1270,12 +1598,12 @@ function objectToFormDataEnhanced(obj, formData = new FormData(), parentKey = ''
 // Example usage:
 // objectToFormDataEnhanced({ user: { name: 'John', age: 30 } });
 /**
- * Converts a JavaScript object into FormData.
+ * Recursively converts a JavaScript object into a `FormData` object, handling nested objects and boolean conversion.
  *
- * @param obj - The object to be converted.
- * @param form - An optional FormData instance to use.
- * @param namespace - An optional namespace to use for nested objects.
- * @returns The FormData instance with the object's key-value pairs.
+ * @param {any} obj - The object to convert.
+ * @param {FormData} [form] - An optional existing `FormData` object to append to.
+ * @param {string} [namespace] - An optional namespace for keys of nested properties.
+ * @returns {FormData} The resulting `FormData` object.
  */
 const objectToFormData = function (obj, form, namespace) {
     const fd = form || new FormData();
@@ -1305,11 +1633,12 @@ const objectToFormData = function (obj, form, namespace) {
     return fd;
 };
 /**
- * Flattens a nested object, bringing all properties to the top level.
- * @param {Object} obj The object to flatten.
- * @param {string} [parentKey] The parent key for nested properties.
- * @param {Object} [result] The resulting flattened object.
- * @returns {Object} The flattened object.
+ * Flattens a nested object into a single-level object with dot-separated keys.
+ *
+ * @param {Record<string, any>} obj - The object to flatten.
+ * @param {string} [parentKey=''] - The prefix to use for the keys of the flattened properties.
+ * @param {Record<string, any>} [result={}] - An object to merge the flattened properties into.
+ * @returns {Record<string, any>} The flattened object.
  */
 function flattenObject(obj, parentKey = '', result = {}) {
     for (const key in obj) {
@@ -1329,13 +1658,14 @@ function flattenObject(obj, parentKey = '', result = {}) {
 // flattenObject({ a: 1, b: { c: 2, d: { e: 3 } } }); // { 'a': 1, 'b.c': 2, 'b.d.e': 3 }
 
 /**
- * Extracts and validates the access and refresh tokens from a response object.
- * Throws an error if the tokens are not found or are invalid.
+ * Extracts access and refresh tokens from a response object using specified dot-notation paths
+ * and validates their existence and type.
  *
- * @param {any} data - The API response object.
- * @param {AuthTokenPaths} tokenPaths - The paths for the tokens.
- * @param {string} errorSource - A prefix for the error message ("LOGIN" or "REFRESH").
- * @returns {TokenValidationResult} An object with the validated tokens.
+ * @param {any} data - The response object from which to extract the tokens.
+ * @param {AuthTokenPaths} tokenPaths - An object containing the dot-notation paths for the access and refresh tokens.
+ * @param {string} errorSource - A string to identify the source of the operation (e.g., "LOGIN", "REFRESH") for error messages.
+ * @returns {TokenValidationResult} An object containing the extracted `accessToken` and `refreshToken`.
+ * @throws {Error} If the data object is missing, or if the access or refresh tokens cannot be found at the specified paths or are not strings.
  */
 const extractAndValidateTokens = (data, tokenPaths, errorSource) => {
     const accessTokenPath = tokenPaths?.accessTokenPath || "access_token";
@@ -1355,52 +1685,149 @@ const extractAndValidateTokens = (data, tokenPaths, errorSource) => {
 };
 
 /**
-* Stores the access and refresh tokens in the appropriate storage based on the user's preference.
-*
-* @param {string} accessToken - El token de acceso.
-* @param {string} refreshToken - El token de refresco.
-* @param {LocationPreference} persistence - La preferencia de almacenamiento.
-*/
+ * Encrypts and stores both the access and refresh tokens in the specified storage location.
+ * Supports localStorage, sessionStorage, and cookies (with encryption and security options).
+ *
+ * @param {string} accessToken - The access token to be stored.
+ * @param {string} refreshToken - The refresh token to be stored.
+ * @param {LocationPreference} persistence - The desired storage location: 'local' for `localStorage`, 'session' for `sessionStorage`, or 'cookie' for cookies.
+ * @returns {Promise<void>} A promise that resolves when both tokens have been successfully stored.
+ */
 const storeTokens = async (accessToken, refreshToken, persistence) => {
     await storeAuthToken(accessToken, getAppKey(), persistence);
     await storeAuthRefreshToken(refreshToken, getAppKey(), persistence);
 };
 
+let defaultAuthFetcher = null;
+let createDefaultFetcher = null;
+/**
+ * Configures a default fetcher for authentication operations.
+ * If not configured, useAuth will use the default Axios fetcher.
+ *
+ * @param fetcher - The fetcher function to use for auth operations
+ *
+ * @example
+ * ```typescript
+ * import { configAuthFetcher, createOfetchFetcher } from '@arex95/vue-core';
+ *
+ * const ofetchFetcher = createOfetchFetcher();
+ * configAuthFetcher(ofetchFetcher);
+ * ```
+ */
+function configAuthFetcher(fetcher) {
+    defaultAuthFetcher = fetcher;
+}
+/**
+ * Configures a factory function to create the default fetcher lazily.
+ * This is used internally to avoid circular dependencies.
+ *
+ * @param factory - Factory function that creates a fetcher
+ */
+function setDefaultAuthFetcherFactory(factory) {
+    createDefaultFetcher = factory;
+}
+/**
+ * Gets the default auth fetcher, creating one from Axios if not configured.
+ * This allows lazy initialization to avoid circular dependencies.
+ *
+ * @returns The fetcher function to use
+ */
+function getDefaultAuthFetcher() {
+    if (defaultAuthFetcher) {
+        return defaultAuthFetcher;
+    }
+    if (createDefaultFetcher) {
+        defaultAuthFetcher = createDefaultFetcher();
+        return defaultAuthFetcher;
+    }
+    throw new Error('Auth fetcher not configured. Please configure Axios or set a custom auth fetcher.');
+}
+
 /**
-   * Refreshes the authentication tokens using the stored refresh token.
-   * This function can also accept optional token paths if the refresh endpoint
-   * returns tokens with a different structure than the default login.
-   * If no refresh token is found, it throws an error and initiates a logout.
-   *
-   * @param {AuthTokenPaths} [tokenPaths] - Optional configuration for the paths (in dot notation) of the access and refresh tokens in the refresh endpoint response.
-   * @returns {Promise<AuthResponse>} The new authentication response with refreshed tokens.
-   * @throws {Error} If the refresh token is missing or the refresh request fails.
-   */
-const refreshTokens = async (axiosInstance) => {
+ * Refreshes the access and refresh tokens by making a POST request to the refresh endpoint.
+ * It retrieves the current refresh token from storage, sends it to the refresh endpoint,
+ * and then stores the new tokens upon a successful response. If the refresh process fails
+ * or no refresh token is found, it clears all credentials and reloads the page.
+ *
+ * @param {Fetcher} [fetcher] - Optional fetcher function to use for the refresh request. If not provided, uses the default configured fetcher.
+ * @returns {Promise<AuthResponse>} A promise that resolves with the new authentication response containing the refreshed tokens.
+ * @throws {Error} Throws an error if the refresh token is missing or if the refresh request fails, which is then caught to trigger a logout.
+ */
+const refreshTokens = async (fetcher) => {
     const tokenPaths = getRefreshTokenPathsConfig();
     const endpoints = getEndpointsConfig();
     const secretKey = getAppKey();
     const persistence = await getSessionPersistence();
+    const getFetcher = () => fetcher || getDefaultAuthFetcher();
     try {
         const refreshTokenFromStorage = await getAuthRefreshToken(secretKey, "any");
         if (!refreshTokenFromStorage) {
             throw new Error("TOKEN_MISSING: No refresh token found in storage.");
         }
-        const { data } = await axiosInstance.post(endpoints.REFRESH);
+        const data = await getFetcher()({
+            method: 'POST',
+            url: endpoints.REFRESH,
+        });
         const { accessToken, refreshToken } = extractAndValidateTokens(data, tokenPaths, "REFRESH");
         await storeTokens(accessToken, refreshToken, persistence);
         return data;
     }
     catch (error) {
-        handleError(error, false);
+        handleError(error);
         await cleanCredentials(persistence);
-        if (window) {
+        if (typeof window !== 'undefined') {
             window.location.reload();
         }
         throw error;
     }
 };
 
+/**
+ * Creates a fetcher function using Axios.
+ *
+ * @param axiosInstance - The Axios instance to use
+ * @returns A fetcher function compatible with RestStd
+ *
+ * @example
+ * ```typescript
+ * import axios from 'axios';
+ * import { createAxiosFetcher, RestStd } from '@arex95/vue-core';
+ *
+ * const axiosInstance = axios.create({ baseURL: 'https://api.example.com' });
+ *
+ * export class Role extends RestStd {
+ *     static override resource = 'roles';
+ *     static fetchFn = createAxiosFetcher(axiosInstance);
+ * }
+ * ```
+ */
+function createAxiosFetcher(axiosInstance) {
+    return async (config) => {
+        try {
+            const response = await axiosInstance({
+                method: config.method,
+                url: config.url,
+                params: config.params,
+                data: config.data,
+                headers: config.headers,
+            });
+            return response.data;
+        }
+        catch (error) {
+            if (error instanceof AxiosError || error?.isAxiosError) {
+                throw NetworkError.fromAxiosError(error);
+            }
+            throw error;
+        }
+    };
+}
+
+/**
+ * A service class that encapsulates a customizable Axios instance with built-in interceptors
+ * for handling authentication, token refreshing, and request cancellation. It is designed to
+ * streamline API communication by automatically attaching authorization headers and managing
+ * token refresh logic for 401 Unauthorized responses.
+ */
 class AxiosService {
     instance;
     cancelTokenSource;
@@ -1408,6 +1835,10 @@ class AxiosService {
     refreshTokenUrl;
     isRefreshing = false;
     failedQueue = [];
+    /**
+     * Creates an instance of AxiosService.
+     * @param {AxiosServiceOptions} options - Configuration options for the Axios instance, such as `baseURL`, `timeout`, and custom `headers`.
+     */
     constructor(options) {
         this.cancelTokenSource = axios.CancelToken.source();
         const endpointsConfig = getEndpointsConfig();
@@ -1450,7 +1881,7 @@ class AxiosService {
             this.activeRequests++;
             return config;
         }, (error) => {
-            handleError(error, false);
+            handleError(error);
             return Promise.reject(error);
         });
         this.instance.interceptors.response.use((response) => {
@@ -1463,11 +1894,11 @@ class AxiosService {
             const isRefreshCall = originalRequest?.url === this.refreshTokenUrl;
             const isRetry = originalRequest?._retry === true;
             if (!isAuthError || isRefreshCall || isRetry) {
-                handleError(error, false);
+                handleError(error);
                 return Promise.reject(error);
             }
             if (!originalRequest) {
-                handleError(error, false);
+                handleError(error);
                 return Promise.reject(error);
             }
             if (this.isRefreshing) {
@@ -1485,7 +1916,8 @@ class AxiosService {
             this.isRefreshing = true;
             originalRequest._retry = true;
             try {
-                await refreshTokens(this.instance);
+                const fetcher = createAxiosFetcher(this.instance);
+                await refreshTokens(fetcher);
                 const newToken = await getAuthToken(getAppKey(), "any");
                 if (newToken) {
                     this.processQueue(null, newToken);
@@ -1502,49 +1934,113 @@ class AxiosService {
             catch (refreshError) {
                 this.processQueue(refreshError, null);
                 this.isRefreshing = false;
-                handleError(refreshError, false);
+                handleError(refreshError);
                 return Promise.reject(error);
             }
         });
     }
+    /**
+     * Returns the number of active (in-flight) requests.
+     * @returns {number} The number of active requests.
+     */
     getActiveRequests() {
         return this.activeRequests;
     }
+    /**
+     * Returns the underlying Axios instance.
+     * @returns {AxiosInstance} The Axios instance.
+     */
     getAxiosInstance() {
         return this.instance;
     }
+    /**
+     * Cancels all ongoing requests made by this Axios instance.
+     */
     cancelAllRequests() {
         this.cancelTokenSource.cancel("Operation canceled by the user.");
         this.cancelTokenSource = axios.CancelToken.source();
     }
+    /**
+     * Sets a default header for all subsequent requests.
+     * @param {string} key - The header key.
+     * @param {string} value - The header value.
+     */
     setHeader(key, value) {
         this.instance.defaults.headers.common[key] = value;
     }
+    /**
+     * Removes a default header.
+     * @param {string} key - The header key to remove.
+     */
     removeHeader(key) {
         delete this.instance.defaults.headers.common[key];
     }
 }
 
-let axiosServiceInstance;
+let axiosServiceInstance = null;
+let defaultConfig = null;
+/**
+ * Configures the singleton Axios service instance for the application.
+ * This function should be called once at the application's entry point to set up
+ * the base URL, headers, and other default configurations for all API requests.
+ *
+ * @param {AxiosServiceOptions} config - The configuration options for the Axios service.
+ */
 const configAxios = (config) => {
+    defaultConfig = config;
     axiosServiceInstance = new AxiosService({
         baseURL: config.baseURL,
         headers: config.headers,
         timeout: config.timeout,
         withCredentials: config.withCredentials
     });
+    // Configure auth fetcher factory to avoid circular dependency
+    const { setDefaultAuthFetcherFactory } = require("@/config/auth/authFetcher");
+    const { createAxiosFetcher } = require("@/fetchers/axios");
+    setDefaultAuthFetcherFactory(() => {
+        return createAxiosFetcher(axiosServiceInstance.getAxiosInstance());
+    });
 };
+/**
+ * Retrieves the configured singleton Axios instance.
+ * If not configured yet, creates a default instance with minimal configuration.
+ * This allows lazy initialization to avoid dependency circular issues in Nuxt and other frameworks.
+ *
+ * @returns {AxiosInstance} The configured Axios instance.
+ */
 const getConfiguredAxiosInstance = () => {
     if (!axiosServiceInstance) {
-        throw new Error("Axios instance not configured. Call configAxios first.");
+        if (defaultConfig) {
+            axiosServiceInstance = new AxiosService({
+                baseURL: defaultConfig.baseURL,
+                headers: defaultConfig.headers,
+                timeout: defaultConfig.timeout,
+                withCredentials: defaultConfig.withCredentials
+            });
+        }
+        else {
+            axiosServiceInstance = new AxiosService({
+                baseURL: '',
+                headers: {},
+                timeout: 30000,
+                withCredentials: false
+            });
+        }
+        // Configure auth fetcher factory to avoid circular dependency
+        const { setDefaultAuthFetcherFactory } = require("@/config/auth/authFetcher");
+        const { createAxiosFetcher } = require("@/fetchers/axios");
+        setDefaultAuthFetcherFactory(() => {
+            return createAxiosFetcher(axiosServiceInstance.getAxiosInstance());
+        });
     }
     return axiosServiceInstance.getAxiosInstance();
 };
 
 /**
- * Creates and downloads a file from Blob data.
- * @param {Blob} blob The Blob containing the file data.
- * @param {string} fileName The name of the file to create.
+ * Triggers a browser download for a file created from a `Blob` object.
+ *
+ * @param {Blob} blob - The `Blob` containing the file's data.
+ * @param {string} fileName - The desired name for the downloaded file.
  */
 function downloadFile(blob, fileName) {
     const link = document.createElement('a');
@@ -1559,10 +2055,11 @@ function downloadFile(blob, fileName) {
     URL.revokeObjectURL(url);
 }
 /**
- * Exports data to a CSV file.
- * @param {string[]} headers The headers for the CSV.
- * @param {any[][]} data The data to export, as an array of arrays.
- * @param {string} fileName The name of the file to create.
+ * Converts an array of data into a CSV format and triggers a download.
+ *
+ * @param {string[]} headers - An array of strings to be used as the CSV header row.
+ * @param {any[][]} data - A 2D array representing the rows and cells of the data to be exported.
+ * @param {string} fileName - The desired name for the downloaded CSV file.
  */
 function exportToCSV(headers, data, fileName) {
     const csvRows = [];
@@ -1579,10 +2076,11 @@ function exportToCSV(headers, data, fileName) {
     downloadFile(blob, fileName);
 }
 /**
- * Exports data to an Excel file (.xls) using HTML table.
- * @param {string[]} headers The headers for the Excel file.
- * @param {any[][]} data The data to export, as an array of arrays.
- * @param {string} fileName The name of the file to create.
+ * Converts an array of data into an HTML table, then triggers a download as an Excel (.xls) file.
+ *
+ * @param {string[]} headers - An array of strings for the table headers.
+ * @param {any[][]} data - A 2D array of the data to be exported.
+ * @param {string} fileName - The desired name for the downloaded Excel file.
  */
 function exportToExcel(headers, data, fileName) {
     // Create a table element
@@ -1611,9 +2109,10 @@ function exportToExcel(headers, data, fileName) {
     downloadFile(blob, fileName);
 }
 /**
- * Exports data to a JSON file.
- * @param {any[]} data The data to export.
- * @param {string} fileName The name of the file to create.
+ * Converts an array of data into a pretty-printed JSON string and triggers a download.
+ *
+ * @param {any[]} data - The data to be serialized into JSON.
+ * @param {string} fileName - The desired name for the downloaded JSON file.
  */
 function exportToJSON(data, fileName) {
     const jsonContent = JSON.stringify(data, null, 2); // Pretty print with 2 spaces
@@ -1622,10 +2121,11 @@ function exportToJSON(data, fileName) {
     downloadFile(blob, fileName);
 }
 /**
- * Exports data to an XML file.
- * @param {string[]} headers The headers for the XML.
- * @param {any[][]} data The data to export, as an array of arrays.
- * @param {string} fileName The name of the file to create.
+ * Converts an array of data into a simple XML format and triggers a download.
+ *
+ * @param {string[]} headers - An array of strings to be used as column headers in the XML.
+ * @param {any[][]} data - A 2D array of the data to be exported.
+ * @param {string} fileName - The desired name for the downloaded XML file.
  */
 function exportToXML(headers, data, fileName) {
     let xmlContent = '<?xml version="1.0" encoding="UTF-8"?>\n<rows>\n';
@@ -1649,10 +2149,11 @@ function exportToXML(headers, data, fileName) {
     downloadFile(blob, fileName);
 }
 /**
- * Exports data to a plain text file.
- * @param {string[]} headers The headers for the text file.
- * @param {any[][]} data The data to export, as an array of arrays.
- * @param {string} fileName The name of the file to create.
+ * Converts an array of data into a tab-separated text format and triggers a download.
+ *
+ * @param {string[]} headers - An array of strings for the header row.
+ * @param {any[][]} data - A 2D array of the data to be exported.
+ * @param {string} fileName - The desired name for the downloaded text file.
  */
 function exportToText(headers, data, fileName) {
     const textRows = [];
@@ -1670,12 +2171,13 @@ function exportToText(headers, data, fileName) {
 }
 
 /**
- * Opens a new window with the specified URL and options.
- * @param {string} url The URL to open.
- * @param {Object} [opt] Options for the new window.
- * @param {string} [opt.target='__blank'] The target window name.
- * @param {boolean} [opt.noopener=true] Whether to add 'noopener' attribute.
- * @param {boolean} [opt.noreferrer=true] Whether to add 'noreferrer' attribute.
+ * Opens a new browser window or tab with a specified URL, providing options for the target and security attributes.
+ *
+ * @param {string} url - The URL to open in the new window.
+ * @param {object} [opt] - Optional configuration for the new window.
+ * @param {string} [opt.target='_blank'] - The target attribute for the link, specifying where to open the content (e.g., '_blank', '_self').
+ * @param {boolean} [opt.noopener=true] - If `true`, adds `noopener` to the window features to prevent the new window from accessing the original window's object.
+ * @param {boolean} [opt.noreferrer=true] - If `true`, adds `noreferrer` to prevent the browser from sending the `Referer` HTTP header.
  */
 function openWindow(url, opt) {
     const { target = '__blank', noopener = true, noreferrer = true } = opt || {};
@@ -1689,9 +2191,11 @@ function openWindow(url, opt) {
     window.open(url, target, features.join(','));
 }
 /**
- * Copies text to the clipboard.
- * @param {string} text The text to copy.
- * @returns {Promise<void>} A promise that resolves when the text has been copied.
+ * Asynchronously copies a given string to the user's clipboard. It uses the modern `navigator.clipboard` API
+ * with a fallback to the deprecated `document.execCommand` for older browsers.
+ *
+ * @param {string} text - The string to be copied to the clipboard.
+ * @returns {Promise<void>} A promise that resolves when the text has been successfully copied.
  */
 async function copyToClipboard(text) {
     if (navigator.clipboard) {
@@ -1708,8 +2212,10 @@ async function copyToClipboard(text) {
     }
 }
 /**
- * Scrolls the window to the top smoothly.
- * @param {number} [duration=300] Duration of the scroll animation in milliseconds.
+ * Smoothly scrolls the window to the top of the page using a `requestAnimationFrame` loop
+ * for a fluid animation.
+ *
+ * @param {number} [duration=300] - The total duration of the scroll animation in milliseconds.
  */
 function scrollToTop(duration = 300) {
     const start = window.scrollY;
@@ -1725,9 +2231,10 @@ function scrollToTop(duration = 300) {
     requestAnimationFrame(scroll);
 }
 /**
- * Gets the value of a query parameter from the URL.
- * @param {string} paramName The name of the query parameter.
- * @returns {string | null} The value of the query parameter, or null if it does not exist.
+ * Retrieves the value of a specified query parameter from the current URL's search string.
+ *
+ * @param {string} paramName - The name of the query parameter to retrieve.
+ * @returns {string | null} The value of the query parameter, or `null` if the parameter is not present in the URL.
  */
 function getQueryParam(paramName) {
     const urlParams = new URLSearchParams(window.location.search);
@@ -1735,7 +2242,7 @@ function getQueryParam(paramName) {
 }
 
 /**
- * Disables the right-click context menu on the window.
+ * Disables the default right-click context menu on the entire window.
  */
 function disableRightClick() {
     const handler = (event) => event.preventDefault();
@@ -1745,7 +2252,7 @@ function disableRightClick() {
 }
 disableRightClick.handler = null;
 /**
- * Enables the right-click context menu on the window.
+ * Re-enables the right-click context menu if it was previously disabled by `disableRightClick`.
  */
 function enableRightClick() {
     if (disableRightClick.handler) {
@@ -1753,8 +2260,9 @@ function enableRightClick() {
     }
 }
 /**
- * Disables specific mouse buttons.
- * @param {Array<number>} buttons Array of mouse button codes to disable (0 for left, 1 for middle, 2 for right).
+ * Prevents the default action for specific mouse buttons on the `mousedown` event.
+ *
+ * @param {number[]} buttons - An array of mouse button codes to disable (0 for left, 1 for middle, 2 for right).
  */
 function disableMouseButtons(buttons) {
     const handler = (event) => {
@@ -1769,7 +2277,7 @@ function disableMouseButtons(buttons) {
 }
 disableMouseButtons.handlers = [];
 /**
- * Enables all previously disabled mouse buttons.
+ * Re-enables all mouse buttons that were previously disabled by `disableMouseButtons`.
  */
 function enableMouseButtons() {
     for (const handler of disableMouseButtons.handlers) {
@@ -1779,17 +2287,19 @@ function enableMouseButtons() {
     disableMouseButtons.handlers = [];
 }
 /**
- * Adds a double-click event listener to a specific element.
- * @param {HTMLElement} element The target element.
- * @param {(event: MouseEvent) => void} callback The callback function to execute on double click.
+ * Attaches a `dblclick` event listener to a specified HTML element.
+ *
+ * @param {HTMLElement} element - The DOM element to attach the listener to.
+ * @param {(event: MouseEvent) => void} callback - The function to execute when the element is double-clicked.
  */
 function addDoubleClickListener(element, callback) {
     element.addEventListener('dblclick', callback);
 }
 /**
- * Removes a double-click event listener from a specific element.
- * @param {HTMLElement} element The target element.
- * @param {(event: MouseEvent) => void} callback The callback function to remove.
+ * Removes a `dblclick` event listener from a specified HTML element.
+ *
+ * @param {HTMLElement} element - The DOM element to remove the listener from.
+ * @param {(event: MouseEvent) => void} callback - The callback function that was originally added.
  */
 function removeDoubleClickListener(element, callback) {
     element.removeEventListener('dblclick', callback);
@@ -1797,9 +2307,10 @@ function removeDoubleClickListener(element, callback) {
 // Example usage:
 // addDoubleClickListener(document.body, () => alert('Double clicked!'));
 /**
- * Detects a click outside a specific element and triggers a callback.
- * @param {HTMLElement} element The element to detect clicks outside of.
- * @param {() => void} callback The callback function to execute when a click outside is detected.
+ * Sets up a global click listener to detect when a user clicks outside of a specified element.
+ *
+ * @param {HTMLElement} element - The element to monitor for outside clicks.
+ * @param {() => void} callback - The function to execute when a click outside the element is detected.
  */
 function clickOutside(element, callback) {
     const handler = (event) => {
@@ -1813,8 +2324,9 @@ function clickOutside(element, callback) {
 }
 clickOutside.handlers = [];
 /**
- * Removes the click outside listener for a specific element.
- * @param {HTMLElement} element The element to stop detecting clicks outside of.
+ * Removes the "click outside" event listener for a specific element that was added by `clickOutside`.
+ *
+ * @param {HTMLElement} element - The element for which to remove the listener.
  */
 function removeClickOutside(element) {
     const index = clickOutside.handlers.findIndex(h => h.element === element);
@@ -1829,7 +2341,8 @@ function removeClickOutside(element) {
 //     clickOutside(menu, () => menu.style.display = 'none');
 // }
 /**
- * Disables the F12 key and certain key combinations for developer tools.
+ * Disables the F12 key and common developer tool shortcuts (Ctrl+Shift+I, Ctrl+Shift+J)
+ * to prevent users from easily opening the browser's developer console.
  */
 function disableF12Key() {
     const handler = function (event) {
@@ -1838,8 +2351,9 @@ function disableF12Key() {
     document.addEventListener('keydown', handler);
 }
 /**
- * Enables or disables the tab navigation (Tab key) on the page.
- * @param {boolean} enable Whether to enable or disable tab navigation.
+ * Enables or disables the ability to navigate through focusable elements using the Tab key.
+ *
+ * @param {boolean} enable - If `true`, tab navigation is enabled; if `false`, it is disabled.
  */
 function toggleTabNavigation(enable) {
     if (enable) {
@@ -1856,7 +2370,7 @@ function toggleTabNavigation(enable) {
     }
 }
 /**
- * Disables the copy (Ctrl + C) functionality on the page.
+ * Prevents users from copying content from the page by intercepting the `copy` event.
  */
 function disableCopy() {
     document.addEventListener('copy', (event) => {
@@ -1865,11 +2379,12 @@ function disableCopy() {
     });
 }
 /**
- * Adds a custom keyboard shortcut to execute a given callback function.
- * @param {string} key The key to trigger the callback.
- * @param {Function} callback The function to execute on the key press.
- * @param {boolean} [ctrlKey=false] Whether Ctrl key should be pressed.
- * @param {boolean} [shiftKey=false] Whether Shift key should be pressed.
+ * Registers a global keyboard shortcut that triggers a callback when a specific key combination is pressed.
+ *
+ * @param {string} key - The main key for the shortcut (e.g., 'S', 'F1').
+ * @param {() => void} callback - The function to execute when the shortcut is pressed.
+ * @param {boolean} [ctrlKey=false] - If `true`, the Ctrl key must be pressed.
+ * @param {boolean} [shiftKey=false] - If `true`, the Shift key must be pressed.
  */
 function addCustomKeyboardShortcut(key, callback, ctrlKey = false, shiftKey = false) {
     document.addEventListener('keydown', (event) => {
@@ -1882,10 +2397,11 @@ function addCustomKeyboardShortcut(key, callback, ctrlKey = false, shiftKey = fa
     });
 }
 /**
- * Removes a custom keyboard shortcut by key and modifiers.
- * @param {string} key The key to trigger the callback.
- * @param {boolean} [ctrlKey=false] Whether Ctrl key should be pressed.
- * @param {boolean} [shiftKey=false] Whether Shift key should be pressed.
+ * Removes a global keyboard shortcut that was previously added.
+ *
+ * @param {string} key - The main key of the shortcut to remove.
+ * @param {boolean} [ctrlKey=false] - The Ctrl key modifier of the shortcut.
+ * @param {boolean} [shiftKey=false] - The Shift key modifier of the shortcut.
  */
 function removeCustomKeyboardShortcut(key, ctrlKey = false, shiftKey = false) {
     const handler = (event) => {
@@ -1898,8 +2414,9 @@ function removeCustomKeyboardShortcut(key, ctrlKey = false, shiftKey = false) {
     document.removeEventListener('keydown', handler);
 }
 /**
- * Disables specific keys or key combinations.
- * @param {Array<string>} keys Array of key names to disable (e.g., ['F1', 'F5', 'Control+S']).
+ * Disables a list of specified keys or key combinations.
+ *
+ * @param {string[]} keys - An array of key names or combinations (e.g., 'F1', 'Control+S') to disable.
  */
 function disableSpecificKeys(keys) {
     const handler = (event) => {
@@ -1914,7 +2431,7 @@ function disableSpecificKeys(keys) {
 }
 disableSpecificKeys.handlers = [];
 /**
- * Enables keys that were previously disabled using disableSpecificKeys.
+ * Re-enables all keys that were previously disabled by `disableSpecificKeys`.
  */
 function enableSpecificKeys() {
     for (const handler of disableSpecificKeys.handlers) {
@@ -1923,8 +2440,9 @@ function enableSpecificKeys() {
     disableSpecificKeys.handlers = [];
 }
 /**
- * Registers multiple keyboard shortcuts with their respective callback functions.
- * @param {Array<{ key: string, ctrlKey?: boolean, shiftKey?: boolean, altKey?: boolean, callback: Function }>} shortcuts Array of shortcut objects.
+ * Registers multiple keyboard shortcuts from an array of shortcut configurations.
+ *
+ * @param {Array<{ key: string; ctrlKey?: boolean; shiftKey?: boolean; altKey?: boolean; callback: () => void }>} shortcuts - An array of shortcut objects.
  */
 function registerKeyboardShortcuts(shortcuts) {
     const handler = (event) => {
@@ -1944,7 +2462,7 @@ function registerKeyboardShortcuts(shortcuts) {
 }
 registerKeyboardShortcuts.handlers = [];
 /**
- * Unregisters all keyboard shortcuts that were registered with registerKeyboardShortcuts.
+ * Removes all keyboard shortcuts that were registered using `registerKeyboardShortcuts`.
  */
 function unregisterKeyboardShortcuts() {
     for (const handler of registerKeyboardShortcuts.handlers) {
@@ -1953,9 +2471,10 @@ function unregisterKeyboardShortcuts() {
     registerKeyboardShortcuts.handlers = [];
 }
 /**
- * Adds a listener for a specific key to trigger a custom event.
- * @param {string} key The key to listen for (e.g., 'Enter', 'Escape').
- * @param {Function} callback The function to execute when the key is pressed.
+ * Adds a global `keydown` listener for a specific key.
+ *
+ * @param {string} key - The key to listen for (e.g., 'Enter', 'Escape').
+ * @param {() => void} callback - The function to execute when the key is pressed.
  */
 function addKeyListener(key, callback) {
     const handler = (event) => {
@@ -1970,7 +2489,7 @@ function addKeyListener(key, callback) {
 }
 addKeyListener.handlers = [];
 /**
- * Removes all custom key listeners added by addKeyListener.
+ * Removes all key listeners that were added using `addKeyListener`.
  */
 function removeKeyListeners() {
     for (const handler of addKeyListener.handlers) {
@@ -1979,9 +2498,10 @@ function removeKeyListeners() {
     addKeyListener.handlers = [];
 }
 /**
- * Detects if a specific key is held down.
- * @param {string} key The key to detect (e.g., 'Shift', 'Control', 'Alt', 'a').
- * @param {Function} onHold Callback function to execute while the key is held down.
+ * Executes a callback function repeatedly while a specific key is held down.
+ *
+ * @param {string} key - The key to monitor.
+ * @param {() => void} onHold - The callback function to execute on each `keydown` event for the specified key.
  */
 function detectKeyHold(key, onHold) {
     const keyDownHandler = (event) => {
@@ -1995,7 +2515,7 @@ function detectKeyHold(key, onHold) {
 }
 detectKeyHold.handlers = [];
 /**
- * Stops detecting if a specific key is held down.
+ * Removes all key hold listeners that were added by `detectKeyHold`.
  */
 function stopDetectingKeyHold() {
     for (const handler of detectKeyHold.handlers) {
@@ -2004,8 +2524,9 @@ function stopDetectingKeyHold() {
     detectKeyHold.handlers = [];
 }
 /**
- * Tracks currently pressed keys and provides a map of active keys.
- * @returns {Set<string>} A set of currently pressed keys.
+ * Creates and maintains a `Set` of currently pressed keys.
+ *
+ * @returns {Set<string>} A `Set` that dynamically updates with the keys being pressed.
  */
 function createKeyMap() {
     const pressedKeys = new Set();
@@ -2025,13 +2546,14 @@ function createKeyMap() {
     return pressedKeys;
 }
 /**
- * Clears listeners for the key map tracking.
+ * Clears the `keydown` and `keyup` event listeners created by `createKeyMap`.
  */
 createKeyMap.clearListeners = () => { };
 /**
- * Sets up custom keyboard shortcuts with flexible order.
- * @param {Array<string>} keys The combination of keys for the shortcut.
- * @param {Function} callback The callback function to execute when the combination is detected.
+ * Sets up a keyboard shortcut that triggers a callback when a specific combination of keys is held down, regardless of order.
+ *
+ * @param {string[]} keys - An array of keys that constitute the shortcut.
+ * @param {() => void} callback - The function to execute when the key combination is active.
  */
 function customShortcut(keys, callback) {
     const pressedKeys = new Set();
@@ -2051,7 +2573,7 @@ function customShortcut(keys, callback) {
 }
 customShortcut.handlers = [];
 /**
- * Removes all custom keyboard shortcuts added by customShortcut.
+ * Removes all keyboard shortcut listeners that were added by `customShortcut`.
  */
 function removeCustomShortcuts() {
     for (const { keyDownHandler, keyUpHandler } of customShortcut.handlers) {
@@ -2061,11 +2583,12 @@ function removeCustomShortcuts() {
     customShortcut.handlers = [];
 }
 /**
- * Simulates a key press event.
- * @param {string} key The key to simulate (e.g., 'Enter', 'a').
- * @param {boolean} ctrlKey If true, include Ctrl key in the event.
- * @param {boolean} shiftKey If true, include Shift key in the event.
- * @param {boolean} altKey If true, include Alt key in the event.
+ * Programmatically dispatches a `keydown` event to simulate a key press.
+ *
+ * @param {string} key - The key to simulate (e.g., 'Enter', 'a').
+ * @param {boolean} [ctrlKey=false] - Whether to simulate the Ctrl key being pressed.
+ * @param {boolean} [shiftKey=false] - Whether to simulate the Shift key being pressed.
+ * @param {boolean} [altKey=false] - Whether to simulate the Alt key being pressed.
  */
 function simulateKeyPress(key, ctrlKey = false, shiftKey = false, altKey = false) {
     const event = new KeyboardEvent('keydown', {
@@ -2080,9 +2603,11 @@ function simulateKeyPress(key, ctrlKey = false, shiftKey = false, altKey = false
 }
 
 /**
- * Parses a date string into a Date object.
- * @param {string} dateString The date string in 'YYYY-MM-DD' format.
- * @returns {Date | null} The parsed Date object or null if the format is invalid.
+ * Parses a date string in the format 'YYYY-MM-DD' and returns a `Date` object.
+ * It includes validation to ensure the parsed date is a valid calendar date.
+ *
+ * @param {string} dateString - The date string to parse.
+ * @returns {Date | null} A `Date` object if the string is a valid date, otherwise `null`.
  */
 function parseDate(dateString) {
     const parts = dateString.split('-');
@@ -2098,9 +2623,11 @@ function parseDate(dateString) {
     return null;
 }
 /**
- * Formats a Date object into a string.
- * @param {Date} date The date to format.
- * @param {string} format The format string (e.g., 'YYYY-MM-DD').
+ * Formats a `Date` object into a custom string format.
+ * Supported format specifiers: YYYY, MM, DD, HH, mm, ss.
+ *
+ * @param {Date} date - The `Date` object to format.
+ * @param {string} format - The desired string format (e.g., 'YYYY-MM-DD HH:mm:ss').
  * @returns {string} The formatted date string.
  */
 function formatDate(date, format) {
@@ -2115,9 +2642,10 @@ function formatDate(date, format) {
     return format.replace(/YYYY|MM|DD|HH|mm|ss/g, (matched) => (map[matched] || matched).toString());
 }
 /**
- * Calculates the number of days between two dates.
- * @param {Date} startDate The start date.
- * @param {Date} endDate The end date.
+ * Calculates the total number of full days between two dates.
+ *
+ * @param {Date} startDate - The starting date.
+ * @param {Date} endDate - The ending date.
  * @returns {number} The number of days between the two dates.
  */
 function daysBetween(startDate, endDate) {
@@ -2125,10 +2653,11 @@ function daysBetween(startDate, endDate) {
     return Math.round((endDate.getTime() - startDate.getTime()) / millisecondsPerDay);
 }
 /**
- * Adds a specified number of days to a date.
- * @param {Date} date The date to modify.
- * @param {number} days The number of days to add.
- * @returns {Date} The new date with days added.
+ * Adds a specified number of days to a given date.
+ *
+ * @param {Date} date - The original date.
+ * @param {number} days - The number of days to add (can be negative to subtract).
+ * @returns {Date} A new `Date` object representing the resulting date.
  */
 function addDays(date, days) {
     const result = new Date(date);
@@ -2136,41 +2665,46 @@ function addDays(date, days) {
     return result;
 }
 /**
- * Subtracts a specified number of days from a date.
- * @param {Date} date The date to modify.
- * @param {number} days The number of days to subtract.
- * @returns {Date} The new date with days subtracted.
+ * Subtracts a specified number of days from a given date.
+ *
+ * @param {Date} date - The original date.
+ * @param {number} days - The number of days to subtract.
+ * @returns {Date} A new `Date` object representing the resulting date.
  */
 function subtractDays(date, days) {
     return addDays(date, -days);
 }
 /**
- * Determines if a year is a leap year.
- * @param {number} year The year to check.
- * @returns {boolean} True if the year is a leap year, false otherwise.
+ * Determines whether a given year is a leap year according to the Gregorian calendar rules.
+ *
+ * @param {number} year - The year to check.
+ * @returns {boolean} `true` if the year is a leap year, otherwise `false`.
  */
 function isLeapYear(year) {
     return (year % 4 === 0 && year % 100 !== 0) || (year % 400 === 0);
 }
 /**
- * Gets the first day of the month for a given date.
- * @param {Date} date The date to use.
- * @returns {Date} The first day of the month.
+ * Returns a new `Date` object set to the first day of the month for a given date.
+ *
+ * @param {Date} date - The date from which to determine the month and year.
+ * @returns {Date} A `Date` object representing the start of the month.
  */
 function getStartOfMonth(date) {
     return new Date(date.getFullYear(), date.getMonth(), 1);
 }
 /**
- * Gets the last day of the month for a given date.
- * @param {Date} date The date to use.
- * @returns {Date} The last day of the month.
+ * Returns a new `Date` object set to the last day of the month for a given date.
+ *
+ * @param {Date} date - The date from which to determine the month and year.
+ * @returns {Date} A `Date` object representing the end of the month.
  */
 function getEndOfMonth(date) {
     return new Date(date.getFullYear(), date.getMonth() + 1, 0);
 }
 /**
- * Calculates age from a given birth date.
- * @param {Date} birthDate The birth date.
+ * Calculates the current age in years based on a given birth date.
+ *
+ * @param {Date} birthDate - The date of birth.
  * @returns {number} The calculated age.
  */
 function calculateAge(birthDate) {
@@ -2183,8 +2717,9 @@ function calculateAge(birthDate) {
     return age;
 }
 /**
- * Calculates the number of days until the next birthday.
- * @param {Date} birthDate The birth date.
+ * Calculates the number of days from the current date until the next birthday.
+ *
+ * @param {Date} birthDate - The date of birth.
  * @returns {number} The number of days until the next birthday.
  */
 function daysToNextBirthday(birthDate) {
@@ -2198,10 +2733,11 @@ function daysToNextBirthday(birthDate) {
     return daysBetween(today, nextBirthday);
 }
 /**
- * Calculates the age at a specific date.
- * @param {Date} birthDate The birth date.
- * @param {Date} atDate The date to calculate the age at.
- * @returns {number} The calculated age.
+ * Calculates the age of a person on a specific date in the past or future.
+ *
+ * @param {Date} birthDate - The date of birth.
+ * @param {Date} atDate - The target date for which to calculate the age.
+ * @returns {number} The age on the specified date.
  */
 function ageAtDate(birthDate, atDate) {
     let age = atDate.getFullYear() - birthDate.getFullYear();
@@ -2213,11 +2749,12 @@ function ageAtDate(birthDate, atDate) {
 }
 
 /**
- * Creates a debounced asynchronous validator function.
+ * Creates a debounced version of an asynchronous validator function. This is useful for scenarios
+ * like form input validation where you want to delay validation until the user has stopped typing.
  *
- * @param validator - The async validator function to debounce.
- * @param delay - The debounce delay in milliseconds.
- * @returns A debounced version of the validator function.
+ * @param validator - The asynchronous validator function to be debounced. It receives the value to validate and a `debounce` function.
+ * @param {number} delay - The debounce delay in milliseconds.
+ * @returns A new function that takes a value and returns a promise that resolves or rejects based on the debounced validation.
  */
 function debounceAsyncValidator(validator, delay) {
     let currentPromiseReject = null;
@@ -2248,10 +2785,13 @@ function debounceAsyncValidator(validator, delay) {
     };
 }
 /**
- * Creates a debounced version of an asynchronous function.
- * @param {Function} func The asynchronous function to debounce.
- * @param {number} wait The number of milliseconds to wait before invoking the function.
- * @returns {Function} The debounced function.
+ * Creates a debounced version of an asynchronous function. The debounced function will only
+ * resolve the promise of the last invocation within the `wait` period.
+ *
+ * @template T - The type of the asynchronous function.
+ * @param {T} func - The asynchronous function to debounce.
+ * @param {number} wait - The debounce delay in milliseconds.
+ * @returns A new debounced asynchronous function.
  */
 function debounceAsync(func, wait) {
     let timeoutReject = null;
@@ -2270,10 +2810,13 @@ function debounceAsync(func, wait) {
     };
 }
 /**
- * Creates a debounced asynchronous function that executes immediately on the first call.
- * @param {Function} func The asynchronous function to debounce.
- * @param {number} wait The number of milliseconds to wait before invoking the function.
- * @returns {Function} The debounced function with immediate execution on the first call.
+ * Creates a debounced version of an asynchronous function that executes immediately on the first call
+ * and then waits for the specified delay before allowing the next execution.
+ *
+ * @template T - The type of the asynchronous function.
+ * @param {T} func - The asynchronous function to debounce.
+ * @param {number} wait - The cooldown period in milliseconds after an immediate execution.
+ * @returns A new debounced asynchronous function that executes on the leading edge.
  */
 function debounceAsyncWithImmediate(func, wait) {
     let timeoutReject = null;
@@ -2305,10 +2848,13 @@ function debounceAsyncWithImmediate(func, wait) {
     };
 }
 /**
- * Creates a debounced version of a function that executes on the leading edge.
- * @param {Function} func The function to debounce.
- * @param {number} wait The number of milliseconds to wait before invoking the function.
- * @returns {Function} The debounced function.
+ * Creates a debounced function that invokes `func` on the leading edge of the `wait` timeout.
+ * Subsequent calls within the `wait` period are ignored.
+ *
+ * @template T - The type of the function.
+ * @param {T} func - The function to debounce.
+ * @param {number} wait - The debounce delay in milliseconds.
+ * @returns A new debounced function.
  */
 function debounceLeading(func, wait) {
     let timeoutReject = null;
@@ -2329,10 +2875,13 @@ function debounceLeading(func, wait) {
     };
 }
 /**
- * Creates a debounced version of a function that executes on the trailing edge.
- * @param {Function} func The function to debounce.
- * @param {number} wait The number of milliseconds to wait before invoking the function.
- * @returns {Function} The debounced function.
+ * Creates a debounced function that invokes `func` on the trailing edge of the `wait` timeout.
+ * The function is called only after `wait` milliseconds of inactivity.
+ *
+ * @template T - The type of the function.
+ * @param {T} func - The function to debounce.
+ * @param {number} wait - The debounce delay in milliseconds.
+ * @returns A new debounced function.
  */
 function debounceTrailing(func, wait) {
     let timeoutReject = null;
@@ -2350,10 +2899,13 @@ function debounceTrailing(func, wait) {
     };
 }
 /**
- * Creates a debounced version of a function that executes on both leading and trailing edges.
- * @param {Function} func The function to debounce.
- * @param {number} wait The number of milliseconds to wait before invoking the function.
- * @returns {Function} The debounced function.
+ * Creates a debounced function that invokes `func` on both the leading and trailing edges of the `wait` timeout.
+ * This is useful for UIs where an action should happen immediately on the first event, but also after a pause in events.
+ *
+ * @template T - The type of the function.
+ * @param {T} func - The function to debounce.
+ * @param {number} wait - The debounce delay in milliseconds.
+ * @returns A new debounced function.
  */
 function debounceLeadingTrailing(func, wait) {
     let timeoutReject = null;
@@ -2379,10 +2931,13 @@ function debounceLeadingTrailing(func, wait) {
     };
 }
 /**
- * Creates a debounced version of a function.
- * @param {Function} func The function to debounce.
- * @param {number} wait The number of milliseconds to wait before invoking the function.
- * @returns {Function} The debounced function.
+ * Creates a standard debounced function that delays invoking `func` until after `wait` milliseconds
+ * have elapsed since the last time the debounced function was invoked. (This is an alias for `debounceTrailing`).
+ *
+ * @template T - The type of the function.
+ * @param {T} func - The function to debounce.
+ * @param {number} wait - The debounce delay in milliseconds.
+ * @returns A new debounced function.
  */
 function debounce(func, wait) {
     let timeoutReject = null;
@@ -2399,10 +2954,13 @@ function debounce(func, wait) {
     };
 }
 /**
- * Creates a throttled version of a function.
- * @param {Function} func The function to throttle.
- * @param {number} limit The number of milliseconds to wait between function calls.
- * @returns {Function} The throttled function.
+ * Creates a throttled function that only invokes `func` at most once per every `limit` milliseconds.
+ * This is useful for rate-limiting events that fire frequently, such as scrolling or resizing.
+ *
+ * @template T - The type of the function.
+ * @param {T} func - The function to throttle.
+ * @param {number} limit - The throttle duration in milliseconds.
+ * @returns A new throttled function.
  */
 function throttle(func, limit) {
     let lastCall = 0;
@@ -2416,9 +2974,11 @@ function throttle(func, limit) {
 }
 
 /**
- * Converts a FormData object to a plain JavaScript object.
- * @param {FormData} formData The FormData object to convert.
- * @returns {Record<string, any>} The plain JavaScript object.
+ * Converts a `FormData` object into a regular JavaScript object. It correctly handles
+ * multiple values for the same key by creating an array for that key.
+ *
+ * @param {FormData} formData - The `FormData` object to convert.
+ * @returns {Record<string, any>} A plain JavaScript object representation of the FormData.
  */
 function formDataToObject(formData) {
     const obj = {};
@@ -2437,9 +2997,10 @@ function formDataToObject(formData) {
     return obj;
 }
 /**
- * Reads a file as text.
- * @param {File} file The file to read.
- * @returns {Promise<string>} A promise that resolves with the file content.
+ * Asynchronously reads the content of a `File` object as a text string.
+ *
+ * @param {File} file - The `File` object to read.
+ * @returns {Promise<string>} A promise that resolves with the text content of the file.
  */
 function readFileAsText(file) {
     return new Promise((resolve, reject) => {
@@ -2450,9 +3011,10 @@ function readFileAsText(file) {
     });
 }
 /**
- * Reads a file as a Data URL.
- * @param {File} file The file to read.
- * @returns {Promise<string>} A promise that resolves with the Data URL.
+ * Asynchronously reads the content of a `File` object as a Base64-encoded Data URL.
+ *
+ * @param {File} file - The `File` object to read.
+ * @returns {Promise<string>} A promise that resolves with the Data URL representing the file's content.
  */
 function readFileAsDataURL(file) {
     return new Promise((resolve, reject) => {
@@ -2463,27 +3025,30 @@ function readFileAsDataURL(file) {
     });
 }
 /**
- * Creates a Blob from a string.
- * @param {string} content The string content for the Blob.
- * @param {string} [type='text/plain'] The MIME type of the Blob.
- * @returns {Blob} The Blob object.
+ * Creates a `Blob` object from a string.
+ *
+ * @param {string} content - The string content to be put into the Blob.
+ * @param {string} [type='text/plain'] - The MIME type of the Blob.
+ * @returns {Blob} A new `Blob` object.
  */
 function stringToBlob(content, type = 'text/plain') {
     return new Blob([content], { type });
 }
 /**
- * Creates a Blob from an ArrayBuffer.
- * @param {ArrayBuffer} buffer The ArrayBuffer to convert.
- * @param {string} [type='application/octet-stream'] The MIME type of the Blob.
- * @returns {Blob} The Blob object.
+ * Creates a `Blob` object from an `ArrayBuffer`.
+ *
+ * @param {ArrayBuffer} buffer - The `ArrayBuffer` to be put into the Blob.
+ * @param {string} [type='application/octet-stream'] - The MIME type of the Blob.
+ * @returns {Blob} A new `Blob` object.
  */
 function bufferToBlob(buffer, type = 'application/octet-stream') {
     return new Blob([buffer], { type });
 }
 /**
- * Creates and downloads a file from Blob data.
- * @param {Blob} blob The Blob containing the file data.
- * @param {string} fileName The name of the file to create.
+ * Triggers a browser download for a file created from a `Blob` object.
+ *
+ * @param {Blob} blob - The `Blob` containing the file data.
+ * @param {string} fileName - The desired name for the downloaded file.
  */
 function downloadBlob(blob, fileName) {
     const link = document.createElement('a');
@@ -2498,11 +3063,12 @@ function downloadBlob(blob, fileName) {
     URL.revokeObjectURL(url);
 }
 /**
- * Creates a FormData object containing a Blob.
- * @param {Blob} blob The Blob to include in the FormData.
- * @param {string} name The name of the form field.
- * @param {string} [fileName='file'] The file name for the Blob.
- * @returns {FormData} The FormData object.
+ * Appends a `Blob` to a new `FormData` object.
+ *
+ * @param {Blob} blob - The `Blob` to append.
+ * @param {string} name - The name of the field to append the blob as.
+ * @param {string} [fileName='file'] - The filename to associate with the blob in the `FormData`.
+ * @returns {FormData} A new `FormData` object containing the blob.
  */
 function blobToFormData(blob, name, fileName = 'file') {
     const formData = new FormData();
@@ -2511,9 +3077,10 @@ function blobToFormData(blob, name, fileName = 'file') {
 }
 
 /**
- * Capitalizes the first character of a string.
- * @param {string} s The string to capitalize.
- * @returns {string} The capitalized string.
+ * Capitalizes the first letter of a string.
+ *
+ * @param {string} s - The input string.
+ * @returns {string} The string with the first letter capitalized.
  */
 function upperFirst(s) {
     return s.charAt(0).toUpperCase() + s.slice(1);
@@ -2521,9 +3088,10 @@ function upperFirst(s) {
 // Example usage:
 // console.log(upperFirst('hello')); // 'Hello'
 /**
- * Lowercases the first character of a string.
- * @param {string} s The string to lowercase.
- * @returns {string} The lowercased string.
+ * Converts the first letter of a string to lowercase.
+ *
+ * @param {string} s - The input string.
+ * @returns {string} The string with the first letter in lowercase.
  */
 function lowerFirst(s) {
     return s.charAt(0).toLowerCase() + s.slice(1);
@@ -2531,9 +3099,11 @@ function lowerFirst(s) {
 // Example usage:
 // console.log(lowerFirst('Hello')); // 'hello'
 /**
- * Removes accents and special characters from a string and converts it to a URL-friendly format.
- * @param {string} input The string to process.
- * @returns {string} The processed string.
+ * Normalizes a string by converting it to lowercase, trimming whitespace, replacing spaces with hyphens,
+ * and removing diacritical marks (accents).
+ *
+ * @param {string} input - The string to normalize.
+ * @returns {string} The URL-friendly, normalized string.
  */
 function removeAccent(input) {
     return input
@@ -2547,8 +3117,9 @@ function removeAccent(input) {
 // Example usage:
 // console.log(removeAccent('Café du Nord')); // 'cafe-du-nord'
 /**
- * Reverses a string.
- * @param {string} str The string to reverse.
+ * Reverses the characters of a string.
+ *
+ * @param {string} str - The input string.
  * @returns {string} The reversed string.
  */
 function reverseString(str) {
@@ -2557,9 +3128,10 @@ function reverseString(str) {
 // Example usage:
 // console.log(reverseString('hello')); // 'olleh'
 /**
- * Counts the number of words in a string.
- * @param {string} str The string to analyze.
- * @returns {number} The word count.
+ * Counts the number of words in a string, based on whitespace separation.
+ *
+ * @param {string} str - The input string.
+ * @returns {number} The number of words in the string.
  */
 function countWords(str) {
     return str.trim().split(/\s+/).length;
@@ -2567,9 +3139,10 @@ function countWords(str) {
 // Example usage:
 // console.log(countWords('Hello world!')); // 2
 /**
- * Truncates a string to the specified length and adds ellipsis if necessary.
- * @param {string} str The string to truncate.
- * @param {number} maxLength The maximum length of the string.
+ * Truncates a string to a specified maximum length, appending '...' if the string is cut.
+ *
+ * @param {string} str - The input string.
+ * @param {number} maxLength - The maximum desired length of the string.
  * @returns {string} The truncated string.
  */
 function truncateString(str, maxLength) {
@@ -2578,9 +3151,10 @@ function truncateString(str, maxLength) {
 // Example usage:
 // console.log(truncateString('This is a long string', 10)); // 'This is a...'
 /**
- * Converts a string to camel case.
- * @param {string} str The string to convert.
- * @returns {string} The camel cased string.
+ * Converts a string from various cases (e.g., snake_case, kebab-case, space separated) into camelCase.
+ *
+ * @param {string} str - The input string.
+ * @returns {string} The camelCase version of the string.
  */
 function toCamelCase(str) {
     return str
@@ -2590,9 +3164,10 @@ function toCamelCase(str) {
 // Example usage:
 // console.log(toCamelCase('hello world example')); // 'helloWorldExample'
 /**
- * Converts a string to kebab case.
- * @param {string} str The string to convert.
- * @returns {string} The kebab cased string.
+ * Converts a string from various cases (e.g., camelCase, PascalCase, space separated) into kebab-case.
+ *
+ * @param {string} str - The input string.
+ * @returns {string} The kebab-case version of the string.
  */
 function toKebabCase(str) {
     return str
@@ -2603,11 +3178,12 @@ function toKebabCase(str) {
 // Example usage:
 // console.log(toKebabCase('Hello World Example')); // 'hello-world-example'
 /**
- * Replaces all instances of a substring within a string.
- * @param {string} str The original string.
- * @param {string} find The substring to find.
- * @param {string} replace The substring to replace with.
- * @returns {string} The modified string.
+ * Replaces all occurrences of a substring with a new substring.
+ *
+ * @param {string} str - The original string.
+ * @param {string} find - The substring to find and replace.
+ * @param {string} replace - The substring to replace with.
+ * @returns {string} A new string with all replacements made.
  */
 function replaceAll(str, find, replace) {
     return str.split(find).join(replace);
@@ -2615,9 +3191,10 @@ function replaceAll(str, find, replace) {
 // Example usage:
 // console.log(replaceAll('hello world', 'o', 'a')); // 'hella warld'
 /**
- * Generates a random string of a specific length.
- * @param {number} length The length of the string to generate.
- * @returns {string} The random string.
+ * Generates a random alphanumeric string of a specified length.
+ *
+ * @param {number} length - The desired length of the random string.
+ * @returns {string} The generated random string.
  */
 function generateRandomString(length) {
     const characters = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
@@ -2627,9 +3204,10 @@ function generateRandomString(length) {
 // console.log(generateRandomString(10)); // 'A1b2C3d4E5'
 
 /**
- * Validates if the key pressed is a valid letter or special character.
- * @param {KeyboardEvent} e The keyboard event.
- * @returns {boolean} True if the key is valid, otherwise false.
+ * An event handler that prevents a `KeyboardEvent`'s default action if the key pressed is not a letter or a specific special character.
+ *
+ * @param {KeyboardEvent} e - The `KeyboardEvent` object.
+ * @returns {boolean} `true` if the key is valid, `false` otherwise.
  */
 function validateLetters(e) {
     const key = e.keyCode;
@@ -2660,9 +3238,10 @@ function validateLetters(e) {
 // Example usage:
 // document.addEventListener('keydown', validateLetters);
 /**
- * Validates if the key pressed is a valid alphanumeric character.
- * @param {KeyboardEvent} e The keyboard event.
- * @returns {boolean} True if the key is valid, otherwise false.
+ * An event handler that prevents a `KeyboardEvent`'s default action if the key pressed is not an alphanumeric character.
+ *
+ * @param {KeyboardEvent} e - The `KeyboardEvent` object.
+ * @returns {boolean} `true` if the key is valid, `false` otherwise.
  */
 function validateAlphanumeric(e) {
     const key = e.keyCode;
@@ -2683,9 +3262,10 @@ function validateAlphanumeric(e) {
 // Example usage:
 // document.addEventListener('keydown', validateAlphanumeric);
 /**
- * Validates if the key pressed is a number.
- * @param {KeyboardEvent} e The keyboard event.
- * @returns {boolean} True if the key is a number, otherwise false.
+ * An event handler that prevents a `KeyboardEvent`'s default action if the key pressed is not a number.
+ *
+ * @param {KeyboardEvent} e - The `KeyboardEvent` object.
+ * @returns {boolean} `true` if the key is a number, otherwise `false`.
  */
 function validateNumbers(e) {
     const key = e.keyCode;
@@ -2698,9 +3278,10 @@ function validateNumbers(e) {
 // Example usage:
 // document.addEventListener('keydown', validateNumbers);
 /**
- * Validates if a phone number is valid.
- * @param {string} phoneNumber The phone number to validate.
- * @returns {boolean} True if the phone number is valid, otherwise false.
+ * Validates a phone number against a regex for 10-digit numbers.
+ *
+ * @param {string} phoneNumber - The phone number to validate.
+ * @returns {boolean} `true` if the phone number is valid, otherwise `false`.
  */
 function isValidPhoneNumber(phoneNumber) {
     const phonePattern = /^[0-9]{10}$/; // Example pattern for 10-digit phone numbers
@@ -2710,9 +3291,10 @@ function isValidPhoneNumber(phoneNumber) {
 // console.log(isValidPhoneNumber('1234567890')); // true
 // console.log(isValidPhoneNumber('123-456-7890')); // false
 /**
- * Validates if a string is a valid email address.
- * @param {string} email The email address to validate.
- * @returns {boolean} True if the email address is valid, otherwise false.
+ * Validates an email address against a standard regex pattern.
+ *
+ * @param {string} email - The email address to validate.
+ * @returns {boolean} `true` if the email is valid, otherwise `false`.
  */
 function isValidEmail(email) {
     const emailPattern = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
@@ -2722,9 +3304,10 @@ function isValidEmail(email) {
 // console.log(isValidEmail('example@domain.com')); // true
 // console.log(isValidEmail('invalid-email')); // false
 /**
- * Validates if a string is a valid URL.
- * @param {string} url The URL to validate.
- * @returns {boolean} True if the URL is valid, otherwise false.
+ * Validates a string to see if it is a well-formed URL.
+ *
+ * @param {string} url - The URL string to validate.
+ * @returns {boolean} `true` if the URL is valid, otherwise `false`.
  */
 function isValidURL(url) {
     try {
@@ -2739,9 +3322,10 @@ function isValidURL(url) {
 // console.log(isValidURL('https://www.example.com')); // true
 // console.log(isValidURL('invalid-url')); // false
 /**
- * Validates if a string is a valid date in YYYY-MM-DD format.
- * @param {string} date The date string to validate.
- * @returns {boolean} True if the date is valid, otherwise false.
+ * Validates a string to ensure it is a valid date in 'YYYY-MM-DD' format.
+ *
+ * @param {string} date - The date string to validate.
+ * @returns {boolean} `true` if the date is valid, otherwise `false`.
  */
 function isValidDate(date) {
     const datePattern = /^\d{4}-\d{2}-\d{2}$/;
@@ -2755,9 +3339,10 @@ function isValidDate(date) {
 // console.log(isValidDate('2024-08-31')); // true
 // console.log(isValidDate('2024-02-30')); // false
 /**
- * Validates if a password meets certain strength criteria.
- * @param {string} password The password to validate.
- * @returns {boolean} True if the password is strong, otherwise false.
+ * Checks if a password meets a set of strength requirements (minimum length, uppercase, lowercase, numbers, special characters).
+ *
+ * @param {string} password - The password to validate.
+ * @returns {boolean} `true` if the password is strong, otherwise `false`.
  */
 function isStrongPassword(password) {
     const minLength = 8;
@@ -2771,9 +3356,10 @@ function isStrongPassword(password) {
 // console.log(isStrongPassword('Strong1@password')); // true
 // console.log(isStrongPassword('weakpass')); // false
 /**
- * Validates a credit card number using the Luhn algorithm.
- * @param {string} cardNumber The credit card number to validate.
- * @returns {boolean} True if the credit card number is valid, otherwise false.
+ * Validates a credit card number using the Luhn algorithm (mod-10 check).
+ *
+ * @param {string} cardNumber - The credit card number to validate.
+ * @returns {boolean} `true` if the credit card number is valid, otherwise `false`.
  */
 function isValidCreditCard(cardNumber) {
     const sanitized = cardNumber.replace(/\D/g, '');
@@ -2795,9 +3381,10 @@ function isValidCreditCard(cardNumber) {
 // console.log(isValidCreditCard('4111111111111111')); // true
 // console.log(isValidCreditCard('1234567812345670')); // false
 /**
- * Validates if a string is a valid hex color code.
- * @param {string} color The color code to validate.
- * @returns {boolean} True if the color code is valid, otherwise false.
+ * Validates a string to check if it's a valid 3- or 6-digit hexadecimal color code.
+ *
+ * @param {string} color - The hex color string to validate.
+ * @returns {boolean} `true` if the color code is valid, otherwise `false`.
  */
 function isValidHexColor(color) {
     const hexPattern = /^#([0-9A-Fa-f]{6}|[0-9A-Fa-f]{3})$/;
@@ -2808,9 +3395,10 @@ function isValidHexColor(color) {
 // console.log(isValidHexColor('#FFF')); // true
 // console.log(isValidHexColor('#12345G')); // false
 /**
- * Validates if a string is a valid time in HH:MM format.
- * @param {string} time The time string to validate.
- * @returns {boolean} True if the time is valid, otherwise false.
+ * Validates a string to ensure it represents a valid time in 24-hour HH:MM format.
+ *
+ * @param {string} time - The time string to validate.
+ * @returns {boolean} `true` if the time is valid, otherwise `false`.
  */
 function isValidTime(time) {
     const timePattern = /^([01]\d|2[0-3]):([0-5]\d)$/;
@@ -2820,9 +3408,10 @@ function isValidTime(time) {
 // console.log(isValidTime('14:30')); // true
 // console.log(isValidTime('25:00')); // false
 /**
- * Validates if a string is a valid IPv4 address.
- * @param {string} ip The IP address to validate.
- * @returns {boolean} True if the IP address is valid, otherwise false.
+ * Validates a string to check if it is a valid IPv4 address.
+ *
+ * @param {string} ip - The IP address string to validate.
+ * @returns {boolean} `true` if the IP address is valid, otherwise `false`.
  */
 function isValidIP(ip) {
     const ipPattern = /^(25[0-5]|2[0-4][0-9]|[0-1]?[0-9][0-9]?)\.(25[0-5]|2[0-4][0-9]|[0-1]?[0-9][0-9]?)\.(25[0-5]|2[0-4][0-9]|[0-1]?[0-9][0-9]?)\.(25[0-5]|2[0-4][0-9]|[0-1]?[0-9][0-9]?)$/;
@@ -2832,9 +3421,10 @@ function isValidIP(ip) {
 // console.log(isValidIP('192.168.1.1')); // true
 // console.log(isValidIP('999.999.999.999')); // false
 /**
- * Validates if a string is a valid U.S. Social Security Number (SSN).
- * @param {string} ssn The SSN to validate.
- * @returns {boolean} True if the SSN is valid, otherwise false.
+ * Validates a string to check if it matches the format of a U.S. Social Security Number (SSN).
+ *
+ * @param {string} ssn - The SSN string to validate.
+ * @returns {boolean} `true` if the SSN format is valid, otherwise `false`.
  */
 function isValidSSN(ssn) {
     const ssnPattern = /^\d{3}-\d{2}-\d{4}$/;
@@ -2844,9 +3434,10 @@ function isValidSSN(ssn) {
 // console.log(isValidSSN('123-45-6789')); // true
 // console.log(isValidSSN('123-45-678')); // false
 /**
- * Validates if a string is a valid U.S. ZIP code.
- * @param {string} zip The ZIP code to validate.
- * @returns {boolean} True if the ZIP code is valid, otherwise false.
+ * Validates a string to check if it is a valid 5-digit or 9-digit (ZIP+4) U.S. ZIP code.
+ *
+ * @param {string} zip - The ZIP code string to validate.
+ * @returns {boolean} `true` if the ZIP code is valid, otherwise `false`.
  */
 function isValidZIP(zip) {
     const zipPattern = /^\d{5}(-\d{4})?$/;
@@ -2857,9 +3448,10 @@ function isValidZIP(zip) {
 // console.log(isValidZIP('12345-6789')); // true
 // console.log(isValidZIP('1234')); // false
 /**
- * Validates if a string is a valid credit card expiry date in MM/YY format.
- * @param {string} expiryDate The expiry date to validate.
- * @returns {boolean} True if the expiry date is valid, otherwise false.
+ * Validates a credit card expiry date string (MM/YY format) to ensure it is a valid, non-expired date.
+ *
+ * @param {string} expiryDate - The expiry date to validate.
+ * @returns {boolean} `true` if the expiry date is valid and not in the past, otherwise `false`.
  */
 function isValidExpiryDate(expiryDate) {
     const expiryPattern = /^(0[1-9]|1[0-2])\/\d{2}$/;
@@ -2874,9 +3466,10 @@ function isValidExpiryDate(expiryDate) {
 // console.log(isValidExpiryDate('08/24')); // true
 // console.log(isValidExpiryDate('12/22')); // false
 /**
- * Validates if a string is a valid 8-character hexadecimal color code (including alpha).
- * @param {string} color The color code to validate.
- * @returns {boolean} True if the color code is valid, otherwise false.
+ * Validates a string to check if it's a valid 8-digit hexadecimal color code (with alpha channel).
+ *
+ * @param {string} color - The hex color string to validate.
+ * @returns {boolean} `true` if the color code is valid, otherwise `false`.
  */
 function isValidHexColorAlpha(color) {
     const hexPattern = /^#([0-9A-Fa-f]{8})$/;
@@ -2886,9 +3479,10 @@ function isValidHexColorAlpha(color) {
 // console.log(isValidHexColorAlpha('#RRGGBBAA')); // true
 // console.log(isValidHexColorAlpha('#FFFFFF')); // false
 /**
- * Validates if a username meets specific criteria.
- * @param {string} username The username to validate.
- * @returns {boolean} True if the username is valid, otherwise false.
+ * Validates a username to ensure it contains only alphanumeric characters and underscores, with a length between 3 and 16 characters.
+ *
+ * @param {string} username - The username to validate.
+ * @returns {boolean} `true` if the username is valid, otherwise `false`.
  */
 function isValidUsername(username) {
     const usernamePattern = /^[a-zA-Z0-9_]{3,16}$/; // 3 to 16 characters, letters, numbers, and underscores only
@@ -2898,9 +3492,10 @@ function isValidUsername(username) {
 // console.log(isValidUsername('user_name123')); // true
 // console.log(isValidUsername('us')); // false
 /**
- * Validates if a string represents a valid age between 0 and 120.
- * @param {string} age The age to validate.
- * @returns {boolean} True if the age is valid, otherwise false.
+ * Validates a string to ensure it represents a plausible human age (0-120).
+ *
+ * @param {string} age - The age string to validate.
+ * @returns {boolean} `true` if the age is valid, otherwise `false`.
  */
 function isValidAge(age) {
     const ageNumber = parseInt(age, 10);
@@ -2910,9 +3505,10 @@ function isValidAge(age) {
 // console.log(isValidAge('25')); // true
 // console.log(isValidAge('121')); // false
 /**
- * Validates if a string is a valid hexadecimal number.
- * @param {string} hex The hexadecimal number to validate.
- * @returns {boolean} True if the number is valid, otherwise false.
+ * Validates a string to check if it contains only valid hexadecimal characters.
+ *
+ * @param {string} hex - The string to validate.
+ * @returns {boolean} `true` if the string is a valid hexadecimal number, otherwise `false`.
  */
 function isValidHexNumber(hex) {
     const hexPattern = /^[0-9A-Fa-f]+$/;
@@ -2922,73 +3518,211 @@ function isValidHexNumber(hex) {
 // console.log(isValidHexNumber('1A3F')); // true
 // console.log(isValidHexNumber('GHIJ')); // false
 
+const DEFAULT_RETRY_CONFIG = {
+    retries: 3,
+    retryDelay: 1000,
+    maxRetryDelay: 10000,
+    backoffMultiplier: 2,
+    retryCondition: (error) => {
+        if (error instanceof NetworkError || error instanceof ServerError) {
+            const statusCode = error.statusCode;
+            if (!statusCode)
+                return true;
+            if (statusCode >= 500)
+                return true;
+            if (statusCode === 408 || statusCode === 429)
+                return true;
+            return false;
+        }
+        if (error instanceof Error) {
+            return error.message.includes('timeout') || error.message.includes('network');
+        }
+        return false;
+    },
+};
+async function retryWithBackoff(fn, config = {}) {
+    const finalConfig = { ...DEFAULT_RETRY_CONFIG, ...config };
+    let lastError;
+    let delay = finalConfig.retryDelay;
+    for (let attempt = 0; attempt <= finalConfig.retries; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            lastError = error;
+            if (attempt === finalConfig.retries) {
+                break;
+            }
+            if (!finalConfig.retryCondition(error)) {
+                throw error;
+            }
+            await new Promise((resolve) => setTimeout(resolve, delay));
+            delay = Math.min(delay * finalConfig.backoffMultiplier, finalConfig.maxRetryDelay);
+        }
+    }
+    throw lastError;
+}
+
+/**
+ * A standardized RESTful class that provides a generic interface for performing
+ * CRUD (Create, Read, Update, Delete) operations on a specific API resource. It is designed
+ * to be extended directly from your models. It supports both JSON and FormData requests.
+ *
+ * @example
+ * ```typescript
+ * export class Role extends RestStd {
+ *     static override resource = 'roles';
+ *     static fetchFn = createAxiosFetcher(axiosInstance);
+ * }
+ *
+ * const roles = await Role.getAll();
+ * ```
+ */
 class RestStd {
+    /**
+     * The resource endpoint. MUST be overridden in subclasses.
+     * @example static override resource = 'users';
+     */
     static resource;
+    /** A flag to determine if request data should be sent as FormData. Defaults to `false`. */
     static isFormData = false;
+    /** A record of global headers to be sent with every request. */
     static headers = {};
+    /** The function used to make the actual HTTP requests. Optional, defaults to Axios fetcher. */
     static fetchFn;
+    /** Retry configuration for failed requests. Optional. */
+    static retryConfig;
     /**
-     * Set global headers for all requests.
-     * @param headers Object containing headers to be set globally.
+     * Validates that the resource property is defined.
+     * @throws {Error} If resource is not defined
+     */
+    static validateResource() {
+        if (!this.resource || this.resource.trim() === '') {
+            throw new Error(`[${this.constructor.name}] Static property 'resource' is required. ` +
+                `Please define: static override resource = 'your-resource';`);
+        }
+    }
+    /**
+     * Gets the fetcher function, using default if not provided.
+     * Creates a default Axios fetcher if not configured, allowing lazy initialization.
+     * @returns The fetcher function to use
+     */
+    static getFetchFn() {
+        if (this.fetchFn) {
+            return this.fetchFn;
+        }
+        const axiosInstance = getConfiguredAxiosInstance();
+        return createAxiosFetcher(axiosInstance);
+    }
+    /**
+     * Executes a fetch request with optional retry logic.
+     * @param config - The fetcher configuration
+     * @returns A promise that resolves with the response data
+     */
+    static async executeFetch(config) {
+        const fetcher = this.getFetchFn();
+        if (this.retryConfig) {
+            return retryWithBackoff(() => fetcher(config), this.retryConfig);
+        }
+        try {
+            return await fetcher(config);
+        }
+        catch (error) {
+            if (error && typeof error === 'object' && 'response' in error) {
+                throw NetworkError.fromAxiosError(error);
+            }
+            if (error instanceof Error && error.name === 'TypeError' && error.message?.includes('fetch')) {
+                throw NetworkError.fromFetchError(error);
+            }
+            throw error;
+        }
+    }
+    /**
+     * Builds a URL by combining base URL and suffix.
+     * @param baseUrl - The base URL
+     * @param suffix - Optional suffix to append
+     * @returns The combined URL
+     */
+    static buildUrl(baseUrl, suffix) {
+        const cleanBase = baseUrl.replace(/\/$/, '');
+        if (suffix) {
+            const cleanSuffix = suffix.startsWith('/') ? suffix : `/${suffix}`;
+            return cleanBase + cleanSuffix;
+        }
+        return cleanBase;
+    }
+    /**
+     * Sets global headers that will be included in all subsequent requests made by this class.
+     * @param headers - An object containing the headers to be set
      */
     static setHeaders(headers) {
         this.headers = { ...this.headers, ...headers };
     }
     /**
-     * Convert data to FormData if isFormData is true, otherwise return the data as is.
-     * @param data Data to be converted.
-     * @returns Data in FormData format or as is.
+     * Conditionally transforms the request data to FormData if `isFormData` is true.
+     * @param data - The data to be potentially transformed
+     * @returns The transformed data as FormData, or the original data
      */
     static transformData(data) {
         if (this.isFormData) {
-            const formData = objectToFormData(data);
-            return formData;
+            return objectToFormData(data);
         }
         return data;
     }
     /**
-     * Fetch a list of items from the server.
-     *
-     * @param params Query parameters for filtering the results.
-     * @param options Additional options for the fetch function.
-     * @returns The result of the fetch function (typically a promise).
+     * Fetches a list of items from the resource's endpoint.
+     * @template TResponse The expected response type
+     * @template TParams The type of query parameters
+     * @param options - Options including params, options, and optional url override
+     * @returns A promise that resolves with the response data
      */
-    static getAll(params, options = {}) {
-        return this.fetchFn({
+    static getAll(options = {}) {
+        this.validateResource();
+        const { params, url } = options;
+        const finalUrl = url || this.resource;
+        const config = {
             method: "GET",
-            url: this.resource,
+            url: finalUrl,
             params,
             headers: this.headers,
-        }, options);
+        };
+        return this.executeFetch(config);
     }
     /**
-     * Fetch a single item by ID from the server.
-     *
-     * @param id The ID of the item to fetch.
-     * @param params Additional query parameters for the request.
-     * @param options Additional options for the fetch function.
-     * @returns The result of the fetch function (typically a promise).
+     * Fetches a single item by its ID.
+     * @template TResponse The expected response type
+     * @template TParams The type of query parameters
+     * @param options - Options including id, params, options, and optional url override
+     * @returns A promise that resolves with the response data
      */
-    static getOne(id, params, options = {}) {
-        return this.fetchFn({
+    static getOne(options) {
+        this.validateResource();
+        const { id, params, url } = options;
+        const baseUrl = url || this.resource;
+        const finalUrl = this.buildUrl(baseUrl, String(id));
+        const config = {
             method: "GET",
-            url: `${this.resource}/${id}`,
+            url: finalUrl,
             params,
             headers: this.headers,
-        }, options);
+        };
+        return this.executeFetch(config);
     }
     /**
-     * Create a new item on the server.
-     *
-     * @param data The data for the new item to create.
-     * @param options Additional options for the fetch function.
-     * @returns The result of the fetch function (typically a promise).
+     * Creates a new item.
+     * @template TResponse The expected response type
+     * @template TData The type of data to send
+     * @param options - Options including data, options, and optional url override
+     * @returns A promise that resolves with the response data
      */
-    static create(data, options = {}) {
+    static create(options) {
+        this.validateResource();
+        const { data, url } = options;
+        const finalUrl = url || this.resource;
         const transformedData = this.transformData(data);
-        return this.fetchFn({
+        const config = {
             method: "POST",
-            url: this.resource,
+            url: finalUrl,
             data: transformedData,
             headers: {
                 ...this.headers,
@@ -2996,22 +3730,27 @@ class RestStd {
                     ? ContentTypeEnum.FORM_DATA
                     : ContentTypeEnum.JSON,
             },
-        }, options);
+        };
+        return this.executeFetch(config);
     }
     /**
-     * Create multiple new items on the server.
-     *
-     * @param data An array of data for the items to create.
-     * @param options Additional options for the fetch function.
-     * @returns The result of the fetch function.
+     * Creates multiple new items in a single request.
+     * @template TResponse The expected response type
+     * @template TData The type of data items to send
+     * @param options - Options including data array, options, and optional url override
+     * @returns A promise that resolves with the response data
      */
-    static bulkCreate(data, options = {}) {
+    static bulkCreate(options) {
+        this.validateResource();
+        const { data, url } = options;
+        const baseUrl = url || this.resource;
+        const finalUrl = this.buildUrl(baseUrl, 'bulk');
         const transformedData = this.isFormData
             ? data.map((item) => this.transformData(item))
             : data;
-        return this.fetchFn({
+        const config = {
             method: "POST",
-            url: `${this.resource}/bulk`,
+            url: finalUrl,
             data: transformedData,
             headers: {
                 ...this.headers,
@@ -3019,21 +3758,25 @@ class RestStd {
                     ? ContentTypeEnum.FORM_DATA
                     : ContentTypeEnum.JSON,
             },
-        }, options);
+        };
+        return this.executeFetch(config);
     }
     /**
-     * Update an existing item on the server.
-     *
-     * @param id The ID of the item to update.
-     * @param data The updated data for the item.
-     * @param options Additional options for the fetch function.
-     * @returns The result of the fetch function (typically a promise).
+     * Updates an existing item by its ID.
+     * @template TResponse The expected response type
+     * @template TData The type of data to send
+     * @param options - Options including id, data, options, and optional url override
+     * @returns A promise that resolves with the response data
      */
-    static update(id, data, options = {}) {
+    static update(options) {
+        this.validateResource();
+        const { id, data, url } = options;
+        const baseUrl = url || this.resource;
+        const finalUrl = this.buildUrl(baseUrl, String(id));
         const transformedData = this.transformData(data);
-        return this.fetchFn({
+        const config = {
             method: "PUT",
-            url: `${this.resource}/${id}`,
+            url: finalUrl,
             data: transformedData,
             headers: {
                 ...this.headers,
@@ -3041,22 +3784,27 @@ class RestStd {
                     ? ContentTypeEnum.FORM_DATA
                     : ContentTypeEnum.JSON,
             },
-        }, options);
+        };
+        return this.executeFetch(config);
     }
     /**
-     * Update multiple existing items on the server.
-     *
-     * @param data An array of data for the items to update (each object should have an ID).
-     * @param options Additional options for the fetch function.
-     * @returns The result of the fetch function.
+     * Updates multiple existing items in a single request.
+     * @template TResponse The expected response type
+     * @template TData The type of data items to send
+     * @param options - Options including data array, options, and optional url override
+     * @returns A promise that resolves with the response data
      */
-    static bulkUpdate(data, options = {}) {
+    static bulkUpdate(options) {
+        this.validateResource();
+        const { data, url } = options;
+        const baseUrl = url || this.resource;
+        const finalUrl = this.buildUrl(baseUrl, 'bulk');
         const transformedData = this.isFormData
             ? data.map((item) => this.transformData(item))
             : data;
-        return this.fetchFn({
+        const config = {
             method: "PUT",
-            url: `${this.resource}/bulk`,
+            url: finalUrl,
             data: transformedData,
             headers: {
                 ...this.headers,
@@ -3064,21 +3812,25 @@ class RestStd {
                     ? ContentTypeEnum.FORM_DATA
                     : ContentTypeEnum.JSON,
             },
-        }, options);
+        };
+        return this.executeFetch(config);
     }
     /**
-     * Partially update an existing item on the server.
-     *
-     * @param id The ID of the item to update.
-     * @param data The updated data for the item.
-     * @param options Additional options for the fetch function.
-     * @returns The result of the fetch function (typically a promise).
+     * Partially updates an existing item by its ID.
+     * @template TResponse The expected response type
+     * @template TData The type of data to send (partial)
+     * @param options - Options including id, data, options, and optional url override
+     * @returns A promise that resolves with the response data
      */
-    static patch(id, data, options = {}) {
+    static patch(options) {
+        this.validateResource();
+        const { id, data, url } = options;
+        const baseUrl = url || this.resource;
+        const finalUrl = this.buildUrl(baseUrl, String(id));
         const transformedData = this.transformData(data);
-        return this.fetchFn({
+        const config = {
             method: "PATCH",
-            url: `${this.resource}/${id}`,
+            url: finalUrl,
             data: transformedData,
             headers: {
                 ...this.headers,
@@ -3086,65 +3838,80 @@ class RestStd {
                     ? ContentTypeEnum.FORM_DATA
                     : ContentTypeEnum.JSON,
             },
-        }, options);
+        };
+        return this.executeFetch(config);
     }
     /**
-     * Delete an item from the server.
-     *
-     * @param id The ID of the item to delete.
-     * @param options Additional options for the fetch function.
-     * @returns The result of the fetch function (typically a promise).
+     * Deletes an item by its ID.
+     * @template TResponse The expected response type
+     * @param options - Options including id, options, and optional url override
+     * @returns A promise that resolves with the response data
      */
-    static delete(id, options = {}) {
-        return this.fetchFn({
+    static delete(options) {
+        this.validateResource();
+        const { id, url } = options;
+        const baseUrl = url || this.resource;
+        const finalUrl = this.buildUrl(baseUrl, String(id));
+        const config = {
             method: "DELETE",
-            url: `${this.resource}/${id}`,
+            url: finalUrl,
             headers: this.headers,
-        }, options);
+        };
+        return this.executeFetch(config);
     }
     /**
-     * Delete multiple items from the server by their IDs.
-     *
-     * @param ids An array of IDs of the items to delete.
-     * @param options Additional options for the fetch function.
-     * @returns The result of the fetch function.
+     * Deletes multiple items by their IDs in a single request.
+     * @template TResponse The expected response type
+     * @param options - Options including ids array, options, and optional url override
+     * @returns A promise that resolves with the response data
      */
-    static bulkDelete(ids, options = {}) {
-        return this.fetchFn({
+    static bulkDelete(options) {
+        this.validateResource();
+        const { ids, url } = options;
+        const baseUrl = url || this.resource;
+        const finalUrl = this.buildUrl(baseUrl, 'bulk');
+        const config = {
             method: "DELETE",
-            url: `${this.resource}/bulk`,
+            url: finalUrl,
             data: { ids },
             headers: this.headers,
-        }, options);
+        };
+        return this.executeFetch(config);
     }
     /**
-     * Upsert method that decides whether to create or update based on the presence of 'id'.
-     *
-     * @param data The data for the item to create or update.
-     * @param options Additional options for the fetch function.
-     * @returns The result of the fetch function (typically a promise).
+     * Creates a new item or updates an existing one, based on the presence of an `id` property in the data.
+     * @template TResponse The expected response type
+     * @template TData The type of data to send (must have optional id)
+     * @param options - Options including data, options, and optional url override
+     * @returns A promise that resolves with the response data
      */
-    static upsert(data, options = {}) {
-        if (data.id) {
-            return this.update(data.id, data, options);
+    static upsert(options) {
+        if (options.data.id) {
+            return this.update({
+                id: options.data.id,
+                data: options.data,
+                url: options.url,
+            });
         }
         else {
-            return this.create(data, options);
+            return this.create({
+                data: options.data,
+                url: options.url,
+            });
         }
     }
     /**
-     * Custom request method for more flexibility.
-     *
-     * @param method HTTP method (GET, POST, etc.).
-     * @param url The custom URL for the request.
-     * @param params Query parameters.
-     * @param data Request body data.
-     * @param options Additional options for the fetch function.
-     * @returns The result of the fetch function (typically a promise).
+     * Makes a custom HTTP request, providing full flexibility over the method, URL, and data.
+     * @template TResponse The expected response type
+     * @template TParams The type of query parameters
+     * @template TData The type of request body data
+     * @param options - Options including method, url, params, data, and options
+     * @returns A promise that resolves with the response data
      */
-    static customRequest(method, url, params, data, options = {}) {
+    static customRequest(options) {
+        const { method, url, params, data } = options;
         const transformedData = this.transformData(data);
-        return this.fetchFn({
+        const config = {
             method: method,
             url: url,
             params: params,
@@ -3155,17 +3922,20 @@ class RestStd {
                     ? ContentTypeEnum.FORM_DATA
                     : ContentTypeEnum.JSON,
             },
-        }, options);
+        };
+        return this.executeFetch(config);
     }
 }
 
 /**
- * Custom composable function for making API requests with Axios.
+ * A composable function that executes an Axios request and returns the response data.
+ * It simplifies making API calls by wrapping the Axios request in a reusable function.
  *
- * @template T The expected return type of the API request.
- * @param {AxiosInstance} axios - The Axios instance for making HTTP requests.
- * @param {AxiosRequestConfig} axiosRequest - Configuration for the Axios request.
- * @returns {Promise<T>} A promise with the result of the API request.
+ * @template T The expected type of the response data.
+ * @param {AxiosInstance} axios - The Axios instance to use for making the request.
+ * @param {AxiosRequestConfig} axiosRequest - The configuration for the Axios request (e.g., URL, method, headers).
+ * @returns {Promise<T>} A promise that resolves with the data from the Axios response.
+ * @throws {Error} Throws an error if the Axios request fails.
  */
 async function axiosFetch(axios, axiosRequest) {
     return axios(axiosRequest)
@@ -3176,10 +3946,19 @@ async function axiosFetch(axios, axiosRequest) {
 }
 
 /**
- * Creates a fetchFn for Axios requests with an optional custom instance.
- * @param fetchComposable - The fn to use for the request (can be any fetch function).
- * @param axiosCustomInstance - An optional custom Axios instance to use for the request.
- * @returns A function that handles the request using the provided fn.
+ * A factory function that creates a reusable query function for making API requests.
+ * It abstracts the Axios instance creation and allows for a custom instance to be provided.
+ * This is particularly useful for creating typed query functions for use with libraries like Vue Query.
+ *
+ * @template TQueryFnData The expected data type of the query function's response.
+ * @template TData The expected data type of the transformed data.
+ * @param {Function} fetchFn - The underlying function that will be called to perform the fetch operation.
+ *   This function should accept an Axios instance, Axios request configuration, and optional query options.
+ * @param {AxiosInstance} [axiosCustomInstance] - An optional custom Axios instance to use for the request.
+ *   If not provided, a default configured instance will be used.
+ * @returns {(axiosRequestConfig: AxiosRequestConfig, options?: UseQueryOptions<TQueryFnData, Error, TData>) => any}
+ *   A new function that takes Axios request configuration and optional query options, and when executed,
+ *   performs the API request using the configured `fetchFn`.
  */
 function useFetch(fetchFn, axiosCustomInstance) {
     const instance = axiosCustomInstance || getConfiguredAxiosInstance();
@@ -3188,131 +3967,20 @@ function useFetch(fetchFn, axiosCustomInstance) {
     };
 }
 
-/**
- * Custom composable for integrating Axios requests with Vue Query.
- *
- * @template T - The type of data expected from the query.
- * @param {AxiosInstance} axios - Axios instance used for making HTTP requests.
- * @param {AxiosRequestConfig} axiosRequest - Initial Axios request configuration.
- * @param {ExtendedQueryOptions<T>} [queryOptions] - Optional Vue Query options with server execution flag.
- * @returns {object} Composable functions and query state for managing API requests.
- */
-function useVueQuery(axios, axiosRequest, queryOptions) {
-    const key = ref([
-        queryOptions?.queryKey || `${axiosRequest.url}-${JSON.stringify(axiosRequest)}`
-    ]);
-    const axiosRequestRef = ref(axiosRequest);
-    const queryOptionsRef = ref(queryOptions);
-    const isInitialized = ref(false);
-    const errorCallbacks = ref([]);
-    const resultCallbacks = ref([]);
-    /**
-     * Vue Query instance for managing API requests.
-     */
-    const query = useQuery({
-        queryKey: key.value,
-        queryFn: async () => {
-            const response = await axios(axiosRequestRef.value);
-            return response.data;
-        },
-        ...(queryOptionsRef.value?.options ?? {})
-    });
-    /**
-     * Executes the query manually with optional new key and request parameters.
-     *
-     * @param {Array<any>} [newKey] - New query key to use.
-     * @param {object} [newRequestParams] - New request parameters to use.
-     * @param {ExtendedQueryOptions<T>} [newQueryOptions] - New Vue Query options to use.
-     */
-    function execute(newKey, newRequestParams, newQueryOptions) {
-        if (newKey) {
-            key.value = newKey;
-        }
-        if (newRequestParams) {
-            axiosRequestRef.value.data = newRequestParams;
-        }
-        if (newQueryOptions) {
-            queryOptionsRef.value = newQueryOptions;
-        }
-        query.refetch();
-    }
-    /**
-     * Registers a callback to be executed on successful request result.
-     * If data is already available, the callback will be executed immediately.
-     *
-     * @param {(data: T) => void} cb - Callback function to handle the result.
-     */
-    function onResult(cb) {
-        resultCallbacks.value.push(cb);
-        if (query.data.value !== undefined && query.data.value !== null) {
-            cb(query.data.value);
-        }
-    }
-    /**
-     * Registers a callback to be executed when the request results in an error.
-     * If an error is already present, the callback will be executed immediately.
-     *
-     * @param {(e: unknown) => void} callback - Callback function to handle errors.
-     */
-    function onError(callback) {
-        errorCallbacks.value.push(callback);
-        if (query.error.value !== undefined) {
-            callback(query.error.value);
-        }
-    }
-    /**
-     * Watches for changes in the query result and triggers result callbacks.
-     */
-    watch(query.data, (newData) => {
-        if (newData !== undefined && newData !== null && isInitialized.value) {
-            resultCallbacks.value.forEach((cb) => cb(newData));
-        }
-    });
-    /**
-     * Watches for changes in query errors and triggers error callbacks.
-     */
-    watch(query.error, (newError) => {
-        if (newError !== undefined && isInitialized.value) {
-            errorCallbacks.value.forEach((cb) => cb(newError));
-        }
-    });
-    /**
-     * Handles server-side prefetching for SSR.
-     * Ensures data is fetched before rendering on the server.
-     */
-    onServerPrefetch(async () => {
-        if (queryOptionsRef.value?.server !== false) {
-            await query.suspense();
-            if (query.data.value != null) {
-                resultCallbacks.value.forEach((cb) => cb(query.data.value));
-            }
-        }
-    });
-    /**
-     * Ensures callbacks are executed after the component is mounted on the client-side.
-     */
-    onMounted(() => {
-        isInitialized.value = true;
-        if (query.data.value != null) {
-            resultCallbacks.value.forEach((cb) => cb(query.data.value));
-        }
-        if (query.error.value !== undefined) {
-            errorCallbacks.value.forEach((cb) => cb(query.error.value));
-        }
-    });
-    return {
-        execute,
-        onResult,
-        onError,
-        ...query
-    };
-}
-
 let notified = false;
 /**
- * Composable to manage breakpoints using Tailwind CSS and shared window resize listener.
+ * A composable that provides a reactive interface to Tailwind CSS breakpoints using `@vueuse/core`.
+ * It simplifies working with responsive layouts by offering a set of reactive booleans for different
+ * screen sizes and combinations. On its first invocation, it also logs the current device type (Mobile,
+ * Tablet, Laptop, or Desktop) to the console for easier debugging during development.
  *
- * @returns {Object} An object containing the breakpoints and their states.
+ * @returns {object} An object containing various reactive properties for screen sizes, window dimensions, and breakpoint utilities, including:
+ *   - `current`: A ref to the current breakpoint name.
+ *   - `active`: A ref to the currently active breakpoint name.
+ *   - `sm_S`, `md_GE`, etc.: A series of refs indicating if the screen is smaller than, greater than or equal to, or between specific breakpoints.
+ *   - `mobile`, `tablet`, `laptop`, `desktop`: Refs that are true for common device width ranges.
+ *   - `windowWidth`, `windowHeight`: Reactive refs for the window's width and height.
+ *   - `breakpoints`: The original `useBreakpoints` return object from `@vueuse/core`.
  */
 function useBreakpoint() {
     const breakpoints = useBreakpoints(breakpointsTailwind);
@@ -3424,15 +4092,20 @@ function useBreakpoint() {
 }
 
 /**
- * A composable function that filters objects based on a specific field and criteria.
+ * A composable function that filters an array of objects based on a specified field, data type, and criteria.
+ * It supports filtering by date range, string matching (case-insensitive and diacritic-insensitive), number range, and boolean values.
  *
- * @param {Object[]} items - The list of objects to filter.
- * @param {Object} filterConfig - Configuration for the filter, specifying the field, the data type to filter, and the criteria.
- * @param {string} filterConfig.field - The field in the objects to filter.
- * @param {string} filterConfig.type - The data type of the field ('date', 'string', 'number', 'boolean').
- * @param {any} filterConfig.criteria - The criteria for filtering. Can be a date range, a string to search, a number range, or a boolean value.
- *
- * @returns {Object[]} - The filtered list of objects.
+ * @template T A generic type that extends a record of string keys to any value, representing the objects in the array.
+ * @param {T[]} items - The array of objects to be filtered.
+ * @param {object} filterConfig - The configuration object for filtering.
+ * @param {string} filterConfig.field - The name of the field in the objects to filter by.
+ * @param {'date' | 'string' | 'number' | 'boolean'} filterConfig.type - The data type of the field to be filtered.
+ * @param {any} filterConfig.criteria - The criteria for filtering, which varies based on the `type`:
+ *   - For 'date': An object `{ startDate: string, endDate: string }`.
+ *   - For 'string': A string to search for.
+ *   - For 'number': An object `{ min: number, max: number }`.
+ *   - For 'boolean': A boolean value.
+ * @returns {T[]} The filtered array of objects. If the criteria are invalid or not provided, the original array is returned.
  */
 function useFilter(items, filterConfig) {
     // Ensure the filterConfig is correctly structured
@@ -3481,12 +4154,20 @@ function useFilter(items, filterConfig) {
 }
 
 /**
- * Composable to handle pagination logic.
+ * A composable that provides pagination logic based on reactive refs for the current page,
+ * total number of items, and items per page.
  *
- * @param page - Reactive ref for the current page number.
- * @param total - Reactive ref for total number of items.
- * @param pageSize - Reactive ref for number of items per page.
- * @returns An object with pagination controls.
+ * @param {Ref<number>} page - A reactive ref representing the current page number.
+ * @param {Ref<number>} total - A reactive ref representing the total number of items to be paginated.
+ * @param {Ref<number>} pageSize - A reactive ref representing the number of items per page.
+ * @returns {{
+ *   totalPages: import('vue').ComputedRef<number>,
+ *   canFetchNextPage: () => boolean,
+ *   canFetchPreviousPage: () => boolean
+ * }} An object containing:
+ *   - `totalPages`: A computed property that calculates the total number of pages.
+ *   - `canFetchNextPage`: A function that returns `true` if there is a next page.
+ *   - `canFetchPreviousPage`: A function that returns `true` if there is a previous page.
  */
 function usePagination(page, total, pageSize) {
     // Calculate the total number of pages
@@ -3503,11 +4184,16 @@ function usePagination(page, total, pageSize) {
 }
 
 /**
- * Custom composable for sorting products based on a selected criterion.
- * @param {Array} items - The array of products to sort.
- * @param {Array} criteriaList - The list of available sorting criteria.
- * @param {Number} selectedCriteria - The currently selected sorting criterion.
- * @returns {ComputedRef<Array>} - The sorted array of products.
+ * A composable that sorts an array of objects based on a selected criterion from a list of predefined sorting options.
+ * It supports sorting by number, date, boolean, and string fields, in both ascending and descending order.
+ *
+ * @template T The type of items in the array.
+ * @param {T[]} items - The array of objects to sort.
+ * @param {Array<{value: number, label: string, field: string, order: string, type: string}>} criteriaList - A list of
+ *   sorting criteria objects. Each object defines a sorting option with a unique `value`, a `label` for display, the `field`
+ *   to sort by, the `order` ('asc' or 'desc'), and the data `type` ('number', 'date', 'boolean', 'string').
+ * @param {number} selectedCriteria - The `value` of the currently selected sorting criterion from the `criteriaList`.
+ * @returns {ComputedRef<T[]>} A computed ref containing the sorted items. If the selected criterion is not found, the original array is returned.
  */
 function useSorter(items, criteriaList, selectedCriteria) {
     return computed(() => {
@@ -3539,36 +4225,58 @@ function useSorter(items, criteriaList, selectedCriteria) {
                 return criteria.order === 'asc' ? strA.localeCompare(strB) : strB.localeCompare(strA);
             }
         });
-    }).value;
+    });
 }
 
 /**
  * Custom hook for authentication logic, including login, logout, token management, and session preference.
+ * Accepts an optional fetcher function. If not provided, uses the default configured fetcher or falls back to Axios.
+ *
+ * @param {Fetcher} [fetcher] - Optional fetcher function to use for auth requests. If not provided, uses the default configured fetcher.
+ * @returns {{
+ *   logout: (params?: Record<string, unknown>) => Promise<void>,
+ *   login: (params: Record<string, unknown>, persistence: LocationPreference, tokenPaths?: AuthTokenPaths) => Promise<AuthResponse>
+ * }} An object containing authentication functions.
  *
- * @param {string} secretKey - The secret key used for token encryption/decryption.
- * @returns {AuthHook} An object containing authentication functions.
+ * @example
+ * ```typescript
+ * // Using default fetcher (Axios)
+ * const auth = useAuth();
+ *
+ * // Using custom fetcher
+ * const customFetcher = createOfetchFetcher();
+ * const auth = useAuth(customFetcher);
+ * ```
  */
-function useAuth() {
-    const axiosInstance = getConfiguredAxiosInstance();
+function useAuth(fetcher) {
     const endpoints = getEndpointsConfig();
+    const getFetcher = () => {
+        return fetcher || getDefaultAuthFetcher();
+    };
     /**
      * Logs out the user by making a POST request to the logout endpoint,
      * cleaning all stored credentials, and reloading the page.
      * The session persistence preference is NOT reset here; it persists across logouts.
      *
-     * @param {AuthParams} [params={}] - Optional parameters to send with the logout request.
+     * @param {Record<string, unknown>} [params={}] - Optional parameters to send with the logout request.
      * @returns {Promise<void>}
      */
     const logout = async (params = {}) => {
         try {
-            await axiosInstance.post(endpoints.LOGOUT, params);
+            await getFetcher()({
+                method: 'POST',
+                url: endpoints.LOGOUT,
+                data: params,
+            });
         }
         catch (error) {
-            handleError(error, false);
+            handleError(error);
         }
         finally {
             await cleanCredentials(await getSessionPersistence());
-            window.location.reload();
+            if (typeof window !== 'undefined') {
+                window.location.reload();
+            }
         }
     };
     /**
@@ -3583,7 +4291,11 @@ function useAuth() {
      */
     const login = async (params = {}, persistence, tokenPaths = getTokenPathsConfig()) => {
         try {
-            const { data } = await axiosInstance.post(endpoints.LOGIN, params);
+            const data = await getFetcher()({
+                method: 'POST',
+                url: endpoints.LOGIN,
+                data: params,
+            });
             const { accessToken, refreshToken } = extractAndValidateTokens(data, tokenPaths, "LOGIN");
             configSession({
                 persistencePreference: persistence,
@@ -3592,7 +4304,7 @@ function useAuth() {
             return data;
         }
         catch (error) {
-            handleError(error, false);
+            handleError(error);
             throw error;
         }
     };
@@ -3602,17 +4314,63 @@ function useAuth() {
     };
 }
 
+// @ts-ignore - ofetch is an optional peer dependency
+/**
+ * Creates a fetcher function using ofetch.
+ *
+ * @param baseURL - Optional base URL for requests
+ * @param defaultOptions - Optional default options for ofetch
+ * @returns A fetcher function compatible with RestStd
+ *
+ * @example
+ * ```typescript
+ * import { createOfetchFetcher, RestStd } from '@arex95/vue-core';
+ *
+ * export class Role extends RestStd {
+ *     static override resource = 'roles';
+ *     static fetchFn = createOfetchFetcher('https://api.example.com');
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * import { createFetch } from 'ofetch';
+ * import { createOfetchFetcher, RestStd } from '@arex95/vue-core';
+ *
+ * const ofetchInstance = createFetch({ baseURL: 'https://api.example.com' });
+ *
+ * export class Role extends RestStd {
+ *     static override resource = 'roles';
+ *     static fetchFn = createOfetchFetcher(undefined, { fetch: ofetchInstance });
+ * }
+ * ```
+ */
+function createOfetchFetcher(baseURL, defaultOptions) {
+    return async (config) => {
+        const url = baseURL
+            ? `${baseURL.replace(/\/$/, '')}/${config.url.replace(/^\//, '')}`
+            : config.url;
+        return $fetch(url, {
+            method: config.method,
+            query: config.params,
+            body: config.data,
+            headers: config.headers,
+            ...defaultOptions,
+        });
+    };
+}
+
 /**
- * The Vue plugin for @arex95/vue-core.
- * Configures the core functionalities for authentication and API communication.
+ * A Vue plugin that serves as the entry point for the `@arex95/vue-core` library.
+ * It initializes and configures all the core modules, such as authentication, API communication,
+ * and token management, based on the provided options.
  */
 const ArexVueCore = {
     /**
-     * The `install` method is the entry point for the Vue plugin.
-     * It is automatically called when `app.use(ArexVueCore, options)` is executed.
+     * The `install` method required by Vue's plugin system. It is called when `app.use()` is invoked.
      *
-     * @param app The Vue application instance.
-     * @param options The configuration options provided by the user.
+     * @param {App} app - The Vue application instance.
+     * @param {ArexVueCoreOptions} options - The configuration object for the library.
      */
     install: (app, options) => {
         if (!options) {
@@ -3648,4 +4406,4 @@ const ArexVueCore = {
     },
 };
 
-export { AppTypes, ArchiveTypes, ArexVueCore, AudioTypes, AxiosService, ContentTypeEnum, DocumentTypes, ERROR_MESSAGES, ERROR_STYLES, ErrorEnum, ErrorMessages, ErrorStyles, ExceptionEnum, FontTypes, ImageTypes, KeyCodeEnum, OtherTypes, RestStd, ScreenBreakpoint, ScreenSize, StorageKeyEnum, StorageTypeEnum, TextTypes, VideoTypes, ab2hex, addCustomKeyboardShortcut, addDays, addDoubleClickListener, addKeyListener, ageAtDate, axiosFetch, blobToFormData, bufferToBlob, calculateAge, cleanCredentials, clickOutside, compareObject, configAppKey, configAxios, configEndpoints, configRefreshTokenPaths, configSession, configTokenKeys, configTokenPaths, copyToClipboard, countWords, createKeyMap, customShortcut, daysBetween, daysToNextBirthday, debounce, debounceAsync, debounceAsyncValidator, debounceAsyncWithImmediate, debounceLeading, debounceLeadingTrailing, debounceTrailing, decrypt, deepClone, deepEqual, deepMerge, detectKeyHold, disableCopy, disableF12Key, disableMouseButtons, disableRightClick, disableSpecificKeys, downloadBlob, enableMouseButtons, enableRightClick, enableSpecificKeys, encrypt, exportToCSV, exportToExcel, exportToJSON, exportToText, exportToXML, extractAndValidateTokens, filterObjectByKeys, flattenObject, formDataToObject, formatDate, generateRandomString, getAppKey, getAuthRefreshToken, getAuthToken, getConfiguredAxiosInstance, getDecryptedItem, getEndOfMonth, getEndpointsConfig, getObjectDifferences, getObjectKeys, getQueryParam, getRefreshTokenPathsConfig, getSessionConfig, getSessionId, getSessionPersistence, getStartOfMonth, getTokenConfig, getTokenPathsConfig, handleError, hasNestedProperties, hex2ab, importKey, isEmptyObject, isLeapYear, isStrongPassword, isValidAge, isValidCreditCard, isValidDate, isValidEmail, isValidExpiryDate, isValidHexColor, isValidHexColorAlpha, isValidHexNumber, isValidIP, isValidPhoneNumber, isValidSSN, isValidTime, isValidURL, isValidUsername, isValidZIP, lowerFirst, objectToFormData, objectToFormDataEnhanced, objectToQueryString, openWindow, parseDate, proxyToPlainObject, readFileAsDataURL, readFileAsText, refreshTokens, registerKeyboardShortcuts, removeAccent, removeClickOutside, removeCustomKeyboardShortcut, removeCustomShortcuts, removeDoubleClickListener, removeEmptyProperties, removeKeyListeners, replaceAll, reverseString, safeGet, screenMap, scrollToTop, simulateKeyPress, stopDetectingKeyHold, storeAuthRefreshToken, storeAuthToken, storeEncryptedItem, storeTokens, stringToBlob, subtractDays, throttle, toCamelCase, toKebabCase, toggleTabNavigation, truncateString, unregisterKeyboardShortcuts, upperFirst, useAuth, useBreakpoint, useFetch, useFilter, usePagination, useSorter, useVueQuery, validateAlphanumeric, validateLetters, validateNumbers, verifyAuth };
+export { AppTypes, ArchiveTypes, ArexVueCore, AudioTypes, AuthError, AxiosService, BaseError, ContentTypeEnum, DocumentTypes, ERROR_MESSAGES, ERROR_STYLES, ErrorEnum, ErrorMessages, ErrorStyles, ExceptionEnum, FontTypes, ImageTypes, KeyCodeEnum, NetworkError, OtherTypes, RestStd, ScreenBreakpoint, ScreenSize, ServerError, StorageKeyEnum, StorageTypeEnum, TextTypes, ValidationError, VideoTypes, ab2hex, addCustomKeyboardShortcut, addDays, addDoubleClickListener, addKeyListener, ageAtDate, axiosFetch, blobToFormData, bufferToBlob, calculateAge, cleanCredentials, clickOutside, compareObject, configAppKey, configAuthFetcher, configAxios, configEndpoints, configRefreshTokenPaths, configSession, configTokenKeys, configTokenPaths, copyToClipboard, countWords, createAxiosFetcher, createKeyMap, createOfetchFetcher, customShortcut, daysBetween, daysToNextBirthday, debounce, debounceAsync, debounceAsyncValidator, debounceAsyncWithImmediate, debounceLeading, debounceLeadingTrailing, debounceTrailing, decrypt, deepClone, deepEqual, deepMerge, detectKeyHold, disableCopy, disableF12Key, disableMouseButtons, disableRightClick, disableSpecificKeys, downloadBlob, enableMouseButtons, enableRightClick, enableSpecificKeys, encrypt, exportToCSV, exportToExcel, exportToJSON, exportToText, exportToXML, extractAndValidateTokens, filterObjectByKeys, flattenObject, formDataToObject, formatDate, generateRandomString, getAppKey, getAuthRefreshToken, getAuthToken, getConfiguredAxiosInstance, getCookieStorage, getDecryptedItem, getDefaultAuthFetcher, getEndOfMonth, getEndpointsConfig, getObjectDifferences, getObjectKeys, getPreferredStorage, getQueryParam, getRefreshTokenPathsConfig, getSessionConfig, getSessionId, getSessionPersistence, getSessionStorage, getStartOfMonth, getStorage, getTokenConfig, getTokenPathsConfig, handleError, hasNestedProperties, hex2ab, importKey, isClient, isEmptyObject, isLeapYear, isServer, isStrongPassword, isValidAge, isValidCreditCard, isValidDate, isValidEmail, isValidExpiryDate, isValidHexColor, isValidHexColorAlpha, isValidHexNumber, isValidIP, isValidPhoneNumber, isValidSSN, isValidTime, isValidURL, isValidUsername, isValidZIP, lowerFirst, objectToFormData, objectToFormDataEnhanced, objectToQueryString, openWindow, parseDate, proxyToPlainObject, readFileAsDataURL, readFileAsText, refreshTokens, registerKeyboardShortcuts, removeAccent, removeClickOutside, removeCustomKeyboardShortcut, removeCustomShortcuts, removeDoubleClickListener, removeEmptyProperties, removeKeyListeners, replaceAll, retryWithBackoff, reverseString, safeGet, screenMap, scrollToTop, setDefaultAuthFetcherFactory, simulateKeyPress, stopDetectingKeyHold, storeAuthRefreshToken, storeAuthToken, storeEncryptedItem, storeTokens, stringToBlob, subtractDays, throttle, toCamelCase, toKebabCase, toggleTabNavigation, truncateString, unregisterKeyboardShortcuts, upperFirst, useAuth, useBreakpoint, useFetch, useFilter, usePagination, useSorter, validateAlphanumeric, validateLetters, validateNumbers, verifyAuth };