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

package/dist/BigDecimal.d.ts

@@ -24,14 +24,15 @@ declare 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
@@ -45,7 +46,8 @@ export interface BigDecimal extends Equal.Equal, Pipeable, Inspectable {
 /**
  * Checks if a given value is a `BigDecimal`.
  *
- * @example
+ * **Example** (Checking BigDecimal values)
+ *
  * ```ts
  * import { BigDecimal } from "effect"
  *
@@ -55,14 +57,15 @@ export interface BigDecimal extends Equal.Equal, Pipeable, Inspectable {
  * console.log(BigDecimal.isBigDecimal("123.45")) // false
  * ```
  *
- * @since 2.0.0
  * @category guards
+ * @since 2.0.0
  */
 export declare const isBigDecimal: (u: unknown) => u is BigDecimal;
 /**
  * Creates a `BigDecimal` from a `bigint` value and a scale.
  *
- * @example
+ * **Example** (Creating decimals from bigint and scale)
+ *
  * ```ts
  * import { BigDecimal } from "effect"
  *
@@ -75,39 +78,42 @@ export declare const isBigDecimal: (u: unknown) => u is BigDecimal;
  * console.log(BigDecimal.format(integer)) // "42"
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export declare const make: (value: bigint, scale: number) => BigDecimal;
 /**
  * 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 declare 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"
  *
@@ -122,17 +128,19 @@ export declare const normalize: (self: BigDecimal) => BigDecimal;
  * console.log(BigDecimal.format(reduced)) // "123.4"
  * ```
  *
- * @since 2.0.0
  * @category scaling
+ * @since 2.0.0
  */
 export declare 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"
      *
@@ -147,17 +155,19 @@ export declare 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"
      *
@@ -172,419 +182,422 @@ export declare const scale: {
      * console.log(BigDecimal.format(reduced)) // "123.4"
      * ```
      *
-     * @since 2.0.0
      * @category scaling
+     * @since 2.0.0
      */
     (self: BigDecimal, scale: number): 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
  */
 export declare 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;
 };
 /**
  * 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 declare 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 declare 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;
 };
 /**
  * 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 declare 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 declare 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;
 };
 /**
  * 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 declare 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>;
 };
 /**
  * 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 declare 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;
 };
 /**
  * Provides an `Order` instance for `BigDecimal` that allows comparing and sorting BigDecimal values.
  *
- * @example
+ * **Example** (Comparing decimals)
+ *
  * ```ts
  * import { BigDecimal } from "effect"
  *
@@ -597,330 +610,343 @@ export declare const divideUnsafe: {
  * console.log(BigDecimal.Order(a, c)) // 0 (a === c)
  * ```
  *
- * @since 2.0.0
  * @category instances
+ * @since 2.0.0
  */
 export declare const Order: order.Order<BigDecimal>;
 /**
  * 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 declare 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;
 };
 /**
  * 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 declare 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;
 };
 /**
  * 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 declare 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;
 };
 /**
  * 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 declare 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;
 };
 /**
  * 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"
@@ -935,14 +961,15 @@ export declare const isGreaterThanOrEqualTo: {
  * assert.deepStrictEqual(between(BigDecimal.fromStringUnsafe("6")), false)
  * ```
  *
- * @since 2.0.0
  * @category predicates
+ * @since 2.0.0
  */
 export declare 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"
@@ -957,8 +984,8 @@ export declare const between: {
      * assert.deepStrictEqual(between(BigDecimal.fromStringUnsafe("6")), false)
      * ```
      *
-     * @since 2.0.0
      * @category predicates
+     * @since 2.0.0
      */
     (options: {
         minimum: BigDecimal;
@@ -967,7 +994,8 @@ export declare 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"
@@ -982,8 +1010,8 @@ export declare const between: {
      * assert.deepStrictEqual(between(BigDecimal.fromStringUnsafe("6")), false)
      * ```
      *
-     * @since 2.0.0
      * @category predicates
+     * @since 2.0.0
      */
     (self: BigDecimal, options: {
         minimum: BigDecimal;
@@ -997,7 +1025,8 @@ export declare 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"
@@ -1021,8 +1050,8 @@ export declare const between: {
  * )
  * ```
  *
- * @since 2.0.0
  * @category math
+ * @since 2.0.0
  */
 export declare const clamp: {
     /**
@@ -1032,7 +1061,8 @@ export declare 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"
@@ -1056,8 +1086,8 @@ export declare const clamp: {
      * )
      * ```
      *
-     * @since 2.0.0
      * @category math
+     * @since 2.0.0
      */
     (options: {
         minimum: BigDecimal;
@@ -1070,7 +1100,8 @@ export declare 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"
@@ -1094,8 +1125,8 @@ export declare const clamp: {
      * )
      * ```
      *
-     * @since 2.0.0
      * @category math
+     * @since 2.0.0
      */
     (self: BigDecimal, options: {
         minimum: BigDecimal;
@@ -1105,161 +1136,170 @@ export declare 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 declare 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;
 };
 /**
  * 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 declare 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;
 };
 /**
  * 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 declare const sign: (n: BigDecimal) => Ordering;
 /**
  * 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 declare const abs: (n: BigDecimal) => BigDecimal;
 /**
  * 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 declare const negate: (n: BigDecimal) => BigDecimal;
 /**
@@ -1267,7 +1307,8 @@ export declare const negate: (n: BigDecimal) => BigDecimal;
  *
  * 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"
@@ -1295,8 +1336,8 @@ export declare const negate: (n: BigDecimal) => BigDecimal;
  * )
  * ```
  *
- * @since 2.0.0
  * @category math
+ * @since 2.0.0
  */
 export declare const remainder: {
     /**
@@ -1304,7 +1345,8 @@ export declare 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"
@@ -1332,8 +1374,8 @@ export declare const remainder: {
      * )
      * ```
      *
-     * @since 2.0.0
      * @category math
+     * @since 2.0.0
      */
     (divisor: BigDecimal): (self: BigDecimal) => Option.Option<BigDecimal>;
     /**
@@ -1341,7 +1383,8 @@ export declare 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"
@@ -1369,8 +1412,8 @@ export declare const remainder: {
      * )
      * ```
      *
-     * @since 2.0.0
      * @category math
+     * @since 2.0.0
      */
     (self: BigDecimal, divisor: BigDecimal): Option.Option<BigDecimal>;
 };
@@ -1379,27 +1422,28 @@ export declare 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 declare const remainderUnsafe: {
     /**
@@ -1407,27 +1451,28 @@ export declare 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;
     /**
@@ -1435,40 +1480,42 @@ export declare 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;
 };
 /**
  * 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)
@@ -1481,65 +1528,69 @@ export declare const Equivalence: Equ.Equivalence<BigDecimal>;
 /**
  * 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 declare 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;
 };
 /**
  * Creates a `BigDecimal` from a `bigint` value.
  *
- * @example
+ * **Example** (Creating decimals from bigint)
+ *
  * ```ts
  * import { BigDecimal } from "effect"
  *
@@ -1550,8 +1601,8 @@ export declare const equals: {
  * console.log(BigDecimal.format(largeBigInt)) // "9007199254740991"
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export declare const fromBigInt: (n: bigint) => BigDecimal;
 /**
@@ -1562,17 +1613,18 @@ export declare const fromBigInt: (n: bigint) => BigDecimal;
  *
  * 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 declare const fromNumberUnsafe: (n: number) => BigDecimal;
 /**
@@ -1583,7 +1635,8 @@ export declare 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"
@@ -1596,14 +1649,19 @@ export declare const fromNumberUnsafe: (n: number) => BigDecimal;
  * assert.deepStrictEqual(BigDecimal.fromNumber(Infinity), Option.none())
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export declare 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"
@@ -1616,144 +1674,159 @@ export declare 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 declare 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 declare const fromStringUnsafe: (s: string) => BigDecimal;
 /**
- * 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 declare 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 declare 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 declare const toNumberUnsafe: (n: BigDecimal) => number;
 /**
  * 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 declare const isInteger: (n: BigDecimal) => boolean;
 /**
  * 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 declare const isZero: (n: BigDecimal) => boolean;
 /**
  * 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 declare const isNegative: (n: BigDecimal) => boolean;
 /**
  * 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 declare const isPositive: (n: BigDecimal) => boolean;
 /**
@@ -1770,52 +1843,54 @@ export declare const isPositive: (n: BigDecimal) => boolean;
  * `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" | "floor" | "to-zero" | "from-zero" | "half-ceil" | "half-floor" | "half-to-zero" | "half-from-zero" | "half-even" | "half-odd";
 /**
  * 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 declare 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;
@@ -1824,23 +1899,24 @@ export declare 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
      */
     (n: BigDecimal, options?: {
         scale?: number;
@@ -1848,194 +1924,185 @@ export declare const round: {
     }): 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
  */
 export declare 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;
 };
 /**
  * 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 declare 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;
 };
 /**
  * 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 declare 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;
 };