JSPM

dnum provides a small set of utilities to manipulate large numbers represented as a pair composed of a value (stored as a BigInt) and corresponding decimals. This structure makes it possible to handle large decimal numbers in an easy manner, without any loss of precision, and using an open structure that preserves flexibility.

type Dnum = [value: bigint, decimals: number];

Install

npm install --save dnum
pnpm add dnum
yarn add dnum

TL;DR

dnum might be a good option for your project if:

• You are dealing with numbers represented as integers associated with a number of decimals (e.g. currencies).
• You need common math operations, safely and by having their representation abstracted.
• You want to format these numbers without having to convert them into Number first (and thus losing precision).
• You want to avoid adding a library to your project that would be too big, or lack flexibility.

Example

dnum can be useful to manipulate different currencies together, so let’s imagine a situation where you have the price of a given token token TKN expressed in ETH, which you received it as a string to avoid any precision issue:

let tknPriceInEth = "17.30624293209842";

And you have the price of ETH in USD, as a number this time:

let ethPriceInUsd = 1002.37;

Finally, you have a certain quantity of TKN to be displayed, as a BigInt:

let tknQuantity = 1401385000000000000000n; // 1401.385 with 18 decimals precision

You want to display the USD value of tknQuantity, which would normally require to:

• Parse the numbers correctly (without using parseInt() / parseFloat() to avoid precision loss).
• Convert everything into BigInt values with an identical decimals precision.
• Multiply the numbers and get the result.
• Convert it into a string to format it − without using Number since you’d lose precision.

dnum can do all of this for you:

// No need to convert anything, you can just multiply different formats of decimal numbers:
let tknPriceInUsd = dnum.multiply(tknPriceInEth, ethPriceInUsd);

// A Dnum is just a two entries array (or tuple): [value: bigint, decimals: number]
let tknQuantityInUsd = dnum.multiply([tknQuantity, 18], tknPriceInUsd);

dnum.format(tknQuantityInUsd, 2); // $24,310,188.17

You can play with this example on CodeSandbox.

API

Types

type Dnum = [value: bigint, decimals: number];
type Numberish = string | number | bigint | Dnum;

format(value, options)

Formats the number for display purposes.

Example

let amount = [123456789000000000000000n, 18];

// If no digits are provided, the digits correspond to the decimals
dnum.format(amount); // 123,456.789

// options.digits
dnum.format(amount, { digits: 2 }); // 123,456.79
dnum.format(amount, 2); // (alias)

// options.compact
dnum.format(amount, { compact: true }); // 123K

// options.trailingZeros
dnum.format(amount, { digits: 6, trailingZeros: true }); // 123,456.789000

from(valueToParse, decimals)

Parse a value and convert it into a Dnum. It can be a string, a number, a bigint, or even a Dnum (which can be useful to change its decimals).

Example

// Parses a number expressed as a string or number
let amount = dnum.from("17.30624", 18);

// amount equals [17306240000000000000n, 18]

add(value1, value2, decimals)

Adds two values together, regardless of their decimals. decimals correspond to the decimals desired in the result.

subtract(value1, value2, decimals)

Subtract a value from another one, regardless of their decimals. decimals correspond to the decimals desired in the result.

Alias: sub()

multiply(value1, value2, decimals)

Multiply two values together, regardless of their decimals. decimals correspond to the decimals desired in the result.

Alias: mul()

Example

let ethPriceUsd = [100000n, 2]; // 1000 USD
let tokenPriceEth = [570000000000000000, 18]; // 0.57 ETH

let tokenPriceUsd = dnum.multiply(tokenPriceEth, ethPriceUsd, 2); // 570 USD

// tokenPriceUsd equals [57000, 2]

divide(value1, value2, decimals)

Divide a value by another one, regardless of their decimals. decimals correspond to the decimals desired in the result.

Alias: div()

Example

let ethPriceUsd = [100000n, 2]; // 1000 USD
let tokenPriceUsd = [57000, 2]; // 570 USD

let tokenPriceEth = dnum.divide(tokenPriceUsd, ethPriceUsd, 18); // 0.57 ETH

// tokenPriceEth equals [570000000000000000, 18]

abs(value, decimals)

Equivalent to the Math.abs() function: it returns the absolute value of the Dnum number.

Example

let value = [-100000n, 2];

dnum.abs(value); // [100000n, 2]

round(value, decimals)

Equivalent to the Math.round() function: it returns the value of a number rounded to the nearest integer.

Example

let value = [-123456n, 2]; // 1234.56

dnum.round(value); // [123500n, 2] or 1235.00

floor(value, decimals)

Equivalent to the Math.floor() function: it rounds down and returns the largest integer less than or equal to the number.

ceil(value, decimals)

Equivalent to the Math.ceil() function: it rounds rounds up and returns the smaller integer greater than or equal to the number.

greaterThan(value1, value2, decimals)

Equivalent to the > operator: it returns true if the first value is greater than the second value and false otherwise, regardless of their respective decimals.

Alias: gt()

Example

let value1 = [10000100n, 4];
let value2 = [100000n, 2];

dnum.greaterThan(value1, value2); // true
dnum.greaterThan(value1, value1); // false
dnum.greaterThan(value2, value1); // false

lessThan(value1, value2, decimals)

Equivalent to the < operator: it returns true if the first value is less than the second value and false otherwise, regardless of their respective decimals.

Alias: lt()

Example

let value1 = [100000n, 2];
let value2 = [10000100n, 4];

dnum.lessThan(value1, value2); // true
dnum.lessThan(value1, value1); // false
dnum.lessThan(value2, value1); // false

equal(value1, value2, decimals)

Equivalent to the == operator: it returns true if the first value is equal to the second value and false otherwise, regardless of their respective decimals.

Alias: eq()

Example

let value1 = [100000n, 2];
let value2 = [10000000n, 4];

dnum.lessThan(value1, value2); // true

toNumber(value, options)

Converts the Dnum data structure into a Number. This will result in a loss of precision depending on how large the number is.

let value = [123456789000000000000000n, 18];

toNumber(value); // 123456.789
toNumber(value, 1); // 123456.8

toJSON(value)

Converts the Dnum data structure into a JSON-compatible string. This function is provided because JSON.stringify() doesn’t work with BigInt data types.

let json = toJSON([123456789000000000000n, 18]);

// json == "[\"123456789000000000000\", 18]";

fromJSON(value)

Converts the string resulting from toJSON() back into a Dnum.

let dnum = fromJSON("[\"123456789000000000000\", 18]");

// dnum == [123456789000000000000n, 18]

setDecimals(value, decimals, options)

Return a new Dnum with a different amount of decimals. The value will reflect this change so that the represented number stays the same.

Note: from(value, decimals) can also be used instead.

Tree shaking

To make use of tree shaking, named exports are also provided:

import { format, from } from "dnum";

FAQ

Should dnum be used instead of BigInt or libraries such as BN.js or decimal.js?

dnum is not a full replacement for libraries such as decimal.js or BigInt. Instead, dnum focuses on a small (~1kb) set of utilities focused around the simple Dnum data structure, allowing to manipulate numbers represented in various decimal precisions in a safe manner.

Why is it called dnum?

dnum stands for Decimal Numbers.

Who made the logo and banner? 😍

The gorgeous visual identity of dnum has been created by Paty Davila.

Acknowledgements

• ethers, in particular its parseFixed() function.
• token-amount which was an attempt at solving a similar problem.