shelving 1.236.0 → 1.236.2

package/util/equal.js

@@ -3,37 +3,103 @@ import { isArray } from "./array.js";
 import { isMap } from "./map.js";
 import { isObject, isProp } from "./object.js";
 import { compareAscending } from "./sort.js";
-/** Assert two values are equal. */
+/**
+ * Assert that two values are exactly (referentially) equal, narrowing `left` to the type of `right`.
+ *
+ * @param left The value to check and narrow.
+ * @param right The value `left` must equal.
+ * @param caller Function to attribute a thrown error to (defaults to `assertEqual`).
+ * @throws {RequiredError} If the values are not equal.
+ * @example assertEqual(1, 1); // passes
+ * @see https://dhoulb.github.io/shelving/util/equal/assertEqual
+ */
 export function assertEqual(left, right, caller = assertEqual) {
     if (left !== right)
         new RequiredError("Must be equal", { left, right, caller });
 }
-/** Assert two values are equal. */
+/**
+ * Assert that two values are not equal, narrowing `left` to exclude the type of `right`.
+ *
+ * @param left The value to check and narrow.
+ * @param right The value `left` must not equal.
+ * @param caller Function to attribute a thrown error to (defaults to `assertNot`).
+ * @throws {RequiredError} If the values are equal.
+ * @example assertNot(1, 2); // passes
+ * @see https://dhoulb.github.io/shelving/util/equal/assertNot
+ */
 export function assertNot(left, right, caller = assertNot) {
     if (left === right)
         new RequiredError("Must not be equal", { left, right, caller });
 }
-/** Is unknown value `left` exactly equal to `right`? */
+/**
+ * Is unknown value `left` exactly (referentially) equal to `right`?
+ *
+ * @param left The value to check and narrow.
+ * @param right The value to compare against.
+ * @returns `true` if the values are strictly equal.
+ * @example isEqual(1, 1) // true
+ * @see https://dhoulb.github.io/shelving/util/equal/isEqual
+ */
 export function isEqual(left, right) {
     return left === right;
 }
-/** Is unknown value `left` not exactly equal to `right`? */
+/**
+ * Is unknown value `left` not exactly (referentially) equal to `right`?
+ *
+ * @param left The value to check and narrow.
+ * @param right The value to compare against.
+ * @returns `true` if the values are not strictly equal.
+ * @example notEqual(1, 2) // true
+ * @see https://dhoulb.github.io/shelving/util/equal/notEqual
+ */
 export function notEqual(left, right) {
     return left !== right;
 }
-/** Is unknown value `left` less than `right`? */
+/**
+ * Is unknown value `left` less than `right` (using `compareAscending`)?
+ *
+ * @param left The value to compare.
+ * @param right The value to compare against.
+ * @returns `true` if `left` sorts before `right`.
+ * @example isLess(1, 2) // true
+ * @see https://dhoulb.github.io/shelving/util/equal/isLess
+ */
 export function isLess(left, right) {
     return compareAscending(left, right) < 0;
 }
-/** Is unknown value `left` less than or equal to `right`? */
+/**
+ * Is unknown value `left` less than or equal to `right` (using `compareAscending`)?
+ *
+ * @param left The value to compare.
+ * @param right The value to compare against.
+ * @returns `true` if `left` sorts before or equal to `right`.
+ * @example isEqualLess(2, 2) // true
+ * @see https://dhoulb.github.io/shelving/util/equal/isEqualLess
+ */
 export function isEqualLess(left, right) {
     return compareAscending(left, right) <= 0;
 }
-/** Is unknown value `left` greater than `right`? */
+/**
+ * Is unknown value `left` greater than `right` (using `compareAscending`)?
+ *
+ * @param left The value to compare.
+ * @param right The value to compare against.
+ * @returns `true` if `left` sorts after `right`.
+ * @example isGreater(2, 1) // true
+ * @see https://dhoulb.github.io/shelving/util/equal/isGreater
+ */
 export function isGreater(left, right) {
     return compareAscending(left, right) > 0;
 }
-/** Is unknown value `left` greater than or equal to `right`? */
+/**
+ * Is unknown value `left` greater than or equal to `right` (using `compareAscending`)?
+ *
+ * @param left The value to compare.
+ * @param right The value to compare against.
+ * @returns `true` if `left` sorts after or equal to `right`.
+ * @example isEqualGreater(2, 2) // true
+ * @see https://dhoulb.github.io/shelving/util/equal/isEqualGreater
+ */
 export function isEqualGreater(left, right) {
     return compareAscending(left, right) >= 0;
 }
@@ -53,27 +119,62 @@ function _isEqualRecursively(left, right, recursor) {
 /**
  * Are two unknown values shallowly equal?
  * - If the values are both arrays/objects, see if the items/properties are **shallowly** equal with each other.
+ *
+ * @param left The value to check and narrow.
+ * @param right The value to compare against.
+ * @returns `true` if the values are shallowly equal.
+ * @example isShallowEqual({ a: 1 }, { a: 1 }) // true
+ * @see https://dhoulb.github.io/shelving/util/equal/isShallowEqual
  */
 export function isShallowEqual(left, right) {
     return _isEqualRecursively(left, right, isEqual);
 }
-/** Are two unknown values not shallowly equal? */
+/**
+ * Are two unknown values not shallowly equal?
+ *
+ * @param left The value to check and narrow.
+ * @param right The value to compare against.
+ * @returns `true` if the values are not shallowly equal.
+ * @example notShallowEqual({ a: 1 }, { a: 2 }) // true
+ * @see https://dhoulb.github.io/shelving/util/equal/notShallowEqual
+ */
 export function notShallowEqual(left, right) {
     return !isShallowEqual(left, right);
 }
 /**
  * Are two unknown values deeply equal?
  * - If the values are both arrays/objects, see if the items/properties are **deeply** equal with each other.
+ *
+ * @param left The value to check and narrow.
+ * @param right The value to compare against.
+ * @returns `true` if the values are deeply equal.
+ * @example isDeepEqual({ a: { b: 1 } }, { a: { b: 1 } }) // true
+ * @see https://dhoulb.github.io/shelving/util/equal/isDeepEqual
  */
 export function isDeepEqual(left, right) {
     return _isEqualRecursively(left, right, isDeepEqual);
 }
-/** Are two unknown values not deeply equal? */
+/**
+ * Are two unknown values not deeply equal?
+ *
+ * @param left The value to check and narrow.
+ * @param right The value to compare against.
+ * @returns `true` if the values are not deeply equal.
+ * @example notDeepEqual({ a: { b: 1 } }, { a: { b: 2 } }) // true
+ * @see https://dhoulb.github.io/shelving/util/equal/notDeepEqual
+ */
 export function notDeepEqual(left, right) {
     return !isShallowEqual(left, right);
 }
 /**
- * Are two maps equal (based on their items).
+ * Are two maps equal based on their items?
+ *
+ * @param left The map to check and narrow.
+ * @param right The map to compare against.
+ * @param recursor Function that checks each value of the map (defaults to `isEqual` for strict equality; pass `isDeepEqual` for deep equality).
+ * @returns `true` if both maps have the same keys and matching values.
+ * @example isMapEqual(new Map([["a", 1]]), new Map([["a", 1]])) // true
+ * @see https://dhoulb.github.io/shelving/util/equal/isMapEqual
  */
 export function isMapEqual(left, right, recursor = isEqual) {
     if (left === right)
@@ -93,9 +194,14 @@ export function isMapEqual(left, right, recursor = isEqual) {
 /**
  * Are two arrays equal based on their items?
  *
+ * @param left The array to check and narrow.
+ * @param right The array to compare against.
  * @param recursor Function that checks each item of the array.
  * - Defaults to `isEqual()` to check strict equality of the items.
  * - Use `isDeepEqual()` as the recursor to check to check deep equality of the items.
+ * @returns `true` if both arrays have the same length and matching items.
+ * @example isArrayEqual([1, 2], [1, 2]) // true
+ * @see https://dhoulb.github.io/shelving/util/equal/isArrayEqual
  */
 export function isArrayEqual(left, right, recursor = isEqual) {
     if (left === right)
@@ -107,19 +213,51 @@ export function isArrayEqual(left, right, recursor = isEqual) {
             return false;
     return true;
 }
-/** Is unknown value `left` in array `right`? */
+/**
+ * Is unknown value `left` in array `right`?
+ *
+ * @param left The value to look for and narrow.
+ * @param right The array to search within.
+ * @returns `true` if `left` is an item of `right`.
+ * @example isInArray(2, [1, 2, 3]) // true
+ * @see https://dhoulb.github.io/shelving/util/equal/isInArray
+ */
 export function isInArray(left, right) {
     return right.includes(left);
 }
-/** Is unknown value `left` not in array `right`? */
+/**
+ * Is unknown value `left` not in array `right`?
+ *
+ * @param left The value to look for.
+ * @param right The array to search within.
+ * @returns `true` if `left` is not an item of `right`.
+ * @example notInArray(9, [1, 2, 3]) // true
+ * @see https://dhoulb.github.io/shelving/util/equal/notInArray
+ */
 export function notInArray(left, right) {
     return !isInArray(left, right);
 }
-/** Is unknown value `left` an array including `right`? */
+/**
+ * Is unknown value `left` an array that includes `right`?
+ *
+ * @param left The value to check and narrow.
+ * @param right The item the array must include.
+ * @returns `true` if `left` is an array containing `right`.
+ * @example isArrayWith([1, 2, 3], 2) // true
+ * @see https://dhoulb.github.io/shelving/util/equal/isArrayWith
+ */
 export function isArrayWith(left, right) {
     return isArray(left) && left.includes(right);
 }
-/** Is unknown value `left` not an array or does not include `right`? */
+/**
+ * Is unknown value `left` not an array, or an array that does not include `right`?
+ *
+ * @param left The value to check.
+ * @param right The item the array must include.
+ * @returns `true` if `left` is not an array or does not include `right`.
+ * @example notArrayWith([1, 2, 3], 9) // true
+ * @see https://dhoulb.github.io/shelving/util/equal/notArrayWith
+ */
 export function notArrayWith(left, right) {
     return !isArrayWith(left, right);
 }
@@ -128,9 +266,14 @@ export function notArrayWith(left, right) {
  * - `left` must have every property present in `right`
  * - `left` must not have excess properties not present in `right`
  *
+ * @param left The object to check and narrow.
+ * @param right The object to compare against.
  * @param recursor Function that checks each prop of the object.
  * - Defaults to `isEqual()` to check strict equality of the properties.
  * - Use `isDeepEqual()` as the recursor to check to check deep equality of the properties.
+ * @returns `true` if both objects have exactly the same own props and matching values.
+ * @example isObjectEqual({ a: 1 }, { a: 1 }) // true
+ * @see https://dhoulb.github.io/shelving/util/equal/isObjectEqual
  */
 export function isObjectEqual(left, right, recursor = isEqual) {
     if (left === right)
@@ -149,9 +292,14 @@ export function isObjectEqual(left, right, recursor = isEqual) {
  * - `left` must have every property present in `right`
  * - `left` may have have excess properties not present in `right`
  *
+ * @param left The object to check and narrow.
+ * @param right The object whose props `left` must contain.
  * @param recursor Function that checks each prop of the object.
  * - Defaults to `isEqual()` to check strict equality of the properties.
  * - Use `isDeepEqual()` as the recursor to check to check deep equality of the properties.
+ * @returns `true` if `left` contains every prop of `right` with matching values.
+ * @example isObjectMatch({ a: 1, b: 2 }, { a: 1 }) // true
+ * @see https://dhoulb.github.io/shelving/util/equal/isObjectMatch
  */
 export function isObjectMatch(left, right, recursor = isEqual) {
     if (left === right)
@@ -162,11 +310,27 @@ export function isObjectMatch(left, right, recursor = isEqual) {
             return false;
     return true;
 }
-/** Is unknown value `left` an object with every prop from `right`? */
+/**
+ * Is unknown value `left` an object with every prop from `right`?
+ *
+ * @param left The value to check.
+ * @param right The object whose props `left` must contain.
+ * @returns `true` if `left` is an object containing every prop of `right`.
+ * @example isObjectWith({ a: 1, b: 2 }, { a: 1 }) // true
+ * @see https://dhoulb.github.io/shelving/util/equal/isObjectWith
+ */
 export function isObjectWith(left, right) {
     return isObject(left) && isObjectMatch(left, right);
 }
-/** Is unknown value `left` not an object or missing one or more props from `right`? */
+/**
+ * Is unknown value `left` not an object or missing one or more props from `right`?
+ *
+ * @param left The value to check.
+ * @param right The object whose props `left` must contain.
+ * @returns `true` if `left` is not an object or is missing one or more props of `right`.
+ * @example notObjectWith({ a: 1 }, { b: 2 }) // true
+ * @see https://dhoulb.github.io/shelving/util/equal/notObjectWith
+ */
 export function notObjectWith(left, right) {
     return !isObjectWith(left, right);
 }

package/util/error.d.ts

@@ -1,24 +1,65 @@
 import type { ImmutableDictionary } from "./dictionary.js";
 import type { AnyCaller } from "./function.js";
-/** Log an error to the console. */
+/**
+ * Log an error to the console.
+ *
+ * @param reason The error (or any thrown value) to log.
+ * @returns Nothing.
+ * @example logError(new Error("Boom")) // logs to console.error
+ * @see https://dhoulb.github.io/shelving/util/error/logError
+ */
 export declare function logError(reason: unknown): void;
-/** Is an unknown value an `Error` instance? */
+/**
+ * Is an unknown value an `Error` instance?
+ * - Uses the native `Error.isError()` if available, otherwise falls back to `instanceof Error`.
+ *
+ * @param v The value to check and narrow.
+ * @returns `true` if `v` is an `Error` (narrowing it, with an optional `code` string).
+ * @see https://dhoulb.github.io/shelving/util/error/isError
+ */
 export declare function isError(v: unknown): v is Error & {
     readonly code?: string | undefined;
 };
-/** Things that can be a message. */
+/**
+ * Things that can be a message: a string, or an object with a `message` string property.
+ *
+ * @see https://dhoulb.github.io/shelving/util/error/PossibleMessage
+ */
 export type PossibleMessage = {
     message: string;
 } | string;
-/** Return the string message from an unknown value, or return `undefined` if it could not be found. */
+/**
+ * Return the string message from an unknown value, or return `undefined` if it could not be found.
+ *
+ * @param input The value to read a message from (a string, or an object with a `message` string).
+ * @returns The message string, or `undefined` if none could be found.
+ * @example getMessage(new Error("Boom")) // "Boom"
+ * @example getMessage(123) // undefined
+ * @see https://dhoulb.github.io/shelving/util/error/getMessage
+ */
 export declare function getMessage(input: unknown): string | undefined;
-/** Require a message from an unknown value, or throw `RequiredError` if it could not be found. */
+/**
+ * Require a message from an unknown value, or throw `RequiredError` if it could not be found.
+ *
+ * @param input The value to read a message from (a string, or an object with a `message` string).
+ * @param caller Function to attribute a thrown error to (defaults to `requireMessage`).
+ * @returns The message string.
+ * @throws `RequiredError` if no message could be found.
+ * @example requireMessage(new Error("Boom")) // "Boom"
+ * @see https://dhoulb.github.io/shelving/util/error/requireMessage
+ */
 export declare function requireMessage(input: PossibleMessage, caller?: AnyCaller): string;
 /**
  * Split a string message into lines, look for prefixes like `name:`, and return a dictionary of those named messages.
  * - Full messages strings can have multiple lines separated by `\n` newline.
  * - Named messages are extracted into their own entries in the dictionary.
  * - Unnamed messages are combined into a single entry with the key `""` (empty string).
+ *
+ * @param input The value to read a message from (a string, or an object with a `message` string).
+ * @returns Dictionary mapping each name (or `""` for unnamed lines) to its combined message.
+ * @throws `RequiredError` if no message could be found.
+ * @example splitMessage("name: Bad\nUh oh") // { name: "Bad", "": "Uh oh" }
+ * @see https://dhoulb.github.io/shelving/util/error/splitMessage
  */
 export declare function splitMessage(input: PossibleMessage): ImmutableDictionary<string>;
 /**
@@ -26,10 +67,21 @@ export declare function splitMessage(input: PossibleMessage): ImmutableDictionar
  * - The `""` (empty string) key is emitted as unnamed lines.
  * - Named messages are emitted as `name: message`, one line per message line.
  * - Empty lines are skipped and each emitted line is trimmed to match `splitMessage()` semantics.
+ *
+ * @param input Dictionary mapping each name (or `""` for unnamed lines) to its message.
+ * @returns The combined message string, with one line per message line.
+ * @example joinMessage({ name: "Bad", "": "Uh oh" }) // "name: Bad\nUh oh"
+ * @see https://dhoulb.github.io/shelving/util/error/joinMessage
  */
 export declare function joinMessage(input: ImmutableDictionary<string>): string;
 /**
  * Name a message by applying a `name: ` prefix to it.
  * - Assumes each line in the message is a separate error, so each line has the same prefix applied.
+ *
+ * @param name The name to prefix each line of the message with.
+ * @param message The message to prefix (may contain multiple `\n`-separated lines).
+ * @returns The message with `name: ` prefixed to every line.
+ * @example getNamedMessage("email", "Required\nInvalid") // "email: Required\nemail: Invalid"
+ * @see https://dhoulb.github.io/shelving/util/error/getNamedMessage
  */
 export declare function getNamedMessage(name: string | number, message: string): string;

package/util/error.js

@@ -1,18 +1,49 @@
 import { RequiredError } from "../error/RequiredError.js";
 import { isObject } from "./object.js";
-/** Log an error to the console. */
+/**
+ * Log an error to the console.
+ *
+ * @param reason The error (or any thrown value) to log.
+ * @returns Nothing.
+ * @example logError(new Error("Boom")) // logs to console.error
+ * @see https://dhoulb.github.io/shelving/util/error/logError
+ */
 export function logError(reason) {
     console.error(reason);
 }
-/** Is an unknown value an `Error` instance? */
+/**
+ * Is an unknown value an `Error` instance?
+ * - Uses the native `Error.isError()` if available, otherwise falls back to `instanceof Error`.
+ *
+ * @param v The value to check and narrow.
+ * @returns `true` if `v` is an `Error` (narrowing it, with an optional `code` string).
+ * @see https://dhoulb.github.io/shelving/util/error/isError
+ */
 export function isError(v) {
     return typeof Error.isError === "function" ? Error.isError(v) : v instanceof Error;
 }
-/** Return the string message from an unknown value, or return `undefined` if it could not be found. */
+/**
+ * Return the string message from an unknown value, or return `undefined` if it could not be found.
+ *
+ * @param input The value to read a message from (a string, or an object with a `message` string).
+ * @returns The message string, or `undefined` if none could be found.
+ * @example getMessage(new Error("Boom")) // "Boom"
+ * @example getMessage(123) // undefined
+ * @see https://dhoulb.github.io/shelving/util/error/getMessage
+ */
 export function getMessage(input) {
     return typeof input === "string" ? input : isObject(input) && typeof input.message === "string" ? input.message : undefined;
 }
-/** Require a message from an unknown value, or throw `RequiredError` if it could not be found. */
+/**
+ * Require a message from an unknown value, or throw `RequiredError` if it could not be found.
+ *
+ * @param input The value to read a message from (a string, or an object with a `message` string).
+ * @param caller Function to attribute a thrown error to (defaults to `requireMessage`).
+ * @returns The message string.
+ * @throws `RequiredError` if no message could be found.
+ * @example requireMessage(new Error("Boom")) // "Boom"
+ * @see https://dhoulb.github.io/shelving/util/error/requireMessage
+ */
 export function requireMessage(input, caller = requireMessage) {
     const message = getMessage(input);
     if (message === undefined)
@@ -24,6 +55,12 @@ export function requireMessage(input, caller = requireMessage) {
  * - Full messages strings can have multiple lines separated by `\n` newline.
  * - Named messages are extracted into their own entries in the dictionary.
  * - Unnamed messages are combined into a single entry with the key `""` (empty string).
+ *
+ * @param input The value to read a message from (a string, or an object with a `message` string).
+ * @returns Dictionary mapping each name (or `""` for unnamed lines) to its combined message.
+ * @throws `RequiredError` if no message could be found.
+ * @example splitMessage("name: Bad\nUh oh") // { name: "Bad", "": "Uh oh" }
+ * @see https://dhoulb.github.io/shelving/util/error/splitMessage
  */
 export function splitMessage(input) {
     const messages = requireMessage(input, splitMessage).split("\n");
@@ -57,6 +94,11 @@ export function splitMessage(input) {
  * - The `""` (empty string) key is emitted as unnamed lines.
  * - Named messages are emitted as `name: message`, one line per message line.
  * - Empty lines are skipped and each emitted line is trimmed to match `splitMessage()` semantics.
+ *
+ * @param input Dictionary mapping each name (or `""` for unnamed lines) to its message.
+ * @returns The combined message string, with one line per message line.
+ * @example joinMessage({ name: "Bad", "": "Uh oh" }) // "name: Bad\nUh oh"
+ * @see https://dhoulb.github.io/shelving/util/error/joinMessage
  */
 export function joinMessage(input) {
     const output = [];
@@ -73,6 +115,12 @@ export function joinMessage(input) {
 /**
  * Name a message by applying a `name: ` prefix to it.
  * - Assumes each line in the message is a separate error, so each line has the same prefix applied.
+ *
+ * @param name The name to prefix each line of the message with.
+ * @param message The message to prefix (may contain multiple `\n`-separated lines).
+ * @returns The message with `name: ` prefixed to every line.
+ * @example getNamedMessage("email", "Required\nInvalid") // "email: Required\nemail: Invalid"
+ * @see https://dhoulb.github.io/shelving/util/error/getNamedMessage
  */
 export function getNamedMessage(name, message) {
     return `${name}: ${message.split("\n").join(`\n${name}: `)}`;

package/util/file.d.ts

@@ -1,6 +1,10 @@
 import type { AnyCaller } from "./function.js";
 import type { Nullish } from "./null.js";
-/** List of file types in `extension: mime` format. */
+/**
+ * List of file types in `extension: mime` format.
+ *
+ * @see https://dhoulb.github.io/shelving/util/file/FileTypes
+ */
 export type FileTypes = {
     [extension: string]: string;
 };
@@ -9,13 +13,32 @@ export type FileTypes = {
  * - Extension with no leading dot, e.g. `"ts"`.
  * - Returns `undefined` for either part if the filename has no dot or starts with a dot only.
  *
- * @example `splitFileExtension("array.ts")` returns `["array", ".ts"]`
- * @example `splitFileExtension("no-ext")` returns `["no-ext", undefined]`
- * @example `splitFileExtension(".gitignore")` returns `[undefined, "gitignore"]`
- * @example `splitFileExtension(undefined)` returns `[undefined, undefined]`
+ * @param file The filename to split, or a nullish value (defaults to `""`).
+ * @returns A `[base, extension]` tuple, with `undefined` for either part that is absent.
+ * @example splitFileExtension("array.ts") // ["array", "ts"]
+ * @example splitFileExtension("no-ext") // ["no-ext", undefined]
+ * @example splitFileExtension(".gitignore") // [undefined, "gitignore"]
+ * @example splitFileExtension(undefined) // [undefined, undefined]
+ * @see https://dhoulb.github.io/shelving/util/file/splitFileExtension
  */
 export declare function splitFileExtension(file?: Nullish<string>): [base: string | undefined, extension: string | undefined];
-/** Get the file extension from a file path, e.g. `"md"`, or return `undefined` if the input has no extension. */
+/**
+ * Get the file extension from a file path, e.g. `"md"`, or return `undefined` if the input has no extension.
+ *
+ * @param file The filename to read the extension from, or a nullish value.
+ * @returns The extension (no leading dot), or `undefined` if the input has no extension.
+ * @example getFileExtension("readme.md") // "md"
+ * @see https://dhoulb.github.io/shelving/util/file/getFileExtension
+ */
 export declare function getFileExtension(file: Nullish<string>): string | undefined;
-/** Get the file extension from a file path e.g. `"tsx"`, or throw `RequiredError` if the input has no extension. */
+/**
+ * Get the file extension from a file path e.g. `"tsx"`, or throw `RequiredError` if the input has no extension.
+ *
+ * @param file The filename to read the extension from.
+ * @param caller Function to attribute a thrown error to (defaults to `requireFileExtension`).
+ * @returns The extension (no leading dot).
+ * @throws `RequiredError` if the input has no extension.
+ * @example requireFileExtension("component.tsx") // "tsx"
+ * @see https://dhoulb.github.io/shelving/util/file/requireFileExtension
+ */
 export declare function requireFileExtension(file: string, caller?: AnyCaller): string;

package/util/file.js

@@ -4,10 +4,13 @@ import { RequiredError } from "../error/RequiredError.js";
  * - Extension with no leading dot, e.g. `"ts"`.
  * - Returns `undefined` for either part if the filename has no dot or starts with a dot only.
  *
- * @example `splitFileExtension("array.ts")` returns `["array", ".ts"]`
- * @example `splitFileExtension("no-ext")` returns `["no-ext", undefined]`
- * @example `splitFileExtension(".gitignore")` returns `[undefined, "gitignore"]`
- * @example `splitFileExtension(undefined)` returns `[undefined, undefined]`
+ * @param file The filename to split, or a nullish value (defaults to `""`).
+ * @returns A `[base, extension]` tuple, with `undefined` for either part that is absent.
+ * @example splitFileExtension("array.ts") // ["array", "ts"]
+ * @example splitFileExtension("no-ext") // ["no-ext", undefined]
+ * @example splitFileExtension(".gitignore") // [undefined, "gitignore"]
+ * @example splitFileExtension(undefined) // [undefined, undefined]
+ * @see https://dhoulb.github.io/shelving/util/file/splitFileExtension
  */
 export function splitFileExtension(file = "") {
     if (!file)
@@ -17,11 +20,27 @@ export function splitFileExtension(file = "") {
         return [file, undefined];
     return [file.slice(0, i) || undefined, file.slice(i + 1) || undefined];
 }
-/** Get the file extension from a file path, e.g. `"md"`, or return `undefined` if the input has no extension. */
+/**
+ * Get the file extension from a file path, e.g. `"md"`, or return `undefined` if the input has no extension.
+ *
+ * @param file The filename to read the extension from, or a nullish value.
+ * @returns The extension (no leading dot), or `undefined` if the input has no extension.
+ * @example getFileExtension("readme.md") // "md"
+ * @see https://dhoulb.github.io/shelving/util/file/getFileExtension
+ */
 export function getFileExtension(file) {
     return splitFileExtension(file)[1];
 }
-/** Get the file extension from a file path e.g. `"tsx"`, or throw `RequiredError` if the input has no extension. */
+/**
+ * Get the file extension from a file path e.g. `"tsx"`, or throw `RequiredError` if the input has no extension.
+ *
+ * @param file The filename to read the extension from.
+ * @param caller Function to attribute a thrown error to (defaults to `requireFileExtension`).
+ * @returns The extension (no leading dot).
+ * @throws `RequiredError` if the input has no extension.
+ * @example requireFileExtension("component.tsx") // "tsx"
+ * @see https://dhoulb.github.io/shelving/util/file/requireFileExtension
+ */
 export function requireFileExtension(file, caller = requireFileExtension) {
     const extension = getFileExtension(file);
     if (!extension)

package/util/filter.d.ts

@@ -1,10 +1,42 @@
 import type { ImmutableArray } from "./array.js";
 import type { Arguments } from "./function.js";
-/** Function that can match an item against a target. */
+/**
+ * Function that can match an item against a target.
+ *
+ * @see https://dhoulb.github.io/shelving/util/filter/Match
+ */
 export type Match<A extends Arguments = unknown[]> = (...args: A) => boolean;
-/** Filter an iterable set of items using a matcher. */
+/**
+ * Filter an iterable set of items using a matcher.
+ *
+ * @param items Iterable of items to filter.
+ * @param match Matcher called with each item (plus any extra `args`); items it returns `true` for are kept.
+ * @param args Extra arguments passed to `match` after each item.
+ * @returns Iterable yielding only the items the matcher returned `true` for.
+ * @example Array.from(filterItems([1, 2, 3], n => n > 1)) // [2, 3]
+ * @see https://dhoulb.github.io/shelving/util/filter/filterItems
+ */
 export declare function filterItems<T, A extends Arguments = []>(items: Iterable<T>, match: Match<[T, ...A]>, ...args: A): Iterable<T>;
-/** Filter an array (immutably) using a matcher. */
+/**
+ * Filter an array (immutably) using a matcher.
+ * - Returns the exact same array instance if no items were removed (for referential stability).
+ *
+ * @param input Array of items to filter.
+ * @param match Matcher called with each item (plus any extra `args`); items it returns `true` for are kept.
+ * @param args Extra arguments passed to `match` after each item.
+ * @returns A filtered array, or the same `input` instance if nothing was removed.
+ * @example filterArray([1, 2, 3], n => n > 1) // [2, 3]
+ * @see https://dhoulb.github.io/shelving/util/filter/filterArray
+ */
 export declare function filterArray<T, A extends Arguments = []>(input: ImmutableArray<T>, match: Match<[T, ...A]>, ...args: A): ImmutableArray<T>;
-/** Filter a sequence of values using a matcher. */
+/**
+ * Filter a sequence of values using a matcher.
+ *
+ * @param sequence Async iterable of items to filter.
+ * @param match Matcher called with each item (plus any extra `args`); items it returns `true` for are kept.
+ * @param args Extra arguments passed to `match` after each item.
+ * @returns Async iterable yielding only the items the matcher returned `true` for.
+ * @example for await (const n of filterSequence(stream, n => n > 1)) { ... }
+ * @see https://dhoulb.github.io/shelving/util/filter/filterSequence
+ */
 export declare function filterSequence<T, A extends Arguments = []>(sequence: AsyncIterable<T>, match: Match, ...args: A): AsyncIterable<T>;