dnum provides a small set of utilities designed for the manipulation of large numbers. It provides useful features for everyday apps, such as formatting and math functions. Numbers are represented as a pair composed of a value (BigInt) and a decimal precision. This structure allows to maintain the number precision while offering a great flexibility.

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

Usage

import * as dn from "dnum";

let a = dn.from(2, 18); // the number 2 followed by 18 decimals
let a = [2000000000000000000n, 18]; // equivalent to the previous line

let b = dn.from("870983127.93887"); // dn.from() can parse strings, numbers, bigint and more

let c = dn.multiply(a, b); // returns [1741966255877740000000000000n, 18]

console.log(
  dn.format(a), // "2"
  dn.format(b, 2), // "870,983,127.94"
  dn.format(c, 2), // "1,741,966,255.88"
  dn.format(b, { compact: true }), // "1.7B"
);

Install

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

TL;DR

dnum might be a good option for your project if:

Your numbers are represented as value + decimals pairs.
You need to format large numbers for UI purposes.
You want to keep your big numbers library small.
You want a simple, straightforward data structure.

Example

dnum can be used to perform math operations on currency values. Let’s consider a scenario where you have the price of a specific token known as TKN, expressed in ETH, received as a string to prevent potential precision issues:

let tknPriceInEth = "17.30624293209842";

And you received the price of 1 ETH in USD from a different source, as a JavaScript number:

let ethPriceInUsd = 1002.37;

Finally, your app has a specific quantity of TKN to be displayed, represented as a BigInt with an implied 18 decimals precision:

let tknQuantity = 1401385000000000000000n; // 1401.385 (18 decimals precision)

You want to display the USD value of tknQuantity. This 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.
Convert the resulting BigInt into a string and format it for display purposes, without Intl.NumberFormat since it would cause precision loss.

dnum can do all of this for you:

let tknPriceInEth = "17.30624293209842";
let ethPriceInUsd = 1002.37;
let tknQuantity = 1401385000000000000000n; // 1401.385 (18 decimals precision)

// dnum function parameters accept various ways to represent decimal numbers.
let tknPriceInUsd = dnum.multiply(tknPriceInEth, ethPriceInUsd);

let tknQuantityInUsd = dnum.multiply(
  // Here we only attach the 18 decimals precision with the bigint value,
  // which corresponds to the Dnum type: [value: bigint, decimals: number].
  // You can pass this structure anywhere dnum expects a value, and this is
  // also what most dnum functions return.
  [tknQuantity, 18],
  tknPriceInUsd,
);

// We can now format the obtained result, rounding its decimals to 2 digits:
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.

Name	Description	Type
`value`	The value to format.	`Dnum`
`options.digits`	Number of digits to display. Setting `options` to a number acts as an alias for this option (see example below). Defaults to the number of decimals in the `Dnum` passed to `value`.	`number`
`options.compact`	Compact formatting (e.g. “1,000” becomes “1K”).	`boolean`
`options.trailingZeros`	Add trailing zeros if any, following the number of digits.	`boolean`
`options.locale`	The locale used to format the number.	`string`
`options.decimalsRounding`	Method used to round to `digits` decimals (defaults to `"ROUND_HALF"`).	`"ROUND_HALF" \| "ROUND_UP" \| "ROUND_DOWN"`
`options.signDisplay`	When to display the sign for the number. Follows the same rules as `Intl.NumberFormat`. Defaults to `"auto"`.	`"auto" \| "always" \| "exceptZero" \| "negative" \| "never"`
returns	Formatted string.	`string`

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); // 123,456.79 (alias for { digits: 2 })

// 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. The passed value can be a string, a number, a bigint, or even a Dnum − which can be useful to change its decimals.

Name	Description	Type
`valueToParse`	Value to convert into a `Dnum`	`Numberish`
`decimals` (optional)	Number of decimals (defaults to `true` for auto)	`number \| true`
returns	Converted value	`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.

Name	Description	Type
`value1`	First value to add	`Numberish`
`value2`	Second value to add	`Numberish`
`decimals` (optional)	Result decimals (defaults to `value1` decimals)	`number`
returns	Result	`Dnum`

`subtract(value1, value2, decimals)`

Subtracts the second value from the first one, regardless of their decimals. decimals correspond to the decimals desired in the result.

Name	Description	Type
`value1`	Value from which `value2` is subtracted	`Numberish`
`value2`	Value to subtract from `value1`	`Numberish`
`decimals` (optional)	Result decimals (defaults to `value1` decimals)	`number`
returns	Result	`Dnum`

Alias: sub()

`multiply(value1, value2, optionsOrDecimals)`

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

Name	Description	Type
`value1`	First value to multiply	`Numberish`
`value2`	Second value to multiply	`Numberish`
`options.decimals` (optional)	Results decimals (defaults to `value1` decimals). Setting `options` to a `number` acts as an alias for this option.	`Decimals`
`options.rounding` (optional)	How to round round results (defaults to `"ROUND_HALF"`)	`Rounding`
returns	Result	`Dnum`

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, optionsOrDecimals)`

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

Name	Description	Type
`value1`	Dividend	`Numberish`
`value2`	Divisor	`Numberish`
`options.decimals` (optional)	Results decimals (defaults to `value1` decimals). Setting `options` to a `number` acts as an alias for this option.	`Decimals`
`options.rounding` (optional)	How to round round results (defaults to `"ROUND_HALF"`)	`Rounding`
returns	Result	`Dnum`

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]

`remainder(value1, value2, decimals)`

Equivalent to the % operator: calculate the remainder left over when one operand is divided by a second operand.

Name	Description	Type
`value1`	Dividend	`Numberish`
`value2`	Divisor	`Numberish`
`decimals` (optional)	Result decimals (defaults to `value1` decimals)	`number`
returns	Result	`Dnum`

Alias: rem()

`abs(value, decimals)`

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

Name	Description	Type
`value`	Value to remove the sign from	`Numberish`
`decimals` (optional)	Result decimals (defaults to `value` decimals)	`number`
returns	Result	`Dnum`

Example

let value = [-100000n, 2];

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

`round(value, optionsOrDecimals)`

Equivalent to the Math.round() function, with added option to forcibly round up or down: it returns the value of a number rounded to the nearest integer.

Name	Description	Type
`value`	Value to round to the nearest integer	`Numberish`
`options.decimals` (optional)	Results decimals (defaults to `value` decimals). Setting `options` to a `number` acts as an alias for this option.	`Decimals`
`options.rounding` (optional)	How to round round results (defaults to `"ROUND_HALF"`)	`Rounding`
returns	Result	`Dnum`

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.

Name	Description	Type
`value`	Value to round down	`Numberish`
`decimals` (optional)	Result decimals (defaults to `value` decimals)	`number`
returns	Result	`Dnum`

`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.

Name	Description	Type
`value`	Value to round up	`Numberish`
`decimals` (optional)	Result decimals (defaults to `value` decimals)	`number`
returns	Result	`Dnum`

`greaterThan(value1, value2)`

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.

Name	Description	Type
`value1`	First value	`Numberish`
`value2`	Second value	`Numberish`
returns	Comparison result	`boolean`

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

`greaterThanOrEqual(value1, value2)`

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

Name	Description	Type
`value1`	First value	`Numberish`
`value2`	Second value	`Numberish`
returns	Comparison result	`boolean`

Alias: gte()

`lessThan(value1, value2)`

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.

Name	Description	Type
`value1`	First value	`Numberish`
`value2`	Second value	`Numberish`
returns	Comparison result	`boolean`

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

`lessThanOrEqual(value1, value2)`

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

Name	Description	Type
`value1`	First value	`Numberish`
`value2`	Second value	`Numberish`
returns	Comparison result	`boolean`

Alias: lte()

`equal(value1, value2)`

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.

Name	Description	Type
`value1`	First value	`Numberish`
`value2`	Second value	`Numberish`
returns	Comparison result	`boolean`

Alias: eq()

Example

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

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

`compare(value1, value2)`

Returns 1 if value1 > value2, -1 if value1 < value2, 0 if value1 == value2. It makes it easy to combine Dnum values with sorting functions such as Array#sort().

Name	Description	Type
`value1`	First value	`Numberish`
`value2`	Second value	`Numberish`
returns	Comparison result	`1 \| -1 \| 0`

Alias: cmp()

Example

let sorted = [
  1,
  8n,
  [700n, 2],
  3.1,
  2n,
  5,
].sort(compare);

console.log(sorted); // [1, 2n, 3.1, 5, [700n, 2], 8n];

`toNumber(value, optionsOrDigits)`

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

Name	Description	Type
`value`	The number to convert into a `number`	`Dnum`
`options.digits`	Number of digits to keep after the decimal point. Setting `options` to a number acts as an alias for this option (see example below). Defaults to the number of decimals in the `Dnum` passed to `value`.	`number`
`options.decimalsRounding`	Method used to round to `digits` decimals (defaults to `"ROUND_HALF"`).	`"ROUND_HALF" \| "ROUND_UP" \| "ROUND_DOWN"`
returns	Result	`number`

let value = [123456789000000000000000n, 18];

toNumber(value); // 123456.789
toNumber(value, { digits: 1 }); // 123456.8
toNumber(value, 1); // 123456.8 (alias for { digits: 1 })

`toString(value, optionsOrDigits)`

Converts the Dnum data structure into a string, without any formatting. This might result in a loss of precision depending on how large the number is.

Name	Description	Type
`value`	The number to convert into a `string`	`Dnum`
`options.digits`	Number of digits to keep after the decimal point. Setting `options` to a number acts as an alias for this option (see example below). Defaults to the number of decimals in the `Dnum` passed to `value`.	`string`
`options.decimalsRounding`	Method used to round to `digits` decimals (defaults to `"ROUND_HALF"`).	`"ROUND_HALF" \| "ROUND_UP" \| "ROUND_DOWN"`
returns	String conversion of the value	`string`

let value = [123456789000000000000000n, 18];

toString(value); // "123456.789"
toString(value, { digits: 1 }); // "123456.8"
toString(value, 1); // "123456.8" (alias for { digits: 1 })

Note that if you want to format the number for display purposes, you should probably use format() instead. If you need to convert the number into a JSON-compatible string without any precision loss, use toJSON() instead.

`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.

Name	Description	Type
`value`	The number to convert into a JSON	`Dnum`
returns	JSON conversion of the value	`string`

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

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

`fromJSON(value)`

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

Name	Description	Type
`value`	The string value to convert back into a `Dnum`	`string`
returns	`Dnum` value parsed from the JSON	`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.

Name	Description	Type
`value`	The number from which decimals will be changed	`Dnum`
`decimals`	New number of decimals	`number`
`options.round`	In case of reduction, whether to round the remaining decimals (defaults to `"ROUND_HALF"`).	`Rounding`
returns	Result	`Dnum`

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.

Files

README.md

Latest commit

History

README.md

File metadata and controls

Usage

Install

TL;DR

Example

API

Types

format(value, options)

Example

from(valueToParse, decimals)

Example

add(value1, value2, decimals)

subtract(value1, value2, decimals)

multiply(value1, value2, optionsOrDecimals)

Example

divide(value1, value2, optionsOrDecimals)

Example

remainder(value1, value2, decimals)

abs(value, decimals)

Example

round(value, optionsOrDecimals)

Example

floor(value, decimals)

ceil(value, decimals)

greaterThan(value1, value2)

Example

greaterThanOrEqual(value1, value2)

lessThan(value1, value2)

Example

lessThanOrEqual(value1, value2)

equal(value1, value2)

Example

compare(value1, value2)

Example

toNumber(value, optionsOrDigits)

toString(value, optionsOrDigits)

toJSON(value)

fromJSON(value)

setDecimals(value, decimals, options)

Tree shaking

FAQ

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

Why is it called dnum?

Who made the logo and banner? 😍

Acknowledgements

`format(value, options)`

`from(valueToParse, decimals)`

`add(value1, value2, decimals)`

`subtract(value1, value2, decimals)`

`multiply(value1, value2, optionsOrDecimals)`

`divide(value1, value2, optionsOrDecimals)`

`remainder(value1, value2, decimals)`

`abs(value, decimals)`

`round(value, optionsOrDecimals)`

`floor(value, decimals)`

`ceil(value, decimals)`

`greaterThan(value1, value2)`

`greaterThanOrEqual(value1, value2)`

`lessThan(value1, value2)`

`lessThanOrEqual(value1, value2)`

`equal(value1, value2)`

`compare(value1, value2)`

`toNumber(value, optionsOrDigits)`

`toString(value, optionsOrDigits)`

`toJSON(value)`

`fromJSON(value)`

`setDecimals(value, decimals, options)`