tiny-essentials 1.28.18 → 1.29.0

package/dist/v1/regexp/Glob.mjs

@@ -0,0 +1,260 @@
+/**
+ * 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 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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;
+    }
+};

package/dist/v1/regexp/Ipv4.cjs

@@ -0,0 +1,57 @@
+'use strict';
+
+// Credits: https://oneuptime.com/blog/post/2026-03-20-validate-ipv4-regex-javascript/view
+
+// Each octet matches 0-255 without leading zeros (except "0" itself)
+const octet = '(?:25[0-5]|2[0-4]\\d|1\\d{2}|[1-9]\\d|\\d)';
+
+/**
+ * Generates a regular expression that matches a standard IPv4 address.
+ * The pattern ensures the string contains exactly four octets ranging from 0 to 255, separated by periods.
+ * @returns {RegExp}
+ */
+function ipv4Regex() {
+  return new RegExp(`^${octet}\\.${octet}\\.${octet}\\.${octet}$`);
+}
+
+/**
+ * Validates whether a given input string is a correctly formatted IPv4 address.
+ * It checks the string against the IPv4 regular expression pattern and returns a boolean result.
+ * @param {string} s - The input string to be validated.
+ * @param {RegExp} [regex] - The regex used to execute the function.
+ * @returns {boolean} - True if the string is a valid IPv4 address, false otherwise.
+ */
+function isValidIPv4(s, regex) {
+  if (typeof s !== 'string') {
+    throw new TypeError('The input must be a string.');
+  }
+  return (regex ?? ipv4Regex()).test(s);
+}
+
+/**
+ * Creates a global regular expression used to locate IPv4 addresses within a larger block of text.
+ * It utilizes word boundaries to ensure that only complete IP addresses are matched.
+ * @returns {RegExp}
+ */
+function findIPv4Regex() {
+  return new RegExp(`\\b${octet}(?:\\.${octet}){3}\\b`, 'g');
+}
+
+/**
+ * Scans the provided text and extracts all occurrences of IPv4 addresses.
+ * This function uses a global regular expression to find multiple matches within the input.
+ * @param {string} text - The input text content to be searched.
+ * @param {RegExp} [regex] - The regex used to execute the function.
+ * @returns {string[]} - An array of all matched IP addresses, or null if no matches are found.
+ */
+function extractIPsV4(text, regex) {
+  if (typeof text !== 'string') {
+    throw new TypeError('The input must be a string.');
+  }
+  return text.match(regex ?? findIPv4Regex()) ?? [];
+}
+
+exports.extractIPsV4 = extractIPsV4;
+exports.findIPv4Regex = findIPv4Regex;
+exports.ipv4Regex = ipv4Regex;
+exports.isValidIPv4 = isValidIPv4;

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

@@ -0,0 +1,29 @@
+/**
+ * Generates a regular expression that matches a standard IPv4 address.
+ * The pattern ensures the string contains exactly four octets ranging from 0 to 255, separated by periods.
+ * @returns {RegExp}
+ */
+export declare function ipv4Regex(): RegExp;
+/**
+ * Validates whether a given input string is a correctly formatted IPv4 address.
+ * It checks the string against the IPv4 regular expression pattern and returns a boolean result.
+ * @param {string} s - The input string to be validated.
+ * @param {RegExp} [regex] - The regex used to execute the function.
+ * @returns {boolean} - True if the string is a valid IPv4 address, false otherwise.
+ */
+export declare function isValidIPv4(s: string, regex?: RegExp): boolean;
+/**
+ * Creates a global regular expression used to locate IPv4 addresses within a larger block of text.
+ * It utilizes word boundaries to ensure that only complete IP addresses are matched.
+ * @returns {RegExp}
+ */
+export declare function findIPv4Regex(): RegExp;
+/**
+ * Scans the provided text and extracts all occurrences of IPv4 addresses.
+ * This function uses a global regular expression to find multiple matches within the input.
+ * @param {string} text - The input text content to be searched.
+ * @param {RegExp} [regex] - The regex used to execute the function.
+ * @returns {string[]} - An array of all matched IP addresses, or null if no matches are found.
+ */
+export declare function extractIPsV4(text: string, regex?: RegExp): string[];
+//# sourceMappingURL=Ipv4.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Ipv4.d.mts","sourceRoot":"","sources":["../../../src/v1/regexp/Ipv4.mjs"],"names":[],"mappings":"AAKA;;;;GAIG;AACH,wBAAgB,SAAS,IAFZ,MAAM,CAIlB;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAJlB,MAIkB,EAAE,KAAK,AAHjC,CACA,EADQ,MAGyB,GAFvB,OAAO,CAOnB;AAED;;;;GAIG;AACH,wBAAgB,aAAa,IAFhB,MAAM,CAIlB;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAJtB,MAIsB,EAAE,KAAK,AAHrC,CACA,EADQ,MAG6B,GAF3B,MAAM,EAAE,CAOpB"}

package/dist/v1/regexp/Ipv4.mjs

@@ -0,0 +1,45 @@
+// Credits: https://oneuptime.com/blog/post/2026-03-20-validate-ipv4-regex-javascript/view
+// Each octet matches 0-255 without leading zeros (except "0" itself)
+const octet = '(?:25[0-5]|2[0-4]\\d|1\\d{2}|[1-9]\\d|\\d)';
+/**
+ * Generates a regular expression that matches a standard IPv4 address.
+ * The pattern ensures the string contains exactly four octets ranging from 0 to 255, separated by periods.
+ * @returns {RegExp}
+ */
+export function ipv4Regex() {
+    return new RegExp(`^${octet}\\.${octet}\\.${octet}\\.${octet}$`);
+}
+/**
+ * Validates whether a given input string is a correctly formatted IPv4 address.
+ * It checks the string against the IPv4 regular expression pattern and returns a boolean result.
+ * @param {string} s - The input string to be validated.
+ * @param {RegExp} [regex] - The regex used to execute the function.
+ * @returns {boolean} - True if the string is a valid IPv4 address, false otherwise.
+ */
+export function isValidIPv4(s, regex) {
+    if (typeof s !== 'string') {
+        throw new TypeError('The input must be a string.');
+    }
+    return (regex ?? ipv4Regex()).test(s);
+}
+/**
+ * Creates a global regular expression used to locate IPv4 addresses within a larger block of text.
+ * It utilizes word boundaries to ensure that only complete IP addresses are matched.
+ * @returns {RegExp}
+ */
+export function findIPv4Regex() {
+    return new RegExp(`\\b${octet}(?:\\.${octet}){3}\\b`, 'g');
+}
+/**
+ * Scans the provided text and extracts all occurrences of IPv4 addresses.
+ * This function uses a global regular expression to find multiple matches within the input.
+ * @param {string} text - The input text content to be searched.
+ * @param {RegExp} [regex] - The regex used to execute the function.
+ * @returns {string[]} - An array of all matched IP addresses, or null if no matches are found.
+ */
+export function extractIPsV4(text, regex) {
+    if (typeof text !== 'string') {
+        throw new TypeError('The input must be a string.');
+    }
+    return text.match(regex ?? findIPv4Regex()) ?? [];
+}

package/dist/v1/regexp/Ipv6.cjs

@@ -0,0 +1,67 @@
+'use strict';
+
+// Credits: https://oneuptime.com/blog/post/2026-03-20-validate-ipv4-regex-javascript/view
+// Note: IPv6 logic is significantly more complex due to hexadecimal format and zero compression (::).
+
+/**
+ * Matches a single hexadecimal group (1 to 4 hex digits).
+ * @type {string}
+ */
+const hexGroup = '[0-9a-fA-F]{1,4}';
+
+/**
+ * A pattern to match standard IPv6 addresses.
+ * @type {string}
+ */
+const ipv6Pattern = `((${hexGroup}:){7}${hexGroup}|(${hexGroup}:){1,7}:|(${hexGroup}:){1,6}:${hexGroup}|(${hexGroup}:){1,5}(:${hexGroup}){1,2}|(${hexGroup}:){1,4}(:${hexGroup}){1,3}|(${hexGroup}:){1,3}(:${hexGroup}){1,4}|(${hexGroup}:){1,2}(:${hexGroup}){1,5}|${hexGroup}:((:${hexGroup}){1,6})|:((:${hexGroup}){1,7}|:))`;
+
+/**
+ * Generates a regular expression that matches a standard IPv6 address.
+ * @returns {RegExp}
+ */
+function ipv6Regex() {
+  return new RegExp(`^${ipv6Pattern}$`);
+}
+
+/**
+ * Validates whether a given input string is a correctly formatted IPv6 address.
+ * @param {string} s - The input string to be validated.
+ * @param {RegExp} [regex] - The regex used to execute the function.
+ * @throws {TypeError} If the input is not a string.
+ * @returns {boolean} - True if the string is a valid IPv6 address, false otherwise.
+ */
+function isValidIPv6(s, regex) {
+  if (typeof s !== 'string') {
+    throw new TypeError('The input must be a string.');
+  }
+  return (regex ?? ipv6Regex()).test(s);
+}
+
+/**
+ * Creates a global regular expression used to locate IPv6 addresses within a larger block of text.
+ * It utilizes word boundaries to ensure that only complete IP addresses are matched.
+ * @returns {RegExp}
+ */
+function findIPv6Regex() {
+  return new RegExp(`\\b${ipv6Pattern}\\b`, 'g');
+}
+
+/**
+ * Scans the provided text and extracts all occurrences of IPv6 addresses.
+ * This function uses a global regular expression to find multiple matches within the input.
+ * @param {string} text - The input text content to be searched.
+ * @param {RegExp} [regex] - The regex used to execute the function.
+ * @throws {TypeError} If the input is not a string.
+ * @returns {string[]} - An array of all matched IP addresses, or null if no matches are found.
+ */
+function extractIPsV6(text, regex) {
+  if (typeof text !== 'string') {
+    throw new TypeError('The input must be a string.');
+  }
+  return text.match(regex ?? findIPv6Regex()) ?? [];
+}
+
+exports.extractIPsV6 = extractIPsV6;
+exports.findIPv6Regex = findIPv6Regex;
+exports.ipv6Regex = ipv6Regex;
+exports.isValidIPv6 = isValidIPv6;

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

@@ -0,0 +1,29 @@
+/**
+ * Generates a regular expression that matches a standard IPv6 address.
+ * @returns {RegExp}
+ */
+export declare function ipv6Regex(): RegExp;
+/**
+ * Validates whether a given input string is a correctly formatted IPv6 address.
+ * @param {string} s - The input string to be validated.
+ * @param {RegExp} [regex] - The regex used to execute the function.
+ * @throws {TypeError} If the input is not a string.
+ * @returns {boolean} - True if the string is a valid IPv6 address, false otherwise.
+ */
+export declare function isValidIPv6(s: string, regex?: RegExp): boolean;
+/**
+ * Creates a global regular expression used to locate IPv6 addresses within a larger block of text.
+ * It utilizes word boundaries to ensure that only complete IP addresses are matched.
+ * @returns {RegExp}
+ */
+export declare function findIPv6Regex(): RegExp;
+/**
+ * Scans the provided text and extracts all occurrences of IPv6 addresses.
+ * This function uses a global regular expression to find multiple matches within the input.
+ * @param {string} text - The input text content to be searched.
+ * @param {RegExp} [regex] - The regex used to execute the function.
+ * @throws {TypeError} If the input is not a string.
+ * @returns {string[]} - An array of all matched IP addresses, or null if no matches are found.
+ */
+export declare function extractIPsV6(text: string, regex?: RegExp): string[];
+//# sourceMappingURL=Ipv6.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Ipv6.d.mts","sourceRoot":"","sources":["../../../src/v1/regexp/Ipv6.mjs"],"names":[],"mappings":"AAeA;;;GAGG;AACH,wBAAgB,SAAS,IAFZ,MAAM,CAIlB;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,CAAC,EALlB,MAKkB,EAAE,KAAK,AAJjC,CACA,EADQ,MAIyB,GAFvB,OAAO,CAOnB;AAED;;;;GAIG;AACH,wBAAgB,aAAa,IAFhB,MAAM,CAIlB;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,IAAI,EALtB,MAKsB,EAAE,KAAK,AAJrC,CACA,EADQ,MAI6B,GAF3B,MAAM,EAAE,CAOpB"}

package/dist/v1/regexp/Ipv6.mjs

@@ -0,0 +1,54 @@
+// Credits: https://oneuptime.com/blog/post/2026-03-20-validate-ipv4-regex-javascript/view
+// Note: IPv6 logic is significantly more complex due to hexadecimal format and zero compression (::).
+/**
+ * Matches a single hexadecimal group (1 to 4 hex digits).
+ * @type {string}
+ */
+const hexGroup = '[0-9a-fA-F]{1,4}';
+/**
+ * A pattern to match standard IPv6 addresses.
+ * @type {string}
+ */
+const ipv6Pattern = `((${hexGroup}:){7}${hexGroup}|(${hexGroup}:){1,7}:|(${hexGroup}:){1,6}:${hexGroup}|(${hexGroup}:){1,5}(:${hexGroup}){1,2}|(${hexGroup}:){1,4}(:${hexGroup}){1,3}|(${hexGroup}:){1,3}(:${hexGroup}){1,4}|(${hexGroup}:){1,2}(:${hexGroup}){1,5}|${hexGroup}:((:${hexGroup}){1,6})|:((:${hexGroup}){1,7}|:))`;
+/**
+ * Generates a regular expression that matches a standard IPv6 address.
+ * @returns {RegExp}
+ */
+export function ipv6Regex() {
+    return new RegExp(`^${ipv6Pattern}$`);
+}
+/**
+ * Validates whether a given input string is a correctly formatted IPv6 address.
+ * @param {string} s - The input string to be validated.
+ * @param {RegExp} [regex] - The regex used to execute the function.
+ * @throws {TypeError} If the input is not a string.
+ * @returns {boolean} - True if the string is a valid IPv6 address, false otherwise.
+ */
+export function isValidIPv6(s, regex) {
+    if (typeof s !== 'string') {
+        throw new TypeError('The input must be a string.');
+    }
+    return (regex ?? ipv6Regex()).test(s);
+}
+/**
+ * Creates a global regular expression used to locate IPv6 addresses within a larger block of text.
+ * It utilizes word boundaries to ensure that only complete IP addresses are matched.
+ * @returns {RegExp}
+ */
+export function findIPv6Regex() {
+    return new RegExp(`\\b${ipv6Pattern}\\b`, 'g');
+}
+/**
+ * Scans the provided text and extracts all occurrences of IPv6 addresses.
+ * This function uses a global regular expression to find multiple matches within the input.
+ * @param {string} text - The input text content to be searched.
+ * @param {RegExp} [regex] - The regex used to execute the function.
+ * @throws {TypeError} If the input is not a string.
+ * @returns {string[]} - An array of all matched IP addresses, or null if no matches are found.
+ */
+export function extractIPsV6(text, regex) {
+    if (typeof text !== 'string') {
+        throw new TypeError('The input must be a string.');
+    }
+    return text.match(regex ?? findIPv6Regex()) ?? [];
+}