Skip to content

bpierre/dnum

Repository files navigation

dnum: small library for big decimal numbers

npm version bundle size License

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