numeric-quantity 2.1.0 → 3.1.0

package/dist/numeric-quantity.mjs

@@ -1,225 +1,348 @@
-// src/constants.ts
-var vulgarFractionToAsciiMap = {
-  "\xBC": "1/4",
-  "\xBD": "1/2",
-  "\xBE": "3/4",
-  "\u2150": "1/7",
-  "\u2151": "1/9",
-  "\u2152": "1/10",
-  "\u2153": "1/3",
-  "\u2154": "2/3",
-  "\u2155": "1/5",
-  "\u2156": "2/5",
-  "\u2157": "3/5",
-  "\u2158": "4/5",
-  "\u2159": "1/6",
-  "\u215A": "5/6",
-  "\u215B": "1/8",
-  "\u215C": "3/8",
-  "\u215D": "5/8",
-  "\u215E": "7/8",
-  "\u215F": "1/"
+//#region src/constants.ts
+/**
+* Unicode decimal digit block start code points.
+* Each block contains 10 contiguous digits (0-9).
+* This list covers all \p{Nd} (Decimal_Number) blocks through Unicode 17.0.
+* The drift test in index.test.ts validates completeness against the JS engine.
+*/
+const decimalDigitBlockStarts = [
+	48,
+	1632,
+	1776,
+	1984,
+	2406,
+	2534,
+	2662,
+	2790,
+	2918,
+	3046,
+	3174,
+	3302,
+	3430,
+	3558,
+	3664,
+	3792,
+	3872,
+	4160,
+	4240,
+	6112,
+	6160,
+	6470,
+	6608,
+	6784,
+	6800,
+	6992,
+	7088,
+	7232,
+	7248,
+	42528,
+	43216,
+	43264,
+	43472,
+	43504,
+	43600,
+	44016,
+	65296,
+	66720,
+	68912,
+	68928,
+	69734,
+	69872,
+	69942,
+	70096,
+	70384,
+	70736,
+	70864,
+	71248,
+	71360,
+	71376,
+	71386,
+	71472,
+	71904,
+	72016,
+	72688,
+	72784,
+	73040,
+	73120,
+	73184,
+	73552,
+	90416,
+	92768,
+	92864,
+	93008,
+	93552,
+	118e3,
+	120782,
+	120792,
+	120802,
+	120812,
+	120822,
+	123200,
+	123632,
+	124144,
+	124401,
+	125264,
+	130032
+];
+/**
+* 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.
+*/
+const normalizeDigits = (str) => str.replace(/\p{Nd}/gu, (ch) => {
+	const cp = ch.codePointAt(0);
+	if (cp <= 57) return ch;
+	let lo = 0;
+	let hi = decimalDigitBlockStarts.length - 1;
+	while (lo < hi) {
+		const mid = lo + hi + 1 >>> 1;
+		if (decimalDigitBlockStarts[mid] <= cp) lo = mid;
+		else hi = mid - 1;
+	}
+	return String(cp - decimalDigitBlockStarts[lo]);
+});
+/**
+* Map of Unicode fraction code points to their ASCII equivalents.
+*/
+const vulgarFractionToAsciiMap = {
+	"¼": "1/4",
+	"½": "1/2",
+	"¾": "3/4",
+	"⅐": "1/7",
+	"⅑": "1/9",
+	"⅒": "1/10",
+	"⅓": "1/3",
+	"⅔": "2/3",
+	"⅕": "1/5",
+	"⅖": "2/5",
+	"⅗": "3/5",
+	"⅘": "4/5",
+	"⅙": "1/6",
+	"⅚": "5/6",
+	"⅛": "1/8",
+	"⅜": "3/8",
+	"⅝": "5/8",
+	"⅞": "7/8",
+	"⅟": "1/"
 };
-var 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)?)?$/;
-var numericRegexWithTrailingInvalid = new RegExp(
-  numericRegex.source.replace(/\$$/, "(?:\\s*[^\\.\\d\\/].*)?")
-);
-var vulgarFractionsRegex = new RegExp(
-  `(${Object.keys(vulgarFractionToAsciiMap).join("|")})`
-);
-var romanNumeralValues = {
-  MMM: 3e3,
-  MM: 2e3,
-  M: 1e3,
-  CM: 900,
-  DCCC: 800,
-  DCC: 700,
-  DC: 600,
-  D: 500,
-  CD: 400,
-  CCC: 300,
-  CC: 200,
-  C: 100,
-  XC: 90,
-  LXXX: 80,
-  LXX: 70,
-  LX: 60,
-  L: 50,
-  XL: 40,
-  XXX: 30,
-  XX: 20,
-  XII: 12,
-  // only here for tests; not used in practice
-  XI: 11,
-  // only here for tests; not used in practice
-  X: 10,
-  IX: 9,
-  VIII: 8,
-  VII: 7,
-  VI: 6,
-  V: 5,
-  IV: 4,
-  III: 3,
-  II: 2,
-  I: 1
+/**
+* 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` | "negative" dash                                  | `"-"` 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 ]
+* ```
+*/
+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.
+*/
+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.
+*/
+const vulgarFractionsRegex = /([¼½¾⅐⅑⅒⅓⅔⅕⅖⅗⅘⅙⅚⅛⅜⅝⅞⅟}])/g;
+/**
+* Map of Roman numeral sequences to their decimal equivalents.
+*/
+const romanNumeralValues = {
+	MMM: 3e3,
+	MM: 2e3,
+	M: 1e3,
+	CM: 900,
+	DCCC: 800,
+	DCC: 700,
+	DC: 600,
+	D: 500,
+	CD: 400,
+	CCC: 300,
+	CC: 200,
+	C: 100,
+	XC: 90,
+	LXXX: 80,
+	LXX: 70,
+	LX: 60,
+	L: 50,
+	XL: 40,
+	XXX: 30,
+	XX: 20,
+	XII: 12,
+	XI: 11,
+	X: 10,
+	IX: 9,
+	VIII: 8,
+	VII: 7,
+	VI: 6,
+	V: 5,
+	IV: 4,
+	III: 3,
+	II: 2,
+	I: 1
 };
-var romanNumeralUnicodeToAsciiMap = {
-  // Roman Numeral One (U+2160)
-  "\u2160": "I",
-  // Roman Numeral Two (U+2161)
-  "\u2161": "II",
-  // Roman Numeral Three (U+2162)
-  "\u2162": "III",
-  // Roman Numeral Four (U+2163)
-  "\u2163": "IV",
-  // Roman Numeral Five (U+2164)
-  "\u2164": "V",
-  // Roman Numeral Six (U+2165)
-  "\u2165": "VI",
-  // Roman Numeral Seven (U+2166)
-  "\u2166": "VII",
-  // Roman Numeral Eight (U+2167)
-  "\u2167": "VIII",
-  // Roman Numeral Nine (U+2168)
-  "\u2168": "IX",
-  // Roman Numeral Ten (U+2169)
-  "\u2169": "X",
-  // Roman Numeral Eleven (U+216A)
-  "\u216A": "XI",
-  // Roman Numeral Twelve (U+216B)
-  "\u216B": "XII",
-  // Roman Numeral Fifty (U+216C)
-  "\u216C": "L",
-  // Roman Numeral One Hundred (U+216D)
-  "\u216D": "C",
-  // Roman Numeral Five Hundred (U+216E)
-  "\u216E": "D",
-  // Roman Numeral One Thousand (U+216F)
-  "\u216F": "M",
-  // Small Roman Numeral One (U+2170)
-  "\u2170": "I",
-  // Small Roman Numeral Two (U+2171)
-  "\u2171": "II",
-  // Small Roman Numeral Three (U+2172)
-  "\u2172": "III",
-  // Small Roman Numeral Four (U+2173)
-  "\u2173": "IV",
-  // Small Roman Numeral Five (U+2174)
-  "\u2174": "V",
-  // Small Roman Numeral Six (U+2175)
-  "\u2175": "VI",
-  // Small Roman Numeral Seven (U+2176)
-  "\u2176": "VII",
-  // Small Roman Numeral Eight (U+2177)
-  "\u2177": "VIII",
-  // Small Roman Numeral Nine (U+2178)
-  "\u2178": "IX",
-  // Small Roman Numeral Ten (U+2179)
-  "\u2179": "X",
-  // Small Roman Numeral Eleven (U+217A)
-  "\u217A": "XI",
-  // Small Roman Numeral Twelve (U+217B)
-  "\u217B": "XII",
-  // Small Roman Numeral Fifty (U+217C)
-  "\u217C": "L",
-  // Small Roman Numeral One Hundred (U+217D)
-  "\u217D": "C",
-  // Small Roman Numeral Five Hundred (U+217E)
-  "\u217E": "D",
-  // Small Roman Numeral One Thousand (U+217F)
-  "\u217F": "M"
+/**
+* Map of Unicode Roman numeral code points to their ASCII equivalents.
+*/
+const romanNumeralUnicodeToAsciiMap = {
+	Ⅰ: "I",
+	Ⅱ: "II",
+	Ⅲ: "III",
+	Ⅳ: "IV",
+	Ⅴ: "V",
+	Ⅵ: "VI",
+	Ⅶ: "VII",
+	Ⅷ: "VIII",
+	Ⅸ: "IX",
+	Ⅹ: "X",
+	Ⅺ: "XI",
+	Ⅻ: "XII",
+	Ⅼ: "L",
+	Ⅽ: "C",
+	Ⅾ: "D",
+	Ⅿ: "M",
+	ⅰ: "I",
+	ⅱ: "II",
+	ⅲ: "III",
+	ⅳ: "IV",
+	ⅴ: "V",
+	ⅵ: "VI",
+	ⅶ: "VII",
+	ⅷ: "VIII",
+	ⅸ: "IX",
+	ⅹ: "X",
+	ⅺ: "XI",
+	ⅻ: "XII",
+	ⅼ: "L",
+	ⅽ: "C",
+	ⅾ: "D",
+	ⅿ: "M"
 };
-var romanNumeralUnicodeRegex = new RegExp(
-  `(${Object.keys(romanNumeralUnicodeToAsciiMap).join("|")})`,
-  "gi"
-);
-var romanNumeralRegex = /^(?=[MDCLXVI])(M{0,3})(C[MD]|D?C{0,3})(X[CL]|L?X{0,3})(I[XV]|V?I{0,3})$/i;
-var defaultOptions = {
-  round: 3,
-  allowTrailingInvalid: false,
-  romanNumerals: false,
-  bigIntOnOverflow: false
+/**
+* Captures all Unicode Roman numeral code points.
+*/
+const romanNumeralUnicodeRegex = /([ⅠⅡⅢⅣⅤⅥⅦⅧⅨⅩⅪⅫⅬⅭⅮⅯⅰⅱⅲⅳⅴⅵⅶⅷⅸⅹⅺⅻⅼⅽⅾⅿ])/gi;
+/**
+* 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" ]
+* ```
+*/
+const romanNumeralRegex = /^(?=[MDCLXVI])(M{0,3})(C[MD]|D?C{0,3})(X[CL]|L?X{0,3})(I[XV]|V?I{0,3})$/i;
+/**
+* Default options for {@link numericQuantity}.
+*/
+const defaultOptions = {
+	round: 3,
+	allowTrailingInvalid: false,
+	romanNumerals: false,
+	bigIntOnOverflow: false,
+	decimalSeparator: "."
 };
 
-// src/parseRomanNumerals.ts
-var parseRomanNumerals = (romanNumerals) => {
-  const normalized = `${romanNumerals}`.replace(
-    romanNumeralUnicodeRegex,
-    (_m, rn) => romanNumeralUnicodeToAsciiMap[rn]
-  ).toUpperCase();
-  const regexResult = romanNumeralRegex.exec(normalized);
-  if (!regexResult) {
-    return NaN;
-  }
-  const [, thousands, hundreds, tens, ones] = regexResult;
-  return (romanNumeralValues[thousands] ?? 0) + (romanNumeralValues[hundreds] ?? 0) + (romanNumeralValues[tens] ?? 0) + (romanNumeralValues[ones] ?? 0);
+//#endregion
+//#region src/parseRomanNumerals.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`).
+*/
+const parseRomanNumerals = (romanNumerals) => {
+	const normalized = `${romanNumerals}`.replace(romanNumeralUnicodeRegex, (_m, rn) => romanNumeralUnicodeToAsciiMap[rn]).toUpperCase();
+	const regexResult = romanNumeralRegex.exec(normalized);
+	if (!regexResult) return NaN;
+	const [, thousands, hundreds, tens, ones] = regexResult;
+	return (romanNumeralValues[thousands] ?? 0) + (romanNumeralValues[hundreds] ?? 0) + (romanNumeralValues[tens] ?? 0) + (romanNumeralValues[ones] ?? 0);
 };
 
-// src/numericQuantity.ts
-var spaceThenSlashRegex = /^\s*\//;
+//#endregion
+//#region src/numericQuantity.ts
+const spaceThenSlashRegex = /^\s*\//;
 function numericQuantity(quantity, options = defaultOptions) {
-  if (typeof quantity === "number" || typeof quantity === "bigint") {
-    return quantity;
-  }
-  let finalResult = NaN;
-  const quantityAsString = `${quantity}`.replace(
-    vulgarFractionsRegex,
-    (_m, vf) => ` ${vulgarFractionToAsciiMap[vf]}`
-  ).replace("\u2044", "/").trim();
-  if (quantityAsString.length === 0) {
-    return NaN;
-  }
-  const opts = {
-    ...defaultOptions,
-    ...options
-  };
-  const regexResult = (opts.allowTrailingInvalid ? numericRegexWithTrailingInvalid : numericRegex).exec(quantityAsString);
-  if (!regexResult) {
-    return opts.romanNumerals ? parseRomanNumerals(quantityAsString) : NaN;
-  }
-  const [, dash, ng1temp, ng2temp] = regexResult;
-  const numberGroup1 = ng1temp.replace(/[,_]/g, "");
-  const numberGroup2 = ng2temp?.replace(/[,_]/g, "");
-  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;
-      }
-    }
-    finalResult = parseInt(numberGroup1);
-  }
-  if (!numberGroup2) {
-    return dash ? finalResult * -1 : 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}`);
-    finalResult = isNaN(roundingFactor) ? decimalValue : Math.round(decimalValue * roundingFactor) / roundingFactor;
-  } else if (spaceThenSlashRegex.test(numberGroup2)) {
-    const numerator = parseInt(numberGroup1);
-    const denominator = parseInt(numberGroup2.replace("/", ""));
-    finalResult = isNaN(roundingFactor) ? numerator / denominator : Math.round(numerator * roundingFactor / denominator) / roundingFactor;
-  } else {
-    const fractionArray = numberGroup2.split("/");
-    const [numerator, denominator] = fractionArray.map((v) => parseInt(v));
-    finalResult += isNaN(roundingFactor) ? numerator / denominator : Math.round(numerator * roundingFactor / denominator) / roundingFactor;
-  }
-  return dash ? finalResult * -1 : finalResult;
+	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
+	};
+	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;
+			const firstCommaIndex = quantityAsString.indexOf(",");
+			const secondCommaIndex = quantityAsString.indexOf(",", firstCommaIndex + 1);
+			const beforeSecondComma = quantityAsString.substring(0, secondCommaIndex).replaceAll(".", "_").replace(",", ".");
+			const afterSecondComma = quantityAsString.substring(secondCommaIndex + 1);
+			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 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;
+		}
+		finalResult = parseInt(numberGroup1);
+	}
+	if (!numberGroup2) return dash ? finalResult * -1 : 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}`);
+		finalResult = isNaN(roundingFactor) ? decimalValue : Math.round(decimalValue * roundingFactor) / roundingFactor;
+	} else if (spaceThenSlashRegex.test(numberGroup2)) {
+		const numerator = parseInt(numberGroup1);
+		const denominator = parseInt(numberGroup2.replace("/", ""));
+		finalResult = isNaN(roundingFactor) ? numerator / denominator : Math.round(numerator * roundingFactor / denominator) / roundingFactor;
+	} else {
+		const [numerator, denominator] = numberGroup2.split("/").map((v) => parseInt(v));
+		finalResult += isNaN(roundingFactor) ? numerator / denominator : Math.round(numerator * roundingFactor / denominator) / roundingFactor;
+	}
+	return dash ? finalResult * -1 : finalResult;
 }
-export {
-  defaultOptions,
-  numericQuantity,
-  numericRegex,
-  numericRegexWithTrailingInvalid,
-  parseRomanNumerals,
-  romanNumeralRegex,
-  romanNumeralUnicodeRegex,
-  romanNumeralUnicodeToAsciiMap,
-  romanNumeralValues,
-  vulgarFractionToAsciiMap,
-  vulgarFractionsRegex
-};
+
+//#endregion
+export { defaultOptions, normalizeDigits, numericQuantity, numericRegex, numericRegexWithTrailingInvalid, parseRomanNumerals, romanNumeralRegex, romanNumeralUnicodeRegex, romanNumeralUnicodeToAsciiMap, romanNumeralValues, vulgarFractionToAsciiMap, vulgarFractionsRegex };
 //# sourceMappingURL=numeric-quantity.mjs.map