shelving 1.236.0 → 1.236.2

package/util/filter.js

@@ -1,17 +1,45 @@
-/** Filter an iterable set of items using a matcher. */
+/**
+ * Filter an iterable set of items using a matcher.
+ *
+ * @param items Iterable of items to filter.
+ * @param match Matcher called with each item (plus any extra `args`); items it returns `true` for are kept.
+ * @param args Extra arguments passed to `match` after each item.
+ * @returns Iterable yielding only the items the matcher returned `true` for.
+ * @example Array.from(filterItems([1, 2, 3], n => n > 1)) // [2, 3]
+ * @see https://dhoulb.github.io/shelving/util/filter/filterItems
+ */
 export function* filterItems(items, match, ...args) {
     for (const item of items)
         if (match(item, ...args))
             yield item;
 }
-/** Filter an array (immutably) using a matcher. */
+/**
+ * Filter an array (immutably) using a matcher.
+ * - Returns the exact same array instance if no items were removed (for referential stability).
+ *
+ * @param input Array of items to filter.
+ * @param match Matcher called with each item (plus any extra `args`); items it returns `true` for are kept.
+ * @param args Extra arguments passed to `match` after each item.
+ * @returns A filtered array, or the same `input` instance if nothing was removed.
+ * @example filterArray([1, 2, 3], n => n > 1) // [2, 3]
+ * @see https://dhoulb.github.io/shelving/util/filter/filterArray
+ */
 export function filterArray(input, match, ...args) {
     if (!input.length)
         return input;
     const output = Array.from(filterItems(input, match, ...args));
     return output.length === input.length ? input : output;
 }
-/** Filter a sequence of values using a matcher. */
+/**
+ * Filter a sequence of values using a matcher.
+ *
+ * @param sequence Async iterable of items to filter.
+ * @param match Matcher called with each item (plus any extra `args`); items it returns `true` for are kept.
+ * @param args Extra arguments passed to `match` after each item.
+ * @returns Async iterable yielding only the items the matcher returned `true` for.
+ * @example for await (const n of filterSequence(stream, n => n > 1)) { ... }
+ * @see https://dhoulb.github.io/shelving/util/filter/filterSequence
+ */
 export async function* filterSequence(sequence, match, ...args) {
     for await (const item of sequence)
         if (match(item, ...args))

package/util/focus.d.ts

@@ -1,2 +1,10 @@
-/** Find the first focusable element inside HTML element (including the element itself). */
+/**
+ * Find the first focusable element inside an HTML element (including the element itself).
+ * - An element is focusable if it's an enabled link, button, input, select, or textarea, or has a non-negative `tabindex`.
+ *
+ * @param el The HTML element to search (it is tested first, then its descendants).
+ * @returns The first focusable `HTMLElement`, or `null` if none is found.
+ * @example getFirstFocusable(form) // the first enabled input inside the form
+ * @see https://dhoulb.github.io/shelving/util/focus/getFirstFocusable
+ */
 export declare function getFirstFocusable(el: HTMLElement): HTMLElement | null;

package/util/focus.js

@@ -1,6 +1,14 @@
 /** Selector for elements that can take focus */
 const FOCUSABLE = `a:link, button:enabled, input:enabled, select:enabled, textarea:enabled, [tabindex]:not([tabindex="-1"]):not(:disabled)`;
-/** Find the first focusable element inside HTML element (including the element itself). */
+/**
+ * Find the first focusable element inside an HTML element (including the element itself).
+ * - An element is focusable if it's an enabled link, button, input, select, or textarea, or has a non-negative `tabindex`.
+ *
+ * @param el The HTML element to search (it is tested first, then its descendants).
+ * @returns The first focusable `HTMLElement`, or `null` if none is found.
+ * @example getFirstFocusable(form) // the first enabled input inside the form
+ * @see https://dhoulb.github.io/shelving/util/focus/getFirstFocusable
+ */
 export function getFirstFocusable(el) {
     return el.matches(FOCUSABLE) ? el : el.querySelector(FOCUSABLE);
 }

package/util/format.d.ts

@@ -4,38 +4,84 @@ import type { AnyCaller } from "./function.js";
 import { type ImmutableObject } from "./object.js";
 import { type PossibleURI } from "./uri.js";
 import { type PossibleURL } from "./url.js";
-/** Options that are shared across all formatters. */
+/**
+ * Options that are shared across all formatters.
+ *
+ * @see https://dhoulb.github.io/shelving/util/format/FormatOptions
+ */
 export interface FormatOptions {
-    /** Override the locale for formatting (defaults to detected locale). */
+    /**
+     * Override the locale for formatting (defaults to detected locale).
+     *
+     * @see https://dhoulb.github.io/shelving/util/format/FormatOptions/locale
+     */
     readonly locale?: Intl.Locale | undefined;
 }
-/** Format a boolean as "Yes" or "No". */
+/**
+ * Format a boolean as `"Yes"` or `"No"`.
+ *
+ * @param value Boolean value to format.
+ * @returns `"Yes"` if `value` is `true`, otherwise `"No"`.
+ * @example formatBoolean(true) // "Yes"
+ * @see https://dhoulb.github.io/shelving/util/format/formatBoolean
+ */
 export declare function formatBoolean(value: boolean): string;
-/** Options we use for number formatting. */
+/**
+ * Options we use for number formatting.
+ *
+ * @see https://dhoulb.github.io/shelving/util/format/NumberFormatOptions
+ */
 export interface NumberFormatOptions extends FormatOptions, Omit<Intl.NumberFormatOptions, "style" | "unit" | "unitDisplay" | "currency" | "currencyDisplay" | "currencySign"> {
 }
-/** Format a number (based on the user's browser language settings). */
+/**
+ * Format a number (based on the user's browser language settings).
+ *
+ * @param num Number to format.
+ * @param options Formatting options passed through to `Intl.NumberFormat`.
+ * @returns Locale-formatted number string.
+ * @example formatNumber(1234.5) // "1,234.5"
+ * @see https://dhoulb.github.io/shelving/util/format/formatNumber
+ */
 export declare function formatNumber(num: number, options?: NumberFormatOptions): string;
-/** Format a number range (based on the user's browser language settings). */
+/**
+ * Format a number range (based on the user's browser language settings).
+ *
+ * @param from Number at the start of the range.
+ * @param to Number at the end of the range.
+ * @param options Formatting options passed through to `Intl.NumberFormat`.
+ * @returns Locale-formatted number range string.
+ * @example formatRange(1, 10) // "1–10"
+ * @see https://dhoulb.github.io/shelving/util/format/formatRange
+ */
 export declare function formatRange(from: number, to: number, options?: NumberFormatOptions): string;
-/** Options for quantity formatting. */
+/**
+ * Options for quantity formatting.
+ *
+ * @see https://dhoulb.github.io/shelving/util/format/UnitFormatOptions
+ */
 export interface UnitFormatOptions extends FormatOptions, Omit<Intl.NumberFormatOptions, "style" | "unit" | "currency" | "currencyDisplay" | "currencySign"> {
     /**
      * String for one of this thing, e.g. `product` or `item` or `sheep`
      * - Used for `unitDisplay: "long"` formatting.
      * - Defaults to unit reference, e.g. "minute"
+     *
+     * @see https://dhoulb.github.io/shelving/util/format/UnitFormatOptions/one
      */
     readonly one?: string | undefined;
     /**
      * String for several of this thing, e.g. `products` or `items` or `sheep`
      * - Used for `unitDisplay: "long"` formatting.
      * - Defaults to `one + "s"`
+     *
+     * @see https://dhoulb.github.io/shelving/util/format/UnitFormatOptions/many
      */
     readonly many?: string | undefined;
     /**
      * Abbreviation for this thing, e.g. `products` or `items` or `sheep` (defaults to `one` + "s").
      * - Used for `unitDisplay: "narrow"` formatting.
      * - Defaults to unit reference, e.g. "minute"
+     *
+     * @see https://dhoulb.github.io/shelving/util/format/UnitFormatOptions/abbr
      */
     readonly abbr?: string | undefined;
 }
@@ -46,14 +92,40 @@ export interface UnitFormatOptions extends FormatOptions, Omit<Intl.NumberFormat
  * - Unfortunately the list of supported units changes in different browsers.
  * - Ideally we want to format units using the built-in formatting so things like translation and internationalisation are covered.
  * - But we want provide fallback formatting for unsupported units, and do something _good enough_ job in most cases.
+ *
+ * @param num Quantity to format.
+ * @param unit Unit reference to format the quantity as, e.g. `"minute"` or `"product"`.
+ * @param options Formatting options including custom `one`/`many`/`abbr` strings for unsupported units.
+ * @returns Formatted quantity string, e.g. `"5 minutes"` or `"5 products"`.
+ * @example formatUnit(5, "minute", { unitDisplay: "long" }) // "5 minutes"
+ * @see https://dhoulb.github.io/shelving/util/format/formatUnit
  */
 export declare function formatUnit(num: number, unit: string, options?: UnitFormatOptions): string;
-/** Options we use for currency formatting. */
+/**
+ * Options we use for currency formatting.
+ *
+ * @see https://dhoulb.github.io/shelving/util/format/CurrencyFormatOptions
+ */
 export interface CurrencyFormatOptions extends FormatOptions, Omit<Intl.NumberFormatOptions, "style" | "unit" | "unitDisplay" | "currency"> {
 }
-/** Format a currency amount (based on the user's browser language settings). */
+/**
+ * Format a currency amount (based on the user's browser language settings).
+ *
+ * @param amount Amount of money to format.
+ * @param currency ISO 4217 currency code, e.g. `"USD"` or `"GBP"`.
+ * @param options Formatting options passed through to `Intl.NumberFormat`.
+ * @param caller Function to attribute a thrown error to (defaults to `formatCurrency` itself).
+ * @returns Locale-formatted currency string.
+ * @throws {RequiredError} If `currency` is not a valid currency code.
+ * @example formatCurrency(1234.5, "USD") // "$1,234.50"
+ * @see https://dhoulb.github.io/shelving/util/format/formatCurrency
+ */
 export declare function formatCurrency(amount: number, currency: string, options?: CurrencyFormatOptions, caller?: AnyCaller): string;
-/** Options we use for percent formatting. */
+/**
+ * Options we use for percent formatting.
+ *
+ * @see https://dhoulb.github.io/shelving/util/format/PercentFormatOptions
+ */
 export interface PercentFormatOptions extends FormatOptions, Omit<Intl.NumberFormatOptions, "style" | "unit" | "unitDisplay" | "currency" | "currencyDisplay" | "currencySign"> {
 }
 /**
@@ -64,6 +136,10 @@ export interface PercentFormatOptions extends FormatOptions, Omit<Intl.NumberFor
  *
  * @param numerator Number representing the amount of progress (e.g. `50`).
  * @param denumerator The number representing the whole amount (defaults to 100).
+ * @param options Formatting options passed through to `Intl.NumberFormat`.
+ * @returns Locale-formatted percentage string.
+ * @example formatPercent(50) // "50%"
+ * @see https://dhoulb.github.io/shelving/util/format/formatPercent
  */
 export declare function formatPercent(numerator: number, denumerator?: number, options?: PercentFormatOptions): string;
 /**
@@ -71,32 +147,104 @@ export declare function formatPercent(numerator: number, denumerator?: number, o
  * - 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.
+ *
+ * @param obj Object to format.
+ * @returns Best-available string representation of `obj`, or `"Object"` as a fallback.
+ * @example formatObject({ name: "Dave" }) // "Dave"
+ * @see https://dhoulb.github.io/shelving/util/format/formatObject
  */
 export declare function formatObject(obj: ImmutableObject): string;
+/**
+ * Options for formatting an array as a string with `formatArray()`.
+ *
+ * @see https://dhoulb.github.io/shelving/util/format/ArrayFormatOptions
+ */
 export interface ArrayFormatOptions extends FormatOptions, Intl.ListFormatOptions {
 }
-/** Format an unknown array as a string. */
+/**
+ * Format an unknown array as a string.
+ *
+ * @param arr Array of values to format.
+ * @param options Formatting options passed through to `Intl.ListFormat`.
+ * @param caller Function to attribute a thrown error to (defaults to `formatArray` itself).
+ * @returns Locale-formatted list string with each item converted via `formatValue()`.
+ * @example formatArray(["a", "b", "c"]) // "a, b, and c"
+ * @see https://dhoulb.github.io/shelving/util/format/formatArray
+ */
 export declare function formatArray(arr: ImmutableArray<unknown>, options?: ArrayFormatOptions, caller?: AnyCaller): string;
-/** Options we use for currency formatting. */
+/**
+ * Options we use for date, time, and datetime formatting.
+ *
+ * @see https://dhoulb.github.io/shelving/util/format/DateFormatOptions
+ */
 export interface DateFormatOptions extends Intl.DateTimeFormatOptions {
-    /** Override the locale for formatting (defaults to detected locale). */
+    /**
+     * Override the locale for formatting (defaults to detected locale).
+     *
+     * @see https://dhoulb.github.io/shelving/util/format/DateFormatOptions/locale
+     */
     readonly locale?: Intl.Locale | undefined;
 }
-/** Format a date in the browser locale. */
+/**
+ * Format a date in the browser locale.
+ *
+ * @param date Date to format.
+ * @param options Formatting options passed through to `Date.toLocaleDateString`.
+ * @param caller Function to attribute a thrown error to (defaults to `formatDate` itself).
+ * @returns Locale-formatted date string.
+ * @throws {RequiredError} If `date` cannot be converted to a valid date.
+ * @example formatDate("2025-01-01") // "1/1/2025"
+ * @see https://dhoulb.github.io/shelving/util/format/formatDate
+ */
 export declare function formatDate(date: PossibleDate, options?: DateFormatOptions, caller?: AnyCaller): string;
-/** Format a time in the browser locale (no seconds by default). */
+/**
+ * Format a time in the browser locale (no seconds by default).
+ *
+ * @param time Time to format (defaults to now).
+ * @param options Formatting options passed through to `Date.toLocaleTimeString`.
+ * @param caller Function to attribute a thrown error to (defaults to `formatTime` itself).
+ * @returns Locale-formatted time string.
+ * @throws {RequiredError} If `time` cannot be converted to a valid date.
+ * @example formatTime("2025-01-01T13:30") // "01:30 PM"
+ * @see https://dhoulb.github.io/shelving/util/format/formatTime
+ */
 export declare function formatTime(time?: PossibleDate, options?: DateFormatOptions, caller?: AnyCaller): string;
-/** Format a datetime in the browser locale (no seconds by default). */
+/**
+ * Format a datetime in the browser locale (no seconds by default).
+ *
+ * @param date Date to format.
+ * @param options Formatting options passed through to `Date.toLocaleString`.
+ * @param caller Function to attribute a thrown error to (defaults to `formatDateTime` itself).
+ * @returns Locale-formatted datetime string.
+ * @throws {RequiredError} If `date` cannot be converted to a valid date.
+ * @example formatDateTime("2025-01-01T13:30") // "1/1/2025, 01:30 PM"
+ * @see https://dhoulb.github.io/shelving/util/format/formatDateTime
+ */
 export declare function formatDateTime(date: PossibleDate, options?: DateFormatOptions, caller?: AnyCaller): string;
 /**
- * Format a URI as a user-friendly string
- * e.g. `mailto:dave@shax.com` → `dave@shax.com`
- * e.g. `http://shax.com/test?uid=129483` → `shax.com/test`
+ * Format a URI as a user-friendly string.
+ * - e.g. `mailto:dave@shax.com` → `dave@shax.com`
+ * - e.g. `http://shax.com/test?uid=129483` → `shax.com/test`
+ *
+ * @param url URI to format.
+ * @param caller Function to attribute a thrown error to (defaults to `formatURI` itself).
+ * @returns Friendly string showing the host and path with any trailing slash removed.
+ * @throws {RequiredError} If `url` cannot be converted to a valid URI.
+ * @example formatURI("http://shax.com/test?uid=129483") // "shax.com/test"
+ * @see https://dhoulb.github.io/shelving/util/format/formatURI
  */
 export declare function formatURI(url: PossibleURI, caller?: AnyCaller): string;
 /**
- * Format a URI as a string.
- * e.g. `http://shax.com/test?uid=129483` → `shax.com/test`
+ * Format a URL as a user-friendly string.
+ * - e.g. `http://shax.com/test?uid=129483` → `shax.com/test`
+ *
+ * @param url URL to format.
+ * @param base Base URL to resolve `url` against if it is relative.
+ * @param caller Function to attribute a thrown error to (defaults to `formatURL` itself).
+ * @returns Friendly string showing the host and path with any trailing slash removed.
+ * @throws {RequiredError} If `url` cannot be converted to a valid URL.
+ * @example formatURL("http://shax.com/test?uid=129483") // "shax.com/test"
+ * @see https://dhoulb.github.io/shelving/util/format/formatURL
  */
 export declare function formatURL(url: PossibleURL, base?: PossibleURL, caller?: AnyCaller): string;
 /**
@@ -111,7 +259,23 @@ export declare function formatURL(url: PossibleURL, base?: PossibleURL, caller?:
  *   2. `object.title` if it exists.
  * - Falsy values like `null` and `undefined` return `"None"`
  * - Everything else returns `"Unknown"`
+ *
+ * @param value Unknown value to format.
+ * @param options Formatting options passed through to the underlying formatter.
+ * @param caller Function to attribute a thrown error to (defaults to `formatValue` itself).
+ * @returns User-facing string representation of `value`.
+ * @example formatValue(1234) // "1,234"
+ * @see https://dhoulb.github.io/shelving/util/format/formatValue
  */
 export declare function formatValue(value: unknown, options?: FormatOptions, caller?: AnyCaller): string;
-/** Format a sequence of values. */
+/**
+ * Format a sequence of values.
+ *
+ * @param values Iterable of unknown values to format.
+ * @param options Formatting options passed through to `formatValue()` for each item.
+ * @param caller Function to attribute a thrown error to (defaults to `formatValues` itself).
+ * @returns Iterable yielding the user-facing string for each value.
+ * @example [...formatValues([1234, true])] // ["1,234", "Yes"]
+ * @see https://dhoulb.github.io/shelving/util/format/formatValues
+ */
 export declare function formatValues(values: Iterable<unknown>, options?: FormatOptions, caller?: AnyCaller): Iterable<string>;

package/util/format.js

@@ -5,15 +5,39 @@ import { getPercent } from "./number.js";
 import { isObject } from "./object.js";
 import { isURI, requireURI } from "./uri.js";
 import { requireURL } from "./url.js";
-/** Format a boolean as "Yes" or "No". */
+/**
+ * Format a boolean as `"Yes"` or `"No"`.
+ *
+ * @param value Boolean value to format.
+ * @returns `"Yes"` if `value` is `true`, otherwise `"No"`.
+ * @example formatBoolean(true) // "Yes"
+ * @see https://dhoulb.github.io/shelving/util/format/formatBoolean
+ */
 export function formatBoolean(value) {
     return value ? "Yes" : "No";
 }
-/** Format a number (based on the user's browser language settings). */
+/**
+ * Format a number (based on the user's browser language settings).
+ *
+ * @param num Number to format.
+ * @param options Formatting options passed through to `Intl.NumberFormat`.
+ * @returns Locale-formatted number string.
+ * @example formatNumber(1234.5) // "1,234.5"
+ * @see https://dhoulb.github.io/shelving/util/format/formatNumber
+ */
 export function formatNumber(num, options) {
     return Intl.NumberFormat(options?.locale, options).format(num);
 }
-/** Format a number range (based on the user's browser language settings). */
+/**
+ * Format a number range (based on the user's browser language settings).
+ *
+ * @param from Number at the start of the range.
+ * @param to Number at the end of the range.
+ * @param options Formatting options passed through to `Intl.NumberFormat`.
+ * @returns Locale-formatted number range string.
+ * @example formatRange(1, 10) // "1–10"
+ * @see https://dhoulb.github.io/shelving/util/format/formatRange
+ */
 export function formatRange(from, to, options) {
     return Intl.NumberFormat(options?.locale, options).formatRange(from, to);
 }
@@ -24,6 +48,13 @@ export function formatRange(from, to, options) {
  * - Unfortunately the list of supported units changes in different browsers.
  * - Ideally we want to format units using the built-in formatting so things like translation and internationalisation are covered.
  * - But we want provide fallback formatting for unsupported units, and do something _good enough_ job in most cases.
+ *
+ * @param num Quantity to format.
+ * @param unit Unit reference to format the quantity as, e.g. `"minute"` or `"product"`.
+ * @param options Formatting options including custom `one`/`many`/`abbr` strings for unsupported units.
+ * @returns Formatted quantity string, e.g. `"5 minutes"` or `"5 products"`.
+ * @example formatUnit(5, "minute", { unitDisplay: "long" }) // "5 minutes"
+ * @see https://dhoulb.github.io/shelving/util/format/formatUnit
  */
 export function formatUnit(num, unit, options) {
     // Check if the unit is supported by the browser.
@@ -36,7 +67,18 @@ export function formatUnit(num, unit, options) {
         return `${str} ${str === "1" ? one : many}`;
     return `${str}${unitDisplay === "narrow" ? "" : " "}${abbr}`; // "short" is the default.
 }
-/** Format a currency amount (based on the user's browser language settings). */
+/**
+ * Format a currency amount (based on the user's browser language settings).
+ *
+ * @param amount Amount of money to format.
+ * @param currency ISO 4217 currency code, e.g. `"USD"` or `"GBP"`.
+ * @param options Formatting options passed through to `Intl.NumberFormat`.
+ * @param caller Function to attribute a thrown error to (defaults to `formatCurrency` itself).
+ * @returns Locale-formatted currency string.
+ * @throws {RequiredError} If `currency` is not a valid currency code.
+ * @example formatCurrency(1234.5, "USD") // "$1,234.50"
+ * @see https://dhoulb.github.io/shelving/util/format/formatCurrency
+ */
 export function formatCurrency(amount, currency, options, caller = formatCurrency) {
     return Intl.NumberFormat(options?.locale, {
         style: "currency",
@@ -52,6 +94,10 @@ export function formatCurrency(amount, currency, options, caller = formatCurrenc
  *
  * @param numerator Number representing the amount of progress (e.g. `50`).
  * @param denumerator The number representing the whole amount (defaults to 100).
+ * @param options Formatting options passed through to `Intl.NumberFormat`.
+ * @returns Locale-formatted percentage string.
+ * @example formatPercent(50) // "50%"
+ * @see https://dhoulb.github.io/shelving/util/format/formatPercent
  */
 export function formatPercent(numerator, denumerator, options) {
     return Intl.NumberFormat(options?.locale, {
@@ -66,6 +112,11 @@ export function formatPercent(numerator, denumerator, options) {
  * - 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.
+ *
+ * @param obj Object to format.
+ * @returns Best-available string representation of `obj`, or `"Object"` as a fallback.
+ * @example formatObject({ name: "Dave" }) // "Dave"
+ * @see https://dhoulb.github.io/shelving/util/format/formatObject
  */
 export function formatObject(obj) {
     if (typeof obj.toString === "function" && obj.toString !== Object.prototype.toString)
@@ -81,15 +132,44 @@ export function formatObject(obj) {
         return id;
     return "Object";
 }
-/** Format an unknown array as a string. */
+/**
+ * Format an unknown array as a string.
+ *
+ * @param arr Array of values to format.
+ * @param options Formatting options passed through to `Intl.ListFormat`.
+ * @param caller Function to attribute a thrown error to (defaults to `formatArray` itself).
+ * @returns Locale-formatted list string with each item converted via `formatValue()`.
+ * @example formatArray(["a", "b", "c"]) // "a, b, and c"
+ * @see https://dhoulb.github.io/shelving/util/format/formatArray
+ */
 export function formatArray(arr, options, caller = formatArray) {
     return new Intl.ListFormat(undefined, { style: "long", type: "unit", ...options }).format(formatValues(arr, options, caller));
 }
-/** Format a date in the browser locale. */
+/**
+ * Format a date in the browser locale.
+ *
+ * @param date Date to format.
+ * @param options Formatting options passed through to `Date.toLocaleDateString`.
+ * @param caller Function to attribute a thrown error to (defaults to `formatDate` itself).
+ * @returns Locale-formatted date string.
+ * @throws {RequiredError} If `date` cannot be converted to a valid date.
+ * @example formatDate("2025-01-01") // "1/1/2025"
+ * @see https://dhoulb.github.io/shelving/util/format/formatDate
+ */
 export function formatDate(date, options, caller = formatDate) {
     return requireDate(date, caller).toLocaleDateString(options?.locale, options);
 }
-/** Format a time in the browser locale (no seconds by default). */
+/**
+ * Format a time in the browser locale (no seconds by default).
+ *
+ * @param time Time to format (defaults to now).
+ * @param options Formatting options passed through to `Date.toLocaleTimeString`.
+ * @param caller Function to attribute a thrown error to (defaults to `formatTime` itself).
+ * @returns Locale-formatted time string.
+ * @throws {RequiredError} If `time` cannot be converted to a valid date.
+ * @example formatTime("2025-01-01T13:30") // "01:30 PM"
+ * @see https://dhoulb.github.io/shelving/util/format/formatTime
+ */
 export function formatTime(time, options, caller = formatTime) {
     return requireDate(time, caller).toLocaleTimeString(options?.locale, {
         hour: "2-digit",
@@ -98,7 +178,17 @@ export function formatTime(time, options, caller = formatTime) {
         ...options,
     });
 }
-/** Format a datetime in the browser locale (no seconds by default). */
+/**
+ * Format a datetime in the browser locale (no seconds by default).
+ *
+ * @param date Date to format.
+ * @param options Formatting options passed through to `Date.toLocaleString`.
+ * @param caller Function to attribute a thrown error to (defaults to `formatDateTime` itself).
+ * @returns Locale-formatted datetime string.
+ * @throws {RequiredError} If `date` cannot be converted to a valid date.
+ * @example formatDateTime("2025-01-01T13:30") // "1/1/2025, 01:30 PM"
+ * @see https://dhoulb.github.io/shelving/util/format/formatDateTime
+ */
 export function formatDateTime(date, options, caller = formatDateTime) {
     return requireDate(date, caller).toLocaleString(options?.locale, {
         year: "numeric",
@@ -111,9 +201,16 @@ export function formatDateTime(date, options, caller = formatDateTime) {
     });
 }
 /**
- * Format a URI as a user-friendly string
- * e.g. `mailto:dave@shax.com` → `dave@shax.com`
- * e.g. `http://shax.com/test?uid=129483` → `shax.com/test`
+ * Format a URI as a user-friendly string.
+ * - e.g. `mailto:dave@shax.com` → `dave@shax.com`
+ * - e.g. `http://shax.com/test?uid=129483` → `shax.com/test`
+ *
+ * @param url URI to format.
+ * @param caller Function to attribute a thrown error to (defaults to `formatURI` itself).
+ * @returns Friendly string showing the host and path with any trailing slash removed.
+ * @throws {RequiredError} If `url` cannot be converted to a valid URI.
+ * @example formatURI("http://shax.com/test?uid=129483") // "shax.com/test"
+ * @see https://dhoulb.github.io/shelving/util/format/formatURI
  */
 export function formatURI(url, caller = formatURI) {
     return _formatURI(requireURI(url, caller));
@@ -122,8 +219,16 @@ function _formatURI({ host, pathname }) {
     return `${host}${pathname.endsWith("/") ? pathname.slice(0, -1) : pathname}`;
 }
 /**
- * Format a URI as a string.
- * e.g. `http://shax.com/test?uid=129483` → `shax.com/test`
+ * Format a URL as a user-friendly string.
+ * - e.g. `http://shax.com/test?uid=129483` → `shax.com/test`
+ *
+ * @param url URL to format.
+ * @param base Base URL to resolve `url` against if it is relative.
+ * @param caller Function to attribute a thrown error to (defaults to `formatURL` itself).
+ * @returns Friendly string showing the host and path with any trailing slash removed.
+ * @throws {RequiredError} If `url` cannot be converted to a valid URL.
+ * @example formatURL("http://shax.com/test?uid=129483") // "shax.com/test"
+ * @see https://dhoulb.github.io/shelving/util/format/formatURL
  */
 export function formatURL(url, base, caller = formatURL) {
     return _formatURI(requireURL(url, base, caller));
@@ -140,6 +245,13 @@ export function formatURL(url, base, caller = formatURL) {
  *   2. `object.title` if it exists.
  * - Falsy values like `null` and `undefined` return `"None"`
  * - Everything else returns `"Unknown"`
+ *
+ * @param value Unknown value to format.
+ * @param options Formatting options passed through to the underlying formatter.
+ * @param caller Function to attribute a thrown error to (defaults to `formatValue` itself).
+ * @returns User-facing string representation of `value`.
+ * @example formatValue(1234) // "1,234"
+ * @see https://dhoulb.github.io/shelving/util/format/formatValue
  */
 export function formatValue(value, options, caller = formatValue) {
     if (value === null || value === undefined)
@@ -164,7 +276,16 @@ export function formatValue(value, options, caller = formatValue) {
         return formatURI(value, caller);
     return "Unknown";
 }
-/** Format a sequence of values. */
+/**
+ * Format a sequence of values.
+ *
+ * @param values Iterable of unknown values to format.
+ * @param options Formatting options passed through to `formatValue()` for each item.
+ * @param caller Function to attribute a thrown error to (defaults to `formatValues` itself).
+ * @returns Iterable yielding the user-facing string for each value.
+ * @example [...formatValues([1234, true])] // ["1,234", "Yes"]
+ * @see https://dhoulb.github.io/shelving/util/format/formatValues
+ */
 export function* formatValues(values, options, caller = formatValues) {
     for (const v of values)
         yield formatValue(v, options, caller);