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:

1. value: A BigInt that stores the digits of the number.
2. 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
// Output: { _id: 'BigDecimal', value: '1', scale: 2 }
8

9
// Convert the BigDecimal to a string
10
console.log(String(decimal))
11
// Output: BigDecimal(0.01)
12

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

17
// Convert the BigDecimal to exponential notation
18
console.log(BigDecimal.toExponential(decimal))
19
// Output: 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
// Output: { _id: 'BigDecimal', value: '10', scale: 0 }

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 } from "effect"
2

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

5
console.log(decimal)
6
/*
7
Output:
8
{
9
  _id: 'Option',
10
  _tag: 'Some',
11
  value: { _id: 'BigDecimal', value: '2', scale: 2 }
12
}
13
*/

unsafeFromString

The unsafeFromString 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.unsafeFromString("0.02")
4

5
console.log(decimal)
6
// Output: { _id: 'BigDecimal', value: '2', scale: 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.unsafeFromNumber(123.456))
4
// Output: { _id: 'BigDecimal', value: '123456', scale: 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:

Example (Performing Basic Arithmetic with BigDecimal)

1
import { BigDecimal } from "effect"
2

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

6
// Addition
7
console.log(String(BigDecimal.sum(dec1, dec2)))
8
// Output: BigDecimal(3.15)
9

10
// Multiplication
11
console.log(String(BigDecimal.multiply(dec1, dec2)))
12
// Output: BigDecimal(2.205)
13

14
// Subtraction
15
console.log(String(BigDecimal.subtract(dec2, dec1)))
16
// Output: BigDecimal(1.05)
17

18
// Division (safe, returns Option<BigDecimal>)
19
console.log(BigDecimal.divide(dec2, dec1))
20
/*
21
Output:
22
{
23
  _id: 'Option',
24
  _tag: 'Some',
25
  value: { _id: 'BigDecimal', value: '2', scale: 0 }
26
}
27
*/
28

29
// Division (unsafe, throws if divisor is zero)
30
console.log(String(BigDecimal.unsafeDivide(dec2, dec1)))
31
// Output: BigDecimal(2)
32

33
// Negation
34
console.log(String(BigDecimal.negate(dec1)))
35
// Output: BigDecimal(-1.05)
36

37
// Modulus (unsafe, throws if divisor is zero)
38
console.log(String(BigDecimal.unsafeRemainder(dec2, BigDecimal.unsafeFromString("0.6"))))
39
// Output: 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
// Output: 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

Example (Comparing Two BigDecimal Values)

1
import { BigDecimal } from "effect"
2

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

6
console.log(BigDecimal.lessThan(dec1, dec2))
7
// Output: true
8

9
console.log(BigDecimal.lessThanOrEqualTo(dec1, dec2))
10
// Output: true
11

12
console.log(BigDecimal.greaterThan(dec1, dec2))
13
// Output: false
14

15
console.log(BigDecimal.greaterThanOrEqualTo(dec1, dec2))
16
// Output: false
17

18
console.log(BigDecimal.min(dec1, dec2))
19
// Output: { _id: 'BigDecimal', value: '105', scale: 2 }
20

21
console.log(BigDecimal.max(dec1, dec2))
22
// Output: { _id: 'BigDecimal', value: '210', scale: 2 }

Predicates for Comparison

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

Example (Checking the Sign and Properties of BigDecimal Values)

1
import { BigDecimal } from "effect"
2

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

6
console.log(BigDecimal.isZero(BigDecimal.unsafeFromString("0")))
7
// Output: true
8

9
console.log(BigDecimal.isPositive(dec1))
10
// Output: true
11

12
console.log(BigDecimal.isNegative(dec2))
13
// Output: true
14

15
console.log(
16
  BigDecimal.between({
17
    minimum: BigDecimal.unsafeFromString("1"),
18
    maximum: BigDecimal.unsafeFromString("2"),
19
  })(dec1),
20
)
21
// Output: true
22

23
console.log(BigDecimal.isInteger(dec2), BigDecimal.isInteger(BigDecimal.fromBigInt(3n)))
24
// Output: false 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
// Output: { _id: 'BigDecimal', value: '105', scale: 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
// Output: true