tessl/npm-whatwg-url

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

—

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

WHATWG URL

Name: tessl/npm-whatwg-url
Author: tessl

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";

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