shelving 1.162.1 → 1.164.0

package/package.json

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

package/util/date.d.ts

@@ -35,6 +35,12 @@ export declare function getYesterday(): Date;
 export declare function getToday(): Date;
 /** Get a date representing midnight of the next day. */
 export declare function getTomorrow(): Date;
+/** Get a Date representing exactly midnight of the specified date. */
+export declare function getMidnight(target?: PossibleDate, caller?: AnyCaller): Date;
+/** Get a Date representing midnight on Monday of the specified week. */
+export declare function getMonday(target?: PossibleDate, caller?: AnyCaller): Date;
+/** Get a Date representing the first day of the specified month. */
+export declare function getMonthStart(target?: PossibleDate, caller?: AnyCaller): Date;
 /**
  * Convert a possible date to a `Date` instance, or throw `RequiredError` if it couldn't be converted.
  * @param value Any value that we want to parse as a valid date (defaults to `"now"`).
@@ -57,47 +63,31 @@ export declare function getTimeString(value?: unknown): string | undefined;
 /** Convert a possible `Date` instance to local time string like "18:32:00", or throw `RequiredError` if it couldn't be converted. */
 export declare function requireTimeString(value?: PossibleDate, caller?: AnyCaller): string;
 /** List of day-of-week strings. */
-export declare const DAYS: readonly ["sunday", "monday", "tuesday", "wednesday", "thursday", "friday", "saturday"];
+export declare const DAYS: readonly ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"];
 /** Type listing day-of-week strings. */
 export type Day = (typeof DAYS)[number];
-/** Convert a `Date` instance to a day-of-week string like "monday" */
+/** Convert a `Date` instance to a day-of-week string like "Monday" */
 export declare function getDay(target?: PossibleDate): Day;
-/** Get a Date representing exactly midnight of the specified date. */
-export declare function getMidnight(target?: PossibleDate, caller?: AnyCaller): Date;
-/** Get a Date representing midnight on Monday of the specified week. */
-export declare function getMonday(target?: PossibleDate, caller?: AnyCaller): Date;
-/** Return a new date that increase or decreases the number of days based on an input date. */
-export declare function addDays(change: number, target?: PossibleDate): Date;
-/** Return a new date that increase or decreases the number of hours based on an input date. */
-export declare function addHours(change: number, target?: PossibleDate): Date;
 /**
- * Get the duration (in milliseconds) between two dates.
- *
- * @param target The date when the thing will happen or did happen.
- * @param current Today's date (or a different date to measure from).
+ * Return a new date that increase or decreases the month based on an input date.
+ * - February 29th is a special cased and is _rounded down_ to February 28th on non-leap years.
+ */
+export declare function addYears(change: number, target?: PossibleDate, caller?: AnyCaller): Date;
+/**
+ * Return a new date that increase or decreases the month based on an input date.
+ * - Note that with Javascript "rollover" semantics, adding a month when we're on e.g. 31st of August would normally roll _past_ September and return 1st October.
+ * - To avoid this we clamp the date to the end of the month if rollover happens.
  */
-export declare function getMillisecondsUntil(target: PossibleDate, current?: PossibleDate, caller?: AnyCaller): number;
-/** Count the number of seconds until a date. */
-export declare function getSecondsUntil(target: PossibleDate, current?: PossibleDate, caller?: AnyCaller): number;
-/** Count the number of days ago a date was. */
-export declare function getSecondsAgo(target: PossibleDate, current?: PossibleDate, caller?: AnyCaller): number;
-/** Count the number of days until a date. */
-export declare function getDaysUntil(target: PossibleDate, current?: PossibleDate, caller?: AnyCaller): number;
-/** Count the number of days ago a date was. */
-export declare function getDaysAgo(target: PossibleDate, current?: PossibleDate, caller?: AnyCaller): number;
-/** Count the number of weeks until a date. */
-export declare function getWeeksUntil(target: PossibleDate, current?: PossibleDate, caller?: AnyCaller): number;
-/** Count the number of weeks ago a date was. */
-export declare function getWeeksAgo(target: PossibleDate, current?: PossibleDate, caller?: AnyCaller): number;
-/** Is a date in the past? */
-export declare function isPast(target: PossibleDate, current?: PossibleDate, caller?: AnyCaller): boolean;
-/** Is a date in the future? */
-export declare function isFuture(target: PossibleDate, current?: PossibleDate, caller?: AnyCaller): boolean;
-/** Is a date today (taking into account midnight). */
-export declare function isToday(target: PossibleDate, current?: PossibleDate, caller?: AnyCaller): boolean;
-/** Compact when a date happens/happened, e.g. `in 10d` or `2h ago` or `in 1w` or `just now` */
-export declare function formatWhen(target: PossibleDate, current?: PossibleDate, options?: Intl.NumberFormatOptions): string;
-/** Compact when a date happens, e.g. `10d` or `2h` or `-1w` */
-export declare function formatUntil(target: PossibleDate, current?: PossibleDate, options?: Intl.NumberFormatOptions): string;
-/** Compact when a date will happen, e.g. `10d` or `2h` or `-1w` */
-export declare function formatAgo(target: PossibleDate, current?: PossibleDate, options?: Intl.NumberFormatOptions): string;
+export declare function addMonths(change: number, target?: PossibleDate, caller?: AnyCaller): Date;
+/** Return a new date that increase or decreases the week based on an input date. */
+export declare function addWeeks(change: number, target?: PossibleDate, caller?: AnyCaller): Date;
+/** Return a new date that increase or decreases the day based on an input date. */
+export declare function addDays(change: number, target?: PossibleDate, caller?: AnyCaller): Date;
+/** Return a new date that increase or decreases the hour based on an input date. */
+export declare function addHours(change: number, target?: PossibleDate, caller?: AnyCaller): Date;
+/** Return a new date that increase or decreases the minute based on an input date. */
+export declare function addMinutes(change: number, target?: PossibleDate, caller?: AnyCaller): Date;
+/** Return a new date that increase or decreases the minute based on an input date. */
+export declare function addSeconds(change: number, target?: PossibleDate, caller?: AnyCaller): Date;
+/** Return a new date that increase or decreases the minute based on an input date. */
+export declare function addMilliseconds(change: number, target?: PossibleDate, caller?: AnyCaller): Date;

package/util/date.js

@@ -1,6 +1,4 @@
 import { RequiredError } from "../error/RequiredError.js";
-import { DAY, HOUR, MONTH, SECOND, WEEK } from "./constants.js";
-import { TIME_UNITS } from "./units.js";
 /**
  * Is a value a valid date?
  * - Note: `Date` instances can be invalid (e.g. `new Date("blah blah").getTime()` returns `NaN`). These are detected and will always return `false`
@@ -75,6 +73,28 @@ export function getTomorrow() {
     date.setDate(date.getDate() + 1);
     return date;
 }
+/** Get a Date representing exactly midnight of the specified date. */
+export function getMidnight(target, caller = getMidnight) {
+    const date = new Date(requireDate(target, caller));
+    date.setHours(0, 0, 0, 0);
+    return date;
+}
+/** Get a Date representing midnight on Monday of the specified week. */
+export function getMonday(target, caller = getMonday) {
+    const date = getMidnight(target, caller);
+    const day = date.getDay();
+    if (day === 0)
+        date.setDate(date.getDate() - 6);
+    else if (day !== 1)
+        date.setDate(date.getDate() - (day - 1));
+    return date;
+}
+/** Get a Date representing the first day of the specified month. */
+export function getMonthStart(target, caller = getMonthStart) {
+    const date = getMidnight(target, caller);
+    date.setDate(1);
+    return date;
+}
 /**
  * Convert a possible date to a `Date` instance, or throw `RequiredError` if it couldn't be converted.
  * @param value Any value that we want to parse as a valid date (defaults to `"now"`).
@@ -136,121 +156,69 @@ export function requireTimeString(value, caller = requireTimeString) {
     return _time(requireDate(value, caller));
 }
 /** List of day-of-week strings. */
-export const DAYS = ["sunday", "monday", "tuesday", "wednesday", "thursday", "friday", "saturday"];
-/** Convert a `Date` instance to a day-of-week string like "monday" */
+export const DAYS = ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"];
+/** Convert a `Date` instance to a day-of-week string like "Monday" */
 export function getDay(target) {
     return DAYS[requireDate(target, getDay).getDay()];
 }
-/** Get a Date representing exactly midnight of the specified date. */
-export function getMidnight(target, caller = getMidnight) {
-    const date = new Date(requireDate(target, caller)); // New instance, because we modify it.
-    date.setHours(0, 0, 0, 0);
-    return date;
+/**
+ * Return a new date that increase or decreases the month based on an input date.
+ * - February 29th is a special cased and is _rounded down_ to February 28th on non-leap years.
+ */
+export function addYears(change, target, caller = addYears) {
+    const input = requireDate(target, caller);
+    const output = new Date(input);
+    output.setFullYear(output.getFullYear() + change);
+    if (input.getMonth() !== output.getMonth())
+        output.setDate(0); // Handle February 29th case.
+    return output;
 }
-/** Get a Date representing midnight on Monday of the specified week. */
-export function getMonday(target, caller = getMonday) {
-    const date = getMidnight(target, caller); // New instance, because we modify it.
-    const day = date.getDay();
-    if (day === 0)
-        date.setDate(date.getDate() - 6);
-    else if (day !== 1)
-        date.setDate(date.getDate() - (day - 1));
+/**
+ * Return a new date that increase or decreases the month based on an input date.
+ * - Note that with Javascript "rollover" semantics, adding a month when we're on e.g. 31st of August would normally roll _past_ September and return 1st October.
+ * - To avoid this we clamp the date to the end of the month if rollover happens.
+ */
+export function addMonths(change, target, caller = addMonths) {
+    const input = requireDate(target, caller);
+    const output = new Date(input);
+    output.setMonth(output.getMonth() + change);
+    if (input.getMonth() !== output.getMonth() + change)
+        output.setDate(0); // Handle 31st rollover case.
+    return output;
+}
+/** Return a new date that increase or decreases the week based on an input date. */
+export function addWeeks(change, target, caller = addWeeks) {
+    const date = new Date(requireDate(target, caller));
+    date.setDate(date.getDate() + change * 7);
     return date;
 }
-/** Return a new date that increase or decreases the number of days based on an input date. */
-export function addDays(change, target) {
-    const date = new Date(requireDate(target, addDays)); // New instance, because we modify it.
+/** Return a new date that increase or decreases the day based on an input date. */
+export function addDays(change, target, caller = addDays) {
+    const date = new Date(requireDate(target, caller));
     date.setDate(date.getDate() + change);
     return date;
 }
-/** Return a new date that increase or decreases the number of hours based on an input date. */
-export function addHours(change, target) {
-    const date = new Date(requireDate(target, addHours)); // New instance, because we modify it.
+/** Return a new date that increase or decreases the hour based on an input date. */
+export function addHours(change, target, caller = addHours) {
+    const date = new Date(requireDate(target, caller));
     date.setHours(date.getHours() + change);
     return date;
 }
-/**
- * Get the duration (in milliseconds) between two dates.
- *
- * @param target The date when the thing will happen or did happen.
- * @param current Today's date (or a different date to measure from).
- */
-export function getMillisecondsUntil(target, current, caller = getMillisecondsUntil) {
-    return requireDate(target, caller).getTime() - requireDate(current, caller).getTime();
-}
-/** Count the number of seconds until a date. */
-export function getSecondsUntil(target, current, caller = getSecondsUntil) {
-    return getMillisecondsUntil(target, current, caller) / SECOND;
-}
-/** Count the number of days ago a date was. */
-export function getSecondsAgo(target, current, caller = getSecondsAgo) {
-    return 0 - getSecondsUntil(target, current, caller);
-}
-/** Count the number of days until a date. */
-export function getDaysUntil(target, current, caller = getDaysUntil) {
-    return Math.round((requireDate(target, caller).getTime() - requireDate(current, caller).getTime()) / DAY);
-}
-/** Count the number of days ago a date was. */
-export function getDaysAgo(target, current, caller = getDaysAgo) {
-    return 0 - getDaysUntil(target, current, caller);
-}
-/** Count the number of weeks until a date. */
-export function getWeeksUntil(target, current, caller = getWeeksUntil) {
-    return Math.floor(getDaysUntil(target, current, caller) / 7);
-}
-/** Count the number of weeks ago a date was. */
-export function getWeeksAgo(target, current, caller = getWeeksAgo) {
-    return 0 - getWeeksUntil(target, current, caller);
-}
-/** Is a date in the past? */
-export function isPast(target, current, caller = isPast) {
-    return getMillisecondsUntil(target, current, caller) < 0;
-}
-/** Is a date in the future? */
-export function isFuture(target, current, caller = isFuture) {
-    return getMillisecondsUntil(target, current, caller) > 0;
-}
-/** Is a date today (taking into account midnight). */
-export function isToday(target, current, caller = isToday) {
-    return getDaysUntil(target, current, caller) === 0;
-}
-/** Get an appropriate time unit based on an amount in milliseconds. */
-function getBestTimeUnit(ms) {
-    const abs = Math.abs(ms);
-    if (abs > 18 * MONTH)
-        return TIME_UNITS.require("year");
-    if (abs > 10 * WEEK)
-        return TIME_UNITS.require("month");
-    if (abs > 2 * WEEK)
-        return TIME_UNITS.require("week");
-    if (abs > DAY)
-        return TIME_UNITS.require("day");
-    if (abs > HOUR)
-        return TIME_UNITS.require("hour");
-    if (abs > 9949)
-        return TIME_UNITS.require("minute");
-    if (abs > SECOND)
-        return TIME_UNITS.require("second");
-    return TIME_UNITS.require("millisecond");
-}
-/** Compact when a date happens/happened, e.g. `in 10d` or `2h ago` or `in 1w` or `just now` */
-export function formatWhen(target, current, options) {
-    const ms = getMillisecondsUntil(target, current, formatWhen);
-    const abs = Math.abs(ms);
-    if (abs < 30 * SECOND)
-        return "just now";
-    const unit = getBestTimeUnit(ms);
-    return ms > 0 ? `in ${unit.format(unit.from(abs), options)}` : `${unit.format(unit.from(abs), options)} ago`;
-}
-/** Compact when a date happens, e.g. `10d` or `2h` or `-1w` */
-export function formatUntil(target, current, options) {
-    const ms = getMillisecondsUntil(target, current, formatUntil);
-    const unit = getBestTimeUnit(ms);
-    return unit.format(unit.from(ms), options);
-}
-/** Compact when a date will happen, e.g. `10d` or `2h` or `-1w` */
-export function formatAgo(target, current, options) {
-    const ms = 0 - getMillisecondsUntil(target, current, formatAgo);
-    const unit = getBestTimeUnit(ms);
-    return unit.format(unit.from(ms), options);
+/** Return a new date that increase or decreases the minute based on an input date. */
+export function addMinutes(change, target, caller = addMinutes) {
+    const date = new Date(requireDate(target, caller));
+    date.setMinutes(date.getMinutes() + change);
+    return date;
+}
+/** Return a new date that increase or decreases the minute based on an input date. */
+export function addSeconds(change, target, caller = addSeconds) {
+    const date = new Date(requireDate(target, caller));
+    date.setSeconds(date.getSeconds() + change);
+    return date;
+}
+/** Return a new date that increase or decreases the minute based on an input date. */
+export function addMilliseconds(change, target, caller = addMilliseconds) {
+    const date = new Date(requireDate(target, caller));
+    date.setMilliseconds(date.getMilliseconds() + change);
+    return date;
 }

package/util/duration.d.ts

@@ -0,0 +1,120 @@
+import { type PossibleDate } from "./date.js";
+import type { AnyCaller } from "./function.js";
+import { type TimeUnitKey, type Unit } from "./units.js";
+/**
+ * Duration object.
+ * - This should be compatible with `Intl.DurationFormat` when that is available.
+ */
+export type Duration = {
+    readonly years?: number | undefined;
+    readonly months?: number | undefined;
+    readonly weeks?: number | undefined;
+    readonly days?: number | undefined;
+    readonly hours?: number | undefined;
+    readonly minutes?: number | undefined;
+    readonly seconds?: number | undefined;
+    readonly milliseconds?: number | undefined;
+    readonly microseconds?: number | undefined;
+    readonly nanoseconds?: number | undefined;
+};
+/** Get the millisecond difference between two dates. */
+export declare function getMilliseconds(from?: PossibleDate, to?: PossibleDate, caller?: AnyCaller): number;
+/** Count the various time units between two dates and return a `Duration` format. */
+export declare function getDuration(from?: PossibleDate, to?: PossibleDate, caller?: AnyCaller): Duration;
+/** Get the various time units until a certain date. */
+export declare function getUntil(target: PossibleDate, current?: PossibleDate, caller?: AnyCaller): Duration;
+/** Get the various time units since a certain date. */
+export declare function getAgo(target: PossibleDate, current?: PossibleDate, caller?: AnyCaller): Duration;
+/** Count the milliseconds until a date. */
+export declare function getMillisecondsUntil(target: PossibleDate, current?: PossibleDate, caller?: AnyCaller): number;
+/** Count the milliseconds since a date. */
+export declare function getMillisecondsAgo(target: PossibleDate, current?: PossibleDate, caller?: AnyCaller): number;
+/**
+ * Count the whole seconds until a date.
+ * - Rounds to the nearest whole second, i.e. `1 second 499 ms` returns `1`
+ */
+export declare function getSecondsUntil(target: PossibleDate, current?: PossibleDate, caller?: AnyCaller): number;
+/**
+ * Count the whole seconds since a date.
+ * - Rounds to the nearest whole second, i.e. `1 second 499 ms` returns `1`
+ */
+export declare function getSecondsAgo(target: PossibleDate, current?: PossibleDate, caller?: AnyCaller): number;
+/**
+ * Count the whole minutes until a date.
+ * - Rounds to the nearest whole minute, i.e. `1 min 29 seconds` returns `1`
+ */
+export declare function getMinutesUntil(target: PossibleDate, current?: PossibleDate, caller?: AnyCaller): number;
+/**
+ * Count the whole minutes since a date.
+ * - Rounds to the nearest whole minute, i.e. `1 min 29 seconds` returns `1`
+ */
+export declare function getMinutesAgo(target: PossibleDate, current?: PossibleDate, caller?: AnyCaller): number;
+/**
+ * Count the whole hours until a date.
+ * - Rounds to the nearest whole hour, i.e. `1 hour 29 minutes` returns `1`
+ */
+export declare function getHoursUntil(target: PossibleDate, current?: PossibleDate, caller?: AnyCaller): number;
+/**
+ * Count the whole hours since a date.
+ * - Rounds to the nearest whole hour, i.e. `1 hour 29 minutes` returns `1`
+ */
+export declare function getHoursAgo(target: PossibleDate, current?: PossibleDate, caller?: AnyCaller): number;
+/**
+ * Count the calendar days until a date.
+ * - e.g. from 23:59 to 00:01 is 1 day, even though it's only 1 minutes.
+ */
+export declare function getDaysUntil(target: PossibleDate, current?: PossibleDate, caller?: AnyCaller): number;
+/**
+ * Count the calendar days since a date.
+ * - Rounds to the nearest whole days.
+ */
+export declare function getDaysAgo(target: PossibleDate, current?: PossibleDate, caller?: AnyCaller): number;
+/**
+ * Count the whole weeks until a date.
+ * - Rounds down to the nearest whole week, i.e.
+ */
+export declare function getWeeksUntil(target: PossibleDate, current?: PossibleDate, caller?: AnyCaller): number;
+/**
+ * Count the whole weeks since a date.
+ * - Rounds to the nearest whole week.
+ */
+export declare function getWeeksAgo(target: PossibleDate, current?: PossibleDate, caller?: AnyCaller): number;
+/**
+ * Count the calendar months until a date.
+ * - e.g. from March 31st to April 1st is 1 month, even though it's only 1 day.
+ */
+export declare function getMonthsUntil(target: PossibleDate, current?: PossibleDate, caller?: AnyCaller): number;
+/**
+ * Count the calendar months since a date.
+ * - e.g. from March 31st to April 1st is 1 month, even though it's only 1 day.
+ */
+export declare function getMonthsAgo(target: PossibleDate, current?: PossibleDate, caller?: AnyCaller): number;
+/**
+ * Count the calendar years until a date.
+ * - e.g. from December 31st to January 1st is 1 year, even though it's only 1 day.
+ */
+export declare function getYearsUntil(target: PossibleDate, current?: PossibleDate, caller?: AnyCaller): number;
+/**
+ * Count the calendar years since a date.
+ * - Note this counts calendar years, not 365-day periods.
+ * - e.g. from December 31st to January 1st is -1 years, even though it's only 1 day.
+ */
+export declare function getYearsAgo(target: PossibleDate, current?: PossibleDate, caller?: AnyCaller): number;
+/** Is a date in the past? */
+export declare function isPast(target: PossibleDate, current?: PossibleDate, caller?: AnyCaller): boolean;
+/** Is a date in the future? */
+export declare function isFuture(target: PossibleDate, current?: PossibleDate, caller?: AnyCaller): boolean;
+/** Is a date today (taking into account midnight). */
+export declare function isToday(target: PossibleDate, current?: PossibleDate, caller?: AnyCaller): boolean;
+/**
+ * Get a best-fit time unit based on an amount in milliseconds.
+ * - Makes a sensible choice about the best time unit to use.
+ * - Years will be used for anything 18 months or more, e.g. `in 2 years`
+ * - Months will be used for anything 10 weeks or more, e.g. `in 14 months`
+ * - Weeks will be used for anything 2 weeks or more, e.g. `in 9 weeks`
+ * - Days will be used for anything 24 hours or more, e.g. `in 13 days`
+ * - Hours will be used for anything 90 minutes or more, e.g. `in 23 hours`
+ * - Minutes will be used for anything 1 second or more, e.g. `1 minute ago` or `in 59 minutes`
+ * - Seconds will be used for anything 1000 milliseconds or more, e.g. `in 59 seconds`
+ */
+export declare function getBestTimeUnit(ms: number): Unit<TimeUnitKey>;

package/util/duration.js

@@ -0,0 +1,179 @@
+import { DAY, HOUR, MINUTE, MONTH, SECOND, WEEK, YEAR } from "./constants.js";
+import { getMidnight, requireDate } from "./date.js";
+import { TIME_UNITS } from "./units.js";
+/** Get the millisecond difference between two dates. */
+export function getMilliseconds(from, to, caller = getMilliseconds) {
+    return requireDate(to, caller).getTime() - requireDate(from, caller).getTime();
+}
+/** Count the various time units between two dates and return a `Duration` format. */
+export function getDuration(from, to, caller = getDuration) {
+    const ms = getMilliseconds(from, to, caller);
+    return {
+        years: Math.trunc(ms / YEAR),
+        months: Math.trunc((ms % YEAR) / MONTH),
+        weeks: Math.trunc((ms % MONTH) / WEEK),
+        days: Math.trunc((ms % WEEK) / DAY),
+        hours: Math.trunc((ms % DAY) / HOUR),
+        minutes: Math.trunc((ms % HOUR) / MINUTE),
+        seconds: Math.trunc((ms % MINUTE) / SECOND),
+        milliseconds: Math.trunc((ms % SECOND) / 1),
+    };
+}
+/** Get the various time units until a certain date. */
+export function getUntil(target, current = "now", caller = getUntil) {
+    return getDuration(current, target, caller);
+}
+/** Get the various time units since a certain date. */
+export function getAgo(target, current = "now", caller = getAgo) {
+    return getDuration(target, current, caller);
+}
+/** Count the milliseconds until a date. */
+export function getMillisecondsUntil(target, current, caller = getMillisecondsUntil) {
+    return getMilliseconds(current, target, caller);
+}
+/** Count the milliseconds since a date. */
+export function getMillisecondsAgo(target, current, caller = getMillisecondsAgo) {
+    return 0 - getMillisecondsUntil(target, current, caller);
+}
+/**
+ * Count the whole seconds until a date.
+ * - Rounds to the nearest whole second, i.e. `1 second 499 ms` returns `1`
+ */
+export function getSecondsUntil(target, current, caller = getSecondsUntil) {
+    return Math.round(getMilliseconds(current, target, caller) / SECOND);
+}
+/**
+ * Count the whole seconds since a date.
+ * - Rounds to the nearest whole second, i.e. `1 second 499 ms` returns `1`
+ */
+export function getSecondsAgo(target, current, caller = getSecondsAgo) {
+    return 0 - getSecondsUntil(target, current, caller);
+}
+/**
+ * Count the whole minutes until a date.
+ * - Rounds to the nearest whole minute, i.e. `1 min 29 seconds` returns `1`
+ */
+export function getMinutesUntil(target, current, caller = getMinutesUntil) {
+    return Math.round(getMilliseconds(current, target, caller) / MINUTE);
+}
+/**
+ * Count the whole minutes since a date.
+ * - Rounds to the nearest whole minute, i.e. `1 min 29 seconds` returns `1`
+ */
+export function getMinutesAgo(target, current, caller = getMinutesAgo) {
+    return 0 - getMinutesUntil(target, current, caller);
+}
+/**
+ * Count the whole hours until a date.
+ * - Rounds to the nearest whole hour, i.e. `1 hour 29 minutes` returns `1`
+ */
+export function getHoursUntil(target, current, caller = getHoursUntil) {
+    return Math.round(getMilliseconds(current, target, caller) / HOUR);
+}
+/**
+ * Count the whole hours since a date.
+ * - Rounds to the nearest whole hour, i.e. `1 hour 29 minutes` returns `1`
+ */
+export function getHoursAgo(target, current, caller = getHoursAgo) {
+    return 0 - getHoursUntil(target, current, caller);
+}
+/**
+ * Count the calendar days until a date.
+ * - e.g. from 23:59 to 00:01 is 1 day, even though it's only 1 minutes.
+ */
+export function getDaysUntil(target, current, caller = getDaysUntil) {
+    return Math.round((getMidnight(target, caller).getTime() - getMidnight(current, caller).getTime()) / DAY);
+}
+/**
+ * Count the calendar days since a date.
+ * - Rounds to the nearest whole days.
+ */
+export function getDaysAgo(target, current, caller = getDaysAgo) {
+    return 0 - getDaysUntil(target, current, caller);
+}
+/**
+ * Count the whole weeks until a date.
+ * - Rounds down to the nearest whole week, i.e.
+ */
+export function getWeeksUntil(target, current, caller = getWeeksUntil) {
+    return Math.trunc(getDaysUntil(target, current, caller) / 7);
+}
+/**
+ * Count the whole weeks since a date.
+ * - Rounds to the nearest whole week.
+ */
+export function getWeeksAgo(target, current, caller = getWeeksAgo) {
+    return 0 - getWeeksUntil(target, current, caller);
+}
+/**
+ * Count the calendar months until a date.
+ * - e.g. from March 31st to April 1st is 1 month, even though it's only 1 day.
+ */
+export function getMonthsUntil(target, current, caller = getMonthsUntil) {
+    const t = requireDate(target, caller);
+    const c = requireDate(current, caller);
+    const years = t.getFullYear() - c.getFullYear();
+    const months = t.getMonth() - c.getMonth();
+    return years * 12 + months;
+}
+/**
+ * Count the calendar months since a date.
+ * - e.g. from March 31st to April 1st is 1 month, even though it's only 1 day.
+ */
+export function getMonthsAgo(target, current, caller = getMonthsAgo) {
+    return 0 - getMonthsUntil(target, current, caller);
+}
+/**
+ * Count the calendar years until a date.
+ * - e.g. from December 31st to January 1st is 1 year, even though it's only 1 day.
+ */
+export function getYearsUntil(target, current, caller = getYearsUntil) {
+    return requireDate(target, caller).getFullYear() - requireDate(current, caller).getFullYear();
+}
+/**
+ * Count the calendar years since a date.
+ * - Note this counts calendar years, not 365-day periods.
+ * - e.g. from December 31st to January 1st is -1 years, even though it's only 1 day.
+ */
+export function getYearsAgo(target, current, caller = getYearsAgo) {
+    return 0 - getYearsUntil(target, current, caller);
+}
+/** Is a date in the past? */
+export function isPast(target, current, caller = isPast) {
+    return getMilliseconds(current, target, caller) < 0;
+}
+/** Is a date in the future? */
+export function isFuture(target, current, caller = isFuture) {
+    return getMilliseconds(current, target, caller) > 0;
+}
+/** Is a date today (taking into account midnight). */
+export function isToday(target, current, caller = isToday) {
+    return getDaysUntil(target, current, caller) === 0;
+}
+/**
+ * Get a best-fit time unit based on an amount in milliseconds.
+ * - Makes a sensible choice about the best time unit to use.
+ * - Years will be used for anything 18 months or more, e.g. `in 2 years`
+ * - Months will be used for anything 10 weeks or more, e.g. `in 14 months`
+ * - Weeks will be used for anything 2 weeks or more, e.g. `in 9 weeks`
+ * - Days will be used for anything 24 hours or more, e.g. `in 13 days`
+ * - Hours will be used for anything 90 minutes or more, e.g. `in 23 hours`
+ * - Minutes will be used for anything 1 second or more, e.g. `1 minute ago` or `in 59 minutes`
+ * - Seconds will be used for anything 1000 milliseconds or more, e.g. `in 59 seconds`
+ */
+export function getBestTimeUnit(ms) {
+    const abs = Math.abs(ms);
+    if (abs > 18 * MONTH)
+        return TIME_UNITS.require("year");
+    if (abs > 10 * WEEK)
+        return TIME_UNITS.require("month");
+    if (abs > DAY)
+        return TIME_UNITS.require("day");
+    if (abs > HOUR)
+        return TIME_UNITS.require("hour");
+    if (abs > MINUTE * 90)
+        return TIME_UNITS.require("minute");
+    if (abs > SECOND)
+        return TIME_UNITS.require("second");
+    return TIME_UNITS.require("millisecond");
+}

package/util/format.d.ts

@@ -1,24 +1,62 @@
 import { type ImmutableArray } from "./array.js";
 import { type PossibleDate } from "./date.js";
+import { type Duration } from "./duration.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.
@@ -50,3 +88,27 @@ export declare function formatURL(possible: PossibleURL, base?: PossibleURL): st
  * - Everything else returns `"Unknown"`
  */
 export declare function formatValue(value: unknown): string;
+/**
+ * Compact best-fit when a date happens/happened, e.g. `in 10d` or `2h ago` or `in 1w` or `just now`
+ * - See `getBestTimeUnit()` for details on how the best-fit unit is chosen.
+ * - But: anything under 30 seconds will show `just now`, which makes more sense in most UIs.
+ */
+export declare function formatWhen(target: PossibleDate, current?: PossibleDate, options?: Intl.NumberFormatOptions): string;
+/** Compact when a date happens, e.g. `10d` or `2h` or `-1w` */
+export declare function formatUntil(target: PossibleDate, current?: PossibleDate, options?: Intl.NumberFormatOptions): string;
+/** Compact when a date will happen, e.g. `10d` or `2h` or `-1w` */
+export declare function formatAgo(target: PossibleDate, current?: PossibleDate, options?: Intl.NumberFormatOptions): string;
+/**
+ * This roughly corresponds to `Intl.DurationFormatOptions`
+ * @todo Use `Intl.DurationFormatOptions` instead it's available in TS lib.
+ */
+interface DurationFormatOptions {
+    style?: "short" | "long" | "narrow";
+}
+/**
+ * Format a duration as a string, e.g. `1 year, 2 months, 3 days` or `1y 2m 3d`
+ * @todo Use `Intl.DurationFormat().format()` instead it's more widely supported and is available in TS lib.
+ */
+export declare function formatDuration(duration: Duration, options?: DurationFormatOptions): string;
+export declare function _getDurationStrings(duration: Duration, options?: Intl.NumberFormatOptions): Iterable<string>;
+export {};

package/util/format.js

@@ -1,49 +1,64 @@
 import { isArray } from "./array.js";
-import { NNBSP } from "./constants.js";
+import { SECOND } from "./constants.js";
 import { isDate, requireDate } from "./date.js";
+import { getBestTimeUnit, getMilliseconds } from "./duration.js";
 import { getPercent } from "./number.js";
 import { isObject } from "./object.js";
+import { TIME_UNITS } from "./units.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 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 number with a longer full-word suffix. */
-export function pluralizeQuantity(num, one, many, options) {
-    const qty = formatNumber(num, {
+/**
+ * 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.
@@ -133,3 +148,46 @@ export function formatValue(value) {
         return formatObject(value);
     return "Unknown";
 }
+/**
+ * Compact best-fit when a date happens/happened, e.g. `in 10d` or `2h ago` or `in 1w` or `just now`
+ * - See `getBestTimeUnit()` for details on how the best-fit unit is chosen.
+ * - But: anything under 30 seconds will show `just now`, which makes more sense in most UIs.
+ */
+export function formatWhen(target, current, options) {
+    const ms = getMilliseconds(current, target, formatWhen);
+    const abs = Math.abs(ms);
+    if (abs < 30 * SECOND)
+        return "just now";
+    const unit = getBestTimeUnit(ms);
+    return ms > 0 ? `in ${unit.format(unit.from(abs), options)}` : `${unit.format(unit.from(abs), options)} ago`;
+}
+/** Compact when a date happens, e.g. `10d` or `2h` or `-1w` */
+export function formatUntil(target, current, options) {
+    const ms = getMilliseconds(current, target, formatUntil);
+    const unit = getBestTimeUnit(ms);
+    return unit.format(unit.from(ms), options);
+}
+/** Compact when a date will happen, e.g. `10d` or `2h` or `-1w` */
+export function formatAgo(target, current, options) {
+    const ms = getMilliseconds(target, current, formatAgo);
+    const unit = getBestTimeUnit(ms);
+    return unit.format(unit.from(ms), options);
+}
+/**
+ * Format a duration as a string, e.g. `1 year, 2 months, 3 days` or `1y 2m 3d`
+ * @todo Use `Intl.DurationFormat().format()` instead it's more widely supported and is available in TS lib.
+ */
+export function formatDuration(duration, options) {
+    // Map `DurationFormatOptions` to `NumberFormatOptions`
+    const style = options?.style ?? "short";
+    return new Intl.ListFormat(undefined, { style, type: "unit" }).format(_getDurationStrings(duration, { ...options, style: "unit", unitDisplay: style }));
+}
+export function* _getDurationStrings(duration, options) {
+    for (const key of TIME_KEYS) {
+        const value = duration[`${key}s`];
+        if (typeof value === "number" && value !== 0)
+            yield TIME_UNITS.require(key)?.format(value, options);
+    }
+}
+// Keys we loop through in the right order.
+const TIME_KEYS = ["year", "month", "week", "day", "hour", "minute", "second", "millisecond"];

package/util/index.d.ts

@@ -16,6 +16,7 @@ export * from "./debug.js";
 export * from "./dictionary.js";
 export * from "./diff.js";
 export * from "./dispose.js";
+export * from "./duration.js";
 export * from "./entity.js";
 export * from "./entry.js";
 export * from "./equal.js";

package/util/index.js

@@ -16,6 +16,7 @@ export * from "./debug.js";
 export * from "./dictionary.js";
 export * from "./diff.js";
 export * from "./dispose.js";
+export * from "./duration.js";
 export * from "./entity.js";
 export * from "./entry.js";
 export * from "./equal.js";

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 },
+    },
 });

package/util/url.js

@@ -4,6 +4,17 @@ import { isData } from "./data.js";
 import { notNullish } from "./null.js";
 import { getProps } from "./object.js";
 import { getString, isString } from "./string.js";
+function parseURL(value, base) {
+    const ctor = URL;
+    if (typeof ctor.parse === "function")
+        return ctor.parse(value, base);
+    try {
+        return new URL(value, base);
+    }
+    catch {
+        return null;
+    }
+}
 /** Is an unknown value a URL object? */
 export function isURL(value) {
     return value instanceof URL;
@@ -16,7 +27,7 @@ export function assertURL(value, caller = assertURL) {
 /** Convert a possible URL to a URL, or return `undefined` if conversion fails. */
 export function getURL(possible, base = _BASE) {
     if (notNullish(possible))
-        return isURL(possible) ? possible : URL.parse(possible, base) || undefined;
+        return isURL(possible) ? possible : parseURL(possible, base) || undefined;
 }
 const _BASE = typeof document === "object" ? document.baseURI : undefined;
 /** Convert a possible URL to a URL, or throw `RequiredError` if conversion fails. */