effect 4.0.0-beta.70 → 4.0.0-beta.72

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.
+ * Exposes the global bigint constructor for JavaScript bigint coercion.
+ *
+ * **When to use**
+ *
+ * Use to access native JavaScript bigint constructor coercion 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)
  *
@@ -30,7 +106,11 @@ import * as Reducer from "./Reducer.ts";
  */
 export declare const BigInt: BigIntConstructor;
 /**
- * Tests if a value is a `bigint`.
+ * Checks whether a value is a `bigint`.
+ *
+ * **When to use**
+ *
+ * Use to validate unknown input and narrow it to `bigint`.
  *
  * **Example** (Checking for bigints)
  *
@@ -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
@@ -194,7 +322,12 @@ export declare const subtract: {
     (self: bigint, that: bigint): bigint;
 };
 /**
- * Safely divides one `bigint` by another.
+ * Divides one `bigint` by another safely.
+ *
+ * **When to use**
+ *
+ * Use to divide `bigint` values while representing division by zero as
+ * `Option.none`.
  *
  * **Details**
  *
@@ -211,12 +344,20 @@ 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
  */
 export declare const divide: {
     /**
-     * Safely divides one `bigint` by another.
+     * Divides one `bigint` by another safely.
+     *
+     * **When to use**
+     *
+     * Use to divide `bigint` values while representing division by zero as
+     * `Option.none`.
      *
      * **Details**
      *
@@ -233,12 +374,20 @@ 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
      */
     (that: bigint): (self: bigint) => Option.Option<bigint>;
     /**
-     * Safely divides one `bigint` by another.
+     * Divides one `bigint` by another safely.
+     *
+     * **When to use**
+     *
+     * Use to divide `bigint` values while representing division by zero as
+     * `Option.none`.
      *
      * **Details**
      *
@@ -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,11 @@ 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 sorting or comparing bigint values through APIs that accept an
+ * ordering instance.
+ *
  * **Example** (Comparing bigints with Order)
  *
  * ```ts
@@ -393,7 +579,12 @@ export declare const decrement: (n: bigint) => bigint;
  */
 export declare const Order: order.Order<bigint>;
 /**
- * An `Equivalence` instance for bigints using strict equality (`===`).
+ * Equivalence instance for bigints using strict equality (`===`).
+ *
+ * **When to use**
+ *
+ * Use when checking bigint equality through APIs that accept an equivalence
+ * relation.
  *
  * **Example** (Comparing bigints for equivalence)
  *
@@ -411,6 +602,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 +624,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 +646,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 +669,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 +691,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 +713,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 +736,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 +758,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 +780,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 +803,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 +825,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 +847,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
@@ -629,7 +868,11 @@ export declare const isGreaterThanOrEqualTo: {
     (self: bigint, that: bigint): boolean;
 };
 /**
- * Checks if a `bigint` is between a `minimum` and `maximum` value (inclusive).
+ * Checks whether 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)
  *
@@ -644,12 +887,18 @@ 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
  */
 export declare const between: {
     /**
-     * Checks if a `bigint` is between a `minimum` and `maximum` value (inclusive).
+     * Checks whether 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)
      *
@@ -664,6 +913,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
      */
@@ -672,7 +923,11 @@ export declare const between: {
         maximum: bigint;
     }): (self: bigint) => boolean;
     /**
-     * Checks if a `bigint` is between a `minimum` and `maximum` value (inclusive).
+     * Checks whether 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)
      *
@@ -687,6 +942,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 +955,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 +978,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 +987,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 +1010,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 +1022,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 +1045,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 +1058,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 +1071,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 +1080,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 +1093,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 +1102,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 +1115,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 +1125,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 +1138,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 +1147,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 +1160,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 +1169,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 +1182,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 +1192,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 +1214,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 +1236,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 +1251,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 +1260,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 +1275,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 +1284,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 +1299,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 +1309,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 +1324,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 +1333,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 +1348,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 +1357,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 +1372,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 +1382,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,12 +1406,19 @@ 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
  */
 export declare const sqrtUnsafe: (n: bigint) => bigint;
 /**
- * Safely returns the integer square root of a `bigint`.
+ * Computes the integer square root of a `bigint` safely.
+ *
+ * **When to use**
+ *
+ * Use to compute an integer square root while representing negative input as
+ * `Option.none`.
  *
  * **Details**
  *
@@ -1071,6 +1437,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 +1446,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 +1459,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 +1469,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,12 +1482,20 @@ 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
  */
 export declare const multiplyAll: (collection: Iterable<bigint>) => bigint;
 /**
- * Converts a `bigint` to a `number`.
+ * Converts a `bigint` to a `number` safely.
+ *
+ * **When to use**
+ *
+ * Use to convert a `bigint` to a JavaScript number only when it is a safe
+ * integer.
  *
  * **Details**
  *
@@ -1125,12 +1512,18 @@ 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
  */
 export declare const toNumber: (b: bigint) => Option.Option<number>;
 /**
- * Converts a string to a `bigint`.
+ * Parses a string into a `bigint` safely.
+ *
+ * **When to use**
+ *
+ * Use to parse a string as a `bigint` without throwing on invalid input.
  *
  * **Details**
  *
@@ -1147,6 +1540,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 +1549,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 +1570,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 +1580,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 +1603,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 +1612,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 +1635,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 +1644,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,34 +1667,72 @@ 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
      */
     (self: bigint, divisor: bigint): bigint;
 };
 /**
- * A `Reducer` for combining `bigint`s using addition.
+ * 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
  */
 export declare const ReducerSum: Reducer.Reducer<bigint>;
 /**
- * A `Reducer` for combining `bigint`s using multiplication.
+ * 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
  */
 export declare const ReducerMultiply: Reducer.Reducer<bigint>;
 /**
- * A `Combiner` that returns the maximum `bigint`.
+ * 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
  */
 export declare const CombinerMax: Combiner.Combiner<bigint>;
 /**
- * A `Combiner` that returns the minimum `bigint`.
+ * 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