URLStoreclass

new URLStore(url: PossibleURL, base?: PossibleURL)

Param	Type
`url`	`PossibleURL`	The initial URL value. required
`base`	`PossibleURL`	An optional base URL that relative URLs are resolved against.

Return
`URLStore`	Store a URL, e.g. top.com/a/b/c

Property	Type
`.base`	`ImmutableURL`	Base URL that relative URL inputs are resolved against, or `undefined` if none was set. readonly
`.href`	`URLString`	Get or set the full URL string (e.g. `https://top.com/a/b/c?x=1`). required
`.origin`	`URLString`	Get the origin of the URL (e.g. `https://top.com`). required readonly
`.protocol`	`URIScheme`	Get the protocol/scheme of the URL (e.g. `https:`). required readonly
`.username`	`string`	Get the username component of the URL. required readonly
`.password`	`string`	Get the password component of the URL. required readonly
`.hostname`	`string`	Get the hostname of the URL (e.g. `top.com`). required readonly
`.host`	`string`	Get the host of the URL including port (e.g. `top.com:8080`). required readonly
`.port`	`string`	Get the port of the URL, or an empty string if none is set. required readonly
`.pathname`	`AbsolutePath`	Get the absolute pathname of the URL (e.g. `/a/b/c`). required readonly
`.search`	`string`	Get the URL params as a query string (e.g. `?x=1&y=2`). required readonly
`.params`	`URIParams`	Get the URL params as a dictionary of key/value pairs. required readonly

Store a URL, e.g. https://top.com/a/b/c

Accepts any PossibleURL as input and normalises it to an ImmutableURL (resolved against this.base).
Exposes the URL's components (href, origin, pathname, etc.) and helpers to read and mutate its search params.

A Store for a URL such as https://example.com/a/b/c. URLStore coerces any assigned URL or URL string (resolved against an optional base), exposes the URL's parts as accessors, and adds query-param and route-matching helpers.

Usage

import { URLStore } from "shelving/store";

const url = new URLStore("https://example.com/search?q=hats");

console.log(url.hostname);        // "example.com"
console.log(url.getParam("q"));   // "hats"

url.setParam("page", "2");        // updates the stored URL's query
url.value = "/search?q=shoes";    // assign a relative path — resolved against the current URL

url.isActive("https://example.com/search?q=shoes"); // true
url.isProud("https://example.com/search");          // true — current URL sits below this one

Param helpers come in mutating (setParam, updateParams, deleteParam, clearParams) and non-mutating (withParam, withParams, omitParam) forms — the latter return a new URL without changing the store.

Examples

const store = new URLStore("https://top.com/a/b/c");
store.setParam("page", 2); // https://top.com/a/b/c?page=2
store.isActive("https://top.com/a/b/c?page=2"); // true

Methods

URLStore.getParam()method

Return a single param in this URL, or undefined if it could not be found.

getParam(key: string): string | undefined

URLStore.requireParam()method

Require a single param in this URL, or throw RequiredError if it could not be found.

requireParam(key: string): string | undefined

URLStore.setParams()method

Set all params in this URL (all current params are cleared first).

setParams(params: PossibleURIParams): void

URLStore.setParam()method

Set a single named param in this URL.

setParam(key: string, value: unknown): void

URLStore.updateParams()method

Update several params in this URL (merged with current params).

updateParams(params: PossibleURIParams): void

URLStore.deleteParam()method

Delete one or more params from this URL.

deleteParam(key: string, ...keys: string[]): void

URLStore.deleteParams()method

Delete one or more params from this URL.

deleteParams(key: string, ...keys: string[]): void

URLStore.clearParams()method

Clear all params from this URL.

clearParams(): void

URLStore.withParam()method

Return the current URL with an additional param (without mutating this store).

withParam(key: string, value: unknown): ImmutableURL

URLStore.withParams()method

Return the current URL with additional params (without mutating this store).

withParams(params: PossibleURIParams): ImmutableURL

URLStore.omitParams()method

Return the current URL with one or more params removed (without mutating this store).

omitParams(...keys: string[]): ImmutableURL

URLStore.omitParam()method

Return the current URL with a single param removed (without mutating this store).

omitParam(key: string): ImmutableURL

URLStore.isActive()method

Is target active relative to this store's URL?

isActive(target: PossibleURL): boolean

URLStore.isProud()method

Is target proud relative to this store's URL?

isProud(target: PossibleURL): boolean