tessl/npm-whatwg-url

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

—

Pending

Overview

Eval results

Files

URL Manipulation

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

Low-level URL manipulation utilities for modifying URL record objects and handling URL component validation. These functions operate directly on URL records and follow the WHATWG URL specification algorithms.

Capabilities

setTheUsername

Sets the username component of a URL record according to the WHATWG specification.

/**
 * Set the username on a URL record
 * @param {URLRecord} urlRecord - URL record to modify
 * @param {string} usernameString - Username to set
 */
function setTheUsername(urlRecord, usernameString)

setThePassword

Sets the password component of a URL record according to the WHATWG specification.

/**
 * Set the password on a URL record
 * @param {URLRecord} urlRecord - URL record to modify
 * @param {string} passwordString - Password to set
 */
function setThePassword(urlRecord, passwordString)

Usage Examples:

const { parseURL, setTheUsername, setThePassword, serializeURL } = require("whatwg-url");

// Parse a URL
const url = parseURL("https://example.com/path");

// Set username and password
setTheUsername(url, "user123");
setThePassword(url, "secret");

console.log(serializeURL(url)); 
// "https://user123:secret@example.com/path"

// Modify existing credentials
const urlWithAuth = parseURL("https://olduser:oldpass@example.com/");
setTheUsername(urlWithAuth, "newuser");
setThePassword(urlWithAuth, "newpass");

console.log(serializeURL(urlWithAuth)); 
// "https://newuser:newpass@example.com/"

cannotHaveAUsernamePasswordPort

Determines whether a URL record can have username, password, or port components based on its scheme and host.

/**
 * Check if URL cannot have username, password, or port
 * @param {URLRecord} urlRecord - URL record to check
 * @returns {boolean} True if URL cannot have username/password/port
 */
function cannotHaveAUsernamePasswordPort(urlRecord)

Returns true for:

URLs with null host (like file: URLs)
URLs with empty host
Certain special schemes that don't support authentication

Usage Examples:

const { parseURL, cannotHaveAUsernamePasswordPort } = require("whatwg-url");

// File URL cannot have credentials
const fileUrl = parseURL("file:///path/to/file.txt");
console.log(cannotHaveAUsernamePasswordPort(fileUrl)); // true

// HTTP URL can have credentials
const httpUrl = parseURL("https://example.com/");
console.log(cannotHaveAUsernamePasswordPort(httpUrl)); // false

// Data URL cannot have credentials  
const dataUrl = parseURL("data:text/plain,Hello");
console.log(cannotHaveAUsernamePasswordPort(dataUrl)); // true

hasAnOpaquePath

Determines whether a URL record has an opaque path (string) rather than a structured path (array).

/**
 * Check if URL has an opaque path
 * @param {URLRecord} urlRecord - URL record to check
 * @returns {boolean} True if URL has opaque path (string), false if structured path (array)
 */
function hasAnOpaquePath(urlRecord)

Opaque paths are used for:

Non-special URLs (schemes not in the special schemes list)
URLs like data:, mailto:, javascript:, etc.
URLs where the path cannot be structured into segments

Usage Examples:

const { parseURL, hasAnOpaquePath } = require("whatwg-url");

// HTTP URL has structured path (array)
const httpUrl = parseURL("https://example.com/api/users");
console.log(hasAnOpaquePath(httpUrl)); // false
console.log(httpUrl.path); // ["", "api", "users"]

// Data URL has opaque path (string)
const dataUrl = parseURL("data:text/plain;base64,SGVsbG8=");
console.log(hasAnOpaquePath(dataUrl)); // true
console.log(dataUrl.path); // "text/plain;base64,SGVsbG8="

// Mailto URL has opaque path (string)
const mailtoUrl = parseURL("mailto:user@example.com");
console.log(hasAnOpaquePath(mailtoUrl)); // true
console.log(mailtoUrl.path); // "user@example.com"

// Custom scheme URL has opaque path
const customUrl = parseURL("myscheme:some-opaque-data");
console.log(hasAnOpaquePath(customUrl)); // true
console.log(customUrl.path); // "some-opaque-data"

Advanced Usage Patterns

Safe URL Modification

Always check URL constraints before attempting modifications:

const { 
  parseURL, 
  setTheUsername, 
  setThePassword, 
  cannotHaveAUsernamePasswordPort,
  serializeURL 
} = require("whatwg-url");

function safeSetCredentials(urlString, username, password) {
  const url = parseURL(urlString);
  if (!url) {
    throw new Error("Invalid URL");
  }
  
  if (cannotHaveAUsernamePasswordPort(url)) {
    throw new Error("URL cannot have username/password");
  }
  
  setTheUsername(url, username);
  setThePassword(url, password);
  
  return serializeURL(url);
}

// Safe usage
try {
  const result = safeSetCredentials("https://example.com/", "user", "pass");
  console.log(result); // "https://user:pass@example.com/"
} catch (error) {
  console.error(error.message);
}

// Will throw error
try {
  safeSetCredentials("file:///path/file.txt", "user", "pass");
} catch (error) {
  console.error(error.message); // "URL cannot have username/password"
}

Path Type Detection

Handle different path types appropriately:

const { parseURL, hasAnOpaquePath, serializePath } = require("whatwg-url");

function analyzePath(urlString) {
  const url = parseURL(urlString);
  if (!url) return null;
  
  if (hasAnOpaquePath(url)) {
    return {
      type: "opaque",
      path: url.path, // string
      segments: null
    };
  } else {
    return {
      type: "structured", 
      path: serializePath(url), // serialized string
      segments: url.path // array
    };
  }
}

console.log(analyzePath("https://example.com/api/users"));
// { type: "structured", path: "/api/users", segments: ["", "api", "users"] }

console.log(analyzePath("data:text/plain,Hello"));
// { type: "opaque", path: "text/plain,Hello", segments: null }

Install with Tessl CLI