shelving 1.236.0 → 1.236.2

package/util/null.js

@@ -1,50 +1,131 @@
 import { RequiredError } from "../error/RequiredError.js";
-/** Function that always returns null. */
+/**
+ * Function that always returns `null`.
+ * - Useful as a default callback or placeholder.
+ *
+ * @returns `null`, always.
+ * @example getNull() // null
+ * @see https://dhoulb.github.io/shelving/util/null/getNull
+ */
 export function getNull() {
     return null;
 }
-/** Is a value null? */
+/**
+ * Is a value `null`?
+ *
+ * @param value The value to test.
+ * @returns `true` if `value` is `null`, otherwise `false`.
+ * @see https://dhoulb.github.io/shelving/util/null/isNull
+ */
 export function isNull(value) {
     return value === null;
 }
-/** Assert that a value is not null. */
+/**
+ * Assert that a value is `null`.
+ *
+ * @param value The value to assert.
+ * @param caller Function used to attribute a thrown error to the calling site.
+ * @returns Nothing; narrows `value` to `T`.
+ * @throws RequiredError if `value` is not `null`.
+ * @see https://dhoulb.github.io/shelving/util/null/assertNull
+ */
 export function assertNull(value, caller = assertNull) {
     if (value !== null)
         throw new RequiredError("Must be null", { received: value, caller });
 }
-/** Is a value not null? */
+/**
+ * Is a value not `null`?
+ *
+ * @param value The value to test.
+ * @returns `true` if `value` is not `null`, otherwise `false`.
+ * @see https://dhoulb.github.io/shelving/util/null/notNull
+ */
 export function notNull(value) {
     return value !== null;
 }
-/** Assert that a value is not null. */
+/**
+ * Assert that a value is not `null`.
+ *
+ * @param value The value to assert.
+ * @param caller Function used to attribute a thrown error to the calling site.
+ * @returns Nothing; narrows `value` to `T`.
+ * @throws RequiredError if `value` is `null`.
+ * @see https://dhoulb.github.io/shelving/util/null/assertNotNull
+ */
 export function assertNotNull(value, caller = assertNotNull) {
     if (value === null)
         throw new RequiredError("Must not be null", { received: value, caller });
 }
-/** Get the not-nullish version of value. */
+/**
+ * Get the not-null version of a value, or throw `RequiredError` if it is `null`.
+ *
+ * @param value The value to require.
+ * @param caller Function used to attribute a thrown error to the calling site.
+ * @returns The value, narrowed to `T`.
+ * @throws RequiredError if `value` is `null`.
+ * @example requireNotNull("a") // "a"
+ * @see https://dhoulb.github.io/shelving/util/null/requireNotNull
+ */
 export function requireNotNull(value, caller = requireNotNull) {
     assertNotNull(value, caller);
     return value;
 }
-/** Is a value nullish? */
+/**
+ * Is a value nullish (`null` or `undefined`)?
+ *
+ * @param value The value to test.
+ * @returns `true` if `value` is `null` or `undefined`, otherwise `false`.
+ * @see https://dhoulb.github.io/shelving/util/null/isNullish
+ */
 export function isNullish(value) {
     return value === null || value === undefined;
 }
-/** Assert that a value is not nullish. */
+/**
+ * Assert that a value is nullish (`null` or `undefined`).
+ *
+ * @param value The value to assert.
+ * @param caller Function used to attribute a thrown error to the calling site.
+ * @returns Nothing; narrows `value` to `T`.
+ * @throws RequiredError if `value` is not `null` or `undefined`.
+ * @see https://dhoulb.github.io/shelving/util/null/assertNullish
+ */
 export function assertNullish(value, caller = assertNullish) {
     if (value !== null && value !== undefined)
         throw new RequiredError("Must be null or undefined", { received: value, caller });
 }
-/** Is a value not nullish? */
+/**
+ * Is a value not nullish (not `null` and not `undefined`)?
+ *
+ * @param value The value to test.
+ * @returns `true` if `value` is not `null` and not `undefined`, otherwise `false`.
+ * @see https://dhoulb.github.io/shelving/util/null/notNullish
+ */
 export function notNullish(value) {
     return value !== null && value !== undefined;
 }
-/** Assert that a value is not nullish. */
+/**
+ * Assert that a value is not nullish (not `null` and not `undefined`).
+ *
+ * @param value The value to assert.
+ * @param caller Function used to attribute a thrown error to the calling site.
+ * @returns Nothing; narrows `value` to `T`.
+ * @throws RequiredError if `value` is `null` or `undefined`.
+ * @see https://dhoulb.github.io/shelving/util/null/assertNotNullish
+ */
 export function assertNotNullish(value, caller = assertNotNullish) {
     if (value === null || value === undefined)
         throw new RequiredError("Must not be null or undefined", { received: value, caller });
 }
-/** Get the not-nullish version of value. */
+/**
+ * Get the not-nullish version of a value, or throw `RequiredError` if it is `null` or `undefined`.
+ *
+ * @param value The value to require.
+ * @param caller Function used to attribute a thrown error to the calling site.
+ * @returns The value, narrowed to `T`.
+ * @throws RequiredError if `value` is `null` or `undefined`.
+ * @example requireNotNullish("a") // "a"
+ * @see https://dhoulb.github.io/shelving/util/null/requireNotNullish
+ */
 export function requireNotNullish(value, caller = requireNotNullish) {
     assertNotNullish(value, caller);
     return value;

package/util/number.d.ts

@@ -1,9 +1,33 @@
 import type { AnyCaller } from "./function.js";
-/** Values that can be converted to a number. */
+/**
+ * Values that can be converted to a number.
+ *
+ * @see https://dhoulb.github.io/shelving/util/number/PossibleNumber
+ */
 export type PossibleNumber = number | string | Date;
-/** Is a value a finite number? */
+/**
+ * Is a value a finite number (optionally within a specified min/max range)?
+ *
+ * @param value The value to test.
+ * @param min Minimum allowed value, inclusive (defaults to `-Infinity`).
+ * @param max Maximum allowed value, inclusive (defaults to `+Infinity`).
+ * @returns `true` if `value` is a finite number within range, otherwise `false`.
+ * @example isNumber(17, 10, 20) // true
+ * @see https://dhoulb.github.io/shelving/util/number/isNumber
+ */
 export declare function isNumber(value: unknown, min?: number, max?: number): value is number;
-/** Assert that a value is a finite number. */
+/**
+ * Assert that a value is a finite number (optionally within a specified min/max range).
+ *
+ * @param value The value to assert.
+ * @param min Minimum allowed value, inclusive.
+ * @param max Maximum allowed value, inclusive.
+ * @param caller Function used to attribute a thrown error to the calling site.
+ * @returns Nothing; narrows `value` to `number`.
+ * @throws RequiredError if `value` is not a finite number within range.
+ * @example assertNumber(5, 0, 10); // passes
+ * @see https://dhoulb.github.io/shelving/util/number/assertNumber
+ */
 export declare function assertNumber(value: unknown, min?: number, max?: number, caller?: AnyCaller): asserts value is number;
 /**
  * Convert an unknown value to a finite number, or return `undefined` if it cannot be converted.
@@ -15,15 +39,49 @@ export declare function assertNumber(value: unknown, min?: number, max?: number,
  * - Strings are parsed as numbers using `Number.parseFloat()` after removing all non-numeric characters.
  * - Dates return their milliseconds (e.g. `date.getTime()`).
  * - Everything else returns `undefined`
+ *
+ * @param value The value to convert.
+ * @returns The finite number, or `undefined` if `value` cannot be converted.
+ * @example getNumber("1.5kg") // 1.5
+ * @see https://dhoulb.github.io/shelving/util/number/getNumber
  */
 export declare function getNumber(value: unknown): number | undefined;
 /**
  * Convert a possible number to a finite number, or throw `ValueError` if the value cannot be converted.
+ *
+ * @param value The value to convert.
+ * @param min Minimum allowed value, inclusive.
+ * @param max Maximum allowed value, inclusive.
+ * @param caller Function used to attribute a thrown error to the calling site.
+ * @returns The finite number.
+ * @throws RequiredError if `value` cannot be converted to a finite number within range.
+ * @example requireNumber("42") // 42
+ * @see https://dhoulb.github.io/shelving/util/number/requireNumber
  */
 export declare function requireNumber(value: PossibleNumber, min?: number, max?: number, caller?: AnyCaller): number;
-/** Is an unknown value an integer (optionally with specified min/max values). */
+/**
+ * Is an unknown value an integer (optionally within specified min/max values)?
+ *
+ * @param value The value to test.
+ * @param min Minimum allowed value, inclusive (defaults to `Number.MIN_SAFE_INTEGER`).
+ * @param max Maximum allowed value, inclusive (defaults to `Number.MAX_SAFE_INTEGER`).
+ * @returns `true` if `value` is an integer within range, otherwise `false`.
+ * @example isInteger(5, 0, 10) // true
+ * @see https://dhoulb.github.io/shelving/util/number/isInteger
+ */
 export declare function isInteger(value: unknown, min?: number, max?: number): value is number;
-/** Assert that a value is an integer. */
+/**
+ * Assert that a value is an integer (optionally within specified min/max values).
+ *
+ * @param value The value to assert.
+ * @param min Minimum allowed value, inclusive.
+ * @param max Maximum allowed value, inclusive.
+ * @param caller Function used to attribute a thrown error to the calling site.
+ * @returns Nothing; narrows `value` to `number`.
+ * @throws RequiredError if `value` is not an integer within range.
+ * @example assertInteger(5, 0, 10); // passes
+ * @see https://dhoulb.github.io/shelving/util/number/assertInteger
+ */
 export declare function assertInteger(value: unknown, min?: number, max?: number, caller?: AnyCaller): asserts value is number;
 /**
  * Convert an unknown value to an integer, or return `undefined` if it cannot be converted.
@@ -34,9 +92,25 @@ export declare function assertInteger(value: unknown, min?: number, max?: number
  * - Strings are parsed as integers using `parseInt()` after removing non-numeric characters.
  * - Dates return their milliseconds (e.g. `date.getTime()`).
  * - Everything else returns `undefined`
+ *
+ * @param value The value to convert.
+ * @returns The integer, or `undefined` if `value` cannot be converted.
+ * @example getInteger("42px") // 42
+ * @see https://dhoulb.github.io/shelving/util/number/getInteger
  */
 export declare function getInteger(value: unknown): number | undefined;
-/** Convert a possible number to an integer, or throw `ValueError` if the value cannot be converted. */
+/**
+ * Convert a possible number to an integer, or throw `ValueError` if the value cannot be converted.
+ *
+ * @param value The value to convert.
+ * @param min Minimum allowed value, inclusive.
+ * @param max Maximum allowed value, inclusive.
+ * @param caller Function used to attribute a thrown error to the calling site.
+ * @returns The integer.
+ * @throws RequiredError if `value` cannot be converted to an integer within range.
+ * @example requireInteger("42") // 42
+ * @see https://dhoulb.github.io/shelving/util/number/requireInteger
+ */
 export declare function requireInteger(value: PossibleNumber, min?: number, max?: number, caller?: AnyCaller): number;
 /**
  * Is a number within a specified range?
@@ -44,6 +118,9 @@ export declare function requireInteger(value: PossibleNumber, min?: number, max?
  * @param num The number to test, e.g. `17`
  * @param min The start of the range, e.g. `10`
  * @param max The end of the range, e.g. `20`
+ * @returns `true` if `num` is between `min` and `max` (inclusive), otherwise `false`.
+ * @example isBetween(17, 10, 20) // true
+ * @see https://dhoulb.github.io/shelving/util/number/isBetween
  */
 export declare function isBetween(num: number, min: number, max: number): boolean;
 /**
@@ -53,6 +130,8 @@ export declare function isBetween(num: number, min: number, max: number): boolea
  * @param step The rounding to round to, e.g. `2` or `0.1` (defaults to `1`, i.e. round numbers).
  *
  * @returns The number rounded to the specified step.
+ * @example roundStep(17, 5) // 15
+ * @see https://dhoulb.github.io/shelving/util/number/roundStep
  */
 export declare function roundStep(num: number, step?: number): number;
 /**
@@ -64,6 +143,8 @@ export declare function roundStep(num: number, step?: number): number;
  * @param precision Maximum number of digits shown after the decimal point (defaults to 10).
  *
  * @returns The number rounded to the specified precision.
+ * @example roundNumber(1.2345, 2) // 1.23
+ * @see https://dhoulb.github.io/shelving/util/number/roundNumber
  */
 export declare function roundNumber(num: number, precision?: number): number;
 /**
@@ -73,11 +154,21 @@ export declare function roundNumber(num: number, precision?: number): number;
  * @param num The number to truncate.
  * @param precision Maximum number of digits shown after the decimal point (defaults to 0).
  * @returns The number truncated to the specified precision.
+ * @example truncateNumber(1.2999, 2) // 1.29
+ * @see https://dhoulb.github.io/shelving/util/number/truncateNumber
  */
 export declare function truncateNumber(num: number, precision?: number): number;
 /**
  * Bound a number between two values.
  * - e.g. `12` bounded by `2` and `8` is `8`
+ *
+ * @param num The number to bound.
+ * @param min The minimum bound, inclusive.
+ * @param max The maximum bound, inclusive.
+ * @returns `num` clamped to lie between `min` and `max`.
+ * @throws ValueError if `max` is less than `min`.
+ * @example boundNumber(12, 2, 8) // 8
+ * @see https://dhoulb.github.io/shelving/util/number/boundNumber
  */
 export declare function boundNumber(num: number, min: number, max: number): number;
 /**
@@ -86,6 +177,14 @@ export declare function boundNumber(num: number, min: number, max: number): numb
  * - e.g. `12` bounded by `2` and `8` is `6`
  * - Words in both directions.
  * - e.g. `-2` bounded by `2` and `8` is `4`
+ *
+ * @param num The number to wrap.
+ * @param min The minimum bound, inclusive.
+ * @param max The maximum bound, exclusive (values wrap back to `min`).
+ * @returns `num` wrapped to lie between `min` and `max`.
+ * @throws ValueError if `max` is less than `min`.
+ * @example wrapNumber(12, 2, 8) // 6
+ * @see https://dhoulb.github.io/shelving/util/number/wrapNumber
  */
 export declare function wrapNumber(num: number, min: number, max: number): number;
 /**
@@ -93,9 +192,27 @@ export declare function wrapNumber(num: number, min: number, max: number): numbe
  *
  * @param numerator Number representing the amount of progress.
  * @param denumerator The number representing the whole amount (defaults to 100).
+ * @returns `numerator` expressed as a percentage of `denumerator`.
+ * @example getPercent(1, 4) // 25
+ * @see https://dhoulb.github.io/shelving/util/number/getPercent
  */
 export declare function getPercent(numerator: number, denumerator?: number): number;
-/** Sum an iterable set of numbers and return the total. */
+/**
+ * Sum an iterable set of numbers and return the total.
+ *
+ * @param nums The iterable of numbers to sum.
+ * @returns The total of all the numbers (`0` if `nums` is empty).
+ * @example sumNumbers([1, 2, 3]) // 6
+ * @see https://dhoulb.github.io/shelving/util/number/sumNumbers
+ */
 export declare function sumNumbers(nums: Iterable<number>): number;
-/** Find the number that's closest to a target in an iterable set of numbers. */
+/**
+ * Find the number that's closest to a target in an iterable set of numbers.
+ *
+ * @param nums The iterable of numbers to search.
+ * @param target The target number to find the closest match for.
+ * @returns The number closest to `target`, or `undefined` if `nums` is empty.
+ * @example getClosestNumber([1, 5, 10], 6) // 5
+ * @see https://dhoulb.github.io/shelving/util/number/getClosestNumber
+ */
 export declare function getClosestNumber<T extends number>(nums: Iterable<T>, target: number): T | undefined;

package/util/number.js

@@ -1,10 +1,30 @@
 import { RequiredError } from "../error/RequiredError.js";
 import { ValueError } from "../error/ValueError.js";
-/** Is a value a finite number? */
+/**
+ * Is a value a finite number (optionally within a specified min/max range)?
+ *
+ * @param value The value to test.
+ * @param min Minimum allowed value, inclusive (defaults to `-Infinity`).
+ * @param max Maximum allowed value, inclusive (defaults to `+Infinity`).
+ * @returns `true` if `value` is a finite number within range, otherwise `false`.
+ * @example isNumber(17, 10, 20) // true
+ * @see https://dhoulb.github.io/shelving/util/number/isNumber
+ */
 export function isNumber(value, min = Number.NEGATIVE_INFINITY, max = Number.POSITIVE_INFINITY) {
     return Number.isFinite(value) && value >= min && value <= max;
 }
-/** Assert that a value is a finite number. */
+/**
+ * Assert that a value is a finite number (optionally within a specified min/max range).
+ *
+ * @param value The value to assert.
+ * @param min Minimum allowed value, inclusive.
+ * @param max Maximum allowed value, inclusive.
+ * @param caller Function used to attribute a thrown error to the calling site.
+ * @returns Nothing; narrows `value` to `number`.
+ * @throws RequiredError if `value` is not a finite number within range.
+ * @example assertNumber(5, 0, 10); // passes
+ * @see https://dhoulb.github.io/shelving/util/number/assertNumber
+ */
 export function assertNumber(value, min, max, caller = assertNumber) {
     if (!isNumber(value, min, max))
         throw new RequiredError(`Must be finite number${max !== undefined ? ` between ${min ?? 0} and ${max}` : min !== undefined ? ` above ${min}` : ""}`, { received: value, caller });
@@ -19,6 +39,11 @@ export function assertNumber(value, min, max, caller = assertNumber) {
  * - Strings are parsed as numbers using `Number.parseFloat()` after removing all non-numeric characters.
  * - Dates return their milliseconds (e.g. `date.getTime()`).
  * - Everything else returns `undefined`
+ *
+ * @param value The value to convert.
+ * @returns The finite number, or `undefined` if `value` cannot be converted.
+ * @example getNumber("1.5kg") // 1.5
+ * @see https://dhoulb.github.io/shelving/util/number/getNumber
  */
 export function getNumber(value) {
     if (typeof value === "number" && Number.isFinite(value))
@@ -31,17 +56,46 @@ export function getNumber(value) {
 const NOT_NUMERIC_REGEXP = /[^0-9-.]/g;
 /**
  * Convert a possible number to a finite number, or throw `ValueError` if the value cannot be converted.
+ *
+ * @param value The value to convert.
+ * @param min Minimum allowed value, inclusive.
+ * @param max Maximum allowed value, inclusive.
+ * @param caller Function used to attribute a thrown error to the calling site.
+ * @returns The finite number.
+ * @throws RequiredError if `value` cannot be converted to a finite number within range.
+ * @example requireNumber("42") // 42
+ * @see https://dhoulb.github.io/shelving/util/number/requireNumber
  */
 export function requireNumber(value, min, max, caller) {
     const num = getNumber(value);
     assertNumber(num, min, max, caller);
     return num;
 }
-/** Is an unknown value an integer (optionally with specified min/max values). */
+/**
+ * Is an unknown value an integer (optionally within specified min/max values)?
+ *
+ * @param value The value to test.
+ * @param min Minimum allowed value, inclusive (defaults to `Number.MIN_SAFE_INTEGER`).
+ * @param max Maximum allowed value, inclusive (defaults to `Number.MAX_SAFE_INTEGER`).
+ * @returns `true` if `value` is an integer within range, otherwise `false`.
+ * @example isInteger(5, 0, 10) // true
+ * @see https://dhoulb.github.io/shelving/util/number/isInteger
+ */
 export function isInteger(value, min = Number.MIN_SAFE_INTEGER, max = Number.MAX_SAFE_INTEGER) {
     return Number.isInteger(value) && value >= min && value <= max;
 }
-/** Assert that a value is an integer. */
+/**
+ * Assert that a value is an integer (optionally within specified min/max values).
+ *
+ * @param value The value to assert.
+ * @param min Minimum allowed value, inclusive.
+ * @param max Maximum allowed value, inclusive.
+ * @param caller Function used to attribute a thrown error to the calling site.
+ * @returns Nothing; narrows `value` to `number`.
+ * @throws RequiredError if `value` is not an integer within range.
+ * @example assertInteger(5, 0, 10); // passes
+ * @see https://dhoulb.github.io/shelving/util/number/assertInteger
+ */
 export function assertInteger(value, min, max, caller = assertInteger) {
     if (!isInteger(value, min, max))
         throw new RequiredError(`Must be integer${max !== undefined ? ` between ${min ?? 0} and ${max}` : min !== undefined ? ` above ${min}` : ""}`, { received: value, caller });
@@ -55,6 +109,11 @@ export function assertInteger(value, min, max, caller = assertInteger) {
  * - Strings are parsed as integers using `parseInt()` after removing non-numeric characters.
  * - Dates return their milliseconds (e.g. `date.getTime()`).
  * - Everything else returns `undefined`
+ *
+ * @param value The value to convert.
+ * @returns The integer, or `undefined` if `value` cannot be converted.
+ * @example getInteger("42px") // 42
+ * @see https://dhoulb.github.io/shelving/util/number/getInteger
  */
 export function getInteger(value) {
     if (typeof value === "number" && Number.isInteger(value))
@@ -64,7 +123,18 @@ export function getInteger(value) {
     if (value instanceof Date)
         return getInteger(value.getTime());
 }
-/** Convert a possible number to an integer, or throw `ValueError` if the value cannot be converted. */
+/**
+ * Convert a possible number to an integer, or throw `ValueError` if the value cannot be converted.
+ *
+ * @param value The value to convert.
+ * @param min Minimum allowed value, inclusive.
+ * @param max Maximum allowed value, inclusive.
+ * @param caller Function used to attribute a thrown error to the calling site.
+ * @returns The integer.
+ * @throws RequiredError if `value` cannot be converted to an integer within range.
+ * @example requireInteger("42") // 42
+ * @see https://dhoulb.github.io/shelving/util/number/requireInteger
+ */
 export function requireInteger(value, min, max, caller = requireInteger) {
     const num = getNumber(value);
     assertInteger(num, min, max, caller);
@@ -76,6 +146,9 @@ export function requireInteger(value, min, max, caller = requireInteger) {
  * @param num The number to test, e.g. `17`
  * @param min The start of the range, e.g. `10`
  * @param max The end of the range, e.g. `20`
+ * @returns `true` if `num` is between `min` and `max` (inclusive), otherwise `false`.
+ * @example isBetween(17, 10, 20) // true
+ * @see https://dhoulb.github.io/shelving/util/number/isBetween
  */
 export function isBetween(num, min, max) {
     return num >= min && num <= max;
@@ -87,6 +160,8 @@ export function isBetween(num, min, max) {
  * @param step The rounding to round to, e.g. `2` or `0.1` (defaults to `1`, i.e. round numbers).
  *
  * @returns The number rounded to the specified step.
+ * @example roundStep(17, 5) // 15
+ * @see https://dhoulb.github.io/shelving/util/number/roundStep
  */
 export function roundStep(num, step = 1) {
     return Math.round(num / step) * step;
@@ -100,6 +175,8 @@ export function roundStep(num, step = 1) {
  * @param precision Maximum number of digits shown after the decimal point (defaults to 10).
  *
  * @returns The number rounded to the specified precision.
+ * @example roundNumber(1.2345, 2) // 1.23
+ * @see https://dhoulb.github.io/shelving/util/number/roundNumber
  */
 export function roundNumber(num, precision = 0) {
     return Math.round(num * 10 ** precision) / 10 ** precision;
@@ -111,6 +188,8 @@ export function roundNumber(num, precision = 0) {
  * @param num The number to truncate.
  * @param precision Maximum number of digits shown after the decimal point (defaults to 0).
  * @returns The number truncated to the specified precision.
+ * @example truncateNumber(1.2999, 2) // 1.29
+ * @see https://dhoulb.github.io/shelving/util/number/truncateNumber
  */
 export function truncateNumber(num, precision = 0) {
     return Math.trunc(num * 10 ** precision) / 10 ** precision;
@@ -118,6 +197,14 @@ export function truncateNumber(num, precision = 0) {
 /**
  * Bound a number between two values.
  * - e.g. `12` bounded by `2` and `8` is `8`
+ *
+ * @param num The number to bound.
+ * @param min The minimum bound, inclusive.
+ * @param max The maximum bound, inclusive.
+ * @returns `num` clamped to lie between `min` and `max`.
+ * @throws ValueError if `max` is less than `min`.
+ * @example boundNumber(12, 2, 8) // 8
+ * @see https://dhoulb.github.io/shelving/util/number/boundNumber
  */
 export function boundNumber(num, min, max) {
     if (max < min)
@@ -130,6 +217,14 @@ export function boundNumber(num, min, max) {
  * - e.g. `12` bounded by `2` and `8` is `6`
  * - Words in both directions.
  * - e.g. `-2` bounded by `2` and `8` is `4`
+ *
+ * @param num The number to wrap.
+ * @param min The minimum bound, inclusive.
+ * @param max The maximum bound, exclusive (values wrap back to `min`).
+ * @returns `num` wrapped to lie between `min` and `max`.
+ * @throws ValueError if `max` is less than `min`.
+ * @example wrapNumber(12, 2, 8) // 6
+ * @see https://dhoulb.github.io/shelving/util/number/wrapNumber
  */
 export function wrapNumber(num, min, max) {
     if (max < min)
@@ -145,18 +240,36 @@ export function wrapNumber(num, min, max) {
  *
  * @param numerator Number representing the amount of progress.
  * @param denumerator The number representing the whole amount (defaults to 100).
+ * @returns `numerator` expressed as a percentage of `denumerator`.
+ * @example getPercent(1, 4) // 25
+ * @see https://dhoulb.github.io/shelving/util/number/getPercent
  */
 export function getPercent(numerator, denumerator = 100) {
     return denumerator === 100 ? numerator : (100 / denumerator) * numerator;
 }
-/** Sum an iterable set of numbers and return the total. */
+/**
+ * Sum an iterable set of numbers and return the total.
+ *
+ * @param nums The iterable of numbers to sum.
+ * @returns The total of all the numbers (`0` if `nums` is empty).
+ * @example sumNumbers([1, 2, 3]) // 6
+ * @see https://dhoulb.github.io/shelving/util/number/sumNumbers
+ */
 export function sumNumbers(nums) {
     let sum = 0;
     for (const num of nums)
         sum += num;
     return sum;
 }
-/** Find the number that's closest to a target in an iterable set of numbers. */
+/**
+ * Find the number that's closest to a target in an iterable set of numbers.
+ *
+ * @param nums The iterable of numbers to search.
+ * @param target The target number to find the closest match for.
+ * @returns The number closest to `target`, or `undefined` if `nums` is empty.
+ * @example getClosestNumber([1, 5, 10], 6) // 5
+ * @see https://dhoulb.github.io/shelving/util/number/getClosestNumber
+ */
 export function getClosestNumber(nums, target) {
     let closest;
     for (const item of nums)