format-quantity 3.1.0 → 3.2.0

package/README.md

@@ -4,16 +4,17 @@
 [![downloads](https://img.shields.io/npm/dm/format-quantity.svg)](https://npm-stat.com/charts.html?package=format-quantity&from=2015-08-01)
 [![MIT License](https://img.shields.io/npm/l/format-quantity.svg)](https://opensource.org/licenses/MIT)
 
-Formats a number (or string that appears to be a number) as one would see it written in imperial measurements, e.g. "1 1/2" instead of "1.5".
+Formats a `number` (or `bigint`, or `string` that appears to be a number) as one would see it written in imperial measurements, e.g. "1 1/2" instead of "1.5".
 
 **[Full documentation](https://jakeboone02.github.io/format-quantity/)**
 
 Features:
 
 - To use vulgar fraction characters like "⅞", pass `true` as the second argument. Other options like Roman numerals are described below.
-- String inputs are parsed with [`numeric-quantity`](https://www.npmjs.com/package/numeric-quantity), so mixed numbers (`"1 1/2"`), vulgar fractions (`"½"`), bare fractions (`"1/3"`), and comma/underscore-separated numbers (`"1,000"`) are all accepted in addition to plain decimal strings.
-- The return value will be `null` if the first argument is not a recognized numeric format.
-- The return value will be an empty string (`""`) if the first argument is `0` or `"0"`, which fits the primary use case of formatting recipe ingredient quantities.
+- String inputs are parsed with [`numeric-quantity`](https://www.npmjs.com/package/numeric-quantity), so mixed numbers (`"1 1/2"`), vulgar fractions (`"½"`), bare fractions (`"1/3"`), and comma- or underscore-separated numbers (`"1,000"`) are all accepted in addition to plain decimal strings.
+- The return value will be `null` if the first argument is not a `number`, `string`, or `bigint`, or is a string with no recognizable numeric portion at the start. Trailing junk is tolerated, so `formatQuantity("1.5 cups")` returns `"1 1/2"`.
+- The return value will be an empty string (`""`) if the first argument is `0`, `0n`, or `"0"`, which fits the primary use case of formatting recipe ingredient quantities.
+- Values too large or too small for positional notation are returned in JavaScript's exponential form (e.g. `formatQuantity(1e21)` is `"1e+21"`), and `Infinity`/`-Infinity` are stringified as-is. `bigint` inputs are never exponential; they stringify in full.
 
 > _For the inverse operation—converting a string to a `number`—check out [numeric-quantity](https://www.npmjs.com/package/numeric-quantity). It handles mixed numbers, vulgar fractions, comma/underscore separators, and Roman numerals._
 >
@@ -59,7 +60,7 @@ The second parameter to `formatQuantity` can be a `boolean` value or an options
 ### `vulgarFractions`
 
 | Type      | Default |
-| --------- | ------: |
+| --------- | ------- |
 | `boolean` | `false` |
 
 Returns vulgar fractions when appropriate. This option has the same effect as passing a plain `boolean` value as the second parameter.
@@ -75,7 +76,7 @@ Note: `formatQuantity` supports sixteenths, but no vulgar fraction characters ex
 ### `fractionSlash`
 
 | Type      | Default |
-| --------- | ------: |
+| --------- | ------- |
 | `boolean` | `false` |
 
 Uses the [fraction slash character](<https://en.wikipedia.org/wiki/Slash_(punctuation)#Fractions>) (`"\u2044"`) to separate the numerator and denominator instead of the regular "solidus" slash (`"\u002f"`), with Unicode superscript numerator and subscript denominator digits. This option is ignored if the `vulgarFractions` option is also `true`.
@@ -88,8 +89,8 @@ formatQuantity(3.875, { fractionSlash: true, vulgarFractions: true }); // "3⅞"
 ### `separator`
 
 | Type     | Default |
-| -------- | ------: |
-| `string` |     N/A |
+| -------- | ------- |
+| `string` | N/A     |
 
 Overrides the string placed between the whole number and the fraction. When not specified, the default is `" "` (a space) for ASCII and fraction-slash fractions, and `""` (no space) for vulgar fractions. Common alternatives include a hyphen (`"-"`) and a no-break space (`"\u00a0"`).
 
@@ -101,21 +102,61 @@ formatQuantity(1.5, { separator: '\u00a0' }); // "1\u00a01/2" (no-break space)
 
 ### `tolerance`
 
-| Type     |  Default |
-| -------- | -------: |
-| `number` | `0.0075` |
+| Type              |  Default |
+| ----------------- | -------: |
+| `number \| false` | `0.0075` |
 
 This option determines how close the decimal portion of a number has to be to the actual quotient of a fraction to be considered a match. For example, consider the fraction 1⁄3: $1 \div 3 = 0.\overline{333}$, repeating forever. The number `0.333` (exactly 333 thousandths) is not equivalent to 1⁄3, but it's very close. So even though $0.333 \neq 1 \div 3$, both `formatQuantity(0.333)` and `formatQuantity(1/3)` will return `"1/3"`.
 
-A lower tolerance increases the likelihood that `formatQuantity` will return a decimal representation instead of a fraction or mixed number since the matching algorithm will be stricter. An higher tolerance increases the likelihood that `formatQuantity` will return a fraction or mixed number, but at the risk of arbitrarily matching an incorrect fraction simply because it gets evaluated first (the export `fractionDecimalMatches` defines the order of evaluation).
+The window is centered on the exact quotient and is checked against every candidate fraction; when more than one is within the window, the **closest** one wins regardless of evaluation order.
+
+A lower tolerance increases the likelihood that `formatQuantity` will return a decimal representation instead of a fraction or mixed number since the matching algorithm will be stricter. A higher tolerance increases the likelihood that `formatQuantity` will return a fraction or mixed number, but at the risk of matching a fraction that is only loosely related to the input.
 
 ```js
 // Low tolerance - returns a decimal since 0.333 is not close enough to 1/3
 formatQuantity(0.333, { tolerance: 0.00001 }); // "0.333"
-// High tolerance - matches "1/3" even for 3/10
-formatQuantity(0.3, { tolerance: 0.1 }); // "1/3"
-// *Way* too high tolerance - incorrect result because thirds get evaluated before halves
-formatQuantity(0.5, { tolerance: 0.5 }); // "1/3"
+// High tolerance - 0.3 is within 0.1 of both 5/16 and 1/3, and 5/16 is closer
+formatQuantity(0.3, { tolerance: 0.1 }); // "5/16"
+```
+
+Two values are special:
+
+- `0` means **only exact quotients match**. Anything else falls through to its decimal representation.
+- `false` **disables fraction matching entirely**, so every non-integer is returned as a decimal.
+
+```js
+formatQuantity(1.5, { tolerance: 0 }); // "1 1/2" (0.5 is exactly 1 ÷ 2)
+formatQuantity(1.51, { tolerance: 0 }); // "1.51"
+formatQuantity(1.5, { tolerance: false }); // "1.5"
+```
+
+Any other value—a negative number, `NaN`, a numeric string, `null`, `undefined`—is ignored and the default is used instead.
+
+### `zeroFormat`
+
+| Type     | Default |
+| -------- | ------- |
+| `string` | `""`    |
+
+Specify the string to return when the input numerically evaluates to zero (`0`).
+
+```js
+formatQuantity(0, { zeroFormat: '' }); // "" (default)
+formatQuantity(0, { zeroFormat: '0' }); // "0"
+formatQuantity(0, { zeroFormat: 'N/A' }); // "N/A"
+```
+
+### `allowTrailingInvalid`
+
+| Type      | Default |
+| --------- | ------- |
+| `boolean` | `true`  |
+
+If input is a `string`, ignore trailing non-numeric input (à la `parseFloat`). Set to `false` for strict parsing — any invalid characters will result in `null`.
+
+```js
+formatQuantity('123abc', { allowTrailingInvalid: true }); // "123"
+formatQuantity('123abc', { allowTrailingInvalid: false }); // null
 ```
 
 ### `romanNumerals`
@@ -124,13 +165,17 @@ formatQuantity(0.5, { tolerance: 0.5 }); // "1/3"
 | --------- | ------: |
 | `boolean` | `false` |
 
-Coerces the number into an integer using `Math.floor`, then formats the value as Roman numerals. The algorithm uses strict, modern rules, so the number must be between 1 and 3999 (inclusive).
+Coerces the number into an integer using `Math.floor`, then formats the value as Roman numerals. The algorithm uses strict, modern rules, so the number must be between `1` and `3999` inclusive (or between `1n` and `3999n` — `bigint` is also allowed). Values outside that range return `null`.
 
 When this option is `true`, all other options are ignored.
 
 ```js
 formatQuantity(1214, { romanNumerals: true }); // "MCCXIV"
 formatQuantity(12.14, { romanNumerals: true, vulgarFractions: true }); // "XII"
+formatQuantity(4000, { romanNumerals: true }); // null
+formatQuantity(-1, { romanNumerals: true }); // null
 ```
 
-[badge-npm]: https://img.shields.io/npm/v/numeric-quantity.svg?cacheSeconds=3600&logo=npm
+> _`formatQuantity(0, …)` returns `""` (or the configured `zeroFormat`) regardless of this option, since the zero rule is applied before options are processed._
+
+[badge-npm]: https://img.shields.io/npm/v/format-quantity.svg?cacheSeconds=3600&logo=npm

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

@@ -1,107 +1,131 @@
 //#region src/types.d.ts
 interface FormatQuantityOptions {
   /**
-  * Output vulgar fractions, like "½" instead of "1/2", when appropriate.
-  * Overrides the `fractionSlash` option.
-  */
+   * Output vulgar fractions, like "½" instead of "1/2", when appropriate.
+   * Overrides the `fractionSlash` option.
+   *
+   * @default false
+   */
   vulgarFractions?: boolean;
   /**
-  * Amount by which a number can deviate from the calculated quotient to be
-  * considered a match. For example, 0.66 is close enough to 2 ÷ 3 (which
-  * is 0.66666... repeating) to be considered equivalent so the function
-  * will return "2/3". The smaller this number, the higher the likelihood that
-  * the function will return a decimal instead of a fraction or mixed number.
-  *
-  * @default 0.0075
-  */
-  tolerance?: number;
+   * Amount by which a number can deviate from the calculated quotient to be
+   * considered a match. For example, 0.66 is close enough to 2 ÷ 3 (which
+   * is 0.66666... repeating) to be considered equivalent so the function
+   * will return "2/3". The smaller this number, the higher the likelihood that
+   * the function will return a decimal instead of a fraction or mixed number.
+   *
+   * `0` means only exact quotients match. `false` disables fraction matching
+   * entirely, so decimal values are always returned as decimals.
+   *
+   * Any other value—negative, non-numeric, `NaN`, `null`, `undefined`—resolves
+   * to the default.
+   *
+   * @default 0.0075
+   */
+  tolerance?: number | false;
   /**
-  * Output the fraction slash character (⁄) instead of the "solidus"
-  * slash (/) for fractions. Results appear like "1⁄2" instead of "1/2".
-  * Overridden by the `vulgarFractions` option.
-  */
+   * Output the fraction slash character (⁄) instead of the "solidus"
+   * slash (/) for fractions. Results appear like "1⁄2" instead of "1/2".
+   * Overridden by the `vulgarFractions` option.
+   *
+   * @default false
+   */
   fractionSlash?: boolean;
   /**
-  * Output in Roman numerals. Provided value must be between 1 and 3999, inclusive.
-  * Decimal values will be ignored (`Math.floor` is used to remove them). Overrides
-  * all other options.
-  */
+   * Output in Roman numerals. Provided value must be between 1 and 3999, inclusive.
+   * Decimal values will be ignored (`Math.floor` is used to remove them). Overrides
+   * all other options.
+   *
+   * @default false
+   */
   romanNumerals?: boolean;
   /**
-  * String to place between the whole number and fraction parts. When not specified,
-  * defaults to `" "` for ASCII and fraction-slash fractions, and `""` for vulgar
-  * fractions (preserving the standard typographic convention of no space before
-  * vulgar fraction characters).
-  */
+   * String to place between the whole number and fraction parts. When not specified,
+   * defaults to `" "` for ASCII and fraction-slash fractions, and `""` for vulgar
+   * fractions (preserving the standard typographic convention of no space before
+   * vulgar fraction characters).
+   */
   separator?: string;
+  /**
+   * String to return when the input evaluates numerically to zero.
+   *
+   * @default "" (empty string)
+   */
+  zeroFormat?: string;
+  /**
+   * If `qty` is a string, allow trailing invalid characters after the numeric portion.
+   *
+   * @default true
+   */
+  allowTrailingInvalid?: boolean;
 }
 /**
-* {@link FormatQuantityOptions} with all properties resolved to their
-* default values, except {@link FormatQuantityOptions.separator | separator}
-* which remains optional so that unset vs explicitly-set can be distinguished.
-*/
+ * {@link FormatQuantityOptions} with all properties resolved to their
+ * default values, except {@link FormatQuantityOptions.separator | separator}
+ * which remains optional so that unset vs explicitly-set can be distinguished.
+ */
 type ResolvedFormatQuantityOptions = Required<Omit<FormatQuantityOptions, "separator">> & Pick<FormatQuantityOptions, "separator">;
 /**
-* Function signature of {@link formatQuantity}.
-*/
+ * Function signature of {@link formatQuantity}.
+ */
 interface FormatQuantity {
-  (qty: string | number, options?: boolean | FormatQuantityOptions): string | null;
+  (qty: string | number | bigint, options?: boolean | FormatQuantityOptions): string | null;
 }
 /** Any numeric character. */
 type Digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9";
 /** Any numeric character except '0'. */
 type NonZeroDigit = Exclude<Digit, "0">;
 /**
-* Fraction string with either one or two numeric characters in both the
-* numerator and denominator (but not two characters in the numerator while
-* the denominator only has one).
-*/
+ * Fraction string with either one or two numeric characters in both the
+ * numerator and denominator (but not two characters in the numerator while
+ * the denominator only has one).
+ */
 type SimpleFraction = `${NonZeroDigit}/${NonZeroDigit}` | `${NonZeroDigit}/${NonZeroDigit}${Digit}` | `${NonZeroDigit}${Digit}/${NonZeroDigit}${Digit}`;
 /**
-* Odd numerator sixteenth fraction strings.
-*/
+ * Odd numerator sixteenth fraction strings.
+ */
 type Sixteenth = `${"1" | "3" | "5" | "7" | "9" | "11" | "13" | "15"}/16`;
 /**
-* Unicode vulgar fraction code points.
-*/
+ * Unicode vulgar fraction code points.
+ */
 type VulgarFraction = "¼" | "½" | "¾" | "⅐" | "⅑" | "⅒" | "⅓" | "⅔" | "⅕" | "⅖" | "⅗" | "⅘" | "⅙" | "⅚" | "⅛" | "⅜" | "⅝" | "⅞";
-/** @hidden */
-type FormatQuantityTests = Record<string, ([Parameters<FormatQuantity>[0], ReturnType<FormatQuantity>] | [Parameters<FormatQuantity>[0], ReturnType<FormatQuantity>, Parameters<FormatQuantity>[1]])[]>;
 //#endregion
 //#region src/constants.d.ts
 /**
-* Default tolerance used by {@link formatQuantity} when determining if a number
-* is close enough to a fraction value to be considered equivalent.
-*/
+ * Default tolerance used by {@link formatQuantity} when determining if a number
+ * is close enough to a fraction value to be considered equivalent.
+ */
 declare const defaultTolerance: 0.0075;
 /**
-* Default options for {@link formatQuantity}.
-*/
-declare const defaultOptions: ResolvedFormatQuantityOptions;
+ * Default options for {@link formatQuantity}.
+ */
+declare const defaultOptions: Readonly<ResolvedFormatQuantityOptions>;
 /**
-* Map of vulgar fractions to their traditional ASCII equivalents.
-*/
-declare const vulgarToAsciiMap: Record<VulgarFraction, SimpleFraction>;
+ * Map of vulgar fractions to their traditional ASCII equivalents.
+ */
+declare const vulgarToAsciiMap: Readonly<Record<VulgarFraction, SimpleFraction>>;
 /**
-* Map of "close enough" decimal values to the {@link VulgarFraction} or
-* {@link Sixteenth} fraction string matches.
-*/
-declare const fractionDecimalMatches: [number, VulgarFraction | Sixteenth][];
+ * Map of "close enough" values to the {@link VulgarFraction} or {@link Sixteenth} fraction
+ * string matches. The value +/- the `tolerance` option (or {@link defaultTolerance} if not
+ * specified) is considered close enough to match the fraction.
+ */
+declare const fractionDecimalMatches: readonly (readonly [number, VulgarFraction | Sixteenth])[];
 //#endregion
 //#region src/formatQuantity.d.ts
 /**
-* Formats a number as Roman numerals. The number must be between
-* 1 and 3999, inclusive.
-*/
-declare const formatRomanNumerals: (qty: number) => string | null;
+ * Formats a number or bigint as Roman numerals. The number must be between
+ * 1 and 3999, inclusive; any other value—including non-numbers,
+ * `NaN`, and non-finite numbers—yields `null`.
+ */
+declare const formatRomanNumerals: (quantity: number | bigint) => string | null;
 /**
-* Formats a number (or string that appears to be a number)
-* as one would see it written in imperial measurements, e.g.
-* "1 1/2" instead of "1.5". To use vulgar fraction characters
-* like "½", pass `true` as the second argument. For other options
-* see {@link FormatQuantityOptions}.
-*/
+ * Formats a number (or string that appears to be a number)
+ * as one would see it written in imperial measurements, e.g.
+ * "1 1/2" instead of "1.5". To use vulgar fraction characters
+ * like "½", pass `true` as the second argument. For other options
+ * see {@link FormatQuantityOptions}.
+ */
 declare const formatQuantity: FormatQuantity;
 //#endregion
-export { Digit, FormatQuantity, FormatQuantityOptions, FormatQuantityTests, NonZeroDigit, ResolvedFormatQuantityOptions, SimpleFraction, Sixteenth, VulgarFraction, defaultOptions, defaultTolerance, formatQuantity, formatRomanNumerals, fractionDecimalMatches, vulgarToAsciiMap };
+export { Digit, FormatQuantity, FormatQuantityOptions, NonZeroDigit, ResolvedFormatQuantityOptions, SimpleFraction, Sixteenth, VulgarFraction, defaultOptions, defaultTolerance, formatQuantity, formatRomanNumerals, fractionDecimalMatches, vulgarToAsciiMap };
 //# sourceMappingURL=format-quantity.cjs.development.d.ts.map

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

@@ -1,6 +1,5 @@
-Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 let numeric_quantity = require("numeric-quantity");
-
 //#region src/constants.ts
 /**
 * Default tolerance used by {@link formatQuantity} when determining if a number
@@ -10,16 +9,18 @@ const defaultTolerance = .0075;
 /**
 * Default options for {@link formatQuantity}.
 */
-const defaultOptions = {
+const defaultOptions = Object.freeze({
 	vulgarFractions: false,
 	tolerance: defaultTolerance,
 	fractionSlash: false,
-	romanNumerals: false
-};
+	romanNumerals: false,
+	zeroFormat: "",
+	allowTrailingInvalid: true
+});
 /**
 * Map of vulgar fractions to their traditional ASCII equivalents.
 */
-const vulgarToAsciiMap = {
+const vulgarToAsciiMap = Object.freeze({
 	"¼": "1/4",
 	"½": "1/2",
 	"¾": "3/4",
@@ -38,59 +39,46 @@ const vulgarToAsciiMap = {
 	"⅜": "3/8",
 	"⅝": "5/8",
 	"⅞": "7/8"
-};
+});
 /**
-* Map of "close enough" decimal values to the {@link VulgarFraction} or
-* {@link Sixteenth} fraction string matches.
+* Map of "close enough" values to the {@link VulgarFraction} or {@link Sixteenth} fraction
+* string matches. The value +/- the `tolerance` option (or {@link defaultTolerance} if not
+* specified) is considered close enough to match the fraction.
 */
-const fractionDecimalMatches = [
-	[.33, "⅓"],
-	[.66, "⅔"],
-	[.2, "⅕"],
-	[.4, "⅖"],
-	[.6, "⅗"],
-	[.8, "⅘"],
-	[.166, "⅙"],
-	[.833, "⅚"],
-	[.143, "⅐"],
-	[.111, "⅑"],
-	[.1, "⅒"],
-	[.125, "⅛"],
-	[.25, "¼"],
-	[.375, "⅜"],
-	[.5, "½"],
-	[.625, "⅝"],
-	[.75, "¾"],
-	[.875, "⅞"],
-	[.0625, "1/16"],
-	[.1875, "3/16"],
-	[.3125, "5/16"],
-	[.4375, "7/16"],
-	[.5625, "9/16"],
-	[.6875, "11/16"],
-	[.8125, "13/16"],
-	[.9375, "15/16"]
-];
-
+const fractionDecimalMatches = Object.freeze([
+	[1 / 16, "1/16"],
+	[1 / 10, "⅒"],
+	[1 / 9, "⅑"],
+	[1 / 8, "⅛"],
+	[1 / 7, "⅐"],
+	[1 / 6, "⅙"],
+	[3 / 16, "3/16"],
+	[1 / 5, "⅕"],
+	[1 / 4, "¼"],
+	[5 / 16, "5/16"],
+	[1 / 3, "⅓"],
+	[3 / 8, "⅜"],
+	[2 / 5, "⅖"],
+	[7 / 16, "7/16"],
+	[1 / 2, "½"],
+	[9 / 16, "9/16"],
+	[3 / 5, "⅗"],
+	[5 / 8, "⅝"],
+	[2 / 3, "⅔"],
+	[11 / 16, "11/16"],
+	[3 / 4, "¾"],
+	[4 / 5, "⅘"],
+	[13 / 16, "13/16"],
+	[5 / 6, "⅚"],
+	[7 / 8, "⅞"],
+	[15 / 16, "15/16"]
+].map((entry) => Object.freeze(entry)));
 //#endregion
 //#region src/formatQuantity.ts
-/**
-* Determines if two numbers are close enough to consider
-* them equal for the purposes of this package.
-*/
-const closeEnough = (n1, n2, tolerance) => Math.abs(n1 - n2) < tolerance;
 const superscriptDigits = "⁰¹²³⁴⁵⁶⁷⁸⁹";
 const subscriptDigits = "₀₁₂₃₄₅₆₇₈₉";
-const toSuperscript = (s) => {
-	let r = "";
-	for (let i = 0; i < s.length; i++) r += superscriptDigits[+s[i]];
-	return r;
-};
-const toSubscript = (s) => {
-	let r = "";
-	for (let i = 0; i < s.length; i++) r += subscriptDigits[+s[i]];
-	return r;
-};
+const toSuperscript = (s) => [...s].map((c) => superscriptDigits[+c]).join("");
+const toSubscript = (s) => [...s].map((c) => subscriptDigits[+c]).join("");
 /**
 * Applies the `vulgarFractions` or `fractionSlash` options as necessary.
 */
@@ -104,13 +92,25 @@ const getFraction = (vulgarFractionOrSixteenth, { fractionSlash, vulgarFractions
 	return plainFraction;
 };
 /**
+* Only `false` (matching disabled) or a non-negative number is a valid
+* `tolerance`. Everything else—negative numbers, `NaN`, non-numbers,
+* `null`, `undefined`—resolves to {@link defaultTolerance}.
+*/
+const isValidTolerance = (tolerance) => tolerance === false || typeof tolerance === "number" && tolerance >= 0;
+/**
 * Merges options object with default options, converting boolean to object if necessary.
 */
-const normalizeOptions = (options) => ({
-	...defaultOptions,
-	...typeof options === "boolean" ? { vulgarFractions: options } : options
-});
-const romanNumeralValueKey = [
+const normalizeOptions = (options) => {
+	const opts = {
+		...defaultOptions,
+		...typeof options === "boolean" ? { vulgarFractions: options } : typeof options === "object" && options !== null ? options : {}
+	};
+	if (!isValidTolerance(opts.tolerance)) opts.tolerance = defaultOptions.tolerance;
+	if (typeof opts.zeroFormat !== "string") opts.zeroFormat = defaultOptions.zeroFormat;
+	if (opts.allowTrailingInvalid !== false) opts.allowTrailingInvalid = true;
+	return opts;
+};
+const romanNumeralsByPlace = [
 	"",
 	"C",
 	"CC",
@@ -143,16 +143,17 @@ const romanNumeralValueKey = [
 	"IX"
 ];
 /**
-* Formats a number as Roman numerals. The number must be between
-* 1 and 3999, inclusive.
+* Formats a number or bigint as Roman numerals. The number must be between
+* 1 and 3999, inclusive; any other value—including non-numbers,
+* `NaN`, and non-finite numbers—yields `null`.
 */
-const formatRomanNumerals = (qty) => {
-	if (typeof qty !== "number" || isNaN(qty)) return null;
-	if (qty < 1 || qty >= 4e3) return "";
+const formatRomanNumerals = (quantity) => {
+	if (typeof quantity !== "number" && typeof quantity !== "bigint" || !(quantity >= 1 && quantity < 4e3)) return null;
+	const qty = Number(quantity);
 	const digits = `${Math.floor(qty)}`.split("");
 	let roman = "";
 	let i = 3;
-	while (i--) roman = `${romanNumeralValueKey[+digits.pop() + i * 10] || ""}${roman}`;
+	while (i--) roman = `${romanNumeralsByPlace[+digits.pop() + i * 10] || ""}${roman}`;
 	return `${Array(+digits.join("") + 1).join("M")}${roman}`;
 };
 /**
@@ -162,29 +163,46 @@ const formatRomanNumerals = (qty) => {
 * like "½", pass `true` as the second argument. For other options
 * see {@link FormatQuantityOptions}.
 */
-const formatQuantity = (qty, options = defaultOptions) => {
-	const qtyAsNumber = typeof qty === "string" ? (0, numeric_quantity.numericQuantity)(qty, {
-		round: false,
-		allowTrailingInvalid: true
+const formatQuantity = (qty, options) => {
+	if (typeof qty !== "number" && typeof qty !== "string" && typeof qty !== "bigint") return null;
+	const opts = normalizeOptions(options);
+	const qtyAsNumber = typeof qty !== "number" && typeof qty !== "bigint" ? (0, numeric_quantity.numericQuantity)(qty, {
+		allowTrailingInvalid: opts.allowTrailingInvalid,
+		romanNumerals: opts.romanNumerals,
+		bigIntOnOverflow: true,
+		round: false
 	}) : qty;
-	if (isNaN(qtyAsNumber) || qtyAsNumber === null) return null;
-	if (qtyAsNumber === 0) return "";
-	const opts = normalizeOptions(options ?? defaultOptions);
+	if (typeof qtyAsNumber === "number" && isNaN(qtyAsNumber)) return null;
+	if (Number(qtyAsNumber) === 0) return opts.zeroFormat;
 	if (opts.romanNumerals) return formatRomanNumerals(qtyAsNumber);
-	const absoluteValue = Math.abs(qtyAsNumber);
-	const flooredAbsVal = Math.floor(absoluteValue);
-	const sign = qtyAsNumber < 0 ? "-" : "";
-	const wholeStr = flooredAbsVal === 0 ? "" : `${flooredAbsVal}`;
-	const decimalValue = absoluteValue - flooredAbsVal;
+	const absoluteValue = typeof qtyAsNumber === "bigint" ? qtyAsNumber < 0n ? -qtyAsNumber : qtyAsNumber : Math.abs(qtyAsNumber);
+	const flooredAbsVal = typeof absoluteValue === "bigint" ? absoluteValue : Math.floor(absoluteValue);
+	const wholeNumberStr = `${flooredAbsVal || ""}`;
+	const decimalValue = typeof absoluteValue === "bigint" ? 0 : absoluteValue - flooredAbsVal;
 	if (decimalValue === 0) return `${qtyAsNumber}`;
-	for (const [num, vf] of fractionDecimalMatches) if (closeEnough(decimalValue, num, opts.tolerance)) {
-		const fraction = getFraction(vf, opts);
+	let closestMatch = null;
+	let closestMatchDiff = Infinity;
+	if (opts.tolerance !== false) for (const [num, vf] of fractionDecimalMatches) {
+		const diff = Math.abs(decimalValue - num);
+		if (diff < opts.tolerance || diff === 0) {
+			if (diff === 0) {
+				closestMatch = vf;
+				break;
+			}
+			if (diff < closestMatchDiff) {
+				closestMatch = vf;
+				closestMatchDiff = diff;
+			}
+		}
+	}
+	if (closestMatch) {
+		const fraction = getFraction(closestMatch, opts);
 		const isVulgar = fraction in vulgarToAsciiMap;
-		return `${sign}${wholeStr}${wholeStr ? opts.separator ?? (isVulgar ? "" : " ") : ""}${fraction}`;
+		const sep = wholeNumberStr ? opts.separator ?? (isVulgar ? "" : " ") : "";
+		return `${qtyAsNumber < 0 ? "-" : ""}${wholeNumberStr}${sep}${fraction}`;
 	}
 	return `${qtyAsNumber}`;
 };
-
 //#endregion
 exports.defaultOptions = defaultOptions;
 exports.defaultTolerance = defaultTolerance;
@@ -192,4 +210,5 @@ exports.formatQuantity = formatQuantity;
 exports.formatRomanNumerals = formatRomanNumerals;
 exports.fractionDecimalMatches = fractionDecimalMatches;
 exports.vulgarToAsciiMap = vulgarToAsciiMap;
+
 //# sourceMappingURL=format-quantity.cjs.development.js.map