shelving 1.83.4 → 1.84.0

package/package.json

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

package/schema/DateSchema.d.ts

@@ -1,6 +1,6 @@
 import { PossibleDate } from "../util/date.js";
 import { Schema, SchemaOptions } from "./Schema.js";
-/** Define a valid date, e.g. `2005-09-12` */
+/** Define a valid date in YMD format, e.g. `2005-09-12` */
 export declare class DateSchema extends Schema<string> {
     readonly value: PossibleDate;
     readonly min: PossibleDate | null;

package/schema/DateSchema.js

@@ -2,7 +2,7 @@ import { getOptionalDate, getYmd } from "../util/date.js";
 import { InvalidFeedback } from "../feedback/InvalidFeedback.js";
 import { Schema } from "./Schema.js";
 import { OPTIONAL } from "./OptionalSchema.js";
-/** Define a valid date, e.g. `2005-09-12` */
+/** Define a valid date in YMD format, e.g. `2005-09-12` */
 export class DateSchema extends Schema {
     constructor({ value = "now", min = null, max = null, ...options }) {
         super(options);

package/schema/TimeSchema.d.ts

@@ -0,0 +1,14 @@
+import { PossibleTime } from "../util/time.js";
+import { Schema, SchemaOptions } from "./Schema.js";
+/** Define a valid time in 24h hh:mm:ss.fff format, e.g. `23:59` or `24:00 */
+export declare class TimeSchema extends Schema<string> {
+    readonly value: PossibleTime;
+    constructor({ value, ...options }: SchemaOptions & {
+        readonly value?: PossibleTime;
+    });
+    validate(unsafeValue?: unknown): string;
+}
+/** Valid time, e.g. `2005-09-12` (required because falsy values are invalid). */
+export declare const TIME: TimeSchema;
+/** Valid time, e.g. `2005-09-12`, or `null` */
+export declare const OPTIONAL_TIME: import("./OptionalSchema.js").OptionalSchema<string>;

package/schema/TimeSchema.js

@@ -0,0 +1,21 @@
+import { InvalidFeedback } from "../feedback/InvalidFeedback.js";
+import { getOptionalTime } from "../util/time.js";
+import { OPTIONAL } from "./OptionalSchema.js";
+import { Schema } from "./Schema.js";
+/** Define a valid time in 24h hh:mm:ss.fff format, e.g. `23:59` or `24:00 */
+export class TimeSchema extends Schema {
+    constructor({ value = "now", ...options }) {
+        super(options);
+        this.value = value;
+    }
+    validate(unsafeValue = this.value) {
+        const time = getOptionalTime(unsafeValue);
+        if (!time)
+            throw new InvalidFeedback(unsafeValue ? "Invalid time" : "Required", { value: unsafeValue });
+        return time.long;
+    }
+}
+/** Valid time, e.g. `2005-09-12` (required because falsy values are invalid). */
+export const TIME = new TimeSchema({});
+/** Valid time, e.g. `2005-09-12`, or `null` */
+export const OPTIONAL_TIME = OPTIONAL(TIME);

package/schema/index.d.ts

@@ -10,9 +10,10 @@ export * from "./EmailSchema.js";
 export * from "./KeySchema.js";
 export * from "./LinkSchema.js";
 export * from "./NumberSchema.js";
-export * from "./OptionalSchema.js";
 export * from "./PhoneSchema.js";
-export * from "./RequiredSchema.js";
 export * from "./SlugSchema.js";
 export * from "./StringSchema.js";
+export * from "./TimeSchema.js";
 export * from "./ThroughSchema.js";
+export * from "./OptionalSchema.js";
+export * from "./RequiredSchema.js";

package/schema/index.js

@@ -10,9 +10,10 @@ export * from "./EmailSchema.js";
 export * from "./KeySchema.js";
 export * from "./LinkSchema.js";
 export * from "./NumberSchema.js";
-export * from "./OptionalSchema.js";
 export * from "./PhoneSchema.js";
-export * from "./RequiredSchema.js";
 export * from "./SlugSchema.js";
 export * from "./StringSchema.js";
+export * from "./TimeSchema.js";
 export * from "./ThroughSchema.js";
+export * from "./OptionalSchema.js";
+export * from "./RequiredSchema.js";

package/util/color.d.ts

@@ -1,13 +1,17 @@
+export declare const HEX3_REGEXP: RegExp;
+export declare const HEX6_REGEXP: RegExp;
 /** Things that can be converted to a `Color` instance. */
 export declare type PossibleColor = Color | string;
 export declare type PossibleOptionalColor = PossibleColor | null;
 /** Represent a color. */
 export declare class Color {
+    /** Make a `Color` from a 3 or 6 or 8 byte hex string. */
+    static fromHex(str: string): Color | null;
     readonly r: number;
     readonly g: number;
     readonly b: number;
     readonly a: number;
-    constructor(r?: number | string, g?: number | string, b?: number | string, a?: number | string);
+    constructor(r?: number, g?: number, b?: number, a?: number);
     /** Convert this color to a six or eight digit hex color. */
     get hex(): string;
     /** Convert this color to an `rgb()` string. */
@@ -16,19 +20,17 @@ export declare class Color {
     get rgba(): string;
     /** Get the sRGB luminance of this color. */
     get luminance(): number;
+    /** Is this color light. */
+    get isLight(): boolean;
+    /** Is this color dark. */
+    get isDark(): boolean;
     toString(): string;
 }
 /** Is an unknown value a `Color` instance. */
 export declare const isColor: (v: Color | unknown) => v is Color;
 /** Assert that an unknown value is a `Color` instance. */
 export declare function assertColor(v: Color | unknown): asserts v is Color;
-/** Convert a number or string to a color channel number that's within bounds (strings like `0a` or `ff` are parsed as hexadecimal). */
-export declare function getColorChannel(channel: number | string): number;
 /** Convert a possible color to a `Color` instance or `null` */
-export declare function getOptionalColor(possibleColor: unknown): Color | null;
+export declare function getOptionalColor(possible: unknown): Color | null;
 /** Convert a possible color to a `Color` instance */
-export declare function getColor(possibleColor: PossibleColor): Color;
-/** Is a color light? */
-export declare const isLight: (input: PossibleColor) => boolean;
-/** Is a color dark? */
-export declare const isDark: (input: PossibleColor) => boolean;
+export declare function getColor(possible: PossibleColor): Color;

package/util/color.js

@@ -1,23 +1,29 @@
 import { AssertionError } from "../error/AssertionError.js";
-import { getBetween, roundNumber } from "./number.js";
+import { boundNumber, roundNumber } from "./number.js";
 // Constants.
 const DARK = 140; // Anything with a luminance > 140 is considered light.
-const MIN = 0; // Maximum value of a channel.
-const MAX = 255; // Maximum value of a channel.
 // Regular expressions.
-const HEX3 = /^#?([0-F])([0-F])([0-F])$/i;
-const HEX6 = /^#?([0-F]{2})([0-F]{2})([0-F]{2})([0-F]{2})?$/i;
+export const HEX3_REGEXP = /^#?([0-F])([0-F])([0-F])$/i;
+export const HEX6_REGEXP = /^#?([0-F]{2})([0-F]{2})([0-F]{2})([0-F]{2})?$/i;
 /** Represent a color. */
 export class Color {
     constructor(r = 255, g = 255, b = 255, a = 255) {
-        this.r = getColorChannel(r);
-        this.g = getColorChannel(g);
-        this.b = getColorChannel(b);
-        this.a = getColorChannel(a);
+        this.r = boundNumber(r, 0, 255);
+        this.g = boundNumber(g, 0, 255);
+        this.b = boundNumber(b, 0, 255);
+        this.a = boundNumber(a, 0, 255);
+    }
+    /** Make a `Color` from a 3 or 6 or 8 byte hex string. */
+    static fromHex(str) {
+        const matches = (str.match(HEX3_REGEXP) || str.match(HEX6_REGEXP));
+        if (!matches)
+            return null;
+        const [, r, g, b, a] = matches;
+        return new Color(_parse(r), _parse(g), _parse(b), typeof a === "string" ? _parse(a) : undefined);
     }
     /** Convert this color to a six or eight digit hex color. */
     get hex() {
-        return `#${_hex(this.r)}${_hex(this.g)}${_hex(this.b)}${this.a < MAX ? _hex(this.a) : ""}`;
+        return `#${_hex(this.r)}${_hex(this.g)}${_hex(this.b)}${this.a < 255 ? _hex(this.a) : ""}`;
     }
     /** Convert this color to an `rgb()` string. */
     get rgb() {
@@ -32,11 +38,19 @@ export class Color {
         // Green is the largest component of the luminence, etc.
         return Math.round(0.2126 * this.r + 0.7152 * this.g + 0.0722 * this.b);
     }
+    /** Is this color light. */
+    get isLight() {
+        return this.luminance > DARK;
+    }
+    /** Is this color dark. */
+    get isDark() {
+        return this.luminance <= DARK;
+    }
     toString() {
         return this.rgba;
     }
 }
-/** Convert number channel to a hex string (results will be unpredictable if number is outside 0-MAX). */
+const _parse = (hex) => parseInt(hex.padStart(2, "00"), 16);
 const _hex = (channel) => channel.toString(16).padStart(2, "00");
 /** Is an unknown value a `Color` instance. */
 export const isColor = (v) => v instanceof Color;
@@ -45,35 +59,18 @@ export function assertColor(v) {
     if (!isColor(v))
         throw new AssertionError("Invalid color", v);
 }
-/** Convert a number or string to a color channel number that's within bounds (strings like `0a` or `ff` are parsed as hexadecimal). */
-export function getColorChannel(channel) {
-    const num = typeof channel === "string" ? parseInt(channel.padStart(2, "00"), 16) : Math.round(channel);
-    if (Number.isFinite(num))
-        return getBetween(num, MIN, MAX);
-    throw new AssertionError("Invalid color channel", channel);
-}
 /** Convert a possible color to a `Color` instance or `null` */
-export function getOptionalColor(possibleColor) {
-    if (isColor(possibleColor))
-        return possibleColor;
-    if (typeof possibleColor === "string") {
-        const hex3 = possibleColor.match(HEX3);
-        if (hex3)
-            return new Color(hex3[1], hex3[2], hex3[3]);
-        const hex6 = possibleColor.match(HEX6);
-        if (hex6)
-            return new Color(hex6[1], hex6[2], hex6[3], hex6[4]);
-    }
+export function getOptionalColor(possible) {
+    if (isColor(possible))
+        return possible;
+    if (typeof possible === "string")
+        return Color.fromHex(possible);
     return null;
 }
 /** Convert a possible color to a `Color` instance */
-export function getColor(possibleColor) {
-    const color = getOptionalColor(possibleColor);
+export function getColor(possible) {
+    const color = getOptionalColor(possible);
     if (!color)
-        throw new AssertionError("Invalid color", possibleColor);
+        throw new AssertionError("Invalid color", possible);
     return color;
 }
-/** Is a color light? */
-export const isLight = (input) => getColor(input).luminance > DARK;
-/** Is a color dark? */
-export const isDark = (input) => getColor(input).luminance <= DARK;

package/util/date.d.ts

@@ -1,7 +1,7 @@
 /** Things that converted to dates. */
-export declare type PossibleDate = Date | number | string | (() => PossibleDate);
+export declare type PossibleDate = Date | number | string | (() => Date | number | string);
 /** Things that converted to dates or `null` */
-export declare type PossibleOptionalDate = Date | number | string | null | (() => PossibleDate | null);
+export declare type PossibleOptionalDate = Date | number | string | null | (() => Date | number | string | null | null);
 /** Is a value a date? */
 export declare const isDate: (v: Date | unknown) => v is Date;
 /** Assert that a value is a `Date` instance. */
@@ -65,11 +65,13 @@ export declare const getDaysAgo: (target: PossibleDate, current?: PossibleDate)
 export declare const getWeeksUntil: (target: PossibleDate, current?: PossibleDate) => number;
 /** Count the number of weeks ago a date was. */
 export declare const getWeeksAgo: (target: PossibleDate, current?: PossibleDate) => number;
-/** Format a date in the browser locale. */
-export declare const formatDate: (date: PossibleDate) => string;
 /** Is a date in the past? */
 export declare const isPast: (target: PossibleDate, current?: PossibleDate) => boolean;
 /** Is a date in the future? */
 export declare const isFuture: (target: PossibleDate, current?: PossibleDate) => boolean;
 /** Is a date today (taking into account midnight). */
 export declare const isToday: (target: PossibleDate, current?: PossibleDate) => boolean;
+/** Format a date in the browser locale. */
+export declare const formatDate: (date: PossibleDate) => string;
+/** Format an optional time as a string. */
+export declare const formatOptionalDate: (date?: unknown) => string | null;

package/util/date.js

@@ -58,8 +58,13 @@ export function getOptionalYmd(possibleDate) {
 }
 /** Convert a `Date` instance to a YMD string like "2015-09-12", or throw `AssertionError` if it couldn't be converted.  */
 export function getYmd(possibleDate = "now") {
-    return getDate(possibleDate).toISOString().slice(0, 10);
+    const date = getDate(possibleDate);
+    const y = _pad(date.getUTCFullYear(), 4);
+    const m = _pad(date.getUTCMonth() + 1, 2);
+    const d = _pad(date.getUTCDate(), 2);
+    return `${y}-${m}-${d}`;
 }
+const _pad = (num, size) => num.toString(10).padStart(size, "0000");
 /** 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" */
@@ -67,10 +72,7 @@ export const getDay = (target) => days[getDate(target).getDay()];
 /** Get a Date representing exactly midnight of the specified date. */
 export function getMidnight(target) {
     const date = new Date(getDate(target)); // New instance, because we modify it.
-    date.setHours(0);
-    date.setMinutes(0);
-    date.setSeconds(0);
-    date.setMilliseconds(0);
+    date.setHours(0, 0, 0, 0);
     return date;
 }
 /** Get a Date representing midnight on Monday of the specified week. */
@@ -114,12 +116,13 @@ export const getDaysAgo = (target, current) => 0 - getDaysUntil(target, current)
 export const getWeeksUntil = (target, current) => Math.floor(getDaysUntil(target, current) / 7);
 /** Count the number of weeks ago a date was. */
 export const getWeeksAgo = (target, current) => 0 - getWeeksUntil(target, current);
-/** Format a date in the browser locale. */
-export const formatDate = (date) => _formatter.format(getDate(date));
-const _formatter = new Intl.DateTimeFormat(undefined, {});
 /** Is a date in the past? */
 export const isPast = (target, current) => getDate(target) < getDate(current);
 /** Is a date in the future? */
 export const isFuture = (target, current) => getDate(target) > getDate(current);
 /** Is a date today (taking into account midnight). */
 export const isToday = (target, current) => getMidnight(target) === getMidnight(current);
+/** Format a date in the browser locale. */
+export const formatDate = (date) => getDate(date).toLocaleDateString();
+/** Format an optional time as a string. */
+export const formatOptionalDate = (date) => { var _a; return ((_a = getOptionalDate(date)) === null || _a === void 0 ? void 0 : _a.toLocaleDateString()) || null; };

package/util/index.d.ts

@@ -35,6 +35,7 @@ export * from "./sort.js";
 export * from "./source.js";
 export * from "./string.js";
 export * from "./template.js";
+export * from "./time.js";
 export * from "./timeout.js";
 export * from "./transform.js";
 export * from "./undefined.js";

package/util/index.js

@@ -35,6 +35,7 @@ export * from "./sort.js";
 export * from "./source.js";
 export * from "./string.js";
 export * from "./template.js";
+export * from "./time.js";
 export * from "./timeout.js";
 export * from "./transform.js";
 export * from "./undefined.js";

package/util/number.d.ts

@@ -3,6 +3,16 @@ export declare const isNumber: (v: unknown) => v is number;
 /** Assert that a value is a number. */
 export declare function assertNumber(v: number | unknown): asserts v is number;
 /** Assert that a value is a number greater than. */
+export declare function assertFinite(v: number | unknown): asserts v is number;
+/**
+ * Is a finite number within a specified range?
+ *
+ * @param num The number to test, e.g. `17`
+ * @param min The start of the range, e.g. `10`
+ * @param max The end of the range, e.g. `20`
+ */
+export declare const isBetween: (num: number, min: number, max: number) => boolean;
+/** Assert that a value is a number greater than. */
 export declare function assertBetween(v: number | unknown, min: number, max: number): asserts v is number;
 /** Assert that a value is a number greater than. */
 export declare function assertMax(v: number | unknown, max: number): asserts v is number;
@@ -54,20 +64,16 @@ export declare const roundNumber: (num: number, precision?: number) => number;
  * @returns The number truncated to the specified precision.
  */
 export declare const truncateNumber: (num: number, precision?: number) => number;
-/**
- * Format a number (based on the user's browser settings).
- *
- * @param num The number to format.
- * @param maxPrecision Maximum number of digits shown after the decimal point (defaults to 2).
- * @param minPrecision Minimum number of digits shown after the decimal point (defaults to 0).
- *
- * @returns The number formatted as a string in the browser's current locale.
- */
-export declare function formatNumber(num: number, maxPrecision?: number, minPrecision?: number): string;
+/** Bound a number so it fits between two values. */
+export declare function boundNumber(num: number, min: number, max: number): number;
+/** Wrap a number so it fits between two values. */
+export declare function wrapNumber(num: number, min: number, max: number): number;
+/** Format a number (based on the user's browser language settings). */
+export declare function formatNumber(num: number, precision?: number | null): string;
 /** Format a number with a short abbreviated suffix. */
-export declare const formatQuantity: (num: number, abbr: string, maxPrecision?: number, minPrecision?: number) => string;
+export declare const formatQuantity: (num: number, abbr: string, precision?: number | null) => string;
 /** Format a number with a longer full-word suffix. */
-export declare function formatFullQuantity(num: number, singular: string, plural: string, maxPrecision?: number, minPrecision?: number): string;
+export declare function formatFullQuantity(num: number, singular: string, plural: string, precision?: number | null): string;
 /**
  * Cram a large whole numbers into a space efficient format, e.g. `14.7M`
  * - Improves glanceability.
@@ -96,22 +102,6 @@ export declare function cramNumber(num: number): string;
 export declare const cramQuantity: (num: number, suffix: string) => string;
 /** Cram a number with a longer full-word suffix. */
 export declare function cramFullQuantity(num: number, singular: string, plural: string): string;
-/**
- * Is a number within a specified range?
- *
- * @param num The number to test, e.g. `17`
- * @param start The start of the range, e.g. `10`
- * @param end The end of the range, e.g. `20`
- */
-export declare const isBetween: (num: number, start: number, end: number) => boolean;
-/**
- * Apply a min/max to a number to return a number that's definitely in the specified range.
- *
- * @param num The number to apply the min/max to, e.g. `17`
- * @param start The start of the range, e.g. `10`
- * @param end The end of the range, e.g. `20`
- */
-export declare const getBetween: (num: number, start: number, end: number) => number;
 /**
  * Get a number as a percentage of another number.
  *

package/util/number.js

@@ -8,9 +8,22 @@ export function assertNumber(v) {
         throw new AssertionError(`Must be number`, v);
 }
 /** Assert that a value is a number greater than. */
+export function assertFinite(v) {
+    if (typeof v !== "number" || !Number.isFinite(v))
+        throw new AssertionError(`Must be finite number`, v);
+}
+/**
+ * Is a finite number within a specified range?
+ *
+ * @param num The number to test, e.g. `17`
+ * @param min The start of the range, e.g. `10`
+ * @param max The end of the range, e.g. `20`
+ */
+export const isBetween = (num, min, max) => num >= min && num <= max;
+/** Assert that a value is a number greater than. */
 export function assertBetween(v, min, max) {
-    if (typeof v !== "number" || v < min || v > max)
-        throw new AssertionError(`Must be number between ${min}-${max}`, v);
+    if (typeof v !== "number" || isBetween(v, min, max))
+        throw new AssertionError(`Must be number between ${min} and ${max}`, v);
 }
 /** Assert that a value is a number greater than. */
 export function assertMax(v, max) {
@@ -36,19 +49,19 @@ export function getOptionalNumber(value) {
     if (typeof value === "number")
         return !Number.isFinite(value) ? null : value === 0 ? 0 : value;
     else if (typeof value === "string")
-        return getOptionalNumber(parseFloat(value.replace(NUMERIC, "")));
+        return getOptionalNumber(parseFloat(value.replace(NOT_NUMERIC_REGEXP, "")));
     else if (value instanceof Date)
-        return value.getTime();
+        return getOptionalNumber(value.getTime());
     return null;
 }
-const NUMERIC = /[^0-9-.]/g;
+const NOT_NUMERIC_REGEXP = /[^0-9-.]/g;
 /**
  * Assertively convert an unknown value to a finite number.
  * @throws `AssertionError` if the value cannot be converted.
  */
 export function getNumber(value) {
     const num = getOptionalNumber(value);
-    assertNumber(num);
+    assertFinite(num);
     return num;
 }
 /**
@@ -81,25 +94,31 @@ export const roundNumber = (num, precision = 0) => Math.round(num * 10 ** precis
  * @returns The number truncated to the specified precision.
  */
 export const truncateNumber = (num, precision = 0) => Math.trunc(num * 10 ** precision) / 10 ** precision;
-/**
- * Format a number (based on the user's browser settings).
- *
- * @param num The number to format.
- * @param maxPrecision Maximum number of digits shown after the decimal point (defaults to 2).
- * @param minPrecision Minimum number of digits shown after the decimal point (defaults to 0).
- *
- * @returns The number formatted as a string in the browser's current locale.
- */
-export function formatNumber(num, maxPrecision = 4, minPrecision = 0) {
+/** Bound a number so it fits between two values. */
+export function boundNumber(num, min, max) {
+    assertMin(max, min); // Assert that max is more than min.
+    return Math.max(min, Math.min(max, num));
+}
+/** Wrap a number so it fits between two values. */
+export function wrapNumber(num, min, max) {
+    assertMin(max, min); // Assert that max is more than min.
+    if (num >= max)
+        return ((num - max) % (max - min)) + min;
+    if (num < min)
+        return ((num - min) % (min - max)) + max;
+    return num;
+}
+/** Format a number (based on the user's browser language settings). */
+export function formatNumber(num, precision = null) {
     if (!Number.isFinite(num))
         return Number.isNaN(num) ? "None" : "Infinity";
-    return new Intl.NumberFormat(undefined, { maximumFractionDigits: maxPrecision, minimumFractionDigits: minPrecision }).format(num);
+    return new Intl.NumberFormat(undefined, { minimumFractionDigits: precision !== null && precision !== void 0 ? precision : undefined, maximumFractionDigits: precision !== null && precision !== void 0 ? precision : 20 }).format(num);
 }
 /** Format a number with a short abbreviated suffix. */
-export const formatQuantity = (num, abbr, maxPrecision, minPrecision) => `${formatNumber(num, maxPrecision, minPrecision)}${NNBSP}${abbr}`;
+export const formatQuantity = (num, abbr, precision) => `${formatNumber(num, precision)}${NNBSP}${abbr}`;
 /** Format a number with a longer full-word suffix. */
-export function formatFullQuantity(num, singular, plural, maxPrecision, minPrecision) {
-    const qty = formatNumber(num, maxPrecision, minPrecision);
+export function formatFullQuantity(num, singular, plural, precision) {
+    const qty = formatNumber(num, precision);
     return `${qty} ${qty === "1" ? singular : plural}`;
 }
 /**
@@ -148,22 +167,6 @@ export function cramFullQuantity(num, singular, plural) {
     const qty = cramNumber(num);
     return `${qty} ${qty === "1" ? singular : plural}`;
 }
-/**
- * Is a number within a specified range?
- *
- * @param num The number to test, e.g. `17`
- * @param start The start of the range, e.g. `10`
- * @param end The end of the range, e.g. `20`
- */
-export const isBetween = (num, start, end) => num >= start && num <= end;
-/**
- * Apply a min/max to a number to return a number that's definitely in the specified range.
- *
- * @param num The number to apply the min/max to, e.g. `17`
- * @param start The start of the range, e.g. `10`
- * @param end The end of the range, e.g. `20`
- */
-export const getBetween = (num, start, end) => Math.max(start, Math.min(end, num));
 /**
  * Get a number as a percentage of another number.
  *

package/util/time.d.ts

@@ -0,0 +1,58 @@
+/** Class representing a time in the day in 24 hour format in the user's current locale. */
+export declare class Time {
+    /** Make a new `Time` instance from a date (or any value that can be converted to a date). */
+    static fromDate(possible?: unknown): Time | null;
+    /** Make a new `Time` instance from a time string. */
+    static fromString(str: string): Time | null;
+    readonly time: number;
+    constructor(time: number);
+    /** Get the number of hours in this time. */
+    get h(): number;
+    /** Get the number of minutes in this time. */
+    get m(): number;
+    /** Get the number of seconds in this time. */
+    get s(): number;
+    /** Get the number of seconds in this time. */
+    get ms(): number;
+    /** Get the time as in `hh:mm` format (hours, minutes), e.g. `13.59` */
+    get short(): string;
+    /** Get the time in `hh:mm:ss` format (hours, minutes seconds), e.g. `13.16.19.123` */
+    get medium(): string;
+    /** Get this time in `hh:mm:ss.fff` format (ISO 8601 compatible, hours, minutes, seconds, milliseconds), e.g. `13:16:19.123` */
+    get long(): string;
+    /** Get a date corresponding to this time. */
+    get date(): Date;
+    /**
+     * Format this time using the browser locale settings with a specified amount of precision.
+     * @param precision Reveal additional parts of the time, e.g. `2` shows hours and minutes, `3` also shows seconds, and `4 | 5 | 6` show mlliseconds at increasing precision.
+     */
+    format(precision?: 2 | 3 | 4 | 5 | 6): string;
+    valueOf(): number;
+    toString(): string;
+}
+/** Regular expression that matches a time in ISO 8601 format. */
+export declare const TIME_REGEXP: RegExp;
+/** Things that converted to times. */
+export declare type PossibleTime = Time | Date | number | string | (() => number | string);
+/** Things that converted to times or `null` */
+export declare type PossibleOptionalTime = Time | Date | number | string | null | (() => number | string | null);
+/** Is an unknown value a `Time` instance. */
+export declare const isTime: (v: Time | unknown) => v is Time;
+/**
+ * Convert a value to a `Time` instance or `null`
+ * - Works with possible dates, e.g. `now` or `Date` or `2022-09-12 18:32` or `19827263567`
+ * - Works with time strings, e.g. `18:32` or `23:59:59.999`
+ */
+export declare function getOptionalTime(possible: unknown): Time | null;
+/** Convert a possible time to a `Time` instance, or throw `AssertionError` if it couldn't be converted. */
+export declare function getTime(possible?: PossibleTime): Time;
+/** Get the time as in `hh:mm` format (hours, minutes), e.g. `13.59` */
+export declare const getShortTime: (time?: PossibleTime) => string;
+/** Get the time in `hh:mm:ss` format (hours, minutes seconds), e.g. `13.16.19.123` */
+export declare const getMediumTime: (time?: PossibleTime) => string;
+/** Get this time in `hh:mm:ss.fff` format (ISO 8601 compatible, hours, minutes, seconds, milliseconds), e.g. `13:16:19.123` */
+export declare const getLongTime: (time?: PossibleTime) => string;
+/** Format a time as a string based on the browser locale settings. */
+export declare const formatTime: (time?: PossibleTime, precision?: 2 | 3 | 4 | 5 | 6) => string;
+/** Format an optional time as a string based on the browser locale settings. */
+export declare const formatOptionalTime: (time?: unknown, precision?: 2 | 3 | 4 | 5 | 6) => string | null;

package/util/time.js

@@ -0,0 +1,111 @@
+import { AssertionError } from "../error/AssertionError.js";
+import { DAY, HOUR, MINUTE, SECOND } from "./constants.js";
+import { getOptionalDate } from "./date.js";
+import { wrapNumber } from "./number.js";
+/** Class representing a time in the day in 24 hour format in the user's current locale. */
+export class Time {
+    constructor(time) {
+        this.time = wrapNumber(Math.round(time), 0, DAY);
+    }
+    /** Make a new `Time` instance from a date (or any value that can be converted to a date). */
+    static fromDate(possible) {
+        const date = getOptionalDate(possible);
+        return date ? new Time(date.getHours() * HOUR + date.getMinutes() * MINUTE + date.getSeconds() * SECOND + date.getMilliseconds()) : null;
+    }
+    /** Make a new `Time` instance from a time string. */
+    static fromString(str) {
+        const matches = str.match(TIME_REGEXP);
+        if (!matches)
+            return null;
+        const [, h, m, s, ms] = matches;
+        return new Time(parseInt(h, 10) * HOUR + parseInt(m, 10) * MINUTE + (typeof s === "string" ? parseInt(s, 10) * SECOND : 0) + (typeof ms === "string" ? parseInt(ms, 10) : 0));
+    }
+    /** Get the number of hours in this time. */
+    get h() {
+        return Math.trunc(this.time / HOUR);
+    }
+    /** Get the number of minutes in this time. */
+    get m() {
+        return Math.trunc((this.time % HOUR) / MINUTE);
+    }
+    /** Get the number of seconds in this time. */
+    get s() {
+        return Math.trunc((this.time % MINUTE) / SECOND);
+    }
+    /** Get the number of seconds in this time. */
+    get ms() {
+        return this.time % SECOND;
+    }
+    /** Get the time as in `hh:mm` format (hours, minutes), e.g. `13.59` */
+    get short() {
+        return `${_pad(this.h, 2)}:${_pad(this.m, 2)}`;
+    }
+    /** Get the time in `hh:mm:ss` format (hours, minutes seconds), e.g. `13.16.19.123` */
+    get medium() {
+        return `${_pad(this.h, 2)}:${_pad(this.m, 2)}:${_pad(this.s, 2)}`;
+    }
+    /** Get this time in `hh:mm:ss.fff` format (ISO 8601 compatible, hours, minutes, seconds, milliseconds), e.g. `13:16:19.123` */
+    get long() {
+        return `${_pad(this.h, 2)}:${_pad(this.m, 2)}:${_pad(this.s, 2)}.${_pad(this.ms, 3)}`;
+    }
+    /** Get a date corresponding to this time. */
+    get date() {
+        const date = new Date();
+        date.setHours(0, 0, 0, 0);
+        return date;
+    }
+    /**
+     * Format this time using the browser locale settings with a specified amount of precision.
+     * @param precision Reveal additional parts of the time, e.g. `2` shows hours and minutes, `3` also shows seconds, and `4 | 5 | 6` show mlliseconds at increasing precision.
+     */
+    format(precision = 2) {
+        return this.date.toLocaleTimeString(undefined, {
+            hour: "2-digit",
+            minute: "2-digit",
+            second: precision >= 3 ? "2-digit" : undefined,
+            fractionalSecondDigits: precision >= 4 ? precision - 3 : undefined,
+        });
+    }
+    // Implement `valueOf()`
+    valueOf() {
+        return this.time;
+    }
+    // Implement `toString()`
+    toString() {
+        return this.long;
+    }
+}
+const _pad = (num, size) => num.toString(10).padStart(size, "0000");
+/** Regular expression that matches a time in ISO 8601 format. */
+export const TIME_REGEXP = /([0-9]+):([0-9]+)(?::([0-9]+)(?:.([0-9]+))?)?/;
+/** Is an unknown value a `Time` instance. */
+export const isTime = (v) => v instanceof Time;
+/**
+ * Convert a value to a `Time` instance or `null`
+ * - Works with possible dates, e.g. `now` or `Date` or `2022-09-12 18:32` or `19827263567`
+ * - Works with time strings, e.g. `18:32` or `23:59:59.999`
+ */
+export function getOptionalTime(possible) {
+    if (isTime(possible))
+        return possible;
+    if (typeof possible === "function")
+        return getOptionalTime(possible());
+    return (typeof possible === "string" && Time.fromString(possible)) || Time.fromDate(possible) || null;
+}
+/** Convert a possible time to a `Time` instance, or throw `AssertionError` if it couldn't be converted. */
+export function getTime(possible = "now") {
+    const time = getOptionalTime(possible);
+    if (!time)
+        throw new AssertionError(`Must be time`, possible);
+    return time;
+}
+/** Get the time as in `hh:mm` format (hours, minutes), e.g. `13.59` */
+export const getShortTime = (time) => getTime(time).long;
+/** Get the time in `hh:mm:ss` format (hours, minutes seconds), e.g. `13.16.19.123` */
+export const getMediumTime = (time) => getTime(time).long;
+/** Get this time in `hh:mm:ss.fff` format (ISO 8601 compatible, hours, minutes, seconds, milliseconds), e.g. `13:16:19.123` */
+export const getLongTime = (time) => getTime(time).long;
+/** Format a time as a string based on the browser locale settings. */
+export const formatTime = (time, precision = 2) => getTime(time).format(precision);
+/** Format an optional time as a string based on the browser locale settings. */
+export const formatOptionalTime = (time, precision = 2) => { var _a; return ((_a = getOptionalTime(time)) === null || _a === void 0 ? void 0 : _a.format(precision)) || null; };

package/util/units.d.ts

@@ -14,6 +14,8 @@ declare type UnitProps<T extends string> = {
     readonly singular?: string;
     /** Plural name for this unit, e.g. `kilometers` (defaults to `id`). */
     readonly plural?: string;
+    /** Default precision for this unit (defaults to `null`). */
+    readonly precision?: number | null;
     /** Conversions to other units (typically needs at least the base conversion, unless it's already the base unit). */
     readonly to?: Conversions<T>;
 };
@@ -30,6 +32,8 @@ export declare class Unit<T extends string> {
     readonly singular: string;
     /** Plural name for this unit, e.g. `kilometers` (defaults to `singular` + "s"). */
     readonly plural: string;
+    /** Default precision for this unit (defaults to `null`). */
+    readonly precision: number | null;
     /** Title for this unit (uses format `abbr (plural)`, e.g. `fl oz (US fluid ounces)`) */
     get title(): string;
     constructor(
@@ -38,7 +42,7 @@ export declare class Unit<T extends string> {
     /** Key for this unit, e.g. `kilometer` */
     id: T, 
     /** Props to configure this unit. */
-    { abbr, singular, plural, to }: UnitProps<T>);
+    { abbr, singular, plural, precision, to }: UnitProps<T>);
     /** Convert an amount from this unit to another unit. */
     to(amount: number, id?: T | Unit<T>): number;
     /** Convert an amount from another unit to this unit. */
@@ -46,9 +50,9 @@ export declare class Unit<T extends string> {
     /** Convert an amount from this unit to another unit (must specify another `Unit` instance). */
     private _toUnit;
     /** Format a number with a given unit of measure, e.g. `12 kg` or `29.5 l` */
-    format(amount: number, maxPrecision?: number, minPrecision?: number): string;
+    format(amount: number, precision?: number | null): string;
     /** Format a number with a given unit of measure, e.g. `12 kilograms` or `29.5 liters` or `1 degree` */
-    formatFull(amount: number, maxPrecision?: number, minPrecision?: number): string;
+    formatFull(amount: number, precision?: number | null): string;
 }
 /** Represent a list of units. */
 export declare class UnitList<T extends string> extends ImmutableRequiredMap<T, Unit<T>> {
@@ -86,11 +90,11 @@ export declare type VolumeUnitIdentifier = MapKey<typeof VOLUME_UNITS>;
 export declare const TEMPERATURE_UNITS: UnitList<"celsius" | "fahrenheit" | "kelvin">;
 export declare type TemperatureUnitIdentifier = MapKey<typeof TEMPERATURE_UNITS>;
 /** Format a percentage (combines `getPercent()` and `formatUnits()` for convenience). */
-export declare const formatPercent: (numerator: number, denumerator: number, maxPrecision?: number, minPrecision?: number) => string;
+export declare const formatPercent: (numerator: number, denumerator: number, precision?: number) => string;
 /** Format a full format of a duration of time using the most reasonable units e.g. `5 years` or `1 week` or `4 minutes` or `12 milliseconds`. */
-export declare function formatFullDuration(ms: number, maxPrecision?: number, minPrecision?: number): string;
+export declare function formatFullDuration(ms: number, precision?: number): string;
 /** Format a description of a duration of time using the most reasonable units e.g. `5y` or `4m` or `12ms`. */
-export declare function formatDuration(ms: number, maxPrecision?: number, minPrecision?: number): string;
+export declare function formatDuration(ms: number, precision?: number): string;
 /** Full when a date happens/happened, e.g. `in 10 days` or `2 hours ago` */
 export declare const formatFullWhen: (target: PossibleDate, current?: PossibleDate) => string;
 /** Compact when a date happens/happened, e.g. `in 10d` or `2h ago` or `in 1w` */

package/util/units.js

@@ -14,12 +14,13 @@ export class Unit {
     /** Key for this unit, e.g. `kilometer` */
     id, 
     /** Props to configure this unit. */
-    { abbr = id.slice(0, 1), singular = id.replace(/-/, " "), plural = `${singular}s`, to }) {
+    { abbr = id.slice(0, 1), singular = id.replace(/-/, " "), plural = `${singular}s`, precision = null, to }) {
         this.list = list;
         this.id = id;
         this.abbr = abbr;
         this.singular = singular;
         this.plural = plural;
+        this.precision = precision;
         this._to = to;
     }
     /** Title for this unit (uses format `abbr (plural)`, e.g. `fl oz (US fluid ounces)`) */
@@ -57,12 +58,12 @@ export class Unit {
         throw new ConditionError(`Cannot convert "${this.id}" to "${unit.id}"`);
     }
     /** Format a number with a given unit of measure, e.g. `12 kg` or `29.5 l` */
-    format(amount, maxPrecision, minPrecision) {
-        return formatQuantity(amount, this.abbr, maxPrecision, minPrecision);
+    format(amount, precision = this.precision) {
+        return formatQuantity(amount, this.abbr, precision);
     }
     /** Format a number with a given unit of measure, e.g. `12 kilograms` or `29.5 liters` or `1 degree` */
-    formatFull(amount, maxPrecision, minPrecision) {
-        return formatFullQuantity(amount, this.singular, this.plural, maxPrecision, minPrecision);
+    formatFull(amount, precision = this.precision) {
+        return formatFullQuantity(amount, this.singular, this.plural, precision);
     }
 }
 const _getUnit = (list, id) => (typeof id === "string" ? list.get(id) : id);
@@ -206,7 +207,7 @@ export const TEMPERATURE_UNITS = new UnitList({
     kelvin: { abbr: "°K", singular: "degree Kelvin", plural: "degrees Kelvin", to: { celsius: n => n - 273.15 } },
 });
 /** Format a percentage (combines `getPercent()` and `formatUnits()` for convenience). */
-export const formatPercent = (numerator, denumerator, maxPrecision, minPrecision) => formatQuantity(getPercent(numerator, denumerator), "%", maxPrecision, minPrecision);
+export const formatPercent = (numerator, denumerator, precision) => formatQuantity(getPercent(numerator, denumerator), "%", precision);
 /** Get the ID for a time unit based on the amount in milliseconds. */
 function _getTimeUnitIdentifier(ms) {
     const abs = Math.abs(ms);
@@ -227,14 +228,14 @@ function _getTimeUnitIdentifier(ms) {
     return "millisecond";
 }
 /** Format a full format of a duration of time using the most reasonable units e.g. `5 years` or `1 week` or `4 minutes` or `12 milliseconds`. */
-export function formatFullDuration(ms, maxPrecision, minPrecision) {
+export function formatFullDuration(ms, precision) {
     const unit = TIME_UNITS.get(_getTimeUnitIdentifier(ms));
-    return unit.formatFull(unit.from(ms), maxPrecision, minPrecision);
+    return unit.formatFull(unit.from(ms), precision);
 }
 /** Format a description of a duration of time using the most reasonable units e.g. `5y` or `4m` or `12ms`. */
-export function formatDuration(ms, maxPrecision, minPrecision) {
+export function formatDuration(ms, precision) {
     const unit = TIME_UNITS.get(_getTimeUnitIdentifier(ms));
-    return unit.format(unit.from(ms), maxPrecision, minPrecision);
+    return unit.format(unit.from(ms), precision);
 }
 /** format when a data happens/happened. */
 function _formatWhen(formatter, target, current) {