or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-url-polyfill

Polyfill URL and URLSearchParams to match WHATWG specifications for legacy browser compatibility

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

To install, run

npx @tessl/cli install tessl/npm-url-polyfill@1.1.0

index.mddocs/

URL Polyfill

URL Polyfill provides polyfill implementations for the URL and URLSearchParams web APIs to ensure compatibility with older browsers that don't support these standards. It implements the WHATWG URL specification to provide consistent URL parsing and manipulation capabilities across different browser environments, specifically tested on IE 10+.

Package Information

  • Package Name: url-polyfill
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install url-polyfill --save

Core Imports

Include the polyfill script to automatically add support for URL and URLSearchParams:

<script src="node_modules/url-polyfill/url-polyfill.js"></script>

Or in Node.js:

require('url-polyfill');

The polyfill automatically detects missing or incomplete URL/URLSearchParams support and adds the functionality to the global scope.

Basic Usage

// URL API usage
const url = new URL('https://www.example.com:8080/?fr=yset_ie_syc_oracle&type=orcl_hpset#page0');

console.log(url.hash);       // "#page0"
console.log(url.host);       // "www.example.com:8080"
console.log(url.hostname);   // "www.example.com"
console.log(url.href);       // "https://www.example.com:8080/?fr=yset_ie_syc_oracle&type=orcl_hpset#page0"
console.log(url.origin);     // "https://www.example.com:8080"
console.log(url.pathname);   // "/"
console.log(url.port);       // "8080"
console.log(url.protocol);   // "https:"
console.log(url.search);     // "?fr=yset_ie_syc_oracle&type=orcl_hpset"

// URLSearchParams API usage
url.searchParams.append('page', 0);
console.log(url.toString()); // "https://www.example.com:8080/?fr=yset_ie_syc_oracle&type=orcl_hpset&page=0#page0"

// Standalone URLSearchParams usage
const params = new URLSearchParams('a=1&b=2&a=3');
console.log(params.get('a'));    // "1"
console.log(params.getAll('a')); // ["1", "3"]
console.log(params.has('b'));    // true
params.set('c', '4');
console.log(params.toString());  // "a=1&b=2&a=3&c=4"

Capabilities

URL Constructor

Creates a new URL instance for parsing and manipulating URLs.

/**
 * Creates a new URL object
 * @param {string} url - The URL string to parse
 * @param {string} [base] - Base URL for relative URLs
 * @throws {TypeError} When URL is invalid
 */
new URL(url, base);

URL Instance Properties

Properties for accessing and modifying URL components.

/**
 * Gets/sets the fragment identifier including the '#'
 * @type {string}
 */
url.hash;

/**
 * Gets/sets the host (hostname + port)
 * @type {string}
 */
url.host;

/**
 * Gets/sets the hostname without port
 * @type {string}
 */
url.hostname;

/**
 * Gets/sets the complete URL string
 * @type {string}
 */
url.href;

/**
 * Gets the origin (protocol + hostname + port) - read-only
 * @type {string}
 */
url.origin;

/**
 * Gets/sets the path portion of the URL
 * @type {string}
 */
url.pathname;

/**
 * Gets/sets the port number
 * @type {string}
 */
url.port;

/**
 * Gets/sets the protocol scheme including ':'
 * @type {string}
 */
url.protocol;

/**
 * Gets/sets the query string including '?'
 * @type {string}
 */
url.search;

/**
 * Gets URLSearchParams object linked to the URL's query string - read-only
 * @type {URLSearchParams}
 */
url.searchParams;

/**
 * Gets/sets the username (not fully implemented - always returns empty string)
 * @type {string}
 */
url.username;

/**
 * Gets/sets the password (not fully implemented - always returns empty string)
 * @type {string}
 */
url.password;

URL Instance Methods

Methods for URL string conversion and manipulation.

/**
 * Returns the complete URL as a string
 * @returns {string} The complete URL
 */
url.toString();

URL Static Methods

Static utility methods for blob URL management.

/**
 * Creates an object URL for a blob (delegates to native implementation)
 * @param {Blob} blob - The blob object
 * @returns {string} Object URL string
 */
URL.createObjectURL(blob);

/**
 * Revokes an object URL (delegates to native implementation)  
 * @param {string} url - Object URL string to revoke
 * @returns {void}
 */
URL.revokeObjectURL(url);

URLSearchParams Constructor

Creates a new URLSearchParams instance for working with URL search parameters.

/**
 * Creates a new URLSearchParams object
 * @param {string|URLSearchParams|Array|Object} [init] - Initial search parameters
 * @throws {TypeError} When input type is unsupported
 */
new URLSearchParams(init);

Constructor Examples:

// From string
const params1 = new URLSearchParams('a=1&b=2&a=3');

// From another URLSearchParams instance
const params2 = new URLSearchParams(params1);

// From array of key-value pairs
const params3 = new URLSearchParams([['a', '1'], ['b', '2'], ['a', '3']]);

// From object
const params4 = new URLSearchParams({ a: '1', b: '2' });

// Empty
const params5 = new URLSearchParams();

URLSearchParams Instance Methods

Methods for manipulating search parameters.

/**
 * Appends a key/value pair to the search parameters
 * @param {string} name - Parameter name
 * @param {string} value - Parameter value
 * @returns {void}
 */
searchParams.append(name, value);

/**
 * Deletes all entries with the given name
 * @param {string} name - Parameter name to delete
 * @returns {void}
 */
searchParams.delete(name);

/**
 * Gets the first value associated with the given name
 * @param {string} name - Parameter name
 * @returns {string|null} The first value or null if not found
 */
searchParams.get(name);

/**
 * Gets all values associated with the given name
 * @param {string} name - Parameter name
 * @returns {Array<string>} Array of all values
 */
searchParams.getAll(name);

/**
 * Checks if a parameter with the given name exists
 * @param {string} name - Parameter name
 * @returns {boolean} True if parameter exists
 */
searchParams.has(name);

/**
 * Sets the value for the given name, replacing any existing values
 * @param {string} name - Parameter name
 * @param {string} value - Parameter value
 * @returns {void}
 */
searchParams.set(name, value);

/**
 * Sorts all parameters by name
 * @returns {void}
 */
searchParams.sort();

/**
 * Returns the search parameters as a URL-encoded string
 * @returns {string} URL-encoded parameter string
 */
searchParams.toString();

/**
 * Executes callback for each parameter
 * @param {function} callback - Function called for each parameter (value, name, searchParams)
 * @param {any} [thisArg] - Value to use as 'this' when executing callback
 * @returns {void}
 */
searchParams.forEach(callback, thisArg);

/**
 * Returns an iterator for parameter names
 * @returns {Iterator<string>} Iterator for names
 */
searchParams.keys();

/**
 * Returns an iterator for parameter values
 * @returns {Iterator<string>} Iterator for values
 */
searchParams.values();

/**
 * Returns an iterator for [name, value] pairs
 * @returns {Iterator<Array<string>>} Iterator for key-value pairs
 */
searchParams.entries();

URLSearchParams Iterator Support

When Symbol.iterator is supported, URLSearchParams provides iteration capability.

/**
 * Returns an iterator for [name, value] pairs (same as entries())
 * Available when Symbol.iterator is supported
 * @returns {Iterator<Array<string>>} Iterator for key-value pairs
 */
searchParams[Symbol.iterator]();

Iterator Usage Examples:

const params = new URLSearchParams('a=1&b=2&a=3');

// Using for...of (when Symbol.iterator is supported)
for (const [name, value] of params) {
  console.log(name, value);
}

// Using entries() explicitly
for (const [name, value] of params.entries()) {
  console.log(name, value);
}

// Using keys()
for (const name of params.keys()) {
  console.log(name);
}

// Using values()
for (const value of params.values()) {
  console.log(value);
}

URLSearchParams Instance Properties

Properties providing information about the search parameters.

/**
 * Gets the number of parameter names - read-only
 * @type {number}
 */
searchParams.size;

Error Handling

The polyfill throws standard web API errors:

  • TypeError: Thrown for invalid URLs in URL constructor
  • TypeError: Thrown for unsupported URLSearchParams input types
  • Error: Thrown for invalid base URLs

Error Examples:

try {
  const url = new URL('invalid-url');
} catch (error) {
  console.log(error instanceof TypeError); // true
}

try {
  const params = new URLSearchParams(123); // Unsupported type
} catch (error) {
  console.log(error instanceof TypeError); // true
}

Special Behavior

Parameter Encoding

The polyfill follows WHATWG URL specification for parameter encoding:

  • Spaces are encoded as + in search parameters
  • Special characters are properly percent-encoded
  • Decoding handles both + and %20 for spaces
const params = new URLSearchParams();
params.append('query', 'hello world');
console.log(params.toString()); // "query=hello+world"

const decoded = new URLSearchParams('query=hello+world');
console.log(decoded.get('query')); // "hello world"

const encoded = new URLSearchParams('query=hello%20world');
console.log(encoded.get('query')); // "hello world"

Conditional Polyfilling

The library only applies polyfills when native implementations are missing or incomplete:

  • Tests for proper URL support with searchParams integration
  • Tests for complete URLSearchParams functionality
  • Preserves native implementations when they work correctly

Legacy Browser Support

Designed specifically for IE 10+ and other legacy browsers:

  • Handles missing Symbol.iterator gracefully
  • Provides fallback iterator implementations
  • Uses DOM elements for URL parsing in older browsers

Global Location Enhancement

The polyfill also enhances the global location object:

  • Adds origin property to location when missing
  • Provides proper origin calculation for legacy browsers