tuijs-util 1.2.2 → 1.3.0

package/src/cjs/index.cjs

@@ -1,86 +1,143 @@
 'use strict';
 
-// Checks for a valid FQDN (uses regex)
-function checkFqdn(str) {
-  if (typeof str !== "string" || str.length === 0 || str.length > 253) {
-    return false;
+/**
+ * List of RegEx variables for different patterns.
+*/
+const regExLetters = /^[a-zA-Z]+$/;
+const regExLettersLower = /^[a-z]+$/;
+const regExLettersUpper = /^[A-Z]+$/;
+const regExNumbers = /^\d+$/;
+const regExBinary = /^[01]+$/;
+const regExHexadecimal = /^[0-9A-Fa-f]+$/;
+const regExSpecial = /^[\!\@\#\$\%\^\&\*\(\)\_\+\-\=\[\]\{\}\|\;\:\'\"\,\.\<\>\/\?\`\\\~]+$/;
+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,}))$/;
+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
+const regExEmail = /^[\w-\.]+@([\w-]+\.)+[a-zA-Z]{2,}$/;
+
+/**
+ * Removes characters from a string based on a provided regex pattern.
+ * @param {string} string The string to process.
+ * @param {RegExp} regex The regex pattern of characters to remove from the string.
+ * @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.
+ */
+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);
   }
-  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)
-function checkUrl(str) {
+/**
+ * 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.
+ */
+function checkFqdn(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 regExFqdn.test(string);
   } catch (er) {
-    throw new Error(er);
+    throw new Error(er.message);
   }
 }
 
-// Checks for special characters (Returns true if it matches)
-function checkSpecialChar(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.
+ */
+function checkUrl(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 regExUrl.test(string); // Returns false if the url is invalid
   } catch (er) {
-    throw new Error(er);
+    throw new Error(er.message);
   }
 }
 
-// Checks for a valid Email (uses regex)
-function checkEmail(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.
+ */
+function checkSpecialChar(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 regExSpecial.test(string);
+  } catch (er) {
+    throw new Error(er.message);
+  }
+}
+
+/**
+ * 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.
+ */
+function checkEmail(string) {
+  try {
+    if (typeof string !== 'string' || string.length === 0) {
+      return false;
     }
-    return false;
+    ;
+    return regExEmail.test(string);
   } catch (er) {
-    throw new Error(er);
+    throw new Error(er.message);
   }
 }
 
-// Checks for a space in a string
-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.
+ */
+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
+ */
 function checkIsList(input) {
   try {
     // Check if the variable is a string
@@ -98,29 +155,43 @@ 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.
+ */
 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.
  */
 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.
+ */
 function checkIsJson(input) {
   try {
     JSON.parse(input);
@@ -130,59 +201,88 @@ function checkIsJson(input) {
   }
 }
 
-// Checks for number values in a string (Returns true if it matches)
-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.
+ */
+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)
-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.
+ */
+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)
-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.
+ */
+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 regExLettersUpper.test(string);
+  } catch (er) {
+    throw new Error(er.message);
+  }
+}
+
+/**
+ * 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.
+ */
+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 false;
+    return template.content;
   } catch (er) {
-    throw new Error(er);
+    throw new Error(er.message);
   }
 }
 
 /**
- * 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 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.
  */
 function elmCleaner(templateLit) {
   try {
@@ -191,13 +291,18 @@ 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
  */
 function elmCleanerTr(templateLit) {
   try {
@@ -207,13 +312,18 @@ 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
  */
 function elmCleanerArray(templateLit) {
   try {
@@ -222,98 +332,109 @@ function elmCleanerArray(templateLit) {
     let elms = elmBody.body.querySelectorAll("*");
     return Array.from(elms);
   } catch (er) {
-    console.error(er);
-    throw new Error(er);
+    throw new Error(er.message);
   }
 }
 
 /**
- * Parses template literal with 'template' tag
+ * 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.
  */
-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);
-  }
-}
-
-// Adds 'http://' if valid URL
 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.
+ */
 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
-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.
+ */
+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.
+ */
 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.
+ */
 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: {
@@ -322,15 +443,18 @@ 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
+ */
 async function reqPostForm(url, dataForm) {
   try {
     if (!(dataForm instanceof FormData)) {
@@ -351,34 +475,60 @@ async function reqPostForm(url, dataForm) {
 
 const htmlTags = ["html", "body", "div", "span", "applet", "object", "iframe", "h1", "h2", "h3", "h4", "h5", "h6", "p", "blockquote", "pre", "a", "abbr", "acronym", "address", "big", "cite", "code", "del", "dfn", "em", "img", "ins", "kbd", "q", "s", "samp", "small", "strike", "strong", "sub", "sup", "tt", "var", "b", "u", "i", "center", "dl", "dt", "dd", "ol", "ul", "li", "fieldset", "form", "label", "legend", "table", "caption", "tbody", "tfoot", "thead", "tr", "th", "td", "article", "aside", "canvas", "details", "embed", "figure", "figcaption", "footer", "header", "hgroup", "menu", "nav", "output", "ruby", "section", "summary", "time", "mark", "audio", "video"];
 
-// 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.
+ */
 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.
  */
-function generateUID() {
-  return 'uid-' + Date.now().toString(36) + '-' + Math.random().toString(36).substr(2);
+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.
  */
 function preloadImages(imgUrls) {
   imgUrls.forEach(url => {
     const img = new Image();
     img.src = url;
+    img.onerror = () => {
+      throw new Error(`Failed to load image: ${url}`);
+    };
   });
 }
 
@@ -391,36 +541,7 @@ function sleep(ms) {
   return new Promise(resolve => setTimeout(resolve, ms));
 }
 
-/**
- * List of RegEx variables for different patterns.
-*/
-const letters = /^[a-zA-Z]+$/;
-const lettersLower = /^[a-z]+$/;
-const lettersUpper = /^[A-Z]+$/;
-const numbers = /^\d+$/;
-const binary = /[^01]/g;
-const hexadecimal = /[^0-9A-Fa-f]/g;
-const special = /^[\!\@\#\$\%\^\&\*\(\)\_\+\-\=\[\]\{\}\|\;\'\:\"\,\.\<\>\?\/]+$/;
-
-/**
- * Removes characters from a string based on a provided regex pattern.
- * @param {string} string The string to process.
- * @param {RegExp} regex The regex pattern of characters to remove from the string.
- * @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.
- */
-function removeChar(string, regex) {
-  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, '');
-}
-
 exports.addLeadZero = addLeadZero;
-exports.binary = binary;
 exports.checkEmail = checkEmail;
 exports.checkFqdn = checkFqdn;
 exports.checkIsArray = checkIsArray;
@@ -437,20 +558,24 @@ exports.elmCleaner = elmCleaner;
 exports.elmCleanerArray = elmCleanerArray;
 exports.elmCleanerTr = elmCleanerTr;
 exports.generateUID = generateUID;
-exports.hexadecimal = hexadecimal;
 exports.htmlTags = htmlTags;
-exports.letters = letters;
-exports.lettersLower = lettersLower;
-exports.lettersUpper = lettersUpper;
-exports.numbers = numbers;
 exports.parseTemplate = parseTemplate;
 exports.preloadImages = preloadImages;
+exports.regExBinary = regExBinary;
+exports.regExEmail = regExEmail;
+exports.regExFqdn = regExFqdn;
+exports.regExHexadecimal = regExHexadecimal;
+exports.regExLetters = regExLetters;
+exports.regExLettersLower = regExLettersLower;
+exports.regExLettersUpper = regExLettersUpper;
+exports.regExNumbers = regExNumbers;
+exports.regExSpecial = regExSpecial;
+exports.regExUrl = regExUrl;
 exports.removeChar = removeChar;
 exports.reqFileJson = reqFileJson;
 exports.reqGet = reqGet;
 exports.reqPostForm = reqPostForm;
 exports.reqPostJson = reqPostJson;
 exports.sleep = sleep;
-exports.special = special;
 exports.urlAddHttp = urlAddHttp;
 exports.urlAddHttps = urlAddHttps;