Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/jscheiny/safe-units
Type-safe TypeScript units of measure ๐ท๐
https://github.com/jscheiny/safe-units
dimensional-analysis typesafe typescript units units-of-measure
Last synced: about 2 months ago
JSON representation
Type-safe TypeScript units of measure ๐ท๐
- Host: GitHub
- URL: https://github.com/jscheiny/safe-units
- Owner: jscheiny
- License: mit
- Created: 2018-05-10T21:04:29.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2024-07-01T13:25:47.000Z (3 months ago)
- Last Synced: 2024-07-19T02:12:44.776Z (2 months ago)
- Topics: dimensional-analysis, typesafe, typescript, units, units-of-measure
- Language: TypeScript
- Homepage: https://jscheiny.github.io/safe-units
- Size: 771 KB
- Stars: 258
- Watchers: 4
- Forks: 13
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Safe Units
[![NPM Version](https://img.shields.io/npm/v/safe-units.svg)](https://www.npmjs.com/package/safe-units) [![MIT License](https://img.shields.io/npm/l/safe-units.svg)](https://github.com/jscheiny/safe-units/blob/master/LICENSE)
Safe Units is a type safe library for using units of measurement in TypeScript. 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.
```ts
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()); // 30 m
console.log(time.toString()); // 15 s
console.log(velocity.toString()); // 2 m * s^-1// @ts-expect-error ERROR: A measure of m*s isn't assignable to a measure of m/s.
const error: Velocity = length.times(time);
```## Features
โญย Compile-time unit arithmetic for typesafe dimensional analysis (with exponents between -5 and +5)!
โญย Large library of predefined units including SI (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](http://www.typescriptlang.org/) 3.2 or later
- [Strict null checks](https://www.typescriptlang.org/docs/handbook/compiler-options.html) enabled for your project## Installation
```
npm install safe-units
```or
```
yarn add safe-units
```## Examples
### Unit Arithmetic
```ts
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 mass = Measure.of(30, kilograms);
const mps2 = meters.per(seconds.squared());
const acceleration = Measure.of(9.8, mps2);const force = mass.times(acceleration); // 294 N
const pressure = force.over(area); // 49 Pa
const maxPressure = Measure.of(0.5, milli(bars)); // 0.5 mbar
pressure.lt(maxPressure); // true```
### Type Errors
```ts
import { Force, hours, Length, Measure, meters, seconds, Time } from "safe-units";const length: Length = Measure.of(10, meters);
const time: Time = Measure.of(10, seconds);// @ts-expect-error - Measures of different units cannot be added
length.plus(time);// @ts-expect-error - Measures of different units cannot be compared
length.eq(time);// @ts-expect-error - Measure of m/s is not assigneable to measure of kg*m/s^2
const force: Force = length.over(time);// @ts-expect-error - Cannot convert length measure to time measure
length.in(hours);```
### Naming Units
```ts
import { days, Measure, mega, micro, miles, speedOfLight, yards } from "safe-units";const furlongs = Measure.of(220, yards, "fur");
Measure.of(8, furlongs).in(miles); // "1 mi"
Measure.of(1, miles).in(furlongs); // "8 fur"const fortnights = Measure.of(14, days, "ftn");
const megafurlong = mega(furlongs);
const microfortnight = micro(fortnights);
const mfPerUFtn = megafurlong.per(microfortnight).withSymbol("Mfur/ยตftn");speedOfLight.in(mfPerUFtn); // "1.8026174997852542 Mfur/ยตftn"
```
### Deriving Quantities
```ts
import { kilograms, liters, Mass, Measure, Volume } from "safe-units";const VolumeDensity = Mass.over(Volume);
type VolumeDensity = typeof VolumeDensity;const mass = Measure.of(30, kilograms);
const volume = Measure.of(3, liters);const density: VolumeDensity = mass.over(volume);
console.log(density.toString()); // 10 kg * m^-3
```
### Defining Unit Systems
```ts
import { Measure, UnitSystem } from "safe-units";const GameUnitSystem = UnitSystem.from({
frames: "fr",
time: "s",
});const frames = Measure.dimension(GameUnitSystem, "frames");
const seconds = Measure.dimension(GameUnitSystem, "time");const Frames = frames;
type Frames = typeof frames;const Time = seconds;
type Time = typeof seconds;const FrameRate = Frames.over(Time);
type FrameRate = typeof FrameRate;const fps: FrameRate = frames.per(seconds).withSymbol("fps");
const minFrameRate = Measure.of(60, fps);
const measuredFrames = Measure.of(8000, frames);
const elapsedTime = Measure.of(120, seconds);
const measuredFps: FrameRate = measuredFrames.over(elapsedTime);if (measuredFps.lt(minFrameRate)) {
// Optimize
}```