百科.dev
全部条目在线工具AI 编程趋势榜开源项目技术资讯提交条目
登录
< 返回工具列表
J

js-quantities

> 编程语言
开源

用于数量计算和单位转换的 JavaScript 库

398 stars0 点赞2 次浏览
访问官网GitHub

工具介绍

用于数量计算和单位转换的 JavaScript 库

JS-quantities

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.

Installation

Install with npm install js-quantities or download latest release v1.8.0 as:

  • UMD module
  • ES module

Usage

Node.js

javascript
// As CommonJS module
const Qty = require('js-quantities');

// As ES module
import Qty from 'js-quantities';

Browsers

  • UMD module could be included as is:
xml

In this case, it will define a global variable Qty.

  • With an AMD loader like Require.JS:
javascript
define(['quantities'], function(Qty) {
  ...
});
  • As ES module:
xml

Synopsis

Creation

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):

javascript
qty = new Qty('23 ft'); // constructor
qty = Qty('23 ft'); // factory

Qty 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:

javascript
qty = new Qty(124, 'cm'); // => 1.24 meter
qty = Qty(124, 'cm'); // => 1.24 meter

For the sake of simplicity, one will use the factory way below but using new Qty() is equivalent.

javascript
qty = Qty('1m'); // => 1 meter
qty = Qty('m'); // =>  1 meter (scalar defaults to 1)

qty = Qty('1 N*m');
qty = Qty('1 N m'); // * is optional

qty = Qty('1 m/s');

qty = Qty('1 m^2/s^2');
qty = Qty('1 m^2 s^-2'); // negative powers
qty = Qty('1 m2 s-2'); // ^ is optional

qty = Qty('1 m^2 kg^2 J^2/s^2 A');

qty = Qty('1.5'); // unitless quantity
qty = Qty(1.5); // number as initializing value

qty = Qty('1 attoparsec/microfortnight');

qtyCopy = Qty(qty); // quantity could be copied when used as
                    // initializing value

Qty.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.

javascript
Qty.parse('1 m'); // => 1 meter
Qty.parse('foo') // => null

Available well-known kinds

javascript
Qty.getKinds(); // => Array of names of every well-known kind of units

Available units of a particular kind

javascript
Qty.getUnits('currency'); // => [ 'dollar', 'cents' ]
// Or all alphabetically sorted
Qty.getUnits(); // => [ 'acre','Ah','ampere','AMU','angstrom']

Alternative names of a unit

javascript
Qty.getAliases('m'); // => [ 'm', 'meter', 'meters', 'metre', 'metres' ]

Quantity compatibility, kind and various queries

javascript
qty1.isCompatible(qty2); // => true or false

qty.kind(); // => 'length', 'area', etc...

qty.isUnitless(); // => true or false
qty.isBase(); // => true if quantity is represented with base units

Conversion

…

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.

javascript
var convert = Qty.swiftConverter('m/h', 'ft/s'); // Configures converter

// Converting single value
var converted = convert(2500); // => 2.278..

// Converting large array of values
var convertedSerie = convert([2500, 5000, ...]); // => [2.278.., 4.556.., ...]

The main drawback of this conversion method is that it does not take care of rounding issues.

Comparison

javascript
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 qty2
qty1.lte(qty2); // => true if qty1 is less than or equal to qty2
qty1.gt(qty2); // => true if qty1 is stricty greater than qty2
qty1.gte(qty2); // => true if qty1 is greater than or equal to qty2

qty1.compareTo(qty2); // => -1 if qty1  0 if qty1 == qty2,
                      // => 1 if qty1 > qty2

Operators

  • 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.

Rounding

Qty#toPrec(precision) : returns the nearest multiple of quantity passed as precision.

…

Formatting quantities

Qty#toString returns a string using the canonical form of the quantity (that is it could be seamlessly reparsed by Qty).

javascript
var qty = 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.

javascript
var qty = 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:

javascript
var qty = 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.

javascript
var qty = 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.

javascript
var configurableRoundingFormatter = function(maxDecimals) {
  return function(scalar, units) {
    var pow = Math.pow(10, maxDecimals);
    var rounded = Math.round(scalar * pow) / pow;

    return rounded + ' ' + units;
  };
};

var qty = 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.

javascript
Qty.formatter = configurableRoundingFormatter(2);
var qty = Qty('1.1234 m');
qty.format(); // same units, current default formatter => '1.12 m'

Temperatures

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.

javascript
Qty('37 tempC').to('tempF') // => 98.6 tempF

JS-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.

…
javascript
Qty('100 tempC').to('degC') // => 100 degC

This conversion references the 0 point on the scale of the temperature unit

javascript
Qty('100 degC').to('tempC') // => -173.15 tempC

These conversions are always interpreted as being relative to absolute zero. Conversions are probably better done like this...

javascript
Qty('0 tempC').add('100 degC') // => 100 tempC

Errors

Every error thrown by JS-quantities is an instance of Qty.Error.

javascript
try {
  // code triggering an error inside JS-quantities
}
catch(e) {
  if(e instanceof Qty.Error) {
    // ...
  }
  else {
    // ...
  }
}

Tests

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

Performance regression 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

TypeScript type declarations

A TypeScript declaration file is published on DefinitelyTyped.

It could be installed with npm install @types/js-quantities.

Contribute

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.

Issues· 59 开放

查看全部 Issues在 GitHub 打开

暂无开放 Issues,或尚未同步最近议题。

> 标签

JavaScriptconversionconvertimperialjavascript

暂无评论,来聊聊你的看法吧

> 工具信息

发布日期2026年8月1日
最后更新2026年9月17日
分类编程语言
定价开源

> 相关工具

T
TypeScript
JavaScript 的超集,为前端与全栈提供静态类型
P
Python
通用编程语言,广泛用于 Web、数据与 AI
G
Go
Google 推出的简洁高效系统语言