tessl/npm-uri-js

An RFC 3986/3987 compliant, scheme extendable URI/IRI parsing/normalizing/resolving/serializing library for JavaScript.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

URI.js

Name: tessl/npm-uri-js
Author: tessl

URI.js is an RFC 3986/3987 compliant, scheme extendable URI parsing, normalizing, resolving, and serializing library for JavaScript environments. It provides comprehensive support for URI and IRI handling with built-in scheme support, IPv4/IPv6 address normalization, and internationalized domain name (IDN) processing.

Package Information

Package Name: uri-js
Package Type: npm
Language: TypeScript
Installation: npm install uri-js

Core Imports

import * as URI from "uri-js";

For named imports:

import { 
  parse, 
  serialize, 
  resolve, 
  normalize, 
  equal,
  escapeComponent,
  unescapeComponent,
  removeDotSegments,
  resolveComponents,
  pctEncChar,
  pctDecChars,
  SCHEMES,
  URIComponents,
  URIOptions,
  URISchemeHandler,
  URIRegExps
} from "uri-js";

For CommonJS:

const URI = require("uri-js");
// or
const { 
  parse, 
  serialize, 
  resolve, 
  normalize, 
  equal,
  escapeComponent,
  unescapeComponent,
  removeDotSegments,
  resolveComponents,
  pctEncChar,
  pctDecChars,
  SCHEMES 
} = require("uri-js");

Basic Usage

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

// Parse a URI into components
const components = parse("http://user:pass@example.com:8080/path?query=value#fragment");
console.log(components);
// {
//   scheme: "http",
//   userinfo: "user:pass", 
//   host: "example.com",
//   port: 8080,
//   path: "/path",
//   query: "query=value",
//   fragment: "fragment"
// }

// Serialize components back to URI string
const uri = serialize({
  scheme: "https",
  host: "example.com",
  path: "/api/data",
  query: "format=json"
});
console.log(uri); // "https://example.com/api/data?format=json"

// Resolve relative URIs
const resolved = resolve("http://example.com/a/b/c", "../d/e");
console.log(resolved); // "http://example.com/a/d/e"

// Normalize URIs
const normalized = normalize("HTTP://EXAMPLE.COM:80/%7Efoo");
console.log(normalized); // "http://example.com/~foo"

// Compare URIs for equality
const isEqual = equal("http://example.com/", "HTTP://EXAMPLE.COM:80/");
console.log(isEqual); // true

Architecture

URI.js is built around several key components:

Core Parser: RFC 3986/3987 compliant parsing engine with support for both URI and IRI formats
Component System: Structured representation of URI parts (scheme, host, path, query, etc.)
Scheme Handlers: Extensible scheme-specific processing for HTTP, HTTPS, WebSocket, mailto, and URN protocols
Normalization Engine: Standardization of URI formatting including case normalization and percent-encoding
Resolution System: Relative URI resolution following RFC 3986 algorithms
Type System: Full TypeScript support with comprehensive type definitions

Capabilities

Core URI Operations

Essential URI parsing, serialization, and manipulation functions for standard URI processing workflows.

function parse(uriString: string, options?: URIOptions): URIComponents;
function serialize(components: URIComponents, options?: URIOptions): string;
function resolve(baseURI: string, relativeURI: string, options?: URIOptions): string;
function normalize(uri: string, options?: URIOptions): string;
function normalize(uri: URIComponents, options?: URIOptions): URIComponents;
function equal(uriA: string, uriB: string, options?: URIOptions): boolean;
function equal(uriA: URIComponents, uriB: URIComponents, options?: URIOptions): boolean;

Core Operations

Component Processing

Advanced component-level URI manipulation including encoding, escaping, and path segment processing.

function escapeComponent(str: string, options?: URIOptions): string;
function unescapeComponent(str: string, options?: URIOptions): string; 
function removeDotSegments(input: string): string;
function resolveComponents(base: URIComponents, relative: URIComponents, options?: URIOptions, skipNormalization?: boolean): URIComponents;
function pctEncChar(chr: string): string;
function pctDecChars(str: string): string;

Component Processing

Scheme Support

Built-in handlers for common URI schemes with protocol-specific parsing and serialization logic.

interface URISchemeHandler<Components extends URIComponents = URIComponents, Options extends URIOptions = URIOptions, ParentComponents extends URIComponents = URIComponents> {
  scheme: string;
  parse(components: ParentComponents, options: Options): Components;
  serialize(components: Components, options: Options): ParentComponents;
  unicodeSupport?: boolean;
  domainHost?: boolean;
  absolutePath?: boolean;
}

const SCHEMES: {[scheme: string]: URISchemeHandler};

Built-in scheme support includes: HTTP, HTTPS, WebSocket (WS/WSS), mailto, URN, and URN UUID.

Scheme Support

Core Types

interface URIComponents {
  scheme?: string;
  userinfo?: string;
  host?: string;
  port?: number | string;
  path?: string;
  query?: string;
  fragment?: string;
  reference?: string;
  error?: string;
}

interface URIOptions {
  scheme?: string;
  reference?: string;
  tolerant?: boolean;
  absolutePath?: boolean;
  iri?: boolean;
  unicodeSupport?: boolean;
  domainHost?: boolean;
}

interface URIRegExps {
  NOT_SCHEME: RegExp;
  NOT_USERINFO: RegExp;
  NOT_HOST: RegExp;
  NOT_PATH: RegExp;
  NOT_PATH_NOSCHEME: RegExp;
  NOT_QUERY: RegExp;
  NOT_FRAGMENT: RegExp;
  ESCAPE: RegExp;
  UNRESERVED: RegExp;
  OTHER_CHARS: RegExp;
  PCT_ENCODED: RegExp;
  IPV4ADDRESS: RegExp;
  IPV6ADDRESS: RegExp;
}

Specialized Component Types

These interfaces extend the base URIComponents for scheme-specific parsing and serialization. They are used internally by scheme handlers and returned by parsing functions when processing specific URI schemes.

interface WSComponents extends URIComponents {
  resourceName?: string;
  secure?: boolean;
}

interface MailtoHeaders {
  [hfname: string]: string;
}

interface MailtoComponents extends URIComponents {
  to: Array<string>;
  headers?: MailtoHeaders;
  subject?: string;
  body?: string;
}

interface URNComponents extends URIComponents {
  nid?: string;
  nss?: string;
}

interface URNOptions extends URIOptions {
  nid?: string;
}

interface UUIDComponents extends URNComponents {
  uuid?: string;
}

Workspace: tessl
Visibility: Public
Created: 7 months ago
Last updated: 3 months ago
Describes: pkg:npm/uri-js@4.4.x
Publish Source: CLI
Badge