@hyperjump/uri
TypeScript icon, indicating that this package has built-in type declarations

1.2.2 • Public • Published

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"

const resolved = resolveUri("foo/bar", "http://example.com/aaa/bbb"); // https://example.com/aaa/foo/bar

const components = 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"
// }

const a = isUri("http://examplé.org/rosé#"); // false
const a = isIri("http://examplé.org/rosé#"); // true

API

Resolve Relative References

These functions resovle 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 percent-encoded characters and dot segments (/., /..).

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

Normalize

These functions apply two 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.
  • normalizeUri: (uri: string) => string
  • normalizeIri: (iri: string, baseIri: 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) => IdentifierComponents

absolute-URI

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

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

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) => IdentifierComponents

absolute-IRI

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

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

Types

  • IdentifierComponents
    • scheme: string
    • authority: string
    • userinfo: string
    • host: string
    • port: string
    • path: string
    • query: string
    • fragment: string

Contributing

Tests

Run the tests

npm test

Run the tests with a continuous test runner

npm test -- --watch

Package Sidebar

Install

npm i @hyperjump/uri

Weekly Downloads

2,376

Version

1.2.2

License

MIT

Unpacked Size

15.6 kB

Total Files

4

Last publish

Collaborators

  • jason.desrosiers