shelving 1.86.0 → 1.86.2

package/util/data.js

@@ -13,25 +13,7 @@ export function getData(result) {
 export function getDataProps(data) {
     return Object.entries(data);
 }
-/**
- * Format a data object as a string.
- * - Use the custom `.toString()` function if it exists (don't use built in `Object.prototype.toString` because it's useless.
- * - Use `.title` or `.name` or `.id` if they exist and are strings.
- * - Use `Object` otherwise.
- */
-export function formatData(data) {
-    const { toString, name, title, id } = data;
-    if (typeof toString === "function" && toString !== Object.prototype.toString)
-        return data.toString();
-    if (typeof name === "string")
-        return name;
-    if (typeof title === "string")
-        return title;
-    if (typeof id === "string")
-        return id;
-    return "Object";
-}
 /** An empty object. */
-export const EMPTY_DATA = {};
+export const EMPTY_DATA = { __proto__: null };
 /** Function that returns an an empty object. */
 export const getEmptyData = () => EMPTY_DATA;

package/util/date.d.ts

@@ -1,7 +1,7 @@
 /** Things that converted to dates. */
-export declare type PossibleDate = Date | number | string;
+export type PossibleDate = Date | number | string;
 /** Things that converted to dates or `null` */
-export declare type PossibleOptionalDate = Date | number | string | null;
+export type PossibleOptionalDate = Date | number | string | null;
 /** Is a value a date? */
 export declare const isDate: (v: Date | unknown) => v is Date;
 /** Assert that a value is a `Date` instance. */
@@ -35,7 +35,7 @@ export declare const getYMD: (possible?: PossibleDate) => string;
 /** List of day-of-week strings. */
 export declare const days: readonly ["sunday", "monday", "tuesday", "wednesday", "thursday", "friday", "saturday"];
 /** Type listing day-of-week strings. */
-export declare type Day = typeof days[number];
+export type Day = (typeof days)[number];
 /** Convert a `Date` instance to a day-of-week string like "monday" */
 export declare const getDay: (target?: PossibleDate) => Day;
 /** Get a Date representing exactly midnight of the specified date. */

package/util/debug.d.ts

@@ -1,3 +1,4 @@
+/** Note: try to avoid non-type imports in this file, it can easily cause circular imports. */
 import type { ImmutableArray } from "./array.js";
 import type { ImmutableMap } from "./map.js";
 import type { ImmutableSet } from "./set.js";

package/util/debug.js

@@ -38,25 +38,25 @@ const _escapeChar = (char) => ESCAPE_LIST[char] || `\\x${char.charCodeAt(0).toSt
 /** Debug an array. */
 export function debugArray(value) {
     const prototype = Object.getPrototypeOf(value);
-    const name = prototype === Array ? "" : prototype.name || "";
+    const name = prototype === Array.prototype ? "" : prototype.constructor.name || "";
     return `${name ? `${name} ` : ""}${value.length ? `[\n\t${value.map(debug).join(",\n\t")}\n]` : "[]"}`;
 }
 /** Debug a set. */
 export function debugSet(value) {
     const prototype = Object.getPrototypeOf(value);
-    const name = prototype === Array ? "" : prototype.name || "Set";
+    const name = prototype === Set.prototype ? "" : prototype.constructor.name || "Set";
     return `${name}(value.size) ${value.size ? `{\n\t${Array.from(value).map(debug).join(",\n\t")}\n}` : "{}"}`;
 }
 /** Debug a map. */
 export function debugMap(value) {
     const prototype = Object.getPrototypeOf(value);
-    const name = prototype === Array ? "" : prototype.name || "Map";
+    const name = prototype === Map.prototype ? "" : prototype.constructor.name || "Map";
     return `${name}(value.size) ${value.size ? `{\n\t${Array.from(value).map(_debugProp).join(",\n\t")}\n}` : "{}"}`;
 }
 /** Debug an object. */
 export function debugObject(value) {
-    const prototype = Object.getPrototypeOf(value) || Object;
-    const name = prototype === Object ? "" : prototype.name || "";
+    const prototype = Object.getPrototypeOf(value);
+    const name = prototype === Object.prototype ? "" : prototype.constructor.name || "";
     const props = Object.entries(value).map(_debugProp);
     return `${name ? `${name} ` : ""}${props.length ? `{\n\t${props.join(",\n\t")}\n}` : "{}"}`;
 }

package/util/dictionary.d.ts

@@ -1,17 +1,17 @@
 /** Readonly dictionary object. */
-export declare type ImmutableDictionary<T = unknown> = {
+export type ImmutableDictionary<T = unknown> = {
     readonly [K in string]: T;
 };
 /** Writable dictionary object. */
-export declare type MutableDictionary<T = unknown> = {
+export type MutableDictionary<T = unknown> = {
     [K in string]: T;
 };
 /** Get the type for an item of a dictionary object in entry format. */
-export declare type DictionaryItem<T> = readonly [string, T];
+export type DictionaryItem<T> = readonly [string, T];
 /** Get the type of the _values_ of the items of a dictionary object. */
-export declare type DictionaryValue<T extends ImmutableDictionary> = T[string];
+export type DictionaryValue<T extends ImmutableDictionary> = T[string];
 /** Something that can be converted to a dictionary object. */
-export declare type PossibleDictionary<T> = ImmutableDictionary<T> | Iterable<DictionaryItem<T>>;
+export type PossibleDictionary<T> = ImmutableDictionary<T> | Iterable<DictionaryItem<T>>;
 /** Is an unknown value a dictionary object? */
 export declare const isDictionary: <T extends ImmutableDictionary<T>>(value: unknown) => value is T;
 /** Assert that an unknown value is a dictionary object */

package/util/duration.d.ts

@@ -0,0 +1,17 @@
+import { PossibleDate } from "./date.js";
+/** 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, 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, 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` */
+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;
+/** 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;

package/util/duration.js

@@ -0,0 +1,52 @@
+import { MONTH, WEEK, DAY, HOUR, SECOND } from "./constants.js";
+import { getDuration } from "./date.js";
+import { getMapItem } from "./map.js";
+import { TIME_UNITS } from "./units.js";
+/** Get the ID for a time unit based on the amount in milliseconds. */
+function _getTimeUnitKey(ms) {
+    const abs = Math.abs(ms);
+    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, precision) {
+    const unit = getMapItem(TIME_UNITS, _getTimeUnitKey(ms));
+    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, precision) {
+    const unit = getMapItem(TIME_UNITS, _getTimeUnitKey(ms));
+    return unit.format(unit.from(ms), precision);
+}
+/** format when a data happens/happened. */
+function _formatWhen(formatter, target, current) {
+    const ms = getDuration(target, current);
+    const abs = Math.abs(ms);
+    const duration = formatter(ms);
+    return abs < 10 * SECOND ? "just now" : ms > 0 ? `in ${duration}` : `${duration} ago`;
+}
+/** 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));
+/** 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));

package/util/entry.d.ts

@@ -6,11 +6,11 @@ import { ImmutableSet } from "./set.js";
  * - Consistency with `UnknownObject`
  * - Always readonly.
  */
-export declare type Entry<K = unknown, T = unknown> = readonly [K, T];
+export type Entry<K = unknown, T = unknown> = readonly [K, T];
 /** Extract the type for the value of an entry. */
-export declare type EntryKey<X> = X extends Entry<infer Y, unknown> ? Y : never;
+export type EntryKey<X> = X extends Entry<infer Y, unknown> ? Y : never;
 /** Extract the type for the value of an entry. */
-export declare type EntryValue<X> = X extends Entry<unknown, infer Y> ? Y : never;
+export type EntryValue<X> = X extends Entry<unknown, infer Y> ? Y : never;
 /** Extract the key from an object entry. */
 export declare const getEntryKey: <K, T>([k]: Entry<K, T>) => K;
 /** Extract the value from an object entry. */

package/util/equal.js

@@ -1,5 +1,5 @@
 import { isArray } from "./array.js";
-import { isObject } from "./object.js";
+import { getPrototype, isObject } from "./object.js";
 import { isMap } from "./map.js";
 // Internal shared by shallow/deep equal.
 function _equal(left, right, recursor) {
@@ -35,7 +35,10 @@ export function isMapEqual(left, right, recursor = isExactlyEqual) {
         return false; // Different lengths aren't equal.
     const rightIterator = right.entries();
     for (const [leftKey, leftValue] of left) {
-        const [rightKey, rightValue] = rightIterator.next().value;
+        const { done, value } = rightIterator.next();
+        if (done)
+            return false;
+        const [rightKey, rightValue] = value;
         if (leftKey !== rightKey || !recursor(leftValue, rightValue))
             return false;
     }
@@ -70,7 +73,7 @@ export function isObjectEqual(left, right, recursor = isExactlyEqual) {
     var _a, _b;
     if (left === right)
         return true; // Referentially equal.
-    if (((_a = Object.getPrototypeOf(left)) === null || _a === void 0 ? void 0 : _a.constructor) !== ((_b = Object.getPrototypeOf(right)) === null || _b === void 0 ? void 0 : _b.constructor))
+    if (((_a = getPrototype(left)) === null || _a === void 0 ? void 0 : _a.constructor) !== ((_b = getPrototype(right)) === null || _b === void 0 ? void 0 : _b.constructor))
         return false; // Constructors are not equal.
     const leftEntries = Object.entries(left);
     const rightKeys = Object.keys(right);

package/util/function.d.ts

@@ -1,21 +1,21 @@
 /** Unknown function. */
-export declare type UnknownFunction = (...args: unknown[]) => unknown;
+export type UnknownFunction = (...args: unknown[]) => unknown;
 /** Any function (designed for use with `extends AnyFunction` guards). */
-export declare type AnyFunction = (...args: any) => any;
+export type AnyFunction = (...args: any) => any;
 /** Is a value a function? */
 export declare const isFunction: <T extends AnyFunction>(v: unknown) => v is T;
 /** Assert that a value is a function. */
 export declare function assertFunction<T extends AnyFunction>(v: T | unknown): asserts v is T;
 /** Readonly unknown array that is being used as a set of arguments to a function. */
-export declare type Arguments = readonly unknown[];
+export type Arguments = readonly unknown[];
 /** Function that just passes through the first argument. */
 export declare const PASSTHROUGH: <T>(value: T) => T;
 /** Function that does nothing with its arguments and always returns void. */
 export declare const BLACKHOLE: (...args: Arguments) => void | undefined;
 /** Function that receives a dispatched value. */
-export declare type Dispatch<T extends Arguments = []> = (...value: T) => void;
+export type Dispatch<T extends Arguments = []> = (...value: T) => void;
 /** Function that receives a dispatched value. */
-export declare type AsyncDispatch<T extends Arguments = []> = (...value: T) => void | PromiseLike<void>;
+export type AsyncDispatch<T extends Arguments = []> = (...value: T) => void | PromiseLike<void>;
 /** Safely dispatch a value to a dispatcher function. */
 export declare function dispatch<A extends Arguments>(func: AsyncDispatch<A>, ...value: A): void;
 /** Return a function that dispatches a value to a dispatcher function. */
@@ -25,8 +25,8 @@ export declare function dispatchMethod<T extends Arguments, M extends string | s
     [K in M]: AsyncDispatch<T>;
 }, key: M, ...value: T): void;
 /** Function that starts something. */
-export declare type Start<A extends Arguments = []> = (...args: A) => Stop | void;
+export type Start<A extends Arguments = []> = (...args: A) => Stop | void;
 /** Function that stops something. */
-export declare type Stop = Dispatch;
+export type Stop = Dispatch;
 /** Function that handles an error. */
-export declare type Handler = (reason: Error | unknown) => void;
+export type Handler = (reason: Error | unknown) => void;

package/util/hydrate.d.ts

@@ -5,7 +5,7 @@ import { Transformable } from "./transform.js";
  * A set of hydrations describes a set of string keys and the class constructor to be dehydrated and rehydrated.
  * - We can't use `class.name` because we don't know that the name of the class will survive minification.
  */
-export declare type Hydrations = ImmutableDictionary<Class>;
+export type Hydrations = ImmutableDictionary<Class>;
 /**
  * Deeply dehydrate a class instance based on a set of `Hydrations`
  * - Dehydration allows you to pass class instances from a server back to a client.
@@ -26,9 +26,9 @@ export declare function dehydrate(value: unknown, hydrations: Hydrations): unkno
  */
 export declare function hydrate(value: unknown, hydrations: Hydrations): unknown;
 /** A dehydrated object with a `$type` key. */
-export declare type DehydratedObject = {
+export type DehydratedObject = {
     readonly $type: string;
-    readonly $value: any;
+    readonly $value: unknown;
 };
 /** Hydrates a value with a set of hydrations. */
 export declare class Hydrator implements Transformable<unknown, unknown> {

package/util/hydrate.js

@@ -2,7 +2,7 @@ import { AssertionError } from "../error/AssertionError.js";
 import { isArray } from "./array.js";
 import { isDate } from "./date.js";
 import { isMap } from "./map.js";
-import { isObject, isPlainObject } from "./object.js";
+import { getPrototype, isObject, isPlainObject } from "./object.js";
 import { isSet } from "./set.js";
 import { isString } from "./string.js";
 import { mapArray, mapObject, mapEntries, mapItems } from "./transform.js";
@@ -72,7 +72,7 @@ export class Dehydrator {
         if (isDate(value))
             return { $type: "Date", $value: value.getTime() };
         if (isObject(value)) {
-            const proto = Object.getPrototypeOf(value);
+            const proto = getPrototype(value);
             if (proto === Object.prototype || proto === null)
                 return mapObject(value, this);
             for (const [$type, hydration] of Object.entries(this._hydrations))

package/util/index.d.ts

@@ -12,6 +12,7 @@ export * from "./date.js";
 export * from "./debug.js";
 export * from "./dictionary.js";
 export * from "./diff.js";
+export * from "./duration.js";
 export * from "./entry.js";
 export * from "./equal.js";
 export * from "./error.js";

package/util/index.js

@@ -12,6 +12,7 @@ export * from "./date.js";
 export * from "./debug.js";
 export * from "./dictionary.js";
 export * from "./diff.js";
+export * from "./duration.js";
 export * from "./entry.js";
 export * from "./equal.js";
 export * from "./error.js";

package/util/iterate.d.ts

@@ -7,7 +7,7 @@ import { Arguments } from "./function.js";
 import { Matcher } from "./match.js";
 export declare const isIterable: <T extends Iterable<unknown>>(value: unknown) => value is T;
 /** An iterable containing items or nested iterables of items. */
-export declare type DeepIterable<T> = T | Iterable<DeepIterable<T>>;
+export type DeepIterable<T> = T | Iterable<DeepIterable<T>>;
 /** Flatten one or more iterables. */
 export declare function flattenItems<T>(items: DeepIterable<T>): Iterable<T>;
 /**

package/util/jsx.d.ts

@@ -1,10 +1,10 @@
 /** Set of valid props for a JSX element. */
-export declare type JSXProps = {
+export type JSXProps = {
     [key: string]: unknown;
     children?: JSXNode;
 };
 /** JSX element (similar to `React.ReactElement`)  */
-export declare type JSXElement<P extends JSXProps = JSXProps> = {
+export type JSXElement<P extends JSXProps = JSXProps> = {
     type: string | ((props: P) => JSXElement | null);
     props: P;
     key: string | number | null;
@@ -12,7 +12,7 @@ export declare type JSXElement<P extends JSXProps = JSXProps> = {
     $$typeof?: symbol;
 };
 /** JSX node (similar to `React.ReactNode`) */
-export declare type JSXNode = undefined | null | string | JSXElement | JSXNode[];
+export type JSXNode = undefined | null | string | JSXElement | JSXNode[];
 /** Is an unknown value a JSX element? */
 export declare const isJSXElement: <T extends JSXElement<JSXProps>>(v: unknown) => v is T;
 /** Is an unknown value a JSX node? */

package/util/lazy.d.ts

@@ -3,7 +3,7 @@ import { Arguments } from "./function.js";
  * Lazy value: a plain value, or an initialiser function that returns that value.
  * @param ...args Any arguments the lazy value needs if it's a function.
  */
-export declare type Lazy<T, A extends Arguments = []> = ((...args: A) => T) | T;
+export type Lazy<T, A extends Arguments = []> = ((...args: A) => T) | T;
 /**
  * Initialise a lazy value.
  *

package/util/map.d.ts

@@ -1,18 +1,22 @@
 import { Entry } from "./entry.js";
 /** `Map` that cannot be changed. */
-export declare type ImmutableMap<K = unknown, T = unknown> = ReadonlyMap<K, T>;
+export type ImmutableMap<K = unknown, T = unknown> = ReadonlyMap<K, T>;
+/** Class for a `Map` that cannot be changed (so you can extend `Map` while implementing `ImmutableMap`). */
+export declare const ImmutableMap: {
+    new <K, T>(...params: ConstructorParameters<typeof Map<K, T>>): ImmutableMap<K, T>;
+};
 /** `Map` that can be changed. */
-export declare type MutableMap<K = unknown, T = unknown> = Map<K, T>;
+export type MutableMap<K = unknown, T = unknown> = Map<K, T>;
 /** Extract the type for the value of a map. */
-export declare type MapKey<X> = X extends ReadonlyMap<infer Y, unknown> ? Y : never;
+export type MapKey<X> = X extends ReadonlyMap<infer Y, unknown> ? Y : never;
 /** Extract the type for the value of a map. */
-export declare type MapValue<X> = X extends ReadonlyMap<unknown, infer Y> ? Y : never;
+export type MapValue<X> = X extends ReadonlyMap<unknown, infer Y> ? Y : never;
 /** Get the type for an item of a map in entry format. */
-export declare type MapItem<T extends ImmutableMap> = readonly [MapKey<T>, MapValue<T>];
+export type MapItem<T extends ImmutableMap> = readonly [MapKey<T>, MapValue<T>];
 /** Things that can be converted to maps. */
-export declare type PossibleMap<K, T> = ImmutableMap<K, T> | Iterable<Entry<K, T>>;
+export type PossibleMap<K, T> = ImmutableMap<K, T> | Iterable<Entry<K, T>>;
 /** Things that can be converted to maps with string keys. */
-export declare type PossibleStringMap<K extends string, T> = PossibleMap<K, T> | {
+export type PossibleStringMap<K extends string, T> = PossibleMap<K, T> | {
     readonly [KK in K]: T;
 };
 /** Is an unknown value a map? */
@@ -24,9 +28,6 @@ export declare function assertMap<T extends ImmutableMap>(v: T | unknown): asser
 /** Convert an iterable to a `Map` (if it's already a `Map` it passes through unchanged). */
 export declare function getMap<K extends string, T>(input: PossibleStringMap<K, T>): ImmutableMap<K, T>;
 export declare function getMap<K, T>(input: PossibleMap<K, T>): ImmutableMap<K, T>;
-/** Convert an iterable to a `Map` (if it's already a `Map` it passes through unchanged). */
-export declare function getRequiredMap<K extends string, T>(input: PossibleStringMap<K, T>): ImmutableRequiredMap<K, T>;
-export declare function getRequiredMap<K, T>(input: PossibleMap<K, T>): ImmutableRequiredMap<K, T>;
 /** Apply a limit to a map. */
 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. */
@@ -35,12 +36,7 @@ export declare function setMapItem<K, T>(map: MutableMap<K, T>, key: K, value: T
 export declare function setMapItems<K, T>(map: MutableMap<K, T>, items: Iterable<MapItem<ImmutableMap<K, T>>>): void;
 /** Remove multiple items from a set (by reference). */
 export declare function removeMapItems<K, T>(map: MutableMap<K, T>, ...keys: K[]): void;
-/** Mutable map that changes `get()` to throw an error if the requested value doesn't exist. */
-export declare class MutableRequiredMap<K, T> extends Map<K, T> {
-    get(key: K): T;
-}
-/** Immutable map that changes `get()` to throw an error if the requested value doesn't exist. */
-export declare const ImmutableRequiredMap: {
-    new <K, T>(...params: ConstructorParameters<typeof MutableRequiredMap<K, T>>): ImmutableRequiredMap<K, T>;
-};
-export declare type ImmutableRequiredMap<K, T> = Omit<MutableRequiredMap<K, T>, "set" | "delete">;
+/** Get an item in a map or throw an error if it doesn't exist. */
+export declare function getMapItem<K, T>(map: ImmutableMap<K, T>, key: K): T;
+/** Get an item in a map or `null` if it doesn't exist. */
+export declare function getOptionalMapItem<K, T>(map: ImmutableMap<K, T>, key: K): T | null;

package/util/map.js

@@ -1,7 +1,8 @@
 import { AssertionError } from "../error/AssertionError.js";
 import { RequiredError } from "../error/RequiredError.js";
 import { isIterable, limitItems } from "./iterate.js";
-import { getString } from "./string.js";
+/** Class for a `Map` that cannot be changed (so you can extend `Map` while implementing `ImmutableMap`). */
+export const ImmutableMap = Map;
 /** Is an unknown value a map? */
 export const isMap = (v) => v instanceof Map;
 /** Is an unknown value a key for an item in a map? */
@@ -14,9 +15,6 @@ export function assertMap(v) {
 export function getMap(input) {
     return isMap(input) ? input : new Map(isIterable(input) ? input : Object.entries(input));
 }
-export function getRequiredMap(input) {
-    return input instanceof ImmutableRequiredMap ? input : new ImmutableRequiredMap(isIterable(input) ? input : Object.entries(input));
-}
 /** Apply a limit to a map. */
 export function limitMap(map, limit) {
     return limit > map.size ? map : new Map(limitItems(map, limit));
@@ -36,13 +34,13 @@ export function removeMapItems(map, ...keys) {
     for (const key of keys)
         map.delete(key);
 }
-/** Mutable map that changes `get()` to throw an error if the requested value doesn't exist. */
-export class MutableRequiredMap extends Map {
-    get(key) {
-        if (!this.has(key))
-            throw new RequiredError(`Item "${getString(key)}" is required`);
-        return super.get(key);
-    }
+/** Get an item in a map or throw an error if it doesn't exist. */
+export function getMapItem(map, key) {
+    if (!map.has(key))
+        throw new RequiredError(`Map item is required`);
+    return map.get(key);
+}
+/** Get an item in a map or `null` if it doesn't exist. */
+export function getOptionalMapItem(map, key) {
+    return map.has(key) ? map.get(key) : null;
 }
-/** Immutable map that changes `get()` to throw an error if the requested value doesn't exist. */
-export const ImmutableRequiredMap = MutableRequiredMap;

package/util/match.d.ts

@@ -4,9 +4,9 @@ export interface Matchable<A extends Arguments = unknown[]> {
     match(...args: A): boolean;
 }
 /** Function that can match an item against a target. */
-export declare type Match<A extends Arguments = unknown[]> = (...args: A) => boolean;
+export type Match<A extends Arguments = unknown[]> = (...args: A) => boolean;
 /** Match is either a `Matcherable` object, or matcher function. */
-export declare type Matcher<A extends Arguments = unknown[]> = Matchable<A> | Match<A>;
+export type Matcher<A extends Arguments = unknown[]> = Matchable<A> | Match<A>;
 /** Match two values using a `Matcher`. */
 export declare function match<A extends Arguments>(matcher: Matcher<A>, ...args: A): boolean;
 export declare const isEqual: Match<[item: unknown, target: unknown]>;

package/util/merge.d.ts

@@ -1,6 +1,6 @@
 import { ImmutableArray } from "./array.js";
 import { ImmutableObject } from "./object.js";
-declare type MergeRecursor = (left: unknown, right: unknown) => unknown;
+type MergeRecursor = (left: unknown, right: unknown) => unknown;
 /**
  * Exact merge two unknown values.
  * - Always returns `right`.

package/util/null.d.ts

@@ -9,7 +9,7 @@ export declare function assertNotNull<T>(v: T | null): asserts v is T;
 /** Get the not-nullish version of value. */
 export declare function getNotNull<T>(v: T | null): T;
 /** Nullish is `null` or `undefined` */
-export declare type Nullish<T> = T | null | undefined;
+export type Nullish<T> = T | null | undefined;
 /** Is a value nullish? */
 export declare const isNullish: <T>(v: Nullish<T>) => v is null | undefined;
 /** Is a value not nullish? */

package/util/number.d.ts

@@ -70,7 +70,7 @@ export declare function boundNumber(num: number, min: number, max: number): numb
 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. */
+/** Format a number with a short suffix, e.g. `1,000 kg` */
 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, precision?: number | null): string;
@@ -98,7 +98,7 @@ export declare function formatFullQuantity(num: number, singular: string, plural
  * @returns The number formatted as a crammed string.
  */
 export declare function cramNumber(num: number): string;
-/** Cram a number with a short suffix. */
+/** Cram a number with a short suffix, e.g. `1.02M kg` */
 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;
@@ -109,6 +109,8 @@ export declare function cramFullQuantity(num: number, singular: string, plural:
  * @param denumerator The number representing the whole amount.
  */
 export declare const getPercent: (numerator: number, denumerator: number) => number;
+/** Format a percentage (combines `getPercent()` and `formatQuantity()` for convenience). */
+export declare const formatPercent: (numerator: number, denumerator: number, precision?: number) => string;
 /** Sum an iterable set of numbers and return the total. */
 export declare function sumNumbers(nums: Iterable<number>): number;
 /** Find the number that's closest to a target in an iterable set of numbers. */

package/util/number.js

@@ -1,5 +1,5 @@
 import { AssertionError } from "../error/AssertionError.js";
-import { BILLION, MILLION, NNBSP, TRILLION } from "./constants.js";
+import { BILLION, MILLION, NNBSP, TEN_THOUSAND, THOUSAND, TRILLION } from "./constants.js";
 /** Is a value a number? */
 export const isNumber = (v) => typeof v === "number";
 /** Assert that a value is a number. */
@@ -114,7 +114,7 @@ export function formatNumber(num, precision = null) {
         return Number.isNaN(num) ? "None" : "Infinity";
     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. */
+/** Format a number with a short suffix, e.g. `1,000 kg` */
 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, precision) {
@@ -152,16 +152,16 @@ export function cramNumber(num) {
         return `${_significance(num / BILLION)}B`;
     if (abs >= MILLION)
         return `${_significance(num / MILLION)}M`;
-    if (abs >= 10000)
-        return `${_significance(num / 1000)}K`;
+    if (abs >= TEN_THOUSAND)
+        return `${_significance(num / THOUSAND)}K`;
     return truncateNumber(num, 2).toString();
 }
 function _significance(num) {
     const digits = num >= 100 ? 0 : num >= 10 ? 1 : 2;
     return truncateNumber(num, digits).toFixed(digits);
 }
-/** Cram a number with a short suffix. */
-export const cramQuantity = (num, suffix) => `${cramNumber(num)}${suffix}`;
+/** Cram a number with a short suffix, e.g. `1.02M kg` */
+export const cramQuantity = (num, suffix) => `${cramNumber(num)}${NNBSP}${suffix}`;
 /** Cram a number with a longer full-word suffix. */
 export function cramFullQuantity(num, singular, plural) {
     const qty = cramNumber(num);
@@ -174,6 +174,8 @@ export function cramFullQuantity(num, singular, plural) {
  * @param denumerator The number representing the whole amount.
  */
 export const getPercent = (numerator, denumerator) => Math.max(0, Math.min(100, (100 / denumerator) * numerator));
+/** Format a percentage (combines `getPercent()` and `formatQuantity()` for convenience). */
+export const formatPercent = (numerator, denumerator, precision) => formatQuantity(getPercent(numerator, denumerator), "%", precision);
 /** Sum an iterable set of numbers and return the total. */
 export function sumNumbers(nums) {
     let sum = 0;