@hailstonelabs/big-number-utils v1.0.8

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