shelving 1.81.0 → 1.82.0

package/iterate/InspectGenerator.d.ts

@@ -10,7 +10,6 @@ import { ThroughGenerator } from "./ThroughGenerator.js";
  * 	console.log("RETURNED", watch.returned);
  */
 export declare class InspectGenerator<T, R, N> extends ThroughGenerator<T, R, N> {
-    private static readonly NOVALUE;
     /** Get the number of results received by this iterator so far. */
     readonly count = 0;
     /** Is the iteration done? */

package/iterate/InspectGenerator.js

@@ -1,5 +1,7 @@
 import { ConditionError } from "../error/ConditionError.js";
 import { ThroughGenerator } from "./ThroughGenerator.js";
+/** Used when the sequence hasn't inspected anything yet. */
+const _NOVALUE = Symbol("shelving/InspectGenerator.NOVALUE");
 /**
  * Iterable that inspects a source iterable as it iterates.
  * - Stores: first/last yielded value, returned value, whether iteration is done, the number of items that were iterated.
@@ -17,25 +19,25 @@ export class InspectGenerator extends ThroughGenerator {
         this.count = 0;
         /** Is the iteration done? */
         this.done = false;
-        this._first = InspectGenerator.NOVALUE;
-        this._last = InspectGenerator.NOVALUE;
-        this._returned = InspectGenerator.NOVALUE;
+        this._first = _NOVALUE;
+        this._last = _NOVALUE;
+        this._returned = _NOVALUE;
     }
     /** The first yielded value (throws if the iteration yielded no values, i.e. `this.count === 0`). */
     get first() {
-        if (this._first === InspectGenerator.NOVALUE)
+        if (this._first === _NOVALUE)
             throw new ConditionError("Iteration not started");
         return this._first;
     }
     /** The last yielded value (throws if the iteration yielded no values, i.e. `this.count === 0`). */
     get last() {
-        if (this._last === InspectGenerator.NOVALUE)
+        if (this._last === _NOVALUE)
             throw new ConditionError("Iteration not started");
         return this._last;
     }
     /** The returned value (throws if the iteration is not done, i.e. `this.done === false`). */
     get returned() {
-        if (this._returned === InspectGenerator.NOVALUE)
+        if (this._returned === _NOVALUE)
             throw new ConditionError("Iteration not done");
         return this._returned;
     }
@@ -64,4 +66,3 @@ export class InspectGenerator extends ThroughGenerator {
         return result;
     }
 }
-InspectGenerator.NOVALUE = Symbol();

package/package.json

@@ -11,7 +11,7 @@
 		"state-management",
 		"query-builder"
 	],
-	"version": "1.81.0",
+	"version": "1.82.0",
 	"repository": "https://github.com/dhoulb/shelving",
 	"author": "Dave Houlbrooke <dave@shax.com>",
 	"license": "0BSD",
@@ -71,6 +71,8 @@
 		"@typescript-eslint/eslint-plugin": "^5.33.1",
 		"@typescript-eslint/parser": "^5.33.1",
 		"dpdm": "^3.9.0",
+		"esbuild": "^0.15.7",
+		"esbuild-jest": "^0.5.0",
 		"eslint": "^8.22.0",
 		"eslint-config-prettier": "^8.5.0",
 		"eslint-plugin-import": "^2.26.0",
@@ -81,7 +83,6 @@
 		"prettier": "^2.6.2",
 		"react": "^18.1.0",
 		"react-dom": "^18.1.0",
-		"ts-jest": "^28.0.8",
 		"typescript": "^4.6.4"
 	},
 	"peerDependencies": {

package/schema/AllowSchema.d.ts

@@ -7,8 +7,8 @@ export declare type Allowed<T extends string | number> = ReadonlyArray<T> | {
 export declare function validateAllowed<T extends string | number>(value: unknown, allowed: Allowed<T>): T;
 /** Define a valid value from an allowed set of values. */
 export declare abstract class AllowSchema<T extends string | number> extends Schema<T> {
-    readonly allow: Allowed<T>;
     readonly value: T | null;
+    readonly allow: Allowed<T>;
     constructor({ allow, value, ...options }: ConstructorParameters<typeof Schema>[0] & {
         allow: Allowed<T>;
         value?: T | null;

package/schema/DataSchema.d.ts

@@ -4,8 +4,8 @@ import { OptionalSchema } from "./OptionalSchema.js";
 import { Schema } from "./Schema.js";
 /** Validate a data object. */
 export declare class DataSchema<T extends Data> extends Schema<T> {
-    readonly props: Validators<T>;
     readonly value: Partial<T>;
+    readonly props: Validators<T>;
     constructor({ value, props, ...options }: ConstructorParameters<typeof Schema>[0] & {
         readonly props: Validators<T>;
         readonly value?: Partial<T>;

package/schema/ObjectSchema.d.ts

@@ -3,8 +3,8 @@ import { Validator } from "../util/validate.js";
 import { Schema } from "./Schema.js";
 /** Validate a map-like object (whose props are all the same). */
 export declare class ObjectSchema<T> extends Schema<ImmutableObject<T>> {
-    readonly items: Validator<T>;
     readonly value: ImmutableObject;
+    readonly items: Validator<T>;
     readonly min: number | null;
     readonly max: number | null;
     constructor({ value, items, min, max, ...rest }: ConstructorParameters<typeof Schema>[0] & {

package/schema/Schema.d.ts

@@ -11,6 +11,8 @@ export declare abstract class Schema<T extends unknown = unknown> implements Val
     readonly description: string;
     /** Placeholder, e.g. for showing in fields. */
     readonly placeholder: string;
+    /** Default value. */
+    readonly value: unknown;
     constructor({ title, description, placeholder, }: {
         /** Title of the schema, e.g. for using as the title of a corresponding field. */
         readonly title?: string;

package/sequence/DeferredSequence.js

@@ -2,7 +2,7 @@ import { Deferred } from "../util/async.js";
 import { runSequence } from "../util/sequence.js";
 import { AbstractSequence } from "./AbstractSequence.js";
 /** Used when the deferred sequence has no value or reason queued. */
-const NOVALUE = Symbol("shelving/DeferredSequence.NOVALUE");
+const _NOVALUE = Symbol("shelving/DeferredSequence.NOVALUE");
 /**
  * Deferred sequence of values.
  * - Implements `AsyncIterable` so values can be iterated over using `for await...of`
@@ -14,27 +14,27 @@ export class DeferredSequence extends AbstractSequence {
         /** Resolve the current deferred in the sequence. */
         this.resolve = (value) => {
             this._nextValue = value;
-            this._nextReason = NOVALUE;
+            this._nextReason = _NOVALUE;
             queueMicrotask(this._fulfill);
         };
-        this._nextValue = NOVALUE;
+        this._nextValue = _NOVALUE;
         /** Reject the current deferred in the sequence. */
         this.reject = (reason) => {
-            this._nextValue = NOVALUE;
+            this._nextValue = _NOVALUE;
             this._nextReason = reason;
             queueMicrotask(this._fulfill);
         };
-        this._nextReason = NOVALUE;
+        this._nextReason = _NOVALUE;
         /** Fulfill the current deferred by resolving or rejecting it. */
         this._fulfill = () => {
             const { _deferred, _nextReason, _nextValue } = this;
             if (_deferred) {
                 this._deferred = undefined;
-                this._nextReason = NOVALUE;
-                this._nextValue = NOVALUE;
-                if (_nextReason !== NOVALUE)
+                this._nextReason = _NOVALUE;
+                this._nextValue = _NOVALUE;
+                if (_nextReason !== _NOVALUE)
                     _deferred.reject(_nextReason);
-                else if (_nextValue !== NOVALUE)
+                else if (_nextValue !== _NOVALUE)
                     _deferred.resolve(_nextValue);
             }
         };

package/sequence/InspectSequence.d.ts

@@ -10,7 +10,6 @@ import { ThroughSequence } from "./ThroughSequence.js";
  * 	console.log("RETURNED", watch.returned);
  */
 export declare class InspectSequence<T, R> extends ThroughSequence<T, R> {
-    private static readonly NOVALUE;
     /** Get the number of results received by this iterator so far. */
     readonly count = 0;
     /** Is the iteration done? */

package/sequence/InspectSequence.js

@@ -1,5 +1,7 @@
 import { ConditionError } from "../error/ConditionError.js";
 import { ThroughSequence } from "./ThroughSequence.js";
+/** Used when the sequence hasn't inspected anything yet. */
+const _NOVALUE = Symbol("shelving/InspectSequence.NOVALUE");
 /**
  * Sequence of values that inspects a source sequence of values as it iterates.
  * - Stores: first/last yielded value, returned value, whether iteration is done, the number of items that were iterated.
@@ -17,25 +19,25 @@ export class InspectSequence extends ThroughSequence {
         this.count = 0;
         /** Is the iteration done? */
         this.done = false;
-        this._first = InspectSequence.NOVALUE;
-        this._last = InspectSequence.NOVALUE;
-        this._returned = InspectSequence.NOVALUE;
+        this._first = _NOVALUE;
+        this._last = _NOVALUE;
+        this._returned = _NOVALUE;
     }
     /** The first yielded value (throws if the iteration yielded no values, i.e. `this.count === 0`). */
     get first() {
-        if (this._first === InspectSequence.NOVALUE)
+        if (this._first === _NOVALUE)
             throw new ConditionError("Iteration not started");
         return this._first;
     }
     /** The last yielded value (throws if the iteration yielded no values, i.e. `this.count === 0`). */
     get last() {
-        if (this._last === InspectSequence.NOVALUE)
+        if (this._last === _NOVALUE)
             throw new ConditionError("Iteration not started");
         return this._last;
     }
     /** The returned value (throws if the iteration is not done, i.e. `this.done === false`). */
     get returned() {
-        if (this._returned === InspectSequence.NOVALUE)
+        if (this._returned === _NOVALUE)
             throw new ConditionError("Iteration not done");
         return this._returned;
     }
@@ -64,4 +66,3 @@ export class InspectSequence extends ThroughSequence {
         return result;
     }
 }
-InspectSequence.NOVALUE = Symbol();

package/util/async.d.ts

@@ -1,3 +1,4 @@
+import { SIGNAL } from "./constants.js";
 import type { Handler, Dispatch } from "./function.js";
 /** Is a value an asynchronous value implementing a `then()` function. */
 export declare const isAsync: <T>(v: T | PromiseLike<T>) => v is PromiseLike<T>;
@@ -39,8 +40,6 @@ export declare class Deferred<T = void> extends Promise<T> {
 export declare class Delay extends AbstractPromise<void> {
     constructor(ms: number);
 }
-/** The `SIGNAL` symbol indicates a signal. */
-export declare const SIGNAL: unique symbol;
 /** Resolve to `SIGNAL` on a specific signal. */
 export declare class Signal extends AbstractPromise<typeof Signal.SIGNAL> {
     /** The `SIGNAL` symbol indicates a signal. */

package/util/async.js

@@ -1,4 +1,5 @@
 import { AssertionError } from "../error/AssertionError.js";
+import { SIGNAL } from "./constants.js";
 /** Is a value an asynchronous value implementing a `then()` function. */
 export const isAsync = (v) => typeof v === "object" && v !== null && typeof v.then === "function";
 /** Is a value a synchronous value. */
@@ -76,8 +77,6 @@ export class Delay extends AbstractPromise {
         setTimeout(this._resolve, ms);
     }
 }
-/** The `SIGNAL` symbol indicates a signal. */
-export const SIGNAL = Symbol("shelving/SIGNAL");
 /** Resolve to `SIGNAL` on a specific signal. */
 export class Signal extends AbstractPromise {
     constructor() {

package/util/constants.d.ts

@@ -0,0 +1,34 @@
+/** One thousand. */
+export declare const THOUSAND = 1000;
+/** Ten thousand. */
+export declare const TEN_THOUSAND: number;
+/** Hundred thousand. */
+export declare const HUNDRED_THOUSAND: number;
+/** One million. */
+export declare const MILLION: number;
+/** One billion. */
+export declare const BILLION: number;
+/** One trillion. */
+export declare const TRILLION: number;
+/** One second in millseconds. */
+export declare const SECOND = 1000;
+/** One minute in millseconds. */
+export declare const MINUTE: number;
+/** One hour in millseconds. */
+export declare const HOUR: number;
+/** One day in millseconds. */
+export declare const DAY: number;
+/** One week in millseconds. */
+export declare const WEEK: number;
+/** One month in millseconds. */
+export declare const MONTH: number;
+/** One year in millseconds. */
+export declare const YEAR: number;
+/** Non-breaking space. */
+export declare const NBSP = "\u00A0";
+/** Thin space. */
+export declare const THINSP = "\u2009";
+/** Non-breaking narrow space (goes between numbers and their corresponding units). */
+export declare const NNBSP = "\u202F";
+/** The `SIGNAL` symbol indicates a signal. */
+export declare const SIGNAL: unique symbol;

package/util/constants.js

@@ -0,0 +1,34 @@
+/** One thousand. */
+export const THOUSAND = 1000;
+/** Ten thousand. */
+export const TEN_THOUSAND = 10 * THOUSAND;
+/** Hundred thousand. */
+export const HUNDRED_THOUSAND = 100 * THOUSAND;
+/** One million. */
+export const MILLION = 1000 * THOUSAND;
+/** One billion. */
+export const BILLION = 1000 * MILLION;
+/** One trillion. */
+export const TRILLION = 1000 * BILLION;
+/** One second in millseconds. */
+export const SECOND = 1000;
+/** One minute in millseconds. */
+export const MINUTE = 60 * SECOND;
+/** One hour in millseconds. */
+export const HOUR = 60 * MINUTE;
+/** One day in millseconds. */
+export const DAY = 24 * HOUR;
+/** One week in millseconds. */
+export const WEEK = 7 * DAY;
+/** One month in millseconds. */
+export const MONTH = 30 * DAY;
+/** One year in millseconds. */
+export const YEAR = 365 * DAY;
+/** Non-breaking space. */
+export const NBSP = "\xA0";
+/** Thin space. */
+export const THINSP = "\u2009";
+/** Non-breaking narrow space (goes between numbers and their corresponding units). */
+export const NNBSP = "\u202F";
+/** The `SIGNAL` symbol indicates a signal. */
+export const SIGNAL = Symbol("shelving/SIGNAL");

package/util/index.d.ts

@@ -6,6 +6,7 @@ export * from "./boolean.js";
 export * from "./class.js";
 export * from "./clone.js";
 export * from "./color.js";
+export * from "./constants.js";
 export * from "./data.js";
 export * from "./date.js";
 export * from "./debug.js";

package/util/index.js

@@ -6,6 +6,7 @@ export * from "./boolean.js";
 export * from "./class.js";
 export * from "./clone.js";
 export * from "./color.js";
+export * from "./constants.js";
 export * from "./data.js";
 export * from "./date.js";
 export * from "./debug.js";

package/util/iterate.js

@@ -99,6 +99,5 @@ export function* getChunks(input, size) {
 /** Merge two or more iterables into a single iterable set. */
 export function* mergeItems(...inputs) {
     for (const input of inputs)
-        for (const item of input)
-            yield item;
+        yield* input;
 }

package/util/map.d.ts

@@ -2,6 +2,10 @@
 export declare type ImmutableMap<K = unknown, T = unknown> = ReadonlyMap<K, T>;
 /** `Map` that can be changed. */
 export declare type MutableMap<K = unknown, T = unknown> = Map<K, T>;
+/** Extract the type for the value of an entry. */
+export declare type MapKey<X> = X extends ReadonlyMap<infer Y, unknown> ? Y : never;
+/** Extract the type for the value of an entry. */
+export declare type MapValue<X> = X extends ReadonlyMap<unknown, infer Y> ? Y : never;
 /** Things that can be converted to maps. */
 export declare type PossibleMap<K, T> = ImmutableMap<K, T> | Iterable<readonly [K, T]>;
 /** Is an unknown value a map? */
@@ -14,3 +18,7 @@ export declare function getMap<K, T>(iterable: PossibleMap<K, T>): ImmutableMap<
 export declare function limitMap<T>(map: ImmutableMap<T>, limit: number): ImmutableMap<T>;
 /** Function that lets new items in a map be created and updated by calling a `reduce()` callback that receives the existing value. */
 export declare function setMapItem<K, T>(map: MutableMap<K, T>, key: K, value: T): T;
+/** Map that changes `get()` to throw an error if the requested value doesn't exist. */
+export declare class RequiredMap<K, T> extends Map<K, T> {
+    get(key: K): T;
+}

package/util/map.js

@@ -1,5 +1,7 @@
 import { AssertionError } from "../error/AssertionError.js";
+import { RequiredError } from "../error/RequiredError.js";
 import { limitItems } from "./iterate.js";
+import { getString } from "./string.js";
 /** Is an unknown value a map? */
 export const isMap = (v) => v instanceof Map;
 /** Assert that a value is a `Map` instance. */
@@ -20,3 +22,11 @@ export function setMapItem(map, key, value) {
     map.set(key, value);
     return value;
 }
+/** Map that changes `get()` to throw an error if the requested value doesn't exist. */
+export class RequiredMap extends Map {
+    get(key) {
+        if (!this.has(key))
+            throw new RequiredError(`Item "${getString(key)}" is required`);
+        return super.get(key);
+    }
+}

package/util/number.d.ts

@@ -1,6 +1,3 @@
-export declare const TRILLION = 1000000000000;
-export declare const BILLION = 1000000000;
-export declare const MILLION = 1000000;
 /** Is a value a number? */
 export declare const isNumber: (v: unknown) => v is number;
 /** Assert that a value is a number. */
@@ -67,8 +64,8 @@ export declare const truncateNumber: (num: number, precision?: number) => number
  * @returns The number formatted as a string in the browser's current locale.
  */
 export declare function formatNumber(num: number, maxPrecision?: number, minPrecision?: number): string;
-/** Format a number with a short suffix. */
-export declare const formatQuantity: (num: number, suffix: string, maxPrecision?: number, minPrecision?: number) => string;
+/** Format a number with a short abbreviated suffix. */
+export declare const formatQuantity: (num: number, abbr: string, maxPrecision?: number, minPrecision?: number) => 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;
 /**

package/util/number.js

@@ -1,8 +1,5 @@
 import { AssertionError } from "../error/AssertionError.js";
-// Constants.
-export const TRILLION = 1000000000000;
-export const BILLION = 1000000000;
-export const MILLION = 1000000;
+import { BILLION, MILLION, NNBSP, TRILLION } from "./constants.js";
 /** Is a value a number? */
 export const isNumber = (v) => typeof v === "number";
 /** Assert that a value is a number. */
@@ -98,8 +95,8 @@ export function formatNumber(num, maxPrecision = 4, minPrecision = 0) {
         return Number.isNaN(num) ? "None" : "Infinity";
     return new Intl.NumberFormat(undefined, { maximumFractionDigits: maxPrecision, minimumFractionDigits: minPrecision }).format(num);
 }
-/** Format a number with a short suffix. */
-export const formatQuantity = (num, suffix, maxPrecision, minPrecision) => `${formatNumber(num, maxPrecision, minPrecision)}${suffix}`;
+/** Format a number with a short abbreviated suffix. */
+export const formatQuantity = (num, abbr, maxPrecision, minPrecision) => `${formatNumber(num, maxPrecision, minPrecision)}${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);

package/util/sequence.d.ts

@@ -1,4 +1,4 @@
-import { SIGNAL } from "./async.js";
+import { SIGNAL } from "./constants.js";
 import { Handler, Stop, AsyncDispatch, Dispatch } from "./function.js";
 /** Slightly modify the definition of `AsyncIterable` to default `R` and `N` to `void` */
 export declare interface AsyncIterable<T, R = void, N = void> {

package/util/sequence.js

@@ -1,5 +1,6 @@
 import { RequiredError } from "../error/RequiredError.js";
-import { Delay, Signal, SIGNAL } from "./async.js";
+import { Delay, Signal } from "./async.js";
+import { SIGNAL } from "./constants.js";
 import { logError } from "./error.js";
 import { dispatch } from "./function.js";
 /**

package/util/string.d.ts

@@ -9,12 +9,6 @@ export declare type NotString = {
     toUpperCase?: never;
     toLowerCase?: never;
 };
-/** Non-breaking space. */
-export declare const NBSP = "\u00A0";
-/** Thin space. */
-export declare const THINSP = "\u2009";
-/** Non-breaking narrow space (goes between numbers and their corresponding units). */
-export declare const NNBSP = "\u202F";
 /** Is a value a string? */
 export declare const isString: (v: unknown) => v is string;
 /** Assert that a value is a string. */

package/util/string.js

@@ -4,12 +4,6 @@ import { formatDate, isDate } from "./date.js";
 import { formatData, isData } from "./data.js";
 import { getArray, isArray } from "./array.js";
 import { formatNumber, isBetween } from "./number.js";
-/** Non-breaking space. */
-export const NBSP = "\xA0";
-/** Thin space. */
-export const THINSP = "\u2009";
-/** Non-breaking narrow space (goes between numbers and their corresponding units). */
-export const NNBSP = "\u202F";
 /** Is a value a string? */
 export const isString = (v) => typeof v === "string";
 /** Assert that a value is a string. */

package/util/units.d.ts

@@ -1,100 +1,113 @@
 import { PossibleDate } from "./date.js";
-/** One second in millseconds. */
-export declare const SECOND = 1000;
-/** One minute in millseconds. */
-export declare const MINUTE: number;
-/** One hour in millseconds. */
-export declare const HOUR: number;
-/** One day in millseconds. */
-export declare const DAY: number;
-/** One week in millseconds. */
-export declare const WEEK: number;
-/** One month in millseconds. */
-export declare const MONTH: number;
-/** One year in millseconds. */
-export declare const YEAR: number;
-/** Valid information about a unit of measure. */
-export declare type UnitData = {
-    /** Type of a unit. */
-    readonly type: UnitType;
-    /** Singular name for a unit, e.g. `foot` (only needed if different from reference). */
+import { MapKey, RequiredMap } from "./map.js";
+/** Conversion from one unit to another (either a number to multiple by, or a function to convert). */
+declare type Conversion = number | ((num: number) => number);
+/** Set of possible conversions for a set of items. */
+declare type Conversions<T extends string> = {
+    readonly [K in T]?: Conversion;
+};
+declare type UnitProps<T extends string> = {
+    /** Short abbreviation for this unit, e.g. `km` (defaults to first letter of `ref`). */
+    readonly abbr?: string;
+    /** Singular name for this unit, e.g. `kilometer` (defaults to `ref` + "s"). */
     readonly singular?: string;
-    /** Plural name for a unit, e.g. `feet` */
+    /** Plural name for this unit, e.g. `kilometers` (defaults to `ref`). */
     readonly plural?: string;
-    /** Short suffix for this unit, e.g. `km` */
-    readonly suffix: string;
-    /** All units must specify their 'base' unit, e.g. `meter` for for distance units and `liter` for volume units. */
-    readonly base: number;
-} & {
-    [K in UnitReference]?: number;
-};
-/** Valid system of measurement reference. */
-export declare type UnitType = "percentage" | "angle" | "temperature" | "length" | "speed" | "pace" | "mass" | "time" | "volume";
-/** Valid unit of measurement reference (correspond to units allowed in `Intl.NumberFormat`, but not all). */
-export declare type UnitReference = "percent" | "permille" | "permyriad" | "ppm" | "percentage-point" | "basis-point" | "degree" | "millimeter" | "centimeter" | "meter" | "kilometer" | "mile" | "yard" | "foot" | "inch" | "liter" | "milliliter" | "gallon" | "fluid-ounce" | "milligram" | "gram" | "kilogram" | "pound" | "stone" | "ounce" | "millisecond" | "second" | "minute" | "day" | "hour" | "week" | "month" | "year";
-/** List of units. */
-export declare const UNITS: {
-    [K in UnitReference]: UnitData;
+    /** Conversions to other units (typically needs at least the base conversion, unless it's already the base unit). */
+    readonly to?: Conversions<T>;
 };
-/** Convert between two units of the same type. */
-export declare function convertUnits(num: number, from: UnitReference, to: UnitReference): number;
-/**
- * Format a number with a given unit of measure, e.g. `12 kg` or `29.5 l`
- *
- * @param num The number to format.
- * @param unit String reference for a unit of measure e.g. `kilometer`
- * @param maxPrecision Number of decimal places to round the number to e.g. `2`
- */
-export declare const formatUnits: (num: number, unit: UnitReference, maxPrecision?: number, minPrecision?: number) => string;
-/**
- * Format a number with a given unit of measure, e.g. `12 kilograms` or `29.5 liters` or `1 degree`
- *
- * @param num The number to format.
- * @param unit String reference for a unit of measure e.g. `kilometer`
- * @param maxPrecision Number of decimal places to round the number to e.g. `2`
- */
-export declare const formatFullUnits: (num: number, unit: UnitReference, maxPrecision?: number, minPrecision?: number) => string;
-/**
- * Format a percentage.
- * - Combines `getPercent()` and `formatUnits()` for convenience.
- */
+/** Represent a unit. */
+export declare class Unit<T extends string> {
+    /** `UnitList` this unit belongs to. */
+    readonly list: UnitList<T>;
+    private readonly _to;
+    /** Reference for this unit, e.g. `kilometer` */
+    readonly ref: T;
+    /** Short abbreviation for this unit, e.g. `km` (defaults to first letter of `ref`). */
+    readonly abbr: string;
+    /** Singular name for this unit, e.g. `kilometer` (defaults to `ref`). */
+    readonly singular: string;
+    /** Plural name for this unit, e.g. `kilometers` (defaults to `singular` + "s"). */
+    readonly plural: string;
+    constructor(
+    /** `UnitList` this unit belongs to. */
+    list: UnitList<T>, 
+    /** Reference for this unit. */
+    ref: T, 
+    /** Props to configure this unit. */
+    { abbr, singular, plural, to }: UnitProps<T>);
+    /** Convert an amount from this unit to another unit. */
+    to(amount: number, ref?: T | Unit<T>): number;
+    /** Convert an amount from another unit to this unit. */
+    from(amount: number, ref?: T | Unit<T>): number;
+    /** Get a unit from a unit or unit reference. */
+    private _unit;
+    /** 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 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;
+}
+/** Represent a list of units. */
+export declare class UnitList<T extends string> extends RequiredMap<T, Unit<T>> {
+    readonly base: Unit<T>;
+    constructor(units: {
+        [K in T]: UnitProps<T>;
+    });
+}
+export interface UnitList<T extends string> {
+    (units: {
+        [K in T]: UnitProps<T>;
+    }): UnitList<T>;
+    set: never;
+    delete: never;
+}
+/** Percentage units. */
+export declare const PERCENTAGE_UNITS: UnitList<"percent">;
+export declare type PercentageUnit = MapKey<typeof PERCENTAGE_UNITS>;
+/** Point units. */
+export declare const POINT_UNITS: UnitList<"basis-point" | "percentage-point">;
+export declare type PointUnit = MapKey<typeof POINT_UNITS>;
+/** Angle units. */
+export declare const ANGLE_UNITS: UnitList<"degree" | "radian" | "gradian">;
+export declare type AngleUnit = MapKey<typeof ANGLE_UNITS>;
+/** Mass units. */
+export declare const MASS_UNITS: UnitList<"milligram" | "gram" | "kilogram" | "ounce" | "pound" | "stone">;
+export declare type MassUnit = MapKey<typeof MASS_UNITS>;
+/** Time units. */
+export declare const TIME_UNITS: UnitList<"millisecond" | "second" | "minute" | "hour" | "day" | "week" | "month" | "year">;
+export declare type TimeUnit = MapKey<typeof TIME_UNITS>;
+/** Length units. */
+export declare const LENGTH_UNITS: UnitList<"millimeter" | "centimeter" | "meter" | "kilometer" | "inch" | "foot" | "yard" | "furlong" | "mile">;
+export declare type LengthUnit = MapKey<typeof LENGTH_UNITS>;
+/** Speed units. */
+export declare const SPEED_UNITS: UnitList<"meter-per-second" | "kilometer-per-hour" | "mile-per-hour">;
+export declare type SpeedUnit = MapKey<typeof SPEED_UNITS>;
+/** Area units. */
+export declare const AREA_UNITS: UnitList<"square-millimeter" | "square-centimeter" | "square-meter" | "square-kilometer" | "hectare" | "square-inch" | "square-foot" | "square-yard" | "acre">;
+/** Volume units. */
+export declare const VOLUME_UNITS: UnitList<"milliliter" | "liter" | "cubic-centimeter" | "cubic-meter" | "us-fluid-ounce" | "us-pint" | "us-quart" | "us-gallon" | "imperial-fluid-ounce" | "imperial-pint" | "imperial-quart" | "imperial-gallon" | "cubic-inch" | "cubic-foot" | "cubic-yard">;
+export declare type VolumeUnit = MapKey<typeof VOLUME_UNITS>;
+/** Temperature units. */
+export declare const TEMPERATURE_UNITS: UnitList<"celsius" | "fahrenheit" | "kelvin">;
+export declare type TemperatureUnit = 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;
-/** Format a full description 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 const formatFullDuration: (ms: number, maxPrecision?: number, minPrecision?: 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;
 /** Format a description of a duration of time using the most reasonable units e.g. `5y` or `4m` or `12ms`. */
-export declare const formatDuration: (ms: number, maxPrecision?: number, minPrecision?: number) => string;
-/**
- * Return full description of the gap between two dates, e.g. `in 10 days` or `2 hours ago`
- *
- * @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 declare function formatFullWhen(target: PossibleDate, current?: PossibleDate): string;
-/**
- * Return full description of when a date will happen, e.g. `10 days` or `2 hours` or `-1 week`
- *
- * @param target The date when the thing happened.
- * @param current Today's date (or a different date to measure from).
- */
-export declare const formatFullAgo: (target: PossibleDate, current?: PossibleDate) => string;
-/**
- * Compact how long until a date happens, e.g. `in 10d` or `2h ago` or `in 1w`
- *
- * @param target The date when the thing will happen.
- * @param current Today's date (or a different date to measure from).
- */
-export declare function formatWhen(target: PossibleDate, current?: PossibleDate): string;
-/**
- * Return short description of when a date happened, e.g. `10d` or `2h` or `-1w`
- *
- * @param target The date when the thing will happen.
- * @param current Today's date (or a different date to measure from).
- */
+export declare function formatDuration(ms: number, maxPrecision?: number, minPrecision?: 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` */
+export declare const formatWhen: (target: PossibleDate, current?: PossibleDate) => string;
+/** Full when a date happens, e.g. `10 days` or `2 hours` or `-1 week` */
+export declare const formatFullUntil: (target: PossibleDate, current?: PossibleDate) => string;
+/** Compact when a date happens, e.g. `10d` or `2h` or `-1w` */
 export declare const formatUntil: (target: PossibleDate, current?: PossibleDate) => string;
-/**
- * Return short description of when a date will happen, e.g. `10d` or `2h` or `-1w`
- *
- * @param target The date when the thing happened.
- * @param current Today's date (or a different date to measure from).
- */
+/** Full when a date happened, e.g. `10 days` or `2 hours` or `-1 week` */
+export declare const formatFullAgo: (target: PossibleDate, current?: PossibleDate) => string;
+/** Compact when a date will happen, e.g. `10d` or `2h` or `-1w` */
 export declare const formatAgo: (target: PossibleDate, current?: PossibleDate) => string;
+export {};

package/util/units.js

@@ -1,153 +1,256 @@
-import { AssertionError } from "../error/AssertionError.js";
+import { ConditionError } from "../error/ConditionError.js";
+import { DAY, HOUR, MILLION, MINUTE, MONTH, NNBSP, SECOND, WEEK, YEAR } from "./constants.js";
 import { getDuration } from "./date.js";
-import { formatFullQuantity, formatQuantity, getPercent, MILLION } from "./number.js";
-import { NNBSP } from "./string.js";
-/** One second in millseconds. */
-export const SECOND = 1000;
-/** One minute in millseconds. */
-export const MINUTE = 60 * SECOND;
-/** One hour in millseconds. */
-export const HOUR = 60 * MINUTE;
-/** One day in millseconds. */
-export const DAY = 24 * HOUR;
-/** One week in millseconds. */
-export const WEEK = 7 * DAY;
-/** One month in millseconds. */
-export const MONTH = 30 * DAY;
-/** One year in millseconds. */
-export const YEAR = 365 * DAY;
-/** List of units. */
-export const UNITS = {
-    "percent": { type: "percentage", base: 1, suffix: "%" },
-    "permille": { type: "percentage", base: 10, suffix: `${NNBSP}‰` },
-    "permyriad": { type: "percentage", base: 100, suffix: `${NNBSP}‱` },
-    "ppm": { type: "percentage", base: MILLION, suffix: `${NNBSP}ppm`, singular: "part per million", plural: "parts per million" },
-    "percentage-point": { type: "percentage", base: 1, suffix: `${NNBSP}pp`, singular: "percentage point", plural: "percentage points" },
-    "basis-point": { type: "percentage", base: 10000, suffix: `${NNBSP}bp`, singular: "basis point", plural: "basis points" },
-    "degree": { type: "angle", base: 1, suffix: `${NNBSP}deg` },
-    "millimeter": { type: "length", base: 1, suffix: `${NNBSP}mm` },
-    "centimeter": { type: "length", base: 10, suffix: `${NNBSP}cm` },
-    "meter": { type: "length", base: 1000, centimeter: 100, millimeter: 1000, suffix: `${NNBSP}m` },
-    "kilometer": { type: "length", base: 1000000, centimeter: 100000, millimeter: 1000000, suffix: `${NNBSP}km` },
-    "inch": { type: "length", base: 25.4, suffix: `${NNBSP}in` },
-    "foot": { type: "length", base: 304.8, inch: 12, suffix: `${NNBSP}ft`, plural: "feet" },
-    "yard": { type: "length", base: 914.4, inch: 36, foot: 3, suffix: `${NNBSP}yd` },
-    "mile": { type: "length", base: 1609344, yard: 1760, foot: 5280, inch: 63360, suffix: `${NNBSP}mi` },
-    "milliliter": { type: "volume", base: 1, suffix: `${NNBSP}ml` },
-    "liter": { type: "volume", base: 1000, suffix: `${NNBSP}l` },
-    "fluid-ounce": { type: "volume", base: 29.5735295625, gallon: 128, suffix: `${NNBSP}fl${NNBSP}oz`, singular: "fluid ounce", plural: "fluid ounces" },
-    "gallon": { type: "volume", base: 3785.411784, suffix: `${NNBSP}gal` },
-    "milligram": { type: "mass", base: 1, suffix: `${NNBSP}mg` },
-    "gram": { type: "mass", base: 1000, suffix: `${NNBSP}g` },
-    "kilogram": { type: "mass", base: 1000000, suffix: `${NNBSP}kg` },
-    "ounce": { type: "mass", base: 28349.523125, pound: 0.0625, suffix: `${NNBSP}oz` },
-    "pound": { type: "mass", base: 453592.37, ounce: 16, suffix: `${NNBSP}lb` },
-    "stone": { type: "mass", base: 6350293.18, pound: 14, ounce: 224, suffix: `${NNBSP}st`, plural: "stone" },
-    "millisecond": { type: "time", base: 1, suffix: `${NNBSP}ms` },
-    "second": { type: "time", base: SECOND, suffix: `${NNBSP}s` },
-    "minute": { type: "time", base: MINUTE, suffix: `${NNBSP}m` },
-    "hour": { type: "time", base: HOUR, suffix: `${NNBSP}h` },
-    "day": { type: "time", base: DAY, suffix: `${NNBSP}d` },
-    "week": { type: "time", base: WEEK, suffix: `${NNBSP}w` },
-    "month": { type: "time", base: MONTH, suffix: `${NNBSP}m` },
-    "year": { type: "time", base: YEAR, suffix: `${NNBSP}y` },
-};
-/** Convert between two units of the same type. */
-export function convertUnits(num, from, to) {
-    if (from === to)
-        return num;
-    const fromData = UNITS[from];
-    const exact = fromData[to]; // Get the exact conversion if possible (e.g. 5280 feet in a mile).
-    if (typeof exact === "number")
-        return num * exact;
-    const toData = UNITS[to];
-    if (fromData.type !== toData.type)
-        throw new AssertionError(`Target unit must be ${fromData.type}`, toData.type);
-    return (num * fromData.base) / toData.base;
+import { RequiredMap } from "./map.js";
+import { formatFullQuantity, formatQuantity, getPercent } from "./number.js";
+import { getProps } from "./object.js";
+/** Convert an amount using a `Conversion. */
+const _convert = (amount, conversion) => (typeof conversion === "function" ? conversion(amount) : conversion === 1 ? amount : amount * conversion);
+/** Represent a unit. */
+export class Unit {
+    constructor(
+    /** `UnitList` this unit belongs to. */
+    list, 
+    /** Reference for this unit. */
+    ref, 
+    /** Props to configure this unit. */
+    { abbr = ref.slice(0, 1), singular = ref.replace(/-/, " "), plural = `${singular}s`, to }) {
+        this.list = list;
+        this.ref = ref;
+        this.abbr = abbr;
+        this.singular = singular;
+        this.plural = plural;
+        this._to = to;
+    }
+    /** Convert an amount from this unit to another unit. */
+    to(amount, ref = this.list.base) {
+        return this._toUnit(amount, this._unit(ref));
+    }
+    /** Convert an amount from another unit to this unit. */
+    from(amount, ref = this.list.base) {
+        return this._unit(ref)._toUnit(amount, this);
+    }
+    /** Get a unit from a unit or unit reference. */
+    _unit(ref) {
+        return typeof ref === "string" ? this.list.get(ref) : ref;
+    }
+    /** Convert an amount from this unit to another unit (must specify another `Unit` instance). */
+    _toUnit(amount, unit) {
+        var _a, _b, _c;
+        // Convert to self.
+        if (unit === this)
+            return amount;
+        // Exact conversion.
+        const thisToUnit = (_a = this._to) === null || _a === void 0 ? void 0 : _a[unit.ref];
+        if (thisToUnit)
+            return _convert(amount, thisToUnit);
+        // Invert number conversion (can't do this for function conversions).
+        const unitToThis = (_b = unit._to) === null || _b === void 0 ? void 0 : _b[this.ref];
+        if (typeof unitToThis === "number")
+            return amount / unitToThis;
+        // Two step conversion via base.
+        const base = this.list.base;
+        const thisToBase = (_c = this._to) === null || _c === void 0 ? void 0 : _c[base.ref];
+        if (thisToBase)
+            return base._toUnit(_convert(amount, thisToBase), unit);
+        // Cannot convert.
+        throw new ConditionError(`Cannot convert "${this.ref}" to "${unit.ref}"`);
+    }
+    /** 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 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);
+    }
 }
-/**
- * Format a number with a given unit of measure, e.g. `12 kg` or `29.5 l`
- *
- * @param num The number to format.
- * @param unit String reference for a unit of measure e.g. `kilometer`
- * @param maxPrecision Number of decimal places to round the number to e.g. `2`
- */
-export const formatUnits = (num, unit, maxPrecision, minPrecision) => formatQuantity(num, UNITS[unit].suffix, maxPrecision, minPrecision);
-/**
- * Format a number with a given unit of measure, e.g. `12 kilograms` or `29.5 liters` or `1 degree`
- *
- * @param num The number to format.
- * @param unit String reference for a unit of measure e.g. `kilometer`
- * @param maxPrecision Number of decimal places to round the number to e.g. `2`
- */
-export const formatFullUnits = (num, unit, maxPrecision, minPrecision) => formatFullQuantity(num, UNITS[unit].singular || unit, UNITS[unit].plural || `${unit}s`, maxPrecision, minPrecision);
-/**
- * Format a percentage.
- * - Combines `getPercent()` and `formatUnits()` for convenience.
- */
-export const formatPercent = (numerator, denumerator, maxPrecision, minPrecision) => formatQuantity(getPercent(numerator, denumerator), UNITS.percent.suffix, maxPrecision, minPrecision);
-function _formatDuration(formatter, ms, maxPrecision = 0, minPrecision) {
+/** Represent a list of units. */
+export class UnitList extends RequiredMap {
+    constructor(units) {
+        super();
+        for (const [ref, props] of getProps(units)) {
+            const unit = new Unit(this, ref, props);
+            if (!this.base)
+                this.base = unit;
+            super.set(ref, unit);
+        }
+    }
+}
+// Distance constants.
+const IN_PER_FT = 12;
+const IN_PER_YD = 36;
+const IN_PER_MI = 63360;
+const FT_PER_YD = 3;
+const FT_PER_MI = 5280;
+const YD_PER_MI = 1760;
+const YD_PER_FUR = 220;
+const MM_PER_CM = 10;
+const MM_PER_M = 1000;
+const MM_PER_KM = MILLION;
+const MM_PER_IN = 25.4;
+const MM_PER_MI = 1609344;
+// Mass constants.
+const MG_PER_LB = 453592.37;
+const OZ_PER_LB = 16;
+const LB_PER_ST = 14;
+// Area constants.
+const MM2_PER_IN2 = MM_PER_IN ** 2;
+const FT2_PER_ACRE = 66 * 660;
+const YD2_PER_ACRE = 22 * 220;
+// Volume constants.
+const MM3_PER_IN3 = MM_PER_IN ** 3;
+const ML_PER_IN3 = MM3_PER_IN3 / 1000;
+const US_IN3_PER_GAL = 231;
+const IMP_ML_PER_GAL = 4546090 / 1000;
+/** Percentage units. */
+export const PERCENTAGE_UNITS = new UnitList({
+    percent: { abbr: "%", plural: "percent" },
+});
+/** Point units. */
+export const POINT_UNITS = new UnitList({
+    "basis-point": { abbr: "bp" },
+    "percentage-point": { abbr: "pp", to: { "basis-point": 100 } },
+});
+/** Angle units. */
+export const ANGLE_UNITS = new UnitList({
+    degree: { abbr: "deg" },
+    radian: { abbr: "rad", to: { degree: 180 / Math.PI } },
+    gradian: { abbr: "grad", to: { degree: 180 / 200 } },
+});
+/** Mass units. */
+export const MASS_UNITS = new UnitList({
+    // Metric.
+    milligram: { abbr: "mg" },
+    gram: { abbr: "g", to: { milligram: 1000 } },
+    kilogram: { abbr: "kg", to: { milligram: MILLION } },
+    // Imperial.
+    ounce: { abbr: "oz", to: { milligram: MG_PER_LB / OZ_PER_LB } },
+    pound: { abbr: "lb", to: { milligram: MG_PER_LB, ounce: OZ_PER_LB } },
+    stone: { abbr: "st", plural: "stone", to: { milligram: MG_PER_LB * LB_PER_ST, pound: LB_PER_ST, ounce: OZ_PER_LB * LB_PER_ST } },
+});
+/** Time units. */
+export const TIME_UNITS = new UnitList({
+    // Metric.
+    millisecond: { abbr: "ms" },
+    second: { to: { millisecond: SECOND } },
+    minute: { to: { millisecond: MINUTE } },
+    hour: { to: { millisecond: HOUR } },
+    day: { to: { millisecond: DAY } },
+    week: { to: { millisecond: WEEK } },
+    month: { to: { millisecond: MONTH } },
+    year: { to: { millisecond: YEAR } },
+});
+/** Length units. */
+export const LENGTH_UNITS = new UnitList({
+    // Metric.
+    millimeter: { abbr: "mm" },
+    centimeter: { abbr: "cm", to: { millimeter: MM_PER_CM } },
+    meter: { to: { millimeter: MM_PER_M } },
+    kilometer: { abbr: "km", to: { millimeter: MM_PER_KM } },
+    // Imperial.
+    inch: { abbr: "in", plural: "inches", to: { millimeter: MM_PER_IN } },
+    foot: { abbr: "ft", plural: "feet", to: { millimeter: IN_PER_FT * MM_PER_IN, inch: IN_PER_FT } },
+    yard: { abbr: "yd", to: { millimeter: IN_PER_YD * MM_PER_IN, inch: IN_PER_YD, foot: FT_PER_YD } },
+    furlong: { abbr: "fur", to: { millimeter: IN_PER_YD * MM_PER_IN * YD_PER_FUR, foot: YD_PER_FUR * FT_PER_YD, yard: YD_PER_FUR } },
+    mile: { abbr: "mi", to: { millimeter: MM_PER_MI, yard: YD_PER_MI, foot: FT_PER_MI, inch: IN_PER_MI } },
+});
+/** Speed units. */
+export const SPEED_UNITS = new UnitList({
+    // Metric.
+    "meter-per-second": { abbr: "m/s", singular: "meter per second", plural: "meters per second", to: { "kilometer-per-hour": 3.6 } },
+    "kilometer-per-hour": { abbr: "kph", singular: "kilometer per hour", plural: "kilometers per hour", to: { "meter-per-second": MM_PER_KM / HOUR } },
+    // Imperial.
+    "mile-per-hour": { abbr: "mph", singular: "mile per hour", plural: "miles per hour", to: { "meter-per-second": MM_PER_MI / HOUR } },
+});
+/** Area units. */
+export const AREA_UNITS = new UnitList({
+    // Metric.
+    "square-millimeter": { abbr: "mm²" },
+    "square-centimeter": { abbr: "cm²", to: { "square-millimeter": MM_PER_CM ** 2 } },
+    "square-meter": { abbr: "m²", to: { "square-millimeter": MM_PER_M ** 2 } },
+    "square-kilometer": { abbr: "km²", to: { "square-millimeter": MM_PER_KM ** 2 } },
+    "hectare": { abbr: "ha", to: { "square-millimeter": (MM_PER_M * 100) ** 2 } },
+    // Imperial.
+    "square-inch": { abbr: `in²`, plural: "square inches", to: { "square-millimeter": MM2_PER_IN2 } },
+    "square-foot": { abbr: `ft²`, plural: "square feet", to: { "square-millimeter": IN_PER_FT ** 2 * MM2_PER_IN2, "square-inch": IN_PER_FT ** 2 } },
+    "square-yard": { abbr: `yd²`, to: { "square-millimeter": IN_PER_YD ** 2 * MM2_PER_IN2, "square-foot": FT_PER_YD ** 2, "square-inch": IN_PER_YD ** 2 } },
+    "acre": { abbr: "acre", to: { "square-millimeter": IN_PER_YD ** 2 * YD2_PER_ACRE * MM2_PER_IN2, "square-foot": FT2_PER_ACRE, "square-yard": YD2_PER_ACRE } },
+});
+/** Volume units. */
+export const VOLUME_UNITS = new UnitList({
+    // Metric.
+    "milliliter": { abbr: "ml" },
+    "liter": { to: { milliliter: 1000 } },
+    "cubic-centimeter": { abbr: "cm³", to: { milliliter: 1 } },
+    "cubic-meter": { abbr: "m³", to: { milliliter: MILLION } },
+    // US.
+    "us-fluid-ounce": { abbr: `fl${NNBSP}oz`, singular: "US fluid ounce", plural: "US fluid ounces", to: { milliliter: (US_IN3_PER_GAL * ML_PER_IN3) / 128 } },
+    "us-pint": { abbr: "pt", singular: "US pint", to: { "milliliter": (US_IN3_PER_GAL * ML_PER_IN3) / 8, "us-fluid-ounce": 16 } },
+    "us-quart": { abbr: "qt", singular: "US quart", to: { "milliliter": (US_IN3_PER_GAL * ML_PER_IN3) / 4, "us-pint": 2, "us-fluid-ounce": 32 } },
+    "us-gallon": { abbr: "gal", singular: "US gallon", to: { "milliliter": US_IN3_PER_GAL * ML_PER_IN3, "us-quart": 4, "us-pint": 8, "us-fluid-ounce": 128 } },
+    // Imperial.
+    "imperial-fluid-ounce": { abbr: `fl${NNBSP}oz`, to: { milliliter: IMP_ML_PER_GAL / 160 } },
+    "imperial-pint": { abbr: `pt`, to: { "milliliter": IMP_ML_PER_GAL / 8, "imperial-fluid-ounce": 20 } },
+    "imperial-quart": { abbr: "qt", to: { "milliliter": IMP_ML_PER_GAL / 4, "imperial-pint": 2, "imperial-fluid-ounce": 40 } },
+    "imperial-gallon": { abbr: "gal", to: { "milliliter": IMP_ML_PER_GAL, "imperial-quart": 4, "imperial-pint": 8, "imperial-fluid-ounce": 160 } },
+    "cubic-inch": { abbr: "in³", plural: "cubic inches", to: { milliliter: ML_PER_IN3 } },
+    "cubic-foot": { abbr: "ft³", plural: "cubic feet", to: { "milliliter": IN_PER_FT ** 3 * ML_PER_IN3, "cubic-inch": IN_PER_FT ** 3 } },
+    "cubic-yard": { abbr: "yd³", to: { "milliliter": IN_PER_YD ** 3 * ML_PER_IN3, "cubic-foot": FT_PER_YD ** 3, "cubic-inch": IN_PER_YD ** 3 } },
+});
+/** Temperature units. */
+export const TEMPERATURE_UNITS = new UnitList({
+    celsius: { abbr: "°C", singular: "degree Celsius", plural: "degrees Celsius", to: { fahrenheit: n => n * (9 / 5) + 32, kelvin: n => n + 273.15 } },
+    fahrenheit: { abbr: "°F", singular: "degree Fahrenheit", plural: "degrees Fahrenheit", to: { celsius: n => (n - 32) * (5 / 9) } },
+    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);
+/** Format a duration with a formatter. */
+function _getTimeUnitReference(ms) {
     const abs = Math.abs(ms);
-    if (abs <= 99 * SECOND)
-        return formatter(ms, "second", maxPrecision, minPrecision); // Up to 99 seconds, e.g. '22 seconds ago'
-    if (abs <= HOUR)
-        return formatter(ms / MINUTE, "minute", maxPrecision, minPrecision); // Up to one hour  — show minutes, e.g. '18 minutes ago'
-    if (abs <= DAY)
-        return formatter(ms / HOUR, "hour", maxPrecision, minPrecision); // Up to one day — show hours, e.g. '23 hours ago'
-    if (abs <= 2 * WEEK)
-        return formatter(ms / DAY, "day", maxPrecision, minPrecision); // Up to 2 weeks — show days, e.g. '13 days ago'
-    if (abs <= 10 * WEEK)
-        return formatter(ms / WEEK, "week", maxPrecision, minPrecision); // Up to 2 months — show weeks, e.g. '6 weeks ago'
-    if (abs <= 18 * MONTH)
-        return formatter(ms / MONTH, "month", maxPrecision, minPrecision); // Up to 18 months — show months, e.g. '6 months ago'
-    return formatter(ms / YEAR, "year", maxPrecision, minPrecision); // Above 18 months — show years, e.g. '2 years ago'
+    if (abs > 18 * MONTH)
+        return "year";
+    if (abs > 10 * WEEK)
+        return "month";
+    if (abs > 2 * WEEK)
+        return "week";
+    if (abs > DAY)
+        return "day";
+    if (abs > HOUR)
+        return "hour";
+    if (abs > 9949)
+        return "minute";
+    if (abs > SECOND)
+        return "second";
+    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) {
+    const unit = TIME_UNITS.get(_getTimeUnitReference(ms));
+    return unit.formatFull(unit.from(ms), maxPrecision, minPrecision);
 }
-/** Format a full description of a duration of time using the most reasonable units e.g. `5 years` or `1 week` or `4 minutes` or `12 milliseconds`. */
-export const formatFullDuration = (ms, maxPrecision, minPrecision) => _formatDuration(formatFullUnits, ms, maxPrecision, minPrecision);
 /** Format a description of a duration of time using the most reasonable units e.g. `5y` or `4m` or `12ms`. */
-export const formatDuration = (ms, maxPrecision, minPrecision) => _formatDuration(formatUnits, ms, maxPrecision, minPrecision);
-/**
- * Return full description of the gap between two dates, e.g. `in 10 days` or `2 hours ago`
- *
- * @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 formatFullWhen(target, current) {
-    const ms = getDuration(target, current);
-    const abs = Math.abs(ms);
-    const duration = formatFullDuration(abs);
-    return abs < 10 * SECOND ? "just now" : ms > 0 ? `in ${duration}` : `${duration} ago`;
+export function formatDuration(ms, maxPrecision, minPrecision) {
+    const unit = TIME_UNITS.get(_getTimeUnitReference(ms));
+    return unit.format(unit.from(ms), maxPrecision, minPrecision);
 }
-/**
- * Return full description of when a date will happen, e.g. `10 days` or `2 hours` or `-1 week`
- *
- * @param target The date when the thing happened.
- * @param current Today's date (or a different date to measure from).
- */
-export const formatFullAgo = (target, current) => formatFullDuration(getDuration(current, target));
-/**
- * Compact how long until a date happens, e.g. `in 10d` or `2h ago` or `in 1w`
- *
- * @param target The date when the thing will happen.
- * @param current Today's date (or a different date to measure from).
- */
-export function formatWhen(target, current) {
+/** format when a data happens/happened. */
+function _formatWhen(formatter, target, current) {
     const ms = getDuration(target, current);
     const abs = Math.abs(ms);
-    const duration = formatDuration(abs);
+    const duration = formatter(ms);
     return abs < 10 * SECOND ? "just now" : ms > 0 ? `in ${duration}` : `${duration} ago`;
 }
-/**
- * Return short description of when a date happened, e.g. `10d` or `2h` or `-1w`
- *
- * @param target The date when the thing will happen.
- * @param current Today's date (or a different date to measure from).
- */
+/** Full when a date happens/happened, e.g. `in 10 days` or `2 hours ago` */
+export const formatFullWhen = (target, current) => _formatWhen(formatFullDuration, target, current);
+/** Compact when a date happens/happened, e.g. `in 10d` or `2h ago` or `in 1w` */
+export const formatWhen = (target, current) => _formatWhen(formatDuration, target, current);
+/** Full when a date happens, e.g. `10 days` or `2 hours` or `-1 week` */
+export const formatFullUntil = (target, current) => formatFullDuration(getDuration(target, current));
+/** Compact when a date happens, e.g. `10d` or `2h` or `-1w` */
 export const formatUntil = (target, current) => formatDuration(getDuration(target, current));
-/**
- * Return short description of when a date will happen, e.g. `10d` or `2h` or `-1w`
- *
- * @param target The date when the thing happened.
- * @param current Today's date (or a different date to measure from).
- */
+/** Full when a date happened, e.g. `10 days` or `2 hours` or `-1 week` */
+export const formatFullAgo = (target, current) => formatFullDuration(getDuration(current, target));
+/** Compact when a date will happen, e.g. `10d` or `2h` or `-1w` */
 export const formatAgo = (target, current) => formatDuration(getDuration(current, target));