format-quantity 3.0.0 → 3.2.0

package/dist/format-quantity.mjs

@@ -1,157 +1,208 @@
-// src/constants.ts
-var defaultTolerance = 75e-4;
-var defaultOptions = {
-  vulgarFractions: false,
-  tolerance: defaultTolerance,
-  fractionSlash: false,
-  romanNumerals: false
-};
-var vulgarToAsciiMap = {
-  "\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"
+import { numericQuantity } from "numeric-quantity";
+//#region src/constants.ts
+/**
+* Default tolerance used by {@link formatQuantity} when determining if a number
+* is close enough to a fraction value to be considered equivalent.
+*/
+const defaultTolerance = .0075;
+/**
+* Default options for {@link formatQuantity}.
+*/
+const defaultOptions = Object.freeze({
+	vulgarFractions: false,
+	tolerance: defaultTolerance,
+	fractionSlash: false,
+	romanNumerals: false,
+	zeroFormat: "",
+	allowTrailingInvalid: true
+});
+/**
+* Map of vulgar fractions to their traditional ASCII equivalents.
+*/
+const vulgarToAsciiMap = Object.freeze({
+	"¼": "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"
+});
+/**
+* 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 = 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
+const superscriptDigits = "⁰¹²³⁴⁵⁶⁷⁸⁹";
+const subscriptDigits = "₀₁₂₃₄₅₆₇₈₉";
+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.
+*/
+const getFraction = (vulgarFractionOrSixteenth, { fractionSlash, vulgarFractions }) => {
+	if (vulgarFractions) return vulgarFractionOrSixteenth;
+	const plainFraction = vulgarToAsciiMap[vulgarFractionOrSixteenth] ?? vulgarFractionOrSixteenth;
+	if (fractionSlash) {
+		const [num, den] = plainFraction.split("/");
+		return `${toSuperscript(num)}⁄${toSubscript(den)}`;
+	}
+	return plainFraction;
 };
-var fractionDecimalMatches = [
-  [0.33, "\u2153"],
-  [0.66, "\u2154"],
-  [0.2, "\u2155"],
-  [0.4, "\u2156"],
-  [0.6, "\u2157"],
-  [0.8, "\u2158"],
-  [0.166, "\u2159"],
-  [0.833, "\u215A"],
-  [0.143, "\u2150"],
-  [0.111, "\u2151"],
-  [0.1, "\u2152"],
-  [0.125, "\u215B"],
-  [0.25, "\xBC"],
-  [0.375, "\u215C"],
-  [0.5, "\xBD"],
-  [0.625, "\u215D"],
-  [0.75, "\xBE"],
-  [0.875, "\u215E"],
-  [0.0625, "1/16"],
-  [0.1875, "3/16"],
-  [0.3125, "5/16"],
-  [0.4375, "7/16"],
-  [0.5625, "9/16"],
-  [0.6875, "11/16"],
-  [0.8125, "13/16"],
-  [0.9375, "15/16"]
-];
-
-// src/formatQuantity.ts
-var closeEnough = (n1, n2, tolerance) => Math.abs(n1 - n2) < tolerance;
-var getFraction = (vulgarFractionOrSixteenth, { fractionSlash, vulgarFractions }) => {
-  if (vulgarFractions) {
-    return vulgarFractionOrSixteenth;
-  }
-  const plainFraction = vulgarToAsciiMap[vulgarFractionOrSixteenth] ?? vulgarFractionOrSixteenth;
-  if (fractionSlash) {
-    return plainFraction.replace("/", "\u2044");
-  }
-  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) => {
+	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;
 };
-var normalizeOptions = (options) => ({
-  ...defaultOptions,
-  ...typeof options === "boolean" ? { vulgarFractions: options } : options
-});
-var romanNumeralValueKey = [
-  "",
-  "C",
-  "CC",
-  "CCC",
-  "CD",
-  "D",
-  "DC",
-  "DCC",
-  "DCCC",
-  "CM",
-  "",
-  "X",
-  "XX",
-  "XXX",
-  "XL",
-  "L",
-  "LX",
-  "LXX",
-  "LXXX",
-  "XC",
-  "",
-  "I",
-  "II",
-  "III",
-  "IV",
-  "V",
-  "VI",
-  "VII",
-  "VIII",
-  "IX"
+const romanNumeralsByPlace = [
+	"",
+	"C",
+	"CC",
+	"CCC",
+	"CD",
+	"D",
+	"DC",
+	"DCC",
+	"DCCC",
+	"CM",
+	"",
+	"X",
+	"XX",
+	"XXX",
+	"XL",
+	"L",
+	"LX",
+	"LXX",
+	"LXXX",
+	"XC",
+	"",
+	"I",
+	"II",
+	"III",
+	"IV",
+	"V",
+	"VI",
+	"VII",
+	"VIII",
+	"IX"
 ];
-var formatRomanNumerals = (qty) => {
-  if (typeof qty !== "number" || isNaN(qty)) {
-    return null;
-  }
-  if (qty < 1 || qty >= 4e3) {
-    return "";
-  }
-  const floored = Math.floor(qty);
-  const digits = `${floored}`.split("");
-  let roman = "";
-  let i = 3;
-  while (i--) {
-    roman = `${romanNumeralValueKey[+digits.pop() + i * 10] || ""}${roman}`;
-  }
-  return `${Array(+digits.join("") + 1).join("M")}${roman}`;
+/**
+* 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 = (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 = `${romanNumeralsByPlace[+digits.pop() + i * 10] || ""}${roman}`;
+	return `${Array(+digits.join("") + 1).join("M")}${roman}`;
 };
-var formatQuantity = (qty, options = defaultOptions) => {
-  const qtyAsNumber = typeof qty === "string" ? parseFloat(qty) : qty;
-  if (isNaN(qtyAsNumber) || qtyAsNumber === null) {
-    return null;
-  }
-  if (qtyAsNumber === 0) {
-    return "";
-  }
-  const opts = normalizeOptions(options ?? defaultOptions);
-  if (opts.romanNumerals) {
-    return formatRomanNumerals(qtyAsNumber);
-  }
-  const absoluteValue = Math.abs(qtyAsNumber);
-  const flooredAbsVal = Math.floor(absoluteValue);
-  const flooredAbsValStr = `${qtyAsNumber < 0 ? "-" : ""}${flooredAbsVal === 0 ? "" : `${flooredAbsVal} `}`;
-  const decimalValue = absoluteValue - flooredAbsVal;
-  if (decimalValue === 0) {
-    return `${qtyAsNumber}`;
-  }
-  for (const [num, vf] of fractionDecimalMatches) {
-    if (closeEnough(decimalValue, num, opts.tolerance)) {
-      const fraction = getFraction(vf, opts);
-      const int = fraction in vulgarToAsciiMap ? flooredAbsValStr.trim() : flooredAbsValStr;
-      return `${int}${fraction}`;
-    }
-  }
-  return `${qtyAsNumber}`;
-};
-export {
-  defaultOptions,
-  defaultTolerance,
-  formatQuantity,
-  fractionDecimalMatches,
-  vulgarToAsciiMap
+/**
+* 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}.
+*/
+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" ? numericQuantity(qty, {
+		allowTrailingInvalid: opts.allowTrailingInvalid,
+		romanNumerals: opts.romanNumerals,
+		bigIntOnOverflow: true,
+		round: false
+	}) : qty;
+	if (typeof qtyAsNumber === "number" && isNaN(qtyAsNumber)) return null;
+	if (Number(qtyAsNumber) === 0) return opts.zeroFormat;
+	if (opts.romanNumerals) return formatRomanNumerals(qtyAsNumber);
+	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}`;
+	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;
+		const sep = wholeNumberStr ? opts.separator ?? (isVulgar ? "" : " ") : "";
+		return `${qtyAsNumber < 0 ? "-" : ""}${wholeNumberStr}${sep}${fraction}`;
+	}
+	return `${qtyAsNumber}`;
 };
+//#endregion
+export { defaultOptions, defaultTolerance, formatQuantity, formatRomanNumerals, fractionDecimalMatches, vulgarToAsciiMap };
+
 //# sourceMappingURL=format-quantity.mjs.map

package/dist/format-quantity.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/constants.ts","../src/formatQuantity.ts"],"sourcesContent":["import type {\n  FormatQuantityOptions,\n  SimpleFraction,\n  Sixteenth,\n  VulgarFraction,\n} from './types';\n\n/**\n * Default tolerance used by {@link formatQuantity} when determining if a number\n * is close enough to a fraction value to be considered equivalent.\n */\nexport const defaultTolerance = 0.0075 as const;\n\n/**\n * Default options for {@link formatQuantity}.\n */\nexport const defaultOptions = {\n  vulgarFractions: false,\n  tolerance: defaultTolerance,\n  fractionSlash: false,\n  romanNumerals: false,\n} as const satisfies Required<FormatQuantityOptions>;\n\n/**\n * Map of vulgar fractions to their traditional ASCII equivalents.\n */\nexport const vulgarToAsciiMap = {\n  '¼': '1/4',\n  '½': '1/2',\n  '¾': '3/4',\n  '⅐': '1/7',\n  '⅑': '1/9',\n  '⅒': '1/10',\n  '⅓': '1/3',\n  '⅔': '2/3',\n  '⅕': '1/5',\n  '⅖': '2/5',\n  '⅗': '3/5',\n  '⅘': '4/5',\n  '⅙': '1/6',\n  '⅚': '5/6',\n  '⅛': '1/8',\n  '⅜': '3/8',\n  '⅝': '5/8',\n  '⅞': '7/8',\n} as const satisfies Record<VulgarFraction, SimpleFraction>;\n\n/**\n * Map of \"close enough\" decimal values to the {@link VulgarFraction} or\n * {@link Sixteenth} fraction string matches.\n */\nexport const fractionDecimalMatches = [\n  [0.33, '⅓'],\n  [0.66, '⅔'],\n  [0.2, '⅕'],\n  [0.4, '⅖'],\n  [0.6, '⅗'],\n  [0.8, '⅘'],\n  [0.166, '⅙'],\n  [0.833, '⅚'],\n  [0.143, '⅐'],\n  [0.111, '⅑'],\n  [0.1, '⅒'],\n  [0.125, '⅛'],\n  [0.25, '¼'],\n  [0.375, '⅜'],\n  [0.5, '½'],\n  [0.625, '⅝'],\n  [0.75, '¾'],\n  [0.875, '⅞'],\n  [0.0625, '1/16'],\n  [0.1875, '3/16'],\n  [0.3125, '5/16'],\n  [0.4375, '7/16'],\n  [0.5625, '9/16'],\n  [0.6875, '11/16'],\n  [0.8125, '13/16'],\n  [0.9375, '15/16'],\n] satisfies [number, VulgarFraction | Sixteenth][];\n","import {\n  defaultOptions,\n  fractionDecimalMatches,\n  vulgarToAsciiMap,\n} from './constants';\nimport type {\n  FormatQuantity,\n  FormatQuantityOptions,\n  SimpleFraction,\n  Sixteenth,\n  VulgarFraction,\n} from './types';\n\n/**\n * Determines if two numbers are close enough to consider\n * them equal for the purposes of this package.\n */\nconst closeEnough = (n1: number, n2: number, tolerance: number) =>\n  Math.abs(n1 - n2) < tolerance;\n\n/**\n * Applies the `vulgarFractions` or `fractionSlash` options as necessary.\n */\nconst getFraction = (\n  vulgarFractionOrSixteenth: VulgarFraction | Sixteenth,\n  { fractionSlash, vulgarFractions }: FormatQuantityOptions\n) => {\n  if (vulgarFractions) {\n    return vulgarFractionOrSixteenth;\n  }\n\n  const plainFraction: SimpleFraction =\n    vulgarToAsciiMap[vulgarFractionOrSixteenth as VulgarFraction] ??\n    vulgarFractionOrSixteenth;\n\n  if (fractionSlash) {\n    return plainFraction.replace('/', '⁄');\n  }\n\n  return plainFraction;\n};\n\n/**\n * Merges options object with default options, converting boolean to object if necessary.\n */\nconst normalizeOptions = (\n  options: Parameters<FormatQuantity>[1]\n): Required<FormatQuantityOptions> => ({\n  ...defaultOptions,\n  ...(typeof options === 'boolean' ? { vulgarFractions: options } : options),\n});\n\n// prettier-ignore\nconst romanNumeralValueKey = [\n  \"\", \"C\", \"CC\", \"CCC\", \"CD\", \"D\", \"DC\", \"DCC\", \"DCCC\", \"CM\",\n  \"\", \"X\", \"XX\", \"XXX\", \"XL\", \"L\", \"LX\", \"LXX\", \"LXXX\", \"XC\",\n  \"\", \"I\", \"II\", \"III\", \"IV\", \"V\", \"VI\", \"VII\", \"VIII\", \"IX\",\n] as const;\n\n/**\n * Formats a number as Roman numerals. The number must be between\n * 1 and 3999, inclusive.\n */\nexport const formatRomanNumerals = (qty: number) => {\n  if (typeof qty !== 'number' || isNaN(qty)) {\n    return null;\n  }\n\n  if (qty < 1 || qty >= 4000) {\n    return '';\n  }\n\n  const floored = Math.floor(qty);\n\n  const digits = `${floored}`.split('');\n  let roman = '';\n  let i = 3;\n  while (i--) {\n    roman = `${romanNumeralValueKey[+digits.pop()! + i * 10] || ''}${roman}`;\n  }\n\n  return `${Array(+digits.join('') + 1).join('M')}${roman}`;\n};\n\n/**\n * Formats a number (or string that appears to be a number)\n * as one would see it written in imperial measurements, e.g.\n * \"1 1/2\" instead of \"1.5\". To use vulgar fraction characters\n * like \"½\", pass `true` as the second argument. For other options\n * see {@link FormatQuantityOptions}.\n */\nexport const formatQuantity: FormatQuantity = (\n  qty,\n  options = defaultOptions\n) => {\n  // TODO: use numericQuantity instead of parseFloat?\n  const qtyAsNumber = typeof qty === 'string' ? parseFloat(qty) : qty;\n\n  // Return `null` if input is not number-like.\n  if (isNaN(qtyAsNumber) || qtyAsNumber === null) {\n    return null;\n  }\n\n  // Return an empty string if the value is zero.\n  if (qtyAsNumber === 0) {\n    return '';\n  }\n\n  // The default options parameter in the function signature only takes effect\n  // if the parameter is `undefined`. The nullish coalescing operator below\n  // covers the `null` case.\n  const opts = normalizeOptions(options ?? defaultOptions);\n\n  if (opts.romanNumerals) {\n    return formatRomanNumerals(qtyAsNumber);\n  }\n\n  const absoluteValue = Math.abs(qtyAsNumber);\n  const flooredAbsVal = Math.floor(absoluteValue);\n  const flooredAbsValStr = `${qtyAsNumber < 0 ? '-' : ''}${\n    flooredAbsVal === 0 ? '' : `${flooredAbsVal} `\n  }`;\n  const decimalValue = absoluteValue - flooredAbsVal;\n\n  // For integers just return the given value as a string.\n  if (decimalValue === 0) {\n    return `${qtyAsNumber}`;\n  }\n\n  for (const [num, vf] of fractionDecimalMatches) {\n    if (closeEnough(decimalValue, num, opts.tolerance)) {\n      const fraction = getFraction(vf, opts);\n      const int =\n        fraction in vulgarToAsciiMap\n          ? flooredAbsValStr.trim()\n          : flooredAbsValStr;\n      return `${int}${fraction}`;\n    }\n  }\n\n  return `${qtyAsNumber}`;\n};\n"],"mappings":"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","names":[]}
+{"version":3,"file":"format-quantity.mjs","names":[],"sources":["../src/constants.ts","../src/formatQuantity.ts"],"sourcesContent":["import type {\n  ResolvedFormatQuantityOptions,\n  SimpleFraction,\n  Sixteenth,\n  VulgarFraction,\n} from './types';\n\n/**\n * Default tolerance used by {@link formatQuantity} when determining if a number\n * is close enough to a fraction value to be considered equivalent.\n */\nexport const defaultTolerance = 0.0075 as const;\n\n/**\n * Default options for {@link formatQuantity}.\n */\nexport const defaultOptions: Readonly<ResolvedFormatQuantityOptions> = Object.freeze({\n  vulgarFractions: false,\n  tolerance: defaultTolerance,\n  fractionSlash: false,\n  romanNumerals: false,\n  zeroFormat: '',\n  allowTrailingInvalid: true,\n});\n\n/**\n * Map of vulgar fractions to their traditional ASCII equivalents.\n */\nexport const vulgarToAsciiMap: Readonly<Record<VulgarFraction, SimpleFraction>> = Object.freeze({\n  '¼': '1/4',\n  '½': '1/2',\n  '¾': '3/4',\n  '⅐': '1/7',\n  '⅑': '1/9',\n  '⅒': '1/10',\n  '⅓': '1/3',\n  '⅔': '2/3',\n  '⅕': '1/5',\n  '⅖': '2/5',\n  '⅗': '3/5',\n  '⅘': '4/5',\n  '⅙': '1/6',\n  '⅚': '5/6',\n  '⅛': '1/8',\n  '⅜': '3/8',\n  '⅝': '5/8',\n  '⅞': '7/8',\n});\n\n/**\n * Map of \"close enough\" values to the {@link VulgarFraction} or {@link Sixteenth} fraction\n * string matches. The value +/- the `tolerance` option (or {@link defaultTolerance} if not\n * specified) is considered close enough to match the fraction.\n */\nexport const fractionDecimalMatches: readonly (readonly [number, VulgarFraction | Sixteenth])[] =\n  Object.freeze(\n    (\n      [\n        [1 / 16, '1/16'],\n        [1 / 10, '⅒'],\n        [1 / 9, '⅑'],\n        [1 / 8, '⅛'],\n        [1 / 7, '⅐'],\n        [1 / 6, '⅙'],\n        [3 / 16, '3/16'],\n        [1 / 5, '⅕'],\n        [1 / 4, '¼'],\n        [5 / 16, '5/16'],\n        [1 / 3, '⅓'],\n        [3 / 8, '⅜'],\n        [2 / 5, '⅖'],\n        [7 / 16, '7/16'],\n        [1 / 2, '½'],\n        [9 / 16, '9/16'],\n        [3 / 5, '⅗'],\n        [5 / 8, '⅝'],\n        [2 / 3, '⅔'],\n        [11 / 16, '11/16'],\n        [3 / 4, '¾'],\n        [4 / 5, '⅘'],\n        [13 / 16, '13/16'],\n        [5 / 6, '⅚'],\n        [7 / 8, '⅞'],\n        [15 / 16, '15/16'],\n      ] satisfies [number, VulgarFraction | Sixteenth][]\n    ).map(entry => Object.freeze(entry))\n  );\n","import { numericQuantity } from 'numeric-quantity';\nimport { defaultOptions, fractionDecimalMatches, vulgarToAsciiMap } from './constants';\nimport type {\n  FormatQuantity,\n  ResolvedFormatQuantityOptions,\n  SimpleFraction,\n  Sixteenth,\n  VulgarFraction,\n} from './types';\n\nconst superscriptDigits = '⁰¹²³⁴⁵⁶⁷⁸⁹';\nconst subscriptDigits = '₀₁₂₃₄₅₆₇₈₉';\n\n// oxlint-disable-next-line typescript/no-misused-spread\nconst toSuperscript = (s: string) => [...s].map(c => superscriptDigits[+c]).join('');\n// oxlint-disable-next-line typescript/no-misused-spread\nconst toSubscript = (s: string) => [...s].map(c => subscriptDigits[+c]).join('');\n\n/**\n * Applies the `vulgarFractions` or `fractionSlash` options as necessary.\n */\nconst getFraction = (\n  vulgarFractionOrSixteenth: VulgarFraction | Sixteenth,\n  { fractionSlash, vulgarFractions }: ResolvedFormatQuantityOptions\n) => {\n  if (vulgarFractions) {\n    return vulgarFractionOrSixteenth;\n  }\n\n  const plainFraction: SimpleFraction =\n    vulgarToAsciiMap[vulgarFractionOrSixteenth as VulgarFraction] ?? vulgarFractionOrSixteenth;\n\n  if (fractionSlash) {\n    const [num, den] = plainFraction.split('/');\n    return `${toSuperscript(num)}⁄${toSubscript(den)}`;\n  }\n\n  return plainFraction;\n};\n\n/**\n * Only `false` (matching disabled) or a non-negative number is a valid\n * `tolerance`. Everything else—negative numbers, `NaN`, non-numbers,\n * `null`, `undefined`—resolves to {@link defaultTolerance}.\n */\nconst isValidTolerance = (tolerance: unknown): tolerance is number | false =>\n  tolerance === false || (typeof tolerance === 'number' && tolerance >= 0);\n\n/**\n * Merges options object with default options, converting boolean to object if necessary.\n */\nconst normalizeOptions = (\n  options: Parameters<FormatQuantity>[1]\n): ResolvedFormatQuantityOptions => {\n  const opts: ResolvedFormatQuantityOptions = {\n    ...defaultOptions,\n    ...(typeof options === 'boolean'\n      ? { vulgarFractions: options }\n      : typeof options === 'object' && options !== null\n        ? options\n        : {}),\n  };\n\n  if (!isValidTolerance(opts.tolerance)) {\n    opts.tolerance = defaultOptions.tolerance;\n  }\n\n  if (typeof opts.zeroFormat !== 'string') {\n    opts.zeroFormat = defaultOptions.zeroFormat;\n  }\n\n  if (opts.allowTrailingInvalid !== false) {\n    opts.allowTrailingInvalid = true;\n  }\n\n  return opts;\n};\n\n// oxfmt-ignore\nconst romanNumeralsByPlace = [\n  '', 'C', 'CC', 'CCC', 'CD', 'D', 'DC', 'DCC', 'DCCC', 'CM',\n  '', 'X', 'XX', 'XXX', 'XL', 'L', 'LX', 'LXX', 'LXXX', 'XC',\n  '', 'I', 'II', 'III', 'IV', 'V', 'VI', 'VII', 'VIII', 'IX',\n] as const;\n\n/**\n * Formats a number or bigint as Roman numerals. The number must be between\n * 1 and 3999, inclusive; any other value—including non-numbers,\n * `NaN`, and non-finite numbers—yields `null`.\n */\nexport const formatRomanNumerals = (quantity: number | bigint): string | null => {\n  if (\n    (typeof quantity !== 'number' && typeof quantity !== 'bigint') ||\n    !(quantity >= 1 && quantity < 4000)\n  ) {\n    return null;\n  }\n\n  const qty = Number(quantity);\n\n  const floored = Math.floor(qty);\n\n  const digits = `${floored}`.split('');\n  let roman = '';\n  let i = 3;\n  while (i--) {\n    roman = `${romanNumeralsByPlace[+digits.pop()! + i * 10] || ''}${roman}`;\n  }\n\n  return `${Array(+digits.join('') + 1).join('M')}${roman}`;\n};\n\n/**\n * Formats a number (or string that appears to be a number)\n * as one would see it written in imperial measurements, e.g.\n * \"1 1/2\" instead of \"1.5\". To use vulgar fraction characters\n * like \"½\", pass `true` as the second argument. For other options\n * see {@link FormatQuantityOptions}.\n */\nexport const formatQuantity: FormatQuantity = (qty, options) => {\n  // Only numbers, bigints, and strings are accepted. Anything else (objects, booleans,\n  // nullish, arrays like `[1]` that would coerce to a numeric string) is\n  // rejected up front so off-type inputs behave consistently.\n  if (typeof qty !== 'number' && typeof qty !== 'string' && typeof qty !== 'bigint') {\n    return null;\n  }\n\n  const opts = normalizeOptions(options);\n\n  const qtyAsNumber =\n    typeof qty !== 'number' && typeof qty !== 'bigint'\n      ? numericQuantity(qty, {\n          allowTrailingInvalid: opts.allowTrailingInvalid,\n          romanNumerals: opts.romanNumerals,\n          bigIntOnOverflow: true,\n          round: false,\n        })\n      : qty;\n\n  // Return `null` if input is not number-like.\n  if (typeof qtyAsNumber === 'number' && isNaN(qtyAsNumber)) {\n    return null;\n  }\n\n  // Return empty string (or configured `zeroFormat`) if the value is zero.\n  if (Number(qtyAsNumber) === 0) {\n    return opts.zeroFormat;\n  }\n\n  if (opts.romanNumerals) {\n    return formatRomanNumerals(qtyAsNumber);\n  }\n\n  const absoluteValue =\n    typeof qtyAsNumber === 'bigint'\n      ? qtyAsNumber < 0n\n        ? -qtyAsNumber\n        : qtyAsNumber\n      : Math.abs(qtyAsNumber);\n  const flooredAbsVal =\n    typeof absoluteValue === 'bigint' ? absoluteValue : Math.floor(absoluteValue);\n  const wholeNumberStr = `${flooredAbsVal || ''}`;\n  const decimalValue =\n    typeof absoluteValue === 'bigint' ? 0 : absoluteValue - (flooredAbsVal as number);\n\n  // For integers just return the given value as a string.\n  if (decimalValue === 0) {\n    return `${qtyAsNumber}`;\n  }\n\n  let closestMatch: VulgarFraction | Sixteenth | null = null;\n  let closestMatchDiff = Infinity;\n  // `tolerance: false` disables fraction matching entirely.\n  if (opts.tolerance !== false) {\n    for (const [num, vf] of fractionDecimalMatches) {\n      const diff = Math.abs(decimalValue - num);\n      // `diff === 0` keeps exact quotients matching even at `tolerance: 0`.\n      if (diff < opts.tolerance || diff === 0) {\n        if (diff === 0) {\n          closestMatch = vf;\n          break;\n        }\n        if (diff < closestMatchDiff) {\n          closestMatch = vf;\n          closestMatchDiff = diff;\n        }\n      }\n    }\n  }\n\n  if (closestMatch) {\n    const fraction = getFraction(closestMatch, opts);\n    const isVulgar = fraction in vulgarToAsciiMap;\n    const sep = wholeNumberStr ? (opts.separator ?? (isVulgar ? '' : ' ')) : '';\n    return `${qtyAsNumber < 0 ? '-' : ''}${wholeNumberStr}${sep}${fraction}`;\n  }\n\n  return `${qtyAsNumber}`;\n};\n"],"mappings":"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"}

package/dist/format-quantity.production.d.mts

@@ -1,42 +1,80 @@
+//#region src/types.d.ts
 interface FormatQuantityOptions {
-    /**
-     * Output vulgar fractions, like "½" instead of "1/2", when appropriate.
-     * Overrides the `fractionSlash` option.
-     */
-    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;
-    /**
-     * 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.
-     */
-    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.
-     */
-    romanNumerals?: boolean;
+  /**
+   * 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.
+   *
+   * `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.
+   *
+   * @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.
+   *
+   * @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).
+   */
+  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.
+ */
+type ResolvedFormatQuantityOptions = Required<Omit<FormatQuantityOptions, "separator">> & Pick<FormatQuantityOptions, "separator">;
 /**
  * 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';
+type Digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9";
 /** Any numeric character except '0'. */
-type NonZeroDigit = Exclude<Digit, '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
@@ -46,27 +84,13 @@ type SimpleFraction = `${NonZeroDigit}/${NonZeroDigit}` | `${NonZeroDigit}/${Non
 /**
  * Odd numerator sixteenth fraction strings.
  */
-type Sixteenth = `${'1' | '3' | '5' | '7' | '9' | '11' | '13' | '15'}/16`;
+type Sixteenth = `${"1" | "3" | "5" | "7" | "9" | "11" | "13" | "15"}/16`;
 /**
  * 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]
-])[]>;
-
-/**
- * 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;
-
+type VulgarFraction = "¼" | "½" | "¾" | "⅐" | "⅑" | "⅒" | "⅓" | "⅔" | "⅕" | "⅖" | "⅗" | "⅘" | "⅙" | "⅚" | "⅛" | "⅜" | "⅝" | "⅞";
+//#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.
@@ -75,39 +99,33 @@ declare const defaultTolerance: 0.0075;
 /**
  * Default options for {@link formatQuantity}.
  */
-declare const defaultOptions: {
-    readonly vulgarFractions: false;
-    readonly tolerance: 0.0075;
-    readonly fractionSlash: false;
-    readonly romanNumerals: false;
-};
+declare const defaultOptions: Readonly<ResolvedFormatQuantityOptions>;
 /**
  * Map of vulgar fractions to their traditional ASCII equivalents.
  */
-declare const vulgarToAsciiMap: {
-    readonly '\u00BC': "1/4";
-    readonly '\u00BD': "1/2";
-    readonly '\u00BE': "3/4";
-    readonly '\u2150': "1/7";
-    readonly '\u2151': "1/9";
-    readonly '\u2152': "1/10";
-    readonly '\u2153': "1/3";
-    readonly '\u2154': "2/3";
-    readonly '\u2155': "1/5";
-    readonly '\u2156': "2/5";
-    readonly '\u2157': "3/5";
-    readonly '\u2158': "4/5";
-    readonly '\u2159': "1/6";
-    readonly '\u215A': "5/6";
-    readonly '\u215B': "1/8";
-    readonly '\u215C': "3/8";
-    readonly '\u215D': "5/8";
-    readonly '\u215E': "7/8";
-};
+declare const vulgarToAsciiMap: Readonly<Record<VulgarFraction, SimpleFraction>>;
 /**
- * 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.
  */
-declare const fractionDecimalMatches: ([number, "⅓"] | [number, "⅔"] | [number, "⅕"] | [number, "⅖"] | [number, "⅗"] | [number, "⅘"] | [number, "⅙"] | [number, "⅚"] | [number, "⅐"] | [number, "⅑"] | [number, "⅒"] | [number, "⅛"] | [number, "¼"] | [number, "⅜"] | [number, "½"] | [number, "⅝"] | [number, "¾"] | [number, "⅞"] | [number, "1/16"] | [number, "3/16"] | [number, "5/16"] | [number, "7/16"] | [number, "9/16"] | [number, "11/16"] | [number, "13/16"] | [number, "15/16"])[];
-
-export { type Digit, type FormatQuantity, type FormatQuantityOptions, type FormatQuantityTests, type NonZeroDigit, type SimpleFraction, type Sixteenth, type VulgarFraction, defaultOptions, defaultTolerance, formatQuantity, fractionDecimalMatches, vulgarToAsciiMap };
+declare const fractionDecimalMatches: readonly (readonly [number, VulgarFraction | Sixteenth])[];
+//#endregion
+//#region src/formatQuantity.d.ts
+/**
+ * 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}.
+ */
+declare const formatQuantity: FormatQuantity;
+//#endregion
+export { Digit, FormatQuantity, FormatQuantityOptions, NonZeroDigit, ResolvedFormatQuantityOptions, SimpleFraction, Sixteenth, VulgarFraction, defaultOptions, defaultTolerance, formatQuantity, formatRomanNumerals, fractionDecimalMatches, vulgarToAsciiMap };
+//# sourceMappingURL=format-quantity.production.d.mts.map