@catbee/utils 0.0.1 → 0.0.2

package/build/src/utils/string.utils.js

@@ -1,47 +1,62 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.truncate = exports.slugify = exports.toCamelCase = exports.toKebabCase = exports.capitalize = void 0;
+exports.capitalize = capitalize;
+exports.toKebabCase = toKebabCase;
+exports.toCamelCase = toCamelCase;
+exports.slugify = slugify;
+exports.truncate = truncate;
+exports.toPascalCase = toPascalCase;
+exports.toSnakeCase = toSnakeCase;
+exports.mask = mask;
+exports.stripHtml = stripHtml;
+exports.equalsIgnoreCase = equalsIgnoreCase;
+exports.reverse = reverse;
+exports.countOccurrences = countOccurrences;
 /**
  * Capitalizes the first character of a string.
  *
  * @param {string} str - The input string.
  * @returns {string} The string with the first character in uppercase.
  */
-const capitalize = (str) => str.length === 0 ? "" : str.charAt(0).toUpperCase() + str.slice(1);
-exports.capitalize = capitalize;
+function capitalize(str) {
+    return str.length === 0 ? "" : str.charAt(0).toUpperCase() + str.slice(1);
+}
 /**
  * Converts a string to kebab-case (e.g., "FooBar test" → "foo-bar-test").
  *
  * @param {string} str - The input string.
  * @returns {string} The kebab-cased string.
  */
-const toKebabCase = (str) => str
-    .replace(/([a-z])([A-Z])/g, "$1-$2") // camelCase -> camel-Case
-    .replace(/\s+/g, "-") // spaces to dash
-    .replace(/_+/g, "-") // underscores to dash
-    .toLowerCase();
-exports.toKebabCase = toKebabCase;
+function toKebabCase(str) {
+    return str
+        .replace(/([a-z])([A-Z])/g, "$1-$2") // camelCase -> camel-Case
+        .replace(/\s+/g, "-") // spaces to dash
+        .replace(/_+/g, "-") // underscores to dash
+        .toLowerCase();
+}
 /**
  * Converts a kebab-case or snake_case string to camelCase.
  *
  * @param {string} str - The input string.
  * @returns {string} The camelCased string.
  */
-const toCamelCase = (str) => str.replace(/[-_](.)/g, (_, c) => c.toUpperCase());
-exports.toCamelCase = toCamelCase;
+function toCamelCase(str) {
+    return str.replace(/[-_](.)/g, (_, c) => c.toUpperCase());
+}
 /**
  * Converts a string to a URL-friendly slug (lowercase, dashes, alphanumeric).
  *
  * @param {string} str - The input string.
  * @returns {string} The slugified string.
  */
-const slugify = (str) => str
-    .toLowerCase()
-    .replace(/[^\w\s-]/g, "") // remove non-word
-    .replace(/\s+/g, "-") // spaces to dash
-    .replace(/-+/g, "-") // multiple dashes to one
-    .replace(/^-+|-+$/g, ""); // trim leading/trailing dashes
-exports.slugify = slugify;
+function slugify(str) {
+    return str
+        .toLowerCase()
+        .replace(/[^\w\s-]/g, "") // remove non-word
+        .replace(/\s+/g, "-") // spaces to dash
+        .replace(/-+/g, "-") // multiple dashes to one
+        .replace(/^-+|-+$/g, ""); // trim leading/trailing dashes
+}
 /**
  * Truncates a string to a specific length, appending '...' if truncated.
  *
@@ -49,6 +64,93 @@ exports.slugify = slugify;
  * @param {number} len - The maximum length.
  * @returns {string} The truncated string.
  */
-const truncate = (str, len) => str.length > len ? str.slice(0, len) + "..." : str;
-exports.truncate = truncate;
+function truncate(str, len) {
+    return str.length > len ? str.slice(0, len) + "..." : str;
+}
+/**
+ * Converts a string to PascalCase (e.g., "foo-bar" → "FooBar").
+ *
+ * @param {string} str - The input string.
+ * @returns {string} The PascalCased string.
+ */
+function toPascalCase(str) {
+    return capitalize(toCamelCase(str));
+}
+/**
+ * Converts a string to snake_case (e.g., "FooBar test" → "foo_bar_test").
+ *
+ * @param {string} str - The input string.
+ * @returns {string} The snake_cased string.
+ */
+function toSnakeCase(str) {
+    return str
+        .trim()
+        .replace(/([a-z])([A-Z])/g, "$1_$2") // camelCase -> camel_Case
+        .replace(/\s+/g, "_") // spaces to underscore
+        .replace(/-+/g, "_") // dashes to underscore
+        .toLowerCase();
+}
+/**
+ * Masks a string by replacing characters with a mask character.
+ * Useful for hiding sensitive information like credit cards or passwords.
+ *
+ * @param {string} str - The string to mask.
+ * @param {number} [visibleStart=0] - Number of characters to show at start.
+ * @param {number} [visibleEnd=0] - Number of characters to show at end.
+ * @param {string} [maskChar="*"] - Character to use for masking.
+ * @returns {string} The masked string.
+ */
+function mask(str, visibleStart = 0, visibleEnd = 0, maskChar = "*") {
+    if (!str || str.length === 0)
+        return "";
+    if (visibleStart >= str.length)
+        return str;
+    const start = str.slice(0, visibleStart);
+    const end = visibleEnd > 0 ? str.slice(-visibleEnd) : "";
+    const masked = maskChar.repeat(Math.max(0, str.length - visibleStart - visibleEnd));
+    return start + masked + end;
+}
+/**
+ * Removes all HTML tags from a string.
+ *
+ * @param {string} str - The HTML string to process.
+ * @returns {string} The string with HTML tags removed.
+ */
+function stripHtml(str) {
+    return str.replace(/<[^>]*>/g, "");
+}
+/**
+ * Performs case-insensitive string comparison.
+ *
+ * @param {string} a - First string.
+ * @param {string} b - Second string.
+ * @returns {boolean} True if the strings are equal ignoring case.
+ */
+function equalsIgnoreCase(a, b) {
+    return a.toLowerCase() === b.toLowerCase();
+}
+/**
+ * Reverses a string.
+ *
+ * @param {string} str - The string to reverse.
+ * @returns {string} The reversed string.
+ */
+function reverse(str) {
+    return str.split("").reverse().join("");
+}
+/**
+ * Counts occurrences of a substring within a string.
+ *
+ * @param {string} str - The source string.
+ * @param {string} substring - The substring to count.
+ * @param {boolean} [caseSensitive=true] - Whether to perform case-sensitive counting.
+ * @returns {number} Number of occurrences.
+ */
+function countOccurrences(str, substring, caseSensitive = true) {
+    if (!caseSensitive) {
+        str = str.toLowerCase();
+        substring = substring.toLowerCase();
+    }
+    return str.split(substring).length - 1;
+}
 //# sourceMappingURL=string.utils.js.map

package/build/src/utils/string.utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"string.utils.js","sourceRoot":"","sources":["../../../src/utils/string.utils.ts"],"names":[],"mappings":";;;AAAA;;;;;GAKG;AACI,MAAM,UAAU,GAAG,CAAC,GAAW,EAAU,EAAE,CAChD,GAAG,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AADxD,QAAA,UAAU,cAC8C;AAErE;;;;;GAKG;AACI,MAAM,WAAW,GAAG,CAAC,GAAW,EAAU,EAAE,CACjD,GAAG;KACA,OAAO,CAAC,iBAAiB,EAAE,OAAO,CAAC,CAAC,0BAA0B;KAC9D,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,iBAAiB;KACtC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,sBAAsB;KAC1C,WAAW,EAAE,CAAC;AALN,QAAA,WAAW,eAKL;AAEnB;;;;;GAKG;AACI,MAAM,WAAW,GAAG,CAAC,GAAW,EAAU,EAAE,CACjD,GAAG,CAAC,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC,EAAE,CAAS,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC;AADhD,QAAA,WAAW,eACqC;AAE7D;;;;;GAKG;AACI,MAAM,OAAO,GAAG,CAAC,GAAW,EAAU,EAAE,CAC7C,GAAG;KACA,WAAW,EAAE;KACb,OAAO,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC,kBAAkB;KAC3C,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,iBAAiB;KACtC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,yBAAyB;KAC7C,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC,CAAC,+BAA+B;AANhD,QAAA,OAAO,WAMS;AAE7B;;;;;;GAMG;AACI,MAAM,QAAQ,GAAG,CAAC,GAAW,EAAE,GAAW,EAAU,EAAE,CAC3D,GAAG,CAAC,MAAM,GAAG,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC;AADxC,QAAA,QAAQ,YACgC","sourcesContent":["/**\n * Capitalizes the first character of a string.\n *\n * @param {string} str - The input string.\n * @returns {string} The string with the first character in uppercase.\n */\nexport const capitalize = (str: string): string =>\n  str.length === 0 ? \"\" : str.charAt(0).toUpperCase() + str.slice(1);\n\n/**\n * Converts a string to kebab-case (e.g., \"FooBar test\" → \"foo-bar-test\").\n *\n * @param {string} str - The input string.\n * @returns {string} The kebab-cased string.\n */\nexport const toKebabCase = (str: string): string =>\n  str\n    .replace(/([a-z])([A-Z])/g, \"$1-$2\") // camelCase -> camel-Case\n    .replace(/\\s+/g, \"-\") // spaces to dash\n    .replace(/_+/g, \"-\") // underscores to dash\n    .toLowerCase();\n\n/**\n * Converts a kebab-case or snake_case string to camelCase.\n *\n * @param {string} str - The input string.\n * @returns {string} The camelCased string.\n */\nexport const toCamelCase = (str: string): string =>\n  str.replace(/[-_](.)/g, (_, c: string) => c.toUpperCase());\n\n/**\n * Converts a string to a URL-friendly slug (lowercase, dashes, alphanumeric).\n *\n * @param {string} str - The input string.\n * @returns {string} The slugified string.\n */\nexport const slugify = (str: string): string =>\n  str\n    .toLowerCase()\n    .replace(/[^\\w\\s-]/g, \"\") // remove non-word\n    .replace(/\\s+/g, \"-\") // spaces to dash\n    .replace(/-+/g, \"-\") // multiple dashes to one\n    .replace(/^-+|-+$/g, \"\"); // trim leading/trailing dashes\n\n/**\n * Truncates a string to a specific length, appending '...' if truncated.\n *\n * @param {string} str - The input string.\n * @param {number} len - The maximum length.\n * @returns {string} The truncated string.\n */\nexport const truncate = (str: string, len: number): string =>\n  str.length > len ? str.slice(0, len) + \"...\" : str;\n"]}
+{"version":3,"file":"string.utils.js","sourceRoot":"","sources":["../../../src/utils/string.utils.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Capitalizes the first character of a string.\n *\n * @param {string} str - The input string.\n * @returns {string} The string with the first character in uppercase.\n */\nexport function capitalize(str: string): string {\n  return str.length === 0 ? \"\" : str.charAt(0).toUpperCase() + str.slice(1);\n}\n\n/**\n * Converts a string to kebab-case (e.g., \"FooBar test\" → \"foo-bar-test\").\n *\n * @param {string} str - The input string.\n * @returns {string} The kebab-cased string.\n */\nexport function toKebabCase(str: string): string {\n  return str\n    .replace(/([a-z])([A-Z])/g, \"$1-$2\") // camelCase -> camel-Case\n    .replace(/\\s+/g, \"-\") // spaces to dash\n    .replace(/_+/g, \"-\") // underscores to dash\n    .toLowerCase();\n}\n\n/**\n * Converts a kebab-case or snake_case string to camelCase.\n *\n * @param {string} str - The input string.\n * @returns {string} The camelCased string.\n */\nexport function toCamelCase(str: string): string {\n  return str.replace(/[-_](.)/g, (_, c: string) => c.toUpperCase());\n}\n\n/**\n * Converts a string to a URL-friendly slug (lowercase, dashes, alphanumeric).\n *\n * @param {string} str - The input string.\n * @returns {string} The slugified string.\n */\nexport function slugify(str: string): string {\n  return str\n    .toLowerCase()\n    .replace(/[^\\w\\s-]/g, \"\") // remove non-word\n    .replace(/\\s+/g, \"-\") // spaces to dash\n    .replace(/-+/g, \"-\") // multiple dashes to one\n    .replace(/^-+|-+$/g, \"\"); // trim leading/trailing dashes\n}\n\n/**\n * Truncates a string to a specific length, appending '...' if truncated.\n *\n * @param {string} str - The input string.\n * @param {number} len - The maximum length.\n * @returns {string} The truncated string.\n */\nexport function truncate(str: string, len: number): string {\n  return str.length > len ? str.slice(0, len) + \"...\" : str;\n}\n\n/**\n * Converts a string to PascalCase (e.g., \"foo-bar\" → \"FooBar\").\n *\n * @param {string} str - The input string.\n * @returns {string} The PascalCased string.\n */\nexport function toPascalCase(str: string): string {\n  return capitalize(toCamelCase(str));\n}\n\n/**\n * Converts a string to snake_case (e.g., \"FooBar test\" → \"foo_bar_test\").\n *\n * @param {string} str - The input string.\n * @returns {string} The snake_cased string.\n */\nexport function toSnakeCase(str: string): string {\n  return str\n    .trim()\n    .replace(/([a-z])([A-Z])/g, \"$1_$2\") // camelCase -> camel_Case\n    .replace(/\\s+/g, \"_\") // spaces to underscore\n    .replace(/-+/g, \"_\") // dashes to underscore\n    .toLowerCase();\n}\n\n/**\n * Masks a string by replacing characters with a mask character.\n * Useful for hiding sensitive information like credit cards or passwords.\n *\n * @param {string} str - The string to mask.\n * @param {number} [visibleStart=0] - Number of characters to show at start.\n * @param {number} [visibleEnd=0] - Number of characters to show at end.\n * @param {string} [maskChar=\"*\"] - Character to use for masking.\n * @returns {string} The masked string.\n */\nexport function mask(\n  str: string,\n  visibleStart: number = 0,\n  visibleEnd: number = 0,\n  maskChar: string = \"*\",\n): string {\n  if (!str || str.length === 0) return \"\";\n  if (visibleStart >= str.length) return str;\n\n  const start = str.slice(0, visibleStart);\n  const end = visibleEnd > 0 ? str.slice(-visibleEnd) : \"\";\n  const masked = maskChar.repeat(\n    Math.max(0, str.length - visibleStart - visibleEnd),\n  );\n\n  return start + masked + end;\n}\n\n/**\n * Removes all HTML tags from a string.\n *\n * @param {string} str - The HTML string to process.\n * @returns {string} The string with HTML tags removed.\n */\nexport function stripHtml(str: string): string {\n  return str.replace(/<[^>]*>/g, \"\");\n}\n\n/**\n * Performs case-insensitive string comparison.\n *\n * @param {string} a - First string.\n * @param {string} b - Second string.\n * @returns {boolean} True if the strings are equal ignoring case.\n */\nexport function equalsIgnoreCase(a: string, b: string): boolean {\n  return a.toLowerCase() === b.toLowerCase();\n}\n\n/**\n * Reverses a string.\n *\n * @param {string} str - The string to reverse.\n * @returns {string} The reversed string.\n */\nexport function reverse(str: string): string {\n  return str.split(\"\").reverse().join(\"\");\n}\n\n/**\n * Counts occurrences of a substring within a string.\n *\n * @param {string} str - The source string.\n * @param {string} substring - The substring to count.\n * @param {boolean} [caseSensitive=true] - Whether to perform case-sensitive counting.\n * @returns {number} Number of occurrences.\n */\nexport function countOccurrences(\n  str: string,\n  substring: string,\n  caseSensitive: boolean = true,\n): number {\n  if (!caseSensitive) {\n    str = str.toLowerCase();\n    substring = substring.toLowerCase();\n  }\n\n  return str.split(substring).length - 1;\n}\n"]}

package/build/src/utils/url.utils.d.ts

@@ -21,4 +21,121 @@ export declare function appendQueryParams(url: string, params: Record<string, st
  * // → { page: '1', limit: '10' }
  */
 export declare function parseQueryString(query: string): Record<string, string>;
+/**
+ * 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 declare function isValidUrl(url: string, requireHttps?: boolean): boolean;
+/**
+ * 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 declare function getDomain(url: string, removeSubdomains?: boolean): string;
+/**
+ * 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 declare function joinPaths(...segments: string[]): string;
+/**
+ * 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 declare function normalizeUrl(url: string, base?: string): string;
+/**
+ * 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 declare function createUrlBuilder(baseUrl: string): {
+    /**
+     * 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(path: string, params?: Record<string, any>): string;
+    /**
+     * 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(params: Record<string, any>): string;
+};
+/**
+ * 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 declare function extractQueryParams(url: string, paramNames: string[]): Record<string, string>;
+/**
+ * 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 declare function removeQueryParams(url: string, paramsToRemove: string[]): string;
+/**
+ * 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 declare function getExtension(url: string): string;
+/**
+ * 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 declare function parseTypedQueryParams<T extends Record<string, any>>(url: string, converters?: Record<keyof T, (val: string) => any>): Partial<T>;
 //# sourceMappingURL=url.utils.d.ts.map

package/build/src/utils/url.utils.js

@@ -2,6 +2,15 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.appendQueryParams = appendQueryParams;
 exports.parseQueryString = parseQueryString;
+exports.isValidUrl = isValidUrl;
+exports.getDomain = getDomain;
+exports.joinPaths = joinPaths;
+exports.normalizeUrl = normalizeUrl;
+exports.createUrlBuilder = createUrlBuilder;
+exports.extractQueryParams = extractQueryParams;
+exports.removeQueryParams = removeQueryParams;
+exports.getExtension = getExtension;
+exports.parseTypedQueryParams = parseTypedQueryParams;
 const url_1 = require("url");
 /**
  * Appends query parameters to a given URL.
@@ -36,4 +45,252 @@ function parseQueryString(query) {
     // Object.fromEntries guarantees string values in result
     return Object.fromEntries(new url_1.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.
+ */
+function isValidUrl(url, requireHttps = false) {
+    try {
+        const parsedUrl = new url_1.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'
+ */
+function getDomain(url, removeSubdomains = false) {
+    try {
+        const { hostname } = new url_1.URL(url);
+        if (!removeSubdomains) {
+            return hostname;
+        }
+        // Extract root domain (remove subdomains)
+        const parts = hostname.split(".");
+        if (parts.length <= 2)
+            return hostname;
+        // Handle special cases like co.in, com.au
+        const secondLevelDomains = ["co", "com", "org", "net", "gov", "edu", "ac"];
+        const 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'
+ */
+function joinPaths(...segments) {
+    let result = segments
+        .filter((s) => s !== undefined && s !== null)
+        .map((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'
+ */
+function normalizeUrl(url, base) {
+    try {
+        // Handle protocol-relative URLs
+        if (url.startsWith("//")) {
+            url = `https:${url}`;
+        }
+        // Resolve relative URLs against a base
+        const parsedUrl = base ? new url_1.URL(url, base) : new url_1.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'
+ */
+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(path, params) {
+            const 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(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.
+ */
+function extractQueryParams(url, paramNames) {
+    try {
+        const parsedUrl = new url_1.URL(url);
+        const result = {};
+        for (const name of paramNames) {
+            const value = parsedUrl.searchParams.get(name);
+            if (value !== null) {
+                result[name] = value;
+            }
+        }
+        return result;
+    }
+    catch (_a) {
+        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.
+ */
+function removeQueryParams(url, paramsToRemove) {
+    try {
+        const parsedUrl = new url_1.URL(url);
+        for (const param of paramsToRemove) {
+            parsedUrl.searchParams.delete(param);
+        }
+        return parsedUrl.toString();
+    }
+    catch (_a) {
+        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'
+ */
+function getExtension(url) {
+    try {
+        const { pathname } = new url_1.URL(url);
+        const match = pathname.match(/\.([^./\\?#]+)$/);
+        return match ? match[1].toLowerCase() : "";
+    }
+    catch (_a) {
+        // If URL parsing fails, try a simpler approach
+        const 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' }
+ */
+function parseTypedQueryParams(url, converters) {
+    try {
+        const { searchParams } = new url_1.URL(url);
+        const result = {};
+        for (const [key, value] of searchParams.entries()) {
+            if (converters && key in converters) {
+                try {
+                    result[key] = converters[key](value);
+                }
+                catch (_a) {
+                    // Skip on conversion error
+                }
+            }
+            else {
+                result[key] = value;
+            }
+        }
+        return result;
+    }
+    catch (_b) {
+        return {};
+    }
+}
 //# sourceMappingURL=url.utils.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"url.utils.js","sourceRoot":"","sources":["../../../src/utils/url.utils.ts"],"names":[],"mappings":";;AAaA,8CASC;AAYD,4CAOC;AAzCD,6BAA2C;AAE3C;;;;;;;;;;GAUG;AACH,SAAgB,iBAAiB,CAC/B,GAAW,EACX,MAAuC;IAEvC,MAAM,MAAM,GAAG,IAAI,SAAG,CAAC,GAAG,CAAC,CAAC;IAC5B,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAClD,MAAM,CAAC,YAAY,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC;IACjD,CAAC;IACD,OAAO,MAAM,CAAC,QAAQ,EAAE,CAAC;AAC3B,CAAC;AAED;;;;;;;;;GASG;AACH,SAAgB,gBAAgB,CAAC,KAAa;IAC5C,MAAM,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,qBAAe,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"]}