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 { ImmutableURL, 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}`;
export type URISearch = `?${string}`;
export type URIHash = `#${string}`;
/**
 * Construct a correctly-typed `URI` object.
 * - This is a more correctly typed version of the builtin Javascript `URL` constructor.
 * - Takes a URI string or URI object that already encodes a complete URI — no base parameter, so relative inputs are not accepted.
 * - To resolve a relative input against a base, use `getBasedURI()` from `url.ts`.
 */
export interface ImmutableURIConstructor {
    new (input: URIString | ImmutableURI): ImmutableURI;
}
/**
 * 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.
 */
export interface ImmutableURI extends URL {
    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;
}
export declare const ImmutableURI: ImmutableURIConstructor;
/** Values that can be converted to an ImmutableURI instance. */
export type PossibleURI = string | URL;
/** Is an unknown value a URI object? */
export declare function isURI(value: unknown): value is ImmutableURI;
/** Assert that an unknown value is a URI object. */
export declare function assertURI(value: unknown, caller?: AnyCaller): asserts value is ImmutableURI;
/**
 * Convert a possible URI to a URI, or return `undefined` if conversion fails.
 * - Only inputs that already encode a complete URI succeed — relative inputs return `undefined`. No implicit fallback to the document or window URL.
 * - To resolve a relative ref against a base, use `getBasedURI()` from `url.ts`.
 */
export declare function getURI(possible: Nullish<PossibleURI>): ImmutableURI | undefined;
/** Convert a possible URI to a URI, or throw `RequiredError` if conversion fails. */
export declare function requireURI(possible: PossibleURI, caller?: AnyCaller): ImmutableURI;
/** 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(params: PossibleURIParams, caller?: AnyCaller): URIParams;
/** Get a single named param from a URI. */
export declare function getURIParam(params: PossibleURIParams, key: string): string | undefined;
/** Get a single named param from a URI. */
export declare function requireURIParam(params: 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(uri: ImmutableURL | URLString, key: string, value: unknown, caller?: AnyCaller): ImmutableURL;
export declare function withURIParam(uri: PossibleURI, key: string, value: unknown, caller?: AnyCaller): ImmutableURI;
/**
 * Return a URI with several new params set (or same URI if no changes were made).
 * - Any params with `undefined` value will be ignored.
 *
 * @param params A set of possible URI params.
 * - If `params` is `null` or `undefined` the same input URL will be returned.
 *
 * @throws `ValueError` if any of the values could not be converted to strings.
 */
export declare function withURIParams(uri: ImmutableURL | URLString, params: Nullish<PossibleURIParams>, caller?: AnyCaller): ImmutableURL;
export declare function withURIParams(uri: PossibleURI, params: Nullish<PossibleURIParams>, caller?: AnyCaller): ImmutableURI;
/**
 * Return a URI without one or more params (or same URI if no changes were made).
 */
export declare function omitURIParams(uri: ImmutableURL | URLString, ...keys: string[]): ImmutableURL;
export declare function omitURIParams(uri: PossibleURI, ...keys: string[]): ImmutableURI;
/** Return a URI without a param (or same URI if no changes were made). */
export declare const omitURIParam: (uri: PossibleURI, key: string) => ImmutableURI;
/** Return a URI with no search params (or same URI if no changes were made). */
export declare function clearURIParams(uri: ImmutableURL | URLString, caller?: AnyCaller): ImmutableURL;
export declare function clearURIParams(uri: PossibleURI, caller?: AnyCaller): ImmutableURI;
/** 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;