effect 4.0.0-beta.70 → 4.0.0-beta.71

package/src/Number.ts

@@ -1,6 +1,60 @@
 /**
- * This module provides utility functions and type class instances for working with the `number` type in TypeScript.
- * It includes functions for basic arithmetic operations.
+ * Operations for working with TypeScript `number` values. Use this module for
+ * arithmetic, safe parsing and division, comparisons, range checks, clamping,
+ * rounding, and reducers for numeric aggregation.
+ *
+ * **Mental model**
+ *
+ * Numbers remain plain JavaScript numbers, including `NaN`, `Infinity`, and
+ * floating-point behavior. The module adds named operations around that runtime
+ * model: arithmetic such as {@link sum}, {@link multiply}, {@link subtract},
+ * and {@link remainder}; safety wrappers such as {@link parse} and
+ * {@link divide}; range helpers such as {@link between} and {@link clamp}; and
+ * instances such as {@link Order} and {@link Equivalence}.
+ *
+ * **Common tasks**
+ *
+ * - Coerce, parse, or narrow input: {@link Number}, {@link parse},
+ *   {@link isNumber}
+ * - Do arithmetic: {@link sum}, {@link multiply}, {@link subtract},
+ *   {@link divide}, {@link divideUnsafe}, {@link remainder}, {@link round}
+ * - Work with counters and powers: {@link increment}, {@link decrement},
+ *   {@link nextPow2}
+ * - Compare and bound values: {@link isLessThan}, {@link isGreaterThan},
+ *   {@link between}, {@link clamp}, {@link min}, {@link max}, {@link sign}
+ * - Aggregate iterables or reducer inputs: {@link sumAll}, {@link multiplyAll},
+ *   {@link ReducerSum}, {@link ReducerMultiply}, {@link ReducerMax},
+ *   {@link ReducerMin}
+ *
+ * **Gotchas**
+ *
+ * - {@link Number} is the native JavaScript constructor. For example,
+ *   `Number.Number("")` returns `0`; {@link parse} returns `Option.none()` for
+ *   blank strings and invalid numeric text.
+ * - {@link divide} returns `Option.none()` only when the divisor is `0`.
+ *   Other JavaScript number results, including `NaN`, still follow normal
+ *   number semantics.
+ * - {@link Equivalence} treats `NaN` as equivalent to `NaN`, unlike `===`.
+ * - Reducers have identity values: {@link ReducerSum} starts at `0`,
+ *   {@link ReducerMultiply} starts at `1`, {@link ReducerMax} starts at
+ *   `-Infinity`, and {@link ReducerMin} starts at `Infinity`.
+ *
+ * **Quickstart**
+ *
+ * **Example** (Parsing and bounding a number)
+ *
+ * ```ts
+ * import { Number } from "effect"
+ *
+ * const parsed = Number.parse("42")
+ * console.log(parsed) // Option.some(42)
+ *
+ * const bounded = Number.clamp(120, { minimum: 0, maximum: 100 })
+ * console.log(bounded) // 100
+ *
+ * const total = Number.sumAll([1, 2, 3])
+ * console.log(total) // 6
+ * ```
  *
  * @since 2.0.0
  */
@@ -15,6 +69,18 @@ import * as Reducer from "./Reducer.ts"
 /**
  * The global `Number` constructor.
  *
+ * **When to use**
+ *
+ * Use when you want native `Number` constructor coercion from the Effect module
+ * namespace.
+ *
+ * **Gotchas**
+ *
+ * This follows native `Number` coercion rules, including empty strings
+ * becoming `0` and invalid numeric strings becoming `NaN`.
+ *
+ * @see {@link parse} for parsing strings into an `Option`
+ *
  * **Example** (Coercing values to numbers)
  *
  * ```ts
@@ -35,6 +101,10 @@ export const Number = globalThis.Number
 /**
  * Tests if a value is a `number`.
  *
+ * **When to use**
+ *
+ * Use to validate unknown input and narrow it to `number`.
+ *
  * **Example** (Checking for numbers)
  *
  * ```ts
@@ -53,6 +123,10 @@ export const isNumber: (input: unknown) => input is number = predicate.isNumber
 /**
  * Provides an addition operation on `number`s.
  *
+ * **When to use**
+ *
+ * Use to add two numbers.
+ *
  * **Example** (Adding numbers)
  *
  * ```ts
@@ -62,6 +136,8 @@ export const isNumber: (input: unknown) => input is number = predicate.isNumber
  * assert.deepStrictEqual(Number.sum(2, 3), 5)
  * ```
  *
+ * @see {@link sumAll} for summing an iterable of numbers
+ *
  * @category math
  * @since 2.0.0
  */
@@ -69,6 +145,10 @@ export const sum: {
   /**
    * Provides an addition operation on `number`s.
    *
+   * **When to use**
+   *
+   * Use to add two numbers.
+   *
    * **Example** (Adding numbers)
    *
    * ```ts
@@ -78,6 +158,8 @@ export const sum: {
    * assert.deepStrictEqual(Number.sum(2, 3), 5)
    * ```
    *
+   * @see {@link sumAll} for summing an iterable of numbers
+   *
    * @category math
    * @since 2.0.0
    */
@@ -85,6 +167,10 @@ export const sum: {
   /**
    * Provides an addition operation on `number`s.
    *
+   * **When to use**
+   *
+   * Use to add two numbers.
+   *
    * **Example** (Adding numbers)
    *
    * ```ts
@@ -94,6 +180,8 @@ export const sum: {
    * assert.deepStrictEqual(Number.sum(2, 3), 5)
    * ```
    *
+   * @see {@link sumAll} for summing an iterable of numbers
+   *
    * @category math
    * @since 2.0.0
    */
@@ -103,6 +191,10 @@ export const sum: {
 /**
  * Provides a multiplication operation on `number`s.
  *
+ * **When to use**
+ *
+ * Use to multiply two numbers.
+ *
  * **Example** (Multiplying numbers)
  *
  * ```ts
@@ -112,6 +204,8 @@ export const sum: {
  * assert.deepStrictEqual(Number.multiply(2, 3), 6)
  * ```
  *
+ * @see {@link multiplyAll} for multiplying an iterable of numbers
+ *
  * @category math
  * @since 2.0.0
  */
@@ -119,6 +213,10 @@ export const multiply: {
   /**
    * Provides a multiplication operation on `number`s.
    *
+   * **When to use**
+   *
+   * Use to multiply two numbers.
+   *
    * **Example** (Multiplying numbers)
    *
    * ```ts
@@ -128,6 +226,8 @@ export const multiply: {
    * assert.deepStrictEqual(Number.multiply(2, 3), 6)
    * ```
    *
+   * @see {@link multiplyAll} for multiplying an iterable of numbers
+   *
    * @category math
    * @since 2.0.0
    */
@@ -135,6 +235,10 @@ export const multiply: {
   /**
    * Provides a multiplication operation on `number`s.
    *
+   * **When to use**
+   *
+   * Use to multiply two numbers.
+   *
    * **Example** (Multiplying numbers)
    *
    * ```ts
@@ -144,6 +248,8 @@ export const multiply: {
    * assert.deepStrictEqual(Number.multiply(2, 3), 6)
    * ```
    *
+   * @see {@link multiplyAll} for multiplying an iterable of numbers
+   *
    * @category math
    * @since 2.0.0
    */
@@ -153,6 +259,10 @@ export const multiply: {
 /**
  * Provides a subtraction operation on `number`s.
  *
+ * **When to use**
+ *
+ * Use to subtract one number from another.
+ *
  * **Example** (Subtracting numbers)
  *
  * ```ts
@@ -169,6 +279,10 @@ export const subtract: {
   /**
    * Provides a subtraction operation on `number`s.
    *
+   * **When to use**
+   *
+   * Use to subtract one number from another.
+   *
    * **Example** (Subtracting numbers)
    *
    * ```ts
@@ -185,6 +299,10 @@ export const subtract: {
   /**
    * Provides a subtraction operation on `number`s.
    *
+   * **When to use**
+   *
+   * Use to subtract one number from another.
+   *
    * **Example** (Subtracting numbers)
    *
    * ```ts
@@ -203,6 +321,10 @@ export const subtract: {
 /**
  * Provides a division operation on `number`s, returning `Option.none()` if the divisor is `0`.
  *
+ * **When to use**
+ *
+ * Use to divide numbers while representing division by zero as `Option.none`.
+ *
  * **Example** (Dividing numbers safely)
  *
  * ```ts
@@ -212,6 +334,9 @@ export const subtract: {
  * Number.divide(6, 0) // Option.none()
  * ```
  *
+ * @see {@link divideUnsafe} for division that throws when the divisor is zero
+ * @see {@link remainder} for the numeric remainder operation
+ *
  * @category math
  * @since 2.0.0
  */
@@ -219,6 +344,10 @@ export const divide: {
   /**
    * Provides a division operation on `number`s, returning `Option.none()` if the divisor is `0`.
    *
+   * **When to use**
+   *
+   * Use to divide numbers while representing division by zero as `Option.none`.
+   *
    * **Example** (Dividing numbers safely)
    *
    * ```ts
@@ -228,6 +357,9 @@ export const divide: {
    * Number.divide(6, 0) // Option.none()
    * ```
    *
+   * @see {@link divideUnsafe} for division that throws when the divisor is zero
+   * @see {@link remainder} for the numeric remainder operation
+   *
    * @category math
    * @since 2.0.0
    */
@@ -235,6 +367,10 @@ export const divide: {
   /**
    * Provides a division operation on `number`s, returning `Option.none()` if the divisor is `0`.
    *
+   * **When to use**
+   *
+   * Use to divide numbers while representing division by zero as `Option.none`.
+   *
    * **Example** (Dividing numbers safely)
    *
    * ```ts
@@ -244,6 +380,9 @@ export const divide: {
    * Number.divide(6, 0) // Option.none()
    * ```
    *
+   * @see {@link divideUnsafe} for division that throws when the divisor is zero
+   * @see {@link remainder} for the numeric remainder operation
+   *
    * @category math
    * @since 2.0.0
    */
@@ -256,6 +395,11 @@ export const divide: {
 /**
  * Provides an unsafe division operation on `number`s that throws a `RangeError` if the divisor is `0`.
  *
+ * **When to use**
+ *
+ * Use when the divisor is known to be non-zero and division by zero should be a
+ * thrown exception.
+ *
  * **Example** (Dividing numbers unsafely)
  *
  * ```ts
@@ -266,6 +410,8 @@ export const divide: {
  * // Passing 0 as the divisor throws a RangeError("Division by zero").
  * ```
  *
+ * @see {@link divide} for division that returns `Option.none` when the divisor is zero
+ *
  * @category math
  * @since 4.0.0
  */
@@ -273,6 +419,11 @@ export const divideUnsafe: {
   /**
    * Provides an unsafe division operation on `number`s that throws a `RangeError` if the divisor is `0`.
    *
+   * **When to use**
+   *
+   * Use when the divisor is known to be non-zero and division by zero should be a
+   * thrown exception.
+   *
    * **Example** (Dividing numbers unsafely)
    *
    * ```ts
@@ -283,6 +434,8 @@ export const divideUnsafe: {
    * // Passing 0 as the divisor throws a RangeError("Division by zero").
    * ```
    *
+   * @see {@link divide} for division that returns `Option.none` when the divisor is zero
+   *
    * @category math
    * @since 4.0.0
    */
@@ -290,6 +443,11 @@ export const divideUnsafe: {
   /**
    * Provides an unsafe division operation on `number`s that throws a `RangeError` if the divisor is `0`.
    *
+   * **When to use**
+   *
+   * Use when the divisor is known to be non-zero and division by zero should be a
+   * thrown exception.
+   *
    * **Example** (Dividing numbers unsafely)
    *
    * ```ts
@@ -300,6 +458,8 @@ export const divideUnsafe: {
    * // Passing 0 as the divisor throws a RangeError("Division by zero").
    * ```
    *
+   * @see {@link divide} for division that returns `Option.none` when the divisor is zero
+   *
    * @category math
    * @since 4.0.0
    */
@@ -313,6 +473,10 @@ export const divideUnsafe: {
 /**
  * Returns the result of adding `1` to a given number.
  *
+ * **When to use**
+ *
+ * Use to increment a numeric counter by one.
+ *
  * **Example** (Incrementing a number)
  *
  * ```ts
@@ -330,6 +494,10 @@ export const increment = (n: number): number => n + 1
 /**
  * Decrements a number by `1`.
  *
+ * **When to use**
+ *
+ * Use to decrement a numeric counter by one.
+ *
  * **Example** (Decrementing a number)
  *
  * ```ts
@@ -347,6 +515,10 @@ export const decrement = (n: number): number => n - 1
 /**
  * An `Order` instance for `number` values.
  *
+ * **When to use**
+ *
+ * Use when an API needs an `Order` instance for numbers.
+ *
  * **Example** (Comparing numbers)
  *
  * ```ts
@@ -365,6 +537,10 @@ export const Order: order.Order<number> = order.Number
 /**
  * An `Equivalence` instance for numbers where `NaN` is considered equal to `NaN`.
  *
+ * **When to use**
+ *
+ * Use when an API needs an `Equivalence` instance for numeric equality.
+ *
  * **Example** (Comparing numbers for equivalence)
  *
  * ```ts
@@ -383,6 +559,10 @@ export const Equivalence: Equ.Equivalence<number> = Equ.Number
 /**
  * Returns `true` if the first argument is less than the second, otherwise `false`.
  *
+ * **When to use**
+ *
+ * Use to test whether one number is strictly less than another.
+ *
  * **Example** (Checking less-than comparisons)
  *
  * ```ts
@@ -401,6 +581,10 @@ export const isLessThan: {
   /**
    * Returns `true` if the first argument is less than the second, otherwise `false`.
    *
+   * **When to use**
+   *
+   * Use to test whether one number is strictly less than another.
+   *
    * **Example** (Checking less-than comparisons)
    *
    * ```ts
@@ -419,6 +603,10 @@ export const isLessThan: {
   /**
    * Returns `true` if the first argument is less than the second, otherwise `false`.
    *
+   * **When to use**
+   *
+   * Use to test whether one number is strictly less than another.
+   *
    * **Example** (Checking less-than comparisons)
    *
    * ```ts
@@ -439,6 +627,10 @@ export const isLessThan: {
 /**
  * Returns a function that checks if a given `number` is less than or equal to the provided one.
  *
+ * **When to use**
+ *
+ * Use to test whether one number is less than or equal to another.
+ *
  * **Example** (Checking less-than-or-equal comparisons)
  *
  * ```ts
@@ -457,6 +649,10 @@ export const isLessThanOrEqualTo: {
   /**
    * Returns a function that checks if a given `number` is less than or equal to the provided one.
    *
+   * **When to use**
+   *
+   * Use to test whether one number is less than or equal to another.
+   *
    * **Example** (Checking less-than-or-equal comparisons)
    *
    * ```ts
@@ -475,6 +671,10 @@ export const isLessThanOrEqualTo: {
   /**
    * Returns a function that checks if a given `number` is less than or equal to the provided one.
    *
+   * **When to use**
+   *
+   * Use to test whether one number is less than or equal to another.
+   *
    * **Example** (Checking less-than-or-equal comparisons)
    *
    * ```ts
@@ -495,6 +695,10 @@ export const isLessThanOrEqualTo: {
 /**
  * Returns `true` if the first argument is greater than the second, otherwise `false`.
  *
+ * **When to use**
+ *
+ * Use to test whether one number is strictly greater than another.
+ *
  * **Example** (Checking greater-than comparisons)
  *
  * ```ts
@@ -513,6 +717,10 @@ export const isGreaterThan: {
   /**
    * Returns `true` if the first argument is greater than the second, otherwise `false`.
    *
+   * **When to use**
+   *
+   * Use to test whether one number is strictly greater than another.
+   *
    * **Example** (Checking greater-than comparisons)
    *
    * ```ts
@@ -531,6 +739,10 @@ export const isGreaterThan: {
   /**
    * Returns `true` if the first argument is greater than the second, otherwise `false`.
    *
+   * **When to use**
+   *
+   * Use to test whether one number is strictly greater than another.
+   *
    * **Example** (Checking greater-than comparisons)
    *
    * ```ts
@@ -551,6 +763,10 @@ export const isGreaterThan: {
 /**
  * Returns a function that checks if a given `number` is greater than or equal to the provided one.
  *
+ * **When to use**
+ *
+ * Use to test whether one number is greater than or equal to another.
+ *
  * **Example** (Checking greater-than-or-equal comparisons)
  *
  * ```ts
@@ -569,6 +785,10 @@ export const isGreaterThanOrEqualTo: {
   /**
    * Returns a function that checks if a given `number` is greater than or equal to the provided one.
    *
+   * **When to use**
+   *
+   * Use to test whether one number is greater than or equal to another.
+   *
    * **Example** (Checking greater-than-or-equal comparisons)
    *
    * ```ts
@@ -587,6 +807,10 @@ export const isGreaterThanOrEqualTo: {
   /**
    * Returns a function that checks if a given `number` is greater than or equal to the provided one.
    *
+   * **When to use**
+   *
+   * Use to test whether one number is greater than or equal to another.
+   *
    * **Example** (Checking greater-than-or-equal comparisons)
    *
    * ```ts
@@ -607,6 +831,10 @@ export const isGreaterThanOrEqualTo: {
 /**
  * Checks if a `number` is between a `minimum` and `maximum` value (inclusive).
  *
+ * **When to use**
+ *
+ * Use to test whether a number falls inside an inclusive range.
+ *
  * **Example** (Checking inclusive ranges)
  *
  * ```ts
@@ -620,6 +848,8 @@ export const isGreaterThanOrEqualTo: {
  * assert.deepStrictEqual(between(6), false)
  * ```
  *
+ * @see {@link clamp} for forcing a number into an inclusive range
+ *
  * @category predicates
  * @since 2.0.0
  */
@@ -627,6 +857,10 @@ export const between: {
   /**
    * Checks if a `number` is between a `minimum` and `maximum` value (inclusive).
    *
+   * **When to use**
+   *
+   * Use to test whether a number falls inside an inclusive range.
+   *
    * **Example** (Checking inclusive ranges)
    *
    * ```ts
@@ -640,6 +874,8 @@ export const between: {
    * assert.deepStrictEqual(between(6), false)
    * ```
    *
+   * @see {@link clamp} for forcing a number into an inclusive range
+   *
    * @category predicates
    * @since 2.0.0
    */
@@ -652,6 +888,10 @@ export const between: {
   /**
    * Checks if a `number` is between a `minimum` and `maximum` value (inclusive).
    *
+   * **When to use**
+   *
+   * Use to test whether a number falls inside an inclusive range.
+   *
    * **Example** (Checking inclusive ranges)
    *
    * ```ts
@@ -665,6 +905,8 @@ export const between: {
    * assert.deepStrictEqual(between(6), false)
    * ```
    *
+   * @see {@link clamp} for forcing a number into an inclusive range
+   *
    * @category predicates
    * @since 2.0.0
    */
@@ -680,6 +922,10 @@ export const between: {
 /**
  * Restricts the given `number` to be within the range specified by the `minimum` and `maximum` values.
  *
+ * **When to use**
+ *
+ * Use to force a number into an inclusive range.
+ *
  * **Details**
  *
  * - If the `number` is less than the `minimum` value, the function returns the `minimum` value.
@@ -699,6 +945,8 @@ export const between: {
  * assert.equal(clamp(6), 5)
  * ```
  *
+ * @see {@link between} for checking whether a number is already inside a range
+ *
  * @category math
  * @since 2.0.0
  */
@@ -706,6 +954,10 @@ export const clamp: {
   /**
    * Restricts the given `number` to be within the range specified by the `minimum` and `maximum` values.
    *
+   * **When to use**
+   *
+   * Use to force a number into an inclusive range.
+   *
    * **Details**
    *
    * - If the `number` is less than the `minimum` value, the function returns the `minimum` value.
@@ -725,6 +977,8 @@ export const clamp: {
    * assert.equal(clamp(6), 5)
    * ```
    *
+   * @see {@link between} for checking whether a number is already inside a range
+   *
    * @category math
    * @since 2.0.0
    */
@@ -737,6 +991,10 @@ export const clamp: {
   /**
    * Restricts the given `number` to be within the range specified by the `minimum` and `maximum` values.
    *
+   * **When to use**
+   *
+   * Use to force a number into an inclusive range.
+   *
    * **Details**
    *
    * - If the `number` is less than the `minimum` value, the function returns the `minimum` value.
@@ -756,6 +1014,8 @@ export const clamp: {
    * assert.equal(clamp(6), 5)
    * ```
    *
+   * @see {@link between} for checking whether a number is already inside a range
+   *
    * @category math
    * @since 2.0.0
    */
@@ -771,6 +1031,10 @@ export const clamp: {
 /**
  * Returns the minimum between two `number`s.
  *
+ * **When to use**
+ *
+ * Use to select the smaller of two numbers.
+ *
  * **Example** (Finding the minimum)
  *
  * ```ts
@@ -780,6 +1044,8 @@ export const clamp: {
  * assert.deepStrictEqual(Number.min(2, 3), 2)
  * ```
  *
+ * @see {@link max} for selecting the larger value
+ *
  * @category math
  * @since 2.0.0
  */
@@ -787,6 +1053,10 @@ export const min: {
   /**
    * Returns the minimum between two `number`s.
    *
+   * **When to use**
+   *
+   * Use to select the smaller of two numbers.
+   *
    * **Example** (Finding the minimum)
    *
    * ```ts
@@ -796,6 +1066,8 @@ export const min: {
    * assert.deepStrictEqual(Number.min(2, 3), 2)
    * ```
    *
+   * @see {@link max} for selecting the larger value
+   *
    * @category math
    * @since 2.0.0
    */
@@ -803,6 +1075,10 @@ export const min: {
   /**
    * Returns the minimum between two `number`s.
    *
+   * **When to use**
+   *
+   * Use to select the smaller of two numbers.
+   *
    * **Example** (Finding the minimum)
    *
    * ```ts
@@ -812,6 +1088,8 @@ export const min: {
    * assert.deepStrictEqual(Number.min(2, 3), 2)
    * ```
    *
+   * @see {@link max} for selecting the larger value
+   *
    * @category math
    * @since 2.0.0
    */
@@ -821,6 +1099,10 @@ export const min: {
 /**
  * Returns the maximum between two `number`s.
  *
+ * **When to use**
+ *
+ * Use to select the larger of two numbers.
+ *
  * **Example** (Finding the maximum)
  *
  * ```ts
@@ -830,6 +1112,8 @@ export const min: {
  * assert.deepStrictEqual(Number.max(2, 3), 3)
  * ```
  *
+ * @see {@link min} for selecting the smaller value
+ *
  * @category math
  * @since 2.0.0
  */
@@ -837,6 +1121,10 @@ export const max: {
   /**
    * Returns the maximum between two `number`s.
    *
+   * **When to use**
+   *
+   * Use to select the larger of two numbers.
+   *
    * **Example** (Finding the maximum)
    *
    * ```ts
@@ -846,6 +1134,8 @@ export const max: {
    * assert.deepStrictEqual(Number.max(2, 3), 3)
    * ```
    *
+   * @see {@link min} for selecting the smaller value
+   *
    * @category math
    * @since 2.0.0
    */
@@ -853,6 +1143,10 @@ export const max: {
   /**
    * Returns the maximum between two `number`s.
    *
+   * **When to use**
+   *
+   * Use to select the larger of two numbers.
+   *
    * **Example** (Finding the maximum)
    *
    * ```ts
@@ -862,6 +1156,8 @@ export const max: {
    * assert.deepStrictEqual(Number.max(2, 3), 3)
    * ```
    *
+   * @see {@link min} for selecting the smaller value
+   *
    * @category math
    * @since 2.0.0
    */
@@ -871,6 +1167,10 @@ export const max: {
 /**
  * Determines the sign of a given `number`.
  *
+ * **When to use**
+ *
+ * Use to classify a number as negative, zero, or positive.
+ *
  * **Example** (Determining the sign)
  *
  * ```ts
@@ -890,6 +1190,10 @@ export const sign = (n: number): Ordering => Order(n, 0)
 /**
  * Takes an `Iterable` of `number`s and returns their sum as a single `number`.
  *
+ * **When to use**
+ *
+ * Use to sum all numbers in an iterable.
+ *
  * **Example** (Summing an iterable)
  *
  * ```ts
@@ -899,6 +1203,9 @@ export const sign = (n: number): Ordering => Order(n, 0)
  * assert.deepStrictEqual(Number.sumAll([2, 3, 4]), 9)
  * ```
  *
+ * @see {@link sum} for adding two numbers
+ * @see {@link ReducerSum} for summing through APIs that consume a `Reducer`
+ *
  * @category math
  * @since 2.0.0
  */
@@ -913,6 +1220,10 @@ export const sumAll = (collection: Iterable<number>): number => {
 /**
  * Takes an `Iterable` of `number`s and returns their multiplication as a single `number`.
  *
+ * **When to use**
+ *
+ * Use to multiply all numbers in an iterable.
+ *
  * **Example** (Multiplying an iterable)
  *
  * ```ts
@@ -922,6 +1233,9 @@ export const sumAll = (collection: Iterable<number>): number => {
  * assert.deepStrictEqual(Number.multiplyAll([2, 3, 4]), 24)
  * ```
  *
+ * @see {@link multiply} for multiplying two numbers
+ * @see {@link ReducerMultiply} for multiplying through APIs that consume a `Reducer`
+ *
  * @category math
  * @since 2.0.0
  */
@@ -939,6 +1253,11 @@ export const multiplyAll = (collection: Iterable<number>): number => {
 /**
  * Returns the remainder left over when one operand is divided by a second operand, always taking the sign of the dividend.
  *
+ * **When to use**
+ *
+ * Use to compute a numeric remainder while preserving decimal precision better
+ * than direct JavaScript `%` for decimal operands.
+ *
  * **Example** (Calculating remainders)
  *
  * ```ts
@@ -950,6 +1269,8 @@ export const multiplyAll = (collection: Iterable<number>): number => {
  * assert.deepStrictEqual(Number.remainder(-4, 2), -0)
  * ```
  *
+ * @see {@link divide} for quotient calculation with division-by-zero represented as `Option.none`
+ *
  * @category math
  * @since 2.0.0
  */
@@ -957,6 +1278,11 @@ export const remainder: {
   /**
    * Returns the remainder left over when one operand is divided by a second operand, always taking the sign of the dividend.
    *
+   * **When to use**
+   *
+   * Use to compute a numeric remainder while preserving decimal precision better
+   * than direct JavaScript `%` for decimal operands.
+   *
    * **Example** (Calculating remainders)
    *
    * ```ts
@@ -968,6 +1294,8 @@ export const remainder: {
    * assert.deepStrictEqual(Number.remainder(-4, 2), -0)
    * ```
    *
+   * @see {@link divide} for quotient calculation with division-by-zero represented as `Option.none`
+   *
    * @category math
    * @since 2.0.0
    */
@@ -975,6 +1303,11 @@ export const remainder: {
   /**
    * Returns the remainder left over when one operand is divided by a second operand, always taking the sign of the dividend.
    *
+   * **When to use**
+   *
+   * Use to compute a numeric remainder while preserving decimal precision better
+   * than direct JavaScript `%` for decimal operands.
+   *
    * **Example** (Calculating remainders)
    *
    * ```ts
@@ -986,6 +1319,8 @@ export const remainder: {
    * assert.deepStrictEqual(Number.remainder(-4, 2), -0)
    * ```
    *
+   * @see {@link divide} for quotient calculation with division-by-zero represented as `Option.none`
+   *
    * @category math
    * @since 2.0.0
    */
@@ -1013,6 +1348,10 @@ function decimalCount(n: number): number {
 /**
  * Returns the next power of 2 from the given number.
  *
+ * **When to use**
+ *
+ * Use to round a number up to the next power of two.
+ *
  * **Example** (Finding the next power of two)
  *
  * ```ts
@@ -1035,6 +1374,10 @@ export const nextPow2 = (n: number): number => {
  * Tries to parse a `number` from a `string` using the `Number()` function.
  * The following special string values are supported: "NaN", "Infinity", "-Infinity".
  *
+ * **When to use**
+ *
+ * Use to parse numeric text without throwing on invalid input.
+ *
  * **Example** (Parsing numbers from strings)
  *
  * ```ts
@@ -1048,6 +1391,8 @@ export const nextPow2 = (n: number): number => {
  * Number.parse("not a number") // Option.none()
  * ```
  *
+ * @see {@link Number} for native constructor coercion
+ *
  * @category constructors
  * @since 2.0.0
  */
@@ -1071,6 +1416,10 @@ export const parse = (s: string): Option.Option<number> => {
 /**
  * Returns the number rounded with the given precision.
  *
+ * **When to use**
+ *
+ * Use to round a number to a fixed number of decimal places.
+ *
  * **Example** (Rounding with precision)
  *
  * ```ts
@@ -1088,6 +1437,10 @@ export const round: {
   /**
    * Returns the number rounded with the given precision.
    *
+   * **When to use**
+   *
+   * Use to round a number to a fixed number of decimal places.
+   *
    * **Example** (Rounding with precision)
    *
    * ```ts
@@ -1105,6 +1458,10 @@ export const round: {
   /**
    * Returns the number rounded with the given precision.
    *
+   * **When to use**
+   *
+   * Use to round a number to a fixed number of decimal places.
+   *
    * **Example** (Rounding with precision)
    *
    * ```ts
@@ -1127,6 +1484,17 @@ export const round: {
 /**
  * A `Reducer` for combining `number`s using addition.
  *
+ * **When to use**
+ *
+ * Use to sum many numbers through APIs that consume a `Reducer`.
+ *
+ * **Details**
+ *
+ * The reducer starts from `0`, so `combineAll([])` returns `0`.
+ *
+ * @see {@link sumAll} for summing an iterable directly
+ * @see {@link ReducerMultiply} for multiplying number values
+ *
  * @category math
  * @since 4.0.0
  */
@@ -1135,6 +1503,21 @@ export const ReducerSum: Reducer.Reducer<number> = Reducer.make((a, b) => a + b,
 /**
  * A `Reducer` for combining `number`s using multiplication.
  *
+ * **When to use**
+ *
+ * Use to multiply many numbers through APIs that consume a `Reducer`.
+ *
+ * **Details**
+ *
+ * The reducer starts from `1`, so reducing an empty collection returns `1`.
+ *
+ * **Gotchas**
+ *
+ * Reducing an iterable short-circuits when it sees `0`, so later elements are
+ * not consumed.
+ *
+ * @see {@link multiplyAll} for multiplying an iterable directly
+ *
  * @category math
  * @since 4.0.0
  */
@@ -1150,6 +1533,22 @@ export const ReducerMultiply: Reducer.Reducer<number> = Reducer.make((a, b) => a
 /**
  * A `Reducer` for reducing `number`s by keeping the maximum value.
  *
+ * **When to use**
+ *
+ * Use to keep the largest number through APIs that consume a `Reducer`.
+ *
+ * **Details**
+ *
+ * The reducer starts from `-Infinity`, so reducing an empty collection returns
+ * `-Infinity`.
+ *
+ * **Gotchas**
+ *
+ * `NaN` values propagate through `Math.max`.
+ *
+ * @see {@link ReducerMin} for keeping the smallest number
+ * @see {@link max} for comparing two numbers directly
+ *
  * @category math
  * @since 4.0.0
  */
@@ -1158,6 +1557,22 @@ export const ReducerMax: Reducer.Reducer<number> = Reducer.make((a, b) => Math.m
 /**
  * A `Reducer` for reducing `number`s by keeping the minimum value.
  *
+ * **When to use**
+ *
+ * Use to keep the smallest number through APIs that consume a `Reducer`.
+ *
+ * **Details**
+ *
+ * The reducer starts from `Infinity`, so reducing an empty collection returns
+ * `Infinity`.
+ *
+ * **Gotchas**
+ *
+ * `NaN` values propagate through `Math.min`.
+ *
+ * @see {@link ReducerMax} for keeping the largest number
+ * @see {@link min} for comparing two numbers directly
+ *
  * @category math
  * @since 4.0.0
  */