# @hyperjump/uri

> A small and fast library for validating parsing and resolving URIs and IRIs

Latest version **1.3.6** (published 2026-08-30) · MIT license · 0 weekly downloads

## Install

```sh
npm install @hyperjump/uri
pnpm add @hyperjump/uri
yarn add @hyperjump/uri
bun add @hyperjump/uri
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 1.3.6 |
| Published | 2026-08-30 |
| First published | 2023-01-13 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 22.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 5 |
| Author | Jason Desrosiers |
| Maintainers | jason.desrosiers |
| Keywords | URI, IRI, resolve, relative, parse, RFC3986, RFC-3986, RFC3987, RFC-3987 |

## Links

- npm: https://www.npmjs.com/package/@hyperjump/uri
- Repository: https://github.com/hyperjump-io/uri
- Homepage: https://github.com/hyperjump-io/uri#readme
- Issues: https://github.com/hyperjump-io/uri/issues
- Funding: https://github.com/sponsors/jdesrosiers
- npm.io page: https://npm.io/package/@hyperjump/uri

## Alternatives

- [babylon](https://npm.io/package/babylon.md) — 5.1M weekly downloads
- [csscolorparser](https://npm.io/package/csscolorparser.md) — 3.7M weekly downloads
- [expr-eval-fork](https://npm.io/package/expr-eval-fork.md) — 1.5M weekly downloads
- [@leeoniya/ufuzzy](https://npm.io/package/@leeoniya/ufuzzy.md) — 247.7K weekly downloads
- [xml-parser](https://npm.io/package/xml-parser.md) — 78.4K weekly downloads

## Recent versions

- 1.3.6 (latest) — 2026-08-30
- 1.3.5 — 2026-08-14
- 1.3.4 — 2026-05-06
- 1.3.3 — 2026-03-05
- 1.3.2 — 2025-09-23
- 1.3.1 — 2025-02-03
- 1.3.0 — 2025-02-03
- 1.2.2 — 2023-09-14
- 1.2.1 — 2023-09-01
- 1.2.0 — 2023-05-04
- 1.1.0 — 2023-01-13
- 1.0.0 — 2023-01-13

## README

# URI
A small and fast library for validating, parsing, and resolving URIs
([RFC 3986](https://www.rfc-editor.org/rfc/rfc3986)) and IRIs
([RFC 3987](https://www.rfc-editor.org/rfc/rfc3987)).

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

```
npm install @hyperjump/uri
```

## Usage
```javascript
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 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](#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](https://www.rfc-editor.org/rfc/rfc3986#section-3) 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](https://www.rfc-editor.org/rfc/rfc3986#section-4.1) may be
relative.

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

### absolute-URI
An [absolute-URI](https://www.rfc-editor.org/rfc/rfc3986#section-4.3) 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
```

---
_Source: https://npm.io/package/@hyperjump/uri · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._