Units is a Javascript unit conversion and utility library built to support the OneStepGPS tracking platform and API. This library can be used in both the browser and with Node.js.
Currently this library supports the following types: Distance, Speed, Duration, Pressure, Fuel Rate, Acceleration, Temperature, Flow Rate, Volume
Install this package using npm:
$ npm install @onestepgps/units
Units objects can be created in a few different ways.
import { Distance } from "@onestepgps/units";
let my_distance = new Distance(10, "mi"); //two arguments, value and unit
let my_distance = new Distance("10mi"); //single string argument
let my_distance = new Distance({ value: 10, unit: "mi" }); //single object argument
All Units objects have the following three properties:
my_distance.value; // 10
my_distance.unit; // 'mi'
my_distance.display; // '10 mi'
The set
function should be used to change the internal value of a units object. This function will accept the same inputs as the constructer.
my_distance.set(15, "km").display; // '15 km'
my_distance.set("120m").display; // '120 m'
my_distance.set({ value: 25, unit: "mi" }).display; // '25 mi'
Aditionally, a single Number
argument can be used to set the value property if the object has a valid unit.
let my_distance = new Speed("10km");
my_distance.set(33).display; // '33 km'
The value and unit can also be manually updated, but this is discouraged because the display property will not be automatically updated. Use the function updateDisplay to set the display to reflect manual changes to unit/value.
let my_distance = new Speed("10 km");
my_distance.value = 2;
my_distance.unit = "mi";
my_distance.display; // '10 km'
my_distance.updateDisplay();
my_distance.display; // '2 mi'
The add
function is used to add objects together, and will accept the same format of arguments as the set
function. Objects of the same type but with different units can be added. Note that the function displayRounded
is also used below, which returns the display property with the value rounded to the given number of decimal points
let my_speed = new Speed("2mph");
my_speed.add(3).display; // '5mph'
my_speed.add(5, "mph").display; // '7 mph'
my_speed.add("1 km/h").displayRounded(3); // '2.621 mph'
my_speed.add(new Speed(100, "m/s")).displayRounded(2); // '225.69 mph'
The function cmp
is used to compare objects of the same type. Arguments can be in any formats which set
accepts. Objects of different units can be compared. The cmp
function will output -1 if it is less than the given value, 1 if greater, and 0 if equal.
let my_pressure = new Pressure("10pa");
my_pressure.cmp(20, 'pa'); // -1
my_pressure.cmp(0.5 'kpa'); // 1
A object can be converted to a different unit with the toUnit
function, which takes a single unit string argument.
let my_temp = new Temperature("75f");
my_temp.toUnit("c").display; // '23.8889 c`
A type is 'valid' if it has a Number in its value
prop, a supported unit in its unit
prop, and a non-empty string value in its display
prop. The isValid
function will return a boolean indicating whether or not the object is 'valid'.
let my_dist = new Distance("10mi");
my_dist.isValid(); // true
my_dist.value = null;
my_dist.isValid(); // false
The isEmpty
function is used to check if an object has undefined or null for all its properties. An 'empty' object is by definition not 'valid'.
let my_empty_speed = new Speed({});
my_empty_speed.isEmpty(); // true
my_empty_speed.isValid(); // false
Note that 'empty' objects will not throw an error upon creation, but all other non 'valid' objects will throw an error on creation.
The string representation of Duration
is slightly different than other types. Duration
objects can be created with a single string argument using the format shown in the examples below. Note that the largest duration unit given will be the setting of the unit
property.
new Duration("2m").display; // '2m 0s'
new Duration("1h 2m 60s").display; // '1h 3m 0s'
new Duration("85s").display; // '85s'
new Duration("1m85s").display; // '2m 25s'
new Duration("1h2s").display; // '1h 0m 2s'
Temperature units are displayed in a slightly different format compared to other types, e.g. 10°F
instead of 10 f
. The Temperature constructor can also accept strings of this format to create new temperature objects.
Distance
- mi - miles
- km - kilometers
- m - meters
- cm - centimeters
- mm - millimeters
- in - inches
- ft - feet
Speed
- mph - miles per hour
- km/h - kilometers per hour
- m/s - meters per second
- cm/s - centimeter per second
Duration
- h - hours
- m - minutes
- s - seconds
- ms - milliseconds
Pressure
- pa - pascal
- kpa - kilopascal
- psi - pound per square inch
- bar - bar
Fuel Rate
- mpg - miles per gallon
- km/l - kilometers per liter
Acceleration
- cm/s/s - centimeters per second squared
- g - gravitational acceleration
Temperature
- f - Fahrenheit
- c - Celsius
Flow Rate
- ml/h - milliliters per hour
Volume
- ml - milliliters
- l - liters
- g - gallons
- floz - fluid ounces