@catbee/utils 0.0.8-rc.1 → 0.0.8-rc.2

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

@@ -1,196 +0,0 @@
-"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

@@ -1 +0,0 @@
-{"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

@@ -1,141 +0,0 @@
-/**
- * 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

@@ -1,317 +0,0 @@
-"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