effect 3.10.18 → 3.11.0

package/src/BigDecimal.ts

@@ -26,6 +26,7 @@ import { type Pipeable, pipeArguments } from "./Pipeable.js"
 import { hasProperty } from "./Predicate.js"
 
 const DEFAULT_PRECISION = 100
+const FINITE_INT_REGEX = /^[+-]?\d+$/
 
 /**
  * @since 2.0.0
@@ -134,10 +135,12 @@ const zero = unsafeMakeNormalized(bigint0, 0)
  * @param self - The `BigDecimal` to normalize.
  *
  * @example
+ * ```ts
  * import { normalize, make, unsafeFromString } from "effect/BigDecimal"
  *
  * assert.deepStrictEqual(normalize(unsafeFromString("123.00000")), normalize(make(123n, 0)))
  * assert.deepStrictEqual(normalize(unsafeFromString("12300000")), normalize(make(123n, -5)))
+ * ```
  *
  * @since 2.0.0
  * @category scaling
@@ -229,9 +232,11 @@ export const scale: {
  * @param that - The second operand.
  *
  * @example
+ * ```ts
  * import { sum, unsafeFromString } from "effect/BigDecimal"
  *
  * assert.deepStrictEqual(sum(unsafeFromString("2"), unsafeFromString("3")), unsafeFromString("5"))
+ * ```
  *
  * @since 2.0.0
  * @category math
@@ -244,9 +249,11 @@ export const sum: {
    * @param that - The second operand.
    *
    * @example
+   * ```ts
    * import { sum, unsafeFromString } from "effect/BigDecimal"
    *
    * assert.deepStrictEqual(sum(unsafeFromString("2"), unsafeFromString("3")), unsafeFromString("5"))
+   * ```
    *
    * @since 2.0.0
    * @category math
@@ -259,9 +266,11 @@ export const sum: {
    * @param that - The second operand.
    *
    * @example
+   * ```ts
    * import { sum, unsafeFromString } from "effect/BigDecimal"
    *
    * assert.deepStrictEqual(sum(unsafeFromString("2"), unsafeFromString("3")), unsafeFromString("5"))
+   * ```
    *
    * @since 2.0.0
    * @category math
@@ -294,9 +303,11 @@ export const sum: {
  * @param that - The second operand.
  *
  * @example
+ * ```ts
  * import { multiply, unsafeFromString } from "effect/BigDecimal"
  *
  * assert.deepStrictEqual(multiply(unsafeFromString("2"), unsafeFromString("3")), unsafeFromString("6"))
+ * ```
  *
  * @since 2.0.0
  * @category math
@@ -309,9 +320,11 @@ export const multiply: {
    * @param that - The second operand.
    *
    * @example
+   * ```ts
    * import { multiply, unsafeFromString } from "effect/BigDecimal"
    *
    * assert.deepStrictEqual(multiply(unsafeFromString("2"), unsafeFromString("3")), unsafeFromString("6"))
+   * ```
    *
    * @since 2.0.0
    * @category math
@@ -324,9 +337,11 @@ export const multiply: {
    * @param that - The second operand.
    *
    * @example
+   * ```ts
    * import { multiply, unsafeFromString } from "effect/BigDecimal"
    *
    * assert.deepStrictEqual(multiply(unsafeFromString("2"), unsafeFromString("3")), unsafeFromString("6"))
+   * ```
    *
    * @since 2.0.0
    * @category math
@@ -347,9 +362,11 @@ export const multiply: {
  * @param that - The second operand.
  *
  * @example
+ * ```ts
  * import { subtract, unsafeFromString } from "effect/BigDecimal"
  *
  * assert.deepStrictEqual(subtract(unsafeFromString("2"), unsafeFromString("3")), unsafeFromString("-1"))
+ * ```
  *
  * @since 2.0.0
  * @category math
@@ -362,9 +379,11 @@ export const subtract: {
    * @param that - The second operand.
    *
    * @example
+   * ```ts
    * import { subtract, unsafeFromString } from "effect/BigDecimal"
    *
    * assert.deepStrictEqual(subtract(unsafeFromString("2"), unsafeFromString("3")), unsafeFromString("-1"))
+   * ```
    *
    * @since 2.0.0
    * @category math
@@ -377,9 +396,11 @@ export const subtract: {
    * @param that - The second operand.
    *
    * @example
+   * ```ts
    * import { subtract, unsafeFromString } from "effect/BigDecimal"
    *
    * assert.deepStrictEqual(subtract(unsafeFromString("2"), unsafeFromString("3")), unsafeFromString("-1"))
+   * ```
    *
    * @since 2.0.0
    * @category math
@@ -485,11 +506,13 @@ export const roundTerminal = (n: bigint): bigint => {
  * @param that - The divisor operand.
  *
  * @example
+ * ```ts
  * import { BigDecimal, Option } from "effect"
  *
  * assert.deepStrictEqual(BigDecimal.divide(BigDecimal.unsafeFromString("6"), BigDecimal.unsafeFromString("3")), Option.some(BigDecimal.unsafeFromString("2")))
  * assert.deepStrictEqual(BigDecimal.divide(BigDecimal.unsafeFromString("6"), BigDecimal.unsafeFromString("4")), Option.some(BigDecimal.unsafeFromString("1.5")))
  * assert.deepStrictEqual(BigDecimal.divide(BigDecimal.unsafeFromString("6"), BigDecimal.unsafeFromString("0")), Option.none())
+ * ```
  *
  * @since 2.0.0
  * @category math
@@ -507,11 +530,13 @@ export const divide: {
    * @param that - The divisor operand.
    *
    * @example
+   * ```ts
    * import { BigDecimal, Option } from "effect"
    *
    * assert.deepStrictEqual(BigDecimal.divide(BigDecimal.unsafeFromString("6"), BigDecimal.unsafeFromString("3")), Option.some(BigDecimal.unsafeFromString("2")))
    * assert.deepStrictEqual(BigDecimal.divide(BigDecimal.unsafeFromString("6"), BigDecimal.unsafeFromString("4")), Option.some(BigDecimal.unsafeFromString("1.5")))
    * assert.deepStrictEqual(BigDecimal.divide(BigDecimal.unsafeFromString("6"), BigDecimal.unsafeFromString("0")), Option.none())
+   * ```
    *
    * @since 2.0.0
    * @category math
@@ -529,11 +554,13 @@ export const divide: {
    * @param that - The divisor operand.
    *
    * @example
+   * ```ts
    * import { BigDecimal, Option } from "effect"
    *
    * assert.deepStrictEqual(BigDecimal.divide(BigDecimal.unsafeFromString("6"), BigDecimal.unsafeFromString("3")), Option.some(BigDecimal.unsafeFromString("2")))
    * assert.deepStrictEqual(BigDecimal.divide(BigDecimal.unsafeFromString("6"), BigDecimal.unsafeFromString("4")), Option.some(BigDecimal.unsafeFromString("1.5")))
    * assert.deepStrictEqual(BigDecimal.divide(BigDecimal.unsafeFromString("6"), BigDecimal.unsafeFromString("0")), Option.none())
+   * ```
    *
    * @since 2.0.0
    * @category math
@@ -568,10 +595,12 @@ export const divide: {
  * @param that - The divisor operand.as
  *
  * @example
+ * ```ts
  * import { unsafeDivide, unsafeFromString } from "effect/BigDecimal"
  *
  * assert.deepStrictEqual(unsafeDivide(unsafeFromString("6"), unsafeFromString("3")), unsafeFromString("2"))
  * assert.deepStrictEqual(unsafeDivide(unsafeFromString("6"), unsafeFromString("4")), unsafeFromString("1.5"))
+ * ```
  *
  * @since 2.0.0
  * @category math
@@ -589,10 +618,12 @@ export const unsafeDivide: {
    * @param that - The divisor operand.as
    *
    * @example
+   * ```ts
    * import { unsafeDivide, unsafeFromString } from "effect/BigDecimal"
    *
    * assert.deepStrictEqual(unsafeDivide(unsafeFromString("6"), unsafeFromString("3")), unsafeFromString("2"))
    * assert.deepStrictEqual(unsafeDivide(unsafeFromString("6"), unsafeFromString("4")), unsafeFromString("1.5"))
+   * ```
    *
    * @since 2.0.0
    * @category math
@@ -610,10 +641,12 @@ export const unsafeDivide: {
    * @param that - The divisor operand.as
    *
    * @example
+   * ```ts
    * import { unsafeDivide, unsafeFromString } from "effect/BigDecimal"
    *
    * assert.deepStrictEqual(unsafeDivide(unsafeFromString("6"), unsafeFromString("3")), unsafeFromString("2"))
    * assert.deepStrictEqual(unsafeDivide(unsafeFromString("6"), unsafeFromString("4")), unsafeFromString("1.5"))
+   * ```
    *
    * @since 2.0.0
    * @category math
@@ -663,11 +696,13 @@ export const Order: order.Order<BigDecimal> = order.make((self, that) => {
  * @param that - The second argument.
  *
  * @example
+ * ```ts
  * import { lessThan, unsafeFromString } from "effect/BigDecimal"
  *
  * assert.deepStrictEqual(lessThan(unsafeFromString("2"), unsafeFromString("3")), true)
  * assert.deepStrictEqual(lessThan(unsafeFromString("3"), unsafeFromString("3")), false)
  * assert.deepStrictEqual(lessThan(unsafeFromString("4"), unsafeFromString("3")), false)
+ * ```
  *
  * @since 2.0.0
  * @category predicates
@@ -680,11 +715,13 @@ export const lessThan: {
    * @param that - The second argument.
    *
    * @example
+   * ```ts
    * import { lessThan, unsafeFromString } from "effect/BigDecimal"
    *
    * assert.deepStrictEqual(lessThan(unsafeFromString("2"), unsafeFromString("3")), true)
    * assert.deepStrictEqual(lessThan(unsafeFromString("3"), unsafeFromString("3")), false)
    * assert.deepStrictEqual(lessThan(unsafeFromString("4"), unsafeFromString("3")), false)
+   * ```
    *
    * @since 2.0.0
    * @category predicates
@@ -697,11 +734,13 @@ export const lessThan: {
    * @param that - The second argument.
    *
    * @example
+   * ```ts
    * import { lessThan, unsafeFromString } from "effect/BigDecimal"
    *
    * assert.deepStrictEqual(lessThan(unsafeFromString("2"), unsafeFromString("3")), true)
    * assert.deepStrictEqual(lessThan(unsafeFromString("3"), unsafeFromString("3")), false)
    * assert.deepStrictEqual(lessThan(unsafeFromString("4"), unsafeFromString("3")), false)
+   * ```
    *
    * @since 2.0.0
    * @category predicates
@@ -716,11 +755,13 @@ export const lessThan: {
  * @param that - The second `BigDecimal` to compare with.
  *
  * @example
+ * ```ts
  * import { lessThanOrEqualTo, unsafeFromString } from "effect/BigDecimal"
  *
  * assert.deepStrictEqual(lessThanOrEqualTo(unsafeFromString("2"), unsafeFromString("3")), true)
  * assert.deepStrictEqual(lessThanOrEqualTo(unsafeFromString("3"), unsafeFromString("3")), true)
  * assert.deepStrictEqual(lessThanOrEqualTo(unsafeFromString("4"), unsafeFromString("3")), false)
+ * ```
  *
  * @since 2.0.0
  * @category predicates
@@ -733,11 +774,13 @@ export const lessThanOrEqualTo: {
    * @param that - The second `BigDecimal` to compare with.
    *
    * @example
+   * ```ts
    * import { lessThanOrEqualTo, unsafeFromString } from "effect/BigDecimal"
    *
    * assert.deepStrictEqual(lessThanOrEqualTo(unsafeFromString("2"), unsafeFromString("3")), true)
    * assert.deepStrictEqual(lessThanOrEqualTo(unsafeFromString("3"), unsafeFromString("3")), true)
    * assert.deepStrictEqual(lessThanOrEqualTo(unsafeFromString("4"), unsafeFromString("3")), false)
+   * ```
    *
    * @since 2.0.0
    * @category predicates
@@ -750,11 +793,13 @@ export const lessThanOrEqualTo: {
    * @param that - The second `BigDecimal` to compare with.
    *
    * @example
+   * ```ts
    * import { lessThanOrEqualTo, unsafeFromString } from "effect/BigDecimal"
    *
    * assert.deepStrictEqual(lessThanOrEqualTo(unsafeFromString("2"), unsafeFromString("3")), true)
    * assert.deepStrictEqual(lessThanOrEqualTo(unsafeFromString("3"), unsafeFromString("3")), true)
    * assert.deepStrictEqual(lessThanOrEqualTo(unsafeFromString("4"), unsafeFromString("3")), false)
+   * ```
    *
    * @since 2.0.0
    * @category predicates
@@ -769,11 +814,13 @@ export const lessThanOrEqualTo: {
  * @param that - The second argument.
  *
  * @example
+ * ```ts
  * import { greaterThan, unsafeFromString } from "effect/BigDecimal"
  *
  * assert.deepStrictEqual(greaterThan(unsafeFromString("2"), unsafeFromString("3")), false)
  * assert.deepStrictEqual(greaterThan(unsafeFromString("3"), unsafeFromString("3")), false)
  * assert.deepStrictEqual(greaterThan(unsafeFromString("4"), unsafeFromString("3")), true)
+ * ```
  *
  * @since 2.0.0
  * @category predicates
@@ -786,11 +833,13 @@ export const greaterThan: {
    * @param that - The second argument.
    *
    * @example
+   * ```ts
    * import { greaterThan, unsafeFromString } from "effect/BigDecimal"
    *
    * assert.deepStrictEqual(greaterThan(unsafeFromString("2"), unsafeFromString("3")), false)
    * assert.deepStrictEqual(greaterThan(unsafeFromString("3"), unsafeFromString("3")), false)
    * assert.deepStrictEqual(greaterThan(unsafeFromString("4"), unsafeFromString("3")), true)
+   * ```
    *
    * @since 2.0.0
    * @category predicates
@@ -803,11 +852,13 @@ export const greaterThan: {
    * @param that - The second argument.
    *
    * @example
+   * ```ts
    * import { greaterThan, unsafeFromString } from "effect/BigDecimal"
    *
    * assert.deepStrictEqual(greaterThan(unsafeFromString("2"), unsafeFromString("3")), false)
    * assert.deepStrictEqual(greaterThan(unsafeFromString("3"), unsafeFromString("3")), false)
    * assert.deepStrictEqual(greaterThan(unsafeFromString("4"), unsafeFromString("3")), true)
+   * ```
    *
    * @since 2.0.0
    * @category predicates
@@ -822,11 +873,13 @@ export const greaterThan: {
  * @param that - The second `BigDecimal` to compare with.
  *
  * @example
+ * ```ts
  * import { greaterThanOrEqualTo, unsafeFromString } from "effect/BigDecimal"
  *
  * assert.deepStrictEqual(greaterThanOrEqualTo(unsafeFromString("2"), unsafeFromString("3")), false)
  * assert.deepStrictEqual(greaterThanOrEqualTo(unsafeFromString("3"), unsafeFromString("3")), true)
  * assert.deepStrictEqual(greaterThanOrEqualTo(unsafeFromString("4"), unsafeFromString("3")), true)
+ * ```
  *
  * @since 2.0.0
  * @category predicates
@@ -839,11 +892,13 @@ export const greaterThanOrEqualTo: {
    * @param that - The second `BigDecimal` to compare with.
    *
    * @example
+   * ```ts
    * import { greaterThanOrEqualTo, unsafeFromString } from "effect/BigDecimal"
    *
    * assert.deepStrictEqual(greaterThanOrEqualTo(unsafeFromString("2"), unsafeFromString("3")), false)
    * assert.deepStrictEqual(greaterThanOrEqualTo(unsafeFromString("3"), unsafeFromString("3")), true)
    * assert.deepStrictEqual(greaterThanOrEqualTo(unsafeFromString("4"), unsafeFromString("3")), true)
+   * ```
    *
    * @since 2.0.0
    * @category predicates
@@ -856,11 +911,13 @@ export const greaterThanOrEqualTo: {
    * @param that - The second `BigDecimal` to compare with.
    *
    * @example
+   * ```ts
    * import { greaterThanOrEqualTo, unsafeFromString } from "effect/BigDecimal"
    *
    * assert.deepStrictEqual(greaterThanOrEqualTo(unsafeFromString("2"), unsafeFromString("3")), false)
    * assert.deepStrictEqual(greaterThanOrEqualTo(unsafeFromString("3"), unsafeFromString("3")), true)
    * assert.deepStrictEqual(greaterThanOrEqualTo(unsafeFromString("4"), unsafeFromString("3")), true)
+   * ```
    *
    * @since 2.0.0
    * @category predicates
@@ -876,6 +933,7 @@ export const greaterThanOrEqualTo: {
  * @param maximum - The `maximum` value to check.
  *
  * @example
+ * ```ts
  * import { BigDecimal } from "effect"
  *
  * const between = BigDecimal.between({
@@ -886,6 +944,7 @@ export const greaterThanOrEqualTo: {
  * assert.deepStrictEqual(between(BigDecimal.unsafeFromString("3")), true)
  * assert.deepStrictEqual(between(BigDecimal.unsafeFromString("0")), false)
  * assert.deepStrictEqual(between(BigDecimal.unsafeFromString("6")), false)
+ * ```
  *
  * @since 2.0.0
  * @category predicates
@@ -899,6 +958,7 @@ export const between: {
    * @param maximum - The `maximum` value to check.
    *
    * @example
+   * ```ts
    * import { BigDecimal } from "effect"
    *
    * const between = BigDecimal.between({
@@ -909,6 +969,7 @@ export const between: {
    * assert.deepStrictEqual(between(BigDecimal.unsafeFromString("3")), true)
    * assert.deepStrictEqual(between(BigDecimal.unsafeFromString("0")), false)
    * assert.deepStrictEqual(between(BigDecimal.unsafeFromString("6")), false)
+   * ```
    *
    * @since 2.0.0
    * @category predicates
@@ -927,6 +988,7 @@ export const between: {
    * @param maximum - The `maximum` value to check.
    *
    * @example
+   * ```ts
    * import { BigDecimal } from "effect"
    *
    * const between = BigDecimal.between({
@@ -937,6 +999,7 @@ export const between: {
    * assert.deepStrictEqual(between(BigDecimal.unsafeFromString("3")), true)
    * assert.deepStrictEqual(between(BigDecimal.unsafeFromString("0")), false)
    * assert.deepStrictEqual(between(BigDecimal.unsafeFromString("6")), false)
+   * ```
    *
    * @since 2.0.0
    * @category predicates
@@ -962,6 +1025,7 @@ export const between: {
  * @param maximum - The upper end of the range.
  *
  * @example
+ * ```ts
  * import { BigDecimal } from "effect"
  *
  * const clamp = BigDecimal.clamp({
@@ -972,6 +1036,7 @@ export const between: {
  * assert.deepStrictEqual(clamp(BigDecimal.unsafeFromString("3")), BigDecimal.unsafeFromString("3"))
  * assert.deepStrictEqual(clamp(BigDecimal.unsafeFromString("0")), BigDecimal.unsafeFromString("1"))
  * assert.deepStrictEqual(clamp(BigDecimal.unsafeFromString("6")), BigDecimal.unsafeFromString("5"))
+ * ```
  *
  * @since 2.0.0
  * @category math
@@ -989,6 +1054,7 @@ export const clamp: {
    * @param maximum - The upper end of the range.
    *
    * @example
+   * ```ts
    * import { BigDecimal } from "effect"
    *
    * const clamp = BigDecimal.clamp({
@@ -999,6 +1065,7 @@ export const clamp: {
    * assert.deepStrictEqual(clamp(BigDecimal.unsafeFromString("3")), BigDecimal.unsafeFromString("3"))
    * assert.deepStrictEqual(clamp(BigDecimal.unsafeFromString("0")), BigDecimal.unsafeFromString("1"))
    * assert.deepStrictEqual(clamp(BigDecimal.unsafeFromString("6")), BigDecimal.unsafeFromString("5"))
+   * ```
    *
    * @since 2.0.0
    * @category math
@@ -1021,6 +1088,7 @@ export const clamp: {
    * @param maximum - The upper end of the range.
    *
    * @example
+   * ```ts
    * import { BigDecimal } from "effect"
    *
    * const clamp = BigDecimal.clamp({
@@ -1031,6 +1099,7 @@ export const clamp: {
    * assert.deepStrictEqual(clamp(BigDecimal.unsafeFromString("3")), BigDecimal.unsafeFromString("3"))
    * assert.deepStrictEqual(clamp(BigDecimal.unsafeFromString("0")), BigDecimal.unsafeFromString("1"))
    * assert.deepStrictEqual(clamp(BigDecimal.unsafeFromString("6")), BigDecimal.unsafeFromString("5"))
+   * ```
    *
    * @since 2.0.0
    * @category math
@@ -1051,9 +1120,11 @@ export const clamp: {
  * @param that - The second `BigDecimal`.
  *
  * @example
+ * ```ts
  * import { min, unsafeFromString } from "effect/BigDecimal"
  *
  * assert.deepStrictEqual(min(unsafeFromString("2"), unsafeFromString("3")), unsafeFromString("2"))
+ * ```
  *
  * @since 2.0.0
  * @category math
@@ -1066,9 +1137,11 @@ export const min: {
    * @param that - The second `BigDecimal`.
    *
    * @example
+   * ```ts
    * import { min, unsafeFromString } from "effect/BigDecimal"
    *
    * assert.deepStrictEqual(min(unsafeFromString("2"), unsafeFromString("3")), unsafeFromString("2"))
+   * ```
    *
    * @since 2.0.0
    * @category math
@@ -1081,9 +1154,11 @@ export const min: {
    * @param that - The second `BigDecimal`.
    *
    * @example
+   * ```ts
    * import { min, unsafeFromString } from "effect/BigDecimal"
    *
    * assert.deepStrictEqual(min(unsafeFromString("2"), unsafeFromString("3")), unsafeFromString("2"))
+   * ```
    *
    * @since 2.0.0
    * @category math
@@ -1098,9 +1173,11 @@ export const min: {
  * @param that - The second `BigDecimal`.
  *
  * @example
+ * ```ts
  * import { max, unsafeFromString } from "effect/BigDecimal"
  *
  * assert.deepStrictEqual(max(unsafeFromString("2"), unsafeFromString("3")), unsafeFromString("3"))
+ * ```
  *
  * @since 2.0.0
  * @category math
@@ -1113,9 +1190,11 @@ export const max: {
    * @param that - The second `BigDecimal`.
    *
    * @example
+   * ```ts
    * import { max, unsafeFromString } from "effect/BigDecimal"
    *
    * assert.deepStrictEqual(max(unsafeFromString("2"), unsafeFromString("3")), unsafeFromString("3"))
+   * ```
    *
    * @since 2.0.0
    * @category math
@@ -1128,9 +1207,11 @@ export const max: {
    * @param that - The second `BigDecimal`.
    *
    * @example
+   * ```ts
    * import { max, unsafeFromString } from "effect/BigDecimal"
    *
    * assert.deepStrictEqual(max(unsafeFromString("2"), unsafeFromString("3")), unsafeFromString("3"))
+   * ```
    *
    * @since 2.0.0
    * @category math
@@ -1144,11 +1225,13 @@ export const max: {
  * @param n - The `BigDecimal` to determine the sign of.
  *
  * @example
+ * ```ts
  * import { sign, unsafeFromString } from "effect/BigDecimal"
  *
  * assert.deepStrictEqual(sign(unsafeFromString("-5")), -1)
  * assert.deepStrictEqual(sign(unsafeFromString("0")), 0)
  * assert.deepStrictEqual(sign(unsafeFromString("5")), 1)
+ * ```
  *
  * @since 2.0.0
  * @category math
@@ -1161,11 +1244,13 @@ export const sign = (n: BigDecimal): Ordering => n.value === bigint0 ? 0 : n.val
  * @param n - The `BigDecimal` to determine the absolute value of.
  *
  * @example
+ * ```ts
  * import { abs, unsafeFromString } from "effect/BigDecimal"
  *
  * assert.deepStrictEqual(abs(unsafeFromString("-5")), unsafeFromString("5"))
  * assert.deepStrictEqual(abs(unsafeFromString("0")), unsafeFromString("0"))
  * assert.deepStrictEqual(abs(unsafeFromString("5")), unsafeFromString("5"))
+ * ```
  *
  * @since 2.0.0
  * @category math
@@ -1178,10 +1263,12 @@ export const abs = (n: BigDecimal): BigDecimal => n.value < bigint0 ? make(-n.va
  * @param n - The `BigDecimal` to negate.
  *
  * @example
+ * ```ts
  * import { negate, unsafeFromString } from "effect/BigDecimal"
  *
  * assert.deepStrictEqual(negate(unsafeFromString("3")), unsafeFromString("-3"))
  * assert.deepStrictEqual(negate(unsafeFromString("-6")), unsafeFromString("6"))
+ * ```
  *
  * @since 2.0.0
  * @category math
@@ -1197,11 +1284,13 @@ export const negate = (n: BigDecimal): BigDecimal => make(-n.value, n.scale)
  * @param divisor - The divisor.
  *
  * @example
+ * ```ts
  * import { BigDecimal, Option } from "effect"
  *
  * assert.deepStrictEqual(BigDecimal.remainder(BigDecimal.unsafeFromString("2"), BigDecimal.unsafeFromString("2")), Option.some(BigDecimal.unsafeFromString("0")))
  * assert.deepStrictEqual(BigDecimal.remainder(BigDecimal.unsafeFromString("3"), BigDecimal.unsafeFromString("2")), Option.some(BigDecimal.unsafeFromString("1")))
  * assert.deepStrictEqual(BigDecimal.remainder(BigDecimal.unsafeFromString("-4"), BigDecimal.unsafeFromString("2")), Option.some(BigDecimal.unsafeFromString("0")))
+ * ```
  *
  * @since 2.0.0
  * @category math
@@ -1216,11 +1305,13 @@ export const remainder: {
    * @param divisor - The divisor.
    *
    * @example
+   * ```ts
    * import { BigDecimal, Option } from "effect"
    *
    * assert.deepStrictEqual(BigDecimal.remainder(BigDecimal.unsafeFromString("2"), BigDecimal.unsafeFromString("2")), Option.some(BigDecimal.unsafeFromString("0")))
    * assert.deepStrictEqual(BigDecimal.remainder(BigDecimal.unsafeFromString("3"), BigDecimal.unsafeFromString("2")), Option.some(BigDecimal.unsafeFromString("1")))
    * assert.deepStrictEqual(BigDecimal.remainder(BigDecimal.unsafeFromString("-4"), BigDecimal.unsafeFromString("2")), Option.some(BigDecimal.unsafeFromString("0")))
+   * ```
    *
    * @since 2.0.0
    * @category math
@@ -1235,11 +1326,13 @@ export const remainder: {
    * @param divisor - The divisor.
    *
    * @example
+   * ```ts
    * import { BigDecimal, Option } from "effect"
    *
    * assert.deepStrictEqual(BigDecimal.remainder(BigDecimal.unsafeFromString("2"), BigDecimal.unsafeFromString("2")), Option.some(BigDecimal.unsafeFromString("0")))
    * assert.deepStrictEqual(BigDecimal.remainder(BigDecimal.unsafeFromString("3"), BigDecimal.unsafeFromString("2")), Option.some(BigDecimal.unsafeFromString("1")))
    * assert.deepStrictEqual(BigDecimal.remainder(BigDecimal.unsafeFromString("-4"), BigDecimal.unsafeFromString("2")), Option.some(BigDecimal.unsafeFromString("0")))
+   * ```
    *
    * @since 2.0.0
    * @category math
@@ -1263,11 +1356,13 @@ export const remainder: {
  * @param divisor - The divisor.
  *
  * @example
+ * ```ts
  * import { unsafeRemainder, unsafeFromString } from "effect/BigDecimal"
  *
  * assert.deepStrictEqual(unsafeRemainder(unsafeFromString("2"), unsafeFromString("2")), unsafeFromString("0"))
  * assert.deepStrictEqual(unsafeRemainder(unsafeFromString("3"), unsafeFromString("2")), unsafeFromString("1"))
  * assert.deepStrictEqual(unsafeRemainder(unsafeFromString("-4"), unsafeFromString("2")), unsafeFromString("0"))
+ * ```
  *
  * @since 2.0.0
  * @category math
@@ -1282,11 +1377,13 @@ export const unsafeRemainder: {
    * @param divisor - The divisor.
    *
    * @example
+   * ```ts
    * import { unsafeRemainder, unsafeFromString } from "effect/BigDecimal"
    *
    * assert.deepStrictEqual(unsafeRemainder(unsafeFromString("2"), unsafeFromString("2")), unsafeFromString("0"))
    * assert.deepStrictEqual(unsafeRemainder(unsafeFromString("3"), unsafeFromString("2")), unsafeFromString("1"))
    * assert.deepStrictEqual(unsafeRemainder(unsafeFromString("-4"), unsafeFromString("2")), unsafeFromString("0"))
+   * ```
    *
    * @since 2.0.0
    * @category math
@@ -1301,11 +1398,13 @@ export const unsafeRemainder: {
    * @param divisor - The divisor.
    *
    * @example
+   * ```ts
    * import { unsafeRemainder, unsafeFromString } from "effect/BigDecimal"
    *
    * assert.deepStrictEqual(unsafeRemainder(unsafeFromString("2"), unsafeFromString("2")), unsafeFromString("0"))
    * assert.deepStrictEqual(unsafeRemainder(unsafeFromString("3"), unsafeFromString("2")), unsafeFromString("1"))
    * assert.deepStrictEqual(unsafeRemainder(unsafeFromString("-4"), unsafeFromString("2")), unsafeFromString("0"))
+   * ```
    *
    * @since 2.0.0
    * @category math
@@ -1375,20 +1474,73 @@ export const fromBigInt = (n: bigint): BigDecimal => make(n, 0)
  * It is not recommended to convert a floating point number to a decimal directly,
  * as the floating point representation may be unexpected.
  *
+ * Throws a `RangeError` if the number is not finite (`NaN`, `+Infinity` or `-Infinity`).
+ *
  * @param value - The `number` value to create a `BigDecimal` from.
  *
  * @example
+ * ```ts
  * import { fromNumber, make } from "effect/BigDecimal"
  *
  * assert.deepStrictEqual(fromNumber(123), make(123n, 0))
  * assert.deepStrictEqual(fromNumber(123.456), make(123456n, 3))
+ * ```
+ *
+ * @since 3.11.0
+ * @category constructors
+ */
+export const unsafeFromNumber = (n: number): BigDecimal =>
+  Option.getOrThrowWith(safeFromNumber(n), () => new RangeError(`Number must be finite, got ${n}`))
+
+/**
+ * Creates a `BigDecimal` from a `number` value.
+ *
+ * It is not recommended to convert a floating point number to a decimal directly,
+ * as the floating point representation may be unexpected.
+ *
+ * Throws a `RangeError` if the number is not finite (`NaN`, `+Infinity` or `-Infinity`).
+ *
+ * @param value - The `number` value to create a `BigDecimal` from.
  *
  * @since 2.0.0
  * @category constructors
+ * @deprecated Use {@link unsafeFromNumber} instead.
  */
-export const fromNumber = (n: number): BigDecimal => {
-  const [lead, trail = ""] = `${n}`.split(".")
-  return make(BigInt(`${lead}${trail}`), trail.length)
+export const fromNumber: (n: number) => BigDecimal = unsafeFromNumber
+
+/**
+ * Creates a `BigDecimal` from a `number` value.
+ *
+ * It is not recommended to convert a floating point number to a decimal directly,
+ * as the floating point representation may be unexpected.
+ *
+ * Returns `None` if the number is not finite (`NaN`, `+Infinity` or `-Infinity`).
+ *
+ * @param n - The `number` value to create a `BigDecimal` from.
+ *
+ * @example
+ * import { BigDecimal, Option } from "effect"
+ *
+ * assert.deepStrictEqual(BigDecimal.safeFromNumber(123), Option.some(BigDecimal.make(123n, 0)))
+ * assert.deepStrictEqual(BigDecimal.safeFromNumber(123.456), Option.some(BigDecimal.make(123456n, 3)))
+ * assert.deepStrictEqual(BigDecimal.safeFromNumber(Infinity), Option.none())
+ *
+ * @since 3.11.0
+ * @category constructors
+ */
+export const safeFromNumber = (n: number): Option.Option<BigDecimal> => {
+  // TODO: Rename this to `fromNumber` after removing the current, unsafe implementation of `fromNumber`.
+  if (!Number.isFinite(n)) {
+    return Option.none()
+  }
+
+  const string = `${n}`
+  if (string.includes("e")) {
+    return fromString(string)
+  }
+
+  const [lead, trail = ""] = string.split(".")
+  return Option.some(make(BigInt(`${lead}${trail}`), trail.length))
 }
 
 /**
@@ -1397,36 +1549,56 @@ export const fromNumber = (n: number): BigDecimal => {
  * @param s - The `string` to parse.
  *
  * @example
+ * ```ts
  * import { BigDecimal, Option } from "effect"
  *
  * assert.deepStrictEqual(BigDecimal.fromString("123"), Option.some(BigDecimal.make(123n, 0)))
  * assert.deepStrictEqual(BigDecimal.fromString("123.456"), Option.some(BigDecimal.make(123456n, 3)))
  * assert.deepStrictEqual(BigDecimal.fromString("123.abc"), Option.none())
+ * ```
  *
  * @since 2.0.0
  * @category constructors
  */
 export const fromString = (s: string): Option.Option<BigDecimal> => {
-  let digits: string
-  let scale: number
+  if (s === "") {
+    return Option.some(zero)
+  }
 
-  const dot = s.search(/\./)
+  let base: string
+  let exp: number
+  const seperator = s.search(/[eE]/)
+  if (seperator !== -1) {
+    const trail = s.slice(seperator + 1)
+    base = s.slice(0, seperator)
+    exp = Number(trail)
+    if (base === "" || !Number.isSafeInteger(exp) || !FINITE_INT_REGEX.test(trail)) {
+      return Option.none()
+    }
+  } else {
+    base = s
+    exp = 0
+  }
+
+  let digits: string
+  let offset: number
+  const dot = base.search(/\./)
   if (dot !== -1) {
-    const lead = s.slice(0, dot)
-    const trail = s.slice(dot + 1)
+    const lead = base.slice(0, dot)
+    const trail = base.slice(dot + 1)
     digits = `${lead}${trail}`
-    scale = trail.length
+    offset = trail.length
   } else {
-    digits = s
-    scale = 0
+    digits = base
+    offset = 0
   }
 
-  if (digits === "") {
-    // TODO: This mimics the BigInt constructor behavior. Should this be `Option.none()`?
-    return Option.some(zero)
+  if (!FINITE_INT_REGEX.test(digits)) {
+    return Option.none()
   }
 
-  if (!/^(?:\+|-)?\d+$/.test(digits)) {
+  const scale = offset - exp
+  if (!Number.isSafeInteger(scale)) {
     return Option.none()
   }
 
@@ -1439,11 +1611,13 @@ export const fromString = (s: string): Option.Option<BigDecimal> => {
  * @param s - The `string` to parse.
  *
  * @example
+ * ```ts
  * import { unsafeFromString, make } from "effect/BigDecimal"
  *
  * assert.deepStrictEqual(unsafeFromString("123"), make(123n, 0))
  * assert.deepStrictEqual(unsafeFromString("123.456"), make(123456n, 3))
  * assert.throws(() => unsafeFromString("123.abc"))
+ * ```
  *
  * @since 2.0.0
  * @category constructors
@@ -1454,30 +1628,40 @@ export const unsafeFromString = (s: string): BigDecimal =>
 /**
  * Formats a given `BigDecimal` as a `string`.
  *
- * @param normalized - The `BigDecimal` to format.
+ * If the scale of the `BigDecimal` is greater than or equal to 16, the `BigDecimal` will
+ * be formatted in scientific notation.
+ *
+ * @param n - The `BigDecimal` to format.
  *
  * @example
+ * ```ts
  * import { format, unsafeFromString } from "effect/BigDecimal"
  *
  * assert.deepStrictEqual(format(unsafeFromString("-5")), "-5")
  * assert.deepStrictEqual(format(unsafeFromString("123.456")), "123.456")
  * assert.deepStrictEqual(format(unsafeFromString("-0.00000123")), "-0.00000123")
+ * ```
  *
  * @since 2.0.0
  * @category conversions
  */
 export const format = (n: BigDecimal): string => {
-  const negative = n.value < bigint0
-  const absolute = negative ? `${n.value}`.substring(1) : `${n.value}`
+  const normalized = normalize(n)
+  if (Math.abs(normalized.scale) >= 16) {
+    return toExponential(normalized)
+  }
+
+  const negative = normalized.value < bigint0
+  const absolute = negative ? `${normalized.value}`.substring(1) : `${normalized.value}`
 
   let before: string
   let after: string
 
-  if (n.scale >= absolute.length) {
+  if (normalized.scale >= absolute.length) {
     before = "0"
-    after = "0".repeat(n.scale - absolute.length) + absolute
+    after = "0".repeat(normalized.scale - absolute.length) + absolute
   } else {
-    const location = absolute.length - n.scale
+    const location = absolute.length - normalized.scale
     if (location > absolute.length) {
       const zeros = location - absolute.length
       before = `${absolute}${"0".repeat(zeros)}`
@@ -1492,6 +1676,38 @@ export const format = (n: BigDecimal): string => {
   return negative ? `-${complete}` : complete
 }
 
+/**
+ * Formats a given `BigDecimal` as a `string` in scientific notation.
+ *
+ * @param n - The `BigDecimal` to format.
+ *
+ * @example
+ * import { toExponential, make } from "effect/BigDecimal"
+ *
+ * assert.deepStrictEqual(toExponential(make(123456n, -5)), "1.23456e+10")
+ *
+ * @since 3.11.0
+ * @category conversions
+ */
+export const toExponential = (n: BigDecimal): string => {
+  if (isZero(n)) {
+    return "0e+0"
+  }
+
+  const normalized = normalize(n)
+  const digits = `${abs(normalized).value}`
+  const head = digits.slice(0, 1)
+  const tail = digits.slice(1)
+
+  let output = `${isNegative(normalized) ? "-" : ""}${head}`
+  if (tail !== "") {
+    output += `.${tail}`
+  }
+
+  const exp = tail.length - normalized.scale
+  return `${output}e${exp >= 0 ? "+" : ""}${exp}`
+}
+
 /**
  * Converts a `BigDecimal` to a `number`.
  *
@@ -1500,9 +1716,11 @@ export const format = (n: BigDecimal): string => {
  * @param n - The `BigDecimal` to convert.
  *
  * @example
+ * ```ts
  * import { unsafeToNumber, unsafeFromString } from "effect/BigDecimal"
  *
  * assert.deepStrictEqual(unsafeToNumber(unsafeFromString("123.456")), 123.456)
+ * ```
  *
  * @since 2.0.0
  * @category conversions
@@ -1515,11 +1733,13 @@ export const unsafeToNumber = (n: BigDecimal): number => Number(format(n))
  * @param n - The `BigDecimal` to check.
  *
  * @example
+ * ```ts
  * import { isInteger, unsafeFromString } from "effect/BigDecimal"
  *
  * assert.deepStrictEqual(isInteger(unsafeFromString("0")), true)
  * assert.deepStrictEqual(isInteger(unsafeFromString("1")), true)
  * assert.deepStrictEqual(isInteger(unsafeFromString("1.1")), false)
+ * ```
  *
  * @since 2.0.0
  * @category predicates
@@ -1532,10 +1752,12 @@ export const isInteger = (n: BigDecimal): boolean => normalize(n).scale <= 0
  * @param n - The `BigDecimal` to check.
  *
  * @example
+ * ```ts
  * import { isZero, unsafeFromString } from "effect/BigDecimal"
  *
  * assert.deepStrictEqual(isZero(unsafeFromString("0")), true)
  * assert.deepStrictEqual(isZero(unsafeFromString("1")), false)
+ * ```
  *
  * @since 2.0.0
  * @category predicates
@@ -1548,11 +1770,13 @@ export const isZero = (n: BigDecimal): boolean => n.value === bigint0
  * @param n - The `BigDecimal` to check.
  *
  * @example
+ * ```ts
  * import { isNegative, unsafeFromString } from "effect/BigDecimal"
  *
  * assert.deepStrictEqual(isNegative(unsafeFromString("-1")), true)
  * assert.deepStrictEqual(isNegative(unsafeFromString("0")), false)
  * assert.deepStrictEqual(isNegative(unsafeFromString("1")), false)
+ * ```
  *
  * @since 2.0.0
  * @category predicates
@@ -1565,11 +1789,13 @@ export const isNegative = (n: BigDecimal): boolean => n.value < bigint0
  * @param n - The `BigDecimal` to check.
  *
  * @example
+ * ```ts
  * import { isPositive, unsafeFromString } from "effect/BigDecimal"
  *
  * assert.deepStrictEqual(isPositive(unsafeFromString("-1")), false)
  * assert.deepStrictEqual(isPositive(unsafeFromString("0")), false)
  * assert.deepStrictEqual(isPositive(unsafeFromString("1")), true)
+ * ```
  *
  * @since 2.0.0
  * @category predicates