numeric-quantity

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

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>

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>

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

Coercion rules:

• Non-finite values (NaN, Infinity, -Infinity) are treated as false, i.e. no rounding.
• Negative values clamp to 0, i.e. round to a whole number.
• round does not apply to bigint results (see bigIntOnOverflow).
• When the percentage option divides by 100, round applies to the value as written, before the division (see Percentages).

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

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)

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

Large Numbers (bigIntOnOverflow)

When the parsed value exceeds Number.MAX_SAFE_INTEGER or is less than Number.MIN_SAFE_INTEGER, set bigIntOnOverflow: true to return a bigint instead.

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

This applies to any overflowing value, not just integers as written—decimals, fractions, mixed numbers, and exponents all participate. The value is evaluated exactly as a rational number and only rounded at the end.

const opts = { bigIntOnOverflow: true };
numericQuantity('9007199254740993.5', opts); // 9007199254740994n (half-up)
numericQuantity('-9007199254740993.5', opts); // -9007199254740994n (half away from zero)
numericQuantity('9007199254740993 1/2', opts); // 9007199254740994n
numericQuantity('9007199254740993e1', opts); // 90071992547409930n (exact, no rounding)

Notes:

• Fractional tails are unrecoverable anyway. Past Number.MAX_SAFE_INTEGER the gap between adjacent number values is 2, so no number can carry a fraction at that magnitude. Rounding to a bigint loses less than falling back to number would.

• round is not consulted. bigint has no fractional representation, so round: false does not disable the half-up rounding.

• Rounding can cause overflow. numericQuantity('9007199254740991.6', opts) is 9007199254740992n, even though the integer part as written is within range.

• percentage division is folded in exactly, as a factor of 100n in the denominator, so it is subject to the same single half-up rounding at the end.

  const opts = { bigIntOnOverflow: true, percentage: true };
  numericQuantity('900719925474099300%', opts); // 9007199254740993n (exact)
  numericQuantity('900719925474099399%', opts); // 9007199254740994n (rounded)

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

round applies to the value as written, before the division by 100, so the requested number of decimal places is not silently reduced:

numericQuantity('12.345%', { percentage: true, round: 3 }); // 0.12345, not 0.123
numericQuantity('1%', { percentage: true, round: 0 }); // 0.01
numericQuantity('1.0%', { percentage: true, round: 0 }); // 0.01
numericQuantity('1/1%', { percentage: true, round: 0 }); // 0.01

Roman numerals honor percentage as well:

numericQuantity('L%', { percentage: true, romanNumerals: true }); // 0.5

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

Currency symbols and the % suffix may appear in either order, but at most one % is stripped per parse:

const opts = { allowCurrency: true, percentage: true };
numericQuantity('50%€', opts); // 0.5
numericQuantity('100€%', opts); // 1
numericQuantity('100 € %', opts); // 1
numericQuantity('50%%', opts); // NaN
numericQuantity('50%€%', opts); // NaN

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: '
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
// }
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")
}
Infinity
Infinity is a valid result, not an error. Division by zero and overflowing exponents both produce it, and isNumericQuantity returns true for them.
numericQuantity('1/0'); // Infinity
numericQuantity('1e400'); // Infinity
isNumericQuantity('1/0'); // true
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
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
Constants and utilities
The internals used by the parser are also part of the public API and are safe to depend on:



Export
Description



normalizeDigits(str)
Converts non-ASCII decimal digits (70+ Unicode scripts) to ASCII 0–9


numericRegex
The core pattern matched against a fully normalized string


numericRegexWithTrailingInvalid
Same, but with a trailing capture group for allowTrailingInvalid


vulgarFractionToAsciiMap / vulgarFractionsRegex
Vulgar fraction characters (½, ⅔, …) and their ASCII equivalents


superSubDigitToAsciiMap / superSubDigitsRegex
Superscript/subscript digits (¹, ₂, …) and their ASCII equivalents


romanNumeralValues / romanNumeralRegex
Roman numeral values and the validation pattern


romanNumeralUnicodeToAsciiMap / romanNumeralUnicodeRegex
Unicode Roman numeral characters (Ⅻ, …) and their ASCII equivalents


defaultOptions
The fully-resolved default option set


,
//   percentageSuffix: true
// }

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

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

__CODE_BLOCK_16__

The verbose result object has the following shape:

__CODE_BLOCK_17__

__INLINE_CODE_82__

__INLINE_CODE_83__ is a valid result, not an error. Division by zero and overflowing exponents both produce it, and __INLINE_CODE_84__ returns __INLINE_CODE_85__ for them.

__CODE_BLOCK_18__

Additional Exports

__INLINE_CODE_86__

Returns __INLINE_CODE_87__ if the string can be parsed as a valid number, __INLINE_CODE_88__ otherwise. Accepts the same options as __INLINE_CODE_89__.

__CODE_BLOCK_19__

__INLINE_CODE_90__

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

__CODE_BLOCK_20__

Constants and utilities

The internals used by the parser are also part of the public API and are safe to depend on:

Export	Description
__INLINE_CODE_92__	Converts non-ASCII decimal digits (70+ Unicode scripts) to ASCII __INLINE_CODE_93__–__INLINE_CODE_94__
__INLINE_CODE_95__	The core pattern matched against a fully normalized string
__INLINE_CODE_96__	Same, but with a trailing capture group for __INLINE_CODE_97__
__INLINE_CODE_98__ / __INLINE_CODE_99__	Vulgar fraction characters (__INLINE_CODE_100__, __INLINE_CODE_101__, …) and their ASCII equivalents
__INLINE_CODE_102__ / __INLINE_CODE_103__	Superscript/subscript digits (__INLINE_CODE_104__, __INLINE_CODE_105__, …) and their ASCII equivalents
__INLINE_CODE_106__ / __INLINE_CODE_107__	Roman numeral values and the validation pattern
__INLINE_CODE_108__ / __INLINE_CODE_109__	Unicode Roman numeral characters (__INLINE_CODE_110__, …) and their ASCII equivalents
__INLINE_CODE_111__	The fully-resolved default option set