{"id":20470177,"url":"https://github.com/dividab/uom","last_synced_at":"2025-04-13T10:43:59.275Z","repository":{"id":57387023,"uuid":"135833906","full_name":"dividab/uom","owner":"dividab","description":"Extensible unit of measure conversion with type safety for typescript","archived":false,"fork":false,"pushed_at":"2021-08-12T16:47:21.000Z","size":628,"stargazers_count":18,"open_issues_count":6,"forks_count":1,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-09T23:02:25.680Z","etag":null,"topics":["measure","unit","unit-of-measure","uom"],"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/dividab.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-06-02T16:27:05.000Z","updated_at":"2024-04-11T05:39:51.000Z","dependencies_parsed_at":"2022-09-26T16:50:44.937Z","dependency_job_id":null,"html_url":"https://github.com/dividab/uom","commit_stats":null,"previous_names":[],"tags_count":23,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dividab%2Fuom","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dividab%2Fuom/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dividab%2Fuom/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dividab%2Fuom/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dividab","download_url":"https://codeload.github.com/dividab/uom/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248415901,"owners_count":21099777,"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":["measure","unit","unit-of-measure","uom"],"created_at":"2024-11-15T14:12:00.788Z","updated_at":"2025-04-13T10:43:59.253Z","avatar_url":"https://github.com/dividab.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# uom\n\n[![npm version][version-image]][version-url]\n[![travis build][travis-image]][travis-url]\n[![Coverage Status][codecov-image]][codecov-url]\n[![code style: prettier][prettier-image]][prettier-url]\n[![MIT license][license-image]][license-url]\n\nExtensible unit of measure conversion with type safety for typescript\n\n## Introduction\n\nThis package has functions to handle unit of measures. It works particulary well with typescript in which case it can provice some type safety for amounts of different quantity.\n\n## Installation\n\n`npm install --save uom`\n\nThe library is compiled to ES5 and no polyfills are required.\n\n\u003e NOTE: The base package `uom` does only contain the base SI units. In order to get more units to convert between you also need to install the `uom-units` package:\n\n`npm install --save uom-units`\n\n## Features\n\n### Conversion\n\nThis feature allows you to convert amounts into different units.\n\n```js\nimport { Amount } from \"uom\";\nimport { Units } from \"uom-units\";\n\nconst amount = Amount.create(10, Units.Meter);\nconst inch = Amount.valueAs(Units.Inch, amount);\n```\n\n### Extension (create your own unit)\n\nA measure system has a number of `BaseUnit`s which is used to create all other derived units in the system which are represented as `ProductUnit` or `TransformedUnit`. For example in the SI measure system, `m` and `s` are `BaseUnits`s and they can be used to create the `m/s` `ProductUnit`.\n\nIn the case that a derived unit can be known by a different name, an `AlternateUnit` can be used. For example in the SI system the derived unit `N/m2` is also known as `Pascal`.\n\nBy using the base units you can create any unit.\n\n```js\nimport { Amount, Unit } from \"uom\";\nimport { Units } from \"uom-units\";\n\nconst myInchUnit = Unit.divideNumber(12.0, Units.Foot);\nconst amount = Amount.create(10, myInchUnit);\nconst meter = Amount.valueAs(Units.Meter, amount);\n```\n\n### Type safety (typescript only)\n\nBy declaring your functions with a signature of typed Amount you can make sure the right type of amounts are inputs to the function.\n\n```ts\nimport { Amount } from \"uom\";\nimport { Units } from \"uom-units\";\n\nconst length1 = Amount.create(10, Units.Meter);\nconst length2 = Amount.create(10, Units.Inch);\nconst volume1 = Amount.create(10, Units.CubicMeter);\n\nconst result = calculate(length1, length2); // OK\nconst result = calculate(volume1, length2); // Compile error\n\nfunction calculate(Amount\u003cLength\u003e length1, Amount\u003cLength\u003e length2): Amount\u003cLength\u003e {\n    return Amount.plus(length1, length2);\n}\n```\n\n### Formatting\n\nAsosciating formatting directly with an `Unit` or `Quantity` is generally not a good idea. Formatting is application specific and should be implemented within application code. For example, an application may have air flows and water flows that both are of `VolumeFlow` quantity. In this case you may want separate labels and default units for air flow and water flow. Associating formatting directly with `VolumeFlow` or its units will not solve this. Instead, try tagging each `VolumeFlow` field within the application with either `air_flow`, or `water_flow` and provide different labels and default units per tag.\n\nHowever if you are just building something smaller and want quick formatting, this package has some utilities for assigning formats directly associated with each `Unit`. Specifically you can assign a format consisting of a label and number of decimals for each unit. The actual formats are not present in this package but is provided in external unit packages such as [uom-units](https://www.npmjs.com/package/uom-units).\n\n```ts\nimport { Amount, Format } from \"uom\";\nimport { Units, UnitsFormat } from \"uom-units\";\n\nconst format = UnitFormat.getUnitFormat(Units.Meter, UnitsFormat);\nconsole.log(\n  \"The amount is \" +\n    Math.round(Amount.valueAs(Units.Meter, amount), format.decimalCount) +\n    \" \" +\n    format.label\n);\n```\n\nThere is also the `buildDerivedSymbol()` function which will derive a symbol for a unit by looking at which base units the unit was created:\n\n```ts\nimport { Amount, Format } from \"uom\";\nimport { Units } from \"uom-units\";\n\nconst length = Amount.create(10, Units.MeterPerSecond);\nconst label = Unit.buildDerivedSymbol(length);\nconsole.log(label); // m/s\n```\n\n### Serialization\n\nThis feature can be used to serialize the units for persisting to/from for example a database.\n\n```ts\nimport { Amount, Serialize } from \"uom\";\nimport { Units } from \"uom-units\";\n\nconst length = Amount.create(10, Units.Meter);\nconst serialized = Serialize.amountToString(length);\nconst deserialized = Serialize.stringToAmount(serialized);\n```\n\n## API\n\nThe API is divided into modules, where each module contains functions that operate on a type that is exported from that module. For example the `Amount` module exports the type `Amount.Amount` and has functions like `Amount.plus()`.\n\nFor more information, see the [full API docs](docs/api.md).\n\n## How to develop\n\nCreate a PR for addition or changes. Please update the changelog's \"unreleased\" section with your changes in your PR.\n\n## How to publish\n\nDon't forget to update the changelog before publishing. Then run:\n\n```\nyarn version --patch\nyarn version --minor\nyarn version --major\n```\n\n## Prior art\n\nThis library was inspired by [JSR-275](http://download.oracle.com/otn-pub/jcp/untis-0.6-edr-oth-JSpec/Units-v0.6_edr.pdf?AuthParam=1527941513_89b45d975b743c799d22105ff16f961b). See also this [repo](http://code.google.com/p/unitsofmeasure/), this [article](https://www.javaworld.com/article/2077770/core-java/introduction-to-jsr-275--measures-and-units.html). Altough JSR-275 was not accepted it evolved into [JSR-363](http://www.baeldung.com/javax-measure) which is now accepted.\n\n[version-image]: https://img.shields.io/npm/v/uom.svg?style=flat\n[version-url]: https://www.npmjs.com/package/uom\n[travis-image]: https://travis-ci.com/dividab/uom.svg?branch=master\u0026style=flat\n[travis-url]: https://travis-ci.com/dividab/uom\n[codecov-image]: https://codecov.io/gh/dividab/uom/branch/master/graph/badge.svg\n[codecov-url]: https://codecov.io/gh/dividab/uom\n[license-image]: https://img.shields.io/github/license/dividab/uom.svg?style=flat\n[license-url]: https://opensource.org/licenses/MIT\n[prettier-image]: https://img.shields.io/badge/code_style-prettier-ff69b4.svg?style=flat\n[prettier-url]: https://github.com/prettier/prettier\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdividab%2Fuom","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdividab%2Fuom","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdividab%2Fuom/lists"}