numeric-quantity 3.1.0 → 3.2.0

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,225 @@
+//#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 = "¼" | "½" | "¾" | "⅐" | "⅑" | "⅒" | "⅓" | "⅔" | "⅕" | "⅖" | "⅗" | "⅘" | "⅙" | "⅚" | "⅛" | "⅜" | "⅝" | "⅞" | "⅟";
+/**
+* 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 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, VulgarFraction, defaultOptions, isNumericQuantity, normalizeDigits, numericQuantity, numericRegex, numericRegexWithTrailingInvalid, parseRomanNumerals, romanNumeralRegex, romanNumeralUnicodeRegex, romanNumeralUnicodeToAsciiMap, romanNumeralValues, vulgarFractionToAsciiMap, vulgarFractionsRegex };
+//# sourceMappingURL=numeric-quantity.cjs.development.d.ts.map

package/dist/cjs/numeric-quantity.cjs.development.js

@@ -138,7 +138,7 @@ const vulgarFractionToAsciiMap = {
 * |  #  |    Description                                   |        Example(s)                                                   |
 * | --- | ------------------------------------------------ | ------------------------------------------------------------------- |
 * | `0` | entire string                                    | `"2 1/3"` from `"2 1/3"`                                            |
-* | `1` | "negative" dash                                  | `"-"` 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"` |
 *
@@ -154,11 +154,12 @@ const vulgarFractionToAsciiMap = {
 * numericRegex.exec("2 / 3") // [ "2 / 3", "2", "/ 3",  null ]
 * ```
 */
-const numericRegex = /^(?=-?\s*\.\d|-?\s*\d)(-)?\s*((?:\d(?:[,_]\d|\d)*)*)(([eE][+-]?\d(?:[,_]\d|\d)*)?|\.\d(?:[,_]\d|\d)*([eE][+-]?\d(?:[,_]\d|\d)*)?|(\s+\d(?:[,_]\d|\d)*\s*)?\s*\/\s*\d(?:[,_]\d|\d)*)?$/;
+const numericRegex = /^(?=[-+]?\s*\.\d|[-+]?\s*\d)([-+])?\s*((?:\d(?:[,_]\d|\d)*)*)(([eE][+-]?\d(?:[,_]\d|\d)*)?|\.\d(?:[,_]\d|\d)*([eE][+-]?\d(?:[,_]\d|\d)*)?|(\s+\d(?:[,_]\d|\d)*\s*)?\s*\/\s*\d(?:[,_]\d|\d)*)?$/;
 /**
 * Same as {@link numericRegex}, but allows (and ignores) trailing invalid characters.
+* Capture group 7 contains the trailing invalid portion.
 */
-const numericRegexWithTrailingInvalid = /^(?=-?\s*\.\d|-?\s*\d)(-)?\s*((?:\d(?:[,_]\d|\d)*)*)(([eE][+-]?\d(?:[,_]\d|\d)*)?|\.\d(?:[,_]\d|\d)*([eE][+-]?\d(?:[,_]\d|\d)*)?|(\s+\d(?:[,_]\d|\d)*\s*)?\s*\/\s*\d(?:[,_]\d|\d)*)?(?:\s*[^.\d/].*)?/;
+const numericRegexWithTrailingInvalid = /^(?=[-+]?\s*\.\d|[-+]?\s*\d)([-+])?\s*((?:\d(?:[,_]\d|\d)*)*)(([eE][+-]?\d(?:[,_]\d|\d)*)?|\.\d(?:[,_]\d|\d)*([eE][+-]?\d(?:[,_]\d|\d)*)?|(\s+\d(?:[,_]\d|\d)*\s*)?\s*\/\s*\d(?:[,_]\d|\d)*)?(\s*[^.\d/].*)?/;
 /**
 * Captures any Unicode vulgar fractions.
 */
@@ -271,7 +272,10 @@ const defaultOptions = {
 	allowTrailingInvalid: false,
 	romanNumerals: false,
 	bigIntOnOverflow: false,
-	decimalSeparator: "."
+	decimalSeparator: ".",
+	allowCurrency: false,
+	percentage: false,
+	verbose: false
 };
 
 //#endregion
@@ -294,21 +298,68 @@ const parseRomanNumerals = (romanNumerals) => {
 //#endregion
 //#region src/numericQuantity.ts
 const spaceThenSlashRegex = /^\s*\//;
+const currencyPrefixRegex = /^([-+]?)\s*(\p{Sc}+)\s*/u;
+const currencySuffixRegex = /\s*(\p{Sc}+)$/u;
+const percentageSuffixRegex = /%$/;
 function numericQuantity(quantity, options = defaultOptions) {
-	if (typeof quantity === "number" || typeof quantity === "bigint") return quantity;
-	let finalResult = NaN;
-	const quantityAsString = normalizeDigits(`${quantity}`.replace(vulgarFractionsRegex, (_m, vf) => ` ${vulgarFractionToAsciiMap[vf]}`).replace("⁄", "/").trim());
-	if (quantityAsString.length === 0) return NaN;
 	const opts = {
 		...defaultOptions,
 		...options
 	};
+	const originalInput = typeof quantity === "string" ? quantity : `${quantity}`;
+	let currencyPrefix;
+	let currencySuffix;
+	let percentageSuffix;
+	let trailingInvalid;
+	let parsedSign;
+	let parsedWhole;
+	let parsedNumerator;
+	let parsedDenominator;
+	const buildVerboseResult = (value) => {
+		const result = {
+			value,
+			input: originalInput
+		};
+		if (currencyPrefix) result.currencyPrefix = currencyPrefix;
+		if (currencySuffix) result.currencySuffix = currencySuffix;
+		if (percentageSuffix) result.percentageSuffix = percentageSuffix;
+		if (trailingInvalid) result.trailingInvalid = trailingInvalid;
+		if (parsedSign) result.sign = parsedSign;
+		if (parsedWhole !== void 0) result.whole = parsedWhole;
+		if (parsedNumerator !== void 0) result.numerator = parsedNumerator;
+		if (parsedDenominator !== void 0) result.denominator = parsedDenominator;
+		return result;
+	};
+	const returnValue = (value) => opts.verbose ? buildVerboseResult(value) : value;
+	if (typeof quantity === "number" || typeof quantity === "bigint") return returnValue(quantity);
+	let finalResult = NaN;
+	let workingString = `${quantity}`;
+	if (opts.allowCurrency) {
+		const prefixMatch = currencyPrefixRegex.exec(workingString);
+		if (prefixMatch && prefixMatch[2]) {
+			currencyPrefix = prefixMatch[2];
+			workingString = (prefixMatch[1] || "") + workingString.slice(prefixMatch[0].length);
+		}
+	}
+	if (opts.allowCurrency) {
+		const suffixMatch = currencySuffixRegex.exec(workingString);
+		if (suffixMatch) {
+			currencySuffix = suffixMatch[1];
+			workingString = workingString.slice(0, -suffixMatch[0].length);
+		}
+	}
+	if (opts.percentage && percentageSuffixRegex.test(workingString)) {
+		percentageSuffix = true;
+		workingString = workingString.slice(0, -1);
+	}
+	const quantityAsString = normalizeDigits(workingString.replace(vulgarFractionsRegex, (_m, vf) => ` ${vulgarFractionToAsciiMap[vf]}`).replace("⁄", "/").trim());
+	if (quantityAsString.length === 0) return returnValue(NaN);
 	let normalizedString = quantityAsString;
 	if (opts.decimalSeparator === ",") {
 		const commaCount = (quantityAsString.match(/,/g) || []).length;
 		if (commaCount === 1) normalizedString = quantityAsString.replaceAll(".", "_").replace(",", ".");
 		else if (commaCount > 1) {
-			if (!opts.allowTrailingInvalid) return NaN;
+			if (!opts.allowTrailingInvalid) return returnValue(NaN);
 			const firstCommaIndex = quantityAsString.indexOf(",");
 			const secondCommaIndex = quantityAsString.indexOf(",", firstCommaIndex + 1);
 			const beforeSecondComma = quantityAsString.substring(0, secondCommaIndex).replaceAll(".", "_").replace(",", ".");
@@ -316,20 +367,30 @@ function numericQuantity(quantity, options = defaultOptions) {
 			normalizedString = opts.allowTrailingInvalid ? beforeSecondComma + "&" + afterSecondComma : beforeSecondComma;
 		} else normalizedString = quantityAsString.replaceAll(".", "_");
 	}
-	const regexResult = (opts.allowTrailingInvalid ? numericRegexWithTrailingInvalid : numericRegex).exec(normalizedString);
-	if (!regexResult) return opts.romanNumerals ? parseRomanNumerals(quantityAsString) : NaN;
-	const [, dash, ng1temp, ng2temp] = regexResult;
+	const regexResult = numericRegexWithTrailingInvalid.exec(normalizedString);
+	if (!regexResult) return returnValue(opts.romanNumerals ? parseRomanNumerals(quantityAsString) : NaN);
+	const rawTrailing = (regexResult[7] || normalizedString.slice(regexResult[0].length)).trim();
+	if (rawTrailing) {
+		trailingInvalid = rawTrailing;
+		if (!opts.allowTrailingInvalid) return returnValue(NaN);
+	}
+	const [, sign, ng1temp, ng2temp] = regexResult;
+	if (sign === "-" || sign === "+") parsedSign = sign;
 	const numberGroup1 = ng1temp.replaceAll(",", "").replaceAll("_", "");
 	const numberGroup2 = ng2temp === null || ng2temp === void 0 ? void 0 : ng2temp.replaceAll(",", "").replaceAll("_", "");
 	if (!numberGroup1 && numberGroup2 && numberGroup2.startsWith(".")) finalResult = 0;
 	else {
 		if (opts.bigIntOnOverflow) {
-			const asBigInt = dash ? BigInt(`-${numberGroup1}`) : BigInt(numberGroup1);
-			if (asBigInt > BigInt(Number.MAX_SAFE_INTEGER) || asBigInt < BigInt(Number.MIN_SAFE_INTEGER)) return asBigInt;
+			const asBigInt = sign === "-" ? BigInt(`-${numberGroup1}`) : BigInt(numberGroup1);
+			if (asBigInt > BigInt(Number.MAX_SAFE_INTEGER) || asBigInt < BigInt(Number.MIN_SAFE_INTEGER)) return returnValue(asBigInt);
 		}
 		finalResult = parseInt(numberGroup1);
 	}
-	if (!numberGroup2) return dash ? finalResult * -1 : finalResult;
+	if (!numberGroup2) {
+		finalResult = sign === "-" ? finalResult * -1 : finalResult;
+		if (percentageSuffix && opts.percentage !== "number") finalResult = finalResult / 100;
+		return returnValue(finalResult);
+	}
 	const roundingFactor = opts.round === false ? NaN : parseFloat(`1e${Math.floor(Math.max(0, opts.round))}`);
 	if (numberGroup2.startsWith(".") || numberGroup2.startsWith("e") || numberGroup2.startsWith("E")) {
 		const decimalValue = parseFloat(`${finalResult}${numberGroup2}`);
@@ -337,16 +398,40 @@ function numericQuantity(quantity, options = defaultOptions) {
 	} else if (spaceThenSlashRegex.test(numberGroup2)) {
 		const numerator = parseInt(numberGroup1);
 		const denominator = parseInt(numberGroup2.replace("/", ""));
+		parsedNumerator = numerator;
+		parsedDenominator = denominator;
 		finalResult = isNaN(roundingFactor) ? numerator / denominator : Math.round(numerator * roundingFactor / denominator) / roundingFactor;
 	} else {
 		const [numerator, denominator] = numberGroup2.split("/").map((v) => parseInt(v));
+		parsedWhole = finalResult;
+		parsedNumerator = numerator;
+		parsedDenominator = denominator;
 		finalResult += isNaN(roundingFactor) ? numerator / denominator : Math.round(numerator * roundingFactor / denominator) / roundingFactor;
 	}
-	return dash ? finalResult * -1 : finalResult;
+	finalResult = sign === "-" ? finalResult * -1 : finalResult;
+	if (percentageSuffix && opts.percentage !== "number") finalResult = isNaN(roundingFactor) ? finalResult / 100 : Math.round(finalResult / 100 * roundingFactor) / roundingFactor;
+	return returnValue(finalResult);
 }
 
+//#endregion
+//#region src/isNumericQuantity.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`.
+*/
+const isNumericQuantity = (quantity, options) => {
+	const result = numericQuantity(quantity, {
+		...options,
+		verbose: false
+	});
+	return typeof result === "bigint" || !isNaN(result);
+};
+
 //#endregion
 exports.defaultOptions = defaultOptions;
+exports.isNumericQuantity = isNumericQuantity;
 exports.normalizeDigits = normalizeDigits;
 exports.numericQuantity = numericQuantity;
 exports.numericRegex = numericRegex;