URI

A small and fast library for validating, parsing, and resolving URIs (RFC 3986) and IRIs (RFC 3987).

Install

Designed for node.js (ES Modules, TypeScript) and browsers.

npm install @hyperjump/uri

Usage

import{resolveUri,parseUri,isUri,isIri}from"@hyperjump/uri"constresolved=resolveUri("foo/bar","http://example.com/aaa/bbb");// https://example.com/aaa/foo/barconstcomponents=parseUri("https://jason@example.com:80/foo?bar#baz");// {// scheme: "https",// authority: "jason@example.com:80",// userinfo: "jason",// host: "example.com",// port: "80",// path: "/foo",// query: "bar",// fragment: "baz"// }consta=isUri("http://examplé.org/rosé#");// falseconsta=isIri("http://examplé.org/rosé#");// true

API

Resolve Relative References

These functions resolve relative-references against a base URI/IRI. The base URI/IRI must be absolute, meaning it must have a scheme (https) and no fragment (#foo). The resolution process will normalize the result.

• resolveUri: (uriReference: string, baseUri: string) => string
• resolveIri: (iriReference: string, baseIri: string) => string

Normalize

These functions apply the following normalization rules.

1. Decode any unnecessarily percent-encoded characters.
2. Convert any lowercase characters in the hex numbers of percent-encoded characters to uppercase.
3. Resolve and remove any dot-segments (/., /..) in paths.
4. Convert the scheme to lowercase.
5. Convert the authority to lowercase.

• normalizeUri: (uri: string) => string
• normalizeIri: (iri: string) => string

To Relative

These functions convert a non-relative URI/IRI into a relative URI/IRI given a base.

• toRelativeUri: (uri: string, relativeTo: string) => string
• toRelativeIri: (iri: string, relativeTo: string) => string

URI

A URI is not relative and may include a fragment.

• isUri: (value: string) => boolean

• parseUri: (value: string) => IdentifierComponents

• toAbsoluteUri: (value: string) => string

  Takes a URI and strips its fragment component if it exists.

URI-Reference

A URI-reference may be relative.

• isUriReference: (value: string) => boolean
• parseUriReference: (value: string) => RelativeIdentifierComponents

absolute-URI

An absolute-URI is not relative an does not include a fragment.

• isAbsoluteUri: (value: string) => boolean
• parseAbsoluteUri: (value: string) => AbsoluteIdentifierComponents

IRI

An IRI is not relative and may include a fragment.

• isIri: (value: string) => boolean

• parseIri: (value: string) => IdentifierComponents

• toAbsoluteIri: (value: string) => string

  Takes an IRI and strips its fragment component if it exists.

IRI-reference

An IRI-reference may be relative.

• isIriReference: (value: string) => boolean
• parseIriReference: (value: string) => RelativeIdentifierComponents

absolute-IRI

An absolute-IRI is not relative an does not include a fragment.

• isAbsoluteIri: (value: string) => boolean
• parseAbsoluteIri: (value: string) => AbsoluteIdentifierComponents

Types

• IdentifierComponents

  • scheme: string
  • authority: string
  • userinfo: string (optional)
  • host: string
  • port: string (optional)
  • path: string
  • query: string (optional)
  • fragment: string (optional)

• RelativeIdentifierComponents

  • scheme: string (optional)
  • authority: string (optional)
  • userinfo: string (optional)
  • host: string (optional)
  • port: string (optional)
  • path: string
  • query: string (optional)
  • fragment: string (optional)

• AbsoluteIdentifierComponents

  • scheme: string
  • authority: string
  • userinfo: string (optional)
  • host: string
  • port: string (optional)
  • path: string
  • query: string (optional)

Contributing

Tests

Run the tests

npm test

Run the tests with a continuous test runner

npm test -- --watch