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

package/dist/BigInt.d.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
  */
@@ -11,7 +74,20 @@ import * as order from "./Order.ts";
 import type { Ordering } from "./Ordering.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)
  *
@@ -32,6 +108,10 @@ export declare const BigInt: BigIntConstructor;
 /**
  * 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
@@ -49,6 +129,10 @@ export declare const isBigInt: (u: unknown) => u is bigint;
 /**
  * Provides an addition operation on `bigint`s.
  *
+ * **When to use**
+ *
+ * Use to add two `bigint` values.
+ *
  * **Example** (Adding bigints)
  *
  * ```ts
@@ -58,6 +142,8 @@ export declare const isBigInt: (u: unknown) => u is bigint;
  * assert.deepStrictEqual(BigInt.sum(2n, 3n), 5n)
  * ```
  *
+ * @see {@link sumAll} for summing an iterable of `bigint` values
+ *
  * @category math
  * @since 2.0.0
  */
@@ -65,6 +151,10 @@ export declare const sum: {
     /**
      * Provides an addition operation on `bigint`s.
      *
+     * **When to use**
+     *
+     * Use to add two `bigint` values.
+     *
      * **Example** (Adding bigints)
      *
      * ```ts
@@ -74,6 +164,8 @@ export declare 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
      */
@@ -81,6 +173,10 @@ export declare const sum: {
     /**
      * Provides an addition operation on `bigint`s.
      *
+     * **When to use**
+     *
+     * Use to add two `bigint` values.
+     *
      * **Example** (Adding bigints)
      *
      * ```ts
@@ -90,6 +186,8 @@ export declare 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
      */
@@ -98,6 +196,10 @@ export declare const sum: {
 /**
  * Provides a multiplication operation on `bigint`s.
  *
+ * **When to use**
+ *
+ * Use to multiply two `bigint` values.
+ *
  * **Example** (Multiplying bigints)
  *
  * ```ts
@@ -107,6 +209,8 @@ export declare 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
  */
@@ -114,6 +218,10 @@ export declare const multiply: {
     /**
      * Provides a multiplication operation on `bigint`s.
      *
+     * **When to use**
+     *
+     * Use to multiply two `bigint` values.
+     *
      * **Example** (Multiplying bigints)
      *
      * ```ts
@@ -123,6 +231,8 @@ export declare 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
      */
@@ -130,6 +240,10 @@ export declare const multiply: {
     /**
      * Provides a multiplication operation on `bigint`s.
      *
+     * **When to use**
+     *
+     * Use to multiply two `bigint` values.
+     *
      * **Example** (Multiplying bigints)
      *
      * ```ts
@@ -139,6 +253,8 @@ export declare 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
      */
@@ -147,6 +263,10 @@ export declare const multiply: {
 /**
  * Provides a subtraction operation on `bigint`s.
  *
+ * **When to use**
+ *
+ * Use to subtract one `bigint` value from another.
+ *
  * **Example** (Subtracting bigints)
  *
  * ```ts
@@ -163,6 +283,10 @@ export declare const subtract: {
     /**
      * Provides a subtraction operation on `bigint`s.
      *
+     * **When to use**
+     *
+     * Use to subtract one `bigint` value from another.
+     *
      * **Example** (Subtracting bigints)
      *
      * ```ts
@@ -179,6 +303,10 @@ export declare const subtract: {
     /**
      * Provides a subtraction operation on `bigint`s.
      *
+     * **When to use**
+     *
+     * Use to subtract one `bigint` value from another.
+     *
      * **Example** (Subtracting bigints)
      *
      * ```ts
@@ -196,6 +324,11 @@ export declare 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
@@ -211,6 +344,9 @@ export declare 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
  */
@@ -218,6 +354,11 @@ export declare 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
@@ -233,6 +374,9 @@ export declare 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
      */
@@ -240,6 +384,11 @@ export declare 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
@@ -255,6 +404,9 @@ export declare 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
      */
@@ -263,6 +415,11 @@ export declare 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
@@ -282,6 +439,8 @@ export declare 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
  */
@@ -289,6 +448,11 @@ export declare 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
@@ -308,6 +472,8 @@ export declare 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
      */
@@ -315,6 +481,11 @@ export declare 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
@@ -334,6 +505,8 @@ export declare 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
      */
@@ -342,6 +515,10 @@ export declare 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
@@ -358,6 +535,10 @@ export declare const increment: (n: bigint) => bigint;
 /**
  * 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
@@ -374,6 +555,10 @@ export declare const decrement: (n: bigint) => bigint;
 /**
  * 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
@@ -395,6 +580,10 @@ export declare const Order: order.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
@@ -411,6 +600,10 @@ export declare const Equivalence: Equ.Equivalence<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
@@ -429,6 +622,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 `bigint` is strictly less than another.
+     *
      * **Example** (Checking less-than comparisons)
      *
      * ```ts
@@ -447,6 +644,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 `bigint` is strictly less than another.
+     *
      * **Example** (Checking less-than comparisons)
      *
      * ```ts
@@ -466,6 +667,10 @@ export declare 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
@@ -484,6 +689,10 @@ export declare 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
@@ -502,6 +711,10 @@ export declare 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
@@ -521,6 +734,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 `bigint` is strictly greater than another.
+ *
  * **Example** (Checking greater-than comparisons)
  *
  * ```ts
@@ -539,6 +756,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 `bigint` is strictly greater than another.
+     *
      * **Example** (Checking greater-than comparisons)
      *
      * ```ts
@@ -557,6 +778,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 `bigint` is strictly greater than another.
+     *
      * **Example** (Checking greater-than comparisons)
      *
      * ```ts
@@ -576,6 +801,10 @@ export declare 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
@@ -594,6 +823,10 @@ export declare 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
@@ -612,6 +845,10 @@ export declare 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
@@ -631,6 +868,10 @@ export declare 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
@@ -644,6 +885,8 @@ export declare const isGreaterThanOrEqualTo: {
  * assert.deepStrictEqual(between(6n), false)
  * ```
  *
+ * @see {@link clamp} for forcing a `bigint` into an inclusive range
+ *
  * @category predicates
  * @since 2.0.0
  */
@@ -651,6 +894,10 @@ export declare 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
@@ -664,6 +911,8 @@ export declare const between: {
      * assert.deepStrictEqual(between(6n), false)
      * ```
      *
+     * @see {@link clamp} for forcing a `bigint` into an inclusive range
+     *
      * @category predicates
      * @since 2.0.0
      */
@@ -674,6 +923,10 @@ export declare 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
@@ -687,6 +940,8 @@ export declare const between: {
      * assert.deepStrictEqual(between(6n), false)
      * ```
      *
+     * @see {@link clamp} for forcing a `bigint` into an inclusive range
+     *
      * @category predicates
      * @since 2.0.0
      */
@@ -698,6 +953,10 @@ export declare 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.
@@ -717,6 +976,8 @@ export declare 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
  */
@@ -724,6 +985,10 @@ export declare 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.
@@ -743,6 +1008,8 @@ export declare 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
      */
@@ -753,6 +1020,10 @@ export declare 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.
@@ -772,6 +1043,8 @@ export declare 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
      */
@@ -783,6 +1056,10 @@ export declare 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
@@ -792,6 +1069,8 @@ export declare const clamp: {
  * assert.deepStrictEqual(BigInt.min(2n, 3n), 2n)
  * ```
  *
+ * @see {@link max} for selecting the larger value
+ *
  * @category math
  * @since 2.0.0
  */
@@ -799,6 +1078,10 @@ export declare 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
@@ -808,6 +1091,8 @@ export declare const min: {
      * assert.deepStrictEqual(BigInt.min(2n, 3n), 2n)
      * ```
      *
+     * @see {@link max} for selecting the larger value
+     *
      * @category math
      * @since 2.0.0
      */
@@ -815,6 +1100,10 @@ export declare 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
@@ -824,6 +1113,8 @@ export declare const min: {
      * assert.deepStrictEqual(BigInt.min(2n, 3n), 2n)
      * ```
      *
+     * @see {@link max} for selecting the larger value
+     *
      * @category math
      * @since 2.0.0
      */
@@ -832,6 +1123,10 @@ export declare 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
@@ -841,6 +1136,8 @@ export declare const min: {
  * assert.deepStrictEqual(BigInt.max(2n, 3n), 3n)
  * ```
  *
+ * @see {@link min} for selecting the smaller value
+ *
  * @category math
  * @since 2.0.0
  */
@@ -848,6 +1145,10 @@ export declare 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
@@ -857,6 +1158,8 @@ export declare const max: {
      * assert.deepStrictEqual(BigInt.max(2n, 3n), 3n)
      * ```
      *
+     * @see {@link min} for selecting the smaller value
+     *
      * @category math
      * @since 2.0.0
      */
@@ -864,6 +1167,10 @@ export declare 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
@@ -873,6 +1180,8 @@ export declare const max: {
      * assert.deepStrictEqual(BigInt.max(2n, 3n), 3n)
      * ```
      *
+     * @see {@link min} for selecting the smaller value
+     *
      * @category math
      * @since 2.0.0
      */
@@ -881,6 +1190,10 @@ export declare 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
@@ -899,6 +1212,10 @@ export declare const sign: (n: bigint) => Ordering;
 /**
  * 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
@@ -917,6 +1234,10 @@ export declare const abs: (n: bigint) => bigint;
 /**
  * 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
@@ -928,6 +1249,8 @@ export declare const abs: (n: bigint) => bigint;
  * assert.deepStrictEqual(BigInt.gcd(16n, 24n), 8n)
  * ```
  *
+ * @see {@link lcm} for computing the least common multiple
+ *
  * @category math
  * @since 2.0.0
  */
@@ -935,6 +1258,10 @@ export declare 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
@@ -946,6 +1273,8 @@ export declare const gcd: {
      * assert.deepStrictEqual(BigInt.gcd(16n, 24n), 8n)
      * ```
      *
+     * @see {@link lcm} for computing the least common multiple
+     *
      * @category math
      * @since 2.0.0
      */
@@ -953,6 +1282,10 @@ export declare 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
@@ -964,6 +1297,8 @@ export declare const gcd: {
      * assert.deepStrictEqual(BigInt.gcd(16n, 24n), 8n)
      * ```
      *
+     * @see {@link lcm} for computing the least common multiple
+     *
      * @category math
      * @since 2.0.0
      */
@@ -972,6 +1307,10 @@ export declare 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
@@ -983,6 +1322,8 @@ export declare const gcd: {
  * assert.deepStrictEqual(BigInt.lcm(16n, 24n), 48n)
  * ```
  *
+ * @see {@link gcd} for computing the greatest common divisor
+ *
  * @category math
  * @since 2.0.0
  */
@@ -990,6 +1331,10 @@ export declare 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
@@ -1001,6 +1346,8 @@ export declare const lcm: {
      * assert.deepStrictEqual(BigInt.lcm(16n, 24n), 48n)
      * ```
      *
+     * @see {@link gcd} for computing the greatest common divisor
+     *
      * @category math
      * @since 2.0.0
      */
@@ -1008,6 +1355,10 @@ export declare 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
@@ -1019,6 +1370,8 @@ export declare const lcm: {
      * assert.deepStrictEqual(BigInt.lcm(16n, 24n), 48n)
      * ```
      *
+     * @see {@link gcd} for computing the greatest common divisor
+     *
      * @category math
      * @since 2.0.0
      */
@@ -1027,6 +1380,10 @@ export declare 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
@@ -1047,6 +1404,8 @@ export declare 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
  */
@@ -1054,6 +1413,11 @@ export declare 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
@@ -1071,6 +1435,8 @@ export declare 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
  */
@@ -1078,6 +1444,10 @@ export declare 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
@@ -1087,6 +1457,9 @@ export declare 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
  */
@@ -1094,6 +1467,10 @@ export declare 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
@@ -1103,6 +1480,9 @@ export declare 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
  */
@@ -1110,6 +1490,11 @@ export declare 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`
@@ -1125,6 +1510,8 @@ export declare 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
  */
@@ -1132,6 +1519,10 @@ export declare 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
@@ -1147,6 +1538,8 @@ export declare 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
  */
@@ -1154,6 +1547,10 @@ export declare 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
@@ -1171,6 +1568,9 @@ export declare 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
  */
@@ -1178,6 +1578,10 @@ export declare 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
@@ -1197,6 +1601,8 @@ export declare 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
  */
@@ -1204,6 +1610,10 @@ export declare 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
@@ -1223,6 +1633,8 @@ export declare 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
      */
@@ -1230,6 +1642,10 @@ export declare 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
@@ -1249,6 +1665,8 @@ export declare 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
      */
@@ -1257,6 +1675,17 @@ export declare 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
  */
@@ -1264,6 +1693,17 @@ export declare const ReducerSum: Reducer.Reducer<bigint>;
 /**
  * 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
  */
@@ -1271,6 +1711,13 @@ export declare const ReducerMultiply: Reducer.Reducer<bigint>;
 /**
  * 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
  */
@@ -1278,6 +1725,13 @@ export declare const CombinerMax: Combiner.Combiner<bigint>;
 /**
  * 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
  */