https://github.com/hyperjump-io/uri
A small and fast library for validating, parsing, and resolving URIs (RFC 3986) and IRIs (RFC 3987).
https://github.com/hyperjump-io/uri
Last synced: 5 months ago
JSON representation
A small and fast library for validating, parsing, and resolving URIs (RFC 3986) and IRIs (RFC 3987).
- Host: GitHub
- URL: https://github.com/hyperjump-io/uri
- Owner: hyperjump-io
- License: mit
- Created: 2023-01-12T22:56:00.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2025-09-23T23:52:23.000Z (9 months ago)
- Last Synced: 2025-12-15T06:47:39.804Z (6 months ago)
- Language: JavaScript
- Homepage:
- Size: 42 KB
- Stars: 3
- Watchers: 1
- Forks: 1
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
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) => IdentifierComponents
### 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) => 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
```