or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.mdpercent-encoding.mdurl-class.mdurl-manipulation.mdurl-parsing.mdurl-search-params.md
tile.json

tessl/npm-whatwg-url

An implementation of the WHATWG URL Standard's URL API and parsing machinery

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/whatwg-url@14.2.x

To install, run

npx @tessl/cli install tessl/npm-whatwg-url@14.2.0

index.mddocs/

WHATWG URL

WHATWG URL is a comprehensive implementation of the WHATWG URL Standard, providing both high-level URL and URLSearchParams classes for standard web compatibility, and low-level URL parsing and manipulation APIs for advanced use cases like browser engine development.

Package Information

  • Package Name: whatwg-url
  • Package Type: npm
  • Language: JavaScript (Node.js)
  • Installation: npm install whatwg-url

Core Imports

const { URL, URLSearchParams } = require("whatwg-url");

For advanced URL parsing:

const { 
  parseURL, 
  basicURLParse, 
  serializeURL,
  percentDecodeString 
} = require("whatwg-url");

For WebIDL wrapper interfaces:

const { URL, URLSearchParams } = require("whatwg-url/webidl2js-wrapper");

Basic Usage

const { URL, URLSearchParams } = require("whatwg-url");

// Create and manipulate URLs
const url = new URL("https://example.com/path?query=value#fragment");
console.log(url.hostname); // "example.com"
console.log(url.pathname); // "/path"

// Modify URL components
url.pathname = "/new-path";
url.searchParams.set("newParam", "newValue");
console.log(url.href); // "https://example.com/new-path?query=value&newParam=newValue#fragment"

// Work with query parameters
const params = new URLSearchParams("?name=John&age=30");
params.append("city", "New York");
console.log(params.toString()); // "name=John&age=30&city=New+York"

// Low-level URL parsing
const parsed = parseURL("https://example.com/path", { baseURL: null });
if (parsed) {
  console.log(parsed.scheme); // "https"
  console.log(parsed.host); // "example.com"
}

Architecture

WHATWG URL is built around several key components:

  • Standards Compliance: Full implementation of the WHATWG URL Standard for maximum web compatibility
  • High-Level API: URL and URLSearchParams classes matching browser APIs exactly
  • Low-Level API: Internal URL parsing functions and utilities for building URL-aware applications
  • WebIDL Integration: Generated interfaces using webidl2js for precise specification compliance
  • Error Handling: Proper error handling with TypeError exceptions for invalid inputs

Capabilities

URL Class

Standard web-compatible URL class for parsing, manipulating, and serializing URLs with full property access and modification support.

class URL {
  constructor(url, base);
  static parse(url, base);
  static canParse(url, base);
  
  href; // string getter/setter
  origin; // string readonly
  protocol; // string getter/setter
  username; // string getter/setter
  password; // string getter/setter
  host; // string getter/setter
  hostname; // string getter/setter
  port; // string getter/setter
  pathname; // string getter/setter
  search; // string getter/setter
  searchParams; // URLSearchParams readonly
  hash; // string getter/setter
  
  toJSON();
}

URL Class

URLSearchParams Class

Query string parameter manipulation with full iteration support and standard web API compatibility.

class URLSearchParams {
  constructor(init);
  
  size; // number readonly
  
  append(name, value);
  delete(name, value);
  get(name);
  getAll(name);
  has(name, value);
  set(name, value);
  sort();
  toString();
  [Symbol.iterator]();
}

URLSearchParams Class

URL Parsing

Low-level URL parsing functions following the WHATWG specification for building URL-aware applications and browser engines.

function parseURL(input, options);
function basicURLParse(input, options);
function serializeURL(urlRecord, excludeFragment);
function serializePath(urlRecord);
function serializeHost(hostFromURLRecord);
function serializeURLOrigin(urlRecord);
function serializeInteger(integer);

URL Parsing

URL Manipulation

Low-level URL manipulation utilities for modifying URL record objects and handling URL components.

function setTheUsername(urlRecord, usernameString);
function setThePassword(urlRecord, passwordString);
function cannotHaveAUsernamePasswordPort(urlRecord);
function hasAnOpaquePath(urlRecord);

URL Manipulation

Percent Encoding

Percent encoding and decoding utilities for handling URL-encoded strings and byte sequences.

function percentDecodeString(string);
function percentDecodeBytes(uint8Array);

Percent Encoding

Types

/**
 * URL record object returned by parsing functions
 */
interface URLRecord {
  scheme: string;
  username: string;
  password: string;
  host: string | null;
  port: number | null;
  path: string[] | string; // array for normal URLs, string for opaque paths
  query: string | null;
  fragment: string | null;
}

/**
 * Options for URL parsing functions
 */
interface ParseOptions {
  baseURL?: URLRecord | null;
  url?: URLRecord; // for basicURLParse only
  stateOverride?: string; // for basicURLParse only
}

/**
 * State override values for basicURLParse
 */
type StateOverride = 
  | "scheme start" | "scheme" | "no scheme"
  | "special relative or authority" | "path or authority" | "relative"
  | "relative slash" | "special authority slashes" | "special authority ignore slashes"
  | "authority" | "host" | "hostname" | "port"
  | "file" | "file slash" | "file host"
  | "path start" | "path" | "opaque path"
  | "query" | "fragment";