JS-quantities is originally a JavaScript port of Kevin Olbrich's library Ruby Units (http://github.com/olbrich/ruby-units).
The library aims to simplify the handling of units for scientific calculations involving quantities.
JS-quantities is built as UMD and ES modules and can be used with Node.js and browsers. It has no dependencies.
Install with npm install js-quantities or download latest release v1.7.5 as:
// As CommonJS module
const Qty = require('js-quantities');
// As ES module
import Qty from 'js-quantities/esm';
- UMD module could be included as is:
<scriptsrc='quantities.js'></script>In this case, it will define a global variable Qty.
- With an AMD loader like Require.JS:
define(['quantities'],function(Qty){
...
});Instances of quantities are made by means of Qty() method. Qty can both be
used as a constructor (with new) or as a factory (without new):
qty=newQty('23 ft');// constructorqty=Qty('23 ft');// factoryQty constructor accepts strings, numbers and Qty instances as
initializing values.
If scalars and their respective units are available programmatically, the two argument signature may be useful:
qty=newQty(124,'cm');// => 1.24 meterqty=Qty(124,'cm');// => 1.24 meterFor the sake of simplicity, one will use the factory way below but using
new Qty() is equivalent.
qty=Qty('1m');// => 1 meterqty=Qty('m');// => 1 meter (scalar defaults to 1)qty=Qty('1 N*m');qty=Qty('1 N m');// * is optionalqty=Qty('1 m/s');qty=Qty('1 m^2/s^2');qty=Qty('1 m^2 s^-2');// negative powersqty=Qty('1 m2 s-2');// ^ is optionalqty=Qty('1 m^2 kg^2 J^2/s^2 A');qty=Qty('1.5');// unitless quantityqty=Qty(1.5);// number as initializing valueqty=Qty('1 attoparsec/microfortnight');qtyCopy=Qty(qty);// quantity could be copied when used as// initializing valueQty.parse utility method is also provided to parse and create
quantities from strings. Unlike the constructor, it will return null
instead of throwing an error when parsing an invalid quantity.
Qty.parse('1 m');// => 1 meterQty.parse('foo')// => nullQty.getKinds();// => Array of names of every well-known kind of unitsQty.getUnits('currency');// => [ 'dollar', 'cents' ]// Or all alphabetically sortedQty.getUnits();// => [ 'acre','Ah','ampere','AMU','angstrom']Qty.getAliases('m');// => [ 'm', 'meter', 'meters', 'metre', 'metres' ]qty1.isCompatible(qty2);// => true or falseqty.kind();// => 'length', 'area', etc...qty.isUnitless();// => true or falseqty.isBase();// => true if quantity is represented with base unitsqty.toBase();// converts to SI units (10 cm => 0.1 m) (new instance)qty.toFloat();// returns scalar of unitless quantity// (otherwise throws error)qty.to('m');// converts quantity to meter if compatible// or throws an error (new instance)qty1.to(qty2);// converts quantity to same unit of qty2 if compatible// or throws an error (new instance)qty.inverse();// converts quantity to its inverse// ('100 m/s' => '.01 s/m')// Inverses can be used, but there is no special checking to// rename the unitsQty('10ohm').inverse()// '.1/ohm'// (not '.1S', although they are equivalent)// however, the 'to' command will convert between inverses alsoQty('10ohm').to('S')// '.1S'Qty.swiftConverter() is a fast way to efficiently convert large array of
Number values. It configures a function accepting a value or an array of Number
values to convert.
varconvert=Qty.swiftConverter('m/h','ft/s');// Configures converter// Converting single valuevarconverted=convert(2500);// => 2.278..// Converting large array of valuesvarconvertedSerie=convert([2500,5000, ...]);// => [2.278.., 4.556.., ...]The main drawback of this conversion method is that it does not take care of rounding issues.
qty1.eq(qty2);// => true if both quantities are equal (1m == 100cm => true)qty1.same(qty2);// => true if both quantities are same (1m == 100cm => false)qty1.lt(qty2);// => true if qty1 is stricty less than qty2qty1.lte(qty2);// => true if qty1 is less than or equal to qty2qty1.gt(qty2);// => true if qty1 is stricty greater than qty2qty1.gte(qty2);// => true if qty1 is greater than or equal to qty2qty1.compareTo(qty2);// => -1 if qty1 < qty2,// => 0 if qty1 == qty2,// => 1 if qty1 > qty2- add(other): Add. other can be string or quantity. other should be unit compatible.
- sub(other): Substract. other can be string or quantity. other should be unit compatible.
- mul(other): Multiply. other can be string, number or quantity.
- div(other): Divide. other can be string, number or quantity.
Qty#toPrec(precision) : returns the nearest multiple of quantity passed as
precision.
varqty=Qty('5.17 ft');qty.toPrec('ft');// => 5 ftqty.toPrec('0.5 ft');// => 5 ftqty.toPrec('0.25 ft');// => 5.25 ftqty.toPrec('0.1 ft');// => 5.2 ftqty.toPrec('0.05 ft');// => 5.15 ftqty.toPrec('0.01 ft');// => 5.17 ftqty.toPrec('0.00001 ft');// => 5.17 ftqty.toPrec('2 ft');// => 6 ftqty.toPrec('2');// => 6 ftvarqty=Qty('6.3782 m');qty.toPrec('dm');// => 6.4 mqty.toPrec('cm');// => 6.38 mqty.toPrec('mm');// => 6.378 mqty.toPrec('5 cm');// => 6.4 mqty.toPrec('10 m');// => 10 mqty.toPrec(0.1);// => 6.3 mvarqty=Qty('1.146 MPa');qty.toPrec('0.1 bar');// => 1.15 MPaQty#toString returns a string using the canonical form of the quantity (that
is it could be seamlessly reparsed by Qty).
varqty=Qty('1.146 MPa');qty.toString();// => '1.146 MPa'As a shorthand, units could be passed to Qty#toString and is equivalent to
successively call Qty#to then Qty#toString.
varqty=Qty('1.146 MPa');qty.toString('bar');// => '11.46 bar'qty.to('bar').toString();// => '11.46 bar'Qty#toString could also be used with any method from Qty to make some sort
of formatting. For instance, one could use Qty#toPrec to fix the maximum
number of decimals:
varqty=Qty('1.146 MPa');qty.toPrec(0.1).toString();// => '1.1 MPa'qty.to('bar').toPrec(0.1).toString();// => '11.5 bar'For advanced formatting needs as localization, specific rounding or any other
custom customization, quantities can be transformed into strings through
Qty#format according to optional target units and formatter. If target units
are specified, the quantity is converted into them before formatting.
Such a string is not intended to be reparsed to construct a new instance of
Qty (unlike output of Qty#toString).
If no formatter is specified, quantities are formatted according to default
js-quantities' formatter and is equivalent to Qty#toString.
varqty=Qty('1.1234 m');qty.format();// same units, default formatter => '1.234 m'qty.format('cm');// converted to 'cm', default formatter => '123.45 cm'Qty#format could delegates formatting to a custom formatter if required. A
formatter is a callback function accepting scalar and units as parameters and
returning a formatted string representing the quantity.
varconfigurableRoundingFormatter=function(maxDecimals){returnfunction(scalar,units){varpow=Math.pow(10,maxDecimals);varrounded=Math.round(scalar*pow)/pow;returnrounded+' '+units;};};varqty=Qty('1.1234 m');// same units, custom formatter => '1.12 m'qty.format(configurableRoundingFormatter(2));// convert to 'cm', custom formatter => '123.4 cm'qty.format('cm',configurableRoundingFormatter(1));Custom formatter can be configured globally by setting Qty.formatter.
Qty.formatter=configurableRoundingFormatter(2);varqty=Qty('1.1234 m');qty.format();// same units, current default formatter => '1.12 m'Like ruby-units, JS-quantities makes a distinction between a temperature (which technically is a property) and degrees of temperature (which temperatures are measured in).
Temperature units (i.e., 'tempK') can be converted back and forth, and will take into account the differences in the zero points of the various scales. Differential temperature (e.g., '100 degC') units behave like most other units.
Qty('37 tempC').to('tempF')// => 98.6 tempFJS-quantities will throw an error if you attempt to create a temperature unit that would fall below absolute zero.
Unit math on temperatures is fairly limited.
Qty('100 tempC').add('10 degC')// 110 tempCQty('100 tempC').sub('10 degC')// 90 tempCQty('100 tempC').add('50 tempC')// throws errorQty('100 tempC').sub('50 tempC')// 50 degCQty('50 tempC').sub('100 tempC')// -50 degCQty('100 tempC').mul(scalar)// 100*scalar tempCQty('100 tempC').div(scalar)// 100/scalar tempCQty('100 tempC').mul(qty)// throws errorQty('100 tempC').div(qty)// throws errorQty('100 tempC*unit')// throws errorQty('100 tempC/unit')// throws errorQty('100 unit/tempC')// throws errorQty('100 tempC').inverse()// throws errorQty('100 tempC').to('degC')// => 100 degCThis conversion references the 0 point on the scale of the temperature unit
Qty('100 degC').to('tempC')// => -173.15 tempCThese conversions are always interpreted as being relative to absolute zero. Conversions are probably better done like this...
Qty('0 tempC').add('100 degC')// => 100 tempCEvery error thrown by JS-quantities is an instance of Qty.Error.
try{// code triggering an error inside JS-quantities}catch(e){if(einstanceofQty.Error){// ...}else{// ...}}Tests are implemented with Jasmine (https://github.com/pivotal/jasmine). You could use both HTML and jasmine-node runners.
To execute specs through HTML runner, just open SpecRunner.html file in a
browser to execute them.
To execute specs through jasmine-node, launch:
make test
There is a small benchmarking HTML page to spot performance regression between currently checked-out quantities.js and any committed version. Just execute:
make bench
then open http://0.0.0.0:3000/bench
Checked-out version is benchmarked against HEAD by default but it could be changed by passing any commit SHA on the command line. Port (default 3000) is also configurable.
make bench COMMIT=e0c7fc468 PORT=5000
A TypeScript declaration file is published on DefinitelyTyped.
It could be installed with npm install @types/js-quantities.
Feedback and contributions are welcomed.
Pull requests must pass tests and linting. Please make sure that make test
and make lint return no errors before submitting.