Touch up i18n features

Author: jakeboone02

CHANGELOG.md

@@ -12,7 +12,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - [#39] `isNumericQuantity(str, options?)` function for boolean validation without parsing.
 - [#39] `percentage` option to parse percentage strings (`"50%"` → `0.5` with `'decimal'`/`true`, or `50` with `'number'`).
 - [#39] `allowCurrency` option to strip Unicode currency symbols (`$`, `€`, `£`, `¥`, `₹`, `₿`, etc.) from prefix or suffix.
-- [#39] `verbose` option to return a detailed result object with `value`, `input`, `currencyPrefix`, `currencySuffix`, `percentageSuffix`, and `trailingInvalid` fields.
+- [#39] `verbose` option to return a detailed result object with `value`, `input`, `currencyPrefix`, `currencySuffix`, `percentageSuffix`, and `trailingInvalid` fields. `trailingInvalid` is populated whenever trailing non-numeric characters are detected, regardless of the `allowTrailingInvalid` setting.
 
 ## [v3.1.0] - 2026-02-11
 

src/index.test.ts

@@ -3,7 +3,6 @@ import { normalizeDigits } from './constants';
 import { isNumericQuantity } from './isNumericQuantity';
 import { numericQuantity } from './numericQuantity';
 import { numericQuantityTests } from './numericQuantityTests';
-import type { NumericQuantityVerboseResult } from './types';
 
 // Verify that decimalDigitBlockStarts covers every \p{Nd} codepoint.
 // If a future Unicode version adds a new Nd block, this test will fail.
@@ -86,7 +85,7 @@ describe('verbose output', () => {
     const result = numericQuantity('$100', {
       verbose: true,
       allowCurrency: true,
-    }) as NumericQuantityVerboseResult;
+    });
     expect(result.value).toBe(100);
     expect(result.currencyPrefix).toBe('$');
   });
@@ -95,7 +94,7 @@ describe('verbose output', () => {
     const result = numericQuantity('100€', {
       verbose: true,
       allowCurrency: true,
-    }) as NumericQuantityVerboseResult;
+    });
     expect(result.value).toBe(100);
     expect(result.currencySuffix).toBe('€');
   });
@@ -104,7 +103,7 @@ describe('verbose output', () => {
     const result = numericQuantity('50%', {
       verbose: true,
       percentage: 'decimal',
-    }) as NumericQuantityVerboseResult;
+    });
     expect(result.value).toBe(0.5);
     expect(result.percentageSuffix).toBe(true);
   });
@@ -113,17 +112,26 @@ describe('verbose output', () => {
     const result = numericQuantity('100abc', {
       verbose: true,
       allowTrailingInvalid: true,
-    }) as NumericQuantityVerboseResult;
+    });
     expect(result.value).toBe(100);
     expect(result.trailingInvalid).toBe('abc');
   });
 
+  test('includes trailingInvalid even when allowTrailingInvalid is false', () => {
+    const result = numericQuantity('100abc', {
+      verbose: true,
+    });
+    expect(result.value).toBeNaN();
+    expect(result.input).toBe('100abc');
+    expect(result.trailingInvalid).toBe('abc');
+  });
+
   test('handles combined currency and percentage', () => {
     const result = numericQuantity('$50%', {
       verbose: true,
       allowCurrency: true,
       percentage: 'decimal',
-    }) as NumericQuantityVerboseResult;
+    });
     expect(result.value).toBe(0.5);
     expect(result.currencyPrefix).toBe('$');
     expect(result.percentageSuffix).toBe(true);
@@ -132,7 +140,7 @@ describe('verbose output', () => {
   test('returns NaN value for invalid input', () => {
     const result = numericQuantity('invalid', {
       verbose: true,
-    }) as NumericQuantityVerboseResult;
+    });
     expect(result.value).toBeNaN();
     expect(result.input).toBe('invalid');
   });
@@ -141,4 +149,13 @@ describe('verbose output', () => {
     const result = numericQuantity(42, { verbose: true });
     expect(result).toEqual({ value: 42, input: '42' });
   });
+
+  test('works with bigIntOnOverflow', () => {
+    const result = numericQuantity('9007199254740992', {
+      verbose: true,
+      bigIntOnOverflow: true,
+    });
+    expect(result.value).toBe(9007199254740992n);
+    expect(result.input).toBe('9007199254740992');
+  });
 });

src/isNumericQuantity.ts

@@ -11,6 +11,6 @@ export const isNumericQuantity = (
   quantity: string | number,
   options?: NumericQuantityOptions
 ): boolean => {
-  const result = numericQuantity(quantity, options);
+  const result = numericQuantity(quantity, { ...options, verbose: false });
   return typeof result === 'bigint' || !isNaN(result);
 };

src/numericQuantity.ts

@@ -1,14 +1,14 @@
 import {
   defaultOptions,
   normalizeDigits,
-  numericRegex,
   numericRegexWithTrailingInvalid,
   vulgarFractionToAsciiMap,
   vulgarFractionsRegex,
 } from './constants';
 import { parseRomanNumerals } from './parseRomanNumerals';
 import type {
   NumericQuantityOptions,
+  NumericQuantityReturnType,
   NumericQuantityVerboseResult,
 } from './types';
 
@@ -23,14 +23,10 @@ const percentageSuffixRegex = /%$/;
  * The string can include mixed numbers, vulgar fractions, or Roman numerals.
  */
 function numericQuantity(quantity: string | number): number;
-function numericQuantity(
-  quantity: string | number,
-  options: NumericQuantityOptions & { verbose: true }
-): NumericQuantityVerboseResult;
-function numericQuantity(
+function numericQuantity<T extends NumericQuantityOptions>(
   quantity: string | number,
-  options: NumericQuantityOptions & { bigIntOnOverflow: true }
-): number | bigint;
+  options: T
+): NumericQuantityReturnType<T>;
 function numericQuantity(
   quantity: string | number,
   options?: NumericQuantityOptions
@@ -155,27 +151,25 @@ function numericQuantity(
     }
   }
 
-  const regexResult = (
-    opts.allowTrailingInvalid ? numericRegexWithTrailingInvalid : numericRegex
-  ).exec(normalizedString);
+  const regexResult = numericRegexWithTrailingInvalid.exec(normalizedString);
 
   // If the Arabic numeral regex fails, try Roman numerals
   if (!regexResult) {
-    const romanResult = opts.romanNumerals
-      ? parseRomanNumerals(quantityAsString)
-      : NaN;
-    if (!isNaN(romanResult) && percentageSuffix) {
-      const percentageValue =
-        opts.percentage === 'number' ? romanResult : romanResult / 100;
-      return returnValue(percentageValue);
-    }
-    return returnValue(romanResult);
+    return returnValue(
+      opts.romanNumerals ? parseRomanNumerals(quantityAsString) : NaN);
   }
 
-  // Capture trailing invalid characters if present (group 7 of the regex)
-  if (opts.allowTrailingInvalid && regexResult[7]) {
-    trailingInvalid = regexResult[7].trim();
-    if (!trailingInvalid) trailingInvalid = undefined;
+  // Capture trailing invalid characters: group 7 catches chars starting with
+  // [^.\d/], but the regex (which lacks a $ anchor) may also leave unconsumed
+  // input starting with ".", "/", or digits (e.g. "0.1.2" or "1/").
+  const rawTrailing = (
+    regexResult[7] || normalizedString.slice(regexResult[0].length)
+  ).trim();
+  if (rawTrailing) {
+    trailingInvalid = rawTrailing;
+    if (!opts.allowTrailingInvalid) {
+      return returnValue(NaN);
+    }
   }
 
   const [, dash, ng1temp, ng2temp] = regexResult;

src/numericQuantityTests.ts

@@ -392,8 +392,8 @@ export const numericQuantityTests: Record<
     ['0.5%', 0.5, { percentage: 'number' }],
     ['1/2%', 0.5, { percentage: 'number' }],
     ['-50%', -50, { percentage: 'number' }],
-    // Roman numerals with percentage
-    ['L%', 0.5, { percentage: 'decimal', romanNumerals: true }],
+    // Roman numerals with percentage (percentage never affects Roman numeral output)
+    ['L%', 50, { percentage: 'decimal', romanNumerals: true }],
     ['L%', 50, { percentage: 'number', romanNumerals: true }],
     // Without % symbol - should work normally
     ['50', 50, { percentage: 'decimal' }],

src/types.ts

@@ -55,6 +55,17 @@ export interface NumericQuantityOptions {
   verbose?: boolean;
 }
 
+/**
+ * Resolves the return type of {@link numericQuantity} based on the options provided.
+ */
+export 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.
  */
@@ -69,7 +80,7 @@ export interface NumericQuantityVerboseResult {
   currencySuffix?: string;
   /** True if a `%` suffix was stripped. */
   percentageSuffix?: boolean;
-  /** Characters ignored due to `allowTrailingInvalid`, if any. */
+  /** Trailing invalid (usually non-numeric) characters detected in the input, if any. Populated even when `allowTrailingInvalid` is `false`. */
   trailingInvalid?: string;
 }