hailstonelabs/big-number-utils

hailstonelabs/big-number-utils is a library for BigNumber formatting and calculation, developed by Hailstone Labs.

Installation

To install and set up the library, run:

$ npm install @hailstonelabs/big-number-utils

Or if you prefer using Yarn:

$ yarn add @hailstonelabs/big-number-utils

Use

Big Number

Many operations in Ethereum operate on numbers which are outside the range of safe values to use in JavaScript.

A BigNumber is an object which safely allows mathematical operations on numbers of any magnitude. Most operations which need to return a value will return a BigNumber and parameters which accept values will generally accept them.

This library is compatible with the BigNumber exported from ether.js Source.

Safe Arithmetic

Inspiring by DS Maths Source, @hailstonelabs/big-number-utils provides arithmetic functions for the common numerical primitive types of typescript. This package provides arithmetic functions for new two higher level numerical concepts called wad (18 decimals) and ray (27 decimals). These are used to represent fixed-point decimal numbers.

WAD and RAY

A wad is a decimal number with 18 digits of precision and a ray is a decimal number with 27 digits of precision. These functions are necessary to account for the difference between how integer arithmetic behaves normally, and how decimal arithmetic should actually work.

const WAD = BigNumber.from(10).pow(18)
const RAY = BigNumber.from(10).pow(27)

DS Math API Reference

[.strToWad]

It changes string to WAD if not undefined or ParsableString, else return constants.Zero

Params

wadString {string | undefined}
returns {BigNumber}

[.getPercentageFromTwoWAD]

It returns the percentage of x in y, in string and return upperBound if the value exceeds upperBound.

Params

x {BigNumber}: x in WAD
y {BigNumber}: t in WAD
upperBound {BigNumber}: the upper bound percentage, in WAD
returns {string}: the percentage of x in y, in string

getPercentageFromTwoWAD(strToWad('20000'), strToWad('40000'))
//=> 50

getPercentageFromTwoWAD(strToWad('50000'), strToWad('40000'), strToWad('100'))
//=> 100

[.getMinValue]

Params

x {string}: x number in string
y {string}: y number in string
returns {BigNumber}: the minimum value in WAD

[.sum]

It returns the summation of two values.

Params

x {string | BigNumber}: BigNumber must be WAD
y {string | BigNumber}: BigNumber must be WAD
returns {string}: sum

Example

sum(strToWad('20000'), strToWad('30000'))
//=> 50000

[.differenceComparesValue]

It compare x - y with the value.

Params

x {BigNumber}
y {BigNumber}
value {BigNumber}
operator {'lt' | 'eq' | 'gt'} less than / equal to / greater than
returns {boolean}

Example

differenceComparesValue(BigNumber.from(20000), BigNumber.from(20000), 'eq')
//=> true

differenceComparesValue(BigNumber.from(40000), BigNumber.from(20000), 'lt')
//=> false

[.lessThanZeroPointZeroOne]

It checks whether x is less than 0.01.

Params

x {BigNumber}
decimal {number}
returns {boolean}

Example

lessThanZeroPointZeroOne(BigNumber.from(0.00003), 5))
//=> true

[.changeDecimal]

It changes tokenA amount (with tokenA decimal) to target value (with tokenB decimal).

Params

fromDecimal {number}
toDecimal {number}
fromAmount {BigNumber}
returns {BigNumber}

[.nativeToWAD]

Params

x {BigNumber} x in BigNumber
decimal {number}
returns {BigNumber}: convertion to WAD

[.wadToNative]

Params

x {BigNumber} x in WAD
decimal {number}
returns {BigNumber}: convertion to Origin

[.bnIntToWAD]

Params

x {BigNumber} in BigNumber Int
returns {BigNumber}: convertion to WAD

[.bnIntToRAY]

Params

x {BigNumber} x in BigNumber Int
returns {BigNumber}: convertion to RAY

[.wadToRay]

Params

x {BigNumber} x in WAD
returns {BigNumber}: convertion to RAY

[.rayToWad]

Params

x {BigNumber} x in RAY
returns {BigNumber}: convertion to WAD

[.wmul]

Params

x {BigNumber} x in WAD
y {BigNumber} y in WAD
returns {BigNumber}: the product of x and y, in WAD

[.wdiv]

Params

x {BigNumber} x in WAD
y {BigNumber} y in WAD
returns {BigNumber}: the quotient of x divided by y, in WAD

[.safeWdiv]

Params

x {BigNumber} x in WAD
y {BigNumber} y in WAD
returns {BigNumber}: the quotient of x divided by y, in WAD

[.safeDiv]

Params

x {BigNumber} x in BigNumber
y {BigNumber} y in BigNumber
returns {BigNumber}: the quotient of x divided by y, in BigNumber

[.rmul]

Params

x {BigNumber} x in RAY
y {BigNumber} y in RAY
returns {BigNumber}: the product of x and y, in RAY

[.rpow]

Params

x {BigNumber} x in RAY
n {BigNumber}
returns {BigNumber}: the exponential of x to the power n, in RAY

[.sqrt]

Params

x {BigNumber} x in BigNumber Int
returns {BigNumber}: the square root of x, in BigNumber Int

[.wsqrt]

Params

x {BigNumber} x in WAD
returns {BigNumber}: the square root of x, in WAD

Parsable String API Reference

[.isParsableString]

Check whether bnString can be parsed as a BigNumber.

Params

bnString {string}
dp {number} the decimals
isNonNegativeOnly {boolean} whether the string is only a non negative value
returns {boolean}: whether the string is parsable

isParsableString(strToWad('100000000'), 18, false)
//=> true

isParsableString(strToWad('100000000000000000000'), 18, false)
//=> false

[.getParsableString]

Params

bnString {string}
dp {number} the decimals
isNonNegativeOnly {boolean}
returns {BigNumber}: If bnString is parsable, return bnStrin, else return 0

Number Display Format API Reference

[.getStringInput]

If a value is in WAD, it will format the value.

Params

value {string | BigNumber}: a value in string or in WAD
returns {string}: a formatted string value

Example

getStringInput(strToWad('20000'))
//=> 20000

[.getDpFormat]

It trim extra decimals in order to avoid fractional component exceeds decimals.

Params

value {string | BigNumber}: a value in string or in WAD
decimalPlace {number}: decimal place, the default is 2
rounding {'down'|'off'}: decimal place, the default is down
returns {string}: a decimal trimmed value

Example

getDpFormat(strToWad('1.1234567'), 6)
//=> 1.123456

getDpFormat(strToWad('1.1234567'), 6, 'off')
//=> 1.123457

[.getMillifiedFormat]

It converts long numbers to human-readable string.

Params

value {string | BigNumber}: a value in string or in WAD
returns {string}: a millified value with 1 d.p.

Example

getMillifiedFormat(strToWad('1424000'))
//=> 1.4M

getMillifiedFormat(strToWad('2500'))
//=> 2.5K

[.getCommifiedFormat]

It always checks whether an actualValue is less than 0.01.

Params

actualValue {string | BigNumber}: a value in string or in WAD
decimalPlace {number}: decimal place, the default is 2
returns {string}: readable string, rounded to x decimal places or if the actualValue is less than 0.01, it returns "< 0.01"

Example

getCommifiedFormat(strToWad('0.00007'))
//=> < 0.01

getCommifiedFormat(strToWad('1255354.664'))
//=> 1,255,354.66

[.getDynamicFormat]

If actualValue is greater than or equal to 100000 return millified format value, else return commified format value.

Params

actualValue {string | BigNumber}: a value in string or in WAD
decimalPlace {number}: decimal place, the default is 2
returns {string}: readable string with millified format or commified format

Example

getDynamicFormat(strToWad('1024000'))
//=> 1.02M

getDynamicFormat(strToWad('90000'))
//=> 90,000