effect 4.0.0-beta.66 → 4.0.0-beta.68

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,23 +156,24 @@ 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 { BigDecimal } from "effect"
  * import * as assert from "node:assert"
  *
  * assert.deepStrictEqual(
- *   normalize(fromStringUnsafe("123.00000")),
- *   normalize(make(123n, 0))
+ *   BigDecimal.normalize(BigDecimal.fromStringUnsafe("123.00000")),
+ *   BigDecimal.normalize(BigDecimal.make(123n, 0))
  * )
  * assert.deepStrictEqual(
- *   normalize(fromStringUnsafe("12300000")),
- *   normalize(make(123n, -5))
+ *   BigDecimal.normalize(BigDecimal.fromStringUnsafe("12300000")),
+ *   BigDecimal.normalize(BigDecimal.make(123n, -5))
  * )
  * ```
  *
- * @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.
+   *
+   * 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"
    *
@@ -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,55 +300,58 @@ export const scale: {
 /**
  * Provides an addition operation on `BigDecimal`s.
  *
- * @example
+ * **Example** (Adding decimals)
+ *
  * ```ts
- * import { fromStringUnsafe, sum } from "effect/BigDecimal"
+ * import { BigDecimal } from "effect"
  * import * as assert from "node:assert"
  *
  * assert.deepStrictEqual(
- *   sum(fromStringUnsafe("2"), fromStringUnsafe("3")),
- *   fromStringUnsafe("5")
+ *   BigDecimal.sum(BigDecimal.fromStringUnsafe("2"), BigDecimal.fromStringUnsafe("3")),
+ *   BigDecimal.fromStringUnsafe("5")
  * )
  * ```
  *
- * @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 { BigDecimal } from "effect"
    * import * as assert from "node:assert"
    *
    * assert.deepStrictEqual(
-   *   sum(fromStringUnsafe("2"), fromStringUnsafe("3")),
-   *   fromStringUnsafe("5")
+   *   BigDecimal.sum(BigDecimal.fromStringUnsafe("2"), BigDecimal.fromStringUnsafe("3")),
+   *   BigDecimal.fromStringUnsafe("5")
    * )
    * ```
    *
-   * @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 { BigDecimal } from "effect"
    * import * as assert from "node:assert"
    *
    * assert.deepStrictEqual(
-   *   sum(fromStringUnsafe("2"), fromStringUnsafe("3")),
-   *   fromStringUnsafe("5")
+   *   BigDecimal.sum(BigDecimal.fromStringUnsafe("2"), BigDecimal.fromStringUnsafe("3")),
+   *   BigDecimal.fromStringUnsafe("5")
    * )
    * ```
    *
-   * @since 2.0.0
    * @category math
+   * @since 2.0.0
    */
   (self: BigDecimal, that: BigDecimal): BigDecimal
 } = dual(2, (self: BigDecimal, that: BigDecimal): BigDecimal => {
@@ -364,19 +377,20 @@ 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 { BigDecimal } from "effect"
  * import * as assert from "node:assert"
  *
  * assert.deepStrictEqual(
- *   sumAll([fromStringUnsafe("2"), fromStringUnsafe("3"), fromStringUnsafe("4")]),
- *   fromStringUnsafe("9")
+ *   BigDecimal.sumAll([BigDecimal.fromStringUnsafe("2"), BigDecimal.fromStringUnsafe("3"), BigDecimal.fromStringUnsafe("4")]),
+ *   BigDecimal.fromStringUnsafe("9")
  * )
  * ```
  *
- * @since 4.0.0
  * @category math
+ * @since 3.16.0
  */
 export const sumAll = (collection: Iterable<BigDecimal>): BigDecimal => {
   let out: BigDecimal = zero
@@ -389,55 +403,58 @@ 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 { BigDecimal } from "effect"
  * import * as assert from "node:assert"
  *
  * assert.deepStrictEqual(
- *   multiply(fromStringUnsafe("2"), fromStringUnsafe("3")),
- *   fromStringUnsafe("6")
+ *   BigDecimal.multiply(BigDecimal.fromStringUnsafe("2"), BigDecimal.fromStringUnsafe("3")),
+ *   BigDecimal.fromStringUnsafe("6")
  * )
  * ```
  *
- * @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 { BigDecimal } from "effect"
    * import * as assert from "node:assert"
    *
    * assert.deepStrictEqual(
-   *   multiply(fromStringUnsafe("2"), fromStringUnsafe("3")),
-   *   fromStringUnsafe("6")
+   *   BigDecimal.multiply(BigDecimal.fromStringUnsafe("2"), BigDecimal.fromStringUnsafe("3")),
+   *   BigDecimal.fromStringUnsafe("6")
    * )
    * ```
    *
-   * @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 { BigDecimal } from "effect"
    * import * as assert from "node:assert"
    *
    * assert.deepStrictEqual(
-   *   multiply(fromStringUnsafe("2"), fromStringUnsafe("3")),
-   *   fromStringUnsafe("6")
+   *   BigDecimal.multiply(BigDecimal.fromStringUnsafe("2"), BigDecimal.fromStringUnsafe("3")),
+   *   BigDecimal.fromStringUnsafe("6")
    * )
    * ```
    *
-   * @since 2.0.0
    * @category math
+   * @since 2.0.0
    */
   (self: BigDecimal, that: BigDecimal): BigDecimal
 } = dual(2, (self: BigDecimal, that: BigDecimal): BigDecimal => {
@@ -451,19 +468,20 @@ 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 { BigDecimal } from "effect"
  * import * as assert from "node:assert"
  *
  * assert.deepStrictEqual(
- *   multiplyAll([fromStringUnsafe("2"), fromStringUnsafe("3"), fromStringUnsafe("4")]),
- *   fromStringUnsafe("24")
+ *   BigDecimal.multiplyAll([BigDecimal.fromStringUnsafe("2"), BigDecimal.fromStringUnsafe("3"), BigDecimal.fromStringUnsafe("4")]),
+ *   BigDecimal.fromStringUnsafe("24")
  * )
  * ```
  *
- * @since 4.0.0
  * @category math
+ * @since 4.0.0
  */
 export const multiplyAll = (collection: Iterable<BigDecimal>): BigDecimal => {
   let out: BigDecimal = one
@@ -479,55 +497,58 @@ 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 { BigDecimal } from "effect"
  * import * as assert from "node:assert"
  *
  * assert.deepStrictEqual(
- *   subtract(fromStringUnsafe("2"), fromStringUnsafe("3")),
- *   fromStringUnsafe("-1")
+ *   BigDecimal.subtract(BigDecimal.fromStringUnsafe("2"), BigDecimal.fromStringUnsafe("3")),
+ *   BigDecimal.fromStringUnsafe("-1")
  * )
  * ```
  *
- * @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 { BigDecimal } from "effect"
    * import * as assert from "node:assert"
    *
    * assert.deepStrictEqual(
-   *   subtract(fromStringUnsafe("2"), fromStringUnsafe("3")),
-   *   fromStringUnsafe("-1")
+   *   BigDecimal.subtract(BigDecimal.fromStringUnsafe("2"), BigDecimal.fromStringUnsafe("3")),
+   *   BigDecimal.fromStringUnsafe("-1")
    * )
    * ```
    *
-   * @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 { BigDecimal } from "effect"
    * import * as assert from "node:assert"
    *
    * assert.deepStrictEqual(
-   *   subtract(fromStringUnsafe("2"), fromStringUnsafe("3")),
-   *   fromStringUnsafe("-1")
+   *   BigDecimal.subtract(BigDecimal.fromStringUnsafe("2"), BigDecimal.fromStringUnsafe("3")),
+   *   BigDecimal.fromStringUnsafe("-1")
    * )
    * ```
    *
-   * @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"
+ * import { BigDecimal } from "effect"
  *
- * assert.deepStrictEqual(
- *   divideUnsafe(fromStringUnsafe("6"), fromStringUnsafe("3")),
- *   fromStringUnsafe("2")
- * )
- * assert.deepStrictEqual(
- *   divideUnsafe(fromStringUnsafe("6"), fromStringUnsafe("4")),
- *   fromStringUnsafe("1.5")
- * )
+ * console.log(BigDecimal.divideUnsafe(BigDecimal.fromStringUnsafe("6"), BigDecimal.fromStringUnsafe("3"))) // BigDecimal(2)
+ * console.log(BigDecimal.divideUnsafe(BigDecimal.fromStringUnsafe("6"), BigDecimal.fromStringUnsafe("4"))) // BigDecimal(1.5)
  * ```
  *
- * @since 2.0.0
  * @category math
+ * @since 4.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"
+   * import { BigDecimal } from "effect"
    *
-   * assert.deepStrictEqual(
-   *   divideUnsafe(fromStringUnsafe("6"), fromStringUnsafe("3")),
-   *   fromStringUnsafe("2")
-   * )
-   * assert.deepStrictEqual(
-   *   divideUnsafe(fromStringUnsafe("6"), fromStringUnsafe("4")),
-   *   fromStringUnsafe("1.5")
-   * )
+   * console.log(BigDecimal.divideUnsafe(BigDecimal.fromStringUnsafe("6"), BigDecimal.fromStringUnsafe("3"))) // BigDecimal(2)
+   * console.log(BigDecimal.divideUnsafe(BigDecimal.fromStringUnsafe("6"), BigDecimal.fromStringUnsafe("4"))) // BigDecimal(1.5)
    * ```
    *
-   * @since 2.0.0
    * @category math
+   * @since 4.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"
+   * import { BigDecimal } from "effect"
    *
-   * assert.deepStrictEqual(
-   *   divideUnsafe(fromStringUnsafe("6"), fromStringUnsafe("3")),
-   *   fromStringUnsafe("2")
-   * )
-   * assert.deepStrictEqual(
-   *   divideUnsafe(fromStringUnsafe("6"), fromStringUnsafe("4")),
-   *   fromStringUnsafe("1.5")
-   * )
+   * console.log(BigDecimal.divideUnsafe(BigDecimal.fromStringUnsafe("6"), BigDecimal.fromStringUnsafe("3"))) // BigDecimal(2)
+   * console.log(BigDecimal.divideUnsafe(BigDecimal.fromStringUnsafe("6"), BigDecimal.fromStringUnsafe("4"))) // BigDecimal(1.5)
    * ```
    *
-   * @since 2.0.0
    * @category math
+   * @since 4.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,79 +904,82 @@ 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 { BigDecimal } from "effect"
  * import * as assert from "node:assert"
  *
  * assert.deepStrictEqual(
- *   isLessThan(fromStringUnsafe("2"), fromStringUnsafe("3")),
+ *   BigDecimal.isLessThan(BigDecimal.fromStringUnsafe("2"), BigDecimal.fromStringUnsafe("3")),
  *   true
  * )
  * assert.deepStrictEqual(
- *   isLessThan(fromStringUnsafe("3"), fromStringUnsafe("3")),
+ *   BigDecimal.isLessThan(BigDecimal.fromStringUnsafe("3"), BigDecimal.fromStringUnsafe("3")),
  *   false
  * )
  * assert.deepStrictEqual(
- *   isLessThan(fromStringUnsafe("4"), fromStringUnsafe("3")),
+ *   BigDecimal.isLessThan(BigDecimal.fromStringUnsafe("4"), BigDecimal.fromStringUnsafe("3")),
  *   false
  * )
  * ```
  *
- * @since 2.0.0
  * @category predicates
+ * @since 4.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 { BigDecimal } from "effect"
    * import * as assert from "node:assert"
    *
    * assert.deepStrictEqual(
-   *   isLessThan(fromStringUnsafe("2"), fromStringUnsafe("3")),
+   *   BigDecimal.isLessThan(BigDecimal.fromStringUnsafe("2"), BigDecimal.fromStringUnsafe("3")),
    *   true
    * )
    * assert.deepStrictEqual(
-   *   isLessThan(fromStringUnsafe("3"), fromStringUnsafe("3")),
+   *   BigDecimal.isLessThan(BigDecimal.fromStringUnsafe("3"), BigDecimal.fromStringUnsafe("3")),
    *   false
    * )
    * assert.deepStrictEqual(
-   *   isLessThan(fromStringUnsafe("4"), fromStringUnsafe("3")),
+   *   BigDecimal.isLessThan(BigDecimal.fromStringUnsafe("4"), BigDecimal.fromStringUnsafe("3")),
    *   false
    * )
    * ```
    *
-   * @since 2.0.0
    * @category predicates
+   * @since 4.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 { BigDecimal } from "effect"
    * import * as assert from "node:assert"
    *
    * assert.deepStrictEqual(
-   *   isLessThan(fromStringUnsafe("2"), fromStringUnsafe("3")),
+   *   BigDecimal.isLessThan(BigDecimal.fromStringUnsafe("2"), BigDecimal.fromStringUnsafe("3")),
    *   true
    * )
    * assert.deepStrictEqual(
-   *   isLessThan(fromStringUnsafe("3"), fromStringUnsafe("3")),
+   *   BigDecimal.isLessThan(BigDecimal.fromStringUnsafe("3"), BigDecimal.fromStringUnsafe("3")),
    *   false
    * )
    * assert.deepStrictEqual(
-   *   isLessThan(fromStringUnsafe("4"), fromStringUnsafe("3")),
+   *   BigDecimal.isLessThan(BigDecimal.fromStringUnsafe("4"), BigDecimal.fromStringUnsafe("3")),
    *   false
    * )
    * ```
    *
-   * @since 2.0.0
    * @category predicates
+   * @since 4.0.0
    */
   (self: BigDecimal, that: BigDecimal): boolean
 } = order.isLessThan(Order)
@@ -971,79 +987,82 @@ 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 { BigDecimal } from "effect"
  * import * as assert from "node:assert"
  *
  * assert.deepStrictEqual(
- *   isLessThanOrEqualTo(fromStringUnsafe("2"), fromStringUnsafe("3")),
+ *   BigDecimal.isLessThanOrEqualTo(BigDecimal.fromStringUnsafe("2"), BigDecimal.fromStringUnsafe("3")),
  *   true
  * )
  * assert.deepStrictEqual(
- *   isLessThanOrEqualTo(fromStringUnsafe("3"), fromStringUnsafe("3")),
+ *   BigDecimal.isLessThanOrEqualTo(BigDecimal.fromStringUnsafe("3"), BigDecimal.fromStringUnsafe("3")),
  *   true
  * )
  * assert.deepStrictEqual(
- *   isLessThanOrEqualTo(fromStringUnsafe("4"), fromStringUnsafe("3")),
+ *   BigDecimal.isLessThanOrEqualTo(BigDecimal.fromStringUnsafe("4"), BigDecimal.fromStringUnsafe("3")),
  *   false
  * )
  * ```
  *
- * @since 2.0.0
  * @category predicates
+ * @since 4.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 { BigDecimal } from "effect"
    * import * as assert from "node:assert"
    *
    * assert.deepStrictEqual(
-   *   isLessThanOrEqualTo(fromStringUnsafe("2"), fromStringUnsafe("3")),
+   *   BigDecimal.isLessThanOrEqualTo(BigDecimal.fromStringUnsafe("2"), BigDecimal.fromStringUnsafe("3")),
    *   true
    * )
    * assert.deepStrictEqual(
-   *   isLessThanOrEqualTo(fromStringUnsafe("3"), fromStringUnsafe("3")),
+   *   BigDecimal.isLessThanOrEqualTo(BigDecimal.fromStringUnsafe("3"), BigDecimal.fromStringUnsafe("3")),
    *   true
    * )
    * assert.deepStrictEqual(
-   *   isLessThanOrEqualTo(fromStringUnsafe("4"), fromStringUnsafe("3")),
+   *   BigDecimal.isLessThanOrEqualTo(BigDecimal.fromStringUnsafe("4"), BigDecimal.fromStringUnsafe("3")),
    *   false
    * )
    * ```
    *
-   * @since 2.0.0
    * @category predicates
+   * @since 4.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 { BigDecimal } from "effect"
    * import * as assert from "node:assert"
    *
    * assert.deepStrictEqual(
-   *   isLessThanOrEqualTo(fromStringUnsafe("2"), fromStringUnsafe("3")),
+   *   BigDecimal.isLessThanOrEqualTo(BigDecimal.fromStringUnsafe("2"), BigDecimal.fromStringUnsafe("3")),
    *   true
    * )
    * assert.deepStrictEqual(
-   *   isLessThanOrEqualTo(fromStringUnsafe("3"), fromStringUnsafe("3")),
+   *   BigDecimal.isLessThanOrEqualTo(BigDecimal.fromStringUnsafe("3"), BigDecimal.fromStringUnsafe("3")),
    *   true
    * )
    * assert.deepStrictEqual(
-   *   isLessThanOrEqualTo(fromStringUnsafe("4"), fromStringUnsafe("3")),
+   *   BigDecimal.isLessThanOrEqualTo(BigDecimal.fromStringUnsafe("4"), BigDecimal.fromStringUnsafe("3")),
    *   false
    * )
    * ```
    *
-   * @since 2.0.0
    * @category predicates
+   * @since 4.0.0
    */
   (self: BigDecimal, that: BigDecimal): boolean
 } = order.isLessThanOrEqualTo(Order)
@@ -1051,79 +1070,82 @@ 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 { BigDecimal } from "effect"
  * import * as assert from "node:assert"
  *
  * assert.deepStrictEqual(
- *   isGreaterThan(fromStringUnsafe("2"), fromStringUnsafe("3")),
+ *   BigDecimal.isGreaterThan(BigDecimal.fromStringUnsafe("2"), BigDecimal.fromStringUnsafe("3")),
  *   false
  * )
  * assert.deepStrictEqual(
- *   isGreaterThan(fromStringUnsafe("3"), fromStringUnsafe("3")),
+ *   BigDecimal.isGreaterThan(BigDecimal.fromStringUnsafe("3"), BigDecimal.fromStringUnsafe("3")),
  *   false
  * )
  * assert.deepStrictEqual(
- *   isGreaterThan(fromStringUnsafe("4"), fromStringUnsafe("3")),
+ *   BigDecimal.isGreaterThan(BigDecimal.fromStringUnsafe("4"), BigDecimal.fromStringUnsafe("3")),
  *   true
  * )
  * ```
  *
- * @since 2.0.0
  * @category predicates
+ * @since 4.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 { BigDecimal } from "effect"
    * import * as assert from "node:assert"
    *
    * assert.deepStrictEqual(
-   *   isGreaterThan(fromStringUnsafe("2"), fromStringUnsafe("3")),
+   *   BigDecimal.isGreaterThan(BigDecimal.fromStringUnsafe("2"), BigDecimal.fromStringUnsafe("3")),
    *   false
    * )
    * assert.deepStrictEqual(
-   *   isGreaterThan(fromStringUnsafe("3"), fromStringUnsafe("3")),
+   *   BigDecimal.isGreaterThan(BigDecimal.fromStringUnsafe("3"), BigDecimal.fromStringUnsafe("3")),
    *   false
    * )
    * assert.deepStrictEqual(
-   *   isGreaterThan(fromStringUnsafe("4"), fromStringUnsafe("3")),
+   *   BigDecimal.isGreaterThan(BigDecimal.fromStringUnsafe("4"), BigDecimal.fromStringUnsafe("3")),
    *   true
    * )
    * ```
    *
-   * @since 2.0.0
    * @category predicates
+   * @since 4.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 { BigDecimal } from "effect"
    * import * as assert from "node:assert"
    *
    * assert.deepStrictEqual(
-   *   isGreaterThan(fromStringUnsafe("2"), fromStringUnsafe("3")),
+   *   BigDecimal.isGreaterThan(BigDecimal.fromStringUnsafe("2"), BigDecimal.fromStringUnsafe("3")),
    *   false
    * )
    * assert.deepStrictEqual(
-   *   isGreaterThan(fromStringUnsafe("3"), fromStringUnsafe("3")),
+   *   BigDecimal.isGreaterThan(BigDecimal.fromStringUnsafe("3"), BigDecimal.fromStringUnsafe("3")),
    *   false
    * )
    * assert.deepStrictEqual(
-   *   isGreaterThan(fromStringUnsafe("4"), fromStringUnsafe("3")),
+   *   BigDecimal.isGreaterThan(BigDecimal.fromStringUnsafe("4"), BigDecimal.fromStringUnsafe("3")),
    *   true
    * )
    * ```
    *
-   * @since 2.0.0
    * @category predicates
+   * @since 4.0.0
    */
   (self: BigDecimal, that: BigDecimal): boolean
 } = order.isGreaterThan(Order)
@@ -1131,79 +1153,82 @@ 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 { BigDecimal } from "effect"
  * import * as assert from "node:assert"
  *
  * assert.deepStrictEqual(
- *   isGreaterThanOrEqualTo(fromStringUnsafe("2"), fromStringUnsafe("3")),
+ *   BigDecimal.isGreaterThanOrEqualTo(BigDecimal.fromStringUnsafe("2"), BigDecimal.fromStringUnsafe("3")),
  *   false
  * )
  * assert.deepStrictEqual(
- *   isGreaterThanOrEqualTo(fromStringUnsafe("3"), fromStringUnsafe("3")),
+ *   BigDecimal.isGreaterThanOrEqualTo(BigDecimal.fromStringUnsafe("3"), BigDecimal.fromStringUnsafe("3")),
  *   true
  * )
  * assert.deepStrictEqual(
- *   isGreaterThanOrEqualTo(fromStringUnsafe("4"), fromStringUnsafe("3")),
+ *   BigDecimal.isGreaterThanOrEqualTo(BigDecimal.fromStringUnsafe("4"), BigDecimal.fromStringUnsafe("3")),
  *   true
  * )
  * ```
  *
- * @since 2.0.0
  * @category predicates
+ * @since 4.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 { BigDecimal } from "effect"
    * import * as assert from "node:assert"
    *
    * assert.deepStrictEqual(
-   *   isGreaterThanOrEqualTo(fromStringUnsafe("2"), fromStringUnsafe("3")),
+   *   BigDecimal.isGreaterThanOrEqualTo(BigDecimal.fromStringUnsafe("2"), BigDecimal.fromStringUnsafe("3")),
    *   false
    * )
    * assert.deepStrictEqual(
-   *   isGreaterThanOrEqualTo(fromStringUnsafe("3"), fromStringUnsafe("3")),
+   *   BigDecimal.isGreaterThanOrEqualTo(BigDecimal.fromStringUnsafe("3"), BigDecimal.fromStringUnsafe("3")),
    *   true
    * )
    * assert.deepStrictEqual(
-   *   isGreaterThanOrEqualTo(fromStringUnsafe("4"), fromStringUnsafe("3")),
+   *   BigDecimal.isGreaterThanOrEqualTo(BigDecimal.fromStringUnsafe("4"), BigDecimal.fromStringUnsafe("3")),
    *   true
    * )
    * ```
    *
-   * @since 2.0.0
    * @category predicates
+   * @since 4.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 { BigDecimal } from "effect"
    * import * as assert from "node:assert"
    *
    * assert.deepStrictEqual(
-   *   isGreaterThanOrEqualTo(fromStringUnsafe("2"), fromStringUnsafe("3")),
+   *   BigDecimal.isGreaterThanOrEqualTo(BigDecimal.fromStringUnsafe("2"), BigDecimal.fromStringUnsafe("3")),
    *   false
    * )
    * assert.deepStrictEqual(
-   *   isGreaterThanOrEqualTo(fromStringUnsafe("3"), fromStringUnsafe("3")),
+   *   BigDecimal.isGreaterThanOrEqualTo(BigDecimal.fromStringUnsafe("3"), BigDecimal.fromStringUnsafe("3")),
    *   true
    * )
    * assert.deepStrictEqual(
-   *   isGreaterThanOrEqualTo(fromStringUnsafe("4"), fromStringUnsafe("3")),
+   *   BigDecimal.isGreaterThanOrEqualTo(BigDecimal.fromStringUnsafe("4"), BigDecimal.fromStringUnsafe("3")),
    *   true
    * )
    * ```
    *
-   * @since 2.0.0
    * @category predicates
+   * @since 4.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,55 +1439,58 @@ export const clamp: {
 /**
  * Returns the minimum between two `BigDecimal`s.
  *
- * @example
+ * **Example** (Selecting the smaller decimal)
+ *
  * ```ts
- * import { fromStringUnsafe, min } from "effect/BigDecimal"
+ * import { BigDecimal } from "effect"
  * import * as assert from "node:assert"
  *
  * assert.deepStrictEqual(
- *   min(fromStringUnsafe("2"), fromStringUnsafe("3")),
- *   fromStringUnsafe("2")
+ *   BigDecimal.min(BigDecimal.fromStringUnsafe("2"), BigDecimal.fromStringUnsafe("3")),
+ *   BigDecimal.fromStringUnsafe("2")
  * )
  * ```
  *
- * @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 { BigDecimal } from "effect"
    * import * as assert from "node:assert"
    *
    * assert.deepStrictEqual(
-   *   min(fromStringUnsafe("2"), fromStringUnsafe("3")),
-   *   fromStringUnsafe("2")
+   *   BigDecimal.min(BigDecimal.fromStringUnsafe("2"), BigDecimal.fromStringUnsafe("3")),
+   *   BigDecimal.fromStringUnsafe("2")
    * )
    * ```
    *
-   * @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 { BigDecimal } from "effect"
    * import * as assert from "node:assert"
    *
    * assert.deepStrictEqual(
-   *   min(fromStringUnsafe("2"), fromStringUnsafe("3")),
-   *   fromStringUnsafe("2")
+   *   BigDecimal.min(BigDecimal.fromStringUnsafe("2"), BigDecimal.fromStringUnsafe("3")),
+   *   BigDecimal.fromStringUnsafe("2")
    * )
    * ```
    *
-   * @since 2.0.0
    * @category math
+   * @since 2.0.0
    */
   (self: BigDecimal, that: BigDecimal): BigDecimal
 } = order.min(Order)
@@ -1464,55 +1498,58 @@ export const min: {
 /**
  * Returns the maximum between two `BigDecimal`s.
  *
- * @example
+ * **Example** (Selecting the larger decimal)
+ *
  * ```ts
- * import { fromStringUnsafe, max } from "effect/BigDecimal"
+ * import { BigDecimal } from "effect"
  * import * as assert from "node:assert"
  *
  * assert.deepStrictEqual(
- *   max(fromStringUnsafe("2"), fromStringUnsafe("3")),
- *   fromStringUnsafe("3")
+ *   BigDecimal.max(BigDecimal.fromStringUnsafe("2"), BigDecimal.fromStringUnsafe("3")),
+ *   BigDecimal.fromStringUnsafe("3")
  * )
  * ```
  *
- * @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 { BigDecimal } from "effect"
    * import * as assert from "node:assert"
    *
    * assert.deepStrictEqual(
-   *   max(fromStringUnsafe("2"), fromStringUnsafe("3")),
-   *   fromStringUnsafe("3")
+   *   BigDecimal.max(BigDecimal.fromStringUnsafe("2"), BigDecimal.fromStringUnsafe("3")),
+   *   BigDecimal.fromStringUnsafe("3")
    * )
    * ```
    *
-   * @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 { BigDecimal } from "effect"
    * import * as assert from "node:assert"
    *
    * assert.deepStrictEqual(
-   *   max(fromStringUnsafe("2"), fromStringUnsafe("3")),
-   *   fromStringUnsafe("3")
+   *   BigDecimal.max(BigDecimal.fromStringUnsafe("2"), BigDecimal.fromStringUnsafe("3")),
+   *   BigDecimal.fromStringUnsafe("3")
    * )
    * ```
    *
-   * @since 2.0.0
    * @category math
+   * @since 2.0.0
    */
   (self: BigDecimal, that: BigDecimal): BigDecimal
 } = order.max(Order)
@@ -1520,53 +1557,56 @@ export const max: {
 /**
  * Determines the sign of a given `BigDecimal`.
  *
- * @example
+ * **Example** (Reading decimal signs)
+ *
  * ```ts
- * import { fromStringUnsafe, sign } from "effect/BigDecimal"
+ * import { BigDecimal } from "effect"
  * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(sign(fromStringUnsafe("-5")), -1)
- * assert.deepStrictEqual(sign(fromStringUnsafe("0")), 0)
- * assert.deepStrictEqual(sign(fromStringUnsafe("5")), 1)
+ * assert.deepStrictEqual(BigDecimal.sign(BigDecimal.fromStringUnsafe("-5")), -1)
+ * assert.deepStrictEqual(BigDecimal.sign(BigDecimal.fromStringUnsafe("0")), 0)
+ * assert.deepStrictEqual(BigDecimal.sign(BigDecimal.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 { BigDecimal } from "effect"
  * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(abs(fromStringUnsafe("-5")), fromStringUnsafe("5"))
- * assert.deepStrictEqual(abs(fromStringUnsafe("0")), fromStringUnsafe("0"))
- * assert.deepStrictEqual(abs(fromStringUnsafe("5")), fromStringUnsafe("5"))
+ * assert.deepStrictEqual(BigDecimal.abs(BigDecimal.fromStringUnsafe("-5")), BigDecimal.fromStringUnsafe("5"))
+ * assert.deepStrictEqual(BigDecimal.abs(BigDecimal.fromStringUnsafe("0")), BigDecimal.fromStringUnsafe("0"))
+ * assert.deepStrictEqual(BigDecimal.abs(BigDecimal.fromStringUnsafe("5")), BigDecimal.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 { BigDecimal } from "effect"
  * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(negate(fromStringUnsafe("3")), fromStringUnsafe("-3"))
- * assert.deepStrictEqual(negate(fromStringUnsafe("-6")), fromStringUnsafe("6"))
+ * assert.deepStrictEqual(BigDecimal.negate(BigDecimal.fromStringUnsafe("3")), BigDecimal.fromStringUnsafe("-3"))
+ * assert.deepStrictEqual(BigDecimal.negate(BigDecimal.fromStringUnsafe("-6")), BigDecimal.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,27 +1738,28 @@ export const remainder: {
  *
  * Throws a `RangeError` if the divisor is `0`.
  *
- * @example
+ * **Example** (Computing remainders unsafely)
+ *
  * ```ts
- * import { fromStringUnsafe, remainderUnsafe } from "effect/BigDecimal"
+ * import { BigDecimal } from "effect"
  * import * as assert from "node:assert"
  *
  * assert.deepStrictEqual(
- *   remainderUnsafe(fromStringUnsafe("2"), fromStringUnsafe("2")),
- *   fromStringUnsafe("0")
+ *   BigDecimal.remainderUnsafe(BigDecimal.fromStringUnsafe("2"), BigDecimal.fromStringUnsafe("2")),
+ *   BigDecimal.fromStringUnsafe("0")
  * )
  * assert.deepStrictEqual(
- *   remainderUnsafe(fromStringUnsafe("3"), fromStringUnsafe("2")),
- *   fromStringUnsafe("1")
+ *   BigDecimal.remainderUnsafe(BigDecimal.fromStringUnsafe("3"), BigDecimal.fromStringUnsafe("2")),
+ *   BigDecimal.fromStringUnsafe("1")
  * )
  * assert.deepStrictEqual(
- *   remainderUnsafe(fromStringUnsafe("-4"), fromStringUnsafe("2")),
- *   fromStringUnsafe("0")
+ *   BigDecimal.remainderUnsafe(BigDecimal.fromStringUnsafe("-4"), BigDecimal.fromStringUnsafe("2")),
+ *   BigDecimal.fromStringUnsafe("0")
  * )
  * ```
  *
- * @since 2.0.0
  * @category math
+ * @since 4.0.0
  */
 export const remainderUnsafe: {
   /**
@@ -1723,27 +1767,28 @@ export const remainderUnsafe: {
    *
    * Throws a `RangeError` if the divisor is `0`.
    *
-   * @example
+   * **Example** (Computing remainders unsafely)
+   *
    * ```ts
-   * import { fromStringUnsafe, remainderUnsafe } from "effect/BigDecimal"
+   * import { BigDecimal } from "effect"
    * import * as assert from "node:assert"
    *
    * assert.deepStrictEqual(
-   *   remainderUnsafe(fromStringUnsafe("2"), fromStringUnsafe("2")),
-   *   fromStringUnsafe("0")
+   *   BigDecimal.remainderUnsafe(BigDecimal.fromStringUnsafe("2"), BigDecimal.fromStringUnsafe("2")),
+   *   BigDecimal.fromStringUnsafe("0")
    * )
    * assert.deepStrictEqual(
-   *   remainderUnsafe(fromStringUnsafe("3"), fromStringUnsafe("2")),
-   *   fromStringUnsafe("1")
+   *   BigDecimal.remainderUnsafe(BigDecimal.fromStringUnsafe("3"), BigDecimal.fromStringUnsafe("2")),
+   *   BigDecimal.fromStringUnsafe("1")
    * )
    * assert.deepStrictEqual(
-   *   remainderUnsafe(fromStringUnsafe("-4"), fromStringUnsafe("2")),
-   *   fromStringUnsafe("0")
+   *   BigDecimal.remainderUnsafe(BigDecimal.fromStringUnsafe("-4"), BigDecimal.fromStringUnsafe("2")),
+   *   BigDecimal.fromStringUnsafe("0")
    * )
    * ```
    *
-   * @since 2.0.0
    * @category math
+   * @since 4.0.0
    */
   (divisor: BigDecimal): (self: BigDecimal) => BigDecimal
   /**
@@ -1751,27 +1796,28 @@ export const remainderUnsafe: {
    *
    * Throws a `RangeError` if the divisor is `0`.
    *
-   * @example
+   * **Example** (Computing remainders unsafely)
+   *
    * ```ts
-   * import { fromStringUnsafe, remainderUnsafe } from "effect/BigDecimal"
+   * import { BigDecimal } from "effect"
    * import * as assert from "node:assert"
    *
    * assert.deepStrictEqual(
-   *   remainderUnsafe(fromStringUnsafe("2"), fromStringUnsafe("2")),
-   *   fromStringUnsafe("0")
+   *   BigDecimal.remainderUnsafe(BigDecimal.fromStringUnsafe("2"), BigDecimal.fromStringUnsafe("2")),
+   *   BigDecimal.fromStringUnsafe("0")
    * )
    * assert.deepStrictEqual(
-   *   remainderUnsafe(fromStringUnsafe("3"), fromStringUnsafe("2")),
-   *   fromStringUnsafe("1")
+   *   BigDecimal.remainderUnsafe(BigDecimal.fromStringUnsafe("3"), BigDecimal.fromStringUnsafe("2")),
+   *   BigDecimal.fromStringUnsafe("1")
    * )
    * assert.deepStrictEqual(
-   *   remainderUnsafe(fromStringUnsafe("-4"), fromStringUnsafe("2")),
-   *   fromStringUnsafe("0")
+   *   BigDecimal.remainderUnsafe(BigDecimal.fromStringUnsafe("-4"), BigDecimal.fromStringUnsafe("2")),
+   *   BigDecimal.fromStringUnsafe("0")
    * )
    * ```
    *
-   * @since 2.0.0
    * @category math
+   * @since 4.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,17 +1950,18 @@ 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 { BigDecimal } from "effect"
  * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(fromNumberUnsafe(123), make(123n, 0))
- * assert.deepStrictEqual(fromNumberUnsafe(123.456), make(123456n, 3))
+ * assert.deepStrictEqual(BigDecimal.fromNumberUnsafe(123), BigDecimal.make(123n, 0))
+ * assert.deepStrictEqual(BigDecimal.fromNumberUnsafe(123.456), BigDecimal.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 2.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,43 +2076,50 @@ 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 { BigDecimal } from "effect"
  * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(fromStringUnsafe("123"), make(123n, 0))
- * assert.deepStrictEqual(fromStringUnsafe("123.456"), make(123456n, 3))
- * assert.throws(() => fromStringUnsafe("123.abc"))
+ * assert.deepStrictEqual(BigDecimal.fromStringUnsafe("123"), BigDecimal.make(123n, 0))
+ * assert.deepStrictEqual(BigDecimal.fromStringUnsafe("123.456"), BigDecimal.make(123456n, 3))
+ * assert.throws(() => BigDecimal.fromStringUnsafe("123.abc"))
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 4.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.
  *
- * If the scale of the `BigDecimal` is greater than or equal to 16, the `BigDecimal` will
- * be formatted in scientific notation.
+ * 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.
+ *
+ * **Example** (Formatting decimals)
  *
- * @example
  * ```ts
- * import { format, fromStringUnsafe } from "effect/BigDecimal"
+ * import { BigDecimal } from "effect"
  * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(format(fromStringUnsafe("-5")), "-5")
- * assert.deepStrictEqual(format(fromStringUnsafe("123.456")), "123.456")
- * assert.deepStrictEqual(format(fromStringUnsafe("-0.00000123")), "-0.00000123")
+ * assert.deepStrictEqual(BigDecimal.format(BigDecimal.fromStringUnsafe("-5")), "-5")
+ * assert.deepStrictEqual(BigDecimal.format(BigDecimal.fromStringUnsafe("123.456")), "123.456")
+ * assert.deepStrictEqual(BigDecimal.format(BigDecimal.fromStringUnsafe("-0.00000123")), "-0.00000123")
  * ```
  *
+ * @category converting
  * @since 2.0.0
- * @category conversions
  */
 export const format = (n: BigDecimal): string => {
   const normalized = normalize(n)
@@ -2090,16 +2155,17 @@ 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 { BigDecimal } from "effect"
  * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(toExponential(make(123456n, -5)), "1.23456e+10")
+ * assert.deepStrictEqual(BigDecimal.toExponential(BigDecimal.make(123456n, -5)), "1.23456e+10")
  * ```
  *
- * @since 4.0.0
- * @category conversions
+ * @category converting
+ * @since 3.11.0
  */
 export const toExponential = (n: BigDecimal): string => {
   if (isZero(n)) {
@@ -2121,91 +2187,98 @@ 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 { BigDecimal } from "effect"
  * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(toNumberUnsafe(fromStringUnsafe("123.456")), 123.456)
+ * assert.deepStrictEqual(BigDecimal.toNumberUnsafe(BigDecimal.fromStringUnsafe("123.456")), 123.456)
  * ```
  *
- * @since 2.0.0
- * @category conversions
+ * @category converting
+ * @since 4.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 { BigDecimal } from "effect"
  * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(isInteger(fromStringUnsafe("0")), true)
- * assert.deepStrictEqual(isInteger(fromStringUnsafe("1")), true)
- * assert.deepStrictEqual(isInteger(fromStringUnsafe("1.1")), false)
+ * assert.deepStrictEqual(BigDecimal.isInteger(BigDecimal.fromStringUnsafe("0")), true)
+ * assert.deepStrictEqual(BigDecimal.isInteger(BigDecimal.fromStringUnsafe("1")), true)
+ * assert.deepStrictEqual(BigDecimal.isInteger(BigDecimal.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 { BigDecimal } from "effect"
  * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(isZero(fromStringUnsafe("0")), true)
- * assert.deepStrictEqual(isZero(fromStringUnsafe("1")), false)
+ * assert.deepStrictEqual(BigDecimal.isZero(BigDecimal.fromStringUnsafe("0")), true)
+ * assert.deepStrictEqual(BigDecimal.isZero(BigDecimal.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 { BigDecimal } from "effect"
  * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(isNegative(fromStringUnsafe("-1")), true)
- * assert.deepStrictEqual(isNegative(fromStringUnsafe("0")), false)
- * assert.deepStrictEqual(isNegative(fromStringUnsafe("1")), false)
+ * assert.deepStrictEqual(BigDecimal.isNegative(BigDecimal.fromStringUnsafe("-1")), true)
+ * assert.deepStrictEqual(BigDecimal.isNegative(BigDecimal.fromStringUnsafe("0")), false)
+ * assert.deepStrictEqual(BigDecimal.isNegative(BigDecimal.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 { BigDecimal } from "effect"
  * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(isPositive(fromStringUnsafe("-1")), false)
- * assert.deepStrictEqual(isPositive(fromStringUnsafe("0")), false)
- * assert.deepStrictEqual(isPositive(fromStringUnsafe("1")), true)
+ * assert.deepStrictEqual(BigDecimal.isPositive(BigDecimal.fromStringUnsafe("-1")), false)
+ * assert.deepStrictEqual(BigDecimal.isPositive(BigDecimal.fromStringUnsafe("0")), false)
+ * assert.deepStrictEqual(BigDecimal.isPositive(BigDecimal.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 3.16.0
  */
 export type RoundingMode =
   | "ceil"
@@ -2243,67 +2316,70 @@ 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 { BigDecimal } from "effect"
  * import * as assert from "node:assert"
  *
  * assert.deepStrictEqual(
- *   round(fromStringUnsafe("145"), { mode: "from-zero", scale: -1 }),
- *   fromStringUnsafe("150")
+ *   BigDecimal.round(BigDecimal.fromStringUnsafe("145"), { mode: "from-zero", scale: -1 }),
+ *   BigDecimal.fromStringUnsafe("150")
  * )
  * assert.deepStrictEqual(
- *   round(fromStringUnsafe("-14.5")),
- *   fromStringUnsafe("-15")
+ *   BigDecimal.round(BigDecimal.fromStringUnsafe("-14.5")),
+ *   BigDecimal.fromStringUnsafe("-15")
  * )
  * ```
  *
- * @since 4.0.0
  * @category math
+ * @since 3.16.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 { BigDecimal } from "effect"
    * import * as assert from "node:assert"
    *
    * assert.deepStrictEqual(
-   *   round(fromStringUnsafe("145"), { mode: "from-zero", scale: -1 }),
-   *   fromStringUnsafe("150")
+   *   BigDecimal.round(BigDecimal.fromStringUnsafe("145"), { mode: "from-zero", scale: -1 }),
+   *   BigDecimal.fromStringUnsafe("150")
    * )
    * assert.deepStrictEqual(
-   *   round(fromStringUnsafe("-14.5")),
-   *   fromStringUnsafe("-15")
+   *   BigDecimal.round(BigDecimal.fromStringUnsafe("-14.5")),
+   *   BigDecimal.fromStringUnsafe("-15")
    * )
    * ```
    *
-   * @since 4.0.0
    * @category math
+   * @since 3.16.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 { BigDecimal } from "effect"
    * import * as assert from "node:assert"
    *
    * assert.deepStrictEqual(
-   *   round(fromStringUnsafe("145"), { mode: "from-zero", scale: -1 }),
-   *   fromStringUnsafe("150")
+   *   BigDecimal.round(BigDecimal.fromStringUnsafe("145"), { mode: "from-zero", scale: -1 }),
+   *   BigDecimal.fromStringUnsafe("150")
    * )
    * assert.deepStrictEqual(
-   *   round(fromStringUnsafe("-14.5")),
-   *   fromStringUnsafe("-15")
+   *   BigDecimal.round(BigDecimal.fromStringUnsafe("-14.5")),
+   *   BigDecimal.fromStringUnsafe("-15")
    * )
    * ```
    *
-   * @since 4.0.0
    * @category math
+   * @since 3.16.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"
+ * import { BigDecimal } from "effect"
  *
- * assert.deepStrictEqual(
- *   truncate(fromStringUnsafe("145"), -1),
- *   fromStringUnsafe("140")
- * )
- * assert.deepStrictEqual(
- *   truncate(fromStringUnsafe("-14.5")),
- *   fromStringUnsafe("-14")
- * )
+ * console.log(BigDecimal.truncate(BigDecimal.fromStringUnsafe("145"), -1)) // BigDecimal(140)
+ * console.log(BigDecimal.truncate(BigDecimal.fromStringUnsafe("-14.5"))) // BigDecimal(-14)
  * ```
  *
- * @since 4.0.0
  * @category math
+ * @since 3.16.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"
+   * import { BigDecimal } from "effect"
    *
-   * assert.deepStrictEqual(
-   *   truncate(fromStringUnsafe("145"), -1),
-   *   fromStringUnsafe("140")
-   * )
-   * assert.deepStrictEqual(
-   *   truncate(fromStringUnsafe("-14.5")),
-   *   fromStringUnsafe("-14")
-   * )
+   * console.log(BigDecimal.truncate(BigDecimal.fromStringUnsafe("145"), -1)) // BigDecimal(140)
+   * console.log(BigDecimal.truncate(BigDecimal.fromStringUnsafe("-14.5"))) // BigDecimal(-14)
    * ```
    *
-   * @since 4.0.0
    * @category math
+   * @since 3.16.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"
+   * import { BigDecimal } from "effect"
    *
-   * assert.deepStrictEqual(
-   *   truncate(fromStringUnsafe("145"), -1),
-   *   fromStringUnsafe("140")
-   * )
-   * assert.deepStrictEqual(
-   *   truncate(fromStringUnsafe("-14.5")),
-   *   fromStringUnsafe("-14")
-   * )
+   * console.log(BigDecimal.truncate(BigDecimal.fromStringUnsafe("145"), -1)) // BigDecimal(140)
+   * console.log(BigDecimal.truncate(BigDecimal.fromStringUnsafe("-14.5"))) // BigDecimal(-14)
    * ```
    *
-   * @since 4.0.0
    * @category math
+   * @since 3.16.0
    */
   (self: BigDecimal, scale?: number): BigDecimal
 } = dual(isBigDecimalArgs, (self: BigDecimal, scale: number = 0): BigDecimal => {
@@ -2431,58 +2492,61 @@ 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 { BigDecimal } from "effect"
  * import * as assert from "node:assert"
  *
  * assert.deepStrictEqual(
- *   ceil(fromStringUnsafe("145"), -1),
- *   fromStringUnsafe("150")
+ *   BigDecimal.ceil(BigDecimal.fromStringUnsafe("145"), -1),
+ *   BigDecimal.fromStringUnsafe("150")
  * )
- * assert.deepStrictEqual(ceil(fromStringUnsafe("-14.5")), fromStringUnsafe("-14"))
+ * assert.deepStrictEqual(BigDecimal.ceil(BigDecimal.fromStringUnsafe("-14.5")), BigDecimal.fromStringUnsafe("-14"))
  * ```
  *
- * @since 4.0.0
  * @category math
+ * @since 3.16.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 { BigDecimal } from "effect"
    * import * as assert from "node:assert"
    *
    * assert.deepStrictEqual(
-   *   ceil(fromStringUnsafe("145"), -1),
-   *   fromStringUnsafe("150")
+   *   BigDecimal.ceil(BigDecimal.fromStringUnsafe("145"), -1),
+   *   BigDecimal.fromStringUnsafe("150")
    * )
-   * assert.deepStrictEqual(ceil(fromStringUnsafe("-14.5")), fromStringUnsafe("-14"))
+   * assert.deepStrictEqual(BigDecimal.ceil(BigDecimal.fromStringUnsafe("-14.5")), BigDecimal.fromStringUnsafe("-14"))
    * ```
    *
-   * @since 4.0.0
    * @category math
+   * @since 3.16.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 { BigDecimal } from "effect"
    * import * as assert from "node:assert"
    *
    * assert.deepStrictEqual(
-   *   ceil(fromStringUnsafe("145"), -1),
-   *   fromStringUnsafe("150")
+   *   BigDecimal.ceil(BigDecimal.fromStringUnsafe("145"), -1),
+   *   BigDecimal.fromStringUnsafe("150")
    * )
-   * assert.deepStrictEqual(ceil(fromStringUnsafe("-14.5")), fromStringUnsafe("-14"))
+   * assert.deepStrictEqual(BigDecimal.ceil(BigDecimal.fromStringUnsafe("-14.5")), BigDecimal.fromStringUnsafe("-14"))
    * ```
    *
-   * @since 4.0.0
    * @category math
+   * @since 3.16.0
    */
   (self: BigDecimal, scale?: number): BigDecimal
 } = dual(isBigDecimalArgs, (self: BigDecimal, scale: number = 0): BigDecimal => {
@@ -2531,67 +2595,70 @@ 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 { BigDecimal } from "effect"
  * import * as assert from "node:assert"
  *
  * assert.deepStrictEqual(
- *   floor(fromStringUnsafe("145"), -1),
- *   fromStringUnsafe("140")
+ *   BigDecimal.floor(BigDecimal.fromStringUnsafe("145"), -1),
+ *   BigDecimal.fromStringUnsafe("140")
  * )
  * assert.deepStrictEqual(
- *   floor(fromStringUnsafe("-14.5")),
- *   fromStringUnsafe("-15")
+ *   BigDecimal.floor(BigDecimal.fromStringUnsafe("-14.5")),
+ *   BigDecimal.fromStringUnsafe("-15")
  * )
  * ```
  *
- * @since 4.0.0
  * @category math
+ * @since 3.16.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 { BigDecimal } from "effect"
    * import * as assert from "node:assert"
    *
    * assert.deepStrictEqual(
-   *   floor(fromStringUnsafe("145"), -1),
-   *   fromStringUnsafe("140")
+   *   BigDecimal.floor(BigDecimal.fromStringUnsafe("145"), -1),
+   *   BigDecimal.fromStringUnsafe("140")
    * )
    * assert.deepStrictEqual(
-   *   floor(fromStringUnsafe("-14.5")),
-   *   fromStringUnsafe("-15")
+   *   BigDecimal.floor(BigDecimal.fromStringUnsafe("-14.5")),
+   *   BigDecimal.fromStringUnsafe("-15")
    * )
    * ```
    *
-   * @since 4.0.0
    * @category math
+   * @since 3.16.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 { BigDecimal } from "effect"
    * import * as assert from "node:assert"
    *
    * assert.deepStrictEqual(
-   *   floor(fromStringUnsafe("145"), -1),
-   *   fromStringUnsafe("140")
+   *   BigDecimal.floor(BigDecimal.fromStringUnsafe("145"), -1),
+   *   BigDecimal.fromStringUnsafe("140")
    * )
    * assert.deepStrictEqual(
-   *   floor(fromStringUnsafe("-14.5")),
-   *   fromStringUnsafe("-15")
+   *   BigDecimal.floor(BigDecimal.fromStringUnsafe("-14.5")),
+   *   BigDecimal.fromStringUnsafe("-15")
    * )
    * ```
    *
-   * @since 4.0.0
    * @category math
+   * @since 3.16.0
    */
   (self: BigDecimal, scale?: number): BigDecimal
 } = dual(isBigDecimalArgs, (self: BigDecimal, scale: number = 0): BigDecimal => {