shelving 1.236.0 → 1.236.2

package/util/uri.js

@@ -2,12 +2,31 @@ import { RequiredError } from "../error/RequiredError.js";
 import { ValueError } from "../error/ValueError.js";
 import { getDictionaryItems, isDictionary } from "./dictionary.js";
 import { getString, isString } from "./string.js";
+/**
+ * Correctly-typed `URI` constructor (the builtin `URL` class typed as `ImmutableURIConstructor`).
+ *
+ * @see https://dhoulb.github.io/shelving/util/uri/ImmutableURI
+ */
 export const ImmutableURI = 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 function isURI(value) {
     return value instanceof 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 function assertURI(value, caller = assertURI) {
     if (!isURI(value))
         throw new RequiredError("Invalid URI", { received: value, caller });
@@ -16,6 +35,11 @@ export function assertURI(value, caller = assertURI) {
  * 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 function getURI(possible) {
     if (!possible)
@@ -29,7 +53,16 @@ export function getURI(possible) {
         //
     }
 }
-/** 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 function requireURI(possible, caller = requireURI) {
     const url = getURI(possible);
     assertURI(url, caller);
@@ -69,6 +102,14 @@ function* getURIEntries(params, caller = getURIParams) {
 /**
  * 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 function getURIParams(params, caller = getURIParams) {
     const output = {};

package/util/url.d.ts

@@ -6,6 +6,8 @@ import type { ImmutableURI } 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.
+ *
+ * @see https://dhoulb.github.io/shelving/util/url/URLString
  */
 export type URLString = `${string}://${string}`;
 /**
@@ -14,6 +16,8 @@ export type URLString = `${string}://${string}`;
  * - 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
+ *
+ * @see https://dhoulb.github.io/shelving/util/url/ImmutableURLConstructor
  */
 export interface ImmutableURLConstructor {
     new (input: URLString | ImmutableURL, base?: URLString | ImmutableURL): ImmutableURL;
@@ -35,6 +39,8 @@ export interface ImmutableURLConstructor {
  * - 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).
  * - Javascript URLs are mutable which can lead to subtle bugs.
+ *
+ * @see https://dhoulb.github.io/shelving/util/url/ImmutableURL
  */
 export interface ImmutableURL extends ImmutableURI {
     readonly href: URLString;
@@ -42,14 +48,42 @@ export interface ImmutableURL extends ImmutableURI {
     readonly pathname: AbsolutePath;
 }
 export declare const ImmutableURL: ImmutableURLConstructor;
-/** Values that can be converted to a URL instance. */
+/**
+ * Values that can be converted to a URL instance.
+ *
+ * @see https://dhoulb.github.io/shelving/util/url/PossibleURL
+ */
 export type PossibleURL = string | URL;
 /**
  * Is an unknown value a URL object?
  * - Must be a `URL` instance and its origin must start with `scheme://`
+ *
+ * @param value Unknown value to test.
+ * @returns `true` if `value` is a true `scheme://host` URL object, otherwise `false`.
+ *
+ * @example
+ * ```ts
+ * if (isURL(value)) value.pathname; // `value` is narrowed to `ImmutableURL`
+ * ```
+ *
+ * @see https://dhoulb.github.io/shelving/util/url/isURL
  */
 export declare function isURL(value: unknown): value is ImmutableURL;
-/** Assert that an unknown value is a URL object. */
+/**
+ * Assert that an unknown value is a URL object.
+ *
+ * @param value Unknown value to test.
+ * @param caller Function to attribute a thrown error to — defaults to `assertURL`.
+ * @throws RequiredError If `value` is not a true `scheme://host` URL object.
+ *
+ * @example
+ * ```ts
+ * assertURL(value);
+ * value.pathname; // `value` is narrowed to `ImmutableURL`
+ * ```
+ *
+ * @see https://dhoulb.github.io/shelving/util/url/assertURL
+ */
 export declare function assertURL(value: unknown, caller?: AnyCaller): asserts value is ImmutableURL;
 /**
  * Resolve a possible URI relative to a base, or return `undefined` if conversion fails.
@@ -59,14 +93,52 @@ export declare function assertURL(value: unknown, caller?: AnyCaller): asserts v
  * Note: the base is normalised with `getBaseURL()`, so it is always treated as if it ends in a slash.
  * - e.g. if `base` is `http://p.com/a/b/c` the path resolves relative to `c/` as if a trailing slash was present.
  * - This differs from the default behaviour of `new URL()`, but is the more natural expected result.
+ *
+ * @param input URI string, URL object, or path to resolve — falsy values return `undefined`.
+ * @param base Base URL to resolve a relative `input` against.
+ * @returns Resolved `ImmutableURI`, or `undefined` if conversion fails.
+ *
+ * @example
+ * ```ts
+ * getBasedURI("path/to/page", "http://example.com/base/"); // `http://example.com/base/path/to/page`
+ * ```
+ *
+ * @see https://dhoulb.github.io/shelving/util/url/getBasedURI
  */
 export declare function getBasedURI(input: Nullish<PossibleURL>, base?: PossibleURL): ImmutableURI | undefined;
 /**
  * Resolve a possible URL relative to a base URL, or return `undefined` if conversion fails.
  * - Like `getBasedURI()` but only succeeds for true `scheme://host` URLs — other URIs (e.g. `mailto:`) return `undefined`.
+ *
+ * @param target URL string, URL object, or path to resolve — falsy values return `undefined`.
+ * @param base Base URL to resolve a relative `target` against.
+ * @returns Resolved `ImmutableURL`, or `undefined` if conversion fails or the result is not a true URL.
+ *
+ * @example
+ * ```ts
+ * getURL("/page", "http://example.com/"); // `http://example.com/page`
+ * getURL("mailto:a@b.com"); // `undefined` — not a hierarchical URL
+ * ```
+ *
+ * @see https://dhoulb.github.io/shelving/util/url/getURL
  */
 export declare function getURL(target: Nullish<PossibleURL>, base?: PossibleURL): ImmutableURL | undefined;
-/** Convert a possible URL to a URL, or throw `RequiredError` if conversion fails. */
+/**
+ * Convert a possible URL to a URL, or throw `RequiredError` if conversion fails.
+ *
+ * @param target URL string, URL object, or path to resolve.
+ * @param base Base URL to resolve a relative `target` against.
+ * @param caller Function to attribute a thrown error to — defaults to `requireURL`.
+ * @returns Resolved `ImmutableURL`.
+ * @throws RequiredError If `target` cannot be resolved to a true `scheme://host` URL.
+ *
+ * @example
+ * ```ts
+ * requireURL("/page", "http://example.com/"); // `http://example.com/page`
+ * ```
+ *
+ * @see https://dhoulb.github.io/shelving/util/url/requireURL
+ */
 export declare function requireURL(target: PossibleURL, base?: PossibleURL, caller?: AnyCaller): ImmutableURL;
 /**
  * Resolve and match a target URL/path against a base URL and return the remaining path.
@@ -76,8 +148,18 @@ export declare function requireURL(target: PossibleURL, base?: PossibleURL, call
  * - Relative targets are resolved against the normalized base URL.
  *
  * @param target URL to match against `base` — if this is a relative path it will be resolved against `base`
+ * @param base Base URL the `target` is matched against.
+ * @param caller Function to attribute a thrown error to — defaults to `matchURLPrefix`.
  *
  * @returns Absolute path starting with `/`, or `undefined` for origin mismatches or non-matching paths.
+ * @throws RequiredError If `target` or `base` cannot be resolved to a true URL.
+ *
+ * @example
+ * ```ts
+ * matchURLPrefix("http://x.com/a/b", "http://x.com/a/"); // `/b`
+ * ```
+ *
+ * @see https://dhoulb.github.io/shelving/util/url/matchURLPrefix
  */
 export declare function matchURLPrefix(target: PossibleURL | undefined, base: PossibleURL | undefined, caller?: AnyCaller): AbsolutePath | undefined;
 /**
@@ -87,6 +169,15 @@ export declare function matchURLPrefix(target: PossibleURL | undefined, base: Po
  *
  * @param target URL whose status to test — relative paths resolve against `base`.
  * @param base Base URL to test against.
+ * @param caller Function to attribute a thrown error to — defaults to `isURLActive`.
+ * @returns `true` if `target` resolves to exactly the same URL as `base`, otherwise `false`.
+ *
+ * @example
+ * ```ts
+ * isURLActive("http://x.com/a", "http://x.com/a"); // `true`
+ * ```
+ *
+ * @see https://dhoulb.github.io/shelving/util/url/isURLActive
  */
 export declare function isURLActive(target: PossibleURL | undefined, base: PossibleURL | undefined, caller?: AnyCaller): boolean;
 /**
@@ -97,15 +188,69 @@ export declare function isURLActive(target: PossibleURL | undefined, base: Possi
  *
  * @param target URL whose status to test — relative paths resolve against `base`.
  * @param base Base URL to test against.
+ * @param caller Function to attribute a thrown error to — defaults to `isURLProud`.
+ * @returns `true` if `target` is `base` or a descendant of `base`, otherwise `false`.
+ *
+ * @example
+ * ```ts
+ * isURLProud("http://x.com/a/b", "http://x.com/a"); // `true`
+ * ```
+ *
+ * @see https://dhoulb.github.io/shelving/util/url/isURLProud
  */
 export declare function isURLProud(target: PossibleURL | undefined, base: PossibleURL | undefined, caller?: AnyCaller): boolean;
-/** BaseURL is a URL with a guaranteed trailing slash on pathname. */
+/**
+ * BaseURL is a URL with a guaranteed trailing slash on pathname.
+ *
+ * @see https://dhoulb.github.io/shelving/util/url/BaseURL
+ */
 export interface BaseURL extends ImmutableURL {
     readonly pathname: `/` | `/${string}/`;
 }
-/** Is an unknown value a valid Base URL. */
+/**
+ * Is an unknown value a valid Base URL?
+ * - Must be a true URL whose `pathname` ends in a trailing slash.
+ *
+ * @param value Value to test.
+ * @returns `true` if `value` is a `BaseURL` (a URL with a trailing-slash pathname), otherwise `false`.
+ *
+ * @example
+ * ```ts
+ * isBaseURL(new URL("http://x.com/a/")); // `true`
+ * ```
+ *
+ * @see https://dhoulb.github.io/shelving/util/url/isBaseURL
+ */
 export declare function isBaseURL(value: PossibleURL): value is BaseURL;
-/** Get a Base URL. */
+/**
+ * Get a Base URL — a true URL whose `pathname` is normalised to end in a trailing slash.
+ * - Falsy or non-URL input returns `undefined`.
+ * - A URL without a trailing slash is cloned and given one (the input is never mutated).
+ *
+ * @param input URL string, URL object, or path to normalise.
+ * @returns `BaseURL` with a trailing-slash pathname, or `undefined` if `input` is not a true URL.
+ *
+ * @example
+ * ```ts
+ * getBaseURL("http://x.com/a"); // `http://x.com/a/`
+ * ```
+ *
+ * @see https://dhoulb.github.io/shelving/util/url/getBaseURL
+ */
 export declare function getBaseURL(input: Nullish<PossibleURL>): BaseURL | undefined;
-/** Require a Base URL. */
+/**
+ * Require a Base URL — a true URL whose `pathname` is normalised to end in a trailing slash.
+ *
+ * @param value URL string, URL object, or path to normalise.
+ * @param caller Function to attribute a thrown error to.
+ * @returns `BaseURL` with a trailing-slash pathname.
+ * @throws RequiredError If `value` cannot be resolved to a true URL.
+ *
+ * @example
+ * ```ts
+ * requireBaseURL("http://x.com/a", requireBaseURL); // `http://x.com/a/`
+ * ```
+ *
+ * @see https://dhoulb.github.io/shelving/util/url/requireBaseURL
+ */
 export declare function requireBaseURL(value: PossibleURL, caller: AnyCaller): BaseURL;

package/util/url.js

@@ -3,6 +3,16 @@ export const ImmutableURL = URL;
 /**
  * Is an unknown value a URL object?
  * - Must be a `URL` instance and its origin must start with `scheme://`
+ *
+ * @param value Unknown value to test.
+ * @returns `true` if `value` is a true `scheme://host` URL object, otherwise `false`.
+ *
+ * @example
+ * ```ts
+ * if (isURL(value)) value.pathname; // `value` is narrowed to `ImmutableURL`
+ * ```
+ *
+ * @see https://dhoulb.github.io/shelving/util/url/isURL
  */
 export function isURL(value) {
     return value instanceof URL && _isURL(value);
@@ -10,7 +20,21 @@ export function isURL(value) {
 function _isURL(uri) {
     return uri.href.startsWith(`${uri.protocol}//`);
 }
-/** Assert that an unknown value is a URL object. */
+/**
+ * Assert that an unknown value is a URL object.
+ *
+ * @param value Unknown value to test.
+ * @param caller Function to attribute a thrown error to — defaults to `assertURL`.
+ * @throws RequiredError If `value` is not a true `scheme://host` URL object.
+ *
+ * @example
+ * ```ts
+ * assertURL(value);
+ * value.pathname; // `value` is narrowed to `ImmutableURL`
+ * ```
+ *
+ * @see https://dhoulb.github.io/shelving/util/url/assertURL
+ */
 export function assertURL(value, caller = assertURL) {
     if (!isURL(value))
         throw new RequiredError("Invalid URL", { received: value, caller });
@@ -23,6 +47,17 @@ export function assertURL(value, caller = assertURL) {
  * Note: the base is normalised with `getBaseURL()`, so it is always treated as if it ends in a slash.
  * - e.g. if `base` is `http://p.com/a/b/c` the path resolves relative to `c/` as if a trailing slash was present.
  * - This differs from the default behaviour of `new URL()`, but is the more natural expected result.
+ *
+ * @param input URI string, URL object, or path to resolve — falsy values return `undefined`.
+ * @param base Base URL to resolve a relative `input` against.
+ * @returns Resolved `ImmutableURI`, or `undefined` if conversion fails.
+ *
+ * @example
+ * ```ts
+ * getBasedURI("path/to/page", "http://example.com/base/"); // `http://example.com/base/path/to/page`
+ * ```
+ *
+ * @see https://dhoulb.github.io/shelving/util/url/getBasedURI
  */
 export function getBasedURI(input, base) {
     if (!input)
@@ -39,13 +74,40 @@ export function getBasedURI(input, base) {
 /**
  * Resolve a possible URL relative to a base URL, or return `undefined` if conversion fails.
  * - Like `getBasedURI()` but only succeeds for true `scheme://host` URLs — other URIs (e.g. `mailto:`) return `undefined`.
+ *
+ * @param target URL string, URL object, or path to resolve — falsy values return `undefined`.
+ * @param base Base URL to resolve a relative `target` against.
+ * @returns Resolved `ImmutableURL`, or `undefined` if conversion fails or the result is not a true URL.
+ *
+ * @example
+ * ```ts
+ * getURL("/page", "http://example.com/"); // `http://example.com/page`
+ * getURL("mailto:a@b.com"); // `undefined` — not a hierarchical URL
+ * ```
+ *
+ * @see https://dhoulb.github.io/shelving/util/url/getURL
  */
 export function getURL(target, base) {
     const uri = getBasedURI(target, base);
     if (uri && _isURL(uri))
         return uri;
 }
-/** Convert a possible URL to a URL, or throw `RequiredError` if conversion fails. */
+/**
+ * Convert a possible URL to a URL, or throw `RequiredError` if conversion fails.
+ *
+ * @param target URL string, URL object, or path to resolve.
+ * @param base Base URL to resolve a relative `target` against.
+ * @param caller Function to attribute a thrown error to — defaults to `requireURL`.
+ * @returns Resolved `ImmutableURL`.
+ * @throws RequiredError If `target` cannot be resolved to a true `scheme://host` URL.
+ *
+ * @example
+ * ```ts
+ * requireURL("/page", "http://example.com/"); // `http://example.com/page`
+ * ```
+ *
+ * @see https://dhoulb.github.io/shelving/util/url/requireURL
+ */
 export function requireURL(target, base, caller = requireURL) {
     const url = getURL(target, base);
     assertURL(url, caller);
@@ -59,8 +121,18 @@ export function requireURL(target, base, caller = requireURL) {
  * - Relative targets are resolved against the normalized base URL.
  *
  * @param target URL to match against `base` — if this is a relative path it will be resolved against `base`
+ * @param base Base URL the `target` is matched against.
+ * @param caller Function to attribute a thrown error to — defaults to `matchURLPrefix`.
  *
  * @returns Absolute path starting with `/`, or `undefined` for origin mismatches or non-matching paths.
+ * @throws RequiredError If `target` or `base` cannot be resolved to a true URL.
+ *
+ * @example
+ * ```ts
+ * matchURLPrefix("http://x.com/a/b", "http://x.com/a/"); // `/b`
+ * ```
+ *
+ * @see https://dhoulb.github.io/shelving/util/url/matchURLPrefix
  */
 export function matchURLPrefix(target, base, caller = matchURLPrefix) {
     if (!target || !base)
@@ -87,6 +159,15 @@ export function matchURLPrefix(target, base, caller = matchURLPrefix) {
  *
  * @param target URL whose status to test — relative paths resolve against `base`.
  * @param base Base URL to test against.
+ * @param caller Function to attribute a thrown error to — defaults to `isURLActive`.
+ * @returns `true` if `target` resolves to exactly the same URL as `base`, otherwise `false`.
+ *
+ * @example
+ * ```ts
+ * isURLActive("http://x.com/a", "http://x.com/a"); // `true`
+ * ```
+ *
+ * @see https://dhoulb.github.io/shelving/util/url/isURLActive
  */
 export function isURLActive(target, base, caller = isURLActive) {
     return !!target && !!base && matchURLPrefix(target, base, caller) === "/";
@@ -99,18 +180,54 @@ export function isURLActive(target, base, caller = isURLActive) {
  *
  * @param target URL whose status to test — relative paths resolve against `base`.
  * @param base Base URL to test against.
+ * @param caller Function to attribute a thrown error to — defaults to `isURLProud`.
+ * @returns `true` if `target` is `base` or a descendant of `base`, otherwise `false`.
+ *
+ * @example
+ * ```ts
+ * isURLProud("http://x.com/a/b", "http://x.com/a"); // `true`
+ * ```
+ *
+ * @see https://dhoulb.github.io/shelving/util/url/isURLProud
  */
 export function isURLProud(target, base, caller = isURLProud) {
     return !!target && !!base && matchURLPrefix(target, base, caller) !== undefined;
 }
-/** Is an unknown value a valid Base URL. */
+/**
+ * Is an unknown value a valid Base URL?
+ * - Must be a true URL whose `pathname` ends in a trailing slash.
+ *
+ * @param value Value to test.
+ * @returns `true` if `value` is a `BaseURL` (a URL with a trailing-slash pathname), otherwise `false`.
+ *
+ * @example
+ * ```ts
+ * isBaseURL(new URL("http://x.com/a/")); // `true`
+ * ```
+ *
+ * @see https://dhoulb.github.io/shelving/util/url/isBaseURL
+ */
 export function isBaseURL(value) {
     return isURL(value) && _isBaseURL(value);
 }
 function _isBaseURL(uri) {
     return uri.pathname.endsWith("/");
 }
-/** Get a Base URL. */
+/**
+ * Get a Base URL — a true URL whose `pathname` is normalised to end in a trailing slash.
+ * - Falsy or non-URL input returns `undefined`.
+ * - A URL without a trailing slash is cloned and given one (the input is never mutated).
+ *
+ * @param input URL string, URL object, or path to normalise.
+ * @returns `BaseURL` with a trailing-slash pathname, or `undefined` if `input` is not a true URL.
+ *
+ * @example
+ * ```ts
+ * getBaseURL("http://x.com/a"); // `http://x.com/a/`
+ * ```
+ *
+ * @see https://dhoulb.github.io/shelving/util/url/getBaseURL
+ */
 export function getBaseURL(input) {
     if (!input)
         return;
@@ -124,7 +241,21 @@ export function getBaseURL(input) {
     base.pathname = `${uri.pathname}/`; // Add a trailing slash.
     return base;
 }
-/** Require a Base URL. */
+/**
+ * Require a Base URL — a true URL whose `pathname` is normalised to end in a trailing slash.
+ *
+ * @param value URL string, URL object, or path to normalise.
+ * @param caller Function to attribute a thrown error to.
+ * @returns `BaseURL` with a trailing-slash pathname.
+ * @throws RequiredError If `value` cannot be resolved to a true URL.
+ *
+ * @example
+ * ```ts
+ * requireBaseURL("http://x.com/a", requireBaseURL); // `http://x.com/a/`
+ * ```
+ *
+ * @see https://dhoulb.github.io/shelving/util/url/requireBaseURL
+ */
 export function requireBaseURL(value, caller) {
     const url = getBaseURL(value);
     if (!url)

package/util/uuid.d.ts

@@ -1,6 +1,31 @@
-/** Return a random UUID (v4) */
+/**
+ * Return a random UUID (v4) as a 32-character lowercase hex string with dashes stripped.
+ *
+ * @returns A random 32-character lowercase hex UUID string.
+ * @example randomUUID() // "1b4e28ba2fa14931918f4c9bf9f12b3a"
+ * @see https://dhoulb.github.io/shelving/util/uuid/randomUUID
+ */
 export declare function randomUUID(): string;
-/** Convert/validate a unknown value as as UUID. */
+/**
+ * Convert/validate a string value as a UUID, or return `undefined` if it isn't valid.
+ *
+ * - Strips any non-hex characters (including existing dashes) and normalises to lowercase.
+ * - Requires exactly 32 hex characters after cleaning, otherwise returns `undefined`.
+ * - The returned string is re-grouped into the canonical `8-4-4-4-12` segment layout.
+ *
+ * @param value The value to convert/validate as a UUID.
+ * @returns The normalised UUID string, or `undefined` if the value is not a valid UUID.
+ * @example getUUID("1b4e28ba-2fa1-4931-918f-4c9bf9f12b3a") // "1b4e28ba2fa14931918f4c9bf9f12b3a"
+ * @see https://dhoulb.github.io/shelving/util/uuid/getUUID
+ */
 export declare function getUUID(value: string): string | undefined;
-/** Require a valid UUID. */
+/**
+ * Convert/validate a string value as a UUID, or throw `RequiredError` if it isn't valid.
+ *
+ * @param value The value to convert/validate as a UUID.
+ * @returns The normalised UUID string.
+ * @throws `RequiredError` if the value is not a valid UUID.
+ * @example requireUUID("1b4e28ba-2fa1-4931-918f-4c9bf9f12b3a") // "1b4e28ba2fa14931918f4c9bf9f12b3a"
+ * @see https://dhoulb.github.io/shelving/util/uuid/requireUUID
+ */
 export declare function requireUUID(value: string): string;

package/util/uuid.js

@@ -1,10 +1,27 @@
 import { RequiredError } from "../error/RequiredError.js";
 const R_NOT_LOWERCHAR = /[^0-9a-f]/g;
-/** Return a random UUID (v4) */
+/**
+ * Return a random UUID (v4) as a 32-character lowercase hex string with dashes stripped.
+ *
+ * @returns A random 32-character lowercase hex UUID string.
+ * @example randomUUID() // "1b4e28ba2fa14931918f4c9bf9f12b3a"
+ * @see https://dhoulb.github.io/shelving/util/uuid/randomUUID
+ */
 export function randomUUID() {
     return crypto.randomUUID().replace(R_NOT_LOWERCHAR, "");
 }
-/** Convert/validate a unknown value as as UUID. */
+/**
+ * Convert/validate a string value as a UUID, or return `undefined` if it isn't valid.
+ *
+ * - Strips any non-hex characters (including existing dashes) and normalises to lowercase.
+ * - Requires exactly 32 hex characters after cleaning, otherwise returns `undefined`.
+ * - The returned string is re-grouped into the canonical `8-4-4-4-12` segment layout.
+ *
+ * @param value The value to convert/validate as a UUID.
+ * @returns The normalised UUID string, or `undefined` if the value is not a valid UUID.
+ * @example getUUID("1b4e28ba-2fa1-4931-918f-4c9bf9f12b3a") // "1b4e28ba2fa14931918f4c9bf9f12b3a"
+ * @see https://dhoulb.github.io/shelving/util/uuid/getUUID
+ */
 export function getUUID(value) {
     if (typeof value !== "string" || !value)
         return;
@@ -14,7 +31,15 @@ export function getUUID(value) {
         return;
     return `${cleaned.slice(0, 8)}${cleaned.slice(8, 12)}${cleaned.slice(12, 16)}${cleaned.slice(16, 20)}${cleaned.slice(20)}`;
 }
-/** Require a valid UUID. */
+/**
+ * Convert/validate a string value as a UUID, or throw `RequiredError` if it isn't valid.
+ *
+ * @param value The value to convert/validate as a UUID.
+ * @returns The normalised UUID string.
+ * @throws `RequiredError` if the value is not a valid UUID.
+ * @example requireUUID("1b4e28ba-2fa1-4931-918f-4c9bf9f12b3a") // "1b4e28ba2fa14931918f4c9bf9f12b3a"
+ * @see https://dhoulb.github.io/shelving/util/uuid/requireUUID
+ */
 export function requireUUID(value) {
     const uuid = getUUID(value);
     if (!uuid)