Polyfill URL and URLSearchParams to match WHATWG specifications for legacy browser compatibility
npx @tessl/cli install tessl/npm-url-polyfill@1.1.0URL 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+.
npm install url-polyfill --saveInclude 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.
// 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"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);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;Methods for URL string conversion and manipulation.
/**
* Returns the complete URL as a string
* @returns {string} The complete URL
*/
url.toString();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);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();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();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);
}Properties providing information about the search parameters.
/**
* Gets the number of parameter names - read-only
* @type {number}
*/
searchParams.size;The polyfill throws standard web API errors:
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
}The polyfill follows WHATWG URL specification for parameter encoding:
+ in search parameters+ and %20 for spacesconst 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"The library only applies polyfills when native implementations are missing or incomplete:
Designed specifically for IE 10+ and other legacy browsers:
The polyfill also enhances the global location object:
origin property to location when missing