@tempots/std/url.d.ts

Std library for TypeScript. Natural complement to the Tempo libraries.

/**
 * Utilities for working with URLs and paths.
 *
 * This module provides comprehensive URL manipulation, query parameter handling,
 * and path utilities. Functions are designed to work safely with both absolute
 * and relative URLs, and handle edge cases gracefully.
 *
 * @public
 */
/**
 * Safely parses a URL string into a URL object.
 *
 * This function provides better error handling than the URL constructor
 * by returning null for invalid URLs instead of throwing.
 *
 * @example
 * ```typescript
 * const url = parseUrl('https://example.com/path?param=value')
 * // Result: URL object
 *
 * const invalid = parseUrl('not-a-url')
 * // Result: null
 * ```
 *
 * @param url - The URL string to parse
 * @returns A URL object if valid, null otherwise
 * @public
 */
export declare const parseUrl: (url: string) => URL | null;
/**
 * Builds a URL from a base URL and query parameters.
 *
 * This function safely constructs URLs with query parameters,
 * handling encoding and existing parameters properly.
 *
 * @example
 * ```typescript
 * const url = buildUrl('https://api.example.com/users', {
 *   page: '1',
 *   limit: '10',
 *   search: 'john doe'
 * })
 * // Result: 'https://api.example.com/users?page=1&limit=10&search=john%20doe'
 * ```
 *
 * @param base - The base URL
 * @param params - Query parameters to add
 * @returns The constructed URL string
 * @public
 */
export declare const buildUrl: (base: string, params?: Record<string, string>) => string;
/**
 * Extracts query parameters from a URL as an object.
 *
 * This function parses the query string and returns all parameters
 * as a plain object with string values.
 *
 * @example
 * ```typescript
 * const params = getQueryParams('https://example.com/path?name=john&age=30&active=true')
 * // Result: { name: 'john', age: '30', active: 'true' }
 *
 * const empty = getQueryParams('https://example.com/path')
 * // Result: {}
 * ```
 *
 * @param url - The URL to extract parameters from
 * @returns An object containing all query parameters
 * @public
 */
export declare const getQueryParams: (url: string) => Record<string, string>;
/**
 * Sets a query parameter in a URL.
 *
 * This function adds or updates a single query parameter in a URL,
 * preserving all other parameters and URL components.
 *
 * @example
 * ```typescript
 * const url = setQueryParam('https://example.com/path?existing=value', 'new', 'param')
 * // Result: 'https://example.com/path?existing=value&new=param'
 *
 * const updated = setQueryParam('https://example.com/path?existing=old', 'existing', 'new')
 * // Result: 'https://example.com/path?existing=new'
 * ```
 *
 * @param url - The base URL
 * @param key - The parameter key
 * @param value - The parameter value
 * @returns The URL with the parameter set
 * @public
 */
export declare const setQueryParam: (url: string, key: string, value: string) => string;
/**
 * Removes a query parameter from a URL.
 *
 * This function removes a specific query parameter from a URL,
 * preserving all other parameters and URL components.
 *
 * @example
 * ```typescript
 * const url = removeQueryParam('https://example.com/path?keep=this&remove=that', 'remove')
 * // Result: 'https://example.com/path?keep=this'
 * ```
 *
 * @param url - The base URL
 * @param key - The parameter key to remove
 * @returns The URL with the parameter removed
 * @public
 */
export declare const removeQueryParam: (url: string, key: string) => string;
/**
 * Checks if a string is a valid URL.
 *
 * This function validates URLs more safely than using the URL constructor
 * directly, as it doesn't throw exceptions.
 *
 * @example
 * ```typescript
 * isValidUrl('https://example.com') // true
 * isValidUrl('http://localhost:3000/path') // true
 * isValidUrl('ftp://files.example.com') // true
 * isValidUrl('not-a-url') // false
 * isValidUrl('') // false
 * ```
 *
 * @param url - The string to validate
 * @returns true if the string is a valid URL, false otherwise
 * @public
 */
export declare const isValidUrl: (url: string) => boolean;
/**
 * Joins multiple path segments into a single path.
 *
 * This function properly handles leading and trailing slashes,
 * ensuring a clean path without double slashes or missing separators.
 *
 * @example
 * ```typescript
 * const path = joinPaths('api', 'v1', 'users', '123')
 * // Result: 'api/v1/users/123'
 *
 * const withSlashes = joinPaths('/api/', '/v1/', 'users/')
 * // Result: '/api/v1/users/'
 *
 * const empty = joinPaths('', 'path', '', 'file')
 * // Result: 'path/file'
 * ```
 *
 * @param paths - Path segments to join
 * @returns The joined path
 * @public
 */
export declare const joinPaths: (...paths: string[]) => string;
/**
 * Normalizes a path by removing redundant segments.
 *
 * This function resolves '..' and '.' segments in paths,
 * similar to path.normalize in Node.js but for web contexts.
 *
 * @example
 * ```typescript
 * const path = normalizePath('/api/../users/./123/../456')
 * // Result: '/users/456'
 *
 * const relative = normalizePath('../../parent/child')
 * // Result: '../../parent/child'
 * ```
 *
 * @param path - The path to normalize
 * @returns The normalized path
 * @public
 */
export declare const normalizePath: (path: string) => string;
/**
 * Extracts the file extension from a path.
 *
 * This function returns the file extension including the dot,
 * or an empty string if no extension is found.
 *
 * @example
 * ```typescript
 * getFileExtension('/path/to/file.txt') // '.txt'
 * getFileExtension('image.jpeg') // '.jpeg'
 * getFileExtension('README') // ''
 * getFileExtension('.hidden') // ''
 * getFileExtension('file.tar.gz') // '.gz'
 * ```
 *
 * @param path - The path to extract extension from
 * @returns The file extension including the dot, or empty string
 * @public
 */
export declare const getFileExtension: (path: string) => string;
/**
 * Extracts the file name from a path.
 *
 * This function returns the last segment of a path,
 * which is typically the file name.
 *
 * @example
 * ```typescript
 * getFileName('/path/to/file.txt') // 'file.txt'
 * getFileName('file.txt') // 'file.txt'
 * getFileName('/path/to/directory/') // ''
 * getFileName('/path/to/directory') // 'directory'
 * ```
 *
 * @param path - The path to extract file name from
 * @returns The file name
 * @public
 */
export declare const getFileName: (path: string) => string;
/**
 * Extracts the base name (file name without extension) from a path.
 *
 * This function returns the file name without its extension.
 *
 * @example
 * ```typescript
 * getBaseName('/path/to/file.txt') // 'file'
 * getBaseName('image.jpeg') // 'image'
 * getBaseName('README') // 'README'
 * getBaseName('.hidden') // '.hidden'
 * getBaseName('file.tar.gz') // 'file.tar'
 * ```
 *
 * @param path - The path to extract base name from
 * @returns The base name without extension
 * @public
 */
export declare const getBaseName: (path: string) => string;