format-quantity 2.1.0 → 3.1.0

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

@@ -0,0 +1,107 @@
+//#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;
+  /**
+  * 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;
+}
+/**
+* {@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;
+}
+/** 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).
+*/
+type SimpleFraction = `${NonZeroDigit}/${NonZeroDigit}` | `${NonZeroDigit}/${NonZeroDigit}${Digit}` | `${NonZeroDigit}${Digit}/${NonZeroDigit}${Digit}`;
+/**
+* Odd numerator sixteenth fraction strings.
+*/
+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]])[]>;
+//#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.
+*/
+declare const defaultTolerance: 0.0075;
+/**
+* Default options for {@link formatQuantity}.
+*/
+declare const defaultOptions: ResolvedFormatQuantityOptions;
+/**
+* Map of vulgar fractions to their traditional ASCII equivalents.
+*/
+declare const vulgarToAsciiMap: 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][];
+//#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 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 };
+//# sourceMappingURL=format-quantity.cjs.production.d.ts.map

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

@@ -1,2 +1,2 @@
-"use strict";var l=Object.defineProperty;var C=Object.getOwnPropertyDescriptor;var X=Object.getOwnPropertyNames;var b=Object.prototype.hasOwnProperty;var d=(t,o)=>{for(var r in o)l(t,r,{get:o[r],enumerable:!0})},y=(t,o,r,a)=>{if(o&&typeof o=="object"||typeof o=="function")for(let e of X(o))!b.call(t,e)&&e!==r&&l(t,e,{get:()=>o[e],enumerable:!(a=C(o,e))||a.enumerable});return t};var I=t=>y(l({},"__esModule",{value:!0}),t);var N={};d(N,{default:()=>Q,defaultOptions:()=>n,defaultTolerance:()=>D,formatQuantity:()=>c,fractionDecimalMatches:()=>u,vulgarToAsciiMap:()=>i});module.exports=I(N);var D=.0075,n={vulgarFractions:!1,tolerance:.0075,fractionSlash:!1,romanNumerals:!1},i={"\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"},u=[[.33,"\u2153"],[.66,"\u2154"],[.2,"\u2155"],[.4,"\u2156"],[.6,"\u2157"],[.8,"\u2158"],[.166,"\u2159"],[.833,"\u215A"],[.143,"\u2150"],[.111,"\u2151"],[.1,"\u2152"],[.125,"\u215B"],[.25,"\xBC"],[.375,"\u215C"],[.5,"\xBD"],[.625,"\u215D"],[.75,"\xBE"],[.875,"\u215E"],[.0625,"1/16"],[.1875,"3/16"],[.3125,"5/16"],[.4375,"7/16"],[.5625,"9/16"],[.6875,"11/16"],[.8125,"13/16"],[.9375,"15/16"]];var g=(t,o,r)=>Math.abs(t-o)<r,h=(t,{fractionSlash:o,vulgarFractions:r})=>{if(r)return t;let a=i[t]??t;return o?a.replace("/","\u2044"):a},x=t=>({...n,...typeof t=="boolean"?{vulgarFractions:t}:t}),$=["","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"],M=t=>{if(typeof t!="number"||isNaN(t))return null;if(t<1||t>=4e3)return"";let r=`${Math.floor(t)}`.split(""),a="",e=3;for(;e--;)a=`${$[+r.pop()+e*10]||""}${a}`;return`${Array(+r.join("")+1).join("M")}${a}`},c=(t,o=n)=>{let r=typeof t=="string"?parseFloat(t):t;if(isNaN(r)||r===null)return null;if(r===0)return"";let a=x(o??n);if(a.romanNumerals)return M(r);let e=Math.abs(r),s=Math.floor(e),m=`${r<0?"-":""}${s===0?"":`${s} `}`,f=e-s;if(f===0)return`${r}`;for(let[F,V]of u)if(g(f,F,a.tolerance)){let p=h(V,a);return`${Object.hasOwn(i,p)?m.trim():m}${p}`}return`${r}`};var Q=c;0&&(module.exports={defaultOptions,defaultTolerance,formatQuantity,fractionDecimalMatches,vulgarToAsciiMap});
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});let e=require(`numeric-quantity`);const t=.0075,n={vulgarFractions:!1,tolerance:t,fractionSlash:!1,romanNumerals:!1},r={"¼":`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`},i=[[.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`]],a=(e,t,n)=>Math.abs(e-t)<n,o=e=>{let t=``;for(let n=0;n<e.length;n++)t+=`⁰¹²³⁴⁵⁶⁷⁸⁹`[+e[n]];return t},s=e=>{let t=``;for(let n=0;n<e.length;n++)t+=`₀₁₂₃₄₅₆₇₈₉`[+e[n]];return t},c=(e,{fractionSlash:t,vulgarFractions:n})=>{if(n)return e;let i=r[e]??e;if(t){let[e,t]=i.split(`/`);return`${o(e)}⁄${s(t)}`}return i},l=e=>({...n,...typeof e==`boolean`?{vulgarFractions:e}:e}),u=`.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`.split(`.`),d=e=>{if(typeof e!=`number`||isNaN(e))return null;if(e<1||e>=4e3)return``;let t=`${Math.floor(e)}`.split(``),n=``,r=3;for(;r--;)n=`${u[+t.pop()+r*10]||``}${n}`;return`${Array(+t.join(``)+1).join(`M`)}${n}`},f=(t,o=n)=>{let s=typeof t==`string`?(0,e.numericQuantity)(t,{round:!1,allowTrailingInvalid:!0}):t;if(isNaN(s)||s===null)return null;if(s===0)return``;let u=l(o??n);if(u.romanNumerals)return d(s);let f=Math.abs(s),p=Math.floor(f),m=s<0?`-`:``,h=p===0?``:`${p}`,g=f-p;if(g===0)return`${s}`;for(let[e,t]of i)if(a(g,e,u.tolerance)){let e=c(t,u),n=e in r;return`${m}${h}${h?u.separator??(n?``:` `):``}${e}`}return`${s}`};exports.defaultOptions=n,exports.defaultTolerance=t,exports.formatQuantity=f,exports.formatRomanNumerals=d,exports.fractionDecimalMatches=i,exports.vulgarToAsciiMap=r;
 //# sourceMappingURL=format-quantity.cjs.production.js.map

package/dist/cjs/format-quantity.cjs.production.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/index.ts","../../src/constants.ts","../../src/formatQuantity.ts"],"sourcesContent":["import { formatQuantity } from './formatQuantity';\nexport * from './constants';\nexport * from './types';\nexport { formatQuantity };\nexport default formatQuantity;\n","import type {\n  FormatQuantityOptions,\n  SimpleFraction,\n  Sixteenth,\n  VulgarFraction,\n} from './types';\n\nexport const defaultTolerance = 0.0075 as const;\n\nexport const defaultOptions = {\n  vulgarFractions: false,\n  tolerance: defaultTolerance,\n  fractionSlash: false,\n  romanNumerals: false,\n} satisfies Required<FormatQuantityOptions>;\n\n/**\n * A map of vulgar or simple sixteenth fractions to their traditional ASCII\n * equivalents. Sixteenths map to themselves.\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} satisfies Record<VulgarFraction, SimpleFraction>;\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\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\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  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 the [documentation](https://jakeboone02.github.io/format-quantity/).\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 = Object.hasOwn(vulgarToAsciiMap, fraction)\n        ? flooredAbsValStr.trim()\n        : flooredAbsValStr;\n      return `${int}${fraction}`;\n    }\n  }\n\n  return `${qtyAsNumber}`;\n};\n"],"mappings":"yaAAA,IAAAA,EAAA,GAAAC,EAAAD,EAAA,aAAAE,EAAA,mBAAAC,EAAA,qBAAAC,EAAA,mBAAAC,EAAA,2BAAAC,EAAA,qBAAAC,IAAA,eAAAC,EAAAR,GCOO,IAAMS,EAAmB,MAEnBC,EAAiB,CAC5B,gBAAiB,GACjB,UAAW,MACX,cAAe,GACf,cAAe,EACjB,EAMaC,EAAmB,CAC9B,OAAK,MACL,OAAK,MACL,OAAK,MACL,SAAK,MACL,SAAK,MACL,SAAK,OACL,SAAK,MACL,SAAK,MACL,SAAK,MACL,SAAK,MACL,SAAK,MACL,SAAK,MACL,SAAK,MACL,SAAK,MACL,SAAK,MACL,SAAK,MACL,SAAK,MACL,SAAK,KACP,EAEaC,EAAyB,CACpC,CAAC,IAAM,QAAG,EACV,CAAC,IAAM,QAAG,EACV,CAAC,GAAK,QAAG,EACT,CAAC,GAAK,QAAG,EACT,CAAC,GAAK,QAAG,EACT,CAAC,GAAK,QAAG,EACT,CAAC,KAAO,QAAG,EACX,CAAC,KAAO,QAAG,EACX,CAAC,KAAO,QAAG,EACX,CAAC,KAAO,QAAG,EACX,CAAC,GAAK,QAAG,EACT,CAAC,KAAO,QAAG,EACX,CAAC,IAAM,MAAG,EACV,CAAC,KAAO,QAAG,EACX,CAAC,GAAK,MAAG,EACT,CAAC,KAAO,QAAG,EACX,CAAC,IAAM,MAAG,EACV,CAAC,KAAO,QAAG,EACX,CAAC,MAAQ,MAAM,EACf,CAAC,MAAQ,MAAM,EACf,CAAC,MAAQ,MAAM,EACf,CAAC,MAAQ,MAAM,EACf,CAAC,MAAQ,MAAM,EACf,CAAC,MAAQ,OAAO,EAChB,CAAC,MAAQ,OAAO,EAChB,CAAC,MAAQ,OAAO,CAClB,ECnDA,IAAMC,EAAc,CAACC,EAAYC,EAAYC,IAC3C,KAAK,IAAIF,EAAKC,CAAE,EAAIC,EAEhBC,EAAc,CAClBC,EACA,CAAE,cAAAC,EAAe,gBAAAC,CAAgB,IAC9B,CACH,GAAIA,EACF,OAAOF,EAGT,IAAMG,EACJC,EAAiBJ,CAA2C,GAC5DA,EAEF,OAAIC,EACKE,EAAc,QAAQ,IAAK,QAAG,EAGhCA,CACT,EAEME,EACJC,IACqC,CACrC,GAAGC,EACH,GAAI,OAAOD,GAAY,UAAY,CAAE,gBAAiBA,CAAQ,EAAIA,CACpE,GAGME,EAAuB,CAC3B,GAAI,IAAK,KAAM,MAAO,KAAM,IAAK,KAAM,MAAO,OAAQ,KACtD,GAAI,IAAK,KAAM,MAAO,KAAM,IAAK,KAAM,MAAO,OAAQ,KACtD,GAAI,IAAK,KAAM,MAAO,KAAM,IAAK,KAAM,MAAO,OAAQ,IACxD,EAMaC,EAAuBC,GAAgB,CAClD,GAAI,OAAOA,GAAQ,UAAY,MAAMA,CAAG,EACtC,OAAO,KAGT,GAAIA,EAAM,GAAKA,GAAO,IACpB,MAAO,GAKT,IAAMC,EAAS,GAFC,KAAK,MAAMD,CAAG,IAEF,MAAM,EAAE,EAChCE,EAAQ,GACRC,EAAI,EACR,KAAOA,KACLD,EAAQ,GAAGJ,EAAqB,CAACG,EAAO,IAAI,EAAKE,EAAI,EAAE,GAAK,KAAKD,IAEnE,MAAO,GAAG,MAAM,CAACD,EAAO,KAAK,EAAE,EAAI,CAAC,EAAE,KAAK,GAAG,IAAIC,GACpD,EASaE,EAAiC,CAC5CJ,EACAJ,EAAUC,IACP,CAEH,IAAMQ,EAAc,OAAOL,GAAQ,SAAW,WAAWA,CAAG,EAAIA,EAGhE,GAAI,MAAMK,CAAW,GAAKA,IAAgB,KACxC,OAAO,KAIT,GAAIA,IAAgB,EAClB,MAAO,GAMT,IAAMC,EAAOX,EAAiBC,GAAWC,CAAc,EAEvD,GAAIS,EAAK,cACP,OAAOP,EAAoBM,CAAW,EAGxC,IAAME,EAAgB,KAAK,IAAIF,CAAW,EACpCG,EAAgB,KAAK,MAAMD,CAAa,EACxCE,EAAmB,GAAGJ,EAAc,EAAI,IAAM,KAClDG,IAAkB,EAAI,GAAK,GAAGA,OAE1BE,EAAeH,EAAgBC,EAGrC,GAAIE,IAAiB,EACnB,MAAO,GAAGL,IAGZ,OAAW,CAACM,EAAKC,CAAE,IAAKC,EACtB,GAAI5B,EAAYyB,EAAcC,EAAKL,EAAK,SAAS,EAAG,CAClD,IAAMQ,EAAWzB,EAAYuB,EAAIN,CAAI,EAIrC,MAAO,GAHK,OAAO,OAAOZ,EAAkBoB,CAAQ,EAChDL,EAAiB,KAAK,EACtBA,IACYK,IAIpB,MAAO,GAAGT,GACZ,EFjIA,IAAOU,EAAQC","names":["src_exports","__export","src_default","defaultOptions","defaultTolerance","formatQuantity","fractionDecimalMatches","vulgarToAsciiMap","__toCommonJS","defaultTolerance","defaultOptions","vulgarToAsciiMap","fractionDecimalMatches","closeEnough","n1","n2","tolerance","getFraction","vulgarFractionOrSixteenth","fractionSlash","vulgarFractions","plainFraction","vulgarToAsciiMap","normalizeOptions","options","defaultOptions","romanNumeralValueKey","formatRomanNumerals","qty","digits","roman","i","formatQuantity","qtyAsNumber","opts","absoluteValue","flooredAbsVal","flooredAbsValStr","decimalValue","num","vf","fractionDecimalMatches","fraction","src_default","formatQuantity"]}
+{"version":3,"file":"format-quantity.cjs.production.js","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: ResolvedFormatQuantityOptions = {\n  vulgarFractions: false,\n  tolerance: defaultTolerance,\n  fractionSlash: false,\n  romanNumerals: false,\n} as const;\n\n/**\n * Map of vulgar fractions to their traditional ASCII equivalents.\n */\nexport const vulgarToAsciiMap: Record<VulgarFraction, SimpleFraction> = {\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;\n\n/**\n * Map of \"close enough\" decimal values to the {@link VulgarFraction} or\n * {@link Sixteenth} fraction string matches.\n */\nexport const fractionDecimalMatches: [number, VulgarFraction | Sixteenth][] = [\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] as const;\n","import { numericQuantity } from 'numeric-quantity';\nimport {\n  defaultOptions,\n  fractionDecimalMatches,\n  vulgarToAsciiMap,\n} from './constants';\nimport type {\n  FormatQuantity,\n  FormatQuantityOptions,\n  ResolvedFormatQuantityOptions,\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\nconst superscriptDigits = '⁰¹²³⁴⁵⁶⁷⁸⁹';\nconst subscriptDigits = '₀₁₂₃₄₅₆₇₈₉';\n\nconst toSuperscript = (s: string) => {\n  let r = '';\n  for (let i = 0; i < s.length; i++) r += superscriptDigits[+s[i]];\n  return r;\n};\nconst toSubscript = (s: string) => {\n  let r = '';\n  for (let i = 0; i < s.length; i++) r += subscriptDigits[+s[i]];\n  return r;\n};\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    const [num, den] = plainFraction.split('/');\n    return `${toSuperscript(num)}⁄${toSubscript(den)}`;\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): ResolvedFormatQuantityOptions => ({\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): string | null => {\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  const qtyAsNumber =\n    typeof qty === 'string'\n      ? numericQuantity(qty, { round: false, allowTrailingInvalid: true })\n      : 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  // TODO: Consider a `zeroDisplay` option (e.g. `{ zeroDisplay: \"0\" }`) so\n  // callers outside the recipe-ingredient use case can get \"0\" instead of \"\".\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 sign = qtyAsNumber < 0 ? '-' : '';\n  const wholeStr = flooredAbsVal === 0 ? '' : `${flooredAbsVal}`;\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 isVulgar = fraction in vulgarToAsciiMap;\n      const sep = wholeStr\n        ? (opts.separator ?? (isVulgar ? '' : ' '))\n        : '';\n      return `${sign}${wholeStr}${sep}${fraction}`;\n    }\n  }\n\n  return `${qtyAsNumber}`;\n};\n"],"mappings":"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"}

package/dist/cjs/index.d.ts

@@ -0,0 +1 @@
+export * from './format-quantity.cjs.development.js';

package/dist/format-quantity.d.mts

@@ -0,0 +1,107 @@
+//#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;
+  /**
+  * 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;
+}
+/**
+* {@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;
+}
+/** 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).
+*/
+type SimpleFraction = `${NonZeroDigit}/${NonZeroDigit}` | `${NonZeroDigit}/${NonZeroDigit}${Digit}` | `${NonZeroDigit}${Digit}/${NonZeroDigit}${Digit}`;
+/**
+* Odd numerator sixteenth fraction strings.
+*/
+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]])[]>;
+//#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.
+*/
+declare const defaultTolerance: 0.0075;
+/**
+* Default options for {@link formatQuantity}.
+*/
+declare const defaultOptions: ResolvedFormatQuantityOptions;
+/**
+* Map of vulgar fractions to their traditional ASCII equivalents.
+*/
+declare const vulgarToAsciiMap: 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][];
+//#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 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 };
+//# sourceMappingURL=format-quantity.d.mts.map

package/dist/format-quantity.iife.umd.min.js

@@ -0,0 +1,2 @@
+var FormatQuantity=(function(e,t){Object.defineProperty(e,Symbol.toStringTag,{value:`Module`});let n=.0075,r={vulgarFractions:!1,tolerance:n,fractionSlash:!1,romanNumerals:!1},i={"¼":`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`},a=[[.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`]],o=(e,t,n)=>Math.abs(e-t)<n,s=e=>{let t=``;for(let n=0;n<e.length;n++)t+=`⁰¹²³⁴⁵⁶⁷⁸⁹`[+e[n]];return t},c=e=>{let t=``;for(let n=0;n<e.length;n++)t+=`₀₁₂₃₄₅₆₇₈₉`[+e[n]];return t},l=(e,{fractionSlash:t,vulgarFractions:n})=>{if(n)return e;let r=i[e]??e;if(t){let[e,t]=r.split(`/`);return`${s(e)}⁄${c(t)}`}return r},u=e=>({...r,...typeof e==`boolean`?{vulgarFractions:e}:e}),d=`.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`.split(`.`),f=e=>{if(typeof e!=`number`||isNaN(e))return null;if(e<1||e>=4e3)return``;let t=`${Math.floor(e)}`.split(``),n=``,r=3;for(;r--;)n=`${d[+t.pop()+r*10]||``}${n}`;return`${Array(+t.join(``)+1).join(`M`)}${n}`};return e.defaultOptions=r,e.defaultTolerance=n,e.formatQuantity=(e,n=r)=>{let s=typeof e==`string`?(0,t.numericQuantity)(e,{round:!1,allowTrailingInvalid:!0}):e;if(isNaN(s)||s===null)return null;if(s===0)return``;let c=u(n??r);if(c.romanNumerals)return f(s);let d=Math.abs(s),p=Math.floor(d),m=s<0?`-`:``,h=p===0?``:`${p}`,g=d-p;if(g===0)return`${s}`;for(let[e,t]of a)if(o(g,e,c.tolerance)){let e=l(t,c),n=e in i;return`${m}${h}${h?c.separator??(n?``:` `):``}${e}`}return`${s}`},e.formatRomanNumerals=f,e.fractionDecimalMatches=a,e.vulgarToAsciiMap=i,e})({},numeric_quantity);
+//# sourceMappingURL=format-quantity.iife.umd.min.js.map

package/dist/format-quantity.iife.umd.min.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format-quantity.iife.umd.min.js","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: ResolvedFormatQuantityOptions = {\n  vulgarFractions: false,\n  tolerance: defaultTolerance,\n  fractionSlash: false,\n  romanNumerals: false,\n} as const;\n\n/**\n * Map of vulgar fractions to their traditional ASCII equivalents.\n */\nexport const vulgarToAsciiMap: Record<VulgarFraction, SimpleFraction> = {\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;\n\n/**\n * Map of \"close enough\" decimal values to the {@link VulgarFraction} or\n * {@link Sixteenth} fraction string matches.\n */\nexport const fractionDecimalMatches: [number, VulgarFraction | Sixteenth][] = [\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] as const;\n","import { numericQuantity } from 'numeric-quantity';\nimport {\n  defaultOptions,\n  fractionDecimalMatches,\n  vulgarToAsciiMap,\n} from './constants';\nimport type {\n  FormatQuantity,\n  FormatQuantityOptions,\n  ResolvedFormatQuantityOptions,\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\nconst superscriptDigits = '⁰¹²³⁴⁵⁶⁷⁸⁹';\nconst subscriptDigits = '₀₁₂₃₄₅₆₇₈₉';\n\nconst toSuperscript = (s: string) => {\n  let r = '';\n  for (let i = 0; i < s.length; i++) r += superscriptDigits[+s[i]];\n  return r;\n};\nconst toSubscript = (s: string) => {\n  let r = '';\n  for (let i = 0; i < s.length; i++) r += subscriptDigits[+s[i]];\n  return r;\n};\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    const [num, den] = plainFraction.split('/');\n    return `${toSuperscript(num)}⁄${toSubscript(den)}`;\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): ResolvedFormatQuantityOptions => ({\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): string | null => {\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  const qtyAsNumber =\n    typeof qty === 'string'\n      ? numericQuantity(qty, { round: false, allowTrailingInvalid: true })\n      : 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  // TODO: Consider a `zeroDisplay` option (e.g. `{ zeroDisplay: \"0\" }`) so\n  // callers outside the recipe-ingredient use case can get \"0\" instead of \"\".\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 sign = qtyAsNumber < 0 ? '-' : '';\n  const wholeStr = flooredAbsVal === 0 ? '' : `${flooredAbsVal}`;\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 isVulgar = fraction in vulgarToAsciiMap;\n      const sep = wholeStr\n        ? (opts.separator ?? (isVulgar ? '' : ' '))\n        : '';\n      return `${sign}${wholeStr}${sep}${fraction}`;\n    }\n  }\n\n  return `${qtyAsNumber}`;\n};\n"],"mappings":"+FAWA,IAAa,EAAmB,MAKnB,EAAgD,CAC3D,gBAAiB,GACjB,UAAW,EACX,cAAe,GACf,cAAe,GAChB,CAKY,EAA2D,CACtE,IAAK,MACL,IAAK,MACL,IAAK,MACL,IAAK,MACL,IAAK,MACL,IAAK,OACL,IAAK,MACL,IAAK,MACL,IAAK,MACL,IAAK,MACL,IAAK,MACL,IAAK,MACL,IAAK,MACL,IAAK,MACL,IAAK,MACL,IAAK,MACL,IAAK,MACL,IAAK,MACN,CAMY,EAAiE,CAC5E,CAAC,IAAM,IAAI,CACX,CAAC,IAAM,IAAI,CACX,CAAC,GAAK,IAAI,CACV,CAAC,GAAK,IAAI,CACV,CAAC,GAAK,IAAI,CACV,CAAC,GAAK,IAAI,CACV,CAAC,KAAO,IAAI,CACZ,CAAC,KAAO,IAAI,CACZ,CAAC,KAAO,IAAI,CACZ,CAAC,KAAO,IAAI,CACZ,CAAC,GAAK,IAAI,CACV,CAAC,KAAO,IAAI,CACZ,CAAC,IAAM,IAAI,CACX,CAAC,KAAO,IAAI,CACZ,CAAC,GAAK,IAAI,CACV,CAAC,KAAO,IAAI,CACZ,CAAC,IAAM,IAAI,CACX,CAAC,KAAO,IAAI,CACZ,CAAC,MAAQ,OAAO,CAChB,CAAC,MAAQ,OAAO,CAChB,CAAC,MAAQ,OAAO,CAChB,CAAC,MAAQ,OAAO,CAChB,CAAC,MAAQ,OAAO,CAChB,CAAC,MAAQ,QAAQ,CACjB,CAAC,MAAQ,QAAQ,CACjB,CAAC,MAAQ,QAAQ,CAClB,CC3DK,GAAe,EAAY,EAAY,IAC3C,KAAK,IAAI,EAAK,EAAG,CAAG,EAKhB,EAAiB,GAAc,CACnC,IAAI,EAAI,GACR,IAAK,IAAI,EAAI,EAAG,EAAI,EAAE,OAAQ,IAAK,GAAK,aAAkB,CAAC,EAAE,IAC7D,OAAO,GAEH,EAAe,GAAc,CACjC,IAAI,EAAI,GACR,IAAK,IAAI,EAAI,EAAG,EAAI,EAAE,OAAQ,IAAK,GAAK,aAAgB,CAAC,EAAE,IAC3D,OAAO,GAMH,GACJ,EACA,CAAE,gBAAe,qBACd,CACH,GAAI,EACF,OAAO,EAGT,IAAM,EACJ,EAAiB,IACjB,EAEF,GAAI,EAAe,CACjB,GAAM,CAAC,EAAK,GAAO,EAAc,MAAM,IAAI,CAC3C,MAAO,GAAG,EAAc,EAAI,CAAC,GAAG,EAAY,EAAI,GAGlD,OAAO,GAMH,EACJ,IACmC,CACnC,GAAG,EACH,GAAI,OAAO,GAAY,UAAY,CAAE,gBAAiB,EAAS,CAAG,EACnE,EAGK,EAAuB,sGAI5B,CAMY,EAAuB,GAA+B,CACjE,GAAI,OAAO,GAAQ,UAAY,MAAM,EAAI,CACvC,OAAO,KAGT,GAAI,EAAM,GAAK,GAAO,IACpB,MAAO,GAKT,IAAM,EAAS,GAFC,KAAK,MAAM,EAAI,GAEH,MAAM,GAAG,CACjC,EAAQ,GACR,EAAI,EACR,KAAO,KACL,EAAQ,GAAG,EAAqB,CAAC,EAAO,KAAK,CAAI,EAAI,KAAO,KAAK,IAGnE,MAAO,GAAG,MAAM,CAAC,EAAO,KAAK,GAAG,CAAG,EAAE,CAAC,KAAK,IAAI,GAAG,sEAWlD,EACA,EAAU,IACP,CACH,IAAM,EACJ,OAAO,GAAQ,UAAA,EAAA,EAAA,iBACK,EAAK,CAAE,MAAO,GAAO,qBAAsB,GAAM,CAAC,CAClE,EAGN,GAAI,MAAM,EAAY,EAAI,IAAgB,KACxC,OAAO,KAMT,GAAI,IAAgB,EAClB,MAAO,GAMT,IAAM,EAAO,EAAiB,GAAW,EAAe,CAExD,GAAI,EAAK,cACP,OAAO,EAAoB,EAAY,CAGzC,IAAM,EAAgB,KAAK,IAAI,EAAY,CACrC,EAAgB,KAAK,MAAM,EAAc,CACzC,EAAO,EAAc,EAAI,IAAM,GAC/B,EAAW,IAAkB,EAAI,GAAK,GAAG,IACzC,EAAe,EAAgB,EAGrC,GAAI,IAAiB,EACnB,MAAO,GAAG,IAGZ,IAAK,GAAM,CAAC,EAAK,KAAO,EACtB,GAAI,EAAY,EAAc,EAAK,EAAK,UAAU,CAAE,CAClD,IAAM,EAAW,EAAY,EAAI,EAAK,CAChC,EAAW,KAAY,EAI7B,MAAO,GAAG,IAAO,IAHL,EACP,EAAK,YAAc,EAAW,GAAK,KACpC,KAC8B,IAItC,MAAO,GAAG"}

package/dist/format-quantity.legacy-esm.d.ts

@@ -0,0 +1,107 @@
+//#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;
+  /**
+  * 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;
+}
+/**
+* {@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;
+}
+/** 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).
+*/
+type SimpleFraction = `${NonZeroDigit}/${NonZeroDigit}` | `${NonZeroDigit}/${NonZeroDigit}${Digit}` | `${NonZeroDigit}${Digit}/${NonZeroDigit}${Digit}`;
+/**
+* Odd numerator sixteenth fraction strings.
+*/
+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]])[]>;
+//#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.
+*/
+declare const defaultTolerance: 0.0075;
+/**
+* Default options for {@link formatQuantity}.
+*/
+declare const defaultOptions: ResolvedFormatQuantityOptions;
+/**
+* Map of vulgar fractions to their traditional ASCII equivalents.
+*/
+declare const vulgarToAsciiMap: 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][];
+//#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 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 };
+//# sourceMappingURL=format-quantity.legacy-esm.d.ts.map