BigNumber Notation

Write BigNumber arithmetic as natural math expressions.

Installation

npm install bignumber-notation

Why?

JavaScript numbers lose precision:

0.1 + 0.2                // 0.30000000000000004
9007199254740993 + 1     // 9007199254740994 (wrong!)

BigNumber.js fixes this, but the syntax is verbose. This library lets you write math naturally.

Examples

Basic Arithmetic

import n from 'bignumber-notation'

// Addition
new BigNumber('10').plus('20')         // BigNumber.js
n`10 + 20`                             // bignumber-notation

// Multiplication
new BigNumber('5').times('3')          // BigNumber.js
n`5 * 3`                               // bignumber-notation

// Division
new BigNumber('100').div('4')          // BigNumber.js
n`100 / 4`                             // bignumber-notation

Multiple Operations

// Sum three values
new BigNumber('10').plus('20').plus('30')
n`10 + 20 + 30`

// Price with 8% tax
new BigNumber('100').times('1.08')
n`100 * 1.08`

// Split bill three ways
new BigNumber('90').div('3')
n`90 / 3`

Complex Expressions

// (10 + 20) * 3
new BigNumber('10').plus('20').times('3')
n`(10 + 20) * 3`

// 100 - 15% discount
new BigNumber('100').times(new BigNumber('1').minus('0.15'))
n`100 * (1 - 0.15)`

// Average of three numbers
new BigNumber('10').plus('20').plus('30').div('3')
n`(10 + 20 + 30) / 3`

With Variables

const price = '99.99'
const quantity = '3'
const taxRate = '0.08'

// Total with tax
new BigNumber(price).times(quantity).times(new BigNumber('1').plus(taxRate))
n`${price} * ${quantity} * (1 + ${taxRate})`

// Percentage calculation
const total = '250'
const part = '50'

new BigNumber(part).div(total).times('100')
n`${part} / ${total} * 100`

Large Numbers & Precision

// Large integers (wei to ETH)
const wei = '1000000000000000000'

new BigNumber(wei).div(new BigNumber('10').pow('18'))
n`${wei} / 1e18`

// Precise decimals
new BigNumber('0.1').plus('0.2')       // "0.3" (correct!)
n`0.1 + 0.2`                           // "0.3" (correct!)

Chaining BigNumber Methods

The result is a BigNumber instance:

// Round to 2 decimal places
n`100 / 3`.decimalPlaces(2)            // "33.33"

// Convert to fixed string
n`10 / 3`.toFixed(4)                   // "3.3333"

// Check properties
n`100 / 4`.isInteger()                 // true

Features

• Standard operators: +, -, *, /
• Parentheses for grouping
• Template literal interpolation
• Scientific notation (1e18, 1e-6)
• Full BigNumber.js precision
• TypeScript support

API

import n from 'bignumber-notation'

n`expression` // Returns BigNumber

Requirements

• Node.js >= 18.0.0
• ES Modules

License

MIT