CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-uri-js

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

—

Pending
Overview
Eval results
Files

scheme-support.mddocs/

Scheme Support

Built-in handlers for common URI schemes with protocol-specific parsing and serialization logic. URI.js provides an extensible scheme system with pre-built support for HTTP, HTTPS, WebSocket, mailto, URN, and UUID protocols.

Capabilities

Scheme Handler Interface

The core interface for implementing custom scheme handlers.

/**
 * Interface for URI scheme handlers providing protocol-specific processing
 */
interface URISchemeHandler<
  Components extends URIComponents = URIComponents, 
  Options extends URIOptions = URIOptions, 
  ParentComponents extends URIComponents = URIComponents
> {
  /** The scheme name this handler processes */
  scheme: string;
  /** Parse method for scheme-specific component processing */
  parse(components: ParentComponents, options: Options): Components;
  /** Serialize method for scheme-specific component serialization */
  serialize(components: Components, options: Options): ParentComponents;
  /** Whether this scheme supports Unicode characters */
  unicodeSupport?: boolean;
  /** Whether this scheme treats host as domain name */
  domainHost?: boolean;
  /** Whether this scheme requires absolute paths */
  absolutePath?: boolean;
}

Scheme Registry

Global registry of scheme handlers used by parsing and serialization functions.

/**
 * Global registry of scheme handlers
 * Schemes are automatically registered when imported
 */
const SCHEMES: {[scheme: string]: URISchemeHandler};

Built-in Scheme Handlers

HTTP Scheme

Handler for HTTP URLs with default port normalization and path requirements.

// HTTP scheme handler properties
// scheme: "http"
// domainHost: true (enables IDN processing)
// Default port: 80 (normalized away)
// Empty paths become "/"

Usage Examples:

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

// HTTP parsing normalizes default port
const httpComponents = parse("http://example.com:80/path");
console.log(httpComponents.port); // undefined (default port removed)

// HTTP serialization ensures path presence
const httpUri = serialize({
  scheme: "http",
  host: "example.com"
});
console.log(httpUri); // "http://example.com/" (path added)

// HTTP equality with port normalization
const isEqual = equal("HTTP://ABC.COM:80", "http://abc.com/");
console.log(isEqual); // true

HTTPS Scheme

Handler for HTTPS URLs extending HTTP behavior with secure port defaults.

// HTTPS scheme handler properties  
// scheme: "https"
// domainHost: true (enables IDN processing)
// Default port: 443 (normalized away)
// Empty paths become "/"

Usage Examples:

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

// HTTPS parsing normalizes default secure port
const httpsComponents = parse("https://example.com:443/secure");
console.log(httpsComponents.port); // undefined (default port removed)

// HTTPS equality with port normalization
const isSecureEqual = equal("https://abc.com", "HTTPS://ABC.COM:443/");
console.log(isSecureEqual); // true

WebSocket Scheme (WS)

Handler for WebSocket URLs with resource name composition and security flags.

interface WSComponents extends URIComponents {
  /** Combined path and query for WebSocket resource name */
  resourceName?: string;
  /** Security flag (false for ws://) */
  secure?: boolean;
}

Usage Examples:

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

// WebSocket parsing adds resourceName and secure properties
const wsComponents = parse("ws://example.com/chat?room=general");
console.log(wsComponents);
// {
//   scheme: "ws",
//   host: "example.com",
//   path: "/chat",
//   query: "room=general", 
//   resourceName: "/chat?room=general",
//   secure: false
// }

// WebSocket equality ignores fragments
const wsEqual = equal("WS://ABC.COM:80/chat#one", "ws://abc.com/chat");
console.log(wsEqual); // true

WebSocket Secure Scheme (WSS)

Handler for secure WebSocket URLs extending WS behavior with security flags.

// WSS scheme handler properties
// scheme: "wss" 
// Default port: 443 (normalized away)
// secure: true (security flag enabled)
// resourceName: path + query combination

Usage Examples:

import { parse } from "uri-js";

// WSS parsing sets secure flag
const wssComponents = parse("wss://example.com/secure-chat");
console.log(wssComponents.secure); // true
console.log(wssComponents.resourceName); // "/secure-chat"

Mailto Scheme

Handler for mailto URLs with email address parsing and header support.

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

interface MailtoComponents extends URIComponents {
  /** Array of recipient email addresses */
  to: Array<string>;
  /** Additional email headers */
  headers?: MailtoHeaders;
  /** Email subject line */
  subject?: string;
  /** Email body content */
  body?: string;
}

Usage Examples:

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

// Mailto parsing extracts email components
const mailtoComponents = parse("mailto:alpha@example.com,bravo@example.com?subject=SUBSCRIBE&body=Sign%20me%20up!");
console.log(mailtoComponents);
// {
//   scheme: "mailto",
//   to: ["alpha@example.com", "bravo@example.com"],
//   subject: "SUBSCRIBE", 
//   body: "Sign me up!"
// }

// Mailto serialization with headers
const mailtoUri = serialize({
  scheme: "mailto",
  to: ["alpha@example.com"],
  subject: "REMOVE",
  body: "Please remove me",
  headers: {
    cc: "charlie@example.com"
  }
});
console.log(mailtoUri); 
// "mailto:alpha@example.com?cc=charlie@example.com&subject=REMOVE&body=Please%20remove%20me"

URN Scheme

Handler for Uniform Resource Names with namespace identifier parsing.

interface URNComponents extends URIComponents {
  /** Namespace Identifier */
  nid?: string;
  /** Namespace Specific String */
  nss?: string;
}

interface URNOptions extends URIOptions {
  nid?: string;
}

Usage Examples:

import { parse } from "uri-js";

// URN parsing extracts namespace components
const urnComponents = parse("urn:example:foo");
console.log(urnComponents);
// {
//   scheme: "urn",
//   nid: "example",
//   nss: "foo"
// }

// More complex URN
const complexUrn = parse("urn:isbn:0451450523");
console.log(complexUrn);
// {
//   scheme: "urn", 
//   nid: "isbn",
//   nss: "0451450523"
// }

URN UUID Scheme

Specialized handler for UUID URNs with UUID validation and parsing.

interface UUIDComponents extends URNComponents {
  /** Parsed UUID string */
  uuid?: string;
}

Usage Examples:

import { parse } from "uri-js";

// UUID URN parsing extracts UUID
const uuidComponents = parse("urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6");
console.log(uuidComponents);
// {
//   scheme: "urn",
//   nid: "uuid", 
//   uuid: "f81d4fae-7dec-11d0-a765-00a0c91e6bf6"
// }

Custom Scheme Implementation

You can register custom scheme handlers by adding them to the SCHEMES registry:

import { SCHEMES, URISchemeHandler, URIComponents, URIOptions } from "uri-js";

// Example custom scheme handler
const customHandler: URISchemeHandler = {
  scheme: "custom",
  
  parse(components: URIComponents, options: URIOptions): URIComponents {
    // Custom parsing logic
    if (!components.host) {
      components.error = components.error || "Custom URIs must have a host.";
    }
    return components;
  },
  
  serialize(components: URIComponents, options: URIOptions): URIComponents {
    // Custom serialization logic
    if (components.port === 9999) {
      components.port = undefined; // Normalize default port
    }
    return components;
  },
  
  domainHost: true
};

// Register the custom handler
SCHEMES[customHandler.scheme] = customHandler;

Protocol-Specific Features

IPv6 and Zone Identifier Support

All schemes support IPv6 addresses and zone identifiers:

import { parse } from "uri-js";

// IPv6 address parsing
const ipv6 = parse("http://[2001:db8::1]/path");
console.log(ipv6.host); // "2001:db8::1"

// IPv6 with zone identifier  
const ipv6Zone = parse("http://[2001:db8::7%en1]/path");
console.log(ipv6Zone.host); // "2001:db8::7%en1"

Internationalized Domain Names (IDN)

Schemes with domainHost: true support IDN processing:

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

// IDN to ASCII conversion
const idnUri = serialize(parse("http://examplé.org/rosé"));
console.log(idnUri); // "http://xn--exampl-gva.org/ros%C3%A9"

// ASCII to IDN conversion with IRI option
const iriUri = serialize(parse("http://xn--exampl-gva.org/ros%C3%A9"), { iri: true });
console.log(iriUri); // "http://examplé.org/rosé"

Error Handling

Scheme handlers can add error messages to the components object:

import { parse } from "uri-js";

// HTTP without host generates error
const httpError = parse("http:///path");
console.log(httpError.error); // "HTTP URIs must have a host."

// URN with invalid format
const urnError = parse("urn:invalid");
console.log(urnError.error); // Error message from URN handler

Install with Tessl CLI

npx tessl i tessl/npm-uri-js

docs

component-processing.md

core-operations.md

index.md

scheme-support.md

tile.json