tessl/npm-whatwg-url

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

—

Pending

Overview

Eval results

Files

URLSearchParams Class

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

The URLSearchParams class provides utilities for working with URL query strings, offering a standardized interface for parsing, modifying, and serializing query parameters.

Capabilities

Constructor

Creates a URLSearchParams instance from various input types.

/**
 * Creates a URLSearchParams instance
 * @param {string|URLSearchParams|Array<Array<string>>|Object} [init=""] - Initial data
 */
constructor(init)

Supported input types:

String: Query string with or without leading "?"
URLSearchParams: Another URLSearchParams instance (creates a copy)
Array: Array of key-value pairs [["key1", "value1"], ["key2", "value2"]]
Object: Plain object with string keys and values

Usage Examples:

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

// From string
const params1 = new URLSearchParams("?name=John&age=30");
const params2 = new URLSearchParams("name=John&age=30"); // works without ?

// From array of pairs
const params3 = new URLSearchParams([
  ["name", "John"],
  ["age", "30"],
  ["hobby", "reading"],
  ["hobby", "coding"] // multiple values for same key
]);

// From object
const params4 = new URLSearchParams({
  name: "John",
  age: "30",
  active: "true"
});

// Copy constructor
const params5 = new URLSearchParams(params1);

Properties

size

The number of key-value pairs. Read-only.

/**
 * Number of key-value pairs (readonly)
 * @type {number}
 */
size

Usage Example:

const params = new URLSearchParams("name=John&age=30&hobby=reading");
console.log(params.size); // 3

Methods

append

Adds a new key-value pair without replacing existing ones.

/**
 * Add a key-value pair without replacing existing values
 * @param {string} name - Parameter name
 * @param {string} value - Parameter value
 */
append(name, value)

delete

Removes all key-value pairs with the specified name, or optionally only those with a specific value.

/**
 * Remove key-value pairs by name, optionally by specific value
 * @param {string} name - Parameter name to remove
 * @param {string} [value] - Specific value to remove (if provided)
 */
delete(name, value)

get

Returns the first value for the specified name, or null if not found.

/**
 * Get the first value for a parameter name
 * @param {string} name - Parameter name
 * @returns {string|null} First value or null if not found
 */
get(name)

getAll

Returns an array of all values for the specified name.

/**
 * Get all values for a parameter name
 * @param {string} name - Parameter name
 * @returns {string[]} Array of all values (empty array if none found)
 */
getAll(name)

has

Checks if a parameter exists, optionally with a specific value.

/**
 * Check if parameter exists, optionally with specific value
 * @param {string} name - Parameter name
 * @param {string} [value] - Specific value to check for
 * @returns {boolean} True if parameter exists (with value if specified)
 */
has(name, value)

set

Sets the value for a parameter, replacing all existing values for that name.

/**
 * Set value for parameter, replacing all existing values
 * @param {string} name - Parameter name
 * @param {string} value - Parameter value
 */
set(name, value)

sort

Sorts all key-value pairs by key name using Unicode code points.

/**
 * Sort all key-value pairs by key name
 */
sort()

toString

Returns the serialized query string without leading "?".

/**
 * Serialize to query string without leading "?"
 * @returns {string} Serialized query string
 */
toString()

Usage Examples:

const params = new URLSearchParams();

// Add parameters
params.append("name", "John");
params.append("hobby", "reading");
params.append("hobby", "coding"); // multiple values

console.log(params.toString()); // "name=John&hobby=reading&hobby=coding"

// Check and get values
console.log(params.has("name")); // true
console.log(params.has("hobby", "reading")); // true
console.log(params.get("name")); // "John"
console.log(params.getAll("hobby")); // ["reading", "coding"]

// Modify parameters
params.set("name", "Jane"); // replaces existing
params.delete("hobby", "reading"); // removes only this value
console.log(params.toString()); // "name=Jane&hobby=coding"

// Sort parameters
params.append("age", "30");
params.sort();
console.log(params.toString()); // "age=30&hobby=coding&name=Jane"

Iteration

URLSearchParams implements the iterable protocol, allowing iteration over key-value pairs.

/**
 * Iterator for key-value pairs
 * @returns {Iterator<[string, string]>} Iterator yielding [key, value] pairs
 */
[Symbol.iterator]()

Usage Examples:

const params = new URLSearchParams("name=John&age=30&hobby=reading");

// For-of loop
for (const [key, value] of params) {
  console.log(`${key}: ${value}`);
}
// Output:
// name: John
// age: 30
// hobby: reading

// Destructuring
const entries = [...params];
console.log(entries); // [["name", "John"], ["age", "30"], ["hobby", "reading"]]

// Array methods
const keys = [...params].map(([key]) => key);
console.log(keys); // ["name", "age", "hobby"]

Integration with URL

URLSearchParams automatically syncs with associated URL instances when modified.

Usage Example:

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

const url = new URL("https://example.com?name=John&age=30");

// Modify through searchParams
url.searchParams.set("age", "31");
url.searchParams.append("city", "New York");

console.log(url.href); // "https://example.com/?name=John&age=31&city=New+York"
console.log(url.search); // "?name=John&age=31&city=New+York"

Install with Tessl CLI