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

package/dist/Number.d.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
  */
@@ -12,6 +66,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
@@ -31,6 +97,10 @@ export declare const Number: NumberConstructor;
 /**
  * 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
@@ -48,6 +118,10 @@ export declare const isNumber: (input: unknown) => input is number;
 /**
  * Provides an addition operation on `number`s.
  *
+ * **When to use**
+ *
+ * Use to add two numbers.
+ *
  * **Example** (Adding numbers)
  *
  * ```ts
@@ -57,6 +131,8 @@ export declare const isNumber: (input: unknown) => input is number;
  * assert.deepStrictEqual(Number.sum(2, 3), 5)
  * ```
  *
+ * @see {@link sumAll} for summing an iterable of numbers
+ *
  * @category math
  * @since 2.0.0
  */
@@ -64,6 +140,10 @@ export declare const sum: {
     /**
      * Provides an addition operation on `number`s.
      *
+     * **When to use**
+     *
+     * Use to add two numbers.
+     *
      * **Example** (Adding numbers)
      *
      * ```ts
@@ -73,6 +153,8 @@ export declare const sum: {
      * assert.deepStrictEqual(Number.sum(2, 3), 5)
      * ```
      *
+     * @see {@link sumAll} for summing an iterable of numbers
+     *
      * @category math
      * @since 2.0.0
      */
@@ -80,6 +162,10 @@ export declare const sum: {
     /**
      * Provides an addition operation on `number`s.
      *
+     * **When to use**
+     *
+     * Use to add two numbers.
+     *
      * **Example** (Adding numbers)
      *
      * ```ts
@@ -89,6 +175,8 @@ export declare const sum: {
      * assert.deepStrictEqual(Number.sum(2, 3), 5)
      * ```
      *
+     * @see {@link sumAll} for summing an iterable of numbers
+     *
      * @category math
      * @since 2.0.0
      */
@@ -97,6 +185,10 @@ export declare const sum: {
 /**
  * Provides a multiplication operation on `number`s.
  *
+ * **When to use**
+ *
+ * Use to multiply two numbers.
+ *
  * **Example** (Multiplying numbers)
  *
  * ```ts
@@ -106,6 +198,8 @@ export declare const sum: {
  * assert.deepStrictEqual(Number.multiply(2, 3), 6)
  * ```
  *
+ * @see {@link multiplyAll} for multiplying an iterable of numbers
+ *
  * @category math
  * @since 2.0.0
  */
@@ -113,6 +207,10 @@ export declare const multiply: {
     /**
      * Provides a multiplication operation on `number`s.
      *
+     * **When to use**
+     *
+     * Use to multiply two numbers.
+     *
      * **Example** (Multiplying numbers)
      *
      * ```ts
@@ -122,6 +220,8 @@ export declare const multiply: {
      * assert.deepStrictEqual(Number.multiply(2, 3), 6)
      * ```
      *
+     * @see {@link multiplyAll} for multiplying an iterable of numbers
+     *
      * @category math
      * @since 2.0.0
      */
@@ -129,6 +229,10 @@ export declare const multiply: {
     /**
      * Provides a multiplication operation on `number`s.
      *
+     * **When to use**
+     *
+     * Use to multiply two numbers.
+     *
      * **Example** (Multiplying numbers)
      *
      * ```ts
@@ -138,6 +242,8 @@ export declare const multiply: {
      * assert.deepStrictEqual(Number.multiply(2, 3), 6)
      * ```
      *
+     * @see {@link multiplyAll} for multiplying an iterable of numbers
+     *
      * @category math
      * @since 2.0.0
      */
@@ -146,6 +252,10 @@ export declare const multiply: {
 /**
  * Provides a subtraction operation on `number`s.
  *
+ * **When to use**
+ *
+ * Use to subtract one number from another.
+ *
  * **Example** (Subtracting numbers)
  *
  * ```ts
@@ -162,6 +272,10 @@ export declare const subtract: {
     /**
      * Provides a subtraction operation on `number`s.
      *
+     * **When to use**
+     *
+     * Use to subtract one number from another.
+     *
      * **Example** (Subtracting numbers)
      *
      * ```ts
@@ -178,6 +292,10 @@ export declare const subtract: {
     /**
      * Provides a subtraction operation on `number`s.
      *
+     * **When to use**
+     *
+     * Use to subtract one number from another.
+     *
      * **Example** (Subtracting numbers)
      *
      * ```ts
@@ -195,6 +313,10 @@ export declare 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
@@ -204,6 +326,9 @@ export declare 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
  */
@@ -211,6 +336,10 @@ export declare 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
@@ -220,6 +349,9 @@ export declare 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
      */
@@ -227,6 +359,10 @@ export declare 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
@@ -236,6 +372,9 @@ export declare 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
      */
@@ -244,6 +383,11 @@ export declare 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
@@ -254,6 +398,8 @@ export declare 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
  */
@@ -261,6 +407,11 @@ export declare 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
@@ -271,6 +422,8 @@ export declare 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
      */
@@ -278,6 +431,11 @@ export declare 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
@@ -288,6 +446,8 @@ export declare 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
      */
@@ -296,6 +456,10 @@ export declare 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
@@ -312,6 +476,10 @@ export declare const increment: (n: number) => number;
 /**
  * Decrements a number by `1`.
  *
+ * **When to use**
+ *
+ * Use to decrement a numeric counter by one.
+ *
  * **Example** (Decrementing a number)
  *
  * ```ts
@@ -328,6 +496,10 @@ export declare const decrement: (n: number) => number;
 /**
  * An `Order` instance for `number` values.
  *
+ * **When to use**
+ *
+ * Use when an API needs an `Order` instance for numbers.
+ *
  * **Example** (Comparing numbers)
  *
  * ```ts
@@ -345,6 +517,10 @@ export declare const Order: order.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
@@ -362,6 +538,10 @@ export declare const Equivalence: Equ.Equivalence<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
@@ -380,6 +560,10 @@ export declare 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
@@ -398,6 +582,10 @@ export declare 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
@@ -417,6 +605,10 @@ export declare 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
@@ -435,6 +627,10 @@ export declare 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
@@ -453,6 +649,10 @@ export declare 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
@@ -472,6 +672,10 @@ export declare 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
@@ -490,6 +694,10 @@ export declare 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
@@ -508,6 +716,10 @@ export declare 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
@@ -527,6 +739,10 @@ export declare 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
@@ -545,6 +761,10 @@ export declare 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
@@ -563,6 +783,10 @@ export declare 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
@@ -582,6 +806,10 @@ export declare 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
@@ -595,6 +823,8 @@ export declare const isGreaterThanOrEqualTo: {
  * assert.deepStrictEqual(between(6), false)
  * ```
  *
+ * @see {@link clamp} for forcing a number into an inclusive range
+ *
  * @category predicates
  * @since 2.0.0
  */
@@ -602,6 +832,10 @@ export declare 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
@@ -615,6 +849,8 @@ export declare const between: {
      * assert.deepStrictEqual(between(6), false)
      * ```
      *
+     * @see {@link clamp} for forcing a number into an inclusive range
+     *
      * @category predicates
      * @since 2.0.0
      */
@@ -625,6 +861,10 @@ export declare 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
@@ -638,6 +878,8 @@ export declare const between: {
      * assert.deepStrictEqual(between(6), false)
      * ```
      *
+     * @see {@link clamp} for forcing a number into an inclusive range
+     *
      * @category predicates
      * @since 2.0.0
      */
@@ -649,6 +891,10 @@ export declare 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.
@@ -668,6 +914,8 @@ export declare 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
  */
@@ -675,6 +923,10 @@ export declare 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.
@@ -694,6 +946,8 @@ export declare 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
      */
@@ -704,6 +958,10 @@ export declare 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.
@@ -723,6 +981,8 @@ export declare 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
      */
@@ -734,6 +994,10 @@ export declare 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
@@ -743,6 +1007,8 @@ export declare const clamp: {
  * assert.deepStrictEqual(Number.min(2, 3), 2)
  * ```
  *
+ * @see {@link max} for selecting the larger value
+ *
  * @category math
  * @since 2.0.0
  */
@@ -750,6 +1016,10 @@ export declare 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
@@ -759,6 +1029,8 @@ export declare const min: {
      * assert.deepStrictEqual(Number.min(2, 3), 2)
      * ```
      *
+     * @see {@link max} for selecting the larger value
+     *
      * @category math
      * @since 2.0.0
      */
@@ -766,6 +1038,10 @@ export declare 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
@@ -775,6 +1051,8 @@ export declare const min: {
      * assert.deepStrictEqual(Number.min(2, 3), 2)
      * ```
      *
+     * @see {@link max} for selecting the larger value
+     *
      * @category math
      * @since 2.0.0
      */
@@ -783,6 +1061,10 @@ export declare 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
@@ -792,6 +1074,8 @@ export declare const min: {
  * assert.deepStrictEqual(Number.max(2, 3), 3)
  * ```
  *
+ * @see {@link min} for selecting the smaller value
+ *
  * @category math
  * @since 2.0.0
  */
@@ -799,6 +1083,10 @@ export declare 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
@@ -808,6 +1096,8 @@ export declare const max: {
      * assert.deepStrictEqual(Number.max(2, 3), 3)
      * ```
      *
+     * @see {@link min} for selecting the smaller value
+     *
      * @category math
      * @since 2.0.0
      */
@@ -815,6 +1105,10 @@ export declare 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
@@ -824,6 +1118,8 @@ export declare const max: {
      * assert.deepStrictEqual(Number.max(2, 3), 3)
      * ```
      *
+     * @see {@link min} for selecting the smaller value
+     *
      * @category math
      * @since 2.0.0
      */
@@ -832,6 +1128,10 @@ export declare 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
@@ -850,6 +1150,10 @@ export declare const sign: (n: number) => Ordering;
 /**
  * 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
@@ -859,6 +1163,9 @@ export declare const sign: (n: number) => Ordering;
  * 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
  */
@@ -866,6 +1173,10 @@ export declare 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
@@ -875,6 +1186,9 @@ export declare 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
  */
@@ -882,6 +1196,11 @@ export declare 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
@@ -893,6 +1212,8 @@ export declare 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
  */
@@ -900,6 +1221,11 @@ export declare 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
@@ -911,6 +1237,8 @@ export declare 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
      */
@@ -918,6 +1246,11 @@ export declare 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
@@ -929,6 +1262,8 @@ export declare 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
      */
@@ -937,6 +1272,10 @@ export declare const remainder: {
 /**
  * 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
@@ -955,6 +1294,10 @@ export declare 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
@@ -968,6 +1311,8 @@ export declare 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
  */
@@ -975,6 +1320,10 @@ export declare 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
@@ -992,6 +1341,10 @@ export declare 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
@@ -1009,6 +1362,10 @@ export declare 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
@@ -1027,6 +1384,17 @@ export declare 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
  */
@@ -1034,6 +1402,21 @@ export declare const ReducerSum: Reducer.Reducer<number>;
 /**
  * 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
  */
@@ -1041,6 +1424,22 @@ export declare const ReducerMultiply: Reducer.Reducer<number>;
 /**
  * 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
  */
@@ -1048,6 +1447,22 @@ export declare const ReducerMax: Reducer.Reducer<number>;
 /**
  * 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
  */