@catbee/utils 0.0.8-next.0 → 0.0.8-rc.0

package/build/src/utils/type.utils.js

@@ -0,0 +1,196 @@
+"use strict";
+/*
+ * The MIT License
+ *
+ * Copyright (c) 2025 Catbee Technologies. https://catbee-utils.npm.hprasath.com/license
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isPrimitiveType = isPrimitiveType;
+exports.getTypeOf = getTypeOf;
+exports.isArrayOf = isArrayOf;
+exports.toStr = toStr;
+exports.toNum = toNum;
+exports.toBool = toBool;
+exports.ensureType = ensureType;
+/**
+ * Check if a value is of a specific primitive type.
+ *
+ * @param value - Value to check
+ * @param type - Type to check against
+ * @returns Whether the value is of the specified type
+ *
+ * @example
+ * ```typescript
+ * isPrimitiveType('hello', 'string'); // true
+ * isPrimitiveType(42, 'number'); // true
+ * isPrimitiveType(true, 'boolean'); // true
+ * isPrimitiveType(null, 'null'); // true
+ * isPrimitiveType(undefined, 'undefined'); // true
+ * isPrimitiveType({}, 'object'); // true
+ * isPrimitiveType([], 'array'); // true
+ * ```
+ */
+function isPrimitiveType(value, type) {
+    if (type === 'array') {
+        return Array.isArray(value);
+    }
+    if (type === 'null') {
+        return value === null;
+    }
+    if (type === 'undefined') {
+        return value === undefined;
+    }
+    if (type === 'object') {
+        // Only plain objects, not arrays or null
+        return typeof value === 'object' && value !== null && !Array.isArray(value);
+    }
+    return typeof value === type;
+}
+/**
+ * Get the primitive type of a value as a string.
+ *
+ * @param value - Value to get the type of
+ * @returns String representing the type
+ *
+ * @example
+ * ```typescript
+ * getTypeOf('hello'); // 'string'
+ * getTypeOf(42); // 'number'
+ * getTypeOf([]); // 'array'
+ * getTypeOf(null); // 'null'
+ * ```
+ */
+function getTypeOf(value) {
+    if (value === null)
+        return 'null';
+    if (value === undefined)
+        return 'undefined';
+    if (Array.isArray(value))
+        return 'array';
+    return typeof value;
+}
+/**
+ * Type guard for checking if a value is an array of a specific type.
+ *
+ * @param value - Value to check
+ * @param itemTypeGuard - Function that checks if items are of the expected type
+ * @returns True if the value is an array with items of the expected type
+ *
+ * @example
+ * ```typescript
+ * isArrayOf([1, 2, 3], (item): item is number => typeof item === 'number'); // true
+ * isArrayOf(['a', 'b', 'c'], (item): item is string => typeof item === 'string'); // true
+ * isArrayOf([1, '2', 3], (item): item is number => typeof item === 'number'); // false
+ * ```
+ */
+function isArrayOf(value, itemTypeGuard) {
+    if (!Array.isArray(value))
+        return false;
+    return value.every(item => itemTypeGuard(item));
+}
+/**
+ * Convert a value to a string.
+ *
+ * @param value - Value to convert
+ * @param defaultValue - Default value if conversion fails
+ * @returns String representation of the value
+ */
+function toStr(value, defaultValue = '') {
+    if (value === null || value === undefined)
+        return defaultValue;
+    try {
+        if (typeof value === 'object') {
+            return JSON.stringify(value);
+        }
+        return String(value);
+    }
+    catch (_a) {
+        return defaultValue;
+    }
+}
+/**
+ * Convert a value to a number.
+ *
+ * @param value - Value to convert
+ * @param defaultValue - Default value if conversion fails
+ * @returns Numeric representation of the value
+ */
+function toNum(value, defaultValue = 0) {
+    if (value === null || value === undefined)
+        return defaultValue;
+    if (typeof value === 'number')
+        return value;
+    try {
+        const num = Number(value);
+        return isNaN(num) ? defaultValue : num;
+    }
+    catch (_a) {
+        return defaultValue;
+    }
+}
+/**
+ * Convert a value to a boolean.
+ *
+ * @param value - Value to convert
+ * @param defaultValue - Default value if conversion fails
+ * @returns Boolean representation of the value
+ */
+function toBool(value, defaultValue = false) {
+    if (value === null || value === undefined)
+        return defaultValue;
+    if (typeof value === 'boolean')
+        return value;
+    if (typeof value === 'string') {
+        const lowercased = value.toLowerCase();
+        if (lowercased === 'true' || lowercased === 'yes' || lowercased === 'y' || lowercased === '1') {
+            return true;
+        }
+        if (lowercased === 'false' || lowercased === 'no' || lowercased === 'n' || lowercased === '0') {
+            return false;
+        }
+    }
+    if (typeof value === 'number') {
+        return value !== 0;
+    }
+    return defaultValue;
+}
+/**
+ * Ensure a value matches the expected type, or provide a default.
+ *
+ * @param value - Value to check
+ * @param expectedType - Expected primitive type
+ * @param defaultValue - Default value to use if type doesn't match
+ * @returns The value if it matches the type, otherwise the default
+ *
+ * @example
+ * ```typescript
+ * ensureType(42, 'number', 0); // 42
+ * ensureType('42', 'number', 0); // 0
+ * ensureType(undefined, 'string', 'default'); // 'default'
+ * ```
+ */
+function ensureType(value, expectedType, defaultValue) {
+    if (getTypeOf(value) === expectedType) {
+        return value;
+    }
+    return defaultValue;
+}
+//# sourceMappingURL=type.utils.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"type.utils.js","sourceRoot":"","sources":["../../../src/utils/type.utils.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * The MIT License\n *\n * Copyright (c) 2025 Catbee Technologies. https://catbee-utils.npm.hprasath.com/license\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\n/**\n * Check if a value is of a specific primitive type.\n *\n * @param value - Value to check\n * @param type - Type to check against\n * @returns Whether the value is of the specified type\n *\n * @example\n * ```typescript\n * isPrimitiveType('hello', 'string'); // true\n * isPrimitiveType(42, 'number'); // true\n * isPrimitiveType(true, 'boolean'); // true\n * isPrimitiveType(null, 'null'); // true\n * isPrimitiveType(undefined, 'undefined'); // true\n * isPrimitiveType({}, 'object'); // true\n * isPrimitiveType([], 'array'); // true\n * ```\n */\nexport function isPrimitiveType(\n  value: unknown,\n  type: 'string' | 'number' | 'boolean' | 'symbol' | 'bigint' | 'function' | 'object' | 'array' | 'null' | 'undefined'\n): boolean {\n  if (type === 'array') {\n    return Array.isArray(value);\n  }\n\n  if (type === 'null') {\n    return value === null;\n  }\n\n  if (type === 'undefined') {\n    return value === undefined;\n  }\n\n  if (type === 'object') {\n    // Only plain objects, not arrays or null\n    return typeof value === 'object' && value !== null && !Array.isArray(value);\n  }\n\n  return typeof value === type;\n}\n\n/**\n * Get the primitive type of a value as a string.\n *\n * @param value - Value to get the type of\n * @returns String representing the type\n *\n * @example\n * ```typescript\n * getTypeOf('hello'); // 'string'\n * getTypeOf(42); // 'number'\n * getTypeOf([]); // 'array'\n * getTypeOf(null); // 'null'\n * ```\n */\nexport function getTypeOf(value: unknown): string {\n  if (value === null) return 'null';\n  if (value === undefined) return 'undefined';\n  if (Array.isArray(value)) return 'array';\n  return typeof value;\n}\n\n/**\n * Type guard for checking if a value is an array of a specific type.\n *\n * @param value - Value to check\n * @param itemTypeGuard - Function that checks if items are of the expected type\n * @returns True if the value is an array with items of the expected type\n *\n * @example\n * ```typescript\n * isArrayOf([1, 2, 3], (item): item is number => typeof item === 'number'); // true\n * isArrayOf(['a', 'b', 'c'], (item): item is string => typeof item === 'string'); // true\n * isArrayOf([1, '2', 3], (item): item is number => typeof item === 'number'); // false\n * ```\n */\nexport function isArrayOf<T>(value: unknown, itemTypeGuard: (item: unknown) => item is T): value is T[] {\n  if (!Array.isArray(value)) return false;\n  return value.every(item => itemTypeGuard(item));\n}\n\n/**\n * Convert a value to a string.\n *\n * @param value - Value to convert\n * @param defaultValue - Default value if conversion fails\n * @returns String representation of the value\n */\nexport function toStr(value: unknown, defaultValue: string = ''): string {\n  if (value === null || value === undefined) return defaultValue;\n\n  try {\n    if (typeof value === 'object') {\n      return JSON.stringify(value);\n    }\n    return String(value);\n  } catch {\n    return defaultValue;\n  }\n}\n\n/**\n * Convert a value to a number.\n *\n * @param value - Value to convert\n * @param defaultValue - Default value if conversion fails\n * @returns Numeric representation of the value\n */\nexport function toNum(value: unknown, defaultValue: number = 0): number {\n  if (value === null || value === undefined) return defaultValue;\n\n  if (typeof value === 'number') return value;\n\n  try {\n    const num = Number(value);\n    return isNaN(num) ? defaultValue : num;\n  } catch {\n    return defaultValue;\n  }\n}\n\n/**\n * Convert a value to a boolean.\n *\n * @param value - Value to convert\n * @param defaultValue - Default value if conversion fails\n * @returns Boolean representation of the value\n */\nexport function toBool(value: unknown, defaultValue: boolean = false): boolean {\n  if (value === null || value === undefined) return defaultValue;\n\n  if (typeof value === 'boolean') return value;\n\n  if (typeof value === 'string') {\n    const lowercased = value.toLowerCase();\n    if (lowercased === 'true' || lowercased === 'yes' || lowercased === 'y' || lowercased === '1') {\n      return true;\n    }\n    if (lowercased === 'false' || lowercased === 'no' || lowercased === 'n' || lowercased === '0') {\n      return false;\n    }\n  }\n\n  if (typeof value === 'number') {\n    return value !== 0;\n  }\n\n  return defaultValue;\n}\n\n/**\n * Ensure a value matches the expected type, or provide a default.\n *\n * @param value - Value to check\n * @param expectedType - Expected primitive type\n * @param defaultValue - Default value to use if type doesn't match\n * @returns The value if it matches the type, otherwise the default\n *\n * @example\n * ```typescript\n * ensureType(42, 'number', 0); // 42\n * ensureType('42', 'number', 0); // 0\n * ensureType(undefined, 'string', 'default'); // 'default'\n * ```\n */\nexport function ensureType<T>(value: unknown, expectedType: string, defaultValue: T): T {\n  if (getTypeOf(value) === expectedType) {\n    return value as unknown as T;\n  }\n  return defaultValue;\n}\n"]}

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

@@ -0,0 +1,141 @@
+/**
+ * Appends query parameters to a given URL.
+ *
+ * @param {string} url - The base URL to which query parameters will be appended.
+ * @param {Record<string, string | number>} params - Key-value pairs to add as query parameters.
+ * @returns {string} The new URL string with query parameters appended.
+ *
+ * @example
+ * appendQueryParams('https://example.com', { page: 1, limit: 10 });
+ * // → 'https://example.com/?page=1&limit=10'
+ */
+export declare function appendQueryParams(url: string, params: Record<string, string | number>): string;
+/**
+ * Parses a query string into a key-value object.
+ *
+ * @param {string} query - The query string (with or without leading '?').
+ * @returns {Record<string, string>} Object representing parsed query parameters.
+ *
+ * @example
+ * parseQueryString('?page=1&limit=10');
+ * // → { 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

@@ -0,0 +1,317 @@
+"use strict";
+/*
+ * The MIT License
+ *
+ * Copyright (c) 2025 Catbee Technologies. https://catbee-utils.npm.hprasath.com/license
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+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.
+ *
+ * @param {string} url - The base URL to which query parameters will be appended.
+ * @param {Record<string, string | number>} params - Key-value pairs to add as query parameters.
+ * @returns {string} The new URL string with query parameters appended.
+ *
+ * @example
+ * appendQueryParams('https://example.com', { page: 1, limit: 10 });
+ * // → 'https://example.com/?page=1&limit=10'
+ */
+function appendQueryParams(url, params) {
+    const urlObj = new url_1.URL(url);
+    for (const [key, value] of Object.entries(params)) {
+        urlObj.searchParams.set(key, value.toString());
+    }
+    return urlObj.toString();
+}
+/**
+ * Parses a query string into a key-value object.
+ *
+ * @param {string} query - The query string (with or without leading '?').
+ * @returns {Record<string, string>} Object representing parsed query parameters.
+ *
+ * @example
+ * parseQueryString('?page=1&limit=10');
+ * // → { page: '1', limit: '10' }
+ */
+function parseQueryString(query) {
+    const cleanQuery = query.startsWith('?') ? query.slice(1) : 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