@catbee/utils 0.0.1 → 0.0.2

package/build/esm/utils/url.utils.js

@@ -70,4 +70,291 @@ export function parseQueryString(query) {
     // Object.fromEntries guarantees string values in result
     return Object.fromEntries(new URLSearchParams(cleanQuery));
 }
+/**
+ * Validates if a string is a valid URL.
+ *
+ * @param {string} url - The URL string to validate.
+ * @param {boolean} [requireHttps=false] - If true, requires the URL to use HTTPS.
+ * @returns {boolean} True if the URL is valid, false otherwise.
+ */
+export function isValidUrl(url, requireHttps) {
+    if (requireHttps === void 0) { requireHttps = false; }
+    try {
+        var parsedUrl = new URL(url);
+        if (!parsedUrl.protocol || !parsedUrl.hostname)
+            return false;
+        if (requireHttps && parsedUrl.protocol !== "https:")
+            return false;
+        return true;
+    }
+    catch (_a) {
+        return false;
+    }
+}
+/**
+ * Extracts the domain name from a URL.
+ *
+ * @param {string} url - The URL to extract the domain from.
+ * @param {boolean} [removeSubdomains=false] - If true, removes subdomains (returns root domain only).
+ * @returns {string} The domain name.
+ *
+ * @example
+ * getDomain('https://api.example.com/path');
+ * // → 'api.example.com'
+ *
+ * getDomain('https://api.example.com/path', true);
+ * // → 'example.com'
+ */
+export function getDomain(url, removeSubdomains) {
+    if (removeSubdomains === void 0) { removeSubdomains = false; }
+    try {
+        var hostname = new URL(url).hostname;
+        if (!removeSubdomains) {
+            return hostname;
+        }
+        // Extract root domain (remove subdomains)
+        var parts = hostname.split(".");
+        if (parts.length <= 2)
+            return hostname;
+        // Handle special cases like co.in, com.au
+        var secondLevelDomains = ["co", "com", "org", "net", "gov", "edu", "ac"];
+        var sld = parts[parts.length - 2];
+        if (secondLevelDomains.includes(sld) && parts.length > 2) {
+            return parts.slice(-3).join(".");
+        }
+        return parts.slice(-2).join(".");
+    }
+    catch (_a) {
+        return "";
+    }
+}
+/**
+ * Joins URL paths properly handling slashes.
+ *
+ * @param {...string[]} segments - URL path segments to join.
+ * @returns {string} Joined URL path.
+ *
+ * @example
+ * joinPaths('https://example.com/', '/api/', '/users');
+ * // → 'https://example.com/api/users'
+ */
+export function joinPaths() {
+    var segments = [];
+    for (var _i = 0; _i < arguments.length; _i++) {
+        segments[_i] = arguments[_i];
+    }
+    var result = segments
+        .filter(function (s) { return s !== undefined && s !== null; })
+        .map(function (segment, index) {
+        if (index === 0)
+            return segment.replace(/\/+$/, "");
+        return segment.replace(/^\/+|\/+$/g, "");
+    })
+        .filter(Boolean)
+        .join("/");
+    if (segments[0] === "" && !result.startsWith("/"))
+        result = "/" + result;
+    return result;
+}
+/**
+ * Normalizes a URL by resolving relative paths, handling protocol-relative URLs, etc.
+ *
+ * @param {string} url - The URL to normalize.
+ * @param {string} [base] - Optional base URL for resolving relative URLs.
+ * @returns {string} Normalized URL.
+ *
+ * @example
+ * normalizeUrl('HTTP://Example.COM/foo/../bar');
+ * // → 'http://example.com/bar'
+ */
+export function normalizeUrl(url, base) {
+    try {
+        // Handle protocol-relative URLs
+        if (url.startsWith("//")) {
+            url = "https:".concat(url);
+        }
+        // Resolve relative URLs against a base
+        var parsedUrl = base ? new URL(url, base) : new URL(url);
+        // Normalize
+        parsedUrl.pathname = parsedUrl.pathname.replace(/\/+/g, "/"); // Collapse multiple slashes
+        parsedUrl.pathname = parsedUrl.pathname.replace(/\/+$/, ""); // Remove trailing slash
+        parsedUrl.hostname = parsedUrl.hostname.toLowerCase();
+        return parsedUrl.toString();
+    }
+    catch (_a) {
+        return url; // Return original if invalid
+    }
+}
+/**
+ * Creates a URL builder for constructing URLs with a base URL.
+ *
+ * @param {string} baseUrl - The base URL to build upon.
+ * @returns {Object} URL builder methods.
+ *
+ * @example
+ * const api = createUrlBuilder('https://api.example.com');
+ * api.path('/users', { active: true });
+ * // → 'https://api.example.com/users?active=true'
+ */
+export function createUrlBuilder(baseUrl) {
+    return {
+        /**
+         * Creates a full URL with the given path and query parameters.
+         *
+         * @param {string} path - The path to append to the base URL.
+         * @param {Record<string, any>} [params] - Query parameters to add.
+         * @returns {string} The complete URL.
+         */
+        path: function (path, params) {
+            var url = joinPaths(baseUrl, path);
+            return params
+                ? appendQueryParams(url, params)
+                : url;
+        },
+        /**
+         * Creates a full URL with query parameters but no additional path.
+         *
+         * @param {Record<string, any>} params - Query parameters to add.
+         * @returns {string} The complete URL with query parameters.
+         */
+        query: function (params) {
+            return appendQueryParams(baseUrl, params);
+        },
+    };
+}
+/**
+ * Extracts specific query parameters from a URL.
+ *
+ * @param {string} url - The URL to extract parameters from.
+ * @param {string[]} paramNames - Names of parameters to extract.
+ * @returns {Record<string, string>} Object containing the extracted parameters.
+ */
+export function extractQueryParams(url, paramNames) {
+    var e_2, _a;
+    try {
+        var parsedUrl = new URL(url);
+        var result = {};
+        try {
+            for (var paramNames_1 = __values(paramNames), paramNames_1_1 = paramNames_1.next(); !paramNames_1_1.done; paramNames_1_1 = paramNames_1.next()) {
+                var name_1 = paramNames_1_1.value;
+                var value = parsedUrl.searchParams.get(name_1);
+                if (value !== null) {
+                    result[name_1] = value;
+                }
+            }
+        }
+        catch (e_2_1) { e_2 = { error: e_2_1 }; }
+        finally {
+            try {
+                if (paramNames_1_1 && !paramNames_1_1.done && (_a = paramNames_1.return)) _a.call(paramNames_1);
+            }
+            finally { if (e_2) throw e_2.error; }
+        }
+        return result;
+    }
+    catch (_b) {
+        return {};
+    }
+}
+/**
+ * Removes specified query parameters from a URL.
+ *
+ * @param {string} url - The URL to modify.
+ * @param {string[]} paramsToRemove - Names of parameters to remove.
+ * @returns {string} URL with parameters removed.
+ */
+export function removeQueryParams(url, paramsToRemove) {
+    var e_3, _a;
+    try {
+        var parsedUrl = new URL(url);
+        try {
+            for (var paramsToRemove_1 = __values(paramsToRemove), paramsToRemove_1_1 = paramsToRemove_1.next(); !paramsToRemove_1_1.done; paramsToRemove_1_1 = paramsToRemove_1.next()) {
+                var param = paramsToRemove_1_1.value;
+                parsedUrl.searchParams.delete(param);
+            }
+        }
+        catch (e_3_1) { e_3 = { error: e_3_1 }; }
+        finally {
+            try {
+                if (paramsToRemove_1_1 && !paramsToRemove_1_1.done && (_a = paramsToRemove_1.return)) _a.call(paramsToRemove_1);
+            }
+            finally { if (e_3) throw e_3.error; }
+        }
+        return parsedUrl.toString();
+    }
+    catch (_b) {
+        return url;
+    }
+}
+/**
+ * Gets the file extension from a URL path.
+ *
+ * @param {string} url - The URL to examine.
+ * @returns {string} The file extension (without dot) or empty string if none found.
+ *
+ * @example
+ * getExtension('https://example.com/document.pdf?v=1');
+ * // → 'pdf'
+ */
+export function getExtension(url) {
+    try {
+        var pathname = new URL(url).pathname;
+        var match = pathname.match(/\.([^./\\?#]+)$/);
+        return match ? match[1].toLowerCase() : "";
+    }
+    catch (_a) {
+        // If URL parsing fails, try a simpler approach
+        var match = url.match(/\.([^./\\?#]+)$/);
+        return match ? match[1].toLowerCase() : "";
+    }
+}
+/**
+ * Parses URL query parameters into a strongly-typed object.
+ *
+ * @template T Expected type of the query parameters
+ * @param {string} url - The URL to parse.
+ * @param {Record<keyof T, (val: string) => any>} [converters] - Type converters for params.
+ * @returns {Partial<T>} Typed query parameters.
+ *
+ * @example
+ * parseTypedQueryParams<{page: number, q: string}>('https://example.com?page=2&q=test', {
+ *   page: Number,
+ *   q: String
+ * });
+ * // → { page: 2, q: 'test' }
+ */
+export function parseTypedQueryParams(url, converters) {
+    var e_4, _a;
+    try {
+        var searchParams = new URL(url).searchParams;
+        var result = {};
+        try {
+            for (var _b = __values(searchParams.entries()), _c = _b.next(); !_c.done; _c = _b.next()) {
+                var _d = __read(_c.value, 2), key = _d[0], value = _d[1];
+                if (converters && key in converters) {
+                    try {
+                        result[key] = converters[key](value);
+                    }
+                    catch (_e) {
+                        // Skip on conversion error
+                    }
+                }
+                else {
+                    result[key] = value;
+                }
+            }
+        }
+        catch (e_4_1) { e_4 = { error: e_4_1 }; }
+        finally {
+            try {
+                if (_c && !_c.done && (_a = _b.return)) _a.call(_b);
+            }
+            finally { if (e_4) throw e_4.error; }
+        }
+        return result;
+    }
+    catch (_f) {
+        return {};
+    }
+}
 //# sourceMappingURL=url.utils.js.map

package/build/esm/utils/url.utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"url.utils.js","sourceRoot":"","sources":["../../../src/utils/url.utils.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,OAAO,EAAE,GAAG,EAAE,eAAe,EAAE,MAAM,KAAK,CAAC;AAE3C;;;;;;;;;;GAUG;AACH,MAAM,UAAU,iBAAiB,CAC/B,GAAW,EACX,MAAuC;;IAEvC,IAAM,MAAM,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;;QAC5B,KAA2B,IAAA,KAAA,SAAA,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAA,gBAAA,4BAAE,CAAC;YAAzC,IAAA,KAAA,mBAAY,EAAX,GAAG,QAAA,EAAE,KAAK,QAAA;YACpB,MAAM,CAAC,YAAY,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC;QACjD,CAAC;;;;;;;;;IACD,OAAO,MAAM,CAAC,QAAQ,EAAE,CAAC;AAC3B,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAa;IAC5C,IAAM,UAAU,GAAG,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;IAClE,wDAAwD;IACxD,OAAO,MAAM,CAAC,WAAW,CAAC,IAAI,eAAe,CAAC,UAAU,CAAC,CAGxD,CAAC;AACJ,CAAC","sourcesContent":["import { URL, URLSearchParams } from \"url\";\n\n/**\n * Appends query parameters to a given URL.\n *\n * @param {string} url - The base URL to which query parameters will be appended.\n * @param {Record<string, string | number>} params - Key-value pairs to add as query parameters.\n * @returns {string} The new URL string with query parameters appended.\n *\n * @example\n * appendQueryParams('https://example.com', { page: 1, limit: 10 });\n * // → 'https://example.com/?page=1&limit=10'\n */\nexport function appendQueryParams(\n  url: string,\n  params: Record<string, string | number>,\n): string {\n  const urlObj = new URL(url);\n  for (const [key, value] of Object.entries(params)) {\n    urlObj.searchParams.set(key, value.toString());\n  }\n  return urlObj.toString();\n}\n\n/**\n * Parses a query string into a key-value object.\n *\n * @param {string} query - The query string (with or without leading '?').\n * @returns {Record<string, string>} Object representing parsed query parameters.\n *\n * @example\n * parseQueryString('?page=1&limit=10');\n * // → { page: '1', limit: '10' }\n */\nexport function parseQueryString(query: string): Record<string, string> {\n  const cleanQuery = query.startsWith(\"?\") ? query.slice(1) : query;\n  // Object.fromEntries guarantees string values in result\n  return Object.fromEntries(new URLSearchParams(cleanQuery)) as Record<\n    string,\n    string\n  >;\n}\n"]}
+{"version":3,"file":"url.utils.js","sourceRoot":"","sources":["../../../src/utils/url.utils.ts"],"names":[],"mappings":"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","sourcesContent":["import { URL, URLSearchParams } from \"url\";\n\n/**\n * Appends query parameters to a given URL.\n *\n * @param {string} url - The base URL to which query parameters will be appended.\n * @param {Record<string, string | number>} params - Key-value pairs to add as query parameters.\n * @returns {string} The new URL string with query parameters appended.\n *\n * @example\n * appendQueryParams('https://example.com', { page: 1, limit: 10 });\n * // → 'https://example.com/?page=1&limit=10'\n */\nexport function appendQueryParams(\n  url: string,\n  params: Record<string, string | number>,\n): string {\n  const urlObj = new URL(url);\n  for (const [key, value] of Object.entries(params)) {\n    urlObj.searchParams.set(key, value.toString());\n  }\n  return urlObj.toString();\n}\n\n/**\n * Parses a query string into a key-value object.\n *\n * @param {string} query - The query string (with or without leading '?').\n * @returns {Record<string, string>} Object representing parsed query parameters.\n *\n * @example\n * parseQueryString('?page=1&limit=10');\n * // → { page: '1', limit: '10' }\n */\nexport function parseQueryString(query: string): Record<string, string> {\n  const cleanQuery = query.startsWith(\"?\") ? query.slice(1) : query;\n  // Object.fromEntries guarantees string values in result\n  return Object.fromEntries(new URLSearchParams(cleanQuery)) as Record<\n    string,\n    string\n  >;\n}\n\n/**\n * Validates if a string is a valid URL.\n *\n * @param {string} url - The URL string to validate.\n * @param {boolean} [requireHttps=false] - If true, requires the URL to use HTTPS.\n * @returns {boolean} True if the URL is valid, false otherwise.\n */\nexport function isValidUrl(\n  url: string,\n  requireHttps: boolean = false,\n): boolean {\n  try {\n    const parsedUrl = new URL(url);\n    if (!parsedUrl.protocol || !parsedUrl.hostname) return false;\n    if (requireHttps && parsedUrl.protocol !== \"https:\") return false;\n    return true;\n  } catch {\n    return false;\n  }\n}\n\n/**\n * Extracts the domain name from a URL.\n *\n * @param {string} url - The URL to extract the domain from.\n * @param {boolean} [removeSubdomains=false] - If true, removes subdomains (returns root domain only).\n * @returns {string} The domain name.\n *\n * @example\n * getDomain('https://api.example.com/path');\n * // → 'api.example.com'\n *\n * getDomain('https://api.example.com/path', true);\n * // → 'example.com'\n */\nexport function getDomain(\n  url: string,\n  removeSubdomains: boolean = false,\n): string {\n  try {\n    const { hostname } = new URL(url);\n\n    if (!removeSubdomains) {\n      return hostname;\n    }\n\n    // Extract root domain (remove subdomains)\n    const parts = hostname.split(\".\");\n    if (parts.length <= 2) return hostname;\n\n    // Handle special cases like co.in, com.au\n    const secondLevelDomains = [\"co\", \"com\", \"org\", \"net\", \"gov\", \"edu\", \"ac\"];\n    const sld = parts[parts.length - 2];\n\n    if (secondLevelDomains.includes(sld) && parts.length > 2) {\n      return parts.slice(-3).join(\".\");\n    }\n\n    return parts.slice(-2).join(\".\");\n  } catch {\n    return \"\";\n  }\n}\n\n/**\n * Joins URL paths properly handling slashes.\n *\n * @param {...string[]} segments - URL path segments to join.\n * @returns {string} Joined URL path.\n *\n * @example\n * joinPaths('https://example.com/', '/api/', '/users');\n * // → 'https://example.com/api/users'\n */\nexport function joinPaths(...segments: string[]): string {\n  let result = segments\n    .filter((s) => s !== undefined && s !== null)\n    .map((segment, index) => {\n      if (index === 0) return segment.replace(/\\/+$/, \"\");\n      return segment.replace(/^\\/+|\\/+$/g, \"\");\n    })\n    .filter(Boolean)\n    .join(\"/\");\n  if (segments[0] === \"\" && !result.startsWith(\"/\")) result = \"/\" + result;\n  return result;\n}\n\n/**\n * Normalizes a URL by resolving relative paths, handling protocol-relative URLs, etc.\n *\n * @param {string} url - The URL to normalize.\n * @param {string} [base] - Optional base URL for resolving relative URLs.\n * @returns {string} Normalized URL.\n *\n * @example\n * normalizeUrl('HTTP://Example.COM/foo/../bar');\n * // → 'http://example.com/bar'\n */\nexport function normalizeUrl(url: string, base?: string): string {\n  try {\n    // Handle protocol-relative URLs\n    if (url.startsWith(\"//\")) {\n      url = `https:${url}`;\n    }\n\n    // Resolve relative URLs against a base\n    const parsedUrl = base ? new URL(url, base) : new URL(url);\n\n    // Normalize\n    parsedUrl.pathname = parsedUrl.pathname.replace(/\\/+/g, \"/\"); // Collapse multiple slashes\n    parsedUrl.pathname = parsedUrl.pathname.replace(/\\/+$/, \"\"); // Remove trailing slash\n    parsedUrl.hostname = parsedUrl.hostname.toLowerCase();\n\n    return parsedUrl.toString();\n  } catch {\n    return url; // Return original if invalid\n  }\n}\n\n/**\n * Creates a URL builder for constructing URLs with a base URL.\n *\n * @param {string} baseUrl - The base URL to build upon.\n * @returns {Object} URL builder methods.\n *\n * @example\n * const api = createUrlBuilder('https://api.example.com');\n * api.path('/users', { active: true });\n * // → 'https://api.example.com/users?active=true'\n */\nexport function createUrlBuilder(baseUrl: string) {\n  return {\n    /**\n     * Creates a full URL with the given path and query parameters.\n     *\n     * @param {string} path - The path to append to the base URL.\n     * @param {Record<string, any>} [params] - Query parameters to add.\n     * @returns {string} The complete URL.\n     */\n    path(path: string, params?: Record<string, any>): string {\n      const url = joinPaths(baseUrl, path);\n      return params\n        ? appendQueryParams(url, params as Record<string, string | number>)\n        : url;\n    },\n\n    /**\n     * Creates a full URL with query parameters but no additional path.\n     *\n     * @param {Record<string, any>} params - Query parameters to add.\n     * @returns {string} The complete URL with query parameters.\n     */\n    query(params: Record<string, any>): string {\n      return appendQueryParams(\n        baseUrl,\n        params as Record<string, string | number>,\n      );\n    },\n  };\n}\n\n/**\n * Extracts specific query parameters from a URL.\n *\n * @param {string} url - The URL to extract parameters from.\n * @param {string[]} paramNames - Names of parameters to extract.\n * @returns {Record<string, string>} Object containing the extracted parameters.\n */\nexport function extractQueryParams(\n  url: string,\n  paramNames: string[],\n): Record<string, string> {\n  try {\n    const parsedUrl = new URL(url);\n    const result: Record<string, string> = {};\n\n    for (const name of paramNames) {\n      const value = parsedUrl.searchParams.get(name);\n      if (value !== null) {\n        result[name] = value;\n      }\n    }\n\n    return result;\n  } catch {\n    return {};\n  }\n}\n\n/**\n * Removes specified query parameters from a URL.\n *\n * @param {string} url - The URL to modify.\n * @param {string[]} paramsToRemove - Names of parameters to remove.\n * @returns {string} URL with parameters removed.\n */\nexport function removeQueryParams(\n  url: string,\n  paramsToRemove: string[],\n): string {\n  try {\n    const parsedUrl = new URL(url);\n\n    for (const param of paramsToRemove) {\n      parsedUrl.searchParams.delete(param);\n    }\n\n    return parsedUrl.toString();\n  } catch {\n    return url;\n  }\n}\n\n/**\n * Gets the file extension from a URL path.\n *\n * @param {string} url - The URL to examine.\n * @returns {string} The file extension (without dot) or empty string if none found.\n *\n * @example\n * getExtension('https://example.com/document.pdf?v=1');\n * // → 'pdf'\n */\nexport function getExtension(url: string): string {\n  try {\n    const { pathname } = new URL(url);\n    const match = pathname.match(/\\.([^./\\\\?#]+)$/);\n    return match ? match[1].toLowerCase() : \"\";\n  } catch {\n    // If URL parsing fails, try a simpler approach\n    const match = url.match(/\\.([^./\\\\?#]+)$/);\n    return match ? match[1].toLowerCase() : \"\";\n  }\n}\n\n/**\n * Parses URL query parameters into a strongly-typed object.\n *\n * @template T Expected type of the query parameters\n * @param {string} url - The URL to parse.\n * @param {Record<keyof T, (val: string) => any>} [converters] - Type converters for params.\n * @returns {Partial<T>} Typed query parameters.\n *\n * @example\n * parseTypedQueryParams<{page: number, q: string}>('https://example.com?page=2&q=test', {\n *   page: Number,\n *   q: String\n * });\n * // → { page: 2, q: 'test' }\n */\nexport function parseTypedQueryParams<T extends Record<string, any>>(\n  url: string,\n  converters?: Record<keyof T, (val: string) => any>,\n): Partial<T> {\n  try {\n    const { searchParams } = new URL(url);\n    const result = {} as Partial<T>;\n\n    for (const [key, value] of searchParams.entries()) {\n      if (converters && key in converters) {\n        try {\n          result[key as keyof T] = converters[key as keyof T](value);\n        } catch {\n          // Skip on conversion error\n        }\n      } else {\n        result[key as keyof T] = value as any;\n      }\n    }\n\n    return result;\n  } catch {\n    return {};\n  }\n}\n"]}

package/build/esm/utils/validate.utils.d.ts

@@ -57,4 +57,114 @@ export declare function isHexColor(str: string): boolean;
  * @returns {boolean}
  */
 export declare function isISODate(str: string): boolean;
+/**
+ * Checks if a string matches a specified length range.
+ *
+ * @param {string} str - The input string.
+ * @param {number} min - Minimum length (inclusive).
+ * @param {number} max - Maximum length (inclusive).
+ * @returns {boolean} True if string length is within range.
+ */
+export declare function isLengthBetween(str: string, min: number, max: number): boolean;
+/**
+ * Validates that a number is between specified min and max values (inclusive).
+ *
+ * @param {number} value - The number to validate.
+ * @param {number} min - Minimum value.
+ * @param {number} max - Maximum value.
+ * @returns {boolean} True if number is within range.
+ */
+export declare function isNumberBetween(value: number, min: number, max: number): boolean;
+/**
+ * Checks if a string contains only alphabetic characters.
+ *
+ * @param {string} str - The input string.
+ * @returns {boolean} True if alphabetic only.
+ */
+export declare function isAlpha(str: string): boolean;
+/**
+ * Validates that a string contains at least one uppercase letter,
+ * one lowercase letter, one number, and one special character.
+ *
+ * @param {string} str - The input string.
+ * @returns {boolean} True if string meets password complexity requirements.
+ */
+export declare function isStrongPassword(str: string): boolean;
+/**
+ * Checks if a string is a valid IPv4 address.
+ *
+ * @param {string} str - The input string.
+ * @returns {boolean} True if valid IPv4 address.
+ */
+export declare function isIPv4(str: string): boolean;
+/**
+ * Checks if a string is a valid IPv6 address.
+ *
+ * @param {string} str - The input string.
+ * @returns {boolean} True if valid IPv6 address.
+ */
+export declare function isIPv6(str: string): boolean;
+/**
+ * Validates a credit card number using the Luhn algorithm.
+ *
+ * @param {string} str - The credit card number string.
+ * @returns {boolean} True if valid credit card number.
+ */
+export declare function isCreditCard(str: string): boolean;
+/**
+ * Checks if a string is a valid JSON.
+ *
+ * @param {string} str - The input string.
+ * @returns {boolean} True if valid JSON.
+ */
+export declare function isValidJSON(str: string): boolean;
+/**
+ * Type guard that checks if a value is an array.
+ *
+ * @template T Optional expected element type
+ * @param {unknown} value - The value to check.
+ * @param {(item: unknown) => boolean} [itemGuard] - Optional function to validate each item.
+ * @returns {boolean} True if value is an array (with optional item validation).
+ */
+export declare function isArray<T = unknown>(value: unknown, itemGuard?: (item: unknown) => item is T): value is T[];
+/**
+ * Checks if a string is a valid base64 encoded string.
+ *
+ * @param {string} str - The input string.
+ * @returns {boolean} True if valid base64.
+ */
+export declare function isBase64(str: string): boolean;
+/**
+ * Validates that an object has all required properties.
+ *
+ * @param {object} obj - The object to validate.
+ * @param {string[]} requiredProps - Array of required property names.
+ * @returns {boolean} True if all required properties exist.
+ */
+export declare function hasRequiredProps(obj: Record<string, unknown>, requiredProps: string[]): boolean;
+/**
+ * Validates a date is within a specified range.
+ *
+ * @param {Date} date - The date to validate.
+ * @param {Date} [minDate] - Optional minimum date (inclusive).
+ * @param {Date} [maxDate] - Optional maximum date (inclusive).
+ * @returns {boolean} True if date is within range.
+ */
+export declare function isDateInRange(date: Date, minDate?: Date, maxDate?: Date): boolean;
+/**
+ * Validates a string matches a specific regular expression pattern.
+ *
+ * @param {string} str - The input string.
+ * @param {RegExp} pattern - Regular expression to test against.
+ * @returns {boolean} True if string matches pattern.
+ */
+export declare function matchesPattern(str: string, pattern: RegExp): boolean;
+/**
+ * Validates data against multiple constraints.
+ *
+ * @param {unknown} value - The value to validate.
+ * @param {Array<(value: unknown) => boolean>} validators - Array of validation functions.
+ * @returns {boolean} True if value passes all validations.
+ */
+export declare function validateAll(value: unknown, validators: Array<(value: unknown) => boolean>): boolean;
 //# sourceMappingURL=validate.utils.d.ts.map

package/build/esm/utils/validate.utils.js

@@ -118,4 +118,190 @@ export function isISODate(str) {
     var date = new Date(str);
     return (!isNaN(date.getTime()) && date.toISOString().startsWith(str.slice(0, 10)));
 }
+/**
+ * Checks if a string matches a specified length range.
+ *
+ * @param {string} str - The input string.
+ * @param {number} min - Minimum length (inclusive).
+ * @param {number} max - Maximum length (inclusive).
+ * @returns {boolean} True if string length is within range.
+ */
+export function isLengthBetween(str, min, max) {
+    return str.length >= min && str.length <= max;
+}
+/**
+ * Validates that a number is between specified min and max values (inclusive).
+ *
+ * @param {number} value - The number to validate.
+ * @param {number} min - Minimum value.
+ * @param {number} max - Maximum value.
+ * @returns {boolean} True if number is within range.
+ */
+export function isNumberBetween(value, min, max) {
+    return value >= min && value <= max;
+}
+/**
+ * Checks if a string contains only alphabetic characters.
+ *
+ * @param {string} str - The input string.
+ * @returns {boolean} True if alphabetic only.
+ */
+export function isAlpha(str) {
+    return /^[a-zA-Z]+$/.test(str);
+}
+/**
+ * Validates that a string contains at least one uppercase letter,
+ * one lowercase letter, one number, and one special character.
+ *
+ * @param {string} str - The input string.
+ * @returns {boolean} True if string meets password complexity requirements.
+ */
+export function isStrongPassword(str) {
+    if (str.length < 8)
+        return false;
+    var hasUpperCase = /[A-Z]/.test(str);
+    var hasLowerCase = /[a-z]/.test(str);
+    var hasNumbers = /[0-9]/.test(str);
+    var hasSpecialChar = /[!@#$%^&*()_+\-=[\]{};':"\\|,.<>?]/.test(str);
+    return hasUpperCase && hasLowerCase && hasNumbers && hasSpecialChar;
+}
+/**
+ * Checks if a string is a valid IPv4 address.
+ *
+ * @param {string} str - The input string.
+ * @returns {boolean} True if valid IPv4 address.
+ */
+export function isIPv4(str) {
+    var parts = str.split(".");
+    if (parts.length !== 4)
+        return false;
+    return parts.every(function (part) {
+        var num = parseInt(part, 10);
+        return part === num.toString() && num >= 0 && num <= 255;
+    });
+}
+/**
+ * Checks if a string is a valid IPv6 address.
+ *
+ * @param {string} str - The input string.
+ * @returns {boolean} True if valid IPv6 address.
+ */
+export function isIPv6(str) {
+    // Simple but effective check for common IPv6 formats
+    return /^(([0-9a-fA-F]{1,4}:){7}[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,7}:|([0-9a-fA-F]{1,4}:){1,6}:[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,5}(:[0-9a-fA-F]{1,4}){1,2}|([0-9a-fA-F]{1,4}:){1,4}(:[0-9a-fA-F]{1,4}){1,3}|([0-9a-fA-F]{1,4}:){1,3}(:[0-9a-fA-F]{1,4}){1,4}|([0-9a-fA-F]{1,4}:){1,2}(:[0-9a-fA-F]{1,4}){1,5}|[0-9a-fA-F]{1,4}:((:[0-9a-fA-F]{1,4}){1,6})|:((:[0-9a-fA-F]{1,4}){1,7}|:)|fe80:(:[0-9a-fA-F]{0,4}){0,4}%[0-9a-zA-Z]+|::(ffff(:0{1,4})?:)?((25[0-5]|(2[0-4]|1?[0-9])?[0-9])\.){3}(25[0-5]|(2[0-4]|1?[0-9])?[0-9])|([0-9a-fA-F]{1,4}:){1,4}:((25[0-5]|(2[0-4]|1?[0-9])?[0-9])\.){3}(25[0-5]|(2[0-4]|1?[0-9])?[0-9]))$/.test(str);
+}
+/**
+ * Validates a credit card number using the Luhn algorithm.
+ *
+ * @param {string} str - The credit card number string.
+ * @returns {boolean} True if valid credit card number.
+ */
+export function isCreditCard(str) {
+    // Remove non-digit characters
+    var cardNumber = str.replace(/\D/g, "");
+    if (cardNumber.length < 13 || cardNumber.length > 19)
+        return false;
+    // Luhn algorithm implementation
+    var sum = 0;
+    var shouldDouble = false;
+    for (var i = cardNumber.length - 1; i >= 0; i--) {
+        var digit = parseInt(cardNumber.charAt(i), 10);
+        if (shouldDouble) {
+            digit *= 2;
+            if (digit > 9)
+                digit -= 9;
+        }
+        sum += digit;
+        shouldDouble = !shouldDouble;
+    }
+    return sum % 10 === 0;
+}
+/**
+ * Checks if a string is a valid JSON.
+ *
+ * @param {string} str - The input string.
+ * @returns {boolean} True if valid JSON.
+ */
+export function isValidJSON(str) {
+    try {
+        JSON.parse(str);
+        return true;
+    }
+    catch (_a) {
+        return false;
+    }
+}
+/**
+ * Type guard that checks if a value is an array.
+ *
+ * @template T Optional expected element type
+ * @param {unknown} value - The value to check.
+ * @param {(item: unknown) => boolean} [itemGuard] - Optional function to validate each item.
+ * @returns {boolean} True if value is an array (with optional item validation).
+ */
+export function isArray(value, itemGuard) {
+    if (!Array.isArray(value))
+        return false;
+    return !itemGuard || value.every(function (item) { return itemGuard(item); });
+}
+/**
+ * Checks if a string is a valid base64 encoded string.
+ *
+ * @param {string} str - The input string.
+ * @returns {boolean} True if valid base64.
+ */
+export function isBase64(str) {
+    return /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(str);
+}
+/**
+ * Validates that an object has all required properties.
+ *
+ * @param {object} obj - The object to validate.
+ * @param {string[]} requiredProps - Array of required property names.
+ * @returns {boolean} True if all required properties exist.
+ */
+export function hasRequiredProps(obj, requiredProps) {
+    return requiredProps.every(function (prop) {
+        return Object.prototype.hasOwnProperty.call(obj, prop) &&
+            obj[prop] !== undefined &&
+            obj[prop] !== null;
+    });
+}
+/**
+ * Validates a date is within a specified range.
+ *
+ * @param {Date} date - The date to validate.
+ * @param {Date} [minDate] - Optional minimum date (inclusive).
+ * @param {Date} [maxDate] - Optional maximum date (inclusive).
+ * @returns {boolean} True if date is within range.
+ */
+export function isDateInRange(date, minDate, maxDate) {
+    if (!(date instanceof Date) || isNaN(date.getTime()))
+        return false;
+    if (minDate && date < minDate)
+        return false;
+    if (maxDate && date > maxDate)
+        return false;
+    return true;
+}
+/**
+ * Validates a string matches a specific regular expression pattern.
+ *
+ * @param {string} str - The input string.
+ * @param {RegExp} pattern - Regular expression to test against.
+ * @returns {boolean} True if string matches pattern.
+ */
+export function matchesPattern(str, pattern) {
+    return pattern.test(str);
+}
+/**
+ * Validates data against multiple constraints.
+ *
+ * @param {unknown} value - The value to validate.
+ * @param {Array<(value: unknown) => boolean>} validators - Array of validation functions.
+ * @returns {boolean} True if value passes all validations.
+ */
+export function validateAll(value, validators) {
+    return validators.every(function (validator) { return validator(value); });
+}
 //# sourceMappingURL=validate.utils.js.map