Merge pull request #32 from jakeboone02:bigint

Add `bigint` support

Author: jakeboone02

CHANGELOG.md

@@ -9,6 +9,12 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 - N/A
 
+## [v2.1.0] - 2025-06-09
+
+### Added
+
+- `bigIntOnOverflow` option will produce a `bigint` value if the input represents a valid integer greater than `Number.MAX_SAFE_INTEGER` or less than `Number.MIN_SAFE_INTEGER`.
+
 ## [v2.0.1] - 2024-01-15
 
 ### Fixed
@@ -169,7 +175,9 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 <!-- Release comparison links -->
 
-[unreleased]: https://github.com/jakeboone02/numeric-quantity/compare/v2.0.0...HEAD
+[unreleased]: https://github.com/jakeboone02/numeric-quantity/compare/v2.1.0...HEAD
+[v2.1.0]: https://github.com/jakeboone02/numeric-quantity/compare/v2.0.1...v2.1.0
+[v2.0.1]: https://github.com/jakeboone02/numeric-quantity/compare/v2.0.0...v2.0.1
 [v2.0.0]: https://github.com/jakeboone02/numeric-quantity/compare/v1.0.4...v2.0.0
 [v1.0.4]: https://github.com/jakeboone02/numeric-quantity/compare/v1.0.3...v1.0.4
 [v1.0.3]: https://github.com/jakeboone02/numeric-quantity/compare/v1.0.2...v1.0.3

README.md

@@ -13,6 +13,7 @@ Features:
 - 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'`).
 - 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 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.
 

src/constants.ts

@@ -235,4 +235,5 @@ export const defaultOptions: Required<NumericQuantityOptions> = {
   round: 3,
   allowTrailingInvalid: false,
   romanNumerals: false,
+  bigIntOnOverflow: false,
 } as const;

src/dev.ts

@@ -22,7 +22,12 @@ for (const [title, tests] of Object.entries(numericQuantityTests)) {
 
   for (const [test, expect, opts] of tests) {
     const result = numericQuantity(test, opts);
-    const pass = isNaN(expect) ? isNaN(result) : expect === result;
+    const pass =
+      typeof expect === 'bigint'
+        ? expect === (result as unknown as bigint)
+        : isNaN(expect)
+          ? isNaN(result)
+          : expect === result;
     const testTR = document.createElement('tr');
     const tdCall = document.createElement('td');
     const tdResult = document.createElement('td');

src/index.test.ts

@@ -1,4 +1,4 @@
-import { describe, expect, test } from 'bun:test';
+import { describe, expect, Matchers, test } from 'bun:test';
 import { numericQuantity } from './numericQuantity';
 import { numericQuantityTests } from './numericQuantityTests';
 
@@ -15,7 +15,9 @@ for (const [title, tests] of Object.entries(numericQuantityTests)) {
           : ''
       } should evaluate to ${expected}`, () => {
         const expectation = expect(numericQuantity(arg, options));
-        if (isNaN(expected)) {
+        if (typeof expected === 'bigint') {
+          (expectation as unknown as Matchers<bigint>).toBe(expected);
+        } else if (isNaN(expected)) {
           expectation.toBeNaN();
         } else {
           expectation.toBe(expected);

src/numericQuantity.ts

@@ -15,10 +15,20 @@ const spaceThenSlashRegex = /^\s*\//;
  *
  * The string can include mixed numbers, vulgar fractions, or Roman numerals.
  */
-export const numericQuantity = (
+function numericQuantity(quantity: string | number): number;
+function numericQuantity(quantity: string | number): number;
+function numericQuantity(
+  quantity: string | number,
+  options: NumericQuantityOptions & { bigIntOnOverflow: true }
+): number | bigint;
+function numericQuantity(
+  quantity: string | number,
+  options?: NumericQuantityOptions
+): number;
+function numericQuantity(
   quantity: string | number,
   options: NumericQuantityOptions = defaultOptions
-): number => {
+) {
   if (typeof quantity === 'number' || typeof quantity === 'bigint') {
     return quantity;
   }
@@ -65,6 +75,16 @@ export const numericQuantity = (
   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);
   }
 
@@ -106,4 +126,6 @@ export const numericQuantity = (
   }
 
   return dash ? finalResult * -1 : finalResult;
-};
+}
+
+export { numericQuantity };

src/numericQuantityTests.ts

@@ -14,6 +14,11 @@ export const numericQuantityTests: Record<
   (
     | [string | number, number]
     | [string | number, number, NumericQuantityOptions]
+    | [
+        string | number,
+        number | bigint,
+        NumericQuantityOptions & { bigIntOnOverflow: true },
+      ]
   )[]
 > = {
   'Non-numeric stuff': [
@@ -216,6 +221,12 @@ export const numericQuantityTests: Record<
     ['1⁄2', 0.5],
     ['2 1⁄2', 2.5],
   ],
+  BigInts: [
+    ['9007199254740992', 9007199254740992n, { bigIntOnOverflow: true }],
+    ['-9007199254740992', -9007199254740992n, { bigIntOnOverflow: true }],
+    ['123', 123, { bigIntOnOverflow: true }],
+    ['-123', -123, { bigIntOnOverflow: true }],
+  ],
   'Roman numerals': (
     [
       // Invalid

src/types.ts

@@ -18,6 +18,11 @@ export interface NumericQuantityOptions {
    * @default false
    */
   romanNumerals?: boolean;
+  /**
+   * Generates a `bigint` value if the string represents
+   * a valid integer too large for the `number` type.
+   */
+  bigIntOnOverflow?: boolean;
 }
 
 /**

tsconfig.json

@@ -11,7 +11,8 @@
     "esModuleInterop": true,
     "noEmit": true,
     "skipLibCheck": true,
-    "lib": ["ES2015", "DOM"]
+    "lib": ["ES2015", "DOM"],
+    "target": "es2020"
   },
   "include": ["./*.ts", "./src"]
 }