@dereekb/util 13.0.7 → 13.2.0

package/src/lib/string/replace.d.ts

@@ -1,7 +1,13 @@
 import { type ArrayOrValue } from '../array/array';
 import { type Maybe } from '../value/maybe.type';
 import { type MapSameFunction } from '../value/map';
+/**
+ * Function that replaces target substrings within an input string.
+ */
 export type ReplaceStringsFunction = MapSameFunction<string>;
+/**
+ * Configuration for creating a {@link ReplaceStringsFunction}.
+ */
 export interface ReplaceStringsConfig {
     /**
      * Strings to target/replace.
@@ -12,15 +18,31 @@ export interface ReplaceStringsConfig {
      */
     readonly replaceWith: string;
 }
+/**
+ * Creates a function that replaces all occurrences of the configured target strings with a replacement value.
+ *
+ * @param config - Configuration specifying strings to find and the replacement value.
+ * @returns A function that performs the configured replacements on an input string.
+ */
 export declare function replaceStringsFunction(config: ReplaceStringsConfig): (input: string) => string;
+/**
+ * Array of characters that have special meaning in regular expressions and need escaping.
+ */
 export declare const REGEX_SPECIAL_CHARACTERS: string[];
+/**
+ * Set of regex special characters for efficient lookup.
+ */
 export declare const REGEX_SPECIAL_CHARACTERS_SET: Set<string>;
 /**
- * Creates an escaped regex string joined with or values that finds all of the input values.
+ * Creates an escaped regex string that matches any of the input values, joined with the OR (`|`) operator.
  *
- * @param find
+ * @param find - One or more strings to create a matching regex pattern for.
+ * @returns A regex-compatible string with special characters escaped and values joined by `|`.
  */
 export declare function findStringsRegexString(find: ArrayOrValue<string>): string;
+/**
+ * Configuration for creating an {@link EscapeStringCharactersFunction}.
+ */
 export interface EscapeStringCharactersFunctionConfig {
     /**
      * The set of characters to find and use the escapeCharacter() function on.
@@ -43,36 +65,51 @@ export interface EscapeStringCharactersFunctionConfig {
  */
 export type EscapeStringCharactersFunction = (input: string) => string;
 /**
- * Creates an EscapeStringCharactersFunction
+ * Creates an {@link EscapeStringCharactersFunction} that escapes specific characters in a string using the configured escape strategy.
  *
- * @param config
- * @returns
+ * @param config - Configuration specifying which characters to escape and how to escape them.
+ * @returns A function that escapes the configured characters in any input string.
  */
 export declare function escapeStringCharactersFunction(config: EscapeStringCharactersFunctionConfig): EscapeStringCharactersFunction;
 /**
- * Escapes the input string to be usable in a Regex value.
+ * Escapes the input string so it can be safely used as a literal value in a regular expression.
  *
- * For instance, 'hello.world' will be escaped to be 'hello\.world'
+ * For instance, `'hello.world'` will be escaped to `'hello\\.world'`.
  *
- * @param input
+ * @param input - The string to escape for regex use.
+ * @returns The escaped string with all regex special characters prefixed with a backslash.
  */
 export declare const escapeStringForRegex: EscapeStringCharactersFunction;
+/**
+ * Function that finds all indices of characters from a pre-configured set within an input string.
+ *
+ * @param input - The string to search through.
+ * @param max - Optional maximum number of occurrences to return.
+ * @returns An array of zero-based indices where matching characters were found.
+ */
 export type FindAllCharacterOccurencesFunction = (input: string, max?: Maybe<number>) => number[];
+/**
+ * Creates a {@link FindAllCharacterOccurencesFunction} that searches for characters from the given set.
+ *
+ * @param characterSet - The set of characters to search for.
+ * @returns A function that finds all occurrences of the configured characters in an input string.
+ */
 export declare function findAllCharacterOccurencesFunction(characterSet: Set<string>): FindAllCharacterOccurencesFunction;
 /**
- * First all occurences of the characters from the set in the input string.
+ * Finds all indices of characters from the set that appear in the input string.
  *
- * @param set
- * @param input
- * @returns
+ * @param set - The set of characters to search for.
+ * @param input - The string to search through.
+ * @param max - Optional maximum number of occurrences to return.
+ * @returns An array of zero-based indices where matching characters were found.
  */
 export declare function findAllCharacterOccurences(set: Set<string>, input: string, max?: number): number[];
 /**
- * First the first occurence of a character from the set in the input string.
+ * Finds the index of the first occurrence of any character from the set in the input string.
  *
- * @param set
- * @param input
- * @returns
+ * @param set - The set of characters to search for.
+ * @param input - The string to search through.
+ * @returns The zero-based index of the first matching character, or `undefined` if none found.
  */
 export declare function findFirstCharacterOccurence(set: Set<string>, input: string): Maybe<number>;
 /**
@@ -87,12 +124,19 @@ export type SplitStringAtFirstCharacterOccurenceResult = [string, string | undef
  */
 export type SplitStringAtFirstCharacterOccurenceFunction = (input: string) => SplitStringAtFirstCharacterOccurenceResult;
 /**
- * Splits the string into two parts at the first occurence of a string or any string in the set.
+ * Creates a function that splits a string into two parts at the first occurrence of any character in the configured set.
  *
- * @param set
- * @param input
+ * @param splitAt - A single character or set of characters to split on.
+ * @returns A function that splits input strings at the first matching character.
  */
 export declare function splitStringAtFirstCharacterOccurenceFunction(splitAt: string | Set<string>): SplitStringAtFirstCharacterOccurenceFunction;
+/**
+ * Splits the input string into two parts at the first occurrence of any character in the split set.
+ *
+ * @param input - The string to split.
+ * @param splitAt - A single character or set of characters to split on.
+ * @returns A tuple of [before, after], where `after` is `undefined` if no split character was found.
+ */
 export declare function splitStringAtFirstCharacterOccurence(input: string, splitAt: string | Set<string>): [string, string | undefined];
 /**
  * Keeps all characters from the input string after the first character occurence pre-determined by the function.
@@ -101,18 +145,18 @@ export declare function splitStringAtFirstCharacterOccurence(input: string, spli
  */
 export type KeepCharactersAfterFirstCharacterOccurenceFunction = (input: string) => string;
 /**
- * Splits the string into two parts at the first occurence of a string or any string in the set.
+ * Creates a function that returns only the characters after the first occurrence of any character in the configured set.
  *
- * @param set
- * @param input
+ * @param findCharacters - A single character or set of characters to search for.
+ * @returns A function that extracts the substring after the first matching character, or an empty string if none found.
  */
 export declare function keepCharactersAfterFirstCharacterOccurenceFunction(findCharacters: string | Set<string>): KeepCharactersAfterFirstCharacterOccurenceFunction;
 /**
- * Keeps all characters from the input string after the first character occurence from findCharacters input.
+ * Returns only the characters after the first occurrence of any character from the find set.
  *
- * @param input
- * @param splitAt
- * @returns
+ * @param input - The string to search through.
+ * @param findCharacters - A single character or set of characters to search for.
+ * @returns The substring after the first matching character, or an empty string if none found.
  */
 export declare function keepCharactersAfterFirstCharacterOccurence(input: string, findCharacters: string | Set<string>): string;
 /**
@@ -120,17 +164,17 @@ export declare function keepCharactersAfterFirstCharacterOccurence(input: string
  */
 export type RemoveCharactersAfterFirstCharacterOccurenceFunction = (input: string) => string;
 /**
- * Splits the string into two parts at the first occurence of a string or any string in the set.
+ * Creates a function that removes all characters after (and including) the first occurrence of any character in the configured set.
  *
- * @param set
- * @param input
+ * @param findCharacters - A single character or set of characters to search for.
+ * @returns A function that truncates input strings at the first matching character.
  */
 export declare function removeCharactersAfterFirstCharacterOccurenceFunction(findCharacters: string | Set<string>): RemoveCharactersAfterFirstCharacterOccurenceFunction;
 /**
- * Removes all characters from the input string after the first character occurence from findCharacters input.
+ * Removes all characters after (and including) the first occurrence of any character from the find set.
  *
- * @param input
- * @param splitAt
- * @returns
+ * @param input - The string to truncate.
+ * @param findCharacters - A single character or set of characters to search for.
+ * @returns The substring before the first matching character, or the full string if none found.
  */
 export declare function removeCharactersAfterFirstCharacterOccurence(input: string, findCharacters: string | Set<string>): string;

package/src/lib/string/search.d.ts

@@ -8,30 +8,40 @@ export type SearchStringDecisionFunctionFactory = DecisionFunctionFactory<string
  * Filters values by the input filter text.
  */
 export type SearchStringFilterFunction<T> = (filterText: string, values: T[]) => T[];
+/**
+ * Configuration for creating a {@link SearchStringFilterFunction}.
+ *
+ * @template T - The type of values being filtered.
+ */
 export interface SearchStringFilterConfig<T> {
     /**
-     * Reads the search value(s) from the input
+     * Reads the search value(s) from the input item to compare against the filter text.
      */
     readStrings: ReadKeyFunction<T, string> | ReadMultipleKeysFunction<T, string>;
     /**
-     * (Optional) decision function factory for the input.
+     * Optional decision function factory for matching logic.
      *
-     * Defaults to caseInsensitiveFilterByIndexOfDecisionFactory() if not defined.
+     * Defaults to {@link caseInsensitiveFilterByIndexOfDecisionFactory} if not defined.
      */
     decisionFactory?: SearchStringDecisionFunctionFactory;
 }
+/**
+ * Input for creating a {@link SearchStringFilterFunction}. Can be a read function directly or a full config object.
+ *
+ * @template T - The type of values being filtered.
+ */
 export type SearchStringFilterFunctionConfigInput<T> = ReadKeyFunction<T, string> | ReadMultipleKeysFunction<T, string> | SearchStringFilterConfig<T>;
 /**
- * Creates a SearchStringFilterFunction
+ * Creates a {@link SearchStringFilterFunction} that filters values based on whether their string representation matches the filter text.
  *
- * @param config
- * @returns
+ * @param config - A read function or full configuration specifying how to extract and match search strings.
+ * @returns A function that filters an array of values by a search/filter text string.
  */
 export declare function searchStringFilterFunction<T>(config: SearchStringFilterFunctionConfigInput<T>): SearchStringFilterFunction<T>;
 /**
- * SearchStringDecisionFunctionFactory that searches for string matches using the input search term/filter text.
+ * Default {@link SearchStringDecisionFunctionFactory} that performs case-insensitive substring matching using `indexOf`.
  *
- * @param filterText
- * @returns
+ * @param filterText - The search term to match against.
+ * @returns A decision function that returns `true` if the input string contains the filter text (case-insensitive).
  */
 export declare const caseInsensitiveFilterByIndexOfDecisionFactory: SearchStringDecisionFunctionFactory;

package/src/lib/string/sort.d.ts

@@ -5,10 +5,19 @@ import { type ReadStringFunction } from './string';
  */
 export type SortByStringFunction<T> = SortCompareFunction<T>;
 /**
- * Creates a SortByStringFunction that sorts values in ascending order.
+ * Creates a {@link SortByStringFunction} that sorts values in ascending alphabetical order using `localeCompare`.
+ *
+ * @param readStringFn - Function to extract a string from each value for comparison.
+ * @returns A comparator function suitable for use with `Array.sort()`.
  */
 export declare function sortByStringFunction<T>(readStringFn: ReadStringFunction<T>): SortByStringFunction<T>;
+/**
+ * Input type for objects that can be sorted by their `label` property.
+ */
 export interface SortByLabelInput {
     label: string;
 }
+/**
+ * Pre-configured sort comparator that sorts objects by their `label` property in ascending alphabetical order.
+ */
 export declare const sortByLabelFunction: SortByStringFunction<SortByLabelInput>;

package/src/lib/string/string.d.ts

@@ -25,7 +25,16 @@ export type CommaSeparatedString<T = unknown> = string;
  * I.E. 0 1 2
  */
 export type SpaceSeparatedString<T = unknown> = string;
+/**
+ * Default comma joiner character used by comma-related string functions.
+ */
 export declare const COMMA_JOINER = ",";
+/**
+ * Converts a string to its lowercase equivalent for case-insensitive comparison.
+ *
+ * @param input - string to convert to lowercase
+ * @returns the lowercased string, or undefined if the input is undefined
+ */
 export declare function caseInsensitiveString(input: string): string;
 export declare function caseInsensitiveString(input: undefined): undefined;
 export declare function caseInsensitiveString(input: Maybe<string>): Maybe<string>;
@@ -57,40 +66,61 @@ export declare function joinStringsWithCommas(input: ArrayOrValue<Maybe<string>>
  */
 export declare function splitCommaSeparatedString(input: CommaSeparatedString<string>): string[];
 export declare function splitCommaSeparatedString<T = unknown>(input: CommaSeparatedString<T>, mapFn: MapStringFunction<T>): T[];
+/**
+ * Splits a comma-separated string into a Set of unique trimmed string values.
+ *
+ * @param input - comma-separated string to split, or null/undefined
+ * @returns a Set of unique string values; empty Set if input is null/undefined
+ */
 export declare function splitCommaSeparatedStringToSet(input: Maybe<CommaSeparatedString>): Set<string>;
 /**
  * Adds a plus prefix to the input value and converts it to a string. If the value is negative or 0, no prefix is added.
  *
  * Undefined is returned if a null/undefined value is input.
+ *
+ * @param value - the number to prefix
+ * @param prefix - the prefix character to use for positive numbers; defaults to '+'
+ * @returns the prefixed string, or undefined if the input is null/undefined
  */
 export declare function addPlusPrefixToNumber(value?: Maybe<number>, prefix?: string): string | undefined;
 /**
- * Capitalizes the first letter of the input.
+ * Capitalizes the first letter of the input string.
  *
- * @param value
- * @returns
+ * @param value - string to capitalize
+ * @returns the input string with its first character uppercased
  */
 export declare function capitalizeFirstLetter(value: string): string;
 /**
- * Lowercases the first letter of the input.
+ * Lowercases the first letter of the input string.
  *
- * @param value
- * @returns
+ * @param value - string to modify
+ * @returns the input string with its first character lowercased
  */
 export declare function lowercaseFirstLetter(value: string): string;
 /**
- * Performs split, but joins the remainder instead of discarding them.
+ * Splits a string like {@link String.prototype.split}, but joins overflow segments back together
+ * instead of discarding them. Useful when you only want to split on the first N-1 occurrences.
  *
- * @param input
+ * @param input - string to split
+ * @param separator - delimiter to split on
+ * @param limit - maximum number of resulting segments; overflow segments are rejoined with the separator
+ * @returns array of string segments, with length at most equal to limit
  */
 export declare function splitJoinRemainder(input: string, separator: string, limit: number): string[];
+/**
+ * A tuple of [firstName, lastName] where lastName may be undefined if the input has no space.
+ */
 export type FirstNameLastNameTuple = [string, string | undefined];
+/**
+ * Default space joiner character used by space-related string functions.
+ */
 export declare const SPACE_JOINER = " ";
 /**
- * Splits the input string like it is a name with a space separating the first and last name string.
+ * Splits the input string into a first name and last name tuple using a space as the delimiter.
+ * If the name contains more than one space, the remainder is treated as the last name.
  *
- * @param input
- * @returns
+ * @param input - full name string to split
+ * @returns a tuple of [firstName, lastName], where lastName includes all text after the first space
  */
 export declare function splitJoinNameString(input: string): FirstNameLastNameTuple;
 /**
@@ -102,13 +132,16 @@ export declare function splitJoinNameString(input: string): FirstNameLastNameTup
 export declare function joinStringsWithSpaces(input: MaybeNot): MaybeNot;
 export declare function joinStringsWithSpaces(input: ArrayOrValue<Maybe<string>>): string;
 /**
- * Creates a string that repeats the given character a number of times.
+ * Creates a string that repeats the given string a specified number of times.
  *
- * @param char
- * @param reapeat
- * @returns
+ * @param string - the string to repeat
+ * @param reapeat - number of times to repeat the string
+ * @returns the repeated string concatenation
  */
 export declare function repeatString(string: string, reapeat: number): string;
+/**
+ * Configuration for creating a {@link CutStringFunction}.
+ */
 export interface CutStringFunctionConfig {
     /**
      * Max length of the string.
@@ -127,23 +160,43 @@ export interface CutStringFunctionConfig {
      */
     readonly endText?: Maybe<string>;
 }
+/**
+ * Default ellipsis text appended when a string is truncated by {@link cutStringFunction}.
+ */
 export declare const DEFAULT_CUT_STRING_END_TEXT = "...";
+/**
+ * A function that truncates a string to a configured maximum length, optionally appending end text.
+ */
 export type CutStringFunction = ((input: string) => string) & ((input: Maybe<string>) => Maybe<string>);
+/**
+ * Creates a {@link CutStringFunction} that truncates strings exceeding the configured maximum length.
+ *
+ * @param config - configuration controlling max length and end text behavior
+ * @returns a reusable function that truncates input strings
+ */
 export declare function cutStringFunction(config: CutStringFunctionConfig): CutStringFunction;
+/**
+ * Truncates a string to the given maximum length, appending end text (defaults to "...") if truncated.
+ *
+ * @param input - the string to truncate, or null/undefined
+ * @param maxLength - maximum allowed length for the output string
+ * @param endText - text to append when truncated; defaults to "..."
+ * @returns the truncated string, or null/undefined if the input is null/undefined
+ */
 export declare function cutString(input: Maybe<string>, maxLength: number, endText?: Maybe<string>): Maybe<string>;
 /**
- * Replaces all whitespaces with a single space.
+ * Collapses consecutive whitespace characters (excluding newlines) into a single space, then trims.
  *
  * Newlines are preserved.
  *
- * @param input
- * @returns
+ * @param input - string to flatten
+ * @returns the string with collapsed whitespace
  */
 export declare function flattenWhitespace(input: string): string;
 /**
- * Reduces multiple newlines to a single newline and reduces multiple whitespaces to a single space.
+ * Reduces multiple consecutive newlines to a single newline and collapses multiple whitespace characters to a single space.
  *
- * @param input
- * @returns
+ * @param input - string to simplify
+ * @returns the string with simplified whitespace and newlines
  */
 export declare function simplifyWhitespace(input: string): string;

package/src/lib/string/transform.d.ts

@@ -97,6 +97,13 @@ export declare function transformStringFunctionConfig<S extends string = string>
  * @returns A `TransformStringFunction` that applies the configured transformations.
  */
 export declare function transformStringFunction<S extends string = string>(config: TransformStringFunctionConfig<S>): TransformStringFunction<S>;
+/**
+ * Adds a prefix to the input string if it does not already start with that prefix.
+ *
+ * @param prefix - The prefix to add.
+ * @param input - The string to modify.
+ * @returns The string with the prefix applied.
+ */
 export declare function addPrefix(prefix: string, input: string): string;
 /**
  * Function that adds a configured prefix to the input string if it does not exist on that string.

package/src/lib/string/tree.d.ts

@@ -1,13 +1,28 @@
 import { type ArrayOrValue } from '../array/array';
 import { type Maybe } from '../value/maybe.type';
 /**
- * A tree node
+ * A string value representing a node in a split string tree.
  */
 export type SplitStringTreeNodeString = string;
+/**
+ * The default value used for the root node of a split string tree.
+ */
 export declare const SPLIT_STRING_TREE_NODE_ROOT_VALUE = "";
+/**
+ * Map of child nodes in a split string tree, keyed by their node value.
+ *
+ * @template M - The type of metadata attached to tree nodes.
+ */
 export type SplitStringTreeChildren<M = unknown> = {
     [key: string]: SplitStringTree<M>;
 };
+/**
+ * A node in a tree structure built by splitting strings on a separator character.
+ *
+ * For example, splitting `"a/b/c"` on `"/"` produces a tree with nodes for `"a"`, `"b"`, and `"c"`.
+ *
+ * @template M - The type of metadata attached to tree nodes.
+ */
 export interface SplitStringTree<M = unknown> {
     /**
      * The full string value.
@@ -38,28 +53,69 @@ export interface SplitStringTree<M = unknown> {
      */
     readonly meta?: M;
 }
+/**
+ * A root-level split string tree containing only children (no own value).
+ *
+ * @template M - The type of metadata attached to tree nodes.
+ */
 export type SplitStringTreeRoot<M = unknown> = Pick<SplitStringTree<M>, 'children'>;
+/**
+ * Input for a {@link SplitStringTreeFactory}, specifying values to add and optional metadata.
+ *
+ * @template M - The type of metadata attached to tree nodes.
+ */
 export interface SplitStringTreeFactoryInput<M = unknown> extends Pick<AddToSplitStringTreeInputValueWithMeta<M>, 'leafMeta' | 'nodeMeta'> {
+    /** One or more string values to split and add to the tree. */
     readonly values: ArrayOrValue<SplitStringTreeNodeString>;
 }
+/**
+ * Factory function that builds or extends a {@link SplitStringTree} from string values split on a configured separator.
+ *
+ * @template M - The type of metadata attached to tree nodes.
+ */
 export type SplitStringTreeFactory<M = unknown> = ((input: SplitStringTreeFactoryInput<M>, existing?: Maybe<SplitStringTree<M>>) => SplitStringTree<M>) & {
     readonly _separator: string;
 };
+/**
+ * Configuration for a {@link SplitStringTreeFactory}.
+ *
+ * @template M - The type of metadata attached to tree nodes.
+ */
 export type SplitStringTreeFactoryConfig<M = unknown> = AddToSplitStringTreeInputConfig<M>;
 /**
- * Creates a SplitStringTreeFactory with the configured splitter.
+ * Creates a {@link SplitStringTreeFactory} that builds tree structures by splitting strings on the configured separator.
  *
- * @param config
- * @returns
+ * @param config - Configuration specifying the separator and optional metadata merge strategy.
+ * @returns A factory function that creates or extends split string trees.
  */
 export declare function splitStringTreeFactory<M = unknown>(config: SplitStringTreeFactoryConfig<M>): SplitStringTreeFactory<M>;
+/**
+ * Input for {@link applySplitStringTreeWithMultipleValues}.
+ *
+ * @template M - The type of metadata attached to tree nodes.
+ */
 export interface ApplySplitStringTreeWithMultipleValuesInput<M = unknown> {
+    /** The entries to add to the tree, each potentially with different metadata. */
     readonly entries: SplitStringTreeFactoryInput<M>[];
+    /** The factory to use for building the tree. */
     readonly factory: SplitStringTreeFactory<M>;
+    /** An optional existing tree to extend rather than creating a new one. */
     readonly existing?: SplitStringTree<M>;
 }
+/**
+ * Builds or extends a split string tree by applying multiple entry sets sequentially.
+ *
+ * @param input - The entries, factory, and optional existing tree.
+ * @returns The resulting split string tree with all entries applied.
+ */
 export declare function applySplitStringTreeWithMultipleValues<M = unknown>(input: ApplySplitStringTreeWithMultipleValuesInput<M>): SplitStringTree<M>;
+/**
+ * A value and optional metadata to add to a split string tree.
+ *
+ * @template M - The type of metadata attached to tree nodes.
+ */
 export interface AddToSplitStringTreeInputValueWithMeta<M = unknown> {
+    /** The string value to split and insert into the tree. */
     readonly value: SplitStringTreeNodeString;
     /**
      * The meta value to merge/attach to each node in the tree
@@ -70,7 +126,13 @@ export interface AddToSplitStringTreeInputValueWithMeta<M = unknown> {
      */
     readonly leafMeta?: M;
 }
+/**
+ * Configuration for splitting strings and adding them to a tree.
+ *
+ * @template M - The type of metadata attached to tree nodes.
+ */
 export interface AddToSplitStringTreeInputConfig<M = unknown> {
+    /** The separator character used to split string values into tree path segments. */
     readonly separator: string;
     /**
      * Used for merging the meta values of two nodes.
@@ -82,51 +144,51 @@ export interface AddToSplitStringTreeInputConfig<M = unknown> {
     readonly mergeMeta?: (current: M, next: M) => M;
 }
 /**
- * Adds a value to the target SplitStringTree.
+ * Adds a value to the target {@link SplitStringTree} by splitting it on the configured separator and inserting nodes along the path.
  *
- * @param tree
- * @param value
- * @param separator
- * @returns
+ * @param tree - The tree to add the value to.
+ * @param inputValue - The string value and optional metadata to insert.
+ * @param config - Configuration specifying the separator and optional metadata merge strategy.
+ * @returns The same tree instance with the new value added.
  */
 export declare function addToSplitStringTree<M = unknown>(tree: SplitStringTree<M>, inputValue: AddToSplitStringTreeInputValueWithMeta<M>, config: AddToSplitStringTreeInputConfig<M>): SplitStringTree<M>;
 /**
- * Returns the best match for the value in the tree, including the input tree value.
+ * Returns the deepest matching node for the value in the tree, including the input tree node itself.
  *
- * Only returns a result if there is match of any kind.
+ * Only returns a result if there is a match of any kind.
  *
- * @param tree
- * @param value
- * @returns
+ * @param tree - The tree to search.
+ * @param value - The string value to find a match for.
+ * @returns The best matching tree node, or `undefined` if no match is found.
  */
 export declare function findBestSplitStringTreeMatch<M = unknown>(tree: SplitStringTree<M>, value: SplitStringTreeNodeString): Maybe<SplitStringTree<M>>;
 /**
- * Returns the best match for the value in the true, excluding the input tree value.
+ * Returns the deepest matching child node for the value in the tree, excluding the input tree node itself.
  *
- * Only returns a result if there is match of any kind.
+ * Only returns a result if there is a match of any kind.
  *
- * @param tree
- * @param value
- * @returns
+ * @param tree - The tree to search.
+ * @param value - The string value to find a match for.
+ * @returns The best matching child tree node, or `undefined` if no match is found.
  */
 export declare function findBestSplitStringTreeChildMatch<M = unknown>(tree: SplitStringTree<M>, value: SplitStringTreeNodeString): Maybe<SplitStringTree<M>>;
 /**
- * Returns the best match for the value in the tree, including the input tree value.
+ * Returns the full path of matching nodes for the value in the tree, including the input tree node itself.
  *
- * Only returns a result if there is match of any kind.
+ * Only returns a result if there is a match of any kind.
  *
- * @param tree
- * @param value
- * @returns
+ * @param tree - The tree to search.
+ * @param value - The string value to find a match path for.
+ * @returns An array of tree nodes forming the match path from root to deepest match, or `undefined` if no match is found.
  */
 export declare function findBestSplitStringTreeMatchPath<M = unknown>(tree: SplitStringTree<M>, value: SplitStringTreeNodeString): Maybe<SplitStringTree<M>[]>;
 /**
- * Returns the best match for the value in the true, excluding the input tree value.
+ * Returns the full path of matching child nodes for the value in the tree, excluding the input tree node itself.
  *
- * Only returns a result if there is match of any kind.
+ * Only returns a result if there is a match of any kind.
  *
- * @param tree
- * @param value
- * @returns
+ * @param tree - The tree to search.
+ * @param value - The string value to find a match path for.
+ * @returns An array of child tree nodes forming the match path, or `undefined` if no match is found.
  */
 export declare function findBestSplitStringTreeChildMatchPath<M = unknown>(tree: SplitStringTree<M>, value: SplitStringTreeNodeString): Maybe<SplitStringTree<M>[]>;