shelving 1.236.0 → 1.236.2

package/util/source.js

@@ -1,6 +1,15 @@
 import { RequiredError } from "../error/RequiredError.js";
 import { isObject } from "./object.js";
-/** Recurse through `Sourceable` objects and return the first one that is an instance of `type`, or `undefined` if no source object matches. */
+/**
+ * Recurse through `Sourceable` objects and return the first one that is an instance of `type`, or `undefined` if no source object matches.
+ * - Follows the `source` property chain (e.g. layered providers) until a matching instance is found.
+ *
+ * @param type The class to search for an instance of.
+ * @param value The object to start searching from.
+ * @returns The first matching source instance, or `undefined` if none matches.
+ * @example getSource(CacheProvider, provider) // CacheProvider instance or undefined
+ * @see https://dhoulb.github.io/shelving/util/source/getSource
+ */
 export function getSource(type, value) {
     if (isObject(value)) {
         if (value instanceof type)
@@ -9,7 +18,18 @@ export function getSource(type, value) {
             return getSource(type, value.source);
     }
 }
-/** Recurse through `Sourceable` objects and return the first one that is an instance of `type`, or throw `RequiredError` if no source object matches. */
+/**
+ * Recurse through `Sourceable` objects and return the first one that is an instance of `type`, or throw `RequiredError` if no source object matches.
+ * - Like `getSource`, but throws instead of returning `undefined` when no match is found.
+ *
+ * @param type The class to search for an instance of.
+ * @param data The object to start searching from.
+ * @param caller Function to attribute a thrown error to (defaults to `requireSource`).
+ * @returns The first matching source instance.
+ * @throws {RequiredError} If no source object is an instance of `type`.
+ * @example requireSource(CacheProvider, provider) // CacheProvider instance
+ * @see https://dhoulb.github.io/shelving/util/source/requireSource
+ */
 export function requireSource(type, data, caller = requireSource) {
     const source = getSource(type, data);
     if (!source)

package/util/start.d.ts

@@ -1,24 +1,81 @@
 import { type Arguments } from "./function.js";
-/** Callback function that starts something with multiple values and returns an optional stop callback. */
+/**
+ * Callback function that starts something with multiple values and returns an optional stop callback.
+ *
+ * @see https://dhoulb.github.io/shelving/util/start/StartCallback
+ */
 export type StartCallback<T extends Arguments = []> = (...values: T) => StopCallback | void;
-/** Callback function that stops something. */
+/**
+ * Callback function that stops something.
+ *
+ * @see https://dhoulb.github.io/shelving/util/start/StopCallback
+ */
 export type StopCallback = () => void;
-/** Callback function that does nothing and returns a blackhole stop callback. */
+/**
+ * Callback function that does nothing and returns a blackhole stop callback.
+ * - Useful as a no-op default where a `StartCallback` is expected.
+ *
+ * @example STOPHOLE() // BLACKHOLE
+ * @see https://dhoulb.github.io/shelving/util/start/STOPHOLE
+ */
 export declare const STOPHOLE: (...args: Arguments) => StopCallback;
 /**
  * Wrapper class to handle state on start/stop callback process.
  * - If process has already started, `starter.start()` won't be called twice (including if `start()` didn't return a `stop()` callback).
+ * - Implements `Disposable` so it can be used with `using`, calling `stop()` on disposal.
+ *
+ * @example
+ * const starter = new Starter(() => { console.log("start"); return () => console.log("stop"); });
+ * starter.start();
+ * starter.stop();
+ * @see https://dhoulb.github.io/shelving/util/start/Starter
  */
 export declare class Starter<T extends Arguments = []> implements Disposable {
     private readonly _start;
     private _started;
     private _stop;
+    /**
+     * Create a new `Starter` wrapping a start callback.
+     *
+     * @param start The callback to run on `start()`, which may return a stop callback.
+     */
     constructor(start: StartCallback<T>);
+    /**
+     * Run the start callback (once).
+     * - Does nothing if the process has already been started.
+     *
+     * @param values Values forwarded to the start callback.
+     * @returns Nothing.
+     * @throws {UnexpectedError} If the start callback throws.
+     * @example starter.start();
+     * @see https://dhoulb.github.io/shelving/util/start/Starter/start
+     */
     start(...values: T): void;
+    /**
+     * Run the stop callback (if one was returned by the start callback).
+     * - Does nothing if the process was never started.
+     *
+     * @returns Nothing.
+     * @throws {UnexpectedError} If the stop callback throws.
+     * @example starter.stop();
+     * @see https://dhoulb.github.io/shelving/util/start/Starter/stop
+     */
     stop(): void;
     [Symbol.dispose](): void;
 }
-/** Something that can be made into a `Starter` */
+/**
+ * Something that can be made into a `Starter`.
+ *
+ * @see https://dhoulb.github.io/shelving/util/start/PossibleStarter
+ */
 export type PossibleStarter<T extends Arguments> = StartCallback<T> | Starter<T>;
-/** Get a `Starter` from a `PossibleStarter` */
+/**
+ * Get a `Starter` from a `PossibleStarter`.
+ * - Returns the input unchanged when it is already a `Starter`; otherwise wraps the callback in a new `Starter`.
+ *
+ * @param start A `StartCallback` or an existing `Starter`.
+ * @returns A `Starter` instance.
+ * @example getStarter(() => () => {}) // Starter instance
+ * @see https://dhoulb.github.io/shelving/util/start/getStarter
+ */
 export declare function getStarter<T extends Arguments>(start: StartCallback<T> | Starter<T>): Starter<T>;

package/util/start.js

@@ -1,18 +1,46 @@
 import { UnexpectedError } from "../error/UnexpectedError.js";
 import { BLACKHOLE } from "./function.js";
-/** Callback function that does nothing and returns a blackhole stop callback. */
+/**
+ * Callback function that does nothing and returns a blackhole stop callback.
+ * - Useful as a no-op default where a `StartCallback` is expected.
+ *
+ * @example STOPHOLE() // BLACKHOLE
+ * @see https://dhoulb.github.io/shelving/util/start/STOPHOLE
+ */
 export const STOPHOLE = () => BLACKHOLE;
 /**
  * Wrapper class to handle state on start/stop callback process.
  * - If process has already started, `starter.start()` won't be called twice (including if `start()` didn't return a `stop()` callback).
+ * - Implements `Disposable` so it can be used with `using`, calling `stop()` on disposal.
+ *
+ * @example
+ * const starter = new Starter(() => { console.log("start"); return () => console.log("stop"); });
+ * starter.start();
+ * starter.stop();
+ * @see https://dhoulb.github.io/shelving/util/start/Starter
  */
 export class Starter {
     _start;
     _started = false;
     _stop = undefined;
+    /**
+     * Create a new `Starter` wrapping a start callback.
+     *
+     * @param start The callback to run on `start()`, which may return a stop callback.
+     */
     constructor(start) {
         this._start = start;
     }
+    /**
+     * Run the start callback (once).
+     * - Does nothing if the process has already been started.
+     *
+     * @param values Values forwarded to the start callback.
+     * @returns Nothing.
+     * @throws {UnexpectedError} If the start callback throws.
+     * @example starter.start();
+     * @see https://dhoulb.github.io/shelving/util/start/Starter/start
+     */
     start(...values) {
         if (this._started)
             return;
@@ -24,6 +52,15 @@ export class Starter {
             throw new UnexpectedError("Unexpected error in start callback", { cause: thrown, caller: this.start });
         }
     }
+    /**
+     * Run the stop callback (if one was returned by the start callback).
+     * - Does nothing if the process was never started.
+     *
+     * @returns Nothing.
+     * @throws {UnexpectedError} If the stop callback throws.
+     * @example starter.stop();
+     * @see https://dhoulb.github.io/shelving/util/start/Starter/stop
+     */
     stop() {
         if (!this._started)
             return;
@@ -43,7 +80,15 @@ export class Starter {
         this.stop();
     }
 }
-/** Get a `Starter` from a `PossibleStarter` */
+/**
+ * Get a `Starter` from a `PossibleStarter`.
+ * - Returns the input unchanged when it is already a `Starter`; otherwise wraps the callback in a new `Starter`.
+ *
+ * @param start A `StartCallback` or an existing `Starter`.
+ * @returns A `Starter` instance.
+ * @example getStarter(() => () => {}) // Starter instance
+ * @see https://dhoulb.github.io/shelving/util/start/getStarter
+ */
 export function getStarter(start) {
     return typeof start === "function" ? new Starter(start) : start;
 }

package/util/string.d.ts

@@ -5,41 +5,131 @@ import type { AnyCaller } from "./function.js";
  * - `string` itself is iterable (iterating over its individual characters) and implements `Iterable<string>`
  * - Using `Iterable<string> & NotString` allows an iterable containing strings but not `string` itself.
  * - This helps catch this category of subtle errors.
+ *
+ * @see https://dhoulb.github.io/shelving/util/string/NotString
  */
 export type NotString = {
     toUpperCase?: never;
     toLowerCase?: never;
 };
-/** Things that can be reliably converted to a string with no confusion. */
+/**
+ * Things that can be reliably converted to a string with no confusion.
+ *
+ * @see https://dhoulb.github.io/shelving/util/string/PossibleString
+ */
 export type PossibleString = boolean | string | number | Date;
-/** Series of string segments with at least one one (this is what you _actually_ get back when you split a string). */
+/**
+ * Series of string segments with at least one segment (this is what you _actually_ get back when you split a string).
+ *
+ * @see https://dhoulb.github.io/shelving/util/string/Segments
+ */
 export type Segments = readonly [string, ...string[]];
-/** Is a value a string? */
+/**
+ * Is an unknown value a string?
+ *
+ * @param value The value to check.
+ * @returns `true` if `value` is a `string`, otherwise `false`.
+ * @see https://dhoulb.github.io/shelving/util/string/isString
+ */
 export declare function isString(value: unknown): value is string;
-/** Assert that a value is a string. */
+/**
+ * Assert that a value is a string.
+ *
+ * @param value The value to assert on.
+ * @param caller Function to attribute a thrown error to (defaults to `assertString`).
+ * @throws {RequiredError} If `value` is not a string.
+ * @example assertString("a"); // Passes.
+ * @see https://dhoulb.github.io/shelving/util/string/assertString
+ */
 export declare function assertString(value: unknown, caller?: AnyCaller): asserts value is string;
-/** Convert an unknown value to a string, or return `undefined` if conversion fails. */
+/**
+ * Convert an unknown value to a string, or return `undefined` if conversion fails.
+ * - Coerces numbers, booleans, and `Date` values, and joins arrays with `,` commas; returns `undefined` for anything else.
+ *
+ * @param value The value to convert.
+ * @returns The string representation of `value`, or `undefined` if it cannot be converted.
+ * @example getString(123) // "123"
+ * @see https://dhoulb.github.io/shelving/util/string/getString
+ */
 export declare function getString(value: unknown): string | undefined;
-/** Convert a possible string to a string (optionally with specified min/max length), or throw `RequiredError` if conversion fails. */
+/**
+ * Convert a possible string to a string, or throw `RequiredError` if conversion fails.
+ *
+ * @param value The value to convert.
+ * @param caller Function to attribute a thrown error to (defaults to `requireString`).
+ * @returns The string representation of `value`.
+ * @throws {RequiredError} If `value` cannot be converted to a string.
+ * @example requireString(123) // "123"
+ * @see https://dhoulb.github.io/shelving/util/string/requireString
+ */
 export declare function requireString(value: PossibleString, caller?: AnyCaller): string;
-/** Is a value a string with min/max length? */
+/**
+ * Is a value a string with a length between `min` and `max`?
+ *
+ * @param value The value to check.
+ * @param min The minimum allowed length (defaults to `0`).
+ * @param max The maximum allowed length (defaults to `Infinity`).
+ * @returns `true` if `value` is a string within the length bounds, otherwise `false`.
+ * @see https://dhoulb.github.io/shelving/util/string/isStringLength
+ */
 export declare function isStringLength(value: unknown, min?: number, max?: number): value is string;
-/** Assert that a value is a string with min/max length. */
+/**
+ * Assert that a value is a string with a length between `min` and `max`.
+ *
+ * @param value The value to assert on.
+ * @param min The minimum allowed length.
+ * @param max The maximum allowed length.
+ * @param caller Function to attribute a thrown error to (defaults to `assertString`).
+ * @throws {RequiredError} If `value` is not a string within the length bounds.
+ * @example assertStringLength("abc", 1, 5); // Passes.
+ * @see https://dhoulb.github.io/shelving/util/string/assertStringLength
+ */
 export declare function assertStringLength(value: unknown, min?: number, max?: number, caller?: AnyCaller): asserts value is string;
-/** Convert a possible string to a string (optionally with specified min/max length), or throw `RequiredError` if conversion fails. */
+/**
+ * Convert a possible string to a string with min/max length, or throw `RequiredError` if conversion fails.
+ *
+ * @param value The value to convert.
+ * @param min The minimum allowed length.
+ * @param max The maximum allowed length.
+ * @param caller Function to attribute a thrown error to (defaults to `requireString`).
+ * @returns The string representation of `value`.
+ * @throws {RequiredError} If `value` cannot be converted to a string within the length bounds.
+ * @example requireStringLength("abc", 1, 5) // "abc"
+ * @see https://dhoulb.github.io/shelving/util/string/requireStringLength
+ */
 export declare function requireStringLength(value: PossibleString, min?: number, max?: number, caller?: AnyCaller): string;
-/** Does a string have a length between `min` and `max` */
+/**
+ * Does a string have a length between `min` and `max`?
+ *
+ * @param str The string to measure.
+ * @param min The minimum allowed length (defaults to `0`).
+ * @param max The maximum allowed length (defaults to `Infinity`).
+ * @returns `true` if `str` is within the length bounds, otherwise `false`.
+ * @see https://dhoulb.github.io/shelving/util/string/isStringBetween
+ */
 export declare function isStringBetween(str: string, min?: number, max?: number): boolean;
-/** Concatenate an iterable set of strings together. */
+/**
+ * Concatenate an iterable set of strings together.
+ *
+ * @param strs The iterable of strings to join (must not be a bare `string`).
+ * @param joiner The separator to insert between strings (defaults to `""`).
+ * @returns The joined string.
+ * @throws {RequiredError} If `strs` is not a valid array of strings.
+ * @example joinStrings(["a", "b"], "-") // "a-b"
+ * @see https://dhoulb.github.io/shelving/util/string/joinStrings
+ */
 export declare function joinStrings(strs: Iterable<string> & NotString, joiner?: string): string;
 /**
  * Sanitize a single line of text.
  * - Used when you're sanitising a single-line input, e.g. a title for something.
- * - Remove allow control characters
- * - Normalise runs of whitespace to one ` ` space,
+ * - Remove all control characters.
+ * - Normalise runs of whitespace to one ` ` space.
  * - Trim whitespace from the start and end of the string.
  *
- * @example santizeString("\x00Nice!   "); // Returns `"Nice!"`
+ * @param str The string to sanitize.
+ * @returns The sanitized single-line string.
+ * @example sanitizeText("\x00Nice!   ") // "Nice!"
+ * @see https://dhoulb.github.io/shelving/util/string/sanitizeText
  */
 export declare function sanitizeText(str: string): string;
 /**
@@ -48,7 +138,10 @@ export declare function sanitizeText(str: string): string;
  * - Remove all control characters (like `sanitizeText()`).
  * - Strip all whitespace entirely (rather than collapsing runs to a single space like `sanitizeText()`).
  *
+ * @param str The string to sanitize.
+ * @returns The sanitized single-word string.
  * @example sanitizeWord("\x00 a b c "); // Returns `"abc"`
+ * @see https://dhoulb.github.io/shelving/util/string/sanitizeWord
  */
 export declare function sanitizeWord(str: string): string;
 /**
@@ -60,6 +153,11 @@ export declare function sanitizeWord(str: string): string;
  * - Normalise indentation to tabs (four or more spaces are a tab, three or fewer spaces are removed).
  * - Allow spaces at the start of each line (for indentation) but trim the end of each line.
  * - Trim excess newlines at the start and end of the string and runs of more than two newlines in a row.
+ *
+ * @param str The string to sanitize.
+ * @returns The sanitized multi-line string.
+ * @example sanitizeMultilineText("\x00Line one\n\n\n\nLine two   ") // "Line one\n\nLine two"
+ * @see https://dhoulb.github.io/shelving/util/string/sanitizeMultilineText
  */
 export declare function sanitizeMultilineText(str: string): string;
 /**
@@ -67,18 +165,53 @@ export declare function sanitizeMultilineText(str: string): string;
  * - Normalizes the string by
  * - Useful when you're running a query against a string entered by a user.
  *
+ * @param str The string to simplify.
+ * @returns The simplified, lowercased string containing only numbers, letters, and single spaces.
  * @example simplifyString("Däve-is\nREALLY    éxcitable—apparęntly!!!    😂"); // Returns "dave is really excitable apparently"
+ * @see https://dhoulb.github.io/shelving/util/string/simplifyString
  *
  * @todo Convert confusables (e.g. `ℵ` alef symbol or `℮` estimate symbol) to their letterlike equivalent (e.g. `N` and `e`).
  */
 export declare function simplifyString(str: string): string;
-/** Convert a string to a `kebab-case` URL slug, or return `undefined` if conversion resulted in an empty ref. */
+/**
+ * Convert a string to a `kebab-case` URL slug, or return `undefined` if conversion resulted in an empty ref.
+ *
+ * @param str The string to convert.
+ * @returns The `kebab-case` slug, or `undefined` if conversion resulted in an empty string.
+ * @example getSlug("Hello World!") // "hello-world"
+ * @see https://dhoulb.github.io/shelving/util/string/getSlug
+ */
 export declare function getSlug(str: string): string | undefined;
-/** Convert a string to a `kebab-case` URL slug, or throw `RequiredError` if conversion resulted in an empty ref. */
+/**
+ * Convert a string to a `kebab-case` URL slug, or throw `RequiredError` if conversion resulted in an empty ref.
+ *
+ * @param str The string to convert.
+ * @param caller Function to attribute a thrown error to (defaults to `requireSlug` itself).
+ * @returns The `kebab-case` slug.
+ * @throws {RequiredError} If conversion resulted in an empty string.
+ * @example requireSlug("Hello World!") // "hello-world"
+ * @see https://dhoulb.github.io/shelving/util/string/requireSlug
+ */
 export declare function requireSlug(str: string, caller?: AnyCaller): string;
-/** Convert a string to a unique ref e.g. `abc123`, or return `undefined` if conversion resulted in an empty string. */
+/**
+ * Convert a string to a unique ref e.g. `abc123`, or return `undefined` if conversion resulted in an empty string.
+ *
+ * @param str The string to convert.
+ * @returns The ref, or `undefined` if conversion resulted in an empty string.
+ * @example getRef("Hello World!") // "helloworld"
+ * @see https://dhoulb.github.io/shelving/util/string/getRef
+ */
 export declare function getRef(str: string): string | undefined;
-/** Convert a string to a unique ref e.g. `abc123`, or throw `RequiredError` if conversion resulted in an empty string. */
+/**
+ * Convert a string to a unique ref e.g. `abc123`, or throw `RequiredError` if conversion resulted in an empty string.
+ *
+ * @param str The string to convert.
+ * @param caller Function to attribute a thrown error to (defaults to `requireRef` itself).
+ * @returns The ref.
+ * @throws {RequiredError} If conversion resulted in an empty string.
+ * @example requireRef("Hello World!") // "helloworld"
+ * @see https://dhoulb.github.io/shelving/util/string/requireRef
+ */
 export declare function requireRef(str: string, caller?: AnyCaller): string;
 /**
  * Return an array of the separate words and "quoted phrases" found in a string.
@@ -86,18 +219,49 @@ export declare function requireRef(str: string, caller?: AnyCaller): string;
  * - Performs no processing on the words, so control chars, punctuation, symbols, and case are all preserved.
  *
  * Note: this splits words based on spaces, so won't work well with logographic writing systems e.g. kanji.
+ *
+ * @param str The string to extract words from.
+ * @returns Array of the separate words and quoted phrases found in `str`.
+ * @example getWords(`a "b c" d`) // ["a", "b c", "d"]
+ * @see https://dhoulb.github.io/shelving/util/string/getWords
  */
 export declare function getWords(str: string): ImmutableArray<string>;
-/** Get the (trimmed) first full line of a string. */
+/**
+ * Get the (trimmed) first full line of a string.
+ *
+ * @param str The string to read the first line from.
+ * @returns The trimmed first line of `str` (everything before the first `\n` newline).
+ * @example getFirstLine("first\nsecond") // "first"
+ * @see https://dhoulb.github.io/shelving/util/string/getFirstLine
+ */
 export declare function getFirstLine(str: string): string;
-/** Is the first character of a string an uppercase letter? */
+/**
+ * Is the first character of a string an uppercase letter?
+ *
+ * @param str The string whose first character is tested.
+ * @returns `true` if the first character of `str` is an uppercase A–Z letter, otherwise `false`.
+ * @see https://dhoulb.github.io/shelving/util/string/isUppercaseLetter
+ */
 export declare function isUppercaseLetter(str: string): boolean;
-/** Is the first character of a string a lowercase letter? */
+/**
+ * Is the first character of a string a lowercase letter?
+ *
+ * @param str The string whose first character is tested.
+ * @returns `true` if the first character of `str` is a lowercase a–z letter, otherwise `false`.
+ * @see https://dhoulb.github.io/shelving/util/string/isLowercaseLetter
+ */
 export declare function isLowercaseLetter(str: string): boolean;
 /**
  * Limit a string to a given length.
  * - Stops at the last space inside `maxLength`
  * - Appends an `…` ellipses after the string (but only if a limit is applied).
+ *
+ * @param str The string to limit.
+ * @param maxLength The maximum length of the returned string (before `append` is added).
+ * @param append The string to append when a limit is applied (defaults to `"…"`).
+ * @returns `str` unchanged if it's shorter than `maxLength`, otherwise truncated with `append` added.
+ * @example limitString("the quick brown fox", 9) // "the quick…"
+ * @see https://dhoulb.github.io/shelving/util/string/limitString
  */
 export declare function limitString(str: string, maxLength: number, append?: string): string;
 /**
@@ -106,8 +270,15 @@ export declare function limitString(str: string, maxLength: number, append?: str
  * - Excess segments in `String.prototype.split()` is counterintuitive because further parts are thrown away.
  * - Excess segments in `splitString()` are concatenated onto the last segment (set `max` to `null` if you want infinite segments).
  *
- * @throws RequiredError if `min` isn't met.
- * @throws RequiredError if any of the segments are empty.
+ * @param str The string to divide.
+ * @param separator The separator to divide `str` on.
+ * @param min The minimum number of segments required (defaults to `1`).
+ * @param max The maximum number of segments (excess segments are concatenated onto the last; defaults to `Infinity`).
+ * @param caller Function to attribute a thrown error to (defaults to `splitString` itself).
+ * @returns Array of the divided segments.
+ * @throws {ValueError} If `min` isn't met, or if any of the segments are empty.
+ * @example splitString("a-b-c", "-", 2, 2) // ["a", "b-c"]
+ * @see https://dhoulb.github.io/shelving/util/string/splitString
  */
 export declare function splitString(str: string, separator: string, min: 1, max: 1, caller?: AnyCaller): readonly [string];
 export declare function splitString(str: string, separator: string, min: 2, max: 2, caller?: AnyCaller): readonly [string, string];
@@ -118,7 +289,20 @@ export declare function splitString(str: string, separator: string, min: 2, max?
 export declare function splitString(str: string, separator: string, min: 3, max?: number, caller?: AnyCaller): readonly [string, string, string, ...string[]];
 export declare function splitString(str: string, separator: string, min: 4, max?: number, caller?: AnyCaller): readonly [string, string, string, string, ...string[]];
 export declare function splitString(str: string, separator: string, min?: number, max?: number, caller?: AnyCaller): ImmutableArray<string>;
-/** Trim a string (as a function, so it can be used in mapping. */
+/**
+ * Trim a string (as a function, so it can be used in mapping).
+ *
+ * @param str The string to trim.
+ * @returns `str` with whitespace trimmed from both ends.
+ * @example ["  a  ", " b "].map(trimString) // ["a", "b"]
+ * @see https://dhoulb.github.io/shelving/util/string/trimString
+ */
 export declare function trimString(str: string): string;
-/** Does a string have length? */
+/**
+ * Does a string have length?
+ *
+ * @param str The string to test.
+ * @returns `true` if `str` has a length greater than zero, otherwise `false`.
+ * @see https://dhoulb.github.io/shelving/util/string/isNonEmptyString
+ */
 export declare function isNonEmptyString(str: string): boolean;