url

Utility functions for building, encoding, and manipulating URLs.

build

Signature

url.build (baseUrl, params)

Description

Builds a URL from a base URL and a params object. Only defined values are appended as query parameters.

Parameters

Name	Type	Required	Description
baseUrl	string	yes	The base URL
params	object	yes	Query parameters to append

Returns

Type	Description
string	The constructed URL with query parameters

Throws

Throws a TypeError if baseUrl is not a valid URL or if params is not a non-empty object.

Examples

url.build('https://api.example.com/search', { q: 'hello', page: 1 })
// 'https://api.example.com/search?q=hello&page=1'

url.build('https://api.example.com', { q: 'hello', filter: undefined })
// 'https://api.example.com/?q=hello' — undefined values are ignored

parse

Signature

url.parse (url, defaultPort)

Description

Parses a URL and extracts its host, port and path. If no port is present in the URL, defaultPort is used as fallback.

Parameters

Name	Type	Required	Description
url	string	yes	The URL to parse
defaultPort	number	no	Fallback port when none is specified in the URL (default: 80)

Returns

Type	Description
{ host: string, port: number, path: string }	The parsed URL components

Throws

Throws a TypeError if url is not a valid URL or if defaultPort is not a number.

Examples

url.parse('https://example.com:3000/api/users')
// { host: 'example.com', port: 3000, path: '/api/users' }

url.parse('https://example.com/api/users')
// { host: 'example.com', port: 80, path: '/api/users' } — defaultPort used as fallback

url.parse('https://example.com/api/users', 443)
// { host: 'example.com', port: 443, path: '/api/users' }

addQueryParam

Signature

url.addQueryParam (url, params)

Description

Appends query parameters to an existing URL. Existing parameters are preserved. Only defined values are added. If a key already exists, its value is overwritten.

Parameters

Name	Type	Required	Description
url	string	yes	The URL to extend
params	object	yes	Query parameters to append

Returns

Type	Description
string	The URL with the additional query parameters

Throws

Throws a TypeError if url is not a valid URL or if params is not a non-empty object.

Examples

url.addQueryParam('https://api.example.com?q=hello', { page: 2 })
// 'https://api.example.com/?q=hello&page=2'

url.addQueryParam('https://api.example.com?page=1', { page: 2 })
// 'https://api.example.com/?page=2' — existing key is overwritten

encode

Signature

url.encode (url)

Description

Encodes a URL using encodeURI, making it safe for use in HTTP requests. Characters that have special meaning in URLs (such as spaces) are percent-encoded.

Parameters

Name	Type	Required	Description
url	string	yes	The URL to encode

Returns

Type	Description
string	The encoded URL

Throws

Throws a TypeError if url is not a valid URL.

Examples

url.encode('https://example.com/path with spaces')
// 'https://example.com/path%20with%20spaces'

obfuscate

Signature

url.obfuscate (url, mask = '*****')

Description

Replaces the username and password in a URL with a mask string. Useful for safely logging URLs that contain credentials.

Parameters

Name	Type	Required	Description
url	string	yes	The URL to obfuscate
mask	string	no	The string to replace credentials with. Defaults to '*****'

Returns

Type	Description
string	The URL with credentials replaced by the mask

Throws

Throws a TypeError if url is not a valid URL or if mask is not a string.

Examples

url.obfuscate('https://user:password@example.com')
// 'https://*****:*****@example.com'

url.obfuscate('https://user:password@example.com', '###')
// 'https://###:###@example.com'

url.obfuscate('https://example.com')
// 'https://example.com' — no credentials, unchanged