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.
Constructors
fromBigInt
Signature
declare function fromBigInt(n: bigint): BigDecimal;fromNumber
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
fromNumberUnsafefor throwing when the number is not finitefromStringfor parsing decimal strings directly
Signature
declare function fromNumber(n: number): Option<BigDecimal>;fromNumberUnsafe
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
fromNumberfor returningOption.nonewhen the number is not finite
Signature
declare function fromNumberUnsafe(n: number): BigDecimal;fromString
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
fromStringUnsafefor parsing that throws on invalid inputfromNumberfor converting finite JavaScript numbers
Signature
declare function fromString(s: string): Option<BigDecimal>;fromStringUnsafe
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
fromStringfor returningOption.noneon invalid input
Signature
declare function fromStringUnsafe(s: string): BigDecimal;Creates a BigDecimal from a bigint value and a scale.
When to use
Use to construct a decimal directly from its unscaled integer value and decimal scale.
See
fromBigIntfor constructing an integer decimal from abigint
Signature
declare function make(value: bigint, scale: number): BigDecimal;Converting
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
toExponentialfor always rendering scientific notation
Signature
declare function format(n: BigDecimal): string;toExponential
Formats a given BigDecimal as a string in scientific notation.
When to use
Use to render a BigDecimal in scientific notation.
See
formatfor plain decimal formatting when possible
Signature
declare function toExponential(n: BigDecimal): string;toNumberUnsafe
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
formatfor preserving decimal precision as text
Signature
declare function toNumberUnsafe(n: BigDecimal): number;Guards
isBigDecimal
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;Instances
Equivalence
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>;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>;Math
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;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
floorfor rounding toward negative infinitytruncatefor rounding toward zeroroundfor configurable rounding modes Example (Rounding decimals up) ``ts import.meta.vitest import { BigDecimal } from "effect" BigDecimal.ceil(BigDecimal.fromStringUnsafe("145"), -1) // => BigDecimal.fromBigInt(150n) BigDecimal.ceil(BigDecimal.fromStringUnsafe("-14.5")) // => BigDecimal.fromBigInt(-14n)``
Signature
declare const ceil: {
(scale: number): (self: BigDecimal) => BigDecimal;
(self: BigDecimal, scale?: number): BigDecimal;
};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
betweenfor checking whether aBigDecimalis already inside a range
Signature
declare const clamp: {
(options: { maximum: BigDecimal; minimum: BigDecimal }): (self: BigDecimal) => BigDecimal;
(
self: BigDecimal,
options: {
maximum: BigDecimal;
minimum: BigDecimal;
},
): BigDecimal;
};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
divideUnsafefor division that throws when the divisor is zeroremainderfor the decimal remainder operation
Signature
declare const divide: {
(that: BigDecimal): (self: BigDecimal) => Option<BigDecimal>;
(self: BigDecimal, that: BigDecimal): Option<BigDecimal>;
};divideUnsafe
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
dividefor division that returnsOption.nonewhen the divisor is zero
Signature
declare const divideUnsafe: {
(that: BigDecimal): (self: BigDecimal) => BigDecimal;
(self: BigDecimal, that: BigDecimal): BigDecimal;
};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
Signature
declare const floor: {
(scale: number): (self: BigDecimal) => BigDecimal;
(self: BigDecimal, scale?: number): BigDecimal;
};Returns the maximum between two BigDecimals.
When to use
Use to select the larger of two BigDecimal values.
See
minfor selecting the smaller value
Signature
declare const max: {
(that: BigDecimal): (self: BigDecimal) => BigDecimal;
(self: BigDecimal, that: BigDecimal): BigDecimal;
};Returns the minimum between two BigDecimals.
When to use
Use to select the smaller of two BigDecimal values.
See
maxfor selecting the larger value
Signature
declare const min: {
(that: BigDecimal): (self: BigDecimal) => BigDecimal;
(self: BigDecimal, that: BigDecimal): BigDecimal;
};Provides a multiplication operation on BigDecimals.
When to use
Use to multiply two BigDecimal values.
See
multiplyAllfor multiplying an iterable ofBigDecimalvalues
Signature
declare const multiply: {
(that: BigDecimal): (self: BigDecimal) => BigDecimal;
(self: BigDecimal, that: BigDecimal): BigDecimal;
};multiplyAll
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
multiplyfor multiplying twoBigDecimalvalues
Signature
declare function multiplyAll(collection: Iterable<BigDecimal>): BigDecimal;Provides a negate operation on BigDecimals.
When to use
Use to flip the sign of a BigDecimal.
Signature
declare function negate(n: BigDecimal): BigDecimal;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
remainderUnsafefor remainder calculation that throws when the divisor is zerodividefor decimal quotient calculation
Signature
declare const remainder: {
(divisor: BigDecimal): (self: BigDecimal) => Option<BigDecimal>;
(self: BigDecimal, divisor: BigDecimal): Option<BigDecimal>;
};remainderUnsafe
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
remainderfor returningOption.nonewhen the divisor is zero
Signature
declare const remainderUnsafe: {
(divisor: BigDecimal): (self: BigDecimal) => BigDecimal;
(self: BigDecimal, divisor: BigDecimal): BigDecimal;
};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
Signature
declare const round: {
(options: { mode?: RoundingMode; scale?: number }): (self: BigDecimal) => BigDecimal;
(
n: BigDecimal,
options?: {
mode?: RoundingMode;
scale?: number;
},
): BigDecimal;
};RoundingMode type
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
Signature
type RoundingMode =
| "ceil"
| "floor"
| "to-zero"
| "from-zero"
| "half-ceil"
| "half-floor"
| "half-to-zero"
| "half-from-zero"
| "half-even"
| "half-odd";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;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;
};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
sumAllfor summing an iterable ofBigDecimalvalues
Signature
declare const sum: {
(that: BigDecimal): (self: BigDecimal) => BigDecimal;
(self: BigDecimal, that: BigDecimal): BigDecimal;
};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
sumfor adding twoBigDecimalvalues
Signature
declare function sumAll(collection: Iterable<BigDecimal>): BigDecimal;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
Signature
declare const truncate: {
(scale: number): (self: BigDecimal) => BigDecimal;
(self: BigDecimal, scale?: number): BigDecimal;
};Models
BigDecimal interface
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;
}Predicates
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
clampfor forcing aBigDecimalinto an inclusive range
Signature
declare const between: {
(options: { maximum: BigDecimal; minimum: BigDecimal }): (self: BigDecimal) => boolean;
(
self: BigDecimal,
options: {
maximum: BigDecimal;
minimum: BigDecimal;
},
): boolean;
};Checks whether two BigDecimals are equal.
When to use
Use to compare two BigDecimal values for numeric equality.
See
Equivalencefor passing decimal equality to APIs that require anEquivalence
Signature
declare const equals: {
(that: BigDecimal): (self: BigDecimal) => boolean;
(self: BigDecimal, that: BigDecimal): boolean;
};isGreaterThan
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;
};isGreaterThanOrEqualTo
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;
};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;isLessThan
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;
};isLessThanOrEqualTo
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;
};isNegative
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;isPositive
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;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;Scaling
Normalizes a given BigDecimal by removing trailing zeros.
When to use
Use to canonicalize decimals that have equivalent values but different internal scales.
See
formatfor rendering normalized decimals as strings
Signature
declare function normalize(self: BigDecimal): BigDecimal;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
roundfor changing scale with configurable rounding
Signature
declare const scale: {
(scale: number): (self: BigDecimal) => BigDecimal;
(self: BigDecimal, scale: number): BigDecimal;
};
Creates a
BigDecimalfrom abigintvalue.When to use
Use to construct an integer
BigDecimalfrom abigint.See
makefor constructing a decimal with an explicit scale