tuijs-util 1.2.2 → 1.3.0

package/src/esm/index.js

@@ -36,13 +36,16 @@ export {
     sleep
 } from './lib/util.misc.js';
 export {
-    binary,
-    hexadecimal,
-    letters,
-    lettersLower,
-    lettersUpper,
-    numbers,
-    removeChar,
-    special
+    regExLetters,
+    regExLettersLower,
+    regExLettersUpper,
+    regExNumbers,
+    regExBinary,
+    regExHexadecimal,
+    regExSpecial,
+    regExFqdn,
+    regExUrl,
+    regExEmail,
+    removeChar
 } from './lib/util.regex.js';
 

package/src/esm/lib/util.check.js

@@ -1,80 +1,95 @@
-// Checks for a valid FQDN (uses regex)
-export function checkFqdn(str) {
-    if (typeof str !== "string" || str.length === 0 || str.length > 253) {
-        return false;
+import { regExNumbers, regExLettersLower, regExLettersUpper, regExSpecial, regExFqdn, regExUrl, regExEmail } from "./util.regex";
+
+/**
+ * Checks for a valid FQDN (Uses RegEx).
+ * @param {string} string 
+ * @returns {boolean} - Returns true if test is successful and false if the string is not validated or the RegEx test fails.
+ * @throws {Error} - Throws error message if error occurs.
+ */
+export function checkFqdn(string) {
+    try {
+        if (typeof string !== 'string' || string.length === 0) {
+            return false;
+        }
+        return regExFqdn.test(string);
+    } catch (er) {
+        throw new Error(er.message);
     }
-    var pattern = /^(?=.{1,253}$)(([a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?\.)+([a-zA-Z]{2,}|[a-zA-Z0-9-]{2,}))$/;
-    return pattern.test(str);
 }
 
-// Checks for a valid URL (uses regex)
-export function checkUrl(str) {
+
+/**
+ * Checks for a valid URL (Uses RegEx).
+ * @param {string} string 
+ * @returns {boolean} - Returns true if test is successful and false if the string is not validated or the RegEx test fails.
+ * @throws {Error} - Throws error message if error occurs.
+ */
+export function checkUrl(string) {
     try {
-        if (str === null || typeof str !== "string") {
-            throw new Error(`Invalid input.`);
+        if (typeof string !== 'string' || string.length === 0) {
+            return false;
         };
-        var pattern = new RegExp('^(https?:\\/\\/)?' + // protocol
-            '((([a-z\\d]([a-z\\d-]*[a-z\\d])*)\\.)+[a-z]{2,}|' + // domain name
-            '((\\d{1,3}\\.){3}\\d{1,3}))' + // OR ip (v4) address
-            '(\\:\\d+)?(\\/[-a-z\\d%_.~+]*)*' + // port and path
-            '(\\?[;&a-z\\d%_.~+=-]*)?' + // query string
-            '(\\#[-a-z\\d_]*)?$', 'i'); // fragment locator
-        return !!pattern.test(str); // Returns false if the url is invalid
+        return regExUrl.test(string); // Returns false if the url is invalid
     } catch (er) {
-        throw new Error(er);
+        throw new Error(er.message);
     }
 }
 
-// Checks for special characters (Returns true if it matches)
-export function checkSpecialChar(str) {
+/**
+ * Checks for special characters (Uses RegEx).
+ * @param {string} string 
+ * @returns {boolean} - Returns true if a special character is found and false if the string is not validated or the RegEx test fails.
+ * @throws {Error} - Throws error message if error occurs.
+ */
+export function checkSpecialChar(string) {
     try {
-        if (str === null || typeof str !== "string") {
-            throw new Error(`Invalid input.`);
+        if (typeof string !== 'string' || string.length === 0) {
+            return false;
         };
-        const regSp = /[\!\@\#\$\%\^\&\*\(\)\_\+\=\[\]\{\}\?]/;
-        if (regSp.test(str) == true) {
-            return true;
-        }
-        return false;
+        return regExSpecial.test(string);
     } catch (er) {
-        throw new Error(er);
+        throw new Error(er.message);
     }
 }
 
 /**
- * Determines if an input string is a valid email address using RegEx.
- * @param {string} str - String input
- * @returns {boolean} - Return false if the string is not an email and true if it is.
- * @throws {Error} - Throws Error if input is not a string or if another error occurs.
+ * Checks for a valid email address. (Uses RegEx).
+ * @param {string} string 
+ * @returns {boolean} - Returns true if email pattern test is successful and false if the string is not validated or the RegEx test fails.
+ * @throws {Error} - Throws error message if error occurs.
  */
-export function checkEmail(str) {
+export function checkEmail(string) {
     try {
-        if (str === null || typeof str !== 'string') {
-            throw new Error(`Invalid input.`);
+        if (typeof string !== 'string' || string.length === 0) {
+            return false;
         };
-        var validRegex = /^[\w-\.]+@([\w-]+\.)+[\w-]{2,4}$/;
-        if (str.match(validRegex)) {
-            return true;
-        }
-        return false;
+        return regExEmail.test(string);
     } catch (er) {
         throw new Error(er.message);
     }
 }
 
-// Checks for a space in a string
-export function checkSpaces(str) {
+/**
+ * Checks for a space in a string
+ * @param {string} string 
+ * @returns {boolean} - Returns true if space is found and false if the string is not validated or if a space is not found.
+ * @throws {Error} - Throws error message if error occurs.
+ */
+export function checkSpaces(string) {
     try {
-        if (str === null || typeof str !== "string") {
-            throw new Error(`Invalid input.`);
+        if (typeof string !== 'string' || string.length === 0) {
+            return false;
         };
         return str.indexOf(' ') >= 0;
     } catch (er) {
-        throw new Error(er);
+        throw new Error(er.message);
     }
 }
 
 // Check for a list of text???
+/**
+ * IN WORK
+ */
 export function checkIsList(input) {
     try {
         // Check if the variable is a string
@@ -92,31 +107,43 @@ export function checkIsList(input) {
         }
         return true;
     } catch (er) {
-        throw new Error(er);
+        throw new Error(er.message);
     }
 }
 
+/**
+ * Checks an input to determine if it is an Array.
+ * @param {*} input 
+ * @returns {boolean} - Returns true if the input is an Array and false if not.
+ * @throws {Error} - Throws error message if error occurs.
+ */
 export function checkIsArray(input) {
     try {
         return input.constructor === Array;
     } catch (er) {
-        throw new Error(er);
+        throw new Error(er.message);
     }
 }
 
 /**
- * Checks if an input value is an object.
- * @param {*} input - Any variable
- * @returns {boolean}
+ * Checks an input to determine if it is an Object.
+ * @param {*} input 
+ * @returns {boolean} - Returns true if the input is an Object and false if not.
+ * @throws {Error} - Throws error message if error occurs.
  */
 export function checkIsObject(input) {
     try {
         return input.constructor === Object;
     } catch (er) {
-        throw new Error(er);
+        throw new Error(er.message);
     }
 }
 
+/**
+ * Checks an input to determine if it is valid JSON.
+ * @param {*} input 
+ * @returns {boolean} - Returns true if the input is valid JSON and false if not.
+ */
 export function checkIsJson(input) {
     try {
         JSON.parse(input);
@@ -126,51 +153,53 @@ export function checkIsJson(input) {
     }
 }
 
-
-// Checks for number values in a string (Returns true if it matches)
-export function checkNum(str) {
+/**
+ * Checks for number values in a string (Uses RegEx)
+ * @param {string} string 
+ * @returns {boolean} - Returns true if a number is found and false if not.
+ * @throws {Error} - Throws error message if error occurs.
+ */
+export function checkNum(string) {
     try {
-        if (str === null || typeof str !== "string") {
-            throw new Error(`Invalid input.`);
+        if (typeof string !== 'string' || string.length === 0) {
+            return false;
         };
-        const regNm = /[0-9]/;
-        if (regNm.test(str) === true) {
-            return true;
-        }
-        return false;
+        return regExNumbers.test(string);
     } catch (er) {
-        throw new Error(er);
+        throw new Error(er.message);
     }
 }
 
-// Checks for lowercase characters (Returns true if it matches)
-export function checkLowercase(str) {
+/**
+ * Checks for lowercase characters (Uses RegEx)
+ * @param {string} string 
+ * @returns {boolean} - Returns true if a lowercase character is found and false if not.
+ * @throws {Error} - Throws error message if error occurs.
+ */
+export function checkLowercase(string) {
     try {
-        if (str === null || typeof str !== "string") {
-            throw new Error(`Invalid input.`);
+        if (typeof string !== 'string' || string.length === 0) {
+            return false;
         };
-        const regLo = /[a-z]/;
-        if (regLo.test(str) == true) {
-            return true;
-        }
-        return false;
+        return regExLettersLower.test(string);
     } catch (er) {
-        throw new Error(er);
+        throw new Error(er.message);
     }
 }
 
-// Checks for uppercase characters (Returns true if it matches)
-export function checkUppercase(str) {
+/**
+ * Checks for uppercase characters (Uses RegEx)
+ * @param {string} string 
+ * @returns {boolean} - Returns true if a uppercase character is found and false if not.
+ * @throws {Error} - Throws error message if error occurs.
+ */
+export function checkUppercase(string) {
     try {
-        if (str === null || typeof str !== "string") {
-            throw new Error(`Invalid input.`);
+        if (typeof string !== 'string' || string.length === 0) {
+            return false;
         };
-        const regUp = /[A-Z]/;
-        if (regUp.test(str) == true) {
-            return true;
-        }
-        return false;
+        return regExLettersUpper.test(string);
     } catch (er) {
-        throw new Error(er);
+        throw new Error(er.message);
     }
 }

package/src/esm/lib/util.dom.js

@@ -1,5 +1,31 @@
 /**
- * Takes an HTML template literal, parses it with the DOM parser, then extracts the element with querySelectorAll.
+ * Takes an HTML template literal, parses it, then extracts it.
+ * All elements in the template MUST be contained within a single set of template tags.
+ * THIS IS THE RECOMMENDED PARSER TO USE.
+ * @param {string} templateLit - An HTML string containing a <template> tag.
+ * @returns {DocumentFragment} - Returns a DocumentFragment which has been parsed and queried.
+ * @throws {Error} - Throws error message if error occurs.
+ */
+export function parseTemplate(templateLit) {
+    try {
+        let parser = new DOMParser();
+        let doc = parser.parseFromString(templateLit, 'text/html');
+        let template = doc.querySelector('template');
+        if (!template) {
+            throw new Error('No template tag found in the provided string.');
+        }
+        return template.content;
+    } catch (er) {
+        throw new Error(er.message);
+    }
+}
+
+/**
+ * Takes an HTML template literal, parses it, then extracts the element.
+ * All elements in the template MUST be contained within a single parent element.
+ * @param {string} templateLit 
+ * @returns {Element} - Returns a element Object which has been parsed and queried.
+ * @throws {Error} - Throws error message if error occurs.
  */
 export function elmCleaner(templateLit) {
     try {
@@ -8,13 +34,18 @@ export function elmCleaner(templateLit) {
         let elms = elmBody.body.querySelectorAll("*");
         return elms[0];
     } catch (er) {
-        console.error(er);
-        throw new Error(er);
+        throw new Error(er.message);
     }
 }
 
 /**
- * Takes an HTML table row template literal, parses it with the DOM parser, then extracts the element with querySelectorAll.
+ * Takes an HTML table row template literal, parses it, then extracts the element.
+ * @param {string} templateLit 
+ * @returns {Element} - Returns a element Object which has been parsed and queried.
+ * @throws {Error} - Throws error message if error occurs.
+ */
+/**
+ * IN WORK
  */
 export function elmCleanerTr(templateLit) {
     try {
@@ -24,13 +55,18 @@ export function elmCleanerTr(templateLit) {
         elmTemp.remove();
         return elms;
     } catch (er) {
-        console.error(er);
-        throw new Error(er);
+        throw new Error(er.message);
     }
 }
 
 /**
  * Takes an HTML template literal, parses it with the DOM parser, then extracts the NodeList. The list is then returned as an array.
+ * @param {string} templateLit 
+ * @returns {Element} - Returns a element Object which has been parsed and queried.
+ * @throws {Error} - Throws error message if error occurs.
+ */
+/**
+ * IN WORK
  */
 export function elmCleanerArray(templateLit) {
     try {
@@ -39,25 +75,6 @@ export function elmCleanerArray(templateLit) {
         let elms = elmBody.body.querySelectorAll("*");
         return Array.from(elms);
     } catch (er) {
-        console.error(er);
-        throw new Error(er);
-    }
-}
-
-/**
- * Parses template literal with 'template' tag
- */
-export function parseTemplate(templateLit) {
-    try {
-        let parser = new DOMParser();
-        let doc = parser.parseFromString(templateLit, 'text/html');
-        let template = doc.querySelector('template');
-        if (!template) {
-            throw new Error('No template tag found in the provided string.');
-        }
-        return template.content;
-    } catch (er) {
-        console.error(er);
-        throw new Error(er);
+        throw new Error(er.message);
     }
 }

package/src/esm/lib/util.http.js

@@ -1,70 +1,100 @@
-import { checkUrl } from './util.check.js';
+import { checkUrl, checkIsJson } from './util.check.js';
 
-// Adds 'http://' if valid URL
+/**
+ * Adds 'http://' if valid URL and 'http://' or 'https://' is missing.
+ * @param {string} url 
+ * @returns {string} - Returns an updated url string if necessary or returns the same string if url already starts with 'http://' or 'https://'.
+ * @throws {Error} - Throws Error if an error is detected.
+ */
 export function urlAddHttp(url) {
     try {
         if (url === null || !checkUrl(url)) {
-            throw `Invalid input.`;
+            throw new Error(`Invalid input.`);
         };
-        if (url.startsWith("http://") == false && url.startsWith("https://") == false) {
+        if (url.startsWith("http://") === false && url.startsWith("https://") === false) {
             url = "http://" + url
         }
         return url;
     } catch (er) {
-        throw new Error(er);
+        throw new Error(er.message);
     }
 }
 
-// Adds 'https://' if valid URL
+/**
+ * Adds 'https://' if valid URL and 'http://' or 'https://' is missing.
+ * @param {string} url 
+ * @returns {string} - Returns an updated url string if necessary or returns the same string if url already starts with 'http://' or 'https://'.
+ * @throws {Error} - Throws Error if an error is detected.
+ */
 export function urlAddHttps(url) {
     try {
         if (url === null || !checkUrl(url)) {
-            throw `Invalid input.`;
+            throw new Error(`Invalid input.`);
         };
-        if (url.startsWith("http://") == false && url.startsWith("https://") == false) {
+        if (url.startsWith("http://") === false && url.startsWith("https://") === false) {
             url = "https://" + url
         }
         return url;
     } catch (er) {
-        throw new Error(er);
+        throw new Error(er.message);
     }
 }
 
-// Simple read JSON file utility
-export async function reqFileJson(file) {
+/**
+ * Collects and parses data from a JSON file
+ * @async
+ * @param {string} filePath
+ * @returns {Promise<Object>} - Returns data if response is ok, otherwise it throws an Error.
+ * @throws {Error} - Throws Error if an error is detected.
+ */
+export async function reqFileJson(filePath) {
     try {
-        const res = await fetch(file);
+        const res = await fetch(filePath);
         if (!res.ok) {
-            return res;
+            throw new Error(res);
         }
         const data = await res.json();
         return data;
     } catch (er) {
-        throw new Error(er);
+        throw new Error(er.message);
     }
 }
 
-// Simple GET request - This is expecting JSON data from the target URL
+/**
+ * Sends GET request to specified URL
+ * @async
+ * @param {string} url
+ * @returns {Promise<Object>} - Returns response if response is ok, otherwise it throws an Error.
+ * @throws {Error} - Throws Error if an error is detected.
+ */
 export async function reqGet(url) {
     try {
         const res = await fetch(url, { method: 'GET' });
         if (!res.ok) {
-            throw res;
+            throw new Error(res);
         }
         return res;
     } catch (er) {
-        throw er;
+        throw new Error(er.message);
     }
 }
 
-// Simple POST request. export function is expecting JSON data. The JSON.parse will throw an error if data is not valid JSON.
-// NEEDS REVIEW
+/**
+ * Sends POST request to specified URL, which contains JSON data in the body.
+ * @async
+ * @param {string} url
+ * @param {JSON} dataJson
+ * @returns {Promise<Object>} - Returns response if response is ok, otherwise it throws an Error.
+ * @throws {Error} - Throws Error if an error is detected.
+ */
 export async function reqPostJson(url, dataJson) {
     try {
         if (dataJson === null || dataJson === undefined) {
-            throw `No JSON data provided`;
+            throw new Error(`No data provided.`);
+        }
+        if (!checkIsJson(dataJson)) {
+            throw new Error(`Provided data is not JSON.`);
         }
-        JSON.parse(dataJson);
         const res = await fetch(url, {
             method: 'POST',
             headers: {
@@ -73,15 +103,18 @@ export async function reqPostJson(url, dataJson) {
             body: dataJson
         });
         if (!res.ok) {
-            return res;
+            throw new Error(res);
         }
         return res;
     } catch (er) {
-        throw new Error(er);
+        throw new Error(er.message);
     }
 }
+
 // Simple POST request. export function is expecting FormData.
-// NEEDS REVIEW
+/**
+ * IN WORK
+ */
 export async function reqPostForm(url, dataForm) {
     try {
         if (!(dataForm instanceof FormData)) {

package/src/esm/lib/util.misc.js

@@ -1,30 +1,55 @@
-// Adds zero in front of numbers less than 10
+/**
+ * Adds zero in front of numbers less than 10 and returns as a string.
+ * @param {number} num 
+ * @returns {string}
+ * @throws {Error} - Throws Error if an error is detected.
+ */
 export function addLeadZero(num) {
     try {
         if (num === null || typeof num !== 'number' || num > 9) {
-            throw `Invalid input.`;
+            throw new Error(`Invalid input.`);
         };
-        num = "0" + num;
+        return "0" + num;;
     } catch (er) {
-        console.error(er);
-        throw new Error(er);
+        throw new Error(er.message);
     }
 }
 
 /**
  * Generates a unique ID
+ * @param {number} [length=16] - The number of characters for the random part of the ID.
+ * @returns {string}
+ * @throws {Error} - Throws Error if input is invalid or another error is detected.
  */
-export function generateUID() {
-    return 'uid-' + Date.now().toString(36) + '-' + Math.random().toString(36).substr(2);
+export function generateUID(length = 16) {
+    try {
+        if (typeof length !== 'number' || length <= 0) {
+            throw new Error(`Invalid input. The 'length' parameter must be a positive number.`);
+        }
+        const timestampPart = Date.now().toString(36);
+        const randomPart = Math.random().toString(36).slice(2, 2 + length);
+        return 'uid-' + timestampPart + '-' + randomPart;
+    } catch (er) {
+        throw new Error(er.message);
+    }
 }
 
 /**
- * Preloads images. Requires an array of image URL strings.
+ * @typedef {string[]} ImgUrls - An array of URL strings
+ */
+/**
+ * Preloads images in cache.
+ * @param {ImgUrls} imgUrls - An array of URL strings
+ * @returns {void}
+ * @throws {Error} - Throws an Error if loading an image fails.
  */
 export function preloadImages(imgUrls) {
     imgUrls.forEach(url => {
         const img = new Image();
         img.src = url;
+        img.onerror = () => {
+            throw new Error(`Failed to load image: ${url}`);
+        };
     });
 }
 

package/src/esm/lib/util.regex.js

@@ -1,13 +1,21 @@
 /**
  * List of RegEx variables for different patterns.
 */
-export const letters = /^[a-zA-Z]+$/;
-export const lettersLower = /^[a-z]+$/;
-export const lettersUpper = /^[A-Z]+$/;
-export const numbers = /^\d+$/;
-export const binary = /[^01]/g;
-export const hexadecimal = /[^0-9A-Fa-f]/g;
-export const special = /^[\!\@\#\$\%\^\&\*\(\)\_\+\-\=\[\]\{\}\|\;\'\:\"\,\.\<\>\?\/]+$/;
+export const regExLetters = /^[a-zA-Z]+$/;
+export const regExLettersLower = /^[a-z]+$/;
+export const regExLettersUpper = /^[A-Z]+$/;
+export const regExNumbers = /^\d+$/;
+export const regExBinary = /^[01]+$/;
+export const regExHexadecimal = /^[0-9A-Fa-f]+$/;
+export const regExSpecial = /^[\!\@\#\$\%\^\&\*\(\)\_\+\-\=\[\]\{\}\|\;\:\'\"\,\.\<\>\/\?\`\\\~]+$/;
+export const regExFqdn = /^(?=.{1,253}$)(([a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?\.)+([a-zA-Z]{2,}|[a-zA-Z0-9-]{2,}))$/;
+export const regExUrl = new RegExp('^(https?:\\/\\/)?' + // protocol
+    '((([a-z\\d]([a-z\\d-]*[a-z\\d])*)\\.)+[a-z]{2,}|' + // domain name
+    '((\\d{1,3}\\.){3}\\d{1,3}))' + // OR ip (v4) address
+    '(\\:\\d+)?(\\/[-a-z\\d%_.~+]*)*' + // port and path
+    '(\\?[;&a-z\\d%_.~+=-]*)?' + // query string
+    '(\\#[-a-z\\d_]*)?$', 'i'); // fragment locator
+export const regExEmail = /^[\w-\.]+@([\w-]+\.)+[a-zA-Z]{2,}$/;
 
 /**
  * Removes characters from a string based on a provided regex pattern.
@@ -16,12 +24,16 @@ export const special = /^[\!\@\#\$\%\^\&\*\(\)\_\+\-\=\[\]\{\}\|\;\'\:\"\,\.\<\>
  * @return {string} The processed string with specified characters removed.
  * @throws {Error} Throws an error if the first parameter is not a string or if the second parameter is not a RegExp.
  */
-export function removeChar(string, regex) {
-    if (typeof string !== 'string') {
-        throw new Error(`First parameter must be a string.`);
+export function removeChar(string, regEx) {
+    try {
+        if (typeof string !== 'string') {
+            throw new Error(`First parameter must be a string.`);
+        }
+        if (!(regEx instanceof RegExp)) {
+            throw new Error(`Second parameter must be a RegExp.`);
+        }
+        return string.replace(regEx, '');
+    } catch (er) {
+        throw new Error(er.message);
     }
-    if (!(regex instanceof RegExp)) {
-        throw new Error(`Second parameter must be a RegExp.`);
-    }
-    return string.replace(regex, '');
 }