Have ideas to improve npm?Join in the discussion! ¬Ľ

    amounts

    0.5.0¬†‚Äʬ†Public¬†‚Äʬ†Published

    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

    Install

    npm i amounts

    DownloadsWeekly Downloads

    2,779

    Version

    0.5.0

    License

    MIT

    Last publish

    Collaborators

    • avatar