Skip to content

πŸ”— A tiny immutable URL library, backed by the native whatwg URL.

License

Notifications You must be signed in to change notification settings

tom-sherman/immurl

Folders and files

NameName
Last commit message
Last commit date

Latest commit

Β 

History

29 Commits
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

immurl

πŸ”— A tiny (< 500B), 0-dependency, immutable URL library, backed by the native whatwg URL. πŸŽ‰ Now with immutable Headers support!

Install

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.

Usage

ImmutableURL

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

ImmutableURLSearchParams

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()
);

ImmutableHeaders

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"

API

See the docs at https://immurl.netlify.app/