npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

uom

v6.0.0

Published

Extensible unit of measure conversion with type safety for typescript

Downloads

3,035

Readme

uom

npm version travis build Coverage Status code style: prettier MIT license

Extensible unit of measure conversion with type safety for typescript

Introduction

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

Installation

npm install --save uom

The library is compiled to ES5 and no polyfills are required.

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:

npm install --save uom-units

Features

Conversion

This feature allows you to convert amounts into different units.

import { Amount } from "uom";
import { Units } from "uom-units";

const amount = Amount.create(10, Units.Meter);
const inch = Amount.valueAs(Units.Inch, amount);

Extension (create your own unit)

A measure system has a number of BaseUnits 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 BaseUnitss and they can be used to create the m/s ProductUnit.

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

By using the base units you can create any unit.

import { Amount, Unit } from "uom";
import { Units } from "uom-units";

const myInchUnit = Unit.divideNumber(12.0, Units.Foot);
const amount = Amount.create(10, myInchUnit);
const meter = Amount.valueAs(Units.Meter, amount);

Type safety (typescript only)

By declaring your functions with a signature of typed Amount you can make sure the right type of amounts are inputs to the function.

import { Amount } from "uom";
import { Units } from "uom-units";

const length1 = Amount.create(10, Units.Meter);
const length2 = Amount.create(10, Units.Inch);
const volume1 = Amount.create(10, Units.CubicMeter);

const result = calculate(length1, length2); // OK
const result = calculate(volume1, length2); // Compile error

function calculate(Amount<Length> length1, Amount<Length> length2): Amount<Length> {
    return Amount.plus(length1, length2);
}

Formatting

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

However if you are just building something smaller and want quick formatting, the [uo] package has some opinionated formatting that is directly associated with each Unit built-in. Specifically you can get the label and number of decimals for each unit.

However if you are just building something smaller and want quick formatting, this package has some opinionated formatting that is directly associated with each Unit built-in. Specifically you can get the label and number of decimals for each unit.

import { Amount, Format } from "uom";
import { Units } from "uom-units";

const length = Amount.create(10, Units.Meter);
const format = UnitFormat.getUnitFormat(length);
console.log(
  "The amount is " +
    Math.round(Amount.valueAs(Units.Inch, amount), format.decimalCount) +
    " " +
    format.label
);

There is also the buildDerivedSymbol() function which will derive a symbol for a unit by looking at which base units the unit was created:

import { Amount, Format } from "uom";
import { Units } from "uom-units";

const length = Amount.create(10, Units.MeterPerSecond);
const label = Unit.buildDerivedSymbol(length);
console.log(label); // m/s

Serialization

This feature can be used to serialize the units for persisting to/from for example a database.

import { Amount, Serialize } from "uom";
import { Units } from "uom-units";

const length = Amount.create(10, Units.Meter);
const serialized = Serialize.amountToString(length);
const deserialized = Serialize.stringToAmount(serialized);

API

The 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().

For more information, see the full API docs.

How to develop

Create a PR for addition or changes. Please update the changelog's "unreleased" section with your changes in your PR.

How to publish

Don't forget to update the changelog before publishing. Then run:

yarn version --patch
yarn version --minor
yarn version --major

Prior art

This library was inspired by JSR-275. See also this repo, this article. Altough JSR-275 was not accepted it evolved into JSR-363 which is now accepted.