numeric-quantity 3.1.0 → 3.2.1

package/README.md

@@ -4,20 +4,16 @@
 [![downloads](https://img.shields.io/npm/dm/numeric-quantity.svg)](https://npm-stat.com/charts.html?package=numeric-quantity&from=2015-08-01)
 [![MIT License](https://img.shields.io/npm/l/numeric-quantity.svg)](https://opensource.org/licenses/MIT)
 
-Converts a string to a number, like an enhanced version of `parseFloat`.
+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](https://jakeboone02.github.io/numeric-quantity/)**
 
-Features:
+In addition to plain integers and decimals, `numeric-quantity` handles:
 
-- In addition to plain integers and decimals, `numeric-quantity` can parse numbers with comma or underscore separators (`'1,000'` or `'1_000'`), mixed numbers (`'1 2/3'`), vulgar fractions (`'1⅖'`), and the fraction slash character (`'1 2⁄3'`).
-- Supports non-ASCII decimal numeral systems including Arabic-Indic (`'٣'`), Devanagari (`'३'`), Bengali (`'৩'`), Thai (`'๓'`), Fullwidth (`'３'`), and 70+ other Unicode digit scripts.
-- To allow and ignore trailing invalid characters _à la_ `parseFloat`, pass `{ allowTrailingInvalid: true }` as the second argument.
-- To parse Roman numerals like `'MCCXIV'` or `'Ⅻ'`, pass `{ romanNumerals: true }` as the second argument or call `parseRomanNumerals` directly.
-- To parse numbers with European-style decimal comma (where `'1,0'` means `1`, not `10`), pass `{ decimalSeparator: ',' }` as the second argument.
-- To produce `bigint` values when the input represents an integer that would exceeds the boundaries of `number`, pass `{ bigIntOnOverflow: true }` as the second argument.
-- Results will be rounded to three decimal places by default. To avoid rounding, pass `{ round: false }` as the second argument. To round to a different number of decimal places, assign that number to the `round` option (`{ round: 5 }` will round to five decimal places).
-- Returns `NaN` if the provided string does not resemble a number.
+- **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](#roman-numerals-romannumerals) 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](https://www.npmjs.com/package/format-quantity)._
 
@@ -57,12 +53,172 @@ As UMD (all exports are properties of the global object `NumericQuantity`):
 
 ## Options
 
-| Option                 | Type              | Default | Description                                                                                          |
-| ---------------------- | ----------------- | ------- | ---------------------------------------------------------------------------------------------------- |
-| `round`                | `number \| false` | `3`     | Round the result to a certain number of decimal places. Must be greater than or equal to zero.       |
-| `allowTrailingInvalid` | `boolean`         | `false` | Allow and ignore trailing invalid characters _à la_ `parseFloat`.                                    |
-| `romanNumerals`        | `boolean`         | `false` | Attempt to parse Roman numerals if Arabic numeral parsing fails.                                     |
-| `bigIntOnOverflow`     | `boolean`         | `false` | Generates a `bigint` value if the string represents a valid integer too large for the `number` type. |
-| `decimalSeparator`     | `',' \| '.'`      | `"."`   | Specifies which character to treat as the decimal separator.                                         |
+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.
+
+```js
+numericQuantity('1/3'); // 0.333 (default: 3 decimal places)
+numericQuantity('1/3', { round: 5 }); // 0.33333
+numericQuantity('1/3', { round: false }); // 0.3333333333333333
+```
+
+### 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`.
+
+```js
+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.
+
+```js
+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: ','`.
+
+```js
+numericQuantity('1,5'); // 15 (comma treated as thousands separator)
+numericQuantity('1,5', { decimalSeparator: ',' }); // 1.5
+numericQuantity('1.000,50', { decimalSeparator: ',' }); // 1000.5
+```
+
+### 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.
+
+```js
+numericQuantity('9007199254740992'); // 9007199254740992 (loses precision)
+numericQuantity('9007199254740992', { bigIntOnOverflow: true }); // 9007199254740992n
+```
+
+### 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.
+
+```js
+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
+```
+
+### Currency Symbols (`allowCurrency`)
+
+Strip currency symbols from the start or end of the string by setting `allowCurrency: true`. Supports all Unicode currency symbols (`$`, `€`, `£`, `¥`, `₹`, `₽`, `₿`, `₩`, etc.).
+
+```js
+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
+```
+
+### 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.
+
+```js
+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'
+// }
+```
+
+For fraction and mixed-number inputs, the result also includes parsed fraction components (always unsigned):
+
+```js
+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:
+
+```ts
+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")
+}
+```
+
+## 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`.
+
+```js
+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.
+
+```js
+import { parseRomanNumerals } from 'numeric-quantity';
+
+parseRomanNumerals('MCMXCIX'); // 1999
+parseRomanNumerals('Ⅻ'); // 12
+parseRomanNumerals('invalid'); // NaN
+```
 
 [badge-npm]: https://img.shields.io/npm/v/numeric-quantity.svg?cacheSeconds=3600&logo=npm

package/dist/cjs/index.d.ts

@@ -0,0 +1 @@
+export * from './numeric-quantity.cjs.development.js';

package/dist/cjs/numeric-quantity.cjs.development.d.ts

@@ -0,0 +1,241 @@
+//#region src/types.d.ts
+interface NumericQuantityOptions {
+  /**
+  * Round the result to this many decimal places. Defaults to 3; must
+  * be greater than or equal to zero.
+  *
+  * @default 3
+  */
+  round?: number | false;
+  /**
+  * Allow and ignore trailing invalid characters _à la_ `parseFloat`.
+  *
+  * @default false
+  */
+  allowTrailingInvalid?: boolean;
+  /**
+  * Attempt to parse Roman numerals if Arabic numeral parsing fails.
+  *
+  * @default false
+  */
+  romanNumerals?: boolean;
+  /**
+  * Generates a `bigint` value if the string represents
+  * a valid integer too large for the `number` type.
+  */
+  bigIntOnOverflow?: boolean;
+  /**
+  * Specifies which character ("." or ",") to treat as the decimal separator.
+  *
+  * @default "."
+  */
+  decimalSeparator?: "," | ".";
+  /**
+  * Allow and strip currency symbols (Unicode `\p{Sc}` category) from the
+  * start and/or end of the string.
+  *
+  * @default false
+  */
+  allowCurrency?: boolean;
+  /**
+  * Parse percentage strings by stripping the `%` suffix.
+  * - `'decimal'` or `true`: `"50%"` → `0.5` (divide by 100)
+  * - `'number'`: `"50%"` → `50` (strip `%`, keep value)
+  * - `false` or omitted: `"50%"` → `NaN` (default behavior)
+  *
+  * @default false
+  */
+  percentage?: "decimal" | "number" | boolean;
+  /**
+  * Return a verbose result object with additional parsing metadata.
+  *
+  * @default false
+  */
+  verbose?: boolean;
+}
+/**
+* Resolves the return type of {@link numericQuantity} based on the options provided.
+*/
+type NumericQuantityReturnType<T extends NumericQuantityOptions | undefined = undefined> = T extends {
+  verbose: true;
+} ? NumericQuantityVerboseResult : T extends {
+  bigIntOnOverflow: true;
+} ? number | bigint : number;
+/**
+* Verbose result returned when `verbose: true` is set.
+*/
+interface NumericQuantityVerboseResult {
+  /** The parsed numeric value (NaN if invalid). */
+  value: number | bigint;
+  /** The original input string. */
+  input: string;
+  /** Currency symbol(s) stripped from the start, if any. */
+  currencyPrefix?: string;
+  /** Currency symbol(s) stripped from the end, if any. */
+  currencySuffix?: string;
+  /** True if a `%` suffix was stripped. */
+  percentageSuffix?: boolean;
+  /** Trailing invalid (usually non-numeric) characters detected in the input, if any. Populated even when `allowTrailingInvalid` is `false`. */
+  trailingInvalid?: string;
+  /** The leading sign character (`'-'` or `'+'`), if present. Omitted when no explicit sign was in the input. */
+  sign?: "-" | "+";
+  /** The whole-number part of a mixed fraction (e.g. `1` from `"1 2/3"`). Omitted for pure fractions, decimals, and integers. */
+  whole?: number;
+  /** The numerator of a fraction (e.g. `2` from `"1 2/3"`, or `1` from `"1/2"`). Always unsigned. */
+  numerator?: number;
+  /** The denominator of a fraction (e.g. `3` from `"1 2/3"`, or `2` from `"1/2"`). Always unsigned. */
+  denominator?: number;
+}
+/**
+* Unicode vulgar fraction code points.
+*/
+type VulgarFraction = "¼" | "½" | "¾" | "⅐" | "⅑" | "⅒" | "⅓" | "⅔" | "⅕" | "⅖" | "⅗" | "⅘" | "⅙" | "⅚" | "⅛" | "⅜" | "⅝" | "⅞" | "⅟";
+/**
+* Unicode superscript digit code points.
+*/
+type SuperscriptDigit = "⁰" | "¹" | "²" | "³" | "⁴" | "⁵" | "⁶" | "⁷" | "⁸" | "⁹";
+/**
+* Unicode subscript digit code points.
+*/
+type SubscriptDigit = "₀" | "₁" | "₂" | "₃" | "₄" | "₅" | "₆" | "₇" | "₈" | "₉";
+/**
+* Allowable Roman numeral characters (ASCII, uppercase only).
+*/
+type RomanNumeralAscii = "I" | "V" | "X" | "L" | "C" | "D" | "M";
+/**
+* Unicode Roman numeral code points (uppercase and lowercase,
+* representing 1-12, 50, 100, 500, and 1000).
+*/
+type RomanNumeralUnicode = "Ⅰ" | "Ⅱ" | "Ⅲ" | "Ⅳ" | "Ⅴ" | "Ⅵ" | "Ⅶ" | "Ⅷ" | "Ⅸ" | "Ⅹ" | "Ⅺ" | "Ⅻ" | "Ⅼ" | "Ⅽ" | "Ⅾ" | "Ⅿ" | "ⅰ" | "ⅱ" | "ⅲ" | "ⅳ" | "ⅴ" | "ⅵ" | "ⅶ" | "ⅷ" | "ⅸ" | "ⅹ" | "ⅺ" | "ⅻ" | "ⅼ" | "ⅽ" | "ⅾ" | "ⅿ";
+/**
+* Union of ASCII and Unicode Roman numeral characters/code points.
+*/
+type RomanNumeral = RomanNumeralAscii | RomanNumeralUnicode;
+//#endregion
+//#region src/constants.d.ts
+/**
+* Normalizes non-ASCII decimal digits to ASCII digits.
+* Converts characters from Unicode decimal digit blocks (e.g., Arabic-Indic,
+* Devanagari, Bengali) to their ASCII equivalents (0-9).
+*
+* All current Unicode \p{Nd} blocks are included in decimalDigitBlockStarts.
+*/
+declare const normalizeDigits: (str: string) => string;
+/**
+* Map of Unicode superscript and subscript digit code points to ASCII digits.
+*/
+declare const superSubDigitToAsciiMap: Record<SuperscriptDigit | SubscriptDigit, string>;
+/**
+* Captures Unicode superscript and subscript digits.
+*/
+declare const superSubDigitsRegex: RegExp;
+/**
+* Map of Unicode fraction code points to their ASCII equivalents.
+*/
+declare const vulgarFractionToAsciiMap: Record<VulgarFraction, `${number}/${number | ""}`>;
+/**
+* Captures the individual elements of a numeric string. Commas and underscores are allowed
+* as separators, as long as they appear between digits and are not consecutive.
+*
+* Capture groups:
+*
+* |  #  |    Description                                   |        Example(s)                                                   |
+* | --- | ------------------------------------------------ | ------------------------------------------------------------------- |
+* | `0` | entire string                                    | `"2 1/3"` from `"2 1/3"`                                            |
+* | `1` | sign (`-` or `+`)                                | `"-"` from `"-2 1/3"`                                               |
+* | `2` | whole number or numerator                        | `"2"` from `"2 1/3"`; `"1"` from `"1/3"`                            |
+* | `3` | entire fraction, decimal portion, or denominator | `" 1/3"` from `"2 1/3"`; `".33"` from `"2.33"`; `"/3"` from `"1/3"` |
+*
+* _Capture group 2 may include comma/underscore separators._
+*
+* @example
+*
+* ```ts
+* numericRegex.exec("1")     // [ "1",     "1", null,   null ]
+* numericRegex.exec("1.23")  // [ "1.23",  "1", ".23",  null ]
+* numericRegex.exec("1 2/3") // [ "1 2/3", "1", " 2/3", " 2" ]
+* numericRegex.exec("2/3")   // [ "2/3",   "2", "/3",   null ]
+* numericRegex.exec("2 / 3") // [ "2 / 3", "2", "/ 3",  null ]
+* ```
+*/
+declare const numericRegex: RegExp;
+/**
+* Same as {@link numericRegex}, but allows (and ignores) trailing invalid characters.
+* Capture group 7 contains the trailing invalid portion.
+*/
+declare const numericRegexWithTrailingInvalid: RegExp;
+/**
+* Captures any Unicode vulgar fractions.
+*/
+declare const vulgarFractionsRegex: RegExp;
+type RomanNumeralSequenceFragment = `${RomanNumeralAscii}` | `${RomanNumeralAscii}${RomanNumeralAscii}` | `${RomanNumeralAscii}${RomanNumeralAscii}${RomanNumeralAscii}` | `${RomanNumeralAscii}${RomanNumeralAscii}${RomanNumeralAscii}${RomanNumeralAscii}`;
+/**
+* Map of Roman numeral sequences to their decimal equivalents.
+*/
+declare const romanNumeralValues: { [k in RomanNumeralSequenceFragment]?: number };
+/**
+* Map of Unicode Roman numeral code points to their ASCII equivalents.
+*/
+declare const romanNumeralUnicodeToAsciiMap: Record<RomanNumeralUnicode, keyof typeof romanNumeralValues>;
+/**
+* Captures all Unicode Roman numeral code points.
+*/
+declare const romanNumeralUnicodeRegex: RegExp;
+/**
+* Captures a valid Roman numeral sequence.
+*
+* Capture groups:
+*
+* |  #  |  Description    |         Example          |
+* | --- | --------------- | ------------------------ |
+* | `0` |  Entire string  |  "MCCXIV" from "MCCXIV"  |
+* | `1` |  Thousands      |  "M" from "MCCXIV"       |
+* | `2` |  Hundreds       |  "CC" from "MCCXIV"      |
+* | `3` |  Tens           |  "X" from "MCCXIV"       |
+* | `4` |  Ones           |  "IV" from "MCCXIV"      |
+*
+* @example
+*
+* ```ts
+* romanNumeralRegex.exec("M")      // [      "M", "M",   "",  "",   "" ]
+* romanNumeralRegex.exec("XII")    // [    "XII",  "",   "", "X", "II" ]
+* romanNumeralRegex.exec("MCCXIV") // [ "MCCXIV", "M", "CC", "X", "IV" ]
+* ```
+*/
+declare const romanNumeralRegex: RegExp;
+/**
+* Default options for {@link numericQuantity}.
+*/
+declare const defaultOptions: Required<NumericQuantityOptions>;
+//#endregion
+//#region src/isNumericQuantity.d.ts
+/**
+* Checks if a string represents a valid numeric quantity.
+*
+* Returns `true` if the string can be parsed as a number, `false` otherwise.
+* Accepts the same options as `numericQuantity`.
+*/
+declare const isNumericQuantity: (quantity: string | number, options?: NumericQuantityOptions) => boolean;
+//#endregion
+//#region src/numericQuantity.d.ts
+/**
+* Converts a string to a number, like an enhanced version of `parseFloat`.
+*
+* The string can include mixed numbers, vulgar fractions, or Roman numerals.
+*/
+declare function numericQuantity(quantity: string | number): number;
+declare function numericQuantity<T extends NumericQuantityOptions>(quantity: string | number, options: T): NumericQuantityReturnType<T>;
+declare function numericQuantity(quantity: string | number, options?: NumericQuantityOptions): number;
+//#endregion
+//#region src/parseRomanNumerals.d.ts
+/**
+* Converts a string of Roman numerals to a number, like `parseInt`
+* for Roman numerals. Uses modern, strict rules (only 1 to 3999).
+*
+* The string can include ASCII representations of Roman numerals
+* or Unicode Roman numeral code points (`U+2160` through `U+217F`).
+*/
+declare const parseRomanNumerals: (romanNumerals: string) => number;
+//#endregion
+export { NumericQuantityOptions, NumericQuantityReturnType, NumericQuantityVerboseResult, RomanNumeral, RomanNumeralAscii, RomanNumeralUnicode, SubscriptDigit, SuperscriptDigit, VulgarFraction, defaultOptions, isNumericQuantity, normalizeDigits, numericQuantity, numericRegex, numericRegexWithTrailingInvalid, parseRomanNumerals, romanNumeralRegex, romanNumeralUnicodeRegex, romanNumeralUnicodeToAsciiMap, romanNumeralValues, superSubDigitToAsciiMap, superSubDigitsRegex, vulgarFractionToAsciiMap, vulgarFractionsRegex };
+//# sourceMappingURL=numeric-quantity.cjs.development.d.ts.map