Skip to content
Effect 4.0 is here. One ecosystem. Zero dependencies.

BigDecimal

Decimal numbers and arithmetic for cases where JavaScript number rounding is not precise enough. A BigDecimal stores digits as a bigint plus a decimal scale, which lets the module parse, compare, add, subtract, multiply, divide, round, and format decimal values such as money, quantities, and measurements.

45 exports Since v2.0.0 Source

Constructors

fromBigInt

Since v2.0.0

Creates a BigDecimal from a bigint value.

When to use

Use to construct an integer BigDecimal from a bigint.

See

  • make for constructing a decimal with an explicit scale

Signature

declare function fromBigInt(n: bigint): BigDecimal

Example Creating decimals from bigint 

import { BigDecimal } from "effect"


const decimal = BigDecimal.fromBigInt(123n)
decimal // => BigDecimal.fromStringUnsafe("123")


const largeBigInt = BigDecimal.fromBigInt(9007199254740991n)
largeBigInt // => BigDecimal.fromStringUnsafe("9007199254740991")

fromNumber

Since v2.0.0

Creates a BigDecimal safely from a finite number.

When to use

Use to convert a finite JavaScript number to a BigDecimal without throwing on invalid input.

Details

Returns Option.none() for NaN, +Infinity or -Infinity.

Gotchas

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

See

Signature

declare function fromNumber(n: number): Option<BigDecimal>

Example Creating decimals from numbers safely 

import { BigDecimal, Option } from "effect"


BigDecimal.fromNumber(123.456) // => Option.some(BigDecimal.fromStringUnsafe("123.456"))
BigDecimal.fromNumber(Infinity) // => Option.none()

fromNumberUnsafe

Since v4.0.0

Creates a BigDecimal from a finite number.

When to use

Use when you need to convert a trusted finite JavaScript number to a BigDecimal and want a plain result instead of an Option.

Gotchas

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

See

  • fromNumber for returning Option.none when the number is not finite

Signature

declare function fromNumberUnsafe(n: number): BigDecimal

Example Creating decimals from finite numbers 

import { BigDecimal } from "effect"


BigDecimal.fromNumberUnsafe(123) // => BigDecimal.fromBigInt(123n)
BigDecimal.fromNumberUnsafe(123.456) // => BigDecimal.fromStringUnsafe("123.456")

fromString

Since v2.0.0

Parses a decimal string into a BigDecimal safely.

When to use

Use to parse external decimal text without throwing on invalid input.

Details

Returns Option.some for valid decimal or exponent notation and Option.none when the string cannot be parsed or would produce an unsafe scale. The empty string parses as zero.

See

Signature

declare function fromString(s: string): Option<BigDecimal>

Example Parsing decimal strings safely 

import { BigDecimal, Option } from "effect"


BigDecimal.fromString("123.456") // => Option.some(BigDecimal.make(123456n, 3))
BigDecimal.fromString("123.abc") // => Option.none()

fromStringUnsafe

Since v4.0.0

Parses a decimal string into a BigDecimal, throwing if the string is invalid.

When to use

Use when you expect decimal text to be valid and want parse errors to throw.

Details

Accepts the same syntax as fromString. Use fromString when invalid input should be represented as Option.none instead of throwing.

See

  • fromString for returning Option.none on invalid input

Signature

declare function fromStringUnsafe(s: string): BigDecimal

Example Parsing decimal strings unsafely 

import { BigDecimal } from "effect"


BigDecimal.fromStringUnsafe("123") // => BigDecimal.fromBigInt(123n)
BigDecimal.fromStringUnsafe("123.456") // => BigDecimal.make(123456n, 3)

make

Since v2.0.0

Creates a BigDecimal from a bigint value and a safe integer scale.

When to use

Use to construct a decimal directly from its unscaled integer value and decimal scale.

Gotchas

Throws a RangeError if scale is not a safe integer.

See

  • fromBigInt for constructing an integer decimal from a bigint

Signature

declare function make(value: bigint, scale: number): BigDecimal

Example Creating decimals from bigint and scale 

import { BigDecimal } from "effect"


// Create 123.45 (12345 with scale 2)
const decimal = BigDecimal.make(12345n, 2)
decimal // => BigDecimal.fromStringUnsafe("123.45")


// Create 42 (42 with scale 0)
const integer = BigDecimal.make(42n, 0)
integer // => BigDecimal.fromBigInt(42n)

Converting

format

Since v2.0.0

Formats a BigDecimal as a string.

When to use

Use to render a BigDecimal as plain decimal text when possible.

Details

The value is normalized before formatting. Scientific notation is used when the absolute value of the normalized scale is at least 16; otherwise plain decimal notation is used.

See

Signature

declare function format(n: BigDecimal): string

Example Formatting decimals 

import { BigDecimal } from "effect"


BigDecimal.format(BigDecimal.fromStringUnsafe("-5")) // => "-5"
BigDecimal.format(BigDecimal.fromStringUnsafe("123.456")) // => "123.456"
BigDecimal.format(BigDecimal.fromStringUnsafe("-0.00000123")) // => "-0.00000123"

toExponential

Since v3.11.0

Formats a given BigDecimal as a string in scientific notation.

When to use

Use to render a BigDecimal in scientific notation.

See

  • format for plain decimal formatting when possible

Signature

declare function toExponential(n: BigDecimal): string

Example Formatting decimals exponentially 

import { BigDecimal } from "effect"


BigDecimal.toExponential(BigDecimal.make(123456n, -5)) // => "1.23456e+10"

toNumberUnsafe

Since v4.0.0

Converts a BigDecimal to a JavaScript number.

When to use

Use when you need a JavaScript number at an interop boundary where precision loss is acceptable.

Gotchas

This conversion is unsafe because the result can lose integer or fractional precision, round to a nearby representable value, or become Infinity when the decimal cannot be represented as a finite JavaScript number.

See

  • format for preserving decimal precision as text

Signature

declare function toNumberUnsafe(n: BigDecimal): number

Example Converting decimals to numbers 

import { BigDecimal } from "effect"


BigDecimal.toNumberUnsafe(BigDecimal.fromStringUnsafe("123.456")) // => 123.456

Guards

isBigDecimal

Since v2.0.0

Checks whether a given value is a BigDecimal.

When to use

Use to validate unknown input and narrow it to BigDecimal.

Signature

declare function isBigDecimal(u: unknown): u is BigDecimal

Example Checking BigDecimal values 

import { BigDecimal } from "effect"


const decimal = BigDecimal.fromNumber(123.45)
BigDecimal.isBigDecimal(decimal) // => false
BigDecimal.isBigDecimal(BigDecimal.fromStringUnsafe("123.45")) // => true
BigDecimal.isBigDecimal(123.45) // => false
BigDecimal.isBigDecimal("123.45") // => false

Instances

Equivalence

Since v2.0.0

Provides an Equivalence instance for BigDecimal that determines equality between BigDecimal values.

When to use

Use when comparing decimal values through APIs that accept an equivalence relation.

Signature

declare const Equivalence: Equ.Equivalence<BigDecimal>

Example Checking decimal equivalence 

import { BigDecimal } from "effect"


const a = BigDecimal.fromStringUnsafe("1.50")
const b = BigDecimal.fromStringUnsafe("1.5")
const c = BigDecimal.fromStringUnsafe("2.0")


BigDecimal.Equivalence(a, b) // => true
BigDecimal.Equivalence(a, c) // => false

Order

Since v2.0.0

Provides an Order instance for BigDecimal that allows comparing and sorting BigDecimal values.

When to use

Use when you need to sort or compare decimal values through APIs that accept an ordering instance.

Signature

declare const Order: order.Order<BigDecimal>

Example Comparing decimals 

import { BigDecimal } from "effect"


const a = BigDecimal.fromNumberUnsafe(1.5)
const b = BigDecimal.fromNumberUnsafe(2.3)
const c = BigDecimal.fromNumberUnsafe(1.5)


BigDecimal.Order(a, b) // => -1
BigDecimal.Order(b, a) // => 1
BigDecimal.Order(a, c) // => 0

Math

abs

Since v2.0.0

Determines the absolute value of a given BigDecimal.

When to use

Use to remove the sign from a BigDecimal while preserving its magnitude.

Signature

declare function abs(n: BigDecimal): BigDecimal

Example Calculating absolute values 

import { BigDecimal } from "effect"


BigDecimal.abs(BigDecimal.fromStringUnsafe("-5")) // => BigDecimal.fromBigInt(5n)
BigDecimal.abs(BigDecimal.fromStringUnsafe("0")) // => BigDecimal.fromBigInt(0n)
BigDecimal.abs(BigDecimal.fromStringUnsafe("5")) // => BigDecimal.fromBigInt(5n)

ceil

Since v3.16.0

Computes the ceiling of a BigDecimal at the given scale.

When to use

Use to round a decimal toward positive infinity at a requested scale.

Details

The default scale is 0. Positive scales keep digits to the right of the decimal point, and negative scales round positions to the left of the decimal point.

See

  • floor for rounding toward negative infinity
  • truncate for rounding toward zero
  • round for configurable rounding modes

Signature

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

clamp

Since v2.0.0

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

When to use

Use to force a BigDecimal into an inclusive range.

Details

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

See

  • between for checking whether a BigDecimal is already inside a range

Signature

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

Example Clamping decimals to a range 

import { BigDecimal } from "effect"


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


clamp(BigDecimal.fromStringUnsafe("3")) // => BigDecimal.fromBigInt(3n)
clamp(BigDecimal.fromStringUnsafe("0")) // => BigDecimal.fromBigInt(1n)
clamp(BigDecimal.fromStringUnsafe("6")) // => BigDecimal.fromBigInt(5n)

divide

Since v2.0.0

Divides BigDecimals safely.

When to use

Use to divide BigDecimal values while representing division by zero as Option.none.

Details

If the dividend is not a multiple of the divisor, the result will be a BigDecimal value with up to the default division precision. If the divisor is 0, the result will be Option.none().

See

  • divideUnsafe for division that throws when the divisor is zero
  • remainder for the decimal remainder operation

Signature

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

Example Dividing decimals safely 

import { BigDecimal, Option } from "effect"


const six = BigDecimal.fromBigInt(6n)


BigDecimal.divide(six, BigDecimal.fromBigInt(3n)) // => Option.some(BigDecimal.fromBigInt(2n))
BigDecimal.divide(six, BigDecimal.fromBigInt(4n)) // => Option.some(BigDecimal.fromStringUnsafe("1.5"))
BigDecimal.divide(six, BigDecimal.fromBigInt(0n)) // => Option.none()

divideUnsafe

Since v4.0.0

Provides an unsafe division operation on BigDecimals.

When to use

Use when you need to divide BigDecimal values where the divisor is known to be non-zero, so division by zero should be a thrown exception.

Details

If the dividend is not a multiple of the divisor, the result will be a BigDecimal value with up to the default division precision.

Gotchas

Throws a RangeError if the divisor is 0.

See

  • divide for division that returns Option.none when the divisor is zero

Signature

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

Example Dividing decimals unsafely 

import { BigDecimal } from "effect"


BigDecimal.divideUnsafe(BigDecimal.fromStringUnsafe("6"), BigDecimal.fromStringUnsafe("3")) // => BigDecimal.fromBigInt(2n)
BigDecimal.divideUnsafe(BigDecimal.fromStringUnsafe("6"), BigDecimal.fromStringUnsafe("4")) // => BigDecimal.fromStringUnsafe("1.5")

floor

Since v3.16.0

Computes the floor of a BigDecimal at the given scale.

When to use

Use to round a decimal toward negative infinity at a requested scale.

See

  • ceil for rounding toward positive infinity
  • truncate for rounding toward zero
  • round for configurable rounding modes

Signature

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

Example Rounding decimals down 

import { BigDecimal } from "effect"


BigDecimal.floor(BigDecimal.fromStringUnsafe("145"), -1) // => BigDecimal.fromBigInt(140n)
BigDecimal.floor(BigDecimal.fromStringUnsafe("-14.5")) // => BigDecimal.fromBigInt(-15n)

max

Since v2.0.0

Returns the maximum between two BigDecimals.

When to use

Use to select the larger of two BigDecimal values.

See

  • min for selecting the smaller value

Signature

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

Example Selecting the larger decimal 

import { BigDecimal } from "effect"


const result = BigDecimal.max(
  BigDecimal.fromStringUnsafe("2"),
  BigDecimal.fromStringUnsafe("3")
) // => BigDecimal.fromBigInt(3n)

min

Since v2.0.0

Returns the minimum between two BigDecimals.

When to use

Use to select the smaller of two BigDecimal values.

See

  • max for selecting the larger value

Signature

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

Example Selecting the smaller decimal 

import { BigDecimal } from "effect"


const result = BigDecimal.min(
  BigDecimal.fromStringUnsafe("2"),
  BigDecimal.fromStringUnsafe("3")
) // => BigDecimal.fromBigInt(2n)

multiply

Since v2.0.0

Provides a multiplication operation on BigDecimals.

When to use

Use to multiply two BigDecimal values.

See

  • multiplyAll for multiplying an iterable of BigDecimal values

Signature

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

Example Multiplying decimals 

import { BigDecimal } from "effect"


const result = BigDecimal.multiply(
  BigDecimal.fromStringUnsafe("2"),
  BigDecimal.fromStringUnsafe("3")
) // => BigDecimal.fromBigInt(6n)

multiplyAll

Since v4.0.0

Takes an Iterable of BigDecimals and returns their multiplication as a single BigDecimal.

When to use

Use to multiply all BigDecimal values in an iterable.

See

  • multiply for multiplying two BigDecimal values

Signature

declare function multiplyAll(collection: Iterable<BigDecimal>): BigDecimal

Example Multiplying multiple decimals 

import { BigDecimal } from "effect"


const result = BigDecimal.multiplyAll([
  BigDecimal.fromStringUnsafe("2"),
  BigDecimal.fromStringUnsafe("3"),
  BigDecimal.fromStringUnsafe("4")
]) // => BigDecimal.fromBigInt(24n)

negate

Since v2.0.0

Provides a negate operation on BigDecimals.

When to use

Use to flip the sign of a BigDecimal.

Signature

declare function negate(n: BigDecimal): BigDecimal

Example Negating decimals 

import { BigDecimal } from "effect"


BigDecimal.negate(BigDecimal.fromStringUnsafe("3")) // => BigDecimal.fromBigInt(-3n)
BigDecimal.negate(BigDecimal.fromStringUnsafe("-6")) // => BigDecimal.fromBigInt(6n)

remainder

Since v2.0.0

Computes the decimal remainder safely when one operand is divided by a second operand.

When to use

Use to compute a decimal remainder while representing division by zero as Option.none.

Details

If the divisor is 0, the result will be Option.none().

See

  • remainderUnsafe for remainder calculation that throws when the divisor is zero
  • divide for decimal quotient calculation

Signature

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

Example Computing remainders safely 

import { BigDecimal, Option } from "effect"


const two = BigDecimal.fromStringUnsafe("2")
const three = BigDecimal.fromStringUnsafe("3")
const zero = BigDecimal.fromStringUnsafe("0")


BigDecimal.remainder(three, two) // => Option.some(BigDecimal.fromBigInt(1n))
BigDecimal.remainder(two, zero) // => Option.none()

remainderUnsafe

Since v4.0.0

Returns the decimal remainder left over when one operand is divided by a non-zero second operand.

When to use

Use when you need to compute a BigDecimal remainder with a divisor known to be non-zero and want a plain BigDecimal result instead of an Option.

Gotchas

Throws a RangeError if the divisor is 0.

See

  • remainder for returning Option.none when the divisor is zero

Signature

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

Example Computing remainders unsafely 

import { BigDecimal } from "effect"


BigDecimal.remainderUnsafe(
  BigDecimal.fromStringUnsafe("3"),
  BigDecimal.fromStringUnsafe("2")
) // => BigDecimal.fromBigInt(1n)

round

Since v3.16.0

Computes a rounded BigDecimal at the given scale with the specified rounding mode.

When to use

Use to round a decimal at a requested scale with an explicit rounding mode.

See

  • ceil for fixed rounding toward positive infinity
  • floor for fixed rounding toward negative infinity
  • truncate for fixed rounding toward zero

Signature

declare const round: {
  (options: {
    mode?: RoundingMode;
    scale?: number;
  }): (self: BigDecimal) => BigDecimal;
  (n: BigDecimal, options?: {
    mode?: RoundingMode;
    scale?: number;
  }): BigDecimal;
}

Example Rounding decimals 

import { BigDecimal } from "effect"


const positive = BigDecimal.round(BigDecimal.fromStringUnsafe("145"), { mode: "from-zero", scale: -1 })
positive // => BigDecimal.fromBigInt(150n)


const negative = BigDecimal.round(BigDecimal.fromStringUnsafe("-14.5"))
negative // => BigDecimal.fromBigInt(-15n)

RoundingMode

type
Since v3.16.0

Rounding modes for BigDecimal.

When to use

Use with round to choose how discarded digits affect a BigDecimal rounded to a target scale.

Details

  • ceil: round towards positive infinity
  • floor: round towards negative infinity
  • to-zero: round towards zero
  • from-zero: round away from zero
  • half-ceil: round to the nearest neighbor; if equidistant round towards positive infinity
  • half-floor: round to the nearest neighbor; if equidistant round towards negative infinity
  • half-to-zero: round to the nearest neighbor; if equidistant round towards zero
  • half-from-zero: round to the nearest neighbor; if equidistant round away from zero
  • half-even: round to the nearest neighbor; if equidistant round to the neighbor with an even digit
  • half-odd: round to the nearest neighbor; if equidistant round to the neighbor with an odd digit

See

  • round for configurable rounding with a RoundingMode
  • ceil for fixed rounding toward positive infinity
  • floor for fixed rounding toward negative infinity
  • truncate for fixed rounding toward zero

Signature

type RoundingMode = "ceil" | "floor" | "to-zero" | "from-zero" | "half-ceil" | "half-floor" | "half-to-zero" | "half-from-zero" | "half-even" | "half-odd"

sign

Since v2.0.0

Determines the sign of a given BigDecimal.

When to use

Use to classify a BigDecimal as negative, zero, or positive.

Signature

declare function sign(n: BigDecimal): Ordering

Example Reading decimal signs 

import { BigDecimal } from "effect"


BigDecimal.sign(BigDecimal.fromStringUnsafe("-5")) // => -1
BigDecimal.sign(BigDecimal.fromStringUnsafe("0")) // => 0
BigDecimal.sign(BigDecimal.fromStringUnsafe("5")) // => 1

subtract

Since v2.0.0

Provides a subtraction operation on BigDecimals.

When to use

Use to subtract one BigDecimal value from another.

Signature

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

Example Subtracting decimals 

import { BigDecimal } from "effect"


const result = BigDecimal.subtract(
  BigDecimal.fromStringUnsafe("2"),
  BigDecimal.fromStringUnsafe("3")
) // => BigDecimal.fromBigInt(-1n)

sum

Since v2.0.0

Provides an addition operation on BigDecimals.

When to use

Use when you need a decimal addition function for piping or higher-order APIs while preserving decimal precision.

See

  • sumAll for summing an iterable of BigDecimal values

Signature

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

Example Adding decimals 

import { BigDecimal } from "effect"


const result = BigDecimal.sum(
  BigDecimal.fromStringUnsafe("2"),
  BigDecimal.fromStringUnsafe("3")
) // => BigDecimal.fromBigInt(5n)

sumAll

Since v3.16.0

Takes an Iterable of BigDecimals and returns their sum as a single BigDecimal.

When to use

Use when you need to aggregate decimal quantities with decimal precision instead of converting through JavaScript numbers.

See

  • sum for adding two BigDecimal values

Signature

declare function sumAll(collection: Iterable<BigDecimal>): BigDecimal

Example Adding multiple decimals 

import { BigDecimal } from "effect"


const result = BigDecimal.sumAll([
  BigDecimal.fromStringUnsafe("2"),
  BigDecimal.fromStringUnsafe("3"),
  BigDecimal.fromStringUnsafe("4")
]) // => BigDecimal.fromBigInt(9n)

truncate

Since v3.16.0

Computes a truncated BigDecimal at the given scale. This removes fractional digits beyond the scale, rounding toward zero.

When to use

Use when you need to discard fractional digits beyond a scale rather than round half up, half down, or toward an infinity.

See

  • round for configurable rounding modes
  • ceil for rounding toward positive infinity
  • floor for rounding toward negative infinity

Signature

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

Example Truncating decimals 

import { BigDecimal } from "effect"


BigDecimal.truncate(BigDecimal.fromStringUnsafe("145"), -1) // => BigDecimal.fromBigInt(140n)
BigDecimal.truncate(BigDecimal.fromStringUnsafe("-14.5")) // => BigDecimal.fromBigInt(-14n)

Models

BigDecimal

interface
Since v2.0.0

Represents an arbitrary precision decimal number.

When to use

Use when decimal arithmetic needs to avoid JavaScript floating point representation errors.

Signature

interface BigDecimal extends Equal, Pipeable, Inspectable {
  readonly "~effect/BigDecimal": "~effect/BigDecimal";
  readonly scale: number;
  readonly value: bigint;
}

Example Inspecting BigDecimal storage 

import { BigDecimal } from "effect"


const d = BigDecimal.fromStringUnsafe("123.45")


d.value // => 12345n
d.scale // => 2

Predicates

between

Since v2.0.0

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

When to use

Use to test whether a BigDecimal falls inside an inclusive range.

See

  • clamp for forcing a BigDecimal into an inclusive range

Signature

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

Example Checking decimal ranges 

import { BigDecimal } from "effect"


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


between(BigDecimal.fromStringUnsafe("3")) // => true
between(BigDecimal.fromStringUnsafe("0")) // => false
between(BigDecimal.fromStringUnsafe("6")) // => false

equals

Since v2.0.0

Checks whether two BigDecimals are equal.

When to use

Use to compare two BigDecimal values for numeric equality.

See

  • Equivalence for passing decimal equality to APIs that require an Equivalence

Signature

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

Example Checking decimal equality 

import { BigDecimal } from "effect"


const a = BigDecimal.fromStringUnsafe("1.5")
const b = BigDecimal.fromStringUnsafe("1.50")
const c = BigDecimal.fromStringUnsafe("2.0")


BigDecimal.equals(a, b) // => true
BigDecimal.equals(a, c) // => false

isGreaterThan

Since v4.0.0

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

When to use

Use to test whether one BigDecimal is strictly greater than another.

Signature

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

Example Checking greater-than comparisons 

import { BigDecimal } from "effect"


const two = BigDecimal.fromStringUnsafe("2")
const three = BigDecimal.fromStringUnsafe("3")
const four = BigDecimal.fromStringUnsafe("4")


BigDecimal.isGreaterThan(two, three) // => false
BigDecimal.isGreaterThan(three, three) // => false
BigDecimal.isGreaterThan(four, three) // => true

isGreaterThanOrEqualTo

Since v4.0.0

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

When to use

Use to test whether one BigDecimal is greater than or equal to another.

Signature

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

Example Checking greater-than-or-equal comparisons 

import { BigDecimal } from "effect"


const two = BigDecimal.fromStringUnsafe("2")
const three = BigDecimal.fromStringUnsafe("3")
const four = BigDecimal.fromStringUnsafe("4")


BigDecimal.isGreaterThanOrEqualTo(two, three) // => false
BigDecimal.isGreaterThanOrEqualTo(three, three) // => true
BigDecimal.isGreaterThanOrEqualTo(four, three) // => true

isInteger

Since v2.0.0

Checks whether a given BigDecimal is an integer.

When to use

Use to test whether a BigDecimal has no fractional decimal part.

Signature

declare function isInteger(n: BigDecimal): boolean

Example Checking integer decimals 

import { BigDecimal } from "effect"


BigDecimal.isInteger(BigDecimal.fromStringUnsafe("0")) // => true
BigDecimal.isInteger(BigDecimal.fromStringUnsafe("1")) // => true
BigDecimal.isInteger(BigDecimal.fromStringUnsafe("1.1")) // => false

isLessThan

Since v4.0.0

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

When to use

Use to test whether one BigDecimal is strictly less than another.

Signature

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

Example Checking less-than comparisons 

import { BigDecimal } from "effect"


const two = BigDecimal.fromStringUnsafe("2")
const three = BigDecimal.fromStringUnsafe("3")
const four = BigDecimal.fromStringUnsafe("4")


BigDecimal.isLessThan(two, three) // => true
BigDecimal.isLessThan(three, three) // => false
BigDecimal.isLessThan(four, three) // => false

isLessThanOrEqualTo

Since v4.0.0

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

When to use

Use to test whether one BigDecimal is less than or equal to another.

Signature

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

Example Checking less-than-or-equal comparisons 

import { BigDecimal } from "effect"


const two = BigDecimal.fromStringUnsafe("2")
const three = BigDecimal.fromStringUnsafe("3")
const four = BigDecimal.fromStringUnsafe("4")


BigDecimal.isLessThanOrEqualTo(two, three) // => true
BigDecimal.isLessThanOrEqualTo(three, three) // => true
BigDecimal.isLessThanOrEqualTo(four, three) // => false

isNegative

Since v2.0.0

Checks whether a given BigDecimal is negative.

When to use

Use to test whether a BigDecimal is less than zero.

Signature

declare function isNegative(n: BigDecimal): boolean

Example Checking negative decimals 

import { BigDecimal } from "effect"


BigDecimal.isNegative(BigDecimal.fromStringUnsafe("-1")) // => true
BigDecimal.isNegative(BigDecimal.fromStringUnsafe("0")) // => false
BigDecimal.isNegative(BigDecimal.fromStringUnsafe("1")) // => false

isPositive

Since v2.0.0

Checks whether a given BigDecimal is positive.

When to use

Use to test whether a BigDecimal is greater than zero.

Signature

declare function isPositive(n: BigDecimal): boolean

Example Checking positive decimals 

import { BigDecimal } from "effect"


BigDecimal.isPositive(BigDecimal.fromStringUnsafe("-1")) // => false
BigDecimal.isPositive(BigDecimal.fromStringUnsafe("0")) // => false
BigDecimal.isPositive(BigDecimal.fromStringUnsafe("1")) // => true

isZero

Since v2.0.0

Checks whether a given BigDecimal is 0.

When to use

Use to test whether a BigDecimal is exactly zero.

Signature

declare function isZero(n: BigDecimal): boolean

Example Checking zero decimals 

import { BigDecimal } from "effect"


BigDecimal.isZero(BigDecimal.fromStringUnsafe("0")) // => true
BigDecimal.isZero(BigDecimal.fromStringUnsafe("1")) // => false

Scaling

normalize

Since v2.0.0

Normalizes a given BigDecimal by removing trailing zeros.

When to use

Use to canonicalize decimals that have equivalent values but different internal scales.

See

  • format for rendering normalized decimals as strings

Signature

declare function normalize(self: BigDecimal): BigDecimal

Example Normalizing trailing zeros 

import { BigDecimal } from "effect"


const decimal = BigDecimal.normalize(BigDecimal.fromStringUnsafe("123.00000"))
const decimalStorage = [decimal.value, decimal.scale] // => [123n, 0]


const largeDecimal = BigDecimal.normalize(BigDecimal.fromStringUnsafe("12300000"))
const largeDecimalStorage = [largeDecimal.value, largeDecimal.scale] // => [123n, -5]

scale

Since v2.0.0

Changes a BigDecimal to the specified scale.

When to use

Use to change how many decimal places are represented by a BigDecimal.

Details

Increasing the scale appends decimal zeros. Decreasing the scale discards digits beyond the target scale by bigint division, which truncates toward zero.

See

  • round for changing scale with configurable rounding

Signature

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

Example Scaling decimal precision 

import { BigDecimal } from "effect"


const decimal = BigDecimal.fromNumberUnsafe(123.45)


// Increase scale (add more precision)
const scaled = BigDecimal.scale(decimal, 4)
const scaledStorage = [scaled.value, scaled.scale] // => [1234500n, 4]


// Decrease scale (reduce precision, truncating toward zero)
const reduced = BigDecimal.scale(decimal, 1)
reduced // => BigDecimal.fromStringUnsafe("123.4")