shelving 1.163.0 → 1.165.0

package/package.json

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

package/schema/DataSchema.d.ts

@@ -1,5 +1,6 @@
 import type { Data, Database, PartialData } from "../util/data.js";
 import type { Identifier, Item } from "../util/item.js";
+import { type Key } from "../util/object.js";
 import type { NullableSchema } from "./NullableSchema.js";
 import type { SchemaOptions, Schemas } from "./Schema.js";
 import { Schema } from "./Schema.js";
@@ -15,6 +16,8 @@ export declare class DataSchema<T extends Data> extends Schema<unknown> {
     readonly props: Schemas<T>;
     constructor({ one, title, props, value: partialValue, ...options }: DataSchemaOptions<T>);
     validate(unsafeValue?: unknown): T;
+    pick<K extends Key<T>>(...keys: K[]): DataSchema<Pick<T, K>>;
+    omit<K extends Key<T>>(...keys: K[]): DataSchema<Omit<T, K>>;
 }
 /** Set of named data schemas. */
 export type DataSchemas<T extends Database> = {

package/schema/DataSchema.js

@@ -1,5 +1,6 @@
 import { ValueFeedback } from "../feedback/Feedback.js";
 import { isData } from "../util/data.js";
+import { omitProps, pickProps } from "../util/object.js";
 import { mapProps } from "../util/transform.js";
 import { validateData } from "../util/validate.js";
 import { NULLABLE } from "./NullableSchema.js";
@@ -19,6 +20,12 @@ export class DataSchema extends Schema {
             throw new ValueFeedback("Must be object", unsafeValue);
         return validateData(unsafeValue, this.props);
     }
+    pick(...keys) {
+        return new DataSchema({ ...this, props: pickProps(this.props, ...keys) });
+    }
+    omit(...keys) {
+        return new DataSchema({ ...this, props: omitProps(this.props, ...keys) });
+    }
 }
 function _getSchemaValue([, { value }]) {
     return value;

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,5 +1,6 @@
 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";
 /** Options we use for number formatting. */
@@ -87,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,7 +1,10 @@
 import { isArray } from "./array.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 (based on the user's browser language settings). */
 export function formatNumber(num, options) {
@@ -145,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/template.d.ts

@@ -26,6 +26,9 @@ export declare function getPlaceholders(template: string): readonly string[];
  *
  * @param templates Either a single template string, or an iterator that returns multiple template template strings.
  * - Template strings can include placeholders (e.g. `:name-${country}/{city}`).
+ * - Template strings do not match the `/` character.
+ * - The `**` double splat placeholder _can_ match multiple path segments (e.g. `a/b/c`).
+ *
  * @param target The string containing values, e.g. `Dave-UK/Manchester`
  *
  * @return An object containing values, e.g. `{ name: "Dave", country: "UK", city: "Manchester" }`, or undefined if target didn't match the template.

package/util/template.js

@@ -5,7 +5,7 @@ import { setMapItem } from "./map.js";
 import { isObject } from "./object.js";
 import { getString } from "./string.js";
 // RegExp to find named variables in several formats e.g. `:a`, `${b}`, `{{c}}` or `{d}`
-const R_PLACEHOLDERS = /(\*|:[a-z][a-z0-9]*|\$\{[a-z][a-z0-9]*\}|\{\{[a-z][a-z0-9]*\}\}|\{[a-z][a-z0-9]*\})/i;
+const R_PLACEHOLDERS = /(\*\*?|:[a-z][a-z0-9]*|\$\{[a-z][a-z0-9]*\}|\{\{[a-z][a-z0-9]*\}\}|\{[a-z][a-z0-9]*\})/i;
 // Find actual name within template placeholder e.g. `${name}` → `name`
 const R_NAME = /[a-z0-9]+/i;
 /**
@@ -26,7 +26,7 @@ function _splitTemplate(template, caller) {
         const post = matches[i + 1];
         if (i > 1 && !pre.length)
             throw new ValueError("Template placeholders must be separated by at least one character", { received: template, caller });
-        const name = placeholder === "*" ? String(asterisks++) : R_NAME.exec(placeholder)?.[0] || "";
+        const name = placeholder[0] === "*" ? String(asterisks++) : R_NAME.exec(placeholder)?.[0] || "";
         chunks.push({ pre, placeholder, name, post });
     }
     return chunks;
@@ -53,6 +53,9 @@ function _getPlaceholder({ name }) {
  *
  * @param templates Either a single template string, or an iterator that returns multiple template template strings.
  * - Template strings can include placeholders (e.g. `:name-${country}/{city}`).
+ * - Template strings do not match the `/` character.
+ * - The `**` double splat placeholder _can_ match multiple path segments (e.g. `a/b/c`).
+ *
  * @param target The string containing values, e.g. `Dave-UK/Manchester`
  *
  * @return An object containing values, e.g. `{ name: "Dave", country: "UK", city: "Manchester" }`, or undefined if target didn't match the template.
@@ -70,13 +73,15 @@ export function matchTemplate(template, target, caller = matchTemplate) {
     // Loop through the placeholders (placeholders are at all the even-numbered positions in `chunks`).
     let startIndex = firstChunk.pre.length;
     const values = {};
-    for (const { name, post } of chunks) {
+    for (const { name, post, placeholder } of chunks) {
         const stopIndex = !post ? Number.POSITIVE_INFINITY : target.indexOf(post, startIndex);
         if (stopIndex < 0)
             return undefined; // Target doesn't match template because chunk post wasn't found.
         const value = target.slice(startIndex, stopIndex);
         if (!value.length)
             return undefined; // Target doesn't match template because chunk value was missing.
+        if (placeholder !== "**" && value.includes("/"))
+            return undefined; // Placeholders can't consume multiple path segments.
         values[name] = value;
         startIndex = stopIndex + post.length;
     }

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. */