tiny-essentials 1.27.1 → 1.28.1

package/dist/v1/basics/html.d.mts

@@ -1,35 +1,36 @@
 /**
  * Reads the contents of a file using the specified FileReader method.
  *
- * @param {File} file - The file to be read.
+ * @param {File|Blob} file - The file to be read.
  * @param {'readAsArrayBuffer'|'readAsDataURL'|'readAsText'|'readAsBinaryString'} method -
- *   The FileReader method to use for reading the file.
+ * The FileReader method to use for reading the file.
  * @returns {Promise<any>} - A promise that resolves with the file content, according to the chosen method.
+ * @throws {TypeError} - If arguments don't match expected types.
  * @throws {Error} - If an unexpected error occurs while handling the result.
  * @throws {DOMException} - If the FileReader encounters an error while reading the file.
  */
-export function readFileBlob(file: File, method: "readAsArrayBuffer" | "readAsDataURL" | "readAsText" | "readAsBinaryString"): Promise<any>;
+export function readFileBlob(file: File | Blob, method: "readAsArrayBuffer" | "readAsDataURL" | "readAsText" | "readAsBinaryString"): Promise<any>;
 /**
  * Reads a file as a Base64 string using FileReader, and optionally formats it as a full data URL.
  *
  * Performs strict validation to ensure the result is a valid Base64 string or a proper data URL.
  *
- * @param {File} file - The file to be read.
+ * @param {File|Blob} file - The file to be read.
  * @param {boolean|string} [isDataUrl=false] - If true, returns a full data URL; if false, returns only the Base64 string;
- *   if a string is passed, it is used as the MIME type in the data URL.
+ * if a string is passed, it is used as the MIME type in the data URL.
  * @returns {Promise<string>} - A promise that resolves with the Base64 string or data URL.
  *
  * @throws {TypeError} - If the result is not a string or if `isDataUrl` is not a valid type.
  * @throws {Error} - If the result does not match the expected data URL format or Base64 structure.
  * @throws {DOMException} - If the FileReader fails to read the file.
  */
-export function readBase64Blob(file: File, isDataUrl?: boolean | string): Promise<string>;
+export function readBase64Blob(file: File | Blob, isDataUrl?: boolean | string): Promise<string>;
 /**
  * Reads a file and strictly validates its content as proper JSON using FileReader.
  *
  * Performs several checks to ensure the file contains valid, parsable JSON data.
  *
- * @param {File} file - The file to be read. It must contain valid JSON as plain text.
+ * @param {File|Blob} file - The file to be read. It must contain valid JSON as plain text.
  * @returns {Promise<Record<string|number|symbol, any>|any[]>} - A promise that resolves with the parsed JSON object.
  *
  * @throws {SyntaxError} - If the file content is not valid JSON syntax.
@@ -37,24 +38,15 @@ export function readBase64Blob(file: File, isDataUrl?: boolean | string): Promis
  * @throws {Error} - If the result is empty or structurally invalid as JSON.
  * @throws {DOMException} - If the FileReader fails to read the file.
  */
-export function readJsonBlob(file: File): Promise<Record<string | number | symbol, any> | any[]>;
+export function readJsonBlob(file: File | Blob): Promise<Record<string | number | symbol, any> | any[]>;
 /**
  * Saves a JSON object as a downloadable file.
  * @param {string} filename
  * @param {any} data
  * @param {number} [spaces=2]
+ * @throws {TypeError} - If arguments do not match expected types.
  */
 export function saveJsonFile(filename: string, data: any, spaces?: number): void;
-/**
- * @typedef {Object} FetchTemplateOptions
- * @property {string} [method="GET"] - HTTP method to use (GET, POST, etc.).
- * @property {any} [body] - Request body (only for methods like POST, PUT).
- * @property {number} [timeout=0] - Timeout in milliseconds (ignored if signal is provided).
- * @property {number} [retries=0] - Number of retry attempts (ignored if signal is provided).
- * @property {Headers|Record<string, *>} [headers={}] - Additional headers.
- * @property {AbortSignal|null} [signal] - External AbortSignal; disables timeout and retries.
- * @property {FetchOnProgressResult} [onProgress] - Track the load progress.
- */
 /**
  * Callback function used to report the progress of a data download.
  *
@@ -72,38 +64,41 @@ export function saveJsonFile(filename: string, data: any, spaces?: number): void
  *
  * @param {Response} response - The original response object to be tracked.
  * @param {FetchOnProgressResult} onProgress - The callback function to handle progress events.
+ * @param {(res: Response) => ResponseInit} [returnResponse] - The callback function to return the ResponseInit to ReadableStream.
  * @returns {Response} A new Response object with the tracked stream.
  */
-export function trackFetchProgress(response: Response, onProgress: FetchOnProgressResult): Response;
+export function trackFetchProgress(response: Response, onProgress: FetchOnProgressResult, returnResponse?: (res: Response) => ResponseInit): Response;
 /**
  * Loads and parses a JSON from a remote URL using Fetch API.
  *
- * @param {string} url - The full URL to fetch JSON from.
- * @param {FetchTemplateOptions} [options] - Optional settings.
+ * @param {string | URL | Request} url - The full URL to fetch JSON from.
+ * @param {RequestInit|null} [options] - Optional settings.
+ * @param {FetchOnProgressResult} [onProgress] - Track the load progress.
  * @returns {Promise<any[] | Record<string | number | symbol, unknown>>} Parsed JSON object.
  * @throws {Error} Throws if fetch fails, times out, or returns invalid JSON.
  */
-export function fetchJson(url: string, options?: FetchTemplateOptions): Promise<any[] | Record<string | number | symbol, unknown>>;
+export function fetchJson(url: string | URL | Request, options?: RequestInit | null, onProgress?: FetchOnProgressResult): Promise<any[] | Record<string | number | symbol, unknown>>;
 /**
  * Loads a remote file as a Blob using Fetch API.
  *
- * @param {string} url - The full URL to fetch the file from.
- * @param {FetchTemplateOptions} [options] - Optional fetch options.
+ * @param {string | URL | Request} url - The full URL to fetch the file from.
  * @param {string[]} [allowedMimeTypes] - Optional list of accepted MIME types (e.g., ['image/jpeg']).
+ * @param {RequestInit|null} [options] - Optional fetch options.
+ * @param {FetchOnProgressResult} [onProgress] - Track the load progress.
  * @returns {Promise<Blob>} - The fetched file as a Blob.
  * @throws {Error} Throws if fetch fails, response is not ok, or MIME type is not allowed.
  */
-export function fetchBlob(url: string, allowedMimeTypes?: string[], options?: FetchTemplateOptions): Promise<Blob>;
+export function fetchBlob(url: string | URL | Request, allowedMimeTypes?: string[], options?: RequestInit | null, onProgress?: FetchOnProgressResult): Promise<Blob>;
 /**
  * Loads a remote file as a text using Fetch API.
- *
- * @param {string} url - The full URL to fetch the file from.
- * @param {FetchTemplateOptions} [options] - Optional fetch options.
+ * @param {string | URL | Request} url - The full URL to fetch the file from.
  * @param {string[]} [allowedMimeTypes] - Optional list of accepted MIME types (e.g., ['image/jpeg']).
+ * @param {RequestInit|null} [options] - Optional fetch options.
+ * @param {FetchOnProgressResult} [onProgress] - Track the load progress.
  * @returns {Promise<string>} - The fetched file as a text.
  * @throws {Error} Throws if fetch fails, response is not ok, or MIME type is not allowed.
  */
-export function fetchText(url: string, allowedMimeTypes?: string[], options?: FetchTemplateOptions): Promise<string>;
+export function fetchText(url: string | URL | Request, allowedMimeTypes?: string[], options?: RequestInit | null, onProgress?: FetchOnProgressResult): Promise<string>;
 /**
  * Represents the final state and metadata of an attempted image load.
  * @typedef {Object} ImageLoadResult
@@ -132,7 +127,7 @@ export function fetchText(url: string, allowedMimeTypes?: string[], options?: Fe
  * @param {(event: Event, startTime: number) => void} [options.onLoading]
  * @returns {Promise<ImageLoadResult>}
  */
-export function loadImage({ url, onLoading, crossOrigin }: {
+export function loadImage(options: {
     url: string;
     crossOrigin?: string | undefined;
     onLoading?: ((event: Event, startTime: number) => void) | undefined;
@@ -151,7 +146,7 @@ export function loadImage({ url, onLoading, crossOrigin }: {
  * @returns {() => void} Function that removes all installed event listeners.
  * @throws {TypeError} If any provided setting is invalid.
  */
-export function installWindowHiddenScript({ element, hiddenClass, visibleClass, onVisible, onHidden, }?: {
+export function installWindowHiddenScript(settings?: {
     element?: Element | undefined;
     hiddenClass?: string | undefined;
     visibleClass?: string | undefined;
@@ -166,36 +161,6 @@ export function installWindowHiddenScript({ element, hiddenClass, visibleClass,
         oldClass: string;
     }) => void) | undefined;
 }): () => void;
-export type FetchTemplateOptions = {
-    /**
-     * - HTTP method to use (GET, POST, etc.).
-     */
-    method?: string | undefined;
-    /**
-     * - Request body (only for methods like POST, PUT).
-     */
-    body?: any;
-    /**
-     * - Timeout in milliseconds (ignored if signal is provided).
-     */
-    timeout?: number | undefined;
-    /**
-     * - Number of retry attempts (ignored if signal is provided).
-     */
-    retries?: number | undefined;
-    /**
-     * - Additional headers.
-     */
-    headers?: Headers | Record<string, any> | undefined;
-    /**
-     * - External AbortSignal; disables timeout and retries.
-     */
-    signal?: AbortSignal | null | undefined;
-    /**
-     * - Track the load progress.
-     */
-    onProgress?: FetchOnProgressResult | undefined;
-};
 /**
  * Callback function used to report the progress of a data download.
  */

package/dist/v1/basics/html.mjs

@@ -3,14 +3,22 @@ import { isJsonObject } from './objChecker.mjs';
 /**
  * Reads the contents of a file using the specified FileReader method.
  *
- * @param {File} file - The file to be read.
+ * @param {File|Blob} file - The file to be read.
  * @param {'readAsArrayBuffer'|'readAsDataURL'|'readAsText'|'readAsBinaryString'} method -
- *   The FileReader method to use for reading the file.
+ * The FileReader method to use for reading the file.
  * @returns {Promise<any>} - A promise that resolves with the file content, according to the chosen method.
+ * @throws {TypeError} - If arguments don't match expected types.
  * @throws {Error} - If an unexpected error occurs while handling the result.
  * @throws {DOMException} - If the FileReader encounters an error while reading the file.
  */
 export function readFileBlob(file, method) {
+    if (!(file instanceof Blob)) {
+        return Promise.reject(new TypeError('The "file" argument must be an instance of Blob or File.'));
+    }
+    const validMethods = ['readAsArrayBuffer', 'readAsDataURL', 'readAsText', 'readAsBinaryString'];
+    if (typeof method !== 'string' || !validMethods.includes(method)) {
+        return Promise.reject(new TypeError(`The "method" argument must be one of: ${validMethods.join(', ')}.`));
+    }
     return new Promise((resolve, reject) => {
         const reader = new FileReader();
         reader.onload = () => {
@@ -32,9 +40,9 @@ export function readFileBlob(file, method) {
  *
  * Performs strict validation to ensure the result is a valid Base64 string or a proper data URL.
  *
- * @param {File} file - The file to be read.
+ * @param {File|Blob} file - The file to be read.
  * @param {boolean|string} [isDataUrl=false] - If true, returns a full data URL; if false, returns only the Base64 string;
- *   if a string is passed, it is used as the MIME type in the data URL.
+ * if a string is passed, it is used as the MIME type in the data URL.
  * @returns {Promise<string>} - A promise that resolves with the Base64 string or data URL.
  *
  * @throws {TypeError} - If the result is not a string or if `isDataUrl` is not a valid type.
@@ -42,9 +50,14 @@ export function readFileBlob(file, method) {
  * @throws {DOMException} - If the FileReader fails to read the file.
  */
 export function readBase64Blob(file, isDataUrl = false) {
+    // Validação do argumento 'file'
+    if (!(file instanceof Blob)) {
+        return Promise.reject(new TypeError('The "file" argument must be an instance of Blob or File.'));
+    }
+    if (typeof isDataUrl !== 'string' && typeof isDataUrl !== 'boolean') {
+        return Promise.reject(new TypeError('The isDataUrl parameter must be a boolean or a string.'));
+    }
     return new Promise((resolve, reject) => {
-        if (typeof isDataUrl !== 'string' && typeof isDataUrl !== 'boolean')
-            reject(new TypeError('The isDataUrl parameter must be a boolean or a string.'));
         readFileBlob(file, 'readAsDataURL')
             .then(
         /**
@@ -73,7 +86,7 @@ export function readBase64Blob(file, isDataUrl = false) {
  *
  * Performs several checks to ensure the file contains valid, parsable JSON data.
  *
- * @param {File} file - The file to be read. It must contain valid JSON as plain text.
+ * @param {File|Blob} file - The file to be read. It must contain valid JSON as plain text.
  * @returns {Promise<Record<string|number|symbol, any>|any[]>} - A promise that resolves with the parsed JSON object.
  *
  * @throws {SyntaxError} - If the file content is not valid JSON syntax.
@@ -82,6 +95,9 @@ export function readBase64Blob(file, isDataUrl = false) {
  * @throws {DOMException} - If the FileReader fails to read the file.
  */
 export function readJsonBlob(file) {
+    if (!(file instanceof Blob)) {
+        return Promise.reject(new TypeError('The "file" argument must be an instance of Blob or File.'));
+    }
     return new Promise((resolve, reject) => readFileBlob(file, 'readAsText')
         .then((data) => {
         if (typeof data !== 'string')
@@ -101,8 +117,15 @@ export function readJsonBlob(file) {
  * @param {string} filename
  * @param {any} data
  * @param {number} [spaces=2]
+ * @throws {TypeError} - If arguments do not match expected types.
  */
 export function saveJsonFile(filename, data, spaces = 2) {
+    if (typeof filename !== 'string') {
+        throw new TypeError('The "filename" argument must be a string.');
+    }
+    if (typeof spaces !== 'number' || !Number.isInteger(spaces) || spaces < 0) {
+        throw new TypeError('The "spaces" argument must be a non-negative integer.');
+    }
     const json = JSON.stringify(data, null, spaces);
     const blob = new Blob([json], { type: 'application/json' });
     const url = URL.createObjectURL(blob);
@@ -114,16 +137,6 @@ export function saveJsonFile(filename, data, spaces = 2) {
     document.body.removeChild(link);
     URL.revokeObjectURL(url);
 }
-/**
- * @typedef {Object} FetchTemplateOptions
- * @property {string} [method="GET"] - HTTP method to use (GET, POST, etc.).
- * @property {any} [body] - Request body (only for methods like POST, PUT).
- * @property {number} [timeout=0] - Timeout in milliseconds (ignored if signal is provided).
- * @property {number} [retries=0] - Number of retry attempts (ignored if signal is provided).
- * @property {Headers|Record<string, *>} [headers={}] - Additional headers.
- * @property {AbortSignal|null} [signal] - External AbortSignal; disables timeout and retries.
- * @property {FetchOnProgressResult} [onProgress] - Track the load progress.
- */
 /**
  * Callback function used to report the progress of a data download.
  *
@@ -141,9 +154,17 @@ export function saveJsonFile(filename, data, spaces = 2) {
  *
  * @param {Response} response - The original response object to be tracked.
  * @param {FetchOnProgressResult} onProgress - The callback function to handle progress events.
+ * @param {(res: Response) => ResponseInit} [returnResponse] - The callback function to return the ResponseInit to ReadableStream.
  * @returns {Response} A new Response object with the tracked stream.
  */
-export function trackFetchProgress(response, onProgress) {
+export function trackFetchProgress(response, onProgress, returnResponse = (res) => ({
+    headers: res.headers,
+    status: res.status,
+    statusText: res.statusText,
+})) {
+    if (!(response instanceof Response)) {
+        throw new TypeError('The "response" argument must be an instance of Response.');
+    }
     if (typeof onProgress !== 'function')
         throw new TypeError('The "onProgress" argument must be a function.');
     if (!response.body)
@@ -166,88 +187,31 @@ export function trackFetchProgress(response, onProgress) {
             controller.close();
         },
     });
-    return new Response(stream, {
-        headers: response.headers,
-        status: response.status,
-        statusText: response.statusText,
-    });
-}
-/**
- * @param {string} url - The full URL to fetch data from.
- * @param {FetchTemplateOptions} [options] - Optional settings.
- * @returns {Promise<Response>} Result data.
- * @throws {Error} Throws if fetch fails, times out.
- */
-async function fetchTemplate(url, { method = 'GET', body, timeout = 0, retries = 0, headers = {}, signal = null, onProgress } = {}) {
-    if (typeof url !== 'string' ||
-        (!url.startsWith('../') &&
-            !url.startsWith('./') &&
-            !url.startsWith('/') &&
-            !url.startsWith('https://') &&
-            !url.startsWith('http://')))
-        throw new Error('Invalid URL: must be a valid http or https address.');
-    if (typeof method !== 'string' || !method.trim())
-        throw new Error('Invalid method: must be a non-empty string.');
-    if (!signal) {
-        if (typeof timeout !== 'number' ||
-            !Number.isFinite(timeout) ||
-            Number.isNaN(timeout) ||
-            timeout < 0)
-            throw new Error('Invalid timeout: must be a positive number.');
-        if (typeof retries !== 'number' ||
-            !Number.isFinite(retries) ||
-            Number.isNaN(retries) ||
-            retries < 0)
-            throw new Error('Invalid retries: must be a positive number.');
-    }
-    const attempts = signal ? 1 : retries + 1;
-    /** @type {Error|null} */
-    let lastError = null;
-    for (let attempt = 0; attempt < attempts; attempt++) {
-        const controller = signal ? null : new AbortController();
-        const localSignal = signal || (controller?.signal ?? null);
-        const timer = !signal && timeout && controller ? setTimeout(() => controller.abort(), timeout) : null;
-        try {
-            const response = await fetch(url, {
-                method: method.toUpperCase(),
-                headers: {
-                    Accept: 'application/json',
-                    ...headers,
-                },
-                body: body !== undefined ? (isJsonObject(body) ? JSON.stringify(body) : body) : undefined,
-                signal: localSignal,
-            });
-            if (timer)
-                clearTimeout(timer);
-            if (!response.ok)
-                throw new Error(`HTTP error: ${response.status} ${response.statusText}`);
-            // If onProgress is not provided or body is null, return original response
-            if (!onProgress)
-                return response;
-            return trackFetchProgress(response, onProgress);
-        }
-        catch (err) {
-            lastError = /** @type {Error} */ (err);
-            if (signal)
-                break; // if an external signal came, it does not retry
-            if (attempt < retries)
-                await new Promise((resolve) => setTimeout(resolve, 300 * (attempt + 1)));
-        }
-    }
-    throw new Error(`Failed to fetch JSON from "${url}"${lastError ? `: ${lastError.message}` : '.'}`);
+    return new Response(stream, returnResponse(response));
 }
 /**
  * Loads and parses a JSON from a remote URL using Fetch API.
  *
- * @param {string} url - The full URL to fetch JSON from.
- * @param {FetchTemplateOptions} [options] - Optional settings.
+ * @param {string | URL | Request} url - The full URL to fetch JSON from.
+ * @param {RequestInit|null} [options] - Optional settings.
+ * @param {FetchOnProgressResult} [onProgress] - Track the load progress.
  * @returns {Promise<any[] | Record<string | number | symbol, unknown>>} Parsed JSON object.
  * @throws {Error} Throws if fetch fails, times out, or returns invalid JSON.
  */
-export async function fetchJson(url, options) {
+export async function fetchJson(url, options, onProgress) {
+    if (typeof url !== 'string') {
+        return Promise.reject(new TypeError('The "url" argument must be a string.'));
+    }
+    if (options !== undefined && typeof options !== 'object') {
+        return Promise.reject(new TypeError('The "options" argument must be an object.'));
+    }
+    if (onProgress !== undefined && typeof onProgress !== 'function') {
+        return Promise.reject(new TypeError('The "onProgress" option must be a function.'));
+    }
     return new Promise((resolve, reject) => {
-        fetchTemplate(url, options)
-            .then(async (res) => {
+        fetch(url, options ?? undefined)
+            .then(async (response) => {
+            const res = onProgress ? trackFetchProgress(response, onProgress) : response;
             const contentType = res.headers.get('content-type') || '';
             if (!contentType.includes('application/json'))
                 throw new Error(`Unexpected content-type: ${contentType}`);
@@ -262,16 +226,30 @@ export async function fetchJson(url, options) {
 /**
  * Loads a remote file as a Blob using Fetch API.
  *
- * @param {string} url - The full URL to fetch the file from.
- * @param {FetchTemplateOptions} [options] - Optional fetch options.
+ * @param {string | URL | Request} url - The full URL to fetch the file from.
  * @param {string[]} [allowedMimeTypes] - Optional list of accepted MIME types (e.g., ['image/jpeg']).
+ * @param {RequestInit|null} [options] - Optional fetch options.
+ * @param {FetchOnProgressResult} [onProgress] - Track the load progress.
  * @returns {Promise<Blob>} - The fetched file as a Blob.
  * @throws {Error} Throws if fetch fails, response is not ok, or MIME type is not allowed.
  */
-export async function fetchBlob(url, allowedMimeTypes, options) {
+export async function fetchBlob(url, allowedMimeTypes, options, onProgress) {
+    if (typeof url !== 'string') {
+        return Promise.reject(new TypeError('The "url" argument must be a string.'));
+    }
+    if (allowedMimeTypes !== undefined && !Array.isArray(allowedMimeTypes)) {
+        return Promise.reject(new TypeError('The "allowedMimeTypes" argument must be an array of strings.'));
+    }
+    if (options !== undefined && typeof options !== 'object') {
+        return Promise.reject(new TypeError('The "options" argument must be an object.'));
+    }
+    if (onProgress !== undefined && typeof onProgress !== 'function') {
+        return Promise.reject(new TypeError('The "onProgress" option must be a function.'));
+    }
     return new Promise((resolve, reject) => {
-        fetchTemplate(url, options)
-            .then(async (res) => {
+        fetch(url, options ?? undefined)
+            .then(async (response) => {
+            const res = onProgress ? trackFetchProgress(response, onProgress) : response;
             const contentType = res.headers.get('content-type') || '';
             if (Array.isArray(allowedMimeTypes) &&
                 allowedMimeTypes.length > 0 &&
@@ -286,17 +264,30 @@ export async function fetchBlob(url, allowedMimeTypes, options) {
 }
 /**
  * Loads a remote file as a text using Fetch API.
- *
- * @param {string} url - The full URL to fetch the file from.
- * @param {FetchTemplateOptions} [options] - Optional fetch options.
+ * @param {string | URL | Request} url - The full URL to fetch the file from.
  * @param {string[]} [allowedMimeTypes] - Optional list of accepted MIME types (e.g., ['image/jpeg']).
+ * @param {RequestInit|null} [options] - Optional fetch options.
+ * @param {FetchOnProgressResult} [onProgress] - Track the load progress.
  * @returns {Promise<string>} - The fetched file as a text.
  * @throws {Error} Throws if fetch fails, response is not ok, or MIME type is not allowed.
  */
-export async function fetchText(url, allowedMimeTypes, options) {
+export async function fetchText(url, allowedMimeTypes, options, onProgress) {
+    if (typeof url !== 'string') {
+        return Promise.reject(new TypeError('The "url" argument must be a string.'));
+    }
+    if (allowedMimeTypes !== undefined && !Array.isArray(allowedMimeTypes)) {
+        return Promise.reject(new TypeError('The "allowedMimeTypes" argument must be an array of strings.'));
+    }
+    if (options !== undefined && typeof options !== 'object') {
+        return Promise.reject(new TypeError('The "options" argument must be an object.'));
+    }
+    if (onProgress !== undefined && typeof onProgress !== 'function') {
+        return Promise.reject(new TypeError('The "onProgress" option must be a function.'));
+    }
     return new Promise((resolve, reject) => {
-        fetchTemplate(url, options)
-            .then(async (res) => {
+        fetch(url, options ?? undefined)
+            .then(async (response) => {
+            const res = onProgress ? trackFetchProgress(response, onProgress) : response;
             const contentType = res.headers.get('content-type') || '';
             if (Array.isArray(allowedMimeTypes) &&
                 allowedMimeTypes.length > 0 &&
@@ -338,7 +329,20 @@ export async function fetchText(url, allowedMimeTypes, options) {
  * @param {(event: Event, startTime: number) => void} [options.onLoading]
  * @returns {Promise<ImageLoadResult>}
  */
-export async function loadImage({ url, onLoading, crossOrigin = 'anonymous' }) {
+export async function loadImage(options) {
+    if (options === null || typeof options !== 'object') {
+        return Promise.reject(new TypeError('The "options" argument must be an object.'));
+    }
+    const { url, onLoading, crossOrigin = 'anonymous' } = options;
+    if (typeof url !== 'string') {
+        return Promise.reject(new TypeError('The "url" option must be a string.'));
+    }
+    if (typeof crossOrigin !== 'string') {
+        return Promise.reject(new TypeError('The "crossOrigin" option must be a string.'));
+    }
+    if (onLoading !== undefined && typeof onLoading !== 'function') {
+        return Promise.reject(new TypeError('The "onLoading" option must be a function.'));
+    }
     return new Promise((resolve, reject) => {
         const img = new Image();
         let startTime = performance.now();
@@ -405,7 +409,11 @@ export async function loadImage({ url, onLoading, crossOrigin = 'anonymous' }) {
  * @returns {() => void} Function that removes all installed event listeners.
  * @throws {TypeError} If any provided setting is invalid.
  */
-export function installWindowHiddenScript({ element = document.body, hiddenClass = 'windowHidden', visibleClass = 'windowVisible', onVisible, onHidden, } = {}) {
+export function installWindowHiddenScript(settings = {}) {
+    if (settings === null || typeof settings !== 'object') {
+        throw new TypeError('The "settings" argument must be an object.');
+    }
+    const { element = document.body, hiddenClass = 'windowHidden', visibleClass = 'windowVisible', onVisible, onHidden, } = settings;
     if (!(element instanceof Element))
         throw new TypeError(`"element" must be an instance of Element.`);
     if (typeof hiddenClass !== 'string')

package/dist/v1/basics/index.cjs

@@ -15,6 +15,7 @@ var mediaContent = require('./mediaContent.cjs');
 
 exports.arraySortPositions = array.arraySortPositions;
 exports.diffArrayList = array.diffArrayList;
+exports.multiplyArrayBlocks = array.multiplyArrayBlocks;
 exports.shuffleArray = array.shuffleArray;
 exports.breakdownDuration = clock.breakdownDuration;
 exports.formatCustomTimer = clock.formatCustomTimer;
@@ -51,6 +52,7 @@ exports.getSimplePerc = simpleMath.getSimplePerc;
 exports.ruleOfThree = simpleMath.ruleOfThree;
 exports.addAiMarkerShortcut = text.addAiMarkerShortcut;
 exports.asyncReplace = text.asyncReplace;
+exports.diffObjList = text.diffObjList;
 exports.diffStrings = text.diffStrings;
 exports.safeTextTrim = text.safeTextTrim;
 exports.toTitleCase = text.toTitleCase;

package/dist/v1/basics/index.d.mts

@@ -1,8 +1,10 @@
+import { multiplyArrayBlocks } from './array.mjs';
 import { valMediaContentMetadata } from './mediaContent.mjs';
 import { valMediaContentMetadataPartial } from './mediaContent.mjs';
 import { parseMediaMetadata } from './mediaContent.mjs';
 import { extractMediaId3Tags } from './mediaContent.mjs';
 import { diffStrings } from './text.mjs';
+import { diffObjList } from './text.mjs';
 import { diffArrayList } from './array.mjs';
 import { breakdownDuration } from './clock.mjs';
 import { calculateMarketcap } from './simpleMath.mjs';
@@ -62,5 +64,5 @@ import { getTimeDuration } from './clock.mjs';
 import { shuffleArray } from './array.mjs';
 import { toTitleCase } from './text.mjs';
 import { toTitleCaseLowerFirst } from './text.mjs';
-export { valMediaContentMetadata, valMediaContentMetadataPartial, parseMediaMetadata, extractMediaId3Tags, diffStrings, diffArrayList, breakdownDuration, calculateMarketcap, compareMarketcap, getPercentage, areElsCollTop, areElsCollBottom, areElsCollLeft, areElsCollRight, areElsCollPerfTop, areElsCollPerfBottom, areElsCollPerfLeft, areElsCollPerfRight, areElsColliding, areElsPerfColliding, getElsColliding, getElsPerfColliding, getElsCollOverlap, getElsCollOverlapPos, getRectCenter, getElsRelativeCenterOffset, getElsCollDirDepth, getElsCollDetails, safeTextTrim, installWindowHiddenScript, genFibonacciSeq, fetchJson, fetchText, readJsonBlob, readFileBlob, readBase64Blob, saveJsonFile, documentIsFullScreen, isScreenFilled, requestFullScreen, exitFullScreen, isFullScreenMode, onFullScreenChange, offFullScreenChange, isJsonObject, arraySortPositions, formatBytes, addAiMarkerShortcut, extendObjType, reorderObjTypeOrder, cloneObjTypeOrder, countObj, objType, ruleOfThree, getSimplePerc, asyncReplace, getAge, formatCustomTimer, formatDayTimer, formatTimer, getTimeDuration, shuffleArray, toTitleCase, toTitleCaseLowerFirst };
+export { multiplyArrayBlocks, valMediaContentMetadata, valMediaContentMetadataPartial, parseMediaMetadata, extractMediaId3Tags, diffStrings, diffObjList, diffArrayList, breakdownDuration, calculateMarketcap, compareMarketcap, getPercentage, areElsCollTop, areElsCollBottom, areElsCollLeft, areElsCollRight, areElsCollPerfTop, areElsCollPerfBottom, areElsCollPerfLeft, areElsCollPerfRight, areElsColliding, areElsPerfColliding, getElsColliding, getElsPerfColliding, getElsCollOverlap, getElsCollOverlapPos, getRectCenter, getElsRelativeCenterOffset, getElsCollDirDepth, getElsCollDetails, safeTextTrim, installWindowHiddenScript, genFibonacciSeq, fetchJson, fetchText, readJsonBlob, readFileBlob, readBase64Blob, saveJsonFile, documentIsFullScreen, isScreenFilled, requestFullScreen, exitFullScreen, isFullScreenMode, onFullScreenChange, offFullScreenChange, isJsonObject, arraySortPositions, formatBytes, addAiMarkerShortcut, extendObjType, reorderObjTypeOrder, cloneObjTypeOrder, countObj, objType, ruleOfThree, getSimplePerc, asyncReplace, getAge, formatCustomTimer, formatDayTimer, formatTimer, getTimeDuration, shuffleArray, toTitleCase, toTitleCaseLowerFirst };
 //# sourceMappingURL=index.d.mts.map

package/dist/v1/basics/index.mjs

@@ -1,11 +1,11 @@
-import { diffArrayList, shuffleArray, arraySortPositions } from './array.mjs';
+import { diffArrayList, shuffleArray, arraySortPositions, multiplyArrayBlocks } from './array.mjs';
 import { breakdownDuration, formatCustomTimer, formatDayTimer, formatTimer, getTimeDuration, } from './clock.mjs';
 import { readJsonBlob, saveJsonFile, fetchJson, installWindowHiddenScript, readFileBlob, readBase64Blob, fetchText, } from './html.mjs';
 import { extendObjType, reorderObjTypeOrder, cloneObjTypeOrder, objType } from './objFilter.mjs';
 import { countObj, isJsonObject } from './objChecker.mjs';
 import { documentIsFullScreen, isScreenFilled, requestFullScreen, exitFullScreen, isFullScreenMode, onFullScreenChange, offFullScreenChange, } from './fullScreen.mjs';
 import { calculateMarketcap, compareMarketcap, formatBytes, genFibonacciSeq, getAge, getPercentage, getSimplePerc, ruleOfThree, } from './simpleMath.mjs';
-import { addAiMarkerShortcut, diffStrings, safeTextTrim, toTitleCase, toTitleCaseLowerFirst, asyncReplace, } from './text.mjs';
+import { addAiMarkerShortcut, diffStrings, diffObjList, safeTextTrim, toTitleCase, toTitleCaseLowerFirst, asyncReplace, } from './text.mjs';
 import { areElsCollTop, areElsCollBottom, areElsCollLeft, areElsCollRight, areElsCollPerfTop, areElsCollPerfBottom, areElsCollPerfLeft, areElsCollPerfRight, areElsColliding, areElsPerfColliding, getElsColliding, getElsPerfColliding, getElsCollOverlap, getElsCollOverlapPos, getRectCenter, getElsRelativeCenterOffset, getElsCollDirDepth, getElsCollDetails, } from './collision.mjs';
 import { extractMediaId3Tags, parseMediaMetadata, valMediaContentMetadata, valMediaContentMetadataPartial, } from './mediaContent.mjs';
-export { valMediaContentMetadata, valMediaContentMetadataPartial, parseMediaMetadata, extractMediaId3Tags, diffStrings, diffArrayList, breakdownDuration, calculateMarketcap, compareMarketcap, getPercentage, areElsCollTop, areElsCollBottom, areElsCollLeft, areElsCollRight, areElsCollPerfTop, areElsCollPerfBottom, areElsCollPerfLeft, areElsCollPerfRight, areElsColliding, areElsPerfColliding, getElsColliding, getElsPerfColliding, getElsCollOverlap, getElsCollOverlapPos, getRectCenter, getElsRelativeCenterOffset, getElsCollDirDepth, getElsCollDetails, safeTextTrim, installWindowHiddenScript, genFibonacciSeq, fetchJson, fetchText, readJsonBlob, readFileBlob, readBase64Blob, saveJsonFile, documentIsFullScreen, isScreenFilled, requestFullScreen, exitFullScreen, isFullScreenMode, onFullScreenChange, offFullScreenChange, isJsonObject, arraySortPositions, formatBytes, addAiMarkerShortcut, extendObjType, reorderObjTypeOrder, cloneObjTypeOrder, countObj, objType, ruleOfThree, getSimplePerc, asyncReplace, getAge, formatCustomTimer, formatDayTimer, formatTimer, getTimeDuration, shuffleArray, toTitleCase, toTitleCaseLowerFirst, };
+export { multiplyArrayBlocks, valMediaContentMetadata, valMediaContentMetadataPartial, parseMediaMetadata, extractMediaId3Tags, diffStrings, diffObjList, diffArrayList, breakdownDuration, calculateMarketcap, compareMarketcap, getPercentage, areElsCollTop, areElsCollBottom, areElsCollLeft, areElsCollRight, areElsCollPerfTop, areElsCollPerfBottom, areElsCollPerfLeft, areElsCollPerfRight, areElsColliding, areElsPerfColliding, getElsColliding, getElsPerfColliding, getElsCollOverlap, getElsCollOverlapPos, getRectCenter, getElsRelativeCenterOffset, getElsCollDirDepth, getElsCollDetails, safeTextTrim, installWindowHiddenScript, genFibonacciSeq, fetchJson, fetchText, readJsonBlob, readFileBlob, readBase64Blob, saveJsonFile, documentIsFullScreen, isScreenFilled, requestFullScreen, exitFullScreen, isFullScreenMode, onFullScreenChange, offFullScreenChange, isJsonObject, arraySortPositions, formatBytes, addAiMarkerShortcut, extendObjType, reorderObjTypeOrder, cloneObjTypeOrder, countObj, objType, ruleOfThree, getSimplePerc, asyncReplace, getAge, formatCustomTimer, formatDayTimer, formatTimer, getTimeDuration, shuffleArray, toTitleCase, toTitleCaseLowerFirst, };