Package Exports

@numio/bigmath
@numio/bigmath/package.json

Readme

@numio/bigmath: Precise Arithmetic Beyond JavaScript's Limits

Do you struggle with inaccurate calculations involving very large or very small numbers, or decimal numbers with high precision in JavaScript?

@numio/bigmath is your solution! This library provides a robust set of functions for performing arbitrary-precision arithmetic, effectively overcoming the limitations of JavaScript's built-in Number type. Say goodbye to unexpected rounding errors and precision loss when dealing with numbers that exceed 15 significant digits or involve complex decimal operations.

Why Choose @numio/bigmath?

Solve Precision Problems:

Handle Numbers of Any Size: Perform calculations on integers and decimals of virtually unlimited length, without the risk of JavaScript's Number limitations.
Eliminate Precision Loss: Achieve accurate results even with numeric literals exceeding 15 significant digits, ensuring the integrity of your calculations.
Precise Decimal Operations: Execute addition, subtraction, multiplication, and division on decimal numbers with guaranteed accuracy, including scenarios with negative values.

Unlock Advanced Numerical Operations:

Control Division Precision: Specify the exact number of digits after the decimal point for division results, with a default precision of 20 digits for high accuracy.
Flexible Rounding: Round numbers to the nearest integer or a specific number of decimal places with various rounding modes (up, down, half-up, half-down, half-even, half-odd) to meet your exact requirements.
Round Based on Significant Figures: Control rounding based on the number of significant figures, crucial for scientific and engineering applications.
Chain Operations with Pipe: Simplify complex calculations by chaining arithmetic operations in a readable and intuitive manner.
Analyze Data Distribution:
- Calculate Quartiles (Q1, Q2, Q3): Understand the spread and central tendency of your numerical data, helping identify outliers and the shape of the distribution.
- Calculate Median Absolute Deviation (MAD): Measure the dispersion of a dataset, providing a robust alternative to standard deviation that is less sensitive to outliers.
- Calculate Interquartile Range (IQR): Determine the spread of the middle 50% of your data, useful for identifying the central bulk and potential outliers.
Compare Numbers:
- Check for Equality (isEqual): Accurately determine if two arbitrary-precision numbers are equal.
- Check if Left is Greater (isLeftGreater): Precisely compare two arbitrary-precision numbers to see if the left operand is greater than the right.
Sort Numbers Accurately: Sort arrays of numbers, including negative and decimal values, in ascending or descending order, correctly handling string representations of numbers that JavaScript's native sort might misinterpret.
Calculate Central Tendency: Easily compute the mean (average) of a set of numbers.
Identify Extremes: Find the maximum and minimum values within an array of numbers.

When is @numio/bigmath essential?

This library is particularly invaluable in applications where numerical accuracy and the ability to handle large numbers are paramount:

Financial Applications: Accurate calculations for large sums of money, precise interest rates, and complex financial modeling.
Scientific Computing: Working with extremely large or small numbers in simulations, data analysis, and research.
Cryptography: Implementing cryptographic algorithms that rely on high-precision arithmetic.
E-commerce and Payments: Handling precise amounts and avoiding rounding errors in transactions.
Data Analysis and Statistics: Performing accurate statistical calculations on datasets with varying scales.
Any Scenario Exceeding JavaScript's Number Limits: Ensuring the reliability of your calculations when dealing with numbers beyond the safe integer limit or requiring more than 15 significant digits.

With @numio/bigmath, you can confidently perform complex arithmetic operations with the assurance of accuracy, regardless of the size or precision of the numbers involved.

Latest update

Added isEqual and isLeftGreater - to compare 2 numbers.
Added MAD - Median Absolute Deviation.
Added IQR - Interquartile Range.

Install:

NPM

npm install @numio/bigmath

YARN

yarn add @numio/bigmath

BUN

bun add @numio/bigmath

PNPM

pnpm add @numio/bigmath

DENO

deno add jsr:@numio/bigmath

Examples:

Add numbers

import { add } from "@numio/bigmath";

const int = add(["12345", "99"]); // 12444
const float = add(["0.1", "0.2", "0.3"]); // 0.6
const negative = add(["0.1", "-0.3", "0.1"]); // -0.1

Subtract numbers

import { sub } from "@numio/bigmath";

const int = sub(["150", "99"]); // 51
const float = sub(["1", "0.99"]); // 0.01
const negative = sub(["-0.1", "-0.3", "0.4"]); // -0.2

Multiply numbers

import { mul } from "@numio/bigmath";

const int = mul(["15", "11", "2"]); // 330
const float = mul(["0.01", "0.99"]); // 0.0099
const negative = mul(["-2", "3"]); // -6

Divide numbers

import { div } from "@numio/bigmath";

const int = div(["9999", "33"]); // 303
const float = div(["0.06", "0.2"]); // 0.3
const negative = div(["-2", "-3", "2"]); //0.33333333333333333333

// set number of digit after the decimal. By default it's 20
div(["10", "3"], 4); // 3.3333

Round

import { round } from "@numio/bigmath";

round("-1.12345"); // -1
round("1.5"); // 2
round("1.0"); // 1
round("0.00001"); // 0
round("9.9"); // 10

Round at position

import { round } from "@numio/bigmath";

round("1.12345", { decimals: 1 }); // 1.1
round("1.12345", { decimals: 2 }); // 1.12
round("1.12234", { decimals: 0 }); // 1
round("9.999", { decimals: 2 }); // 10

Round modes

import { round } from "@numio/bigmath";

round("1.11", { decimals: 1, roundMode: "up" }); // 1.2
round("1.19", { decimals: 1, roundMode: "up" }); // 1.2

round("1.11", { decimals: 1, roundMode: "down" }); // 1.1
round("1.19", { decimals: 1, roundMode: "down" }); // 1.1

round("1.15", { decimals: 1, roundMode: "half-up" }); // 1.2
round("1.15", { decimals: 1, roundMode: "half-down" }); // 1.1

round("1.15", { decimals: 1, roundMode: "half-even" }); // 1.2
round("1.25", { decimals: 1, roundMode: "half-even" }); // 1.2
round("1.35", { decimals: 1, roundMode: "half-even" }); // 1.4
round("1.45", { decimals: 1, roundMode: "half-even" }); // 1.4
round("1.55", { decimals: 1, roundMode: "half-even" }); // 1.6

round("1.15", { decimals: 1, roundMode: "half-odd" }); // 1.1
round("1.25", { decimals: 1, roundMode: "half-odd" }); // 1.3
round("1.35", { decimals: 1, roundMode: "half-odd" }); // 1.3
round("1.45", { decimals: 1, roundMode: "half-odd" }); // 1.5
round("1.55", { decimals: 1, roundMode: "half-odd" }); // 1.5

Round with "significant figures" flag

import { round } from "@numio/bigmath";

round("0.000119", { decimals: 2, sigFig: false }); // 0
round("0.000119", { decimals: 2, sigFig: true }); // 0.00012

round("0.0019", { decimals: 1, sigFig: true, roundMode: "down" }); // 0.001
round("0.0011", { decimals: 1, sigFig: true, roundMode: "up" }); // 0.002

round("1.000119", { decimals: 2, sigFig: false }); // 1
round("1.000119", { decimals: 2, sigFig: true }); // 1

Pipe

import { pipe } from "@numio/bigmath";

const addNums = ["1", "2", "3"];
const subNums = ["0.2", "0.3"];
const divNums = ["4"];
const mulNums = ["2", "5", "0.2"];

pipe.add(addNums) // 6
  .div(divNums) // 6 / 4 = 1.5 
  .sub(subNums) // 1.5 - 0.2 - 0.3 = 1
  .mul(mulNums) // 1 * 2 * 5 * 0.2 = 2
  .calc() // convert end result to readable string

Quartile

import { quartile } from "@numio/bigmath";

quartile(["1", "2", "3", "4", "5", "6", "7", "8", "9"]) // { Q1: "2.5", Q2: "5", Q3: "7.5" }
quartile(["0.001", "0.3", "0.4", "1"]) // { Q1: "0.1505", Q2: "0.35", Q3: "0.7" }

Sort

import { sort } from "@numio/bigmath";

// native js sort for strings
["1", "10", "11", "101", "11", "10", "1"].sort() // ["1", "1", "10", "10", "101", "11", "11"]

// sort from "@numio/bigmath"
sort(["1", "10", "11", "101", "11", "10", "1"]) // ["1", "1", "10", "10", "11", "11", "101"]

// ASC sorting
sort(["-0.1", "0.1", "-1"], "asc") // ["-1", "-0.1", "0.1"]

// DESC sorting
sort(["-0.1", "0.1", "-1"], "desc") // ["0.1", "-0.1", "-1"]

Mean

import { mean } from "@numio/bigmath";

mean(["5", "4", "3", "2", "1", "0"]) // "2.5"
mean(["0.5", "0.4", "0.3", "0.2", "0.1", "0"]) // "0.25"

Max

import { max } from "@numio/bigmath";

max(["2", "-1", "0.1"]) // 2;

Min

import { min } from "@numio/bigmath";

min(["2", "-1", "0.1"]) // -1;

IsEqual

import { isEqual } from "@numio/bigmath";

isEqual({left: "0.1", right: "0.1"}) // true;
isEqual({left: "2", right: "0.1"}) // false;

IsLeftGreater

import { isLeftGreater } from "@numio/bigmath";

isLeftGreater({left: "0.1", right: "2"}) // false;
isLeftGreater({left: "2", right: "0.1"}) // true;
isLeftGreater({left: "0.1", right: "0.1"}) // false;
isLeftGreater({left: "0.1", right: "-0.1"}) // true;

MAD - Median Absolute Deviation

import { MAD } from "@numio/bigmath";

MAD(["7", "15", "36", "39", "40", "41"]) // 3;

IQR - Interquartile Range

import { IQR } from "@numio/bigmath";

IQR(["7", "15", "36", "39", "40", "41"]) // 25;

Does not have a limitation on the number of digits. You can use any length you'd like

// NO precision loss using numeric literals with more than 15 significant digits.
const int = sub(
  "999999999999999999999999999999999999999999999999999999999999999",
  "2",
); // "1000000000000000000000000000000000000000000000000000000000000001"

const float = mul(
  "0.00000000000000000000000000000000000000000000000000000000000000000009",
  "0.000000002",
); // 0.00000000000000000000000000000000000000000000000000000000000000000000000000018

Download from NPM - https://www.npmjs.com/package/@numio/bigmath

Download from JSR - https://jsr.io/@numio/bigmath

Home page - https://github.com/shpunter/numio-bigmath/blob/main/README.md

License - https://github.com/shpunter/numio-bigmath/blob/main/LICENSE