π A tiny (< 500B), 0-dependency, immutable URL library, backed by the native whatwg URL. π Now with immutable Headers support!
npm install immurl
Because immurl uses the native whatwg URL API under the hood you'll need a polyfill to support environments that don't implement this API eg. IE11.
ImmutableURL works as you expect, it contains all of the properties of the native URL API.
import { ImmutableURL } from 'immurl'; const url = new ImmutableURL('https://example.com'); console.log(url.href); // 'https://example.com' // Set properties with the .set() method let newUrl = url.set('pathname', '/login'); // Because the set API is immutable you can chain calls to .set() newUrl = url.set('pathname', '/bar').set('hash', '#heading'); // https://example.com/bar#heading
immurl also contains an immutable version of the URLSearchParams API; ImmutableURLSearchParams.
The API for ImmutableURLSearchParams is exactly the same as the native version except the methods that usually mutate (.append(), .delete(), .sort()) return a new ImmutableURLSearchParams instance.
import { ImmutableURLSearchParams } from 'immurl'; let params = new ImmutableURLSearchParams('q=URLUtils.searchParams&topic=api'); params = params.append('foo', 'bar').delete('q'); // topic=api&foo=bar
The searchParams property of ImmutableURL returns an ImmutableURLSearchParams.
const url = new ImmutableURL('https://example.com?foo=bar'); const newParams = url.searchParams .append('q', 'search-term') .set('foo', 'fuz') .sort(); // url.searchParams is unaffected (thanks to immutability π) // We can pass our newParams into url.set() to create a new url with the updated params const newUrl = url.set('searchParams', newParams); // The following code is equvalent to the above const newUrl2 = url.set( 'searchParams', url.searchParams.append('q', 'search-term').set('foo', 'fuz').sort() );
Not strictly related to whatg URLs, but it's shoehorned in here because it's kinda related and they're usually used together.
import { ImmutableHeaders } from 'immurl'; const headers = new ImmutableHeaders({ foo: 'bar' }); const newHeaders = headers.set('foo', 'fuz'); console.log(headers.get('foo')); // Logs "bar" console.log(newHeaders.get('foo')); // Logs "fuz"
See the docs at https://immurl.netlify.app/