shelving 1.236.0 → 1.236.2

package/util/iterate.js

@@ -1,6 +1,21 @@
-/** Is an unknown value an iterable? */
-export const isIterable = (value) => typeof value === "object" && !!value && Symbol.iterator in value;
-/** Flatten one or more iterables. */
+/**
+ * Is an unknown value an iterable?
+ *
+ * @param value The value to test.
+ * @returns `true` if `value` is an object with a `Symbol.iterator` method, otherwise `false`.
+ * @see https://dhoulb.github.io/shelving/util/iterate/isIterable
+ */
+export function isIterable(value) {
+    return typeof value === "object" && !!value && Symbol.iterator in value;
+}
+/**
+ * Flatten one or more (possibly nested) iterables into a flat sequence of items.
+ *
+ * @param items The item or deeply-nested iterable of items to flatten.
+ * @returns An iterable yielding every leaf item in order.
+ * @example Array.from(flattenItems([1, [2, [3, 4]]])) // [1, 2, 3, 4]
+ * @see https://dhoulb.github.io/shelving/util/iterate/flattenItems
+ */
 export function* flattenItems(items) {
     if (isIterable(items))
         for (const item of items)
@@ -10,14 +25,27 @@ export function* flattenItems(items) {
 }
 /**
  * Does an iterable have one or more items.
- * - Checks `items.size` or `items.length` first, or consumes the iterable and counts its iterations.
+ * - Stops as soon as the first item is found, so it never fully consumes the iterable.
+ *
+ * @param items The iterable to test.
+ * @returns `true` if the iterable yields at least one item, otherwise `false`.
+ * @example hasItems([1, 2, 3]) // true
+ * @see https://dhoulb.github.io/shelving/util/iterate/hasItems
  */
 export function hasItems(items) {
     for (const _unused of items)
         return true;
     return false;
 }
-/** Count the number of items in an iterable. */
+/**
+ * Count the number of items in an iterable.
+ * - Fully consumes the iterable to count its iterations.
+ *
+ * @param items The iterable to count.
+ * @returns The number of items yielded by the iterable.
+ * @example countItems([1, 2, 3]) // 3
+ * @see https://dhoulb.github.io/shelving/util/iterate/countItems
+ */
 export function countItems(items) {
     let count = 0;
     for (const _unused of items)
@@ -27,6 +55,13 @@ export function countItems(items) {
 /**
  * Yield a range of numbers from `start` to `end`
  * - Yields in descending order if `end` is lower than `start`
+ * - Both `start` and `end` are inclusive.
+ *
+ * @param start The first number to yield.
+ * @param end The last number to yield (inclusive).
+ * @returns An iterable yielding the numbers between `start` and `end`.
+ * @example Array.from(getRange(1, 4)) // [1, 2, 3, 4]
+ * @see https://dhoulb.github.io/shelving/util/iterate/getRange
  */
 export function* getRange(start, end) {
     if (start <= end)
@@ -38,7 +73,13 @@ export function* getRange(start, end) {
 }
 /**
  * Apply a limit to an iterable set of items.
- * - Checks `items.size` or `items.length` first to see if the limit is necessary.
+ * - Stops yielding once `limit` items have been produced.
+ *
+ * @param items The iterable to limit.
+ * @param limit The maximum number of items to yield.
+ * @returns An iterable yielding at most `limit` items.
+ * @example Array.from(limitItems([1, 2, 3, 4], 2)) // [1, 2]
+ * @see https://dhoulb.github.io/shelving/util/iterate/limitItems
  */
 export function* limitItems(items, limit) {
     let count = 0;
@@ -51,13 +92,31 @@ export function* limitItems(items, limit) {
             return;
     }
 }
-/** Pick items from an iterable set of items. */
+/**
+ * Pick items from an iterable set of items.
+ * - Only yields items that appear in the `pick` list.
+ *
+ * @param items The iterable to filter.
+ * @param pick The items to keep.
+ * @returns An iterable yielding only the items found in `pick`.
+ * @example Array.from(pickItems([1, 2, 3], 1, 3)) // [1, 3]
+ * @see https://dhoulb.github.io/shelving/util/iterate/pickItems
+ */
 export function* pickItems(items, ...pick) {
     for (const item of items)
         if (pick.includes(item))
             yield item;
 }
-/** Omit items from an iterable set of items. */
+/**
+ * Omit items from an iterable set of items.
+ * - Yields every item except those that appear in the `omit` list.
+ *
+ * @param items The iterable to filter.
+ * @param omit The items to remove.
+ * @returns An iterable yielding every item not found in `omit`.
+ * @example Array.from(omitItems([1, 2, 3], 2)) // [1, 3]
+ * @see https://dhoulb.github.io/shelving/util/iterate/omitItems
+ */
 export function* omitItems(items, ...omit) {
     for (const item of items)
         if (!omit.includes(item))
@@ -69,7 +128,16 @@ export function reduceItems(items, reducer, initial) {
         current = reducer(current, item);
     return current;
 }
-/** Yield chunks of a given size. */
+/**
+ * Yield chunks of a given size.
+ * - The final chunk may contain fewer than `size` items.
+ *
+ * @param items The iterable to split into chunks.
+ * @param size The maximum number of items per chunk.
+ * @returns An iterable yielding arrays of up to `size` items.
+ * @example Array.from(getChunks([1, 2, 3, 4, 5], 2)) // [[1, 2], [3, 4], [5]]
+ * @see https://dhoulb.github.io/shelving/util/iterate/getChunks
+ */
 export function* getChunks(items, size) {
     let chunk = [];
     for (const item of items) {
@@ -82,7 +150,15 @@ export function* getChunks(items, size) {
     if (chunk.length)
         yield chunk;
 }
-/** Merge two or more iterables into a single iterable set. */
+/**
+ * Merge two or more iterables into a single iterable set.
+ * - Yields all items from each input in order.
+ *
+ * @param inputs Two or more iterables to merge.
+ * @returns An iterable yielding every item from each input in sequence.
+ * @example Array.from(mergeItems([1, 2], [3, 4])) // [1, 2, 3, 4]
+ * @see https://dhoulb.github.io/shelving/util/iterate/mergeItems
+ */
 export function* mergeItems(...inputs) {
     for (const input of inputs)
         yield* input;

package/util/jwt.d.ts

@@ -2,6 +2,12 @@ import { type Bytes, type PossibleBytes } from "./bytes.js";
 import type { Data } from "./data.js";
 import { type PossibleDate } from "./date.js";
 import type { AnyCaller } from "./function.js";
+/**
+ * Claims payload accepted when encoding a JWT.
+ * - Extends `Data`, so any additional custom claims may be included alongside the standard `iat` / `nbf` / `exp` fields.
+ *
+ * @see https://dhoulb.github.io/shelving/util/jwt/TokenClaims
+ */
 export interface TokenClaims extends Data {
     /**
      * "Issued at" date (defaults to "now").
@@ -23,15 +29,21 @@ export interface TokenClaims extends Data {
 /**
  * Encode a JWT and return the string token.
  * - Currently only supports HMAC SHA-512 signing.
+ * - The `exp` claim defaults to 30 days from now, and `iat` / `nbf` default to "now".
  *
- * @param claims The payload claims to include in the JWT.
- * @param secret The secret key to sign the JWT with.
- * @param expiry The expiry time in milliseconds (defaults to 30 days).
- *
- * @throws ValueError If the input parameters, e.g. `secret` or `issuer`, are invalid.
+ * @param claims The payload claims to include in the JWT, including optional `iat`, `nbf`, and `exp` values.
+ * @param secret The secret key to sign the JWT with (minimum 64 bytes / 512 bits).
+ * @returns A promise resolving to the signed JWT string token.
+ * @throws ValueError If the `secret` is not a byte sequence of at least 64 bytes.
+ * @example const token = await encodeToken({ sub: "user1" }, secret)
+ * @see https://dhoulb.github.io/shelving/util/jwt/encodeToken
  */
 export declare function encodeToken({ nbf, iat, exp, ...claims }: TokenClaims, secret: PossibleBytes): Promise<string>;
-/** Parts that make up a JSON Web Token. */
+/**
+ * Parts that make up a JSON Web Token — the raw encoded segments plus their decoded contents.
+ *
+ * @see https://dhoulb.github.io/shelving/util/jwt/TokenData
+ */
 export type TokenData = {
     header: string;
     payload: string;
@@ -42,22 +54,39 @@ export type TokenData = {
 };
 /**
  * Split a JSON Web Token into its header, payload, and signature, and decode and parse the JSON.
+ * - Does not verify the signature — use `verifyToken` for that.
+ *
+ * @param token The JWT string to split and decode.
+ * @param caller Identity of the calling function for error attribution.
+ * @returns A `TokenData` object with the raw segments and their decoded header, payload, and signature.
+ * @throws UnauthorizedError If the token is malformed, or its segments are not valid Base64URL-encoded JSON.
+ * @example splitToken("aaa.bbb.ccc") // { header, payload, signature, headerData, payloadData, signatureBytes }
+ * @see https://dhoulb.github.io/shelving/util/jwt/splitToken
  */
 export declare function splitToken(token: string, caller?: AnyCaller): TokenData;
 /**
  * Decode a JWT, verify it, and return the full payload data.
  * - Currently only supports HMAC SHA-512 signing.
+ * - Allows a small amount of clock skew when checking `nbf` and `exp`.
  *
- * @throws ValueError If the input parameters, e.g. `secret` or `issuer`, are invalid.
- * @throws UnauthorizedError If the token is invalid or malformed.
- * @throws UnauthorizedError If the token signature is incorrect, token is expired or not issued yet.
+ * @param token The JWT string to verify.
+ * @param secret The secret key to verify the JWT signature with (minimum 64 bytes / 512 bits).
+ * @param caller Identity of the calling function for error attribution.
+ * @returns A promise resolving to the decoded payload claims.
+ * @throws ValueError If the `secret` is not a byte sequence of at least 64 bytes.
+ * @throws UnauthorizedError If the token is malformed, the signature is incorrect, or the token is expired or not yet valid.
+ * @example const { sub } = await verifyToken(token, secret)
+ * @see https://dhoulb.github.io/shelving/util/jwt/verifyToken
  */
 export declare function verifyToken(token: string, secret: PossibleBytes, caller?: AnyCaller): Promise<Data>;
 /**
  * Set the `Authorization: Bearer {token}` on a `Request` object (by reference).
  *
  * @param request The `Request` object to set the token on.
+ * @param token The JWT string to set in the `Authorization` header.
  * @returns The same `Request` object that was passed in.
+ * @example setRequestToken(request, token)
+ * @see https://dhoulb.github.io/shelving/util/jwt/setRequestToken
  */
 export declare function setRequestToken(request: Request, token: string): Request;
 /**
@@ -65,14 +94,19 @@ export declare function setRequestToken(request: Request, token: string): Reques
  *
  * @param request The `Request` object possibly containing an `Authorization: Bearer {token}` header to extract the token from.
  * @returns The string token extracted from the `Authorization` header, or `undefined` if not set.
+ * @example getRequestToken(request) // "eyJ..." or undefined
+ * @see https://dhoulb.github.io/shelving/util/jwt/getRequestToken
  */
 export declare function getRequestToken(request: Request): string | undefined;
 /**
  * Extract the `Authorization: Bearer {token}` from a `Request` object, or throw `UnauthorizedError` if not set or malformed.
  *
  * @param request The `Request` object containing an `Authorization: Bearer {token}` header to extract the token from.
+ * @param caller Identity of the calling function for error attribution.
  * @returns The string token extracted from the `Authorization` header.
  * @throws UnauthorizedError If the `Authorization` header is not set, or the JWT it contains is not well-formed.
+ * @example requireRequestToken(request) // "eyJ..."
+ * @see https://dhoulb.github.io/shelving/util/jwt/requireRequestToken
  */
 export declare function requireRequestToken(request: Request, caller?: AnyCaller): string;
 /**
@@ -81,10 +115,10 @@ export declare function requireRequestToken(request: Request, caller?: AnyCaller
  *
  * @param request The `Request` object containing an `Authorization: Bearer {token}` header to extract the token from.
  * @param secret The secret key to verify the JWT signature with.
- *
- * @returns The decoded payload data from the JWT.
+ * @param caller Identity of the calling function for error attribution.
+ * @returns A promise resolving to the decoded payload data from the JWT.
  * @throws UnauthorizedError If the `Authorization` header is not set, the JWT it contains is not well-formed, or the JWT signature is invalid.
- *
- * @example `const { sub, iss, customClaim } = await verifyRequestToken(request, secret);`
+ * @example const { sub, iss, customClaim } = await verifyRequestToken(request, secret)
+ * @see https://dhoulb.github.io/shelving/util/jwt/verifyRequestToken
  */
 export declare function verifyRequestToken(request: Request, secret: PossibleBytes, caller?: AnyCaller): Promise<Data>;

package/util/jwt.js

@@ -22,12 +22,14 @@ function _getKey(caller, secret, ...usages) {
 /**
  * Encode a JWT and return the string token.
  * - Currently only supports HMAC SHA-512 signing.
+ * - The `exp` claim defaults to 30 days from now, and `iat` / `nbf` default to "now".
  *
- * @param claims The payload claims to include in the JWT.
- * @param secret The secret key to sign the JWT with.
- * @param expiry The expiry time in milliseconds (defaults to 30 days).
- *
- * @throws ValueError If the input parameters, e.g. `secret` or `issuer`, are invalid.
+ * @param claims The payload claims to include in the JWT, including optional `iat`, `nbf`, and `exp` values.
+ * @param secret The secret key to sign the JWT with (minimum 64 bytes / 512 bits).
+ * @returns A promise resolving to the signed JWT string token.
+ * @throws ValueError If the `secret` is not a byte sequence of at least 64 bytes.
+ * @example const token = await encodeToken({ sub: "user1" }, secret)
+ * @see https://dhoulb.github.io/shelving/util/jwt/encodeToken
  */
 export async function encodeToken({ nbf = "now", iat = "now", exp = DAY * 30, ...claims }, secret) {
     // Encode header.
@@ -47,6 +49,14 @@ export async function encodeToken({ nbf = "now", iat = "now", exp = DAY * 30, ..
 }
 /**
  * Split a JSON Web Token into its header, payload, and signature, and decode and parse the JSON.
+ * - Does not verify the signature — use `verifyToken` for that.
+ *
+ * @param token The JWT string to split and decode.
+ * @param caller Identity of the calling function for error attribution.
+ * @returns A `TokenData` object with the raw segments and their decoded header, payload, and signature.
+ * @throws UnauthorizedError If the token is malformed, or its segments are not valid Base64URL-encoded JSON.
+ * @example splitToken("aaa.bbb.ccc") // { header, payload, signature, headerData, payloadData, signatureBytes }
+ * @see https://dhoulb.github.io/shelving/util/jwt/splitToken
  */
 export function splitToken(token, caller = splitToken) {
     // Split token.
@@ -82,10 +92,16 @@ export function splitToken(token, caller = splitToken) {
 /**
  * Decode a JWT, verify it, and return the full payload data.
  * - Currently only supports HMAC SHA-512 signing.
+ * - Allows a small amount of clock skew when checking `nbf` and `exp`.
  *
- * @throws ValueError If the input parameters, e.g. `secret` or `issuer`, are invalid.
- * @throws UnauthorizedError If the token is invalid or malformed.
- * @throws UnauthorizedError If the token signature is incorrect, token is expired or not issued yet.
+ * @param token The JWT string to verify.
+ * @param secret The secret key to verify the JWT signature with (minimum 64 bytes / 512 bits).
+ * @param caller Identity of the calling function for error attribution.
+ * @returns A promise resolving to the decoded payload claims.
+ * @throws ValueError If the `secret` is not a byte sequence of at least 64 bytes.
+ * @throws UnauthorizedError If the token is malformed, the signature is incorrect, or the token is expired or not yet valid.
+ * @example const { sub } = await verifyToken(token, secret)
+ * @see https://dhoulb.github.io/shelving/util/jwt/verifyToken
  */
 export async function verifyToken(token, secret, caller = verifyToken) {
     const { header, payload, signature, headerData, payloadData } = splitToken(token, caller);
@@ -112,7 +128,10 @@ export async function verifyToken(token, secret, caller = verifyToken) {
  * Set the `Authorization: Bearer {token}` on a `Request` object (by reference).
  *
  * @param request The `Request` object to set the token on.
+ * @param token The JWT string to set in the `Authorization` header.
  * @returns The same `Request` object that was passed in.
+ * @example setRequestToken(request, token)
+ * @see https://dhoulb.github.io/shelving/util/jwt/setRequestToken
  */
 export function setRequestToken(request, token) {
     request.headers.set("Authorization", `Bearer ${token}`);
@@ -123,6 +142,8 @@ export function setRequestToken(request, token) {
  *
  * @param request The `Request` object possibly containing an `Authorization: Bearer {token}` header to extract the token from.
  * @returns The string token extracted from the `Authorization` header, or `undefined` if not set.
+ * @example getRequestToken(request) // "eyJ..." or undefined
+ * @see https://dhoulb.github.io/shelving/util/jwt/getRequestToken
  */
 export function getRequestToken(request) {
     const auth = request.headers.get("Authorization");
@@ -133,8 +154,11 @@ export function getRequestToken(request) {
  * Extract the `Authorization: Bearer {token}` from a `Request` object, or throw `UnauthorizedError` if not set or malformed.
  *
  * @param request The `Request` object containing an `Authorization: Bearer {token}` header to extract the token from.
+ * @param caller Identity of the calling function for error attribution.
  * @returns The string token extracted from the `Authorization` header.
  * @throws UnauthorizedError If the `Authorization` header is not set, or the JWT it contains is not well-formed.
+ * @example requireRequestToken(request) // "eyJ..."
+ * @see https://dhoulb.github.io/shelving/util/jwt/requireRequestToken
  */
 export function requireRequestToken(request, caller = requireRequestToken) {
     const token = getRequestToken(request);
@@ -148,11 +172,11 @@ export function requireRequestToken(request, caller = requireRequestToken) {
  *
  * @param request The `Request` object containing an `Authorization: Bearer {token}` header to extract the token from.
  * @param secret The secret key to verify the JWT signature with.
- *
- * @returns The decoded payload data from the JWT.
+ * @param caller Identity of the calling function for error attribution.
+ * @returns A promise resolving to the decoded payload data from the JWT.
  * @throws UnauthorizedError If the `Authorization` header is not set, the JWT it contains is not well-formed, or the JWT signature is invalid.
- *
- * @example `const { sub, iss, customClaim } = await verifyRequestToken(request, secret);`
+ * @example const { sub, iss, customClaim } = await verifyRequestToken(request, secret)
+ * @see https://dhoulb.github.io/shelving/util/jwt/verifyRequestToken
  */
 export function verifyRequestToken(request, secret, caller = verifyRequestToken) {
     const token = requireRequestToken(request, caller);

package/util/lazy.d.ts

@@ -1,18 +1,21 @@
 import type { Arguments } from "./function.js";
 /**
  * Lazy value: a plain value, or an initialiser function that returns that value.
- * @param ...args Any arguments the lazy value needs if it's a function.
+ *
+ * @see https://dhoulb.github.io/shelving/util/lazy/Lazy
  */
 export type Lazy<T, A extends Arguments = []> = ((...args: A) => T) | T;
 /**
  * Initialise a lazy value.
+ * - If `value` is a plain value, that value is returned.
+ * - If `value` is a function, it is called with `args` and its returned value is returned.
  *
  * @param value The lazy value to resolve.
- * - If this is a plain value, that value is returned.
- * - If this is a function, it is called and its returned value is returned.
- *
- * @param ...args Any additional arguments the initialiser needs.
- * - This array of values is passed into the function or class constructor as its parameters.
+ * @param args Any additional arguments passed into the initialiser function as its parameters.
+ * @returns The resolved value.
+ * @example getLazy(() => 123) // 123
+ * @example getLazy(123) // 123
+ * @see https://dhoulb.github.io/shelving/util/lazy/getLazy
  */
 export declare function getLazy<T, A extends Arguments>(value: (...args: A) => T, ...args: A): T;
 export declare function getLazy<T, A extends Arguments>(value: Lazy<T, A>, ...args: A): T;

package/util/link.d.ts

@@ -2,7 +2,11 @@ import type { AnyCaller } from "./function.js";
 import type { Nullish } from "./null.js";
 import { type ImmutableURI, type PossibleURI } from "./uri.js";
 import { type ImmutableURL } from "./url.js";
-/** Anything that can be turned into an `<a href>` */
+/**
+ * Anything that can be turned into an `<a href>`.
+ *
+ * @see https://dhoulb.github.io/shelving/util/link/PossibleLink
+ */
 export type PossibleLink = PossibleURI;
 /**
  * Resolve a possible link to an absolute URI string, or return `undefined` if resolution fails.
@@ -26,6 +30,7 @@ export type PossibleLink = PossibleURI;
  * @example getLink("/schema", pageURL, siteRoot) // → "https://x.com/app/schema" when siteRoot is "https://x.com/app/"
  * @example getLink("./db", new URL("https://x.com/app/schema/")) // → "https://x.com/app/schema/db"
  * @example getLink("mailto:a@b") // → "mailto:a@b"
+ * @see https://dhoulb.github.io/shelving/util/link/getLink
  */
 export declare function getLink(href: Nullish<PossibleLink>, url?: ImmutableURL, root?: ImmutableURL | undefined): ImmutableURI | undefined;
 /**
@@ -36,8 +41,10 @@ export declare function getLink(href: Nullish<PossibleLink>, url?: ImmutableURL,
  * @param href The link to resolve.
  * @param url The current page URL — base for relative refs and scheme-prefixed URIs.
  * @param root The site root URL — base for absolute paths. Defaults to `url`.
- * @param caller Identity of the calling function for error attribution.
+ * @param caller Function to attribute a thrown error to (defaults to `requireLink` itself).
  * @returns An absolute URI string.
- * @throws `RequiredError` if `link` cannot be resolved.
+ * @throws {RequiredError} If `href` cannot be resolved.
+ * @example requireLink("mailto:a@b") // → "mailto:a@b"
+ * @see https://dhoulb.github.io/shelving/util/link/requireLink
  */
 export declare function requireLink(href: PossibleLink, url?: ImmutableURL, root?: ImmutableURL, caller?: AnyCaller): ImmutableURI;

package/util/link.js

@@ -24,6 +24,7 @@ import { getBasedURI, getURL } from "./url.js";
  * @example getLink("/schema", pageURL, siteRoot) // → "https://x.com/app/schema" when siteRoot is "https://x.com/app/"
  * @example getLink("./db", new URL("https://x.com/app/schema/")) // → "https://x.com/app/schema/db"
  * @example getLink("mailto:a@b") // → "mailto:a@b"
+ * @see https://dhoulb.github.io/shelving/util/link/getLink
  */
 export function getLink(href, url, root = url) {
     if (!href)
@@ -45,9 +46,11 @@ export function getLink(href, url, root = url) {
  * @param href The link to resolve.
  * @param url The current page URL — base for relative refs and scheme-prefixed URIs.
  * @param root The site root URL — base for absolute paths. Defaults to `url`.
- * @param caller Identity of the calling function for error attribution.
+ * @param caller Function to attribute a thrown error to (defaults to `requireLink` itself).
  * @returns An absolute URI string.
- * @throws `RequiredError` if `link` cannot be resolved.
+ * @throws {RequiredError} If `href` cannot be resolved.
+ * @example requireLink("mailto:a@b") // → "mailto:a@b"
+ * @see https://dhoulb.github.io/shelving/util/link/requireLink
  */
 export function requireLink(href, url, root, caller = requireLink) {
     const uri = getLink(href, url, root);

package/util/log.d.ts

@@ -1,7 +1,30 @@
 /** biome-ignore-all lint/suspicious/noConsole: This file's purpose is to write logs. */
-/** Log a `Request` */
+/**
+ * Log a `Request` to the console.
+ *
+ * @param request The `Request` to log.
+ * @returns A promise that resolves once the request has been logged.
+ * @example await logRequest(request)
+ * @see https://dhoulb.github.io/shelving/util/log/logRequest
+ */
 export declare function logRequest(request: Request): Promise<void>;
-/** Log a `Response` to a `Request` */
+/**
+ * Log a `Response` to a `Request` to the console.
+ *
+ * @param response The `Response` to log.
+ * @param request The originating `Request`, included in the log for context.
+ * @returns A promise that resolves once the response has been logged.
+ * @example await logRequestResponse(response, request)
+ * @see https://dhoulb.github.io/shelving/util/log/logRequestResponse
+ */
 export declare function logRequestResponse(response: Response, request: Request): Promise<void>;
-/** Log an `Error` from a `Request` */
+/**
+ * Log an `Error` from a `Request` to the console.
+ *
+ * @param reason The error value to log.
+ * @param request The originating `Request`, included in the log for context.
+ * @returns Nothing.
+ * @example logRequestError(error, request)
+ * @see https://dhoulb.github.io/shelving/util/log/logRequestError
+ */
 export declare function logRequestError(reason: unknown, request: Request): void;

package/util/log.js

@@ -1,15 +1,38 @@
 /** biome-ignore-all lint/suspicious/noConsole: This file's purpose is to write logs. */
 import { ANSI_FAILURE, ANSI_LEFT, ANSI_RIGHT } from "./ansi.js";
 import { debug, debugFullRequest, debugFullResponse, debugRequest } from "./debug.js";
-/** Log a `Request` */
+/**
+ * Log a `Request` to the console.
+ *
+ * @param request The `Request` to log.
+ * @returns A promise that resolves once the request has been logged.
+ * @example await logRequest(request)
+ * @see https://dhoulb.github.io/shelving/util/log/logRequest
+ */
 export async function logRequest(request) {
     console.log(`${ANSI_RIGHT} ${await debugFullRequest(request)}`);
 }
-/** Log a `Response` to a `Request` */
+/**
+ * Log a `Response` to a `Request` to the console.
+ *
+ * @param response The `Response` to log.
+ * @param request The originating `Request`, included in the log for context.
+ * @returns A promise that resolves once the response has been logged.
+ * @example await logRequestResponse(response, request)
+ * @see https://dhoulb.github.io/shelving/util/log/logRequestResponse
+ */
 export async function logRequestResponse(response, request) {
     console.log(`${ANSI_LEFT} ${debugRequest(request)}\n\n${await debugFullResponse(response)}`);
 }
-/** Log an `Error` from a `Request` */
+/**
+ * Log an `Error` from a `Request` to the console.
+ *
+ * @param reason The error value to log.
+ * @param request The originating `Request`, included in the log for context.
+ * @returns Nothing.
+ * @example logRequestError(error, request)
+ * @see https://dhoulb.github.io/shelving/util/log/logRequestError
+ */
 export function logRequestError(reason, request) {
     console.error(`${ANSI_FAILURE} ${debugRequest(request)}\n\n${debug(reason)}`);
 }