shelving 1.135.0 → 1.137.0

package/util/link.js

@@ -1,4 +1,4 @@
-import { ValidationError } from "../error/ValidationError.js";
+import { ValueError } from "../error/ValueError.js";
 import { getOptionalURL, isURL } from "./url.js";
 /** Default whitelist for URL schemes. */
 const SCHEMES = ["http:", "https:"];
@@ -7,25 +7,25 @@ export function isLinkURL(value) {
     return isURL(value) && !!value.protocol;
 }
 /** Convert a possible URL to a URL or return `undefined` if conversion fails. */
-export function getOptionalLinkURL(possible, base, schemes = SCHEMES, hosts) {
+export function getLinkURL(possible, base, schemes = SCHEMES, hosts) {
     const url = getOptionalURL(possible, base);
     if (url && schemes.includes(url.protocol) && (!hosts || hosts.includes(url.host)))
         return url;
 }
 /** Convert a possible URL to a URL or return `undefined` if conversion fails. */
-export function getLinkURL(possible, base, schemes, hosts) {
-    const url = getOptionalLinkURL(possible, base, schemes, hosts);
+export function requireLinkURL(possible, base, schemes, hosts) {
+    const url = getLinkURL(possible, base, schemes, hosts);
     if (!url)
-        throw new ValidationError("Invalid link", possible);
+        throw new ValueError("Invalid link", { received: possible, caller: requireLinkURL });
     return url;
 }
 /** Convert a possible URL to a absolute URL string or return `undefined` if conversion fails. */
-export function getOptionalLink(possible, base, schemes = SCHEMES, hosts) {
+export function getLink(possible, base, schemes = SCHEMES, hosts) {
     const url = getOptionalURL(possible, base);
     if (url && schemes.includes(url.protocol) && (!hosts || hosts.includes(url.host)))
         return url.href;
 }
 /** Convert a possible URL to an absolute URL string. */
-export function getLink(possible, base, schemes, hosts) {
-    return getLinkURL(possible, base, schemes, hosts).href;
+export function requireLink(possible, base, schemes, hosts) {
+    return requireLinkURL(possible, base, schemes, hosts).href;
 }

package/util/map.d.ts

@@ -38,7 +38,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;
-/** 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 `undefined` if it doesn't exist. */
-export declare function getOptionalMapItem<K, T>(map: ImmutableMap<K, T>, key: K): T | undefined;
+/** Get an item in a map, or throw `RequiredError` if it doesn't exist. */
+export declare function requireMapItem<K, T>(map: ImmutableMap<K, T>, key: K): T;
+/** Get an item in a map, or `undefined` if it doesn't exist. */
+export declare function getMapItem<K, T>(map: ImmutableMap<K, T>, key: K): T | undefined;

package/util/map.js

@@ -1,5 +1,5 @@
-import { NotFoundError } from "../error/NotFoundError.js";
-import { ValidationError } from "../error/ValidationError.js";
+import { AssertionError } from "../error/AssertionError.js";
+import { RequiredError } from "../error/RequiredError.js";
 import { isIterable, limitItems } from "./iterate.js";
 /** Class for a `Map` that cannot be changed (so you can extend `Map` while implementing `ImmutableMap`). */
 export const ImmutableMap = Map;
@@ -10,7 +10,7 @@ export function isMap(value) {
 /** Assert that a value is a `Map` instance. */
 export function assertMap(value) {
     if (!isMap(value))
-        throw new ValidationError("Must be map", value);
+        throw new AssertionError("Must be map", { received: value, caller: assertMap });
 }
 /** Is an unknown value a key for an item in a map? */
 export function isMapItem(map, key) {
@@ -19,7 +19,7 @@ export function isMapItem(map, key) {
 /** Assert that an unknown value is a key for an item in a map. */
 export function assertMapItem(map, key) {
     if (!isMapItem(map, key))
-        throw new ValidationError("Must be map item", key);
+        throw new AssertionError("Key must exist in map", { key, map, caller: assertMapItem });
 }
 export function getMap(input) {
     return isMap(input) ? input : new Map(isIterable(input) ? input : Object.entries(input));
@@ -43,13 +43,13 @@ export function removeMapItems(map, ...keys) {
     for (const key of keys)
         map.delete(key);
 }
-/** Get an item in a map or throw an error if it doesn't exist. */
-export function getMapItem(map, key) {
+/** Get an item in a map, or throw `RequiredError` if it doesn't exist. */
+export function requireMapItem(map, key) {
     if (!map.has(key))
-        throw new NotFoundError("Map item is required");
+        throw new RequiredError("Key must exist in map", { key, map, caller: requireMapItem });
     return map.get(key);
 }
-/** Get an item in a map or `undefined` if it doesn't exist. */
-export function getOptionalMapItem(map, key) {
+/** Get an item in a map, or `undefined` if it doesn't exist. */
+export function getMapItem(map, key) {
     return map.get(key);
 }

package/util/null.js

@@ -1,4 +1,4 @@
-import { ValidationError } from "../error/ValidationError.js";
+import { AssertionError } from "../error/AssertionError.js";
 /** Function that always returns null. */
 export function getNull() {
     return null;
@@ -10,7 +10,7 @@ export function isNull(value) {
 /** Assert that a value is not null. */
 export function assertNull(value) {
     if (value !== null)
-        throw new ValidationError("Must be null", value);
+        throw new AssertionError("Must be null", { received: value, caller: assertNull });
 }
 /** Is a value not null? */
 export function notNull(value) {
@@ -19,7 +19,7 @@ export function notNull(value) {
 /** Assert that a value is not null. */
 export function assertNotNull(value) {
     if (value === null)
-        throw new ValidationError("Must not be null", value);
+        throw new AssertionError("Must not be null", { received: value, caller: assertNotNull });
 }
 /** Get the not-nullish version of value. */
 export function getNotNull(value) {
@@ -33,7 +33,7 @@ export function isNullish(value) {
 /** Assert that a value is not nullish. */
 export function assertNullish(value) {
     if (value !== null && value !== undefined)
-        throw new ValidationError("Must be null or undefined", value);
+        throw new AssertionError("Must be null or undefined", { received: value, caller: assertNullish });
 }
 /** Is a value not nullish? */
 export function notNullish(value) {
@@ -42,7 +42,7 @@ export function notNullish(value) {
 /** Assert that a value is not nullish. */
 export function assertNotNullish(value) {
     if (value === null || value === undefined)
-        throw new ValidationError("Must not be null or undefined", value);
+        throw new AssertionError("Must not be null or undefined", { received: value, caller: assertNotNullish });
 }
 /** Get the not-nullish version of value. */
 export function getNotNullish(value) {

package/util/number.d.ts

@@ -2,7 +2,7 @@
 export declare function isNumber(value: unknown): value is number;
 /** Assert that a value is a number. */
 export declare function assertNumber(value: unknown): asserts value is number;
-/** Assert that a value is a number greater than. */
+/** Assert that a value is a finite number (i.e. not `NaN` or positive/negative `Infinity`). */
 export declare function assertFinite(value: unknown): asserts value is number;
 /**
  * Is a finite number within a specified range?
@@ -77,19 +77,14 @@ export declare function boundNumber(num: number, min: number, max: number): numb
  * - e.g. `-2` bounded by `2` and `8` is `4`
  */
 export declare function wrapNumber(num: number, min: number, max: number): number;
-/** Options for `formatNumber()` and `formatRange()`. */
-export interface NumberOptions extends Intl.NumberFormatOptions {
-    roundingMode?: "ceil" | "floor" | "expand" | "trunc" | "halfCeil" | "halfFloor" | "halfExpand" | "halfTrunc" | "halfEven" | undefined;
-    roundingPriority?: "morePrecision" | "lessPrecision" | undefined;
-}
 /** Format a number (based on the user's browser language settings). */
-export declare function formatNumber(num: number, options?: NumberOptions): string;
+export declare function formatNumber(num: number, options?: Intl.NumberFormatOptions): string;
 /** Format a number range (based on the user's browser language settings). */
-export declare function formatRange(min: number, max: number, options?: NumberOptions): string;
+export declare function formatRange(min: number, max: number, options?: Intl.NumberFormatOptions): string;
 /** Format a number with a short suffix, e.g. `1,000 kg` */
-export declare function formatQuantity(num: number, abbr: string, options?: NumberOptions): string;
+export declare function formatQuantity(num: number, abbr: string, options?: Intl.NumberFormatOptions): string;
 /** Format a number with a longer full-word suffix. */
-export declare function pluralizeQuantity(num: number, singular: string, plural: string, options?: NumberOptions): string;
+export declare function pluralizeQuantity(num: number, singular: string, plural: string, options?: Intl.NumberFormatOptions): string;
 /**
  * Get a number as a percentage of another number.
  *
@@ -105,7 +100,7 @@ export declare function getPercent(numerator: number, denumerator: number): numb
  * @param numerator Number representing the amount of progress.
  * @param denumerator The number representing the whole amount.
  */
-export declare function formatPercent(numerator: number, denumerator: number, options?: NumberOptions): string;
+export declare function formatPercent(numerator: number, denumerator: number, options?: Intl.NumberFormatOptions): 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,4 +1,5 @@
-import { ValidationError } from "../error/ValidationError.js";
+import { AssertionError } from "../error/AssertionError.js";
+import { ValueError } from "../error/ValueError.js";
 import { NNBSP } from "./constants.js";
 /** Is a value a number? */
 export function isNumber(value) {
@@ -7,12 +8,12 @@ export function isNumber(value) {
 /** Assert that a value is a number. */
 export function assertNumber(value) {
     if (typeof value !== "number")
-        throw new ValidationError("Must be number", value);
+        throw new AssertionError("Must be number", { received: value, caller: assertNumber });
 }
-/** Assert that a value is a number greater than. */
+/** Assert that a value is a finite number (i.e. not `NaN` or positive/negative `Infinity`). */
 export function assertFinite(value) {
     if (typeof value !== "number" || !Number.isFinite(value))
-        throw new ValidationError("Must be finite number", value);
+        throw new AssertionError("Must be finite number", { received: value, caller: assertFinite });
 }
 /**
  * Is a finite number within a specified range?
@@ -25,17 +26,17 @@ export const isBetween = (num, min, max) => num >= min && num <= max;
 /** Assert that a value is a number greater than. */
 export function assertBetween(value, min, max) {
     if (typeof value !== "number" || isBetween(value, min, max))
-        throw new ValidationError(`Must be number between ${min} and ${max}`, value);
+        throw new AssertionError(`Must be number between ${min} and ${max}`, { received: value, caller: assertBetween });
 }
 /** Assert that a value is a number greater than. */
 export function assertMax(value, max) {
     if (typeof value !== "number" || value > max)
-        throw new ValidationError(`Must be number with maximum ${max}`, value);
+        throw new AssertionError(`Must be number with maximum ${max}`, { received: value, caller: assertMax });
 }
 /** Assert that a value is a number less than. */
 export function assertMin(value, min) {
     if (typeof value !== "number" || value < min)
-        throw new ValidationError(`Must be number with minimum ${min}`, value);
+        throw new AssertionError(`Must be number with minimum ${min}`, { received: value, caller: assertMin });
 }
 /**
  * Convert an unknown value to a finite number or `undefined`
@@ -106,7 +107,8 @@ export function truncateNumber(num, precision = 0) {
  * - e.g. `12` bounded by `2` and `8` is `8`
  */
 export function boundNumber(num, min, max) {
-    assertMin(max, min); // Assert that max is more than min.
+    if (max < min)
+        throw new ValueError("Max must be more than min", { min, max, caller: wrapNumber });
     return Math.max(min, Math.min(max, num));
 }
 /**
@@ -117,7 +119,8 @@ export function boundNumber(num, min, max) {
  * - e.g. `-2` bounded by `2` and `8` is `4`
  */
 export function wrapNumber(num, min, max) {
-    assertMin(max, min); // Assert that max is more than min.
+    if (max < min)
+        throw new ValueError("Max must be more than min", { min, max, caller: wrapNumber });
     if (num >= max)
         return ((num - max) % (max - min)) + min;
     if (num < min)
@@ -126,11 +129,9 @@ export function wrapNumber(num, min, max) {
 }
 /** Format a number (based on the user's browser language settings). */
 export function formatNumber(num, options) {
-    if (Number.isNaN(num))
-        return "None";
     if (!Number.isFinite(num))
-        return "∞";
-    return new Intl.NumberFormat(undefined, options).format(num);
+        return Number.isNaN(num) ? "-" : "∞";
+    return new Intl.NumberFormat(undefined, options).format(num).replace(/ /, NNBSP);
 }
 /** Format a number range (based on the user's browser language settings). */
 export function formatRange(min, max, options) {
@@ -138,13 +139,16 @@ export function formatRange(min, max, options) {
 }
 /** Format a number with a short suffix, e.g. `1,000 kg` */
 export function formatQuantity(num, abbr, options) {
-    const str = formatNumber(num, options);
-    return `${str}${str.length > 2 || abbr.length > 2 ? NNBSP : ""}${abbr}`;
+    const o = { unitDisplay: "short", ...options, style: "decimal" };
+    const str = formatNumber(num, o);
+    const sep = o.unitDisplay === "narrow" ? "" : NNBSP;
+    return `${str}${sep}${abbr}`;
 }
 /** Format a number with a longer full-word suffix. */
 export function pluralizeQuantity(num, singular, plural, options) {
-    const qty = formatNumber(num, options);
-    return `${qty} ${qty === "1" ? singular : plural}`;
+    const o = { ...options, style: "decimal" };
+    const qty = formatNumber(num, o);
+    return `${qty}${NNBSP}${num === 1 ? singular : plural}`;
 }
 /**
  * Get a number as a percentage of another number.
@@ -164,7 +168,8 @@ export function getPercent(numerator, denumerator) {
  * @param denumerator The number representing the whole amount.
  */
 export function formatPercent(numerator, denumerator, options) {
-    return formatQuantity(getPercent(numerator, denumerator), "%", { maximumFractionDigits: 0, roundingMode: "trunc", ...options });
+    const fullOptions = { style: "percent", maximumFractionDigits: 0, roundingMode: "trunc", ...options };
+    return formatNumber(getPercent(numerator, denumerator), fullOptions);
 }
 /** Sum an iterable set of numbers and return the total. */
 export function sumNumbers(nums) {

package/util/object.js

@@ -1,4 +1,4 @@
-import { ValidationError } from "../error/ValidationError.js";
+import { AssertionError } from "../error/AssertionError.js";
 import { isIterable } from "./iterate.js";
 /** Is an unknown value an unknown object? */
 export function isObject(value) {
@@ -7,7 +7,7 @@ export function isObject(value) {
 /** Assert that a value is an object */
 export function assertObject(value) {
     if (!isObject(value))
-        throw new ValidationError("Must be object", value);
+        throw new AssertionError("Must be object", { received: value, caller: assertObject });
 }
 /** Is an unknown value a plain object? */
 export function isPlainObject(value) {
@@ -20,14 +20,14 @@ export function isPlainObject(value) {
 /** Assert that an unknown value is a plain object */
 export function assertPlainObject(value) {
     if (!isPlainObject(value))
-        throw new ValidationError("Must be plain object", value);
+        throw new AssertionError("Must be plain object", { received: value, caller: assertPlainObject });
 }
 /** Is an unknown value the key for an own prop of an object. */
 export const isProp = (obj, key) => Object.hasOwn(obj, key);
 /** Assert that an unknown value is the key for an own prop of an object. */
 export function assertProp(obj, key) {
     if (!isProp(obj, key))
-        throw new ValidationError("Must be object prop", key);
+        throw new AssertionError("Key must exist in object", { key, obj, caller: assertProp });
 }
 /** Turn a possible object into an object. */
 export function getObject(obj) {

package/util/optional.js

@@ -1,8 +1,8 @@
-import { NotFoundError } from "../error/NotFoundError.js";
+import { RequiredError } from "../error/RequiredError.js";
 /** Get a required value. */
 export function getRequired(value) {
     if (value === null || value === undefined)
-        throw new NotFoundError();
+        throw new RequiredError("Value is required", { received: value, caller: getRequired });
     return value;
 }
 /** Is a value not optional? */

package/util/path.d.ts

@@ -18,9 +18,9 @@ export declare function isRelativePath(path: string): path is RelativePath;
  * @param base Absolute path used for resolving relative paths in `possible`
  * @return Absolute path with a leading trailing slash, e.g. `/a/c/b`
  */
-export declare function getOptionalPath(possible: Optional<string | URL>, base?: AbsolutePath | undefined): AbsolutePath | undefined;
+export declare function getPath(possible: Optional<string | URL>, base?: AbsolutePath | undefined): AbsolutePath | undefined;
 /**
- * Resolve a relative or absolute path and return the path, or throw `ValueError` if not a valid path.
+ * Resolve a relative or absolute path and return the path, or throw `RequiredError` if not a valid path.
  * - Internally uses `new URL` to do path processing but shouldn't ever reveal that fact.
  * - Returned paths are cleaned with `cleanPath()` so runs of slashes and trailing slashes are removed.
  *
@@ -28,7 +28,7 @@ export declare function getOptionalPath(possible: Optional<string | URL>, base?:
  * @param base Absolute path used for resolving relative paths in `possible`
  * @return Absolute path with a leading trailing slash, e.g. `/a/c/b`
  */
-export declare function getPath(possible: string, base?: AbsolutePath): AbsolutePath;
+export declare function requirePath(possible: string, base?: AbsolutePath): AbsolutePath;
 /** Is a target path active? */
 export declare function isPathActive(target: AbsolutePath, current: AbsolutePath): boolean;
 /** Is a target path proud (i.e. is the current path, or is a child of the current path)? */

package/util/path.js

@@ -1,4 +1,4 @@
-import { ValidationError } from "../error/ValidationError.js";
+import { RequiredError } from "../error/RequiredError.js";
 import { notOptional } from "./optional.js";
 /** Is a string path an absolute path? */
 export function isAbsolutePath(path) {
@@ -22,7 +22,7 @@ function _cleanPath(path) {
  * @param base Absolute path used for resolving relative paths in `possible`
  * @return Absolute path with a leading trailing slash, e.g. `/a/c/b`
  */
-export function getOptionalPath(possible, base = "/") {
+export function getPath(possible, base = "/") {
     if (notOptional(possible)) {
         try {
             const { pathname, search, hash } = new URL(possible, `http://j.com${base}/`);
@@ -35,7 +35,7 @@ export function getOptionalPath(possible, base = "/") {
     }
 }
 /**
- * Resolve a relative or absolute path and return the path, or throw `ValueError` if not a valid path.
+ * Resolve a relative or absolute path and return the path, or throw `RequiredError` if not a valid path.
  * - Internally uses `new URL` to do path processing but shouldn't ever reveal that fact.
  * - Returned paths are cleaned with `cleanPath()` so runs of slashes and trailing slashes are removed.
  *
@@ -43,10 +43,10 @@ export function getOptionalPath(possible, base = "/") {
  * @param base Absolute path used for resolving relative paths in `possible`
  * @return Absolute path with a leading trailing slash, e.g. `/a/c/b`
  */
-export function getPath(possible, base) {
-    const path = getOptionalPath(possible, base);
+export function requirePath(possible, base) {
+    const path = getPath(possible, base);
     if (!path)
-        throw new ValidationError("Invalid URL", possible);
+        throw new RequiredError("Invalid URL", { received: possible, caller: requirePath });
     return path;
 }
 /** Is a target path active? */

package/util/query.d.ts

@@ -71,10 +71,10 @@ export declare function queryWritableItems<T extends Data>(items: Iterable<T>, q
 export declare function matchQueryItem<T extends Data>(item: T, filters: ImmutableArray<Filter>): boolean;
 /**  Filter a set of data items using a set of filters. */
 export declare function filterQueryItems<T extends Data>(items: Iterable<T>, filters: ImmutableArray<Filter>): Iterable<T>;
-/** Compare two data items using a set of sorts. */
-export declare function compareQueryItems<T extends Data>(left: T, right: T, sorts: ImmutableArray<Order>): number;
-/**  Sort a set of data items using a set of sorts. */
-export declare function sortQueryItems<T extends Data>(items: Iterable<T>, sorts: ImmutableArray<Order>): Iterable<T>;
+/** Compare two data items using a set of orders. */
+export declare function compareQueryItems<T extends Data>(left: T, right: T, orders: ImmutableArray<Order>): number;
+/**  Sort a set of data items using a set of orders. */
+export declare function sortQueryItems<T extends Data>(items: Iterable<T>, orders: ImmutableArray<Order>): Iterable<T>;
 /** LImit a set of data items using a set of limit. */
 export declare function limitQueryItems<T extends Data>(items: ImmutableArray<T> | Iterable<T>, limit: number | undefined): Iterable<T>;
 /** Get a query for items that appear before a specified item. */

package/util/query.js

@@ -1,6 +1,7 @@
-import { getLastItem, isArray, limitArray } from "./array.js";
+import { isArray, limitArray } from "./array.js";
 import { getDataProp } from "./data.js";
 import { isArrayWith, isEqual, isEqualGreater, isEqualLess, isGreater, isInArray, isLess, notEqual, notInArray } from "./equal.js";
+import { requireLastItem } from "./iterate.js";
 import { limitItems } from "./iterate.js";
 import { getProps } from "./object.js";
 import { compareAscending, compareDescending, sortArray } from "./sort.js";
@@ -82,9 +83,9 @@ export function* filterQueryItems(items, filters) {
         yield* items;
     }
 }
-/** Compare two data items using a set of sorts. */
-export function compareQueryItems(left, right, sorts) {
-    for (const { key, direction } of sorts) {
+/** Compare two data items using a set of orders. */
+export function compareQueryItems(left, right, orders) {
+    for (const { key, direction } of orders) {
         const l = getDataProp(left, key);
         const r = getDataProp(right, key);
         const c = direction === "asc" ? compareAscending(l, r) : compareDescending(l, r);
@@ -93,9 +94,9 @@ export function compareQueryItems(left, right, sorts) {
     }
     return 0;
 }
-/**  Sort a set of data items using a set of sorts. */
-export function sortQueryItems(items, sorts) {
-    return sorts.length ? sortArray(items, compareQueryItems, sorts) : items;
+/**  Sort a set of data items using a set of orders. */
+export function sortQueryItems(items, orders) {
+    return orders.length ? sortArray(items, compareQueryItems, orders) : items;
 }
 /** LImit a set of data items using a set of limit. */
 export function limitQueryItems(items, limit) {
@@ -104,7 +105,7 @@ export function limitQueryItems(items, limit) {
 /** Get a query for items that appear before a specified item. */
 export function getBeforeQuery(query, item) {
     const sorts = getOrders(query);
-    const lastSort = getLastItem(sorts);
+    const lastSort = requireLastItem(sorts);
     const newQuery = { ...query };
     for (const sort of sorts) {
         const { key, direction } = sort;
@@ -116,7 +117,7 @@ export function getBeforeQuery(query, item) {
 /** Get a query for items that appear after a specified item. */
 export function getAfterQuery(query, item) {
     const sorts = getOrders(query);
-    const lastSort = getLastItem(sorts);
+    const lastSort = requireLastItem(sorts);
     const newQuery = { ...query };
     for (const sort of sorts) {
         const { key, direction } = sort;

package/util/regexp.d.ts

@@ -17,9 +17,9 @@ export declare function getRegExpSource(regexp: PossibleRegExp): string;
 /** Escape special characters in a string regular expression. */
 export declare function escapeRegExp(pattern: string): string;
 /** Create regular expression that matches any of a list of other expressions. */
-export declare function getAnyRegExp(patterns: Iterable<PossibleRegExp> & NotString, flags?: string): RegExp;
+export declare function createRegExpAny(patterns: Iterable<PossibleRegExp> & NotString, flags?: string): RegExp;
 /** Create regular expression that matches all of a list of other expressions. */
-export declare function getAllRegExp(patterns: Iterable<PossibleRegExp> & NotString, flags?: string): RegExp;
+export declare function createRegExpAll(patterns: Iterable<PossibleRegExp> & NotString, flags?: string): RegExp;
 /** Regular expression match array that matches a specific string format. */
 export interface TypedRegExpExecArray<T extends string = string> extends RegExpExecArray {
     0: T;
@@ -45,16 +45,16 @@ export declare function isMatch(str: string, regexp: RegExp): boolean;
 /** Match function for finding strings that match against regular expressions (use with `filter()` to negatively filter iterable sets of items). */
 export declare function notMatch(str: string, regexp: RegExp): boolean;
 /** Get an optional regular expression match, or `undefined` if no match could be made. */
-export declare function getOptionalMatch<T extends NamedRegExpData>(str: string, regexp: NamedRegExp<T>): NamedRegExpExecArray<T> | undefined;
-export declare function getOptionalMatch<T extends string>(str: string, regexp: TypedRegExp<T>): TypedRegExpExecArray<T> | undefined;
-export declare function getOptionalMatch(str: string, regexp: RegExp): RegExpExecArray | undefined;
+export declare function getMatch<T extends NamedRegExpData>(str: string, regexp: NamedRegExp<T>): NamedRegExpExecArray<T> | undefined;
+export declare function getMatch<T extends string>(str: string, regexp: TypedRegExp<T>): TypedRegExpExecArray<T> | undefined;
+export declare function getMatch(str: string, regexp: RegExp): RegExpExecArray | undefined;
 /** Get a required regular expression match, or throw `ValueError` if no match could be made. */
-export declare function getMatch<T extends NamedRegExpData>(str: string, regexp: NamedRegExp<T>): NamedRegExpExecArray<T>;
-export declare function getMatch<T extends string>(str: string, regexp: TypedRegExp<T>): TypedRegExpExecArray<T>;
-export declare function getMatch(str: string, regexp: RegExp): RegExpExecArray;
+export declare function requireMatch<T extends NamedRegExpData>(str: string, regexp: NamedRegExp<T>): NamedRegExpExecArray<T>;
+export declare function requireMatch<T extends string>(str: string, regexp: TypedRegExp<T>): TypedRegExpExecArray<T>;
+export declare function requireMatch(str: string, regexp: RegExp): RegExpExecArray;
 /** Get an optional regular expression match, or `undefined` if no match could be made. */
-export declare function getOptionalMatchGroups<T extends NamedRegExpData>(str: string, regexp: NamedRegExp<T>): T | undefined;
-export declare function getOptionalMatchGroups(str: string, regexp: RegExp): NamedRegExpData | undefined;
+export declare function getMatchGroups<T extends NamedRegExpData>(str: string, regexp: NamedRegExp<T>): T | undefined;
+export declare function getMatchGroups(str: string, regexp: RegExp): NamedRegExpData | undefined;
 /** Get a required regular expression match, or throw `ValueError` if no match could be made. */
-export declare function getMatchGroups<T extends NamedRegExpData>(str: string, regexp: NamedRegExp<T>): T;
-export declare function getMatchGroups(str: string, regexp: RegExp): NamedRegExpData;
+export declare function requireMatchGroups<T extends NamedRegExpData>(str: string, regexp: NamedRegExp<T>): T;
+export declare function requireMatchGroups(str: string, regexp: RegExp): NamedRegExpData;

package/util/regexp.js

@@ -1,4 +1,5 @@
-import { ValidationError } from "../error/ValidationError.js";
+import { AssertionError } from "../error/AssertionError.js";
+import { ValueError } from "../error/ValueError.js";
 import { getArray } from "./array.js";
 /** Regular expression that always matches everything. */
 export const ALWAYS_REGEXP = /^.*$/;
@@ -11,7 +12,7 @@ export function isRegExp(value) {
 /** Assert that an unknown value is a `RegExp` instance. */
 export function assertRegExp(value) {
     if (!(value instanceof RegExp))
-        throw new ValidationError("Must be regular expression", value);
+        throw new AssertionError("Must be regular expression", { received: value, caller: assertRegExp });
 }
 export function getRegExp(pattern, flags) {
     return typeof pattern === "string" ? new RegExp(pattern, flags) : pattern;
@@ -26,7 +27,7 @@ export function escapeRegExp(pattern) {
 }
 const REPLACE_ESCAPED = /[-[\]/{}()*+?.\\^$|]/g;
 /** Create regular expression that matches any of a list of other expressions. */
-export function getAnyRegExp(patterns, flags) {
+export function createRegExpAny(patterns, flags) {
     const arr = getArray(patterns).filter(Boolean);
     // If there are no patterns to match against then _no_ string can ever match against any of nothing.
     if (!arr.length)
@@ -35,7 +36,7 @@ export function getAnyRegExp(patterns, flags) {
     return new RegExp(`(?:${getArray(patterns).map(getRegExpSource).join(")|(?:")})`, flags);
 }
 /** Create regular expression that matches all of a list of other expressions. */
-export function getAllRegExp(patterns, flags) {
+export function createRegExpAll(patterns, flags) {
     const arr = getArray(patterns).filter(Boolean);
     // If there are no patterns to match against then _every_ string will match against the entire list of nothing.
     if (!arr.length)
@@ -51,21 +52,21 @@ export function isMatch(str, regexp) {
 export function notMatch(str, regexp) {
     return !regexp.test(str);
 }
-export function getOptionalMatch(str, regexp) {
+export function getMatch(str, regexp) {
     return regexp.exec(str) || undefined;
 }
-export function getMatch(str, regexp) {
-    const match = getOptionalMatch(str, regexp);
+export function requireMatch(str, regexp) {
+    const match = getMatch(str, regexp);
     if (!match)
-        throw new ValidationError("Must match regular expression", str);
+        throw new ValueError("Must match regular expression", { received: str, expected: regexp, caller: requireMatch });
     return match;
 }
-export function getOptionalMatchGroups(str, regexp) {
+export function getMatchGroups(str, regexp) {
     return regexp.exec(str)?.groups || undefined;
 }
-export function getMatchGroups(str, regexp) {
-    const groups = getOptionalMatchGroups(str, regexp);
+export function requireMatchGroups(str, regexp) {
+    const groups = getMatchGroups(str, regexp);
     if (!groups)
-        throw new ValidationError("Must match regular expression", str);
+        throw new ValueError("Must match regular expression", { received: str, expected: regexp, caller: requireMatchGroups });
     return groups;
 }

package/util/sequence.d.ts

@@ -14,7 +14,5 @@ export declare function repeatUntil<T>(source: AsyncIterable<T>, ...signals: [Pr
 export declare function repeatDelay(ms: number): AsyncIterable<number>;
 /** Dispatch items in a sequence to a (possibly async) callback. */
 export declare function callSequence<T>(sequence: AsyncIterable<T>, callback: AsyncValueCallback<T>): AsyncIterable<T>;
-/** Get the first value from an async iterator. **/
-export declare function getNextValue<T>(sequence: AsyncIterable<T>): Promise<T>;
 /** Pull values from a sequence until the returned function is called. */
 export declare function runSequence<T>(sequence: AsyncIterable<T>, onNext?: ValueCallback<T>, onError?: Report): Stop;

package/util/sequence.js

@@ -1,4 +1,3 @@
-import { NotFoundError } from "../error/NotFoundError.js";
 import { getDeferred, getDelay } from "./async.js";
 import { call, callMethod } from "./callback.js";
 import { STOP } from "./constants.js";
@@ -40,12 +39,6 @@ export async function* callSequence(sequence, callback) {
         yield item;
     }
 }
-/** Get the first value from an async iterator. **/
-export async function getNextValue(sequence) {
-    for await (const item of sequence)
-        return item;
-    throw new NotFoundError("First value is required");
-}
 /** Pull values from a sequence until the returned function is called. */
 export function runSequence(sequence, onNext, onError) {
     const { promise, resolve } = getDeferred();

package/util/serialise.js

@@ -1,4 +1,4 @@
-import { ValidationError } from "../error/ValidationError.js";
+import { ValueError } from "../error/ValueError.js";
 import { isArray } from "./array.js";
 import { getPrototype, isObject } from "./object.js";
 const R_QUOTE = /"/g;
@@ -39,7 +39,7 @@ export function serialise(value) {
         const props = Object.entries(value).map(_serialiseEntry).sort();
         return `{${type ? `"$type":${_escapeString(type)}${props.length ? "," : ""}` : ""}${props.join(",")}}`;
     }
-    throw new ValidationError("Cannot serialize value", value);
+    throw new ValueError("Cannot serialize value", { received: value, caller: serialise });
 }
 function _serialiseEntry([key, value]) {
     return `${_escapeString(key)}:${serialise(value)}`;

package/util/set.js

@@ -1,4 +1,4 @@
-import { ValidationError } from "../error/ValidationError.js";
+import { AssertionError } from "../error/AssertionError.js";
 import { limitItems } from "./iterate.js";
 /** Is an unknown value a set? */
 export function isSet(value) {
@@ -7,7 +7,7 @@ export function isSet(value) {
 /** Assert that a value is a `Set` instance. */
 export function assertSet(value) {
     if (!isSet(value))
-        throw new ValidationError("Must be set", value);
+        throw new AssertionError("Must be set", { received: value, caller: assertSet });
 }
 /** Is an unknown value an item in a set? */
 export function isSetItem(set, item) {
@@ -16,7 +16,7 @@ export function isSetItem(set, item) {
 /** Assert that an unknown value is an item in a set. */
 export function assertSetItem(set, item) {
     if (!isSetItem(set, item))
-        throw new ValidationError("Must be set item", item);
+        throw new AssertionError("Item must exist in set", { item, set, caller: assertSetItem });
 }
 /** Convert an iterable to a `Set` (if it's already a `Set` it passes through unchanged). */
 export function getSet(iterable) {