shelving 1.138.0 → 1.139.1

package/util/format.js

@@ -0,0 +1,113 @@
+import { isArray } from "./array.js";
+import { NNBSP } from "./constants.js";
+import { isDate, requireDate } from "./date.js";
+import { getPercent } from "./number.js";
+import { isObject } from "./object.js";
+import { requireTime } from "./time.js";
+import { requireURL } from "./url.js";
+/** Format a number range (based on the user's browser language settings). */
+export function formatRange(min, max, options) {
+    return `${formatNumber(min, options)}${NNBSP}–${NNBSP}${formatNumber(max, options)}`;
+}
+/** Format a number with a short suffix, e.g. `1,000 kg` */
+export function formatQuantity(num, suffix, options) {
+    const o = { unitDisplay: "short", ...options, style: "decimal" };
+    const str = formatNumber(num, o);
+    const sep = o.unitDisplay === "narrow" ? "" : NNBSP;
+    return `${str}${sep}${suffix}`;
+}
+/** Format a number (based on the user's browser language settings). */
+export function formatNumber(num, options) {
+    if (!Number.isFinite(num))
+        return Number.isNaN(num) ? "-" : "∞";
+    return new Intl.NumberFormat(undefined, options).format(num).replace(/ /, NNBSP);
+}
+/** Format a number with a longer full-word suffix. */
+export function pluralizeQuantity(num, singular, plural, options) {
+    const o = { ...options, style: "decimal" };
+    const qty = formatNumber(num, o);
+    return `${qty}${NNBSP}${num === 1 ? singular : plural}`;
+}
+/**
+ * Format a percentage (combines `getPercent()` and `formatQuantity()` for convenience).
+ * - Defaults to showing no decimal places.
+ * - Defaults to rounding closer to zero (so that 99.99% is shown as 99%).
+ *
+ * @param numerator Number representing the amount of progress.
+ * @param denumerator The number representing the whole amount.
+ */
+export function formatPercent(numerator, denumerator, options) {
+    const fullOptions = { style: "percent", maximumFractionDigits: 0, roundingMode: "trunc", ...options };
+    return formatNumber(getPercent(numerator, denumerator), fullOptions);
+}
+/**
+ * Format an unknown object as a string.
+ * - Use the custom `.toString()` function if it exists (don't use built in `Object.prototype.toString` because it's useless.
+ * - Use `.title` or `.name` or `.id` if they exist and are strings.
+ * - Use `Object` otherwise.
+ */
+export function formatObject(obj) {
+    if (typeof obj.toString === "function" && obj.toString !== Object.prototype.toString)
+        return obj.toString();
+    const name = obj.name;
+    if (typeof name === "string")
+        return name;
+    const title = obj.title;
+    if (typeof title === "string")
+        return title;
+    const id = obj.id;
+    if (typeof id === "string")
+        return id;
+    return "Object";
+}
+/** Format an unknown array as a string. */
+export function formatArray(arr, separator = ", ") {
+    return arr.map(formatValue).join(separator);
+}
+/** Format a date in the browser locale. */
+export function formatDate(date) {
+    return requireDate(date, formatDate).toLocaleDateString();
+}
+/** Format a time as a string based on the browser locale settings. */
+export function formatTime(time, precision = 2) {
+    return requireTime(time, formatTime).format(precision);
+}
+/** 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 : ""}`;
+}
+/**
+ * Convert any unknown value into a friendly string for user-facing use.
+ * - Strings return the string.
+ * - Booleans return `"Yes"` or `"No"`
+ * - Numbers return formatted number with commas etc (e.g. `formatNumber()`).
+ * - Dates return formatted date (e.g. `formatDate()`).
+ * - Arrays return the array items converted to string (with `toTitle()`), and joined with a comma.
+ * - Objects return...
+ *   1. `object.name` if it exists, or
+ *   2. `object.title` if it exists.
+ * - Falsy values like `null` and `undefined` return `"None"`
+ * - Everything else returns `"Unknown"`
+ */
+export function formatValue(value) {
+    if (value === null || value === undefined)
+        return "None";
+    if (typeof value === "boolean")
+        return value ? "Yes" : "No";
+    if (typeof value === "string")
+        return value || "None";
+    if (typeof value === "number")
+        return formatNumber(value);
+    if (typeof value === "symbol")
+        return value.description || "Symbol";
+    if (typeof value === "function")
+        return "Function";
+    if (isDate(value))
+        return formatDate(value);
+    if (isArray(value))
+        return formatArray(value);
+    if (isObject(value))
+        return formatObject(value);
+    return "Unknown";
+}

package/util/function.js

@@ -1,4 +1,4 @@
-import { AssertionError } from "../error/AssertionError.js";
+import { RequiredError } from "../error/RequiredError.js";
 /** Is a value a function? */
 export function isFunction(value) {
     return typeof value === "function";
@@ -6,7 +6,7 @@ export function isFunction(value) {
 /** Assert that a value is a function. */
 export function assertFunction(value) {
     if (typeof value !== "function")
-        throw new AssertionError("Must be function", { received: value, caller: assertFunction });
+        throw new RequiredError("Must be function", { received: value, caller: assertFunction });
 }
 /** Function that just passes through the first argument. */
 export function PASSTHROUGH(value) {

package/util/index.d.ts

@@ -8,6 +8,7 @@ export * from "./callback.js";
 export * from "./class.js";
 export * from "./color.js";
 export * from "./constants.js";
+export * from "./crypto.js";
 export * from "./data.js";
 export * from "./date.js";
 export * from "./debug.js";
@@ -21,6 +22,7 @@ export * from "./error.js";
 export * from "./file.js";
 export * from "./filter.js";
 export * from "./focus.js";
+export * from "./format.js";
 export * from "./function.js";
 export * from "./hash.js";
 export * from "./hydrate.js";

package/util/index.js

@@ -8,6 +8,7 @@ export * from "./callback.js";
 export * from "./class.js";
 export * from "./color.js";
 export * from "./constants.js";
+export * from "./crypto.js";
 export * from "./data.js";
 export * from "./date.js";
 export * from "./debug.js";
@@ -21,6 +22,7 @@ export * from "./error.js";
 export * from "./file.js";
 export * from "./filter.js";
 export * from "./focus.js";
+export * from "./format.js";
 export * from "./function.js";
 export * from "./hash.js";
 export * from "./hydrate.js";

package/util/iterate.d.ts

@@ -1,4 +1,3 @@
-import { type PossibleArray } from "./array.js";
 /** Is an unknown value an iterable? */
 export declare const isIterable: (value: unknown) => value is Iterable<unknown>;
 /** An iterable containing items or nested iterables of items. */
@@ -10,8 +9,6 @@ export declare function flattenItems<T>(items: DeepIterable<T>): Iterable<T>;
  * - Checks `items.size` or `items.length` first, or consumes the iterable and counts its iterations.
  */
 export declare function hasItems(items: Iterable<unknown>): boolean;
-/** Is an unknown value one of the values of an iterable? */
-export declare function isItem<T>(items: Iterable<T>, value: unknown): value is T;
 /** Count the number of items in an iterable. */
 export declare function countItems(items: Iterable<unknown>): number;
 /**
@@ -37,15 +34,3 @@ export declare function reduceItems<I, O>(items: Iterable<I>, reducer: (previous
 export declare function getChunks<T>(items: Iterable<T>, size: number): Iterable<readonly T[]>;
 /** Merge two or more iterables into a single iterable set. */
 export declare function mergeItems<T>(...inputs: [Iterable<T>, Iterable<T>, ...Iterable<T>[]]): Iterable<T>;
-/** Get the first item from an array or iterable, or `undefined` if it didn't exist. */
-export declare function getFirstItem<T>(items: PossibleArray<T>): T | undefined;
-/** Get the first item from an array or iterable. */
-export declare function requireFirstItem<T>(items: PossibleArray<T>): T;
-/** Get the last item from an array or iterable, or `undefined` if it didn't exist. */
-export declare function getLastItem<T>(items: PossibleArray<T>): T | undefined;
-/** Get the last item from an array or iterable. */
-export declare function requireLastItem<T>(items: PossibleArray<T>): T;
-/** Get the next item in an array or iterable. */
-export declare function getNextItem<T>(items: PossibleArray<T>, value: T): T | undefined;
-/** Get the previous item in an array or iterable. */
-export declare function getPrevItem<T>(items: PossibleArray<T>, value: T): T | undefined;

package/util/iterate.js

@@ -1,5 +1,3 @@
-import { RequiredError } from "../error/RequiredError.js";
-import { getArray } from "./array.js";
 /** Is an unknown value an iterable? */
 export const isIterable = (value) => typeof value === "object" && !!value && Symbol.iterator in value;
 /** Flatten one or more iterables. */
@@ -19,13 +17,6 @@ export function hasItems(items) {
         return true;
     return false;
 }
-/** Is an unknown value one of the values of an iterable? */
-export function isItem(items, value) {
-    for (const item of items)
-        if (value === item)
-            return true;
-    return false;
-}
 /** Count the number of items in an iterable. */
 export function countItems(items) {
     let count = 0;
@@ -96,49 +87,3 @@ export function* mergeItems(...inputs) {
     for (const input of inputs)
         yield* input;
 }
-/** Get the first item from an array or iterable, or `undefined` if it didn't exist. */
-export function getFirstItem(items) {
-    const array = getArray(items);
-    return 0 in array ? array[0] : undefined;
-}
-/** Get the first item from an array or iterable. */
-export function requireFirstItem(items) {
-    const item = getFirstItem(items);
-    if (item === undefined)
-        throw new RequiredError("First item is required", { items: items, caller: requireFirstItem });
-    return item;
-}
-/** Get the last item from an array or iterable, or `undefined` if it didn't exist. */
-export function getLastItem(items) {
-    const arr = getArray(items);
-    const j = arr.length - 1;
-    if (j in arr)
-        return arr[j];
-}
-/** Get the last item from an array or iterable. */
-export function requireLastItem(items) {
-    const item = getLastItem(items);
-    if (item === undefined)
-        throw new RequiredError("Last item is required", { items, caller: requireLastItem });
-    return item;
-}
-/** Get the next item in an array or iterable. */
-export function getNextItem(items, value) {
-    const arr = getArray(items);
-    const i = arr.indexOf(value);
-    if (i >= 0) {
-        const j = i + 1;
-        if (j in arr)
-            return arr[j];
-    }
-}
-/** Get the previous item in an array or iterable. */
-export function getPrevItem(items, value) {
-    const arr = getArray(items);
-    const i = arr.indexOf(value);
-    if (i >= 1) {
-        const j = i - 1;
-        if (j in arr)
-            return arr[j];
-    }
-}

package/util/jwt.d.ts

@@ -1,3 +1,4 @@
+import { type PossibleBytes } from "./bytes.js";
 import type { Data } from "./data.js";
 import type { AnyFunction } from "./function.js";
 /**
@@ -6,7 +7,7 @@ import type { AnyFunction } from "./function.js";
  *
  * @throws ValueError If the input parameters, e.g. `secret` or `issuer`, are invalid.
  */
-export declare function encodeToken(claims: Data, secret: string): Promise<string>;
+export declare function encodeToken(claims: Data, secret: PossibleBytes): Promise<string>;
 /** Parts that make up a JSON Web Token. */
 export type TokenData = {
     header: string;
@@ -14,6 +15,7 @@ export type TokenData = {
     signature: string;
     headerData: Data;
     payloadData: Data;
+    signatureBytes: Uint8Array;
 };
 /**
  * Split a JSON Web Token into its header, payload, and signature, and decode and parse the JSON.
@@ -28,4 +30,4 @@ export declare function _splitToken(caller: AnyFunction, token: unknown): TokenD
  * @throws RequestError If the token is invalid or malformed.
  * @throws UnauthorizedError If the token signature is incorrect, token is expired or not issued yet.
  */
-export declare function verifyToken(token: unknown, secret: string): Promise<Data>;
+export declare function verifyToken(token: unknown, secret: PossibleBytes): Promise<Data>;

package/util/jwt.js

@@ -1,14 +1,23 @@
 import { RequestError, UnauthorizedError } from "../error/RequestError.js";
 import { ValueError } from "../error/ValueError.js";
-import { decodeBase64UrlBytes, decodeBase64UrlString, encodeBase64Url } from "./base64.js";
-import { requireBytes } from "./bytes.js";
+import { decodeBase64URLBytes, decodeBase64URLString, encodeBase64URL } from "./base64.js";
+import { getBytes, requireBytes } from "./bytes.js";
 import { DAY } from "./constants.js";
 // Constants.
-const TOKEN_HEADER = { alg: "HS512", typ: "JWT" };
-const TOKEN_EXPIRY_MS = DAY * 10;
-const TOKEN_MINIMUM_SECRET = 16;
-function _getKey(secret, ...usages) {
-    return crypto.subtle.importKey("raw", requireBytes(secret), { name: "HMAC", hash: { name: "SHA-512" } }, false, usages);
+const HASH = "SHA-512";
+const ALGORITHM = { name: "HMAC", hash: HASH };
+const HEADER = { alg: "HS512", typ: "JWT" };
+const EXPIRY_MS = DAY * 10;
+const SKEW_MS = 60; // Allow 1 minute clock skew.
+const SECRET_BYTES = 64; // Minimum 64 bytes / 512 bits
+function _getKey(caller, secret, ...usages) {
+    const bytes = getBytes(secret);
+    if (!bytes || bytes.length < SECRET_BYTES)
+        throw new ValueError(`JWT secret must be byte sequence with mininum ${SECRET_BYTES} bytes`, {
+            received: secret,
+            caller,
+        });
+    return crypto.subtle.importKey("raw", requireBytes(secret), ALGORITHM, false, usages);
 }
 /**
  * Encode a JWT and return the string token.
@@ -17,20 +26,15 @@ function _getKey(secret, ...usages) {
  * @throws ValueError If the input parameters, e.g. `secret` or `issuer`, are invalid.
  */
 export async function encodeToken(claims, secret) {
-    if (typeof secret !== "string" || secret.length < TOKEN_MINIMUM_SECRET)
-        throw new ValueError(`JWT secret must be string with minimum ${TOKEN_MINIMUM_SECRET} characters`, {
-            received: secret,
-            caller: encodeToken,
-        });
     // Encode header.
-    const header = encodeBase64Url(JSON.stringify(TOKEN_HEADER));
+    const header = encodeBase64URL(JSON.stringify(HEADER));
     // Encode payload.
-    const iat = Math.floor(Date.now() / 1000);
-    const exp = Math.floor(iat + TOKEN_EXPIRY_MS / 1000);
-    const payload = encodeBase64Url(JSON.stringify({ iat, exp, ...claims }));
+    const now = Math.floor(Date.now() / 1000);
+    const exp = Math.floor(now + EXPIRY_MS / 1000);
+    const payload = encodeBase64URL(JSON.stringify({ nbf: now, iat: now, exp, ...claims }));
     // Create signature.
-    const key = await _getKey(secret, "sign");
-    const signature = encodeBase64Url(await crypto.subtle.sign("HMAC", key, requireBytes(`${header}.${payload}`)));
+    const key = await _getKey(encodeToken, secret, "sign");
+    const signature = encodeBase64URL(await crypto.subtle.sign("HMAC", key, requireBytes(`${header}.${payload}`)));
     // Combine token.
     return `${header}.${payload}.${signature}`;
 }
@@ -47,23 +51,31 @@ export function _splitToken(caller, token) {
     const [header, payload, signature] = token.split(".");
     if (!header || !payload || !signature)
         throw new RequestError("JWT token must have header, payload, and signature", { received: token, caller });
+    // Decode signature.
+    let signatureBytes;
+    try {
+        signatureBytes = decodeBase64URLBytes(signature);
+    }
+    catch (cause) {
+        throw new RequestError("JWT token signature must be Base64URL encoded", { received: signature, cause, caller });
+    }
     // Decode header.
     let headerData;
     try {
-        headerData = JSON.parse(decodeBase64UrlString(header));
+        headerData = JSON.parse(decodeBase64URLString(header));
     }
-    catch {
-        throw new RequestError("JWT token header must be base64Url encoded JSON", { received: token, caller });
+    catch (cause) {
+        throw new RequestError("JWT token header must be Base64URL encoded JSON", { received: header, cause, caller });
     }
     // Decode payload.
     let payloadData;
     try {
-        payloadData = JSON.parse(decodeBase64UrlString(payload));
+        payloadData = JSON.parse(decodeBase64URLString(payload));
     }
-    catch {
-        throw new RequestError("JWT token payload must be base64Url encoded JSON", { received: token, caller });
+    catch (cause) {
+        throw new RequestError("JWT token payload must be Base64URL encoded JSON", { received: payload, cause, caller });
     }
-    return { header, payload, headerData, payloadData, signature };
+    return { header, payload, signature, headerData, payloadData, signatureBytes };
 }
 /**
  * Decode a JWT, verify it, and return the full payload data.
@@ -74,28 +86,25 @@ export function _splitToken(caller, token) {
  * @throws UnauthorizedError If the token signature is incorrect, token is expired or not issued yet.
  */
 export async function verifyToken(token, secret) {
-    if (typeof secret !== "string" || secret.length < TOKEN_MINIMUM_SECRET)
-        throw new ValueError(`JWT secret must be string with minimum ${TOKEN_MINIMUM_SECRET} characters`, {
-            received: secret,
-            caller: verifyToken,
-        });
     const { header, payload, signature, headerData, payloadData } = _splitToken(verifyToken, token);
     // Validate header.
-    if (headerData.typ !== TOKEN_HEADER.typ)
-        throw new RequestError(`JWT header type must be \"${TOKEN_HEADER.typ}\"`, { received: headerData.typ, caller: verifyToken });
-    if (headerData.alg !== TOKEN_HEADER.alg)
-        throw new RequestError(`JWT header algorithm must be \"${TOKEN_HEADER.alg}\"`, { received: headerData.alg, caller: verifyToken });
+    if (headerData.typ !== HEADER.typ)
+        throw new RequestError(`JWT header type must be \"${HEADER.typ}\"`, { received: headerData.typ, caller: verifyToken });
+    if (headerData.alg !== HEADER.alg)
+        throw new RequestError(`JWT header algorithm must be \"${HEADER.alg}\"`, { received: headerData.alg, caller: verifyToken });
     // Validate signature.
-    const key = await _getKey(secret, "verify");
-    const isValid = await crypto.subtle.verify("HMAC", key, decodeBase64UrlBytes(signature), requireBytes(`${header}.${payload}`));
+    const key = await _getKey(verifyToken, secret, "verify");
+    const isValid = await crypto.subtle.verify("HMAC", key, decodeBase64URLBytes(signature), requireBytes(`${header}.${payload}`));
     if (!isValid)
         throw new UnauthorizedError("JWT signature does not match", { received: token, caller: verifyToken });
     // Validate payload.
-    const { iat, exp } = payloadData;
+    const { nbf, iat, exp } = payloadData;
     const now = Math.floor(Date.now() / 1000);
-    if (typeof iat === "number" && iat > now)
-        throw new UnauthorizedError("JWT not issued yet", { received: iat, caller: verifyToken });
-    if (typeof exp === "number" && exp < now)
-        throw new UnauthorizedError("JWT has expired", { received: exp, caller: verifyToken });
+    if (typeof nbf === "number" && nbf < now - SKEW_MS)
+        throw new UnauthorizedError("JWT cannot be used yet", { received: payloadData, expected: now, caller: verifyToken });
+    if (typeof iat === "number" && iat > now + SKEW_MS)
+        throw new UnauthorizedError("JWT not issued yet", { received: payloadData, expected: now, caller: verifyToken });
+    if (typeof exp === "number" && exp < now - SKEW_MS)
+        throw new UnauthorizedError("JWT has expired", { received: payloadData, expected: now, caller: verifyToken });
     return payloadData;
 }

package/util/link.d.ts

@@ -1,3 +1,4 @@
+import type { AnyCaller } from "../error/BaseError.js";
 import type { ImmutableArray } from "./array.js";
 import type { Optional } from "./optional.js";
 import type { Path } from "./path.js";
@@ -43,13 +44,28 @@ export type LinkHosts = ImmutableArray<string>;
 export type AbsoluteLinkURL = URL & {
     href: AbsoluteLink;
 };
-/** Is an unknown value a URL object with an absolute path component? */
-export declare function isLinkURL(value: unknown): value is AbsoluteLinkURL;
-/** Convert a possible URL to a URL or return `undefined` if conversion fails. */
-export declare function getLinkURL(possible: Optional<PossibleURL>, base?: AbsoluteLinkURL | AbsoluteLink, schemes?: LinkSchemes, hosts?: LinkHosts): AbsoluteLinkURL | undefined;
-/** Convert a possible URL to a URL or return `undefined` if conversion fails. */
-export declare function requireLinkURL(possible: PossibleURL, base?: AbsoluteLinkURL | AbsoluteLink, schemes?: LinkSchemes, hosts?: LinkHosts): AbsoluteLinkURL;
-/** Convert a possible URL to a absolute URL string or return `undefined` if conversion fails. */
-export declare function getLink(possible: Optional<PossibleURL>, base?: AbsoluteLinkURL | AbsoluteLink, schemes?: LinkSchemes, hosts?: LinkHosts): AbsoluteLink | undefined;
-/** Convert a possible URL to an absolute URL string. */
-export declare function requireLink(possible: PossibleURL, base?: AbsoluteLinkURL | AbsoluteLink, schemes?: LinkSchemes, hosts?: LinkHosts): AbsoluteLink;
+/**
+ * Is an unknown value a link URL?
+ * - A valid link URL is a `URL` instance with a scheme matching the `schemes` array, and `host` matching the optional `hosts` array.
+ */
+export declare function isLinkURL(value: unknown, schemes?: LinkSchemes, hosts?: LinkHosts): value is AbsoluteLinkURL;
+/**
+ * Convert a possible URL to a link URL, or return `undefined` if conversion fails.
+ * - A valid link URL is a `URL` instance with a scheme matching the `schemes` array, and `host` matching the optional `hosts` array.
+ */
+export declare function getLinkURL(value: Optional<PossibleURL>, base?: AbsoluteLinkURL | AbsoluteLink, schemes?: LinkSchemes, hosts?: LinkHosts): AbsoluteLinkURL | undefined;
+/**
+ * Convert a possible URL to a link URL, or throw `RequiredError` if conversion fails.
+ * - A valid link URL is a `URL` instance with a scheme matching the `schemes` array, and `host` matching the optional `hosts` array.
+ */
+export declare function requireLinkURL(value: PossibleURL, base?: AbsoluteLinkURL | AbsoluteLink, schemes?: LinkSchemes, hosts?: LinkHosts, caller?: AnyCaller): AbsoluteLinkURL;
+/**
+ * Convert a possible URL to an link URL string, or return `undefined` if conversion fails.
+ * - A valid link URL string is an absolute URL string with a scheme matching the `schemes` array, and `host` matching the optional `hosts` array.
+ */
+export declare function getLink(value: Optional<PossibleURL>, base?: AbsoluteLinkURL | AbsoluteLink, schemes?: LinkSchemes, hosts?: LinkHosts): AbsoluteLink | undefined;
+/**
+ * Convert a possible URL to an link URL string, or throw `RequiredError` if conversion fails.
+ * - A valid link URL string is an absolute URL string with a scheme matching the `schemes` array, and `host` matching the optional `hosts` array.
+ */
+export declare function requireLink(value: PossibleURL, base?: AbsoluteLinkURL | AbsoluteLink, schemes?: LinkSchemes, hosts?: LinkHosts, caller?: AnyCaller): AbsoluteLink;

package/util/link.js

@@ -1,31 +1,44 @@
-import { ValueError } from "../error/ValueError.js";
-import { getOptionalURL, isURL } from "./url.js";
+import { RequiredError } from "../error/RequiredError.js";
+import { getURL, isURL } from "./url.js";
 /** Default whitelist for URL schemes. */
 const SCHEMES = ["http:", "https:"];
-/** Is an unknown value a URL object with an absolute path component? */
-export function isLinkURL(value) {
-    return isURL(value) && !!value.protocol;
+/**
+ * Is an unknown value a link URL?
+ * - A valid link URL is a `URL` instance with a scheme matching the `schemes` array, and `host` matching the optional `hosts` array.
+ */
+export function isLinkURL(value, schemes = SCHEMES, hosts) {
+    return isURL(value) && schemes.includes(value.protocol) && (!hosts || hosts.includes(value.host));
 }
-/** Convert a possible URL to a URL or return `undefined` if conversion fails. */
-export function getLinkURL(possible, base, schemes = SCHEMES, hosts) {
-    const url = getOptionalURL(possible, base);
-    if (url && schemes.includes(url.protocol) && (!hosts || hosts.includes(url.host)))
+/**
+ * Convert a possible URL to a link URL, or return `undefined` if conversion fails.
+ * - A valid link URL is a `URL` instance with a scheme matching the `schemes` array, and `host` matching the optional `hosts` array.
+ */
+export function getLinkURL(value, base, schemes = SCHEMES, hosts) {
+    const url = getURL(value, base);
+    if (isLinkURL(url, schemes, hosts))
         return url;
 }
-/** Convert a possible URL to a URL or return `undefined` if conversion fails. */
-export function requireLinkURL(possible, base, schemes, hosts) {
-    const url = getLinkURL(possible, base, schemes, hosts);
+/**
+ * Convert a possible URL to a link URL, or throw `RequiredError` if conversion fails.
+ * - A valid link URL is a `URL` instance with a scheme matching the `schemes` array, and `host` matching the optional `hosts` array.
+ */
+export function requireLinkURL(value, base, schemes, hosts, caller = requireLinkURL) {
+    const url = getLinkURL(value, base, schemes, hosts);
     if (!url)
-        throw new ValueError("Invalid link", { received: possible, caller: requireLinkURL });
+        throw new RequiredError("Invalid link", { received: value, base, schemes, hosts, caller });
     return url;
 }
-/** Convert a possible URL to a absolute URL string or return `undefined` if conversion fails. */
-export function getLink(possible, base, schemes = SCHEMES, hosts) {
-    const url = getOptionalURL(possible, base);
-    if (url && schemes.includes(url.protocol) && (!hosts || hosts.includes(url.host)))
-        return url.href;
+/**
+ * Convert a possible URL to an link URL string, or return `undefined` if conversion fails.
+ * - A valid link URL string is an absolute URL string with a scheme matching the `schemes` array, and `host` matching the optional `hosts` array.
+ */
+export function getLink(value, base, schemes = SCHEMES, hosts) {
+    return getLinkURL(value, base, schemes, hosts)?.href;
 }
-/** Convert a possible URL to an absolute URL string. */
-export function requireLink(possible, base, schemes, hosts) {
-    return requireLinkURL(possible, base, schemes, hosts).href;
+/**
+ * Convert a possible URL to an link URL string, or throw `RequiredError` if conversion fails.
+ * - A valid link URL string is an absolute URL string with a scheme matching the `schemes` array, and `host` matching the optional `hosts` array.
+ */
+export function requireLink(value, base, schemes, hosts, caller = requireLink) {
+    return requireLinkURL(value, base, schemes, hosts, caller).href;
 }

package/util/map.d.ts

@@ -1,3 +1,4 @@
+import type { AnyCaller } from "../error/BaseError.js";
 import type { Entry } from "./entry.js";
 /** `Map` that cannot be changed. */
 export type ImmutableMap<K = unknown, T = unknown> = ReadonlyMap<K, T>;
@@ -22,23 +23,23 @@ export type PossibleStringMap<K extends string, T> = PossibleMap<K, T> | {
 /** Is an unknown value a map? */
 export declare function isMap(value: unknown): value is ImmutableMap;
 /** Assert that a value is a `Map` instance. */
-export declare function assertMap(value: unknown): asserts value is ImmutableMap;
-/** Is an unknown value a key for an item in a map? */
-export declare function isMapItem<K, V>(map: ImmutableMap<K, V>, key: unknown): key is K;
-/** Assert that an unknown value is a key for an item in a map. */
-export declare function assertMapItem<K, V>(map: ImmutableMap<K, V>, key: unknown): asserts key is K;
+export declare function assertMap(value: unknown, caller?: AnyCaller): asserts value is ImmutableMap;
 /** Convert an iterable to a `Map` (if it's already a `Map` it passes through unchanged). */
 export declare function getMap<K extends string, T>(input: PossibleStringMap<K, T>): ImmutableMap<K, T>;
 export declare function getMap<K, T>(input: PossibleMap<K, T>): ImmutableMap<K, T>;
 /** Apply a limit to a map. */
 export declare function limitMap<T>(map: ImmutableMap<T>, limit: number): ImmutableMap<T>;
+/** Is an unknown value a key for an item in a map? */
+export declare function isMapItem<K, V>(map: ImmutableMap<K, V>, key: unknown): key is K;
+/** Assert that an unknown value is a key for an item in a map. */
+export declare function assertMapItem<K, V>(map: ImmutableMap<K, V>, key: unknown, caller?: AnyCaller): asserts key is K;
 /** Function that lets new items in a map be created and updated by calling a `reduce()` callback that receives the existing value. */
 export declare function setMapItem<K, T>(map: MutableMap<K, T>, key: K, value: T): T;
 /** Add multiple items to a set (by reference). */
 export declare function setMapItems<K, T>(map: MutableMap<K, T>, items: Iterable<MapItem<ImmutableMap<K, T>>>): void;
 /** Remove multiple items from a set (by reference). */
 export declare function removeMapItems<K, T>(map: MutableMap<K, T>, ...keys: K[]): void;
-/** Get an item in a map, or throw `RequiredError` if it doesn't exist. */
-export declare function requireMapItem<K, T>(map: ImmutableMap<K, T>, key: K): T;
 /** Get an item in a map, or `undefined` if it doesn't exist. */
 export declare function getMapItem<K, T>(map: ImmutableMap<K, T>, key: K): T | undefined;
+/** Get an item in a map, or throw `RequiredError` if it doesn't exist. */
+export declare function requireMapItem<K, T>(map: ImmutableMap<K, T>, key: K, caller?: AnyCaller): T;

package/util/map.js

@@ -1,4 +1,3 @@
-import { AssertionError } from "../error/AssertionError.js";
 import { RequiredError } from "../error/RequiredError.js";
 import { isIterable, limitItems } from "./iterate.js";
 /** Class for a `Map` that cannot be changed (so you can extend `Map` while implementing `ImmutableMap`). */
@@ -8,18 +7,9 @@ export function isMap(value) {
     return value instanceof Map;
 }
 /** Assert that a value is a `Map` instance. */
-export function assertMap(value) {
+export function assertMap(value, caller = assertMap) {
     if (!isMap(value))
-        throw new AssertionError("Must be map", { received: value, caller: assertMap });
-}
-/** Is an unknown value a key for an item in a map? */
-export function isMapItem(map, key) {
-    return map.has(key);
-}
-/** Assert that an unknown value is a key for an item in a map. */
-export function assertMapItem(map, key) {
-    if (!isMapItem(map, key))
-        throw new AssertionError("Key must exist in map", { key, map, caller: assertMapItem });
+        throw new RequiredError("Must be map", { received: value, caller });
 }
 export function getMap(input) {
     return isMap(input) ? input : new Map(isIterable(input) ? input : Object.entries(input));
@@ -28,6 +18,15 @@ export function getMap(input) {
 export function limitMap(map, limit) {
     return limit > map.size ? map : new Map(limitItems(map, limit));
 }
+/** Is an unknown value a key for an item in a map? */
+export function isMapItem(map, key) {
+    return map.has(key);
+}
+/** Assert that an unknown value is a key for an item in a map. */
+export function assertMapItem(map, key, caller = assertMapItem) {
+    if (!isMapItem(map, key))
+        throw new RequiredError("Key must exist in map", { key, map, caller });
+}
 /** Function that lets new items in a map be created and updated by calling a `reduce()` callback that receives the existing value. */
 export function setMapItem(map, key, value) {
     map.set(key, value);
@@ -43,13 +42,13 @@ export function removeMapItems(map, ...keys) {
     for (const key of keys)
         map.delete(key);
 }
-/** Get an item in a map, or throw `RequiredError` if it doesn't exist. */
-export function requireMapItem(map, key) {
-    if (!map.has(key))
-        throw new RequiredError("Key must exist in map", { key, map, caller: requireMapItem });
-    return map.get(key);
-}
 /** Get an item in a map, or `undefined` if it doesn't exist. */
 export function getMapItem(map, key) {
     return map.get(key);
 }
+/** Get an item in a map, or throw `RequiredError` if it doesn't exist. */
+export function requireMapItem(map, key, caller = requireMapItem) {
+    if (!map.has(key))
+        throw new RequiredError("Key must exist in map", { key, map, caller });
+    return map.get(key);
+}