# bigval

> Easier calculation and formatting of crypto values with decimals. Useful for smart contract interaction.

Latest version **1.7.0** (published 2023-11-06) · MIT license · 0 weekly downloads

## Install

```sh
npm install bigval
pnpm add bigval
yarn add bigval
bun add bigval
```

## Health

**Score 30/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.7.0 |
| Published | 2023-11-06 |
| First published | 2021-01-04 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 1 |
| Unpacked size | 402.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Ramesh Nair |
| Maintainers | hiddentao |

## Links

- npm: https://www.npmjs.com/package/bigval
- Homepage: https://hiddentao.github.io/bigval/
- npm.io page: https://npm.io/package/bigval

## Dependencies (1)

- [decimal.js](https://npm.io/package/decimal.js.md) ^10.2.1

## Recent versions

- 1.7.0 (latest) — 2023-11-06
- 1.6.0 — 2023-11-06
- 1.5.0 — 2022-03-02
- 1.4.0 — 2021-02-04
- 1.3.1 — 2021-01-14
- 1.3.0 — 2021-01-14
- 1.2.0 — 2021-01-11
- 1.1.2 — 2021-01-09
- 1.1.1 — 2021-01-09
- 1.1.0 — 2021-01-09
- 1.0.2 — 2021-01-08
- 1.0.1 — 2021-01-04
- 1.0.0 — 2021-01-04

## README

[![NPM module](https://badge.fury.io/js/bigval.svg)](https://badge.fury.io/js/bigval)
[![Join the community](https://img.shields.io/badge/Chat%20on-Telegram-brightgreen.svg?color=0088cc)](https://t.me/erdDEV)
[![Follow on Twitter](https://img.shields.io/twitter/url/http/shields.io.svg?style=social&label=Follow&maxAge=2592000)](https://twitter.com/erd_dev)

# bigval

Javascript library for representing arbitrarily large or small crypto values with decimals. 

`bigval` is useful for handling extremely large crypto numbers with precision, e.g. when performing arithmetic with balances.

It is inspired by [ethval](https://github.com/hiddentao/ethval).

Features:

* Built-on on the robust [decimal.js](https://mikemcl.github.io/decimal.js/) library.
* Immutable-by-default to maximize code safety.
* Flexible about input types.
* Easy conversion between number scales (see below).

## Installation

```
npm install --save bigval
```

## Usage

Initializing a value:

```js
const { BigVal } = require('bigval')

const v1 = new BigVal(1000000000000000000)
const v2 = new BigVal('1000000000000000000')
const v3 = new BigVal('0.00000001')
const v4 = new BigVal('0xde0b6b3a7640000')
const v5 = new BigVal('b1000000000000000000')
const v6 = new BigVal(new BigVal(1000000000000000000))
```


Scaling:

```js
const v6 = new BigVal(6, 'coins')
const sameAsV6 = new BigVal('6000000000000000000', 'min')
const sameAsV6Again = new BigVal('6000000000000000000')
```

Scaling is based on no. of decimals:

```js
const v = new BigVal(100, 'min', { decimals: 2 }) // same as new BigVal(1, 'coins', { decimals: 2 })

console.log( v.scale ) // 'min'

const v2 = v.toCoinScale()

console.log( v2.scale ) // 'coins'
console.log( v2.toString() ) // "1"

const v3 = v2.toMinScale()

console.log( v3.scale ) // 'min'
console.log( v3.toString() ) // "100"
```

Simple arithmetic leaves original unchanged:

```js
const v = new BigVal(1000000000000000000)

const v2 = v.add(32) // v2 is a new instance of BigVal

console.log(v2 !== v) // true

console.log(v2.toString()) // "1000000000000000032"

console.log(v.toString()) // "1000000000000000000" - original unchanged
```

Initializing using `from()` static convenience method:

```js
const v6 = BigVal::from('1', 'coins', { decimals: 2 })
const v6_1 = v6.toMinScale()

console.log( v6_1.scale ) // 'min'
console.log( v6_1.toString() ) // "100"
```

Initializing using `fromStr()` static method:

```js
const v7 = BigVal::fromStr('2 coins') // same as BigVal::from(2, 'coins')
const v8 = BigVal::fromStr('0.5 min') // same as BigVal::from(0.5, 'min')
const v9 = BigVal::fromStr('0xff', { decimals: 2 }) // same as BigVal::from(0xff, undefined, { decimals: 2 })
```

Output in different types:

```js
const v = new BigVal(255)

console.log( v.toString() ) // "255"
console.log( v.toString(10) ) // "255"
console.log( v.toString(16) ) // "FF"
console.log( v.toString(2) ) // "1111111"
console.log( v.toNumber() ) // 255
```

Decimals and rounding:

```js
const v = new BigVal(100)

const v2 = v.div(3)

console.log( v2.toString() ) // "33.333333333333333"
console.log( v2.toFixed(1) ) // "33.3"

const v3 = v2.round()

console.log( v3.toString() ) // "33"

const v4 = new BigVal(0.00000001)
console.log(v4.decimalCount) // 8
```


Flexible input types:

```js
const v = new BigVal(255)

// these are all the same
v.add(32)
v.add('32')
v.add(new BigVal(32))
```

Logical operators:

```js
const v = new BigVal(255)

const isGreater = v.gte(254)

console.log( isGreater ) // true
```

## Number scales

At any given time a `BigVal` instance operates at a particular number _scale_. The scale is based on the the no. of `decimals` specified in the configuration (`BigValConfig`). By default the no. of `decimals` is 18.
 
The `min` scale (this is the default) is for numbers which do not have decimal places since they are already denominated in the smallest possible unit. The `coins` scale is for numbers which implicitly have decimal places.
 
For example, if a given `BigVal` has `decimals = 2` then the following two numbers are equivalent in value:
 
 * scale = `min`, value = `100`
 * scale = `coins`, value = `1`

If `decimals = 18` (this is the default) then the following two numbers are equivalent in value:

* scale = `min`, value = `1000000000000000000`
* scale = `coins`, value = `1`
 
The use of scales like this makes it easy to convert between chain-friendly and user-friendly values and perform arithmetic at the desired precision.


## Developer guide

To build both ESM and CommonJS output:

```shell
yarn build
```

To re-build the CommonJS output on chnage:

```shell
yarn dev
```

To test:

```shell
yarn test
```

To build the docs:

```shell
yarn build-docs
```

To publish a new release (this will create a tag, publish to NPM and publish the latest docs):

```shell
yarn release
```

## License

MIT

---
_Source: https://npm.io/package/bigval · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._