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

package/src/BigDecimal.ts

@@ -1,15 +1,59 @@
 /**
- * This module provides utility functions and type class instances for working with the `BigDecimal` type in TypeScript.
- * It includes functions for basic arithmetic operations.
+ * Decimal arithmetic backed by an unscaled `bigint` and a decimal scale.
+ *
+ * `BigDecimal` is useful when values must keep their decimal representation
+ * instead of inheriting JavaScript's binary floating-point rounding, such as
+ * money, quantities, measurements, or protocol values exchanged as decimal
+ * strings. The module includes constructors, parsers, arithmetic operations,
+ * comparisons, rounding helpers, and string formatting.
+ *
+ * **Mental model**
+ *
+ * - A `BigDecimal` stores `value * 10^-scale`; `make(12345n, 2)` represents
+ *   `123.45`
+ * - Values are immutable; arithmetic returns new `BigDecimal` values
+ * - Equivalent values can have different internal scales, so equality and
+ *   ordering normalize trailing zeros
+ * - Division can produce repeating decimals, so {@link divide} and
+ *   {@link divideUnsafe} use the module's default division precision
+ *
+ * **Common tasks**
+ *
+ * - Construct values: {@link make}, {@link fromBigInt}, {@link fromString},
+ *   {@link fromNumber}
+ * - Render values: {@link format}, {@link toExponential},
+ *   {@link toNumberUnsafe}
+ * - Do arithmetic: {@link sum}, {@link subtract}, {@link multiply},
+ *   {@link divide}, {@link remainder}, {@link negate}, {@link abs}
+ * - Compare and constrain values: {@link equals}, {@link Order},
+ *   {@link isLessThan}, {@link between}, {@link clamp}, {@link min},
+ *   {@link max}
+ * - Adjust decimal places: {@link scale}, {@link round}, {@link truncate},
+ *   {@link ceil}, {@link floor}
  *
- * A `BigDecimal` allows storing any real number to arbitrary precision; which avoids common floating point errors
- * (such as 0.1 + 0.2 ≠ 0.3) at the cost of complexity.
+ * **Gotchas**
+ *
+ * - Prefer {@link fromString} or {@link fromBigInt} for external decimal data.
+ *   {@link fromNumber} can only preserve the decimal spelling of a finite
+ *   JavaScript number after any binary floating-point precision has already
+ *   been lost.
+ * - {@link divide} and {@link remainder} return `Option.none()` for division
+ *   by zero; {@link divideUnsafe} and {@link remainderUnsafe} throw instead.
+ * - Parsed scales must fit in JavaScript's safe integer range.
+ *
+ * **Example** (Decimal arithmetic)
+ *
+ * ```ts
+ * import { BigDecimal } from "effect"
  *
- * Internally, `BigDecimal` uses a `BigInt` object, paired with a 64-bit integer which determines the position of the
- * decimal point. Therefore, the precision *is not* actually arbitrary, but limited to 2<sup>63</sup> decimal places.
+ * const subtotal = BigDecimal.multiply(
+ *   BigDecimal.fromStringUnsafe("19.99"),
+ *   BigDecimal.fromBigInt(3n)
+ * )
+ * const total = BigDecimal.sum(subtotal, BigDecimal.fromStringUnsafe("1.50"))
  *
- * It is not recommended to convert a floating point number to a decimal directly, as the floating point representation
- * may be unexpected.
+ * console.log(BigDecimal.format(total)) // "61.47"
+ * ```
  *
  * @since 2.0.0
  */
@@ -33,6 +77,11 @@ const TypeId = "~effect/BigDecimal"
 /**
  * Represents an arbitrary precision decimal number.
  *
+ * **When to use**
+ *
+ * Use when decimal arithmetic needs to avoid JavaScript floating point
+ * representation errors.
+ *
  * **Example** (Inspecting BigDecimal storage)
  *
  * ```ts
@@ -85,6 +134,10 @@ const BigDecimalProto: Omit<BigDecimal, "value" | "scale" | "normalized"> = {
 /**
  * Checks if a given value is a `BigDecimal`.
  *
+ * **When to use**
+ *
+ * Use to validate unknown input and narrow it to `BigDecimal`.
+ *
  * **Example** (Checking BigDecimal values)
  *
  * ```ts
@@ -104,6 +157,11 @@ export const isBigDecimal = (u: unknown): u is BigDecimal => hasProperty(u, Type
 /**
  * Creates a `BigDecimal` from a `bigint` value and a scale.
  *
+ * **When to use**
+ *
+ * Use to construct a decimal directly from its unscaled integer value and
+ * decimal scale.
+ *
  * **Example** (Creating decimals from bigint and scale)
  *
  * ```ts
@@ -118,6 +176,8 @@ export const isBigDecimal = (u: unknown): u is BigDecimal => hasProperty(u, Type
  * console.log(BigDecimal.format(integer)) // "42"
  * ```
  *
+ * @see {@link fromBigInt} for constructing an integer decimal from a `bigint`
+ *
  * @category constructors
  * @since 2.0.0
  */
@@ -156,6 +216,11 @@ const one = makeNormalizedUnsafe(bigint1, 0)
 /**
  * Normalizes a given `BigDecimal` by removing trailing zeros.
  *
+ * **When to use**
+ *
+ * Use to canonicalize decimals that have equivalent values but different
+ * internal scales.
+ *
  * **Example** (Normalizing trailing zeros)
  *
  * ```ts
@@ -172,6 +237,8 @@ const one = makeNormalizedUnsafe(bigint1, 0)
  * )
  * ```
  *
+ * @see {@link format} for rendering normalized decimals as strings
+ *
  * @category scaling
  * @since 2.0.0
  */
@@ -207,6 +274,10 @@ export const normalize = (self: BigDecimal): BigDecimal => {
 /**
  * Scales a `BigDecimal` to the specified scale.
  *
+ * **When to use**
+ *
+ * Use to change how many decimal places are represented by a `BigDecimal`.
+ *
  * **Details**
  *
  * Increasing the scale appends decimal zeros. Decreasing the scale discards
@@ -229,6 +300,8 @@ export const normalize = (self: BigDecimal): BigDecimal => {
  * console.log(BigDecimal.format(reduced)) // "123.4"
  * ```
  *
+ * @see {@link round} for changing scale with configurable rounding
+ *
  * @category scaling
  * @since 2.0.0
  */
@@ -236,6 +309,10 @@ export const scale: {
   /**
    * Scales a `BigDecimal` to the specified scale.
    *
+   * **When to use**
+   *
+   * Use to change how many decimal places are represented by a `BigDecimal`.
+   *
    * **Details**
    *
    * Increasing the scale appends decimal zeros. Decreasing the scale discards
@@ -258,6 +335,8 @@ export const scale: {
    * console.log(BigDecimal.format(reduced)) // "123.4"
    * ```
    *
+   * @see {@link round} for changing scale with configurable rounding
+   *
    * @category scaling
    * @since 2.0.0
    */
@@ -265,6 +344,10 @@ export const scale: {
   /**
    * Scales a `BigDecimal` to the specified scale.
    *
+   * **When to use**
+   *
+   * Use to change how many decimal places are represented by a `BigDecimal`.
+   *
    * **Details**
    *
    * Increasing the scale appends decimal zeros. Decreasing the scale discards
@@ -287,6 +370,8 @@ export const scale: {
    * console.log(BigDecimal.format(reduced)) // "123.4"
    * ```
    *
+   * @see {@link round} for changing scale with configurable rounding
+   *
    * @category scaling
    * @since 2.0.0
    */
@@ -306,6 +391,10 @@ export const scale: {
 /**
  * Provides an addition operation on `BigDecimal`s.
  *
+ * **When to use**
+ *
+ * Use to add two `BigDecimal` values.
+ *
  * **Example** (Adding decimals)
  *
  * ```ts
@@ -318,6 +407,8 @@ export const scale: {
  * )
  * ```
  *
+ * @see {@link sumAll} for summing an iterable of `BigDecimal` values
+ *
  * @category math
  * @since 2.0.0
  */
@@ -325,6 +416,10 @@ export const sum: {
   /**
    * Provides an addition operation on `BigDecimal`s.
    *
+   * **When to use**
+   *
+   * Use to add two `BigDecimal` values.
+   *
    * **Example** (Adding decimals)
    *
    * ```ts
@@ -337,6 +432,8 @@ export const sum: {
    * )
    * ```
    *
+   * @see {@link sumAll} for summing an iterable of `BigDecimal` values
+   *
    * @category math
    * @since 2.0.0
    */
@@ -344,6 +441,10 @@ export const sum: {
   /**
    * Provides an addition operation on `BigDecimal`s.
    *
+   * **When to use**
+   *
+   * Use to add two `BigDecimal` values.
+   *
    * **Example** (Adding decimals)
    *
    * ```ts
@@ -356,6 +457,8 @@ export const sum: {
    * )
    * ```
    *
+   * @see {@link sumAll} for summing an iterable of `BigDecimal` values
+   *
    * @category math
    * @since 2.0.0
    */
@@ -383,6 +486,10 @@ export const sum: {
 /**
  * Takes an `Iterable` of `BigDecimal`s and returns their sum as a single `BigDecimal`.
  *
+ * **When to use**
+ *
+ * Use to sum all `BigDecimal` values in an iterable.
+ *
  * **Example** (Adding multiple decimals)
  *
  * ```ts
@@ -395,6 +502,8 @@ export const sum: {
  * )
  * ```
  *
+ * @see {@link sum} for adding two `BigDecimal` values
+ *
  * @category math
  * @since 3.16.0
  */
@@ -409,6 +518,10 @@ export const sumAll = (collection: Iterable<BigDecimal>): BigDecimal => {
 /**
  * Provides a multiplication operation on `BigDecimal`s.
  *
+ * **When to use**
+ *
+ * Use to multiply two `BigDecimal` values.
+ *
  * **Example** (Multiplying decimals)
  *
  * ```ts
@@ -421,6 +534,8 @@ export const sumAll = (collection: Iterable<BigDecimal>): BigDecimal => {
  * )
  * ```
  *
+ * @see {@link multiplyAll} for multiplying an iterable of `BigDecimal` values
+ *
  * @category math
  * @since 2.0.0
  */
@@ -428,6 +543,10 @@ export const multiply: {
   /**
    * Provides a multiplication operation on `BigDecimal`s.
    *
+   * **When to use**
+   *
+   * Use to multiply two `BigDecimal` values.
+   *
    * **Example** (Multiplying decimals)
    *
    * ```ts
@@ -440,6 +559,8 @@ export const multiply: {
    * )
    * ```
    *
+   * @see {@link multiplyAll} for multiplying an iterable of `BigDecimal` values
+   *
    * @category math
    * @since 2.0.0
    */
@@ -447,6 +568,10 @@ export const multiply: {
   /**
    * Provides a multiplication operation on `BigDecimal`s.
    *
+   * **When to use**
+   *
+   * Use to multiply two `BigDecimal` values.
+   *
    * **Example** (Multiplying decimals)
    *
    * ```ts
@@ -459,6 +584,8 @@ export const multiply: {
    * )
    * ```
    *
+   * @see {@link multiplyAll} for multiplying an iterable of `BigDecimal` values
+   *
    * @category math
    * @since 2.0.0
    */
@@ -474,6 +601,10 @@ export const multiply: {
 /**
  * Takes an `Iterable` of `BigDecimal`s and returns their multiplication as a single `BigDecimal`.
  *
+ * **When to use**
+ *
+ * Use to multiply all `BigDecimal` values in an iterable.
+ *
  * **Example** (Multiplying multiple decimals)
  *
  * ```ts
@@ -486,6 +617,8 @@ export const multiply: {
  * )
  * ```
  *
+ * @see {@link multiply} for multiplying two `BigDecimal` values
+ *
  * @category math
  * @since 4.0.0
  */
@@ -503,6 +636,10 @@ export const multiplyAll = (collection: Iterable<BigDecimal>): BigDecimal => {
 /**
  * Provides a subtraction operation on `BigDecimal`s.
  *
+ * **When to use**
+ *
+ * Use to subtract one `BigDecimal` value from another.
+ *
  * **Example** (Subtracting decimals)
  *
  * ```ts
@@ -522,6 +659,10 @@ export const subtract: {
   /**
    * Provides a subtraction operation on `BigDecimal`s.
    *
+   * **When to use**
+   *
+   * Use to subtract one `BigDecimal` value from another.
+   *
    * **Example** (Subtracting decimals)
    *
    * ```ts
@@ -541,6 +682,10 @@ export const subtract: {
   /**
    * Provides a subtraction operation on `BigDecimal`s.
    *
+   * **When to use**
+   *
+   * Use to subtract one `BigDecimal` value from another.
+   *
    * **Example** (Subtracting decimals)
    *
    * ```ts
@@ -648,6 +793,11 @@ export const roundTerminal = (n: bigint): bigint => {
 /**
  * Provides a division operation on `BigDecimal`s.
  *
+ * **When to use**
+ *
+ * Use to divide `BigDecimal` values while representing division by zero as
+ * `Option.none`.
+ *
  * **Details**
  *
  * If the dividend is not a multiple of the divisor, the result will be a `BigDecimal` value
@@ -685,6 +835,9 @@ export const roundTerminal = (n: bigint): bigint => {
  * ) // true
  * ```
  *
+ * @see {@link divideUnsafe} for division that throws when the divisor is zero
+ * @see {@link remainder} for the decimal remainder operation
+ *
  * @category math
  * @since 2.0.0
  */
@@ -692,6 +845,11 @@ export const divide: {
   /**
    * Provides a division operation on `BigDecimal`s.
    *
+   * **When to use**
+   *
+   * Use to divide `BigDecimal` values while representing division by zero as
+   * `Option.none`.
+   *
    * **Details**
    *
    * If the dividend is not a multiple of the divisor, the result will be a `BigDecimal` value
@@ -729,6 +887,9 @@ export const divide: {
    * ) // true
    * ```
    *
+   * @see {@link divideUnsafe} for division that throws when the divisor is zero
+   * @see {@link remainder} for the decimal remainder operation
+   *
    * @category math
    * @since 2.0.0
    */
@@ -736,6 +897,11 @@ export const divide: {
   /**
    * Provides a division operation on `BigDecimal`s.
    *
+   * **When to use**
+   *
+   * Use to divide `BigDecimal` values while representing division by zero as
+   * `Option.none`.
+   *
    * **Details**
    *
    * If the dividend is not a multiple of the divisor, the result will be a `BigDecimal` value
@@ -773,6 +939,9 @@ export const divide: {
    * ) // true
    * ```
    *
+   * @see {@link divideUnsafe} for division that throws when the divisor is zero
+   * @see {@link remainder} for the decimal remainder operation
+   *
    * @category math
    * @since 2.0.0
    */
@@ -797,6 +966,11 @@ export const divide: {
 /**
  * Provides an unsafe division operation on `BigDecimal`s.
  *
+ * **When to use**
+ *
+ * Use when the divisor is known to be non-zero and division by zero should be a
+ * thrown exception.
+ *
  * **Details**
  *
  * If the dividend is not a multiple of the divisor, the result will be a `BigDecimal` value
@@ -815,6 +989,8 @@ export const divide: {
  * console.log(BigDecimal.divideUnsafe(BigDecimal.fromStringUnsafe("6"), BigDecimal.fromStringUnsafe("4"))) // BigDecimal(1.5)
  * ```
  *
+ * @see {@link divide} for division that returns `Option.none` when the divisor is zero
+ *
  * @category math
  * @since 4.0.0
  */
@@ -822,6 +998,11 @@ export const divideUnsafe: {
   /**
    * Provides an unsafe division operation on `BigDecimal`s.
    *
+   * **When to use**
+   *
+   * Use when the divisor is known to be non-zero and division by zero should be a
+   * thrown exception.
+   *
    * **Details**
    *
    * If the dividend is not a multiple of the divisor, the result will be a `BigDecimal` value
@@ -840,6 +1021,8 @@ export const divideUnsafe: {
    * console.log(BigDecimal.divideUnsafe(BigDecimal.fromStringUnsafe("6"), BigDecimal.fromStringUnsafe("4"))) // BigDecimal(1.5)
    * ```
    *
+   * @see {@link divide} for division that returns `Option.none` when the divisor is zero
+   *
    * @category math
    * @since 4.0.0
    */
@@ -847,6 +1030,11 @@ export const divideUnsafe: {
   /**
    * Provides an unsafe division operation on `BigDecimal`s.
    *
+   * **When to use**
+   *
+   * Use when the divisor is known to be non-zero and division by zero should be a
+   * thrown exception.
+   *
    * **Details**
    *
    * If the dividend is not a multiple of the divisor, the result will be a `BigDecimal` value
@@ -865,6 +1053,8 @@ export const divideUnsafe: {
    * console.log(BigDecimal.divideUnsafe(BigDecimal.fromStringUnsafe("6"), BigDecimal.fromStringUnsafe("4"))) // BigDecimal(1.5)
    * ```
    *
+   * @see {@link divide} for division that returns `Option.none` when the divisor is zero
+   *
    * @category math
    * @since 4.0.0
    */
@@ -888,6 +1078,10 @@ export const divideUnsafe: {
 /**
  * Provides an `Order` instance for `BigDecimal` that allows comparing and sorting BigDecimal values.
  *
+ * **When to use**
+ *
+ * Use when an API needs an `Order` instance for `BigDecimal` values.
+ *
  * **Example** (Comparing decimals)
  *
  * ```ts
@@ -925,6 +1119,10 @@ export const Order: order.Order<BigDecimal> = order.make((self, that) => {
 /**
  * Returns `true` if the first argument is less than the second, otherwise `false`.
  *
+ * **When to use**
+ *
+ * Use to test whether one `BigDecimal` is strictly less than another.
+ *
  * **Example** (Checking less-than comparisons)
  *
  * ```ts
@@ -952,6 +1150,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 `BigDecimal` is strictly less than another.
+   *
    * **Example** (Checking less-than comparisons)
    *
    * ```ts
@@ -979,6 +1181,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 `BigDecimal` is strictly less than another.
+   *
    * **Example** (Checking less-than comparisons)
    *
    * ```ts
@@ -1008,6 +1214,10 @@ export const isLessThan: {
 /**
  * Checks if a given `BigDecimal` is less than or equal to the provided one.
  *
+ * **When to use**
+ *
+ * Use to test whether one `BigDecimal` is less than or equal to another.
+ *
  * **Example** (Checking less-than-or-equal comparisons)
  *
  * ```ts
@@ -1035,6 +1245,10 @@ export const isLessThanOrEqualTo: {
   /**
    * Checks if a given `BigDecimal` is less than or equal to the provided one.
    *
+   * **When to use**
+   *
+   * Use to test whether one `BigDecimal` is less than or equal to another.
+   *
    * **Example** (Checking less-than-or-equal comparisons)
    *
    * ```ts
@@ -1062,6 +1276,10 @@ export const isLessThanOrEqualTo: {
   /**
    * Checks if a given `BigDecimal` is less than or equal to the provided one.
    *
+   * **When to use**
+   *
+   * Use to test whether one `BigDecimal` is less than or equal to another.
+   *
    * **Example** (Checking less-than-or-equal comparisons)
    *
    * ```ts
@@ -1091,6 +1309,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 `BigDecimal` is strictly greater than another.
+ *
  * **Example** (Checking greater-than comparisons)
  *
  * ```ts
@@ -1118,6 +1340,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 `BigDecimal` is strictly greater than another.
+   *
    * **Example** (Checking greater-than comparisons)
    *
    * ```ts
@@ -1145,6 +1371,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 `BigDecimal` is strictly greater than another.
+   *
    * **Example** (Checking greater-than comparisons)
    *
    * ```ts
@@ -1174,6 +1404,10 @@ export const isGreaterThan: {
 /**
  * Checks if a given `BigDecimal` is greater than or equal to the provided one.
  *
+ * **When to use**
+ *
+ * Use to test whether one `BigDecimal` is greater than or equal to another.
+ *
  * **Example** (Checking greater-than-or-equal comparisons)
  *
  * ```ts
@@ -1201,6 +1435,10 @@ export const isGreaterThanOrEqualTo: {
   /**
    * Checks if a given `BigDecimal` is greater than or equal to the provided one.
    *
+   * **When to use**
+   *
+   * Use to test whether one `BigDecimal` is greater than or equal to another.
+   *
    * **Example** (Checking greater-than-or-equal comparisons)
    *
    * ```ts
@@ -1228,6 +1466,10 @@ export const isGreaterThanOrEqualTo: {
   /**
    * Checks if a given `BigDecimal` is greater than or equal to the provided one.
    *
+   * **When to use**
+   *
+   * Use to test whether one `BigDecimal` is greater than or equal to another.
+   *
    * **Example** (Checking greater-than-or-equal comparisons)
    *
    * ```ts
@@ -1257,6 +1499,10 @@ export const isGreaterThanOrEqualTo: {
 /**
  * Checks if a `BigDecimal` is between a `minimum` and `maximum` value (inclusive).
  *
+ * **When to use**
+ *
+ * Use to test whether a `BigDecimal` falls inside an inclusive range.
+ *
  * **Example** (Checking decimal ranges)
  *
  * ```ts
@@ -1273,6 +1519,8 @@ export const isGreaterThanOrEqualTo: {
  * assert.deepStrictEqual(between(BigDecimal.fromStringUnsafe("6")), false)
  * ```
  *
+ * @see {@link clamp} for forcing a `BigDecimal` into an inclusive range
+ *
  * @category predicates
  * @since 2.0.0
  */
@@ -1280,6 +1528,10 @@ export const between: {
   /**
    * Checks if a `BigDecimal` is between a `minimum` and `maximum` value (inclusive).
    *
+   * **When to use**
+   *
+   * Use to test whether a `BigDecimal` falls inside an inclusive range.
+   *
    * **Example** (Checking decimal ranges)
    *
    * ```ts
@@ -1296,6 +1548,8 @@ export const between: {
    * assert.deepStrictEqual(between(BigDecimal.fromStringUnsafe("6")), false)
    * ```
    *
+   * @see {@link clamp} for forcing a `BigDecimal` into an inclusive range
+   *
    * @category predicates
    * @since 2.0.0
    */
@@ -1308,6 +1562,10 @@ export const between: {
   /**
    * Checks if a `BigDecimal` is between a `minimum` and `maximum` value (inclusive).
    *
+   * **When to use**
+   *
+   * Use to test whether a `BigDecimal` falls inside an inclusive range.
+   *
    * **Example** (Checking decimal ranges)
    *
    * ```ts
@@ -1324,6 +1582,8 @@ export const between: {
    * assert.deepStrictEqual(between(BigDecimal.fromStringUnsafe("6")), false)
    * ```
    *
+   * @see {@link clamp} for forcing a `BigDecimal` into an inclusive range
+   *
    * @category predicates
    * @since 2.0.0
    */
@@ -1339,6 +1599,10 @@ export const between: {
 /**
  * Restricts the given `BigDecimal` to be within the range specified by the `minimum` and `maximum` values.
  *
+ * **When to use**
+ *
+ * Use to force a `BigDecimal` into an inclusive range.
+ *
  * **Details**
  *
  * If the `BigDecimal` is less than the `minimum` value, the function returns
@@ -1370,6 +1634,8 @@ export const between: {
  * )
  * ```
  *
+ * @see {@link between} for checking whether a `BigDecimal` is already inside a range
+ *
  * @category math
  * @since 2.0.0
  */
@@ -1377,6 +1643,10 @@ export const clamp: {
   /**
    * Restricts the given `BigDecimal` to be within the range specified by the `minimum` and `maximum` values.
    *
+   * **When to use**
+   *
+   * Use to force a `BigDecimal` into an inclusive range.
+   *
    * **Details**
    *
    * If the `BigDecimal` is less than the `minimum` value, the function returns
@@ -1408,6 +1678,8 @@ export const clamp: {
    * )
    * ```
    *
+   * @see {@link between} for checking whether a `BigDecimal` is already inside a range
+   *
    * @category math
    * @since 2.0.0
    */
@@ -1420,6 +1692,10 @@ export const clamp: {
   /**
    * Restricts the given `BigDecimal` to be within the range specified by the `minimum` and `maximum` values.
    *
+   * **When to use**
+   *
+   * Use to force a `BigDecimal` into an inclusive range.
+   *
    * **Details**
    *
    * If the `BigDecimal` is less than the `minimum` value, the function returns
@@ -1451,6 +1727,8 @@ export const clamp: {
    * )
    * ```
    *
+   * @see {@link between} for checking whether a `BigDecimal` is already inside a range
+   *
    * @category math
    * @since 2.0.0
    */
@@ -1466,6 +1744,10 @@ export const clamp: {
 /**
  * Returns the minimum between two `BigDecimal`s.
  *
+ * **When to use**
+ *
+ * Use to select the smaller of two `BigDecimal` values.
+ *
  * **Example** (Selecting the smaller decimal)
  *
  * ```ts
@@ -1478,6 +1760,8 @@ export const clamp: {
  * )
  * ```
  *
+ * @see {@link max} for selecting the larger value
+ *
  * @category math
  * @since 2.0.0
  */
@@ -1485,6 +1769,10 @@ export const min: {
   /**
    * Returns the minimum between two `BigDecimal`s.
    *
+   * **When to use**
+   *
+   * Use to select the smaller of two `BigDecimal` values.
+   *
    * **Example** (Selecting the smaller decimal)
    *
    * ```ts
@@ -1497,6 +1785,8 @@ export const min: {
    * )
    * ```
    *
+   * @see {@link max} for selecting the larger value
+   *
    * @category math
    * @since 2.0.0
    */
@@ -1504,6 +1794,10 @@ export const min: {
   /**
    * Returns the minimum between two `BigDecimal`s.
    *
+   * **When to use**
+   *
+   * Use to select the smaller of two `BigDecimal` values.
+   *
    * **Example** (Selecting the smaller decimal)
    *
    * ```ts
@@ -1516,6 +1810,8 @@ export const min: {
    * )
    * ```
    *
+   * @see {@link max} for selecting the larger value
+   *
    * @category math
    * @since 2.0.0
    */
@@ -1525,6 +1821,10 @@ export const min: {
 /**
  * Returns the maximum between two `BigDecimal`s.
  *
+ * **When to use**
+ *
+ * Use to select the larger of two `BigDecimal` values.
+ *
  * **Example** (Selecting the larger decimal)
  *
  * ```ts
@@ -1537,6 +1837,8 @@ export const min: {
  * )
  * ```
  *
+ * @see {@link min} for selecting the smaller value
+ *
  * @category math
  * @since 2.0.0
  */
@@ -1544,6 +1846,10 @@ export const max: {
   /**
    * Returns the maximum between two `BigDecimal`s.
    *
+   * **When to use**
+   *
+   * Use to select the larger of two `BigDecimal` values.
+   *
    * **Example** (Selecting the larger decimal)
    *
    * ```ts
@@ -1556,6 +1862,8 @@ export const max: {
    * )
    * ```
    *
+   * @see {@link min} for selecting the smaller value
+   *
    * @category math
    * @since 2.0.0
    */
@@ -1563,6 +1871,10 @@ export const max: {
   /**
    * Returns the maximum between two `BigDecimal`s.
    *
+   * **When to use**
+   *
+   * Use to select the larger of two `BigDecimal` values.
+   *
    * **Example** (Selecting the larger decimal)
    *
    * ```ts
@@ -1575,6 +1887,8 @@ export const max: {
    * )
    * ```
    *
+   * @see {@link min} for selecting the smaller value
+   *
    * @category math
    * @since 2.0.0
    */
@@ -1584,6 +1898,10 @@ export const max: {
 /**
  * Determines the sign of a given `BigDecimal`.
  *
+ * **When to use**
+ *
+ * Use to classify a `BigDecimal` as negative, zero, or positive.
+ *
  * **Example** (Reading decimal signs)
  *
  * ```ts
@@ -1603,6 +1921,10 @@ export const sign = (n: BigDecimal): Ordering => n.value === bigint0 ? 0 : n.val
 /**
  * Determines the absolute value of a given `BigDecimal`.
  *
+ * **When to use**
+ *
+ * Use to remove the sign from a `BigDecimal` while preserving its magnitude.
+ *
  * **Example** (Calculating absolute values)
  *
  * ```ts
@@ -1622,6 +1944,10 @@ export const abs = (n: BigDecimal): BigDecimal => n.value < bigint0 ? make(-n.va
 /**
  * Provides a negate operation on `BigDecimal`s.
  *
+ * **When to use**
+ *
+ * Use to flip the sign of a `BigDecimal`.
+ *
  * **Example** (Negating decimals)
  *
  * ```ts
@@ -1640,6 +1966,11 @@ export const negate = (n: BigDecimal): BigDecimal => make(-n.value, n.scale)
 /**
  * Returns the remainder left over when one operand is divided by a second operand.
  *
+ * **When to use**
+ *
+ * Use to compute a decimal remainder while representing division by zero as
+ * `Option.none`.
+ *
  * **Details**
  *
  * If the divisor is `0`, the result will be `Option.none()`.
@@ -1673,6 +2004,9 @@ export const negate = (n: BigDecimal): BigDecimal => make(-n.value, n.scale)
  * )
  * ```
  *
+ * @see {@link remainderUnsafe} for remainder calculation that throws when the divisor is zero
+ * @see {@link divide} for decimal quotient calculation
+ *
  * @category math
  * @since 2.0.0
  */
@@ -1680,6 +2014,11 @@ export const remainder: {
   /**
    * Returns the remainder left over when one operand is divided by a second operand.
    *
+   * **When to use**
+   *
+   * Use to compute a decimal remainder while representing division by zero as
+   * `Option.none`.
+   *
    * **Details**
    *
    * If the divisor is `0`, the result will be `Option.none()`.
@@ -1713,6 +2052,9 @@ export const remainder: {
    * )
    * ```
    *
+   * @see {@link remainderUnsafe} for remainder calculation that throws when the divisor is zero
+   * @see {@link divide} for decimal quotient calculation
+   *
    * @category math
    * @since 2.0.0
    */
@@ -1720,6 +2062,11 @@ export const remainder: {
   /**
    * Returns the remainder left over when one operand is divided by a second operand.
    *
+   * **When to use**
+   *
+   * Use to compute a decimal remainder while representing division by zero as
+   * `Option.none`.
+   *
    * **Details**
    *
    * If the divisor is `0`, the result will be `Option.none()`.
@@ -1753,6 +2100,9 @@ export const remainder: {
    * )
    * ```
    *
+   * @see {@link remainderUnsafe} for remainder calculation that throws when the divisor is zero
+   * @see {@link divide} for decimal quotient calculation
+   *
    * @category math
    * @since 2.0.0
    */
@@ -1769,6 +2119,11 @@ export const remainder: {
 /**
  * Returns the remainder left over when one operand is divided by a second operand.
  *
+ * **When to use**
+ *
+ * Use when the divisor is known to be non-zero and division by zero should be a
+ * thrown exception.
+ *
  * **Gotchas**
  *
  * Throws a `RangeError` if the divisor is `0`.
@@ -1793,6 +2148,8 @@ export const remainder: {
  * )
  * ```
  *
+ * @see {@link remainder} for returning `Option.none` when the divisor is zero
+ *
  * @category math
  * @since 4.0.0
  */
@@ -1800,6 +2157,11 @@ export const remainderUnsafe: {
   /**
    * Returns the remainder left over when one operand is divided by a second operand.
    *
+   * **When to use**
+   *
+   * Use when the divisor is known to be non-zero and division by zero should be a
+   * thrown exception.
+   *
    * **Gotchas**
    *
    * Throws a `RangeError` if the divisor is `0`.
@@ -1824,6 +2186,8 @@ export const remainderUnsafe: {
    * )
    * ```
    *
+   * @see {@link remainder} for returning `Option.none` when the divisor is zero
+   *
    * @category math
    * @since 4.0.0
    */
@@ -1831,6 +2195,11 @@ export const remainderUnsafe: {
   /**
    * Returns the remainder left over when one operand is divided by a second operand.
    *
+   * **When to use**
+   *
+   * Use when the divisor is known to be non-zero and division by zero should be a
+   * thrown exception.
+   *
    * **Gotchas**
    *
    * Throws a `RangeError` if the divisor is `0`.
@@ -1855,6 +2224,8 @@ export const remainderUnsafe: {
    * )
    * ```
    *
+   * @see {@link remainder} for returning `Option.none` when the divisor is zero
+   *
    * @category math
    * @since 4.0.0
    */
@@ -1871,6 +2242,10 @@ export const remainderUnsafe: {
 /**
  * Provides an `Equivalence` instance for `BigDecimal` that determines equality between BigDecimal values.
  *
+ * **When to use**
+ *
+ * Use when an API needs an `Equivalence` instance for decimal equality.
+ *
  * **Example** (Checking decimal equivalence)
  *
  * ```ts
@@ -1902,6 +2277,10 @@ export const Equivalence: Equ.Equivalence<BigDecimal> = Equ.make((self, that) =>
 /**
  * Checks if two `BigDecimal`s are equal.
  *
+ * **When to use**
+ *
+ * Use to compare two `BigDecimal` values for numeric equality.
+ *
  * **Example** (Checking decimal equality)
  *
  * ```ts
@@ -1915,6 +2294,8 @@ export const Equivalence: Equ.Equivalence<BigDecimal> = Equ.make((self, that) =>
  * console.log(BigDecimal.equals(a, c)) // false
  * ```
  *
+ * @see {@link Equivalence} for passing decimal equality to APIs that require an `Equivalence`
+ *
  * @category predicates
  * @since 2.0.0
  */
@@ -1922,6 +2303,10 @@ export const equals: {
   /**
    * Checks if two `BigDecimal`s are equal.
    *
+   * **When to use**
+   *
+   * Use to compare two `BigDecimal` values for numeric equality.
+   *
    * **Example** (Checking decimal equality)
    *
    * ```ts
@@ -1935,6 +2320,8 @@ export const equals: {
    * console.log(BigDecimal.equals(a, c)) // false
    * ```
    *
+   * @see {@link Equivalence} for passing decimal equality to APIs that require an `Equivalence`
+   *
    * @category predicates
    * @since 2.0.0
    */
@@ -1942,6 +2329,10 @@ export const equals: {
   /**
    * Checks if two `BigDecimal`s are equal.
    *
+   * **When to use**
+   *
+   * Use to compare two `BigDecimal` values for numeric equality.
+   *
    * **Example** (Checking decimal equality)
    *
    * ```ts
@@ -1955,6 +2346,8 @@ export const equals: {
    * console.log(BigDecimal.equals(a, c)) // false
    * ```
    *
+   * @see {@link Equivalence} for passing decimal equality to APIs that require an `Equivalence`
+   *
    * @category predicates
    * @since 2.0.0
    */
@@ -1964,6 +2357,10 @@ export const equals: {
 /**
  * Creates a `BigDecimal` from a `bigint` value.
  *
+ * **When to use**
+ *
+ * Use to construct an integer `BigDecimal` from a `bigint`.
+ *
  * **Example** (Creating decimals from bigint)
  *
  * ```ts
@@ -1976,6 +2373,8 @@ export const equals: {
  * console.log(BigDecimal.format(largeBigInt)) // "9007199254740991"
  * ```
  *
+ * @see {@link make} for constructing a decimal with an explicit scale
+ *
  * @category constructors
  * @since 2.0.0
  */
@@ -1984,6 +2383,11 @@ export const fromBigInt = (n: bigint): BigDecimal => make(n, 0)
 /**
  * Creates a `BigDecimal` from a `number` value.
  *
+ * **When to use**
+ *
+ * Use when a finite JavaScript number must become a `BigDecimal` and invalid
+ * input should throw.
+ *
  * **Gotchas**
  *
  * It is not recommended to convert a floating point number to a decimal
@@ -2000,6 +2404,8 @@ export const fromBigInt = (n: bigint): BigDecimal => make(n, 0)
  * assert.deepStrictEqual(BigDecimal.fromNumberUnsafe(123.456), BigDecimal.make(123456n, 3))
  * ```
  *
+ * @see {@link fromNumber} for returning `Option.none` when the number is not finite
+ *
  * @category constructors
  * @since 4.0.0
  */
@@ -2010,6 +2416,11 @@ export const fromNumberUnsafe = (n: number): BigDecimal => {
 /**
  * Creates a `BigDecimal` from a `number` value.
  *
+ * **When to use**
+ *
+ * Use to convert a finite JavaScript number to a `BigDecimal` without throwing
+ * on invalid input.
+ *
  * **Details**
  *
  * Returns `Option.none()` for `NaN`, `+Infinity` or `-Infinity`.
@@ -2033,6 +2444,9 @@ export const fromNumberUnsafe = (n: number): BigDecimal => {
  * assert.deepStrictEqual(BigDecimal.fromNumber(Infinity), Option.none())
  * ```
  *
+ * @see {@link fromNumberUnsafe} for throwing when the number is not finite
+ * @see {@link fromString} for parsing decimal strings directly
+ *
  * @category constructors
  * @since 2.0.0
  */
@@ -2053,6 +2467,10 @@ export const fromNumber = (n: number): Option.Option<BigDecimal> => {
 /**
  * Safely parses a decimal string into a `BigDecimal`.
  *
+ * **When to use**
+ *
+ * Use to parse external decimal text without throwing on invalid input.
+ *
  * **Details**
  *
  * Returns `Option.some` for valid decimal or exponent notation and
@@ -2073,6 +2491,9 @@ export const fromNumber = (n: number): Option.Option<BigDecimal> => {
  * assert.deepStrictEqual(BigDecimal.fromString("123.abc"), Option.none())
  * ```
  *
+ * @see {@link fromStringUnsafe} for parsing that throws on invalid input
+ * @see {@link fromNumber} for converting finite JavaScript numbers
+ *
  * @category constructors
  * @since 2.0.0
  */
@@ -2125,6 +2546,10 @@ export const fromString = (s: string): Option.Option<BigDecimal> => {
  * Parses a decimal string into a `BigDecimal`, throwing if the string is
  * invalid.
  *
+ * **When to use**
+ *
+ * Use when decimal text is expected to be valid and parse errors should throw.
+ *
  * **Details**
  *
  * Accepts the same syntax as `fromString`. Use `fromString` when invalid input
@@ -2141,6 +2566,8 @@ export const fromString = (s: string): Option.Option<BigDecimal> => {
  * assert.throws(() => BigDecimal.fromStringUnsafe("123.abc"))
  * ```
  *
+ * @see {@link fromString} for returning `Option.none` on invalid input
+ *
  * @category constructors
  * @since 4.0.0
  */
@@ -2151,6 +2578,10 @@ export const fromStringUnsafe = (s: string): BigDecimal => {
 /**
  * Formats a `BigDecimal` as a string.
  *
+ * **When to use**
+ *
+ * Use to render a `BigDecimal` as plain decimal text when possible.
+ *
  * **Details**
  *
  * The value is normalized before formatting. Scientific notation is used when
@@ -2168,6 +2599,8 @@ export const fromStringUnsafe = (s: string): BigDecimal => {
  * assert.deepStrictEqual(BigDecimal.format(BigDecimal.fromStringUnsafe("-0.00000123")), "-0.00000123")
  * ```
  *
+ * @see {@link toExponential} for always rendering scientific notation
+ *
  * @category converting
  * @since 2.0.0
  */
@@ -2205,6 +2638,10 @@ export const format = (n: BigDecimal): string => {
 /**
  * Formats a given `BigDecimal` as a `string` in scientific notation.
  *
+ * **When to use**
+ *
+ * Use to render a `BigDecimal` in scientific notation.
+ *
  * **Example** (Formatting decimals exponentially)
  *
  * ```ts
@@ -2214,6 +2651,8 @@ export const format = (n: BigDecimal): string => {
  * assert.deepStrictEqual(BigDecimal.toExponential(BigDecimal.make(123456n, -5)), "1.23456e+10")
  * ```
  *
+ * @see {@link format} for plain decimal formatting when possible
+ *
  * @category converting
  * @since 3.11.0
  */
@@ -2239,6 +2678,11 @@ export const toExponential = (n: BigDecimal): string => {
 /**
  * Converts a `BigDecimal` to a JavaScript `number`.
  *
+ * **When to use**
+ *
+ * Use when an interop boundary requires a JavaScript number and can tolerate
+ * precision loss.
+ *
  * **Gotchas**
  *
  * This conversion is unsafe because the result can lose integer or fractional
@@ -2254,6 +2698,8 @@ export const toExponential = (n: BigDecimal): string => {
  * assert.deepStrictEqual(BigDecimal.toNumberUnsafe(BigDecimal.fromStringUnsafe("123.456")), 123.456)
  * ```
  *
+ * @see {@link format} for preserving decimal precision as text
+ *
  * @category converting
  * @since 4.0.0
  */
@@ -2262,6 +2708,10 @@ export const toNumberUnsafe = (n: BigDecimal): number => Number(format(n))
 /**
  * Checks if a given `BigDecimal` is an integer.
  *
+ * **When to use**
+ *
+ * Use to test whether a `BigDecimal` has no fractional decimal part.
+ *
  * **Example** (Checking integer decimals)
  *
  * ```ts
@@ -2281,6 +2731,10 @@ export const isInteger = (n: BigDecimal): boolean => normalize(n).scale <= 0
 /**
  * Checks if a given `BigDecimal` is `0`.
  *
+ * **When to use**
+ *
+ * Use to test whether a `BigDecimal` is exactly zero.
+ *
  * **Example** (Checking zero decimals)
  *
  * ```ts
@@ -2299,6 +2753,10 @@ export const isZero = (n: BigDecimal): boolean => n.value === bigint0
 /**
  * Checks if a given `BigDecimal` is negative.
  *
+ * **When to use**
+ *
+ * Use to test whether a `BigDecimal` is less than zero.
+ *
  * **Example** (Checking negative decimals)
  *
  * ```ts
@@ -2318,6 +2776,10 @@ export const isNegative = (n: BigDecimal): boolean => n.value < bigint0
 /**
  * Checks if a given `BigDecimal` is positive.
  *
+ * **When to use**
+ *
+ * Use to test whether a `BigDecimal` is greater than zero.
+ *
  * **Example** (Checking positive decimals)
  *
  * ```ts
@@ -2339,6 +2801,11 @@ const isBigDecimalArgs = (args: IArguments) => isBigDecimal(args[0])
 /**
  * Rounding modes for `BigDecimal`.
  *
+ * **When to use**
+ *
+ * Use with `round` to choose how discarded digits affect a `BigDecimal`
+ * rounded to a target scale.
+ *
  * **Details**
  *
  * - `ceil`: round towards positive infinity
@@ -2352,6 +2819,11 @@ const isBigDecimalArgs = (args: IArguments) => isBigDecimal(args[0])
  * - `half-even`: round to the nearest neighbor; if equidistant round to the neighbor with an even digit
  * - `half-odd`: round to the nearest neighbor; if equidistant round to the neighbor with an odd digit
  *
+ * @see {@link round} for configurable rounding with a `RoundingMode`
+ * @see {@link ceil} for fixed rounding toward positive infinity
+ * @see {@link floor} for fixed rounding toward negative infinity
+ * @see {@link truncate} for fixed rounding toward zero
+ *
  * @category math
  * @since 3.16.0
  */
@@ -2370,6 +2842,10 @@ export type RoundingMode =
 /**
  * Rounds a `BigDecimal` at the given scale with the specified rounding mode.
  *
+ * **When to use**
+ *
+ * Use to round a decimal at a requested scale with an explicit rounding mode.
+ *
  * **Example** (Rounding decimals)
  *
  * ```ts
@@ -2386,6 +2862,10 @@ export type RoundingMode =
  * )
  * ```
  *
+ * @see {@link ceil} for fixed rounding toward positive infinity
+ * @see {@link floor} for fixed rounding toward negative infinity
+ * @see {@link truncate} for fixed rounding toward zero
+ *
  * @category math
  * @since 3.16.0
  */
@@ -2393,6 +2873,10 @@ export const round: {
   /**
    * Rounds a `BigDecimal` at the given scale with the specified rounding mode.
    *
+   * **When to use**
+   *
+   * Use to round a decimal at a requested scale with an explicit rounding mode.
+   *
    * **Example** (Rounding decimals)
    *
    * ```ts
@@ -2409,6 +2893,10 @@ export const round: {
    * )
    * ```
    *
+   * @see {@link ceil} for fixed rounding toward positive infinity
+   * @see {@link floor} for fixed rounding toward negative infinity
+   * @see {@link truncate} for fixed rounding toward zero
+   *
    * @category math
    * @since 3.16.0
    */
@@ -2416,6 +2904,10 @@ export const round: {
   /**
    * Rounds a `BigDecimal` at the given scale with the specified rounding mode.
    *
+   * **When to use**
+   *
+   * Use to round a decimal at a requested scale with an explicit rounding mode.
+   *
    * **Example** (Rounding decimals)
    *
    * ```ts
@@ -2432,6 +2924,10 @@ export const round: {
    * )
    * ```
    *
+   * @see {@link ceil} for fixed rounding toward positive infinity
+   * @see {@link floor} for fixed rounding toward negative infinity
+   * @see {@link truncate} for fixed rounding toward zero
+   *
    * @category math
    * @since 3.16.0
    */
@@ -2487,6 +2983,10 @@ export const round: {
  * Truncate a `BigDecimal` at the given scale. This removes fractional digits beyond the scale,
  * rounding toward zero.
  *
+ * **When to use**
+ *
+ * Use to remove digits beyond a requested scale by rounding toward zero.
+ *
  * **Example** (Truncating decimals)
  *
  * ```ts
@@ -2496,6 +2996,10 @@ export const round: {
  * console.log(BigDecimal.truncate(BigDecimal.fromStringUnsafe("-14.5"))) // BigDecimal(-14)
  * ```
  *
+ * @see {@link round} for configurable rounding modes
+ * @see {@link ceil} for rounding toward positive infinity
+ * @see {@link floor} for rounding toward negative infinity
+ *
  * @category math
  * @since 3.16.0
  */
@@ -2504,6 +3008,10 @@ export const truncate: {
    * Truncate a `BigDecimal` at the given scale. This removes fractional digits beyond the scale,
    * rounding toward zero.
    *
+   * **When to use**
+   *
+   * Use to remove digits beyond a requested scale by rounding toward zero.
+   *
    * **Example** (Truncating decimals)
    *
    * ```ts
@@ -2513,6 +3021,10 @@ export const truncate: {
    * console.log(BigDecimal.truncate(BigDecimal.fromStringUnsafe("-14.5"))) // BigDecimal(-14)
    * ```
    *
+   * @see {@link round} for configurable rounding modes
+   * @see {@link ceil} for rounding toward positive infinity
+   * @see {@link floor} for rounding toward negative infinity
+   *
    * @category math
    * @since 3.16.0
    */
@@ -2521,6 +3033,10 @@ export const truncate: {
    * Truncate a `BigDecimal` at the given scale. This removes fractional digits beyond the scale,
    * rounding toward zero.
    *
+   * **When to use**
+   *
+   * Use to remove digits beyond a requested scale by rounding toward zero.
+   *
    * **Example** (Truncating decimals)
    *
    * ```ts
@@ -2530,6 +3046,10 @@ export const truncate: {
    * console.log(BigDecimal.truncate(BigDecimal.fromStringUnsafe("-14.5"))) // BigDecimal(-14)
    * ```
    *
+   * @see {@link round} for configurable rounding modes
+   * @see {@link ceil} for rounding toward positive infinity
+   * @see {@link floor} for rounding toward negative infinity
+   *
    * @category math
    * @since 3.16.0
    */
@@ -2546,6 +3066,20 @@ export const truncate: {
 /**
  * Calculate the ceiling of a `BigDecimal` at the given scale.
  *
+ * **When to use**
+ *
+ * Use to round a decimal toward positive infinity at a requested scale.
+ *
+ * **Details**
+ *
+ * The default scale is `0`. Positive scales keep digits to the right of the
+ * decimal point, and negative scales round positions to the left of the decimal
+ * point.
+ *
+ * @see {@link floor} for rounding toward negative infinity
+ * @see {@link truncate} for rounding toward zero
+ * @see {@link round} for configurable rounding modes
+ *
  * **Example** (Rounding decimals up)
  *
  * ```ts
@@ -2566,6 +3100,20 @@ export const ceil: {
   /**
    * Calculate the ceiling of a `BigDecimal` at the given scale.
    *
+   * **When to use**
+   *
+   * Use to round a decimal toward positive infinity at a requested scale.
+   *
+   * **Details**
+   *
+   * The default scale is `0`. Positive scales keep digits to the right of the
+   * decimal point, and negative scales round positions to the left of the decimal
+   * point.
+   *
+   * @see {@link floor} for rounding toward negative infinity
+   * @see {@link truncate} for rounding toward zero
+   * @see {@link round} for configurable rounding modes
+   *
    * **Example** (Rounding decimals up)
    *
    * ```ts
@@ -2586,6 +3134,20 @@ export const ceil: {
   /**
    * Calculate the ceiling of a `BigDecimal` at the given scale.
    *
+   * **When to use**
+   *
+   * Use to round a decimal toward positive infinity at a requested scale.
+   *
+   * **Details**
+   *
+   * The default scale is `0`. Positive scales keep digits to the right of the
+   * decimal point, and negative scales round positions to the left of the decimal
+   * point.
+   *
+   * @see {@link floor} for rounding toward negative infinity
+   * @see {@link truncate} for rounding toward zero
+   * @see {@link round} for configurable rounding modes
+   *
    * **Example** (Rounding decimals up)
    *
    * ```ts
@@ -2649,6 +3211,10 @@ export const digitAt: {
 /**
  * Calculate the floor of a `BigDecimal` at the given scale.
  *
+ * **When to use**
+ *
+ * Use to round a decimal toward negative infinity at a requested scale.
+ *
  * **Example** (Rounding decimals down)
  *
  * ```ts
@@ -2665,6 +3231,10 @@ export const digitAt: {
  * )
  * ```
  *
+ * @see {@link ceil} for rounding toward positive infinity
+ * @see {@link truncate} for rounding toward zero
+ * @see {@link round} for configurable rounding modes
+ *
  * @category math
  * @since 3.16.0
  */
@@ -2672,6 +3242,10 @@ export const floor: {
   /**
    * Calculate the floor of a `BigDecimal` at the given scale.
    *
+   * **When to use**
+   *
+   * Use to round a decimal toward negative infinity at a requested scale.
+   *
    * **Example** (Rounding decimals down)
    *
    * ```ts
@@ -2688,6 +3262,10 @@ export const floor: {
    * )
    * ```
    *
+   * @see {@link ceil} for rounding toward positive infinity
+   * @see {@link truncate} for rounding toward zero
+   * @see {@link round} for configurable rounding modes
+   *
    * @category math
    * @since 3.16.0
    */
@@ -2695,6 +3273,10 @@ export const floor: {
   /**
    * Calculate the floor of a `BigDecimal` at the given scale.
    *
+   * **When to use**
+   *
+   * Use to round a decimal toward negative infinity at a requested scale.
+   *
    * **Example** (Rounding decimals down)
    *
    * ```ts
@@ -2711,6 +3293,10 @@ export const floor: {
    * )
    * ```
    *
+   * @see {@link ceil} for rounding toward positive infinity
+   * @see {@link truncate} for rounding toward zero
+   * @see {@link round} for configurable rounding modes
+   *
    * @category math
    * @since 3.16.0
    */