effect 4.0.0-beta.65 → 4.0.0-beta.67

package/dist/BigDecimal.js

@@ -54,7 +54,8 @@ const BigDecimalProto = {
 /**
  * Checks if a given value is a `BigDecimal`.
  *
- * @example
+ * **Example** (Checking BigDecimal values)
+ *
  * ```ts
  * import { BigDecimal } from "effect"
  *
@@ -64,14 +65,15 @@ const BigDecimalProto = {
  * console.log(BigDecimal.isBigDecimal("123.45")) // false
  * ```
  *
- * @since 2.0.0
  * @category guards
+ * @since 2.0.0
  */
 export const isBigDecimal = u => hasProperty(u, TypeId);
 /**
  * Creates a `BigDecimal` from a `bigint` value and a scale.
  *
- * @example
+ * **Example** (Creating decimals from bigint and scale)
+ *
  * ```ts
  * import { BigDecimal } from "effect"
  *
@@ -84,8 +86,8 @@ export const isBigDecimal = u => hasProperty(u, TypeId);
  * console.log(BigDecimal.format(integer)) // "42"
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const make = (value, scale) => {
   const o = Object.create(BigDecimalProto);
@@ -118,7 +120,8 @@ const one = /*#__PURE__*/makeNormalizedUnsafe(bigint1, 0);
 /**
  * Normalizes a given `BigDecimal` by removing trailing zeros.
  *
- * @example
+ * **Example** (Normalizing trailing zeros)
+ *
  * ```ts
  * import { fromStringUnsafe, make, normalize } from "effect/BigDecimal"
  * import * as assert from "node:assert"
@@ -133,8 +136,8 @@ const one = /*#__PURE__*/makeNormalizedUnsafe(bigint1, 0);
  * )
  * ```
  *
- * @since 2.0.0
  * @category scaling
+ * @since 2.0.0
  */
 export const normalize = self => {
   if (self.normalized === undefined) {
@@ -161,12 +164,14 @@ export const normalize = self => {
   return self.normalized;
 };
 /**
- * Scales a given `BigDecimal` to the specified scale.
+ * Scales a `BigDecimal` to the specified scale.
+ *
+ * Increasing the scale appends decimal zeros. Decreasing the scale discards
+ * digits beyond the target scale by `bigint` division, which truncates toward
+ * zero.
  *
- * If the given scale is smaller than the current scale, the value will be rounded down to
- * the nearest integer.
+ * **Example** (Scaling decimal precision)
  *
- * @example
  * ```ts
  * import { BigDecimal } from "effect"
  *
@@ -181,8 +186,8 @@ export const normalize = self => {
  * console.log(BigDecimal.format(reduced)) // "123.4"
  * ```
  *
- * @since 2.0.0
  * @category scaling
+ * @since 2.0.0
  */
 export const scale = /*#__PURE__*/dual(2, (self, scale) => {
   if (scale > self.scale) {
@@ -196,7 +201,8 @@ export const scale = /*#__PURE__*/dual(2, (self, scale) => {
 /**
  * Provides an addition operation on `BigDecimal`s.
  *
- * @example
+ * **Example** (Adding decimals)
+ *
  * ```ts
  * import { fromStringUnsafe, sum } from "effect/BigDecimal"
  * import * as assert from "node:assert"
@@ -207,8 +213,8 @@ export const scale = /*#__PURE__*/dual(2, (self, scale) => {
  * )
  * ```
  *
- * @since 2.0.0
  * @category math
+ * @since 2.0.0
  */
 export const sum = /*#__PURE__*/dual(2, (self, that) => {
   if (that.value === bigint0) {
@@ -228,7 +234,8 @@ export const sum = /*#__PURE__*/dual(2, (self, that) => {
 /**
  * Takes an `Iterable` of `BigDecimal`s and returns their sum as a single `BigDecimal`.
  *
- * @example
+ * **Example** (Adding multiple decimals)
+ *
  * ```ts
  * import { fromStringUnsafe, sumAll } from "effect/BigDecimal"
  * import * as assert from "node:assert"
@@ -239,8 +246,8 @@ export const sum = /*#__PURE__*/dual(2, (self, that) => {
  * )
  * ```
  *
- * @since 4.0.0
  * @category math
+ * @since 4.0.0
  */
 export const sumAll = collection => {
   let out = zero;
@@ -252,7 +259,8 @@ export const sumAll = collection => {
 /**
  * Provides a multiplication operation on `BigDecimal`s.
  *
- * @example
+ * **Example** (Multiplying decimals)
+ *
  * ```ts
  * import { fromStringUnsafe, multiply } from "effect/BigDecimal"
  * import * as assert from "node:assert"
@@ -263,8 +271,8 @@ export const sumAll = collection => {
  * )
  * ```
  *
- * @since 2.0.0
  * @category math
+ * @since 2.0.0
  */
 export const multiply = /*#__PURE__*/dual(2, (self, that) => {
   if (that.value === bigint0 || self.value === bigint0) {
@@ -275,7 +283,8 @@ export const multiply = /*#__PURE__*/dual(2, (self, that) => {
 /**
  * Takes an `Iterable` of `BigDecimal`s and returns their multiplication as a single `BigDecimal`.
  *
- * @example
+ * **Example** (Multiplying multiple decimals)
+ *
  * ```ts
  * import { fromStringUnsafe, multiplyAll } from "effect/BigDecimal"
  * import * as assert from "node:assert"
@@ -286,8 +295,8 @@ export const multiply = /*#__PURE__*/dual(2, (self, that) => {
  * )
  * ```
  *
- * @since 4.0.0
  * @category math
+ * @since 4.0.0
  */
 export const multiplyAll = collection => {
   let out = one;
@@ -302,7 +311,8 @@ export const multiplyAll = collection => {
 /**
  * Provides a subtraction operation on `BigDecimal`s.
  *
- * @example
+ * **Example** (Subtracting decimals)
+ *
  * ```ts
  * import { fromStringUnsafe, subtract } from "effect/BigDecimal"
  * import * as assert from "node:assert"
@@ -313,8 +323,8 @@ export const multiplyAll = collection => {
  * )
  * ```
  *
- * @since 2.0.0
  * @category math
+ * @since 2.0.0
  */
 export const subtract = /*#__PURE__*/dual(2, (self, that) => {
   if (that.value === bigint0) {
@@ -386,41 +396,44 @@ export const roundTerminal = n => {
 /**
  * Provides a division operation on `BigDecimal`s.
  *
- * If the dividend is not a multiple of the divisor the result will be a `BigDecimal` value
- * which represents the integer division rounded down to the nearest integer.
+ * If the dividend is not a multiple of the divisor, the result will be a `BigDecimal` value
+ * with up to the default division precision.
  *
  * If the divisor is `0`, the result will be `Option.none()`.
  *
- * @example
+ * **Example** (Dividing decimals safely)
+ *
  * ```ts
  * import { BigDecimal, Option } from "effect"
- * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(
- *   BigDecimal.divide(
- *     BigDecimal.fromStringUnsafe("6"),
- *     BigDecimal.fromStringUnsafe("3")
- *   ),
- *   Option.some(BigDecimal.fromStringUnsafe("2"))
- * )
- * assert.deepStrictEqual(
- *   BigDecimal.divide(
- *     BigDecimal.fromStringUnsafe("6"),
- *     BigDecimal.fromStringUnsafe("4")
- *   ),
- *   Option.some(BigDecimal.fromStringUnsafe("1.5"))
- * )
- * assert.deepStrictEqual(
- *   BigDecimal.divide(
- *     BigDecimal.fromStringUnsafe("6"),
- *     BigDecimal.fromStringUnsafe("0")
- *   ),
- *   Option.none()
- * )
+ * console.log(
+ *   Option.getOrThrow(
+ *     BigDecimal.divide(
+ *       BigDecimal.fromStringUnsafe("6"),
+ *       BigDecimal.fromStringUnsafe("3")
+ *     )
+ *   )
+ * ) // BigDecimal(2)
+ * console.log(
+ *   Option.getOrThrow(
+ *     BigDecimal.divide(
+ *       BigDecimal.fromStringUnsafe("6"),
+ *       BigDecimal.fromStringUnsafe("4")
+ *     )
+ *   )
+ * ) // BigDecimal(1.5)
+ * console.log(
+ *   Option.isNone(
+ *     BigDecimal.divide(
+ *       BigDecimal.fromStringUnsafe("6"),
+ *       BigDecimal.fromStringUnsafe("0")
+ *     )
+ *   )
+ * ) // true
  * ```
  *
- * @since 2.0.0
  * @category math
+ * @since 2.0.0
  */
 export const divide = /*#__PURE__*/dual(2, (self, that) => {
   if (that.value === bigint0) {
@@ -438,28 +451,22 @@ export const divide = /*#__PURE__*/dual(2, (self, that) => {
 /**
  * Provides an unsafe division operation on `BigDecimal`s.
  *
- * If the dividend is not a multiple of the divisor the result will be a `BigDecimal` value
- * which represents the integer division rounded down to the nearest integer.
+ * If the dividend is not a multiple of the divisor, the result will be a `BigDecimal` value
+ * with up to the default division precision.
  *
  * Throws a `RangeError` if the divisor is `0`.
  *
- * @example
+ * **Example** (Dividing decimals unsafely)
+ *
  * ```ts
  * import { divideUnsafe, fromStringUnsafe } from "effect/BigDecimal"
- * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(
- *   divideUnsafe(fromStringUnsafe("6"), fromStringUnsafe("3")),
- *   fromStringUnsafe("2")
- * )
- * assert.deepStrictEqual(
- *   divideUnsafe(fromStringUnsafe("6"), fromStringUnsafe("4")),
- *   fromStringUnsafe("1.5")
- * )
+ * console.log(divideUnsafe(fromStringUnsafe("6"), fromStringUnsafe("3"))) // BigDecimal(2)
+ * console.log(divideUnsafe(fromStringUnsafe("6"), fromStringUnsafe("4"))) // BigDecimal(1.5)
  * ```
  *
- * @since 2.0.0
  * @category math
+ * @since 2.0.0
  */
 export const divideUnsafe = /*#__PURE__*/dual(2, (self, that) => {
   if (that.value === bigint0) {
@@ -477,7 +484,8 @@ export const divideUnsafe = /*#__PURE__*/dual(2, (self, that) => {
 /**
  * Provides an `Order` instance for `BigDecimal` that allows comparing and sorting BigDecimal values.
  *
- * @example
+ * **Example** (Comparing decimals)
+ *
  * ```ts
  * import { BigDecimal } from "effect"
  *
@@ -490,8 +498,8 @@ export const divideUnsafe = /*#__PURE__*/dual(2, (self, that) => {
  * console.log(BigDecimal.Order(a, c)) // 0 (a === c)
  * ```
  *
- * @since 2.0.0
  * @category instances
+ * @since 2.0.0
  */
 export const Order = /*#__PURE__*/order.make((self, that) => {
   const scmp = order.Number(sign(self), sign(that));
@@ -509,7 +517,8 @@ export const Order = /*#__PURE__*/order.make((self, that) => {
 /**
  * Returns `true` if the first argument is less than the second, otherwise `false`.
  *
- * @example
+ * **Example** (Checking less-than comparisons)
+ *
  * ```ts
  * import { fromStringUnsafe, isLessThan } from "effect/BigDecimal"
  * import * as assert from "node:assert"
@@ -528,14 +537,15 @@ export const Order = /*#__PURE__*/order.make((self, that) => {
  * )
  * ```
  *
- * @since 2.0.0
  * @category predicates
+ * @since 2.0.0
  */
 export const isLessThan = /*#__PURE__*/order.isLessThan(Order);
 /**
  * Checks if a given `BigDecimal` is less than or equal to the provided one.
  *
- * @example
+ * **Example** (Checking less-than-or-equal comparisons)
+ *
  * ```ts
  * import { fromStringUnsafe, isLessThanOrEqualTo } from "effect/BigDecimal"
  * import * as assert from "node:assert"
@@ -554,14 +564,15 @@ export const isLessThan = /*#__PURE__*/order.isLessThan(Order);
  * )
  * ```
  *
- * @since 2.0.0
  * @category predicates
+ * @since 2.0.0
  */
 export const isLessThanOrEqualTo = /*#__PURE__*/order.isLessThanOrEqualTo(Order);
 /**
  * Returns `true` if the first argument is greater than the second, otherwise `false`.
  *
- * @example
+ * **Example** (Checking greater-than comparisons)
+ *
  * ```ts
  * import { fromStringUnsafe, isGreaterThan } from "effect/BigDecimal"
  * import * as assert from "node:assert"
@@ -580,14 +591,15 @@ export const isLessThanOrEqualTo = /*#__PURE__*/order.isLessThanOrEqualTo(Order)
  * )
  * ```
  *
- * @since 2.0.0
  * @category predicates
+ * @since 2.0.0
  */
 export const isGreaterThan = /*#__PURE__*/order.isGreaterThan(Order);
 /**
  * Checks if a given `BigDecimal` is greater than or equal to the provided one.
  *
- * @example
+ * **Example** (Checking greater-than-or-equal comparisons)
+ *
  * ```ts
  * import { fromStringUnsafe, isGreaterThanOrEqualTo } from "effect/BigDecimal"
  * import * as assert from "node:assert"
@@ -606,14 +618,15 @@ export const isGreaterThan = /*#__PURE__*/order.isGreaterThan(Order);
  * )
  * ```
  *
- * @since 2.0.0
  * @category predicates
+ * @since 2.0.0
  */
 export const isGreaterThanOrEqualTo = /*#__PURE__*/order.isGreaterThanOrEqualTo(Order);
 /**
  * Checks if a `BigDecimal` is between a `minimum` and `maximum` value (inclusive).
  *
- * @example
+ * **Example** (Checking decimal ranges)
+ *
  * ```ts
  * import { BigDecimal } from "effect"
  * import * as assert from "node:assert"
@@ -628,8 +641,8 @@ export const isGreaterThanOrEqualTo = /*#__PURE__*/order.isGreaterThanOrEqualTo(
  * assert.deepStrictEqual(between(BigDecimal.fromStringUnsafe("6")), false)
  * ```
  *
- * @since 2.0.0
  * @category predicates
+ * @since 2.0.0
  */
 export const between = /*#__PURE__*/order.isBetween(Order);
 /**
@@ -639,7 +652,8 @@ export const between = /*#__PURE__*/order.isBetween(Order);
  * - If the `BigDecimal` is greater than the `maximum` value, the function returns the `maximum` value.
  * - Otherwise, it returns the original `BigDecimal`.
  *
- * @example
+ * **Example** (Clamping decimals to a range)
+ *
  * ```ts
  * import { BigDecimal } from "effect"
  * import * as assert from "node:assert"
@@ -663,14 +677,15 @@ export const between = /*#__PURE__*/order.isBetween(Order);
  * )
  * ```
  *
- * @since 2.0.0
  * @category math
+ * @since 2.0.0
  */
 export const clamp = /*#__PURE__*/order.clamp(Order);
 /**
  * Returns the minimum between two `BigDecimal`s.
  *
- * @example
+ * **Example** (Selecting the smaller decimal)
+ *
  * ```ts
  * import { fromStringUnsafe, min } from "effect/BigDecimal"
  * import * as assert from "node:assert"
@@ -681,14 +696,15 @@ export const clamp = /*#__PURE__*/order.clamp(Order);
  * )
  * ```
  *
- * @since 2.0.0
  * @category math
+ * @since 2.0.0
  */
 export const min = /*#__PURE__*/order.min(Order);
 /**
  * Returns the maximum between two `BigDecimal`s.
  *
- * @example
+ * **Example** (Selecting the larger decimal)
+ *
  * ```ts
  * import { fromStringUnsafe, max } from "effect/BigDecimal"
  * import * as assert from "node:assert"
@@ -699,14 +715,15 @@ export const min = /*#__PURE__*/order.min(Order);
  * )
  * ```
  *
- * @since 2.0.0
  * @category math
+ * @since 2.0.0
  */
 export const max = /*#__PURE__*/order.max(Order);
 /**
  * Determines the sign of a given `BigDecimal`.
  *
- * @example
+ * **Example** (Reading decimal signs)
+ *
  * ```ts
  * import { fromStringUnsafe, sign } from "effect/BigDecimal"
  * import * as assert from "node:assert"
@@ -716,14 +733,15 @@ export const max = /*#__PURE__*/order.max(Order);
  * assert.deepStrictEqual(sign(fromStringUnsafe("5")), 1)
  * ```
  *
- * @since 2.0.0
  * @category math
+ * @since 2.0.0
  */
 export const sign = n => n.value === bigint0 ? 0 : n.value < bigint0 ? -1 : 1;
 /**
  * Determines the absolute value of a given `BigDecimal`.
  *
- * @example
+ * **Example** (Calculating absolute values)
+ *
  * ```ts
  * import { abs, fromStringUnsafe } from "effect/BigDecimal"
  * import * as assert from "node:assert"
@@ -733,14 +751,15 @@ export const sign = n => n.value === bigint0 ? 0 : n.value < bigint0 ? -1 : 1;
  * assert.deepStrictEqual(abs(fromStringUnsafe("5")), fromStringUnsafe("5"))
  * ```
  *
- * @since 2.0.0
  * @category math
+ * @since 2.0.0
  */
 export const abs = n => n.value < bigint0 ? make(-n.value, n.scale) : n;
 /**
  * Provides a negate operation on `BigDecimal`s.
  *
- * @example
+ * **Example** (Negating decimals)
+ *
  * ```ts
  * import { fromStringUnsafe, negate } from "effect/BigDecimal"
  * import * as assert from "node:assert"
@@ -749,8 +768,8 @@ export const abs = n => n.value < bigint0 ? make(-n.value, n.scale) : n;
  * assert.deepStrictEqual(negate(fromStringUnsafe("-6")), fromStringUnsafe("6"))
  * ```
  *
- * @since 2.0.0
  * @category math
+ * @since 2.0.0
  */
 export const negate = n => make(-n.value, n.scale);
 /**
@@ -758,7 +777,8 @@ export const negate = n => make(-n.value, n.scale);
  *
  * If the divisor is `0`, the result will be `Option.none()`.
  *
- * @example
+ * **Example** (Computing remainders safely)
+ *
  * ```ts
  * import { BigDecimal, Option } from "effect"
  * import * as assert from "node:assert"
@@ -786,8 +806,8 @@ export const negate = n => make(-n.value, n.scale);
  * )
  * ```
  *
- * @since 2.0.0
  * @category math
+ * @since 2.0.0
  */
 export const remainder = /*#__PURE__*/dual(2, (self, divisor) => {
   if (divisor.value === bigint0) {
@@ -801,7 +821,8 @@ export const remainder = /*#__PURE__*/dual(2, (self, divisor) => {
  *
  * Throws a `RangeError` if the divisor is `0`.
  *
- * @example
+ * **Example** (Computing remainders unsafely)
+ *
  * ```ts
  * import { fromStringUnsafe, remainderUnsafe } from "effect/BigDecimal"
  * import * as assert from "node:assert"
@@ -820,8 +841,8 @@ export const remainder = /*#__PURE__*/dual(2, (self, divisor) => {
  * )
  * ```
  *
- * @since 2.0.0
  * @category math
+ * @since 2.0.0
  */
 export const remainderUnsafe = /*#__PURE__*/dual(2, (self, divisor) => {
   if (divisor.value === bigint0) {
@@ -833,13 +854,14 @@ export const remainderUnsafe = /*#__PURE__*/dual(2, (self, divisor) => {
 /**
  * Provides an `Equivalence` instance for `BigDecimal` that determines equality between BigDecimal values.
  *
- * @example
+ * **Example** (Checking decimal equivalence)
+ *
  * ```ts
  * import { BigDecimal } from "effect"
  *
- * const a = BigDecimal.fromNumberUnsafe(1.50)
- * const b = BigDecimal.fromNumberUnsafe(1.5)
- * const c = BigDecimal.fromNumberUnsafe(2.0)
+ * const a = BigDecimal.fromStringUnsafe("1.50")
+ * const b = BigDecimal.fromStringUnsafe("1.5")
+ * const c = BigDecimal.fromStringUnsafe("2.0")
  *
  * console.log(BigDecimal.Equivalence(a, b)) // true (1.50 === 1.5)
  * console.log(BigDecimal.Equivalence(a, c)) // false (1.50 !== 2.0)
@@ -860,26 +882,28 @@ export const Equivalence = /*#__PURE__*/Equ.make((self, that) => {
 /**
  * Checks if two `BigDecimal`s are equal.
  *
- * @example
+ * **Example** (Checking decimal equality)
+ *
  * ```ts
  * import { BigDecimal } from "effect"
  *
- * const a = BigDecimal.fromNumberUnsafe(1.5)
- * const b = BigDecimal.fromNumberUnsafe(1.50)
- * const c = BigDecimal.fromNumberUnsafe(2.0)
+ * const a = BigDecimal.fromStringUnsafe("1.5")
+ * const b = BigDecimal.fromStringUnsafe("1.50")
+ * const c = BigDecimal.fromStringUnsafe("2.0")
  *
  * console.log(BigDecimal.equals(a, b)) // true
  * console.log(BigDecimal.equals(a, c)) // false
  * ```
  *
- * @since 2.0.0
  * @category predicates
+ * @since 2.0.0
  */
 export const equals = /*#__PURE__*/dual(2, (self, that) => Equivalence(self, that));
 /**
  * Creates a `BigDecimal` from a `bigint` value.
  *
- * @example
+ * **Example** (Creating decimals from bigint)
+ *
  * ```ts
  * import { BigDecimal } from "effect"
  *
@@ -890,8 +914,8 @@ export const equals = /*#__PURE__*/dual(2, (self, that) => Equivalence(self, tha
  * console.log(BigDecimal.format(largeBigInt)) // "9007199254740991"
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const fromBigInt = n => make(n, 0);
 /**
@@ -902,7 +926,8 @@ export const fromBigInt = n => make(n, 0);
  *
  * Throws a `RangeError` if the number is not finite (`NaN`, `+Infinity` or `-Infinity`).
  *
- * @example
+ * **Example** (Creating decimals from finite numbers)
+ *
  * ```ts
  * import { fromNumberUnsafe, make } from "effect/BigDecimal"
  * import * as assert from "node:assert"
@@ -911,8 +936,8 @@ export const fromBigInt = n => make(n, 0);
  * assert.deepStrictEqual(fromNumberUnsafe(123.456), make(123456n, 3))
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const fromNumberUnsafe = n => {
   return Option.getOrThrowWith(fromNumber(n), () => new RangeError(`Number must be finite, got ${n}`));
@@ -925,7 +950,8 @@ export const fromNumberUnsafe = n => {
  *
  * Returns `Option.none()` for `NaN`, `+Infinity` or `-Infinity`.
  *
- * @example
+ * **Example** (Creating decimals from numbers safely)
+ *
  * ```ts
  * import { BigDecimal, Option } from "effect"
  * import * as assert from "node:assert"
@@ -938,8 +964,8 @@ export const fromNumberUnsafe = n => {
  * assert.deepStrictEqual(BigDecimal.fromNumber(Infinity), Option.none())
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const fromNumber = n => {
   if (!Number.isFinite(n)) {
@@ -953,9 +979,14 @@ export const fromNumber = n => {
   return Option.some(make(BigInt(`${lead}${trail}`), trail.length));
 };
 /**
- * Parses a numerical `string` into a `BigDecimal`.
+ * Safely parses a decimal string into a `BigDecimal`.
+ *
+ * Returns `Option.some` for valid decimal or exponent notation and
+ * `Option.none` when the string cannot be parsed or would produce an unsafe
+ * scale. The empty string parses as zero.
+ *
+ * **Example** (Parsing decimal strings safely)
  *
- * @example
  * ```ts
  * import { BigDecimal, Option } from "effect"
  * import * as assert from "node:assert"
@@ -968,8 +999,8 @@ export const fromNumber = n => {
  * assert.deepStrictEqual(BigDecimal.fromString("123.abc"), Option.none())
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const fromString = s => {
   if (s === "") {
@@ -1011,9 +1042,14 @@ export const fromString = s => {
   return Option.some(make(BigInt(digits), scale));
 };
 /**
- * Parses a numerical `string` into a `BigDecimal`.
+ * Parses a decimal string into a `BigDecimal`, throwing if the string is
+ * invalid.
+ *
+ * Accepts the same syntax as `fromString`. Use `fromString` when invalid input
+ * should be represented as `Option.none` instead of throwing.
+ *
+ * **Example** (Parsing decimal strings unsafely)
  *
- * @example
  * ```ts
  * import { fromStringUnsafe, make } from "effect/BigDecimal"
  * import * as assert from "node:assert"
@@ -1023,19 +1059,21 @@ export const fromString = s => {
  * assert.throws(() => fromStringUnsafe("123.abc"))
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const fromStringUnsafe = s => {
   return Option.getOrThrowWith(fromString(s), () => new Error(`Invalid numerical string: ${s}`));
 };
 /**
- * Formats a given `BigDecimal` as a `string`.
+ * Formats a `BigDecimal` as a string.
+ *
+ * The value is normalized before formatting. Scientific notation is used when
+ * the absolute value of the normalized scale is at least `16`; otherwise plain
+ * decimal notation is used.
  *
- * If the scale of the `BigDecimal` is greater than or equal to 16, the `BigDecimal` will
- * be formatted in scientific notation.
+ * **Example** (Formatting decimals)
  *
- * @example
  * ```ts
  * import { format, fromStringUnsafe } from "effect/BigDecimal"
  * import * as assert from "node:assert"
@@ -1045,8 +1083,8 @@ export const fromStringUnsafe = s => {
  * assert.deepStrictEqual(format(fromStringUnsafe("-0.00000123")), "-0.00000123")
  * ```
  *
- * @since 2.0.0
  * @category conversions
+ * @since 2.0.0
  */
 export const format = n => {
   const normalized = normalize(n);
@@ -1077,7 +1115,8 @@ export const format = n => {
 /**
  * Formats a given `BigDecimal` as a `string` in scientific notation.
  *
- * @example
+ * **Example** (Formatting decimals exponentially)
+ *
  * ```ts
  * import { make, toExponential } from "effect/BigDecimal"
  * import * as assert from "node:assert"
@@ -1085,8 +1124,8 @@ export const format = n => {
  * assert.deepStrictEqual(toExponential(make(123456n, -5)), "1.23456e+10")
  * ```
  *
- * @since 4.0.0
  * @category conversions
+ * @since 4.0.0
  */
 export const toExponential = n => {
   if (isZero(n)) {
@@ -1104,11 +1143,14 @@ export const toExponential = n => {
   return `${output}e${exp >= 0 ? "+" : ""}${exp}`;
 };
 /**
- * Converts a `BigDecimal` to a `number`.
+ * Converts a `BigDecimal` to a JavaScript `number`.
  *
- * This function will produce incorrect results if the `BigDecimal` exceeds the 64-bit range of a `number`.
+ * This conversion is unsafe because the result can lose integer or fractional
+ * precision, round to a nearby representable value, or become `Infinity` when
+ * the decimal cannot be represented as a finite JavaScript `number`.
+ *
+ * **Example** (Converting decimals to numbers)
  *
- * @example
  * ```ts
  * import { fromStringUnsafe, toNumberUnsafe } from "effect/BigDecimal"
  * import * as assert from "node:assert"
@@ -1116,14 +1158,15 @@ export const toExponential = n => {
  * assert.deepStrictEqual(toNumberUnsafe(fromStringUnsafe("123.456")), 123.456)
  * ```
  *
- * @since 2.0.0
  * @category conversions
+ * @since 2.0.0
  */
 export const toNumberUnsafe = n => Number(format(n));
 /**
  * Checks if a given `BigDecimal` is an integer.
  *
- * @example
+ * **Example** (Checking integer decimals)
+ *
  * ```ts
  * import { fromStringUnsafe, isInteger } from "effect/BigDecimal"
  * import * as assert from "node:assert"
@@ -1133,14 +1176,15 @@ export const toNumberUnsafe = n => Number(format(n));
  * assert.deepStrictEqual(isInteger(fromStringUnsafe("1.1")), false)
  * ```
  *
- * @since 2.0.0
  * @category predicates
+ * @since 2.0.0
  */
 export const isInteger = n => normalize(n).scale <= 0;
 /**
  * Checks if a given `BigDecimal` is `0`.
  *
- * @example
+ * **Example** (Checking zero decimals)
+ *
  * ```ts
  * import { fromStringUnsafe, isZero } from "effect/BigDecimal"
  * import * as assert from "node:assert"
@@ -1149,14 +1193,15 @@ export const isInteger = n => normalize(n).scale <= 0;
  * assert.deepStrictEqual(isZero(fromStringUnsafe("1")), false)
  * ```
  *
- * @since 2.0.0
  * @category predicates
+ * @since 2.0.0
  */
 export const isZero = n => n.value === bigint0;
 /**
  * Checks if a given `BigDecimal` is negative.
  *
- * @example
+ * **Example** (Checking negative decimals)
+ *
  * ```ts
  * import { fromStringUnsafe, isNegative } from "effect/BigDecimal"
  * import * as assert from "node:assert"
@@ -1166,14 +1211,15 @@ export const isZero = n => n.value === bigint0;
  * assert.deepStrictEqual(isNegative(fromStringUnsafe("1")), false)
  * ```
  *
- * @since 2.0.0
  * @category predicates
+ * @since 2.0.0
  */
 export const isNegative = n => n.value < bigint0;
 /**
  * Checks if a given `BigDecimal` is positive.
  *
- * @example
+ * **Example** (Checking positive decimals)
+ *
  * ```ts
  * import { fromStringUnsafe, isPositive } from "effect/BigDecimal"
  * import * as assert from "node:assert"
@@ -1183,15 +1229,16 @@ export const isNegative = n => n.value < bigint0;
  * assert.deepStrictEqual(isPositive(fromStringUnsafe("1")), true)
  * ```
  *
- * @since 2.0.0
  * @category predicates
+ * @since 2.0.0
  */
 export const isPositive = n => n.value > bigint0;
 const isBigDecimalArgs = args => isBigDecimal(args[0]);
 /**
  * Rounds a `BigDecimal` at the given scale with the specified rounding mode.
  *
- * @example
+ * **Example** (Rounding decimals)
+ *
  * ```ts
  * import { fromStringUnsafe, round } from "effect/BigDecimal"
  * import * as assert from "node:assert"
@@ -1206,8 +1253,8 @@ const isBigDecimalArgs = args => isBigDecimal(args[0]);
  * )
  * ```
  *
- * @since 4.0.0
  * @category math
+ * @since 4.0.0
  */
 export const round = /*#__PURE__*/dual(isBigDecimalArgs, (self, options) => {
   const mode = options?.mode ?? "half-from-zero";
@@ -1241,25 +1288,20 @@ export const round = /*#__PURE__*/dual(isBigDecimalArgs, (self, options) => {
   }
 });
 /**
- * Truncate a `BigDecimal` at the given scale. This is the same operation as rounding away from zero.
+ * Truncate a `BigDecimal` at the given scale. This removes fractional digits beyond the scale,
+ * rounding toward zero.
+ *
+ * **Example** (Truncating decimals)
  *
- * @example
  * ```ts
  * import { fromStringUnsafe, truncate } from "effect/BigDecimal"
- * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(
- *   truncate(fromStringUnsafe("145"), -1),
- *   fromStringUnsafe("140")
- * )
- * assert.deepStrictEqual(
- *   truncate(fromStringUnsafe("-14.5")),
- *   fromStringUnsafe("-14")
- * )
+ * console.log(truncate(fromStringUnsafe("145"), -1)) // BigDecimal(140)
+ * console.log(truncate(fromStringUnsafe("-14.5"))) // BigDecimal(-14)
  * ```
  *
- * @since 4.0.0
  * @category math
+ * @since 4.0.0
  */
 export const truncate = /*#__PURE__*/dual(isBigDecimalArgs, (self, scale = 0) => {
   if (self.scale <= scale) {
@@ -1271,7 +1313,8 @@ export const truncate = /*#__PURE__*/dual(isBigDecimalArgs, (self, scale = 0) =>
 /**
  * Calculate the ceiling of a `BigDecimal` at the given scale.
  *
- * @example
+ * **Example** (Rounding decimals up)
+ *
  * ```ts
  * import { ceil, fromStringUnsafe } from "effect/BigDecimal"
  * import * as assert from "node:assert"
@@ -1283,8 +1326,8 @@ export const truncate = /*#__PURE__*/dual(isBigDecimalArgs, (self, scale = 0) =>
  * assert.deepStrictEqual(ceil(fromStringUnsafe("-14.5")), fromStringUnsafe("-14"))
  * ```
  *
- * @since 4.0.0
  * @category math
+ * @since 4.0.0
  */
 export const ceil = /*#__PURE__*/dual(isBigDecimalArgs, (self, scale = 0) => {
   const truncated = truncate(self, scale);
@@ -1310,7 +1353,8 @@ export const digitAt = /*#__PURE__*/dual(2, (self, scale) => {
 /**
  * Calculate the floor of a `BigDecimal` at the given scale.
  *
- * @example
+ * **Example** (Rounding decimals down)
+ *
  * ```ts
  * import { floor, fromStringUnsafe } from "effect/BigDecimal"
  * import * as assert from "node:assert"
@@ -1325,8 +1369,8 @@ export const digitAt = /*#__PURE__*/dual(2, (self, scale) => {
  * )
  * ```
  *
- * @since 4.0.0
  * @category math
+ * @since 4.0.0
  */
 export const floor = /*#__PURE__*/dual(isBigDecimalArgs, (self, scale = 0) => {
   const truncated = truncate(self, scale);