shelving 1.236.0 → 1.236.2

package/util/array.js

@@ -10,7 +10,17 @@ export function assertArray(value, min, max, caller = assertArray) {
             caller,
         });
 }
-/** Convert a possible array to an array. */
+/**
+ * Convert a possible array to an array.
+ *
+ * @param list The value to convert (an array is returned as-is, an iterable is collected into a new array).
+ * @returns An array of the items, or `undefined` if `list` could not be converted.
+ *
+ * @example getArray(new Set([1, 2])); // [1, 2]
+ * @example getArray(123); // undefined
+ *
+ * @see https://dhoulb.github.io/shelving/util/array/getArray
+ */
 export function getArray(list) {
     return Array.isArray(list) ? list : isIterable(list) ? Array.from(list) : undefined;
 }
@@ -19,7 +29,18 @@ export function requireArray(list, min, max, caller = requireArray) {
     assertArray(arr, min, max, caller);
     return arr;
 }
-/** Is an unknown value an item in a specified array or iterable? */
+/**
+ * Is an unknown value an item in a specified array or iterable?
+ *
+ * @param list The array or iterable to search.
+ * @param item The value to look for.
+ * @returns `true` if `item` exists in `list`, narrowing its type.
+ *
+ * @example isArrayItem([1, 2, 3], 2); // true
+ * @example isArrayItem([1, 2, 3], 9); // false
+ *
+ * @see https://dhoulb.github.io/shelving/util/array/isArrayItem
+ */
 export function isArrayItem(list, item) {
     if (isArray(list))
         list.includes(item);
@@ -28,12 +49,34 @@ export function isArrayItem(list, item) {
             return true;
     return false;
 }
-/** Assert that an unknown value is an item in a specified array. */
+/**
+ * Assert that an unknown value is an item in a specified array.
+ *
+ * @param arr The array or iterable to search.
+ * @param item The value to look for.
+ * @param caller Function to attribute a thrown error to (defaults to `assertArrayItem` itself).
+ * @throws {RequiredError} If `item` does not exist in `arr`.
+ *
+ * @example assertArrayItem([1, 2, 3], 2); // (passes)
+ * @example assertArrayItem([1, 2, 3], 9); // throws RequiredError
+ *
+ * @see https://dhoulb.github.io/shelving/util/array/assertArrayItem
+ */
 export function assertArrayItem(arr, item, caller = assertArrayItem) {
     if (!isArrayItem(arr, item))
         throw new RequiredError("Item must exist in array", { item, array: arr, caller });
 }
-/** Add multiple items to an array (immutably) and return a new array with those items (or the same array if no changes were made). */
+/**
+ * Add multiple items to an array (immutably) and return a new array with those items (or the same array if no changes were made).
+ *
+ * @param list The array or iterable to add to.
+ * @param add The items to add (items already present are skipped).
+ * @returns A new array including the added items, or the same array if nothing changed.
+ *
+ * @example withArrayItems([1, 2], 2, 3); // [1, 2, 3]
+ *
+ * @see https://dhoulb.github.io/shelving/util/array/withArrayItems
+ */
 export function withArrayItems(list, ...add) {
     const arr = Array.from(list);
     const extras = add.filter(_doesNotInclude, arr);
@@ -42,32 +85,111 @@ export function withArrayItems(list, ...add) {
 function _doesNotInclude(value) {
     return !this.includes(value);
 }
-/** Add an item to an array (immutably) and return a new array with that item (or the same array if no changes were made). */
+/**
+ * Add an item to an array (immutably) and return a new array with that item (or the same array if no changes were made).
+ *
+ * @param items The array or iterable to add to.
+ * @param add The item to add (skipped if already present).
+ * @returns A new array including the added item, or the same array if nothing changed.
+ *
+ * @example withArrayItem([1, 2], 3); // [1, 2, 3]
+ *
+ * @see https://dhoulb.github.io/shelving/util/array/withArrayItem
+ */
 export const withArrayItem = withArrayItems;
-/** Pick multiple items from an array (immutably) and return a new array with those items (or the same array if no changes were made). */
+/**
+ * Pick multiple items from an array (immutably) and return a new array with those items (or the same array if no changes were made).
+ *
+ * @param items The array or iterable to pick from.
+ * @param pick The items to keep.
+ * @returns A new array containing only the picked items, or the same array if nothing changed.
+ *
+ * @example pickArrayItems([1, 2, 3], 1, 3); // [1, 3]
+ *
+ * @see https://dhoulb.github.io/shelving/util/array/pickArrayItems
+ */
 export function pickArrayItems(items, ...pick) {
     const arr = Array.from(pickItems(items, ...pick));
     return isArray(items) && arr.length === items.length ? items : arr;
 }
-/** Pick an item from an array (immutably) and return a new array with that item (or the same array if no changes were made). */
+/**
+ * Pick an item from an array (immutably) and return a new array with that item (or the same array if no changes were made).
+ *
+ * @param items The array or iterable to pick from.
+ * @param pick The item to keep.
+ * @returns A new array containing only the picked item, or the same array if nothing changed.
+ *
+ * @example pickArrayItem([1, 2, 3], 2); // [2]
+ *
+ * @see https://dhoulb.github.io/shelving/util/array/pickArrayItem
+ */
 export const pickArrayItem = pickArrayItems;
-/** Remove multiple items from an array (immutably) and return a new array without those items (or the same array if no changes were made). */
+/**
+ * Remove multiple items from an array (immutably) and return a new array without those items (or the same array if no changes were made).
+ *
+ * @param items The array or iterable to remove from.
+ * @param omit The items to remove.
+ * @returns A new array without the omitted items, or the same array if nothing changed.
+ *
+ * @example omitArrayItems([1, 2, 3], 2); // [1, 3]
+ *
+ * @see https://dhoulb.github.io/shelving/util/array/omitArrayItems
+ */
 export function omitArrayItems(items, ...omit) {
     const filtered = Array.from(omitItems(items, ...omit));
     return isArray(items) && filtered.length === items.length ? items : filtered;
 }
-/** Remove an item from an array (immutably) and return a new array without those items (or the same array if no changes were made). */
+/**
+ * Remove an item from an array (immutably) and return a new array without that item (or the same array if no changes were made).
+ *
+ * @param items The array or iterable to remove from.
+ * @param omit The item to remove.
+ * @returns A new array without the omitted item, or the same array if nothing changed.
+ *
+ * @example omitArrayItem([1, 2, 3], 2); // [1, 3]
+ *
+ * @see https://dhoulb.github.io/shelving/util/array/omitArrayItem
+ */
 export const omitArrayItem = omitArrayItems;
-/** Toggle an item in and out of an array (immutably) and return a new array with or without the specified items (or the same array if no changes were made). */
+/**
+ * Toggle an item in and out of an array (immutably) and return a new array with or without the specified items (or the same array if no changes were made).
+ *
+ * @param items The array or iterable to toggle within.
+ * @param toggle The items to toggle (added if absent, removed if present).
+ * @returns A new array with the items toggled, or the same array if nothing changed.
+ *
+ * @example toggleArrayItems([1, 2], 2, 3); // [1, 3]
+ *
+ * @see https://dhoulb.github.io/shelving/util/array/toggleArrayItems
+ */
 export function toggleArrayItems(items, ...toggle) {
     const arr = Array.from(items);
     const extras = toggle.filter(_doesNotInclude, arr);
     const filtered = arr.filter(_doesNotInclude, toggle);
     return extras.length ? [...filtered, ...extras] : filtered.length !== arr.length ? filtered : isArray(items) ? items : arr;
 }
-/** Toggle an item in and out of an array (immutably) and return a new array with or without the specified item (or the same array if no changes were made). */
+/**
+ * Toggle an item in and out of an array (immutably) and return a new array with or without the specified item (or the same array if no changes were made).
+ *
+ * @param items The array or iterable to toggle within.
+ * @param toggle The item to toggle (added if absent, removed if present).
+ * @returns A new array with the item toggled, or the same array if nothing changed.
+ *
+ * @example toggleArrayItem([1, 2], 2); // [1]
+ *
+ * @see https://dhoulb.github.io/shelving/util/array/toggleArrayItem
+ */
 export const toggleArrayItem = toggleArrayItems;
-/** Return a shuffled version of an array or iterable. */
+/**
+ * Return a shuffled version of an array or iterable.
+ *
+ * @param items The array or iterable to shuffle.
+ * @returns A new array containing the same items in random order.
+ *
+ * @example shuffleArray([1, 2, 3]); // e.g. [2, 3, 1]
+ *
+ * @see https://dhoulb.github.io/shelving/util/array/shuffleArray
+ */
 export function shuffleArray(items) {
     const arr = Array.from(items);
     for (let i = arr.length - 1; i > 0; i--) {
@@ -79,6 +201,14 @@ export function shuffleArray(items) {
 /**
  * Add an item to an array (by reference) and return the item.
  * - Skip items that already exist.
+ *
+ * @param arr The array to add to (modified in place).
+ * @param item The item to add.
+ * @returns The added `item`.
+ *
+ * @example addArrayItem(arr, 3); // 3 (and `arr` now contains `3`)
+ *
+ * @see https://dhoulb.github.io/shelving/util/array/addArrayItem
  */
 export function addArrayItem(arr, item) {
     if (arr.indexOf(item) < 0)
@@ -88,21 +218,47 @@ export function addArrayItem(arr, item) {
 /**
  * Add multiple items to an array (by reference).
  * - Skip items that already exist.
+ *
+ * @param arr The array to add to (modified in place).
+ * @param items The items to add.
+ * @example addArrayItems(arr, 3, 4); // (`arr` now contains `3` and `4`)
+ * @see https://dhoulb.github.io/shelving/util/array/addArrayItems
  */
 export function addArrayItems(arr, ...items) {
     for (const item of items)
         if (arr.indexOf(item) < 0)
             arr.push(item);
 }
-/** Remove multiple items from an array (by reference). */
+/**
+ * Remove multiple items from an array (by reference).
+ *
+ * @param arr The array to remove from (modified in place).
+ * @param items The items to remove.
+ * @example deleteArrayItems(arr, 2, 3); // (`arr` no longer contains `2` or `3`)
+ * @see https://dhoulb.github.io/shelving/util/array/deleteArrayItems
+ */
 export function deleteArrayItems(arr, ...items) {
     for (let i = arr.length - 1; i >= 0; i--)
         if (i in arr && items.includes(arr[i]))
             arr.splice(i, 1);
 }
-/** Remove an item from an array (by reference). */
+/**
+ * Remove an item from an array (by reference).
+ *
+ * @param arr The array to remove from (modified in place).
+ * @param item The item to remove.
+ * @example deleteArrayItem(arr, 2); // (`arr` no longer contains `2`)
+ * @see https://dhoulb.github.io/shelving/util/array/deleteArrayItem
+ */
 export const deleteArrayItem = deleteArrayItems;
-/** Return an array of the unique items in an array. */
+/**
+ * Return an array of the unique items in an array.
+ *
+ * @param list The array or iterable to deduplicate.
+ * @returns A new array with duplicate items removed, or the same array if all items were already unique.
+ * @example getUniqueArray([1, 2, 2, 3]) // [1, 2, 3]
+ * @see https://dhoulb.github.io/shelving/util/array/getUniqueArray
+ */
 export function getUniqueArray(list) {
     const output = [];
     for (const item of list)
@@ -110,12 +266,28 @@ export function getUniqueArray(list) {
             output.push(item);
     return isArray(list) && list.length === output.length ? list : output;
 }
-/** Apply a limit to an array. */
+/**
+ * Apply a limit to an array.
+ *
+ * @param list The array or iterable to limit.
+ * @param limit The maximum number of items to keep.
+ * @returns An array of at most `limit` items, or the same array if it was already within the limit.
+ * @throws {RequiredError} If `list` cannot be converted to an array.
+ * @example limitArray([1, 2, 3, 4], 2) // [1, 2]
+ * @see https://dhoulb.github.io/shelving/util/array/limitArray
+ */
 export function limitArray(list, limit) {
     const arr = requireArray(list, undefined, undefined, limitArray);
     return limit > arr.length ? arr : arr.slice(0, limit);
 }
-/** Count the items in an array. */
+/**
+ * Count the items in an array.
+ *
+ * @param arr The array to count.
+ * @returns The number of items in `arr`.
+ * @example countArray([1, 2, 3]) // 3
+ * @see https://dhoulb.github.io/shelving/util/array/countArray
+ */
 export function countArray(arr) {
     return arr.length;
 }
@@ -124,32 +296,72 @@ export function interleaveArray(items, separator) {
         return items; // Return same empty array if empty or only one item.
     return Array.from(interleaveItems(items, separator));
 }
-/** Return a new array with a new value replacing a specific index in the array (or the same array if the value was unchanged). */
+/**
+ * Return a new array with a new value replacing a specific index in the array (or the same array if the value was unchanged).
+ *
+ * @param arr The array to update.
+ * @param index The index to replace.
+ * @param value The new value to set at `index`.
+ * @returns A new array with `value` at `index`, or the same array if the value was unchanged.
+ * @example withArrayIndex([1, 2, 3], 1, 9) // [1, 9, 3]
+ * @see https://dhoulb.github.io/shelving/util/array/withArrayIndex
+ */
 export function withArrayIndex(arr, index, value) {
     if (arr[index] === value)
         return arr;
     return [...arr.slice(0, index), value, ...arr.slice(index + 1)];
 }
-/** Return a new array without a specific index in the array (or the same array if the value was unchanged). */
+/**
+ * Return a new array without a specific index in the array (or the same array if the value was unchanged).
+ *
+ * @param arr The array to update.
+ * @param index The index to remove.
+ * @returns A new array without `index`, or the same array if nothing changed.
+ * @example omitArrayIndex([1, 2, 3], 1) // [1, 3]
+ * @see https://dhoulb.github.io/shelving/util/array/omitArrayIndex
+ */
 export function omitArrayIndex(arr, index) {
     const output = [...arr.slice(0, index), ...arr.slice(index + 1)];
     return arr.length !== output.length ? output : arr;
 }
-/** Get the first item from an array or iterable, or `undefined` if it didn't exist. */
+/**
+ * Get the first item from an array or iterable, or `undefined` if it didn't exist.
+ *
+ * @param items The array or iterable to read from.
+ * @returns The first item, or `undefined` if `items` is empty.
+ * @example getFirst([1, 2, 3]) // 1
+ * @see https://dhoulb.github.io/shelving/util/array/getFirst
+ */
 export function getFirst(items) {
     if (isArray(items))
         return items[0];
     for (const i of items)
         return i;
 }
-/** Get the first item from an array or iterable. */
+/**
+ * Get the first item from an array or iterable.
+ *
+ * @param items The array or iterable to read from.
+ * @param caller Function to attribute a thrown error to (defaults to `requireFirst` itself).
+ * @returns The first item.
+ * @throws {RequiredError} If `items` is empty.
+ * @example requireFirst([1, 2, 3]) // 1
+ * @see https://dhoulb.github.io/shelving/util/array/requireFirst
+ */
 export function requireFirst(items, caller = requireFirst) {
     const item = getFirst(items);
     if (item === undefined)
         throw new RequiredError("First item is required", { items: items, caller });
     return item;
 }
-/** Get the last item from an array or iterable, or `undefined` if it didn't exist. */
+/**
+ * Get the last item from an array or iterable, or `undefined` if it didn't exist.
+ *
+ * @param items The array or iterable to read from.
+ * @returns The last item, or `undefined` if `items` is empty.
+ * @example getLast([1, 2, 3]) // 3
+ * @see https://dhoulb.github.io/shelving/util/array/getLast
+ */
 export function getLast(items) {
     if (isArray(items))
         return items[items.length - 1];
@@ -159,14 +371,31 @@ export function getLast(items) {
     }
     return last;
 }
-/** Get the last item from an array or iterable. */
+/**
+ * Get the last item from an array or iterable.
+ *
+ * @param items The array or iterable to read from.
+ * @param caller Function to attribute a thrown error to (defaults to `requireLast` itself).
+ * @returns The last item.
+ * @throws {RequiredError} If `items` is empty.
+ * @example requireLast([1, 2, 3]) // 3
+ * @see https://dhoulb.github.io/shelving/util/array/requireLast
+ */
 export function requireLast(items, caller = requireLast) {
     const item = getLast(items);
     if (item === undefined)
         throw new RequiredError("Last item is required", { items, caller });
     return item;
 }
-/** Get the next item in an array or iterable. */
+/**
+ * Get the next item in an array or iterable.
+ *
+ * @param items The array or iterable to search.
+ * @param item The item to find the successor of.
+ * @returns The item following `item`, or `undefined` if `item` is missing or last.
+ * @example getNext([1, 2, 3], 2) // 3
+ * @see https://dhoulb.github.io/shelving/util/array/getNext
+ */
 export function getNext(items, item) {
     let found = false;
     for (const i of items) {
@@ -176,14 +405,32 @@ export function getNext(items, item) {
             found = true;
     }
 }
-/** Get the next item from an array or iterable. */
+/**
+ * Get the next item from an array or iterable.
+ *
+ * @param items The array or iterable to search.
+ * @param item The item to find the successor of.
+ * @param caller Function to attribute a thrown error to (defaults to `requireNext` itself).
+ * @returns The item following `item`.
+ * @throws {RequiredError} If `item` is missing or has no successor.
+ * @example requireNext([1, 2, 3], 2) // 3
+ * @see https://dhoulb.github.io/shelving/util/array/requireNext
+ */
 export function requireNext(items, item, caller = requireNext) {
     const next = getNext(items, item);
     if (next === undefined)
         throw new RequiredError("Next item is required", { item, items, caller });
     return next;
 }
-/** Get the previous item in an array or iterable. */
+/**
+ * Get the previous item in an array or iterable.
+ *
+ * @param items The array or iterable to search.
+ * @param value The item to find the predecessor of.
+ * @returns The item preceding `value`, or `undefined` if `value` is missing or first.
+ * @example getPrev([1, 2, 3], 2) // 1
+ * @see https://dhoulb.github.io/shelving/util/array/getPrev
+ */
 export function getPrev(items, value) {
     let last;
     for (const i of items) {
@@ -192,7 +439,17 @@ export function getPrev(items, value) {
         last = i;
     }
 }
-/** Get the previous item from an array or iterable. */
+/**
+ * Get the previous item from an array or iterable.
+ *
+ * @param items The array or iterable to search.
+ * @param item The item to find the predecessor of.
+ * @param caller Function to attribute a thrown error to (defaults to `requirePrev` itself).
+ * @returns The item preceding `item`.
+ * @throws {RequiredError} If `item` is missing or has no predecessor.
+ * @example requirePrev([1, 2, 3], 2) // 1
+ * @see https://dhoulb.github.io/shelving/util/array/requirePrev
+ */
 export function requirePrev(items, item, caller = requirePrev) {
     const prev = getPrev(items, item);
     if (prev === undefined)

package/util/async.d.ts

@@ -1,22 +1,65 @@
 import type { ImmutableArray } from "./array.js";
 import { type ErrorCallback, type ValueCallback } from "./function.js";
-/** Is a value an asynchronous value implementing a `then()` function. */
+/**
+ * Is a value an asynchronous value implementing a `then()` function.
+ *
+ * @param value The value to test.
+ * @returns `true` if `value` is a `PromiseLike`, narrowing its type.
+ * @see https://dhoulb.github.io/shelving/util/async/isAsync
+ */
 export declare function isAsync<T>(value: PromiseLike<T> | T): value is PromiseLike<T>;
-/** Is a value a synchronous value. */
+/**
+ * Is a value a synchronous value.
+ *
+ * @param value The value to test.
+ * @returns `true` if `value` is not a `PromiseLike`, narrowing its type.
+ * @see https://dhoulb.github.io/shelving/util/async/notAsync
+ */
 export declare function notAsync<T>(value: PromiseLike<T> | T): value is T;
 /**
  * Throw the value if it's an async (promised) value.
+ *
+ * @param value The value to unwrap.
  * @returns Synchronous (not promised) value.
  * @throws Promise if value is an asynchronous (promised) value.
+ * @example throwAsync(123) // 123
+ * @see https://dhoulb.github.io/shelving/util/async/throwAsync
  */
 export declare function throwAsync<T>(value: PromiseLike<T> | T): T;
-/** Assert an unknown value is synchronous (i.e. does not have a `.then()` method). */
+/**
+ * Assert an unknown value is synchronous (i.e. does not have a `.then()` method).
+ *
+ * @param value The value to assert.
+ * @throws {RequiredError} If `value` is a `PromiseLike`.
+ * @example assertNotAsync(123); // passes
+ * @see https://dhoulb.github.io/shelving/util/async/assertNotAsync
+ */
 export declare function assertNotAsync<T>(value: PromiseLike<T> | T): asserts value is T;
-/** Assert an unknown value is asynchronous (i.e. has a `.then()` method). */
+/**
+ * Assert an unknown value is asynchronous (i.e. has a `.then()` method).
+ *
+ * @param value The value to assert.
+ * @throws {RequiredError} If `value` is not a `PromiseLike`.
+ * @example assertAsync(Promise.resolve(1)); // passes
+ * @see https://dhoulb.github.io/shelving/util/async/assertAsync
+ */
 export declare function assertAsync<T>(value: PromiseLike<T> | T): asserts value is PromiseLike<T>;
-/** Assert that an unknown value is a `Promise` */
+/**
+ * Assert that an unknown value is a `Promise`.
+ *
+ * @param value The value to assert.
+ * @throws {RequiredError} If `value` is not a `Promise` instance.
+ * @example assertPromise(Promise.resolve(1)); // passes
+ * @see https://dhoulb.github.io/shelving/util/async/assertPromise
+ */
 export declare function assertPromise<T>(value: Promise<T> | T): asserts value is Promise<T>;
-/** Run any queued microtasks now. */
+/**
+ * Run any queued microtasks now.
+ *
+ * @returns A promise that resolves after all currently-queued microtasks have run.
+ * @example await runMicrotasks();
+ * @see https://dhoulb.github.io/shelving/util/async/runMicrotasks
+ */
 export declare function runMicrotasks(): Promise<void>;
 /**
  * Get the result of multiple promises concurrently.
@@ -29,6 +72,8 @@ export declare function runMicrotasks(): Promise<void>;
  * @param promises Values (usually async, but not necessarily) that we need to wait for.
  * @returns Array of values of all promises (in the same order/positions as input).
  * @throws {Errors} If one or more promises throws all rejection reasons after resolving all of the promises.
+ * @example const [a, b] = await awaitValues(getA(), getB());
+ * @see https://dhoulb.github.io/shelving/util/async/awaitValues
  */
 export declare function awaitValues<T extends ImmutableArray<unknown>>(...promises: T): Promise<{
     readonly [P in keyof T]: Awaited<T[P]>;
@@ -38,9 +83,19 @@ export declare function awaitValues<T extends ImmutableArray<unknown>>(...promis
  *
  * @param promises Values (usually async, but not necessarily) that we need to wait for.
  * @returns Array of rejection reasons of all promises (or empty array if no promises threw).
+ * @example const errors = await awaitErrors(getA(), getB());
+ * @see https://dhoulb.github.io/shelving/util/async/awaitErrors
  */
 export declare function awaitErrors(...promises: PromiseLike<unknown>[]): Promise<ImmutableArray<unknown>>;
-/** `Promise` designed for extending with `._resolve()` and `._reject()` methods that can be accessed by subclasses. */
+/**
+ * `Promise` designed for extending with `._resolve()` and `._reject()` methods that can be accessed by subclasses.
+ *
+ * @example
+ * class MyPromise extends BasePromise<number> {
+ * 	done() { this._resolve(123); }
+ * }
+ * @see https://dhoulb.github.io/shelving/util/async/BasePromise
+ */
 export declare abstract class BasePromise<T> extends Promise<T> {
     static get [Symbol.species](): PromiseConstructor;
     /** Resolve this promise with a value. */
@@ -49,7 +104,11 @@ export declare abstract class BasePromise<T> extends Promise<T> {
     protected readonly _reject: ErrorCallback;
     constructor();
 }
-/** Deferred allows you to access the internal resolve/reject callbacks of a `Promise` */
+/**
+ * Deferred allows you to access the internal resolve/reject callbacks of a `Promise`.
+ *
+ * @see https://dhoulb.github.io/shelving/util/async/Deferred
+ */
 export type Deferred<T = unknown> = {
     promise: Promise<T>;
     resolve: ValueCallback<T>;
@@ -58,16 +117,31 @@ export type Deferred<T = unknown> = {
 /**
  * Create a deferred to access the `resolve()` and `reject()` functions of a promise.
  * - See https://github.com/tc39/proposal-promise-with-resolvers/
+ *
+ * @returns A `Deferred` exposing the promise and its `resolve()`/`reject()` functions.
+ * @example const { promise, resolve } = createDeferred<number>();
+ * @see https://dhoulb.github.io/shelving/util/async/createDeferred
  */
 export declare function createDeferred<T = void>(): Deferred<T>;
-/** Get a promise that automatically resolves after a delay. */
+/**
+ * Get a promise that automatically resolves after a delay.
+ *
+ * @param ms The delay in milliseconds before the promise resolves.
+ * @returns A promise that resolves with `undefined` after `ms` milliseconds.
+ * @example await getDelay(300); // resolves after 300ms
+ * @see https://dhoulb.github.io/shelving/util/async/getDelay
+ */
 export declare function getDelay(ms: number): Promise<void>;
 /**
  * Get a promise that rejects with the signal's reason when an `AbortSignal` fires.
  * - Rejects immediately if the signal is already aborted.
  * - Use with `awaitRace()` to cancel a concurrent operation when a signal fires.
  *
+ * @param signal The `AbortSignal` to watch.
+ * @returns A promise that never resolves and rejects with the signal's reason when it fires.
+ * @throws The signal's `reason` when the signal aborts.
  * @example await awaitRace(getDelay(300), awaitAbort(signal));
+ * @see https://dhoulb.github.io/shelving/util/async/awaitAbort
  */
 export declare function awaitAbort(signal: AbortSignal): Promise<never>;
 /**
@@ -76,6 +150,10 @@ export declare function awaitAbort(signal: AbortSignal): Promise<never>;
  * - The losing inputs keep running (Promises cannot be cancelled), but their eventual rejection — if any — is silently absorbed instead of bubbling up as an unhandled rejection.
  * - Built for cancellation/timeout patterns, where the loser's eventual fate is genuinely uninteresting once another arm has settled. Do not use when both arms might surface meaningful errors that the caller should see.
  *
+ * @param promises The promises to race against each other.
+ * @returns A promise that settles with the first input to settle.
+ * @throws The rejection reason of the first input to settle, if it rejects.
  * @example await awaitRace(getDelay(300), awaitAbort(signal)); // delay or abort, no leaked ABORT rejection if delay wins
+ * @see https://dhoulb.github.io/shelving/util/async/awaitRace
  */
 export declare function awaitRace<T>(...promises: Promise<T>[]): Promise<T>;