shelving 1.236.0 → 1.236.2

package/util/http.js

@@ -42,12 +42,16 @@ function _parseMessageBody(message, MessageError, caller) {
 /**
  * Parse the body content of an HTTP `Request` based on its content type, or throw `RequestError` if the content could not be parsed.
  *
+ * @param request The `Request` whose body to parse.
+ * @param caller Identity of the calling function for error attribution.
  * @returns undefined If the request method is `GET` or `HEAD` (these request methods have no body).
  * @returns unknown If content type is `application/json` and has valid JSON (including `undefined` if the content is empty).
  * @returns unknown If content type is `multipart/form-data` then convert it to a simple `Data` object.
  * @returns string If content type is `text/plain` or anything else (including `""` empty string if it's empty).
  *
- * @throws RequestError if the content is not `text/plain`, or `application/json` with valid JSON.
+ * @throws {RequestError} If the content is not `text/plain`, or `application/json` with valid JSON.
+ * @example const body = await parseRequestBody(request);
+ * @see https://dhoulb.github.io/shelving/util/http/parseRequestBody
  */
 export function parseRequestBody(request, caller = parseRequestBody) {
     return _parseMessageBody(request, RequestError, caller);
@@ -55,7 +59,12 @@ export function parseRequestBody(request, caller = parseRequestBody) {
 /**
  * Parse JSON from an HTTP `Request`, or return `undefined` when the request has no body.
  *
- * @throws RequestError If the request body is not valid JSON.
+ * @param request The `Request` whose JSON body to parse.
+ * @param caller Identity of the calling function for error attribution.
+ * @returns The parsed JSON value, or `undefined` if the body is empty.
+ * @throws {RequestError} If the request body is not valid JSON.
+ * @example const data = await parseRequestJSON(request);
+ * @see https://dhoulb.github.io/shelving/util/http/parseRequestJSON
  */
 export function parseRequestJSON(request, caller = parseRequestJSON) {
     return _parseMessageJSON(request, RequestError, caller);
@@ -63,7 +72,12 @@ export function parseRequestJSON(request, caller = parseRequestJSON) {
 /**
  * Parse `FormData` from an HTTP `Request`, or return `undefined` when the request has no body.
  *
- * @throws RequestError If the request body is not valid multipart form-data.
+ * @param request The `Request` whose form-data body to parse.
+ * @param caller Identity of the calling function for error attribution.
+ * @returns The parsed `FormData`.
+ * @throws {RequestError} If the request body is not valid multipart form-data.
+ * @example const form = await parseRequestFormData(request);
+ * @see https://dhoulb.github.io/shelving/util/http/parseRequestFormData
  */
 export function parseRequestFormData(request, caller = parseRequestFormData) {
     return _parseMessageFormData(request, RequestError, caller);
@@ -71,11 +85,15 @@ export function parseRequestFormData(request, caller = parseRequestFormData) {
 /**
  * Parse the body content of an HTTP `Response` based on its content type, or throw `ResponseError` if the content could not be parsed.
  *
+ * @param response The `Response` whose body to parse.
+ * @param caller Identity of the calling function for error attribution.
  * @returns unknown If content type is `application/json` and has valid JSON (including `undefined` if the content is empty).
  * @returns unknown If content type is `multipart/form-data` then convert it to a simple `Data` object.
  * @returns string If content type is `text/plain` or anything else (including `""` empty string if it's empty).
  *
- * @throws ResponseError if the content is not `text/plain` or `application/json` with valid JSON.
+ * @throws {ResponseError} If the content is not `text/plain` or `application/json` with valid JSON.
+ * @example const body = await parseResponseBody(response);
+ * @see https://dhoulb.github.io/shelving/util/http/parseResponseBody
  */
 export function parseResponseBody(response, caller = parseResponseBody) {
     return _parseMessageBody(response, ResponseError, caller);
@@ -83,7 +101,12 @@ export function parseResponseBody(response, caller = parseResponseBody) {
 /**
  * Parse JSON from an HTTP `Response`, or return `undefined` when the response has no body.
  *
- * @throws ResponseError If the response body is not valid JSON.
+ * @param response The `Response` whose JSON body to parse.
+ * @param caller Identity of the calling function for error attribution.
+ * @returns The parsed JSON value, or `undefined` if the body is empty.
+ * @throws {ResponseError} If the response body is not valid JSON.
+ * @example const data = await parseResponseJSON(response);
+ * @see https://dhoulb.github.io/shelving/util/http/parseResponseJSON
  */
 export function parseResponseJSON(response, caller = parseResponseJSON) {
     return _parseMessageJSON(response, ResponseError, caller);
@@ -91,16 +114,26 @@ export function parseResponseJSON(response, caller = parseResponseJSON) {
 /**
  * Parse `FormData` from an HTTP `Response`, or return `undefined` when the response has no body.
  *
- * @throws ResponseError If the response body is not valid multipart form-data.
+ * @param response The `Response` whose form-data body to parse.
+ * @param caller Identity of the calling function for error attribution.
+ * @returns The parsed `FormData`.
+ * @throws {ResponseError} If the response body is not valid multipart form-data.
+ * @example const form = await parseResponseFormData(response);
+ * @see https://dhoulb.github.io/shelving/util/http/parseResponseFormData
  */
 export function parseResponseFormData(response, caller = parseResponseFormData) {
     return _parseMessageFormData(response, ResponseError, caller);
 }
 /**
  * Get an HTTP `Response` for an unknown value.
+ * - A `Response` value is returned unchanged.
+ * - `undefined` becomes a `204 No Content` response.
+ * - Anything else becomes a `200` JSON response.
  *
  * @param value The value to convert to a `Response`.
  * @returns A `Response` with a 2xx status, and response body as JSON (if it was set), or no body if `value` is `undefined`
+ * @example getResponse({ name: "abc" }) // 200 JSON Response
+ * @see https://dhoulb.github.io/shelving/util/http/getResponse
  */
 export function getResponse(value) {
     // If it's already a `Response`, return it directly.
@@ -123,7 +156,10 @@ export function getResponse(value) {
  * - Anything else returns a 500 response.
  *
  * @param reason The error value to convert to a `Response`.
- * @param debug If `true` include the error message in the response (for debugging), or `false` to return generic error codes (for security).
+ * @param debug If `true` include the error message in the response (for debugging), or `false` to return generic error codes (for security). Defaults to `false`.
+ * @returns A `Response` with a status code and (optionally) body derived from the error.
+ * @example getErrorResponse("Invalid input") // 422 Response
+ * @see https://dhoulb.github.io/shelving/util/http/getErrorResponse
  */
 export function getErrorResponse(reason, debug = false) {
     // If it's already a `Response`, return it directly.
@@ -147,11 +183,25 @@ export function getErrorResponse(reason, debug = false) {
 const _REQUEST_HEAD_METHODS = ["HEAD", "GET"];
 const _REQUEST_BODY_METHODS = ["POST", "PUT", "PATCH", "DELETE"];
 const _REQUEST_METHODS = [..._REQUEST_HEAD_METHODS, ..._REQUEST_BODY_METHODS];
-/** Check whether an HTTP Request method string is a supported request methods. */
+/**
+ * Is a string a supported HTTP request method?
+ *
+ * @param method The method string to test.
+ * @returns `true` if `method` is a supported `RequestMethod`, narrowing its type.
+ * @example isRequestMethod("GET") // true
+ * @see https://dhoulb.github.io/shelving/util/http/isRequestMethod
+ */
 export function isRequestMethod(method) {
     return _REQUEST_METHODS.includes(method);
 }
-/** Check whether an HTTP Request method string is a supported request method that never sends a body. */
+/**
+ * Is a string a supported HTTP request method that never sends a body?
+ *
+ * @param method The method string to test.
+ * @returns `true` if `method` is a supported `RequestHeadMethod`, narrowing its type.
+ * @example isRequestHeadMethod("GET") // true
+ * @see https://dhoulb.github.io/shelving/util/http/isRequestHeadMethod
+ */
 export function isRequestHeadMethod(method) {
     return _REQUEST_HEAD_METHODS.includes(method);
 }
@@ -160,6 +210,12 @@ export function isRequestHeadMethod(method) {
  * - Scalar options from `b` override `a`.
  * - Header dictionaries are merged so call-level headers override default headers by key.
  * - Abort signals are merged, so either abort signal will cancel the request.
+ *
+ * @param a The provider-level (default) request options.
+ * @param b The call-level request options whose values override `a`.
+ * @returns A merged `RequestOptions` with combined headers and abort signals.
+ * @example mergeRequestOptions({ cache: "no-store" }, { mode: "cors" }) // { cache: "no-store", mode: "cors", ... }
+ * @see https://dhoulb.github.io/shelving/util/http/mergeRequestOptions
  */
 export function mergeRequestOptions({ headers: aHeaders, signal: aSignal, ...a } = {}, { headers: bHeaders, signal: bSignal, ...b } = {}) {
     const headers = { ...aHeaders, ...bHeaders };
@@ -174,9 +230,11 @@ export function mergeRequestOptions({ headers: aHeaders, signal: aSignal, ...a }
  * @param url The target URL.
  * @param params `?query` params to encode into the URL.
  * @param options Additional request options.
+ * @param caller Function to attribute a thrown error to (defaults to `createHeadRequest`).
  * @returns A `Request` with no body content.
  *
  * @example createHeadRequest("POST", "https://api.example.com/items", { name: "abc" })
+ * @see https://dhoulb.github.io/shelving/util/http/createHeadRequest
  */
 export function createHeadRequest(method, url, params, options = {}, caller = createHeadRequest) {
     return new Request(withURIParams(requireURL(url, undefined, caller), params), { ...options, method, body: null });
@@ -190,9 +248,11 @@ export function createHeadRequest(method, url, params, options = {}, caller = cr
  * @param url The target URL.
  * @param body The plain-text request body.
  * @param options Additional request options.
+ * @param caller Function to attribute a thrown error to (defaults to `createTextRequest`).
  * @returns A `Request` with `text/plain` content type.
  *
  * @example createTextRequest("POST", "https://api.example.com/items", "hello")
+ * @see https://dhoulb.github.io/shelving/util/http/createTextRequest
  */
 export function createTextRequest(method, url, body, options = {}, caller = createTextRequest) {
     return new Request(requireURL(url, undefined, caller), { ...mergeRequestOptions(_REQUEST_TEXT_OPTIONS, options), method, body });
@@ -207,9 +267,11 @@ const _REQUEST_TEXT_OPTIONS = { headers: { "Content-Type": "text/plain" } };
  * @param url The target URL.
  * @param body The value to JSON-encode.
  * @param options Additional request options.
+ * @param caller Function to attribute a thrown error to (defaults to `createJSONRequest`).
  * @returns A `Request` with `application/json` content type.
  *
  * @example createJSONRequest("POST", "https://api.example.com/items", { name: "abc" })
+ * @see https://dhoulb.github.io/shelving/util/http/createJSONRequest
  */
 export function createJSONRequest(method, url, body, options = {}, caller = createJSONRequest) {
     return new Request(requireURL(url, undefined, caller), {
@@ -227,9 +289,11 @@ const _REQUEST_JSON_OPTIONS = { headers: { "Content-Type": "application/json" }
  * @param url The target URL.
  * @param body The `FormData` payload.
  * @param options Additional request options.
+ * @param caller Function to attribute a thrown error to (defaults to `createFormDataRequest`).
  * @returns A `Request` with a multipart body.
  *
  * @example createFormDataRequest("POST", "https://api.example.com/upload", new FormData())
+ * @see https://dhoulb.github.io/shelving/util/http/createFormDataRequest
  */
 export function createFormDataRequest(method, url, body, options = {}, caller = createFormDataRequest) {
     return new Request(requireURL(url, undefined, caller), { ...options, method, body });
@@ -243,11 +307,13 @@ export function createFormDataRequest(method, url, body, options = {}, caller =
  * @param url The target URL.
  * @param data The data object to serialize as XML.
  * @param options Additional request options.
+ * @param caller Function to attribute a thrown error to (defaults to `createXMLRequest`).
  * @returns A `Request` with `application/xml` content type.
  *
  * @throws {RequiredError} If the XML data contains invalid element names or values.
  *
  * @example createXMLRequest("POST", "https://api.example.com/items", { item: { name: "abc" } })
+ * @see https://dhoulb.github.io/shelving/util/http/createXMLRequest
  */
 export function createXMLRequest(method, url, data, options = {}, caller = createXMLRequest) {
     return new Request(requireURL(url, undefined, caller), {
@@ -266,9 +332,17 @@ const _REQUEST_XML_OPTIONS = { headers: { "Content-Type": "application/xml; char
  * - Expects a fully valid URL (any `{placeholders}` in the URL are not considered).
  * - As per the HTTP spec, `GET` and `HEAD` requests cannot contain a body
  *
- * @returns Request object.
+ * @param method The HTTP method.
+ * @param url The target URL.
+ * @param payload The body payload, whose type selects the content type.
+ * @param options Additional request options.
+ * @param caller Function to attribute a thrown error to (defaults to `createRequest`).
+ * @returns A `Request` with a content type chosen to match `payload`.
  *
  * @throws {RequiredError} if this is a `HEAD` or `GET` request but `body` is not a data object.
+ *
+ * @example createRequest("POST", "https://api.example.com/items", { name: "abc" }) // JSON Request
+ * @see https://dhoulb.github.io/shelving/util/http/createRequest
  */
 export function createRequest(method, url, payload, options = {}, caller = createRequest) {
     url = requireURL(url, undefined, caller);
@@ -289,7 +363,16 @@ export function createRequest(method, url, payload, options = {}, caller = creat
     // JSON is the default.
     return createJSONRequest(method, url, payload, options, caller);
 }
-/** Assert that the payload for a HEAD or GET method is a data object, null, or undefined. */
+/**
+ * Assert that the payload for a `HEAD` or `GET` method is a data object, `null`, or `undefined`.
+ *
+ * @param payload The payload to assert.
+ * @param method The HTTP method the payload is for (used in the error message).
+ * @param caller Function to attribute a thrown error to (defaults to `assertRequestHeadPayload`).
+ * @throws {RequiredError} If `payload` is not a data object, `null`, or `undefined`.
+ * @example assertRequestHeadPayload({ q: "abc" }, "GET"); // passes
+ * @see https://dhoulb.github.io/shelving/util/http/assertRequestHeadPayload
+ */
 export function assertRequestHeadPayload(payload, method, caller = assertRequestHeadPayload) {
     if (!isData(payload) && !isNullish(payload))
         throw new RequiredError(`Payload for ${method} request must be data object, null, or undefined`, { received: payload, caller });

package/util/hydrate.d.ts

@@ -3,9 +3,15 @@ import type { ImmutableDictionary } from "./dictionary.js";
 /**
  * A set of hydrations describes a set of string keys and the class constructor to be dehydrated and rehydrated.
  * - We can't use `class.name` because we don't know that the name of the class will survive minification.
+ *
+ * @see https://dhoulb.github.io/shelving/util/hydrate/Hydrations
  */
 export type Hydrations = ImmutableDictionary<Class<unknown>>;
-/** A dehydrated object with a `$type` key. */
+/**
+ * A dehydrated object with a `$type` key.
+ *
+ * @see https://dhoulb.github.io/shelving/util/hydrate/DehydratedObject
+ */
 export type DehydratedObject = {
     readonly $type: string;
     readonly $value: unknown;
@@ -16,6 +22,13 @@ export type DehydratedObject = {
  * - By its nature hydration is an unsafe operation.
  * - Deeply iterates into arrays and plain objects to hydrate their items and props too.
  * - Note: the recursion in this function does not currently protect against infinite loops.
+ *
+ * @param value The dehydrated value to hydrate.
+ * @param hydrations The set of `$type` keys mapped to the class constructors used to rebuild instances.
+ * @returns The hydrated value, with matched objects rebuilt as their class instances.
+ * @throws ValueError If a dehydrated object's `$type` is not matched by any constructor in `hydrations`.
+ * @example hydrate({ $type: "Date", $value: 0 }, {}) // Date instance
+ * @see https://dhoulb.github.io/shelving/util/hydrate/hydrate
  */
 export declare function hydrate(value: unknown, hydrations: Hydrations): unknown;
 /**
@@ -25,7 +38,11 @@ export declare function hydrate(value: unknown, hydrations: Hydrations): unknown
  * - Deeply iterates into arrays and plain objects to dehydrate their items and props too.
  * - Note: the recursion in this function does not currently protect against infinite loops.
  *
+ * @param value The value to dehydrate.
+ * @param hydrations The set of `$type` keys mapped to the class constructors used to recognise instances.
  * @returns The dehydrated version of the specified value.
- * @throws `Error` if the value is a class instance that cannot be dehydrated (i.e. is not matched by any constructor in `hydrations`).
+ * @throws ValueError If the value is a class instance that cannot be dehydrated (i.e. is not matched by any constructor in `hydrations`).
+ * @example dehydrate(new Date(0), {}) // { $type: "Date", $value: 0 }
+ * @see https://dhoulb.github.io/shelving/util/hydrate/dehydrate
  */
 export declare function dehydrate(value: unknown, hydrations: Hydrations): unknown;

package/util/hydrate.js

@@ -16,6 +16,13 @@ function _isDehydrated(value) {
  * - By its nature hydration is an unsafe operation.
  * - Deeply iterates into arrays and plain objects to hydrate their items and props too.
  * - Note: the recursion in this function does not currently protect against infinite loops.
+ *
+ * @param value The dehydrated value to hydrate.
+ * @param hydrations The set of `$type` keys mapped to the class constructors used to rebuild instances.
+ * @returns The hydrated value, with matched objects rebuilt as their class instances.
+ * @throws ValueError If a dehydrated object's `$type` is not matched by any constructor in `hydrations`.
+ * @example hydrate({ $type: "Date", $value: 0 }, {}) // Date instance
+ * @see https://dhoulb.github.io/shelving/util/hydrate/hydrate
  */
 export function hydrate(value, hydrations) {
     if (isArray(value))
@@ -48,8 +55,12 @@ function _hydrateProp([, v], hydrations) {
  * - Deeply iterates into arrays and plain objects to dehydrate their items and props too.
  * - Note: the recursion in this function does not currently protect against infinite loops.
  *
+ * @param value The value to dehydrate.
+ * @param hydrations The set of `$type` keys mapped to the class constructors used to recognise instances.
  * @returns The dehydrated version of the specified value.
- * @throws `Error` if the value is a class instance that cannot be dehydrated (i.e. is not matched by any constructor in `hydrations`).
+ * @throws ValueError If the value is a class instance that cannot be dehydrated (i.e. is not matched by any constructor in `hydrations`).
+ * @example dehydrate(new Date(0), {}) // { $type: "Date", $value: 0 }
+ * @see https://dhoulb.github.io/shelving/util/hydrate/dehydrate
  */
 export function dehydrate(value, hydrations) {
     if (isObject(value)) {

package/util/item.d.ts

@@ -1,26 +1,85 @@
 import type { ImmutableArray } from "./array.js";
 import type { Data } from "./data.js";
-/** Allowed types for the "id" property (identifier) for an item. */
+/**
+ * Allowed types for the "id" property (identifier) for an item.
+ *
+ * @see https://dhoulb.github.io/shelving/util/item/Identifier
+ */
 export type Identifier = string | number;
-/** An item object is a data object that includes an "id" identifier property that is either a string or number. */
+/**
+ * An item object is a data object that includes an "id" identifier property that is either a string or number.
+ *
+ * @see https://dhoulb.github.io/shelving/util/item/Item
+ */
 export type Item<I extends Identifier = Identifier, T extends Data = Data> = {
     id: I;
 } & T;
-/** Entity or `undefined` to indicate the item doesn't exist. */
+/**
+ * Item object, or `undefined` to indicate the item doesn't exist.
+ *
+ * @see https://dhoulb.github.io/shelving/util/item/OptionalItem
+ */
 export type OptionalItem<I extends Identifier = Identifier, T extends Data = Data> = Item<I, T> | undefined;
-/** An async sequence of item objects. */
+/**
+ * An async sequence of item objects.
+ *
+ * @see https://dhoulb.github.io/shelving/util/item/ItemSequence
+ */
 export type ItemSequence<I extends Identifier = Identifier, T extends Data = Data> = AsyncIterable<Item<I, T>, void, void>;
-/** An async sequence of optional item objects. */
+/**
+ * An async sequence of optional item objects.
+ *
+ * @see https://dhoulb.github.io/shelving/util/item/OptionalItemSequence
+ */
 export type OptionalItemSequence<I extends Identifier = Identifier, T extends Data = Data> = AsyncIterable<OptionalItem<I, T>, void, void>;
-/** An array of item data. */
+/**
+ * An array of item objects.
+ *
+ * @see https://dhoulb.github.io/shelving/util/item/Items
+ */
 export type Items<I extends Identifier = Identifier, T extends Data = Data> = ImmutableArray<Item<I, T>>;
-/** An async sequence of arrays of item objects. */
+/**
+ * An async sequence of arrays of item objects.
+ *
+ * @see https://dhoulb.github.io/shelving/util/item/ItemsSequence
+ */
 export type ItemsSequence<I extends Identifier = Identifier, T extends Data = Data> = AsyncIterable<Items<I, T>, void, void>;
-/** Get the identifier from an item object. */
+/**
+ * Get the identifier from an item object.
+ *
+ * @param item The item object to read the `id` from.
+ * @returns The item's `id` identifier.
+ * @example getIdentifier({ id: "abc", name: "Dave" }) // "abc"
+ * @see https://dhoulb.github.io/shelving/util/item/getIdentifier
+ */
 export declare function getIdentifier<I extends Identifier, T extends Data>({ id }: Item<I, T>): I;
-/** Get the identifiers from an iterable set item objects. */
+/**
+ * Get the identifiers from an iterable set of item objects.
+ *
+ * @param entities The iterable of item objects to read identifiers from.
+ * @returns An iterable yielding the `id` of each item.
+ * @example Array.from(getIdentifiers([{ id: "a" }, { id: "b" }])) // ["a", "b"]
+ * @see https://dhoulb.github.io/shelving/util/item/getIdentifiers
+ */
 export declare function getIdentifiers<I extends Identifier, T extends Data>(entities: Iterable<Item<I, T>>): Iterable<I>;
-/** Does a data object or data item object. */
+/**
+ * Does a data object have a given identifier (and is therefore an `Item`).
+ *
+ * @param item The data or item object to test.
+ * @param id The identifier to match against the object's `id` property.
+ * @returns `true` if `item.id` equals `id`, otherwise `false`.
+ * @example hasIdentifier({ id: "abc" }, "abc") // true
+ * @see https://dhoulb.github.io/shelving/util/item/hasIdentifier
+ */
 export declare function hasIdentifier<I extends Identifier, T extends Data>(item: T | Item<I, T>, id: I): item is Item<I, T>;
-/** Merge an ID into a set of data to make an `ItemData` */
+/**
+ * Merge an ID into a set of data to make an `Item`.
+ * - Returns the data unchanged if it already has the given `id`.
+ *
+ * @param id The identifier to set on the data.
+ * @param data The data or item object to attach the identifier to.
+ * @returns An item object with the given `id`.
+ * @example getItem("abc", { name: "Dave" }) // { name: "Dave", id: "abc" }
+ * @see https://dhoulb.github.io/shelving/util/item/getItem
+ */
 export declare function getItem<I extends Identifier, T extends Data>(id: I, data: T | Item<I, T>): Item<I, T>;

package/util/item.js

@@ -1,17 +1,48 @@
-/** Get the identifier from an item object. */
+/**
+ * Get the identifier from an item object.
+ *
+ * @param item The item object to read the `id` from.
+ * @returns The item's `id` identifier.
+ * @example getIdentifier({ id: "abc", name: "Dave" }) // "abc"
+ * @see https://dhoulb.github.io/shelving/util/item/getIdentifier
+ */
 export function getIdentifier({ id }) {
     return id;
 }
-/** Get the identifiers from an iterable set item objects. */
+/**
+ * Get the identifiers from an iterable set of item objects.
+ *
+ * @param entities The iterable of item objects to read identifiers from.
+ * @returns An iterable yielding the `id` of each item.
+ * @example Array.from(getIdentifiers([{ id: "a" }, { id: "b" }])) // ["a", "b"]
+ * @see https://dhoulb.github.io/shelving/util/item/getIdentifiers
+ */
 export function* getIdentifiers(entities) {
     for (const { id } of entities)
         yield id;
 }
-/** Does a data object or data item object. */
+/**
+ * Does a data object have a given identifier (and is therefore an `Item`).
+ *
+ * @param item The data or item object to test.
+ * @param id The identifier to match against the object's `id` property.
+ * @returns `true` if `item.id` equals `id`, otherwise `false`.
+ * @example hasIdentifier({ id: "abc" }, "abc") // true
+ * @see https://dhoulb.github.io/shelving/util/item/hasIdentifier
+ */
 export function hasIdentifier(item, id) {
     return item.id === id;
 }
-/** Merge an ID into a set of data to make an `ItemData` */
+/**
+ * Merge an ID into a set of data to make an `Item`.
+ * - Returns the data unchanged if it already has the given `id`.
+ *
+ * @param id The identifier to set on the data.
+ * @param data The data or item object to attach the identifier to.
+ * @returns An item object with the given `id`.
+ * @example getItem("abc", { name: "Dave" }) // { name: "Dave", id: "abc" }
+ * @see https://dhoulb.github.io/shelving/util/item/getItem
+ */
 export function getItem(id, data) {
     return hasIdentifier(data, id) ? data : { ...data, id };
 }

package/util/iterate.d.ts

@@ -1,39 +1,135 @@
-/** Is an unknown value an iterable? */
-export declare const isIterable: (value: unknown) => value is Iterable<unknown>;
-/** An iterable containing items or nested iterables of items. */
+/**
+ * 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 declare function isIterable(value: unknown): value is Iterable<unknown>;
+/**
+ * An iterable containing items or nested iterables of items.
+ *
+ * @see https://dhoulb.github.io/shelving/util/iterate/DeepIterable
+ */
 export type DeepIterable<T> = T | Iterable<DeepIterable<T>>;
-/** Flatten one or more iterables. */
+/**
+ * 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 declare function flattenItems<T>(items: DeepIterable<T>): Iterable<T>;
 /**
  * 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 declare function hasItems(items: Iterable<unknown>): boolean;
-/** 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 declare function countItems(items: Iterable<unknown>): number;
 /**
  * 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 declare function getRange(start: number, end: number): Iterable<number>;
 /**
  * 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 declare function limitItems<T>(items: Iterable<T>, limit: number): Iterable<T>;
-/** 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 declare function pickItems<T>(items: Iterable<T>, ...pick: T[]): Iterable<T>;
-/** 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 declare function omitItems<T>(items: Iterable<T>, ...omit: T[]): Iterable<T>;
-/** Reduce an iterable set of items using a reducer function. */
+/**
+ * Reduce an iterable set of items using a reducer function.
+ * - Calls `reducer` for each item, threading the accumulated value through.
+ *
+ * @param items The iterable to reduce.
+ * @param reducer Reducer called with the previous accumulated value and the current item, returning the next accumulated value.
+ * @param initial The initial accumulated value.
+ * @returns The final accumulated value, or `undefined` if the iterable is empty and no `initial` was given.
+ * @example reduceItems([1, 2, 3], (a, b) => a + b, 0) // 6
+ * @see https://dhoulb.github.io/shelving/util/iterate/reduceItems
+ */
 export declare function reduceItems<T>(items: Iterable<T>, reducer: (previous: T, item: T) => T, initial: T): T;
 export declare function reduceItems<T>(items: Iterable<T>, reducer: (previous: T | undefined, item: T) => T, initial?: T): T | undefined;
 export declare function reduceItems<I, O>(items: Iterable<I>, reducer: (previous: O, item: I) => O, initial: O): O;
 export declare function reduceItems<I, O>(items: Iterable<I>, reducer: (previous: O | undefined, item: I) => O, initial?: O): O | undefined;
-/** 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 declare function getChunks<T>(items: Iterable<T>, size: number): Iterable<readonly T[]>;
-/** 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 declare function mergeItems<T>(...inputs: [Iterable<T>, Iterable<T>, ...Iterable<T>[]]): Iterable<T>;
-/** Interleave items with a separator, i.e. `[item1, separator, item2, separator, item3]` */
+/**
+ * Interleave items with a separator, i.e. `[item1, separator, item2, separator, item3]`
+ *
+ * @param items The iterable to interleave.
+ * @param separator The value to insert between each pair of items.
+ * @returns An iterable yielding the items with `separator` between them.
+ * @example Array.from(interleaveItems([1, 2, 3], 0)) // [1, 0, 2, 0, 3]
+ * @see https://dhoulb.github.io/shelving/util/iterate/interleaveItems
+ */
 export declare function interleaveItems<T>(items: Iterable<T>, separator: T): Iterable<T>;
 export declare function interleaveItems<A, B>(items: Iterable<A>, separator: B): Iterable<A | B>;