URI.js URI/IRI Parser

Common errors

• ReferenceError: URI is not defined

  cause Attempting to use `URI.parse` or other functions without correctly importing the library, often due to an incorrect ESM import for the `URI` object.
  fix Use `import * as URI from 'uri-js';` for ESM or `const URI = require('uri-js');` for CommonJS environments.

• Error: URI malformed

  cause The input string provided to a parsing function does not conform to the strict URI/IRI syntax rules defined by the RFCs.
  fix Review the URI string for syntax errors. If parsing non-standard or 'dirty' URIs, consider using the `{ tolerant: true }` option: `URI.parse(uriString, { tolerant: true })`.

• Expected URI scheme, but got null/undefined

  cause When constructing a URI object programmatically, a required component like `scheme` might be missing or invalid, leading to issues during serialization or validation.
  fix Ensure all necessary URI components (e.g., `scheme`, `host` for absolute URIs) are provided and correctly formatted in the object passed to `URI.serialize` or `URI.build` (if using an extended API).

Warnings

• gotcha URI.js strictly adheres to RFC standards. If you are dealing with malformed or non-compliant URIs that need to be parsed, you might need to enable the `tolerant` option during parsing.
  Fix: Pass `{ tolerant: true }` as an option to parsing functions: `URI.parse(uriString, { tolerant: true })`.
• gotcha Handling Internationalized Resource Identifiers (IRIs) requires specific options. By default, IRIs are converted to their URI-compatible (Punycode and percent-encoded) forms. To work with unescaped non-ASCII characters, `iri: true` for serialization and `unicodeSupport: true` for parsing are necessary.
  Fix: For IRI output, use `URI.serialize(parsedObject, { iri: true })`. For parsing with unicode support, use `URI.parse(iriString, { unicodeSupport: true })`.
• gotcha IPv6 Zone Identifiers require specific percent-encoding for the '%' character itself (e.g., `%25`) within the host component as per RFC 6874. Failure to correctly encode the zone identifier will result in incorrect parsing.
  Fix: Ensure the '%' character in an IPv6 zone identifier is encoded as `%25`. For example, `//[fe80::1%25en0]` instead of `//[fe80::1%en0]`.
• gotcha The library automatically normalizes common URI schemes (HTTP, HTTPS, WS, WSS) according to their respective RFCs, which might alter host casing or port numbers (e.g., port 80 for HTTP). Be aware of these automatic normalizations when comparing URIs.
  Fix: Use `URI.equal()` for comparison where possible, as it accounts for these normalizations. If manually comparing, apply normalization first or be aware of standard port elision and case insensitivity for certain URI components.

Install

• npm install uri-js npm
• yarn add uri-js yarn
• pnpm add uri-js pnpm

Imports

• URI
  wrong:

  import URI from 'uri-js';

  correct:

  import * as URI from 'uri-js';

  The library exports its functions as properties of a single URI object/namespace, not a default export.
• parse
  wrong:

  const { parse } = require('uri-js');

  correct:

  import { parse } from 'uri-js';

  Named imports are available for individual functions, but CommonJS `require` returns the full URI object.
• URI (CommonJS)

  const URI = require('uri-js');

  For CommonJS environments, the entire API is available via `require('uri-js')` as the URI object.

Quickstart

This quickstart demonstrates the core functionalities of URI.js including parsing, serializing, resolving, normalizing, and comparing URIs, alongside its specific support for Internationalized Resource Identifiers (IRIs).

import { parse, serialize, resolve, normalize, equal } from 'uri-js';

const exampleUri = "uri://user:pass@example.com:123/one/two.three?q1=a1&q2=a2#body";
const parsed = parse(exampleUri);

console.log("Parsed URI:", parsed);
// Expected: { scheme: 'uri', userinfo: 'user:pass', host: 'example.com', port: 123, path: '/one/two.three', query: 'q1=a1&q2=a2', fragment: 'body' }

const serialized = serialize({ scheme: "http", host: "example.com", fragment: "footer" });
console.log("Serialized URI:", serialized);
// Expected: http://example.com/#footer

const resolved = resolve("uri://a/b/c/d?q", "../../g");
console.log("Resolved URI:", resolved);
// Expected: uri://a/g

const normalized = normalize("HTTP://ABC.com:80/%7Esmith/home.html");
console.log("Normalized URI:", normalized);
// Expected: http://abc.com/~smith/home.html

// Demonstrating IRI support
const iriExample = "http://examplé.org/rosé";
const uriFromIri = serialize(parse(iriExample));
console.log("IRI to URI (punycode + escape):
", uriFromIri);
// Expected: http://xn--exampl-gva.org/ros%C3%A9

const iriFromUri = serialize(parse(uriFromIri), { iri: true });
console.log("URI to IRI (unescape punycode + percent):
", iriFromUri);
// Expected: http://examplé.org/rosé

console.log("Equality check:", equal("example://a/b/c/%7Bfoo%7D", "eXAMPLE://a/./b/../b/%63/%7bfoo%7d"));
// Expected: true