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

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Constructor and Creation

Name: tessl/npm-bignumber-js
Author: tessl

Core BigNumber constructor and instance creation functionality with support for different bases, input types, and special values.

Capabilities

BigNumber Constructor

Creates a new BigNumber instance from various input types with optional base specification.

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

// Constructor can also be called without 'new'
BigNumber(n: BigNumber.Value, base?: number): BigNumber;

Usage Examples:

import BigNumber from "bignumber.js";

// From string (recommended for precision)
const a = new BigNumber('123.456789');
const b = new BigNumber('1.23e+5');
const c = new BigNumber('-42.7e-10');

// From number (precision may be lost)
const d = new BigNumber(123.456789);
const e = new BigNumber(-42);

// From bigint (Node.js/modern browsers)
const f = new BigNumber(123456789012345678901234567890n);

// From another BigNumber
const g = new BigNumber(a);

// With different bases
const hex = new BigNumber('ff.8', 16);        // 255.5 in decimal
const binary = new BigNumber('1011.101', 2);  // 11.625 in decimal
const base36 = new BigNumber('zz.9', 36);     // 1295.25 in decimal

// Without 'new' keyword
const h = BigNumber('999.999');

Special Values

BigNumber supports JavaScript's special numeric values with proper handling.

// Special values are supported
new BigNumber('Infinity');      // Positive infinity
new BigNumber('-Infinity');     // Negative infinity  
new BigNumber('NaN');           // Not a Number
new BigNumber(NaN);             // Not a Number
new BigNumber(-0);              // Negative zero (preserved)

Usage Examples:

// Special values
const infinity = new BigNumber('Infinity');
const negInfinity = new BigNumber('-Infinity');
const notANumber = new BigNumber('NaN');
const negZero = new BigNumber(-0);

console.log(infinity.toString());     // "Infinity"
console.log(negInfinity.toString());  // "-Infinity"
console.log(notANumber.toString());   // "NaN"
console.log(negZero.valueOf());       // "-0"

Input Validation

BigNumber handles invalid inputs gracefully, returning NaN unless debug mode is enabled.

// Invalid inputs return BigNumber NaN (unless DEBUG = true)
new BigNumber('invalid');       // BigNumber NaN
new BigNumber('1.2.3');         // BigNumber NaN
new BigNumber(9, 2);            // BigNumber NaN (9 is not valid in base 2)

Debug Mode:

// Enable debug mode for error throwing
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"
}

Precision Considerations

When creating BigNumbers from JavaScript numbers, precision may be lost due to floating-point limitations.

Usage Examples:

// Precision loss from numeric literals
new BigNumber(1.0000000000000001);         // "1" (precision lost)
new BigNumber(99999999999999999999);       // "100000000000000000000"

// Use strings to preserve precision
new BigNumber('1.0000000000000001');       // "1.0000000000000001"
new BigNumber('99999999999999999999');     // "99999999999999999999"

// Floating-point arithmetic issues
new BigNumber(0.1 + 0.2);                  // "0.30000000000000004"
new BigNumber('0.1').plus('0.2');          // "0.3"

Object Literal Construction

BigNumber instances can be created from object literals with coefficient, exponent, and sign properties.

/**
 * Create BigNumber from object literal (advanced usage)
 * @param obj - Object with c (coefficient), e (exponent), s (sign) properties
 */
new BigNumber({
  c: number[] | null,      // Coefficient array (base 1e14)
  e: number | null,        // Exponent (-1e9 to 1e9)
  s: number | null,        // Sign (-1, 1, or null)
  _isBigNumber: true       // Internal identifier
}): BigNumber;

Usage Examples:

// Object literal construction (advanced)
const x = new BigNumber({
  s: 1,
  e: 2,
  c: [777, 12300000000000],
  _isBigNumber: true
});
console.log(x.toString()); // "777.123"

// Verify object is well-formed
console.log(BigNumber.isBigNumber(x)); // true

Types

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

interface BigNumber.Instance {
  readonly c: number[] | null;    // Coefficient array
  readonly e: number | null;      // Exponent value
  readonly s: number | null;      // Sign value
  [key: string]: any;
}