Represent measured values with decimal scalars, convert units, and perform arithmetic while tracking dimensions. Requires Node.js 24 or newer; browser applications need an ESM-compatible bundler.
npm install @neutrium/quantity
import { Quantity } from '@neutrium/quantity';
const distance = new Quantity('150 km');
const duration = new Quantity('2 h');
const speed = distance.div(duration).to('km/h');
speed.scalar.toString(); // "75"
speed.units(); // "km/h"
Try the interactive Quantity Lab to explore conversions, arithmetic, and temperatures in your browser.
| Import | Exports | Purpose |
|---|---|---|
@neutrium/quantity |
Quantity | Construct, convert, and calculate quantities. |
@neutrium/quantity/regex |
Quantity | Construct quantities with Regex and exclude Nearley from bundles. |
@neutrium/quantity/core |
QuantityCore, createQuantityClass, supporting types | Configure a parser without importing a built-in parser. |
@neutrium/quantity/parsers/nearley |
NearleyQtyParser, QuantityParseError, error/result and configuration types | Rich expressions and structured diagnostics. |
@neutrium/quantity/parsers/regex |
RegexQtyParser, configuration types | Direct Regex import without Nearley. |
@neutrium/quantity/parsers.js |
NearleyQtyParser, RegexQtyParser | Parse scalar and unit expressions. |
@neutrium/quantity/guards.js |
isQuantity, isQuantityDefinition, QuantityInitParam | Inspect inputs and describe their TypeScript shape. |
QuantityDefinition, UnitPower, and Parser are exported as types from @neutrium/quantity/core. See Migrating to version 5 for the counted definition format.
| Task | API |
|---|---|
| Read the numerical value or unit expression | Quantity.scalar, Quantity.units |
| Convert to chosen units or base units | Quantity.to, Quantity.toBase |
| Add, subtract, multiply, or divide | Quantity.add, Quantity.sub, Quantity.mul, Quantity.div |
| Compare equivalent measurements | Quantity.eq, Quantity.compareTo |
| Check dimensions before an operation | Quantity.isCompatible |
| Distinguish temperature intervals from absolute temperatures | Quantity.isTemperature, Quantity.isDegrees |
Quantity values are getter-only and their counted unit records and arrays are frozen. Use arithmetic or construction to obtain new values. Configuration is also immutable; use Quantity.withConfig() for an isolated numerical context and cache budgets.
For the supported unit categories, prefixes, and naming conventions, see the package README.