Class: URLBuilder

A URL, parsed into its attributes or built from them. Unlike URL, any scheme is handled the same way (redis:, mongodb:, amqp:), relative URLs are accepted, and the query is a plain object of strings.

URLBuilder.parse() fills the attributes from a URL; new URLBuilder({...}) takes them from an object. They are public properties, which can be changed before toString() builds the URL. toString() builds it from the current attributes at each call: an attribute set to undefined or '' is no longer in the URL. host is hostname and port together: setting it sets them, setting them changes it. username and password win over auth, and href and origin are kept as given, not used to build.

Example

import {URLBuilder} from 'lakutata/utils'

const url: URLBuilder = URLBuilder.parse('https://user:secret@example.com:8080/search?q=books#results')
console.log(url.hostname, url.port, url.pathname, url.query)
//example.com 8080 /search {q: 'books'}
url.query = {...url.query, page: '2'}
console.log(url.toString())
//https://user:secret@example.com:8080/search?q=books&page=2#results

const built: URLBuilder = new URLBuilder({protocol: 'redis', hostname: 'localhost', port: '6379', pathname: '0'})
console.log(built.toString())
//redis://localhost:6379/0

Constructors

Constructor

new URLBuilder(options?): URLBuilder

Create a URL from its attributes, to build with toString().

Parameters

options?

URLAttributes

The attributes; none gives an empty URL (toString() returns '').

Returns

URLBuilder

Properties

auth?

optional auth?: string

The credentials, username:password or username alone, percent-encoded. When set, they replace username and password in the URL built (unless these are set too).

---

hash?

optional hash?: string

The fragment, with its # ('#top'); # is added when building without it.

---

href?

optional href?: string

The whole URL, as parsed (or given). Kept as it is: toString() builds the URL from the other attributes, and does not update it.

---

origin?

optional origin?: string

The protocol and the host ('https://example.com:8080'), or 'null' for a scheme without origin (redis:, file:) or a URL without host, as parsed (or given). Kept as it is: toString() does not use nor update it.

---

password?

optional password?: string

The password of the credentials, percent-encoded (when parsed, and when built).

---

pathname?

optional pathname?: string

The path, starting with / ('/a/b'), still percent-encoded; / is added when building without it.

---

protocol?

optional protocol?: string

The scheme with its colon, in lower case ('https:'); '' for a relative URL. Given without its colon ('https'), it is added when building.

---

query?

optional query?: Record<string, string>

The query parameters by name, decoded (+ read as a space). A name repeated keeps its first value only (?a=1&a=2 gives {a: '1'}), and a name without value gives ''. Percent-encoded when building; an empty object gives no query.

---

slashes?

optional slashes?: boolean

Whether the scheme is followed by // (always for http:, https:, ws:, wss:, ftp:, file: and gopher:); undefined is true with a protocol.

---

username?

optional username?: string

The user name of the credentials, percent-encoded (when parsed, and when built).

Accessors

host

Get Signature

get host(): string | undefined

The host name with its port ('example.com:8080'), made of hostname and port: undefined when neither is set. Setting it sets hostname and port ('' when it has none); undefined unsets them both.

Returns

string | undefined

Set Signature

set host(value): void

Parameters

value

string | undefined

Returns

void

---

hostname

Get Signature

get hostname(): string | undefined

The host name, without port, in lower case when parsed.

Returns

string | undefined

Set Signature

set hostname(value): void

Parameters

value

string | undefined

Returns

void

---

port

Get Signature

get port(): string | number | undefined

The port. Parsed, it is a string, '' when absent or when it is the scheme's default (80 for http:, 443 for https:). When building, the scheme's default port is not written.

Returns

string | number | undefined

Set Signature

set port(value): void

Parameters

value

string | number | undefined

Returns

void

Methods

parse()

static parse(url): URLBuilder

Parse a URL into its attributes. The parsing does not validate: a string which is not a URL gives a relative URL of that path ('not a url' gives the pathname 'not a url').

Parameters

url

string

The URL, absolute ('https://example.com/a', 'redis://:pw@host:6379/0') or relative ('/a?b=1').

Returns

URLBuilder

A new instance holding the URL's attributes.

---

toString()

toString(): string

Build the URL from the current attributes (the non-empty strings, port, query and slashes).

Returns

string

The URL; '' when no attribute is set.