Safe Units

Safe Units is a type safe library for using units of measurement in TypeScript. Check it out on github. Safe Units provides an implementation of an SI based unit system but is flexible enough to allow users to create their own unit systems which can be independent or can interoperate with the built-in units. Users can also make unit systems for any numeric type they ' d like not just the JavaScript number type. This library requires TypeScript 3.2 or higher.

import { Length, Measure, meters, seconds, Time, Velocity } from "safe-units" ; const length: Length = Measure.of( 30 , meters); const time: Time = Measure.of( 15 , seconds); const velocity: Velocity = length.over(time); console .log(length.toString()); console .log(time.toString()); console .log(velocity.toString()); const error: Velocity = length.times(time);

Features include:

⭐ Compile-time unit arithmetic for typesafe dimensional analysis (with exponents between -5 and +5) !

⭐ Large library of predefined units including metric (with prefixes), Imperial, and US customary units !

⭐ Ability to add your own unit system that can work with built-in units !

⭐ Long build times & cryptic error messages !

Prerequisites

Safe units is written in TypeScript and should be consumed by TypeScript users to take full advantage of what it provides. In addition you will need the following:

TypeScript 3.2 or later

Strict null checks enabled for your project

Installation

npm install safe-units

or

yarn add safe-units

Examples

Unit arithmetic

import { bars, kilograms, Measure, meters, milli, seconds } from "safe-units" ; const width = Measure.of( 3 , meters); const height = Measure.of( 4 , meters); const area = width.times(height).scale( 0.5 ); const hypot = Measure.sqrt(width.squared().plus(height.squared())); const mass = Measure.of( 30 , kilograms); const mps2 = meters.per(seconds.squared()); const acceleration = Measure.of( 9.8 , mps2); const force = mass.times(acceleration); const pressure = force.over(area); const maxPressure = Measure.of( 0.5 , milli(bars)); pressure.lt(maxPressure)

Type errors

import { Force, Length, Measure, meters, seconds, Time } from "safe-units" ; const length: Length = Measure.of( 10 , meters); const time: Time = Measure.of( 10 , seconds); length.plus(time); length.minus(time); const force: Force = length.over(time); const root = Measure.sqrt(length);

Naming units

import { days, Measure, miles, speedOfLight, yards } from "safe-units" ; const furlongs = Measure.of( 220 , yards, "fur" ); console .log(Measure.of( 8 , furlongs).in(miles)); console .log(Measure.of( 1 , miles).in(furlongs)); const fortnights = Measure.of( 14 , days, "ftn" ); const megaFurlongsPerMicroFortnight = mega(furlongs) .per(micro(fortnights)) .withSymbol( "Mfur/µftn" ); console .log(speedOfLight.in(megaFurlongsPerMicroFortnight));

Deriving quantities

import { Acceleration, Measure, meters, seconds, Time } from "safe-units" ; const Jerk = Acceleration.over(Time); type Jerk = typeof Jerk; const mps2 = meters.per(seconds.squared()); const acceleration = Measure.of( 9.8 , mps2); const jerk: Jerk = acceleration.over(Measure.of( 2 , seconds)); console .log(jerk.toString());

Defining dimensions