@dereekb/util 13.11.14 → 13.11.15

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

@@ -21,14 +21,15 @@ export interface ReplaceStringsConfig {
 /**
  * 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 Performs the configured replacements on an input string.
+ *
  * @dbxUtil
  * @dbxUtilCategory string
  * @dbxUtilKind factory
  * @dbxUtilTags string, replace, regex, substitute, factory
  * @dbxUtilRelated find-strings-regex-string, escape-string-for-regex
  *
- * @param config - Configuration specifying strings to find and the replacement value.
- * @returns A function that performs the configured replacements on an input string.
  * @__NO_SIDE_EFFECTS__
  */
 export declare function replaceStringsFunction(config: ReplaceStringsConfig): (input: string) => string;
@@ -43,13 +44,13 @@ export declare const REGEX_SPECIAL_CHARACTERS_SET: Set<string>;
 /**
  * Creates an escaped regex string that matches any of the input values, joined with the OR (`|`) operator.
  *
+ * @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 `|`.
+ *
  * @dbxUtil
  * @dbxUtilCategory string
  * @dbxUtilTags string, regex, escape, alternation, pattern
  * @dbxUtilRelated escape-string-for-regex, replace-strings-function
- *
- * @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;
 /**
@@ -79,14 +80,15 @@ export type EscapeStringCharactersFunction = (input: string) => string;
 /**
  * Creates an {@link EscapeStringCharactersFunction} that escapes specific characters in a string using the configured escape strategy.
  *
+ * @param config - Configuration specifying which characters to escape and how to escape them.
+ * @returns Escapes the configured characters in any input string.
+ *
  * @dbxUtil
  * @dbxUtilCategory string
  * @dbxUtilKind factory
  * @dbxUtilTags string, escape, characters, factory, transform
  * @dbxUtilRelated escape-string-for-regex, find-all-character-occurences-function
  *
- * @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.
  * @__NO_SIDE_EFFECTS__
  */
 export declare function escapeStringCharactersFunction(config: EscapeStringCharactersFunctionConfig): EscapeStringCharactersFunction;
@@ -110,48 +112,49 @@ export declare const escapeStringForRegex: EscapeStringCharactersFunction;
  *
  * @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.
+ * @returns The 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 Finds all occurrences of the configured characters in an input string.
+ *
  * @dbxUtil
  * @dbxUtilCategory string
  * @dbxUtilKind factory
  * @dbxUtilTags string, search, characters, indices, factory, occurrences
  * @dbxUtilRelated find-all-character-occurences, find-first-character-occurence
  *
- * @param characterSet - The set of characters to search for.
- * @returns A function that finds all occurrences of the configured characters in an input string.
  * @__NO_SIDE_EFFECTS__
  */
 export declare function findAllCharacterOccurencesFunction(characterSet: Set<string>): FindAllCharacterOccurencesFunction;
 /**
  * Finds all indices of characters from the set that appear in the input string.
  *
+ * @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 The zero-based indices where matching characters were found.
+ *
  * @dbxUtil
  * @dbxUtilCategory string
  * @dbxUtilTags string, search, characters, indices, occurrences
  * @dbxUtilRelated find-all-character-occurences-function, find-first-character-occurence
- *
- * @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[];
 /**
  * Finds the index of the first occurrence of any character from the set in the input string.
  *
+ * @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.
+ *
  * @dbxUtil
  * @dbxUtilCategory string
  * @dbxUtilTags string, search, characters, first, index, occurrence
  * @dbxUtilRelated find-all-character-occurences, find-all-character-occurences-function
- *
- * @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>;
 /**
@@ -160,7 +163,7 @@ export declare function findFirstCharacterOccurence(set: Set<string>, input: str
  * The first element is the string before the split character(s).
  * The second element is the string after the split character(s), or is undefined if no split occured.
  */
-export type SplitStringAtFirstCharacterOccurenceResult = [string, string | undefined];
+export type SplitStringAtFirstCharacterOccurenceResult = [string, Maybe<string>];
 /**
  * Splits the input string at the configured split character(s).
  */
@@ -168,30 +171,31 @@ export type SplitStringAtFirstCharacterOccurenceFunction = (input: string) => Sp
 /**
  * Creates a function that splits a string into two parts at the first occurrence of any character in the configured set.
  *
+ * @param splitAt - A single character or set of characters to split on.
+ * @returns Splits input strings at the first matching character.
+ *
  * @dbxUtil
  * @dbxUtilCategory string
  * @dbxUtilKind factory
  * @dbxUtilTags string, split, characters, occurrence, factory
  * @dbxUtilRelated split-string-at-first-character-occurence, keep-characters-after-first-character-occurence-function
  *
- * @param splitAt - A single character or set of characters to split on.
- * @returns A function that splits input strings at the first matching character.
  * @__NO_SIDE_EFFECTS__
  */
 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.
+ *
  * @dbxUtil
  * @dbxUtilCategory string
  * @dbxUtilTags string, split, characters, occurrence, tuple
  * @dbxUtilRelated split-string-at-first-character-occurence-function, find-first-character-occurence
- *
- * @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];
+export declare function splitStringAtFirstCharacterOccurence(input: string, splitAt: string | Set<string>): [string, Maybe<string>];
 /**
  * Keeps all characters from the input string after the first character occurence pre-determined by the function.
  *
@@ -201,28 +205,29 @@ export type KeepCharactersAfterFirstCharacterOccurenceFunction = (input: string)
 /**
  * Creates a function that returns only the characters after the first occurrence of any character in the configured set.
  *
+ * @param findCharacters - A single character or set of characters to search for.
+ * @returns Extracts the substring after the first matching character, or an empty string if none found.
+ *
  * @dbxUtil
  * @dbxUtilCategory string
  * @dbxUtilKind factory
  * @dbxUtilTags string, keep, after, occurrence, factory, suffix
  * @dbxUtilRelated keep-characters-after-first-character-occurence, remove-characters-after-first-character-occurence-function
  *
- * @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.
  * @__NO_SIDE_EFFECTS__
  */
 export declare function keepCharactersAfterFirstCharacterOccurenceFunction(findCharacters: string | Set<string>): KeepCharactersAfterFirstCharacterOccurenceFunction;
 /**
  * Returns only the characters after the first occurrence of any character from the find set.
  *
+ * @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.
+ *
  * @dbxUtil
  * @dbxUtilCategory string
  * @dbxUtilTags string, keep, after, occurrence, suffix
  * @dbxUtilRelated keep-characters-after-first-character-occurence-function, remove-characters-after-first-character-occurence
- *
- * @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;
 /**
@@ -232,27 +237,28 @@ export type RemoveCharactersAfterFirstCharacterOccurenceFunction = (input: strin
 /**
  * Creates a function that removes all characters after (and including) the first occurrence of any character in the configured set.
  *
+ * @param findCharacters - A single character or set of characters to search for.
+ * @returns Truncates input strings at the first matching character.
+ *
  * @dbxUtil
  * @dbxUtilCategory string
  * @dbxUtilKind factory
  * @dbxUtilTags string, remove, truncate, occurrence, factory, prefix
  * @dbxUtilRelated remove-characters-after-first-character-occurence, keep-characters-after-first-character-occurence-function
  *
- * @param findCharacters - A single character or set of characters to search for.
- * @returns A function that truncates input strings at the first matching character.
  * @__NO_SIDE_EFFECTS__
  */
 export declare function removeCharactersAfterFirstCharacterOccurenceFunction(findCharacters: string | Set<string>): RemoveCharactersAfterFirstCharacterOccurenceFunction;
 /**
  * Removes all characters after (and including) the first occurrence of any character from the find set.
  *
+ * @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.
+ *
  * @dbxUtil
  * @dbxUtilCategory string
  * @dbxUtilTags string, remove, truncate, occurrence, prefix
  * @dbxUtilRelated remove-characters-after-first-character-occurence-function, keep-characters-after-first-character-occurence
- *
- * @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

@@ -17,13 +17,13 @@ export interface SearchStringFilterConfig<T> {
     /**
      * Reads the search value(s) from the input item to compare against the filter text.
      */
-    readStrings: ReadKeyFunction<T, string> | ReadMultipleKeysFunction<T, string>;
+    readonly readStrings: ReadKeyFunction<T, string> | ReadMultipleKeysFunction<T, string>;
     /**
      * Optional decision function factory for matching logic.
      *
      * Defaults to {@link caseInsensitiveFilterByIndexOfDecisionFactory} if not defined.
      */
-    decisionFactory?: SearchStringDecisionFunctionFactory;
+    readonly decisionFactory?: SearchStringDecisionFunctionFactory;
 }
 /**
  * Input for creating a {@link SearchStringFilterFunction}. Can be a read function directly or a full config object.
@@ -34,14 +34,15 @@ export type SearchStringFilterFunctionConfigInput<T> = ReadKeyFunction<T, string
 /**
  * Creates a {@link SearchStringFilterFunction} that filters values based on whether their string representation matches the filter text.
  *
+ * @param config - A read function or full configuration specifying how to extract and match search strings.
+ * @returns Filters an array of values by a search/filter text string.
+ *
  * @dbxUtil
  * @dbxUtilCategory string
  * @dbxUtilKind factory
  * @dbxUtilTags string, search, filter, factory, match, decision
  * @dbxUtilRelated case-insensitive-filter-by-index-of-decision-factory
  *
- * @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.
  * @__NO_SIDE_EFFECTS__
  */
 export declare function searchStringFilterFunction<T>(config: SearchStringFilterFunctionConfigInput<T>): SearchStringFilterFunction<T>;

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

@@ -11,9 +11,13 @@ export type SortByStringFunction<T> = SortCompareFunction<T>;
  * `(a, b) => a.localeCompare(b)` everywhere, and to satisfy the no-default-sort
  * lint rule for string arrays.
  *
+ * @param a - The first string to compare.
+ * @param b - The second string to compare.
+ * @returns A negative number when `a` sorts before `b`, positive when after, `0` when equal.
+ *
  * @dbxUtil
  * @dbxUtilCategory string
- * @dbxUtilKind comparator
+ * @dbxUtilKind const
  * @dbxUtilTags string, sort, compare, alphabetical, locale
  * @dbxUtilRelated compare-strings-numeric, sort-by-string-function
  *
@@ -28,9 +32,13 @@ export declare const compareStrings: SortByStringFunction<string>;
  * with the `numeric` collation option enabled, so numeric substrings are compared by value
  * (e.g. `"2"` sorts before `"10"`).
  *
+ * @param a - The first string to compare.
+ * @param b - The second string to compare.
+ * @returns A negative number when `a` sorts before `b`, positive when after, `0` when equal.
+ *
  * @dbxUtil
  * @dbxUtilCategory string
- * @dbxUtilKind comparator
+ * @dbxUtilKind const
  * @dbxUtilTags string, sort, compare, numeric, natural, locale
  * @dbxUtilRelated compare-strings, sort-by-string-function
  *
@@ -43,14 +51,15 @@ export declare const compareStringsNumeric: SortByStringFunction<string>;
 /**
  * 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()`.
+ *
  * @dbxUtil
  * @dbxUtilCategory string
  * @dbxUtilKind factory
  * @dbxUtilTags string, sort, compare, alphabetical, factory, locale
  * @dbxUtilRelated sort-by-label-function, compare-strings
  *
- * @param readStringFn - Function to extract a string from each value for comparison.
- * @returns A comparator function suitable for use with `Array.sort()`.
  * @__NO_SIDE_EFFECTS__
  */
 export declare function sortByStringFunction<T>(readStringFn: ReadStringFunction<T>): SortByStringFunction<T>;

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

@@ -58,15 +58,15 @@ export declare function joinStrings(input: ArrayOrValue<Maybe<string>>, joiner?:
  * 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 - 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.
+ *
  * @dbxUtil
  * @dbxUtilCategory string
  * @dbxUtilTags string, split, limit, separator, parts, segments
  * @dbxUtilRelated join-strings, string-split-join-instance
- *
- * @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[];
 /**
@@ -106,15 +106,15 @@ export interface JoinStringsInstanceConfig {
 /**
  * Creates a {@link JoinStringsInstance} that joins arrays of strings using the configured delimiter.
  *
+ * @param config - Configuration for the delimiter and default trim behavior.
+ * @returns A new callable {@link JoinStringsInstance}
+ *
  * @example
  * ```ts
  * const joinWithPipe = joinStringsInstance({ joiner: '|' });
  * joinWithPipe(['a', 'b']); // 'a|b'
  * joinWithPipe(null); // null
  * ```
- *
- * @param config - configuration for the delimiter and default trim behavior
- * @returns a new callable {@link JoinStringsInstance}
  */
 export declare function joinStringsInstance<T extends string = string>(config: JoinStringsInstanceConfig): JoinStringsInstance<T>;
 /**
@@ -163,15 +163,15 @@ export type StringSplitJoinInstanceConfig = JoinStringsInstanceConfig;
 /**
  * Creates a {@link StringSplitJoinInstance} that splits and joins strings using the configured delimiter.
  *
+ * @param config - Configuration for the delimiter and default trim behavior.
+ * @returns A new {@link StringSplitJoinInstance}
+ *
  * @example
  * ```ts
  * const pipeSplitJoin = stringSplitJoinInstance({ joiner: '|' });
  * pipeSplitJoin.joinStrings(['a', 'b']); // 'a|b'
  * pipeSplitJoin.splitStrings('a|b'); // ['a', 'b']
  * ```
- *
- * @param config - configuration for the delimiter and default trim behavior
- * @returns a new {@link StringSplitJoinInstance}
  */
 export declare function stringSplitJoinInstance<T extends string = string>(config: StringSplitJoinInstanceConfig): StringSplitJoinInstance<T>;
 /**
@@ -201,62 +201,62 @@ export declare function caseInsensitiveString(input: Maybe<string>): Maybe<strin
  *
  * 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
+ * @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;
+export declare function addPlusPrefixToNumber(value?: Maybe<number>, prefix?: string): Maybe<string>;
 /**
  * Capitalizes the first letter of the input string.
  *
+ * @param value - String to capitalize.
+ * @returns The input string with its first character uppercased.
+ *
  * @dbxUtil
  * @dbxUtilCategory string
  * @dbxUtilTags string, capitalize, case, uppercase, first
  * @dbxUtilRelated lowercase-first-letter, case-insensitive-string
- *
- * @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 string.
  *
+ * @param value - String to modify.
+ * @returns The input string with its first character lowercased.
+ *
  * @dbxUtil
  * @dbxUtilCategory string
  * @dbxUtilTags string, lowercase, case, first, decapitalize
  * @dbxUtilRelated capitalize-first-letter, case-insensitive-string
- *
- * @param value - string to modify
- * @returns the input string with its first character lowercased
  */
 export declare function lowercaseFirstLetter(value: string): string;
 /**
  * A tuple of [firstName, lastName] where lastName may be undefined if the input has no space.
  */
-export type FirstNameLastNameTuple = [string, string | undefined];
+export type FirstNameLastNameTuple = [string, Maybe<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 - Full name string to split.
+ * @returns A tuple of [firstName, lastName], where lastName includes all text after the first space.
+ *
  * @dbxUtil
  * @dbxUtilCategory string
  * @dbxUtilTags string, name, split, first, last, person, parse
  * @dbxUtilRelated split-join-remainder
- *
- * @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;
 /**
  * Creates a string that repeats the given string a specified number of times.
  *
+ * @param string - The string to repeat.
+ * @param reapeat - Number of times to repeat the string.
+ * @returns The repeated string concatenation.
+ *
  * @dbxUtil
  * @dbxUtilCategory string
  * @dbxUtilTags string, repeat, build, generate, fill
- *
- * @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;
 /**
@@ -285,34 +285,35 @@ export interface CutStringFunctionConfig {
  */
 export declare const DEFAULT_CUT_STRING_END_TEXT = "...";
 /**
- * A function that truncates a string to a configured maximum length, optionally appending end text.
+ * 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.
+ *
  * @dbxUtil
  * @dbxUtilCategory string
  * @dbxUtilKind factory
  * @dbxUtilTags string, cut, truncate, ellipsis, max-length, factory, abbreviate
  *
- * @param config - configuration controlling max length and end text behavior
- * @returns a reusable function that truncates input strings
  * @__NO_SIDE_EFFECTS__
  */
 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.
+ *
  * @dbxUtil
  * @dbxUtilCategory string
  * @dbxUtilTags string, cut, truncate, ellipsis, max-length, abbreviate, shorten
  * @dbxUtilRelated cut-string-function
- *
- * @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>;
 /**
@@ -320,25 +321,25 @@ export declare function cutString(input: Maybe<string>, maxLength: number, endTe
  *
  * Newlines are preserved.
  *
+ * @param input - String to flatten.
+ * @returns The string with collapsed whitespace.
+ *
  * @dbxUtil
  * @dbxUtilCategory string
  * @dbxUtilTags string, whitespace, flatten, collapse, normalize, trim
  * @dbxUtilRelated simplify-whitespace
- *
- * @param input - string to flatten
- * @returns the string with collapsed whitespace
  */
 export declare function flattenWhitespace(input: string): string;
 /**
  * Reduces multiple consecutive newlines to a single newline and collapses multiple whitespace characters to a single space.
  *
+ * @param input - String to simplify.
+ * @returns The string with simplified whitespace and newlines.
+ *
  * @dbxUtil
  * @dbxUtilCategory string
  * @dbxUtilTags string, whitespace, simplify, normalize, newline, trim
  * @dbxUtilRelated flatten-whitespace
- *
- * @param input - string to simplify
- * @returns the string with simplified whitespace and newlines
  */
 export declare function simplifyWhitespace(input: string): string;
 /**