effect 4.0.0-beta.5 → 4.0.0-beta.51

package/src/BigDecimal.ts

@@ -19,6 +19,7 @@ import * as Equ from "./Equivalence.ts"
 import { dual } from "./Function.ts"
 import * as Hash from "./Hash.ts"
 import { type Inspectable, NodeInspectSymbol } from "./Inspectable.ts"
+import * as Option from "./Option.ts"
 import * as order from "./Order.ts"
 import type { Ordering } from "./Ordering.ts"
 import { type Pipeable, pipeArguments } from "./Pipeable.ts"
@@ -141,8 +142,13 @@ export const makeNormalizedUnsafe = (value: bigint, scale: number): BigDecimal =
 
 const bigint0 = BigInt(0)
 const bigint1 = BigInt(1)
+const bigint_1 = BigInt(-1)
+const bigint2 = BigInt(2)
+const bigint5 = BigInt(5)
+const bigint_5 = BigInt(-5)
 const bigint10 = BigInt(10)
 const zero = makeNormalizedUnsafe(bigint0, 0)
+const one = makeNormalizedUnsafe(bigint1, 0)
 
 /**
  * Normalizes a given `BigDecimal` by removing trailing zeros.
@@ -355,6 +361,31 @@ export const sum: {
   return make(self.value + that.value, self.scale)
 })
 
+/**
+ * Takes an `Iterable` of `BigDecimal`s and returns their sum as a single `BigDecimal`.
+ *
+ * @example
+ * ```ts
+ * import { fromStringUnsafe, sumAll } from "effect/BigDecimal"
+ * import * as assert from "node:assert"
+ *
+ * assert.deepStrictEqual(
+ *   sumAll([fromStringUnsafe("2"), fromStringUnsafe("3"), fromStringUnsafe("4")]),
+ *   fromStringUnsafe("9")
+ * )
+ * ```
+ *
+ * @since 4.0.0
+ * @category math
+ */
+export const sumAll = (collection: Iterable<BigDecimal>): BigDecimal => {
+  let out: BigDecimal = zero
+  for (const n of collection) {
+    out = sum(out, n)
+  }
+  return out
+}
+
 /**
  * Provides a multiplication operation on `BigDecimal`s.
  *
@@ -417,6 +448,34 @@ export const multiply: {
   return make(self.value * that.value, self.scale + that.scale)
 })
 
+/**
+ * Takes an `Iterable` of `BigDecimal`s and returns their multiplication as a single `BigDecimal`.
+ *
+ * @example
+ * ```ts
+ * import { fromStringUnsafe, multiplyAll } from "effect/BigDecimal"
+ * import * as assert from "node:assert"
+ *
+ * assert.deepStrictEqual(
+ *   multiplyAll([fromStringUnsafe("2"), fromStringUnsafe("3"), fromStringUnsafe("4")]),
+ *   fromStringUnsafe("24")
+ * )
+ * ```
+ *
+ * @since 4.0.0
+ * @category math
+ */
+export const multiplyAll = (collection: Iterable<BigDecimal>): BigDecimal => {
+  let out: BigDecimal = one
+  for (const n of collection) {
+    if (n.value === bigint0) {
+      return zero
+    }
+    out = multiply(out, n)
+  }
+  return out
+}
+
 /**
  * Provides a subtraction operation on `BigDecimal`s.
  *
@@ -565,11 +624,11 @@ export const roundTerminal = (n: bigint): bigint => {
  * 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 divisor is `0`, the result will be `undefined`.
+ * If the divisor is `0`, the result will be `Option.none()`.
  *
  * @example
  * ```ts
- * import { BigDecimal } from "effect"
+ * import { BigDecimal, Option } from "effect"
  * import * as assert from "node:assert"
  *
  * assert.deepStrictEqual(
@@ -577,21 +636,21 @@ export const roundTerminal = (n: bigint): bigint => {
  *     BigDecimal.fromStringUnsafe("6"),
  *     BigDecimal.fromStringUnsafe("3")
  *   ),
- *   BigDecimal.fromStringUnsafe("2")
+ *   Option.some(BigDecimal.fromStringUnsafe("2"))
  * )
  * assert.deepStrictEqual(
  *   BigDecimal.divide(
  *     BigDecimal.fromStringUnsafe("6"),
  *     BigDecimal.fromStringUnsafe("4")
  *   ),
- *   BigDecimal.fromStringUnsafe("1.5")
+ *   Option.some(BigDecimal.fromStringUnsafe("1.5"))
  * )
  * assert.deepStrictEqual(
  *   BigDecimal.divide(
  *     BigDecimal.fromStringUnsafe("6"),
  *     BigDecimal.fromStringUnsafe("0")
  *   ),
- *   undefined
+ *   Option.none()
  * )
  * ```
  *
@@ -605,11 +664,11 @@ export const divide: {
    * 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 divisor is `0`, the result will be `undefined`.
+   * If the divisor is `0`, the result will be `Option.none()`.
    *
    * @example
    * ```ts
-   * import { BigDecimal } from "effect"
+   * import { BigDecimal, Option } from "effect"
    * import * as assert from "node:assert"
    *
    * assert.deepStrictEqual(
@@ -617,39 +676,39 @@ export const divide: {
    *     BigDecimal.fromStringUnsafe("6"),
    *     BigDecimal.fromStringUnsafe("3")
    *   ),
-   *   BigDecimal.fromStringUnsafe("2")
+   *   Option.some(BigDecimal.fromStringUnsafe("2"))
    * )
    * assert.deepStrictEqual(
    *   BigDecimal.divide(
    *     BigDecimal.fromStringUnsafe("6"),
    *     BigDecimal.fromStringUnsafe("4")
    *   ),
-   *   BigDecimal.fromStringUnsafe("1.5")
+   *   Option.some(BigDecimal.fromStringUnsafe("1.5"))
    * )
    * assert.deepStrictEqual(
    *   BigDecimal.divide(
    *     BigDecimal.fromStringUnsafe("6"),
    *     BigDecimal.fromStringUnsafe("0")
    *   ),
-   *   undefined
+   *   Option.none()
    * )
    * ```
    *
    * @since 2.0.0
    * @category math
    */
-  (that: BigDecimal): (self: BigDecimal) => BigDecimal | undefined
+  (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 divisor is `0`, the result will be `undefined`.
+   * If the divisor is `0`, the result will be `Option.none()`.
    *
    * @example
    * ```ts
-   * import { BigDecimal } from "effect"
+   * import { BigDecimal, Option } from "effect"
    * import * as assert from "node:assert"
    *
    * assert.deepStrictEqual(
@@ -657,43 +716,43 @@ export const divide: {
    *     BigDecimal.fromStringUnsafe("6"),
    *     BigDecimal.fromStringUnsafe("3")
    *   ),
-   *   BigDecimal.fromStringUnsafe("2")
+   *   Option.some(BigDecimal.fromStringUnsafe("2"))
    * )
    * assert.deepStrictEqual(
    *   BigDecimal.divide(
    *     BigDecimal.fromStringUnsafe("6"),
    *     BigDecimal.fromStringUnsafe("4")
    *   ),
-   *   BigDecimal.fromStringUnsafe("1.5")
+   *   Option.some(BigDecimal.fromStringUnsafe("1.5"))
    * )
    * assert.deepStrictEqual(
    *   BigDecimal.divide(
    *     BigDecimal.fromStringUnsafe("6"),
    *     BigDecimal.fromStringUnsafe("0")
    *   ),
-   *   undefined
+   *   Option.none()
    * )
    * ```
    *
    * @since 2.0.0
    * @category math
    */
-  (self: BigDecimal, that: BigDecimal): BigDecimal | undefined
-} = dual(2, (self: BigDecimal, that: BigDecimal): BigDecimal | undefined => {
+  (self: BigDecimal, that: BigDecimal): Option.Option<BigDecimal>
+} = dual(2, (self: BigDecimal, that: BigDecimal): Option.Option<BigDecimal> => {
   if (that.value === bigint0) {
-    return undefined
+    return Option.none()
   }
 
   if (self.value === bigint0) {
-    return zero
+    return Option.some(zero)
   }
 
   const scale = self.scale - that.scale
   if (self.value === that.value) {
-    return make(bigint1, scale)
+    return Option.some(make(bigint1, scale))
   }
 
-  return divideWithPrecision(self.value, that.value, scale, DEFAULT_PRECISION)
+  return Option.some(divideWithPrecision(self.value, that.value, scale, DEFAULT_PRECISION))
 })
 
 /**
@@ -1514,11 +1573,11 @@ export const negate = (n: BigDecimal): BigDecimal => make(-n.value, n.scale)
 /**
  * Returns the remainder left over when one operand is divided by a second operand.
  *
- * If the divisor is `0`, the result will be `undefined`.
+ * If the divisor is `0`, the result will be `Option.none()`.
  *
  * @example
  * ```ts
- * import { BigDecimal } from "effect"
+ * import { BigDecimal, Option } from "effect"
  * import * as assert from "node:assert"
  *
  * assert.deepStrictEqual(
@@ -1526,21 +1585,21 @@ export const negate = (n: BigDecimal): BigDecimal => make(-n.value, n.scale)
  *     BigDecimal.fromStringUnsafe("2"),
  *     BigDecimal.fromStringUnsafe("2")
  *   ),
- *   BigDecimal.fromStringUnsafe("0")
+ *   Option.some(BigDecimal.fromStringUnsafe("0"))
  * )
  * assert.deepStrictEqual(
  *   BigDecimal.remainder(
  *     BigDecimal.fromStringUnsafe("3"),
  *     BigDecimal.fromStringUnsafe("2")
  *   ),
- *   BigDecimal.fromStringUnsafe("1")
+ *   Option.some(BigDecimal.fromStringUnsafe("1"))
  * )
  * assert.deepStrictEqual(
  *   BigDecimal.remainder(
  *     BigDecimal.fromStringUnsafe("-4"),
  *     BigDecimal.fromStringUnsafe("2")
  *   ),
- *   BigDecimal.fromStringUnsafe("0")
+ *   Option.some(BigDecimal.fromStringUnsafe("0"))
  * )
  * ```
  *
@@ -1551,11 +1610,11 @@ export const remainder: {
   /**
    * Returns the remainder left over when one operand is divided by a second operand.
    *
-   * If the divisor is `0`, the result will be `undefined`.
+   * If the divisor is `0`, the result will be `Option.none()`.
    *
    * @example
    * ```ts
-   * import { BigDecimal } from "effect"
+   * import { BigDecimal, Option } from "effect"
    * import * as assert from "node:assert"
    *
    * assert.deepStrictEqual(
@@ -1563,36 +1622,36 @@ export const remainder: {
    *     BigDecimal.fromStringUnsafe("2"),
    *     BigDecimal.fromStringUnsafe("2")
    *   ),
-   *   BigDecimal.fromStringUnsafe("0")
+   *   Option.some(BigDecimal.fromStringUnsafe("0"))
    * )
    * assert.deepStrictEqual(
    *   BigDecimal.remainder(
    *     BigDecimal.fromStringUnsafe("3"),
    *     BigDecimal.fromStringUnsafe("2")
    *   ),
-   *   BigDecimal.fromStringUnsafe("1")
+   *   Option.some(BigDecimal.fromStringUnsafe("1"))
    * )
    * assert.deepStrictEqual(
    *   BigDecimal.remainder(
    *     BigDecimal.fromStringUnsafe("-4"),
    *     BigDecimal.fromStringUnsafe("2")
    *   ),
-   *   BigDecimal.fromStringUnsafe("0")
+   *   Option.some(BigDecimal.fromStringUnsafe("0"))
    * )
    * ```
    *
    * @since 2.0.0
    * @category math
    */
-  (divisor: BigDecimal): (self: BigDecimal) => BigDecimal | undefined
+  (divisor: BigDecimal): (self: BigDecimal) => Option.Option<BigDecimal>
   /**
    * Returns the remainder left over when one operand is divided by a second operand.
    *
-   * If the divisor is `0`, the result will be `undefined`.
+   * If the divisor is `0`, the result will be `Option.none()`.
    *
    * @example
    * ```ts
-   * import { BigDecimal } from "effect"
+   * import { BigDecimal, Option } from "effect"
    * import * as assert from "node:assert"
    *
    * assert.deepStrictEqual(
@@ -1600,35 +1659,35 @@ export const remainder: {
    *     BigDecimal.fromStringUnsafe("2"),
    *     BigDecimal.fromStringUnsafe("2")
    *   ),
-   *   BigDecimal.fromStringUnsafe("0")
+   *   Option.some(BigDecimal.fromStringUnsafe("0"))
    * )
    * assert.deepStrictEqual(
    *   BigDecimal.remainder(
    *     BigDecimal.fromStringUnsafe("3"),
    *     BigDecimal.fromStringUnsafe("2")
    *   ),
-   *   BigDecimal.fromStringUnsafe("1")
+   *   Option.some(BigDecimal.fromStringUnsafe("1"))
    * )
    * assert.deepStrictEqual(
    *   BigDecimal.remainder(
    *     BigDecimal.fromStringUnsafe("-4"),
    *     BigDecimal.fromStringUnsafe("2")
    *   ),
-   *   BigDecimal.fromStringUnsafe("0")
+   *   Option.some(BigDecimal.fromStringUnsafe("0"))
    * )
    * ```
    *
    * @since 2.0.0
    * @category math
    */
-  (self: BigDecimal, divisor: BigDecimal): BigDecimal | undefined
-} = dual(2, (self: BigDecimal, divisor: BigDecimal): BigDecimal | undefined => {
+  (self: BigDecimal, divisor: BigDecimal): Option.Option<BigDecimal>
+} = dual(2, (self: BigDecimal, divisor: BigDecimal): Option.Option<BigDecimal> => {
   if (divisor.value === bigint0) {
-    return undefined
+    return Option.none()
   }
 
   const max = Math.max(self.scale, divisor.scale)
-  return make(scale(self, max).value % scale(divisor, max).value, max)
+  return Option.some(make(scale(self, max).value % scale(divisor, max).value, max))
 })
 
 /**
@@ -1853,9 +1912,7 @@ export const fromBigInt = (n: bigint): BigDecimal => make(n, 0)
  * @category constructors
  */
 export const fromNumberUnsafe = (n: number): BigDecimal => {
-  const out = fromNumber(n)
-  if (out) return out
-  throw new RangeError(`Number must be finite, got ${n}`)
+  return Option.getOrThrowWith(fromNumber(n), () => new RangeError(`Number must be finite, got ${n}`))
 }
 
 /**
@@ -1864,27 +1921,27 @@ export const fromNumberUnsafe = (n: number): BigDecimal => {
  * It is not recommended to convert a floating point number to a decimal directly,
  * as the floating point representation may be unexpected.
  *
- * Returns `undefined` for `NaN`, `+Infinity` or `-Infinity`.
+ * Returns `Option.none()` for `NaN`, `+Infinity` or `-Infinity`.
  *
  * @example
  * ```ts
- * import { BigDecimal } from "effect"
+ * import { BigDecimal, Option } from "effect"
  * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(BigDecimal.fromNumber(123), BigDecimal.make(123n, 0))
+ * assert.deepStrictEqual(BigDecimal.fromNumber(123), Option.some(BigDecimal.make(123n, 0)))
  * assert.deepStrictEqual(
  *   BigDecimal.fromNumber(123.456),
- *   BigDecimal.make(123456n, 3)
+ *   Option.some(BigDecimal.make(123456n, 3))
  * )
- * assert.deepStrictEqual(BigDecimal.fromNumber(Infinity), undefined)
+ * assert.deepStrictEqual(BigDecimal.fromNumber(Infinity), Option.none())
  * ```
  *
  * @since 4.0.0
  * @category constructors
  */
-export const fromNumber = (n: number): BigDecimal | undefined => {
+export const fromNumber = (n: number): Option.Option<BigDecimal> => {
   if (!Number.isFinite(n)) {
-    return undefined
+    return Option.none()
   }
 
   const string = `${n}`
@@ -1893,7 +1950,7 @@ export const fromNumber = (n: number): BigDecimal | undefined => {
   }
 
   const [lead, trail = ""] = string.split(".")
-  return make(BigInt(`${lead}${trail}`), trail.length)
+  return Option.some(make(BigInt(`${lead}${trail}`), trail.length))
 }
 
 /**
@@ -1901,23 +1958,23 @@ export const fromNumber = (n: number): BigDecimal | undefined => {
  *
  * @example
  * ```ts
- * import { BigDecimal } from "effect"
+ * import { BigDecimal, Option } from "effect"
  * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(BigDecimal.fromString("123"), BigDecimal.make(123n, 0))
+ * assert.deepStrictEqual(BigDecimal.fromString("123"), Option.some(BigDecimal.make(123n, 0)))
  * assert.deepStrictEqual(
  *   BigDecimal.fromString("123.456"),
- *   BigDecimal.make(123456n, 3)
+ *   Option.some(BigDecimal.make(123456n, 3))
  * )
- * assert.deepStrictEqual(BigDecimal.fromString("123.abc"), undefined)
+ * assert.deepStrictEqual(BigDecimal.fromString("123.abc"), Option.none())
  * ```
  *
  * @since 2.0.0
  * @category constructors
  */
-export const fromString = (s: string): BigDecimal | undefined => {
+export const fromString = (s: string): Option.Option<BigDecimal> => {
   if (s === "") {
-    return zero
+    return Option.some(zero)
   }
 
   let base: string
@@ -1928,7 +1985,7 @@ export const fromString = (s: string): BigDecimal | undefined => {
     base = s.slice(0, seperator)
     exp = Number(trail)
     if (base === "" || !Number.isSafeInteger(exp) || !FINITE_INT_REGEXP.test(trail)) {
-      return undefined
+      return Option.none()
     }
   } else {
     base = s
@@ -1949,15 +2006,15 @@ export const fromString = (s: string): BigDecimal | undefined => {
   }
 
   if (!FINITE_INT_REGEXP.test(digits)) {
-    return undefined
+    return Option.none()
   }
 
   const scale = offset - exp
   if (!Number.isSafeInteger(scale)) {
-    return undefined
+    return Option.none()
   }
 
-  return make(BigInt(digits), scale)
+  return Option.some(make(BigInt(digits), scale))
 }
 
 /**
@@ -1977,9 +2034,7 @@ export const fromString = (s: string): BigDecimal | undefined => {
  * @category constructors
  */
 export const fromStringUnsafe = (s: string): BigDecimal => {
-  const out = fromString(s)
-  if (out) return out
-  throw new Error(`Invalid numerical string: ${s}`)
+  return Option.getOrThrowWith(fromString(s), () => new Error(`Invalid numerical string: ${s}`))
 }
 
 /**
@@ -2269,32 +2324,32 @@ export const round: {
       return (isPositive(self) ? ceil(self, scale) : floor(self, scale))
 
     case "half-ceil":
-      return floor(sum(self, make(5n, scale + 1)), scale)
+      return floor(sum(self, make(bigint5, scale + 1)), scale)
 
     case "half-floor":
-      return ceil(sum(self, make(-5n, scale + 1)), scale)
+      return ceil(sum(self, make(bigint_5, scale + 1)), scale)
 
     case "half-to-zero":
       return isNegative(self)
-        ? floor(sum(self, make(5n, scale + 1)), scale)
-        : ceil(sum(self, make(-5n, scale + 1)), scale)
+        ? floor(sum(self, make(bigint5, scale + 1)), scale)
+        : ceil(sum(self, make(bigint_5, scale + 1)), scale)
 
     case "half-from-zero":
       return isNegative(self)
-        ? ceil(sum(self, make(-5n, scale + 1)), scale)
-        : floor(sum(self, make(5n, scale + 1)), scale)
+        ? ceil(sum(self, make(bigint_5, scale + 1)), scale)
+        : floor(sum(self, make(bigint5, scale + 1)), scale)
   }
 
-  const halfCeil = floor(sum(self, make(5n, scale + 1)), scale)
-  const halfFloor = ceil(sum(self, make(-5n, scale + 1)), scale)
+  const halfCeil = floor(sum(self, make(bigint5, scale + 1)), scale)
+  const halfFloor = ceil(sum(self, make(bigint_5, scale + 1)), scale)
   const digit = digitAt(halfCeil, scale)
 
   switch (mode) {
     case "half-even":
-      return equals(halfCeil, halfFloor) ? halfCeil : (digit % 2n === 0n) ? halfCeil : halfFloor
+      return equals(halfCeil, halfFloor) ? halfCeil : (digit % bigint2 === bigint0) ? halfCeil : halfFloor
 
     case "half-odd":
-      return equals(halfCeil, halfFloor) ? halfCeil : (digit % 2n === 0n) ? halfFloor : halfCeil
+      return equals(halfCeil, halfFloor) ? halfCeil : (digit % bigint2 === bigint0) ? halfFloor : halfCeil
   }
 })
 
@@ -2370,7 +2425,7 @@ export const truncate: {
   }
 
   // BigInt division truncates towards zero
-  return make(self.value / (10n ** BigInt(self.scale - scale)), scale)
+  return make(self.value / (bigint10 ** BigInt(self.scale - scale)), scale)
 })
 
 /**
@@ -2434,7 +2489,7 @@ export const ceil: {
   const truncated = truncate(self, scale)
 
   if (isPositive(self) && isLessThan(truncated, self)) {
-    return sum(truncated, make(1n, scale))
+    return sum(truncated, make(bigint1, scale))
   }
 
   return truncated
@@ -2466,11 +2521,11 @@ export const digitAt: {
   (self: BigDecimal, scale: number): bigint
 } = dual(2, (self: BigDecimal, scale: number): bigint => {
   if (self.scale < scale) {
-    return 0n
+    return bigint0
   }
 
-  const scaled = self.value / (10n ** BigInt(self.scale - scale))
-  return scaled % 10n
+  const scaled = self.value / (bigint10 ** BigInt(self.scale - scale))
+  return scaled % bigint10
 })
 
 /**
@@ -2543,7 +2598,7 @@ export const floor: {
   const truncated = truncate(self, scale)
 
   if (isNegative(self) && isGreaterThan(truncated, self)) {
-    return sum(truncated, make(-1n, scale))
+    return sum(truncated, make(bigint_1, scale))
   }
 
   return truncated