shelving 1.167.2 → 1.168.1

package/store/URLStore.js

@@ -1,5 +1,6 @@
 import { getGetter, getSetter } from "../util/class.js";
-import { getURL, getURLParam, getURLParams, omitURLParams, requireURL, requireURLParam, withURLParam, withURLParams, } from "../util/url.js";
+import { getURIParam, getURIParams, omitURIParams, requireURIParam, withURIParam, withURIParams, } from "../util/uri.js";
+import { getURL, requireURL } from "../util/url.js";
 import { Store } from "./Store.js";
 /** Store a URL, e.g. `https://top.com/a/b/c` */
 export class URLStore extends Store {
@@ -51,47 +52,47 @@ export class URLStore extends Store {
     }
     /** Get the URL params as a dictionary. */
     get params() {
-        return getURLParams(this.value.searchParams, getGetter(this, "params"));
+        return getURIParams(this.value.searchParams, getGetter(this, "params"));
     }
     /** Return a single param in this URL, or `undefined` if it could not be found. */
     getParam(key) {
-        return getURLParam(this.value.searchParams, key);
+        return getURIParam(this.value.searchParams, key);
     }
     /** Require a single param in this URL, or throw `RequiredError` if it could not be found. */
     requireParam(key) {
-        return requireURLParam(this.value.searchParams, key, getSetter(this, "requireParam"));
+        return requireURIParam(this.value.searchParams, key, getSetter(this, "requireParam"));
     }
     /** Update a single param in this URL. */
     setParam(key, value) {
-        this.value = withURLParam(this.value, key, value, this.setParams);
+        this.value = withURIParam(this.value, key, value, this.setParams);
     }
     /** Update several params in this URL. */
     setParams(params) {
-        this.value = withURLParams(this.value, params, this.setParams);
+        this.value = withURIParams(this.value, params, this.setParams);
     }
     /** Delete one or more params in this URL. */
     deleteParam(key, ...keys) {
-        this.value = omitURLParams(this.value, key, ...keys);
+        this.value = omitURIParams(this.value, key, ...keys);
     }
     /** Delete one or more params in this URL. */
     deleteParams(key, ...keys) {
-        this.value = omitURLParams(this.value, key, ...keys);
+        this.value = omitURIParams(this.value, key, ...keys);
     }
     /** Return the current URL with an additional param. */
     withParam(key, value) {
-        return withURLParam(this.value, key, value, this.withParam);
+        return withURIParam(this.value, key, value, this.withParam);
     }
     /** Return the current URL with an additional param. */
     withParams(params) {
-        return withURLParams(this.value, params, this.withParams);
+        return withURIParams(this.value, params, this.withParams);
     }
     /** Return the current URL with an additional param. */
     omitParams(...keys) {
-        return omitURLParams(this.value, ...keys);
+        return omitURIParams(this.value, ...keys);
     }
     /** Return the current URL with an additional param. */
     omitParam(key) {
-        return omitURLParams(this.value, key);
+        return omitURIParams(this.value, key);
     }
     toString() {
         return this.href;

package/store/index.d.ts

@@ -2,6 +2,7 @@ export * from "./ArrayStore.js";
 export * from "./BooleanStore.js";
 export * from "./DataStore.js";
 export * from "./DictionaryStore.js";
+export * from "./EndpointStore.js";
 export * from "./PathStore.js";
 export * from "./Store.js";
 export * from "./URLStore.js";

package/store/index.js

@@ -2,6 +2,7 @@ export * from "./ArrayStore.js";
 export * from "./BooleanStore.js";
 export * from "./DataStore.js";
 export * from "./DictionaryStore.js";
+export * from "./EndpointStore.js";
 export * from "./PathStore.js";
 export * from "./Store.js";
 export * from "./URLStore.js";

package/util/format.d.ts

@@ -2,7 +2,7 @@ import { type ImmutableArray } from "./array.js";
 import { type PossibleDate } from "./date.js";
 import { type Duration } from "./duration.js";
 import { type ImmutableObject } from "./object.js";
-import { type PossibleURL } from "./url.js";
+import { type PossibleURI } from "./uri.js";
 /** Options we use for number formatting. */
 export type NumberOptions = Omit<Intl.NumberFormatOptions, "style" | "unit" | "unitDisplay" | "currency" | "currencyDisplay" | "currencySign">;
 /** Format a number (based on the user's browser language settings). */
@@ -73,7 +73,7 @@ export declare function formatTime(time?: PossibleDate, options?: Intl.DateTimeF
 /** Format a datetime in the browser locale (no seconds by default). */
 export declare function formatDateTime(date: PossibleDate, options?: Intl.DateTimeFormatOptions): string;
 /** Format a URL as a user-friendly string, e.g. `http://shax.com/test?uid=129483` → `shax.com/test` */
-export declare function formatURL(possible: PossibleURL, base?: PossibleURL): string;
+export declare function formatURI(possible: PossibleURI): string;
 /**
  * Convert any unknown value into a friendly string for user-facing use.
  * - Strings return the string.

package/util/format.js

@@ -5,7 +5,7 @@ import { getBestTimeUnit, getMilliseconds } from "./duration.js";
 import { getPercent } from "./number.js";
 import { isObject } from "./object.js";
 import { TIME_UNITS } from "./units.js";
-import { requireURL } from "./url.js";
+import { isURI, requireURI } from "./uri.js";
 /** Format a number (based on the user's browser language settings). */
 export function formatNumber(num, options) {
     return Intl.NumberFormat(undefined, options).format(num);
@@ -110,9 +110,9 @@ export function formatDateTime(date, options) {
     });
 }
 /** Format a URL as a user-friendly string, e.g. `http://shax.com/test?uid=129483` → `shax.com/test` */
-export function formatURL(possible, base) {
-    const { host, pathname } = requireURL(possible, base, formatURL);
-    return `${host}${pathname.length > 1 ? pathname : ""}`;
+export function formatURI(possible) {
+    const { host, pathname } = requireURI(possible, formatURI);
+    return `${host}${pathname !== "/" ? pathname : ""}`;
 }
 /**
  * Convert any unknown value into a friendly string for user-facing use.
@@ -146,6 +146,8 @@ export function formatValue(value) {
         return formatArray(value);
     if (isObject(value))
         return formatObject(value);
+    if (isURI(value))
+        return formatURI(value);
     return "Unknown";
 }
 /**

package/util/http.d.ts

@@ -1,6 +1,8 @@
 import { RequestError } from "../error/RequestError.js";
 import { ResponseError } from "../error/ResponseError.js";
+import { type ImmutableDictionary } from "./dictionary.js";
 import type { AnyCaller } from "./function.js";
+import type { URLString } from "./url.js";
 /** A handler function takes a `Request` and returns a `Response` (possibly asynchronously). */
 export type RequestHandler = (request: Request) => Response | Promise<Response>;
 export declare function _getMessageJSON(message: Request | Response, MessageError: typeof RequestError | typeof ResponseError, caller: AnyCaller): Promise<unknown>;
@@ -49,3 +51,23 @@ export declare function getResponse(value: unknown): Response;
  * @param debug If `true` include the error message in the response (for debugging), or `false` to return generic error codes (for security).
  */
 export declare function getErrorResponse(reason: unknown, debug?: boolean): Response;
+/** HTTP request methods. */
+export type RequestMethod = RequestBodyMethod | RequestHeadMethod;
+/** HTTP request methods that have no body. */
+export type RequestHeadMethod = "HEAD" | "GET";
+/** HTTP request methods that have a body. */
+export type RequestBodyMethod = "POST" | "PUT" | "PATCH" | "DELETE";
+/** Configurable options for endpoint. */
+export type RequestOptions = Omit<RequestInit, "method" | "body">;
+/**
+ * Create a `Request` instance for a method/url and payload.
+ *
+ * - If `{placeholders}` are set in the URL, they are replaced by values from payload (will throw if `payload` is not a dictionary object).
+ * - If the method is `HEAD` or `GET`, the payload is sent as `?query` parameters in the URL.
+ * - If the method is anything else, the payload is sent in the body (plain text string, `FormData` object, or JSON for any other).
+ *
+ * @throws ValueError if this is a `HEAD` or `GET` request but `body` is not a dictionary object.
+ * @throws ValueError if `{placeholders}` are set in the URL but `body` is not a dictionary object.
+ */
+export declare function getRequest(method: RequestHeadMethod, url: URLString, payload: ImmutableDictionary<unknown>, options?: RequestOptions, caller?: AnyCaller): Request;
+export declare function getRequest(method: RequestMethod, url: URLString, payload: unknown, options?: RequestOptions, caller?: AnyCaller): Request;

package/util/http.js

@@ -1,7 +1,10 @@
 import { RequestError } from "../error/RequestError.js";
 import { ResponseError } from "../error/ResponseError.js";
 import { Feedback } from "../feedback/Feedback.js";
+import { assertDictionary } from "./dictionary.js";
 import { isError } from "./error.js";
+import { getPlaceholders, renderTemplate } from "./template.js";
+import { omitURIParams, withURIParams } from "./uri.js";
 export async function _getMessageJSON(message, MessageError, caller) {
     const trimmed = (await message.text()).trim();
     if (!trimmed.length)
@@ -112,3 +115,59 @@ export function getErrorResponse(reason, debug = false) {
     // Otherwise return a generic error message with no details.
     return new Response(undefined, { status });
 }
+export function getRequest(method, url, payload, options = {}, caller = getRequest) {
+    // This is a head request, so ensure the payload is a dictionary object.
+    if (method === "GET" || method === "HEAD") {
+        assertDictionary(payload, caller);
+        return getHeadRequest(method, url, payload, options, caller);
+    }
+    // This is a normal body request.
+    return getBodyRequest(method, url, payload, options, caller);
+}
+/**
+ * Create a body-less request to a URL.
+ * - Any `{placeholders}` in the URL will be rendered with values from `params`, and won't be set in `?query` parameters in the URL.
+ */
+function getHeadRequest(method, url, params, options = {}, caller = getHeadRequest) {
+    const placeholders = getPlaceholders(url);
+    // URL has `{placeholders}` to render, so rendere those to the URL and add all other params as `?query` params.
+    if (placeholders.length) {
+        const rendered = omitURIParams(withURIParams(renderTemplate(url, params, caller), params, caller), ...placeholders);
+        return new Request(rendered, { ...options, method });
+    }
+    // URL has no `{placeholders}`, so add all payload params to the URL.
+    return new Request(withURIParams(url, params, caller), { ...options, method });
+}
+/**
+ * Create a body request to a URL.
+ * - Any `{placeholders}` in the URL will be rendered with values from `data`, and won't be set in the request body.
+ * - The payload is sent in the body (either as JSON, string, or `FormData`).
+ *
+ * @throws ValueError if `{placeholders}` are set in the URL but `body` is not a dictionary object.
+ */
+function getBodyRequest(method, url, body, options = {}, caller = getBodyRequest) {
+    const placeholders = getPlaceholders(url);
+    // If `{placeholders}` are set in the URL then body must be a dictionary object and is sent as JSON.
+    if (placeholders.length) {
+        assertDictionary(body, caller);
+        return getJSONRequest(method, renderTemplate(url, body, caller), body, options);
+    }
+    // `FormData` instances pass through unaltered and will set their own `Content-Type` with complex boundary information.
+    if (body instanceof FormData)
+        return getFormDataRequest(method, url, body, options);
+    if (typeof body === "string")
+        return getTextRequest(method, url, body, options);
+    return getJSONRequest(method, url, body, options); // JSON is the default.
+}
+/** Create a `FormData` request to a URL. */
+function getFormDataRequest(method, url, body, options = {}) {
+    return new Request(url, { ...options, method, body });
+}
+/** Create a plain text request to a URL. */
+function getTextRequest(method, url, body, { headers, ...options } = {}) {
+    return new Request(url, { ...options, headers: { ...headers, "Content-Type": "text/plain" }, method, body });
+}
+/** Create a JSON request to a URL. */
+function getJSONRequest(method, url, body, { headers, ...options } = {}) {
+    return new Request(url, { ...options, headers: { ...headers, "Content-Type": "application/json" }, method, body: JSON.stringify(body) });
+}

package/util/index.d.ts

@@ -34,7 +34,6 @@ export * from "./iterate.js";
 export * from "./jsx.js";
 export * from "./jwt.js";
 export * from "./lazy.js";
-export * from "./link.js";
 export * from "./map.js";
 export * from "./merge.js";
 export * from "./null.js";
@@ -56,6 +55,7 @@ export * from "./transform.js";
 export * from "./undefined.js";
 export * from "./units.js";
 export * from "./update.js";
+export * from "./uri.js";
 export * from "./url.js";
 export * from "./uuid.js";
 export * from "./validate.js";

package/util/index.js

@@ -34,7 +34,6 @@ export * from "./iterate.js";
 export * from "./jsx.js";
 export * from "./jwt.js";
 export * from "./lazy.js";
-export * from "./link.js";
 export * from "./map.js";
 export * from "./merge.js";
 export * from "./null.js";
@@ -56,6 +55,7 @@ export * from "./transform.js";
 export * from "./undefined.js";
 export * from "./units.js";
 export * from "./update.js";
+export * from "./uri.js";
 export * from "./url.js";
 export * from "./uuid.js";
 export * from "./validate.js";

package/util/uri.d.ts

@@ -0,0 +1,94 @@
+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. */
+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).
+ * - 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).
+ * - 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;
+/** 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;

package/util/uri.js

@@ -0,0 +1,119 @@
+import { RequiredError } from "../error/RequiredError.js";
+import { ValueError } from "../error/ValueError.js";
+import { getDictionaryItems, isDictionary } from "./dictionary.js";
+import { notNullish } from "./null.js";
+import { getString, isString } from "./string.js";
+export const URI = globalThis.URL;
+/** Is an unknown value a URI object? */
+export function isURI(value) {
+    return value instanceof URI;
+}
+/** Assert that an unknown value is a URI object. */
+export function assertURI(value, caller = assertURI) {
+    if (!isURI(value))
+        throw new RequiredError("Invalid URI", { received: value, caller });
+}
+/** Convert a possible URI to a URI, or return `undefined` if conversion fails. */
+export function getURI(possible) {
+    if (notNullish(possible)) {
+        if (isURI(possible))
+            return possible;
+        try {
+            return new globalThis.URL(possible);
+        }
+        catch {
+            return undefined;
+        }
+    }
+}
+/** Convert a possible URI to a URI, or throw `RequiredError` if conversion fails. */
+export function requireURI(possible, caller = requireURI) {
+    const url = getURI(possible);
+    assertURI(url, caller);
+    return url;
+}
+/** Convert a possible URI to a URI string, or return `undefined` if conversion fails. */
+export function getURIString(possible) {
+    return getURI(possible)?.href;
+}
+/** Convert a possible URI to a URI string, or throw `RequiredError` if conversion fails. */
+export function requireURIString(possible, caller = requireURIString) {
+    return requireURI(possible, caller).href;
+}
+/**
+ * Get a set of entries for a set of possible URI params.
+ *
+ * Note: Not as simple as just converting with `Object.fromEntries()`:
+ * 1. When `URLSearchParams` contains multiple values for the same key, calling `params.get()` will return the _first_ value.
+ * 2. So when converting this to a simple data object, only one value per key can be represented, but it needs to be the _first_ one.
+ * 3. Since we're looping through anyway, we also take the time to convert values to strings, so we can accept a wider range of input types.
+ */
+function* getURIEntries(input, caller = getURIParams) {
+    if (input instanceof URLSearchParams) {
+        yield* input;
+    }
+    else if (isString(input) || input instanceof globalThis.URL) {
+        yield* requireURI(input, caller).searchParams;
+    }
+    else {
+        const done = [];
+        for (const [key, value] of getDictionaryItems(input)) {
+            if (done.includes(key))
+                continue;
+            done.push(key);
+            const str = getString(value);
+            if (str === undefined)
+                throw new ValueError(`URI param "${key}" must be string`, { received: value, caller });
+            yield [key, str];
+        }
+    }
+}
+/** Get a set of params for a URI as a dictionary. */
+export function getURIParams(input, caller = getURIParams) {
+    const output = {};
+    for (const [key, str] of getURIEntries(input, caller))
+        output[key] = str;
+    return output;
+}
+/** Get a single named param from a URI. */
+export function getURIParam(input, key) {
+    if (input instanceof URLSearchParams)
+        return input.get(key) || undefined;
+    if (isDictionary(input))
+        return getString(input[key]);
+    return getURIParams(input)[key];
+}
+/** Get a single named param from a URI. */
+export function requireURIParam(input, key, caller = requireURIParam) {
+    const value = getURIParam(input, key);
+    if (value === undefined)
+        throw new RequiredError(`URI param "${key}" is required`, { received: input, caller });
+    return value;
+}
+export function withURIParam(url, key, value, caller = withURIParam) {
+    const input = requireURI(url, caller);
+    const output = new URI(input);
+    const str = getString(value);
+    if (str === undefined)
+        throw new ValueError(`URI param "${key}" must be string`, { received: value, caller });
+    output.searchParams.set(key, str);
+    return input.href === output.href ? input : output;
+}
+export function withURIParams(url, params, caller = withURIParams) {
+    const input = requireURI(url, caller);
+    const output = new URI(input);
+    for (const [key, str] of getURIEntries(params, caller))
+        output.searchParams.set(key, str);
+    return input.href === output.href ? input : output;
+}
+export function omitURIParams(url, ...keys) {
+    const input = requireURI(url, omitURIParams);
+    const output = new URI(input);
+    for (const key of keys)
+        output.searchParams.delete(key);
+    return input.href === output.href ? input : output;
+}
+/** Return a URI without a param (or same URI if no changes were made). */
+export const omitURIParam = omitURIParams;
+/** Valid HTTP schemes for a URI. */
+export const HTTP_SCHEMES = ["http:", "https:"];

package/util/url.d.ts

@@ -1,46 +1,56 @@
-import type { DictionaryItem, ImmutableDictionary } from "./dictionary.js";
 import type { AnyCaller } from "./function.js";
 import { type Nullish } from "./null.js";
-/** Values that can be converted to a URL instance. */
-export type PossibleURL = string | URL;
-/** Is an unknown value a URL object? */
-export declare function isURL(value: unknown): value is URL;
-/** Assert that an unknown value is a URL object. */
-export declare function assertURL(value: unknown, caller?: AnyCaller): asserts value is URL;
-/** Convert a possible URL to a URL, or return `undefined` if conversion fails. */
-export declare function getURL(possible: Nullish<PossibleURL>, base?: PossibleURL | undefined): URL | undefined;
-/** Convert a possible URL to a URL, or throw `RequiredError` if conversion fails. */
-export declare function requireURL(possible: PossibleURL, base?: PossibleURL, caller?: AnyCaller): URL;
-/** Type for a set of named URL parameters. */
-export type URLParams = ImmutableDictionary<string>;
-/** Type for things that can be converted to named URL parameters. */
-export type PossibleURLParams = PossibleURL | URLSearchParams | ImmutableDictionary<unknown>;
+import type { AbsolutePath, Path } from "./path.js";
+import type { URI } from "./uri.js";
+/**
+ * A URL string has a protocol and a `//`.
+ * - The `//` at the start of a URL indicates that it has a hierarchical path component, so this makes it a URL.
+ * - URLs have a concept of "absolute" or "relative" URLs, since they have a path.
+ */
+export type URLString = `${string}://${string}`;
 /**
- * Get a set of entries for a set of possible URL params.
+ * Object that describes a valid URL, e.g. `http://example.com/path/to/resource`
+ * - Improves the builtin Javascript `URL` class to more accurately type its properties.
  *
- * Note: Not as simple as just converting with `Object.fromEntries()`:
- * 1. When `URLSearchParams` contains multiple values for the same key, calling `params.get()` will return the _first_ value.
- * 2. So when converting this to a simple data object, only one value per key can be represented, but it needs to be the _first_ one.
- * 3. Since we're looping through anyway, we also take the time to convert values to strings, so we can accept a wider range of input types.
+ * 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 declare function getURLEntries(input: PossibleURLParams, caller?: AnyCaller): Iterable<DictionaryItem<string>>;
-/** Get a set of params for a URL as a dictionary. */
-export declare function getURLParams(input: PossibleURLParams, caller?: AnyCaller): URLParams;
-/** Get a single named param from a URL. */
-export declare function getURLParam(input: PossibleURLParams, key: string): string | undefined;
-/** Get a single named param from a URL. */
-export declare function requireURLParam(input: PossibleURLParams, key: string, caller?: AnyCaller): string;
+export interface URL extends URI {
+    href: URLString;
+    origin: URLString;
+    pathname: AbsolutePath;
+}
 /**
- * Return a URL with a new param set (or same URL if no changes were made).
- * - Throws `ValueError` if the value could not be converted to a string.
+ * Construct a correctly-typed `URL` object.
+ * - This is a more correctly typed version of the builtin Javascript `URL` constructor.
+ * - Requires a URL string, URL object, or path as input, and optionally a base URL.
+ * - If a path is provided as input, a base URL _must_ also be provided.
+ * - The returned type is
  */
-export declare function withURLParam(url: PossibleURL, key: string, value: unknown, caller?: AnyCaller): URL;
+export interface URLConstructor {
+    new (input: URLString | URL, base?: URLString | URL): URL;
+    new (input: URLString | URL | Path, base: URLString | URL): URL;
+}
+export declare const URL: URLConstructor;
+/** Values that can be converted to a URL instance. */
+export type PossibleURL = string | globalThis.URL;
 /**
- * Return a URL with several new params set (or same URL if no changes were made).
- * - Throws `ValueError` if any of the values could not be converted to strings.
+ * Is an unknown value a URL object?
+ * - Must be a `URL` instance and its origin must start with `scheme://`
  */
-export declare function withURLParams(url: PossibleURL, params: PossibleURLParams, caller?: AnyCaller): URL;
-/** Return a URL without one or more params (or same URL if no changes were made). */
-export declare function omitURLParams(url: PossibleURL, ...keys: string[]): URL;
-/** Return a URL without a param (or same URL if no changes were made). */
-export declare const omitURLParam: (url: PossibleURL, key: string) => URL;
+export declare function isURL(value: unknown): value is URL;
+/** Assert that an unknown value is a URL object. */
+export declare function assertURL(value: unknown, caller?: AnyCaller): asserts value is URL;
+/** Convert a possible URL to a URL, or return `undefined` if conversion fails. */
+export declare function getURL(possible: Nullish<PossibleURL>, base?: PossibleURL | undefined): URL | undefined;
+/** Convert a possible URL to a URL, or throw `RequiredError` if conversion fails. */
+export declare function requireURL(possible: PossibleURL, base?: PossibleURL | undefined, caller?: AnyCaller): URL;