tiny-essentials 1.28.18 → 1.29.0

package/dist/v1/regexp/SegmentExtractor.cjs

@@ -0,0 +1,145 @@
+'use strict';
+
+/**
+ * @typedef {Record<string, string>} PathParams
+ * Represents a mapping of parameter names to their extracted values.
+ */
+
+/**
+ * @typedef {Object} SegExErrorConfig
+ * @property {string} pathPatternErrorMsg - Custom error message used when the pathPattern is not a string.
+ */
+
+/**
+ * Represents the result of a path execution, containing extracted parameters and the match status.
+ * @typedef {Object} SegExData
+ * @property {PathParams} params - The extracted parameters as a key-value mapping.
+ * @property {boolean} match - Indicates whether the path successfully matched the pattern.
+ */
+
+/**
+ * @callback SegExExec
+ * @param {string} path - The URL path to be processed.
+ * @returns {SegExData} An object containing the parameters extracted from the path.
+ */
+
+/**
+ * @callback SegExIsUsed
+ * @returns {boolean} Returns true if the template has been used to perform a match.
+ */
+
+/**
+ * @typedef {Object} SegExResult
+ * @property {RegExp} regex - The compiled regular expression for the path pattern.
+ * @property {string[]} paramNames - The list of parameter names extracted from the pattern.
+ * @property {SegExExec} exec - Function to extract parameters from a real path.
+ */
+
+/**
+ * @callback SegExReplacer
+ * @param {string[]} paramNames - The accumulated list of parameter names.
+ * @param {string} substring - The original substring found by the search.
+ * @param {...any} args - Additional arguments captured by the RegExp (capture groups).
+ * @returns {string} The replacement value for the RegExp template.
+ */
+
+/**
+ *  A function that accepts a path pattern string and returns a SegExResult object.
+ * @typedef {(pathPattern: string) => SegExResult} SegExFunction
+ */
+
+/**
+ * Factory to create a path segment extractor based on a specific pattern.
+ *
+ * @param {string|RegExp} searchValue - The search pattern (string or RegExp) used to identify dynamic segments.
+ * @param {SegExReplacer} replaceValue - The function defining how to transform a segment into a capture group.
+ * @param {SegExErrorConfig} errorConfig - Optional configuration to customize error messages.
+ * @returns {SegExFunction} A function that accepts a path pattern string and returns a SegExResult.
+ * @throws {TypeError} If `searchValue` is not a string or RegExp, or if `replaceValue` is not a function.
+ */
+const makeSegmentExtractor = (searchValue, replaceValue, errorConfig) => {
+  // Validate searchValue
+  if (
+    searchValue === null ||
+    (typeof searchValue !== 'string' && !(searchValue instanceof RegExp))
+  ) {
+    throw new TypeError('The searchValue must be a string or a RegExp.');
+  }
+
+  // Validate replaceValue
+  if (typeof replaceValue !== 'function') {
+    throw new TypeError('The replaceValue must be a function.');
+  }
+
+  // Deep validation for errorConfig
+  if (typeof errorConfig !== 'object' || errorConfig === null) {
+    throw new TypeError('The errorConfig must be an object.');
+  }
+  if (typeof errorConfig.pathPatternErrorMsg !== 'string') {
+    throw new TypeError('The errorConfig.pathPatternErrorMsg property must be a string.');
+  }
+
+  /**
+   * @param {string} pathPattern - The path pattern to compile.
+   * @returns {SegExResult} The extraction logic object.
+   * @throws {TypeError} If pathPattern is not a string.
+   */
+  return (pathPattern) => {
+    if (typeof pathPattern !== 'string') {
+      throw new TypeError(errorConfig.pathPatternErrorMsg);
+    }
+
+    /** @type {string[]} */
+    const paramNames = [];
+
+    const regexPath = pathPattern.replace(searchValue, (_, ...args) =>
+      replaceValue(paramNames, _, ...args),
+    );
+
+    const regex = new RegExp(`^${regexPath}$`);
+
+    /**
+     * @type {SegExExec}
+     * Function to perform the regex matching and extract parameters from a given path.
+     */
+    const exec = (path) => {
+      /** @type {PathParams} */
+      const params = {};
+
+      const match = path.match(regex);
+
+      if (!match) return { params, match: false };
+
+      // Extract dynamic parameters based on the order they were found in the regex
+      paramNames.forEach((name, index) => {
+        params[name] = decodeURIComponent(match[index + 1]);
+      });
+
+      return { params, match: true };
+    };
+
+    return { regex, paramNames, exec };
+  };
+};
+
+/**
+ * Standard implementation for extracting parameters in the `:paramName` format (e.g., "/user/:id").
+ * @type {SegExFunction}
+ */
+const segmentExtractorV1 = makeSegmentExtractor(
+  /:([^/]+)/g,
+  /**
+   * @param {string[]} paramNames - The accumulated list of parameter names.
+   * @param {string} _ - The full matched substring (e.g., ":id").
+   * @param {string} paramName - The captured parameter name (e.g., "id").
+   * @returns {string} The regex capture group string.
+   */
+  (paramNames, _, paramName) => {
+    paramNames.push(paramName);
+    return '([^/]+)';
+  },
+  { pathPatternErrorMsg: 'The argument must be a string (e.g., "/user/:id")' },
+);
+
+exports.makeSegmentExtractor = makeSegmentExtractor;
+exports.segmentExtractorV1 = segmentExtractorV1;

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

@@ -0,0 +1,91 @@
+/**
+ * @typedef {Record<string, string>} PathParams
+ * Represents a mapping of parameter names to their extracted values.
+ */
+export type PathParams = Record<string, string>;
+export type SegExErrorConfig = {
+    /**
+     * - Custom error message used when the pathPattern is not a string.
+     */
+    pathPatternErrorMsg: string;
+};
+export type SegExData = {
+    /**
+     * - The extracted parameters as a key-value mapping.
+     */
+    params: PathParams;
+    /**
+     * - Indicates whether the path successfully matched the pattern.
+     */
+    match: boolean;
+};
+export type SegExExec = (path: string) => SegExData;
+export type SegExIsUsed = () => boolean;
+export type SegExResult = {
+    /**
+     * - The compiled regular expression for the path pattern.
+     */
+    regex: RegExp;
+    /**
+     * - The list of parameter names extracted from the pattern.
+     */
+    paramNames: string[];
+    /**
+     * - Function to extract parameters from a real path.
+     */
+    exec: SegExExec;
+};
+export type SegExReplacer = (paramNames: string[], substring: string, ...args: any) => string;
+export type SegExFunction = (pathPattern: string) => SegExResult;
+/**
+ * @typedef {Object} SegExErrorConfig
+ * @property {string} pathPatternErrorMsg - Custom error message used when the pathPattern is not a string.
+ */
+/**
+ * Represents the result of a path execution, containing extracted parameters and the match status.
+ * @typedef {Object} SegExData
+ * @property {PathParams} params - The extracted parameters as a key-value mapping.
+ * @property {boolean} match - Indicates whether the path successfully matched the pattern.
+ */
+/**
+ * @callback SegExExec
+ * @param {string} path - The URL path to be processed.
+ * @returns {SegExData} An object containing the parameters extracted from the path.
+ */
+/**
+ * @callback SegExIsUsed
+ * @returns {boolean} Returns true if the template has been used to perform a match.
+ */
+/**
+ * @typedef {Object} SegExResult
+ * @property {RegExp} regex - The compiled regular expression for the path pattern.
+ * @property {string[]} paramNames - The list of parameter names extracted from the pattern.
+ * @property {SegExExec} exec - Function to extract parameters from a real path.
+ */
+/**
+ * @callback SegExReplacer
+ * @param {string[]} paramNames - The accumulated list of parameter names.
+ * @param {string} substring - The original substring found by the search.
+ * @param {...any} args - Additional arguments captured by the RegExp (capture groups).
+ * @returns {string} The replacement value for the RegExp template.
+ */
+/**
+ *  A function that accepts a path pattern string and returns a SegExResult object.
+ * @typedef {(pathPattern: string) => SegExResult} SegExFunction
+ */
+/**
+ * Factory to create a path segment extractor based on a specific pattern.
+ *
+ * @param {string|RegExp} searchValue - The search pattern (string or RegExp) used to identify dynamic segments.
+ * @param {SegExReplacer} replaceValue - The function defining how to transform a segment into a capture group.
+ * @param {SegExErrorConfig} errorConfig - Optional configuration to customize error messages.
+ * @returns {SegExFunction} A function that accepts a path pattern string and returns a SegExResult.
+ * @throws {TypeError} If `searchValue` is not a string or RegExp, or if `replaceValue` is not a function.
+ */
+export declare const makeSegmentExtractor: (searchValue: string | RegExp, replaceValue: SegExReplacer, errorConfig: SegExErrorConfig) => SegExFunction;
+/**
+ * Standard implementation for extracting parameters in the `:paramName` format (e.g., "/user/:id").
+ * @type {SegExFunction}
+ */
+export declare const segmentExtractorV1: SegExFunction;
+//# sourceMappingURL=SegmentExtractor.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"SegmentExtractor.d.mts","sourceRoot":"","sources":["../../../src/v1/regexp/SegmentExtractor.mjs"],"names":[],"mappings":"AAAA;;;GAGG;AAFA,YAAkC,UAAU,GAAlC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAElC;AAGE,YAAkB,gBAAgB,GAClC;;;;IAAmB,mBAAmB,EAA3B,MAAM,CACnB;CAAA,CAAA;AAIE,YAAkB,SAAS,GAC3B;;;;IAAuB,MAAM,EAAlB,UAAU,CACrB;;;;IAAoB,KAAK,EAAd,OAAO,CACpB;CAAA,CAAA;AAGE,YAAU,SAAS,GACnB,CAAgB,IAAI,EAAZ,MACR,KAAU,SACZ,CAAA;AAGE,YAAU,WAAW,GACrB,MAAU,OACZ,CAAA;AAGE,YAAkB,WAAW,GAC7B;;;;IAAmB,KAAK,EAAb,MAAM,CACjB;;;;IAAqB,UAAU,EAApB,MAAM,EAAE,CACnB;;;;IAAsB,IAAI,EAAf,SAAS,CACtB;CAAA,CAAA;AAGE,YAAU,aAAa,GACvB,CAAkB,UAAU,EAApB,MAAM,EACd,EAAgB,SAAS,EAAjB,MACR,EAAA,GACA,AADgB,IAAI,EAAT,GACX,KAAU,MACZ,CAAA;AAIE,YAAgD,aAAa,GAAnD,CAAC,WAAW,EAAE,MAAM,KAAK,WAAW,CAAe;AAxChE;;;GAGG;AAEH;;;;;GAKG;AAEH;;;;GAIG;AAEH;;;GAGG;AAEH;;;;;GAKG;AAEH;;;;;;GAMG;AAEH;;;GAGG;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,gBANtB,MAAM,GAAC,MAAM,gBACb,aAAa,eACb,gBAAgB,KACd,aAsEZ,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,kBAAkB,EAFrB,aAeT,CAAC"}

package/dist/v1/regexp/SegmentExtractor.mjs

@@ -0,0 +1,116 @@
+/**
+ * @typedef {Record<string, string>} PathParams
+ * Represents a mapping of parameter names to their extracted values.
+ */
+/**
+ * @typedef {Object} SegExErrorConfig
+ * @property {string} pathPatternErrorMsg - Custom error message used when the pathPattern is not a string.
+ */
+/**
+ * Represents the result of a path execution, containing extracted parameters and the match status.
+ * @typedef {Object} SegExData
+ * @property {PathParams} params - The extracted parameters as a key-value mapping.
+ * @property {boolean} match - Indicates whether the path successfully matched the pattern.
+ */
+/**
+ * @callback SegExExec
+ * @param {string} path - The URL path to be processed.
+ * @returns {SegExData} An object containing the parameters extracted from the path.
+ */
+/**
+ * @callback SegExIsUsed
+ * @returns {boolean} Returns true if the template has been used to perform a match.
+ */
+/**
+ * @typedef {Object} SegExResult
+ * @property {RegExp} regex - The compiled regular expression for the path pattern.
+ * @property {string[]} paramNames - The list of parameter names extracted from the pattern.
+ * @property {SegExExec} exec - Function to extract parameters from a real path.
+ */
+/**
+ * @callback SegExReplacer
+ * @param {string[]} paramNames - The accumulated list of parameter names.
+ * @param {string} substring - The original substring found by the search.
+ * @param {...any} args - Additional arguments captured by the RegExp (capture groups).
+ * @returns {string} The replacement value for the RegExp template.
+ */
+/**
+ *  A function that accepts a path pattern string and returns a SegExResult object.
+ * @typedef {(pathPattern: string) => SegExResult} SegExFunction
+ */
+/**
+ * Factory to create a path segment extractor based on a specific pattern.
+ *
+ * @param {string|RegExp} searchValue - The search pattern (string or RegExp) used to identify dynamic segments.
+ * @param {SegExReplacer} replaceValue - The function defining how to transform a segment into a capture group.
+ * @param {SegExErrorConfig} errorConfig - Optional configuration to customize error messages.
+ * @returns {SegExFunction} A function that accepts a path pattern string and returns a SegExResult.
+ * @throws {TypeError} If `searchValue` is not a string or RegExp, or if `replaceValue` is not a function.
+ */
+export const makeSegmentExtractor = (searchValue, replaceValue, errorConfig) => {
+    // Validate searchValue
+    if (searchValue === null ||
+        (typeof searchValue !== 'string' && !(searchValue instanceof RegExp))) {
+        throw new TypeError('The searchValue must be a string or a RegExp.');
+    }
+    // Validate replaceValue
+    if (typeof replaceValue !== 'function') {
+        throw new TypeError('The replaceValue must be a function.');
+    }
+    // Deep validation for errorConfig
+    if (typeof errorConfig !== 'object' || errorConfig === null) {
+        throw new TypeError('The errorConfig must be an object.');
+    }
+    if (typeof errorConfig.pathPatternErrorMsg !== 'string') {
+        throw new TypeError('The errorConfig.pathPatternErrorMsg property must be a string.');
+    }
+    /**
+     * @param {string} pathPattern - The path pattern to compile.
+     * @returns {SegExResult} The extraction logic object.
+     * @throws {TypeError} If pathPattern is not a string.
+     */
+    return (pathPattern) => {
+        if (typeof pathPattern !== 'string') {
+            throw new TypeError(errorConfig.pathPatternErrorMsg);
+        }
+        /** @type {boolean} */
+        let used = false;
+        /** @type {string[]} */
+        const paramNames = [];
+        const regexPath = pathPattern.replace(searchValue, (_, ...args) => replaceValue(paramNames, _, ...args));
+        const regex = new RegExp(`^${regexPath}$`);
+        /**
+         * @type {SegExExec}
+         * Function to perform the regex matching and extract parameters from a given path.
+         */
+        const exec = (path) => {
+            /** @type {PathParams} */
+            const params = {};
+            const match = path.match(regex);
+            used = true;
+            if (!match)
+                return { params, match: false };
+            // Extract dynamic parameters based on the order they were found in the regex
+            paramNames.forEach((name, index) => {
+                params[name] = decodeURIComponent(match[index + 1]);
+            });
+            return { params, match: true };
+        };
+        return { regex, paramNames, exec };
+    };
+};
+/**
+ * Standard implementation for extracting parameters in the `:paramName` format (e.g., "/user/:id").
+ * @type {SegExFunction}
+ */
+export const segmentExtractorV1 = makeSegmentExtractor(/:([^/]+)/g, 
+/**
+ * @param {string[]} paramNames - The accumulated list of parameter names.
+ * @param {string} _ - The full matched substring (e.g., ":id").
+ * @param {string} paramName - The captured parameter name (e.g., "id").
+ * @returns {string} The regex capture group string.
+ */
+(paramNames, _, paramName) => {
+    paramNames.push(paramName);
+    return '([^/]+)';
+}, { pathPatternErrorMsg: 'The argument must be a string (e.g., "/user/:id")' });

package/dist/v1/regexp/UrlDetector.cjs

@@ -0,0 +1,125 @@
+'use strict';
+
+/**
+ * @typedef {Object} UrlRegexOptions - Configuration options for customizing the generated URL regular expression.
+ * @property {string} [protocol='https?'] - The protocol scheme (e.g., 'http', 'https').
+ * @property {string} [subDomain=''] - The subdomain string to match.
+ * @property {boolean} [subDomainOptional=true] - Whether the subdomain is required or optional.
+ * @property {[number, number]} [nameMaxLength=[1, 256]] - An array containing the minimum and maximum length for the domain name.
+ * @property {[number, number]} [topLevelDomainLength=[1, 6]] - An array containing the minimum and maximum length for the TLD.
+ */
+
+/**
+ * Validates the UrlRegexOptions object to ensure all properties match the required types.
+ * This is a private helper used to maintain strict type safety at runtime.
+ *
+ * @param {UrlRegexOptions} options - The configuration options to validate.
+ * @throws {TypeError} If the options are not an object or if any property fails type validation.
+ * @private
+ */
+const validateUrlRegexOptions = (options) => {
+  if (options === undefined) return;
+  if (typeof options !== 'object' || options === null || Array.isArray(options)) {
+    throw new TypeError('Options must be an object.');
+  }
+  if (options.protocol !== undefined && typeof options.protocol !== 'string') {
+    throw new TypeError('The "protocol" property must be a string.');
+  }
+  if (options.subDomain !== undefined && typeof options.subDomain !== 'string') {
+    throw new TypeError('The "subDomain" property must be a string.');
+  }
+  if (options.subDomainOptional !== undefined && typeof options.subDomainOptional !== 'boolean') {
+    throw new TypeError('The "subDomainOptional" property must be a boolean.');
+  }
+  if (options.nameMaxLength !== undefined) {
+    if (
+      !Array.isArray(options.nameMaxLength) ||
+      options.nameMaxLength.length !== 2 ||
+      typeof options.nameMaxLength[0] !== 'number' ||
+      typeof options.nameMaxLength[1] !== 'number'
+    ) {
+      throw new TypeError('The "nameMaxLength" property must be an array of two numbers.');
+    }
+  }
+  if (options.topLevelDomainLength !== undefined) {
+    if (
+      !Array.isArray(options.topLevelDomainLength) ||
+      options.topLevelDomainLength.length !== 2 ||
+      typeof options.topLevelDomainLength[0] !== 'number' ||
+      typeof options.topLevelDomainLength[1] !== 'number'
+    ) {
+      throw new TypeError('The "topLevelDomainLength" property must be an array of two numbers.');
+    }
+  }
+};
+
+/**
+ * Constructs a URL regular expression pattern string based on the provided configuration options.
+ * @param {UrlRegexOptions} [options] - The configuration options.
+ * @returns {string} The generated regex pattern string.
+ */
+const urlStringRegexBuilder = (options = {}) => {
+  validateUrlRegexOptions(options);
+  const {
+    protocol = 'https?',
+    subDomain = '',
+    subDomainOptional = true,
+    nameMaxLength = [1, 256],
+    topLevelDomainLength = [1, 6],
+  } = options;
+  return `${protocol}:\\/\\/${subDomain ? `(${subDomain}\\.)${subDomainOptional ? '?' : ''}` : ''}[-a-zA-Z0-9@:%._\\+~#=]{${String(nameMaxLength[0])},${String(nameMaxLength[1])}}\\.[a-zA-Z0-9()]{${String(topLevelDomainLength[0])},${String(topLevelDomainLength[1])}}\\b([-a-zA-Z0-9()@:%_\\+.~#?&//=]*)`;
+};
+
+/**
+ * Creates a RegExp object anchored to the start and end of the string using the provided configuration.
+ * @param {UrlRegexOptions} [options] - The configuration options.
+ * @returns {RegExp} The resulting RegExp object.
+ */
+function urlRegex(options) {
+  return new RegExp(`^${urlStringRegexBuilder(options)}$`);
+}
+
+/**
+ * Validates whether a given string matches the specified URL pattern.
+ * @param {string} s - The string to validate.
+ * @param {UrlRegexOptions} [options] - The configuration options.
+ * @param {RegExp} [regex] - The regex used to execute the function.
+ * @returns {boolean} True if the string is a valid URL according to the pattern, false otherwise.
+ * @throws {TypeError} If the input string is not a string.
+ */
+function isValidUrl(s, options, regex) {
+  if (typeof s !== 'string') {
+    throw new TypeError('The input must be a string.');
+  }
+  return (regex ?? urlRegex(options)).test(s);
+}
+
+/**
+ * Generates a global RegExp object used to find all occurrences of URLs within a text.
+ * @param {UrlRegexOptions} [options] - The configuration options.
+ * @returns {RegExp} The resulting global RegExp object.
+ */
+function findUrlRegex(options) {
+  return new RegExp(`\\b${urlStringRegexBuilder(options)}\\b`, 'g');
+}
+
+/**
+ * Extracts all matching URL strings from a given text using the provided configuration.
+ * @param {string} text - The text to search.
+ * @param {UrlRegexOptions} [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.
+ */
+function extractUrls(text, options, regex) {
+  if (typeof text !== 'string') {
+    throw new TypeError('The input must be a string.');
+  }
+  return text.match(regex ?? findUrlRegex(options)) ?? [];
+}
+
+exports.extractUrls = extractUrls;
+exports.findUrlRegex = findUrlRegex;
+exports.isValidUrl = isValidUrl;
+exports.urlRegex = urlRegex;
+exports.urlStringRegexBuilder = urlStringRegexBuilder;

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

@@ -0,0 +1,67 @@
+/**
+ * @typedef {Object} UrlRegexOptions - Configuration options for customizing the generated URL regular expression.
+ * @property {string} [protocol='https?'] - The protocol scheme (e.g., 'http', 'https').
+ * @property {string} [subDomain=''] - The subdomain string to match.
+ * @property {boolean} [subDomainOptional=true] - Whether the subdomain is required or optional.
+ * @property {[number, number]} [nameMaxLength=[1, 256]] - An array containing the minimum and maximum length for the domain name.
+ * @property {[number, number]} [topLevelDomainLength=[1, 6]] - An array containing the minimum and maximum length for the TLD.
+ */
+export type UrlRegexOptions = {
+    /**
+     * - The protocol scheme (e.g., 'http', 'https').
+     */
+    protocol?: string;
+    /**
+     * - The subdomain string to match.
+     */
+    subDomain?: string;
+    /**
+     * - Whether the subdomain is required or optional.
+     */
+    subDomainOptional?: boolean;
+    /**
+     * - An array containing the minimum and maximum length for the domain name.
+     */
+    nameMaxLength?: [number, number];
+    /**
+     * - An array containing the minimum and maximum length for the TLD.
+     */
+    topLevelDomainLength?: [number, number];
+};
+/**
+ * Constructs a URL regular expression pattern string based on the provided configuration options.
+ * @param {UrlRegexOptions} [options] - The configuration options.
+ * @returns {string} The generated regex pattern string.
+ */
+export declare const urlStringRegexBuilder: (options?: UrlRegexOptions) => string;
+/**
+ * Creates a RegExp object anchored to the start and end of the string using the provided configuration.
+ * @param {UrlRegexOptions} [options] - The configuration options.
+ * @returns {RegExp} The resulting RegExp object.
+ */
+export declare function urlRegex(options?: UrlRegexOptions): RegExp;
+/**
+ * Validates whether a given string matches the specified URL pattern.
+ * @param {string} s - The string to validate.
+ * @param {UrlRegexOptions} [options] - The configuration options.
+ * @param {RegExp} [regex] - The regex used to execute the function.
+ * @returns {boolean} True if the string is a valid URL according to the pattern, false otherwise.
+ * @throws {TypeError} If the input string is not a string.
+ */
+export declare function isValidUrl(s: string, options?: UrlRegexOptions, regex?: RegExp): boolean;
+/**
+ * Generates a global RegExp object used to find all occurrences of URLs within a text.
+ * @param {UrlRegexOptions} [options] - The configuration options.
+ * @returns {RegExp} The resulting global RegExp object.
+ */
+export declare function findUrlRegex(options?: UrlRegexOptions): RegExp;
+/**
+ * Extracts all matching URL strings from a given text using the provided configuration.
+ * @param {string} text - The text to search.
+ * @param {UrlRegexOptions} [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 declare function extractUrls(text: string, options?: UrlRegexOptions, regex?: RegExp): string[];
+//# sourceMappingURL=UrlDetector.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"UrlDetector.d.mts","sourceRoot":"","sources":["../../../src/v1/regexp/UrlDetector.mjs"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AANA,YAAkB,eAAe,GACjC;;;;IAAoB,QAAQ,AAA5B,CACA,EADW,MAAM,CACjB;;;;IAAoB,SAAS,AAA7B,CACA,EADW,MAAM,CACjB;;;;IAAqB,iBAAiB,AAAtC,CACA,EADW,OAAO,CAClB;;;;IAA8B,aAAa,AAA3C,CACA,EADW,CAAC,MAAM,EAAE,MAAM,CAAC,CAC3B;;;;IAA8B,oBAAoB,AAAlD,CACF,EADa,CAAC,MAAM,EAAE,MAAM,CAAC,CAC7B;CAAA,CAAA;AA8CD;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,aAHvB,eAAe,KACb,MAYZ,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,OAAO,AAH7B,CACA,EADQ,eAGqB,GAFnB,MAAM,CAIlB;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,CAAC,EANjB,MAMiB,EAAE,OAAO,AALlC,CACA,EADQ,eAK0B,EAAE,KAAK,AAJzC,CACA,EADQ,MAIiC,GAH/B,OAAO,CAQnB;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,OAAO,AAHjC,CACA,EADQ,eAGyB,GAFvB,MAAM,CAIlB;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,IAAI,EANrB,MAMqB,EAAE,OAAO,AALtC,CACA,EADQ,eAK8B,EAAE,KAAK,AAJ7C,CACA,EADQ,MAIqC,GAHnC,MAAM,EAAE,CAQpB"}

package/dist/v1/regexp/UrlDetector.mjs

@@ -0,0 +1,102 @@
+/**
+ * @typedef {Object} UrlRegexOptions - Configuration options for customizing the generated URL regular expression.
+ * @property {string} [protocol='https?'] - The protocol scheme (e.g., 'http', 'https').
+ * @property {string} [subDomain=''] - The subdomain string to match.
+ * @property {boolean} [subDomainOptional=true] - Whether the subdomain is required or optional.
+ * @property {[number, number]} [nameMaxLength=[1, 256]] - An array containing the minimum and maximum length for the domain name.
+ * @property {[number, number]} [topLevelDomainLength=[1, 6]] - An array containing the minimum and maximum length for the TLD.
+ */
+/**
+ * Validates the UrlRegexOptions object to ensure all properties match the required types.
+ * This is a private helper used to maintain strict type safety at runtime.
+ *
+ * @param {UrlRegexOptions} options - The configuration options to validate.
+ * @throws {TypeError} If the options are not an object or if any property fails type validation.
+ * @private
+ */
+const validateUrlRegexOptions = (options) => {
+    if (options === undefined)
+        return;
+    if (typeof options !== 'object' || options === null || Array.isArray(options)) {
+        throw new TypeError('Options must be an object.');
+    }
+    if (options.protocol !== undefined && typeof options.protocol !== 'string') {
+        throw new TypeError('The "protocol" property must be a string.');
+    }
+    if (options.subDomain !== undefined && typeof options.subDomain !== 'string') {
+        throw new TypeError('The "subDomain" property must be a string.');
+    }
+    if (options.subDomainOptional !== undefined && typeof options.subDomainOptional !== 'boolean') {
+        throw new TypeError('The "subDomainOptional" property must be a boolean.');
+    }
+    if (options.nameMaxLength !== undefined) {
+        if (!Array.isArray(options.nameMaxLength) ||
+            options.nameMaxLength.length !== 2 ||
+            typeof options.nameMaxLength[0] !== 'number' ||
+            typeof options.nameMaxLength[1] !== 'number') {
+            throw new TypeError('The "nameMaxLength" property must be an array of two numbers.');
+        }
+    }
+    if (options.topLevelDomainLength !== undefined) {
+        if (!Array.isArray(options.topLevelDomainLength) ||
+            options.topLevelDomainLength.length !== 2 ||
+            typeof options.topLevelDomainLength[0] !== 'number' ||
+            typeof options.topLevelDomainLength[1] !== 'number') {
+            throw new TypeError('The "topLevelDomainLength" property must be an array of two numbers.');
+        }
+    }
+};
+/**
+ * Constructs a URL regular expression pattern string based on the provided configuration options.
+ * @param {UrlRegexOptions} [options] - The configuration options.
+ * @returns {string} The generated regex pattern string.
+ */
+export const urlStringRegexBuilder = (options = {}) => {
+    validateUrlRegexOptions(options);
+    const { protocol = 'https?', subDomain = '', subDomainOptional = true, nameMaxLength = [1, 256], topLevelDomainLength = [1, 6], } = options;
+    return `${protocol}:\\/\\/${subDomain ? `(${subDomain}\\.)${subDomainOptional ? '?' : ''}` : ''}[-a-zA-Z0-9@:%._\\+~#=]{${String(nameMaxLength[0])},${String(nameMaxLength[1])}}\\.[a-zA-Z0-9()]{${String(topLevelDomainLength[0])},${String(topLevelDomainLength[1])}}\\b([-a-zA-Z0-9()@:%_\\+.~#?&//=]*)`;
+};
+/**
+ * Creates a RegExp object anchored to the start and end of the string using the provided configuration.
+ * @param {UrlRegexOptions} [options] - The configuration options.
+ * @returns {RegExp} The resulting RegExp object.
+ */
+export function urlRegex(options) {
+    return new RegExp(`^${urlStringRegexBuilder(options)}$`);
+}
+/**
+ * Validates whether a given string matches the specified URL pattern.
+ * @param {string} s - The string to validate.
+ * @param {UrlRegexOptions} [options] - The configuration options.
+ * @param {RegExp} [regex] - The regex used to execute the function.
+ * @returns {boolean} True if the string is a valid URL according to the pattern, false otherwise.
+ * @throws {TypeError} If the input string is not a string.
+ */
+export function isValidUrl(s, options, regex) {
+    if (typeof s !== 'string') {
+        throw new TypeError('The input must be a string.');
+    }
+    return (regex ?? urlRegex(options)).test(s);
+}
+/**
+ * Generates a global RegExp object used to find all occurrences of URLs within a text.
+ * @param {UrlRegexOptions} [options] - The configuration options.
+ * @returns {RegExp} The resulting global RegExp object.
+ */
+export function findUrlRegex(options) {
+    return new RegExp(`\\b${urlStringRegexBuilder(options)}\\b`, 'g');
+}
+/**
+ * Extracts all matching URL strings from a given text using the provided configuration.
+ * @param {string} text - The text to search.
+ * @param {UrlRegexOptions} [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 extractUrls(text, options, regex) {
+    if (typeof text !== 'string') {
+        throw new TypeError('The input must be a string.');
+    }
+    return text.match(regex ?? findUrlRegex(options)) ?? [];
+}