shelving 1.236.0 → 1.236.2

package/util/date.js

@@ -1,12 +1,24 @@
 import { RequiredError } from "../error/RequiredError.js";
 /**
- * Is a value a valid date?
+ * Is a value a valid `Date` instance?
  * - Note: `Date` instances can be invalid (e.g. `new Date("blah blah").getTime()` returns `NaN`). These are detected and will always return `false`
+ *
+ * @param value The value to check.
+ * @returns `true` if the value is a `Date` instance representing a valid date, narrowing it to `Date`.
+ * @see https://dhoulb.github.io/shelving/util/date/isDate
  */
 export function isDate(value) {
     return value instanceof Date && Number.isFinite(value.getTime());
 }
-/** Assert that a value is a `Date` instance. */
+/**
+ * Assert that a value is a valid `Date` instance.
+ *
+ * @param value The value to check.
+ * @param caller The function to attribute a thrown error to (defaults to `assertDate`).
+ * @throws {RequiredError} If the value is not a valid `Date` instance.
+ * @example assertDate(value); // throws unless `value` is a valid `Date`
+ * @see https://dhoulb.github.io/shelving/util/date/assertDate
+ */
 export function assertDate(value, caller = assertDate) {
     if (!isDate(value))
         throw new RequiredError("Must be valid date", { received: value, caller });
@@ -27,7 +39,10 @@ export function assertDate(value, caller = assertDate) {
  * - Numbers are return the corresponding date (using `new Date(number)`, i.e. milliseconds since 01/01/1970).
  * - Anything else returns `undefined`
  *
- * @returns `Date` instance if the value could be converted to a valid date, and `null` if not.
+ * @returns `Date` instance if the value could be converted to a valid date, or `undefined` if not.
+ * @example getDate("2003-09-12") // Date instance for 2003-09-12
+ * @example getDate("nope") // undefined
+ * @see https://dhoulb.github.io/shelving/util/date/getDate
  */
 export function getDate(value) {
     if (value === "now")
@@ -49,37 +64,79 @@ export function getDate(value) {
             return time;
     }
 }
-/** Get a date representing this exact moment. */
+/**
+ * Get a date representing this exact moment.
+ *
+ * @returns A new `Date` instance for the current moment.
+ * @example getNow() // Date instance for right now
+ * @see https://dhoulb.github.io/shelving/util/date/getNow
+ */
 export function getNow() {
     return new Date();
 }
-/** Get a date representing midnight of the previous day. */
+/**
+ * Get a date representing midnight of the previous day.
+ *
+ * @returns A new `Date` instance at midnight yesterday.
+ * @example getYesterday() // Date instance for yesterday at 00:00
+ * @see https://dhoulb.github.io/shelving/util/date/getYesterday
+ */
 export function getYesterday() {
     const date = new Date();
     date.setHours(0, 0, 0, 0);
     date.setDate(date.getDate() - 1);
     return date;
 }
-/** Get a date representing midnight of the current day. */
+/**
+ * Get a date representing midnight of the current day.
+ *
+ * @returns A new `Date` instance at midnight today.
+ * @example getToday() // Date instance for today at 00:00
+ * @see https://dhoulb.github.io/shelving/util/date/getToday
+ */
 export function getToday() {
     const date = new Date();
     date.setHours(0, 0, 0, 0);
     return date;
 }
-/** Get a date representing midnight of the next day. */
+/**
+ * Get a date representing midnight of the next day.
+ *
+ * @returns A new `Date` instance at midnight tomorrow.
+ * @example getTomorrow() // Date instance for tomorrow at 00:00
+ * @see https://dhoulb.github.io/shelving/util/date/getTomorrow
+ */
 export function getTomorrow() {
     const date = new Date();
     date.setHours(0, 0, 0, 0);
     date.setDate(date.getDate() + 1);
     return date;
 }
-/** Get a Date representing exactly midnight of the specified date. */
+/**
+ * Get a `Date` representing exactly midnight of the specified date.
+ *
+ * @param target The date to find midnight for (defaults to `"now"`).
+ * @param caller The function to attribute a thrown error to (defaults to `getMidnight`).
+ * @returns A new `Date` instance at midnight of the target date.
+ * @throws {RequiredError} If `target` couldn't be converted to a valid date.
+ * @example getMidnight("2003-09-12") // Date instance for 2003-09-12 at 00:00
+ * @see https://dhoulb.github.io/shelving/util/date/getMidnight
+ */
 export function getMidnight(target, caller = getMidnight) {
     const date = new Date(requireDate(target, caller));
     date.setHours(0, 0, 0, 0);
     return date;
 }
-/** Get a Date representing midnight on Monday of the specified week. */
+/**
+ * Get a `Date` representing midnight on Monday of the specified week.
+ *
+ * @param target The date whose week to find Monday for (defaults to `"now"`).
+ * @param caller The function to attribute a thrown error to (defaults to `getMonday`).
+ * @returns A new `Date` instance at midnight on Monday of the target week.
+ * @throws {RequiredError} If `target` couldn't be converted to a valid date.
+ * @example getMonday("2003-09-12") // Date instance for the Monday of that week at 00:00
+ * @see https://dhoulb.github.io/shelving/util/date/getMonday
+ */
 export function getMonday(target, caller = getMonday) {
     const date = getMidnight(target, caller);
     const day = date.getDay();
@@ -89,7 +146,16 @@ export function getMonday(target, caller = getMonday) {
         date.setDate(date.getDate() - (day - 1));
     return date;
 }
-/** Get a Date representing the first day of the specified month. */
+/**
+ * Get a `Date` representing midnight on the first day of the specified month.
+ *
+ * @param target The date whose month to find the start of (defaults to `"now"`).
+ * @param caller The function to attribute a thrown error to (defaults to `getMonthStart`).
+ * @returns A new `Date` instance at midnight on the 1st of the target month.
+ * @throws {RequiredError} If `target` couldn't be converted to a valid date.
+ * @example getMonthStart("2003-09-12") // Date instance for 2003-09-01 at 00:00
+ * @see https://dhoulb.github.io/shelving/util/date/getMonthStart
+ */
 export function getMonthStart(target, caller = getMonthStart) {
     const date = getMidnight(target, caller);
     date.setDate(1);
@@ -97,18 +163,39 @@ export function getMonthStart(target, caller = getMonthStart) {
 }
 /**
  * Convert a possible date to a `Date` instance, or throw `RequiredError` if it couldn't be converted.
+ *
  * @param value Any value that we want to parse as a valid date (defaults to `"now"`).
+ * @param caller The function to attribute a thrown error to (defaults to `requireDate`).
+ * @returns A valid `Date` instance.
+ * @throws {RequiredError} If `value` couldn't be converted to a valid date.
+ * @example requireDate("2003-09-12") // Date instance for 2003-09-12
+ * @see https://dhoulb.github.io/shelving/util/date/requireDate
  */
 export function requireDate(value = "now", caller = requireDate) {
     const date = getDate(value);
     assertDate(date, caller);
     return date;
 }
-/** Convert an unknown value to a timestamp (milliseconds past Unix epoch), or `undefined` if it couldn't be converted. */
+/**
+ * Convert an unknown value to a timestamp (milliseconds past Unix epoch), or `undefined` if it couldn't be converted.
+ *
+ * @param value Any value that we want to parse as a valid date.
+ * @returns The timestamp in milliseconds, or `undefined` if the value couldn't be converted.
+ * @example getTimestamp("1970-01-01T00:00:00Z") // 0
+ * @see https://dhoulb.github.io/shelving/util/date/getTimestamp
+ */
 export function getTimestamp(value) {
     return getDate(value)?.getTime();
 }
-/** Convert a possible date to a timestamp (milliseconds past Unix epoch), or throw `RequiredError` if it couldn't be converted. */
+/**
+ * Convert a possible date to a timestamp (milliseconds past Unix epoch), or throw `RequiredError` if it couldn't be converted.
+ *
+ * @param value Any value that we want to parse as a valid date (defaults to `"now"`).
+ * @returns The timestamp in milliseconds.
+ * @throws {RequiredError} If `value` couldn't be converted to a valid date.
+ * @example requireTimestamp("1970-01-01T00:00:00Z") // 0
+ * @see https://dhoulb.github.io/shelving/util/date/requireTimestamp
+ */
 export function requireTimestamp(value) {
     return requireDate(value, requireTimestamp).getTime();
 }
@@ -125,17 +212,40 @@ function _time(date) {
 function _datetime(date) {
     return `${_date(date)}T${_time(date)}`;
 }
-/** Convert an unknown value to a local date string like "2015-09-12T18:30:00", or `undefined` if it couldn't be converted. */
+/**
+ * Convert an unknown value to a local date string like "2015-09-12T18:30:00", or `undefined` if it couldn't be converted.
+ *
+ * @param value Any value that we want to parse as a valid date.
+ * @returns The local datetime string, or `undefined` if `value` couldn't be converted.
+ * @example getDateTimeString("2015-09-12T18:30:00") // "2015-09-12T18:30:00"
+ * @see https://dhoulb.github.io/shelving/util/date/getDateTimeString
+ */
 export function getDateTimeString(value) {
     const date = getDate(value);
     if (date)
         return _datetime(date);
 }
-/** Convert a possible `Date` instance to a local YMD string like "2015-09-12T18:30:00", or throw `RequiredError` if it couldn't be converted.  */
+/**
+ * Convert a possible `Date` instance to a local YMD string like "2015-09-12T18:30:00", or throw `RequiredError` if it couldn't be converted.
+ *
+ * @param value Any value that we want to parse as a valid date (defaults to `"now"`).
+ * @param caller Function to attribute a thrown error to (defaults to `requireDateTimeString` itself).
+ * @returns The local datetime string.
+ * @throws {RequiredError} If `value` couldn't be converted to a valid date.
+ * @example requireDateTimeString("2015-09-12T18:30:00") // "2015-09-12T18:30:00"
+ * @see https://dhoulb.github.io/shelving/util/date/requireDateTimeString
+ */
 export function requireDateTimeString(value, caller = requireDateTimeString) {
     return _datetime(requireDate(value, caller));
 }
-/** Convert an unknown value to a local date string like "2015-09-12", or `undefined` if it couldn't be converted. */
+/**
+ * Convert an unknown value to a local date string like "2015-09-12", or `undefined` if it couldn't be converted.
+ *
+ * @param value Any value that we want to parse as a valid date.
+ * @returns The local date string, or `undefined` if `value` couldn't be converted.
+ * @example getDateString("2015-09-12T18:30:00") // "2015-09-12"
+ * @see https://dhoulb.github.io/shelving/util/date/getDateString
+ */
 export function getDateString(value) {
     const date = getDate(value);
     if (date)
@@ -210,13 +320,33 @@ export function addMinutes(change, target, caller = addMinutes) {
     date.setMinutes(date.getMinutes() + change);
     return date;
 }
-/** Return a new date that increase or decreases the minute based on an input date. */
+/**
+ * Return a new date that increases or decreases the seconds based on an input date.
+ *
+ * @param change The number of seconds to add (negative numbers subtract).
+ * @param target Any value that can be converted to a date (defaults to `"now"`).
+ * @param caller Function to attribute a thrown error to (defaults to `addSeconds` itself).
+ * @returns A new `Date` instance offset by `change` seconds.
+ * @throws {RequiredError} If `target` couldn't be converted to a valid date.
+ * @example addSeconds(30, "2003-09-12T00:00:00") // Date instance for 2003-09-12T00:00:30
+ * @see https://dhoulb.github.io/shelving/util/date/addSeconds
+ */
 export function addSeconds(change, target, caller = addSeconds) {
     const date = new Date(requireDate(target, caller));
     date.setSeconds(date.getSeconds() + change);
     return date;
 }
-/** Return a new date that increase or decreases the minute based on an input date. */
+/**
+ * Return a new date that increases or decreases the milliseconds based on an input date.
+ *
+ * @param change The number of milliseconds to add (negative numbers subtract).
+ * @param target Any value that can be converted to a date (defaults to `"now"`).
+ * @param caller Function to attribute a thrown error to (defaults to `addMilliseconds` itself).
+ * @returns A new `Date` instance offset by `change` milliseconds.
+ * @throws {RequiredError} If `target` couldn't be converted to a valid date.
+ * @example addMilliseconds(500, "2003-09-12T00:00:00") // Date instance for 2003-09-12T00:00:00.500
+ * @see https://dhoulb.github.io/shelving/util/date/addMilliseconds
+ */
 export function addMilliseconds(change, target, caller = addMilliseconds) {
     const date = new Date(requireDate(target, caller));
     date.setMilliseconds(date.getMilliseconds() + change);

package/util/debug.d.ts

@@ -2,16 +2,47 @@
 import type { ImmutableArray } from "./array.js";
 import type { ImmutableMap } from "./map.js";
 import type { ImmutableSet } from "./set.js";
-/** Debug a random value as a string. */
+/**
+ * Convert any unknown value into a readable debug string.
+ * - Dispatches on the value's type to a specialised debugger (string, array, map, set, object, `Request`, `Response`, `Headers`, `Date`, `Error`, etc.).
+ * - Nested values are expanded down to `depth` levels; deeper values collapse to their container shape.
+ *
+ * @param value The value to debug.
+ * @param depth How many levels of nested containers to expand (defaults to `1`).
+ * @returns A human-readable string representation of `value`.
+ * @example debug({ a: 1, b: "two" }) // `{\n\t"a": 1,\n\t"b": "two"\n}`
+ * @see https://dhoulb.github.io/shelving/util/debug/debug
+ */
 export declare function debug(value: unknown, depth?: number): string;
-/** Debug a string. */
-export declare const debugString: (value: string) => string;
-/** Debug a set of `Headers` as a string. */
+/**
+ * Convert a string into a quoted, escaped debug string.
+ * - Wraps the value in double quotes and escapes control characters, quotes, and backslashes.
+ *
+ * @param value The string to debug.
+ * @returns The quoted and escaped string.
+ * @example debugString("a\tb") // `"a\\tb"`
+ * @see https://dhoulb.github.io/shelving/util/debug/debugString
+ */
+export declare function debugString(value: string): string;
+/**
+ * Convert a set of `Headers` into a debug string.
+ * - One `key: value` pair per line.
+ *
+ * @param headers The `Headers` object to debug.
+ * @returns A newline-separated string of `key: value` pairs.
+ * @example debugHeaders(new Headers({ "Content-Type": "text/plain" })) // "content-type: text/plain"
+ * @see https://dhoulb.github.io/shelving/util/debug/debugHeaders
+ */
 export declare function debugHeaders(headers: Headers): string;
 /**
  * Debug a full `Request` as a string including its body.
  * - Clones the request before reading the body so the original request can still be sent or parsed later.
  * - Omits the body section when the request body is empty.
+ *
+ * @param request The `Request` to debug.
+ * @returns A promise resolving to the request line, headers, and body as a string.
+ * @example await debugFullRequest(new Request("https://x.com")) // "GET https://x.com/"
+ * @see https://dhoulb.github.io/shelving/util/debug/debugFullRequest
  */
 export declare function debugFullRequest(request: Request): Promise<string>;
 /**
@@ -19,19 +50,89 @@ export declare function debugFullRequest(request: Request): Promise<string>;
  * - Clones the response before reading the body so the original response can still be parsed later.
  * - Omits the headers section when there are no headers.
  * - Omits the body section when the response body is empty.
+ *
+ * @param response The `Response` to debug.
+ * @returns A promise resolving to the status line, headers, and body as a string.
+ * @example await debugFullResponse(new Response("hi", { status: 200 })) // "200 \n\nhi"
+ * @see https://dhoulb.github.io/shelving/util/debug/debugFullResponse
  */
 export declare function debugFullResponse(response: Response): Promise<string>;
-/** Debug a `Request` as a string. */
+/**
+ * Convert a `Request` into a one-line debug string.
+ * - Shows the method and URL only (no headers or body).
+ *
+ * @param request The `Request` to debug.
+ * @returns A string in `METHOD url` format.
+ * @example debugRequest(new Request("https://x.com")) // "GET https://x.com/"
+ * @see https://dhoulb.github.io/shelving/util/debug/debugRequest
+ */
 export declare function debugRequest(request: Request): string;
-/** Debug a `Response` as a string. */
+/**
+ * Convert a `Response` into a one-line debug string.
+ * - Shows the status code and status text only (no headers or body).
+ *
+ * @param response The `Response` to debug.
+ * @returns A string in `status statusText` format.
+ * @example debugResponse(new Response("hi", { status: 404 })) // "404 Not Found"
+ * @see https://dhoulb.github.io/shelving/util/debug/debugResponse
+ */
 export declare function debugResponse(response: Response): string;
-/** Debug an array. */
+/**
+ * Convert an array into a readable debug string.
+ * - Prefixes the constructor name for non-plain arrays.
+ * - Expands items down to `depth` levels.
+ *
+ * @param value The array to debug.
+ * @param depth How many levels of nested containers to expand (defaults to `1`).
+ * @returns A human-readable string representation of the array.
+ * @example debugArray([1, 2]) // `[\n\t1,\n\t2\n]`
+ * @see https://dhoulb.github.io/shelving/util/debug/debugArray
+ */
 export declare function debugArray(value: ImmutableArray, depth?: number): string;
-/** Debug a set. */
+/**
+ * Convert a `Set` into a readable debug string.
+ * - Prefixes the constructor name and item count.
+ * - Expands items down to `depth` levels.
+ *
+ * @param value The set to debug.
+ * @param depth How many levels of nested containers to expand (defaults to `1`).
+ * @returns A human-readable string representation of the set.
+ * @example debugSet(new Set([1, 2])) // `(value.size) {\n\t1,\n\t2\n}`
+ * @see https://dhoulb.github.io/shelving/util/debug/debugSet
+ */
 export declare function debugSet(value: ImmutableSet, depth?: number): string;
-/** Debug a map. */
+/**
+ * Convert a `Map` into a readable debug string.
+ * - Prefixes the constructor name and entry count.
+ * - Expands keys and values down to `depth` levels.
+ *
+ * @param value The map to debug.
+ * @param depth How many levels of nested containers to expand (defaults to `1`).
+ * @returns A human-readable string representation of the map.
+ * @example debugMap(new Map([["a", 1]])) // `(value.size) {\n\t"a": 1\n}`
+ * @see https://dhoulb.github.io/shelving/util/debug/debugMap
+ */
 export declare function debugMap(value: ImmutableMap, depth?: number): string;
-/** Debug an object. */
+/**
+ * Convert an object into a readable debug string.
+ * - Prefixes the constructor name for non-plain objects.
+ * - Expands entries down to `depth` levels.
+ *
+ * @param value The object to debug.
+ * @param depth How many levels of nested containers to expand (defaults to `1`).
+ * @returns A human-readable string representation of the object.
+ * @example debugObject({ a: 1 }) // `{\n\t"a": 1\n}`
+ * @see https://dhoulb.github.io/shelving/util/debug/debugObject
+ */
 export declare function debugObject(value: object, depth?: number): string;
-/** If a string is multiline, push it onto the next line and prepend a tab to each line.. */
+/**
+ * Indent a string for nested debug output.
+ * - Multiline strings are pushed onto a new line with a tab prepended to each line.
+ * - Single-line strings are simply prefixed with a space.
+ *
+ * @param str The string to indent.
+ * @returns The indented string.
+ * @example indent("a\nb") // `\na\n\tb`
+ * @see https://dhoulb.github.io/shelving/util/debug/indent
+ */
 export declare function indent(str: string): string;

package/util/debug.js

@@ -1,4 +1,14 @@
-/** Debug a random value as a string. */
+/**
+ * Convert any unknown value into a readable debug string.
+ * - Dispatches on the value's type to a specialised debugger (string, array, map, set, object, `Request`, `Response`, `Headers`, `Date`, `Error`, etc.).
+ * - Nested values are expanded down to `depth` levels; deeper values collapse to their container shape.
+ *
+ * @param value The value to debug.
+ * @param depth How many levels of nested containers to expand (defaults to `1`).
+ * @returns A human-readable string representation of `value`.
+ * @example debug({ a: 1, b: "two" }) // `{\n\t"a": 1,\n\t"b": "two"\n}`
+ * @see https://dhoulb.github.io/shelving/util/debug/debug
+ */
 export function debug(value, depth = 1) {
     if (value === null)
         return "null";
@@ -36,8 +46,18 @@ export function debug(value, depth = 1) {
     }
     return typeof value;
 }
-/** Debug a string. */
-export const debugString = (value) => `"${value.replace(ESCAPE_REGEXP, _escapeChar)}"`;
+/**
+ * Convert a string into a quoted, escaped debug string.
+ * - Wraps the value in double quotes and escapes control characters, quotes, and backslashes.
+ *
+ * @param value The string to debug.
+ * @returns The quoted and escaped string.
+ * @example debugString("a\tb") // `"a\\tb"`
+ * @see https://dhoulb.github.io/shelving/util/debug/debugString
+ */
+export function debugString(value) {
+    return `"${value.replace(ESCAPE_REGEXP, _escapeChar)}"`;
+}
 // biome-ignore lint/suspicious/noControlCharactersInRegex: Intentional.
 const ESCAPE_REGEXP = /[\x00-\x08\x0B-\x1F\x7F-\x9F"\\]/g; // Match control characters, `"` double quote, `\` backslash.
 const ESCAPE_LIST = {
@@ -51,7 +71,15 @@ const ESCAPE_LIST = {
     "\v": "\\v",
 };
 const _escapeChar = (char) => ESCAPE_LIST[char] || `\\x${char.charCodeAt(0).toString(16).padStart(2, "00")}`;
-/** Debug a set of `Headers` as a string. */
+/**
+ * Convert a set of `Headers` into a debug string.
+ * - One `key: value` pair per line.
+ *
+ * @param headers The `Headers` object to debug.
+ * @returns A newline-separated string of `key: value` pairs.
+ * @example debugHeaders(new Headers({ "Content-Type": "text/plain" })) // "content-type: text/plain"
+ * @see https://dhoulb.github.io/shelving/util/debug/debugHeaders
+ */
 export function debugHeaders(headers) {
     return Array.from(headers, ([key, value]) => `${key}: ${value}`).join("\n");
 }
@@ -59,6 +87,11 @@ export function debugHeaders(headers) {
  * Debug a full `Request` as a string including its body.
  * - Clones the request before reading the body so the original request can still be sent or parsed later.
  * - Omits the body section when the request body is empty.
+ *
+ * @param request The `Request` to debug.
+ * @returns A promise resolving to the request line, headers, and body as a string.
+ * @example await debugFullRequest(new Request("https://x.com")) // "GET https://x.com/"
+ * @see https://dhoulb.github.io/shelving/util/debug/debugFullRequest
  */
 export async function debugFullRequest(request) {
     return _debugFullMessage(debugRequest(request), request);
@@ -68,6 +101,11 @@ export async function debugFullRequest(request) {
  * - Clones the response before reading the body so the original response can still be parsed later.
  * - Omits the headers section when there are no headers.
  * - Omits the body section when the response body is empty.
+ *
+ * @param response The `Response` to debug.
+ * @returns A promise resolving to the status line, headers, and body as a string.
+ * @example await debugFullResponse(new Response("hi", { status: 200 })) // "200 \n\nhi"
+ * @see https://dhoulb.github.io/shelving/util/debug/debugFullResponse
  */
 export async function debugFullResponse(response) {
     return _debugFullMessage(debugResponse(response), response);
@@ -108,22 +146,58 @@ async function _debugMessageBody(message) {
         return `${text}\n[read failed: ${reason?.message ?? reason}]`;
     }
 }
-/** Debug a `Request` as a string. */
+/**
+ * Convert a `Request` into a one-line debug string.
+ * - Shows the method and URL only (no headers or body).
+ *
+ * @param request The `Request` to debug.
+ * @returns A string in `METHOD url` format.
+ * @example debugRequest(new Request("https://x.com")) // "GET https://x.com/"
+ * @see https://dhoulb.github.io/shelving/util/debug/debugRequest
+ */
 export function debugRequest(request) {
     return `${request.method} ${request.url}`;
 }
-/** Debug a `Response` as a string. */
+/**
+ * Convert a `Response` into a one-line debug string.
+ * - Shows the status code and status text only (no headers or body).
+ *
+ * @param response The `Response` to debug.
+ * @returns A string in `status statusText` format.
+ * @example debugResponse(new Response("hi", { status: 404 })) // "404 Not Found"
+ * @see https://dhoulb.github.io/shelving/util/debug/debugResponse
+ */
 export function debugResponse(response) {
     return `${response.status} ${response.statusText}`;
 }
-/** Debug an array. */
+/**
+ * Convert an array into a readable debug string.
+ * - Prefixes the constructor name for non-plain arrays.
+ * - Expands items down to `depth` levels.
+ *
+ * @param value The array to debug.
+ * @param depth How many levels of nested containers to expand (defaults to `1`).
+ * @returns A human-readable string representation of the array.
+ * @example debugArray([1, 2]) // `[\n\t1,\n\t2\n]`
+ * @see https://dhoulb.github.io/shelving/util/debug/debugArray
+ */
 export function debugArray(value, depth = 1) {
     const prototype = Object.getPrototypeOf(value);
     const name = prototype === Array.prototype ? "" : prototype.constructor.name || "";
     const items = depth > 0 && value.length ? value.map(v => debug(v, depth - 1)).join(",\n\t") : "";
     return `${name ? `${name} ` : ""}${value.length ? `[\n\t${items}\n]` : "[]"}`;
 }
-/** Debug a set. */
+/**
+ * Convert a `Set` into a readable debug string.
+ * - Prefixes the constructor name and item count.
+ * - Expands items down to `depth` levels.
+ *
+ * @param value The set to debug.
+ * @param depth How many levels of nested containers to expand (defaults to `1`).
+ * @returns A human-readable string representation of the set.
+ * @example debugSet(new Set([1, 2])) // `(value.size) {\n\t1,\n\t2\n}`
+ * @see https://dhoulb.github.io/shelving/util/debug/debugSet
+ */
 export function debugSet(value, depth = 1) {
     const prototype = Object.getPrototypeOf(value);
     const name = prototype === Set.prototype ? "" : prototype.constructor.name || "Set";
@@ -134,7 +208,17 @@ export function debugSet(value, depth = 1) {
         : "";
     return `${name}(value.size) ${items ? `{\n\t${items}\n}` : "{}"}`;
 }
-/** Debug a map. */
+/**
+ * Convert a `Map` into a readable debug string.
+ * - Prefixes the constructor name and entry count.
+ * - Expands keys and values down to `depth` levels.
+ *
+ * @param value The map to debug.
+ * @param depth How many levels of nested containers to expand (defaults to `1`).
+ * @returns A human-readable string representation of the map.
+ * @example debugMap(new Map([["a", 1]])) // `(value.size) {\n\t"a": 1\n}`
+ * @see https://dhoulb.github.io/shelving/util/debug/debugMap
+ */
 export function debugMap(value, depth = 1) {
     const prototype = Object.getPrototypeOf(value);
     const name = prototype === Map.prototype ? "" : prototype.constructor.name || "Map";
@@ -145,7 +229,17 @@ export function debugMap(value, depth = 1) {
         : "";
     return `${name}(value.size) ${entries ? `{\n\t${entries}\n}` : "{}"}`;
 }
-/** Debug an object. */
+/**
+ * Convert an object into a readable debug string.
+ * - Prefixes the constructor name for non-plain objects.
+ * - Expands entries down to `depth` levels.
+ *
+ * @param value The object to debug.
+ * @param depth How many levels of nested containers to expand (defaults to `1`).
+ * @returns A human-readable string representation of the object.
+ * @example debugObject({ a: 1 }) // `{\n\t"a": 1\n}`
+ * @see https://dhoulb.github.io/shelving/util/debug/debugObject
+ */
 export function debugObject(value, depth = 1) {
     const prototype = Object.getPrototypeOf(value);
     const name = prototype === Object.prototype ? "" : prototype.constructor.name || "";
@@ -156,7 +250,16 @@ export function debugObject(value, depth = 1) {
         : "";
     return `${name ? `${name} ` : ""}${entries ? `{\n\t${entries}\n}` : "{}"}`;
 }
-/** If a string is multiline, push it onto the next line and prepend a tab to each line.. */
+/**
+ * Indent a string for nested debug output.
+ * - Multiline strings are pushed onto a new line with a tab prepended to each line.
+ * - Single-line strings are simply prefixed with a space.
+ *
+ * @param str The string to indent.
+ * @returns The indented string.
+ * @example indent("a\nb") // `\na\n\tb`
+ * @see https://dhoulb.github.io/shelving/util/debug/indent
+ */
 export function indent(str) {
     const lines = str.split("\n");
     return lines.length > 1 ? `\n${lines.join("\n\t")}` : ` ${str}`;