shelving/util/uri.d.ts

Toolkit for using data in JavaScript.

import type { ImmutableArray } from "./array.js";
import { type ImmutableDictionary } from "./dictionary.js";
import type { AnyCaller } from "./function.js";
import { type Nullish } from "./null.js";
import type { URL, URLString } from "./url.js";
/**
 * Valid URI string is anything following `protocol:resource` format, e.g. `urn:isbn:0451450523` or `http://example.com/path/to/resource`
 *
 * URI and URL differences:
 * - According to RFC 3986, URLs are a subset of URIs that have a hierarchical path component, e.g. `http://example.com/path`.
 * - The `//` at the start of a URL indicates that it has a hierarchical path component, so this makes it a URL.
 * - The absence of `//` indicates a non-hierarchical URI.
 * - URLs can be considered as "hierarchical URIs".
 * - All URLs are also URIs, but not all URIs are URLs.
 */
export type URIString = `${string}:${string}`;
/**
 * Object that describes a valid URI, e.g. `urn:isbn:0451450523` or `http://example.com/path/to/resource`
 * - Improves the builtin Javascript `URL` class to more accurately type its properties.
 *
 * URI and URL differences:
 * - According to RFC 3986, URLs are a subset of URIs that have a hierarchical path component, e.g. `http://example.com/path`.
 * - The `//` at the start of a URL indicates that it has a hierarchical path component, so this makes it a URL.
 * - The absence of `//` indicates a non-hierarchical URI.
 * - URLs can be considered as "hierarchical URIs".
 * - All URLs are also URIs, but not all URIs are URLs.
 *
 * Javascript URL problems:
 * - Javascript `URL` instance can actually represent any kind of URI (not just URLs).
 * - It's more "correct" terminology to use `URI` to refer to what the Javascript `URL` class represents.
 * - You can tell the difference because a URL will have a non-empty `host` property, whereas URIs will never have a `host` (it will be `""` empty string).
 */
export interface URI extends globalThis.URL {
    protocol: URIScheme;
    href: URIString;
}
/**
 * Construct a correctly-typed `URI` object.
 * - This is a more correctly typed version of the builtin Javascript `URI` constructor.
 * - Requires a URI string, URI object, or path as input, and optionally a base URI.
 * - If a path is provided as input, a base URI _must_ also be provided.
 * - The returned type is
 */
export interface URIConstructor {
    new (input: URIString | URI): URI;
}
export declare const URI: URIConstructor;
/** Values that can be converted to a URI instance. */
export type PossibleURI = string | globalThis.URL;
/** Is an unknown value a URI object? */
export declare function isURI(value: unknown): value is URI;
/** Assert that an unknown value is a URI object. */
export declare function assertURI(value: unknown, caller?: AnyCaller): asserts value is URI;
/** Convert a possible URI to a URI, or return `undefined` if conversion fails. */
export declare function getURI(possible: Nullish<PossibleURI>): URI | undefined;
/** Convert a possible URI to a URI, or throw `RequiredError` if conversion fails. */
export declare function requireURI(possible: PossibleURI, caller?: AnyCaller): URI;
/** Convert a possible URI to a URI string, or return `undefined` if conversion fails. */
export declare function getURIString(possible: Nullish<PossibleURI>): URIString | undefined;
/** Convert a possible URI to a URI string, or throw `RequiredError` if conversion fails. */
export declare function requireURIString(possible: PossibleURI, caller?: AnyCaller): URIString | undefined;
/** Type for a set of named URL parameters. */
export type URIParams = ImmutableDictionary<string>;
/** Type for things that can be converted to named URI parameters. */
export type PossibleURIParams = PossibleURI | URLSearchParams | ImmutableDictionary<unknown>;
/**
 * Get a set of params for a URI as a dictionary.
 * - Any params with `undefined` value will be ignored.
 */
export declare function getURIParams(input: PossibleURIParams, caller?: AnyCaller): URIParams;
/** Get a single named param from a URI. */
export declare function getURIParam(input: PossibleURIParams, key: string): string | undefined;
/** Get a single named param from a URI. */
export declare function requireURIParam(input: PossibleURIParams, key: string, caller?: AnyCaller): string;
/**
 * Return a URI with a new param set (or same URI if no changes were made).
 * - Any params with `undefined` value will be ignored.
 *
 * @throws `ValueError` if the value could not be converted to a string.
 */
export declare function withURIParam(url: URL | URLString, key: string, value: unknown, caller?: AnyCaller): URL;
export declare function withURIParam(url: PossibleURI, key: string, value: unknown, caller?: AnyCaller): URI;
/**
 * Return a URI with several new params set (or same URI if no changes were made).
 * - Param with `undefined` value will be ignored.
 *
 * @throws `ValueError` if any of the values could not be converted to strings.
 */
export declare function withURIParams(url: URL | URLString, params: PossibleURIParams, caller?: AnyCaller): URL;
export declare function withURIParams(url: PossibleURI, params: PossibleURIParams, caller?: AnyCaller): URI;
/** Return a URI without one or more params (or same URI if no changes were made). */
export declare function omitURIParams(url: URL | URLString, ...keys: string[]): URL;
export declare function omitURIParams(url: PossibleURI, ...keys: string[]): URI;
/** Return a URI without a param (or same URI if no changes were made). */
export declare const omitURIParam: (url: PossibleURI, key: string) => URI;
/** Return a URI with no search params (or same URI if no changes were made). */
export declare function clearURIParams(url: URL | URLString, caller?: AnyCaller): URL;
export declare function clearURIParams(url: PossibleURI, caller?: AnyCaller): URI;
/** A single schema for a URL. */
export type URIScheme = `${string}:`;
/** List of allowed URI schemes. */
export type URISchemes = ImmutableArray<URIScheme>;
/** Valid HTTP schemes for a URI. */
export declare const HTTP_SCHEMES: URISchemes;