numeric-quantity - v3.2.1

Converts a string to a number, like an enhanced version of parseFloat. Returns NaN if the provided string does not resemble a number.

Full documentation

In addition to plain integers and decimals, numeric-quantity handles:

• Fractions and mixed numbers: '1 2/3' → 1.667, '1⅖' → 1.4, '1 2⁄3' → 1.667
• Separators: '1,000' → 1000, '1_000_000' → 1000000
• Roman numerals (see option below): 'XIV' → 14, 'Ⅻ' → 12
• Non-ASCII numerals: Arabic-Indic ('٣'), Devanagari ('३'), Bengali, Thai, Fullwidth, and 70+ other Unicode digit scripts

For the inverse operation—converting a number to an imperial measurement—check out format-quantity.

For a more complete solution to parsing recipe ingredients, try parse-ingredient.

Usage

Installed

import { numericQuantity } from 'numeric-quantity';

console.log(numericQuantity('1 1/2')); // 1.5
console.log(numericQuantity('2 2/3')); // 2.667
Copy

CDN

As an ES module:

<script type="module">
  import { numericQuantity } from 'https://cdn.jsdelivr.net/npm/numeric-quantity/+esm';

  console.log(numericQuantity('10½')); // 10.5
</script>
Copy

As UMD (all exports are properties of the global object NumericQuantity):

<script src="https://unpkg.com/numeric-quantity"></script>
<script>
  console.log(NumericQuantity.numericQuantity('xii', { romanNumerals: true })); // 12
</script>
Copy

Options

All options are passed as the second argument to numericQuantity (and isNumericQuantity).

Rounding (round)

Results are rounded to three decimal places by default. Use the round option to change this behavior.

numericQuantity('1/3'); // 0.333 (default: 3 decimal places)
numericQuantity('1/3', { round: 5 }); // 0.33333
numericQuantity('1/3', { round: false }); // 0.3333333333333333
Copy

Trailing Invalid Characters (allowTrailingInvalid)

By default, strings with trailing non-numeric characters return NaN. Set allowTrailingInvalid: true to ignore trailing invalid characters, similar to parseFloat.

numericQuantity('100abc'); // NaN
numericQuantity('100abc', { allowTrailingInvalid: true }); // 100
Copy

Roman Numerals (romanNumerals)

Parse Roman numerals (ASCII or Unicode) by setting romanNumerals: true. You can also use parseRomanNumerals directly.

numericQuantity('MCCXIV', { romanNumerals: true }); // 1214
numericQuantity('Ⅻ', { romanNumerals: true }); // 12
numericQuantity('xiv', { romanNumerals: true }); // 14 (case-insensitive)
Copy

Decimal Separator (decimalSeparator)

For European-style numbers where comma is the decimal separator, set decimalSeparator: ','.

numericQuantity('1,5'); // 15 (comma treated as thousands separator)
numericQuantity('1,5', { decimalSeparator: ',' }); // 1.5
numericQuantity('1.000,50', { decimalSeparator: ',' }); // 1000.5
Copy

Large Integers (bigIntOnOverflow)

When parsing integers that exceed Number.MAX_SAFE_INTEGER or are less than Number.MIN_SAFE_INTEGER, set bigIntOnOverflow: true to return a bigint instead.

numericQuantity('9007199254740992'); // 9007199254740992 (loses precision)
numericQuantity('9007199254740992', { bigIntOnOverflow: true }); // 9007199254740992n
Copy

Percentages (percentage)

Parse percentage strings by setting the percentage option. Use 'decimal' (or true) to divide by 100, or 'number' to just strip the % symbol.

numericQuantity('50%'); // NaN
numericQuantity('50%', { percentage: true }); // 0.5
numericQuantity('50%', { percentage: 'decimal' }); // 0.5
numericQuantity('50%', { percentage: 'number' }); // 50
numericQuantity('1/2%', { percentage: true }); // 0.005
Copy

Currency Symbols (allowCurrency)

Strip currency symbols from the start or end of the string by setting allowCurrency: true. Supports all Unicode currency symbols ($, €, £, ¥, ₹, ₽, ₿, ₩, etc.).

numericQuantity('$100'); // NaN
numericQuantity('$100', { allowCurrency: true }); // 100
numericQuantity('€1.000,50', { allowCurrency: true, decimalSeparator: ',' }); // 1000.5
numericQuantity('100€', { allowCurrency: true }); // 100
numericQuantity('-$50', { allowCurrency: true }); // -50
Copy

Verbose Output (verbose)

Set verbose: true to return a detailed result object instead of just the numeric value. This is useful for understanding what was parsed and stripped.

numericQuantity('$50%', {
  verbose: true,
  allowCurrency: true,
  percentage: true,
});
// {
//   value: 0.5,
//   input: '$50%',
//   currencyPrefix: '$',
//   percentageSuffix: true
// }

numericQuantity('100abc', {
  verbose: true,
  allowTrailingInvalid: true,
});
// {
//   value: 100,
//   input: '100abc',
//   trailingInvalid: 'abc'
// }
Copy

For fraction and mixed-number inputs, the result also includes parsed fraction components (always unsigned):

numericQuantity('1 2/3', { verbose: true });
// {
//   value: 1.667,
//   input: '1 2/3',
//   whole: 1,
//   numerator: 2,
//   denominator: 3
// }

numericQuantity('½', { verbose: true });
// {
//   value: 0.5,
//   input: '½',
//   numerator: 1,
//   denominator: 2
// }
Copy

The verbose result object has the following shape:

interface NumericQuantityVerboseResult {
  value: number | bigint; // The parsed value (NaN if invalid)
  input: string; // Original input string
  currencyPrefix?: string; // Currency symbol(s) stripped from start
  currencySuffix?: string; // Currency symbol(s) stripped from end
  percentageSuffix?: boolean; // True if "%" was stripped
  trailingInvalid?: string; // Characters ignored (if allowTrailingInvalid)
  sign?: '-' | '+'; // Leading sign character, if present
  whole?: number; // Whole part of a mixed fraction (e.g. 1 from "1 2/3")
  numerator?: number; // Fraction numerator (e.g. 2 from "1 2/3")
  denominator?: number; // Fraction denominator (e.g. 3 from "1 2/3")
}
Copy

Additional Exports

isNumericQuantity(str, options?): boolean

Returns true if the string can be parsed as a valid number, false otherwise. Accepts the same options as numericQuantity.

import { isNumericQuantity } from 'numeric-quantity';

isNumericQuantity('1 1/2'); // true
isNumericQuantity('abc'); // false
isNumericQuantity('XII', { romanNumerals: true }); // true
isNumericQuantity('$100', { allowCurrency: true }); // true
isNumericQuantity('50%', { percentage: true }); // true
Copy

parseRomanNumerals(str): number

Parses a string of Roman numerals directly. Returns NaN for invalid input.

import { parseRomanNumerals } from 'numeric-quantity';

parseRomanNumerals('MCMXCIX'); // 1999
parseRomanNumerals('Ⅻ'); // 12
parseRomanNumerals('invalid'); // NaN
Copy