shelving/util/urimodule

These helpers work with any valid URI — including non-hierarchical ones like urn:isbn:... or mailto: — and provide typed wrappers, query-param manipulation, and safe conversion utilities. They exist because the built-in URL class has loose typing and is mutable, which can cause subtle bugs.

Things to know:

  • ImmutableURI is a re-export of the native URL constructor with a tighter TypeScript interface. At runtime it is URL; the type just restricts properties to narrower literal types.
  • getURI() only accepts complete URIs (with protocol). Relative inputs always return undefined. Use getBasedURI() from url.ts to resolve a path against a base.
  • withURIParam() / withURIParams() return the same URI instance when the params would not change.
  • getURIParams() converts URLSearchParams, a URI string, a URL object, or a plain dictionary — all to the same { key: string } shape.
  • omitURIParam is an alias for omitURIParams() with a single key.

Usage

Parsing and validating URIs

ts
import { getURI, requireURI, isURI, assertURI } from "shelving/util";

getURI("https://example.com/path");   // ImmutableURI
getURI("not-a-uri");                  // undefined
getURI(null);                         // undefined

requireURI("https://example.com");    // ImmutableURI or throws RequiredError
isURI(new URL("https://x.com"));      // true

Reading query params

ts
import { getURIParams, getURIParam, requireURIParam } from "shelving/util";

const uri = "https://example.com/search?q=shelving&page=2";

getURIParams(uri);              // { q: "shelving", page: "2" }
getURIParam(uri, "q");          // "shelving"
getURIParam(uri, "missing");    // undefined
requireURIParam(uri, "q");      // "shelving"
requireURIParam(uri, "missing"); // throws RequiredError

Modifying query params

ts
import { withURIParam, withURIParams, omitURIParams, clearURIParams } from "shelving/util";

const base = "https://example.com/search?q=shelving";

withURIParam(base, "page", 2);              // "https://example.com/search?q=shelving&page=2"
withURIParams(base, { page: 3, lang: "en" }); // adds both params
omitURIParams(base, "q");                   // "https://example.com/search"
clearURIParams(base);                       // "https://example.com/search"

Working with URI schemes

ts
import { HTTP_SCHEMES } from "shelving/util";

HTTP_SCHEMES; // ["http:", "https:"]

Functions

Go

isURI()function

Is an unknown value a URI object?

isURI(value: unknown): value is ImmutableURI
Go

assertURI()function

Assert that an unknown value is a URI object.

assertURI(value: unknown, caller: AnyCaller = assertURI): asserts value is ImmutableURI
Go

getURI()function

Convert a possible URI to a URI, or return undefined if conversion fails.

getURI(possible: Nullish<PossibleURI>): ImmutableURI | undefined
Go

requireURI()function

Convert a possible URI to a URI, or throw RequiredError if conversion fails.

requireURI(possible: PossibleURI, caller: AnyCaller = requireURI): ImmutableURI
Go

getURIParams()function

Get a set of params for a URI as a dictionary.

getURIParams(params: PossibleURIParams, caller: AnyCaller = getURIParams): URIParams
Go

getURIParam()function

Get a single named param from a URI.

getURIParam(params: PossibleURIParams, key: string): string | undefined
Go

requireURIParam()function

Get a single named param from a URI.

requireURIParam(params: PossibleURIParams, key: string, caller: AnyCaller = requireURIParam): string
Go

withURIParam()function

Return a URI with a new param set (or same URI if no changes were made).

withURIParam(uri: ImmutableURL | URLString, key: string, value: unknown, caller?: AnyCaller): ImmutableURL
withURIParam(uri: PossibleURI, key: string, value: unknown, caller?: AnyCaller): ImmutableURI
Go

withURIParams()function

Return a URI with several new params set (or same URI if no changes were made).

withURIParams(uri: ImmutableURL | URLString, params: Nullish<PossibleURIParams>, caller?: AnyCaller): ImmutableURL
withURIParams(uri: PossibleURI, params: Nullish<PossibleURIParams>, caller?: AnyCaller): ImmutableURI
Go

omitURIParams()function

Return a URI without one or more params (or same URI if no changes were made).

omitURIParams(uri: ImmutableURL | URLString, ...keys: string[]): ImmutableURL
omitURIParams(uri: PossibleURI, ...keys: string[]): ImmutableURI
Go

clearURIParams()function

Return a URI with no search params (or same URI if no changes were made).

clearURIParams(uri: ImmutableURL | URLString, caller?: AnyCaller): ImmutableURL
clearURIParams(uri: PossibleURI, caller?: AnyCaller): ImmutableURI

Interfaces

Go

ImmutableURIConstructorinterface

Construct a correctly-typed URI object.

{
	new (input: URIString | ImmutableURI): ImmutableURI;
}
Go

ImmutableURIinterface

Object that describes a valid URI, e.g. urn:isbn:0451450523 or http://example.com/path/to/resource

{
	readonly hash: URIHash | ``;
	readonly host: string;
	readonly hostname: string;
	readonly href: URIString;
	readonly origin: URIString | `null`;
	readonly password: string;
	readonly pathname: string;
	readonly port: string;
	readonly protocol: URIScheme;
	readonly search: URISearch | ``;
	readonly username: string;
}

Types

Go

URIStringtype

Valid URI string is anything following protocol:resource format, e.g. urn:isbn:0451450523 or http://example.com/path/to/resource

`${string}:${string}`
Go

URISearchtype

String for the search component of a URI, including the leading ?

`?${string}`
Go

URIHashtype

String for the hash component of a URI, including the leading #

`#${string}`
Go

PossibleURItype

Values that can be converted to an ImmutableURI instance.

string | URL
Go

URIParamstype

Type for a set of named URI parameters.

ImmutableDictionary<string>
Go

PossibleURIParamstype

Type for things that can be converted to named URI parameters.

PossibleURI | URLSearchParams | ImmutableDictionary<unknown>
Go

URISchemetype

A single schema for a URL.

`${string}:`
Go

URISchemestype

List of allowed URI schemes.

ImmutableArray<URIScheme>

Constants

Go

omitURIParamconstant

Return a URI without a param (or same URI if no changes were made).

omitURIParam: (uri: PossibleURI, key: string) => ImmutableURI
Go

HTTP_SCHEMESconstant

Valid HTTP schemes for a URI.

HTTP_SCHEMES: URISchemes