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

package/src/BigDecimal.ts

@@ -33,14 +33,15 @@ const TypeId = "~effect/BigDecimal"
 /**
  * Represents an arbitrary precision decimal number.
  *
- * @example
+ * **Example** (Inspecting BigDecimal storage)
+ *
  * ```ts
  * import { BigDecimal } from "effect"
  *
- * const d = BigDecimal.fromNumberUnsafe(123.45)
+ * const d = BigDecimal.fromStringUnsafe("123.45")
  *
- * d.value // 12345n
- * d.scale // 2
+ * console.log(d.value) // 12345n
+ * console.log(d.scale) // 2
  * ```
  *
  * @category models
@@ -84,7 +85,8 @@ const BigDecimalProto: Omit<BigDecimal, "value" | "scale" | "normalized"> = {
 /**
  * Checks if a given value is a `BigDecimal`.
  *
- * @example
+ * **Example** (Checking BigDecimal values)
+ *
  * ```ts
  * import { BigDecimal } from "effect"
  *
@@ -94,15 +96,16 @@ const BigDecimalProto: Omit<BigDecimal, "value" | "scale" | "normalized"> = {
  * console.log(BigDecimal.isBigDecimal("123.45")) // false
  * ```
  *
- * @since 2.0.0
  * @category guards
+ * @since 2.0.0
  */
 export const isBigDecimal = (u: unknown): u is BigDecimal => 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"
  *
@@ -115,8 +118,8 @@ export const isBigDecimal = (u: unknown): u is BigDecimal => hasProperty(u, Type
  * console.log(BigDecimal.format(integer)) // "42"
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const make = (value: bigint, scale: number): BigDecimal => {
   const o = Object.create(BigDecimalProto)
@@ -153,7 +156,8 @@ const one = 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"
@@ -168,8 +172,8 @@ const one = makeNormalizedUnsafe(bigint1, 0)
  * )
  * ```
  *
- * @since 2.0.0
  * @category scaling
+ * @since 2.0.0
  */
 export const normalize = (self: BigDecimal): BigDecimal => {
   if (self.normalized === undefined) {
@@ -201,12 +205,14 @@ export const normalize = (self: BigDecimal): BigDecimal => {
 }
 
 /**
- * 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"
  *
@@ -221,17 +227,19 @@ export const normalize = (self: BigDecimal): BigDecimal => {
  * console.log(BigDecimal.format(reduced)) // "123.4"
  * ```
  *
- * @since 2.0.0
  * @category scaling
+ * @since 2.0.0
  */
 export const scale: {
   /**
-   * 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"
    *
@@ -246,17 +254,19 @@ export const scale: {
    * console.log(BigDecimal.format(reduced)) // "123.4"
    * ```
    *
-   * @since 2.0.0
    * @category scaling
+   * @since 2.0.0
    */
   (scale: number): (self: BigDecimal) => BigDecimal
   /**
-   * Scales a given `BigDecimal` to the specified scale.
+   * Scales a `BigDecimal` to the specified scale.
    *
-   * If the given scale is smaller than the current scale, the value will be rounded down to
-   * the nearest integer.
+   * Increasing the scale appends decimal zeros. Decreasing the scale discards
+   * digits beyond the target scale by `bigint` division, which truncates toward
+   * zero.
+   *
+   * **Example** (Scaling decimal precision)
    *
-   * @example
    * ```ts
    * import { BigDecimal } from "effect"
    *
@@ -271,8 +281,8 @@ export const scale: {
    * console.log(BigDecimal.format(reduced)) // "123.4"
    * ```
    *
-   * @since 2.0.0
    * @category scaling
+   * @since 2.0.0
    */
   (self: BigDecimal, scale: number): BigDecimal
 } = dual(2, (self: BigDecimal, scale: number): BigDecimal => {
@@ -290,7 +300,8 @@ export const 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"
@@ -301,14 +312,15 @@ export const scale: {
  * )
  * ```
  *
- * @since 2.0.0
  * @category math
+ * @since 2.0.0
  */
 export const sum: {
   /**
    * Provides an addition operation on `BigDecimal`s.
    *
-   * @example
+   * **Example** (Adding decimals)
+   *
    * ```ts
    * import { fromStringUnsafe, sum } from "effect/BigDecimal"
    * import * as assert from "node:assert"
@@ -319,14 +331,15 @@ export const sum: {
    * )
    * ```
    *
-   * @since 2.0.0
    * @category math
+   * @since 2.0.0
    */
   (that: BigDecimal): (self: BigDecimal) => BigDecimal
   /**
    * Provides an addition operation on `BigDecimal`s.
    *
-   * @example
+   * **Example** (Adding decimals)
+   *
    * ```ts
    * import { fromStringUnsafe, sum } from "effect/BigDecimal"
    * import * as assert from "node:assert"
@@ -337,8 +350,8 @@ export const sum: {
    * )
    * ```
    *
-   * @since 2.0.0
    * @category math
+   * @since 2.0.0
    */
   (self: BigDecimal, that: BigDecimal): BigDecimal
 } = dual(2, (self: BigDecimal, that: BigDecimal): BigDecimal => {
@@ -364,7 +377,8 @@ export const sum: {
 /**
  * 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"
@@ -375,8 +389,8 @@ export const sum: {
  * )
  * ```
  *
- * @since 4.0.0
  * @category math
+ * @since 4.0.0
  */
 export const sumAll = (collection: Iterable<BigDecimal>): BigDecimal => {
   let out: BigDecimal = zero
@@ -389,7 +403,8 @@ export const sumAll = (collection: Iterable<BigDecimal>): BigDecimal => {
 /**
  * Provides a multiplication operation on `BigDecimal`s.
  *
- * @example
+ * **Example** (Multiplying decimals)
+ *
  * ```ts
  * import { fromStringUnsafe, multiply } from "effect/BigDecimal"
  * import * as assert from "node:assert"
@@ -400,14 +415,15 @@ export const sumAll = (collection: Iterable<BigDecimal>): BigDecimal => {
  * )
  * ```
  *
- * @since 2.0.0
  * @category math
+ * @since 2.0.0
  */
 export const multiply: {
   /**
    * Provides a multiplication operation on `BigDecimal`s.
    *
-   * @example
+   * **Example** (Multiplying decimals)
+   *
    * ```ts
    * import { fromStringUnsafe, multiply } from "effect/BigDecimal"
    * import * as assert from "node:assert"
@@ -418,14 +434,15 @@ export const multiply: {
    * )
    * ```
    *
-   * @since 2.0.0
    * @category math
+   * @since 2.0.0
    */
   (that: BigDecimal): (self: BigDecimal) => BigDecimal
   /**
    * Provides a multiplication operation on `BigDecimal`s.
    *
-   * @example
+   * **Example** (Multiplying decimals)
+   *
    * ```ts
    * import { fromStringUnsafe, multiply } from "effect/BigDecimal"
    * import * as assert from "node:assert"
@@ -436,8 +453,8 @@ export const multiply: {
    * )
    * ```
    *
-   * @since 2.0.0
    * @category math
+   * @since 2.0.0
    */
   (self: BigDecimal, that: BigDecimal): BigDecimal
 } = dual(2, (self: BigDecimal, that: BigDecimal): BigDecimal => {
@@ -451,7 +468,8 @@ export const multiply: {
 /**
  * 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"
@@ -462,8 +480,8 @@ export const multiply: {
  * )
  * ```
  *
- * @since 4.0.0
  * @category math
+ * @since 4.0.0
  */
 export const multiplyAll = (collection: Iterable<BigDecimal>): BigDecimal => {
   let out: BigDecimal = one
@@ -479,7 +497,8 @@ export const multiplyAll = (collection: Iterable<BigDecimal>): BigDecimal => {
 /**
  * Provides a subtraction operation on `BigDecimal`s.
  *
- * @example
+ * **Example** (Subtracting decimals)
+ *
  * ```ts
  * import { fromStringUnsafe, subtract } from "effect/BigDecimal"
  * import * as assert from "node:assert"
@@ -490,14 +509,15 @@ export const multiplyAll = (collection: Iterable<BigDecimal>): BigDecimal => {
  * )
  * ```
  *
- * @since 2.0.0
  * @category math
+ * @since 2.0.0
  */
 export const subtract: {
   /**
    * Provides a subtraction operation on `BigDecimal`s.
    *
-   * @example
+   * **Example** (Subtracting decimals)
+   *
    * ```ts
    * import { fromStringUnsafe, subtract } from "effect/BigDecimal"
    * import * as assert from "node:assert"
@@ -508,14 +528,15 @@ export const subtract: {
    * )
    * ```
    *
-   * @since 2.0.0
    * @category math
+   * @since 2.0.0
    */
   (that: BigDecimal): (self: BigDecimal) => BigDecimal
   /**
    * Provides a subtraction operation on `BigDecimal`s.
    *
-   * @example
+   * **Example** (Subtracting decimals)
+   *
    * ```ts
    * import { fromStringUnsafe, subtract } from "effect/BigDecimal"
    * import * as assert from "node:assert"
@@ -526,8 +547,8 @@ export const subtract: {
    * )
    * ```
    *
-   * @since 2.0.0
    * @category math
+   * @since 2.0.0
    */
   (self: BigDecimal, that: BigDecimal): BigDecimal
 } = dual(2, (self: BigDecimal, that: BigDecimal): BigDecimal => {
@@ -621,121 +642,130 @@ export const roundTerminal = (n: bigint): bigint => {
 /**
  * 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: {
   /**
    * 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
    */
   (that: BigDecimal): (self: BigDecimal) => Option.Option<BigDecimal>
   /**
    * 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
    */
   (self: BigDecimal, that: BigDecimal): Option.Option<BigDecimal>
 } = dual(2, (self: BigDecimal, that: BigDecimal): Option.Option<BigDecimal> => {
@@ -758,82 +788,64 @@ export const divide: {
 /**
  * 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: {
   /**
    * 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
    */
   (that: BigDecimal): (self: BigDecimal) => BigDecimal
   /**
    * 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
    */
   (self: BigDecimal, that: BigDecimal): BigDecimal
 } = dual(2, (self: BigDecimal, that: BigDecimal): BigDecimal => {
@@ -855,7 +867,8 @@ export const divideUnsafe: {
 /**
  * Provides an `Order` instance for `BigDecimal` that allows comparing and sorting BigDecimal values.
  *
- * @example
+ * **Example** (Comparing decimals)
+ *
  * ```ts
  * import { BigDecimal } from "effect"
  *
@@ -868,8 +881,8 @@ export const divideUnsafe: {
  * console.log(BigDecimal.Order(a, c)) // 0 (a === c)
  * ```
  *
- * @since 2.0.0
  * @category instances
+ * @since 2.0.0
  */
 export const Order: order.Order<BigDecimal> = order.make((self, that) => {
   const scmp = order.Number(sign(self), sign(that))
@@ -891,7 +904,8 @@ export const Order: order.Order<BigDecimal> = 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"
@@ -910,14 +924,15 @@ export const Order: order.Order<BigDecimal> = order.make((self, that) => {
  * )
  * ```
  *
- * @since 2.0.0
  * @category predicates
+ * @since 2.0.0
  */
 export const isLessThan: {
   /**
    * 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"
@@ -936,14 +951,15 @@ export const isLessThan: {
    * )
    * ```
    *
-   * @since 2.0.0
    * @category predicates
+   * @since 2.0.0
    */
   (that: BigDecimal): (self: BigDecimal) => boolean
   /**
    * 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"
@@ -962,8 +978,8 @@ export const isLessThan: {
    * )
    * ```
    *
-   * @since 2.0.0
    * @category predicates
+   * @since 2.0.0
    */
   (self: BigDecimal, that: BigDecimal): boolean
 } = order.isLessThan(Order)
@@ -971,7 +987,8 @@ export const isLessThan: {
 /**
  * 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"
@@ -990,14 +1007,15 @@ export const isLessThan: {
  * )
  * ```
  *
- * @since 2.0.0
  * @category predicates
+ * @since 2.0.0
  */
 export const isLessThanOrEqualTo: {
   /**
    * 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"
@@ -1016,14 +1034,15 @@ export const isLessThanOrEqualTo: {
    * )
    * ```
    *
-   * @since 2.0.0
    * @category predicates
+   * @since 2.0.0
    */
   (that: BigDecimal): (self: BigDecimal) => boolean
   /**
    * 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"
@@ -1042,8 +1061,8 @@ export const isLessThanOrEqualTo: {
    * )
    * ```
    *
-   * @since 2.0.0
    * @category predicates
+   * @since 2.0.0
    */
   (self: BigDecimal, that: BigDecimal): boolean
 } = order.isLessThanOrEqualTo(Order)
@@ -1051,7 +1070,8 @@ export const isLessThanOrEqualTo: {
 /**
  * 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"
@@ -1070,14 +1090,15 @@ export const isLessThanOrEqualTo: {
  * )
  * ```
  *
- * @since 2.0.0
  * @category predicates
+ * @since 2.0.0
  */
 export const isGreaterThan: {
   /**
    * 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"
@@ -1096,14 +1117,15 @@ export const isGreaterThan: {
    * )
    * ```
    *
-   * @since 2.0.0
    * @category predicates
+   * @since 2.0.0
    */
   (that: BigDecimal): (self: BigDecimal) => boolean
   /**
    * 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"
@@ -1122,8 +1144,8 @@ export const isGreaterThan: {
    * )
    * ```
    *
-   * @since 2.0.0
    * @category predicates
+   * @since 2.0.0
    */
   (self: BigDecimal, that: BigDecimal): boolean
 } = order.isGreaterThan(Order)
@@ -1131,7 +1153,8 @@ export const isGreaterThan: {
 /**
  * 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"
@@ -1150,14 +1173,15 @@ export const isGreaterThan: {
  * )
  * ```
  *
- * @since 2.0.0
  * @category predicates
+ * @since 2.0.0
  */
 export const isGreaterThanOrEqualTo: {
   /**
    * 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"
@@ -1176,14 +1200,15 @@ export const isGreaterThanOrEqualTo: {
    * )
    * ```
    *
-   * @since 2.0.0
    * @category predicates
+   * @since 2.0.0
    */
   (that: BigDecimal): (self: BigDecimal) => boolean
   /**
    * 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"
@@ -1202,8 +1227,8 @@ export const isGreaterThanOrEqualTo: {
    * )
    * ```
    *
-   * @since 2.0.0
    * @category predicates
+   * @since 2.0.0
    */
   (self: BigDecimal, that: BigDecimal): boolean
 } = order.isGreaterThanOrEqualTo(Order)
@@ -1211,7 +1236,8 @@ export const isGreaterThanOrEqualTo: {
 /**
  * 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"
@@ -1226,14 +1252,15 @@ export const isGreaterThanOrEqualTo: {
  * assert.deepStrictEqual(between(BigDecimal.fromStringUnsafe("6")), false)
  * ```
  *
- * @since 2.0.0
  * @category predicates
+ * @since 2.0.0
  */
 export const between: {
   /**
    * 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"
@@ -1248,8 +1275,8 @@ export const between: {
    * assert.deepStrictEqual(between(BigDecimal.fromStringUnsafe("6")), false)
    * ```
    *
-   * @since 2.0.0
    * @category predicates
+   * @since 2.0.0
    */
   (
     options: {
@@ -1260,7 +1287,8 @@ export const between: {
   /**
    * 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"
@@ -1275,8 +1303,8 @@ export const between: {
    * assert.deepStrictEqual(between(BigDecimal.fromStringUnsafe("6")), false)
    * ```
    *
-   * @since 2.0.0
    * @category predicates
+   * @since 2.0.0
    */
   (
     self: BigDecimal,
@@ -1294,7 +1322,8 @@ export const between: {
  * - 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"
@@ -1318,8 +1347,8 @@ export const between: {
  * )
  * ```
  *
- * @since 2.0.0
  * @category math
+ * @since 2.0.0
  */
 export const clamp: {
   /**
@@ -1329,7 +1358,8 @@ export const clamp: {
    * - 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"
@@ -1353,8 +1383,8 @@ export const clamp: {
    * )
    * ```
    *
-   * @since 2.0.0
    * @category math
+   * @since 2.0.0
    */
   (
     options: {
@@ -1369,7 +1399,8 @@ export const clamp: {
    * - 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"
@@ -1393,8 +1424,8 @@ export const clamp: {
    * )
    * ```
    *
-   * @since 2.0.0
    * @category math
+   * @since 2.0.0
    */
   (
     self: BigDecimal,
@@ -1408,7 +1439,8 @@ export const clamp: {
 /**
  * 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"
@@ -1419,14 +1451,15 @@ export const clamp: {
  * )
  * ```
  *
- * @since 2.0.0
  * @category math
+ * @since 2.0.0
  */
 export const min: {
   /**
    * 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"
@@ -1437,14 +1470,15 @@ export const min: {
    * )
    * ```
    *
-   * @since 2.0.0
    * @category math
+   * @since 2.0.0
    */
   (that: BigDecimal): (self: BigDecimal) => BigDecimal
   /**
    * 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"
@@ -1455,8 +1489,8 @@ export const min: {
    * )
    * ```
    *
-   * @since 2.0.0
    * @category math
+   * @since 2.0.0
    */
   (self: BigDecimal, that: BigDecimal): BigDecimal
 } = order.min(Order)
@@ -1464,7 +1498,8 @@ export const min: {
 /**
  * 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"
@@ -1475,14 +1510,15 @@ export const min: {
  * )
  * ```
  *
- * @since 2.0.0
  * @category math
+ * @since 2.0.0
  */
 export const max: {
   /**
    * 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"
@@ -1493,14 +1529,15 @@ export const max: {
    * )
    * ```
    *
-   * @since 2.0.0
    * @category math
+   * @since 2.0.0
    */
   (that: BigDecimal): (self: BigDecimal) => BigDecimal
   /**
    * 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"
@@ -1511,8 +1548,8 @@ export const max: {
    * )
    * ```
    *
-   * @since 2.0.0
    * @category math
+   * @since 2.0.0
    */
   (self: BigDecimal, that: BigDecimal): BigDecimal
 } = order.max(Order)
@@ -1520,7 +1557,8 @@ export const max: {
 /**
  * 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"
@@ -1530,15 +1568,16 @@ export const max: {
  * assert.deepStrictEqual(sign(fromStringUnsafe("5")), 1)
  * ```
  *
- * @since 2.0.0
  * @category math
+ * @since 2.0.0
  */
 export const sign = (n: BigDecimal): Ordering => 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"
@@ -1548,15 +1587,16 @@ export const sign = (n: BigDecimal): Ordering => n.value === bigint0 ? 0 : n.val
  * assert.deepStrictEqual(abs(fromStringUnsafe("5")), fromStringUnsafe("5"))
  * ```
  *
- * @since 2.0.0
  * @category math
+ * @since 2.0.0
  */
 export const abs = (n: BigDecimal): BigDecimal => 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"
@@ -1565,8 +1605,8 @@ export const abs = (n: BigDecimal): BigDecimal => n.value < bigint0 ? make(-n.va
  * assert.deepStrictEqual(negate(fromStringUnsafe("-6")), fromStringUnsafe("6"))
  * ```
  *
- * @since 2.0.0
  * @category math
+ * @since 2.0.0
  */
 export const negate = (n: BigDecimal): BigDecimal => make(-n.value, n.scale)
 
@@ -1575,7 +1615,8 @@ export const negate = (n: BigDecimal): BigDecimal => 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"
@@ -1603,8 +1644,8 @@ export const negate = (n: BigDecimal): BigDecimal => make(-n.value, n.scale)
  * )
  * ```
  *
- * @since 2.0.0
  * @category math
+ * @since 2.0.0
  */
 export const remainder: {
   /**
@@ -1612,7 +1653,8 @@ export const remainder: {
    *
    * 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"
@@ -1640,8 +1682,8 @@ export const remainder: {
    * )
    * ```
    *
-   * @since 2.0.0
    * @category math
+   * @since 2.0.0
    */
   (divisor: BigDecimal): (self: BigDecimal) => Option.Option<BigDecimal>
   /**
@@ -1649,7 +1691,8 @@ export const remainder: {
    *
    * 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"
@@ -1677,8 +1720,8 @@ export const remainder: {
    * )
    * ```
    *
-   * @since 2.0.0
    * @category math
+   * @since 2.0.0
    */
   (self: BigDecimal, divisor: BigDecimal): Option.Option<BigDecimal>
 } = dual(2, (self: BigDecimal, divisor: BigDecimal): Option.Option<BigDecimal> => {
@@ -1695,7 +1738,8 @@ export const remainder: {
  *
  * 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"
@@ -1714,8 +1758,8 @@ export const remainder: {
  * )
  * ```
  *
- * @since 2.0.0
  * @category math
+ * @since 2.0.0
  */
 export const remainderUnsafe: {
   /**
@@ -1723,7 +1767,8 @@ export const remainderUnsafe: {
    *
    * 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"
@@ -1742,8 +1787,8 @@ export const remainderUnsafe: {
    * )
    * ```
    *
-   * @since 2.0.0
    * @category math
+   * @since 2.0.0
    */
   (divisor: BigDecimal): (self: BigDecimal) => BigDecimal
   /**
@@ -1751,7 +1796,8 @@ export const remainderUnsafe: {
    *
    * 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"
@@ -1770,8 +1816,8 @@ export const remainderUnsafe: {
    * )
    * ```
    *
-   * @since 2.0.0
    * @category math
+   * @since 2.0.0
    */
   (self: BigDecimal, divisor: BigDecimal): BigDecimal
 } = dual(2, (self: BigDecimal, divisor: BigDecimal): BigDecimal => {
@@ -1786,13 +1832,14 @@ export const remainderUnsafe: {
 /**
  * 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)
@@ -1816,58 +1863,61 @@ export const Equivalence: Equ.Equivalence<BigDecimal> = 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: {
   /**
    * 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
    */
   (that: BigDecimal): (self: BigDecimal) => boolean
   /**
    * 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
    */
   (self: BigDecimal, that: BigDecimal): boolean
 } = dual(2, (self: BigDecimal, that: BigDecimal): boolean => Equivalence(self, that))
@@ -1875,7 +1925,8 @@ export const equals: {
 /**
  * Creates a `BigDecimal` from a `bigint` value.
  *
- * @example
+ * **Example** (Creating decimals from bigint)
+ *
  * ```ts
  * import { BigDecimal } from "effect"
  *
@@ -1886,8 +1937,8 @@ export const equals: {
  * console.log(BigDecimal.format(largeBigInt)) // "9007199254740991"
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const fromBigInt = (n: bigint): BigDecimal => make(n, 0)
 
@@ -1899,7 +1950,8 @@ export const fromBigInt = (n: bigint): BigDecimal => 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"
@@ -1908,8 +1960,8 @@ export const fromBigInt = (n: bigint): BigDecimal => 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: number): BigDecimal => {
   return Option.getOrThrowWith(fromNumber(n), () => new RangeError(`Number must be finite, got ${n}`))
@@ -1923,7 +1975,8 @@ export const fromNumberUnsafe = (n: number): BigDecimal => {
  *
  * 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"
@@ -1936,8 +1989,8 @@ export const fromNumberUnsafe = (n: number): BigDecimal => {
  * assert.deepStrictEqual(BigDecimal.fromNumber(Infinity), Option.none())
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const fromNumber = (n: number): Option.Option<BigDecimal> => {
   if (!Number.isFinite(n)) {
@@ -1954,9 +2007,14 @@ export const fromNumber = (n: number): Option.Option<BigDecimal> => {
 }
 
 /**
- * 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"
@@ -1969,8 +2027,8 @@ export const fromNumber = (n: number): Option.Option<BigDecimal> => {
  * assert.deepStrictEqual(BigDecimal.fromString("123.abc"), Option.none())
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const fromString = (s: string): Option.Option<BigDecimal> => {
   if (s === "") {
@@ -2018,9 +2076,14 @@ export const fromString = (s: string): Option.Option<BigDecimal> => {
 }
 
 /**
- * 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"
@@ -2030,20 +2093,22 @@ export const fromString = (s: string): Option.Option<BigDecimal> => {
  * assert.throws(() => fromStringUnsafe("123.abc"))
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const fromStringUnsafe = (s: string): BigDecimal => {
   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"
@@ -2053,8 +2118,8 @@ export const fromStringUnsafe = (s: string): BigDecimal => {
  * assert.deepStrictEqual(format(fromStringUnsafe("-0.00000123")), "-0.00000123")
  * ```
  *
- * @since 2.0.0
  * @category conversions
+ * @since 2.0.0
  */
 export const format = (n: BigDecimal): string => {
   const normalized = normalize(n)
@@ -2090,7 +2155,8 @@ export const format = (n: BigDecimal): string => {
 /**
  * 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"
@@ -2098,8 +2164,8 @@ export const format = (n: BigDecimal): string => {
  * assert.deepStrictEqual(toExponential(make(123456n, -5)), "1.23456e+10")
  * ```
  *
- * @since 4.0.0
  * @category conversions
+ * @since 4.0.0
  */
 export const toExponential = (n: BigDecimal): string => {
   if (isZero(n)) {
@@ -2121,11 +2187,14 @@ export const toExponential = (n: BigDecimal): string => {
 }
 
 /**
- * Converts a `BigDecimal` to a `number`.
+ * Converts a `BigDecimal` to a JavaScript `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`.
  *
- * This function will produce incorrect results if the `BigDecimal` exceeds the 64-bit range of a `number`.
+ * **Example** (Converting decimals to numbers)
  *
- * @example
  * ```ts
  * import { fromStringUnsafe, toNumberUnsafe } from "effect/BigDecimal"
  * import * as assert from "node:assert"
@@ -2133,15 +2202,16 @@ export const toExponential = (n: BigDecimal): string => {
  * assert.deepStrictEqual(toNumberUnsafe(fromStringUnsafe("123.456")), 123.456)
  * ```
  *
- * @since 2.0.0
  * @category conversions
+ * @since 2.0.0
  */
 export const toNumberUnsafe = (n: BigDecimal): number => 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"
@@ -2151,15 +2221,16 @@ export const toNumberUnsafe = (n: BigDecimal): number => Number(format(n))
  * assert.deepStrictEqual(isInteger(fromStringUnsafe("1.1")), false)
  * ```
  *
- * @since 2.0.0
  * @category predicates
+ * @since 2.0.0
  */
 export const isInteger = (n: BigDecimal): boolean => 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"
@@ -2168,15 +2239,16 @@ export const isInteger = (n: BigDecimal): boolean => normalize(n).scale <= 0
  * assert.deepStrictEqual(isZero(fromStringUnsafe("1")), false)
  * ```
  *
- * @since 2.0.0
  * @category predicates
+ * @since 2.0.0
  */
 export const isZero = (n: BigDecimal): boolean => 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"
@@ -2186,15 +2258,16 @@ export const isZero = (n: BigDecimal): boolean => n.value === bigint0
  * assert.deepStrictEqual(isNegative(fromStringUnsafe("1")), false)
  * ```
  *
- * @since 2.0.0
  * @category predicates
+ * @since 2.0.0
  */
 export const isNegative = (n: BigDecimal): boolean => 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"
@@ -2204,8 +2277,8 @@ export const isNegative = (n: BigDecimal): boolean => n.value < bigint0
  * assert.deepStrictEqual(isPositive(fromStringUnsafe("1")), true)
  * ```
  *
- * @since 2.0.0
  * @category predicates
+ * @since 2.0.0
  */
 export const isPositive = (n: BigDecimal): boolean => n.value > bigint0
 
@@ -2225,8 +2298,8 @@ 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
  *
- * @since 4.0.0
  * @category math
+ * @since 4.0.0
  */
 export type RoundingMode =
   | "ceil"
@@ -2243,7 +2316,8 @@ export type RoundingMode =
 /**
  * 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"
@@ -2258,14 +2332,15 @@ export type RoundingMode =
  * )
  * ```
  *
- * @since 4.0.0
  * @category math
+ * @since 4.0.0
  */
 export const round: {
   /**
    * 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"
@@ -2280,14 +2355,15 @@ export const round: {
    * )
    * ```
    *
-   * @since 4.0.0
    * @category math
+   * @since 4.0.0
    */
   (options: { scale?: number; mode?: RoundingMode }): (self: BigDecimal) => BigDecimal
   /**
    * 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"
@@ -2302,8 +2378,8 @@ export const round: {
    * )
    * ```
    *
-   * @since 4.0.0
    * @category math
+   * @since 4.0.0
    */
   (n: BigDecimal, options?: { scale?: number; mode?: RoundingMode }): BigDecimal
 } = dual(isBigDecimalArgs, (self: BigDecimal, options?: { scale?: number; mode?: RoundingMode }): BigDecimal => {
@@ -2354,69 +2430,54 @@ export const round: {
 })
 
 /**
- * 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: {
   /**
-   * 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
    */
   (scale: number): (self: BigDecimal) => BigDecimal
   /**
-   * 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
    */
   (self: BigDecimal, scale?: number): BigDecimal
 } = dual(isBigDecimalArgs, (self: BigDecimal, scale: number = 0): BigDecimal => {
@@ -2431,7 +2492,8 @@ export const truncate: {
 /**
  * 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"
@@ -2443,14 +2505,15 @@ export const truncate: {
  * assert.deepStrictEqual(ceil(fromStringUnsafe("-14.5")), fromStringUnsafe("-14"))
  * ```
  *
- * @since 4.0.0
  * @category math
+ * @since 4.0.0
  */
 export const ceil: {
   /**
    * 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"
@@ -2462,14 +2525,15 @@ export const ceil: {
    * assert.deepStrictEqual(ceil(fromStringUnsafe("-14.5")), fromStringUnsafe("-14"))
    * ```
    *
-   * @since 4.0.0
    * @category math
+   * @since 4.0.0
    */
   (scale: number): (self: BigDecimal) => BigDecimal
   /**
    * 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"
@@ -2481,8 +2545,8 @@ export const ceil: {
    * assert.deepStrictEqual(ceil(fromStringUnsafe("-14.5")), fromStringUnsafe("-14"))
    * ```
    *
-   * @since 4.0.0
    * @category math
+   * @since 4.0.0
    */
   (self: BigDecimal, scale?: number): BigDecimal
 } = dual(isBigDecimalArgs, (self: BigDecimal, scale: number = 0): BigDecimal => {
@@ -2531,7 +2595,8 @@ export const digitAt: {
 /**
  * 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"
@@ -2546,14 +2611,15 @@ export const digitAt: {
  * )
  * ```
  *
- * @since 4.0.0
  * @category math
+ * @since 4.0.0
  */
 export const floor: {
   /**
    * 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"
@@ -2568,14 +2634,15 @@ export const floor: {
    * )
    * ```
    *
-   * @since 4.0.0
    * @category math
+   * @since 4.0.0
    */
   (scale: number): (self: BigDecimal) => BigDecimal
   /**
    * 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"
@@ -2590,8 +2657,8 @@ export const floor: {
    * )
    * ```
    *
-   * @since 4.0.0
    * @category math
+   * @since 4.0.0
    */
   (self: BigDecimal, scale?: number): BigDecimal
 } = dual(isBigDecimalArgs, (self: BigDecimal, scale: number = 0): BigDecimal => {