shelving 1.236.0 → 1.236.2

package/util/sequence.d.ts

@@ -1,22 +1,65 @@
 import { ABORT } from "./constants.js";
 import type { ErrorCallback, ValueCallback } from "./function.js";
+/**
+ * Result of an iterator that was aborted via an external signal rather than concluding itself.
+ * - `done` is the `ABORT` symbol, distinguishing it from an iterator's own `done: true` result.
+ *
+ * @see https://dhoulb.github.io/shelving/util/sequence/IteratorAbortResult
+ */
 export interface IteratorAbortResult<R> {
+    /** Always the `ABORT` symbol, marking this result as an external abort rather than the iterator finishing. */
     done: typeof ABORT;
+    /** The value the abort signal resolved with. */
     value: R;
 }
-/** An extension of  */
+/**
+ * Result of stepping an iterator that may either yield, finish itself, or be aborted externally.
+ * - Union of a normal `IteratorResult<T, R>` and an `IteratorAbortResult<R>`.
+ *
+ * @see https://dhoulb.github.io/shelving/util/sequence/IteratorAbortableResult
+ */
 export type IteratorAbortableResult<T, R> = IteratorResult<T, R> | IteratorAbortResult<R>;
 /**
  * Is a value an async iterable object?
- * - Any object with a `Symbol.iterator` property is iterable.
- * - Note: Array and Map instances etc will return true because they implement `Symbol.iterator`
+ * - Any object with a `Symbol.asyncIterator` property is an async iterable.
+ *
+ * @param value The value to test.
+ * @returns `true` if `value` is an `AsyncIterable`, narrowing its type.
+ * @example isSequence((async function* () {})()) // true
+ * @see https://dhoulb.github.io/shelving/util/sequence/isSequence
  */
 export declare function isSequence(value: unknown): value is AsyncIterable<unknown>;
-/** Infinite sequence that yields until a `SIGNAL` is received. */
+/**
+ * Infinite sequence that relays a source sequence until one of the abort signals resolves.
+ * - Races each step of `source` against the supplied signal promises; when a signal wins, tells the source iterator to clean up and returns the signal's value.
+ *
+ * @param source The source sequence to relay values from.
+ * @param signals One or more promises that, when resolved, abort the relay and end the sequence.
+ * @returns The value the winning abort signal resolved with, or the source's own return value if it finishes first.
+ * @throws {UnexpectedError} If the source iterator's `return()` does not return a `done` result.
+ * @example for await (const item of repeatUntil(source, stopSignal)) doSomething(item);
+ * @see https://dhoulb.github.io/shelving/util/sequence/repeatUntil
+ */
 export declare function repeatUntil<T = void, R = void, N = void>(source: AsyncIterable<T, R | undefined, N | undefined>, ...signals: [PromiseLike<R>, ...PromiseLike<R>[]]): AsyncGenerator<T, R | undefined, N | undefined>;
-/** Infinite sequence that yields every X milliseconds (yields a count of the number of iterations). */
+/**
+ * Infinite sequence that yields every X milliseconds (yields a count of the number of iterations).
+ *
+ * @param ms The number of milliseconds to wait between each yield.
+ * @returns An infinite async generator yielding `1`, `2`, `3`… one per interval.
+ * @example for await (const count of repeatDelay(1000)) console.log(count); // 1, 2, 3… one per second
+ * @see https://dhoulb.github.io/shelving/util/sequence/repeatDelay
+ */
 export declare function repeatDelay(ms: number): AsyncGenerator<number, void, void>;
-/** Dispatch items in a sequence to a (possibly async) callback. */
+/**
+ * Dispatch items in a sequence to a (possibly async) callback.
+ * - Calls `callback` with each item as it arrives, then re-yields the item unchanged.
+ *
+ * @param sequence The source sequence to relay.
+ * @param callback Callback invoked with each yielded item.
+ * @returns An async generator that yields the same items as `sequence`.
+ * @example for await (const item of callSequence(source, console.log)) use(item);
+ * @see https://dhoulb.github.io/shelving/util/sequence/callSequence
+ */
 export declare function callSequence<T>(sequence: AsyncIterable<T, void, void>, callback: ValueCallback<T>): AsyncGenerator<T, void, void>;
 /**
  * Iterate over a sequence until the returned `stop()` callback is called.
@@ -26,8 +69,23 @@ export declare function callSequence<T>(sequence: AsyncIterable<T, void, void>,
  * - On the following iterator after throwing an error, a "generator" will return `done: true` (because they regard errors as concluding the iteration).
  * - But the iterator protocol does not require this, so this continues to iterate until it's explicitly ended via the returned `stop()` callback.
  *
- * @return Callback function that can end the sequence run.
+ * @param sequence The source sequence to iterate over.
+ * @param onNext Called with each yielded value; its return value is fed back into the iterator as the next `next()` argument.
+ * @param onError Called with any error thrown during iteration (iteration continues regardless).
+ * @param onReturn Called with the final return value when the sequence ends or is stopped.
+ * @returns Callback function that can end the sequence run, optionally with a return value.
+ * @throws {UnexpectedError} If the source iterator's `return()` does not return a `done` result.
+ * @example const stop = runSequence(source, onNext, onError, onReturn); stop(); // ends the run
+ * @see https://dhoulb.github.io/shelving/util/sequence/runSequence
  */
 export declare function runSequence<T, R, N>(sequence: AsyncIterable<T, R | undefined, N | undefined>, onNext?: (value: T) => N | undefined, onError?: ErrorCallback, onReturn?: (value: R | undefined) => void): (value?: R | undefined) => void;
-/** Merge several sequences (calls the sequences in series). */
+/**
+ * Merge several sequences (calls the sequences in series).
+ * - Yields all items from the first sequence, then all items from the second, and so on.
+ *
+ * @param sequences The sequences to merge, drained one after another in order.
+ * @returns An async iterable that yields every item from each sequence in turn.
+ * @example for await (const item of mergeSequences(a, b)) use(item); // all of `a`, then all of `b`
+ * @see https://dhoulb.github.io/shelving/util/sequence/mergeSequences
+ */
 export declare function mergeSequences<T>(...sequences: AsyncIterable<T>[]): AsyncIterable<T>;

package/util/sequence.js

@@ -21,13 +21,27 @@ async function _iteratorReturn(iterator, initial, caller) {
 }
 /**
  * Is a value an async iterable object?
- * - Any object with a `Symbol.iterator` property is iterable.
- * - Note: Array and Map instances etc will return true because they implement `Symbol.iterator`
+ * - Any object with a `Symbol.asyncIterator` property is an async iterable.
+ *
+ * @param value The value to test.
+ * @returns `true` if `value` is an `AsyncIterable`, narrowing its type.
+ * @example isSequence((async function* () {})()) // true
+ * @see https://dhoulb.github.io/shelving/util/sequence/isSequence
  */
 export function isSequence(value) {
     return typeof value === "object" && !!value && Symbol.asyncIterator in value;
 }
-/** Infinite sequence that yields until a `SIGNAL` is received. */
+/**
+ * Infinite sequence that relays a source sequence until one of the abort signals resolves.
+ * - Races each step of `source` against the supplied signal promises; when a signal wins, tells the source iterator to clean up and returns the signal's value.
+ *
+ * @param source The source sequence to relay values from.
+ * @param signals One or more promises that, when resolved, abort the relay and end the sequence.
+ * @returns The value the winning abort signal resolved with, or the source's own return value if it finishes first.
+ * @throws {UnexpectedError} If the source iterator's `return()` does not return a `done` result.
+ * @example for await (const item of repeatUntil(source, stopSignal)) doSomething(item);
+ * @see https://dhoulb.github.io/shelving/util/sequence/repeatUntil
+ */
 export async function* repeatUntil(source, ...signals) {
     const iterator = source[Symbol.asyncIterator]();
     const aborts = signals.map(_awaitAbortResult);
@@ -56,7 +70,14 @@ export async function* repeatUntil(source, ...signals) {
         }
     }
 }
-/** Infinite sequence that yields every X milliseconds (yields a count of the number of iterations). */
+/**
+ * Infinite sequence that yields every X milliseconds (yields a count of the number of iterations).
+ *
+ * @param ms The number of milliseconds to wait between each yield.
+ * @returns An infinite async generator yielding `1`, `2`, `3`… one per interval.
+ * @example for await (const count of repeatDelay(1000)) console.log(count); // 1, 2, 3… one per second
+ * @see https://dhoulb.github.io/shelving/util/sequence/repeatDelay
+ */
 export async function* repeatDelay(ms) {
     let count = 1;
     while (true) {
@@ -64,7 +85,16 @@ export async function* repeatDelay(ms) {
         yield count++;
     }
 }
-/** Dispatch items in a sequence to a (possibly async) callback. */
+/**
+ * Dispatch items in a sequence to a (possibly async) callback.
+ * - Calls `callback` with each item as it arrives, then re-yields the item unchanged.
+ *
+ * @param sequence The source sequence to relay.
+ * @param callback Callback invoked with each yielded item.
+ * @returns An async generator that yields the same items as `sequence`.
+ * @example for await (const item of callSequence(source, console.log)) use(item);
+ * @see https://dhoulb.github.io/shelving/util/sequence/callSequence
+ */
 export async function* callSequence(sequence, callback) {
     for await (const item of sequence) {
         callback(item);
@@ -79,7 +109,14 @@ export async function* callSequence(sequence, callback) {
  * - On the following iterator after throwing an error, a "generator" will return `done: true` (because they regard errors as concluding the iteration).
  * - But the iterator protocol does not require this, so this continues to iterate until it's explicitly ended via the returned `stop()` callback.
  *
- * @return Callback function that can end the sequence run.
+ * @param sequence The source sequence to iterate over.
+ * @param onNext Called with each yielded value; its return value is fed back into the iterator as the next `next()` argument.
+ * @param onError Called with any error thrown during iteration (iteration continues regardless).
+ * @param onReturn Called with the final return value when the sequence ends or is stopped.
+ * @returns Callback function that can end the sequence run, optionally with a return value.
+ * @throws {UnexpectedError} If the source iterator's `return()` does not return a `done` result.
+ * @example const stop = runSequence(source, onNext, onError, onReturn); stop(); // ends the run
+ * @see https://dhoulb.github.io/shelving/util/sequence/runSequence
  */
 export function runSequence(sequence, onNext, onError, onReturn) {
     const { promise, resolve } = createDeferred();
@@ -109,7 +146,15 @@ async function _runSequenceIterator(iterator, stopped, onNext, onError, onReturn
         }
     }
 }
-/** Merge several sequences (calls the sequences in series). */
+/**
+ * Merge several sequences (calls the sequences in series).
+ * - Yields all items from the first sequence, then all items from the second, and so on.
+ *
+ * @param sequences The sequences to merge, drained one after another in order.
+ * @returns An async iterable that yields every item from each sequence in turn.
+ * @example for await (const item of mergeSequences(a, b)) use(item); // all of `a`, then all of `b`
+ * @see https://dhoulb.github.io/shelving/util/sequence/mergeSequences
+ */
 export async function* mergeSequences(...sequences) {
     for await (const sequence of sequences)
         yield* sequence;

package/util/serialise.d.ts

@@ -1,9 +1,15 @@
 /**
- * Custom JSON.stringify()
+ * Serialise any value to a stable, consistent string (a `JSON.stringify()` that never loses information).
  * - Not optimised for performance. Optimised for consistency!
  * - Allows returned values to be used for fingerprinting values of any type.
  * - Non-JSON-friendly values (like `null`, explicit `undefined`, symbols, functions) are converted to `{ $type: "symbol" }` style constructions.
  * - Objects with custom `toString()` properties assume that string is useful and return a value like `{ $type: "Date", value: "Wed Feb 24 2021 20:59:57 GMT+0000 (Greenwich Mean Time)" }`
  * - Object properties are sorted (by key) before output so they're always consistent.
+ *
+ * @param value The value to serialise (any type is accepted).
+ * @returns A consistent string representation of `value`, suitable for fingerprinting or equality comparison.
+ * @throws {ValueError} If `value` cannot be serialised.
+ * @example serialise({ b: 2, a: 1 }) // `{"a":1,"b":2}`
+ * @see https://dhoulb.github.io/shelving/util/serialise/serialise
  */
 export declare function serialise(value: unknown): string;

package/util/serialise.js

@@ -3,12 +3,18 @@ import { isArray } from "./array.js";
 import { getPrototype, isObject } from "./object.js";
 const R_QUOTE = /"/g;
 /**
- * Custom JSON.stringify()
+ * Serialise any value to a stable, consistent string (a `JSON.stringify()` that never loses information).
  * - Not optimised for performance. Optimised for consistency!
  * - Allows returned values to be used for fingerprinting values of any type.
  * - Non-JSON-friendly values (like `null`, explicit `undefined`, symbols, functions) are converted to `{ $type: "symbol" }` style constructions.
  * - Objects with custom `toString()` properties assume that string is useful and return a value like `{ $type: "Date", value: "Wed Feb 24 2021 20:59:57 GMT+0000 (Greenwich Mean Time)" }`
  * - Object properties are sorted (by key) before output so they're always consistent.
+ *
+ * @param value The value to serialise (any type is accepted).
+ * @returns A consistent string representation of `value`, suitable for fingerprinting or equality comparison.
+ * @throws {ValueError} If `value` cannot be serialised.
+ * @example serialise({ b: 2, a: 1 }) // `{"a":1,"b":2}`
+ * @see https://dhoulb.github.io/shelving/util/serialise/serialise
  */
 export function serialise(value) {
     if (value === true)

package/util/set.d.ts

@@ -1,27 +1,117 @@
 import type { AnyCaller } from "./function.js";
-/** `Set` that cannot be changed. */
+/**
+ * `Set` that cannot be changed.
+ *
+ * @see https://dhoulb.github.io/shelving/util/set/ImmutableSet
+ */
 export type ImmutableSet<T = unknown> = ReadonlySet<T>;
-/** `Set` that can be changed. */
+/**
+ * `Set` that can be changed.
+ *
+ * @see https://dhoulb.github.io/shelving/util/set/MutableSet
+ */
 export type MutableSet<T = unknown> = Set<T>;
-/** Things that can be converted to sets. */
+/**
+ * Things that can be converted to sets.
+ *
+ * @see https://dhoulb.github.io/shelving/util/set/PossibleSet
+ */
 export type PossibleSet<T> = ImmutableSet<T> | Iterable<T>;
-/** Get the type of the _items_ in a set. */
+/**
+ * Get the type of the _items_ in a set.
+ *
+ * @see https://dhoulb.github.io/shelving/util/set/SetItem
+ */
 export type SetItem<X> = X extends ReadonlySet<infer Y> ? Y : never;
-/** Is an unknown value a set? */
+/**
+ * Is an unknown value a set?
+ *
+ * @param value The value to check.
+ * @returns `true` if `value` is a `Set` instance, otherwise `false`.
+ * @see https://dhoulb.github.io/shelving/util/set/isSet
+ */
 export declare function isSet(value: unknown): value is ImmutableSet;
-/** Assert that a value is a `Set` instance. */
+/**
+ * Assert that a value is a `Set` instance.
+ *
+ * @param value The value to assert on.
+ * @param caller Function to attribute a thrown error to (defaults to `assertSet`).
+ * @throws {RequiredError} If `value` is not a `Set` instance.
+ * @example assertSet(new Set()); // Passes.
+ * @see https://dhoulb.github.io/shelving/util/set/assertSet
+ */
 export declare function assertSet(value: unknown, caller?: AnyCaller): asserts value is ImmutableSet;
-/** Convert a possible set to a `Set`. */
+/**
+ * Convert a possible set to a `Set`.
+ * - Returns the input unchanged when it is already a `Set`; otherwise constructs a new `Set` from the iterable.
+ *
+ * @param value A `Set` or any iterable of items.
+ * @returns A `Set` containing the items of `value`.
+ * @example getSet(["a", "b"]) // Set { "a", "b" }
+ * @see https://dhoulb.github.io/shelving/util/set/getSet
+ */
 export declare function getSet<T>(value: PossibleSet<T>): ImmutableSet;
-/** Apply a limit to a set. */
+/**
+ * Apply a limit to a set.
+ * - Returns the input unchanged when it already fits within `limit`.
+ *
+ * @param set The set to limit.
+ * @param limit The maximum number of items to keep.
+ * @returns A set containing at most `limit` items.
+ * @example limitSet(new Set([1, 2, 3]), 2) // Set { 1, 2 }
+ * @see https://dhoulb.github.io/shelving/util/set/limitSet
+ */
 export declare function limitSet<T>(set: ImmutableSet<T>, limit: number): ImmutableSet<T>;
-/** Is an unknown value an item in a set? */
+/**
+ * Is an unknown value an item in a set?
+ *
+ * @param set The set to look in.
+ * @param item The value to check for membership.
+ * @returns `true` if `item` exists in `set`, otherwise `false`.
+ * @see https://dhoulb.github.io/shelving/util/set/isSetItem
+ */
 export declare function isSetItem<T>(set: ImmutableSet<T>, item: unknown): item is T;
-/** Assert that an unknown value is an item in a set. */
+/**
+ * Assert that an unknown value is an item in a set.
+ *
+ * @param set The set to look in.
+ * @param item The value to assert membership of.
+ * @param caller Function to attribute a thrown error to (defaults to `assertSetItem`).
+ * @throws {RequiredError} If `item` does not exist in `set`.
+ * @example assertSetItem(new Set(["a"]), "a"); // Passes.
+ * @see https://dhoulb.github.io/shelving/util/set/assertSetItem
+ */
 export declare function assertSetItem<T>(set: ImmutableSet<T>, item: unknown, caller?: AnyCaller): asserts item is T;
-/** Add an item to a set (by reference) and return the set item. */
+/**
+ * Add an item to a set (by reference) and return the set item.
+ * - Mutates `set` in place.
+ *
+ * @param set The mutable set to add to.
+ * @param item The item to add.
+ * @returns The added `item`.
+ * @example addSetItem(set, "a") // "a"
+ * @see https://dhoulb.github.io/shelving/util/set/addSetItem
+ */
 export declare function addSetItem<T>(set: MutableSet<T>, item: T): T;
-/** Add multiple items to a set (by reference). */
+/**
+ * Add multiple items to a set (by reference).
+ * - Mutates `set` in place.
+ *
+ * @param set The mutable set to add to.
+ * @param items The items to add.
+ * @returns Nothing.
+ * @example addSetItems(set, "a", "b");
+ * @see https://dhoulb.github.io/shelving/util/set/addSetItems
+ */
 export declare function addSetItems<T>(set: MutableSet<T>, ...items: T[]): void;
-/** Remove multiple items from a set (by reference). */
+/**
+ * Remove multiple items from a set (by reference).
+ * - Mutates `set` in place.
+ *
+ * @param set The mutable set to remove from.
+ * @param items The items to remove.
+ * @returns Nothing.
+ * @example deleteSetItems(set, "a", "b");
+ * @see https://dhoulb.github.io/shelving/util/set/deleteSetItems
+ */
 export declare function deleteSetItems<T>(set: MutableSet<T>, ...items: T[]): void;

package/util/set.js

@@ -1,42 +1,116 @@
 import { RequiredError } from "../error/RequiredError.js";
 import { limitItems } from "./iterate.js";
-/** Is an unknown value a set? */
+/**
+ * Is an unknown value a set?
+ *
+ * @param value The value to check.
+ * @returns `true` if `value` is a `Set` instance, otherwise `false`.
+ * @see https://dhoulb.github.io/shelving/util/set/isSet
+ */
 export function isSet(value) {
     return value instanceof Set;
 }
-/** Assert that a value is a `Set` instance. */
+/**
+ * Assert that a value is a `Set` instance.
+ *
+ * @param value The value to assert on.
+ * @param caller Function to attribute a thrown error to (defaults to `assertSet`).
+ * @throws {RequiredError} If `value` is not a `Set` instance.
+ * @example assertSet(new Set()); // Passes.
+ * @see https://dhoulb.github.io/shelving/util/set/assertSet
+ */
 export function assertSet(value, caller = assertSet) {
     if (!isSet(value))
         throw new RequiredError("Must be set", { received: value, caller });
 }
-/** Convert a possible set to a `Set`. */
+/**
+ * Convert a possible set to a `Set`.
+ * - Returns the input unchanged when it is already a `Set`; otherwise constructs a new `Set` from the iterable.
+ *
+ * @param value A `Set` or any iterable of items.
+ * @returns A `Set` containing the items of `value`.
+ * @example getSet(["a", "b"]) // Set { "a", "b" }
+ * @see https://dhoulb.github.io/shelving/util/set/getSet
+ */
 export function getSet(value) {
     return isSet(value) ? value : new Set(value);
 }
-/** Apply a limit to a set. */
+/**
+ * Apply a limit to a set.
+ * - Returns the input unchanged when it already fits within `limit`.
+ *
+ * @param set The set to limit.
+ * @param limit The maximum number of items to keep.
+ * @returns A set containing at most `limit` items.
+ * @example limitSet(new Set([1, 2, 3]), 2) // Set { 1, 2 }
+ * @see https://dhoulb.github.io/shelving/util/set/limitSet
+ */
 export function limitSet(set, limit) {
     return limit > set.size ? set : new Set(limitItems(set, limit));
 }
-/** Is an unknown value an item in a set? */
+/**
+ * Is an unknown value an item in a set?
+ *
+ * @param set The set to look in.
+ * @param item The value to check for membership.
+ * @returns `true` if `item` exists in `set`, otherwise `false`.
+ * @see https://dhoulb.github.io/shelving/util/set/isSetItem
+ */
 export function isSetItem(set, item) {
     return set.has(item);
 }
-/** Assert that an unknown value is an item in a set. */
+/**
+ * Assert that an unknown value is an item in a set.
+ *
+ * @param set The set to look in.
+ * @param item The value to assert membership of.
+ * @param caller Function to attribute a thrown error to (defaults to `assertSetItem`).
+ * @throws {RequiredError} If `item` does not exist in `set`.
+ * @example assertSetItem(new Set(["a"]), "a"); // Passes.
+ * @see https://dhoulb.github.io/shelving/util/set/assertSetItem
+ */
 export function assertSetItem(set, item, caller = assertSetItem) {
     if (!isSetItem(set, item))
         throw new RequiredError("Item must exist in set", { item, set, caller });
 }
-/** Add an item to a set (by reference) and return the set item. */
+/**
+ * Add an item to a set (by reference) and return the set item.
+ * - Mutates `set` in place.
+ *
+ * @param set The mutable set to add to.
+ * @param item The item to add.
+ * @returns The added `item`.
+ * @example addSetItem(set, "a") // "a"
+ * @see https://dhoulb.github.io/shelving/util/set/addSetItem
+ */
 export function addSetItem(set, item) {
     set.add(item);
     return item;
 }
-/** Add multiple items to a set (by reference). */
+/**
+ * Add multiple items to a set (by reference).
+ * - Mutates `set` in place.
+ *
+ * @param set The mutable set to add to.
+ * @param items The items to add.
+ * @returns Nothing.
+ * @example addSetItems(set, "a", "b");
+ * @see https://dhoulb.github.io/shelving/util/set/addSetItems
+ */
 export function addSetItems(set, ...items) {
     for (const item of items)
         set.add(item);
 }
-/** Remove multiple items from a set (by reference). */
+/**
+ * Remove multiple items from a set (by reference).
+ * - Mutates `set` in place.
+ *
+ * @param set The mutable set to remove from.
+ * @param items The items to remove.
+ * @returns Nothing.
+ * @example deleteSetItems(set, "a", "b");
+ * @see https://dhoulb.github.io/shelving/util/set/deleteSetItems
+ */
 export function deleteSetItems(set, ...items) {
     for (const item of items)
         set.delete(item);

package/util/sort.d.ts

@@ -1,6 +1,11 @@
 import type { ImmutableArray } from "./array.js";
 import type { Arguments } from "./function.js";
-/** Function that can compare two values for sorting. */
+/**
+ * Function that can compare two values for sorting.
+ * - Returns a negative number if `left` sorts before `right`, positive if after, or `0` if equally ranked (like `Array.prototype.sort()`).
+ *
+ * @see https://dhoulb.github.io/shelving/util/sort/Compare
+ */
 export type Compare<T, A extends Arguments = []> = (left: T, right: T, ...args: A) => number;
 /**
  * Compare two unknown values in ascending order.
@@ -14,13 +19,33 @@ export type Compare<T, A extends Arguments = []> = (left: T, right: T, ...args:
  * 6. Unsorted values (objects that can't be converted to number or string, symbols, NaN, etc)
  * 7. `undefined`
  *
- * @param x The first value to rank.
- * @param y The second value to rank.
- *
- * @returns Number below zero if `a` is higher, number above zero if `b` is higher, or `0` if they're equally sorted.
+ * @param left The first value to rank.
+ * @param right The second value to rank.
+ * @returns Number below zero if `left` is higher, number above zero if `right` is higher, or `0` if they're equally sorted.
+ * @example compareAscending(1, 2) // -1
+ * @see https://dhoulb.github.io/shelving/util/sort/compareAscending
  */
 export declare function compareAscending(left: unknown, right: unknown): number;
-/** Compare two unknown values in descending order. */
+/**
+ * Compare two unknown values in descending order.
+ * - The exact inverse of `compareAscending`.
+ *
+ * @param left The first value to rank.
+ * @param right The second value to rank.
+ * @returns Number below zero if `right` is higher, number above zero if `left` is higher, or `0` if they're equally sorted.
+ * @example compareDescending(1, 2) // 1
+ * @see https://dhoulb.github.io/shelving/util/sort/compareDescending
+ */
 export declare function compareDescending(left: unknown, right: unknown): number;
-/** Sort an iterable set of items using a ranker (defaults to sorting in ascending order). */
+/**
+ * Sort an iterable set of items using a ranker (defaults to sorting in ascending order).
+ * - When the input is already an array and the sort makes no change, the original array reference is returned unchanged.
+ *
+ * @param input The array or iterable of items to sort.
+ * @param compare A `Compare` function ranking two items (defaults to `compareAscending`).
+ * @param args Extra arguments forwarded to `compare` on each call.
+ * @returns A sorted array (the original reference if it was an already-sorted array).
+ * @example sortArray([3, 1, 2]) // [1, 2, 3]
+ * @see https://dhoulb.github.io/shelving/util/sort/sortArray
+ */
 export declare function sortArray<T, A extends Arguments = []>(input: ImmutableArray<T> | Iterable<T>, compare?: Compare<T, A>, ...args: A): ImmutableArray<T>;

package/util/sort.js

@@ -11,10 +11,11 @@ import { isArray } from "./array.js";
  * 6. Unsorted values (objects that can't be converted to number or string, symbols, NaN, etc)
  * 7. `undefined`
  *
- * @param x The first value to rank.
- * @param y The second value to rank.
- *
- * @returns Number below zero if `a` is higher, number above zero if `b` is higher, or `0` if they're equally sorted.
+ * @param left The first value to rank.
+ * @param right The second value to rank.
+ * @returns Number below zero if `left` is higher, number above zero if `right` is higher, or `0` if they're equally sorted.
+ * @example compareAscending(1, 2) // -1
+ * @see https://dhoulb.github.io/shelving/util/sort/compareAscending
  */
 export function compareAscending(left, right) {
     // Exactly equal is easy.
@@ -68,7 +69,16 @@ export function compareAscending(left, right) {
     // Otherwise a is higher.
     return -1;
 }
-/** Compare two unknown values in descending order. */
+/**
+ * Compare two unknown values in descending order.
+ * - The exact inverse of `compareAscending`.
+ *
+ * @param left The first value to rank.
+ * @param right The second value to rank.
+ * @returns Number below zero if `right` is higher, number above zero if `left` is higher, or `0` if they're equally sorted.
+ * @example compareDescending(1, 2) // 1
+ * @see https://dhoulb.github.io/shelving/util/sort/compareDescending
+ */
 export function compareDescending(left, right) {
     return 0 - compareAscending(left, right);
 }
@@ -120,7 +130,17 @@ function _quicksort(items, compare, args, leftPointer = 0, rightPointer = items.
     // Changes were made.
     return changed;
 }
-/** Sort an iterable set of items using a ranker (defaults to sorting in ascending order). */
+/**
+ * Sort an iterable set of items using a ranker (defaults to sorting in ascending order).
+ * - When the input is already an array and the sort makes no change, the original array reference is returned unchanged.
+ *
+ * @param input The array or iterable of items to sort.
+ * @param compare A `Compare` function ranking two items (defaults to `compareAscending`).
+ * @param args Extra arguments forwarded to `compare` on each call.
+ * @returns A sorted array (the original reference if it was an already-sorted array).
+ * @example sortArray([3, 1, 2]) // [1, 2, 3]
+ * @see https://dhoulb.github.io/shelving/util/sort/sortArray
+ */
 export function sortArray(input, compare = compareAscending, ...args) {
     if (isArray(input)) {
         if (input.length < 2)

package/util/source.d.ts

@@ -1,10 +1,35 @@
 import type { Class } from "./class.js";
 import type { AnyCaller } from "./function.js";
-/** Something that has a source of a specified type. */
+/**
+ * Something that has a source of a specified type.
+ *
+ * @see https://dhoulb.github.io/shelving/util/source/Sourceable
+ */
 export interface Sourceable<T> {
+    /** The wrapped source object this object delegates to. */
     readonly source: T;
 }
-/** Recurse through `Sourceable` objects and return the first one that is an instance of `type`, or `undefined` if no source object matches. */
+/**
+ * Recurse through `Sourceable` objects and return the first one that is an instance of `type`, or `undefined` if no source object matches.
+ * - Follows the `source` property chain (e.g. layered providers) until a matching instance is found.
+ *
+ * @param type The class to search for an instance of.
+ * @param value The object to start searching from.
+ * @returns The first matching source instance, or `undefined` if none matches.
+ * @example getSource(CacheProvider, provider) // CacheProvider instance or undefined
+ * @see https://dhoulb.github.io/shelving/util/source/getSource
+ */
 export declare function getSource<T>(type: Class<T>, value: unknown): T | undefined;
-/** Recurse through `Sourceable` objects and return the first one that is an instance of `type`, or throw `RequiredError` if no source object matches. */
+/**
+ * Recurse through `Sourceable` objects and return the first one that is an instance of `type`, or throw `RequiredError` if no source object matches.
+ * - Like `getSource`, but throws instead of returning `undefined` when no match is found.
+ *
+ * @param type The class to search for an instance of.
+ * @param data The object to start searching from.
+ * @param caller Function to attribute a thrown error to (defaults to `requireSource`).
+ * @returns The first matching source instance.
+ * @throws {RequiredError} If no source object is an instance of `type`.
+ * @example requireSource(CacheProvider, provider) // CacheProvider instance
+ * @see https://dhoulb.github.io/shelving/util/source/requireSource
+ */
 export declare function requireSource<T>(type: Class<T>, data: unknown, caller?: AnyCaller): T;