BigDecimal

In JavaScript, numbers are typically stored as 64-bit floating-point values. While floating-point numbers are fast and versatile, they can introduce small rounding errors. These are often hard to notice in everyday usage but can become problematic in areas like finance or statistics, where small inaccuracies may lead to larger discrepancies over time.

By using the BigDecimal module, you can avoid these issues and perform calculations with a higher degree of precision.

The BigDecimal data type can represent real numbers with a large number of decimal places, preventing the common errors of floating-point math (for example, 0.1 + 0.2 ≠ 0.3).

How BigDecimal Works

A BigDecimal represents a number using two components:

value: A BigInt that stores the digits of the number.
scale: A 64-bit integer that determines the position of the decimal point.

The number represented by a BigDecimal is calculated as: value x 10^-scale.

If scale is zero or positive, it specifies the number of digits to the right of the decimal point.
If scale is negative, the value is multiplied by 10 raised to the power of the negated scale.

For example:

A BigDecimal with value = 12345n and scale = 2 represents 123.45.
A BigDecimal with value = 12345n and scale = -2 represents 1234500.

The maximum precision is large but not infinite, limited to 2⁶³ decimal places.

Creating a BigDecimal

make

The make function creates a BigDecimal by specifying a BigInt value and a scale. The scale determines the number of digits to the right of the decimal point.

Example (Creating a BigDecimal with a Specified Scale)

1
import { BigDecimal } from "effect"
2

3
// Create a BigDecimal from a BigInt (1n) with a scale of 2
4
const decimal = BigDecimal.make(1n, 2)
5

6
console.log(decimal)
7
decimal // => BigDecimal.make(1n, 2)
8

9
// Convert the BigDecimal to a string
10
console.log(String(decimal))
11
String(decimal) // => "BigDecimal(0.01)"
12

13
// Format the BigDecimal as a standard decimal string
14
console.log(BigDecimal.format(decimal))
15
BigDecimal.format(decimal) // => "0.01"
16

17
// Convert the BigDecimal to exponential notation
18
console.log(BigDecimal.toExponential(decimal))
19
BigDecimal.toExponential(decimal) // => "1e-2"

fromBigInt

The fromBigInt function creates a BigDecimal from a bigint. The scale defaults to 0, meaning the number has no fractional part.

Example (Creating a BigDecimal from a BigInt)

1
import { BigDecimal } from "effect"
2

3
const decimal = BigDecimal.fromBigInt(10n)
4

5
console.log(decimal)
6
decimal // => BigDecimal.fromBigInt(10n)

fromString

Parses a numerical string into a BigDecimal. Returns an Option<BigDecimal>:

Some(BigDecimal) if the string is valid.
None if the string is invalid.

Example (Parsing a String into a BigDecimal)

1
import { BigDecimal, Option } from "effect"
2

3
const decimal = BigDecimal.fromString("0.02")
4

5
console.log(decimal)
6
decimal // => Option.some(BigDecimal.make(2n, 2))

unsafeFromString

The fromStringUnsafe function is a variant of fromString that throws an error if the input string is invalid. Use this only when you are confident that the input will always be valid.

Example (Unsafe Parsing of a String)

1
import { BigDecimal } from "effect"
2

3
const decimal = BigDecimal.fromStringUnsafe("0.02")
4

5
console.log(decimal)
6
decimal // => BigDecimal.make(2n, 2)

unsafeFromNumber

Creates a BigDecimal from a JavaScript number. Throws a RangeError for non-finite numbers (NaN, +Infinity, or -Infinity).

Example (Unsafe Parsing of a Number)

1
import { BigDecimal } from "effect"
2

3
console.log(BigDecimal.fromNumberUnsafe(123.456))
4
BigDecimal.fromNumberUnsafe(123.456) // => BigDecimal.make(123456n, 3)

Basic Arithmetic Operations

The BigDecimal module supports a variety of arithmetic operations that provide precision and avoid the rounding errors common in standard JavaScript arithmetic. Below is a list of supported operations:

Function	Description
`sum`	Adds two `BigDecimal` values.
`subtract`	Subtracts one `BigDecimal` value from another.
`multiply`	Multiplies two `BigDecimal` values.
`divide`	Divides one `BigDecimal` value by another, returning an `Option<BigDecimal>`.
`divideUnsafe`	Divides one `BigDecimal` value by another, throwing an error if the divisor is zero.
`negate`	Negates a `BigDecimal` value (i.e., changes its sign).
`remainder`	Returns the remainder of dividing one `BigDecimal` value by another, returning an `Option<BigDecimal>`.
`remainderUnsafe`	Returns the remainder of dividing one `BigDecimal` value by another, throwing an error if the divisor is zero.
`sign`	Returns the sign of a `BigDecimal` value (`-1`, `0`, or `1`).
`abs`	Returns the absolute value of a `BigDecimal`.

Example (Performing Basic Arithmetic with BigDecimal)

1
import { BigDecimal, Option } from "effect"
2

3
const dec1 = BigDecimal.fromStringUnsafe("1.05")
4
const dec2 = BigDecimal.fromStringUnsafe("2.10")
5

6
// Addition
7
console.log(String(BigDecimal.sum(dec1, dec2)))
8
String(BigDecimal.sum(dec1, dec2)) // => "BigDecimal(3.15)"
9

10
// Multiplication
11
console.log(String(BigDecimal.multiply(dec1, dec2)))
12
String(BigDecimal.multiply(dec1, dec2)) // => "BigDecimal(2.205)"
13

14
// Subtraction
15
console.log(String(BigDecimal.subtract(dec2, dec1)))
16
String(BigDecimal.subtract(dec2, dec1)) // => "BigDecimal(1.05)"
17

18
// Division (safe, returns Option<BigDecimal>)
19
console.log(BigDecimal.divide(dec2, dec1))
20
BigDecimal.divide(dec2, dec1) // => Option.some(BigDecimal.make(2n, 0))
21

22
// Division (unsafe, throws if divisor is zero)
23
console.log(String(BigDecimal.divideUnsafe(dec2, dec1)))
24
String(BigDecimal.divideUnsafe(dec2, dec1)) // => "BigDecimal(2)"
25

26
// Negation
27
console.log(String(BigDecimal.negate(dec1)))
28
String(BigDecimal.negate(dec1)) // => "BigDecimal(-1.05)"
29

30
// Modulus (unsafe, throws if divisor is zero)
31
console.log(
32
  String(BigDecimal.remainderUnsafe(dec2, BigDecimal.fromStringUnsafe("0.6"))),
33
)
34
String(BigDecimal.remainderUnsafe(dec2, BigDecimal.fromStringUnsafe("0.6"))) // => "BigDecimal(0.3)"

Using BigDecimal for arithmetic operations helps to avoid the inaccuracies commonly encountered with floating-point numbers in JavaScript. For example:

Example (Avoiding Floating-Point Errors)

1
const dec1 = 1.05
2
const dec2 = 2.1
3

4
console.log(String(dec1 + dec2))
5
String(dec1 + dec2) // => "3.1500000000000004"

Comparison Operations

The BigDecimal module provides several functions for comparing decimal values. These allow you to determine the relative order of two values, find the minimum or maximum, and check specific properties like positivity or integer status.

Comparison Functions

Function	Description
`isLessThan`	Checks if the first `BigDecimal` is smaller than the second.
`isLessThanOrEqualTo`	Checks if the first `BigDecimal` is smaller than or equal to the second.
`isGreaterThan`	Checks if the first `BigDecimal` is larger than the second.
`isGreaterThanOrEqualTo`	Checks if the first `BigDecimal` is larger than or equal to the second.
`min`	Returns the smaller of two `BigDecimal` values.
`max`	Returns the larger of two `BigDecimal` values.

Example (Comparing Two BigDecimal Values)

1
import { BigDecimal } from "effect"
2

3
const dec1 = BigDecimal.fromStringUnsafe("1.05")
4
const dec2 = BigDecimal.fromStringUnsafe("2.10")
5

6
console.log(BigDecimal.isLessThan(dec1, dec2))
7
BigDecimal.isLessThan(dec1, dec2) // => true
8

9
console.log(BigDecimal.isLessThanOrEqualTo(dec1, dec2))
10
BigDecimal.isLessThanOrEqualTo(dec1, dec2) // => true
11

12
console.log(BigDecimal.isGreaterThan(dec1, dec2))
13
BigDecimal.isGreaterThan(dec1, dec2) // => false
14

15
console.log(BigDecimal.isGreaterThanOrEqualTo(dec1, dec2))
16
BigDecimal.isGreaterThanOrEqualTo(dec1, dec2) // => false
17

18
console.log(BigDecimal.min(dec1, dec2))
19
BigDecimal.min(dec1, dec2) // => BigDecimal.make(105n, 2)
20

21
console.log(BigDecimal.max(dec1, dec2))
22
BigDecimal.max(dec1, dec2) // => BigDecimal.make(210n, 2)

Predicates for Comparison

The module also includes predicates to check specific properties of a BigDecimal:

Predicate	Description
`isZero`	Checks if the value is exactly zero.
`isPositive`	Checks if the value is positive.
`isNegative`	Checks if the value is negative.
`between`	Checks if the value lies within a specified range (inclusive).
`isInteger`	Checks if the value is an integer (i.e., no fractional part).

Example (Checking the Sign and Properties of BigDecimal Values)

1
import { BigDecimal } from "effect"
2

3
const dec1 = BigDecimal.fromStringUnsafe("1.05")
4
const dec2 = BigDecimal.fromStringUnsafe("-2.10")
5

6
console.log(BigDecimal.isZero(BigDecimal.fromStringUnsafe("0")))
7
BigDecimal.isZero(BigDecimal.fromStringUnsafe("0")) // => true
8

9
console.log(BigDecimal.isPositive(dec1))
10
BigDecimal.isPositive(dec1) // => true
11

12
console.log(BigDecimal.isNegative(dec2))
13
BigDecimal.isNegative(dec2) // => true
14

15
console.log(
16
  BigDecimal.between({
17
    minimum: BigDecimal.fromStringUnsafe("1"),
18
    maximum: BigDecimal.fromStringUnsafe("2"),
19
  })(dec1),
20
)
21
BigDecimal.between({
22
  minimum: BigDecimal.fromStringUnsafe("1"),
23
  maximum: BigDecimal.fromStringUnsafe("2"),
24
})(dec1) // => true
25

26
console.log(
27
  BigDecimal.isInteger(dec2),
28
  BigDecimal.isInteger(BigDecimal.fromBigInt(3n)),
29
)
30
BigDecimal.isInteger(dec2) // => false
31
BigDecimal.isInteger(BigDecimal.fromBigInt(3n)) // => true

Normalization and Equality

In some cases, two BigDecimal values can have different internal representations but still represent the same number.

For example, 1.05 could be internally represented with different scales, such as:

105n with a scale of 2
1050n with a scale of 3

To ensure consistency, you can normalize a BigDecimal to adjust the scale and remove trailing zeros.

Normalization

The BigDecimal.normalize function adjusts the scale of a BigDecimal and eliminates any unnecessary trailing zeros in its internal representation.

Example (Normalizing a BigDecimal)

1
import { BigDecimal } from "effect"
2

3
const dec = BigDecimal.make(1050n, 3)
4

5
console.log(BigDecimal.normalize(dec))
6
BigDecimal.normalize(dec) // => BigDecimal.make(105n, 2)

Equality

To check if two BigDecimal values are numerically equal, regardless of their internal representation, use the BigDecimal.equals function.

Example (Checking Equality)

1
import { BigDecimal } from "effect"
2

3
const dec1 = BigDecimal.make(105n, 2)
4
const dec2 = BigDecimal.make(1050n, 3)
5

6
console.log(BigDecimal.equals(dec1, dec2))
7
BigDecimal.equals(dec1, dec2) // => true