tessl/npm-whatwg-url

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

—

Pending

Overview

Eval results

Files

URL Class

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

The URL class provides a web-compatible interface for parsing, manipulating, and serializing URLs according to the WHATWG URL Standard.

Capabilities

Constructor

Creates a new URL instance from a URL string with optional base URL.

/**
 * Creates a new URL instance
 * @param {string} url - The URL string to parse
 * @param {string} [base] - Optional base URL for relative URLs
 * @throws {TypeError} If url is invalid or base is provided but invalid
 */
constructor(url, base)

Usage Examples:

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

// Absolute URL
const url1 = new URL("https://example.com/path");

// Relative URL with base
const url2 = new URL("/api/users", "https://example.com");
console.log(url2.href); // "https://example.com/api/users"

// Relative URL with another URL as base
const base = new URL("https://example.com/api/");
const url3 = new URL("users", base);
console.log(url3.href); // "https://example.com/api/users"

Static Methods

parse

Parses a URL string and returns a URL instance or null if invalid.

/**
 * Parse a URL string without throwing on invalid input
 * @param {string} url - The URL string to parse
 * @param {string} [base] - Optional base URL for relative URLs
 * @returns {URL|null} URL instance or null if parsing fails
 */
static parse(url, base)

canParse

Tests whether a URL string can be successfully parsed.

/**
 * Test if a URL can be parsed successfully
 * @param {string} url - The URL string to test
 * @param {string} [base] - Optional base URL for relative URLs
 * @returns {boolean} True if URL can be parsed, false otherwise
 */
static canParse(url, base)

Usage Examples:

// Safe parsing without exceptions
const url = URL.parse("https://example.com/path");
if (url) {
  console.log(url.hostname); // "example.com"
}

// Quick validation
if (URL.canParse("https://example.com")) {
  console.log("Valid URL");
}

// With base URL
const relativeUrl = URL.parse("/api", "https://example.com");
console.log(relativeUrl?.href); // "https://example.com/api"

Properties

href

The complete URL string. Setting this property re-parses the entire URL.

/**
 * Complete URL string (getter/setter)
 * @type {string}
 * @throws {TypeError} When setting to an invalid URL
 */
href

origin

The origin of the URL (protocol + host + port). Read-only.

/**
 * URL origin (readonly)
 * @type {string}
 */
origin

protocol

The protocol scheme including the trailing colon (e.g., "https:").

/**
 * Protocol scheme with colon (getter/setter)
 * @type {string}
 */
protocol

username

The username portion of the URL.

/**
 * Username portion (getter/setter)
 * @type {string}
 */
username

password

The password portion of the URL.

/**
 * Password portion (getter/setter)
 * @type {string}
 */
password

host

The host including port if non-default (e.g., "example.com:8080").

/**
 * Host with port (getter/setter)
 * @type {string}
 */
host

hostname

The hostname without port (e.g., "example.com").

/**
 * Hostname without port (getter/setter)
 * @type {string}
 */
hostname

port

The port number as a string. Empty string for default ports.

/**
 * Port number as string (getter/setter)
 * @type {string}
 */
port

pathname

The path portion of the URL including leading slash.

/**
 * Path portion with leading slash (getter/setter)
 * @type {string}
 */
pathname

search

The query string including leading "?" or empty string if no query.

/**
 * Query string with "?" (getter/setter)
 * @type {string}
 */
search

searchParams

URLSearchParams object for the query string. Read-only reference.

/**
 * Query parameters object (readonly)
 * @type {URLSearchParams}
 */
searchParams

hash

The fragment including leading "#" or empty string if no fragment.

/**
 * Fragment with "#" (getter/setter)
 * @type {string}
 */
hash

Usage Examples:

const url = new URL("https://user:pass@example.com:8080/path?query=value#section");

console.log(url.href);       // "https://user:pass@example.com:8080/path?query=value#section"
console.log(url.origin);     // "https://example.com:8080"
console.log(url.protocol);   // "https:"
console.log(url.username);   // "user"
console.log(url.password);   // "pass"
console.log(url.host);       // "example.com:8080"
console.log(url.hostname);   // "example.com"
console.log(url.port);       // "8080"
console.log(url.pathname);   // "/path"
console.log(url.search);     // "?query=value"
console.log(url.hash);       // "#section"

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

Methods

toJSON

Returns the href string representation for JSON serialization.

/**
 * Returns href string for JSON serialization
 * @returns {string} The href string
 */
toJSON()

Usage Example:

const url = new URL("https://example.com/path");
console.log(JSON.stringify({ url })); // {"url":"https://example.com/path"}
console.log(url.toJSON()); // "https://example.com/path"

Install with Tessl CLI