format-quantity 3.0.0 → 3.2.0

package/README.md

@@ -1,18 +1,20 @@
 [![npm][badge-npm]](https://www.npmjs.com/package/format-quantity)
 ![workflow status](https://github.com/jakeboone02/format-quantity/actions/workflows/main.yml/badge.svg)
 [![codecov.io](https://codecov.io/github/jakeboone02/format-quantity/coverage.svg?branch=main)](https://codecov.io/github/jakeboone02/format-quantity?branch=main)
-[![downloads](https://img.shields.io/npm/dm/format-quantity.svg)](http://npm-stat.com/charts.html?package=format-quantity&from=2015-08-01)
-[![MIT License](https://img.shields.io/npm/l/format-quantity.svg)](http://opensource.org/licenses/MIT)
+[![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.
-- The return value will be `null` if the first argument is neither a number nor a string that evaluates to a number using `parseFloat`.
-- 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._
 >
@@ -58,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.
@@ -74,33 +76,87 @@ 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"`). This option is ignored if the `vulgarFractions` option is also `true`.
+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`.
 
 ```js
-formatQuantity(3.875, { fractionSlash: true }); // "3 7⁄8"
+formatQuantity(3.875, { fractionSlash: true }); // "3 ⁷⁄₈"
 formatQuantity(3.875, { fractionSlash: true, vulgarFractions: true }); // "3⅞"
 ```
 
+### `separator`
+
+| Type     | Default |
+| -------- | ------- |
+| `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"`).
+
+```js
+formatQuantity(1.5, { separator: '-' }); // "1-1/2"
+formatQuantity(1.5, { separator: ' ', vulgarFractions: true }); // "1 ½"
+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`
@@ -109,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,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.cjs.development.d.ts.map