{"id":18285919,"url":"https://github.com/exodusmovement/number-unit","last_synced_at":"2025-04-05T08:30:33.796Z","repository":{"id":65466612,"uuid":"45796375","full_name":"ExodusMovement/number-unit","owner":"ExodusMovement","description":"A JavaScript component to handle arbitrary precision numbers with units.","archived":false,"fork":false,"pushed_at":"2017-03-30T19:44:10.000Z","size":73,"stargazers_count":18,"open_issues_count":10,"forks_count":4,"subscribers_count":36,"default_branch":"master","last_synced_at":"2025-03-30T09:15:48.862Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ExodusMovement.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-11-08T19:58:20.000Z","updated_at":"2023-07-28T23:34:45.000Z","dependencies_parsed_at":"2023-02-20T20:30:51.475Z","dependency_job_id":null,"html_url":"https://github.com/ExodusMovement/number-unit","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ExodusMovement%2Fnumber-unit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ExodusMovement%2Fnumber-unit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ExodusMovement%2Fnumber-unit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ExodusMovement%2Fnumber-unit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ExodusMovement","download_url":"https://codeload.github.com/ExodusMovement/number-unit/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247311247,"owners_count":20918331,"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-11-05T13:18:10.835Z","updated_at":"2025-04-05T08:30:33.481Z","avatar_url":"https://github.com/ExodusMovement.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"Number (with) Unit\n==================\n\n[![NPM Package](https://img.shields.io/npm/v/number-unit.svg?style=flat-square)](https://www.npmjs.org/package/number-unit)\n[![Build Status](https://img.shields.io/travis/ExodusMovement/number-unit.svg?branch=master\u0026style=flat-square)](https://travis-ci.org/ExodusMovement/number-unit)\n\n[![js-standard-style](https://cdn.rawgit.com/feross/standard/master/badge.svg)](http://standardjs.com)\n\nA [heavily tested](https://github.com/jprichardson/number-unit/tree/master/tests) JavaScript component to handle arbitrary precision numbers with units.\n\n\nWhy?\n----\n\nA number without context (unit) is meaningless. Even more so in the realm of\ncomputers. Computers rely on input, usually from humans, to be precise. Humans are prone to error.\nThis library helps to remove that error.\n\nConsider these two famous incidents...\n\n1. **Mars Surveyor '98 Orbiter**\n\nFrom https://en.wikipedia.org/wiki/Mars_Climate_Orbiter:\n\n\u003e However, on September 23, 1999, communication with the spacecraft was lost as the spacecraft went into orbital insertion, due to ground-based computer software which produced output in non-SI units of pound-seconds (lbf s) instead of the metric units of newton-seconds (N s) specified in the contract between NASA and Lockheed. The spacecraft encountered Mars on a trajectory that brought it too close to the planet, causing it to pass through the upper atmosphere and disintegrate.\n\n2. **Air Canada Flight 143**\n\nFrom https://en.wikipedia.org/wiki/Gimli_Glider:\n\n\u003e ...ran out of fuel at an altitude of 12,500 metres (41,000 ft) MSL, about halfway through its flight originating in Montreal to Edmonton. The crew were able to glide the aircraft safely to an emergency landing at Gimli Industrial Park Airport, a former Royal Canadian Air Force base in Gimli, Manitoba.[1]\n\n\u003e The subsequent investigation revealed a combination of company failures and a chain of human errors that defeated built-in safeguards. Fuel loading was miscalculated because of a misunderstanding of the recently adopted metric system which replaced the imperial system.\n\n---\n\nIf you're writing software that **handles people's money** (http://www.exodus.io/), you can't afford to be wrong. **That's why\nthis library was built.**\n\n\nInstall\n-------\n\n    npm i --save number-unit\n\n\nUsage\n-----\n\n**Quick example:**\n\n```js\n// import { UnitType } from 'number-unit' // if using ES6 (ES2015)\nvar UnitType = require('number-unit').UnitType\n\n// create a UnitType first\nvar bitcoin = UnitType.create('bitcoin', { satoshis: 1, bits: 1e2, BTC: 1e8 }, 'bits')\n\n// now create a NumberUnit\nvar amount1 = bitcoin.BTC(1.53)\nvar amount2 = bitcoin.bits('1530000') // notice, can accept strings as well\n\nconsole.log(amount1.toString()) // =\u003e 1.53 BTC\nconsole.log(amount2.toString()) // =\u003e 1530000 bits\n\n// compare numerical values\nconsole.log(amount1.equals(amount2)) // =\u003e true\n```\n\n\n\n### Important Concepts to Know\n\n1. You must use `UnitType.create()` to create a `UnitType()` to start working with\nNumberUnits.\n\n2. UnitTypes can be a type of other UnitTypes. For example, you may create\na `UnitType` named `distance`, and then want to create another named `distanceSI`\nrepresenting your desire to model [SI / Metric Units](https://en.wikipedia.org/wiki/International_System_of_Units).\nNow you may want to create another named `distanceUS`, modeling\n[United States customary units](https://en.wikipedia.org/wiki/United_States_customary_units). Since both\nhave `distance` has a parent type, you can convert between the two. This is the value\nof parent types. As it wouldn't make sense to convert from distance to currency or something\nlie that. See for some examples: https://github.com/jprichardson/number-unit\n\n\n### UnitType\n\n#### UnitType.create()\n\nMethod signature: `UnitType.create(label, [parentUnitType], [definitions], [defaultUnit])`\n\nCreates an instance of `UnitType` and returns it.\n\n- `label`: The unit type label.\n- `parentUnitType`: The parent unit type. Useful for converting between UnitType that have the same parent.\n- `definitions`: Actual conversions.\n- `defaultUnit`: Default unit. Used when `defaultUnit` is called.\n\n```js\nvar UnitType = require('number-unit').UnitType\nvar bitcoin = UnitType.create('bitcoin', { satoshis: 1, bits: 1e2, BTC: 1e8 }, 'bits')\n```\n\n\n#### UnitType.prototype.parse()\n\nMethod signature: `parse(string)`\n\nMethod that parses the input string and returns an instance of `NumberUnit` with\na number value extracted from the string and a `unitName` from the string.\n\n```js\nvar amount = bitcoin.parse('1.53 BTC')\nconsole.log(amount.toNumber()) // =\u003e 1.53\nconsole.log(amount.unitName) // =\u003e BTC\n```\n\n\n#### UnitType.prototype.ZERO\n\nProperty that creates and returns an instance of `NumberUnit` with a number value of `0` and a\nthe unit being the default unit.\n\n```js\nvar zero = bitcoin.ZERO\nconsole.log(amount.toNumber()) // =\u003e 0\nconsole.log(amount.unitName) // =\u003e bits\n```\n\n\n\n### NumberUnit\n\nCreate instances of `NumberUnit` with the UnitType factory methods.\n\n**Note:** All methods on `NumberUnit` instances return new instances of `NumberUnit`,\nthat is, NumberUnits are immutable.\n\n```js\nvar amount = bitcoin.BTC(3.5)\nconsole.log(amount instanceof NumberUnit) // =\u003e true\n```\n\n\n#### NumberUnit.prototype.abs()\n\n**Signature:** `abs()`\n\n**Parameters:** (none)\n\n**Returns:** a new instance of `NumberUnit` with the absolute value of the number.\n\n**Example:**\n\n```js\nvar amount = bitcoin.BTC(-3.5)\nconsole.log(amount.abs().toString()) // =\u003e 3.5 BTC\n```\n\n\n#### NumberUnit.prototype.add()\n\n**Signature:** `add(number)`\n\n**Parameters:**\n- `number`: Can either by of type `number` or `NumberUnit`. If `strict` mode is set\nit can only be of type `NumberUnit`.\n\n**Returns:** a new instance of `NumberUnit` that represents the sum of the two numbers.\n\n**Example:**\n\n```js\nvar amount = bitcoin.BTC(-3.5)\nvar sum = amount.add(bitcoin.bits('1000000'))\nconsole.log(sum.toString()) // =\u003e -2.5 BTC\n```\n\n\n#### NumberUnit.prototype.clampLowerZero()\n\nIf the value is less than zero, return zero.\n\n**Signature:** `clampLowerZero()`\n\n**Parameters:** (none)\n\n**Returns:** An instance of NumberUnit that is either itself or zero.\n\n**Example:**\n\n```js\nconsole.log(bitcoin.BTC(1.53).clampLowerZero().toString()) // =\u003e 1.53 BTC\nconsole.log(bitcoin.BTC(-1.53).clampLowerZero().toString()) // =\u003e 0 BTC\n```\n\n\n#### NumberUnit.prototype.clone()\n\n**Signature:** `clone()`\n\n**Parameters:** (none)\n\n**Returns:** New instance of `NumberUnit` that is a clone.\n\n**Example:**\n\n```js\nvar amount = bitcoin.BTC(1.3)\nvar amount2 = amount.clone()\nconsole.log(amount2.toString()) // =\u003e 1.3 BTC\n```\n\n\n#### NumberUnit.prototype.equals()\n\n**Signature:** `equals(numberUnit)`\n\n**Parameters:**\n- `numberUnit`: Another of instance of a `NumberUnit` to check equality with. Units\ndo not matter. e.g. `1000 m = 1 km`.\n\n**Returns:** A `boolean`, `true` if equals.\n\n**Example:**\n\n```js\nvar distance1 = distanceSI.km(1)\nvar distance2 = distanceSI.m(1000)\n\nconsole.log(distance1.equals(distance2)) // =\u003e true\n```\n\n\n#### NumberUnit.prototype.gt()\n\nCheck if number is greater than the other.\n\n**Signature:** `gt(numberUnit)`\n\n**Parameters:**\n\n- `numberUnit`: Another of instance of a `NumberUnit`.\n\n**Returns:** A `boolean`, `true` if it's greater than.\n\n**Example:**\n\n```js\nvar distance1 = distanceSI.km(1.1)\nvar distance2 = distanceSI.m(1000)\n\nconsole.log(distance1.gt(distance2)) // =\u003e true\n```\n\n\n#### NumberUnit.prototype.gte()\n\nCheck if number is greater than or equal than the other.\n\n**Signature:** `gte(numberUnit)`\n\n**Parameters:**\n\n- `numberUnit`: Another of instance of a `NumberUnit`.\n\n**Returns:** A `boolean`, `true` if it's greater than or equal.\n\n**Example:**\n\n```js\nvar distance1 = distanceSI.km(1.1)\nvar distance2 = distanceSI.m(1000)\n\nconsole.log(distance1.gte(distance2)) // =\u003e true\n```\n\n\n#### NumberUnit.prototype.isZero()\n\nReturns `true` or `false` depending upon whether the number is `0`.\n\n**Signature:** `isZero()`\n\n**Parameters:** (none)\n\n**Returns:**  A `boolean` depending upon whether the number is `0`.\n\n**Example:**\n\n```js\nconsole.log(bitcoin.BTC(0).isZero()) // =\u003e true\nconsole.log(bitcoin.BTC(-1).isZero()) // =\u003e false\n```\n\n\n#### NumberUnit.prototype.lt()\n\nCheck if one number is less than the other.\n\n**Signature:** `lt(numberUnit)`\n\n**Parameters:**\n\n- `numberUnit`: Another of instance of a `NumberUnit`.\n\n**Returns:** A `boolean`, `true` if it's less than.\n\n**Example:**\n\n```js\nvar distance1 = distanceSI.km(1.1)\nvar distance2 = distanceSI.m(1000)\n\nconsole.log(distance1.lt(distance2)) // =\u003e false\n```\n\n\n#### NumberUnit.prototype.lte()\n\nCheck if number is less than or equal than the other.\n\n**Signature:** `lte(numberUnit)`\n\n**Parameters:**\n\n- `numberUnit`: Another of instance of a `NumberUnit`.\n\n**Returns:** A `boolean`, `true` if it's less than or equal.\n\n**Example:**\n\n```js\nvar distance1 = distanceSI.km(1.1)\nvar distance2 = distanceSI.m(1000)\n\nconsole.log(distance1.lte(distance2)) // =\u003e false\n```\n\n\n#### NumberUnit.prototype.negate()\n\nNegate the number.\n\n**Signature:** `negate()`\n\n**Parameters:** (none)\n\n**Returns:** New instance of `NumberUnit` with the number negated.\n\n**Example:**\n\n```js\nvar distance1 = distanceSI.km(1)\nvar distance2 = distance1.negate()\n\nconsole.log(distance2.toString()) // =\u003e '-1 km'\n```\n\n\n#### NumberUnit.prototype.subtract()\n\nCalculate the difference between two numbers.\n\n**Signature:** `subtract(numberUnit)`\n\n**Parameters:**\n\n- `numberUnit`: Another of instance of a `NumberUnit`.\n\n**Returns:** An instance of NumberUnit that represents the subtraction of the two.\n\n**Example:**\n\n```js\nvar distance1 = distanceSI.km(3)\nvar distance2 = distanceSI.m(1000)\nvar distance3 = distance1.subtract(distance2)\n\nconsole.log(distance3.toString()) // =\u003e '2 km'\n```\n\n\n#### NumberUnit.prototype.toBase()\n\nConvert the number to the base number (unit with multiplier of `1`).\n\n**Signature:** `toBase()`\n\n**Parameters:** (none)\n\n**Returns:** An instance of NumberUnit that same number except in the base units.\n\n**Example:**\n\n```js\n// USD has multiplier of `1` and thus, is the 'base' unit.\nvar dollar = UnitType.create('dollar', { USD: 1, cents: 1e-2 }, 'USD')\nvar amount1 = dollar.cents(600)\nvar amount2 = amount1.toBase()\nconsole.log(amount2.toString()) // =\u003e '6 USD'\n```\n\n\n#### NumberUnit.prototype.toDefault()\n\nConvert the number to the default unit.\n\n**Signature:** `toDefault()`\n\n**Parameters:** (none)\n\n**Returns:** An instance of NumberUnit that same number except in the default unit.\n\n**Example:**\n\n```js\n// 'bits' is defined as the default unit.\nvar bitcoin = UnitType.create('bitcoin', { satoshis: 1, bits: 1e2, BTC: 1e8 }, 'bits')\nvar amount1 = bitcoin.BTC(1.5)\nvar amount2 = amount1.toDefault() // convert to 'bits'\nconsole.log(amount2.toString()) // =\u003e '1500000 bits'\n```\n\n\n#### NumberUnit.prototype.to()\n\nConvert the number to any other unit.\n\n**Signature:** `to(unit)`\n\n**Parameters:** `unit` type of `string` or `Unit`.\n\n**Returns:** An instance of NumberUnit that represents the same value, just expressed as a different unit.\n\n**Example:**\n\n```js\n// 'bits' is defined as the default unit.\nvar bitcoin = UnitType.create('bitcoin', { satoshis: 1, bits: 1e2, BTC: 1e8 }, 'bits')\nvar amount1 = bitcoin.BTC(1.5)\nvar amount2 = amount1.to('bits') // type 'string'\nvar amount3 = amount1.to(bitcoin.bits) // type 'Unit'\nconsole.log(amount2.toString()) // =\u003e '1500000 bits'\nconsole.log(amount3.toString()) // =\u003e '1500000 bits'\n```\n\n#### NumberUnit.prototype.toNumber()\n\nConvert a `NumberUnit` to a `number`.\n\n**Signature:** `toNumber()`\n\n**Parameters:** (none)\n\n**Returns:** A `number` representing the numeric value in the `NumberUnit`\n\n**Example:**\n\n```js\n// 'bits' is defined as the default unit.\nvar bitcoin = UnitType.create('bitcoin', { satoshis: 1, bits: 1e2, BTC: 1e8 }, 'bits')\nvar amount1 = bitcoin.BTC(1.5)\nconsole.log(amount1.toNumber()) = // =\u003e 1.5\n```\n\n\n#### NumberUnit.prototype.toString()\n\nConvert a `NumberUnit` to a a `string`.\n\n**Signature:** `toString([options])`\n\n**Parameters:** `options`, type of `object`. Optional.\n  - `unit`: `boolean`, defaults to `true`. If `true`, include the unit string.\n\n**Returns:** A `string` representing the number and optionally the unit.\n\n**Example:**\n\n```js\n// 'bits' is defined as the default unit.\nvar bitcoin = UnitType.create('bitcoin', { satoshis: 1, bits: 1e2, BTC: 1e8 }, 'bits')\nvar amount1 = bitcoin.BTC(1.5)\nconsole.log(amount1.toString()) = // =\u003e 1.5 BTC\nconsole.log(amount1.toString({ unit: false })) = // =\u003e 1.5\n```\n\n\n#### NumberUnit.prototype.isNegative\n\n`boolean` property if number is negative.\n\n**Signature:** `isNegative`\n\n**Returns:** A `boolean`, `true` if the number is negative.\n\n**Example:**\n\n```js\n// 'bits' is defined as the default unit.\nvar bitcoin = UnitType.create('bitcoin', { satoshis: 1, bits: 1e2, BTC: 1e8 }, 'bits')\nvar amount1 = bitcoin.BTC(-1.5)\nconsole.log(amount1.isNegative) // =\u003e true\n```\n\n\n\n### Unit\n\n\n\n\n\n### ConversionUnit\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fexodusmovement%2Fnumber-unit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fexodusmovement%2Fnumber-unit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fexodusmovement%2Fnumber-unit/lists"}