shelving 1.236.0 → 1.236.2

package/util/path.d.ts

@@ -3,17 +3,47 @@
  */
 import type { AnyCaller } from "./function.js";
 import type { Nullish } from "./null.js";
-/** Absolute path string starts with `/` slash. */
+/**
+ * Absolute path string starting with a `/` slash.
+ *
+ * @see https://dhoulb.github.io/shelving/util/path/AbsolutePath
+ */
 export type AbsolutePath = `/` | `/${string}`;
-/** Relative path string is `.` dot, or starts with `./` dot slash. */
+/**
+ * Relative path string that is `.` dot, or starts with `./` dot slash.
+ *
+ * @see https://dhoulb.github.io/shelving/util/path/RelativePath
+ */
 export type RelativePath = `.` | `./` | `./${string}`;
-/** Either an absolute or relative path. */
+/**
+ * Either an absolute or relative path.
+ *
+ * @see https://dhoulb.github.io/shelving/util/path/Path
+ */
 export type Path = AbsolutePath | RelativePath;
-/** Things that can be converted to a path. */
+/**
+ * Things that can be converted to a path.
+ *
+ * @see https://dhoulb.github.io/shelving/util/path/PossiblePath
+ */
 export type PossiblePath = string | readonly string[];
-/** Is a string path an absolute path? */
+/**
+ * Is a string path an absolute path?
+ *
+ * @param path The path to test.
+ * @returns `true` if `path` is an `AbsolutePath` starting with `/`, narrowing its type.
+ * @example isAbsolutePath("/a/b") // true
+ * @see https://dhoulb.github.io/shelving/util/path/isAbsolutePath
+ */
 export declare function isAbsolutePath(path: PossiblePath): path is AbsolutePath;
-/** Is a string path an relative path? */
+/**
+ * Is a string path a relative path?
+ *
+ * @param path The path to test.
+ * @returns `true` if `path` is a `RelativePath` (`.` or starting with `./`), narrowing its type.
+ * @example isRelativePath("./a") // true
+ * @see https://dhoulb.github.io/shelving/util/path/isRelativePath
+ */
 export declare function isRelativePath(path: PossiblePath): path is RelativePath;
 /**
  * Resolve a relative or absolute path and return the absolute path, or `undefined` if not a valid path.
@@ -21,17 +51,24 @@ export declare function isRelativePath(path: PossiblePath): path is RelativePath
  * - Normalises `\` windows paths.
  * - Strips trailing slashes.
  *
- * @param path 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 slash but no trailing slash, e.g. `/a/c/b`
+ * @param inputPath 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 inputBase Absolute path used for resolving relative paths in `inputPath`.
+ * @returns Absolute path with a leading slash but no trailing slash, e.g. `/a/c/b`, or `undefined` if `inputPath` is not a valid path.
+ * @example getPath("./a", "/b") // "/b/a"
+ * @see https://dhoulb.github.io/shelving/util/path/getPath
  */
 export declare function getPath(inputPath: Nullish<PossiblePath>, inputBase?: AbsolutePath): AbsolutePath | undefined;
 /**
- * Normalise a path:
+ * Normalise a path.
  * - Runs of `/` and `\` collapsed to a single `/`.
  * - `.` "current-directory" segments dropped (so `./a/b` → `a/b`, `a/./b` → `a/b`, `.` → `""`).
  * - Trailing slashes stripped.
  * - The root `"/"` is preserved as-is.
+ *
+ * @param path The path to normalise.
+ * @returns The normalised path, preserving the absolute/relative type of `path`.
+ * @example cleanPath("/a//b/") // "/a/b"
+ * @see https://dhoulb.github.io/shelving/util/path/cleanPath
  */
 export declare function cleanPath(path: AbsolutePath): AbsolutePath;
 export declare function cleanPath(path: string): string;
@@ -41,26 +78,65 @@ export declare function cleanPath(path: string): string;
  * - Returned paths are cleaned with `cleanPath()` so runs of slashes and trailing slashes are removed.
  *
  * @param path 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`
+ * @param base Absolute path used for resolving relative paths in `path`.
+ * @param caller Function to attribute a thrown error to (defaults to `requirePath` itself).
+ * @returns Absolute path with a leading slash but no trailing slash, e.g. `/a/c/b`.
+ * @throws {RequiredError} If `path` is not a valid path.
+ * @example requirePath("./a", "/b") // "/b/a"
+ * @see https://dhoulb.github.io/shelving/util/path/requirePath
  */
 export declare function requirePath(path: PossiblePath, base?: AbsolutePath, caller?: AnyCaller): AbsolutePath;
 /**
  * Match and strip a base path prefix from a path using segment-aware pathname rules.
  * - Both inputs must be absolute paths that begin with `/`.
  * - Returns `/` when the paths are an exact match.
+ *
+ * @param target Path to match against `base` — relative paths resolve against `base`.
+ * @param base Base path whose prefix is stripped from `target`.
+ * @param caller Function to attribute a thrown error to (defaults to `matchPathPrefix` itself).
+ * @returns The remaining absolute path after stripping `base`, `/` for an exact match, or `undefined` if `target` is not under `base`.
+ * @throws {RequiredError} If `target` or `base` is not a valid path.
+ * @example matchPathPrefix("/a/b", "/a") // "/b"
+ * @see https://dhoulb.github.io/shelving/util/path/matchPathPrefix
  */
 export declare function matchPathPrefix(target: PossiblePath, base: PossiblePath, caller?: AnyCaller): AbsolutePath | undefined;
-/** Is a target path active? */
+/**
+ * Is a target path active relative to the current path?
+ * - Active means `target` and `current` are exactly the same path.
+ *
+ * @param target Path whose status to test.
+ * @param current Current path to test against.
+ * @returns `true` if `target` is exactly `current`.
+ * @example isPathActive("/a", "/a") // true
+ * @see https://dhoulb.github.io/shelving/util/path/isPathActive
+ */
 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)? */
+/**
+ * Is a target path proud relative to the current path?
+ * - Proud means `target` is the current path, or is an ancestor of the current path.
+ *
+ * @param target Path whose status to test.
+ * @param current Current path to test against.
+ * @returns `true` if `current` is `target` or a descendant of `target`.
+ * @example isPathProud("/a", "/a/b") // true
+ * @see https://dhoulb.github.io/shelving/util/path/isPathProud
+ */
 export declare function isPathProud(target: AbsolutePath, current: AbsolutePath): boolean;
 /**
  * Get the "segments" in an absolute path.
  * - `splitPath("/")` returns `[]` — the root has no segments.
+ *
+ * @param path Path to split (an array of segments is returned as-is).
+ * @returns Array of path segments.
+ * @example splitPath("/a/b") // ["a", "b"]
+ * @see https://dhoulb.github.io/shelving/util/path/splitPath
  */
 export declare function splitPath(path: PossiblePath): readonly string[];
-/** A single argument accepted by `joinPath()` — either a string (full path or single segment) or an array of segments. */
+/**
+ * A single argument accepted by `joinPath()` — either a string (full path or single segment) or an array of segments.
+ *
+ * @see https://dhoulb.github.io/shelving/util/path/PathPart
+ */
 export type PathPart = string | readonly string[];
 /**
  * Join one or more path parts into a single path string.

package/util/path.js

@@ -3,11 +3,25 @@
  */
 import { RequiredError } from "../error/RequiredError.js";
 import { isNullish, splitString } from "./index.js";
-/** Is a string path an absolute path? */
+/**
+ * Is a string path an absolute path?
+ *
+ * @param path The path to test.
+ * @returns `true` if `path` is an `AbsolutePath` starting with `/`, narrowing its type.
+ * @example isAbsolutePath("/a/b") // true
+ * @see https://dhoulb.github.io/shelving/util/path/isAbsolutePath
+ */
 export function isAbsolutePath(path) {
     return typeof path === "string" && path.startsWith("/");
 }
-/** Is a string path an relative path? */
+/**
+ * Is a string path a relative path?
+ *
+ * @param path The path to test.
+ * @returns `true` if `path` is a `RelativePath` (`.` or starting with `./`), narrowing its type.
+ * @example isRelativePath("./a") // true
+ * @see https://dhoulb.github.io/shelving/util/path/isRelativePath
+ */
 export function isRelativePath(path) {
     return typeof path === "string" && (path === "." || path.startsWith("./"));
 }
@@ -17,9 +31,11 @@ export function isRelativePath(path) {
  * - Normalises `\` windows paths.
  * - Strips trailing slashes.
  *
- * @param path 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 slash but no trailing slash, e.g. `/a/c/b`
+ * @param inputPath 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 inputBase Absolute path used for resolving relative paths in `inputPath`.
+ * @returns Absolute path with a leading slash but no trailing slash, e.g. `/a/c/b`, or `undefined` if `inputPath` is not a valid path.
+ * @example getPath("./a", "/b") // "/b/a"
+ * @see https://dhoulb.github.io/shelving/util/path/getPath
  */
 export function getPath(inputPath, inputBase = "/") {
     if (isNullish(inputPath))
@@ -38,8 +54,12 @@ export function cleanPath(path) {
  * - Returned paths are cleaned with `cleanPath()` so runs of slashes and trailing slashes are removed.
  *
  * @param path 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`
+ * @param base Absolute path used for resolving relative paths in `path`.
+ * @param caller Function to attribute a thrown error to (defaults to `requirePath` itself).
+ * @returns Absolute path with a leading slash but no trailing slash, e.g. `/a/c/b`.
+ * @throws {RequiredError} If `path` is not a valid path.
+ * @example requirePath("./a", "/b") // "/b/a"
+ * @see https://dhoulb.github.io/shelving/util/path/requirePath
  */
 export function requirePath(path, base, caller = requirePath) {
     const output = getPath(path, base);
@@ -51,6 +71,14 @@ export function requirePath(path, base, caller = requirePath) {
  * Match and strip a base path prefix from a path using segment-aware pathname rules.
  * - Both inputs must be absolute paths that begin with `/`.
  * - Returns `/` when the paths are an exact match.
+ *
+ * @param target Path to match against `base` — relative paths resolve against `base`.
+ * @param base Base path whose prefix is stripped from `target`.
+ * @param caller Function to attribute a thrown error to (defaults to `matchPathPrefix` itself).
+ * @returns The remaining absolute path after stripping `base`, `/` for an exact match, or `undefined` if `target` is not under `base`.
+ * @throws {RequiredError} If `target` or `base` is not a valid path.
+ * @example matchPathPrefix("/a/b", "/a") // "/b"
+ * @see https://dhoulb.github.io/shelving/util/path/matchPathPrefix
  */
 export function matchPathPrefix(target, base, caller = matchPathPrefix) {
     const basePath = requirePath(base, undefined, caller);
@@ -62,17 +90,40 @@ export function matchPathPrefix(target, base, caller = matchPathPrefix) {
     if (targetPath.startsWith(`${basePath}/`))
         return targetPath.slice(basePath.length);
 }
-/** Is a target path active? */
+/**
+ * Is a target path active relative to the current path?
+ * - Active means `target` and `current` are exactly the same path.
+ *
+ * @param target Path whose status to test.
+ * @param current Current path to test against.
+ * @returns `true` if `target` is exactly `current`.
+ * @example isPathActive("/a", "/a") // true
+ * @see https://dhoulb.github.io/shelving/util/path/isPathActive
+ */
 export function isPathActive(target, current) {
     return target === current;
 }
-/** Is a target path proud (i.e. is the current path, or is a child of the current path)? */
+/**
+ * Is a target path proud relative to the current path?
+ * - Proud means `target` is the current path, or is an ancestor of the current path.
+ *
+ * @param target Path whose status to test.
+ * @param current Current path to test against.
+ * @returns `true` if `current` is `target` or a descendant of `target`.
+ * @example isPathProud("/a", "/a/b") // true
+ * @see https://dhoulb.github.io/shelving/util/path/isPathProud
+ */
 export function isPathProud(target, current) {
     return target === current || (target !== "/" && target.startsWith(`${current}/`));
 }
 /**
  * Get the "segments" in an absolute path.
  * - `splitPath("/")` returns `[]` — the root has no segments.
+ *
+ * @param path Path to split (an array of segments is returned as-is).
+ * @returns Array of path segments.
+ * @example splitPath("/a/b") // ["a", "b"]
+ * @see https://dhoulb.github.io/shelving/util/path/splitPath
  */
 export function splitPath(path) {
     if (typeof path !== "string")

package/util/query.d.ts

@@ -1,7 +1,14 @@
 import type { ImmutableArray } from "./array.js";
 import type { Data, LeafData, LeafDataPath } from "./data.js";
 import type { Segments } from "./string.js";
-/** Query that can be applied to a list of data objects. */
+/**
+ * Query that can be applied to a list of data objects.
+ *
+ * - Keys encode filters: `key` (is), `!key` (not), arrays for in/out, `key<`/`key<=`/`key>`/`key>=` for ranges, and `key[]` for array contains.
+ * - `$order` sets the sort order (prefix `!` for descending) and `$limit` caps the number of results.
+ *
+ * @see https://dhoulb.github.io/shelving/util/query/Query
+ */
 export type Query<T extends Data = Data> = {
     readonly [K in LeafDataPath<T> as `${K}` | `!${K}`]?: LeafData<T>[K] | ImmutableArray<LeafData<T>[K]> | undefined;
 } & {
@@ -12,7 +19,13 @@ export type Query<T extends Data = Data> = {
     readonly $order?: `${LeafDataPath<T>}` | `!${LeafDataPath<T>}` | undefined | ImmutableArray<`${LeafDataPath<T>}` | `!${LeafDataPath<T>}` | undefined>;
     readonly $limit?: number | undefined;
 };
-/** A single filter that can be applied to a list of data objects. */
+/**
+ * A single filter that can be applied to a list of data objects.
+ *
+ * - Discriminated by `operator`: `"is"`, `"not"`, `"in"`, `"out"`, `"contains"`, `"lt"`, `"lte"`, `"gt"`, or `"gte"`.
+ *
+ * @see https://dhoulb.github.io/shelving/util/query/QueryFilter
+ */
 export type QueryFilter = {
     key: Segments;
     operator: "is";
@@ -50,27 +63,83 @@ export type QueryFilter = {
     operator: "gte";
     value: unknown;
 };
-/** A single sort order that can be applied to a list of data objects. */
+/**
+ * A single sort order that can be applied to a list of data objects.
+ *
+ * @see https://dhoulb.github.io/shelving/util/query/QueryOrder
+ */
 export type QueryOrder = {
     key: Segments;
     direction: "asc" | "desc";
 };
-/** Get the `Filter` objects for a query. */
+/**
+ * Get the `QueryFilter` objects decoded from a query.
+ *
+ * @param query The query to extract filters from.
+ * @returns Array of decoded `QueryFilter` objects (excludes `$order` and `$limit` and any `undefined` values).
+ * @example getQueryFilters({ name: "Alice" }) // [{ key: ["name"], operator: "is", value: "Alice" }]
+ * @see https://dhoulb.github.io/shelving/util/query/getQueryFilters
+ */
 export declare function getQueryFilters<T extends Data>(query: Query<T>): ImmutableArray<QueryFilter>;
-/** Get the `Order` objects for a query. */
+/**
+ * Get the `QueryOrder` objects decoded from a query.
+ *
+ * @param query The query to extract sort orders from (reads its `$order` prop).
+ * @returns Array of decoded `QueryOrder` objects (`!`-prefixed keys are descending, others ascending).
+ * @example getQueryOrders({ $order: "!date" }) // [{ key: ["date"], direction: "desc" }]
+ * @see https://dhoulb.github.io/shelving/util/query/getQueryOrders
+ */
 export declare function getQueryOrders<T extends Data>({ $order }: Query<T>): ImmutableArray<QueryOrder>;
-/** Get the limit for a query. */
+/**
+ * Get the limit for a query.
+ *
+ * @param query The query to read the limit from (reads its `$limit` prop).
+ * @returns The maximum number of results, or `undefined` if the query is unlimited.
+ * @example getQueryLimit({ $limit: 10 }) // 10
+ * @see https://dhoulb.github.io/shelving/util/query/getQueryLimit
+ */
 export declare function getQueryLimit<T extends Data>({ $limit }: Query<T>): number | undefined;
-/** Query a set of data items using a query. */
+/**
+ * Query a set of data items using a query.
+ * - Filters, then sorts, then limits the items according to the query.
+ *
+ * @param items The iterable of data items to query.
+ * @param query The query to apply (filters, sort order, and limit).
+ * @returns Iterable of items matching the query, in sorted and limited order.
+ * @example Array.from(queryItems(items, { name: "Alice", $limit: 1 })) // matching items
+ * @see https://dhoulb.github.io/shelving/util/query/queryItems
+ */
 export declare function queryItems<T extends Data>(items: Iterable<T>, query: Query<T>): Iterable<T>;
 /**
  * Query a set of data items for writing using a query.
  * - If no limit is set on the data sorting can be avoided too for performance reasons.
+ *
+ * @param items The iterable of data items to query.
+ * @param query The query to apply (filters, sort order, and limit).
+ * @returns Iterable of matching items (skips sorting when the query has no limit).
+ * @example Array.from(queryWritableItems(items, { name: "Alice" })) // matching items (unsorted)
+ * @see https://dhoulb.github.io/shelving/util/query/queryWritableItems
  */
 export declare function queryWritableItems<T extends Data>(items: Iterable<T>, query: Query<T>): Iterable<T>;
-/** Match a single data item againt a set of filters. */
+/**
+ * Match a single data item against a set of filters.
+ *
+ * @param item The data item to test.
+ * @param filters The set of filters that the item must satisfy.
+ * @returns `true` if the item matches every filter, `false` otherwise.
+ * @example matchQueryItem({ name: "Alice" }, [{ key: ["name"], operator: "is", value: "Alice" }]) // true
+ * @see https://dhoulb.github.io/shelving/util/query/matchQueryItem
+ */
 export declare function matchQueryItem<T extends Data>(item: T, filters: ImmutableArray<QueryFilter>): boolean;
-/**  Filter a set of data items using a set of filters. */
+/**
+ * Filter a set of data items using a set of filters.
+ *
+ * @param items The iterable of data items to filter.
+ * @param filters The set of filters that each yielded item must satisfy.
+ * @yields Items that match every filter (yields all items when `filters` is empty).
+ * @example Array.from(filterQueryItems(items, filters)) // matching items
+ * @see https://dhoulb.github.io/shelving/util/query/filterQueryItems
+ */
 export declare function filterQueryItems<T extends Data>(items: Iterable<T>, filters: ImmutableArray<QueryFilter>): Iterable<T>;
 /** Compare two data items using a set of orders. */
 export declare function compareQueryItems<T extends Data>(left: T, right: T, orders: ImmutableArray<QueryOrder>): number;

package/util/query.js

@@ -16,7 +16,14 @@ const MATCHERS = {
     gt: isGreater,
     gte: isEqualGreater,
 };
-/** Get the `Filter` objects for a query. */
+/**
+ * Get the `QueryFilter` objects decoded from a query.
+ *
+ * @param query The query to extract filters from.
+ * @returns Array of decoded `QueryFilter` objects (excludes `$order` and `$limit` and any `undefined` values).
+ * @example getQueryFilters({ name: "Alice" }) // [{ key: ["name"], operator: "is", value: "Alice" }]
+ * @see https://dhoulb.github.io/shelving/util/query/getQueryFilters
+ */
 export function getQueryFilters(query) {
     return Array.from(yieldQueryFilters(query));
 }
@@ -42,7 +49,14 @@ function* yieldQueryFilters(query) {
             yield isArray(value) ? { key: splitDataPath(key), operator: "in", value } : { key: splitDataPath(key), operator: "is", value };
     }
 }
-/** Get the `Order` objects for a query. */
+/**
+ * Get the `QueryOrder` objects decoded from a query.
+ *
+ * @param query The query to extract sort orders from (reads its `$order` prop).
+ * @returns Array of decoded `QueryOrder` objects (`!`-prefixed keys are descending, others ascending).
+ * @example getQueryOrders({ $order: "!date" }) // [{ key: ["date"], direction: "desc" }]
+ * @see https://dhoulb.github.io/shelving/util/query/getQueryOrders
+ */
 export function getQueryOrders({ $order }) {
     return Array.from(yieldQueryOrders($order));
 }
@@ -56,22 +70,52 @@ function* yieldQueryOrders(order) {
             yield { key: splitDataPath(key), direction: "asc" };
     }
 }
-/** Get the limit for a query. */
+/**
+ * Get the limit for a query.
+ *
+ * @param query The query to read the limit from (reads its `$limit` prop).
+ * @returns The maximum number of results, or `undefined` if the query is unlimited.
+ * @example getQueryLimit({ $limit: 10 }) // 10
+ * @see https://dhoulb.github.io/shelving/util/query/getQueryLimit
+ */
 export function getQueryLimit({ $limit }) {
     return $limit;
 }
-/** Query a set of data items using a query. */
+/**
+ * Query a set of data items using a query.
+ * - Filters, then sorts, then limits the items according to the query.
+ *
+ * @param items The iterable of data items to query.
+ * @param query The query to apply (filters, sort order, and limit).
+ * @returns Iterable of items matching the query, in sorted and limited order.
+ * @example Array.from(queryItems(items, { name: "Alice", $limit: 1 })) // matching items
+ * @see https://dhoulb.github.io/shelving/util/query/queryItems
+ */
 export function queryItems(items, query) {
     return limitQueryItems(sortQueryItems(filterQueryItems(items, getQueryFilters(query)), getQueryOrders(query)), getQueryLimit(query));
 }
 /**
  * Query a set of data items for writing using a query.
  * - If no limit is set on the data sorting can be avoided too for performance reasons.
+ *
+ * @param items The iterable of data items to query.
+ * @param query The query to apply (filters, sort order, and limit).
+ * @returns Iterable of matching items (skips sorting when the query has no limit).
+ * @example Array.from(queryWritableItems(items, { name: "Alice" })) // matching items (unsorted)
+ * @see https://dhoulb.github.io/shelving/util/query/queryWritableItems
  */
 export function queryWritableItems(items, query) {
     return getQueryLimit(query) === undefined ? filterQueryItems(items, getQueryFilters(query)) : queryItems(items, query);
 }
-/** Match a single data item againt a set of filters. */
+/**
+ * Match a single data item against a set of filters.
+ *
+ * @param item The data item to test.
+ * @param filters The set of filters that the item must satisfy.
+ * @returns `true` if the item matches every filter, `false` otherwise.
+ * @example matchQueryItem({ name: "Alice" }, [{ key: ["name"], operator: "is", value: "Alice" }]) // true
+ * @see https://dhoulb.github.io/shelving/util/query/matchQueryItem
+ */
 export function matchQueryItem(item, filters) {
     for (const { key, operator, value } of filters) {
         const matcher = MATCHERS[operator];
@@ -80,7 +124,15 @@ export function matchQueryItem(item, filters) {
     }
     return true;
 }
-/**  Filter a set of data items using a set of filters. */
+/**
+ * Filter a set of data items using a set of filters.
+ *
+ * @param items The iterable of data items to filter.
+ * @param filters The set of filters that each yielded item must satisfy.
+ * @yields Items that match every filter (yields all items when `filters` is empty).
+ * @example Array.from(filterQueryItems(items, filters)) // matching items
+ * @see https://dhoulb.github.io/shelving/util/query/filterQueryItems
+ */
 export function* filterQueryItems(items, filters) {
     if (filters.length) {
         for (const item of items)

package/util/random.d.ts

@@ -1,16 +1,79 @@
 import type { ImmutableArray } from "./array.js";
-/** Generate a random integer between two numbers. */
+/**
+ * Generate a random integer between two numbers (inclusive).
+ *
+ * @param min Lowest possible integer to return — defaults to `Number.MIN_SAFE_INTEGER`.
+ * @param max Highest possible integer to return — defaults to `Number.MAX_SAFE_INTEGER`.
+ * @returns Random integer in the range `min` to `max` (inclusive).
+ *
+ * @example
+ * ```ts
+ * const dice = getRandom(1, 6); // e.g. `4`
+ * ```
+ *
+ * @see https://dhoulb.github.io/shelving/util/random/getRandom
+ */
 export declare function getRandom(min?: number, max?: number): number;
-/** Get a random number that is anything except an existing number. */
+/**
+ * Get a random integer that is anything except an existing number.
+ * - Repeatedly draws a random integer until it differs from `existing`.
+ *
+ * @param existing Number that must not be returned.
+ * @param min Lowest possible integer to return — defaults to `Number.MIN_SAFE_INTEGER`.
+ * @param max Highest possible integer to return — defaults to `Number.MAX_SAFE_INTEGER`.
+ * @returns Random integer in the range `min` to `max` that is not equal to `existing`.
+ *
+ * @example
+ * ```ts
+ * const next = getRandomExcept(current, 1, 6); // any of `1`–`6` except `current`
+ * ```
+ *
+ * @see https://dhoulb.github.io/shelving/util/random/getRandomExcept
+ */
 export declare function getRandomExcept(existing: number, min?: number, max?: number): number;
 /**
  * Make a random key, e.g. `xs23r34hhsdx` or `e4m29klrugef`
  * - Not designed to be cryptographically random!
  * - Will probably clash — if you're making a random ID, check for existence of the record before saving.
  * - Designed to be semi-readable, doesn't use capital letters or `i` or `o` or `l` or `u`
+ *
+ * @param length Number of characters in the returned key — defaults to `12`.
+ * @returns Random string of `length` lowercase alphanumeric characters.
+ *
+ * @example
+ * ```ts
+ * const id = getRandomKey(); // e.g. `xs23r34hhsdx`
+ * ```
+ *
+ * @see https://dhoulb.github.io/shelving/util/random/getRandomKey
  */
 export declare function getRandomKey(length?: number): string;
-/** Get a random character from a string. */
+/**
+ * Get a random character from a string.
+ *
+ * @param str String to pick a character from.
+ * @returns Single character chosen at random from `str`.
+ *
+ * @example
+ * ```ts
+ * const letter = getRandomCharacter("abcde"); // e.g. `"c"`
+ * ```
+ *
+ * @see https://dhoulb.github.io/shelving/util/random/getRandomCharacter
+ */
 export declare function getRandomCharacter(str: string): string;
-/** Get a random item from an array or random character from a string string. */
+/**
+ * Get a random item from an array.
+ *
+ * @param arr Array to pick an item from.
+ * @returns Single item chosen at random from `arr`.
+ * @throws RequiredError If the chosen item is undefined (e.g. the array is empty).
+ *
+ * @example
+ * ```ts
+ * const item = getRandomItem(["a", "b", "c"]); // e.g. `"b"`
+ * ```
+ *
+ * @see https://dhoulb.github.io/shelving/util/random/getRandomItem
+ */
 export declare function getRandomItem<T>(arr: ImmutableArray<T>): T;