dnum

dnum (Decimal Numbers) is a library that allows to operate on large numbers represented as a pair composed of a BigInt for the value, and a Number for the decimals.

It is not a replacement for libraries such as decimal.js or the native BigInt operators. Instead, dnum focuses on a small set of utilities that allow to manipulate numbers represented in this way.

Usage

The data structure is a simple array with two entries: a BigInt representing the value, and a Number representing the decimals. We’ll call it Dnum, and this is how it is represented in TypeScript:

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

import dnum from "dnum";

// Create a Big Integer With Decimals from strings
let amount1 = dnum.from("17.30624", 18); // [17306240000000000000n, 18]

// Or numbers
let amount2 = dnum.from(3.4, 2); // [340, 2]

// You don’t need dnum.from() if you already know the value and decimals
let amount3 = [140138500000n, 8]; // represents 1401.385 with 8 decimals precision

// Format with 2 digits
dnum.format(amount1, 2); // "17.31"

// Format with 4 digits while keeping the trailing zeros
dnum.format(amount2, 4, { trailingZeros: true }); // "3.4000"

// Compact formatting
dnum.format(amount3, 2, { compact: true }); // "1.4K"

Install

npm:

npm install --save dnum

pnpm:

pnpm add dnum

yarn:

yarn add dnum

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.

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]

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)

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";

Acknowledgements

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