shelving 1.70.0 → 1.71.0

package/error/ValidationError.js

@@ -1,7 +1,8 @@
+import { debug } from "../util/debug.js";
 /** Thrown if a value isn't valid. */
 export class ValidationError extends Error {
     constructor(message, feedback) {
-        super(`${message}:\n${feedback.toString()}`);
+        super(`${message}:\n${feedback.message} (received ${debug(feedback.details)})`);
         this.feedback = feedback;
     }
 }

package/feedback/Feedback.d.ts

@@ -12,30 +12,16 @@ import type { ImmutableObject } from "../util/object.js";
  */
 export declare class Feedback {
     /** String feedback message that is safe to show to a user. */
-    readonly feedback: string;
+    readonly message: string;
     /** Nested details providing deeper feedback. */
     readonly details: ImmutableObject;
     constructor(feedback: string, details?: ImmutableObject);
     /**
      * Map details to a set of string messages.
-     * - If a detail is another `Feedback` instance, return its feedback string.
+     * - If a detail is another `Feedback` instance, return its `.message` string.
      * - If a detail is anything else, convert it to string using `toString()`
      */
     get messages(): ImmutableObject<string>;
-    /**
-     * Convert to string (equivalent to `message.details`).
-     * Returns a string including the main message string and a deeply nested list of child message strings.
-     *
-     * > Invalid format
-     * > - name: Invalid format
-     * >   - first: Must be string
-     * >     - value: 123
-     * >   - last: Must be string
-     * >     - value: true
-     * > - age: Must be number
-     * >   - value: "abc"
-     */
-    toString(): string;
 }
 /** Is an unknown value a `Feedback` instance? */
 export declare const isFeedback: <T extends Feedback>(v: unknown) => v is Feedback;

package/feedback/Feedback.js

@@ -1,5 +1,5 @@
-import { debug } from "../util/debug.js";
-import { getTitle } from "../util/string.js";
+import { getString } from "../util/string.js";
+import { mapObject } from "../util/transform.js";
 /**
  * The `Feedback` class represents a feedback message that should be shown to the user.
  * - Basic `Feedback` is neither good nor bad, `SuccessFeedback` indicates good news, and `ErrorFeedback` indicates bad news.
@@ -13,43 +13,18 @@ import { getTitle } from "../util/string.js";
  */
 export class Feedback {
     constructor(feedback, details = {}) {
-        this.feedback = feedback;
+        this.message = feedback;
         this.details = details;
     }
     /**
      * Map details to a set of string messages.
-     * - If a detail is another `Feedback` instance, return its feedback string.
+     * - If a detail is another `Feedback` instance, return its `.message` string.
      * - If a detail is anything else, convert it to string using `toString()`
      */
     get messages() {
-        const messages = {};
-        for (const [k, v] of Object.entries(this.details)) {
-            if (isFeedback(v))
-                messages[k] = v.feedback;
-            else
-                messages[k] = getTitle(v);
-        }
-        return messages;
-    }
-    /**
-     * Convert to string (equivalent to `message.details`).
-     * Returns a string including the main message string and a deeply nested list of child message strings.
-     *
-     * > Invalid format
-     * > - name: Invalid format
-     * >   - first: Must be string
-     * >     - value: 123
-     * >   - last: Must be string
-     * >     - value: true
-     * > - age: Must be number
-     * >   - value: "abc"
-     */
-    toString() {
-        let output = this.feedback;
-        for (const [k, v] of Object.entries(this.details))
-            output += `\n- ${k}: ${isFeedback(v) ? v.toString().replace(/\n/g, "\n  ") : debug(v)}`;
-        return output;
+        return mapObject(this.details, _getMessage);
     }
 }
+const _getMessage = (v) => (isFeedback(v) ? v.message : getString(v));
 /** Is an unknown value a `Feedback` instance? */
 export const isFeedback = (v) => v instanceof Feedback;

package/package.json

@@ -11,7 +11,7 @@
 		"state-management",
 		"query-builder"
 	],
-	"version": "1.70.0",
+	"version": "1.71.0",
 	"repository": "https://github.com/dhoulb/shelving",
 	"author": "Dave Houlbrooke <dave@shax.com>",
 	"license": "0BSD",
@@ -62,7 +62,7 @@
 	},
 	"devDependencies": {
 		"@google-cloud/firestore": "^5.0.2",
-		"@types/jest": "^27.5.1",
+		"@types/jest": "^28.1.6",
 		"@types/react": "^18.0.9",
 		"@types/react-dom": "^18.0.4",
 		"@typescript-eslint/eslint-plugin": "^5.23.0",

package/schema/AllowSchema.js

@@ -2,7 +2,7 @@ import { InvalidFeedback } from "../feedback/InvalidFeedback.js";
 import { getString } from "../util/string.js";
 import { isArray, isItem } from "../util/array.js";
 import { getOptionalNumber } from "../util/number.js";
-import { isKey } from "../util/object.js";
+import { isEntry } from "../util/object.js";
 import { Schema } from "./Schema.js";
 /** Validate a value against a specific set of allowed values. */
 export function validateAllowed(value, allowed) {
@@ -11,7 +11,7 @@ export function validateAllowed(value, allowed) {
             return value;
     }
     else {
-        if (isKey(allowed, value))
+        if (isEntry(allowed, value))
             return value;
     }
     throw new InvalidFeedback("Unknown value", { value });

package/util/array.d.ts

@@ -22,7 +22,6 @@ export declare const isItem: <T>(arr: ImmutableArray<T>, item: unknown) => item
 /** Things that can be converted to arrays. */
 export declare type PossibleArray<T> = ImmutableArray<T> | Iterable<T>;
 /** Convert an iterable to an array (if its not already an array). */
-export declare function getArray<T>(iterable: ImmutableArray<T> | Iterable<T>): ImmutableArray<T>;
 export declare function getArray<T>(items: PossibleArray<T>): ImmutableArray<T>;
 /**
  * Add an item to an array (immutably).

package/util/array.js

@@ -8,6 +8,7 @@ export function assertArray(arr) {
 }
 /** Is an unknown value an item in a specified array? */
 export const isItem = (arr, item) => arr.includes(item);
+/** Convert an iterable to an array (if its not already an array). */
 export function getArray(items) {
     return isArray(items) ? items : Array.from(items);
 }

package/util/clone.js

@@ -1,6 +1,6 @@
 import { isArray } from "./array.js";
 import { isObject } from "./object.js";
-import { mapArray, mapObject } from "./transform.js";
+import { mapArray, mapData } from "./transform.js";
 /** Does an object implement `Cloneable` */
 export const isCloneable = (v) => isObject(v) && typeof v.cloneable === "function";
 /** Shallow clone a value. */
@@ -27,7 +27,7 @@ export function cloneArray(input, recursor = shallowClone) {
 export function cloneObject(input, recursor = shallowClone) {
     if (isCloneable(input))
         return input.clone();
-    const output = mapObject(input, recursor);
+    const output = mapData(input, recursor);
     Object.setPrototypeOf(input, Object.getPrototypeOf(input));
     return output;
 }

package/util/data.d.ts

@@ -29,7 +29,7 @@ export declare type Entities<T extends Data = Data> = ImmutableArray<Entity<T>>;
 export declare type OptionalEntity<T extends Data = Data> = Entity<T> | null;
 /** Is an unknown value a data object? */
 export declare const isData: <T extends Data>(value: unknown) => value is T;
-/** Turn a data object into an array of entries (if it isn't one already). */
+/** Turn a data object into an array of props. */
 export declare function getProps<T extends Data>(data: T): ImmutableArray<Prop<T>>;
 export declare function getProps<T extends Data>(data: Partial<T>): ImmutableArray<Prop<T>>;
 /** Get the data of a result (returns data or throws `RequiredError` if value is `null` or `undefined`). */
@@ -142,3 +142,10 @@ export declare type PickProps<T, TT> = Pick<T, {
 export declare type OmitProps<T, TT> = Omit<T, {
     [K in keyof T]: T[K] extends TT ? K : never;
 }[keyof T]>;
+/**
+ * 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 declare function formatData(data: Data): string;

package/util/data.js

@@ -69,3 +69,21 @@ export function setProps(data, props) {
     for (const [k, v] of getProps(props))
         data[k] = v;
 }
+/**
+ * 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";
+}

package/util/date.d.ts

@@ -37,7 +37,7 @@ export declare const days: readonly ["sunday", "monday", "tuesday", "wednesday",
 /** Type listing day-of-week strings. */
 export declare type Day = typeof days[number];
 /** Convert a `Date` instance to a day-of-week string like "monday" */
-export declare const getDay: (target?: PossibleDate | undefined) => Day;
+export declare const getDay: (target?: PossibleDate) => Day;
 /** Get a Date representing exactly midnight of the specified date. */
 export declare function getMidnight(target?: PossibleDate): Date;
 /** Get a Date representing midnight on Monday of the specified week. */
@@ -52,24 +52,24 @@ export declare function addHours(change: number, target?: PossibleDate): Date;
  * @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 const getDuration: (target?: PossibleDate | undefined, current?: PossibleDate | undefined) => number;
+export declare const getDuration: (target?: PossibleDate, current?: PossibleDate) => number;
 /** Count the number of seconds until a date. */
-export declare const getSecondsUntil: (target: PossibleDate, current?: PossibleDate | undefined) => number;
+export declare const getSecondsUntil: (target: PossibleDate, current?: PossibleDate) => number;
 /** Count the number of days ago a date was. */
-export declare const getSecondsAgo: (target: PossibleDate, current?: PossibleDate | undefined) => number;
+export declare const getSecondsAgo: (target: PossibleDate, current?: PossibleDate) => number;
 /** Count the number of days until a date. */
-export declare const getDaysUntil: (target: PossibleDate, current?: PossibleDate | undefined) => number;
+export declare const getDaysUntil: (target: PossibleDate, current?: PossibleDate) => number;
 /** Count the number of days ago a date was. */
-export declare const getDaysAgo: (target: PossibleDate, current?: PossibleDate | undefined) => number;
+export declare const getDaysAgo: (target: PossibleDate, current?: PossibleDate) => number;
 /** Count the number of weeks until a date. */
-export declare const getWeeksUntil: (target: PossibleDate, current?: PossibleDate | undefined) => number;
+export declare const getWeeksUntil: (target: PossibleDate, current?: PossibleDate) => number;
 /** Count the number of weeks ago a date was. */
-export declare const getWeeksAgo: (target: PossibleDate, current?: PossibleDate | undefined) => number;
+export declare const getWeeksAgo: (target: PossibleDate, current?: PossibleDate) => number;
 /** Format a date in the browser locale. */
 export declare const formatDate: (date: PossibleDate) => string;
 /** Is a date in the past? */
-export declare const isPast: (target: PossibleDate, current?: PossibleDate | undefined) => boolean;
+export declare const isPast: (target: PossibleDate, current?: PossibleDate) => boolean;
 /** Is a date in the future? */
-export declare const isFuture: (target: PossibleDate, current?: PossibleDate | undefined) => boolean;
+export declare const isFuture: (target: PossibleDate, current?: PossibleDate) => boolean;
 /** Is a date today (taking into account midnight). */
-export declare const isToday: (target: PossibleDate, current?: PossibleDate | undefined) => boolean;
+export declare const isToday: (target: PossibleDate, current?: PossibleDate) => boolean;

package/util/debug.d.ts

@@ -1,2 +1,16 @@
+import type { ImmutableArray } from "./array.js";
+import type { ImmutableMap } from "./map.js";
+import type { ImmutableSet } from "./set.js";
+import type { ImmutableObject } from "./object.js";
 /** Debug a random value as a string. */
-export declare const debug: (value: unknown) => string;
+export declare function debug(value: unknown): string;
+/** Debug a string. */
+export declare const debugString: (value: string) => string;
+/** Debug an array. */
+export declare function debugArray(value: ImmutableArray): string;
+/** Debug a set. */
+export declare function debugSet(value: ImmutableSet): string;
+/** Debug a map. */
+export declare function debugMap(value: ImmutableMap): string;
+/** Debug an object. */
+export declare function debugObject(value: ImmutableObject): string;

package/util/debug.js

@@ -1,24 +1,64 @@
+/* eslint-disable no-control-regex */
 /** Debug a random value as a string. */
-export const debug = (value) => typeof value === "function"
-    ? value.name
-        ? `${value.name}()`
-        : "anonymous function"
-    : value === null
-        ? "null"
-        : value === true
-            ? "true"
-            : value === false
-                ? "false"
-                : typeof value === "object"
-                    ? debugObject(value)
-                    : typeof value === "number"
-                        ? value.toString()
-                        : typeof value === "string"
-                            ? debugString(value)
-                            : typeof value;
-const debugString = (value) => (value.length > DEBUG_STRING_MAX ? `"${value.slice(0, DEBUG_STRING_MAX)}…"` : `"${value}"`);
-const DEBUG_STRING_MAX = 23;
-const debugObject = (value) => {
+export function debug(value) {
+    if (value === null)
+        return "null";
+    if (value === undefined)
+        return "undefined";
+    if (typeof value === "boolean")
+        return value ? "true" : "false";
+    if (typeof value === "string")
+        return debugString(value);
+    if (typeof value === "number")
+        return value.toString();
+    if (typeof value === "symbol")
+        return value.toString();
+    if (typeof value === "function")
+        return `function ${value.name || ""}()`;
+    if (typeof value === "object") {
+        if (value instanceof Date)
+            return value.toISOString();
+        if (value instanceof Error)
+            return value.toString();
+        if (value instanceof Array)
+            return debugArray(value);
+        if (value instanceof Map)
+            return debugMap(value);
+        if (value instanceof Set)
+            return debugSet(value);
+        return debugObject(value);
+    }
+    return typeof value;
+}
+/** Debug a string. */
+export const debugString = (value) => `"${value.replace(MATCH_ESCAPES, _debugChar)}"`;
+const MATCH_ESCAPES = /[\x00-\x08\x0B-\x1F\x7F-\x9F"\\]/g; // Match control characters, `"` double quote, `\` backslash.
+const ESCAPES = { '"': '\\"', "\\": "\\\\", "\r": "\\r", "\n": "\\n", "\t": "\\t", "\b": "\\b", "\f": "\\f", "\v": "\\v" };
+const _debugChar = (char) => ESCAPES[char] || `\\x${char.charCodeAt(0).toString(16).padStart(2, "00")}`;
+/** Debug an array. */
+export function debugArray(value) {
     const prototype = Object.getPrototypeOf(value);
-    return (prototype === null || prototype === void 0 ? void 0 : prototype.constructor) ? `instance of ${prototype.constructor.name || "anonymous class"}` : "plain object";
-};
+    const name = prototype === Array ? "" : prototype.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";
+    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";
+    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 props = Object.entries(value).map(_debugProp);
+    return `${name ? `${name} ` : ""}${props.length ? `{\n\t${props.join(",\n\t")}\n}` : "{}"}`;
+}
+/** Debug a prop. */
+const _debugProp = ([key, value]) => `${debug(key)}: ${debug(value)}`;

package/util/function.d.ts

@@ -1,3 +1,5 @@
+/** Unknown function. */
+export declare type UnknownFunction = (...args: unknown[]) => unknown;
 /** Any function (designed for use with `extends AnyFunction` guards). */
 export declare type AnyFunction = (...args: any) => any;
 /** Is a value a function? */

package/util/hydrate.js

@@ -2,7 +2,7 @@ import { AssertionError } from "../error/AssertionError.js";
 import { isArray } from "./array.js";
 import { isData } from "./data.js";
 import { isPlainObject } from "./object.js";
-import { mapArray, mapObject } from "./transform.js";
+import { mapArray, mapData } from "./transform.js";
 /**
  * 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.
@@ -38,11 +38,11 @@ export class Hydrator {
             return mapArray(value, this);
         if (isPlainObject(value)) {
             if (!isDehydrated(value))
-                return mapObject(value, this);
+                return mapData(value, this);
             const { _type, ...props } = value;
             const hydration = this._hydrations[_type];
             if (hydration)
-                return { __proto__: hydration.prototype, ...mapObject(props, this) };
+                return { __proto__: hydration.prototype, ...mapData(props, this) };
             throw new AssertionError(`Cannot hydrate "${_type}" object`, value);
         }
         return value;
@@ -57,11 +57,11 @@ export class Dehydrator {
         if (isArray(value))
             return mapArray(value, this);
         if (isPlainObject(value))
-            return mapObject(value, this);
+            return mapData(value, this);
         if (isData(value)) {
             for (const [_type, hydration] of Object.entries(this._hydrations))
                 if (value instanceof hydration)
-                    return { _type, ...mapObject(value, this) };
+                    return { _type, ...mapData(value, this) };
             throw new AssertionError(`Cannot dehydrate object`, value);
         }
         return value;

package/util/number.d.ts

@@ -66,9 +66,9 @@ export declare const truncateNumber: (num: number, precision?: number) => number
  *
  * @returns The number formatted as a string in the browser's current locale.
  */
-export declare const formatNumber: (num: number, maxPrecision?: number, minPrecision?: number) => string;
+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 | undefined, minPrecision?: number | undefined) => string;
+export declare const formatQuantity: (num: number, suffix: 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

@@ -93,7 +93,11 @@ export const truncateNumber = (num, precision = 0) => Math.trunc(num * 10 ** pre
  *
  * @returns The number formatted as a string in the browser's current locale.
  */
-export const formatNumber = (num, maxPrecision = 4, minPrecision = 0) => new Intl.NumberFormat(undefined, { maximumFractionDigits: maxPrecision, minimumFractionDigits: minPrecision }).format(num);
+export function formatNumber(num, maxPrecision = 4, minPrecision = 0) {
+    if (!Number.isFinite(num))
+        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 longer full-word suffix. */

package/util/object.d.ts

@@ -1,5 +1,6 @@
 import type { ImmutableArray } from "./array.js";
 import type { NotString } from "./string.js";
+import type { Entry } from "./entry.js";
 /** Readonly object with string keys. */
 export declare type ImmutableObject<T = unknown> = {
     readonly [key: string | number]: T;
@@ -23,11 +24,7 @@ export declare const isPlainObject: <T extends ImmutableObject<unknown>>(value:
 /** Assert that a value is a plain object */
 export declare function assertPlainObject<T extends ImmutableObject>(value: T | unknown): asserts value is T;
 /** Is an unknown string an own prop of an object. */
-export declare const isKey: <T extends ImmutableObject<unknown>>(obj: T, key: unknown) => key is keyof T;
-/** Assert that a value is an object with a specific property. */
-export declare function assertKey<K extends string | number | symbol, T extends {
-    [L in K]: unknown;
-}>(value: T | unknown, key: K): asserts value is T;
+export declare const isEntry: <T extends ImmutableObject<unknown>>(obj: T, key: unknown) => key is keyof T;
 /**
  * Add a key/value entry to a map-like object (immutably).
  *
@@ -66,6 +63,12 @@ export declare function withoutEntry<T>(input: ImmutableObject<T>, key: string,
  * - If every entry already exists and has the exact same input object will be returned.
  */
 export declare function withoutEntries<T>(input: ImmutableObject<T>, keys: Iterable<string> & NotString): ImmutableObject<T>;
+/**
+ * Get the entries of an object.
+ *
+ * @param obj The target object.
+ */
+export declare const getEntries: <T>(obj: ImmutableObject<T>) => ImmutableArray<Entry<T>>;
 /**
  * Set a key/value entry on a map-like object (by reference).
  *

package/util/object.js

@@ -1,5 +1,5 @@
 import { AssertionError } from "../error/AssertionError.js";
-import { setProp, setProps, withProp, withProps } from "./data.js";
+import { getProps, setProp, setProps, withProp, withProps } from "./data.js";
 /**
  * Is a value an unknown object?
  * - This is a TypeScript assertion object that asserts the value extends `ImmutableObject`
@@ -19,12 +19,7 @@ export function assertPlainObject(value) {
         throw new AssertionError(`Must be plain object`, value);
 }
 /** Is an unknown string an own prop of an object. */
-export const isKey = (obj, key) => (typeof key === "string" || typeof key === "number" || typeof key === "symbol") && Object.prototype.hasOwnProperty.call(obj, key);
-/** Assert that a value is an object with a specific property. */
-export function assertKey(value, key) {
-    if (!isObject(value) || !(key in value))
-        throw new AssertionError(`Must be object with prop "${key}"`, value);
-}
+export const isEntry = (obj, key) => (typeof key === "string" || typeof key === "number" || typeof key === "symbol") && Object.prototype.hasOwnProperty.call(obj, key);
 /**
  * Add a key/value entry to a map-like object (immutably).
  *
@@ -53,7 +48,7 @@ export const withEntries = withProps;
  * - If `key` doesn't already exist in `obj` then the exact same input object will be returned.
  */
 export function withoutEntry(input, key, value) {
-    if (isKey(input, key) && (value === undefined || input[key] === value)) {
+    if (isEntry(input, key) && (value === undefined || input[key] === value)) {
         const { [key]: unused, ...output } = input;
         return output;
     }
@@ -72,12 +67,18 @@ export function withoutEntries(input, keys) {
     let changed = false;
     const output = { ...input };
     for (const key of keys)
-        if (isKey(input, key)) {
+        if (isEntry(input, key)) {
             delete output[key];
             changed = true;
         }
     return changed ? output : input;
 }
+/**
+ * Get the entries of an object.
+ *
+ * @param obj The target object.
+ */
+export const getEntries = getProps;
 /**
  * Set a key/value entry on a map-like object (by reference).
  *

package/util/regexp.d.ts

@@ -16,7 +16,7 @@ export declare const isRegExp: <T extends RegExp>(v: unknown) => v is T;
 /** Assert that an unknown value is a `RegExp` instance. */
 export declare function assertRegExp<T extends RegExp>(v: T | unknown): asserts v is T;
 /** Convert a string to a regular expression that matches that string. */
-export declare const getRegExp: (pattern: PossibleRegExp, flags?: string | undefined) => RegExp;
+export declare const getRegExp: (pattern: PossibleRegExp, flags?: string) => RegExp;
 /** Convert a regular expression to its string source. */
 export declare const getRegExpSource: (regexp: PossibleRegExp) => string;
 /** Escape special characters in a string regular expression. */
@@ -35,7 +35,7 @@ export interface NamedRegExp<T extends NamedRegExpData = NamedRegExpData> extend
     exec(input: string): NamedRegExpArray<T> | null;
 }
 /** Create a named regular expression (note: this is unsafe). */
-export declare const getNamedRegExp: <T extends NamedRegExpData>(pattern: string | RegExp, flags?: string | undefined) => NamedRegExp<T>;
+export declare const getNamedRegExp: <T extends NamedRegExpData>(pattern: string | RegExp, flags?: string) => NamedRegExp<T>;
 /** Create regular expression that matches a block of content (possibly asserting that it contains named match groups). */
 export declare function getBlockRegExp<T extends NamedRegExpData>(middle: PossibleRegExp, end?: PossibleRegExp, start?: PossibleRegExp, flags?: string): NamedRegExp<T>;
 export declare function getBlockRegExp(middle: PossibleRegExp, end?: PossibleRegExp, start?: PossibleRegExp, flags?: string): RegExp;

package/util/set.d.ts

@@ -0,0 +1,14 @@
+/** `Set` that cannot be changed. */
+export declare type ImmutableSet<T = unknown> = ReadonlySet<T>;
+/** `Set` that can be changed. */
+export declare type MutableSet<T = unknown> = Set<T>;
+/** Things that can be converted to sets. */
+export declare type PossibleSet<T> = ImmutableSet<T> | Iterable<T>;
+/** Is an unknown value a set? */
+export declare const isSet: <T extends ImmutableSet<unknown>>(v: unknown) => v is T;
+/** Assert that a value is a `Set` instance. */
+export declare function assertSet<T extends ImmutableSet>(v: T | unknown): asserts v is T;
+/** Convert an iterable to a `Set` (if it's already a `Set` it passes through unchanged). */
+export declare function getSet<T>(iterable: PossibleSet<T>): ImmutableSet<T>;
+/** Apply a limit to a set. */
+export declare function limitSet<T>(set: ImmutableSet<T>, limit: number): ImmutableSet<T>;

package/util/set.js

@@ -0,0 +1,17 @@
+import { AssertionError } from "../error/AssertionError.js";
+import { limitItems } from "./iterate.js";
+/** Is an unknown value a set? */
+export const isSet = (v) => v instanceof Set;
+/** Assert that a value is a `Set` instance. */
+export function assertSet(v) {
+    if (!isSet(v))
+        throw new AssertionError(`Must be set`, v);
+}
+/** Convert an iterable to a `Set` (if it's already a `Set` it passes through unchanged). */
+export function getSet(iterable) {
+    return isSet(iterable) ? iterable : new Set(iterable);
+}
+/** Apply a limit to a set. */
+export function limitSet(set, limit) {
+    return limit > set.size ? set : new Set(limitItems(set, limit));
+}

package/util/string.d.ts

@@ -19,13 +19,6 @@ export declare const NNBSP = "\u202F";
 export declare const isString: (v: unknown) => v is string;
 /** Assert that a value is a string. */
 export declare function assertString(value: unknown): asserts value is string;
-/**
- * Convert an unknown value into a string for internal use.
- * - Objects use `obj.toString()` as long as it's not the default `Object.toString()` which is garbage.
- * - Primitives return `true`, `false`, `null`, `undefined`
- * - Numbers return the stringified number.
- */
-export declare function getString(value: unknown): string;
 /**
  * Convert an unknown value into a title string for user-facing use.
  * - Strings return the string.
@@ -39,7 +32,7 @@ export declare function getString(value: unknown): string;
  * - Falsy values like `null` and `undefined` return `"None"`
  * - Everything else returns `"Unknown"`
  */
-export declare function getTitle(value: unknown): string;
+export declare function getString(value: unknown): string;
 /** Concatenate an iterable set of strings together. */
 export declare const joinStrings: (strs: Iterable<string> & NotString, joiner?: string) => string;
 /**

package/util/string.js

@@ -1,7 +1,7 @@
 /* eslint-disable no-control-regex */
 import { AssertionError } from "../error/AssertionError.js";
 import { formatDate, isDate } from "./date.js";
-import { isData } from "./data.js";
+import { formatData, isData } from "./data.js";
 import { getArray, isArray } from "./array.js";
 import { formatNumber, isBetween } from "./number.js";
 /** Non-breaking space. */
@@ -17,25 +17,6 @@ export function assertString(value) {
     if (typeof value !== "string")
         throw new AssertionError(`Must be string`, value);
 }
-/**
- * Convert an unknown value into a string for internal use.
- * - Objects use `obj.toString()` as long as it's not the default `Object.toString()` which is garbage.
- * - Primitives return `true`, `false`, `null`, `undefined`
- * - Numbers return the stringified number.
- */
-export function getString(value) {
-    if (typeof value === "string")
-        return value;
-    if (typeof value === "number")
-        return value.toString();
-    if (typeof value === "object")
-        return value === null ? "null" : typeof value.toString === "function" && value.toString !== Object.prototype.toString ? value.toString() : "object";
-    if (typeof value === "boolean")
-        return value.toString();
-    if (typeof value === "function")
-        return value.name || "function";
-    return typeof value; // "symbol" etc.
-}
 /**
  * Convert an unknown value into a title string for user-facing use.
  * - Strings return the string.
@@ -49,25 +30,25 @@ export function getString(value) {
  * - Falsy values like `null` and `undefined` return `"None"`
  * - Everything else returns `"Unknown"`
  */
-export function getTitle(value) {
-    if (typeof value === "string")
-        return value ? value : "None";
+export function getString(value) {
+    if (value === null || value === undefined)
+        return "None";
     if (typeof value === "boolean")
         return value ? "Yes" : "No";
+    if (typeof value === "string")
+        return value || "None";
     if (typeof value === "number")
         return formatNumber(value);
+    if (typeof value === "symbol")
+        return value.description || "Symbol";
+    if (typeof value === "function")
+        return "Function";
     if (isDate(value))
         return formatDate(value);
     if (isArray(value))
-        return value.map(getTitle).join(", ");
-    if (isData(value)) {
-        if ("name" in value)
-            return getTitle(value.name);
-        if ("title" in value)
-            return getTitle(value.title);
-    }
-    if (!value)
-        return "None";
+        return value.map(getString).join(", ");
+    if (isData(value))
+        return formatData(value);
     return "Unknown";
 }
 /** Concatenate an iterable set of strings together. */

package/util/transform.d.ts

@@ -1,6 +1,6 @@
 import { Data, Value, Prop } from "./data.js";
 import type { Entry } from "./entry.js";
-import type { ImmutableObject } from "./object.js";
+import { ImmutableObject } from "./object.js";
 import { ArrayType, ImmutableArray } from "./array.js";
 /** Object that transforms an input value into an output value with its `transform()` method. */
 export interface Transformable<I, O> {
@@ -36,15 +36,19 @@ export declare function transformProps<T extends Data>(data: T, transforms: Prop
 export declare function mapEntries<I, O>(entries: Iterable<Entry<I>>, transformer: (v: I) => O): Iterable<Entry<O>>;
 export declare function mapEntries<I, O>(entries: Iterable<Entry<I>>, transformer: Transformer<I, O>): Iterable<Entry<O>>;
 /**
- * Transform the _values_ of an object using a transformer.
+ * Transform the _values_ of a map-like object using a transformer.
  * @return New object after transforming its entries.
  */
-export declare function mapObject<T extends Data>(obj: T, transformer: Transformer<Value<T>, Value<T>>): T;
-export declare function mapObject<I extends Data, O extends {
-    [K in keyof I]: unknown;
-}>(obj: I, transformer: Transformer<Value<I>, Value<O>>): O;
 export declare function mapObject<I, O>(obj: ImmutableObject<I>, transformer: (v: I) => O): ImmutableObject<O>;
 export declare function mapObject<I, O>(obj: ImmutableObject<I>, transformer: Transformer<I, O>): ImmutableObject<O>;
+/**
+ * Transform the _values_ of an data object using a transformer.
+ * @return New object after transforming its entries.
+ */
+export declare function mapData<T extends Data>(data: T, transformer: Transformer<Value<T>, Value<T>>): T;
+export declare function mapData<I extends Data, O extends {
+    [K in keyof I]: unknown;
+}>(data: I, transformer: Transformer<Value<I>, Value<O>>): O;
 /**
  * Map an iterable set of items using a transformer.
  * @yield Transformed items after calling `transformer()` on each.

package/util/transform.js

@@ -1,5 +1,6 @@
 import { isFunction } from "./function.js";
 import { getProps, isData } from "./data.js";
+import { getEntries } from "./object.js";
 /** Is an unknown value a derivable. */
 export const isTransformable = (v) => isData(v) && typeof v.transform === "function";
 export function transform(input, transformer) {
@@ -25,7 +26,10 @@ export function* mapEntries(entries, transformer) {
         yield [k, transform(v, transformer)];
 }
 export function mapObject(obj, transformer) {
-    return Object.fromEntries(mapEntries(Object.entries(obj), transformer));
+    return Object.fromEntries(mapEntries(getEntries(obj), transformer));
+}
+export function mapData(data, transformer) {
+    return mapObject(data, transformer);
 }
 export function* mapItems(items, transformer) {
     for (const item of items)

package/util/units.d.ts

@@ -45,7 +45,7 @@ export declare function convertUnits(num: number, from: UnitReference, to: UnitR
  * @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 | undefined, minPrecision?: number | undefined) => string;
+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`
  *
@@ -53,16 +53,16 @@ export declare const formatUnits: (num: number, unit: UnitReference, maxPrecisio
  * @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 | undefined, minPrecision?: number | undefined) => string;
+export declare const formatFullUnits: (num: number, unit: UnitReference, maxPrecision?: number, minPrecision?: number) => string;
 /**
  * Format a percentage.
  * - Combines `getPercent()` and `formatUnits()` for convenience.
  */
-export declare const formatPercent: (numerator: number, denumerator: number, maxPrecision?: number | undefined, minPrecision?: number | undefined) => string;
+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 | undefined, minPrecision?: number | undefined) => string;
+export declare const 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 | undefined, minPrecision?: number | undefined) => string;
+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`
  *
@@ -76,7 +76,7 @@ export declare function formatFullWhen(target: PossibleDate, current?: PossibleD
  * @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 | undefined) => string;
+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`
  *
@@ -90,11 +90,11 @@ export declare function formatWhen(target: PossibleDate, current?: PossibleDate)
  * @param target The date when the thing will happen.
  * @param current Today's date (or a different date to measure from).
  */
-export declare const formatUntil: (target: PossibleDate, current?: PossibleDate | undefined) => string;
+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).
  */
-export declare const formatAgo: (target: PossibleDate, current?: PossibleDate | undefined) => string;
+export declare const formatAgo: (target: PossibleDate, current?: PossibleDate) => string;