effect 4.0.0-beta.4 → 4.0.0-beta.41

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"
@@ -143,6 +144,7 @@ const bigint0 = BigInt(0)
 const bigint1 = BigInt(1)
 const bigint10 = BigInt(10)
 const zero = makeNormalizedUnsafe(bigint0, 0)
+const one = makeNormalizedUnsafe(bigint1, 0)
 
 /**
  * Normalizes a given `BigDecimal` by removing trailing zeros.
@@ -355,6 +357,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 +444,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 +620,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 +632,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 +660,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 +672,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 +712,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 +1569,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 +1581,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 +1606,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 +1618,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 +1655,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 +1908,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 +1917,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 +1946,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 +1954,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 +1981,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 +2002,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 +2030,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}`))
 }
 
 /**