BigDecimal.ts overview

This module provides utility functions and type class instances for working with the BigDecimal type in TypeScript. It includes functions for basic arithmetic operations, as well as type class instances for Equivalence and Order.

A BigDecimal allows storing any real number to arbitrary precision; which avoids common floating point errors (such as 0.1 + 0.2 ≠ 0.3) at the cost of complexity.

Internally, BigDecimal uses a BigInt object, paired with a 64-bit integer which determines the position of the decimal point. Therefore, the precision is not actually arbitrary, but limited to 2⁶³ decimal places.

It is not recommended to convert a floating point number to a decimal directly, as the floating point representation may be unexpected.

Since v2.0.0

Exports Grouped by Category

constructors
conversions
guards
- isBigDecimal
instances
- Equivalence
- Order
math
- abs
- clamp
- divide
- max
- min
- multiply
- negate
- remainder
- sign
- subtract
- sum
- unsafeDivide
- unsafeRemainder
models
- BigDecimal (interface)
predicates
scaling
- normalize
- scale
symbol
- TypeId (type alias)
symbols
- TypeId

constructors

fromBigInt

Creates a BigDecimal from a bigint value.

Signature

declare const fromBigInt: (n: bigint) => BigDecimal

Since v2.0.0

fromNumber

Creates a BigDecimal from a number value.

It is not recommended to convert a floating point number to a decimal directly, as the floating point representation may be unexpected.

Throws a RangeError if the number is not finite (NaN, +Infinity or -Infinity).

Signature

declare const fromNumber: (n: number) => BigDecimal

Since v2.0.0

fromString

Parses a numerical string into a BigDecimal.

Example

import * as assert from "node:assert"
import { BigDecimal, Option } from "effect"

assert.deepStrictEqual(BigDecimal.fromString("123"), Option.some(BigDecimal.make(123n, 0)))
assert.deepStrictEqual(BigDecimal.fromString("123.456"), Option.some(BigDecimal.make(123456n, 3)))
assert.deepStrictEqual(BigDecimal.fromString("123.abc"), Option.none())

Signature

declare const fromString: (s: string) => Option.Option<BigDecimal>

Since v2.0.0

make

Creates a BigDecimal from a bigint value and a scale.

Signature

declare const make: (value: bigint, scale: number) => BigDecimal

Since v2.0.0

safeFromNumber

Creates a BigDecimal from a number value.

It is not recommended to convert a floating point number to a decimal directly, as the floating point representation may be unexpected.

Returns None if the number is not finite (NaN, +Infinity or -Infinity).

Example

import * as assert from "node:assert"
import { BigDecimal, Option } from "effect"

assert.deepStrictEqual(BigDecimal.safeFromNumber(123), Option.some(BigDecimal.make(123n, 0)))
assert.deepStrictEqual(BigDecimal.safeFromNumber(123.456), Option.some(BigDecimal.make(123456n, 3)))
assert.deepStrictEqual(BigDecimal.safeFromNumber(Infinity), Option.none())

Signature

declare const safeFromNumber: (n: number) => Option.Option<BigDecimal>

Since v3.11.0

unsafeFromNumber

Creates a BigDecimal from a number value.

It is not recommended to convert a floating point number to a decimal directly, as the floating point representation may be unexpected.

Throws a RangeError if the number is not finite (NaN, +Infinity or -Infinity).

Example

import * as assert from "node:assert"
import { unsafeFromNumber, make } from "effect/BigDecimal"

assert.deepStrictEqual(unsafeFromNumber(123), make(123n, 0))
assert.deepStrictEqual(unsafeFromNumber(123.456), make(123456n, 3))

Signature

declare const unsafeFromNumber: (n: number) => BigDecimal

Since v3.11.0

unsafeFromString

Parses a numerical string into a BigDecimal.

Example

import * as assert from "node:assert"
import { unsafeFromString, make } from "effect/BigDecimal"

assert.deepStrictEqual(unsafeFromString("123"), make(123n, 0))
assert.deepStrictEqual(unsafeFromString("123.456"), make(123456n, 3))
assert.throws(() => unsafeFromString("123.abc"))

Signature

declare const unsafeFromString: (s: string) => BigDecimal

Since v2.0.0

conversions

format

Formats a given BigDecimal as a string.

If the scale of the BigDecimal is greater than or equal to 16, the BigDecimal will be formatted in scientific notation.

Example

import * as assert from "node:assert"
import { format, unsafeFromString } from "effect/BigDecimal"

assert.deepStrictEqual(format(unsafeFromString("-5")), "-5")
assert.deepStrictEqual(format(unsafeFromString("123.456")), "123.456")
assert.deepStrictEqual(format(unsafeFromString("-0.00000123")), "-0.00000123")

Signature

declare const format: (n: BigDecimal) => string

Since v2.0.0

toExponential

Formats a given BigDecimal as a string in scientific notation.

Example

import * as assert from "node:assert"
import { toExponential, make } from "effect/BigDecimal"

assert.deepStrictEqual(toExponential(make(123456n, -5)), "1.23456e+10")

Signature

declare const toExponential: (n: BigDecimal) => string

Since v3.11.0

unsafeToNumber

Converts a BigDecimal to a number.

This function will produce incorrect results if the BigDecimal exceeds the 64-bit range of a number.

Example

import * as assert from "node:assert"
import { unsafeToNumber, unsafeFromString } from "effect/BigDecimal"

assert.deepStrictEqual(unsafeToNumber(unsafeFromString("123.456")), 123.456)

Signature

declare const unsafeToNumber: (n: BigDecimal) => number

Since v2.0.0

guards

isBigDecimal

Checks if a given value is a BigDecimal.

Signature

declare const isBigDecimal: (u: unknown) => u is BigDecimal

Since v2.0.0

instances

Equivalence

Signature

declare const Equivalence: equivalence.Equivalence<BigDecimal>

Since v2.0.0

Order

Signature

declare const Order: order.Order<BigDecimal>

Since v2.0.0

math

abs

Determines the absolute value of a given BigDecimal.

Example

import * as assert from "node:assert"
import { abs, unsafeFromString } from "effect/BigDecimal"

assert.deepStrictEqual(abs(unsafeFromString("-5")), unsafeFromString("5"))
assert.deepStrictEqual(abs(unsafeFromString("0")), unsafeFromString("0"))
assert.deepStrictEqual(abs(unsafeFromString("5")), unsafeFromString("5"))

Signature

declare const abs: (n: BigDecimal) => BigDecimal

Since v2.0.0

clamp

Restricts the given BigDecimal to be within the range specified by the minimum and maximum values.

If the BigDecimal is less than the minimum value, the function returns the minimum value.
If the BigDecimal is greater than the maximum value, the function returns the maximum value.
Otherwise, it returns the original BigDecimal.

Example

import * as assert from "node:assert"
import { BigDecimal } from "effect"

const clamp = BigDecimal.clamp({
  minimum: BigDecimal.unsafeFromString("1"),
  maximum: BigDecimal.unsafeFromString("5")
})

assert.deepStrictEqual(clamp(BigDecimal.unsafeFromString("3")), BigDecimal.unsafeFromString("3"))
assert.deepStrictEqual(clamp(BigDecimal.unsafeFromString("0")), BigDecimal.unsafeFromString("1"))
assert.deepStrictEqual(clamp(BigDecimal.unsafeFromString("6")), BigDecimal.unsafeFromString("5"))

Signature

declare const clamp: {
  (options: { minimum: BigDecimal; maximum: BigDecimal }): (self: BigDecimal) => BigDecimal
  (self: BigDecimal, options: { minimum: BigDecimal; maximum: BigDecimal }): BigDecimal
}

Since v2.0.0

divide

Provides a division operation on BigDecimals.

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 None.

Example

import * as assert from "node:assert"
import { BigDecimal, Option } from "effect"

assert.deepStrictEqual(
  BigDecimal.divide(BigDecimal.unsafeFromString("6"), BigDecimal.unsafeFromString("3")),
  Option.some(BigDecimal.unsafeFromString("2"))
)
assert.deepStrictEqual(
  BigDecimal.divide(BigDecimal.unsafeFromString("6"), BigDecimal.unsafeFromString("4")),
  Option.some(BigDecimal.unsafeFromString("1.5"))
)
assert.deepStrictEqual(
  BigDecimal.divide(BigDecimal.unsafeFromString("6"), BigDecimal.unsafeFromString("0")),
  Option.none()
)

Signature

declare const divide: {
  (that: BigDecimal): (self: BigDecimal) => Option.Option<BigDecimal>
  (self: BigDecimal, that: BigDecimal): Option.Option<BigDecimal>
}

Since v2.0.0

max

Returns the maximum between two BigDecimals.

Example

import * as assert from "node:assert"
import { max, unsafeFromString } from "effect/BigDecimal"

assert.deepStrictEqual(max(unsafeFromString("2"), unsafeFromString("3")), unsafeFromString("3"))

Signature

declare const max: {
  (that: BigDecimal): (self: BigDecimal) => BigDecimal
  (self: BigDecimal, that: BigDecimal): BigDecimal
}

Since v2.0.0

min

Returns the minimum between two BigDecimals.

Example

import * as assert from "node:assert"
import { min, unsafeFromString } from "effect/BigDecimal"

assert.deepStrictEqual(min(unsafeFromString("2"), unsafeFromString("3")), unsafeFromString("2"))

Signature

declare const min: {
  (that: BigDecimal): (self: BigDecimal) => BigDecimal
  (self: BigDecimal, that: BigDecimal): BigDecimal
}

Since v2.0.0

multiply

Provides a multiplication operation on BigDecimals.

Example

import * as assert from "node:assert"
import { multiply, unsafeFromString } from "effect/BigDecimal"

assert.deepStrictEqual(multiply(unsafeFromString("2"), unsafeFromString("3")), unsafeFromString("6"))

Signature

declare const multiply: {
  (that: BigDecimal): (self: BigDecimal) => BigDecimal
  (self: BigDecimal, that: BigDecimal): BigDecimal
}

Since v2.0.0

negate

Provides a negate operation on BigDecimals.

Example

import * as assert from "node:assert"
import { negate, unsafeFromString } from "effect/BigDecimal"

assert.deepStrictEqual(negate(unsafeFromString("3")), unsafeFromString("-3"))
assert.deepStrictEqual(negate(unsafeFromString("-6")), unsafeFromString("6"))

Signature

declare const negate: (n: BigDecimal) => BigDecimal

Since v2.0.0

remainder

Returns the remainder left over when one operand is divided by a second operand.

If the divisor is 0, the result will be None.

Example

import * as assert from "node:assert"
import { BigDecimal, Option } from "effect"

assert.deepStrictEqual(
  BigDecimal.remainder(BigDecimal.unsafeFromString("2"), BigDecimal.unsafeFromString("2")),
  Option.some(BigDecimal.unsafeFromString("0"))
)
assert.deepStrictEqual(
  BigDecimal.remainder(BigDecimal.unsafeFromString("3"), BigDecimal.unsafeFromString("2")),
  Option.some(BigDecimal.unsafeFromString("1"))
)
assert.deepStrictEqual(
  BigDecimal.remainder(BigDecimal.unsafeFromString("-4"), BigDecimal.unsafeFromString("2")),
  Option.some(BigDecimal.unsafeFromString("0"))
)

Signature

declare const remainder: {
  (divisor: BigDecimal): (self: BigDecimal) => Option.Option<BigDecimal>
  (self: BigDecimal, divisor: BigDecimal): Option.Option<BigDecimal>
}

Since v2.0.0

sign

Determines the sign of a given BigDecimal.

Example

import * as assert from "node:assert"
import { sign, unsafeFromString } from "effect/BigDecimal"

assert.deepStrictEqual(sign(unsafeFromString("-5")), -1)
assert.deepStrictEqual(sign(unsafeFromString("0")), 0)
assert.deepStrictEqual(sign(unsafeFromString("5")), 1)

Signature

declare const sign: (n: BigDecimal) => Ordering

Since v2.0.0

subtract

Provides a subtraction operation on BigDecimals.

Example

import * as assert from "node:assert"
import { subtract, unsafeFromString } from "effect/BigDecimal"

assert.deepStrictEqual(subtract(unsafeFromString("2"), unsafeFromString("3")), unsafeFromString("-1"))

Signature

declare const subtract: {
  (that: BigDecimal): (self: BigDecimal) => BigDecimal
  (self: BigDecimal, that: BigDecimal): BigDecimal
}

Since v2.0.0

sum

Provides an addition operation on BigDecimals.

Example

import * as assert from "node:assert"
import { sum, unsafeFromString } from "effect/BigDecimal"

assert.deepStrictEqual(sum(unsafeFromString("2"), unsafeFromString("3")), unsafeFromString("5"))

Signature

declare const sum: {
  (that: BigDecimal): (self: BigDecimal) => BigDecimal
  (self: BigDecimal, that: BigDecimal): BigDecimal
}

Since v2.0.0

unsafeDivide

Provides an unsafe division operation on BigDecimals.

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.

Throws a RangeError if the divisor is 0.

Example

import * as assert from "node:assert"
import { unsafeDivide, unsafeFromString } from "effect/BigDecimal"

assert.deepStrictEqual(unsafeDivide(unsafeFromString("6"), unsafeFromString("3")), unsafeFromString("2"))
assert.deepStrictEqual(unsafeDivide(unsafeFromString("6"), unsafeFromString("4")), unsafeFromString("1.5"))

Signature

declare const unsafeDivide: {
  (that: BigDecimal): (self: BigDecimal) => BigDecimal
  (self: BigDecimal, that: BigDecimal): BigDecimal
}

Since v2.0.0

unsafeRemainder

Returns the remainder left over when one operand is divided by a second operand.

Throws a RangeError if the divisor is 0.

Example

import * as assert from "node:assert"
import { unsafeRemainder, unsafeFromString } from "effect/BigDecimal"

assert.deepStrictEqual(unsafeRemainder(unsafeFromString("2"), unsafeFromString("2")), unsafeFromString("0"))
assert.deepStrictEqual(unsafeRemainder(unsafeFromString("3"), unsafeFromString("2")), unsafeFromString("1"))
assert.deepStrictEqual(unsafeRemainder(unsafeFromString("-4"), unsafeFromString("2")), unsafeFromString("0"))

Signature

declare const unsafeRemainder: {
  (divisor: BigDecimal): (self: BigDecimal) => BigDecimal
  (self: BigDecimal, divisor: BigDecimal): BigDecimal
}

Since v2.0.0

models

BigDecimal (interface)

Signature

export interface BigDecimal extends Equal.Equal, Pipeable, Inspectable {
  readonly [TypeId]: TypeId
  readonly value: bigint
  readonly scale: number
  /** @internal */
  normalized?: BigDecimal
}

Since v2.0.0

predicates

between

Checks if a BigDecimal is between a minimum and maximum value (inclusive).

Example

import * as assert from "node:assert"
import { BigDecimal } from "effect"

const between = BigDecimal.between({
  minimum: BigDecimal.unsafeFromString("1"),
  maximum: BigDecimal.unsafeFromString("5")
})

assert.deepStrictEqual(between(BigDecimal.unsafeFromString("3")), true)
assert.deepStrictEqual(between(BigDecimal.unsafeFromString("0")), false)
assert.deepStrictEqual(between(BigDecimal.unsafeFromString("6")), false)

Signature

declare const between: {
  (options: { minimum: BigDecimal; maximum: BigDecimal }): (self: BigDecimal) => boolean
  (self: BigDecimal, options: { minimum: BigDecimal; maximum: BigDecimal }): boolean
}

Since v2.0.0

equals

Checks if two BigDecimals are equal.

Signature

declare const equals: {
  (that: BigDecimal): (self: BigDecimal) => boolean
  (self: BigDecimal, that: BigDecimal): boolean
}

Since v2.0.0

greaterThan

Returns true if the first argument is greater than the second, otherwise false.

Example

import * as assert from "node:assert"
import { greaterThan, unsafeFromString } from "effect/BigDecimal"

assert.deepStrictEqual(greaterThan(unsafeFromString("2"), unsafeFromString("3")), false)
assert.deepStrictEqual(greaterThan(unsafeFromString("3"), unsafeFromString("3")), false)
assert.deepStrictEqual(greaterThan(unsafeFromString("4"), unsafeFromString("3")), true)

Signature

declare const greaterThan: {
  (that: BigDecimal): (self: BigDecimal) => boolean
  (self: BigDecimal, that: BigDecimal): boolean
}

Since v2.0.0

greaterThanOrEqualTo

Checks if a given BigDecimal is greater than or equal to the provided one.

Example

import * as assert from "node:assert"
import { greaterThanOrEqualTo, unsafeFromString } from "effect/BigDecimal"

assert.deepStrictEqual(greaterThanOrEqualTo(unsafeFromString("2"), unsafeFromString("3")), false)
assert.deepStrictEqual(greaterThanOrEqualTo(unsafeFromString("3"), unsafeFromString("3")), true)
assert.deepStrictEqual(greaterThanOrEqualTo(unsafeFromString("4"), unsafeFromString("3")), true)

Signature

declare const greaterThanOrEqualTo: {
  (that: BigDecimal): (self: BigDecimal) => boolean
  (self: BigDecimal, that: BigDecimal): boolean
}

Since v2.0.0

isInteger

Checks if a given BigDecimal is an integer.

Example

import * as assert from "node:assert"
import { isInteger, unsafeFromString } from "effect/BigDecimal"

assert.deepStrictEqual(isInteger(unsafeFromString("0")), true)
assert.deepStrictEqual(isInteger(unsafeFromString("1")), true)
assert.deepStrictEqual(isInteger(unsafeFromString("1.1")), false)

Signature

declare const isInteger: (n: BigDecimal) => boolean

Since v2.0.0

isNegative

Checks if a given BigDecimal is negative.

Example

import * as assert from "node:assert"
import { isNegative, unsafeFromString } from "effect/BigDecimal"

assert.deepStrictEqual(isNegative(unsafeFromString("-1")), true)
assert.deepStrictEqual(isNegative(unsafeFromString("0")), false)
assert.deepStrictEqual(isNegative(unsafeFromString("1")), false)

Signature

declare const isNegative: (n: BigDecimal) => boolean

Since v2.0.0

isPositive

Checks if a given BigDecimal is positive.

Example

import * as assert from "node:assert"
import { isPositive, unsafeFromString } from "effect/BigDecimal"

assert.deepStrictEqual(isPositive(unsafeFromString("-1")), false)
assert.deepStrictEqual(isPositive(unsafeFromString("0")), false)
assert.deepStrictEqual(isPositive(unsafeFromString("1")), true)

Signature

declare const isPositive: (n: BigDecimal) => boolean

Since v2.0.0

isZero

Checks if a given BigDecimal is 0.

Example

import * as assert from "node:assert"
import { isZero, unsafeFromString } from "effect/BigDecimal"

assert.deepStrictEqual(isZero(unsafeFromString("0")), true)
assert.deepStrictEqual(isZero(unsafeFromString("1")), false)

Signature

declare const isZero: (n: BigDecimal) => boolean

Since v2.0.0

lessThan

Returns true if the first argument is less than the second, otherwise false.

Example

import * as assert from "node:assert"
import { lessThan, unsafeFromString } from "effect/BigDecimal"

assert.deepStrictEqual(lessThan(unsafeFromString("2"), unsafeFromString("3")), true)
assert.deepStrictEqual(lessThan(unsafeFromString("3"), unsafeFromString("3")), false)
assert.deepStrictEqual(lessThan(unsafeFromString("4"), unsafeFromString("3")), false)

Signature

declare const lessThan: {
  (that: BigDecimal): (self: BigDecimal) => boolean
  (self: BigDecimal, that: BigDecimal): boolean
}

Since v2.0.0

lessThanOrEqualTo

Checks if a given BigDecimal is less than or equal to the provided one.

Example

import * as assert from "node:assert"
import { lessThanOrEqualTo, unsafeFromString } from "effect/BigDecimal"

assert.deepStrictEqual(lessThanOrEqualTo(unsafeFromString("2"), unsafeFromString("3")), true)
assert.deepStrictEqual(lessThanOrEqualTo(unsafeFromString("3"), unsafeFromString("3")), true)
assert.deepStrictEqual(lessThanOrEqualTo(unsafeFromString("4"), unsafeFromString("3")), false)

Signature

declare const lessThanOrEqualTo: {
  (that: BigDecimal): (self: BigDecimal) => boolean
  (self: BigDecimal, that: BigDecimal): boolean
}

Since v2.0.0

scaling

normalize

Normalizes a given BigDecimal by removing trailing zeros.

Example

import * as assert from "node:assert"
import { normalize, make, unsafeFromString } from "effect/BigDecimal"

assert.deepStrictEqual(normalize(unsafeFromString("123.00000")), normalize(make(123n, 0)))
assert.deepStrictEqual(normalize(unsafeFromString("12300000")), normalize(make(123n, -5)))

Signature

declare const normalize: (self: BigDecimal) => BigDecimal

Since v2.0.0

scale

Scales a given BigDecimal to the specified scale.

If the given scale is smaller than the current scale, the value will be rounded down to the nearest integer.

Signature

declare const scale: {
  (scale: number): (self: BigDecimal) => BigDecimal
  (self: BigDecimal, scale: number): BigDecimal
}

Since v2.0.0

symbol

TypeId (type alias)

Signature

type TypeId = typeof TypeId

Since v2.0.0

symbols

TypeId

Signature

declare const TypeId: unique symbol

Since v2.0.0