@dereekb/util 13.11.14 → 13.11.15

package/src/lib/array/array.index.d.ts

@@ -23,17 +23,17 @@ export interface IndexSetPair<T> extends IndexRef {
 /**
  * Runs a filter on an array and returns an {@link IndexSet} containing the indices of values that match.
  *
- * @param input - array to search through
- * @param filter - predicate function to test each value
- * @returns an {@link IndexSet} of indices for matching values
+ * @param input - Array to search through.
+ * @param filter - Predicate function to test each value.
+ * @returns An {@link IndexSet} of indices for matching values.
  */
 export declare function findToIndexSet<T>(input: T[], filter: (value: T) => boolean): IndexSet;
 /**
  * Expands an {@link IndexSet} into an {@link IndexSetPairSet} by pairing each index with the corresponding item from the input array.
  *
- * @param input - source array to retrieve items from
- * @param indexSet - set of indices to expand
- * @returns an {@link IndexSetPairSet} pairing each index with its corresponding item
+ * @param input - Source array to retrieve items from.
+ * @param indexSet - Set of indices to expand.
+ * @returns An {@link IndexSetPairSet} pairing each index with its corresponding item.
  */
 export declare function expandIndexSet<T>(input: T[], indexSet: IndexSet): IndexSetPairSet<T>;
 /**
@@ -42,9 +42,9 @@ export declare function expandIndexSet<T>(input: T[], indexSet: IndexSet): Index
  * The comparison follows ascending sort conventions: a negative return value from the compare function
  * indicates the second argument is "better" than the first.
  *
- * @param input - array of items to search through
- * @param compare - comparison function used to determine the best item
- * @returns an {@link IndexSetPair} containing the best item and its index
+ * @param input - Array of items to search through.
+ * @param compare - Comparison function used to determine the best item.
+ * @returns An {@link IndexSetPair} containing the best item and its index.
  */
 export declare function findBest<T>(input: T[], compare: (a: T, b: T) => number): IndexSetPair<T>;
 /**
@@ -52,9 +52,9 @@ export declare function findBest<T>(input: T[], compare: (a: T, b: T) => number)
  *
  * Pairs with null/undefined items are skipped in favor of pairs with defined items.
  *
- * @param input - set of index-item pairs to search through
- * @param compare - ascending sort comparison function used to determine the best item
- * @returns the {@link IndexSetPair} containing the best item
+ * @param input - Set of index-item pairs to search through.
+ * @param compare - Ascending sort comparison function used to determine the best item.
+ * @returns The {@link IndexSetPair} containing the best item.
  */
 export declare function findBestIndexSetPair<T>(input: IndexSetPairSet<T>, compare: AscendingSortCompareFunction<T>): IndexSetPair<T>;
 /**
@@ -67,14 +67,15 @@ export type SliceIndexRangeFunction<T> = (input: T[]) => T[];
 /**
  * Creates a {@link SliceIndexRangeFunction} that slices the specified index range from any input array.
  *
+ * @param inputRange - Range boundaries to bake into the returned slicer.
+ * @returns Reusable slicer that extracts the configured range from any input array.
+ *
  * @dbxUtil
  * @dbxUtilCategory array
  * @dbxUtilKind factory
  * @dbxUtilTags array, slice, index, range, factory
  * @dbxUtilRelated index-range, find-to-index-set
  *
- * @param inputRange - the index range configuration to use for slicing
- * @returns a function that slices the configured range from an input array
  * @__NO_SIDE_EFFECTS__
  */
 export declare function sliceIndexRangeFunction<T>(inputRange: IndexRangeInput): SliceIndexRangeFunction<T>;

package/src/lib/array/array.indexed.d.ts

@@ -4,18 +4,18 @@ import { type ArrayFindDecisionFunction } from './array.find';
 /**
  * Creates an IndexRange for the input array, spanning from index 0 to the array's length.
  *
- * @param array - The array to create an index range for.
- * @returns An IndexRange covering the full extent of the array.
+ * @param array - Source whose length defines the maxIndex boundary.
+ * @returns Range pair spanning index 0 through the array's length.
  */
 export declare function indexRangeForArray<T>(array: T[]): IndexRange;
 /**
  * Finds a value in the array using the provided decision function, then returns the value at the next index.
  *
- * @param array - The array to search through, or undefined/null.
- * @param find - Decision function used to locate the target element.
- * @param wrapAround - Whether to wrap around to the beginning of the array if the found value is at or near the last index.
- * @param steps - Number of steps forward from the found index. Defaults to 1.
- * @returns The value at the next index, or undefined if no match is found or no next value exists.
+ * @param array - Source to scan; nullish input short-circuits with undefined.
+ * @param find - Predicate that locates the anchor element to step from.
+ * @param wrapAround - When true, stepping past the end resumes from index 0.
+ * @param steps - Forward step count from the matched element; defaults to 1.
+ * @returns Element after the anchor, or undefined when the anchor or its step target falls outside the array.
  */
 export declare function findNext<T>(array: Maybe<T[]>, find: ArrayFindDecisionFunction<T>, wrapAround?: boolean, steps?: number): Maybe<T>;
 /**
@@ -26,11 +26,11 @@ export declare function findNext<T>(array: Maybe<T[]>, find: ArrayFindDecisionFu
  * When wrapAround is true, indexes that are larger than the entire array will be used to find an index that is that many steps into the array.
  * For instance, an index of 5 on an array of length 3 will return the index 1.
  *
- * @param array - The array to compute the next index within.
- * @param index - The current index to step from.
- * @param wrapAround - Whether to wrap around when stepping past the end of the array.
- * @param steps - Number of steps forward from the current index.
- * @returns The computed next index, or undefined if the input index is out of bounds.
+ * @param array - Source whose bounds anchor the step computation.
+ * @param index - Current position from which to advance.
+ * @param wrapAround - When true, stepping past the end resumes from index 0.
+ * @param steps - Forward step count from the current index.
+ * @returns Stepped index when `index` is inside the array; otherwise undefined.
  */
 export declare function getArrayNextIndex<T>(array: T[], index: number, wrapAround?: boolean, steps?: number): Maybe<number>;
 /**
@@ -46,14 +46,15 @@ export type RangedIndexedValuesArrayAccessorFactory<T> = (values: T[]) => Ranged
  *
  * Each accessor maps an index to the value whose range contains that index, or undefined if no range matches.
  *
+ * @param readIndexRange - Function that reads the index range from each value.
+ * @returns A factory that creates ranged accessors from arrays of values.
+ *
  * @dbxUtil
  * @dbxUtilCategory array
  * @dbxUtilKind factory
  * @dbxUtilTags array, indexed, range, accessor, factory, lookup
  * @dbxUtilRelated indexed-values-array-accessor-factory, ranged-indexed-values-array-accessor-info-factory
  *
- * @param readIndexRange - Function that reads the index range from each value.
- * @returns A factory that creates ranged accessors from arrays of values.
  * @__NO_SIDE_EFFECTS__
  */
 export declare function rangedIndexedValuesArrayAccessorFactory<T>(readIndexRange: ReadIndexRangeFunction<T>): RangedIndexedValuesArrayAccessorFactory<T>;
@@ -71,15 +72,16 @@ export type IndexedValuesArrayAccessorFactory<T> = (values: T[]) => IndexedValue
  * Each accessor maps an index to the matching value, falling back to the previous value, then the next value.
  * This guarantees a value is always returned.
  *
+ * @param readIndexRange - Function that reads the index range from each value.
+ * @returns A factory that creates indexed accessors from arrays of values.
+ * @throws {Error} If the provided values array is empty.
+ *
  * @dbxUtil
  * @dbxUtilCategory array
  * @dbxUtilKind factory
  * @dbxUtilTags array, indexed, range, accessor, factory, fallback
  * @dbxUtilRelated ranged-indexed-values-array-accessor-factory, ranged-indexed-values-array-accessor-info-factory
  *
- * @param readIndexRange - Function that reads the index range from each value.
- * @returns A factory that creates indexed accessors from arrays of values.
- * @throws Error if the provided values array is empty.
  * @__NO_SIDE_EFFECTS__
  */
 export declare function indexedValuesArrayAccessorFactory<T>(readIndexRange: ReadIndexRangeFunction<T>): IndexedValuesArrayAccessorFactory<T>;
@@ -123,14 +125,15 @@ export interface RangedIndexedValuesArrayInfoAccessorFactoryConfig<T> {
  * Each accessor sorts the values by their index ranges in ascending order, then for a given index
  * returns the matching value along with its previous and next neighbors.
  *
+ * @param config - Configuration containing the index range reader function.
+ * @returns A factory that creates ranged info accessors from arrays of values.
+ *
  * @dbxUtil
  * @dbxUtilCategory array
  * @dbxUtilKind factory
  * @dbxUtilTags array, indexed, range, accessor, info, factory, neighbors
  * @dbxUtilRelated ranged-indexed-values-array-accessor-factory, indexed-values-array-accessor-factory
  *
- * @param config - Configuration containing the index range reader function.
- * @returns A factory that creates ranged info accessors from arrays of values.
  * @__NO_SIDE_EFFECTS__
  */
 export declare function rangedIndexedValuesArrayAccessorInfoFactory<T>(config: RangedIndexedValuesArrayInfoAccessorFactoryConfig<T>): RangedIndexedValuesArrayInfoAccessorFactory<T>;

package/src/lib/array/array.make.d.ts

@@ -23,14 +23,15 @@ export type RandomArrayFactory<T> = FactoryWithInput<T[], number>;
 /**
  * Creates a factory function that generates arrays of a random length populated with items from a make function.
  *
+ * @param config - Configuration containing the make function and random number source.
+ * @returns A factory that produces arrays of random length, optionally accepting a specific count override.
+ *
  * @dbxUtil
  * @dbxUtilCategory array
  * @dbxUtilKind factory
  * @dbxUtilTags array, random, factory, generate, make
  * @dbxUtilRelated array-factory, random-number-factory
  *
- * @param config - configuration containing the make function and random number source
- * @returns a factory that produces arrays of random length, optionally accepting a specific count override
  * @__NO_SIDE_EFFECTS__
  */
 export declare function randomArrayFactory<T>(config: RandomArrayFactoryConfig<T>): RandomArrayFactory<T>;

package/src/lib/array/array.map.d.ts

@@ -27,10 +27,10 @@ export declare function arrayToObject<T, K extends PrimativeKey = PrimativeKey>(
 /**
  * Returns values for each key, reusing existing items when available and generating new ones for missing keys.
  *
- * @param keys - the keys to resolve values for
- * @param existing - array of pre-existing items to check against
- * @param readKey - function to extract a key from an existing item
- * @param generateFn - function to create a new item for a key not found in existing items
- * @returns an array of items corresponding to each input key, in the same order
+ * @param keys - The keys to resolve values for.
+ * @param existing - Array of pre-existing items to check against.
+ * @param readKey - Function to extract a key from an existing item.
+ * @param generateFn - Function to create a new item for a key not found in existing items.
+ * @returns Items aligned to `keys` — reused when present in `existing`, generated otherwise.
  */
 export declare function generateIfDoesNotExist<T, K extends PrimativeKey = PrimativeKey>(keys: K[], existing: T[], readKey: ReadKeyFunction<T, K>, generateFn: (key: K) => T): T[];

package/src/lib/array/array.number.d.ts

@@ -3,55 +3,55 @@ import { type IndexRange } from '../value/indexed';
 /**
  * Reduces an array of numbers to its maximum value.
  *
- * @param array - numbers to evaluate
- * @param emptyArrayValue - value to return when the array is empty
- * @returns the maximum number in the array, or the empty array value if the array is empty
+ * @param array - Numbers to evaluate.
+ * @param emptyArrayValue - Value to return when the array is empty.
+ * @returns The maximum number in the array, or the empty array value if the array is empty.
  */
-export declare function reduceNumbersWithMax(array: number[], emptyArrayValue?: number): number | undefined;
+export declare function reduceNumbersWithMax(array: number[], emptyArrayValue?: number): Maybe<number>;
 /**
  * Creates a reducer function that finds the maximum value in a number array.
  *
- * @param emptyArrayValue - value to return when the array is empty
- * @returns a function that reduces a number array to its maximum value
+ * @param emptyArrayValue - Value to return when the array is empty.
+ * @returns Reducer that, given a number array, yields its maximum value (or the empty-array fallback).
  */
-export declare function reduceNumbersWithMaxFn(emptyArrayValue?: number): (array: number[]) => number | undefined;
+export declare function reduceNumbersWithMaxFn(emptyArrayValue?: number): (array: number[]) => Maybe<number>;
 /**
  * Reduces an array of numbers to its minimum value.
  *
- * @param array - numbers to evaluate
- * @param emptyArrayValue - value to return when the array is empty
- * @returns the minimum number in the array, or the empty array value if the array is empty
+ * @param array - Numbers to evaluate.
+ * @param emptyArrayValue - Value to return when the array is empty.
+ * @returns The minimum number in the array, or the empty array value if the array is empty.
  */
-export declare function reduceNumbersWithMin(array: number[], emptyArrayValue?: number): number | undefined;
+export declare function reduceNumbersWithMin(array: number[], emptyArrayValue?: number): Maybe<number>;
 /**
  * Creates a reducer function that finds the minimum value in a number array.
  *
- * @param emptyArrayValue - value to return when the array is empty
- * @returns a function that reduces a number array to its minimum value
+ * @param emptyArrayValue - Value to return when the array is empty.
+ * @returns Reducer that, given a number array, yields its minimum value (or the empty-array fallback).
  */
-export declare function reduceNumbersWithMinFn(emptyArrayValue?: number): (array: number[]) => number | undefined;
+export declare function reduceNumbersWithMinFn(emptyArrayValue?: number): (array: number[]) => Maybe<number>;
 /**
  * Reduces an array of numbers by summing all values.
  *
- * @param array - numbers to sum
- * @param emptyArrayValue - value to return when the array is empty; defaults to 0
- * @returns the sum of all numbers in the array
+ * @param array - Numbers to sum.
+ * @param emptyArrayValue - Value to return when the array is empty; defaults to 0.
+ * @returns The sum of all numbers in the array.
  */
 export declare function reduceNumbersWithAdd(array: number[], emptyArrayValue?: number): number;
 /**
  * Creates a reducer function that sums all values in a number array.
  *
- * @param emptyArrayValue - value to return when the array is empty; defaults to 0
- * @returns a function that reduces a number array to the sum of its values
+ * @param emptyArrayValue - Value to return when the array is empty; defaults to 0.
+ * @returns Reducer that, given a number array, yields the running sum across all entries.
  */
 export declare function reduceNumbersWithAddFn(emptyArrayValue?: number): (array: number[]) => number;
 /**
  * Reduces an array of numbers using a custom reducer function.
  *
- * @param reduceFn - binary function applied to successive pairs of numbers
- * @param array - numbers to reduce
- * @param emptyArrayValue - value to return when the array is empty
- * @returns the reduced result, or the empty array value if the array is empty
+ * @param reduceFn - Binary function applied to successive pairs of numbers.
+ * @param array - Numbers to reduce.
+ * @param emptyArrayValue - Value to return when the array is empty.
+ * @returns The reduced result, or the empty array value if the array is empty.
  */
 export declare function reduceNumbers(reduceFn: (a: number, b: number) => number, array: number[], emptyArrayValue?: number): Maybe<number>;
 /**
@@ -61,7 +61,7 @@ export declare function reduceNumbers(reduceFn: (a: number, b: number) => number
  * @param emptyArrayValue - value to return when the array is empty
  * @returns a function that reduces a number array to a single value
  */
-export declare function reduceNumbersFn(reduceFn: (a: number, b: number) => number): (array: number[]) => number | undefined;
+export declare function reduceNumbersFn(reduceFn: (a: number, b: number) => number): (array: number[]) => Maybe<number>;
 export declare function reduceNumbersFn<D extends number>(reduceFn: (a: number, b: number) => number, emptyArrayValue?: D): (array: number[]) => number | D;
 /**
  * Exclusive end value used by range().
@@ -92,8 +92,8 @@ export type RangeInput = number | RangeInputObject | IndexRange;
  * Generates an array containing the range of numbers specified. The end value is excluded.
  * Supports ascending and descending ranges.
  *
- * @param input - range specification as a number, {@link RangeInputObject}, or {@link IndexRange}; when a number and `inputEnd` is provided, acts as the start value
- * @param inputEnd - optional exclusive end value when `input` is a number
- * @returns an array of sequential numbers within the specified range
+ * @param input - Range specification as a number, {@link RangeInputObject}, or {@link IndexRange}; when a number and `inputEnd` is provided, acts as the start value.
+ * @param inputEnd - Optional exclusive end value when `input` is a number.
+ * @returns Sequential numbers covering the requested span, ordered ascending or descending as the bounds imply.
  */
 export declare function range(input: RangeInput, inputEnd?: RangeInputEndValue): number[];

package/src/lib/array/array.random.d.ts

@@ -11,40 +11,41 @@ export type RandomPickFactory<T> = (() => T) & {
 /**
  * Creates a {@link RandomPickFactory} from the input values.
  *
+ * @param values - Array of values to randomly pick from.
+ * @returns A callable factory that returns a random value from the array on each invocation.
+ * @throws {Error} If the input array is empty.
+ *
  * @dbxUtil
  * @dbxUtilCategory array
  * @dbxUtilKind factory
  * @dbxUtilTags array, random, pick, sample, choose, factory
  * @dbxUtilRelated pick-one-randomly, random-array-index
  *
- * @param values - array of values to randomly pick from
- * @returns a callable factory that returns a random value from the array on each invocation
- * @throws Error if the input array is empty
  * @__NO_SIDE_EFFECTS__
  */
 export declare function randomPickFactory<T>(values: T[]): RandomPickFactory<T>;
 /**
  * Returns a random index from the input array. Returns 0 if the array is empty.
  *
+ * @param values - Array to generate a random index for.
+ * @returns A random valid index within the array, or 0 if the array is empty.
+ *
  * @dbxUtil
  * @dbxUtilCategory array
  * @dbxUtilTags array, random, index, position
  * @dbxUtilRelated pick-one-randomly, random-pick-factory
- *
- * @param values - array to generate a random index for
- * @returns a random valid index within the array, or 0 if the array is empty
  */
 export declare function randomArrayIndex<T>(values: T[]): IndexNumber;
 /**
  * Picks a single item randomly from the input array.
  *
+ * @param values - Array to pick a random item from.
+ * @returns A randomly selected item from the array.
+ * @throws {Error} If the input array is empty.
+ *
  * @dbxUtil
  * @dbxUtilCategory array
  * @dbxUtilTags array, random, pick, sample, choose
  * @dbxUtilRelated random-pick-factory, random-array-index
- *
- * @param values - array to pick a random item from
- * @returns a randomly selected item from the array
- * @throws Error if the input array is empty
  */
 export declare function pickOneRandomly<T>(values: T[]): T;

package/src/lib/array/array.set.d.ts

@@ -1,50 +1,50 @@
 /**
  * Returns items that exist in both arrays (intersection).
  *
+ * @param values - Source whose entries are kept only when present in the second array.
+ * @param secondArray - Allowed-values gate used for the intersection check.
+ * @returns Intersection of `values` and `secondArray`, ordered like `values`.
+ *
  * @dbxUtil
  * @dbxUtilCategory array
  * @dbxUtilTags array, set, intersection, intersect, keep, common, both
  * @dbxUtilRelated exclude-values-from-array
- *
- * @param values - The source array to filter.
- * @param secondArray - The array of values to keep.
- * @returns A new array containing only the values from `values` that also exist in `secondArray`.
  */
 export declare function keepValuesFromArray<T>(values: T[], secondArray: T[]): T[];
 /**
  * Returns items from the first array that do not exist in the second array (difference).
  *
+ * @param values - Source whose entries are kept only when absent from the second array.
+ * @param secondArray - Excluded-values gate used for the difference check.
+ * @returns Set difference `values \ secondArray`, ordered like `values`.
+ *
  * @dbxUtil
  * @dbxUtilCategory array
  * @dbxUtilTags array, set, difference, exclude, subtract, diff
  * @dbxUtilRelated keep-values-from-array
- *
- * @param values - The source array to filter.
- * @param secondArray - The array of values to exclude.
- * @returns A new array containing only the values from `values` that do not exist in `secondArray`.
  */
 export declare function excludeValuesFromArray<T>(values: T[], secondArray: T[]): T[];
 /**
  * Checks whether the given array contains any duplicate values.
  *
+ * @param values - Source to scan for any repeated entry.
+ * @returns True when at least one value appears more than once; otherwise false.
+ *
  * @dbxUtil
  * @dbxUtilCategory array
  * @dbxUtilTags array, duplicate, check, validation, set
  * @dbxUtilRelated find-index-of-first-duplicate-value, unique
- *
- * @param values - The array to check for duplicates.
- * @returns `true` if the array contains at least one duplicate value, `false` otherwise.
  */
 export declare function arrayContainsDuplicateValue<T>(values: T[]): boolean;
 /**
  * Finds the index of the first duplicate value in the given array.
  *
+ * @param values - Source to scan left-to-right for the first repeat.
+ * @returns Index of the first value that matches an earlier one, or `-1` when all values are unique.
+ *
  * @dbxUtil
  * @dbxUtilCategory array
  * @dbxUtilTags array, duplicate, find, index, search
  * @dbxUtilRelated array-contains-duplicate-value, unique
- *
- * @param values - The array to search for duplicates.
- * @returns The index of the first value that is a duplicate of an earlier value, or `-1` if no duplicates exist.
  */
 export declare function findIndexOfFirstDuplicateValue<T>(values: T[]): number;

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

@@ -5,9 +5,9 @@ import { type TransformStringFunctionConfig } from '../string/transform';
 /**
  * Compares two string arrays and returns whether they contain different values, ignoring case.
  *
- * @param a - first array of strings to compare
- * @param b - second array of strings to compare
- * @returns `true` if the arrays contain different values when compared case-insensitively
+ * @param a - First array of strings to compare.
+ * @param b - Second array of strings to compare.
+ * @returns `true` if the arrays contain different values when compared case-insensitively.
  */
 export declare function hasDifferentStringsNoCase(a: string[], b: string[]): boolean;
 /**
@@ -39,74 +39,74 @@ export type TransformStringsFunction = MapFunction<string[], string[]>;
  * Creates a {@link TransformStringsFunction} from the given configuration. If the configuration results
  * in an identity transform, the returned function will be an identity function.
  *
- * @param config - configuration describing the string transformations to apply
- * @returns a function that applies the configured transformations to an array of strings
+ * @param config - Configuration describing the string transformations to apply.
+ * @returns Operator that runs the configured per-string transform across every element, returning an identity transform when no rewriting is needed.
  */
 export declare function transformStrings(config: TransformStringFunctionConfig): TransformStringsFunction;
 /**
  * Converts an iterable of strings to a lowercase string array for case-insensitive operations.
  *
- * @param values - iterable of strings to convert
- * @returns an array of lowercase strings
+ * @param values - Iterable of strings to convert.
+ * @returns Lower-cased materialization suitable for case-insensitive comparisons.
  */
 export declare function toCaseInsensitiveStringArray(values: Iterable<string>): string[];
 /**
  * Returns an array of unique strings from the input, compared case-insensitively. All returned strings are lowercase.
  *
- * @param values - iterable of strings to deduplicate
- * @returns an array of unique lowercase strings
+ * @param values - Iterable of strings to deduplicate.
+ * @returns Deduped lower-cased values preserving first-seen order.
  */
 export declare function uniqueCaseInsensitiveStrings(values: Iterable<string>): string[];
 /**
  * Returns a {@link Set} of unique lowercase strings from the input, compared case-insensitively.
  *
- * @param values - iterable of strings to deduplicate
- * @returns a set of unique lowercase strings
+ * @param values - Iterable of strings to deduplicate.
+ * @returns Membership-only collection of the deduped lower-cased values.
  */
 export declare function uniqueCaseInsensitiveStringsSet(values: Iterable<string>): Set<string>;
 /**
  * Flattens a two-dimensional array of strings into a single array of unique lowercase strings, compared case-insensitively.
  *
- * @param array - two-dimensional array of strings to flatten and deduplicate
- * @returns a flat array of unique lowercase strings
+ * @param array - Two-dimensional array of strings to flatten and deduplicate.
+ * @returns Single-dimension deduped lower-cased values drawn from every nested row.
  */
 export declare function flattenArrayUniqueCaseInsensitiveStrings(array: string[][]): string[];
 /**
  * Filters an array of models to only include items with unique keys when compared case-insensitively.
  * Items whose keys match the additional keys are also excluded.
  *
- * @param models - array of models to filter
- * @param readKey - function that extracts the string key from each model
- * @param additionalKeys - optional keys to treat as already seen, excluding models with matching keys
- * @returns the filtered array of models with unique case-insensitive keys
+ * @param models - Array of models to filter.
+ * @param readKey - Function that extracts the string key from each model.
+ * @param additionalKeys - Optional keys to treat as already seen, excluding models with matching keys.
+ * @returns The filtered array of models with unique case-insensitive keys.
  */
 export declare function filterUniqueCaseInsensitiveStrings<T, K extends string = string>(models: T[], readKey: ReadKeyFunction<T, K>, additionalKeys?: K[]): T[];
 /**
  * Checks whether the given iterable contains the specified string, ignoring case.
  *
- * @param values - iterable of strings to search
- * @param valueToFind - the string to search for
- * @param mustContainAtleastOneItem - if `true`, returns `false` when the values iterable is empty
- * @returns `true` if the string is found case-insensitively
+ * @param values - Iterable of strings to search.
+ * @param valueToFind - Value to search for, compared case-insensitively.
+ * @param mustContainAtleastOneItem - If `true`, returns `false` when the values iterable is empty.
+ * @returns `true` if the string is found case-insensitively.
  */
 export declare function containsStringAnyCase(values: Iterable<string>, valueToFind: string, mustContainAtleastOneItem?: boolean): boolean;
 /**
  * Checks whether the given iterable contains any of the specified strings, ignoring case.
  *
- * @param values - iterable of strings to search
- * @param valuesToFind - iterable of strings to search for
- * @param mustContainAtleastOneItem - if `true`, returns `false` when the values iterable is empty
- * @returns `true` if at least one of the strings is found case-insensitively
+ * @param values - Iterable of strings to search.
+ * @param valuesToFind - Iterable of strings to search for.
+ * @param mustContainAtleastOneItem - If `true`, returns `false` when the values iterable is empty.
+ * @returns `true` if at least one of the strings is found case-insensitively.
  */
 export declare function containsAnyStringAnyCase(values: Iterable<string>, valuesToFind: Iterable<string>, mustContainAtleastOneItem?: boolean): boolean;
 /**
  * Checks whether the given iterable contains all of the specified strings, ignoring case.
  * Returns `true` if there are no strings to find.
  *
- * @param values - iterable of strings to search
- * @param valuesToFind - iterable of strings that must all be present
- * @param mustContainAtleastOneItem - if `true`, returns `false` when the values iterable is empty
- * @returns `true` if all of the strings are found case-insensitively
+ * @param values - Iterable of strings to search.
+ * @param valuesToFind - Iterable of strings that must all be present.
+ * @param mustContainAtleastOneItem - If `true`, returns `false` when the values iterable is empty.
+ * @returns `true` if all of the strings are found case-insensitively.
  */
 export declare function containsAllStringsAnyCase(values: Iterable<string>, valuesToFind: Iterable<string>, mustContainAtleastOneItem?: boolean): boolean;
 /**
@@ -133,7 +133,7 @@ export type FilterUniqueTransform = TransformStringsFunction;
  * When `caseInsensitive` is enabled, uniqueness is determined before transformation; otherwise, transformation
  * is applied first and then duplicates are removed.
  *
- * @param config - configuration describing transformation, uniqueness comparison, and exclusions
- * @returns a function that transforms and deduplicates an input array of strings
+ * @param config - Configuration describing transformation, uniqueness comparison, and exclusions.
+ * @returns Operator that transforms then dedupes an input array per the supplied configuration.
  */
 export declare function filterUniqueTransform(config: FilterUniqueStringsTransformConfig): FilterUniqueTransform;