shelving 1.135.0 → 1.137.0

package/util/source.d.ts

@@ -3,11 +3,7 @@ import type { Class } from "./class.js";
 export interface Sourceable<T> {
     readonly source: T;
 }
-/**
- * Recurse through `Sourceable` objects and return the first one that is an instance of `type`, or `null` if no source object matches.
- */
-export declare function getOptionalSource<T>(type: Class<T>, value: unknown): T | undefined;
-/**
- * Recurse through `Sourceable` objects and return the first one that is an instance of `type`.
- */
-export declare function getSource<T>(type: Class<T>, data: unknown): T;
+/** Recurse through `Sourceable` objects and return the first one that is an instance of `type`, or `undefined` if no source object matches. */
+export declare function getSource<T>(type: Class<T>, value: unknown): T | undefined;
+/** Recurse through `Sourceable` objects and return the first one that is an instance of `type`, or throw `RequiredError` if no source object matches. */
+export declare function requireSource<T>(type: Class<T>, data: unknown): T;

package/util/source.js

@@ -1,22 +1,18 @@
-import { ValidationError } from "../error/ValidationError.js";
+import { RequiredError } from "../error/RequiredError.js";
 import { isObject } from "./object.js";
-/**
- * Recurse through `Sourceable` objects and return the first one that is an instance of `type`, or `null` if no source object matches.
- */
-export function getOptionalSource(type, value) {
+/** Recurse through `Sourceable` objects and return the first one that is an instance of `type`, or `undefined` if no source object matches. */
+export function getSource(type, value) {
     if (isObject(value)) {
         if (value instanceof type)
             return value;
         if ("source" in value)
-            return getOptionalSource(type, value.source);
+            return getSource(type, value.source);
     }
 }
-/**
- * Recurse through `Sourceable` objects and return the first one that is an instance of `type`.
- */
-export function getSource(type, data) {
-    const source = getOptionalSource(type, data);
+/** Recurse through `Sourceable` objects and return the first one that is an instance of `type`, or throw `RequiredError` if no source object matches. */
+export function requireSource(type, data) {
+    const source = getSource(type, data);
     if (!source)
-        throw new ValidationError(`Source "${type.name}" not found`, data);
+        throw new RequiredError(`Source "${type.name}" not found`, { received: data, expected: type, caller: requireSource });
     return source;
 }

package/util/string.d.ts

@@ -27,12 +27,12 @@ export declare function assertString(value: unknown): asserts value is string;
  * - Everything else returns `"Unknown"`
  */
 export declare function getString(value: unknown): string;
-/** Does a string have the specified minimum length.  */
+/** Does a string have the specified length. */
 export declare function isStringLength(str: string, min?: number, max?: number): boolean;
-/** Assert that a value has a specific length (or length is in a specific range). */
+/** Assert that a value has a specific length, or throw `AssertionError` if the string is outside that length. */
 export declare function assertStringLength(str: unknown, min?: number, max?: number): asserts str is string;
-/** Get a string if it has the specified minimum length.  */
-export declare function getStringLength(str: string, min?: number, max?: number): string;
+/** Get a string if it has the specified length, or throw `RequiredError` if the string was outside that length. */
+export declare function requireStringLength(str: string, min?: number, max?: number): string;
 /** Concatenate an iterable set of strings together. */
 export declare function joinStrings(strs: Iterable<string> & NotString, joiner?: string): string;
 /**
@@ -66,22 +66,14 @@ export declare function sanitizeMultilineText(str: string): string;
  * @todo Convert confusables (e.g. `ℵ` alef symbol or `℮` estimate symbol) to their letterlike equivalent (e.g. `N` and `e`).
  */
 export declare function simplifyString(str: string): string;
-/**
- * Convert a string to a `kebab-case` URL slug, or return `undefined` if conversion resulted in an empty ref.
- */
-export declare function getOptionalSlug(str: string): string | undefined;
-/**
- * Convert a string to a `kebab-case` URL slug, or throw `ValueError` if conversion resulted in an empty ref.
- */
-export declare function getSlug(str: string): string;
-/**
- * Convert a string to a unique ref e.g. `abc123`, or return `undefined` if conversion resulted in an empty string.
- */
-export declare function getOptionalRef(str: string): string | undefined;
-/**
- * Convert a string to a unique ref e.g. `abc123`, or throw `ValueError` if conversion resulted in an empty string.
- */
-export declare function getRef(str: string): string;
+/** Convert a string to a `kebab-case` URL slug, or return `undefined` if conversion resulted in an empty ref. */
+export declare function getSlug(str: string): string | undefined;
+/** Convert a string to a `kebab-case` URL slug, or throw `RequiredError` if conversion resulted in an empty ref. */
+export declare function requireSlug(str: string): string;
+/** Convert a string to a unique ref e.g. `abc123`, or return `undefined` if conversion resulted in an empty string. */
+export declare function getRef(str: string): string | undefined;
+/** Convert a string to a unique ref e.g. `abc123`, or throw `RequiredError` if conversion resulted in an empty string. */
+export declare function requireRef(str: string): string;
 /**
  * Return an array of the separate words and "quoted phrases" found in a string.
  * - Phrases enclosed "in quotes" are a single word.
@@ -108,8 +100,8 @@ export declare function limitString(str: string, maxLength: number, append?: str
  * - Excess segments in `String.prototype.split()` is counterintuitive because further parts are thrown away.
  * - Excess segments in `splitString()` are concatenated onto the last segment (set `max` to `null` if you want infinite segments).
  *
- * @throws ValueError if `min` isn't met.
- * @throws ValueError if any of the segments are empty.
+ * @throws AssertionError if `min` isn't met.
+ * @throws AssertionError if any of the segments are empty.
  */
 export declare function splitString(str: string, separator: string, min: 1, max: 1): readonly [string];
 export declare function splitString(str: string, separator: string, min: 2, max: 2): readonly [string, string];

package/util/string.js

@@ -1,4 +1,6 @@
-import { ValidationError } from "../error/ValidationError.js";
+import { AssertionError } from "../error/AssertionError.js";
+import { RequiredError } from "../error/RequiredError.js";
+import { ValueError } from "../error/ValueError.js";
 import { getArray, isArray } from "./array.js";
 import { formatDate, isDate } from "./date.js";
 import { formatNumber, formatRange, isBetween } from "./number.js";
@@ -10,7 +12,7 @@ export function isString(value) {
 /** Assert that a value is a string. */
 export function assertString(value) {
     if (typeof value !== "string")
-        throw new ValidationError("Must be string", value);
+        throw new ValueError("Must be string", { received: value, caller: assertString });
 }
 /**
  * Convert an unknown value into a title string for user-facing use.
@@ -46,18 +48,19 @@ export function getString(value) {
         return formatObject(value);
     return "Unknown";
 }
-/** Does a string have the specified minimum length.  */
+/** Does a string have the specified length. */
 export function isStringLength(str, min = 1, max = Number.POSITIVE_INFINITY) {
     return str.length >= min && str.length <= max;
 }
-/** Assert that a value has a specific length (or length is in a specific range). */
+/** Assert that a value has a specific length, or throw `AssertionError` if the string is outside that length. */
 export function assertStringLength(str, min = 1, max = Number.POSITIVE_INFINITY) {
     if (!isString(str) || !isStringLength(str, min, max))
-        throw new ValidationError(`Must be string with length ${formatRange(min, max)}`, str);
+        throw new AssertionError(`Must be string with length ${formatRange(min, max)}`, { received: str, caller: assertStringLength });
 }
-/** Get a string if it has the specified minimum length.  */
-export function getStringLength(str, min = 1, max = Number.POSITIVE_INFINITY) {
-    assertStringLength(str, min, max);
+/** Get a string if it has the specified length, or throw `RequiredError` if the string was outside that length. */
+export function requireStringLength(str, min = 1, max = Number.POSITIVE_INFINITY) {
+    if (!isStringLength(str, min, max))
+        throw new RequiredError(`Must be string with length ${formatRange(min, max)}`, { received: str, caller: requireStringLength });
     return str;
 }
 /** Concatenate an iterable set of strings together. */
@@ -118,35 +121,27 @@ export function simplifyString(str) {
         .trim()
         .toLowerCase();
 }
-/**
- * Convert a string to a `kebab-case` URL slug, or return `undefined` if conversion resulted in an empty ref.
- */
-export function getOptionalSlug(str) {
+/** Convert a string to a `kebab-case` URL slug, or return `undefined` if conversion resulted in an empty ref. */
+export function getSlug(str) {
     return simplifyString(str).replaceAll(" ", "-") || undefined;
 }
-/**
- * Convert a string to a `kebab-case` URL slug, or throw `ValueError` if conversion resulted in an empty ref.
- */
-export function getSlug(str) {
-    const slug = getOptionalSlug(str);
+/** Convert a string to a `kebab-case` URL slug, or throw `RequiredError` if conversion resulted in an empty ref. */
+export function requireSlug(str) {
+    const slug = getSlug(str);
     if (slug)
         return slug;
-    throw new ValidationError("Invalid slug", str);
+    throw new RequiredError("Invalid slug", { received: str, caller: requireSlug });
 }
-/**
- * Convert a string to a unique ref e.g. `abc123`, or return `undefined` if conversion resulted in an empty string.
- */
-export function getOptionalRef(str) {
+/** Convert a string to a unique ref e.g. `abc123`, or return `undefined` if conversion resulted in an empty string. */
+export function getRef(str) {
     return simplifyString(str).replaceAll(" ", "") || undefined;
 }
-/**
- * Convert a string to a unique ref e.g. `abc123`, or throw `ValueError` if conversion resulted in an empty string.
- */
-export function getRef(str) {
-    const ref = getOptionalRef(str);
+/** Convert a string to a unique ref e.g. `abc123`, or throw `RequiredError` if conversion resulted in an empty string. */
+export function requireRef(str) {
+    const ref = getRef(str);
     if (ref)
         return ref;
-    throw new ValidationError("Invalid string ref", str);
+    throw new RequiredError("Invalid string ref", { received: str, caller: requireRef });
 }
 /**
  * Return an array of the separate words and "quoted phrases" found in a string.
@@ -195,6 +190,9 @@ export function splitString(str, separator, min = 1, max = Number.POSITIVE_INFIN
     if (segments.length > max)
         segments.splice(max - 1, segments.length, segments.slice(max - 1).join(separator));
     if (segments.length < min || !segments.every(Boolean))
-        throw new ValidationError(`Must be string with ${formatRange(min, max)} non-empty segments separated by "${separator}"`, str);
+        throw new ValueError(`Must be string with ${formatRange(min, max)} non-empty segments separated by "${separator}"`, {
+            received: str,
+            caller: splitString,
+        });
     return segments;
 }

package/util/template.js

@@ -1,4 +1,4 @@
-import { ValidationError } from "../error/ValidationError.js";
+import { ValueError } from "../error/ValueError.js";
 import { EMPTY_DATA } from "./data.js";
 import { setMapItem } from "./map.js";
 import { isObject } from "./object.js";
@@ -6,8 +6,6 @@ import { isObject } from "./object.js";
 const R_PLACEHOLDERS = /(\*|:[a-z][a-z0-9]*|\$\{[a-z][a-z0-9]*\}|\{\{[a-z][a-z0-9]*\}\}|\{[a-z][a-z0-9]*\})/i;
 // Find actual name within template placeholder e.g. `${name}` → `name`
 const R_NAME = /[a-z0-9]+/i;
-// Cache of templates.
-const TEMPLATE_CACHE = new Map();
 /**
  * Split up a template into an array of separator → placeholder → separator → placeholder → separator
  * - Odd numbered chunks are separators.
@@ -16,10 +14,7 @@ const TEMPLATE_CACHE = new Map();
  * @param template The template including template placeholders, e.g. `:name-${country}/{city}`
  * @returns Array of strings alternating separator and placeholder.
  */
-function _splitTemplate(template) {
-    return TEMPLATE_CACHE.get(template) || setMapItem(TEMPLATE_CACHE, template, _split(template));
-}
-function _split(template) {
+function _splitTemplate(template, caller) {
     const matches = template.split(R_PLACEHOLDERS);
     let asterisks = 0;
     const chunks = [];
@@ -28,12 +23,16 @@ function _split(template) {
         const placeholder = matches[i];
         const post = matches[i + 1];
         if (i > 1 && !pre.length)
-            throw new ValidationError("Placeholders must be separated by at least one character", template);
+            throw new ValueError("Placeholders must be separated by at least one character", { received: template, caller });
         const name = placeholder === "*" ? String(asterisks++) : R_NAME.exec(placeholder)?.[0] || "";
         chunks.push({ pre, placeholder, name, post });
     }
     return chunks;
 }
+const TEMPLATE_CACHE = new Map();
+function _splitTemplateCached(template, caller) {
+    return TEMPLATE_CACHE.get(template) || setMapItem(TEMPLATE_CACHE, template, _splitTemplate(template, caller));
+}
 /**
  * Get list of placeholders named in a template string.
  *
@@ -41,7 +40,7 @@ function _split(template) {
  * @returns Array of clean string names of found placeholders, e.g. `["name", "country", "city"]`
  */
 export function getPlaceholders(template) {
-    return _splitTemplate(template).map(_getPlaceholder);
+    return _splitTemplateCached(template, getPlaceholders).map(_getPlaceholder);
 }
 function _getPlaceholder({ name }) {
     return name;
@@ -57,7 +56,7 @@ function _getPlaceholder({ name }) {
  */
 export function matchTemplate(template, target) {
     // Get separators and placeholders from template.
-    const chunks = _splitTemplate(template);
+    const chunks = _splitTemplateCached(template, matchTemplate);
     const firstChunk = chunks[0];
     // Return early if empty.
     if (!firstChunk)
@@ -102,7 +101,7 @@ export function matchTemplates(templates, target) {
  * @throws {ReferenceError} If a placeholder in the template string is not specified in values.
  */
 export function renderTemplate(template, value) {
-    const chunks = _splitTemplate(template);
+    const chunks = _splitTemplateCached(template, renderTemplate);
     if (!chunks.length)
         return template;
     let output = template;

package/util/time.d.ts

@@ -1,4 +1,3 @@
-import type { Optional } from "./optional.js";
 /** 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 time string. */
@@ -40,13 +39,11 @@ export declare function isTime(value: unknown): value is Time;
  *
  * @param possible Any value that we want to parse as a valid time (defaults to `undefined`).
  */
-export declare function getOptionalTime(possible: unknown): Time | undefined;
+export declare function getTime(possible: unknown): Time | undefined;
 /**
  * Convert a possible date to a `Time` instance, or throw `ValueError` if it couldn't be converted (defaults to `"now"`).
  * @param possible Any value that we want to parse as a valid time (defaults to `"now"`).
  */
-export declare function getTime(possible?: PossibleTime): Time;
+export declare function requireTime(possible?: PossibleTime): Time;
 /** Format a time as a string based on the browser locale settings. */
 export declare function 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 function formatOptionalTime(time: Optional<PossibleTime>, precision?: 2 | 3 | 4 | 5 | 6): string | undefined;

package/util/time.js

@@ -1,6 +1,6 @@
-import { ValidationError } from "../error/ValidationError.js";
+import { ValueError } from "../error/ValueError.js";
 import { DAY, HOUR, MINUTE, SECOND } from "./constants.js";
-import { getOptionalDate } from "./date.js";
+import { getDate } 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 {
@@ -20,7 +20,7 @@ export class Time {
                     (typeof ms === "string" ? Number.parseInt(ms, 10) : 0));
             }
         }
-        const date = getOptionalDate(possible);
+        const date = getDate(possible);
         if (date)
             return new Time(date.getHours() * HOUR + date.getMinutes() * MINUTE + date.getSeconds() * SECOND + date.getMilliseconds());
     }
@@ -72,7 +72,7 @@ export class Time {
             hour: "2-digit",
             minute: "2-digit",
             second: precision >= 3 ? "2-digit" : undefined,
-            fractionalSecondDigits: precision >= 4 ? precision - 3 : undefined,
+            fractionalSecondDigits: precision >= 4 ? (precision - 3) : undefined,
         });
     }
     // Implement `valueOf()`
@@ -100,24 +100,23 @@ export function isTime(value) {
  *
  * @param possible Any value that we want to parse as a valid time (defaults to `undefined`).
  */
-export function getOptionalTime(possible) {
+export function getTime(possible) {
     return Time.from(possible);
 }
 /**
  * Convert a possible date to a `Time` instance, or throw `ValueError` if it couldn't be converted (defaults to `"now"`).
  * @param possible Any value that we want to parse as a valid time (defaults to `"now"`).
  */
-export function getTime(possible = "now") {
-    const time = getOptionalTime(possible);
+export function requireTime(possible) {
+    return _time(requireTime, possible);
+}
+function _time(caller, possible = "now") {
+    const time = Time.from(possible);
     if (!time)
-        throw new ValidationError("Invalid time", possible);
+        throw new ValueError("Invalid time", { received: possible, caller });
     return time;
 }
 /** Format a time as a string based on the browser locale settings. */
 export function formatTime(time, precision = 2) {
-    return getTime(time).format(precision);
-}
-/** Format an optional time as a string based on the browser locale settings. */
-export function formatOptionalTime(time, precision = 2) {
-    return getOptionalTime(time)?.format(precision);
+    return _time(formatTime, time).format(precision);
 }

package/util/undefined.js

@@ -1,4 +1,4 @@
-import { ValidationError } from "../error/ValidationError.js";
+import { AssertionError } from "../error/AssertionError.js";
 /** Function that always returns undefined. */
 export const getUndefined = () => undefined;
 /** Is a value undefined? */
@@ -14,7 +14,7 @@ export const notUndefined = isDefined;
 /** Assert that a value is not `undefined` */
 export function assertDefined(value) {
     if (value === undefined)
-        throw new ValidationError("Must be defined", value);
+        throw new AssertionError("Must be defined", { received: value, caller: assertDefined });
 }
 /** Get a defined value. */
 export function getDefined(value) {

package/util/units.d.ts

@@ -1,6 +1,5 @@
 import type { MapKey } from "./map.js";
 import { ImmutableMap } from "./map.js";
-import type { NumberOptions } from "./number.js";
 import type { ImmutableObject } from "./object.js";
 /** Conversion from one unit to another (either an amount to multiple by, or a function to convert). */
 type Conversion = number | ((num: number) => number);
@@ -17,6 +16,8 @@ type UnitProps<T extends string> = {
     readonly plural?: string;
     /** Conversions to other units (typically needs at least the base conversion, unless it's already the base unit). */
     readonly to?: Conversions<T>;
+    /** Possible options for formatting these units with `Intl.NumberFormat` (`.unit` can be specified if different from key, but is not required). */
+    readonly options?: Intl.NumberFormatOptions;
 };
 /** Represent a unit. */
 export declare class Unit<K extends string> {
@@ -31,6 +32,8 @@ export declare class Unit<K extends string> {
     readonly singular: string;
     /** Plural name for this unit, e.g. `kilometers` (defaults to `singular` + "s"). */
     readonly plural: string;
+    /** Possible options for formatting these units with `Intl.NumberFormat` (`.unit` can be specified if different from key, but is not required). */
+    readonly options?: Readonly<Intl.NumberFormatOptions>;
     /** Title for this unit (uses format `abbr (plural)`, e.g. `fl oz (US fluid ounces)`) */
     get title(): string;
     constructor(
@@ -41,15 +44,17 @@ export declare class Unit<K extends string> {
     /** Props to configure this unit. */
     { abbr, singular, plural, to }: UnitProps<K>);
     /** Convert an amount from this unit to another unit. */
-    to(amount: number, units?: K): number;
+    to(amount: number, targetKey?: K): number;
     /** Convert an amount from another unit to this unit. */
-    from(amount: number, units?: K): number;
+    from(amount: number, sourceKey?: K): number;
     /** Convert an amount from this unit to another unit (must specify another `Unit` instance). */
-    private _toUnit;
-    /** Format an amount with a given unit of measure, e.g. `12 kg` or `29.5 l` */
-    format(amount: number, options?: NumberOptions): string;
-    /** Format an amount with a given unit of measure, e.g. `12 kilograms` or `29.5 liters` or `1 degree` */
-    pluralize(amount: number, options?: NumberOptions): string;
+    private _convertTo;
+    /**
+     * Format an amount with a given unit of measure, e.g. `12 kg` or `29.5 l`
+     * - Uses `Intl.NumberFormat` if this is a supported unit (so e.g. `ounce` is translated to e.g. `Unze` in German).
+     * - Polyfills unsupported units to use long/short form based on `options.unitDisplay`.
+     */
+    format(amount: number, options?: Intl.NumberFormatOptions): string;
 }
 /**
  * Represent a list of units.
@@ -61,12 +66,12 @@ export declare class UnitList<K extends string> extends ImmutableMap<K, Unit<K>>
     readonly base: Unit<K>;
     constructor(units: ImmutableObject<K, UnitProps<K>>);
     /** Convert an amount from a unit to another unit. */
-    convert(amount: number, sourceUnits: K, targetUnits: K): number;
+    convert(amount: number, sourceKey: K, targetKey: K): number;
     /**
-     * Get a unit from this list.
-     * @throws RequiredError if the unit is not found.
+     * Require a unit from this list.
+     * @throws RequiredError if the unit key is not found.
      */
-    getUnit(units: K): Unit<K>;
+    require(key: K): Unit<K>;
 }
 /** Percentage units. */
 export declare const PERCENT_UNITS: UnitList<"percent">;

package/util/units.js

@@ -1,8 +1,8 @@
-import { NotFoundError } from "../error/NotFoundError.js";
-import { ValidationError } from "../error/ValidationError.js";
+import { RequiredError } from "../error/RequiredError.js";
+import { ValueError } from "../error/ValueError.js";
 import { DAY, HOUR, MILLION, MINUTE, MONTH, NNBSP, SECOND, WEEK, YEAR } from "./constants.js";
 import { ImmutableMap } from "./map.js";
-import { formatQuantity, pluralizeQuantity } from "./number.js";
+import { formatNumber, formatQuantity, pluralizeQuantity } from "./number.js";
 import { getProps } from "./object.js";
 /** Convert an amount using a `Conversion. */
 function _convert(amount, conversion) {
@@ -21,6 +21,8 @@ export class Unit {
     singular;
     /** Plural name for this unit, e.g. `kilometers` (defaults to `singular` + "s"). */
     plural;
+    /** Possible options for formatting these units with `Intl.NumberFormat` (`.unit` can be specified if different from key, but is not required). */
+    options;
     /** Title for this unit (uses format `abbr (plural)`, e.g. `fl oz (US fluid ounces)`) */
     get title() {
         return `${this.abbr} (${this.plural})`;
@@ -40,41 +42,53 @@ export class Unit {
         this._to = to;
     }
     /** Convert an amount from this unit to another unit. */
-    to(amount, units) {
-        return this._toUnit(amount, units ? this.list.getUnit(units) : this.list.base);
+    to(amount, targetKey) {
+        const target = targetKey ? _requireUnit(this.to, this.list, targetKey) : this.list.base;
+        return this._convertTo(amount, target, this.to);
     }
     /** Convert an amount from another unit to this unit. */
-    from(amount, units) {
-        return (units ? this.list.getUnit(units) : this.list.base)._toUnit(amount, this);
+    from(amount, sourceKey) {
+        const source = sourceKey ? _requireUnit(this.from, this.list, sourceKey) : this.list.base;
+        return source._convertTo(amount, this, this.from);
     }
     /** Convert an amount from this unit to another unit (must specify another `Unit` instance). */
-    _toUnit(amount, unit) {
-        // Convert to self.
-        if (unit === this)
+    _convertTo(amount, target, caller) {
+        // No conversion.
+        if (target === this)
             return amount;
         // Exact conversion.
-        const thisToUnit = this._to?.[unit.key];
+        // When this unit knows the multiplier or function to convert to the target unit.
+        const thisToUnit = this._to?.[target.key];
         if (thisToUnit)
             return _convert(amount, thisToUnit);
-        // Invert number conversion (can't do this for function conversions).
-        const unitToThis = unit._to?.[this.key];
+        // Invert number conversion.
+        // This is where the target type knows the multiplier to convert to this.
+        // Can't do this for function conversions.
+        const unitToThis = target._to?.[this.key];
         if (typeof unitToThis === "number")
             return amount / unitToThis;
-        // Two step conversion via base.
+        // Via base conversion.
+        // Everything should know how to convert to its base units.
         const base = this.list.base;
         const thisToBase = this._to?.[base.key];
         if (thisToBase)
-            return base._toUnit(_convert(amount, thisToBase), unit);
-        // Cannot convert.
-        throw new ValidationError(`Cannot convert "${this.key}" to "${unit.key}"`);
+            return base._convertTo(_convert(amount, thisToBase), target, caller);
+        // Not convertable.
+        throw new ValueError(`Cannot convert "${base.key}" to "${this.key}"`, { list: this, caller });
     }
-    /** Format an amount with a given unit of measure, e.g. `12 kg` or `29.5 l` */
+    /**
+     * Format an amount with a given unit of measure, e.g. `12 kg` or `29.5 l`
+     * - Uses `Intl.NumberFormat` if this is a supported unit (so e.g. `ounce` is translated to e.g. `Unze` in German).
+     * - Polyfills unsupported units to use long/short form based on `options.unitDisplay`.
+     */
     format(amount, options) {
-        return formatQuantity(amount, this.abbr, options);
-    }
-    /** Format an amount with a given unit of measure, e.g. `12 kilograms` or `29.5 liters` or `1 degree` */
-    pluralize(amount, options) {
-        return pluralizeQuantity(amount, this.singular, this.plural, options);
+        // If possible use `Intl` so that the user's locale is used.
+        if (Intl.supportedValuesOf("unit").includes(this.key))
+            return formatNumber(amount, { style: "unit", unitDisplay: "short", ...this.options, ...options, unit: this.key });
+        // Otherwise, use the default number format.
+        // If unitDisplay is "long" use the singular/plural form.
+        const o = { style: "decimal", unitDisplay: "short", ...this.options, ...options };
+        return o.unitDisplay === "long" ? pluralizeQuantity(amount, this.singular, this.plural, o) : formatQuantity(amount, this.abbr, o);
     }
 }
 /**
@@ -95,19 +109,23 @@ export class UnitList extends ImmutableMap {
         }
     }
     /** Convert an amount from a unit to another unit. */
-    convert(amount, sourceUnits, targetUnits) {
-        return this.getUnit(sourceUnits).to(amount, targetUnits);
+    convert(amount, sourceKey, targetKey) {
+        return _requireUnit(this.convert, this, sourceKey).to(amount, targetKey);
     }
     /**
-     * Get a unit from this list.
-     * @throws RequiredError if the unit is not found.
+     * Require a unit from this list.
+     * @throws RequiredError if the unit key is not found.
      */
-    getUnit(units) {
-        if (this.has(units))
-            return this.get(units);
-        throw new NotFoundError("Unknown unit", units);
+    require(key) {
+        return _requireUnit(this.require, this, key);
     }
 }
+function _requireUnit(caller, list, key) {
+    const unit = list.get(key);
+    if (!unit)
+        throw new RequiredError(`Unknown unit "${key}"`, { key, list, caller });
+    return unit;
+}
 // Distance constants.
 const IN_PER_FT = 12;
 const IN_PER_YD = 36;
@@ -160,17 +178,20 @@ export const MASS_UNITS = new UnitList({
     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 } },
 });
+const TIME_OPTIONS = {
+    roundingMode: "trunc",
+    maximumFractionDigits: 0,
+};
 /** 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 } },
+    millisecond: { abbr: "ms", options: TIME_OPTIONS },
+    second: { to: { millisecond: SECOND }, options: TIME_OPTIONS },
+    minute: { to: { millisecond: MINUTE }, options: TIME_OPTIONS },
+    hour: { to: { millisecond: HOUR }, options: TIME_OPTIONS },
+    day: { to: { millisecond: DAY }, options: TIME_OPTIONS },
+    week: { to: { millisecond: WEEK }, options: TIME_OPTIONS },
+    month: { to: { millisecond: MONTH }, options: TIME_OPTIONS },
+    year: { to: { millisecond: YEAR }, options: TIME_OPTIONS },
 });
 /** Length units. */
 export const LENGTH_UNITS = new UnitList({

package/util/url.d.ts

@@ -5,9 +5,9 @@ export type PossibleURL = string | URL;
 export declare function isURL(value: unknown): value is URL;
 /** Assert that an unknown value is a URL object. */
 export declare function assertURL(value: unknown): asserts value is URL;
-/** Convert a possible URL to a URL or return `undefined` if conversion fails. */
+/** Convert a possible URL to a URL, or return `undefined` if conversion fails. */
 export declare function getOptionalURL(possible: Optional<PossibleURL>, base?: PossibleURL | undefined): URL | undefined;
-/** Convert a possible URL to a URL but throw `ValueError` if conversion fails. */
-export declare function getURL(possible: PossibleURL, base?: PossibleURL): URL;
+/** Convert a possible URL to a URL, or throw `AssertionError` if conversion fails. */
+export declare function requireURL(possible: PossibleURL, base?: PossibleURL): URL;
 /** Just get the important part of a URL, e.g. `http://shax.com/test?uid=129483` → `shax.com/test` */
 export declare function formatURL(possible: PossibleURL, base?: PossibleURL): string;