shelving 1.236.0 → 1.236.2

package/util/string.js

@@ -2,16 +2,38 @@ import { RequiredError } from "../error/RequiredError.js";
 import { ValueError } from "../error/ValueError.js";
 import { requireArray } from "./array.js";
 import { isBetween } from "./number.js";
-/** 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 function isString(value) {
     return typeof value === "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 function assertString(value, caller = assertString) {
     if (!isString(value))
         throw new RequiredError(`Must be string`, { received: value, caller });
 }
-/** 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 function getString(value) {
     if (typeof value === "string")
         return value;
@@ -25,43 +47,101 @@ export function getString(value) {
         return value.map(getString).join(",");
     return 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 function requireString(value, caller = requireString) {
     const str = getString(value);
     assertString(str, caller);
     return str;
 }
-/** 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 function isStringLength(value, min = 0, max = Number.POSITIVE_INFINITY) {
     return typeof value === "string" && value.length >= min && value.length <= max;
 }
-/** 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 function assertStringLength(value, min, max, caller = assertString) {
     if (!isStringLength(value, min, max))
         throw new RequiredError(`Must be string with ${min ?? 0} to ${max ?? "∞"} characters`, { received: value, caller });
 }
-/** 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 function requireStringLength(value, min, max, caller = requireString) {
     const str = getString(value);
     assertStringLength(str, min, max, caller);
     return str;
 }
-/** 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 function isStringBetween(str, min = 0, max = Number.POSITIVE_INFINITY) {
     return str.length >= min && str.length <= max;
 }
-/** 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 function joinStrings(strs, joiner = "") {
     return requireArray(strs, undefined, undefined, joinStrings).join(joiner);
 }
 /**
  * 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 function sanitizeText(str) {
     return str
@@ -75,7 +155,10 @@ export function sanitizeText(str) {
  * - 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 function sanitizeWord(str) {
     return str
@@ -91,6 +174,11 @@ export function sanitizeWord(str) {
  * - 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 function sanitizeMultilineText(str) {
     return str
@@ -109,7 +197,10 @@ export function sanitizeMultilineText(str) {
  * - 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`).
  */
@@ -121,22 +212,54 @@ export function simplifyString(str) {
         .trim()
         .toLowerCase();
 }
-/** 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 function getSlug(str) {
     return simplifyString(str).replaceAll(" ", "-") || 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 function requireSlug(str, caller = requireSlug) {
     const slug = getSlug(str);
     if (!slug)
         throw new RequiredError("Invalid slug", { received: str, caller });
     return slug;
 }
-/** 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 function getRef(str) {
     return simplifyString(str).replaceAll(" ", "") || 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 function requireRef(str, caller = requireRef) {
     const ref = getRef(str);
     if (!ref)
@@ -149,6 +272,11 @@ export function requireRef(str, caller = requireRef) {
  * - 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 function getWords(str) {
     return Array.from(_getWords(str));
@@ -161,16 +289,35 @@ function* _getWords(str) {
     }
 }
 const WORD = /([^\s"]+)|"([^"]*)"|'([^']*)'/g; // Runs of characters without spaces, or "quoted phrases"
-/** 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 function getFirstLine(str) {
     const i = str.indexOf("\n");
     return (i >= 0 ? str.substr(0, i) : str).trim();
 }
-/** 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 function isUppercaseLetter(str) {
     return isBetween(str.charCodeAt(0), 65, 90);
 }
-/** 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 function isLowercaseLetter(str) {
     return isBetween(str.charCodeAt(0), 97, 122);
 }
@@ -178,6 +325,13 @@ export function isLowercaseLetter(str) {
  * 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 function limitString(str, maxLength, append = "…") {
     if (str.length < maxLength)
@@ -196,11 +350,24 @@ export function splitString(str, separator, min = 1, max = Number.POSITIVE_INFIN
         });
     return segments;
 }
-/** 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 function trimString(str) {
     return str.trim();
 }
-/** 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 function isNonEmptyString(str) {
     return str.length > 0;
 }

package/util/template.d.ts

@@ -9,18 +9,30 @@ import { type NotString, type PossibleString } from "./string.js";
  * `PossibleString` — Single string used for every `{placeholder}`
  * `ImmutableArray<string>` — Array of strings (or functions that return strings) used for `*` numbered placeholders e.g. `["John"]`
  * `ImmutableDictionary<PossibleString>` — Object containing named strings used for named placeholders, e.g. `{ val1: "Ellie", val2: 123 }`
- * `(placeholder: string) => string` — Function that returns the right string for a named `{placeholder}`.v
+ * `(placeholder: string) => string` — Function that returns the right string for a named `{placeholder}`.
+ *
+ * @see https://dhoulb.github.io/shelving/util/template/TemplateValues
  */
 export type TemplateValues = PossibleString | ImmutableArray<unknown> | ImmutableDictionary<unknown> | ((placeholder: string) => string);
-/** The output of matching a template is a dictionary in `{ myPlaceholder: "value" }` format. */
+/**
+ * The output of matching a template is a dictionary in `{ myPlaceholder: "value" }` format.
+ *
+ * @see https://dhoulb.github.io/shelving/util/template/TemplateMatches
+ */
 export type TemplateMatches = ImmutableDictionary<string>;
-/** List of `{placeholders}` found in a template string. */
+/**
+ * List of `{placeholders}` found in a template string.
+ *
+ * @see https://dhoulb.github.io/shelving/util/template/TemplatePlaceholders
+ */
 export type TemplatePlaceholders = ImmutableArray<string>;
 /**
  * Get list of placeholders named in a template string.
  *
  * @param template The template including template placeholders, e.g. `:name-${country}/{city}`
  * @returns Array of clean string names of found placeholders, e.g. `["name", "country", "city"]`
+ * @example getPlaceholders(":name-${country}/{city}") // ["name", "country", "city"]
+ * @see https://dhoulb.github.io/shelving/util/template/getPlaceholders
  */
 export declare function getPlaceholders(template: string): TemplatePlaceholders;
 /**
@@ -30,31 +42,68 @@ export declare function getPlaceholders(template: string): TemplatePlaceholders;
  *
  * @param template The template string, e.g. `:name-${country}/{city}`.
  * @param target The string containing values, e.g. `Dave-UK/Manchester`.
- *
- * @return An object containing values (e.g. `{ name: "Dave", country: "UK", city: "Manchester" }`), or `undefined` if no match.
+ * @param caller Function to attribute a thrown error to (defaults to `matchTemplate` itself).
+ * @returns An object containing values (e.g. `{ name: "Dave", country: "UK", city: "Manchester" }`), or `undefined` if no match.
+ * @throws {ValueError} If two template placeholders are not separated by at least one character.
+ * @example matchTemplate(":name-${country}/{city}", "Dave-UK/Manchester") // { name: "Dave", country: "UK", city: "Manchester" }
+ * @see https://dhoulb.github.io/shelving/util/template/matchTemplate
  */
 export declare function matchTemplate(template: string, target: string, caller?: AnyCaller): TemplateMatches | undefined;
 /**
  * Match a path-shaped template against a target path.
  * - Like `matchTemplate`, but with `/` segment semantics: non-catchall placeholders cannot span path segments; catchall placeholders can.
  * - A trailing catchall (e.g. `/files/{...path}`) also matches when the trailing separator is absent (e.g. `/files`), with the catchall value as `""`.
+ *
+ * @param template The path-shaped template string, e.g. `/users/{name}`.
+ * @param target The path containing values, e.g. `/users/Dave`.
+ * @param caller Function to attribute a thrown error to (defaults to `matchPathTemplate` itself).
+ * @returns An object containing values (e.g. `{ name: "Dave" }`), or `undefined` if no match.
+ * @throws {ValueError} If two template placeholders are not separated by at least one character.
+ * @example matchPathTemplate("/users/{name}", "/users/Dave") // { name: "Dave" }
+ * @see https://dhoulb.github.io/shelving/util/template/matchPathTemplate
  */
 export declare function matchPathTemplate(template: AbsolutePath, target: AbsolutePath, caller?: AnyCaller): TemplateMatches | undefined;
-/** Match multiple templates against a target string and return the first match (no separator semantics). */
+/**
+ * Match multiple templates against a target string and return the first match (no separator semantics).
+ *
+ * @param templates Iterable of template strings to try in order, e.g. `[":name-:age", ":name"]`.
+ * @param target The string containing values, e.g. `Dave-40`.
+ * @returns An object of values for the first matching template, or `undefined` if none match.
+ * @example matchTemplates([":name-:age", ":name"], "Dave-40") // { name: "Dave", age: "40" }
+ * @see https://dhoulb.github.io/shelving/util/template/matchTemplates
+ */
 export declare function matchTemplates(templates: Iterable<string> & NotString, target: string): TemplateMatches | undefined;
-/** Match multiple path-shaped templates against a target path and return the first match. */
+/**
+ * Match multiple path-shaped templates against a target path and return the first match.
+ *
+ * @param templates Iterable of path-shaped template strings to try in order, e.g. `["/users/{name}", "/users"]`.
+ * @param target The path containing values, e.g. `/users/Dave`.
+ * @returns An object of values for the first matching template, or `undefined` if none match.
+ * @example matchPathTemplates(["/users/{name}", "/users"], "/users/Dave") // { name: "Dave" }
+ * @see https://dhoulb.github.io/shelving/util/template/matchPathTemplates
+ */
 export declare function matchPathTemplates(templates: Iterable<AbsolutePath> & NotString, target: AbsolutePath): TemplateMatches | undefined;
 /**
  * Turn ":year-:month" and `{ year: "2016"... }` etc into "2016-06..." etc.
  *
  * @param template The template including template placeholders, e.g. `:name-${country}/{city}`
  * @param values An object containing values, e.g. `{ name: "Dave", country: "UK", city: "Manchester" }` (functions are called, everything else converted to string), or a function or string to use for all placeholders.
- * @return The rendered string, e.g. `Dave-UK/Manchester`
- *
+ * @param caller Function to attribute a thrown error to (defaults to `renderTemplate` itself).
+ * @returns The rendered string, e.g. `Dave-UK/Manchester`
  * @throws {RequiredError} If a placeholder in the template string is not specified in values.
+ * @example renderTemplate(":name-${country}/{city}", { name: "Dave", country: "UK", city: "Manchester" }) // "Dave-UK/Manchester"
+ * @see https://dhoulb.github.io/shelving/util/template/renderTemplate
  */
 export declare function renderTemplate(template: string, values: TemplateValues, caller?: AnyCaller): string;
 /**
  * Render a path-shaped template. Behaviourally identical to `renderTemplate` — substitution doesn't need separator awareness — but provided as a sibling to `matchPathTemplate` so callers can pair them.
+ *
+ * @param template The path-shaped template including placeholders, e.g. `/users/{name}`.
+ * @param values An object containing values (functions are called, everything else converted to string), or a function or string to use for all placeholders.
+ * @param caller Function to attribute a thrown error to (defaults to `renderPathTemplate` itself).
+ * @returns The rendered path, e.g. `/users/Dave`.
+ * @throws {RequiredError} If a placeholder in the template string is not specified in values.
+ * @example renderPathTemplate("/users/{name}", { name: "Dave" }) // "/users/Dave"
+ * @see https://dhoulb.github.io/shelving/util/template/renderPathTemplate
  */
 export declare function renderPathTemplate(template: AbsolutePath, values: TemplateValues, caller?: AnyCaller): AbsolutePath;

package/util/template.js

@@ -60,6 +60,8 @@ function _splitTemplateCached(template, caller) {
  *
  * @param template The template including template placeholders, e.g. `:name-${country}/{city}`
  * @returns Array of clean string names of found placeholders, e.g. `["name", "country", "city"]`
+ * @example getPlaceholders(":name-${country}/{city}") // ["name", "country", "city"]
+ * @see https://dhoulb.github.io/shelving/util/template/getPlaceholders
  */
 export function getPlaceholders(template) {
     return _splitTemplateCached(template, getPlaceholders).map(_getPlaceholder);
@@ -74,8 +76,11 @@ function _getPlaceholder({ name }) {
  *
  * @param template The template string, e.g. `:name-${country}/{city}`.
  * @param target The string containing values, e.g. `Dave-UK/Manchester`.
- *
- * @return An object containing values (e.g. `{ name: "Dave", country: "UK", city: "Manchester" }`), or `undefined` if no match.
+ * @param caller Function to attribute a thrown error to (defaults to `matchTemplate` itself).
+ * @returns An object containing values (e.g. `{ name: "Dave", country: "UK", city: "Manchester" }`), or `undefined` if no match.
+ * @throws {ValueError} If two template placeholders are not separated by at least one character.
+ * @example matchTemplate(":name-${country}/{city}", "Dave-UK/Manchester") // { name: "Dave", country: "UK", city: "Manchester" }
+ * @see https://dhoulb.github.io/shelving/util/template/matchTemplate
  */
 export function matchTemplate(template, target, caller = matchTemplate) {
     return _matchTemplate(template, target, "", caller);
@@ -84,6 +89,14 @@ export function matchTemplate(template, target, caller = matchTemplate) {
  * Match a path-shaped template against a target path.
  * - Like `matchTemplate`, but with `/` segment semantics: non-catchall placeholders cannot span path segments; catchall placeholders can.
  * - A trailing catchall (e.g. `/files/{...path}`) also matches when the trailing separator is absent (e.g. `/files`), with the catchall value as `""`.
+ *
+ * @param template The path-shaped template string, e.g. `/users/{name}`.
+ * @param target The path containing values, e.g. `/users/Dave`.
+ * @param caller Function to attribute a thrown error to (defaults to `matchPathTemplate` itself).
+ * @returns An object containing values (e.g. `{ name: "Dave" }`), or `undefined` if no match.
+ * @throws {ValueError} If two template placeholders are not separated by at least one character.
+ * @example matchPathTemplate("/users/{name}", "/users/Dave") // { name: "Dave" }
+ * @see https://dhoulb.github.io/shelving/util/template/matchPathTemplate
  */
 export function matchPathTemplate(template, target, caller = matchPathTemplate) {
     return _matchTemplate(template, target, "/", caller);
@@ -128,7 +141,15 @@ function _matchTemplate(template, target, separator, caller) {
         return undefined; // Target doesn't match template because last chunk post didn't reach the end.
     return values;
 }
-/** Match multiple templates against a target string and return the first match (no separator semantics). */
+/**
+ * Match multiple templates against a target string and return the first match (no separator semantics).
+ *
+ * @param templates Iterable of template strings to try in order, e.g. `[":name-:age", ":name"]`.
+ * @param target The string containing values, e.g. `Dave-40`.
+ * @returns An object of values for the first matching template, or `undefined` if none match.
+ * @example matchTemplates([":name-:age", ":name"], "Dave-40") // { name: "Dave", age: "40" }
+ * @see https://dhoulb.github.io/shelving/util/template/matchTemplates
+ */
 export function matchTemplates(templates, target) {
     for (const template of templates) {
         const values = matchTemplate(template, target);
@@ -136,7 +157,15 @@ export function matchTemplates(templates, target) {
             return values;
     }
 }
-/** Match multiple path-shaped templates against a target path and return the first match. */
+/**
+ * Match multiple path-shaped templates against a target path and return the first match.
+ *
+ * @param templates Iterable of path-shaped template strings to try in order, e.g. `["/users/{name}", "/users"]`.
+ * @param target The path containing values, e.g. `/users/Dave`.
+ * @returns An object of values for the first matching template, or `undefined` if none match.
+ * @example matchPathTemplates(["/users/{name}", "/users"], "/users/Dave") // { name: "Dave" }
+ * @see https://dhoulb.github.io/shelving/util/template/matchPathTemplates
+ */
 export function matchPathTemplates(templates, target) {
     for (const template of templates) {
         const values = matchPathTemplate(template, target);
@@ -149,9 +178,11 @@ export function matchPathTemplates(templates, target) {
  *
  * @param template The template including template placeholders, e.g. `:name-${country}/{city}`
  * @param values An object containing values, e.g. `{ name: "Dave", country: "UK", city: "Manchester" }` (functions are called, everything else converted to string), or a function or string to use for all placeholders.
- * @return The rendered string, e.g. `Dave-UK/Manchester`
- *
+ * @param caller Function to attribute a thrown error to (defaults to `renderTemplate` itself).
+ * @returns The rendered string, e.g. `Dave-UK/Manchester`
  * @throws {RequiredError} If a placeholder in the template string is not specified in values.
+ * @example renderTemplate(":name-${country}/{city}", { name: "Dave", country: "UK", city: "Manchester" }) // "Dave-UK/Manchester"
+ * @see https://dhoulb.github.io/shelving/util/template/renderTemplate
  */
 export function renderTemplate(template, values, caller = renderTemplate) {
     const chunks = _splitTemplateCached(template, caller);
@@ -189,6 +220,14 @@ export function renderTemplate(template, values, caller = renderTemplate) {
 }
 /**
  * Render a path-shaped template. Behaviourally identical to `renderTemplate` — substitution doesn't need separator awareness — but provided as a sibling to `matchPathTemplate` so callers can pair them.
+ *
+ * @param template The path-shaped template including placeholders, e.g. `/users/{name}`.
+ * @param values An object containing values (functions are called, everything else converted to string), or a function or string to use for all placeholders.
+ * @param caller Function to attribute a thrown error to (defaults to `renderPathTemplate` itself).
+ * @returns The rendered path, e.g. `/users/Dave`.
+ * @throws {RequiredError} If a placeholder in the template string is not specified in values.
+ * @example renderPathTemplate("/users/{name}", { name: "Dave" }) // "/users/Dave"
+ * @see https://dhoulb.github.io/shelving/util/template/renderPathTemplate
  */
 export function renderPathTemplate(template, values, caller = renderPathTemplate) {
     return renderTemplate(template, values, caller);

package/util/timeout.d.ts

@@ -1,27 +1,51 @@
 import type { Callback } from "./function.js";
 /**
- * Create a new Timeout.
+ * Stateful wrapper around `setTimeout()` that manages a single pending timeout at a time.
+ * - Keeps track of the reference returned from `setTimeout()`.
+ * - Clears any existing timeout when a new timeout is set.
+ * - Allows a default callback and a default delay to be set that are applied to all new timeouts that don't specify their own.
  *
- * Wrapper for `setTimeout()` that...
- * - Keeps track of the reference returned from `setTimeout()`
- * - Clears the any existing timeout when a new timeout is set.
- * - Allows a default delay to be set that is applied to all new timeouts that don't have a delay set.
- *
- * @param ms The default delay for any created timeouts (in ms).
+ * @example
+ * const timeout = new Timeout(() => console.log("fired"), 1000);
+ * timeout.set(); // Fires the callback after 1000ms.
+ * timeout.clear(); // Cancels it before it fires.
+ * @see https://dhoulb.github.io/shelving/util/timeout/Timeout
  */
 export declare class Timeout {
     private _callback;
     private _ms;
     private _timeout;
+    /**
+     * Create a new `Timeout`.
+     *
+     * @param callback The default callback to run when a timeout fires (used by `set()` when no callback is passed).
+     * @param ms The default delay for any created timeouts (in ms).
+     * @example new Timeout(() => console.log("fired"), 1000)
+     * @see https://dhoulb.github.io/shelving/util/timeout/Timeout
+     */
     constructor(callback?: Callback | undefined, ms?: number);
-    /** Is a timeout currently set? */
+    /**
+     * Whether a timeout is currently pending.
+     *
+     * @see https://dhoulb.github.io/shelving/util/timeout/Timeout/exists
+     */
     get exists(): boolean;
     /**
      * Cancel any existing timeout and set a new one.
-     * @param callback
-     * @param ms The delay for this timeout (in ms).
+     *
+     * @param callback The callback to run when this timeout fires (defaults to the callback passed to the constructor).
+     * @param ms The delay for this timeout (in ms, defaults to the delay passed to the constructor).
+     * @returns Nothing.
+     * @example timeout.set(() => console.log("fired"), 500);
+     * @see https://dhoulb.github.io/shelving/util/timeout/Timeout/set
      */
     set(callback?: Callback | undefined, ms?: number): void;
-    /** Cancel any existing timeout.. */
+    /**
+     * Cancel any existing timeout.
+     *
+     * @returns Nothing.
+     * @example timeout.clear();
+     * @see https://dhoulb.github.io/shelving/util/timeout/Timeout/clear
+     */
     clear(): void;
 }