shelving 1.162.1 → 1.163.0

package/package.json

@@ -11,7 +11,7 @@
 		"state-management",
 		"query-builder"
 	],
-	"version": "1.162.1",
+	"version": "1.163.0",
 	"repository": "https://github.com/dhoulb/shelving",
 	"author": "Dave Houlbrooke <dave@shax.com>",
 	"license": "0BSD",

package/util/format.d.ts

@@ -2,23 +2,60 @@ import { type ImmutableArray } from "./array.js";
 import { type PossibleDate } from "./date.js";
 import { type ImmutableObject } from "./object.js";
 import { type PossibleURL } from "./url.js";
-/** Format a number range (based on the user's browser language settings). */
-export declare function formatRange(min: number, max: number, options?: Intl.NumberFormatOptions): string;
-/** Format a number with a short suffix, e.g. `1,000 kg` */
-export declare function formatQuantity(num: number, suffix: string, options?: Intl.NumberFormatOptions): string;
+/** Options we use for number formatting. */
+export type NumberOptions = Omit<Intl.NumberFormatOptions, "style" | "unit" | "unitDisplay" | "currency" | "currencyDisplay" | "currencySign">;
 /** Format a number (based on the user's browser language settings). */
-export declare function formatNumber(num: number, options?: Intl.NumberFormatOptions): string;
-/** Format a number with a longer full-word suffix. */
-export declare function pluralizeQuantity(num: number, one: string, many: string, options?: Intl.NumberFormatOptions): string;
+export declare function formatNumber(num: number, options?: NumberOptions): string;
+/** Format a number range (based on the user's browser language settings). */
+export declare function formatRange(from: number, to: number, options?: NumberOptions): string;
+/** Options for quantity formatting. */
+export interface QuantityOptions extends Omit<Intl.NumberFormatOptions, "style" | "unit" | "currency" | "currencyDisplay" | "currencySign"> {
+    /**
+     * String for one of this thing, e.g. `product` or `item` or `sheep`
+     * - Used for `unitDisplay: "long"` formatting.
+     * - Defaults to unit reference, e.g. "minute"
+     */
+    readonly one?: string;
+    /**
+     * String for several of this thing, e.g. `products` or `items` or `sheep`
+     * - Used for `unitDisplay: "long"` formatting.
+     * - Defaults to `one + "s"`
+     */
+    readonly many?: string;
+    /**
+     * Abbreviation for this thing, e.g. `products` or `items` or `sheep` (defaults to `one` + "s").
+     * - Used for `unitDisplay: "narrow"` formatting.
+     * - Defaults to unit reference, e.g. "minute"
+     */
+    readonly abbr?: string;
+}
+/**
+ * Format a quantity of a given unit.
+ *
+ * - Javascript has built-in support for formatting a number of different units.
+ * - Unfortunately the list of supported units changes in different browsers.
+ * - Ideally we want to format units using the built-in formatting so things like translation and internationalisation are covered.
+ * - But we want provide fallback formatting for unsupported units, and do something _good enough_ job in most cases.
+ */
+export declare function formatUnit(num: number, unit: string, options?: QuantityOptions): string;
+/** Options we use for currency formatting. */
+export type CurrencyOptions = Omit<Intl.NumberFormatOptions, "style" | "unit" | "unitDisplay" | "currency">;
+/**
+ * Format a currency amount (based on the user's browser language settings).
+ */
+export declare function formatCurrency(amount: number, currency: string, options?: CurrencyOptions): string;
+/** Options we use for percent formatting. */
+export type PercentOptions = Omit<Intl.NumberFormatOptions, "style" | "unit" | "unitDisplay" | "currency" | "currencyDisplay" | "currencySign">;
 /**
  * Format a percentage (combines `getPercent()` and `formatQuantity()` for convenience).
  * - Defaults to showing no decimal places.
  * - Defaults to rounding closer to zero (so that 99.99% is shown as 99%).
+ * - Javascript's built-in percent formatting works on the `0` zero to `1` range. This uses `getPercent()` which works on `0` to `100` for convenience.
  *
- * @param numerator Number representing the amount of progress.
- * @param denumerator The number representing the whole amount.
+ * @param numerator Number representing the amount of progress (e.g. `50`).
+ * @param denumerator The number representing the whole amount (defaults to 100).
  */
-export declare function formatPercent(numerator: number, denumerator: number, options?: Intl.NumberFormatOptions): string;
+export declare function formatPercent(numerator: number, denumerator?: number, options?: PercentOptions): string;
 /**
  * Format an unknown object as a string.
  * - Use the custom `.toString()` function if it exists (don't use built in `Object.prototype.toString` because it's useless.

package/util/format.js

@@ -1,49 +1,61 @@
 import { isArray } from "./array.js";
-import { NNBSP } from "./constants.js";
 import { isDate, requireDate } from "./date.js";
 import { getPercent } from "./number.js";
 import { isObject } from "./object.js";
 import { requireURL } from "./url.js";
-/** Format a number range (based on the user's browser language settings). */
-export function formatRange(min, max, options) {
-    return `${formatNumber(min, options)}${NNBSP}–${NNBSP}${formatNumber(max, options)}`;
-}
-/** Format a number with a short suffix, e.g. `1,000 kg` */
-export function formatQuantity(num, suffix, options) {
-    const o = { unitDisplay: "short", ...options, style: "decimal" };
-    const str = formatNumber(num, o);
-    const sep = o.unitDisplay === "narrow" ? "" : NNBSP;
-    return `${str}${sep}${suffix}`;
-}
 /** Format a number (based on the user's browser language settings). */
 export function formatNumber(num, options) {
-    if (!Number.isFinite(num))
-        return Number.isNaN(num) ? "-" : "∞";
-    return new Intl.NumberFormat(undefined, options).format(num).replace(/ /, NNBSP);
+    return Intl.NumberFormat(undefined, options).format(num);
+}
+/** Format a number range (based on the user's browser language settings). */
+export function formatRange(from, to, options) {
+    return Intl.NumberFormat(undefined, options).formatRange(from, to);
 }
-/** Format a number with a longer full-word suffix. */
-export function pluralizeQuantity(num, one, many, options) {
-    const qty = formatNumber(num, {
+/**
+ * Format a quantity of a given unit.
+ *
+ * - Javascript has built-in support for formatting a number of different units.
+ * - Unfortunately the list of supported units changes in different browsers.
+ * - Ideally we want to format units using the built-in formatting so things like translation and internationalisation are covered.
+ * - But we want provide fallback formatting for unsupported units, and do something _good enough_ job in most cases.
+ */
+export function formatUnit(num, unit, options) {
+    // Check if the unit is supported by the browser.
+    if (Intl.supportedValuesOf("unit").includes(unit))
+        return Intl.NumberFormat(undefined, { ...options, style: "unit", unit }).format(num);
+    // Otherwise, use the default number format.
+    const str = Intl.NumberFormat(undefined, { ...options, style: "decimal" }).format(num);
+    const { unitDisplay, abbr = unit, one = unit, many = `${one}s` } = options ?? {};
+    if (unitDisplay === "long")
+        return `${str} ${str === "1" ? one : many}`;
+    return `${str}${unitDisplay === "narrow" ? "" : " "}${abbr}`; // "short" is the default.
+}
+/**
+ * Format a currency amount (based on the user's browser language settings).
+ */
+export function formatCurrency(amount, currency, options) {
+    return Intl.NumberFormat(undefined, {
+        style: "currency",
+        currency,
         ...options,
-        style: "decimal",
-    });
-    return `${qty}${NNBSP}${num === 1 ? one : many}`;
+    }).format(amount);
 }
 /**
  * Format a percentage (combines `getPercent()` and `formatQuantity()` for convenience).
  * - Defaults to showing no decimal places.
  * - Defaults to rounding closer to zero (so that 99.99% is shown as 99%).
+ * - Javascript's built-in percent formatting works on the `0` zero to `1` range. This uses `getPercent()` which works on `0` to `100` for convenience.
  *
- * @param numerator Number representing the amount of progress.
- * @param denumerator The number representing the whole amount.
+ * @param numerator Number representing the amount of progress (e.g. `50`).
+ * @param denumerator The number representing the whole amount (defaults to 100).
  */
 export function formatPercent(numerator, denumerator, options) {
-    return formatNumber(getPercent(numerator, denumerator), {
+    return Intl.NumberFormat(undefined, {
+        style: "percent",
         maximumFractionDigits: 0,
-        roundingMode: "trunc",
+        roundingMode: "floor",
         ...options,
-        style: "percent",
-    });
+    }).format(getPercent(numerator, denumerator) / 100);
 }
 /**
  * Format an unknown object as a string.

package/util/number.d.ts

@@ -92,9 +92,9 @@ export declare function wrapNumber(num: number, min: number, max: number): numbe
  * Get a number as a percentage of another number.
  *
  * @param numerator Number representing the amount of progress.
- * @param denumerator The number representing the whole amount.
+ * @param denumerator The number representing the whole amount (defaults to 100).
  */
-export declare function getPercent(numerator: number, denumerator: number): number;
+export declare function getPercent(numerator: number, denumerator?: number): number;
 /** Sum an iterable set of numbers and return the total. */
 export declare function sumNumbers(nums: Iterable<number>): number;
 /** Find the number that's closest to a target in an iterable set of numbers. */

package/util/number.js

@@ -144,10 +144,10 @@ export function wrapNumber(num, min, max) {
  * Get a number as a percentage of another number.
  *
  * @param numerator Number representing the amount of progress.
- * @param denumerator The number representing the whole amount.
+ * @param denumerator The number representing the whole amount (defaults to 100).
  */
-export function getPercent(numerator, denumerator) {
-    return Math.max(0, Math.min(100, (100 / denumerator) * numerator));
+export function getPercent(numerator, denumerator = 100) {
+    return denumerator === 100 ? numerator : (100 / denumerator) * numerator;
 }
 /** Sum an iterable set of numbers and return the total. */
 export function sumNumbers(nums) {

package/util/units.d.ts

@@ -1,3 +1,4 @@
+import { type QuantityOptions } from "./format.js";
 import { ImmutableMap, type MapKey } from "./map.js";
 import type { ImmutableObject } from "./object.js";
 /** Conversion from one unit to another (either an amount to multiple by, or a function to convert). */
@@ -6,18 +7,10 @@ type Conversion = number | ((num: number) => number);
 type Conversions<T extends string> = {
     readonly [K in T]?: Conversion;
 };
-type UnitProps<T extends string> = {
-    /** Short abbreviation for this unit, e.g. `km` (defaults to first letter of `id`). */
-    readonly abbr?: string;
-    /** Singular name for this unit, e.g. `kilometer` (defaults to `id` + "s"). */
-    readonly one?: string;
-    /** Plural name for this unit, e.g. `kilometers` (defaults to `id`). */
-    readonly many?: string;
+interface UnitProps<T extends string> extends QuantityOptions {
     /** Conversions to other units (typically needs at least the base conversion, unless it's already the base unit). */
     readonly to?: Conversions<T>;
-    /** Possible options for formatting these units with `Intl.NumberFormat` (`.unit` can be specified if different from key, but is not required). */
-    readonly options?: Readonly<Intl.NumberFormatOptions> | undefined;
-};
+}
 /** Represent a unit. */
 export declare class Unit<K extends string> {
     private readonly _to;
@@ -25,23 +18,15 @@ export declare class Unit<K extends string> {
     readonly list: UnitList<K>;
     /** String key for this unit, e.g. `kilometer` */
     readonly key: K;
-    /** Short abbreviation for this unit, e.g. `km` (defaults to first letter of `id`). */
-    readonly abbr: string;
-    /** Singular name for this unit, e.g. `kilometer` (defaults to `id`). */
-    readonly one: string;
-    /** Plural name for this unit, e.g. `kilometers` (defaults to `singular` + "s"). */
-    readonly many: string;
-    /** Possible options for formatting these units with `Intl.NumberFormat` (`.unit` can be specified if different from key, but is not required). */
-    readonly options: Readonly<Intl.NumberFormatOptions> | undefined;
-    /** Title for this unit (uses format `abbr (plural)`, e.g. `fl oz (US fluid ounces)`) */
-    get title(): string;
+    /** Possible options for formatting these units. */
+    readonly options: Readonly<QuantityOptions> | undefined;
     constructor(
     /** `UnitList` this unit belongs to. */
     list: UnitList<K>, 
     /** String key for this unit, e.g. `kilometer` */
     key: K, 
     /** Props to configure this unit. */
-    { abbr, one, many, options, to }: UnitProps<K>);
+    { to, ...options }: UnitProps<K>);
     /** Convert an amount from this unit to another unit. */
     to(amount: number, targetKey?: K): number;
     /** Convert an amount from another unit to this unit. */
@@ -53,7 +38,7 @@ export declare class Unit<K extends string> {
      * - Uses `Intl.NumberFormat` if this is a supported unit (so e.g. `ounce` is translated to e.g. `Unze` in German).
      * - Polyfills unsupported units to use long/short form based on `options.unitDisplay`.
      */
-    format(amount: number, options?: Intl.NumberFormatOptions): string;
+    format(amount: number, options?: QuantityOptions): string;
 }
 /**
  * Represent a list of units.

package/util/units.js

@@ -1,7 +1,7 @@
 import { RequiredError } from "../error/RequiredError.js";
 import { ValueError } from "../error/ValueError.js";
 import { DAY, HOUR, MILLION, MINUTE, MONTH, NNBSP, SECOND, WEEK, YEAR } from "./constants.js";
-import { formatNumber, formatQuantity, pluralizeQuantity } from "./format.js";
+import { formatUnit } from "./format.js";
 import { ImmutableMap } from "./map.js";
 import { getProps } from "./object.js";
 /** Convert an amount using a `Conversion. */
@@ -15,30 +15,17 @@ export class Unit {
     list;
     /** String key for this unit, e.g. `kilometer` */
     key;
-    /** Short abbreviation for this unit, e.g. `km` (defaults to first letter of `id`). */
-    abbr;
-    /** Singular name for this unit, e.g. `kilometer` (defaults to `id`). */
-    one;
-    /** Plural name for this unit, e.g. `kilometers` (defaults to `singular` + "s"). */
-    many;
-    /** Possible options for formatting these units with `Intl.NumberFormat` (`.unit` can be specified if different from key, but is not required). */
+    /** Possible options for formatting these units. */
     options;
-    /** Title for this unit (uses format `abbr (plural)`, e.g. `fl oz (US fluid ounces)`) */
-    get title() {
-        return `${this.abbr} (${this.many})`;
-    }
     constructor(
     /** `UnitList` this unit belongs to. */
     list, 
     /** String key for this unit, e.g. `kilometer` */
     key, 
     /** Props to configure this unit. */
-    { abbr = key.slice(0, 1), one = key.replace(/-/, " "), many = `${one}s`, options, to }) {
+    { to, ...options }) {
         this.list = list;
         this.key = key;
-        this.abbr = abbr;
-        this.one = one;
-        this.many = many;
         this.options = options;
         this._to = to;
     }
@@ -83,13 +70,7 @@ export class Unit {
      * - Polyfills unsupported units to use long/short form based on `options.unitDisplay`.
      */
     format(amount, options) {
-        // If possible use `Intl` so that the user's locale is used.
-        if (Intl.supportedValuesOf("unit").includes(this.key))
-            return formatNumber(amount, { style: "unit", unitDisplay: "short", ...this.options, ...options, unit: this.key });
-        // Otherwise, use the default number format.
-        // If unitDisplay is "long" use the singular/plural form.
-        const o = { style: "decimal", unitDisplay: "short", ...this.options, ...options };
-        return o.unitDisplay === "long" ? pluralizeQuantity(amount, this.one, this.many, o) : formatQuantity(amount, this.abbr, o);
+        return formatUnit(amount, this.key, { ...this.options, ...options });
     }
 }
 /**
@@ -185,14 +166,14 @@ const TIME_OPTIONS = {
 };
 /** Time units. */
 export const TIME_UNITS = new UnitList({
-    millisecond: { abbr: "ms", options: TIME_OPTIONS },
-    second: { to: { millisecond: SECOND }, options: TIME_OPTIONS },
-    minute: { to: { millisecond: MINUTE }, options: TIME_OPTIONS },
-    hour: { to: { millisecond: HOUR }, options: TIME_OPTIONS },
-    day: { to: { millisecond: DAY }, options: TIME_OPTIONS },
-    week: { to: { millisecond: WEEK }, options: TIME_OPTIONS },
-    month: { to: { millisecond: MONTH }, options: TIME_OPTIONS },
-    year: { to: { millisecond: YEAR }, options: TIME_OPTIONS },
+    millisecond: { ...TIME_OPTIONS, abbr: "ms" },
+    second: { ...TIME_OPTIONS, to: { millisecond: SECOND } },
+    minute: { ...TIME_OPTIONS, to: { millisecond: MINUTE } },
+    hour: { ...TIME_OPTIONS, to: { millisecond: HOUR } },
+    day: { ...TIME_OPTIONS, to: { millisecond: DAY } },
+    week: { ...TIME_OPTIONS, to: { millisecond: WEEK } },
+    month: { ...TIME_OPTIONS, to: { millisecond: MONTH } },
+    year: { ...TIME_OPTIONS, to: { millisecond: YEAR } },
 });
 /** Length units. */
 export const LENGTH_UNITS = new UnitList({
@@ -293,6 +274,16 @@ export const TEMPERATURE_UNITS = new UnitList({
         many: "degrees Celsius",
         to: { fahrenheit: n => n * (9 / 5) + 32, kelvin: n => n + 273.15 },
     },
-    fahrenheit: { abbr: "°F", one: "degree Fahrenheit", many: "degrees Fahrenheit", to: { celsius: n => (n - 32) * (5 / 9) } },
-    kelvin: { abbr: "°K", one: "degree Kelvin", many: "degrees Kelvin", to: { celsius: n => n - 273.15 } },
+    fahrenheit: {
+        abbr: "°F",
+        one: "degree Fahrenheit",
+        many: "degrees Fahrenheit",
+        to: { celsius: n => (n - 32) * (5 / 9) },
+    },
+    kelvin: {
+        abbr: "°K",
+        one: "degree Kelvin",
+        many: "degrees Kelvin",
+        to: { celsius: n => n - 273.15 },
+    },
 });