Big.js

import Big from "big.js";

const Big = require("big.js");

<script src="big.js"></script>
<!-- Big is now available globally -->

import Big from "big.js";

// Create Big numbers from numbers, strings, or other Big numbers
const x = new Big(123.4567);
const y = Big('123456.7e-3');  // 'new' is optional
const z = new Big(x);

// All represent the same value
console.log(x.eq(y) && x.eq(z) && y.eq(z)); // true

// Arithmetic operations return new Big instances
const sum = x.plus(y);
const difference = x.minus(y);
const product = x.times(2);
const quotient = x.div(2);

// Method chaining is supported
const result = x.div(y).plus(z).times(9).minus('1.234567801234567e+8');

// String conversion with various formats
console.log(x.toString());           // "123.4567"
console.log(x.toFixed(2));           // "123.46"
console.log(x.toExponential(3));     // "1.235e+2"

/**
 * Creates a new Big number instance, or returns a new Big constructor when called without arguments
 * @param n - A numeric value: number, string, or Big instance (optional)
 * @returns Big number instance, or new Big constructor function if n is undefined
 */
function Big(n?: number | string | Big): Big;

/** Maximum decimal places for division operations (default: 20, range: 0-1000000) */
Big.DP: number;

/** Rounding mode for division operations (default: 1, range: 0-3) */
Big.RM: number;

/** Negative exponent threshold for exponential notation in toString (default: -7) */
Big.NE: number;

/** Positive exponent threshold for exponential notation in toString (default: 21) */
Big.PE: number;

/** Strict mode - throws errors for primitive number inputs (default: false) */
Big.strict: boolean;

/** Rounding mode constants */
Big.roundDown: 0;      // Toward zero (truncate)
Big.roundHalfUp: 1;    // To nearest neighbor, ties away from zero
Big.roundHalfEven: 2;  // To nearest neighbor, ties to even
Big.roundUp: 3;        // Away from zero

/**
 * Returns the absolute value of this Big number
 * @returns New Big with absolute value
 */
abs(): Big;

/**
 * Addition - returns the sum of this Big and y
 * @param y - Number to add (number, string, or Big)
 * @returns New Big with sum
 */
plus(y: number | string | Big): Big;
add(y: number | string | Big): Big; // Alias for plus

/**
 * Subtraction - returns the difference of this Big and y
 * @param y - Number to subtract (number, string, or Big)
 * @returns New Big with difference
 */
minus(y: number | string | Big): Big;
sub(y: number | string | Big): Big; // Alias for minus

/**
 * Multiplication - returns the product of this Big and y
 * @param y - Number to multiply (number, string, or Big)
 * @returns New Big with product
 */
times(y: number | string | Big): Big;
mul(y: number | string | Big): Big; // Alias for times

/**
 * Division - returns quotient of this Big divided by y, rounded to Big.DP decimal places
 * @param y - Divisor (number, string, or Big)
 * @returns New Big with quotient
 * @throws Error if y is zero
 */
div(y: number | string | Big): Big;

/**
 * Modulo - returns remainder of this Big divided by y
 * @param y - Divisor (number, string, or Big)
 * @returns New Big with remainder
 * @throws Error if y is zero
 */
mod(y: number | string | Big): Big;

/**
 * Exponentiation - returns this Big raised to power n
 * @param n - Integer exponent (-1000000 to 1000000)
 * @returns New Big with result
 * @throws Error if n is not integer or out of range
 */
pow(n: number): Big;

/**
 * Square root - returns square root of this Big, rounded to Big.DP decimal places
 * @returns New Big with square root
 * @throws Error if this Big is negative
 */
sqrt(): Big;

/**
 * Negation - returns negated value of this Big
 * @returns New Big with opposite sign
 */
neg(): Big;

/**
 * Compare this Big with y
 * @param y - Number to compare (number, string, or Big)
 * @returns 1 if greater, 0 if equal, -1 if less
 */
cmp(y: number | string | Big): number;

/**
 * Equality comparison
 * @param y - Number to compare (number, string, or Big)
 * @returns true if equal
 */
eq(y: number | string | Big): boolean;

/**
 * Greater than comparison
 * @param y - Number to compare (number, string, or Big)
 * @returns true if this Big is greater than y
 */
gt(y: number | string | Big): boolean;

/**
 * Greater than or equal comparison
 * @param y - Number to compare (number, string, or Big)
 * @returns true if this Big is greater than or equal to y
 */
gte(y: number | string | Big): boolean;

/**
 * Less than comparison
 * @param y - Number to compare (number, string, or Big)
 * @returns true if this Big is less than y
 */
lt(y: number | string | Big): boolean;

/**
 * Less than or equal comparison
 * @param y - Number to compare (number, string, or Big)
 * @returns true if this Big is less than or equal to y
 */
lte(y: number | string | Big): boolean;

/**
 * Round to specified decimal places
 * @param dp - Decimal places (optional, default 0, range: -1000000 to 1000000)
 * @param rm - Rounding mode (optional, uses Big.RM if not specified)
 * @returns New Big rounded to dp decimal places
 */
round(dp?: number, rm?: number): Big;

/**
 * Round to specified significant digits
 * @param sd - Significant digits (1 to 1000000)
 * @param rm - Rounding mode (optional, uses Big.RM if not specified)
 * @returns New Big rounded to sd significant digits
 */
prec(sd: number, rm?: number): Big;

/**
 * Standard string representation
 * Uses exponential notation based on Big.NE and Big.PE thresholds
 * @returns String representation
 */
toString(): string;

/**
 * JSON serialization (same as toString)
 * Also provides Node.js util.inspect custom formatting
 * @returns String representation for JSON.stringify and console output
 */
toJSON(): string;

/**
 * Fixed-point notation with specified decimal places
 * @param dp - Decimal places (optional, range: 0-1000000)
 * @param rm - Rounding mode (optional, uses Big.RM if not specified)
 * @returns Fixed-point string
 */
toFixed(dp?: number, rm?: number): string;

/**
 * Exponential notation with specified decimal places
 * @param dp - Decimal places (optional, range: 0-1000000)
 * @param rm - Rounding mode (optional, uses Big.RM if not specified)
 * @returns Exponential notation string
 */
toExponential(dp?: number, rm?: number): string;

/**
 * String with specified significant digits
 * Uses exponential notation if needed based on magnitude
 * @param sd - Significant digits (optional, range: 1-1000000)
 * @param rm - Rounding mode (optional, uses Big.RM if not specified)
 * @returns String with specified precision
 */
toPrecision(sd?: number, rm?: number): string;

/**
 * Primitive value conversion for type coercion
 * @returns String representation
 * @throws Error if Big.strict is true
 */
valueOf(): string;

/**
 * Convert to primitive number
 * @returns JavaScript number (may lose precision)
 * @throws Error if Big.strict is true and conversion is imprecise
 */
toNumber(): number;

/** Coefficient array containing the significant digits */
c: number[];

/** Exponent indicating decimal point position */
e: number;

/** Sign: 1 for positive, -1 for negative */
s: number;

/** Reference to the Big constructor */
constructor: typeof Big;

/**
 * Big number class for arbitrary-precision decimal arithmetic
 */
declare class Big {
  /** Coefficient array */
  c: number[];
  /** Exponent */
  e: number;
  /** Sign */
  s: number;
  /** Constructor reference */
  constructor: typeof Big;
  
  constructor(n?: number | string | Big);
  
  // Static configuration properties
  static DP: number;
  static RM: number;
  static NE: number;
  static PE: number;
  static strict: boolean;
  
  // Static rounding constants
  static roundDown: 0;
  static roundHalfUp: 1;
  static roundHalfEven: 2;
  static roundUp: 3;
  
  // Instance methods (see Capabilities sections above for details)
  abs(): Big;
  plus(y: number | string | Big): Big;
  add(y: number | string | Big): Big;
  minus(y: number | string | Big): Big;
  sub(y: number | string | Big): Big;
  times(y: number | string | Big): Big;
  mul(y: number | string | Big): Big;
  div(y: number | string | Big): Big;
  mod(y: number | string | Big): Big;
  pow(n: number): Big;
  sqrt(): Big;
  neg(): Big;
  cmp(y: number | string | Big): number;
  eq(y: number | string | Big): boolean;
  gt(y: number | string | Big): boolean;
  gte(y: number | string | Big): boolean;
  lt(y: number | string | Big): boolean;
  lte(y: number | string | Big): boolean;
  round(dp?: number, rm?: number): Big;
  prec(sd: number, rm?: number): Big;
  toString(): string;
  toJSON(): string;
  toFixed(dp?: number, rm?: number): string;
  toExponential(dp?: number, rm?: number): string;
  toPrecision(sd?: number, rm?: number): string;
  valueOf(): string;
  toNumber(): number;
}

declare const Big: {
  new (n?: number | string | Big): Big;
  (n?: number | string | Big): Big | (() => typeof Big);
  DP: number;
  RM: number;
  NE: number;
  PE: number;
  strict: boolean;
  roundDown: 0;
  roundHalfUp: 1;
  roundHalfEven: 2;
  roundUp: 3;
};

export default Big;

// Configure global precision and rounding
Big.DP = 10;                    // 10 decimal places for division
Big.RM = Big.roundHalfUp;       // Round ties away from zero

// Enable strict mode
Big.strict = true;

// JavaScript floating point issues
console.log(0.1 + 0.2);         // 0.30000000000000004

// Big.js precision
const a = new Big('0.1');
const b = new Big('0.2');
console.log(a.plus(b).toString()); // "0.3"

const price = new Big('19.99');
const tax = new Big('0.08');
const quantity = new Big('3');

const subtotal = price.times(quantity);
const taxAmount = subtotal.times(tax);
const total = subtotal.plus(taxAmount);

console.log(total.toFixed(2));   // "64.77"

// Create independent Big constructors with different configurations
const FinancialBig = Big();      // New constructor
FinancialBig.DP = 2;             // 2 decimal places for currency
FinancialBig.RM = FinancialBig.roundHalfUp;

const ScientificBig = Big();     // Another constructor  
ScientificBig.DP = 50;           // High precision for science
ScientificBig.RM = ScientificBig.roundHalfEven;