tiny-essentials 1.28.19 → 1.29.0

package/dist/v1/regexp/Email.mjs

@@ -0,0 +1,153 @@
+/**
+ * A function type used to define custom validation logic for an email address.
+ * @typedef {(email: string) => boolean} EmailValidatorFn
+ */
+/**
+ * Configuration options for customizing email regex patterns and validation rules.
+ * @typedef {Object} EmailRegexOptions
+ * @property {string} [validName] - The regular expression pattern used to match the username portion of the email.
+ * @property {string} [validDomain] - The regular expression pattern used to match the domain portion of the email.
+ * @property {string[]} [blacklistDomains] - An array of domain strings that are explicitly forbidden during validation.
+ * @property {string[]} [whitelistDomains] - An array of domain strings that are the only permitted domains.
+ * @property {string[]} [blacklistUsernames] - An array of username strings that are explicitly forbidden during validation.
+ * @property {string[]} [whitelistUsernames] - An array of username strings that are the only permitted usernames.
+ * @property {EmailValidatorFn} [customValidator] - A callback function that receives the email string and returns a boolean to perform custom validation logic.
+ */
+/**
+ * Validates the EmailRegexOptions object to ensure all properties match the required types.
+ * This is a private helper used to maintain strict type safety at runtime.
+ *
+ * @param {EmailRegexOptions} options - The configuration options to validate.
+ * @throws {TypeError} If the options are not an object or if any property fails type validation.
+ * @private
+ */
+const validateEmailRegexOptions = (options) => {
+    if (options === undefined)
+        return;
+    if (typeof options !== 'object' || options === null || Array.isArray(options)) {
+        throw new TypeError('Options must be an object.');
+    }
+    /**
+     * Helper to validate if a property is an array of strings.
+     * @param {any} arr - The array to validate.
+     * @param {string} name - The name of the property for the error message.
+     * @private
+     */
+    const validateArray = (arr, name) => {
+        if (arr !== undefined) {
+            if (!Array.isArray(arr)) {
+                throw new TypeError(`${name} must be an array.`);
+            }
+            for (let i = 0; i < arr.length; i++) {
+                if (typeof arr[i] !== 'string') {
+                    throw new TypeError(`All elements in ${name} must be strings.`);
+                }
+            }
+        }
+    };
+    validateArray(options.blacklistDomains, 'blacklistDomains');
+    validateArray(options.whitelistDomains, 'whitelistDomains');
+    validateArray(options.blacklistUsernames, 'blacklistUsernames');
+    validateArray(options.whitelistUsernames, 'whitelistUsernames');
+    if (options.customValidator !== undefined && typeof options.customValidator !== 'function') {
+        throw new TypeError('customValidator must be a function.');
+    }
+};
+/**
+ * Constructs a email regular expression pattern string based on the provided configuration options.
+ * @param {EmailRegexOptions} [options] - The configuration options.
+ * @returns {string} The generated regex pattern string.
+ */
+export const emailStringRegexBuilder = (options = {}) => {
+    validateEmailRegexOptions(options);
+    const { validName = '[a-zA-Z0-9._%+-]+', validDomain = '[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}' } = options;
+    return `${validName}@${validDomain}`;
+};
+/**
+ * Creates a RegExp object anchored to the start and end of the string using the provided configuration.
+ * @param {EmailRegexOptions} [options] - The configuration options.
+ * @returns {RegExp} The resulting RegExp object.
+ */
+export function emailRegex(options) {
+    return new RegExp(`^${emailStringRegexBuilder(options)}$`);
+}
+/**
+ * Performs deep validation of an email string against specified whitelist and blacklist rules for domains and usernames.
+ *
+ * @param {string} s - The string to validate.
+ * @param {EmailRegexOptions} [options={}] - The configuration options.
+ * @returns {boolean} True if the string is a valid email, false otherwise.
+ * @throws {TypeError} If the input string is not a string.
+ */
+function verifyEmail(s, options = {}) {
+    // Runs custom validation if provided
+    if (typeof options.customValidator === 'function' && !options.customValidator(s)) {
+        return false;
+    }
+    // Since the regex matched, we can safely split the string into username and domain.
+    const [username, domain] = s.split('@');
+    // Whitelist checks: If a whitelist exists, the value MUST be in it.
+    if (Array.isArray(options.whitelistDomains) &&
+        options.whitelistDomains.length > 0 &&
+        !options.whitelistDomains.includes(domain)) {
+        return false;
+    }
+    if (Array.isArray(options.whitelistUsernames) &&
+        options.whitelistUsernames.length > 0 &&
+        !options.whitelistUsernames.includes(username)) {
+        return false;
+    }
+    // Blacklist checks: If a blacklist exists, the value MUST NOT be in it.
+    if (Array.isArray(options.blacklistDomains) &&
+        options.blacklistDomains.length > 0 &&
+        options.blacklistDomains.includes(domain)) {
+        return false;
+    }
+    if (Array.isArray(options.blacklistUsernames) &&
+        options.blacklistUsernames.length > 0 &&
+        options.blacklistUsernames.includes(username)) {
+        return false;
+    }
+    return true;
+}
+/**
+ * Validates whether a given string matches the specified email pattern,
+ * respects blacklist/whitelist rules, and passes a custom validator if provided.
+ * @param {string} s - The string to validate.
+ * @param {EmailRegexOptions} [options={}] - The configuration options.
+ * @param {RegExp} [regex] - The regex used to execute the function.
+ * @returns {boolean} True if the string is a valid email, false otherwise.
+ * @throws {TypeError} If the input string is not a string.
+ */
+export function isValidEmail(s, options = {}, regex) {
+    if (typeof s !== 'string') {
+        throw new TypeError('The input must be a string.');
+    }
+    const pattern = regex ?? emailRegex(options);
+    if (!pattern.test(s)) {
+        return false;
+    }
+    return verifyEmail(s, options);
+}
+/**
+ * Generates a global RegExp object used to find all occurrences of URLs within a text.
+ * @param {EmailRegexOptions} [options] - The configuration options.
+ * @returns {RegExp} The resulting global RegExp object.
+ */
+export function findEmailRegex(options) {
+    return new RegExp(`\\b${emailStringRegexBuilder(options)}\\b`, 'g');
+}
+/**
+ * Extracts all matching email strings from a given text using the provided configuration.
+ * @param {string} text - The text to search.
+ * @param {EmailRegexOptions} [options] - The configuration options.
+ * @param {RegExp} [regex] - The regex used to execute the function.
+ * @returns {string[]} An array of matches or null if no matches are found.
+ * @throws {TypeError} If the input text is not a string.
+ */
+export function extractEmails(text, options, regex) {
+    if (typeof text !== 'string') {
+        throw new TypeError('The input must be a string.');
+    }
+    return text.match(regex ?? findEmailRegex(options))?.filter((s) => verifyEmail(s, options)) ?? [];
+}

package/dist/v1/regexp/Glob.cjs

@@ -0,0 +1,293 @@
+'use strict';
+
+/**
+ * A highly professional utility to convert GLOB patterns into JavaScript RegExp objects,
+ * and decompile them back into GLOB strings.
+ *
+ * Supports standard features: '*', '**', '?', '[...]', '[!...]', '{a,b}', and '\' escaping.
+ */
+
+/**
+ * Compiles a GLOB string pattern into a RegExp object.
+ *
+ * @param {string|string[]} globData - The GLOB pattern to compile.
+ * @property {boolean} [strict=true] - If true, throws SyntaxError on unbalanced brackets or braces.
+ * @returns {string[]} The resulting regular expression parsed into string array.
+ * @throws {TypeError} If globPattern or flags are not strings.
+ * @throws {SyntaxError} If the pattern has unmatched groups and strict mode is enabled.
+ */
+const compileGlob = (globData, strict = true) => {
+  if (typeof globData !== 'string' && !Array.isArray(globData)) {
+    throw new TypeError('GLOB pattern must be a string or an array of strings.');
+  }
+  if (Array.isArray(globData)) {
+    const allStrings = globData.every((item) => typeof item === 'string');
+    if (!allStrings) {
+      throw new TypeError('All elements in the GLOB array must be strings.');
+    }
+  }
+  if (typeof strict !== 'boolean') {
+    throw new TypeError('Strict mode must be a boolean.');
+  }
+
+  const globPattern = Array.isArray(globData) ? globData.join('') : globData;
+  const regexString = ['^'];
+  let i = 0;
+  let inGroup = false;
+  let inBracket = false;
+
+  while (i < globPattern.length) {
+    const char = globPattern[i];
+
+    // Handle explicit escaping
+    if (char === '\\') {
+      const nextChar = globPattern[i + 1] || '';
+      regexString.push('\\' + nextChar);
+      i += 2;
+      continue;
+    }
+
+    // Handle character classes [...]
+    if (inBracket) {
+      if (char === ']') {
+        inBracket = false;
+        regexString.push(']');
+      } else if (char === '!' && globPattern[i - 1] === '[') {
+        // Translate GLOB negation [!a] to RegExp negation [^a]
+        regexString.push('^');
+      } else {
+        regexString.push(char);
+      }
+      i++;
+      continue;
+    }
+
+    // Handle standard GLOB characters and escape RegExp specials
+    switch (char) {
+      // Escape RegExp syntax characters that have no meaning in GLOB
+      case '/':
+      case '$':
+      case '^':
+      case '+':
+      case '.':
+      case '(':
+      case ')':
+      case '=':
+      case '!':
+      case '|':
+        regexString.push('\\' + char);
+        break;
+
+      // Match a single character (excluding path separators)
+      case '?':
+        regexString.push('[^/]');
+        break;
+
+      // Start character class
+      case '[':
+        inBracket = true;
+        regexString.push(char);
+        break;
+
+      // Literal closing bracket if it wasn't opened
+      case ']':
+        regexString.push('\\]');
+        break;
+
+      // Start an alternation group {a,b}
+      case '{':
+        inGroup = true;
+        regexString.push('(');
+        break;
+
+      // Close an alternation group
+      case '}':
+        if (inGroup) {
+          inGroup = false;
+          regexString.push(')');
+        } else {
+          regexString.push('\\}');
+        }
+        break;
+
+      // Separator inside alternation group
+      case ',':
+        regexString.push(inGroup ? '|' : '\\,');
+        break;
+
+      // Handle wildcards (* and **)
+      case '*':
+        let starCount = 1;
+        while (globPattern[i + 1] === '*') {
+          starCount++;
+          i++;
+        }
+        if (starCount > 1) {
+          // '**' matches anything, including path separators
+          regexString.push('.*');
+        } else {
+          // '*' matches anything except path separators
+          regexString.push('[^/]*');
+        }
+        break;
+
+      // Literal characters
+      default:
+        regexString.push(char);
+    }
+    i++;
+  }
+
+  // Strict validations for unclosed syntax
+  if (strict) {
+    if (inBracket) throw new SyntaxError('Unmatched bracket "[" in GLOB pattern.');
+    if (inGroup) throw new SyntaxError('Unmatched brace "{" in GLOB pattern.');
+  }
+
+  // Anchor to the end of the string
+  regexString.push('$');
+
+  return regexString;
+};
+
+/**
+ * Compiles a GLOB string pattern into a RegExp object.
+ *
+ * @param {string} globPattern - The GLOB pattern to compile.
+ * @param {string} [flags=''] - Optional RegExp flags (e.g., 'i', 'g', 'm').
+ * @property {boolean} [strict=true] - If true, throws SyntaxError on unbalanced brackets or braces.
+ * @returns {RegExp} The resulting regular expression.
+ * @throws {TypeError} If globPattern or flags are not strings.
+ * @throws {SyntaxError} If the pattern has unmatched groups and strict mode is enabled.
+ */
+const compileGlobRegExp = (globPattern, flags = '', strict = true) => {
+  if (typeof flags !== 'string') {
+    throw new TypeError('RegExp flags must be a string.');
+  }
+  return new RegExp(compileGlob(globPattern, strict).join(''), flags);
+};
+
+/**
+ * Decompiles a glob data back into a GLOB string pattern.
+ * Note: This method is designed specifically for values generated by this file compiler method.
+ *
+ * @param {RegExp|string|string[]} regexp - The regular expression to decompile.
+ * @returns {string[]} The reconstructed GLOB pattern.
+ * @throws {TypeError} If the argument is not a valid RegExp instance or string.
+ */
+const decompileGlob = (regexp) => {
+  if (
+    !(regexp instanceof RegExp) &&
+    typeof regexp !== 'string' &&
+    (!Array.isArray(regexp) || !regexp.every((v) => typeof v === 'string'))
+  ) {
+    throw new TypeError('Argument must be a RegExp instance or string stuff.');
+  }
+
+  let source =
+    typeof regexp === 'string' ? regexp : Array.isArray(regexp) ? regexp.join('') : regexp.source;
+  const globPattern = [];
+
+  // Remove the strict start and end anchors that the compiler adds
+  if (source.startsWith('^')) {
+    source = source.slice(1);
+  }
+  if (source.endsWith('$')) {
+    source = source.slice(0, -1);
+  }
+
+  let i = 0;
+  while (i < source.length) {
+    const char = source[i];
+
+    // Handle escaped characters (e.g., '\/' becomes '/', '\.' becomes '.')
+    if (char === '\\') {
+      const nextChar = source[i + 1] || '';
+      globPattern.push(nextChar);
+      i += 2;
+      continue;
+    }
+
+    // Handle '**' wildcard (compiled as '.*')
+    if (char === '.') {
+      if (source[i + 1] === '*') {
+        globPattern.push('**');
+        i += 2;
+        continue;
+      }
+    }
+
+    if (char === '[') {
+      // Handle '*' wildcard (compiled as '[^/]*')
+      if (source.slice(i, i + 5) === '[^/]*') {
+        globPattern.push('*');
+        i += 5;
+        continue;
+      }
+      // Handle '?' wildcard (compiled as '[^/]')
+      if (source.slice(i, i + 4) === '[^/]') {
+        globPattern.push('?');
+        i += 4;
+        continue;
+      }
+      // Handle negation inside brackets (compiled from '[!' to '[^')
+      if (source[i + 1] === '^') {
+        globPattern.push('[!');
+        i += 2;
+        continue;
+      }
+    }
+
+    // Restore alternation groups '{a,b}' (compiled as '(a|b)')
+    if (char === '(') {
+      globPattern.push('{');
+      i++;
+      continue;
+    }
+    if (char === '|') {
+      globPattern.push(',');
+      i++;
+      continue;
+    }
+    if (char === ')') {
+      globPattern.push('}');
+      i++;
+      continue;
+    }
+
+    // Literal character appending
+    globPattern.push(char);
+    i++;
+  }
+
+  return globPattern;
+};
+
+/**
+ * Validates if a given pattern is a syntactically correct GLOB string.
+ *
+ * @param {string|string[]} globPattern - The pattern to validate.
+ * @returns {boolean} True if the pattern is syntactically valid, false otherwise.
+ * @throws {TypeError} If the input is not a string or an array of strings.
+ */
+const isValidGlob = (globPattern) => {
+  try {
+    // 1. Attempt to compile the pattern using the existing strict logic.
+    // If the syntax is broken, compileGlob will throw a SyntaxError.
+    compileGlob(globPattern, true);
+    return true;
+  } catch (error) {
+    // 2. If the error is a SyntaxError, the pattern is mathematically/syntactically invalid.
+    if (error instanceof SyntaxError) {
+      return false;
+    }
+
+    // 3. If it's any other error, re-throw it to avoid masking potential bugs.
+    throw error;
+  }
+};
+
+exports.compileGlob = compileGlob;
+exports.compileGlobRegExp = compileGlobRegExp;
+exports.decompileGlob = decompileGlob;
+exports.isValidGlob = isValidGlob;

package/dist/v1/regexp/Glob.d.mts

@@ -0,0 +1,45 @@
+/**
+ * A highly professional utility to convert GLOB patterns into JavaScript RegExp objects,
+ * and decompile them back into GLOB strings.
+ *
+ * Supports standard features: '*', '**', '?', '[...]', '[!...]', '{a,b}', and '\' escaping.
+ */
+/**
+ * Compiles a GLOB string pattern into a RegExp object.
+ *
+ * @param {string|string[]} globData - The GLOB pattern to compile.
+ * @property {boolean} [strict=true] - If true, throws SyntaxError on unbalanced brackets or braces.
+ * @returns {string[]} The resulting regular expression parsed into string array.
+ * @throws {TypeError} If globPattern or flags are not strings.
+ * @throws {SyntaxError} If the pattern has unmatched groups and strict mode is enabled.
+ */
+export declare const compileGlob: (globData: string | string[], strict?: boolean) => string[];
+/**
+ * Compiles a GLOB string pattern into a RegExp object.
+ *
+ * @param {string} globPattern - The GLOB pattern to compile.
+ * @param {string} [flags=''] - Optional RegExp flags (e.g., 'i', 'g', 'm').
+ * @property {boolean} [strict=true] - If true, throws SyntaxError on unbalanced brackets or braces.
+ * @returns {RegExp} The resulting regular expression.
+ * @throws {TypeError} If globPattern or flags are not strings.
+ * @throws {SyntaxError} If the pattern has unmatched groups and strict mode is enabled.
+ */
+export declare const compileGlobRegExp: (globPattern: string, flags?: string, strict?: boolean) => RegExp;
+/**
+ * Decompiles a glob data back into a GLOB string pattern.
+ * Note: This method is designed specifically for values generated by this file compiler method.
+ *
+ * @param {RegExp|string|string[]} regexp - The regular expression to decompile.
+ * @returns {string[]} The reconstructed GLOB pattern.
+ * @throws {TypeError} If the argument is not a valid RegExp instance or string.
+ */
+export declare const decompileGlob: (regexp: RegExp | string | string[]) => string[];
+/**
+ * Validates if a given pattern is a syntactically correct GLOB string.
+ *
+ * @param {string|string[]} globPattern - The pattern to validate.
+ * @returns {boolean} True if the pattern is syntactically valid, false otherwise.
+ * @throws {TypeError} If the input is not a string or an array of strings.
+ */
+export declare const isValidGlob: (globPattern: string | string[]) => boolean;
+//# sourceMappingURL=Glob.d.mts.map

package/dist/v1/regexp/Glob.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Glob.d.mts","sourceRoot":"","sources":["../../../src/v1/regexp/Glob.mjs"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,WAAW,aANb,MAAM,GAAC,MAAM,EAAE,uBAEb,MAAM,EAwIlB,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,iBAAiB,gBAPnB,MAAM,UACN,MAAM,uBAEJ,MASZ,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa,WAJf,MAAM,GAAC,MAAM,GAAC,MAAM,EAAE,KACpB,MAAM,EAyFlB,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,gBAJb,MAAM,GAAC,MAAM,EAAE,KACb,OAkBZ,CAAC"}