@catbee/utils/build/src/utils/url.utils.d.ts

A modular, production-grade utility toolkit for Node.js and TypeScript, designed for robust, scalable applications (including Express-based services). All utilities are tree-shakable and can be imported independently.

/**
 * 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