Typescript BigNumber

A native big decimal NPM library for Typescript using the BigInt class. It supports fixed-point decimal arithmetic with 18 decimal places in the range -1e36 to 1e36, inclusive.

Features

• Support for fixed-point numbers in the range [-1e36, 1e36] with 18 decimal places.
• Static constructors: copysign(), fromBigInt(), fromString().
• Static constants: E, EULER, INF, POSITIVE_INFINITY, NEG_INF, NEGATIVE_INFINITY, LN_10, LN_2, PI.
• Type conversion methods: toBigInt(), toString(), toInteger().
• Type check methods: isInteger(), isPositive().
• Arithmetic conversion methods: abs(), ceil(), floor(), inv(), neg(), round(), trunc().
• Logic comparison methods: equals(), gt(), greaterThan(), gte(), greaterThanOrEqual(), lt(), lessThan(), lte(), lessThanOrEqual().
• Arithmetic operations: add(), sub(), mul(), div(), mod().

The library does not include a fromNumber() function to preserve precision.

Installation

Node.js 22 or newer is required.

npm install typescript-bignumber

Usage

Once imported, you can use BigNumber in any Typescript project.

import { BigNumber } from 'typescript-bignumber';

const x = BigNumber.fromString('1.28');
const y = BigNumber.fromBigInt(2n);

console.log(x.mul(y).toString()); // 2.56

Creating a BigNumber

You can create a new BigNumber by using fromString() or fromBigInt(). The class does not include a public constructor.

const x = BigNumber.fromString('12.374738');
const y = BigNumber.fromBigInt(12489203475n);

fromString() supports a dot or comma as the decimal separator and also supports scientific notation.

const x = BigNumber.fromString('12,374738');
const y = BigNumber.fromString('1.27e-5');

If the given number has more than 18 decimal places, it is rounded to the 18th decimal place. Ties are rounded away from zero.

const x = BigNumber.fromString('1.9999999999999999999');

console.log(x.toString()); // 2

copysign() takes two BigNumber instances and returns the first argument with the sign of the second argument.

const x = BigNumber.fromString('1.2');
const sign = BigNumber.fromString('-1');

console.log(BigNumber.copysign(x, sign).toString()); // -1.2

Formatting and Conversion

toString() serializes the instance without unnecessary trailing zeros. Pass true to always include all 18 decimal places.

const x = BigNumber.fromString('12.54');

console.log(x.toString());     // 12.54
console.log(x.toString(true)); // 12.540000000000000000

toBigInt() returns the closest BigInt. toInteger() returns the same rounded integer as a string.

const x = BigNumber.fromString('12.54');

console.log(x.toBigInt());  // 13n
console.log(x.toInteger()); // 13

toBigInt(), toInteger(), and round() follow Math.round() behavior. Ties are rounded toward positive infinity.

console.log(BigNumber.fromString('-1.5').round().toString()); // -1

Static Constants

Commonly used mathematical constants are defined under the class and rounded to 18 decimal places.

BigNumber.E;     // Also available as BigNumber.EULER
BigNumber.LN_10;
BigNumber.LN_2;
BigNumber.PI;

INF and NEG_INF are the finite upper and lower bounds of the library. They are also available as POSITIVE_INFINITY and NEGATIVE_INFINITY.

console.log(BigNumber.INF.toString());
// 1000000000000000000000000000000000000

console.log(BigNumber.NEG_INF.toString());
// -1000000000000000000000000000000000000

Methods

Methods that return a BigNumber create a new instance and do not change the existing instance.

Method	Description
abs()	Returns the absolute value.
ceil()	Returns the smallest integer greater than or equal to the value.
floor()	Returns the largest integer less than or equal to the value.
inv()	Returns the inverse of the value.
neg()	Returns the negation of the value.
round()	Returns the value rounded to the closest integer.
trunc()	Returns the integer part by removing fractional digits.
equals(other)	Checks if both values are equal.
gt(other), greaterThan(other)	Checks if the value is greater than other.
gte(other), greaterThanOrEqual(other)	Checks if the value is greater than or equal to other.
lt(other), lessThan(other)	Checks if the value is less than other.
lte(other), lessThanOrEqual(other)	Checks if the value is less than or equal to other.
add(other)	Adds other to the value.
sub(other)	Subtracts other from the value.
mul(other)	Multiplies the value by other.
div(other)	Divides the value by other.
mod(other)	Returns the remainder of division by other.

Multiplication and division results are rounded to 18 decimal places. Ties are rounded away from zero.

mod() follows the Javascript remainder operator (%), including its behavior with negative numbers.

const x = BigNumber.fromString('126.289');
const y = BigNumber.fromString('34.433');

console.log(x.add(y).toString()); // 160.722
console.log(x.sub(y).toString()); // 91.856
console.log(x.mul(y).toString()); // 4348.509137
console.log(x.div(y).toString()); // 3.667673452792379403
console.log(x.mod(y).toString()); // 22.99

isInteger() checks if the value is an integer. isPositive() checks if the value is greater than zero; zero is not positive.

Range and Errors

All values and operation results must be in the range [-1e36, 1e36], inclusive.

• Invalid strings, including NaN and infinity, throw a SyntaxError.
• Values outside the supported range throw a RangeError.
• Division or remainder by zero throws a RangeError.