URI

URI is a URL interface that does not require a base URL. ^{1 2 3}

npm install relative-url-interface

import URI from 'relative-url-interface'

const uri = new URI('../assets/kitten.jpg')

String(uri) // "../assets/kitten.jpg"

The URI class extends URL and can be used as a drop-in replacement. It is powered by spec-url, and it is ideal for server-side code, pre-compiled code, or any situation where absolute URLs may not be known.

import URI from 'relative-url-interface'

const puppy_page = new URI('file://path/to/site/src/pages/puppy.astro')
const kitty_image = URI.from('../assets/kitten.jpg')

const absolute_kitten = new URI(kitty_image, puppy_page)

fs.readFile(absolute_kitten, 'utf8') // contents of "file://path/to/site/src/assets/kitten.jpg"

Properties

segments

The segments property is an array of strings representing the path segments of the URL.

const uri = new URI('https://un:pw@localhost:8080/path/to/asset.jpg?q=a#content')

uri.segments // [ "path", "to", "asset.jpg" ]

const uri = new URI('../to/asset.jpg')

uri.segments // [ "..", "to", "asset.jpg" ]

href

The href property is a string representing the whole URL, including any search parameters and fragment identifiers.

const uri = new URI('https://un:pw@localhost:8080/path/to/asset.jpg?q=a#content')

uri.href // "https://un:pw@localhost:8080/path/to/asset.jpg?q=a#content"

const uri = new URI('../to/asset.jpg')

uri.href // "../to/asset.jpg"

protocol

The protocol property is a string representing the scheme of the URL, including the colon (:) that proceeds it.

const uri = new URI('https://un:pw@localhost:8080/path/to/asset.jpg?q=a#content')

uri.protocol // "https:"

const uri = new URI('../to/asset.jpg')

uri.protocol // ""

origin

The origin property is a string representing the scheme, domain, and port of the URL. When present, the port is preceeded by a colon (:).

const uri = new URI('https://un:pw@localhost:8080/path/to/asset.jpg?q=a#content')

uri.origin // "https://localhost:8080"

const uri = new URI('../to/asset.jpg')

uri.origin // ""

host

The host property is a string representing the domain and port of the URL. When present, the port is preceeded by a colon (:).

const uri = new URI('https://un:pw@localhost:8080/path/to/asset.jpg?q=a#content')

uri.host // "localhost:8080"

const uri = new URI('../to/asset.jpg')

uri.host // ""

hostname

The hostname property is a string representing the domain of the URL.

const uri = new URI('https://un:pw@localhost:8080/path/to/asset.jpg?q=a#content')

uri.hostname // "localhost"

const uri = new URI('../to/asset.jpg')

uri.hostname // ""

username

The username property is a string representing the username of the URL.

const uri = new URI('https://un:pw@localhost:8080/path/to/asset.jpg?q=a#content')

uri.username // "un"

const uri = new URI('../to/asset.jpg')

uri.username // ""

password

The password property is a string representing the password of the URL.

const uri = new URI('https://un:pw@localhost:8080/path/to/asset.jpg?q=a#content')

uri.password // "pw"

const uri = new URI('../to/asset.jpg')

uri.password // ""

port

The port property is a string representing the port of the URL.

const uri = new URI('https://un:pw@localhost:8080/path/to/asset.jpg?q=a#content')

uri.port // "8080"

const uri = new URI('../to/asset.jpg')

uri.port // ""

pathname

The pathname property is a string representing the path of the URL, which does not include the origin, search parameters, or fragment identifiers.

const uri = new URI('https://un:pw@localhost:8080/path/to/asset.jpg?q=a#content')

uri.pathname // "/path/to/asset.jpg"

const uri = new URI('../to/asset.jpg')

uri.pathname // "../to/asset.jpg"

search

The search property is a string representing the search parameters of the URL. When present, it is preceeded by a question mark (?).

const uri = new URI('https://un:pw@localhost:8080/path/to/asset.jpg?q=a#content')

uri.search // "?q=a"

const uri = new URI('../to/asset.jpg')

uri.search // ""

searchParams

The searchParams property is a URLSearchParams object representing the parsed search parameters of the URL.

const uri = new URI('https://un:pw@localhost:8080/path/to/asset.jpg?q=a#content')

uri.searchParams // URLSearchParams { 'q' => 'a' }

const uri = new URI('../to/asset.jpg')

uri.searchParams // URLSearchParams {}

hash

The hash property is a string representing the fragment identifier of the URL. When present, it is preceeded by a number sign (#).

const uri = new URI('https://un:pw@localhost:8080/path/to/asset.jpg?q=a#content')

uri.hash // "#content"

const uri = new URI('../to/asset.jpg')

uri.hash // ""

Methods

toString

The toString method returns the whole URL as a string. It is a synonym for the href getter property.

new URI('../assets/kitten.jpg').toString() // "../assets/kitten.jpg"

toJSON

The toJSON method returns the whole URL as a string. It is a synonym for the href getter property.

new URI('../assets/kitten.jpg').toJSON() // "../assets/kitten.jpg"

to

The to method returns a new URL resolved by the current URL.

const kitten = new URI('../assets/kitten.jpg')

String(kitten.to('puppy.jpg')) // "../assets/puppy.jpg"

Static Methods

from

The static from method returns a new URI resolved by the current source.

const kitten = new URI('../assets/kitten.jpg')

String(kitten.to('puppy.jpg')) // "../assets/puppy.jpg"

---

Impact

URI contributes approximately 42kB of JavaScript when unminified, or 14kB when minified, or 6kB when minified and compressed.

---

License

Code original to this project is licensed under the CC0-1.0 License.

Code from spec-url is licensed under the The MIT License (MIT), Copyright Alwin Blok.