Amounts

Represent amounts of stuff with units and conversions. Supports lenient parsing of amounts, normalization and basic formatting.

const { length, duration } = require('amounts');

// Supports parsing from strings:
const value = length('30 m');
// Convert into another unit (returns a number)
console.log(length.as('ft'));
console.log(length.feet);

// Parse durations
console.log(duration('20 m, 4 s'));

// Supports precision on the numbers
length('2.8 cm')
length('2e10 m')

Amounts tries to be friendly with handling input, supporting variations of units, such as both short and long names, with longer unit names being case insensitive.

These will all parse to the same unit and value:

mass('750 ug');
mass('750 micrograms');
mass('750 micro gram');
mass('750 MikroGram')

But this will not work:

mass('750 uG');

Or fetch units from factories and use convert:

// To convert to mmHg
pressure.unit('mmHg').convert('200.12 kPa');
// Or back to kPa
pressure.unit('kPa').convert(1501.023, 'mmHg');

API

All amounts that can be represented share a common API. Factories support:

• factory(string)

  Parse the given string into an amount.

• factory(value, unit)

  Create an amount with the given value and unit.

• factory(value)

  Create an amount with the given value and the default unit.

• factory.unit(unit)

  Get a unit that can be used for conversions for this factory.

Instances have the following API:

• amount.value: Number

  Get the value of the amount.

• amount.unit: String

  Get the unit of the amount.

• amount.as(unit): Number

  Convert the amount to the given unit and return the result as a number.

• amount.to(unit): Amount

  Convert the amount into another unit and return an object with the value.

Every amount also exposes getters for the most commonly used units:

length('20 cm').meters
length('19 ft').cm

volume(1, 'l').oz

Generic amounts

The generic amount does not have any units, but supports SI-prefixes.

const { generic } = require('amounts');

// Without any unit, returns an amount with value 20
console.log(generic(20));

// With a generic SI-unit, returns an amount with value 20000
console.log(generic('20k'));

// Full length names are supported
console.log(generic('20 micro'))

SI-prefixes

Units in the SI system can be combined with SI-prefixes to create a new unit. SI-prefixes are supported both by their short names and their long names. Examples: cm, milliliters, hPa, MW, kilowatt

Long Name | Short name | Factor | Factor (expanded) ---------------|----------------|---------------------|------------------- yocto | y | 10-24 | 0.000 000 000 000 000 000 000 001 zepto | z | 10-21 | 0.000 000 000 000 000 000 001 atto | a | 10-18 | 0.000 000 000 000 000 001 femto | f | 10-15 | 0.000 000 000 000 001 pico | p | 10-12 | 0.000 000 000 001 nano | n | 10-9 | 0.000 000 001 micro | u, mc, µ | 10-6 | 0.000 001 milli | m | 10-3 | 0.001 centi | c | 10-2 | 0.01 deci | d | 10-1 | 0.1 deca, deka | da | 101 | 10 hecto | h | 102 | 100 kilo | k | 103 | 1 000 mega | M | 106 | 1 000 000 giga | G | 109 | 1 000 000 000 tera | T | 1012 | 1 000 000 000 000 peta | P | 1015 | 1 000 000 000 000 000 exa | E | 1018 | 1 000 000 000 000 000 000 zetta | Z | 1021 | 1 000 000 000 000 000 000 000 yotta | Y | 1024 | 1 000 000 000 000 000 000 000 000

Angle

const { angle } = require('amounts');

console.log(angle(2, 'rad'));
console.log(angle('5 degrees').as('radians'));

Unit | SI | Names -------------|------|-------------------- Degree | No | deg, degree, degrees Radian | Yes | rad, radian, radians

Area

const { area } = require('amounts');

console.log(area(2, 'm^2'));
console.log(area('10 sq ft').as('m2'));

Unit | SI | Names -------------|------|-------------------- Square Meter | Yes | m², m^2, m2, square metre, square metres, square meter, square meters Square Inch | No | sq in, square inch, square inches Square Foot | No | sq ft, square foot, square feet Square Yard | No | sq yd, square yard, square yards Square Mile | No | sq mi, square mile, square miles Hectare | No | ha, hectare, hectares Acre | No | acre, acres

Duration

Durations represent a number of milliseconds something takes. Multiple units can be combined into a value.

const { duration } = require('amounts');

console.log(duration(2000)); // Defaults to milliseconds
console.log(duration('1d'));
console.log(duration('2h 10m'));
console.log(duration('2 days, 5 hours'));

Unit | SI | Names -------------|------|--------------------------- Milliseconds | No | ms, millisecond, milliseconds Seconds | No | s, second, seconds Minutes | No | m, minute, minutes Hours | No | h, hour, hours Days | No | d, day, days

Energy

const { energy } = require('amounts');

console.log(energy(10)); // Joules
console.log(energy('3.5 kJ').kWh);

Unit | SI | Names -------------|------|-------------------- Joules | Yes | J, j, joule, joules Watt hours | True | Wh, wh, watt hour, watt hours

Illuminance

const { illuminance } = require('amounts');

console.log(illuminance(2, 'lx'));
console.log(angle('8000 lux'));

Unit | SI | Names -------------|------|-------------------- Lux | Yes | lx, lux Phot | No | ph, phot Nox | No | nx, nox Foot-candle | No | fc, lm/ft², ft-c, foot-candle, foot-candles, foot candle, foot candles

Length

const { length } = require('amounts');

console.log(length(2)); // Meters
console.log(length('5 ft').as('micrometer'));
console.log(length('2 ft ').cm);

Unit | SI | Names -------------|------|-------------------- Metre | Yes | m, meter, meters, metre, metres Inch | No | in, inch, inches Feet | No | ft, foot, feet Yard | No | yd, yard, yards Mile | No | mi, mile, miles

Mass

const { mass } = require('amounts');

console.log(mass(210)); // Grams
console.log(mass('78 kg').lbs);
console.log(mass('2 stone').kg)

Unit | SI | Names -------------|------|-------------------- Gram | Yes | g, gram, grams, gramme, grammes Pound | No | lb, lbs, pound, pounds, # Ounce | No | oz, ounce, ounces Stone | No | st, stone, stones

Power

const { power } = require('amounts');

console.log(power(500)); // Watts
console.log(power('6000 kW').mW);
console.log(power('6 hp').as('microwatts'));

Unit | SI | Names -------------|------|-------------------- Watt | Yes | w, W, watt Horsepower | No | hp, horsepower

Pressure

const { pressure } = require('amounts');

console.log(pressure(500)); // Pascal
console.log(power('700 hPa').atm);
console.log(power('7 bar').kPa);

Unit | SI | Names -------------|------|-------------------- Pascal | Yes | pa, Pa, pascal, pascals Atmosphere | No | atm, atmosphere, atmospheres Bar | No | bar, bars PSI | No | psi, pounds per square inch, pound per square inch Torr | No | torr mmHg | No | mmHg, 'millimetre of mercury', millimetres of mercury, millimeter of mercury, millimetres of mercury

Sound Pressure Level

const { soundPressureLevel } = require('amounts');

console.log(soundPressureLevel(30)); // db
console.log(soundPressureLevel(30, 'dB')); // db

Unit | SI | Names -------------|------|-------------------- Decibels | No | dB, db, dbs, decibel, decibels

Speed

const { speed } = require('amounts');

console.log(speed(500)); // m/s
console.log(speed('5 km/s').kph);
console.log(speed('10 mph').mps);

Unit | SI | Names ---------------|------|-------------------- Metres/Second | Yes | m/s, mps, metre per second, metres per second, meter per second, meters per second, metre/second, metres/second, meter/second, meters/second Kilometre/Hour | No | km/h, kph, kilometre per hour, kilometres per hour, kilometer per hour kilometers per hour, kilometers/hour, kilometre/hour Miles/Hour | No | mph, mile per hour, miles per hour, mile/hour, miles/hour Feet/Second | No | ft/s, fps, foot per second, feet per second, foot/second, feet/second Knot | No | kt, knot, knots

Temperature

const { temperature } = require('amounts');

console.log(temperature(22)); // Celsius
console.log(temperature('200 K').celsius);
console.log(temperature(80, 'f').kelvin);

Unit | SI | Names -------------|------|-------------------- Celsius | No | C, c, celsius Kelvin | Yes | K, kelvin, kelvins Fahrenheit | No | F, f, fahrenheit, fahrenheits

Voltage

const { voltage } = require('amounts');

console.log(voltage(22)); // Volts
console.log(voltage('200 V').volts);

Unit | SI | Names -------------|------|-------------------- Volt | Yes | V, v, volt, volts

Volume

const { volume } = require('amounts');

console.log(volume(2)); // Liters
console.log(volume(2, 'quarts').dl);
console.log(volume('20 ml').tbsp);

Unit | SI | Names -------------|------|-------------------- Liter | Yes | l, L, liter, litre, litre, litres Gallon | No | gal, gallon, gallons Quart | No | qt, quart, quarts Pint | No | pt, pint, pints Cup | No | cu, cup, cups Fluid ounce | No | floz, oz, fluid ounce, ounce, fluid ounces, ounces Tablespoon | No | tb, tbsp, tbs, tablesppon, tablespoons Teaspoon | No | tsp, teaspoon, teaspoons