tessl/npm-bignumber-js
A JavaScript library for arbitrary-precision decimal and non-decimal arithmetic
- Workspace
- tessl
- Visibility
- Public
- Created
- Last updated
- Describes
To install, run
npx @tessl/cli install tessl/npm-bignumber-js@8.1.0index.mddocs/
BigNumber.js
BigNumber.js is a JavaScript library for arbitrary-precision decimal and non-decimal arithmetic. It provides precise calculations for numbers that exceed JavaScript's native Number precision limits, handles both finite and infinite values (including NaN), supports number bases from 2 to 36, and maintains immutability with chainable methods for complex calculations.
Package Information
- Package Name: bignumber.js
- Package Type: npm
- Language: JavaScript with TypeScript definitions
- Installation:
npm install bignumber.js
Core Imports
const BigNumber = require('bignumber.js');ES modules:
import BigNumber from 'bignumber.js';
// or
import { BigNumber } from 'bignumber.js';Browser:
<script src='bignumber.js'></script>
<!-- BigNumber available globally -->Basic Usage
const BigNumber = require('bignumber.js');
// Create BigNumber instances
const x = new BigNumber(123.4567);
const y = new BigNumber('123456.7e-3');
const z = new BigNumber(x);
// Perform arithmetic operations
const sum = x.plus(y);
const product = x.multipliedBy(2);
const quotient = x.dividedBy(3);
// Compare values
x.isEqualTo(y); // true
x.isGreaterThan(100); // true
// Format output
x.toString(); // '123.4567'
x.toFixed(2); // '123.46'
x.toExponential(2); // '1.23e+2'Architecture
BigNumber.js is built around several key components:
- BigNumber Constructor: Creates immutable BigNumber instances from strings, numbers, or other BigNumbers
- Internal Representation: Uses base 1e14 coefficient arrays with sign and exponent properties for maximum precision
- Arithmetic Operations: All operations return new BigNumber instances, maintaining immutability
- Configuration System: Global configuration for precision, rounding modes, and formatting
- Type Safety: Full TypeScript support with comprehensive type definitions
Capabilities
Constructor and Creation
Core BigNumber constructor for creating arbitrary-precision number instances from various input types.
/**
* Creates a new BigNumber instance
* @param {string|number|BigNumber} n - The numeric value
* @param {number} [base] - The base of n (2-36), default 10
*/
new BigNumber(n, base)Arithmetic Operations
Mathematical operations including addition, subtraction, multiplication, division, and exponentiation with full precision.
// Basic arithmetic
plus(n, base): BigNumber
minus(n, base): BigNumber
multipliedBy(n, base): BigNumber
dividedBy(n, base): BigNumber
// Advanced operations
exponentiatedBy(n, m): BigNumber
squareRoot(): BigNumber
modulo(n, base): BigNumberComparison Methods
Value comparison methods that handle precision edge cases and special values like NaN and Infinity.
// Comparison methods
comparedTo(n, base): number
isEqualTo(n, base): boolean
isGreaterThan(n, base): boolean
isLessThan(n, base): boolean
isGreaterThanOrEqualTo(n, base): boolean
isLessThanOrEqualTo(n, base): booleanType Checking and Properties
Methods for checking number types and properties, including finite/infinite status and sign detection.
// Type checking
isFinite(): boolean
isInteger(): boolean
isNaN(): boolean
isNegative(): boolean
isPositive(): boolean
isZero(): boolean
// Utility methods
absoluteValue(): BigNumber
negated(): BigNumberPrecision and Rounding
Control decimal places, significant digits, and rounding behavior for calculations and output formatting.
// Precision control
precision(includeZeros?: boolean): number
precision(significantDigits: number, roundingMode?: number): BigNumber
decimalPlaces(): number
decimalPlaces(dp: number, rm?: number): BigNumber
integerValue(rm?: number): BigNumber
shiftedBy(n: number): BigNumberString Conversion and Formatting
Multiple output formats including fixed-point, exponential, precision notation, and custom formatting.
// String conversion
toString(base?: number): string
toFixed(dp?: number, rm?: number): string
toExponential(dp?: number, rm?: number): string
toPrecision(sd?: number, rm?: number): string
toFormat(dp?: number, rm?: number, format?: object): string
// Specialized formats
toFraction(maxDenominator?: number): [BigNumber, BigNumber]
toNumber(): number
valueOf(): string
toJSON(): stringConfiguration and Static Methods
Global configuration options and static utility methods for BigNumber behavior customization.
// Configuration
BigNumber.config(object): object
BigNumber.set(object): object
BigNumber.clone(config?: object): Constructor
// Static utilities
BigNumber.isBigNumber(value): boolean
BigNumber.maximum(...values): BigNumber
BigNumber.minimum(...values): BigNumber
BigNumber.random(dp?: number): BigNumber
BigNumber.sum(...values): BigNumberConstants and Enums
// Rounding mode constants
ROUND_UP: 0
ROUND_DOWN: 1
ROUND_CEIL: 2
ROUND_FLOOR: 3
ROUND_HALF_UP: 4
ROUND_HALF_DOWN: 5
ROUND_HALF_EVEN: 6
ROUND_HALF_CEIL: 7
ROUND_HALF_FLOOR: 8
// Modulo mode constants
EUCLID: 9
// Debug property
DEBUG: booleanTypes
// Core types
BigNumber.Value = string | number | BigNumber.Instance
BigNumber.RoundingMode = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8
BigNumber.ModuloMode = 0 | 1 | 3 | 6 | 9
// Instance interface
interface BigNumber.Instance {
c: number[] | null; // coefficient
e: number | null; // exponent
s: number | null; // sign
}
// Configuration interface
interface BigNumber.Config {
DECIMAL_PLACES?: number;
ROUNDING_MODE?: BigNumber.RoundingMode;
EXPONENTIAL_AT?: number | [number, number];
RANGE?: number | [number, number];
CRYPTO?: boolean;
MODULO_MODE?: BigNumber.ModuloMode;
POW_PRECISION?: number;
FORMAT?: BigNumber.Format;
ALPHABET?: string;
}
// Format interface
interface BigNumber.Format {
prefix?: string;
decimalSeparator?: string;
groupSeparator?: string;
groupSize?: number;
secondaryGroupSize?: number;
fractionGroupSeparator?: string;
fractionGroupSize?: number;
suffix?: string;
}