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

package/src/BigInt.ts

@@ -1,6 +1,69 @@
 /**
- * This module provides utility functions and type class instances for working with the `bigint` type in TypeScript.
- * It includes functions for basic arithmetic operations.
+ * Tools for working with JavaScript `bigint` values in Effect code. The module
+ * includes arithmetic, comparisons, range checks, safe conversions, integer
+ * square roots, aggregation helpers, and `Order`, `Equivalence`, `Reducer`, and
+ * `Combiner` instances for APIs that consume those abstractions.
+ *
+ * Reach for `BigInt` when values may exceed JavaScript's safe `number` integer
+ * range, when conversions should make failure explicit with `Option`, or when
+ * Effect collection APIs need bigint-specific ordering or combining behavior.
+ *
+ * **Mental model**
+ *
+ * - Values are native JavaScript `bigint`s; the module does not introduce a
+ *   wrapper type.
+ * - Binary operations such as {@link sum}, {@link multiply}, {@link subtract},
+ *   {@link divide}, {@link min}, and {@link max} are dual and work in
+ *   data-first or data-last style.
+ * - Safe operations return `Option`, including {@link divide}, {@link sqrt},
+ *   {@link fromString}, {@link fromNumber}, and {@link toNumber}.
+ * - Unsafe or native operations keep JavaScript behavior, including thrown
+ *   errors from {@link BigInt}, {@link divideUnsafe}, {@link sqrtUnsafe}, and
+ *   {@link remainder} for invalid inputs.
+ *
+ * **Common tasks**
+ *
+ * - Check and construct values: {@link isBigInt}, {@link BigInt},
+ *   {@link fromString}, {@link fromNumber}, {@link toNumber}
+ * - Do arithmetic: {@link sum}, {@link multiply}, {@link subtract},
+ *   {@link divide}, {@link divideUnsafe}, {@link remainder}, {@link increment},
+ *   {@link decrement}
+ * - Compare and bound values: {@link Order}, {@link Equivalence},
+ *   {@link isLessThan}, {@link isLessThanOrEqualTo}, {@link isGreaterThan},
+ *   {@link isGreaterThanOrEqualTo}, {@link between}, {@link clamp},
+ *   {@link min}, {@link max}
+ * - Work with signs and number theory: {@link sign}, {@link abs}, {@link gcd},
+ *   {@link lcm}, {@link sqrt}, {@link sqrtUnsafe}
+ * - Aggregate many values: {@link sumAll}, {@link multiplyAll},
+ *   {@link ReducerSum}, {@link ReducerMultiply}, {@link CombinerMax},
+ *   {@link CombinerMin}
+ *
+ * **Gotchas**
+ *
+ * - JavaScript does not allow mixing `number` and `bigint` in arithmetic. Use
+ *   {@link fromNumber} and {@link toNumber} when crossing that boundary.
+ * - JavaScript `bigint` division truncates toward zero, and {@link remainder}
+ *   follows JavaScript `%` semantics.
+ * - The native {@link BigInt} constructor follows JavaScript coercion rules and
+ *   may throw. Use {@link fromString} or {@link fromNumber} when failed
+ *   conversion should be represented as `Option.none()`.
+ *
+ * **Quickstart**
+ *
+ * **Example** (Safe arithmetic and conversion)
+ *
+ * ```ts
+ * import { BigInt } from "effect"
+ *
+ * const total = BigInt.sumAll([10n, 20n, 30n])
+ * const average = BigInt.divide(total, 3n)
+ * const bounded = BigInt.clamp(total, { minimum: 0n, maximum: 50n })
+ *
+ * console.log(total) // 60n
+ * console.log(average) // Option.some(20n)
+ * console.log(bounded) // 50n
+ * console.log(BigInt.fromString("not an integer")) // Option.none()
+ * ```
  *
  * @since 2.0.0
  */
@@ -15,7 +78,20 @@ import * as predicate from "./Predicate.ts"
 import * as Reducer from "./Reducer.ts"
 
 /**
- * Reference to the global BigInt constructor.
+ * Reference to the global `BigInt` constructor for JavaScript bigint coercion.
+ *
+ * **When to use**
+ *
+ * Use when you want the native `BigInt` constructor behavior from the Effect
+ * module namespace.
+ *
+ * **Gotchas**
+ *
+ * This follows native `BigInt` coercion rules. It throws for invalid strings or
+ * non-integral numbers, and whitespace-only strings coerce to `0n`.
+ *
+ * @see {@link fromString} for parsing strings into an `Option`
+ * @see {@link fromNumber} for converting safe integers into an `Option`
  *
  * **Example** (Constructing bigints)
  *
@@ -41,6 +117,10 @@ const bigint2 = BigInt(2)
 /**
  * Tests if a value is a `bigint`.
  *
+ * **When to use**
+ *
+ * Use to validate unknown input and narrow it to `bigint`.
+ *
  * **Example** (Checking for bigints)
  *
  * ```ts
@@ -59,6 +139,10 @@ export const isBigInt: (u: unknown) => u is bigint = predicate.isBigInt
 /**
  * Provides an addition operation on `bigint`s.
  *
+ * **When to use**
+ *
+ * Use to add two `bigint` values.
+ *
  * **Example** (Adding bigints)
  *
  * ```ts
@@ -68,6 +152,8 @@ export const isBigInt: (u: unknown) => u is bigint = predicate.isBigInt
  * assert.deepStrictEqual(BigInt.sum(2n, 3n), 5n)
  * ```
  *
+ * @see {@link sumAll} for summing an iterable of `bigint` values
+ *
  * @category math
  * @since 2.0.0
  */
@@ -75,6 +161,10 @@ export const sum: {
   /**
    * Provides an addition operation on `bigint`s.
    *
+   * **When to use**
+   *
+   * Use to add two `bigint` values.
+   *
    * **Example** (Adding bigints)
    *
    * ```ts
@@ -84,6 +174,8 @@ export const sum: {
    * assert.deepStrictEqual(BigInt.sum(2n, 3n), 5n)
    * ```
    *
+   * @see {@link sumAll} for summing an iterable of `bigint` values
+   *
    * @category math
    * @since 2.0.0
    */
@@ -91,6 +183,10 @@ export const sum: {
   /**
    * Provides an addition operation on `bigint`s.
    *
+   * **When to use**
+   *
+   * Use to add two `bigint` values.
+   *
    * **Example** (Adding bigints)
    *
    * ```ts
@@ -100,6 +196,8 @@ export const sum: {
    * assert.deepStrictEqual(BigInt.sum(2n, 3n), 5n)
    * ```
    *
+   * @see {@link sumAll} for summing an iterable of `bigint` values
+   *
    * @category math
    * @since 2.0.0
    */
@@ -109,6 +207,10 @@ export const sum: {
 /**
  * Provides a multiplication operation on `bigint`s.
  *
+ * **When to use**
+ *
+ * Use to multiply two `bigint` values.
+ *
  * **Example** (Multiplying bigints)
  *
  * ```ts
@@ -118,6 +220,8 @@ export const sum: {
  * assert.deepStrictEqual(BigInt.multiply(2n, 3n), 6n)
  * ```
  *
+ * @see {@link multiplyAll} for multiplying an iterable of `bigint` values
+ *
  * @category math
  * @since 2.0.0
  */
@@ -125,6 +229,10 @@ export const multiply: {
   /**
    * Provides a multiplication operation on `bigint`s.
    *
+   * **When to use**
+   *
+   * Use to multiply two `bigint` values.
+   *
    * **Example** (Multiplying bigints)
    *
    * ```ts
@@ -134,6 +242,8 @@ export const multiply: {
    * assert.deepStrictEqual(BigInt.multiply(2n, 3n), 6n)
    * ```
    *
+   * @see {@link multiplyAll} for multiplying an iterable of `bigint` values
+   *
    * @category math
    * @since 2.0.0
    */
@@ -141,6 +251,10 @@ export const multiply: {
   /**
    * Provides a multiplication operation on `bigint`s.
    *
+   * **When to use**
+   *
+   * Use to multiply two `bigint` values.
+   *
    * **Example** (Multiplying bigints)
    *
    * ```ts
@@ -150,6 +264,8 @@ export const multiply: {
    * assert.deepStrictEqual(BigInt.multiply(2n, 3n), 6n)
    * ```
    *
+   * @see {@link multiplyAll} for multiplying an iterable of `bigint` values
+   *
    * @category math
    * @since 2.0.0
    */
@@ -159,6 +275,10 @@ export const multiply: {
 /**
  * Provides a subtraction operation on `bigint`s.
  *
+ * **When to use**
+ *
+ * Use to subtract one `bigint` value from another.
+ *
  * **Example** (Subtracting bigints)
  *
  * ```ts
@@ -175,6 +295,10 @@ export const subtract: {
   /**
    * Provides a subtraction operation on `bigint`s.
    *
+   * **When to use**
+   *
+   * Use to subtract one `bigint` value from another.
+   *
    * **Example** (Subtracting bigints)
    *
    * ```ts
@@ -191,6 +315,10 @@ export const subtract: {
   /**
    * Provides a subtraction operation on `bigint`s.
    *
+   * **When to use**
+   *
+   * Use to subtract one `bigint` value from another.
+   *
    * **Example** (Subtracting bigints)
    *
    * ```ts
@@ -209,6 +337,11 @@ export const subtract: {
 /**
  * Safely divides one `bigint` by another.
  *
+ * **When to use**
+ *
+ * Use to divide `bigint` values while representing division by zero as
+ * `Option.none`.
+ *
  * **Details**
  *
  * Uses JavaScript `bigint` division, so non-exact quotients are truncated
@@ -224,6 +357,9 @@ export const subtract: {
  * assert.deepStrictEqual(BigInt.divide(6n, 0n), Option.none())
  * ```
  *
+ * @see {@link divideUnsafe} for division that throws when the divisor is `0n`
+ * @see {@link remainder} for the JavaScript remainder operation
+ *
  * @category math
  * @since 2.0.0
  */
@@ -231,6 +367,11 @@ export const divide: {
   /**
    * Safely divides one `bigint` by another.
    *
+   * **When to use**
+   *
+   * Use to divide `bigint` values while representing division by zero as
+   * `Option.none`.
+   *
    * **Details**
    *
    * Uses JavaScript `bigint` division, so non-exact quotients are truncated
@@ -246,6 +387,9 @@ export const divide: {
    * assert.deepStrictEqual(BigInt.divide(6n, 0n), Option.none())
    * ```
    *
+   * @see {@link divideUnsafe} for division that throws when the divisor is `0n`
+   * @see {@link remainder} for the JavaScript remainder operation
+   *
    * @category math
    * @since 2.0.0
    */
@@ -253,6 +397,11 @@ export const divide: {
   /**
    * Safely divides one `bigint` by another.
    *
+   * **When to use**
+   *
+   * Use to divide `bigint` values while representing division by zero as
+   * `Option.none`.
+   *
    * **Details**
    *
    * Uses JavaScript `bigint` division, so non-exact quotients are truncated
@@ -268,6 +417,9 @@ export const divide: {
    * assert.deepStrictEqual(BigInt.divide(6n, 0n), Option.none())
    * ```
    *
+   * @see {@link divideUnsafe} for division that throws when the divisor is `0n`
+   * @see {@link remainder} for the JavaScript remainder operation
+   *
    * @category math
    * @since 2.0.0
    */
@@ -280,6 +432,11 @@ export const divide: {
 /**
  * Divides one `bigint` by another, throwing if the divisor is zero.
  *
+ * **When to use**
+ *
+ * Use when the divisor is known to be non-zero and division by zero should be a
+ * thrown exception.
+ *
  * **Details**
  *
  * Uses JavaScript `bigint` division, so non-exact quotients are truncated
@@ -299,6 +456,8 @@ export const divide: {
  * assert.deepStrictEqual(BigInt.divideUnsafe(6n, 4n), 1n)
  * ```
  *
+ * @see {@link divide} for division that returns `Option.none` when the divisor is `0n`
+ *
  * @category math
  * @since 4.0.0
  */
@@ -306,6 +465,11 @@ export const divideUnsafe: {
   /**
    * Divides one `bigint` by another, throwing if the divisor is zero.
    *
+   * **When to use**
+   *
+   * Use when the divisor is known to be non-zero and division by zero should be a
+   * thrown exception.
+   *
    * **Details**
    *
    * Uses JavaScript `bigint` division, so non-exact quotients are truncated
@@ -325,6 +489,8 @@ export const divideUnsafe: {
    * assert.deepStrictEqual(BigInt.divideUnsafe(6n, 4n), 1n)
    * ```
    *
+   * @see {@link divide} for division that returns `Option.none` when the divisor is `0n`
+   *
    * @category math
    * @since 4.0.0
    */
@@ -332,6 +498,11 @@ export const divideUnsafe: {
   /**
    * Divides one `bigint` by another, throwing if the divisor is zero.
    *
+   * **When to use**
+   *
+   * Use when the divisor is known to be non-zero and division by zero should be a
+   * thrown exception.
+   *
    * **Details**
    *
    * Uses JavaScript `bigint` division, so non-exact quotients are truncated
@@ -351,6 +522,8 @@ export const divideUnsafe: {
    * assert.deepStrictEqual(BigInt.divideUnsafe(6n, 4n), 1n)
    * ```
    *
+   * @see {@link divide} for division that returns `Option.none` when the divisor is `0n`
+   *
    * @category math
    * @since 4.0.0
    */
@@ -360,6 +533,10 @@ export const divideUnsafe: {
 /**
  * Returns the result of adding `1n` to a `bigint`.
  *
+ * **When to use**
+ *
+ * Use to increment a `bigint` counter by one.
+ *
  * **Example** (Incrementing a bigint)
  *
  * ```ts
@@ -377,6 +554,10 @@ export const increment = (n: bigint): bigint => n + bigint1
 /**
  * Returns the result of subtracting `1n` from a `bigint`.
  *
+ * **When to use**
+ *
+ * Use to decrement a `bigint` counter by one.
+ *
  * **Example** (Decrementing a bigint)
  *
  * ```ts
@@ -394,6 +575,10 @@ export const decrement = (n: bigint): bigint => n - bigint1
 /**
  * Provides an `Order` instance for `bigint` that allows comparing and sorting BigInt values.
  *
+ * **When to use**
+ *
+ * Use when an API needs an `Order` instance for `bigint` values.
+ *
  * **Example** (Comparing bigints with Order)
  *
  * ```ts
@@ -416,6 +601,10 @@ export const Order: order.Order<bigint> = order.BigInt
 /**
  * An `Equivalence` instance for bigints using strict equality (`===`).
  *
+ * **When to use**
+ *
+ * Use when an API needs an `Equivalence` instance for `bigint` equality.
+ *
  * **Example** (Comparing bigints for equivalence)
  *
  * ```ts
@@ -433,6 +622,10 @@ export const Equivalence: Equ.Equivalence<bigint> = Equ.BigInt
 /**
  * Returns `true` if the first argument is less than the second, otherwise `false`.
  *
+ * **When to use**
+ *
+ * Use to test whether one `bigint` is strictly less than another.
+ *
  * **Example** (Checking less-than comparisons)
  *
  * ```ts
@@ -451,6 +644,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 `bigint` is strictly less than another.
+   *
    * **Example** (Checking less-than comparisons)
    *
    * ```ts
@@ -469,6 +666,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 `bigint` is strictly less than another.
+   *
    * **Example** (Checking less-than comparisons)
    *
    * ```ts
@@ -489,6 +690,10 @@ export const isLessThan: {
 /**
  * Returns a function that checks if a given `bigint` is less than or equal to the provided one.
  *
+ * **When to use**
+ *
+ * Use to test whether one `bigint` is less than or equal to another.
+ *
  * **Example** (Checking less-than-or-equal comparisons)
  *
  * ```ts
@@ -507,6 +712,10 @@ export const isLessThanOrEqualTo: {
   /**
    * Returns a function that checks if a given `bigint` is less than or equal to the provided one.
    *
+   * **When to use**
+   *
+   * Use to test whether one `bigint` is less than or equal to another.
+   *
    * **Example** (Checking less-than-or-equal comparisons)
    *
    * ```ts
@@ -525,6 +734,10 @@ export const isLessThanOrEqualTo: {
   /**
    * Returns a function that checks if a given `bigint` is less than or equal to the provided one.
    *
+   * **When to use**
+   *
+   * Use to test whether one `bigint` is less than or equal to another.
+   *
    * **Example** (Checking less-than-or-equal comparisons)
    *
    * ```ts
@@ -545,6 +758,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 `bigint` is strictly greater than another.
+ *
  * **Example** (Checking greater-than comparisons)
  *
  * ```ts
@@ -563,6 +780,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 `bigint` is strictly greater than another.
+   *
    * **Example** (Checking greater-than comparisons)
    *
    * ```ts
@@ -581,6 +802,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 `bigint` is strictly greater than another.
+   *
    * **Example** (Checking greater-than comparisons)
    *
    * ```ts
@@ -601,6 +826,10 @@ export const isGreaterThan: {
 /**
  * Returns a function that checks if a given `bigint` is greater than or equal to the provided one.
  *
+ * **When to use**
+ *
+ * Use to test whether one `bigint` is greater than or equal to another.
+ *
  * **Example** (Checking greater-than-or-equal comparisons)
  *
  * ```ts
@@ -619,6 +848,10 @@ export const isGreaterThanOrEqualTo: {
   /**
    * Returns a function that checks if a given `bigint` is greater than or equal to the provided one.
    *
+   * **When to use**
+   *
+   * Use to test whether one `bigint` is greater than or equal to another.
+   *
    * **Example** (Checking greater-than-or-equal comparisons)
    *
    * ```ts
@@ -637,6 +870,10 @@ export const isGreaterThanOrEqualTo: {
   /**
    * Returns a function that checks if a given `bigint` is greater than or equal to the provided one.
    *
+   * **When to use**
+   *
+   * Use to test whether one `bigint` is greater than or equal to another.
+   *
    * **Example** (Checking greater-than-or-equal comparisons)
    *
    * ```ts
@@ -657,6 +894,10 @@ export const isGreaterThanOrEqualTo: {
 /**
  * Checks if a `bigint` is between a `minimum` and `maximum` value (inclusive).
  *
+ * **When to use**
+ *
+ * Use to test whether a `bigint` falls inside an inclusive range.
+ *
  * **Example** (Checking whether a bigint is within bounds)
  *
  * ```ts
@@ -670,6 +911,8 @@ export const isGreaterThanOrEqualTo: {
  * assert.deepStrictEqual(between(6n), false)
  * ```
  *
+ * @see {@link clamp} for forcing a `bigint` into an inclusive range
+ *
  * @category predicates
  * @since 2.0.0
  */
@@ -677,6 +920,10 @@ export const between: {
   /**
    * Checks if a `bigint` is between a `minimum` and `maximum` value (inclusive).
    *
+   * **When to use**
+   *
+   * Use to test whether a `bigint` falls inside an inclusive range.
+   *
    * **Example** (Checking whether a bigint is within bounds)
    *
    * ```ts
@@ -690,6 +937,8 @@ export const between: {
    * assert.deepStrictEqual(between(6n), false)
    * ```
    *
+   * @see {@link clamp} for forcing a `bigint` into an inclusive range
+   *
    * @category predicates
    * @since 2.0.0
    */
@@ -702,6 +951,10 @@ export const between: {
   /**
    * Checks if a `bigint` is between a `minimum` and `maximum` value (inclusive).
    *
+   * **When to use**
+   *
+   * Use to test whether a `bigint` falls inside an inclusive range.
+   *
    * **Example** (Checking whether a bigint is within bounds)
    *
    * ```ts
@@ -715,6 +968,8 @@ export const between: {
    * assert.deepStrictEqual(between(6n), false)
    * ```
    *
+   * @see {@link clamp} for forcing a `bigint` into an inclusive range
+   *
    * @category predicates
    * @since 2.0.0
    */
@@ -730,6 +985,10 @@ export const between: {
 /**
  * Restricts the given `bigint` to be within the range specified by the `minimum` and `maximum` values.
  *
+ * **When to use**
+ *
+ * Use to force a `bigint` into an inclusive range.
+ *
  * **Details**
  *
  * - If the `bigint` is less than the `minimum` value, the function returns the `minimum` value.
@@ -749,6 +1008,8 @@ export const between: {
  * assert.equal(clamp(6n), 5n)
  * ```
  *
+ * @see {@link between} for checking whether a `bigint` is already inside a range
+ *
  * @category math
  * @since 2.0.0
  */
@@ -756,6 +1017,10 @@ export const clamp: {
   /**
    * Restricts the given `bigint` to be within the range specified by the `minimum` and `maximum` values.
    *
+   * **When to use**
+   *
+   * Use to force a `bigint` into an inclusive range.
+   *
    * **Details**
    *
    * - If the `bigint` is less than the `minimum` value, the function returns the `minimum` value.
@@ -775,6 +1040,8 @@ export const clamp: {
    * assert.equal(clamp(6n), 5n)
    * ```
    *
+   * @see {@link between} for checking whether a `bigint` is already inside a range
+   *
    * @category math
    * @since 2.0.0
    */
@@ -787,6 +1054,10 @@ export const clamp: {
   /**
    * Restricts the given `bigint` to be within the range specified by the `minimum` and `maximum` values.
    *
+   * **When to use**
+   *
+   * Use to force a `bigint` into an inclusive range.
+   *
    * **Details**
    *
    * - If the `bigint` is less than the `minimum` value, the function returns the `minimum` value.
@@ -806,6 +1077,8 @@ export const clamp: {
    * assert.equal(clamp(6n), 5n)
    * ```
    *
+   * @see {@link between} for checking whether a `bigint` is already inside a range
+   *
    * @category math
    * @since 2.0.0
    */
@@ -821,6 +1094,10 @@ export const clamp: {
 /**
  * Returns the minimum between two `bigint`s.
  *
+ * **When to use**
+ *
+ * Use to select the smaller of two `bigint` values.
+ *
  * **Example** (Finding the minimum bigint)
  *
  * ```ts
@@ -830,6 +1107,8 @@ export const clamp: {
  * assert.deepStrictEqual(BigInt.min(2n, 3n), 2n)
  * ```
  *
+ * @see {@link max} for selecting the larger value
+ *
  * @category math
  * @since 2.0.0
  */
@@ -837,6 +1116,10 @@ export const min: {
   /**
    * Returns the minimum between two `bigint`s.
    *
+   * **When to use**
+   *
+   * Use to select the smaller of two `bigint` values.
+   *
    * **Example** (Finding the minimum bigint)
    *
    * ```ts
@@ -846,6 +1129,8 @@ export const min: {
    * assert.deepStrictEqual(BigInt.min(2n, 3n), 2n)
    * ```
    *
+   * @see {@link max} for selecting the larger value
+   *
    * @category math
    * @since 2.0.0
    */
@@ -853,6 +1138,10 @@ export const min: {
   /**
    * Returns the minimum between two `bigint`s.
    *
+   * **When to use**
+   *
+   * Use to select the smaller of two `bigint` values.
+   *
    * **Example** (Finding the minimum bigint)
    *
    * ```ts
@@ -862,6 +1151,8 @@ export const min: {
    * assert.deepStrictEqual(BigInt.min(2n, 3n), 2n)
    * ```
    *
+   * @see {@link max} for selecting the larger value
+   *
    * @category math
    * @since 2.0.0
    */
@@ -871,6 +1162,10 @@ export const min: {
 /**
  * Returns the maximum between two `bigint`s.
  *
+ * **When to use**
+ *
+ * Use to select the larger of two `bigint` values.
+ *
  * **Example** (Finding the maximum bigint)
  *
  * ```ts
@@ -880,6 +1175,8 @@ export const min: {
  * assert.deepStrictEqual(BigInt.max(2n, 3n), 3n)
  * ```
  *
+ * @see {@link min} for selecting the smaller value
+ *
  * @category math
  * @since 2.0.0
  */
@@ -887,6 +1184,10 @@ export const max: {
   /**
    * Returns the maximum between two `bigint`s.
    *
+   * **When to use**
+   *
+   * Use to select the larger of two `bigint` values.
+   *
    * **Example** (Finding the maximum bigint)
    *
    * ```ts
@@ -896,6 +1197,8 @@ export const max: {
    * assert.deepStrictEqual(BigInt.max(2n, 3n), 3n)
    * ```
    *
+   * @see {@link min} for selecting the smaller value
+   *
    * @category math
    * @since 2.0.0
    */
@@ -903,6 +1206,10 @@ export const max: {
   /**
    * Returns the maximum between two `bigint`s.
    *
+   * **When to use**
+   *
+   * Use to select the larger of two `bigint` values.
+   *
    * **Example** (Finding the maximum bigint)
    *
    * ```ts
@@ -912,6 +1219,8 @@ export const max: {
    * assert.deepStrictEqual(BigInt.max(2n, 3n), 3n)
    * ```
    *
+   * @see {@link min} for selecting the smaller value
+   *
    * @category math
    * @since 2.0.0
    */
@@ -921,6 +1230,10 @@ export const max: {
 /**
  * Determines the sign of a given `bigint`.
  *
+ * **When to use**
+ *
+ * Use to classify a `bigint` as negative, zero, or positive.
+ *
  * **Example** (Determining bigint signs)
  *
  * ```ts
@@ -940,6 +1253,10 @@ export const sign = (n: bigint): Ordering => order.BigInt(n, bigint0)
 /**
  * Determines the absolute value of a given `bigint`.
  *
+ * **When to use**
+ *
+ * Use to remove the sign from a `bigint` while preserving its magnitude.
+ *
  * **Example** (Calculating absolute values)
  *
  * ```ts
@@ -959,6 +1276,10 @@ export const abs = (n: bigint): bigint => (n < bigint0 ? -n : n)
 /**
  * Determines the greatest common divisor of two `bigint`s.
  *
+ * **When to use**
+ *
+ * Use to compute the greatest common divisor of two integer values.
+ *
  * **Example** (Calculating greatest common divisors)
  *
  * ```ts
@@ -970,6 +1291,8 @@ export const abs = (n: bigint): bigint => (n < bigint0 ? -n : n)
  * assert.deepStrictEqual(BigInt.gcd(16n, 24n), 8n)
  * ```
  *
+ * @see {@link lcm} for computing the least common multiple
+ *
  * @category math
  * @since 2.0.0
  */
@@ -977,6 +1300,10 @@ export const gcd: {
   /**
    * Determines the greatest common divisor of two `bigint`s.
    *
+   * **When to use**
+   *
+   * Use to compute the greatest common divisor of two integer values.
+   *
    * **Example** (Calculating greatest common divisors)
    *
    * ```ts
@@ -988,6 +1315,8 @@ export const gcd: {
    * assert.deepStrictEqual(BigInt.gcd(16n, 24n), 8n)
    * ```
    *
+   * @see {@link lcm} for computing the least common multiple
+   *
    * @category math
    * @since 2.0.0
    */
@@ -995,6 +1324,10 @@ export const gcd: {
   /**
    * Determines the greatest common divisor of two `bigint`s.
    *
+   * **When to use**
+   *
+   * Use to compute the greatest common divisor of two integer values.
+   *
    * **Example** (Calculating greatest common divisors)
    *
    * ```ts
@@ -1006,6 +1339,8 @@ export const gcd: {
    * assert.deepStrictEqual(BigInt.gcd(16n, 24n), 8n)
    * ```
    *
+   * @see {@link lcm} for computing the least common multiple
+   *
    * @category math
    * @since 2.0.0
    */
@@ -1022,6 +1357,10 @@ export const gcd: {
 /**
  * Determines the least common multiple of two `bigint`s.
  *
+ * **When to use**
+ *
+ * Use to compute the least common multiple of two integer values.
+ *
  * **Example** (Calculating least common multiples)
  *
  * ```ts
@@ -1033,6 +1372,8 @@ export const gcd: {
  * assert.deepStrictEqual(BigInt.lcm(16n, 24n), 48n)
  * ```
  *
+ * @see {@link gcd} for computing the greatest common divisor
+ *
  * @category math
  * @since 2.0.0
  */
@@ -1040,6 +1381,10 @@ export const lcm: {
   /**
    * Determines the least common multiple of two `bigint`s.
    *
+   * **When to use**
+   *
+   * Use to compute the least common multiple of two integer values.
+   *
    * **Example** (Calculating least common multiples)
    *
    * ```ts
@@ -1051,6 +1396,8 @@ export const lcm: {
    * assert.deepStrictEqual(BigInt.lcm(16n, 24n), 48n)
    * ```
    *
+   * @see {@link gcd} for computing the greatest common divisor
+   *
    * @category math
    * @since 2.0.0
    */
@@ -1058,6 +1405,10 @@ export const lcm: {
   /**
    * Determines the least common multiple of two `bigint`s.
    *
+   * **When to use**
+   *
+   * Use to compute the least common multiple of two integer values.
+   *
    * **Example** (Calculating least common multiples)
    *
    * ```ts
@@ -1069,6 +1420,8 @@ export const lcm: {
    * assert.deepStrictEqual(BigInt.lcm(16n, 24n), 48n)
    * ```
    *
+   * @see {@link gcd} for computing the greatest common divisor
+   *
    * @category math
    * @since 2.0.0
    */
@@ -1078,6 +1431,10 @@ export const lcm: {
 /**
  * Returns the integer square root of a non-negative `bigint`.
  *
+ * **When to use**
+ *
+ * Use when the input is known to be non-negative and invalid input should throw.
+ *
  * **Details**
  *
  * For non-perfect squares, returns the largest `bigint` whose square is less
@@ -1098,6 +1455,8 @@ export const lcm: {
  * assert.deepStrictEqual(BigInt.sqrtUnsafe(16n), 4n)
  * ```
  *
+ * @see {@link sqrt} for returning `Option.none` when the input is negative
+ *
  * @category math
  * @since 4.0.0
  */
@@ -1118,6 +1477,11 @@ export const sqrtUnsafe = (n: bigint): bigint => {
 /**
  * Safely returns the integer square root of a `bigint`.
  *
+ * **When to use**
+ *
+ * Use to compute an integer square root while representing negative input as
+ * `Option.none`.
+ *
  * **Details**
  *
  * For non-perfect squares, returns the largest `bigint` whose square is less
@@ -1135,6 +1499,8 @@ export const sqrtUnsafe = (n: bigint): bigint => {
  * BigInt.sqrt(-1n) // Option.none()
  * ```
  *
+ * @see {@link sqrtUnsafe} for square root computation that throws on negative input
+ *
  * @category math
  * @since 2.0.0
  */
@@ -1144,6 +1510,10 @@ export const sqrt = (n: bigint): Option.Option<bigint> =>
 /**
  * Takes an `Iterable` of `bigint`s and returns their sum as a single `bigint`. Returns `0n` for an empty iterable.
  *
+ * **When to use**
+ *
+ * Use to sum all `bigint` values in an iterable.
+ *
  * **Example** (Summing iterable bigints)
  *
  * ```ts
@@ -1153,6 +1523,9 @@ export const sqrt = (n: bigint): Option.Option<bigint> =>
  * assert.deepStrictEqual(BigInt.sumAll([2n, 3n, 4n]), 9n)
  * ```
  *
+ * @see {@link sum} for adding two `bigint` values
+ * @see {@link ReducerSum} for summing through APIs that consume a `Reducer`
+ *
  * @category math
  * @since 2.0.0
  */
@@ -1167,6 +1540,10 @@ export const sumAll = (collection: Iterable<bigint>): bigint => {
 /**
  * Takes an `Iterable` of `bigint`s and returns their product as a single `bigint`. Returns `1n` for an empty iterable.
  *
+ * **When to use**
+ *
+ * Use to multiply all `bigint` values in an iterable.
+ *
  * **Example** (Multiplying iterable bigints)
  *
  * ```ts
@@ -1176,6 +1553,9 @@ export const sumAll = (collection: Iterable<bigint>): bigint => {
  * assert.deepStrictEqual(BigInt.multiplyAll([2n, 3n, 4n]), 24n)
  * ```
  *
+ * @see {@link multiply} for multiplying two `bigint` values
+ * @see {@link ReducerMultiply} for multiplying through APIs that consume a `Reducer`
+ *
  * @category math
  * @since 2.0.0
  */
@@ -1193,6 +1573,11 @@ export const multiplyAll = (collection: Iterable<bigint>): bigint => {
 /**
  * Converts a `bigint` to a `number`.
  *
+ * **When to use**
+ *
+ * Use to convert a `bigint` to a JavaScript number only when it is a safe
+ * integer.
+ *
  * **Details**
  *
  * If the `bigint` is outside the safe integer range for JavaScript (`Number.MAX_SAFE_INTEGER`
@@ -1208,6 +1593,8 @@ export const multiplyAll = (collection: Iterable<bigint>): bigint => {
  * BI.toNumber(BigInt(Number.MIN_SAFE_INTEGER) - 1n) // Option.none()
  * ```
  *
+ * @see {@link fromNumber} for converting a safe integer number to `bigint`
+ *
  * @category converting
  * @since 2.0.0
  */
@@ -1221,6 +1608,10 @@ export const toNumber = (b: bigint): Option.Option<number> => {
 /**
  * Converts a string to a `bigint`.
  *
+ * **When to use**
+ *
+ * Use to parse a string as a `bigint` without throwing on invalid input.
+ *
  * **Details**
  *
  * If the string is empty or contains characters that cannot be converted into a
@@ -1236,6 +1627,8 @@ export const toNumber = (b: bigint): Option.Option<number> => {
  * BigInt.fromString("a") // Option.none()
  * ```
  *
+ * @see {@link BigInt} for native constructor coercion that throws on invalid input
+ *
  * @category converting
  * @since 2.4.12
  */
@@ -1252,6 +1645,10 @@ export const fromString = (s: string): Option.Option<bigint> => {
 /**
  * Converts a number to a `bigint`.
  *
+ * **When to use**
+ *
+ * Use to convert a JavaScript number to `bigint` only when it is a safe integer.
+ *
  * **Details**
  *
  * If the number is outside the safe integer range for JavaScript
@@ -1269,6 +1666,9 @@ export const fromString = (s: string): Option.Option<bigint> => {
  * BigInt.fromNumber(Number.MIN_SAFE_INTEGER - 1) // Option.none()
  * ```
  *
+ * @see {@link toNumber} for converting `bigint` values back to safe integer numbers
+ * @see {@link BigInt} for native constructor coercion
+ *
  * @category converting
  * @since 2.4.12
  */
@@ -1287,6 +1687,10 @@ export function fromNumber(n: number): Option.Option<bigint> {
 /**
  * Returns the JavaScript remainder of dividing one `bigint` by another.
  *
+ * **When to use**
+ *
+ * Use to compute the JavaScript `%` remainder for two `bigint` values.
+ *
  * **Details**
  *
  * The result follows JavaScript `%` semantics, including the sign of the
@@ -1306,6 +1710,8 @@ export function fromNumber(n: number): Option.Option<bigint> {
  * BigInt.remainder(15n, 4n) // 3n
  * ```
  *
+ * @see {@link divide} for quotient calculation with division-by-zero represented as `Option.none`
+ *
  * @category math
  * @since 4.0.0
  */
@@ -1313,6 +1719,10 @@ export const remainder: {
   /**
    * Returns the JavaScript remainder of dividing one `bigint` by another.
    *
+   * **When to use**
+   *
+   * Use to compute the JavaScript `%` remainder for two `bigint` values.
+   *
    * **Details**
    *
    * The result follows JavaScript `%` semantics, including the sign of the
@@ -1332,6 +1742,8 @@ export const remainder: {
    * BigInt.remainder(15n, 4n) // 3n
    * ```
    *
+   * @see {@link divide} for quotient calculation with division-by-zero represented as `Option.none`
+   *
    * @category math
    * @since 4.0.0
    */
@@ -1339,6 +1751,10 @@ export const remainder: {
   /**
    * Returns the JavaScript remainder of dividing one `bigint` by another.
    *
+   * **When to use**
+   *
+   * Use to compute the JavaScript `%` remainder for two `bigint` values.
+   *
    * **Details**
    *
    * The result follows JavaScript `%` semantics, including the sign of the
@@ -1358,6 +1774,8 @@ export const remainder: {
    * BigInt.remainder(15n, 4n) // 3n
    * ```
    *
+   * @see {@link divide} for quotient calculation with division-by-zero represented as `Option.none`
+   *
    * @category math
    * @since 4.0.0
    */
@@ -1367,6 +1785,17 @@ export const remainder: {
 /**
  * A `Reducer` for combining `bigint`s using addition.
  *
+ * **When to use**
+ *
+ * Use to sum many `bigint` values through APIs that consume a `Reducer`.
+ *
+ * **Details**
+ *
+ * The initial value is `0n`, so `combineAll([])` returns `0n`.
+ *
+ * @see {@link sumAll} for summing an iterable directly
+ * @see {@link ReducerMultiply} for multiplying `bigint` values
+ *
  * @category math
  * @since 4.0.0
  */
@@ -1375,6 +1804,17 @@ export const ReducerSum: Reducer.Reducer<bigint> = Reducer.make((a, b) => a + b,
 /**
  * A `Reducer` for combining `bigint`s using multiplication.
  *
+ * **When to use**
+ *
+ * Use to multiply many `bigint` values through APIs that consume a `Reducer`.
+ *
+ * **Details**
+ *
+ * The initial value is `1n`, so `combineAll([])` returns `1n`.
+ *
+ * @see {@link multiplyAll} for multiplying an iterable directly
+ * @see {@link ReducerSum} for summing `bigint` values
+ *
  * @category math
  * @since 4.0.0
  */
@@ -1390,6 +1830,13 @@ export const ReducerMultiply: Reducer.Reducer<bigint> = Reducer.make((a, b) => a
 /**
  * A `Combiner` that returns the maximum `bigint`.
  *
+ * **When to use**
+ *
+ * Use to keep the largest `bigint` when an API consumes a `Combiner`.
+ *
+ * @see {@link CombinerMin} for keeping the smallest `bigint`
+ * @see {@link max} for comparing two `bigint` values directly
+ *
  * @category math
  * @since 4.0.0
  */
@@ -1398,6 +1845,13 @@ export const CombinerMax: Combiner.Combiner<bigint> = Combiner.max(Order)
 /**
  * A `Combiner` that returns the minimum `bigint`.
  *
+ * **When to use**
+ *
+ * Use to keep the smallest `bigint` through APIs that consume a `Combiner`.
+ *
+ * @see {@link CombinerMax} for keeping the largest `bigint`
+ * @see {@link min} for comparing two `bigint` values directly
+ *
  * @category math
  * @since 4.0.0
  */