CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-bignumber-js

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

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

configuration.mddocs/

Configuration and Static Methods

Global configuration, utility methods, and constants for customizing BigNumber behavior and working with multiple BigNumber values.

Capabilities

Global Configuration

Configure global settings that affect all BigNumber operations.

/**
 * Configure global BigNumber settings
 * @param object - Configuration object (optional)
 * @returns Current configuration object
 */
static config(object?: BigNumber.Config): BigNumber.Config;

// Alias
static set(object?: BigNumber.Config): BigNumber.Config;

Usage Examples:

import BigNumber from "bignumber.js";

// Get current configuration
const currentConfig = BigNumber.config();
console.log(currentConfig.DECIMAL_PLACES); // 20 (default)

// Set configuration
BigNumber.config({
  DECIMAL_PLACES: 40,
  ROUNDING_MODE: BigNumber.ROUND_HALF_CEIL,
  EXPONENTIAL_AT: [-10, 20],
  RANGE: [-500, 500],
  CRYPTO: true,
  MODULO_MODE: BigNumber.ROUND_FLOOR,
  POW_PRECISION: 80,
  FORMAT: {
    groupSize: 3,
    groupSeparator: ' ',
    decimalSeparator: ','
  },
  ALPHABET: '0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ$_'
});

// Verify configuration
console.log(BigNumber.config().DECIMAL_PLACES); // 40

// Using alias method (equivalent to config)
BigNumber.set({ DECIMAL_PLACES: 5 });

Constructor Cloning

Create independent BigNumber constructor with custom configuration.

/**
 * Creates new independent BigNumber constructor with custom configuration
 * @param object - Configuration object (optional)
 * @returns New BigNumber constructor function
 */
static clone(object?: BigNumber.Config): BigNumber.Constructor;

Usage Examples:

// Create separate BigNumber constructor
const BN = BigNumber.clone({ DECIMAL_PLACES: 9 });

const x = new BigNumber(1);
const y = new BN(1);

x.div(3);                       // "0.33333" (default 20 decimal places)
y.div(3);                       // "0.333333333" (9 decimal places)

// Equivalent to:
const BN2 = BigNumber.clone();
BN2.config({ DECIMAL_PLACES: 9 });

// Original BigNumber unchanged
console.log(BigNumber.config().DECIMAL_PLACES); // Still 20

Type Checking

Check if a value is a BigNumber instance.

/**
 * Returns true if value is a BigNumber instance
 * @param value - Value to test
 * @returns Boolean indicating if value is BigNumber
 */
static isBigNumber(value: any): value is BigNumber;

Usage Examples:

const x = 42;
const y = new BigNumber(x);

BigNumber.isBigNumber(x);       // false
y instanceof BigNumber;         // true
BigNumber.isBigNumber(y);       // true

// Works with cloned constructors
const BN = BigNumber.clone();
const z = new BN(x);
z instanceof BigNumber;         // false (different constructor)
BigNumber.isBigNumber(z);       // true (still a BigNumber instance)

// Debug mode validation
BigNumber.DEBUG = true;
// If BigNumber is malformed, isBigNumber will throw error

Maximum Value

Returns the maximum value from a set of BigNumbers.

/**
 * Returns BigNumber with maximum value from arguments
 * @param n - Numeric values to compare
 * @returns BigNumber with maximum value
 */
static maximum(...n: BigNumber.Value[]): BigNumber;

// Alias
static max(...n: BigNumber.Value[]): BigNumber;

Usage Examples:

const x = new BigNumber('3257869345.0378653');
BigNumber.maximum(4e9, x, '123456789.9'); // "4000000000"
BigNumber.max(4e9, x, '123456789.9');     // "4000000000" (alias)

// With array using apply
const arr = [12, '13', new BigNumber(14)];
BigNumber.maximum.apply(null, arr);       // "14"

// Spread operator (modern approach)
BigNumber.max(...arr);                    // "14"

// Mixed types
BigNumber.max(
  new BigNumber('1.5'), 
  2.7, 
  '3.14159', 
  new BigNumber('-100')
);                                        // "3.14159"

Minimum Value

Returns the minimum value from a set of BigNumbers.

/**
 * Returns BigNumber with minimum value from arguments
 * @param n - Numeric values to compare
 * @returns BigNumber with minimum value
 */
static minimum(...n: BigNumber.Value[]): BigNumber;

// Alias
static min(...n: BigNumber.Value[]): BigNumber;

Usage Examples:

const x = new BigNumber('3257869345.0378653');
BigNumber.minimum(4e9, x, '123456789.9');          // "123456789.9"
BigNumber.min(4e9, x, '123456789.9');              // "123456789.9" (alias)

// With negative numbers
const arr = [2, new BigNumber(-14), '-15.9999', -12];
BigNumber.minimum.apply(null, arr);                 // "-15.9999"
BigNumber.min(...arr);                              // "-15.9999"

Sum Calculation

Returns the sum of multiple BigNumbers.

/**
 * Returns BigNumber with sum of all arguments
 * @param n - Numeric values to sum
 * @returns BigNumber with sum
 */
static sum(...n: BigNumber.Value[]): BigNumber;

Usage Examples:

const x = new BigNumber('3257869345.0378653');
BigNumber.sum(4e9, x, '123456789.9');      // "7381326134.9378653"

// With array
const arr = [2, new BigNumber(14), '15.9999', 12];
BigNumber.sum.apply(null, arr);            // "43.9999"
BigNumber.sum(...arr);                     // "43.9999"

// Empty arguments
BigNumber.sum();                           // "0"

// Single argument
BigNumber.sum('42.5');                     // "42.5"

Random Number Generation

Generate cryptographically secure or pseudo-random BigNumbers.

/**
 * Returns pseudo-random BigNumber between 0 and 1
 * @param decimalPlaces - Number of decimal places (0 to 1e9, optional)
 * @returns Random BigNumber
 */
static random(decimalPlaces?: number): BigNumber;

Usage Examples:

// Default decimal places (uses DECIMAL_PLACES setting)
BigNumber.config({ DECIMAL_PLACES: 10 });
BigNumber.random();                        // "0.4117936847" (example)

// Specific decimal places
BigNumber.random(20);                      // "0.78193327636914089009" (example)

// Cryptographically secure (if supported)
BigNumber.config({ CRYPTO: true });
BigNumber.random();                        // Uses crypto.getRandomValues or crypto.randomBytes

// For Node.js crypto support
// global.crypto = require('crypto');
// BigNumber.config({ CRYPTO: true });

// Check if crypto is enabled
const config = BigNumber.config();
console.log(config.CRYPTO);                // true/false

Debug Mode

Enable debug mode for error throwing instead of returning NaN.

/**
 * Enable/disable debug mode for error throwing
 */
static DEBUG?: boolean;

Usage Examples:

// Default behavior (no errors thrown)
new BigNumber('invalid');                  // BigNumber NaN
new BigNumber(9, 2);                       // BigNumber NaN

// Enable debug mode
BigNumber.DEBUG = true;

try {
  new BigNumber('invalid');
} catch (error) {
  console.log(error.message);              // "[BigNumber Error] Not a number"
}

try {
  new BigNumber(9, 2);
} catch (error) {
  console.log(error.message);              // "[BigNumber Error] Not a base 2 number"
}

// Number with too many significant digits
try {
  new BigNumber(823456789123456.3);
} catch (error) {
  console.log(error.message);              // "[BigNumber Error] Number primitive has more than 15 significant digits"
}

// Malformed BigNumber detection
const x = new BigNumber(10);
x.c = NaN; // Corrupt the instance
try {
  BigNumber.isBigNumber(x);
} catch (error) {
  console.log(error.message);              // "[BigNumber Error] Invalid BigNumber"
}

Configuration Properties

interface BigNumber.Config {
  /** Maximum decimal places for division operations (0 to 1e9, default: 20) */
  DECIMAL_PLACES?: number;
  
  /** Default rounding mode (0-8, default: 4) */
  ROUNDING_MODE?: BigNumber.RoundingMode;
  
  /** Exponential notation thresholds (default: [-7, 20]) */
  EXPONENTIAL_AT?: number | [number, number];
  
  /** Overflow/underflow limits (default: [-1e9, 1e9]) */
  RANGE?: number | [number, number];
  
  /** Use cryptographically secure random generation (default: false) */
  CRYPTO?: boolean;
  
  /** Modulo operation mode (0,1,3,6,9, default: 1) */
  MODULO_MODE?: BigNumber.ModuloMode;
  
  /** Maximum precision for power operations (0 to 1e9, default: 0) */
  POW_PRECISION?: number;
  
  /** Default formatting options for toFormat() */
  FORMAT?: BigNumber.Format;
  
  /** Character set for base conversion (default: '0123456789abcdefghijklmnopqrstuvwxyz') */
  ALPHABET?: string;
}

Configuration Examples:

// Financial calculations
BigNumber.config({
  DECIMAL_PLACES: 4,           // 4 decimal places for currency
  ROUNDING_MODE: BigNumber.ROUND_HALF_EVEN,  // Banker's rounding
  FORMAT: {
    prefix: '$',
    groupSeparator: ',',
    groupSize: 3
  }
});

// Scientific calculations
BigNumber.config({
  DECIMAL_PLACES: 50,          // High precision
  EXPONENTIAL_AT: [-20, 20],   // Wide range before exponential notation
  POW_PRECISION: 100           // High precision for powers
});

// Cryptocurrency (high precision integers)
BigNumber.config({
  DECIMAL_PLACES: 18,          // Wei precision for Ethereum
  ROUNDING_MODE: BigNumber.ROUND_DOWN  // No rounding up for safety
});

// Custom alphabet for base conversion
BigNumber.config({
  ALPHABET: '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ'  // Uppercase hex
});

const x = new BigNumber(255);
x.toString(16);                // "FF" instead of "ff"

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

// Type definitions
type BigNumber.Constructor = typeof BigNumber;
type BigNumber.RoundingMode = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8;
type BigNumber.ModuloMode = 0 | 1 | 3 | 6 | 9;

docs

arithmetic.md

comparison.md

configuration.md

constructor.md

conversion.md

index.md

precision.md

tile.json