shelving 1.236.0 → 1.236.2

package/util/units.d.ts

@@ -11,14 +11,36 @@ interface UnitProps<T extends string> extends UnitFormatOptions {
     /** Conversions to other units (typically needs at least the base conversion, unless it's already the base unit). */
     readonly to?: Conversions<T>;
 }
-/** Represent a unit. */
+/**
+ * Represent a single unit of measure within a `UnitList`, e.g. `kilometer`.
+ *
+ * - Knows how to convert amounts to/from other units in its list and to format them for display.
+ *
+ * @param list `UnitList` this unit belongs to.
+ * @param key String key for this unit, e.g. `kilometer`.
+ * @param props Props to configure this unit (conversions and formatting options).
+ * @example LENGTH_UNITS.require("kilometer").to(5, "meter") // 5000
+ * @see https://dhoulb.github.io/shelving/util/units/Unit
+ */
 export declare class Unit<K extends string> {
     private readonly _to;
-    /** `UnitList` this unit belongs to. */
+    /**
+     * `UnitList` this unit belongs to.
+     *
+     * @see https://dhoulb.github.io/shelving/util/units/Unit/list
+     */
     readonly list: UnitList<K>;
-    /** String key for this unit, e.g. `kilometer` */
+    /**
+     * String key for this unit, e.g. `kilometer`
+     *
+     * @see https://dhoulb.github.io/shelving/util/units/Unit/key
+     */
     readonly key: K;
-    /** Possible options for formatting these units. */
+    /**
+     * Possible options for formatting these units.
+     *
+     * @see https://dhoulb.github.io/shelving/util/units/Unit/options
+     */
     readonly options: Readonly<UnitFormatOptions> | undefined;
     constructor(
     /** `UnitList` this unit belongs to. */
@@ -27,9 +49,29 @@ export declare class Unit<K extends string> {
     key: K, 
     /** Props to configure this unit. */
     { to, ...options }: UnitProps<K>);
-    /** Convert an amount from this unit to another unit. */
+    /**
+     * Convert an amount from this unit to another unit.
+     *
+     * @param amount The amount in this unit.
+     * @param targetKey Key of the unit to convert to (defaults to the list's base unit).
+     * @returns The amount expressed in the target unit.
+     * @throws `RequiredError` if `targetKey` is not a unit in this list.
+     * @throws `ValueError` if no conversion path exists to the target unit.
+     * @example LENGTH_UNITS.require("kilometer").to(1, "meter") // 1000
+     * @see https://dhoulb.github.io/shelving/util/units/Unit/to
+     */
     to(amount: number, targetKey?: K): number;
-    /** Convert an amount from another unit to this unit. */
+    /**
+     * Convert an amount from another unit to this unit.
+     *
+     * @param amount The amount in the source unit.
+     * @param sourceKey Key of the unit to convert from (defaults to the list's base unit).
+     * @returns The amount expressed in this unit.
+     * @throws `RequiredError` if `sourceKey` is not a unit in this list.
+     * @throws `ValueError` if no conversion path exists from the source unit.
+     * @example LENGTH_UNITS.require("kilometer").from(1000, "meter") // 1
+     * @see https://dhoulb.github.io/shelving/util/units/Unit/from
+     */
     from(amount: number, sourceKey?: K): number;
     /** Convert an amount from this unit to another unit (must specify another `Unit` instance). */
     private _convertTo;
@@ -37,33 +79,86 @@ export declare class Unit<K extends string> {
      * Format an amount with a given unit of measure, e.g. `12 kg` or `29.5 l`
      * - Uses `Intl.NumberFormat` if this is a supported unit (so e.g. `ounce` is translated to e.g. `Unze` in German).
      * - Polyfills unsupported units to use long/short form based on `options.unitDisplay`.
+     *
+     * @param amount The amount to format.
+     * @param options Formatting options merged over this unit's own `options`.
+     * @returns The formatted unit string.
+     * @example MASS_UNITS.require("kilogram").format(12) // "12 kg"
+     * @see https://dhoulb.github.io/shelving/util/units/Unit/format
      */
     format(amount: number, options?: UnitFormatOptions): string;
 }
 /**
- * Represent a list of units.
+ * Represent a list of related units of measure (e.g. all length units).
  * - Has a known base unit at `.base`
  * - Can get required units from `.unit()`
  * - Cannot have additional units added after it is created.
+ *
+ * @param units Set of units keyed by their string key — the first entry becomes the base unit.
+ * @example new UnitList({ meter: {}, kilometer: { to: { meter: 1000 } } }).convert(1, "kilometer", "meter") // 1000
+ * @see https://dhoulb.github.io/shelving/util/units/UnitList
  */
 export declare class UnitList<K extends string> extends ImmutableMap<K, Unit<K>> {
+    /**
+     * Base unit for this list (the first unit added).
+     *
+     * @see https://dhoulb.github.io/shelving/util/units/UnitList/base
+     */
     readonly base: Unit<K>;
     constructor(units: ImmutableObject<K, UnitProps<K>>);
-    /** Convert an amount from a unit to another unit. */
+    /**
+     * Convert an amount from a unit in this list to another unit in this list.
+     *
+     * @param amount The amount in the source unit.
+     * @param sourceKey Key of the unit to convert from.
+     * @param targetKey Key of the unit to convert to.
+     * @returns The amount expressed in the target unit.
+     * @throws `RequiredError` if `sourceKey` or `targetKey` is not a unit in this list.
+     * @throws `ValueError` if no conversion path exists between the units.
+     * @example LENGTH_UNITS.convert(1, "kilometer", "meter") // 1000
+     * @see https://dhoulb.github.io/shelving/util/units/UnitList/convert
+     */
     convert(amount: number, sourceKey: K, targetKey: K): number;
     /**
      * Require a unit from this list.
-     * @throws RequiredError if the unit key is not found.
+     *
+     * @param key Key of the unit to retrieve.
+     * @returns The matching `Unit` instance.
+     * @throws `RequiredError` if the unit key is not found.
+     * @example LENGTH_UNITS.require("kilometer") // Unit instance
+     * @see https://dhoulb.github.io/shelving/util/units/UnitList/require
      */
     require(key: K): Unit<K>;
 }
-/** Percentage units. */
+/**
+ * Percentage units.
+ *
+ * @see https://dhoulb.github.io/shelving/util/units/PERCENT_UNITS
+ */
 export declare const PERCENT_UNITS: UnitList<"percent">;
+/**
+ * String key for a percentage unit.
+ *
+ * @see https://dhoulb.github.io/shelving/util/units/PercentUnitKey
+ */
 export type PercentUnitKey = MapKey<typeof PERCENT_UNITS>;
-/** Point units. */
+/**
+ * Point units.
+ *
+ * @see https://dhoulb.github.io/shelving/util/units/POINT_UNITS
+ */
 export declare const POINT_UNITS: UnitList<"basis-point" | "percentage-point">;
+/**
+ * String key for a point unit.
+ *
+ * @see https://dhoulb.github.io/shelving/util/units/PointUnitKey
+ */
 export type PointUnitKey = MapKey<typeof POINT_UNITS>;
-/** Angle units. */
+/**
+ * Angle units.
+ *
+ * @see https://dhoulb.github.io/shelving/util/units/ANGLE_UNITS
+ */
 export declare const ANGLE_UNITS: UnitList<"degree" | "gradian" | "radian">;
 export type AngleUnitKey = MapKey<typeof ANGLE_UNITS>;
 /** Mass units. */

package/util/units.js

@@ -8,14 +8,36 @@ import { getProps } from "./object.js";
 function _convert(amount, conversion) {
     return typeof conversion === "function" ? conversion(amount) : conversion === 1 ? amount : amount * conversion;
 }
-/** Represent a unit. */
+/**
+ * Represent a single unit of measure within a `UnitList`, e.g. `kilometer`.
+ *
+ * - Knows how to convert amounts to/from other units in its list and to format them for display.
+ *
+ * @param list `UnitList` this unit belongs to.
+ * @param key String key for this unit, e.g. `kilometer`.
+ * @param props Props to configure this unit (conversions and formatting options).
+ * @example LENGTH_UNITS.require("kilometer").to(5, "meter") // 5000
+ * @see https://dhoulb.github.io/shelving/util/units/Unit
+ */
 export class Unit {
     _to;
-    /** `UnitList` this unit belongs to. */
+    /**
+     * `UnitList` this unit belongs to.
+     *
+     * @see https://dhoulb.github.io/shelving/util/units/Unit/list
+     */
     list;
-    /** String key for this unit, e.g. `kilometer` */
+    /**
+     * String key for this unit, e.g. `kilometer`
+     *
+     * @see https://dhoulb.github.io/shelving/util/units/Unit/key
+     */
     key;
-    /** Possible options for formatting these units. */
+    /**
+     * Possible options for formatting these units.
+     *
+     * @see https://dhoulb.github.io/shelving/util/units/Unit/options
+     */
     options;
     constructor(
     /** `UnitList` this unit belongs to. */
@@ -29,12 +51,32 @@ export class Unit {
         this.options = options;
         this._to = to;
     }
-    /** Convert an amount from this unit to another unit. */
+    /**
+     * Convert an amount from this unit to another unit.
+     *
+     * @param amount The amount in this unit.
+     * @param targetKey Key of the unit to convert to (defaults to the list's base unit).
+     * @returns The amount expressed in the target unit.
+     * @throws `RequiredError` if `targetKey` is not a unit in this list.
+     * @throws `ValueError` if no conversion path exists to the target unit.
+     * @example LENGTH_UNITS.require("kilometer").to(1, "meter") // 1000
+     * @see https://dhoulb.github.io/shelving/util/units/Unit/to
+     */
     to(amount, targetKey) {
         const target = targetKey ? _requireUnit(this.to, this.list, targetKey) : this.list.base;
         return this._convertTo(amount, target, this.to);
     }
-    /** Convert an amount from another unit to this unit. */
+    /**
+     * Convert an amount from another unit to this unit.
+     *
+     * @param amount The amount in the source unit.
+     * @param sourceKey Key of the unit to convert from (defaults to the list's base unit).
+     * @returns The amount expressed in this unit.
+     * @throws `RequiredError` if `sourceKey` is not a unit in this list.
+     * @throws `ValueError` if no conversion path exists from the source unit.
+     * @example LENGTH_UNITS.require("kilometer").from(1000, "meter") // 1
+     * @see https://dhoulb.github.io/shelving/util/units/Unit/from
+     */
     from(amount, sourceKey) {
         const source = sourceKey ? _requireUnit(this.from, this.list, sourceKey) : this.list.base;
         return source._convertTo(amount, this, this.from);
@@ -68,18 +110,33 @@ export class Unit {
      * Format an amount with a given unit of measure, e.g. `12 kg` or `29.5 l`
      * - Uses `Intl.NumberFormat` if this is a supported unit (so e.g. `ounce` is translated to e.g. `Unze` in German).
      * - Polyfills unsupported units to use long/short form based on `options.unitDisplay`.
+     *
+     * @param amount The amount to format.
+     * @param options Formatting options merged over this unit's own `options`.
+     * @returns The formatted unit string.
+     * @example MASS_UNITS.require("kilogram").format(12) // "12 kg"
+     * @see https://dhoulb.github.io/shelving/util/units/Unit/format
      */
     format(amount, options) {
         return formatUnit(amount, this.key, { ...this.options, ...options });
     }
 }
 /**
- * Represent a list of units.
+ * Represent a list of related units of measure (e.g. all length units).
  * - Has a known base unit at `.base`
  * - Can get required units from `.unit()`
  * - Cannot have additional units added after it is created.
+ *
+ * @param units Set of units keyed by their string key — the first entry becomes the base unit.
+ * @example new UnitList({ meter: {}, kilometer: { to: { meter: 1000 } } }).convert(1, "kilometer", "meter") // 1000
+ * @see https://dhoulb.github.io/shelving/util/units/UnitList
  */
 export class UnitList extends ImmutableMap {
+    /**
+     * Base unit for this list (the first unit added).
+     *
+     * @see https://dhoulb.github.io/shelving/util/units/UnitList/base
+     */
     base;
     constructor(units) {
         super();
@@ -90,13 +147,29 @@ export class UnitList extends ImmutableMap {
             Map.prototype.set.call(this, id, unit);
         }
     }
-    /** Convert an amount from a unit to another unit. */
+    /**
+     * Convert an amount from a unit in this list to another unit in this list.
+     *
+     * @param amount The amount in the source unit.
+     * @param sourceKey Key of the unit to convert from.
+     * @param targetKey Key of the unit to convert to.
+     * @returns The amount expressed in the target unit.
+     * @throws `RequiredError` if `sourceKey` or `targetKey` is not a unit in this list.
+     * @throws `ValueError` if no conversion path exists between the units.
+     * @example LENGTH_UNITS.convert(1, "kilometer", "meter") // 1000
+     * @see https://dhoulb.github.io/shelving/util/units/UnitList/convert
+     */
     convert(amount, sourceKey, targetKey) {
         return _requireUnit(this.convert, this, sourceKey).to(amount, targetKey);
     }
     /**
      * Require a unit from this list.
-     * @throws RequiredError if the unit key is not found.
+     *
+     * @param key Key of the unit to retrieve.
+     * @returns The matching `Unit` instance.
+     * @throws `RequiredError` if the unit key is not found.
+     * @example LENGTH_UNITS.require("kilometer") // Unit instance
+     * @see https://dhoulb.github.io/shelving/util/units/UnitList/require
      */
     require(key) {
         return _requireUnit(this.require, this, key);
@@ -134,16 +207,28 @@ const MM3_PER_IN3 = MM_PER_IN ** 3;
 const ML_PER_IN3 = MM3_PER_IN3 / 1000;
 const US_IN3_PER_GAL = 231;
 const IMP_ML_PER_GAL = 4546090 / 1000;
-/** Percentage units. */
+/**
+ * Percentage units.
+ *
+ * @see https://dhoulb.github.io/shelving/util/units/PERCENT_UNITS
+ */
 export const PERCENT_UNITS = new UnitList({
     percent: { abbr: "%", many: "percent" },
 });
-/** Point units. */
+/**
+ * Point units.
+ *
+ * @see https://dhoulb.github.io/shelving/util/units/POINT_UNITS
+ */
 export const POINT_UNITS = new UnitList({
     "basis-point": { abbr: "bp" },
     "percentage-point": { abbr: "pp", to: { "basis-point": 100 } },
 });
-/** Angle units. */
+/**
+ * Angle units.
+ *
+ * @see https://dhoulb.github.io/shelving/util/units/ANGLE_UNITS
+ */
 export const ANGLE_UNITS = new UnitList({
     degree: { abbr: "deg" },
     radian: { abbr: "rad", to: { degree: 180 / Math.PI } },

package/util/update.d.ts

@@ -2,10 +2,14 @@ import { type ImmutableArray } from "./array.js";
 import type { BranchData, BranchDataPath, Data, LeafData, LeafDataPath } from "./data.js";
 import type { Segments } from "./string.js";
 /**
- * Set of named updates for a data object.
+ * Set of named updates for a data object, keyed by encoded update syntax.
+ *
+ * - Plain key `a.b` sets a value, `=a.b` sets a leaf value, `+=`/`-=` sum numbers, and `+[]`/`-[]` add/remove array items.
  *
  * Note: string templates infer best when you have fixed character(s) at the start,
  *   so our `Update` syntax always
+ *
+ * @see https://dhoulb.github.io/shelving/util/update/Updates
  */
 export type Updates<T extends Data = Data> = {
     /**
@@ -35,7 +39,13 @@ export type Updates<T extends Data = Data> = {
      */
     readonly [K in LeafDataPath<T> as `+[]${K}` | `-[]${K}`]?: LeafData<T>[K] extends ImmutableArray<unknown> ? LeafData<T>[K] | LeafData<T>[K][number] | undefined : never;
 };
-/** A single update to a keyed property in an object. */
+/**
+ * A single decoded update to a keyed property in an object.
+ *
+ * - Discriminated by `action`: `"set"`, `"with"` (add array items), `"omit"` (remove array items), or `"sum"` (add to a number).
+ *
+ * @see https://dhoulb.github.io/shelving/util/update/Update
+ */
 export type Update = {
     action: "set";
     key: Segments;
@@ -53,7 +63,29 @@ export type Update = {
     key: Segments;
     value: number;
 };
-/** Yield the prop updates in an `Updates` object as a set of `Update` objects. */
+/**
+ * Decode the prop updates in an `Updates` object into a set of `Update` objects.
+ *
+ * - Props with `undefined` value are skipped.
+ *
+ * @param data The `Updates` object to decode.
+ * @returns Array of decoded `Update` objects.
+ * @throws `RequiredError` if a `+=`/`-=` sum update has a non-number value.
+ * @example getUpdates({ "+=count": 1 }) // [{ action: "sum", key: ["count"], value: 1 }]
+ * @see https://dhoulb.github.io/shelving/util/update/getUpdates
+ */
 export declare function getUpdates<T extends Data>(data: Updates<T>): ImmutableArray<Update>;
-/** Update a data object with a set of updates. */
+/**
+ * Return a copy of a data object with a set of updates applied.
+ *
+ * - Returns the original reference unchanged when no update changed a value.
+ * - Supports nested paths, sum/increment, and array add/remove updates via the encoded `Updates` syntax.
+ *
+ * @param data The data object to update.
+ * @param updates The set of updates to apply.
+ * @returns The updated data object (or the original reference if nothing changed).
+ * @throws `RequiredError` if a `+=`/`-=` sum update has a non-number value.
+ * @example updateData({ count: 1 }, { "+=count": 2 }) // { count: 3 }
+ * @see https://dhoulb.github.io/shelving/util/update/updateData
+ */
 export declare function updateData<T extends Data>(data: T, updates: Updates<T>): T;

package/util/update.js

@@ -4,7 +4,17 @@ import { reduceItems } from "./iterate.js";
 import { requireNumber } from "./number.js";
 import { getProps, isObject } from "./object.js";
 import { isDefined } from "./undefined.js";
-/** Yield the prop updates in an `Updates` object as a set of `Update` objects. */
+/**
+ * Decode the prop updates in an `Updates` object into a set of `Update` objects.
+ *
+ * - Props with `undefined` value are skipped.
+ *
+ * @param data The `Updates` object to decode.
+ * @returns Array of decoded `Update` objects.
+ * @throws `RequiredError` if a `+=`/`-=` sum update has a non-number value.
+ * @example getUpdates({ "+=count": 1 }) // [{ action: "sum", key: ["count"], value: 1 }]
+ * @see https://dhoulb.github.io/shelving/util/update/getUpdates
+ */
 export function getUpdates(data) {
     return getProps(data).map(_getUpdate).filter(isDefined);
 }
@@ -27,7 +37,19 @@ function _getUpdate([key, value]) {
         return { action: "set", key: splitDataPath(key), value };
     }
 }
-/** Update a data object with a set of updates. */
+/**
+ * Return a copy of a data object with a set of updates applied.
+ *
+ * - Returns the original reference unchanged when no update changed a value.
+ * - Supports nested paths, sum/increment, and array add/remove updates via the encoded `Updates` syntax.
+ *
+ * @param data The data object to update.
+ * @param updates The set of updates to apply.
+ * @returns The updated data object (or the original reference if nothing changed).
+ * @throws `RequiredError` if a `+=`/`-=` sum update has a non-number value.
+ * @example updateData({ count: 1 }, { "+=count": 2 }) // { count: 3 }
+ * @see https://dhoulb.github.io/shelving/util/update/updateData
+ */
 export function updateData(data, updates) {
     return reduceItems(getUpdates(updates), _updateProp, data);
 }

package/util/uri.d.ts

@@ -12,17 +12,39 @@ import type { ImmutableURL, URLString } from "./url.js";
  * - 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.
+ *
+ * @see https://dhoulb.github.io/shelving/util/uri/URIString
  */
 export type URIString = `${string}:${string}`;
+/**
+ * String for the search component of a URI, including the leading `?`
+ *
+ * @see https://dhoulb.github.io/shelving/util/uri/URISearch
+ */
 export type URISearch = `?${string}`;
+/**
+ * String for the hash component of a URI, including the leading `#`
+ *
+ * @see https://dhoulb.github.io/shelving/util/uri/URIHash
+ */
 export type URIHash = `#${string}`;
 /**
  * Construct a correctly-typed `URI` object.
  * - This is a more correctly typed version of the builtin Javascript `URL` constructor.
  * - Takes a URI string or URI object that already encodes a complete URI — no base parameter, so relative inputs are not accepted.
  * - To resolve a relative input against a base, use `getBasedURI()` from `url.ts`.
+ *
+ * @see https://dhoulb.github.io/shelving/util/uri/ImmutableURIConstructor
  */
 export interface ImmutableURIConstructor {
+    /**
+     * Construct an `ImmutableURI` from a complete URI string or URI object.
+     *
+     * @param input URI string or URI object that already encodes a complete URI.
+     * @returns New `ImmutableURI` instance.
+     * @throws {TypeError} If `input` is not a valid complete URI.
+     * @see https://dhoulb.github.io/shelving/util/uri/ImmutableURIConstructor/new
+     */
     new (input: URIString | ImmutableURI): ImmutableURI;
 }
 /**
@@ -35,42 +57,152 @@ export interface ImmutableURIConstructor {
  * - 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.
+ *
+ * @see https://dhoulb.github.io/shelving/util/uri/ImmutableURI
  */
 export interface ImmutableURI extends URL {
+    /**
+     * Hash component of the URI, including the leading `#` (empty string if absent).
+     *
+     * @see https://dhoulb.github.io/shelving/util/uri/ImmutableURI/hash
+     */
     readonly hash: URIHash | ``;
+    /**
+     * Host component of the URI (hostname and port), or empty string for non-hierarchical URIs.
+     *
+     * @see https://dhoulb.github.io/shelving/util/uri/ImmutableURI/host
+     */
     readonly host: string;
+    /**
+     * Hostname component of the URI, or empty string for non-hierarchical URIs.
+     *
+     * @see https://dhoulb.github.io/shelving/util/uri/ImmutableURI/hostname
+     */
     readonly hostname: string;
+    /**
+     * Full URI string.
+     *
+     * @see https://dhoulb.github.io/shelving/util/uri/ImmutableURI/href
+     */
     readonly href: URIString;
+    /**
+     * Origin of the URI, or the string `"null"` for origins that cannot be serialised.
+     *
+     * @see https://dhoulb.github.io/shelving/util/uri/ImmutableURI/origin
+     */
     readonly origin: URIString | `null`;
+    /**
+     * Password component of the URI (empty string if absent).
+     *
+     * @see https://dhoulb.github.io/shelving/util/uri/ImmutableURI/password
+     */
     readonly password: string;
+    /**
+     * Pathname component of the URI.
+     *
+     * @see https://dhoulb.github.io/shelving/util/uri/ImmutableURI/pathname
+     */
     readonly pathname: string;
+    /**
+     * Port component of the URI (empty string if absent).
+     *
+     * @see https://dhoulb.github.io/shelving/util/uri/ImmutableURI/port
+     */
     readonly port: string;
+    /**
+     * Protocol scheme of the URI, including the trailing `:`
+     *
+     * @see https://dhoulb.github.io/shelving/util/uri/ImmutableURI/protocol
+     */
     readonly protocol: URIScheme;
+    /**
+     * Search component of the URI, including the leading `?` (empty string if absent).
+     *
+     * @see https://dhoulb.github.io/shelving/util/uri/ImmutableURI/search
+     */
     readonly search: URISearch | ``;
+    /**
+     * Username component of the URI (empty string if absent).
+     *
+     * @see https://dhoulb.github.io/shelving/util/uri/ImmutableURI/username
+     */
     readonly username: string;
 }
+/**
+ * Correctly-typed `URI` constructor (the builtin `URL` class typed as `ImmutableURIConstructor`).
+ *
+ * @see https://dhoulb.github.io/shelving/util/uri/ImmutableURI
+ */
 export declare const ImmutableURI: ImmutableURIConstructor;
-/** Values that can be converted to an ImmutableURI instance. */
+/**
+ * Values that can be converted to an `ImmutableURI` instance.
+ *
+ * @see https://dhoulb.github.io/shelving/util/uri/PossibleURI
+ */
 export type PossibleURI = string | URL;
-/** Is an unknown value a URI object? */
+/**
+ * Is an unknown value a URI object?
+ *
+ * @param value The value to test.
+ * @returns `true` if `value` is an `ImmutableURI`, narrowing its type.
+ * @example isURI(new URL("http://x.com")) // true
+ * @see https://dhoulb.github.io/shelving/util/uri/isURI
+ */
 export declare function isURI(value: unknown): value is ImmutableURI;
-/** Assert that an unknown value is a URI object. */
+/**
+ * Assert that an unknown value is a URI object.
+ *
+ * @param value The value to assert.
+ * @param caller Function to attribute a thrown error to (defaults to `assertURI` itself).
+ * @throws {RequiredError} If `value` is not a URI object.
+ * @see https://dhoulb.github.io/shelving/util/uri/assertURI
+ */
 export declare function assertURI(value: unknown, caller?: AnyCaller): asserts value is ImmutableURI;
 /**
  * Convert a possible URI to a URI, or return `undefined` if conversion fails.
  * - Only inputs that already encode a complete URI succeed — relative inputs return `undefined`. No implicit fallback to the document or window URL.
  * - To resolve a relative ref against a base, use `getBasedURI()` from `url.ts`.
+ *
+ * @param possible Possible URI value to convert (a nullish value returns `undefined`).
+ * @returns Converted `ImmutableURI`, or `undefined` if conversion fails.
+ * @example getURI("http://shax.com") // URL { … }
+ * @see https://dhoulb.github.io/shelving/util/uri/getURI
  */
 export declare function getURI(possible: Nullish<PossibleURI>): ImmutableURI | undefined;
-/** Convert a possible URI to a URI, or throw `RequiredError` if conversion fails. */
+/**
+ * Convert a possible URI to a URI, or throw `RequiredError` if conversion fails.
+ *
+ * @param possible Possible URI value to convert.
+ * @param caller Function to attribute a thrown error to (defaults to `requireURI` itself).
+ * @returns Converted `ImmutableURI`.
+ * @throws {RequiredError} If `possible` cannot be converted to a valid URI.
+ * @example requireURI("http://shax.com") // URL { … }
+ * @see https://dhoulb.github.io/shelving/util/uri/requireURI
+ */
 export declare function requireURI(possible: PossibleURI, caller?: AnyCaller): ImmutableURI;
-/** Type for a set of named URL parameters. */
+/**
+ * Type for a set of named URI parameters.
+ *
+ * @see https://dhoulb.github.io/shelving/util/uri/URIParams
+ */
 export type URIParams = ImmutableDictionary<string>;
-/** Type for things that can be converted to named URI parameters. */
+/**
+ * Type for things that can be converted to named URI parameters.
+ *
+ * @see https://dhoulb.github.io/shelving/util/uri/PossibleURIParams
+ */
 export type PossibleURIParams = PossibleURI | URLSearchParams | ImmutableDictionary<unknown>;
 /**
  * Get a set of params for a URI as a dictionary.
  * - Any params with `undefined` value will be ignored.
+ *
+ * @param params Possible URI params to convert.
+ * @param caller Function to attribute a thrown error to (defaults to `getURIParams` itself).
+ * @returns Dictionary of string params keyed by name.
+ * @throws {RequiredError} If `params` is a string or URL that cannot be converted to a valid URI.
+ * @throws {ValueError} If any param value cannot be converted to a string.
+ * @example getURIParams("http://x.com?a=1&b=2") // { a: "1", b: "2" }
+ * @see https://dhoulb.github.io/shelving/util/uri/getURIParams
  */
 export declare function getURIParams(params: PossibleURIParams, caller?: AnyCaller): URIParams;
 /** Get a single named param from a URI. */