or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

arithmetic.mdcomparison.mdconfiguration.mdconstructor.mdconversion.mdindex.mdprecision.md
tile.json

tessl/npm-bignumber.js

A JavaScript library for arbitrary-precision decimal and non-decimal arithmetic

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/bignumber.js@9.3.x

To install, run

npx @tessl/cli install tessl/npm-bignumber.js@9.3.0

index.mddocs/

BigNumber.js

BigNumber.js is a JavaScript library for arbitrary-precision decimal and non-decimal arithmetic. It provides a comprehensive API for handling large numbers and decimal calculations that exceed JavaScript's native number limitations, ensuring accurate mathematical operations without floating-point precision errors.

Package Information

  • Package Name: bignumber.js
  • Package Type: npm
  • Language: JavaScript (with TypeScript definitions)
  • Installation: npm install bignumber.js

Core Imports

import BigNumber from "bignumber.js";

For CommonJS:

const BigNumber = require("bignumber.js");

Named exports (ES modules):

import { BigNumber } from "bignumber.js";

ESM Module Format:

import BigNumber from "bignumber.js/bignumber.mjs";

Basic Usage

import BigNumber from "bignumber.js";

// Create BigNumbers from strings for precision
const x = new BigNumber('123.456789');
const y = new BigNumber('987.654321');

// Perform precise arithmetic operations
const sum = x.plus(y);                    // "1111.11111"
const product = x.multipliedBy(y);        // "121932.631112635269"
const quotient = x.dividedBy(y);          // "0.124999998860937514"

// Compare values
const isEqual = x.isEqualTo('123.456789'); // true
const isGreater = y.isGreaterThan(x);      // true

// Convert to different formats
console.log(sum.toString());               // "1111.11111"
console.log(product.toFixed(2));          // "121932.63"
console.log(quotient.toExponential(5));   // "1.25000e-1"

Architecture

BigNumber.js is built around several key components:

  • BigNumber Constructor: Creates immutable BigNumber instances from strings, numbers, or other BigNumbers
  • Arithmetic Operations: Full set of mathematical operations with configurable precision and rounding
  • Comparison Methods: Complete comparison API for equality, ordering, and special value checks
  • Conversion Methods: Multiple output formats including strings, numbers, fractions, and formatted representations
  • Configuration System: Global and instance-specific settings for precision, rounding modes, and formatting
  • Type Safety: Complete TypeScript definitions with generic type support

Capabilities

Constructor and Creation

Core BigNumber constructor and instance creation with support for different bases and input types.

/**
 * Creates a new BigNumber instance
 * @param n - Numeric value (string, number, bigint, or BigNumber)
 * @param base - Number base (2-36, defaults to 10)
 */
new BigNumber(n: BigNumber.Value, base?: number): BigNumber;

// Also works without 'new'
BigNumber(n: BigNumber.Value, base?: number): BigNumber;

type BigNumber.Value = string | number | bigint | BigNumber.Instance;

Constructor and Creation

Arithmetic Operations

Complete set of mathematical operations for addition, subtraction, multiplication, division, exponentiation, and more.

// Basic arithmetic operations
plus(n: BigNumber.Value, base?: number): BigNumber;
minus(n: BigNumber.Value, base?: number): BigNumber;
multipliedBy(n: BigNumber.Value, base?: number): BigNumber;
dividedBy(n: BigNumber.Value, base?: number): BigNumber;

// Power and root operations
exponentiatedBy(n: BigNumber.Value, m?: BigNumber.Value): BigNumber;
squareRoot(): BigNumber;

// Aliases available: times, div, pow, sqrt

Arithmetic Operations

Comparison Methods

Comprehensive comparison functionality for equality testing, ordering, and special value detection.

// Equality and ordering
isEqualTo(n: BigNumber.Value, base?: number): boolean;
isGreaterThan(n: BigNumber.Value, base?: number): boolean;
isLessThan(n: BigNumber.Value, base?: number): boolean;
comparedTo(n: BigNumber.Value, base?: number): 1 | -1 | 0 | null;

// Special value checks
isFinite(): boolean;
isInteger(): boolean;
isNaN(): boolean;
isZero(): boolean;

// Aliases available: eq, gt, lt, gte, lte

Comparison Methods

Conversion and Formatting

Multiple output formats including strings, numbers, fractions, and locale-specific formatting.

// String conversion with base support
toString(base?: number): string;
toFixed(decimalPlaces?: number, roundingMode?: BigNumber.RoundingMode): string;
toExponential(decimalPlaces?: number, roundingMode?: BigNumber.RoundingMode): string;
toPrecision(significantDigits?: number, roundingMode?: BigNumber.RoundingMode): string;

// Special formatting
toFormat(decimalPlaces?: number, roundingMode?: BigNumber.RoundingMode, format?: BigNumber.Format): string;
toFraction(maxDenominator?: BigNumber.Value): [BigNumber, BigNumber];
toNumber(): number;

Conversion and Formatting

Precision and Rounding

Precision control and rounding operations for decimal places and significant digits.

// Precision methods
decimalPlaces(dp?: number, rm?: BigNumber.RoundingMode): number | BigNumber;
precision(sd?: number, rm?: BigNumber.RoundingMode): number | BigNumber;
integerValue(rm?: BigNumber.RoundingMode): BigNumber;
shiftedBy(n: number): BigNumber;

// Aliases: dp, sd

Precision and Rounding

Configuration and Static Methods

Global configuration, utility methods, and constants for customizing BigNumber behavior.

// Configuration
static config(object?: BigNumber.Config): BigNumber.Config;
static clone(object?: BigNumber.Config): BigNumber.Constructor;

// Utility methods
static isBigNumber(value: any): value is BigNumber;
static maximum(...values: BigNumber.Value[]): BigNumber;
static minimum(...values: BigNumber.Value[]): BigNumber;
static random(decimalPlaces?: number): BigNumber;
static sum(...values: BigNumber.Value[]): BigNumber;

// Aliases: set, max, min

Configuration and Static Methods

Core Types

interface BigNumber.Config {
  DECIMAL_PLACES?: number;        // 0 to 1e9, default 20
  ROUNDING_MODE?: BigNumber.RoundingMode;  // 0-8, default 4
  EXPONENTIAL_AT?: number | [number, number]; // default [-7, 20]
  RANGE?: number | [number, number];          // default [-1e9, 1e9]
  CRYPTO?: boolean;               // default false
  MODULO_MODE?: BigNumber.ModuloMode;     // 0,1,3,6,9, default 1
  POW_PRECISION?: number;         // 0 to 1e9, default 0
  FORMAT?: BigNumber.Format;
  ALPHABET?: string;
}

interface BigNumber.Format {
  prefix?: string;
  suffix?: string;
  decimalSeparator?: string;
  groupSeparator?: string;
  groupSize?: number;
  secondaryGroupSize?: number;
  fractionGroupSeparator?: string;
  fractionGroupSize?: number;
}

type BigNumber.RoundingMode = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8;
type BigNumber.ModuloMode = 0 | 1 | 3 | 6 | 9;
type BigNumber.Value = string | number | bigint | BigNumber.Instance;

Constants

// Rounding modes
static readonly ROUND_UP: 0;         // Round away from zero
static readonly ROUND_DOWN: 1;       // Round towards zero  
static readonly ROUND_CEIL: 2;       // Round towards +Infinity
static readonly ROUND_FLOOR: 3;      // Round towards -Infinity
static readonly ROUND_HALF_UP: 4;    // Round to nearest, ties away from zero
static readonly ROUND_HALF_DOWN: 5;  // Round to nearest, ties towards zero
static readonly ROUND_HALF_EVEN: 6;  // Round to nearest, ties to even
static readonly ROUND_HALF_CEIL: 7;  // Round to nearest, ties towards +Infinity
static readonly ROUND_HALF_FLOOR: 8; // Round to nearest, ties towards -Infinity

// Modulo modes
static readonly EUCLID: 9;           // Euclidean modulo mode

// Debug mode
static DEBUG?: boolean;              // Enable debug error throwing