shelving 1.138.0 → 1.139.0

package/db/Provider.js

@@ -1,6 +1,6 @@
 import { RequiredError } from "../error/RequiredError.js";
 import { countArray } from "../util/array.js";
-import { getFirstItem } from "../util/iterate.js";
+import { getFirst } from "../util/array.js";
 /** Provider with a fully synchronous interface */
 export class Provider {
     requireItem(collection, id) {
@@ -18,7 +18,7 @@ export class Provider {
         return countArray(this.getQuery(collection, query));
     }
     getFirst(collection, query) {
-        return getFirstItem(this.getQuery(collection, { ...query, $limit: 1 }));
+        return getFirst(this.getQuery(collection, { ...query, $limit: 1 }));
     }
     requireFirst(collection, query) {
         const first = this.getFirst(collection, query);
@@ -49,7 +49,7 @@ export class AsyncProvider {
         return countArray(await this.getQuery(collection, query));
     }
     async getFirst(collection, query) {
-        return getFirstItem(await this.getQuery(collection, { ...query, $limit: 1 }));
+        return getFirst(await this.getQuery(collection, { ...query, $limit: 1 }));
     }
     async requireFirst(collection, query) {
         const first = await this.getFirst(collection, query);

package/error/BaseError.d.ts

@@ -1,5 +1,7 @@
 import type { AnyConstructor } from "../util/class.js";
 import type { AnyFunction } from "../util/function.js";
+/** Any calling function or constructor that can appear in a stack tracer. */
+export type AnyCaller = AnyFunction | AnyConstructor;
 /** Options for `BaseError` that provide additional helpful error functionality. */
 export interface BaseErrorOptions extends ErrorOptions {
     /**
@@ -9,7 +11,7 @@ export interface BaseErrorOptions extends ErrorOptions {
      */
     [key: string]: unknown;
     /** Modify the stack to trim off lines after a certain calling function. */
-    caller?: AnyFunction | AnyConstructor | undefined;
+    caller?: AnyCaller | undefined;
 }
 /** An error that provides additional helpful functionality. */
 export declare abstract class BaseError extends Error {

package/error/index.d.ts

@@ -1,5 +1,4 @@
 export * from "./BaseError.js";
-export * from "./AssertionError.js";
 export * from "./NetworkError.js";
 export * from "./RequestError.js";
 export * from "./RequiredError.js";

package/error/index.js

@@ -1,5 +1,4 @@
 export * from "./BaseError.js";
-export * from "./AssertionError.js";
 export * from "./NetworkError.js";
 export * from "./RequestError.js";
 export * from "./RequiredError.js";

package/markup/rule/link.js

@@ -1,13 +1,14 @@
+import { formatURL } from "../../util/format.js";
 import { getLink } from "../../util/link.js";
 import { getRegExp } from "../../util/regexp.js";
-import { formatURL, getOptionalURL } from "../../util/url.js";
+import { getURL } from "../../util/url.js";
 import { renderMarkup } from "../render.js";
 import { REACT_ELEMENT_TYPE } from "../util/internal.js";
 import { getMarkupRule } from "../util/rule.js";
 /** Render `<a href="">` if the link is a valid one, or `<a>` (with no `href`) if it isn't. */
 function renderLinkMarkupRule({ groups: { title, href: unsafeHref } }, options, key) {
     const { base, schemes, hosts, rel } = options;
-    const url = getOptionalURL(unsafeHref, base);
+    const url = getURL(unsafeHref, base);
     const href = getLink(url, base, schemes, hosts);
     const children = title ? renderMarkup(title, options, "link") : url ? formatURL(url) : "";
     return {

package/package.json

@@ -11,7 +11,7 @@
 		"state-management",
 		"query-builder"
 	],
-	"version": "1.138.0",
+	"version": "1.139.0",
 	"repository": "https://github.com/dhoulb/shelving",
 	"author": "Dave Houlbrooke <dave@shax.com>",
 	"license": "0BSD",

package/schema/AllowSchema.js

@@ -1,14 +1,14 @@
 import { ValueFeedback } from "../feedback/Feedback.js";
-import { requireFirstItem } from "../util/iterate.js";
+import { requireFirst } from "../util/array.js";
+import { formatValue } from "../util/format.js";
 import { getMap, isMapItem } from "../util/map.js";
-import { getString } from "../util/string.js";
 import { Schema } from "./Schema.js";
 /** Define a valid value from an allowed set of values. */
 export class AllowSchema extends Schema {
     allow;
     constructor(options) {
         const allow = getMap(options.allow);
-        const value = requireFirstItem(allow.keys());
+        const value = requireFirst(allow.keys());
         super({ value, ...options });
         this.allow = allow;
     }
@@ -28,7 +28,7 @@ export class AllowStringSchema extends AllowSchema {
         super({ allow: getMap(allow), ...options });
     }
     validator(unsafeValue = this.value) {
-        return super.validate(getString(unsafeValue));
+        return super.validate(formatValue(unsafeValue));
     }
 }
 /** Valid value from an allowed set of values. */

package/schema/DateSchema.js

@@ -1,5 +1,6 @@
 import { ValueFeedback } from "../feedback/Feedback.js";
-import { formatDate, getDate, requireYMD } from "../util/date.js";
+import { getDate, requireYMD } from "../util/date.js";
+import { formatDate } from "../util/format.js";
 import { OPTIONAL } from "./OptionalSchema.js";
 import { Schema } from "./Schema.js";
 /** Define a valid date in YMD format, e.g. `2005-09-12` */

package/schema/EntitySchema.js

@@ -1,6 +1,6 @@
 import { ValueFeedback } from "../feedback/Feedback.js";
-import { isArrayItem } from "../util/array.js";
-import { splitOptionalEntity } from "../util/entity.js";
+import { isItem } from "../util/array.js";
+import { getEntity } from "../util/entity.js";
 import { OPTIONAL } from "./OptionalSchema.js";
 import { StringSchema } from "./StringSchema.js";
 /** Validate a file name matching one or more extensions. */
@@ -12,10 +12,10 @@ export class EntitySchema extends StringSchema {
     }
     validate(unsafeValue = this.value) {
         const entity = super.validate(unsafeValue);
-        const [type] = splitOptionalEntity(entity);
+        const [type] = getEntity(entity);
         if (!type)
             throw new ValueFeedback("Must be entity", unsafeValue);
-        if (this.types && !isArrayItem(this.types, type))
+        if (this.types && !isItem(this.types, type))
             throw new ValueFeedback("Invalid entity type", type);
         return entity;
     }

package/schema/NumberSchema.js

@@ -1,5 +1,6 @@
 import { ValueFeedback } from "../feedback/Feedback.js";
-import { formatNumber, getOptionalNumber, roundStep } from "../util/number.js";
+import { formatNumber } from "../util/format.js";
+import { getNumber, roundStep } from "../util/number.js";
 import { OPTIONAL } from "./OptionalSchema.js";
 import { Schema } from "./Schema.js";
 /** Schema that defines a valid number. */
@@ -14,7 +15,7 @@ export class NumberSchema extends Schema {
         this.step = step;
     }
     validate(unsafeValue = this.value) {
-        const optionalNumber = getOptionalNumber(unsafeValue);
+        const optionalNumber = getNumber(unsafeValue);
         if (typeof optionalNumber !== "number")
             throw new ValueFeedback("Must be number", unsafeValue);
         const roundedNumber = typeof this.step === "number" ? roundStep(optionalNumber, this.step) : optionalNumber;

package/store/ArrayStore.js

@@ -1,5 +1,5 @@
 import { omitArrayItems, toggleArrayItems, withArrayItems } from "../util/array.js";
-import { getFirstItem, getLastItem, requireFirstItem, requireLastItem } from "../util/iterate.js";
+import { getFirst, getLast, requireFirst, requireLast } from "../util/array.js";
 import { Store } from "./Store.js";
 /** Store an array. */
 export class ArrayStore extends Store {
@@ -8,19 +8,19 @@ export class ArrayStore extends Store {
     }
     /** Get the first item in this store or `null` if this query has no items. */
     get optionalFirst() {
-        return getFirstItem(this.value);
+        return getFirst(this.value);
     }
     /** Get the last item in this store or `null` if this query has no items. */
     get optionalLast() {
-        return getLastItem(this.value);
+        return getLast(this.value);
     }
     /** Get the first item in this store. */
     get first() {
-        return requireFirstItem(this.value);
+        return requireFirst(this.value);
     }
     /** Get the last item in this store. */
     get last() {
-        return requireLastItem(this.value);
+        return requireLast(this.value);
     }
     /** Does the document have at least one result. */
     get exists() {

package/util/array.d.ts

@@ -1,3 +1,4 @@
+import type { AnyCaller } from "../error/BaseError.js";
 /**
  * Mutable array: an array that can be changed.
  * - Consistency with `MutableObject<T>` and `ImmutableArray<T>`
@@ -12,16 +13,57 @@ export type ImmutableArray<T = unknown> = readonly T[];
 export type ArrayItem<T extends ImmutableArray> = T[number];
 /** Things that can be converted to arrays. */
 export type PossibleArray<T> = ImmutableArray<T> | Iterable<T>;
-/** Is an unknown value an array? */
-export declare function isArray(value: unknown): value is ImmutableArray;
-/** Assert that an unknown value is an array. */
-export declare function assertArray<T>(arr: unknown): asserts arr is ImmutableArray<T>;
-/** Is an unknown value an item in a specified array? */
-export declare function isArrayItem<T>(arr: ImmutableArray<T>, item: unknown): item is T;
-/** Assert that an unknown value is an item in a specified array. */
-export declare function assertArrayItem<T>(arr: ImmutableArray<T>, item: unknown): asserts item is T;
-/** Convert an iterable to an array (if its not already an array). */
+/** Is an unknown value an array (optionally with specified min/max length). */
+export declare function isArray<T>(arr: MutableArray<T>, min: 1, max: 1): arr is [T];
+export declare function isArray<T>(arr: MutableArray<T>, min: 2, max: 2): arr is [T, T];
+export declare function isArray<T>(arr: MutableArray<T>, min: 3, max: 3): arr is [T, T, T];
+export declare function isArray<T>(arr: MutableArray<T>, min?: 1, max?: number): arr is [T, ...T[]];
+export declare function isArray<T>(arr: MutableArray<T>, min: 2, max?: number): arr is [T, T, ...T[]];
+export declare function isArray<T>(arr: MutableArray<T>, min: 3, max?: number): arr is [T, T, T, ...T[]];
+export declare function isArray<T>(arr: MutableArray<T>, min?: number, max?: number): arr is MutableArray<T>;
+export declare function isArray<T>(arr: ImmutableArray<T>, min: 1, max: 1): arr is readonly [T];
+export declare function isArray<T>(arr: ImmutableArray<T>, min: 2, max: 2): arr is readonly [T, T];
+export declare function isArray<T>(arr: ImmutableArray<T>, min: 3, max: 3): arr is readonly [T, T, T];
+export declare function isArray<T>(arr: ImmutableArray<T>, min?: 1, max?: number): arr is readonly [T, ...T[]];
+export declare function isArray<T>(arr: ImmutableArray<T>, min: 2, max?: number): arr is readonly [T, T, ...T[]];
+export declare function isArray<T>(arr: ImmutableArray<T>, min: 3, max?: number): arr is readonly [T, T, T, ...T[]];
+export declare function isArray<T>(value: unknown, min?: number, max?: number): value is ImmutableArray;
+/** Assert that an unknown value is an array (optionally with specified min/max length). */
+export declare function assertArray<T>(arr: MutableArray<T>, min: 1, max: 1, caller?: AnyCaller): asserts arr is [T];
+export declare function assertArray<T>(arr: MutableArray<T>, min: 2, max: 2, caller?: AnyCaller): asserts arr is [T, T];
+export declare function assertArray<T>(arr: MutableArray<T>, min: 3, max: 3, caller?: AnyCaller): asserts arr is [T, T, T];
+export declare function assertArray<T>(arr: MutableArray<T>, min?: 1, max?: number, caller?: AnyCaller): asserts arr is [T, ...T[]];
+export declare function assertArray<T>(arr: MutableArray<T>, min: 2, max?: number, caller?: AnyCaller): asserts arr is [T, T, ...T[]];
+export declare function assertArray<T>(arr: MutableArray<T>, min: 3, max?: number, caller?: AnyCaller): asserts arr is [T, T, T, ...T[]];
+export declare function assertArray<T>(arr: MutableArray<T>, min: number, max?: number, caller?: AnyCaller): asserts arr is MutableArray<T>;
+export declare function assertArray<T>(arr: ImmutableArray<T>, min: 1, max: 1, caller?: AnyCaller): asserts arr is readonly [T];
+export declare function assertArray<T>(arr: ImmutableArray<T>, min: 2, max: 2, caller?: AnyCaller): asserts arr is readonly [T, T];
+export declare function assertArray<T>(arr: ImmutableArray<T>, min: 3, max: 3, caller?: AnyCaller): asserts arr is readonly [T, T, T];
+export declare function assertArray<T>(arr: ImmutableArray<T>, min?: 1, max?: number, caller?: AnyCaller): asserts arr is readonly [T, ...T[]];
+export declare function assertArray<T>(arr: ImmutableArray<T>, min: 2, max?: number, caller?: AnyCaller): asserts arr is readonly [T, T, ...T[]];
+export declare function assertArray<T>(arr: ImmutableArray<T>, min: 3, max?: number, caller?: AnyCaller): asserts arr is readonly [T, T, T, ...T[]];
+export declare function assertArray<T>(value: unknown, min?: number, max?: number, caller?: AnyCaller): asserts value is ImmutableArray<T>;
+/** Convert a possible array to an array. */
 export declare function getArray<T>(list: PossibleArray<T>): ImmutableArray<T>;
+/** Convert a possible array to an array (optionally with specified min/max length), or throw `RequiredError` if conversion fails. */
+export declare function requireArray<T>(arr: MutableArray<T>, min: 1, max: 1, caller?: AnyCaller): [T];
+export declare function requireArray<T>(arr: MutableArray<T>, min: 2, max: 2, caller?: AnyCaller): [T, T];
+export declare function requireArray<T>(arr: MutableArray<T>, min: 3, max: 3, caller?: AnyCaller): [T, T, T];
+export declare function requireArray<T>(arr: MutableArray<T>, min?: 1, max?: number, caller?: AnyCaller): [T, ...T[]];
+export declare function requireArray<T>(arr: MutableArray<T>, min: 2, max?: number, caller?: AnyCaller): [T, T, ...T[]];
+export declare function requireArray<T>(arr: MutableArray<T>, min: 3, max?: number, caller?: AnyCaller): [T, T, T, ...T[]];
+export declare function requireArray<T>(arr: MutableArray<T>, min?: number, max?: number, caller?: AnyCaller): MutableArray<T>;
+export declare function requireArray<T>(arr: ImmutableArray<T>, min: 1, max: 1, caller?: AnyCaller): readonly [T];
+export declare function requireArray<T>(arr: ImmutableArray<T>, min: 2, max: 2, caller?: AnyCaller): readonly [T, T];
+export declare function requireArray<T>(arr: ImmutableArray<T>, min: 3, max: 3, caller?: AnyCaller): readonly [T, T, T];
+export declare function requireArray<T>(arr: ImmutableArray<T>, min?: 1, max?: number, caller?: AnyCaller): readonly [T, ...T[]];
+export declare function requireArray<T>(arr: ImmutableArray<T>, min: 2, max?: number, caller?: AnyCaller): readonly [T, T, ...T[]];
+export declare function requireArray<T>(arr: ImmutableArray<T>, min: 3, max?: number, caller?: AnyCaller): readonly [T, T, T, ...T[]];
+export declare function requireArray<T>(list: PossibleArray<T>, min?: number, max?: number, caller?: AnyCaller): ImmutableArray<T>;
+/** Is an unknown value an item in a specified array or iterable? */
+export declare function isItem<T>(list: PossibleArray<T>, item: unknown): item is T;
+/** Assert that an unknown value is an item in a specified array. */
+export declare function assertItem<T>(arr: PossibleArray<T>, item: unknown, caller?: AnyCaller): asserts item is T;
 /** Add multiple items to an array (immutably) and return a new array with those items (or the same array if no changes were made). */
 export declare function withArrayItems<T>(list: PossibleArray<T>, ...add: T[]): ImmutableArray<T>;
 /** Pick multiple items from an array (immutably) and return a new array without those items (or the same array if no changes were made). */
@@ -53,60 +95,19 @@ export declare function getUniqueArray<T>(list: PossibleArray<T>): ImmutableArra
 export declare function limitArray<T>(list: PossibleArray<T>, limit: number): ImmutableArray<T>;
 /** Count the items in an array. */
 export declare function countArray<T>(arr: ImmutableArray<T>): number;
-/** Does an array have the specified minimum length.  */
-export declare function isArrayLength<T>(arr: MutableArray<T>, min: 1, max: 1): arr is [T];
-export declare function isArrayLength<T>(arr: MutableArray<T>, min: 2, max: 2): arr is [T, T];
-export declare function isArrayLength<T>(arr: MutableArray<T>, min: 3, max: 3): arr is [T, T, T];
-export declare function isArrayLength<T>(arr: MutableArray<T>, min: 4, max: 4): arr is [T, T, T, T];
-export declare function isArrayLength<T>(arr: MutableArray<T>, min?: 1, max?: number): arr is [T, ...T[]];
-export declare function isArrayLength<T>(arr: MutableArray<T>, min: 2, max?: number): arr is [T, T, ...T[]];
-export declare function isArrayLength<T>(arr: MutableArray<T>, min: 3, max?: number): arr is [T, T, T, ...T[]];
-export declare function isArrayLength<T>(arr: MutableArray<T>, min: 4, max?: number): arr is [T, T, T, T, ...T[]];
-export declare function isArrayLength<T>(arr: MutableArray<T>, min?: number, max?: number): arr is MutableArray<T>;
-export declare function isArrayLength<T>(arr: ImmutableArray<T>, min: 1, max: 1): arr is readonly [T];
-export declare function isArrayLength<T>(arr: ImmutableArray<T>, min: 2, max: 2): arr is readonly [T, T];
-export declare function isArrayLength<T>(arr: ImmutableArray<T>, min: 3, max: 3): arr is readonly [T, T, T];
-export declare function isArrayLength<T>(arr: ImmutableArray<T>, min: 4, max: 4): arr is readonly [T, T, T, T];
-export declare function isArrayLength<T>(arr: ImmutableArray<T>, min?: 1, max?: number): arr is readonly [T, ...T[]];
-export declare function isArrayLength<T>(arr: ImmutableArray<T>, min: 2, max?: number): arr is readonly [T, T, ...T[]];
-export declare function isArrayLength<T>(arr: ImmutableArray<T>, min: 3, max?: number): arr is readonly [T, T, T, ...T[]];
-export declare function isArrayLength<T>(arr: ImmutableArray<T>, min: 4, max?: number): arr is readonly [T, T, T, T, ...T[]];
-export declare function isArrayLength<T>(arr: ImmutableArray<T>, min?: number, max?: number): boolean;
-/** Assert that an array has a specific length (or length is in a specific range). */
-export declare function assertArrayLength<T>(arr: MutableArray<T>, min: 1, max: 1): asserts arr is [T];
-export declare function assertArrayLength<T>(arr: MutableArray<T>, min: 2, max: 2): asserts arr is [T, T];
-export declare function assertArrayLength<T>(arr: MutableArray<T>, min: 3, max: 3): asserts arr is [T, T, T];
-export declare function assertArrayLength<T>(arr: MutableArray<T>, min: 4, max: 4): asserts arr is [T, T, T, T];
-export declare function assertArrayLength<T>(arr: MutableArray<T>, min?: 1, max?: number): asserts arr is [T, ...T[]];
-export declare function assertArrayLength<T>(arr: MutableArray<T>, min: 2, max?: number): asserts arr is [T, T, ...T[]];
-export declare function assertArrayLength<T>(arr: MutableArray<T>, min: 3, max?: number): asserts arr is [T, T, T, ...T[]];
-export declare function assertArrayLength<T>(arr: MutableArray<T>, min: 4, max?: number): asserts arr is [T, T, T, T, ...T[]];
-export declare function assertArrayLength<T>(arr: MutableArray<T>, min: number, max?: number): asserts arr is MutableArray<T>;
-export declare function assertArrayLength<T>(arr: ImmutableArray<T>, min: 1, max: 1): asserts arr is readonly [T];
-export declare function assertArrayLength<T>(arr: ImmutableArray<T>, min: 2, max: 2): asserts arr is readonly [T, T];
-export declare function assertArrayLength<T>(arr: ImmutableArray<T>, min: 3, max: 3): asserts arr is readonly [T, T, T];
-export declare function assertArrayLength<T>(arr: ImmutableArray<T>, min: 4, max: 4): asserts arr is readonly [T, T, T, T];
-export declare function assertArrayLength<T>(arr: ImmutableArray<T>, min?: 1, max?: number): asserts arr is readonly [T, ...T[]];
-export declare function assertArrayLength<T>(arr: ImmutableArray<T>, min: 2, max?: number): asserts arr is readonly [T, T, ...T[]];
-export declare function assertArrayLength<T>(arr: ImmutableArray<T>, min: 3, max?: number): asserts arr is readonly [T, T, T, ...T[]];
-export declare function assertArrayLength<T>(arr: ImmutableArray<T>, min: 4, max?: number): asserts arr is readonly [T, T, T, T, ...T[]];
-export declare function assertArrayLength<T>(arr: ImmutableArray<T>, min: number, max?: number): asserts arr is ImmutableArray<T>;
-/** Require that an array if has the specified minimum length, or throw `RequiredError` if is not. */
-export declare function requireArrayLength<T>(arr: MutableArray<T>, min: 1, max: 1): [T];
-export declare function requireArrayLength<T>(arr: MutableArray<T>, min: 2, max: 2): [T, T];
-export declare function requireArrayLength<T>(arr: MutableArray<T>, min: 3, max: 3): [T, T, T];
-export declare function requireArrayLength<T>(arr: MutableArray<T>, min: 4, max: 4): [T, T, T, T];
-export declare function requireArrayLength<T>(arr: MutableArray<T>, min?: 1, max?: number): [T, ...T[]];
-export declare function requireArrayLength<T>(arr: MutableArray<T>, min: 2, max?: number): [T, T, ...T[]];
-export declare function requireArrayLength<T>(arr: MutableArray<T>, min: 3, max?: number): [T, T, T, ...T[]];
-export declare function requireArrayLength<T>(arr: MutableArray<T>, min: 4, max?: number): [T, T, T, T, ...T[]];
-export declare function requireArrayLength<T>(arr: MutableArray<T>, min?: number, max?: number): MutableArray<T>;
-export declare function requireArrayLength<T>(arr: ImmutableArray<T>, min: 1, max: 1): readonly [T];
-export declare function requireArrayLength<T>(arr: ImmutableArray<T>, min: 2, max: 2): readonly [T, T];
-export declare function requireArrayLength<T>(arr: ImmutableArray<T>, min: 3, max: 3): readonly [T, T, T];
-export declare function requireArrayLength<T>(arr: ImmutableArray<T>, min: 4, max: 4): readonly [T, T, T, T];
-export declare function requireArrayLength<T>(arr: ImmutableArray<T>, min?: 1, max?: number): readonly [T, ...T[]];
-export declare function requireArrayLength<T>(arr: ImmutableArray<T>, min: 2, max?: number): readonly [T, T, ...T[]];
-export declare function requireArrayLength<T>(arr: ImmutableArray<T>, min: 3, max?: number): readonly [T, T, T, ...T[]];
-export declare function requireArrayLength<T>(arr: ImmutableArray<T>, min: 4, max?: number): readonly [T, T, T, T, ...T[]];
-export declare function requireArrayLength<T>(arr: ImmutableArray<T>, min?: number, max?: number): ImmutableArray<T>;
+/** Get the first item from an array or iterable, or `undefined` if it didn't exist. */
+export declare function getFirst<T>(items: PossibleArray<T>): T | undefined;
+/** Get the first item from an array or iterable. */
+export declare function requireFirst<T>(items: PossibleArray<T>, caller?: AnyCaller): T;
+/** Get the last item from an array or iterable, or `undefined` if it didn't exist. */
+export declare function getLast<T>(items: PossibleArray<T>): T | undefined;
+/** Get the last item from an array or iterable. */
+export declare function requireLast<T>(items: PossibleArray<T>, caller?: AnyCaller): T;
+/** Get the next item in an array or iterable. */
+export declare function getNext<T>(items: PossibleArray<T>, item: T): T | undefined;
+/** Get the next item from an array or iterable. */
+export declare function requireNext<T>(items: PossibleArray<T>, item: T, caller?: AnyCaller): T;
+/** Get the previous item in an array or iterable. */
+export declare function getPrev<T>(items: PossibleArray<T>, value: T): T | undefined;
+/** Get the previous item from an array or iterable. */
+export declare function requirePrev<T>(items: PossibleArray<T>, item: T, caller?: AnyCaller): T;

package/util/array.js

@@ -1,28 +1,37 @@
-import { AssertionError } from "../error/AssertionError.js";
 import { RequiredError } from "../error/RequiredError.js";
 import { omitItems, pickItems } from "./iterate.js";
-import { formatRange } from "./number.js";
-/** Is an unknown value an array? */
-export function isArray(value) {
-    return Array.isArray(value);
+export function isArray(value, min = 0, max = Number.POSITIVE_INFINITY) {
+    return Array.isArray(value) && value.length >= min && value.length <= max;
 }
-/** Assert that an unknown value is an array. */
-export function assertArray(arr) {
-    if (!isArray(arr))
-        throw new AssertionError("Must be array", { received: arr, caller: assertArray });
+export function assertArray(value, min, max, caller = assertArray) {
+    if (!isArray(value, min, max))
+        throw new RequiredError(`Must be array${min !== undefined || max !== undefined ? ` with ${min ?? 0} to ${max ?? "∞"} items` : ""}`, {
+            received: value,
+            caller,
+        });
 }
-/** Is an unknown value an item in a specified array? */
-export function isArrayItem(arr, item) {
-    return arr.includes(item);
+/** Convert a possible array to an array. */
+export function getArray(list) {
+    return Array.isArray(list) ? list : Array.from(list);
 }
-/** Assert that an unknown value is an item in a specified array. */
-export function assertArrayItem(arr, item) {
-    if (!isArrayItem(arr, item))
-        throw new AssertionError("Item must exist in array", { item, array: arr, caller: assertArrayItem });
+export function requireArray(list, min, max, caller = requireArray) {
+    const arr = getArray(list);
+    assertArray(arr, min, max, caller);
+    return arr;
 }
-/** Convert an iterable to an array (if its not already an array). */
-export function getArray(list) {
-    return isArray(list) ? list : Array.from(list);
+/** Is an unknown value an item in a specified array or iterable? */
+export function isItem(list, item) {
+    if (isArray(list))
+        list.includes(item);
+    for (const i of list)
+        if (i === item)
+            return true;
+    return false;
+}
+/** Assert that an unknown value is an item in a specified array. */
+export function assertItem(arr, item, caller = assertItem) {
+    if (!isItem(arr, item))
+        throw new RequiredError("Item must exist in array", { item, array: arr, caller });
 }
 /** Add multiple items to an array (immutably) and return a new array with those items (or the same array if no changes were made). */
 export function withArrayItems(list, ...add) {
@@ -55,7 +64,6 @@ export function shuffleArray(items) {
     const arr = Array.from(items);
     for (let i = arr.length - 1; i > 0; i--) {
         const j = Math.floor(Math.random() * (i + 1));
-        // biome-ignore lint/style/noNonNullAssertion: We know these keys are set.
         [arr[i], arr[j]] = [arr[j], arr[i]];
     }
     return arr;
@@ -97,22 +105,74 @@ export function getUniqueArray(list) {
 }
 /** Apply a limit to an array. */
 export function limitArray(list, limit) {
-    const arr = getArray(list);
+    const arr = requireArray(list, undefined, undefined, limitArray);
     return limit > arr.length ? arr : arr.slice(0, limit);
 }
 /** Count the items in an array. */
 export function countArray(arr) {
     return arr.length;
 }
-export function isArrayLength(arr, min = 1, max = Number.POSITIVE_INFINITY) {
-    return arr.length >= min && arr.length <= max;
+/** Get the first item from an array or iterable, or `undefined` if it didn't exist. */
+export function getFirst(items) {
+    if (isArray(items))
+        return items[0];
+    for (const i of items)
+        return i;
+}
+/** Get the first item from an array or iterable. */
+export function requireFirst(items, caller = requireFirst) {
+    const item = getFirst(items);
+    if (item === undefined)
+        throw new RequiredError("First item is required", { items: items, caller });
+    return item;
 }
-export function assertArrayLength(arr, min = 1, max = Number.POSITIVE_INFINITY) {
-    if (!isArrayLength(arr, min, max))
-        throw new AssertionError(`Must be array with length ${formatRange(min, max)}`, { received: arr, caller: assertArrayLength });
+/** Get the last item from an array or iterable, or `undefined` if it didn't exist. */
+export function getLast(items) {
+    if (isArray(items))
+        return items[items.length - 1];
+    let last;
+    for (const i of items) {
+        last = i;
+    }
+    return last;
 }
-export function requireArrayLength(arr, min = 1, max = Number.POSITIVE_INFINITY) {
-    if (!isArrayLength(arr, min, max))
-        throw new RequiredError(`Must be array with length ${formatRange(min, max)}`, { received: arr, caller: requireArrayLength });
-    return arr;
+/** Get the last item from an array or iterable. */
+export function requireLast(items, caller = requireFirst) {
+    const item = getLast(items);
+    if (item === undefined)
+        throw new RequiredError("Last item is required", { items, caller });
+    return item;
+}
+/** Get the next item in an array or iterable. */
+export function getNext(items, item) {
+    let found = false;
+    for (const i of items) {
+        if (found)
+            return i;
+        if (i === item)
+            found = true;
+    }
+}
+/** Get the next item from an array or iterable. */
+export function requireNext(items, item, caller = requireNext) {
+    const next = getNext(items, item);
+    if (next === undefined)
+        throw new RequiredError("Next item is required", { item, items, caller });
+    return next;
+}
+/** Get the previous item in an array or iterable. */
+export function getPrev(items, value) {
+    let last;
+    for (const i of items) {
+        if (i === value)
+            return last;
+        last = i;
+    }
+}
+/** Get the previous item from an array or iterable. */
+export function requirePrev(items, item, caller = requirePrev) {
+    const prev = getPrev(items, item);
+    if (prev === undefined)
+        throw new RequiredError("Previous item is required", { item, items, caller });
+    return prev;
 }

package/util/async.js

@@ -1,4 +1,4 @@
-import { AssertionError } from "../error/AssertionError.js";
+import { RequiredError } from "../error/RequiredError.js";
 /** Is a value an asynchronous value implementing a `then()` function. */
 export function isAsync(value) {
     return typeof value === "object" && value !== null && typeof value.then === "function";
@@ -20,17 +20,17 @@ export function throwAsync(value) {
 /** Assert an unknown value is synchronous (i.e. does not have a `.then()` method). */
 export function assertNotAsync(value) {
     if (isAsync(value))
-        throw new AssertionError("Must be synchronous", { received: value, caller: assertNotAsync });
+        throw new RequiredError("Must be synchronous", { received: value, caller: assertNotAsync });
 }
 /** Assert an unknown value is asynchronous (i.e. has a `.then()` method). */
 export function assertAsync(value) {
     if (!isAsync(value))
-        throw new AssertionError("Must be asynchronous", { received: value, caller: assertAsync });
+        throw new RequiredError("Must be asynchronous", { received: value, caller: assertAsync });
 }
 /** Assert that an unknown value is a `Promise` */
 export function assertPromise(value) {
     if (!(value instanceof Promise))
-        throw new AssertionError("Must be promise", { received: value, caller: assertPromise });
+        throw new RequiredError("Must be promise", { received: value, caller: assertPromise });
 }
 /** Run any queued microtasks now. */
 export function runMicrotasks() {

package/util/base64.d.ts

@@ -1,13 +1,13 @@
 import { type PossibleBytes } from "./bytes.js";
 /** Encode a string or binary data to Base64 string. */
 export declare function encodeBase64(input: PossibleBytes, pad?: boolean): string;
-/** Decode Base64 string to string. */
+/** Decode Base64 string to string (decodes Base64URL too). */
 export declare function decodeBase64String(base64: string): string;
-/** Decode URL-safe Base64 string to binary data (as a UInt8Array). */
+/** Decode URL-safe Base64 string to byte sequence (decodes Base64URL too). */
 export declare function decodeBase64Bytes(base64: string): Uint8Array;
 /** Encode a string or binary data to URL-safe Base64 */
-export declare function encodeBase64Url(input: PossibleBytes, pad?: boolean): string;
-/** Decode a string from URL-safe Base64. */
-export declare function decodeBase64UrlString(base64: string): string;
-/** Decode URL-safe Base64 string to binary data (as a UInt8Array). */
-export declare function decodeBase64UrlBytes(base64: string): Uint8Array;
+export declare function encodeBase64URL(input: PossibleBytes, pad?: boolean): string;
+/** Decode a string from URL-safe Base64 (decodes Base64 too). */
+export declare function decodeBase64URLString(base64: string): string;
+/** Decode URL-safe Base64 string to byte sequence (decodes Base64 too). */
+export declare function decodeBase64URLBytes(base64: string): Uint8Array;