{"id":13792005,"url":"https://github.com/bpierre/dnum","last_synced_at":"2025-06-14T18:11:15.993Z","repository":{"id":56848554,"uuid":"494276780","full_name":"bpierre/dnum","owner":"bpierre","description":"🧮 Small library for big decimal numbers.","archived":false,"fork":false,"pushed_at":"2025-05-21T20:21:56.000Z","size":277,"stargazers_count":259,"open_issues_count":4,"forks_count":7,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-06-13T10:56:10.934Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bpierre.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-05-20T01:03:31.000Z","updated_at":"2025-05-21T20:21:57.000Z","dependencies_parsed_at":"2022-09-09T04:22:19.427Z","dependency_job_id":"68cd85e2-01d0-436a-957c-8acbaffb3ea0","html_url":"https://github.com/bpierre/dnum","commit_stats":null,"previous_names":[],"tags_count":42,"template":false,"template_full_name":null,"purl":"pkg:github/bpierre/dnum","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bpierre%2Fdnum","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bpierre%2Fdnum/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bpierre%2Fdnum/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bpierre%2Fdnum/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bpierre","download_url":"https://codeload.github.com/bpierre/dnum/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bpierre%2Fdnum/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259860438,"owners_count":22922990,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-03T22:01:06.881Z","updated_at":"2025-06-14T18:11:15.969Z","avatar_url":"https://github.com/bpierre.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"\u003cimg alt=\"dnum: small library for big decimal numbers\" src=\"https://user-images.githubusercontent.com/36158/202865124-a4020c0b-5ad7-4e66-aaf4-a5be415a84f3.png\"\u003e\n\n\u003cp align=center\u003e\u003ca href=\"https://www.npmjs.com/package/dnum\"\u003e\u003cimg src=\"https://badgen.net/npm/v/dnum\" alt=\"npm version\"\u003e\u003c/a\u003e \u003ca href=\"https://bundlejs.com/?q=dnum\"\u003e\u003cimg src=\"https://deno.bundlejs.com/badge?q=dnum\" alt=\"bundle size\"\u003e\u003c/a\u003e \u003ca href=\"https://github.com/bpierre/dnum/blob/main/LICENSE\"\u003e\u003cimg src=\"https://badgen.net/github/license/bpierre/dnum\" alt=\"License\"\u003e\u003c/a\u003e\u003c/p\u003e\n\ndnum provides a [small](https://bundlejs.com/?bundle\u0026q=dnum) 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`](https://developer.mozilla.org/en-US/docs/Glossary/BigInt)) and a decimal precision. This structure allows to maintain the number precision while offering a great flexibility.\n\n```ts\ntype Dnum = [value: bigint, decimals: number];\n```\n\n## Usage\n\n```ts\nimport * as dn from \"dnum\";\n\nlet a = dn.from(2, 18); // the number 2 followed by 18 decimals\nlet a = [2000000000000000000n, 18]; // equivalent to the previous line\n\nlet b = dn.from(\"870983127.93887\"); // dn.from() can parse strings, numbers, bigint and more\n\nlet c = dn.multiply(a, b); // returns [1741966255877740000000000000n, 18]\n\nconsole.log(\n  dn.format(a), // \"2\"\n  dn.format(b, 2), // \"870,983,127.94\"\n  dn.format(c, 2), // \"1,741,966,255.88\"\n  dn.format(b, { compact: true }), // \"1.7B\"\n);\n```\n\n## Install\n\n```sh\nnpm install --save dnum\npnpm add dnum\nyarn add dnum\n```\n\n## TL;DR\n\ndnum might be a good option for your project if:\n\n- Your numbers are represented as value + decimals pairs.\n- You need to format large numbers for UI purposes.\n- You want to keep your big numbers library small.\n- You want a simple, straightforward data structure.\n\n## Example\n\ndnum can be used to perform math operations on currency values. Let’s consider a scenario where you have the price of a specific [token](https://ethereum.org/en/developers/docs/standards/tokens/erc-20/) known as TKN, expressed in [ETH](https://ethereum.org/en/developers/docs/intro-to-ether/), received as a string to prevent potential precision issues:\n\n```ts\nlet tknPriceInEth = \"17.30624293209842\";\n```\n\nAnd you received the price of 1 ETH in USD from a different source, as a JavaScript number:\n\n```ts\nlet ethPriceInUsd = 1002.37;\n```\n\nFinally, your app has a specific quantity of TKN to be displayed, represented as a BigInt with an implied 18 decimals precision:\n\n```ts\nlet tknQuantity = 1401385000000000000000n; // 1401.385 (18 decimals precision)\n```\n\nYou want to display the USD value of `tknQuantity`. This would normally require to:\n\n- Parse the numbers correctly (without using `parseInt()` / `parseFloat()` to avoid precision loss).\n- Convert everything into BigInt values with an identical decimals precision.\n- Multiply the numbers.\n- Convert the resulting BigInt into a string and format it for display purposes, without `Intl.NumberFormat` since it would cause precision loss.\n\ndnum can do all of this for you:\n\n```ts\nlet tknPriceInEth = \"17.30624293209842\";\nlet ethPriceInUsd = 1002.37;\nlet tknQuantity = 1401385000000000000000n; // 1401.385 (18 decimals precision)\n\n// dnum function parameters accept various ways to represent decimal numbers.\nlet tknPriceInUsd = dnum.multiply(tknPriceInEth, ethPriceInUsd);\n\nlet tknQuantityInUsd = dnum.multiply(\n  // Here we only attach the 18 decimals precision with the bigint value,\n  // which corresponds to the Dnum type: [value: bigint, decimals: number].\n  // You can pass this structure anywhere dnum expects a value, and this is\n  // also what most dnum functions return.\n  [tknQuantity, 18],\n  tknPriceInUsd,\n);\n\n// We can now format the obtained result, rounding its decimals to 2 digits:\ndnum.format(tknQuantityInUsd, 2); // $24,310,188.17\n```\n\nYou can play with this example [on CodeSandbox](https://codesandbox.io/s/dnum-intro-qljzi6?file=/src/index.ts).\n\n## API\n\n### Types\n\n```ts\ntype Dnum = [value: bigint, decimals: number];\ntype Numberish = string | number | bigint | Dnum;\n```\n\n### `format(value, options)`\n\nFormats the number for display purposes.\n\n| Name                       | Description                                                                                                                                                                                                                                  | Type                                                          |\n| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |\n| `value`                    | The value to format.                                                                                                                                                                                                                         | `Dnum`                                                        |\n| `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`                                                      |\n| `options.compact`          | Compact formatting (e.g. “1,000” becomes “1K”).                                                                                                                                                                                              | `boolean`                                                     |\n| `options.trailingZeros`    | Add trailing zeros if any, following the number of digits.                                                                                                                                                                                   | `boolean`                                                     |\n| `options.locale`           | The locale used to format the number.                                                                                                                                                                                                        | `string`                                                      |\n| `options.decimalsRounding` | Method used to round to `digits` decimals (defaults to `\"ROUND_HALF\"`).                                                                                                                                                                      | `\"ROUND_HALF\" \\| \"ROUND_UP\" \\| \"ROUND_DOWN\"`                  |\n| `options.signDisplay`      | When to display the sign for the number. [Follows the same rules as `Intl.NumberFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#signdisplay). Defaults to `\"auto\"`. | `\"auto\" \\| \"always\" \\| \"exceptZero\" \\| \"negative\" \\| \"never\"` |\n| returns                    | Formatted string.                                                                                                                                                                                                                            | `string`                                                      |\n\n#### Example\n\n```ts\nlet amount = [123456789000000000000000n, 18];\n\n// If no digits are provided, the digits correspond to the decimals\ndnum.format(amount); // 123,456.789\n\n// options.digits\ndnum.format(amount, { digits: 2 }); // 123,456.79\ndnum.format(amount, 2); // 123,456.79 (alias for { digits: 2 })\n\n// options.compact\ndnum.format(amount, { compact: true }); // 123K\n\n// options.trailingZeros\ndnum.format(amount, { digits: 6, trailingZeros: true }); // 123,456.789000\n```\n\n### `from(valueToParse, decimals)`\n\nParse 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.\n\n| Name                  | Description                                      | Type             |\n| --------------------- | ------------------------------------------------ | ---------------- |\n| `valueToParse`        | Value to convert into a `Dnum`                   | `Numberish`      |\n| `decimals` (optional) | Number of decimals (defaults to `true` for auto) | `number \\| true` |\n| returns               | Converted value                                  | `Dnum`           |\n\n#### Example\n\n```ts\n// Parses a number expressed as a string or number\nlet amount = dnum.from(\"17.30624\", 18);\n\n// amount equals [17306240000000000000n, 18]\n```\n\n### `add(value1, value2, decimals)`\n\nAdds two values together, regardless of their decimals. `decimals` correspond to the decimals desired in the result.\n\n| Name                  | Description                                     | Type        |\n| --------------------- | ----------------------------------------------- | ----------- |\n| `value1`              | First value to add                              | `Numberish` |\n| `value2`              | Second value to add                             | `Numberish` |\n| `decimals` (optional) | Result decimals (defaults to `value1` decimals) | `number`    |\n| returns               | Result                                          | `Dnum`      |\n\n### `subtract(value1, value2, decimals)`\n\nSubtracts the second value from the first one, regardless of their decimals. decimals correspond to the decimals desired in the result.\n\n| Name                  | Description                                     | Type        |\n| --------------------- | ----------------------------------------------- | ----------- |\n| `value1`              | Value from which `value2` is subtracted         | `Numberish` |\n| `value2`              | Value to subtract from `value1`                 | `Numberish` |\n| `decimals` (optional) | Result decimals (defaults to `value1` decimals) | `number`    |\n| returns               | Result                                          | `Dnum`      |\n\nAlias: `sub()`\n\n### `multiply(value1, value2, optionsOrDecimals)`\n\nMultiply two values together, regardless of their decimals. `options.decimals` correspond to the decimals desired in the result.\n\n| Name                          | Description                                                                                                         | Type        |\n| ----------------------------- | ------------------------------------------------------------------------------------------------------------------- | ----------- |\n| `value1`                      | First value to multiply                                                                                             | `Numberish` |\n| `value2`                      | Second value to multiply                                                                                            | `Numberish` |\n| `options.decimals` (optional) | Results decimals (defaults to `value1` decimals). Setting `options` to a `number` acts as an alias for this option. | `Decimals`  |\n| `options.rounding` (optional) | How to round round results (defaults to `\"ROUND_HALF\"`)                                                             | `Rounding`  |\n| returns                       | Result                                                                                                              | `Dnum`      |\n\nAlias: `mul()`\n\n#### Example\n\n```ts\nlet ethPriceUsd = [100000n, 2]; // 1000 USD\nlet tokenPriceEth = [570000000000000000, 18]; // 0.57 ETH\n\nlet tokenPriceUsd = dnum.multiply(tokenPriceEth, ethPriceUsd, 2); // 570 USD\n\n// tokenPriceUsd equals [57000, 2]\n```\n\n### `divide(value1, value2, optionsOrDecimals)`\n\nDivide a value by another one, regardless of their decimals. `options.decimals` correspond to the decimals desired in the result.\n\n| Name                          | Description                                                                                                         | Type        |\n| ----------------------------- | ------------------------------------------------------------------------------------------------------------------- | ----------- |\n| `value1`                      | Dividend                                                                                                            | `Numberish` |\n| `value2`                      | Divisor                                                                                                             | `Numberish` |\n| `options.decimals` (optional) | Results decimals (defaults to `value1` decimals). Setting `options` to a `number` acts as an alias for this option. | `Decimals`  |\n| `options.rounding` (optional) | How to round round results (defaults to `\"ROUND_HALF\"`)                                                             | `Rounding`  |\n| returns                       | Result                                                                                                              | `Dnum`      |\n\nAlias: `div()`\n\n#### Example\n\n```ts\nlet ethPriceUsd = [100000n, 2]; // 1000 USD\nlet tokenPriceUsd = [57000, 2]; // 570 USD\n\nlet tokenPriceEth = dnum.divide(tokenPriceUsd, ethPriceUsd, 18); // 0.57 ETH\n\n// tokenPriceEth equals [570000000000000000, 18]\n```\n\n### `remainder(value1, value2, decimals)`\n\nEquivalent to [the `%` operator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Remainder): calculate the remainder left over when one operand is divided by a second operand.\n\n| Name                  | Description                                     | Type        |\n| --------------------- | ----------------------------------------------- | ----------- |\n| `value1`              | Dividend                                        | `Numberish` |\n| `value2`              | Divisor                                         | `Numberish` |\n| `decimals` (optional) | Result decimals (defaults to `value1` decimals) | `number`    |\n| returns               | Result                                          | `Dnum`      |\n\nAlias: `rem()`\n\n### `abs(value, decimals)`\n\nEquivalent to the [`Math.abs()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/abs) function: it returns the absolute value of the `Dnum` number.\n\n| Name                  | Description                                    | Type        |\n| --------------------- | ---------------------------------------------- | ----------- |\n| `value`               | Value to remove the sign from                  | `Numberish` |\n| `decimals` (optional) | Result decimals (defaults to `value` decimals) | `number`    |\n| returns               | Result                                         | `Dnum`      |\n\n#### Example\n\n```ts\nlet value = [-100000n, 2];\n\ndnum.abs(value); // [100000n, 2]\n```\n\n### `round(value, optionsOrDecimals)`\n\nEquivalent to the [`Math.round()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/round) function, with added option to forcibly round up or down: it returns the value of a number rounded to the nearest integer.\n\n| Name                          | Description                                                                                                        | Type        |\n| ----------------------------- | ------------------------------------------------------------------------------------------------------------------ | ----------- |\n| `value`                       | Value to round to the nearest integer                                                                              | `Numberish` |\n| `options.decimals` (optional) | Results decimals (defaults to `value` decimals). Setting `options` to a `number` acts as an alias for this option. | `Decimals`  |\n| `options.rounding` (optional) | How to round round results (defaults to `\"ROUND_HALF\"`)                                                            | `Rounding`  |\n| returns                       | Result                                                                                                             | `Dnum`      |\n\n#### Example\n\n```ts\nlet value = [-123456n, 2]; // 1234.56\n\ndnum.round(value); // [123500n, 2] or 1235.00\n```\n\n### `floor(value, decimals)`\n\nEquivalent to the [`Math.floor()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/floor) function: it rounds down and returns the largest integer less than or equal to the number.\n\n| Name                  | Description                                    | Type        |\n| --------------------- | ---------------------------------------------- | ----------- |\n| `value`               | Value to round down                            | `Numberish` |\n| `decimals` (optional) | Result decimals (defaults to `value` decimals) | `number`    |\n| returns               | Result                                         | `Dnum`      |\n\n### `ceil(value, decimals)`\n\nEquivalent to the [`Math.ceil()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/ceil) function: it rounds rounds up and returns the smaller integer greater than or equal to the number.\n\n| Name                  | Description                                    | Type        |\n| --------------------- | ---------------------------------------------- | ----------- |\n| `value`               | Value to round up                              | `Numberish` |\n| `decimals` (optional) | Result decimals (defaults to `value` decimals) | `number`    |\n| returns               | Result                                         | `Dnum`      |\n\n### `greaterThan(value1, value2)`\n\nEquivalent to [the `\u003e` operator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Greater_than): it returns `true` if the first value is greater than the second value and `false` otherwise, regardless of their respective decimals.\n\n| Name     | Description       | Type        |\n| -------- | ----------------- | ----------- |\n| `value1` | First value       | `Numberish` |\n| `value2` | Second value      | `Numberish` |\n| returns  | Comparison result | `boolean`   |\n\nAlias: `gt()`\n\n#### Example\n\n```ts\nlet value1 = [10000100n, 4];\nlet value2 = [100000n, 2];\n\ndnum.greaterThan(value1, value2); // true\ndnum.greaterThan(value1, value1); // false\ndnum.greaterThan(value2, value1); // false\n```\n\n### `greaterThanOrEqual(value1, value2)`\n\nEquivalent to [the `\u003e=` operator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Greater_than_or_equal): it returns `true` if the first value is greater than or equal to the second value and `false` otherwise, regardless of their respective decimals.\n\n| Name     | Description       | Type        |\n| -------- | ----------------- | ----------- |\n| `value1` | First value       | `Numberish` |\n| `value2` | Second value      | `Numberish` |\n| returns  | Comparison result | `boolean`   |\n\nAlias: `gte()`\n\n### `lessThan(value1, value2)`\n\nEquivalent to [the `\u003c` operator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Less_than): it returns `true` if the first value is less than the second value and `false` otherwise, regardless of their respective decimals.\n\n| Name     | Description       | Type        |\n| -------- | ----------------- | ----------- |\n| `value1` | First value       | `Numberish` |\n| `value2` | Second value      | `Numberish` |\n| returns  | Comparison result | `boolean`   |\n\nAlias: `lt()`\n\n#### Example\n\n```ts\nlet value1 = [100000n, 2];\nlet value2 = [10000100n, 4];\n\ndnum.lessThan(value1, value2); // true\ndnum.lessThan(value1, value1); // false\ndnum.lessThan(value2, value1); // false\n```\n\n### `lessThanOrEqual(value1, value2)`\n\nEquivalent to [the `\u003c=` operator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Less_than_or_equal): it returns `true` if the first value is less than or equal to the second value and `false` otherwise, regardless of their respective decimals.\n\n| Name     | Description       | Type        |\n| -------- | ----------------- | ----------- |\n| `value1` | First value       | `Numberish` |\n| `value2` | Second value      | `Numberish` |\n| returns  | Comparison result | `boolean`   |\n\nAlias: `lte()`\n\n### `equal(value1, value2)`\n\nEquivalent to [the `==` operator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Equality): it returns `true` if the first value is equal to the second value and `false` otherwise, regardless of their respective decimals.\n\n| Name     | Description       | Type        |\n| -------- | ----------------- | ----------- |\n| `value1` | First value       | `Numberish` |\n| `value2` | Second value      | `Numberish` |\n| returns  | Comparison result | `boolean`   |\n\nAlias: `eq()`\n\n#### Example\n\n```ts\nlet value1 = [100000n, 2];\nlet value2 = [10000000n, 4];\n\ndnum.equal(value1, value2); // true\n```\n\n### `compare(value1, value2)`\n\nReturns `1` if `value1 \u003e value2`, `-1` if `value1 \u003c value2`, `0` if `value1 == value2`. It makes it easy to combine `Dnum` values with sorting functions such as [`Array#sort()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort).\n\n| Name     | Description       | Type           |\n| -------- | ----------------- | -------------- |\n| `value1` | First value       | `Numberish`    |\n| `value2` | Second value      | `Numberish`    |\n| returns  | Comparison result | `1 \\| -1 \\| 0` |\n\nAlias: `cmp()`\n\n#### Example\n\n```ts\nlet sorted = [\n  1,\n  8n,\n  [700n, 2],\n  3.1,\n  2n,\n  5,\n].sort(compare);\n\nconsole.log(sorted); // [1, 2n, 3.1, 5, [700n, 2], 8n];\n```\n\n### `toNumber(value, optionsOrDigits)`\n\nConverts the `Dnum` data structure into a `number`. [This might result in a loss of precision](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number#number_encoding) depending on how large the number is.\n\n| Name                       | Description                                                                                                                                                                                               | Type                                         |\n| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- |\n| `value`                    | The number to convert into a `number`                                                                                                                                                                     | `Dnum`                                       |\n| `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`                                     |\n| `options.decimalsRounding` | Method used to round to `digits` decimals (defaults to `\"ROUND_HALF\"`).                                                                                                                                   | `\"ROUND_HALF\" \\| \"ROUND_UP\" \\| \"ROUND_DOWN\"` |\n| returns                    | Result                                                                                                                                                                                                    | `number`                                     |\n\n```ts\nlet value = [123456789000000000000000n, 18];\n\ntoNumber(value); // 123456.789\ntoNumber(value, { digits: 1 }); // 123456.8\ntoNumber(value, 1); // 123456.8 (alias for { digits: 1 })\n```\n\n### `toString(value, optionsOrDigits)`\n\nConverts the `Dnum` data structure into a `string`, without any formatting. [This might result in a loss of precision](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number#number_encoding) depending on how large the number is.\n\n| Name                       | Description                                                                                                                                                                                               | Type                                         |\n| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- |\n| `value`                    | The number to convert into a `string`                                                                                                                                                                     | `Dnum`                                       |\n| `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`                                     |\n| `options.decimalsRounding` | Method used to round to `digits` decimals (defaults to `\"ROUND_HALF\"`).                                                                                                                                   | `\"ROUND_HALF\" \\| \"ROUND_UP\" \\| \"ROUND_DOWN\"` |\n| returns                    | String conversion of the value                                                                                                                                                                            | `string`                                     |\n\n```ts\nlet value = [123456789000000000000000n, 18];\n\ntoString(value); // \"123456.789\"\ntoString(value, { digits: 1 }); // \"123456.8\"\ntoString(value, 1); // \"123456.8\" (alias for { digits: 1 })\n```\n\nNote 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.\n\n### `toJSON(value)`\n\nConverts the `Dnum` data structure into a JSON-compatible string. This function is provided because `JSON.stringify()` doesn’t work with `BigInt` data types.\n\n| Name    | Description                       | Type     |\n| ------- | --------------------------------- | -------- |\n| `value` | The number to convert into a JSON | `Dnum`   |\n| returns | JSON conversion of the value      | `string` |\n\n```ts\nlet json = toJSON([123456789000000000000n, 18]);\n\n// json == \"[\\\"123456789000000000000\\\", 18]\";\n```\n\n### `fromJSON(value)`\n\nConverts the string resulting from `toJSON()` back into a `Dnum`.\n\n| Name    | Description                                    | Type     |\n| ------- | ---------------------------------------------- | -------- |\n| `value` | The string value to convert back into a `Dnum` | `string` |\n| returns | `Dnum` value parsed from the JSON              | `Dnum`   |\n\n```ts\nlet dnum = fromJSON(\"[\\\"123456789000000000000\\\", 18]\");\n\n// dnum == [123456789000000000000n, 18]\n```\n\n### `setDecimals(value, decimals, options)`\n\nReturn a new `Dnum` with a different amount of decimals. The value will reflect this change so that the represented number stays the same.\n\n| Name            | Description                                                                                 | Type       |\n| --------------- | ------------------------------------------------------------------------------------------- | ---------- |\n| `value`         | The number from which decimals will be changed                                              | `Dnum`     |\n| `decimals`      | New number of decimals                                                                      | `number`   |\n| `options.round` | In case of reduction, whether to round the remaining decimals (defaults to `\"ROUND_HALF\"`). | `Rounding` |\n| returns         | Result                                                                                      | `Dnum`     |\n\nNote: `from(value, decimals)` can also be used instead.\n\n## Tree shaking\n\nTo make use of tree shaking, named exports are also provided:\n\n```ts\nimport { format, from } from \"dnum\";\n```\n\n## FAQ\n\n### Should dnum be used instead of BigInt or libraries such as BN.js or decimal.js?\n\ndnum is not a full replacement for libraries such as [decimal.js](https://mikemcl.github.io/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.\n\n### Why is it called dnum?\n\ndnum stands for Decimal Numbers.\n\n### Who made the logo and banner? 😍\n\nThe gorgeous visual identity of dnum has been created by [Paty Davila](https://twitter.com/dizzypaty).\n\n## Acknowledgements\n\n- [ethers](https://ethers.org/), in particular its [`parseFixed()`](https://github.com/ethers-io/ethers.js/blob/8b62aeff9cce44cbd16ff41f8fc01ebb101f8265/packages/bignumber/src.ts/fixednumber.ts#L70) function.\n- [token-amount](https://github.com/aragon/token-amount) which was an attempt at solving a similar problem.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbpierre%2Fdnum","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbpierre%2Fdnum","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbpierre%2Fdnum/lists"}