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

package/dist/BigDecimal.js

@@ -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
  */
@@ -54,6 +98,10 @@ const BigDecimalProto = {
 /**
  * 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
@@ -72,6 +120,11 @@ export const isBigDecimal = u => hasProperty(u, TypeId);
 /**
  * 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
@@ -86,6 +139,8 @@ export const isBigDecimal = u => hasProperty(u, TypeId);
  * console.log(BigDecimal.format(integer)) // "42"
  * ```
  *
+ * @see {@link fromBigInt} for constructing an integer decimal from a `bigint`
+ *
  * @category constructors
  * @since 2.0.0
  */
@@ -120,6 +175,11 @@ const one = /*#__PURE__*/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
@@ -136,6 +196,8 @@ const one = /*#__PURE__*/makeNormalizedUnsafe(bigint1, 0);
  * )
  * ```
  *
+ * @see {@link format} for rendering normalized decimals as strings
+ *
  * @category scaling
  * @since 2.0.0
  */
@@ -166,6 +228,10 @@ export const normalize = self => {
 /**
  * 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
@@ -188,6 +254,8 @@ export const normalize = self => {
  * console.log(BigDecimal.format(reduced)) // "123.4"
  * ```
  *
+ * @see {@link round} for changing scale with configurable rounding
+ *
  * @category scaling
  * @since 2.0.0
  */
@@ -203,6 +271,10 @@ export const scale = /*#__PURE__*/dual(2, (self, scale) => {
 /**
  * Provides an addition operation on `BigDecimal`s.
  *
+ * **When to use**
+ *
+ * Use to add two `BigDecimal` values.
+ *
  * **Example** (Adding decimals)
  *
  * ```ts
@@ -215,6 +287,8 @@ export const scale = /*#__PURE__*/dual(2, (self, scale) => {
  * )
  * ```
  *
+ * @see {@link sumAll} for summing an iterable of `BigDecimal` values
+ *
  * @category math
  * @since 2.0.0
  */
@@ -236,6 +310,10 @@ export const sum = /*#__PURE__*/dual(2, (self, that) => {
 /**
  * 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
@@ -248,6 +326,8 @@ export const sum = /*#__PURE__*/dual(2, (self, that) => {
  * )
  * ```
  *
+ * @see {@link sum} for adding two `BigDecimal` values
+ *
  * @category math
  * @since 3.16.0
  */
@@ -261,6 +341,10 @@ export const sumAll = collection => {
 /**
  * Provides a multiplication operation on `BigDecimal`s.
  *
+ * **When to use**
+ *
+ * Use to multiply two `BigDecimal` values.
+ *
  * **Example** (Multiplying decimals)
  *
  * ```ts
@@ -273,6 +357,8 @@ export const sumAll = collection => {
  * )
  * ```
  *
+ * @see {@link multiplyAll} for multiplying an iterable of `BigDecimal` values
+ *
  * @category math
  * @since 2.0.0
  */
@@ -285,6 +371,10 @@ export const multiply = /*#__PURE__*/dual(2, (self, that) => {
 /**
  * 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
@@ -297,6 +387,8 @@ export const multiply = /*#__PURE__*/dual(2, (self, that) => {
  * )
  * ```
  *
+ * @see {@link multiply} for multiplying two `BigDecimal` values
+ *
  * @category math
  * @since 4.0.0
  */
@@ -313,6 +405,10 @@ export const multiplyAll = collection => {
 /**
  * Provides a subtraction operation on `BigDecimal`s.
  *
+ * **When to use**
+ *
+ * Use to subtract one `BigDecimal` value from another.
+ *
  * **Example** (Subtracting decimals)
  *
  * ```ts
@@ -398,6 +494,11 @@ export const roundTerminal = n => {
 /**
  * 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
@@ -435,6 +536,9 @@ export const roundTerminal = n => {
  * ) // 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
  */
@@ -454,6 +558,11 @@ export const divide = /*#__PURE__*/dual(2, (self, that) => {
 /**
  * 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
@@ -472,6 +581,8 @@ export const divide = /*#__PURE__*/dual(2, (self, that) => {
  * 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
  */
@@ -491,6 +602,10 @@ export const divideUnsafe = /*#__PURE__*/dual(2, (self, that) => {
 /**
  * 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
@@ -524,6 +639,10 @@ export const Order = /*#__PURE__*/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
@@ -551,6 +670,10 @@ export const isLessThan = /*#__PURE__*/order.isLessThan(Order);
 /**
  * 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
@@ -578,6 +701,10 @@ export const isLessThanOrEqualTo = /*#__PURE__*/order.isLessThanOrEqualTo(Order)
 /**
  * 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
@@ -605,6 +732,10 @@ export const isGreaterThan = /*#__PURE__*/order.isGreaterThan(Order);
 /**
  * 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
@@ -632,6 +763,10 @@ export const isGreaterThanOrEqualTo = /*#__PURE__*/order.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
@@ -648,6 +783,8 @@ export const isGreaterThanOrEqualTo = /*#__PURE__*/order.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
  */
@@ -655,6 +792,10 @@ export const between = /*#__PURE__*/order.isBetween(Order);
 /**
  * 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
@@ -686,6 +827,8 @@ export const between = /*#__PURE__*/order.isBetween(Order);
  * )
  * ```
  *
+ * @see {@link between} for checking whether a `BigDecimal` is already inside a range
+ *
  * @category math
  * @since 2.0.0
  */
@@ -693,6 +836,10 @@ export const clamp = /*#__PURE__*/order.clamp(Order);
 /**
  * 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
@@ -705,6 +852,8 @@ export const clamp = /*#__PURE__*/order.clamp(Order);
  * )
  * ```
  *
+ * @see {@link max} for selecting the larger value
+ *
  * @category math
  * @since 2.0.0
  */
@@ -712,6 +861,10 @@ export const min = /*#__PURE__*/order.min(Order);
 /**
  * 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
@@ -724,6 +877,8 @@ export const min = /*#__PURE__*/order.min(Order);
  * )
  * ```
  *
+ * @see {@link min} for selecting the smaller value
+ *
  * @category math
  * @since 2.0.0
  */
@@ -731,6 +886,10 @@ export const max = /*#__PURE__*/order.max(Order);
 /**
  * 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
@@ -749,6 +908,10 @@ export const sign = n => n.value === bigint0 ? 0 : n.value < bigint0 ? -1 : 1;
 /**
  * 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
@@ -767,6 +930,10 @@ export const abs = n => n.value < bigint0 ? make(-n.value, n.scale) : n;
 /**
  * Provides a negate operation on `BigDecimal`s.
  *
+ * **When to use**
+ *
+ * Use to flip the sign of a `BigDecimal`.
+ *
  * **Example** (Negating decimals)
  *
  * ```ts
@@ -784,6 +951,11 @@ export const negate = n => 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()`.
@@ -817,6 +989,9 @@ export const negate = n => 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
  */
@@ -830,6 +1005,11 @@ export const remainder = /*#__PURE__*/dual(2, (self, divisor) => {
 /**
  * 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`.
@@ -854,6 +1034,8 @@ export const remainder = /*#__PURE__*/dual(2, (self, divisor) => {
  * )
  * ```
  *
+ * @see {@link remainder} for returning `Option.none` when the divisor is zero
+ *
  * @category math
  * @since 4.0.0
  */
@@ -867,6 +1049,10 @@ export const remainderUnsafe = /*#__PURE__*/dual(2, (self, divisor) => {
 /**
  * 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
@@ -895,6 +1081,10 @@ export const Equivalence = /*#__PURE__*/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
@@ -908,6 +1098,8 @@ export const Equivalence = /*#__PURE__*/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
  */
@@ -915,6 +1107,10 @@ export const equals = /*#__PURE__*/dual(2, (self, that) => Equivalence(self, tha
 /**
  * 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
@@ -927,6 +1123,8 @@ export const equals = /*#__PURE__*/dual(2, (self, that) => Equivalence(self, tha
  * console.log(BigDecimal.format(largeBigInt)) // "9007199254740991"
  * ```
  *
+ * @see {@link make} for constructing a decimal with an explicit scale
+ *
  * @category constructors
  * @since 2.0.0
  */
@@ -934,6 +1132,11 @@ export const fromBigInt = n => 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
@@ -950,6 +1153,8 @@ export const fromBigInt = n => 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
  */
@@ -959,6 +1164,11 @@ export const fromNumberUnsafe = n => {
 /**
  * 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`.
@@ -982,6 +1192,9 @@ export const fromNumberUnsafe = n => {
  * 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
  */
@@ -999,6 +1212,10 @@ export const fromNumber = n => {
 /**
  * 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
@@ -1019,6 +1236,9 @@ export const fromNumber = n => {
  * 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
  */
@@ -1065,6 +1285,10 @@ export const fromString = s => {
  * 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
@@ -1081,6 +1305,8 @@ export const fromString = s => {
  * assert.throws(() => BigDecimal.fromStringUnsafe("123.abc"))
  * ```
  *
+ * @see {@link fromString} for returning `Option.none` on invalid input
+ *
  * @category constructors
  * @since 4.0.0
  */
@@ -1090,6 +1316,10 @@ export const fromStringUnsafe = s => {
 /**
  * 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
@@ -1107,6 +1337,8 @@ export const fromStringUnsafe = s => {
  * assert.deepStrictEqual(BigDecimal.format(BigDecimal.fromStringUnsafe("-0.00000123")), "-0.00000123")
  * ```
  *
+ * @see {@link toExponential} for always rendering scientific notation
+ *
  * @category converting
  * @since 2.0.0
  */
@@ -1139,6 +1371,10 @@ export const format = n => {
 /**
  * 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
@@ -1148,6 +1384,8 @@ export const format = n => {
  * 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
  */
@@ -1169,6 +1407,11 @@ export const toExponential = n => {
 /**
  * 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
@@ -1184,6 +1427,8 @@ export const toExponential = n => {
  * 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
  */
@@ -1191,6 +1436,10 @@ export const toNumberUnsafe = n => 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
@@ -1209,6 +1458,10 @@ export const isInteger = n => 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
@@ -1226,6 +1479,10 @@ export const isZero = n => 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
@@ -1244,6 +1501,10 @@ export const isNegative = n => 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
@@ -1263,6 +1524,10 @@ const isBigDecimalArgs = args => isBigDecimal(args[0]);
 /**
  * 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
@@ -1279,6 +1544,10 @@ const isBigDecimalArgs = args => isBigDecimal(args[0]);
  * )
  * ```
  *
+ * @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
  */
@@ -1317,6 +1586,10 @@ export const round = /*#__PURE__*/dual(isBigDecimalArgs, (self, options) => {
  * 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
@@ -1326,6 +1599,10 @@ export const round = /*#__PURE__*/dual(isBigDecimalArgs, (self, options) => {
  * 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
  */
@@ -1339,6 +1616,20 @@ export const truncate = /*#__PURE__*/dual(isBigDecimalArgs, (self, scale = 0) =>
 /**
  * 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
@@ -1379,6 +1670,10 @@ export const digitAt = /*#__PURE__*/dual(2, (self, scale) => {
 /**
  * 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
@@ -1395,6 +1690,10 @@ export const digitAt = /*#__PURE__*/dual(2, (self, scale) => {
  * )
  * ```
  *
+ * @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
  */