shelving 1.138.0 → 1.139.1

package/util/null.d.ts

@@ -1,3 +1,4 @@
+import type { AnyCaller } from "../error/BaseError.js";
 /** Function that always returns null. */
 export declare function getNull(): null;
 /** Nullable is the value or `null` */
@@ -5,22 +6,22 @@ export type Nullable<T> = T | null;
 /** Is a value null? */
 export declare function isNull(value: unknown): value is null;
 /** Assert that a value is not null. */
-export declare function assertNull<T>(value: Nullable<T>): asserts value is T;
+export declare function assertNull<T>(value: Nullable<T>, caller?: AnyCaller): asserts value is T;
 /** Is a value not null? */
 export declare function notNull<T>(value: Nullable<T>): value is T;
 /** Assert that a value is not null. */
-export declare function assertNotNull<T>(value: Nullable<T>): asserts value is T;
+export declare function assertNotNull<T>(value: Nullable<T>, caller?: AnyCaller): asserts value is T;
 /** Get the not-nullish version of value. */
-export declare function getNotNull<T>(value: Nullable<T>): T;
+export declare function requireNotNull<T>(value: Nullable<T>, caller?: AnyCaller): T;
 /** Nullish is the value or `null` or `undefined` */
 export type Nullish<T> = T | null | undefined;
 /** Is a value nullish? */
 export declare function isNullish<T>(value: Nullish<T>): value is null | undefined;
 /** Assert that a value is not nullish. */
-export declare function assertNullish<T>(value: Nullish<T>): asserts value is T;
+export declare function assertNullish<T>(value: Nullish<T>, caller?: AnyCaller): asserts value is T;
 /** Is a value not nullish? */
 export declare function notNullish<T>(value: Nullish<T>): value is T;
 /** Assert that a value is not nullish. */
-export declare function assertNotNullish<T>(value: Nullish<T>): asserts value is T;
+export declare function assertNotNullish<T>(value: Nullish<T>, caller?: AnyCaller): asserts value is T;
 /** Get the not-nullish version of value. */
-export declare function getNotNullish<T>(value: Nullish<T>): T;
+export declare function requireNotNullish<T>(value: Nullish<T>, caller?: AnyCaller): T;

package/util/null.js

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

package/util/number.d.ts

@@ -1,40 +1,51 @@
-/** Is a value a number? */
-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 finite number (i.e. not `NaN` or positive/negative `Infinity`). */
-export declare function assertFinite(value: unknown): asserts value is number;
+import type { AnyCaller } from "../error/BaseError.js";
+/** Values that can be converted to a number. */
+export type PossibleNumber = number | string | Date;
+/** Is a value a finite number? */
+export declare function isNumber(value: unknown, min?: number, max?: number): value is number;
+/** Assert that a value is a finite number. */
+export declare function assertNumber(value: unknown, min?: number, max?: number, caller?: AnyCaller): asserts value is number;
 /**
- * Is a finite number within a specified range?
+ * Convert an unknown value to a finite number, or return `undefined` if it cannot be converted.
+ * - Note: numbers can be non-finite numbers like `NaN` or `Infinity`. These are detected and will always return `undefined`
  *
- * @param num The number to test, e.g. `17`
- * @param min The start of the range, e.g. `10`
- * @param max The end of the range, e.g. `20`
+ * Conversion rules:
+ * - Finite numbers return numbers.
+ * - `-0` is normalised to `0`
+ * - Strings are parsed as numbers using `Number.parseFloat()` after removing all non-numeric characters.
+ * - Dates return their milliseconds (e.g. `date.getTime()`).
+ * - Everything else returns `undefined`
  */
-export declare const isBetween: (num: number, min: number, max: number) => boolean;
-/** Assert that a value is a number greater than. */
-export declare function assertBetween(value: unknown, min: number, max: number): asserts value is number;
-/** Assert that a value is a number greater than. */
-export declare function assertMax(value: unknown, max: number): asserts value is number;
-/** Assert that a value is a number less than. */
-export declare function assertMin(value: unknown, min: number): asserts value is number;
+export declare function getNumber(value: unknown): number | undefined;
 /**
- * Convert an unknown value to a finite number or `undefined`
- * - Note: numbers can be non-finite numbers like `NaN` or `Infinity`. These are detected and will always return `undefined`
+ * Convert a possible number to a finite number, or throw `ValueError` if the value cannot be converted.
+ */
+export declare function requireNumber(value: PossibleNumber, min?: number, max?: number, caller?: AnyCaller): number;
+/** Is an unknown value an integer (optionally with specified min/max values). */
+export declare function isInteger(value: unknown, min?: number, max?: number): value is number;
+/** Assert that a value is an integer. */
+export declare function assertInteger(value: unknown, min?: number, max?: number, caller?: AnyCaller): asserts value is number;
+/**
+ * Convert an unknown value to an integer, or return `undefined` if it cannot be converted.
  *
  * Conversion rules:
- * - Finite numbers return numbers.
+ * - Integers return integers.
  * - `-0` is normalised to `0`
- * - Strings are parsed as numbers.
+ * - Strings are parsed as integers using `parseInt()` after removing non-numeric characters.
  * - Dates return their milliseconds (e.g. `date.getTime()`).
  * - Everything else returns `undefined`
  */
-export declare function getOptionalNumber(value: unknown): number | undefined;
+export declare function getInteger(value: unknown): number | undefined;
+/** Convert a possible number to an integer, or throw `ValueError` if the value cannot be converted. */
+export declare function requireInteger(value: PossibleNumber, min?: number, max?: number, caller?: AnyCaller): number;
 /**
- * Assertively convert an unknown value to a finite number.
- * @throws `ValueError` if the value cannot be converted.
+ * Is a number within a specified range?
+ *
+ * @param num The number to test, e.g. `17`
+ * @param min The start of the range, e.g. `10`
+ * @param max The end of the range, e.g. `20`
  */
-export declare function getNumber(value: unknown): number;
+export declare function isBetween(num: number, min: number, max: number): boolean;
 /**
  * Round numbers to a given step.
  *
@@ -77,14 +88,6 @@ 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;
-/** Format a number (based on the user's browser language settings). */
-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?: Intl.NumberFormatOptions): string;
-/** Format a number with a short suffix, e.g. `1,000 kg` */
-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?: Intl.NumberFormatOptions): string;
 /**
  * Get a number as a percentage of another number.
  *
@@ -92,15 +95,6 @@ export declare function pluralizeQuantity(num: number, singular: string, plural:
  * @param denumerator The number representing the whole amount.
  */
 export declare function getPercent(numerator: number, denumerator: number): number;
-/**
- * Format a percentage (combines `getPercent()` and `formatQuantity()` for convenience).
- * - Defaults to showing no decimal places.
- * - Defaults to rounding closer to zero (so that 99.99% is shown as 99%).
- *
- * @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?: 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,72 +1,85 @@
-import { AssertionError } from "../error/AssertionError.js";
+import { RequiredError } from "../error/RequiredError.js";
 import { ValueError } from "../error/ValueError.js";
-import { NNBSP } from "./constants.js";
-/** Is a value a number? */
-export function isNumber(value) {
-    return typeof value === "number";
+/** Is a value a finite number? */
+export function isNumber(value, min = Number.NEGATIVE_INFINITY, max = Number.POSITIVE_INFINITY) {
+    return Number.isFinite(value) && value >= min && value <= max;
 }
-/** Assert that a value is a number. */
-export function assertNumber(value) {
-    if (typeof value !== "number")
-        throw new AssertionError("Must be number", { received: value, caller: assertNumber });
-}
-/** 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 AssertionError("Must be finite number", { received: value, caller: assertFinite });
-}
-/**
- * Is a finite number within a specified range?
- *
- * @param num The number to test, e.g. `17`
- * @param min The start of the range, e.g. `10`
- * @param max The end of the range, e.g. `20`
- */
-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 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 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 AssertionError(`Must be number with minimum ${min}`, { received: value, caller: assertMin });
+/** Assert that a value is a finite number. */
+export function assertNumber(value, min, max, caller = assertNumber) {
+    if (!isNumber(value, min, max))
+        throw new RequiredError(`Must be finite number${max !== undefined ? ` between ${min ?? 0} and ${max}` : min !== undefined ? ` above ${min}` : ""}`, { received: value, caller });
 }
 /**
- * Convert an unknown value to a finite number or `undefined`
+ * Convert an unknown value to a finite number, or return `undefined` if it cannot be converted.
  * - Note: numbers can be non-finite numbers like `NaN` or `Infinity`. These are detected and will always return `undefined`
  *
  * Conversion rules:
  * - Finite numbers return numbers.
  * - `-0` is normalised to `0`
- * - Strings are parsed as numbers.
+ * - Strings are parsed as numbers using `Number.parseFloat()` after removing all non-numeric characters.
  * - Dates return their milliseconds (e.g. `date.getTime()`).
  * - Everything else returns `undefined`
  */
-export function getOptionalNumber(value) {
+export function getNumber(value) {
     if (typeof value === "number" && Number.isFinite(value))
         return value === 0 ? 0 : value;
     if (typeof value === "string")
-        return getOptionalNumber(Number.parseFloat(value.replace(NOT_NUMERIC_REGEXP, "")));
+        return getNumber(Number.parseFloat(value.replace(NOT_NUMERIC_REGEXP, "")));
     if (value instanceof Date)
-        return getOptionalNumber(value.getTime());
+        getNumber(value.getTime());
 }
 const NOT_NUMERIC_REGEXP = /[^0-9-.]/g;
 /**
- * Assertively convert an unknown value to a finite number.
- * @throws `ValueError` if the value cannot be converted.
+ * Convert a possible number to a finite number, or throw `ValueError` if the value cannot be converted.
  */
-export function getNumber(value) {
-    const num = getOptionalNumber(value);
-    assertFinite(num);
+export function requireNumber(value, min, max, caller) {
+    const num = getNumber(value);
+    assertNumber(num, min, max, caller);
     return num;
 }
+/** Is an unknown value an integer (optionally with specified min/max values). */
+export function isInteger(value, min = Number.MIN_SAFE_INTEGER, max = Number.MAX_SAFE_INTEGER) {
+    return Number.isInteger(value) && value >= min && value <= max;
+}
+/** Assert that a value is an integer. */
+export function assertInteger(value, min, max, caller = assertInteger) {
+    if (!isInteger(value, min, max))
+        throw new RequiredError(`Must be integer${max !== undefined ? ` between ${min ?? 0} and ${max}` : min !== undefined ? ` above ${min}` : ""}`, { received: value, caller });
+}
+/**
+ * Convert an unknown value to an integer, or return `undefined` if it cannot be converted.
+ *
+ * Conversion rules:
+ * - Integers return integers.
+ * - `-0` is normalised to `0`
+ * - Strings are parsed as integers using `parseInt()` after removing non-numeric characters.
+ * - Dates return their milliseconds (e.g. `date.getTime()`).
+ * - Everything else returns `undefined`
+ */
+export function getInteger(value) {
+    if (typeof value === "number" && Number.isInteger(value))
+        return value === 0 ? 0 : value;
+    if (typeof value === "string")
+        return getInteger(Number.parseInt(value.replace(NOT_NUMERIC_REGEXP, ""), 10));
+    if (value instanceof Date)
+        return getInteger(value.getTime());
+}
+/** Convert a possible number to an integer, or throw `ValueError` if the value cannot be converted. */
+export function requireInteger(value, min, max, caller = requireInteger) {
+    const num = getNumber(value);
+    assertInteger(num, min, max, caller);
+    return num;
+}
+/**
+ * Is a number within a specified range?
+ *
+ * @param num The number to test, e.g. `17`
+ * @param min The start of the range, e.g. `10`
+ * @param max The end of the range, e.g. `20`
+ */
+export function isBetween(num, min, max) {
+    return num >= min && num <= max;
+}
 /**
  * Round numbers to a given step.
  *
@@ -127,29 +140,6 @@ export function wrapNumber(num, min, max) {
         return ((num - min) % (min - max)) + max;
     return num;
 }
-/** Format a number (based on the user's browser language settings). */
-export function formatNumber(num, options) {
-    if (!Number.isFinite(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) {
-    return `${formatNumber(min, options)}–${formatNumber(max, options)}`;
-}
-/** Format a number with a short suffix, e.g. `1,000 kg` */
-export function formatQuantity(num, abbr, options) {
-    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 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.
  *
@@ -159,18 +149,6 @@ export function pluralizeQuantity(num, singular, plural, options) {
 export function getPercent(numerator, denumerator) {
     return Math.max(0, Math.min(100, (100 / denumerator) * numerator));
 }
-/**
- * Format a percentage (combines `getPercent()` and `formatQuantity()` for convenience).
- * - Defaults to showing no decimal places.
- * - Defaults to rounding closer to zero (so that 99.99% is shown as 99%).
- *
- * @param numerator Number representing the amount of progress.
- * @param denumerator The number representing the whole amount.
- */
-export function formatPercent(numerator, denumerator, 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) {
     let sum = 0;

package/util/object.d.ts

@@ -98,13 +98,6 @@ export declare function setProp<T extends MutableObject, K extends Key<T>>(obj:
 export declare function setProps<T extends MutableObject>(obj: T, entries: T | Partial<T> | Iterable<Prop<T>>): void;
 /** Remove several key/value entries from an object (by reference). */
 export declare function deleteProps<T extends MutableObject>(obj: T, ...keys: Key<T>[]): void;
-/**
- * Format an unknown 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 formatObject(obj: ImmutableObject): string;
 /**
  * Get the prototype of an object instance.
  * - Recommend to use this because Typescript's default lib specifies `Object.getPrototypeOf()` returning `any`.

package/util/object.js

@@ -1,4 +1,4 @@
-import { AssertionError } from "../error/AssertionError.js";
+import { RequiredError } from "../error/RequiredError.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 AssertionError("Must be object", { received: value, caller: assertObject });
+        throw new RequiredError("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 AssertionError("Must be plain object", { received: value, caller: assertPlainObject });
+        throw new RequiredError("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 AssertionError("Key must exist in object", { key, obj, caller: assertProp });
+        throw new RequiredError("Key must exist in object", { key, obj, caller: assertProp });
 }
 /** Turn a possible object into an object. */
 export function getObject(obj) {
@@ -87,26 +87,6 @@ export function deleteProps(obj, ...keys) {
     for (const key of keys)
         delete obj[key];
 }
-/**
- * Format an unknown 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 formatObject(obj) {
-    if (typeof obj.toString === "function" && obj.toString !== Object.prototype.toString)
-        return obj.toString();
-    const name = obj.name;
-    if (typeof name === "string")
-        return name;
-    const title = obj.title;
-    if (typeof title === "string")
-        return title;
-    const id = obj.id;
-    if (typeof id === "string")
-        return id;
-    return "Object";
-}
 /**
  * Get the prototype of an object instance.
  * - Recommend to use this because Typescript's default lib specifies `Object.getPrototypeOf()` returning `any`.

package/util/optional.d.ts

@@ -1,6 +1,7 @@
+import type { AnyCaller } from "../error/BaseError.js";
 /** Optional is the value or `null` or `undefined` (synonym for `Nullish`). */
 export type Optional<T> = T | null | undefined;
 /** Get a required value. */
-export declare function getRequired<T>(value: Optional<T>): T;
+export declare function getRequired<T>(value: Optional<T>, caller?: AnyCaller): T;
 /** Is a value not optional? */
 export declare function notOptional<T>(value: Optional<T>): value is T;

package/util/optional.js

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

package/util/path.d.ts

@@ -1,3 +1,4 @@
+import type { AnyCaller } from "../error/BaseError.js";
 import { type Optional } from "./optional.js";
 /** Absolute path string starts with `/` slash. */
 export type AbsolutePath = `/` | `/${string}`;
@@ -10,25 +11,25 @@ export declare function isAbsolutePath(path: string): path is AbsolutePath;
 /** Is a string path an absolute path? */
 export declare function isRelativePath(path: string): path is RelativePath;
 /**
- * Resolve a relative or absolute path and return the path, or `undefined` if not a valid path.
- * - Uses `new URL` to do path processing, so URL strings e.g.
+ * Resolve a relative or absolute path and return the absolute path, or `undefined` if not a valid path.
+ * - Uses `new URL` to do path processing, so URL strings can also be resolved.
  * - Returned paths are cleaned with `cleanPath()` so runs of slashes and trailing slashes are removed.
  *
- * @param possible Absolute path e.g. `/a/b/c`, relative path e.g. `./a` or `b` or `../c`, URL string e.g. `http://shax.com/a/b/c`, or `URL` instance.
+ * @param value Absolute path e.g. `/a/b/c`, relative path e.g. `./a` or `b` or `../c`, URL string e.g. `http://shax.com/a/b/c`, or `URL` instance.
  * @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: Optional<string | URL>, base?: AbsolutePath | undefined): AbsolutePath | undefined;
+export declare function getPath(value: Optional<string | URL>, base?: AbsolutePath | undefined): AbsolutePath | undefined;
 /**
  * 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.
  *
- * @param possible Absolute path e.g. `/a/b/c`, relative path e.g. `./a` or `b` or `../c`, URL string e.g. `http://shax.com/a/b/c`, or `URL` instance.
+ * @param value Absolute path e.g. `/a/b/c`, relative path e.g. `./a` or `b` or `../c`, URL string e.g. `http://shax.com/a/b/c`, or `URL` instance.
  * @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 requirePath(possible: string, base?: AbsolutePath): AbsolutePath;
+export declare function requirePath(value: string, base?: AbsolutePath, caller?: AnyCaller): 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

@@ -14,18 +14,18 @@ function _cleanPath(path) {
         .replace(/(?!^)\/$/g, ""); // Trailing slashes.
 }
 /**
- * Resolve a relative or absolute path and return the path, or `undefined` if not a valid path.
- * - Uses `new URL` to do path processing, so URL strings e.g.
+ * Resolve a relative or absolute path and return the absolute path, or `undefined` if not a valid path.
+ * - Uses `new URL` to do path processing, so URL strings can also be resolved.
  * - Returned paths are cleaned with `cleanPath()` so runs of slashes and trailing slashes are removed.
  *
- * @param possible Absolute path e.g. `/a/b/c`, relative path e.g. `./a` or `b` or `../c`, URL string e.g. `http://shax.com/a/b/c`, or `URL` instance.
+ * @param value Absolute path e.g. `/a/b/c`, relative path e.g. `./a` or `b` or `../c`, URL string e.g. `http://shax.com/a/b/c`, or `URL` instance.
  * @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 = "/") {
-    if (notOptional(possible)) {
+export function getPath(value, base = "/") {
+    if (notOptional(value)) {
         try {
-            const { pathname, search, hash } = new URL(possible, `http://j.com${base}/`);
+            const { pathname, search, hash } = new URL(value, `http://j.com${base}/`);
             if (isAbsolutePath(pathname))
                 return `${_cleanPath(pathname)}${search}${hash}`;
         }
@@ -39,14 +39,14 @@ export function getPath(possible, base = "/") {
  * - 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.
  *
- * @param possible Absolute path e.g. `/a/b/c`, relative path e.g. `./a` or `b` or `../c`, URL string e.g. `http://shax.com/a/b/c`, or `URL` instance.
+ * @param value Absolute path e.g. `/a/b/c`, relative path e.g. `./a` or `b` or `../c`, URL string e.g. `http://shax.com/a/b/c`, or `URL` instance.
  * @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 requirePath(possible, base) {
-    const path = getPath(possible, base);
+export function requirePath(value, base, caller = requirePath) {
+    const path = getPath(value, base);
     if (!path)
-        throw new RequiredError("Invalid URL", { received: possible, caller: requirePath });
+        throw new RequiredError("Invalid URL", { received: value, caller });
     return path;
 }
 /** Is a target path active? */

package/util/query.js

@@ -1,7 +1,7 @@
 import { isArray, limitArray } from "./array.js";
+import { requireLast } 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";
@@ -105,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 = requireLastItem(sorts);
+    const lastSort = requireLast(sorts);
     const newQuery = { ...query };
     for (const sort of sorts) {
         const { key, direction } = sort;
@@ -117,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 = requireLastItem(sorts);
+    const lastSort = requireLast(sorts);
     const newQuery = { ...query };
     for (const sort of sorts) {
         const { key, direction } = sort;

package/util/random.js

@@ -1,4 +1,4 @@
-import { getDefined } from "./undefined.js";
+import { requireDefined } from "./undefined.js";
 /** Generate a random integer between two numbers. */
 export function getRandom(min = Number.MIN_SAFE_INTEGER, max = Number.MAX_SAFE_INTEGER) {
     return Math.round(Math.random() * (max - min) + min);
@@ -30,5 +30,5 @@ export function getRandomCharacter(str) {
 }
 /** Get a random item from an array or random character from a string string. */
 export function getRandomItem(arr) {
-    return getDefined(arr[getRandom(0, arr.length - 1)]);
+    return requireDefined(arr[getRandom(0, arr.length - 1)]);
 }

package/util/regexp.js

@@ -1,4 +1,4 @@
-import { AssertionError } from "../error/AssertionError.js";
+import { RequiredError } from "../error/RequiredError.js";
 import { ValueError } from "../error/ValueError.js";
 import { getArray } from "./array.js";
 /** Regular expression that always matches everything. */
@@ -12,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 AssertionError("Must be regular expression", { received: value, caller: assertRegExp });
+        throw new RequiredError("Must be regular expression", { received: value, caller: assertRegExp });
 }
 export function getRegExp(pattern, flags) {
     return typeof pattern === "string" ? new RegExp(pattern, flags) : pattern;