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

package/dist/BigDecimal.js

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