@dereekb/util 13.0.7 → 13.2.0

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

@@ -4,57 +4,161 @@ import { type PrimativeKey, type ReadKeyFunction } from '../key';
 import { type SetIncludesMode } from './set.mode';
 import { type DecisionFunction } from '../value/decision';
 import { type MapFunction } from '../value/map';
+/**
+ * Represents a selection that is either everything or nothing.
+ */
 export type AllOrNoneSelection = 'all' | 'none';
+/**
+ * Converts an {@link IterableOrValue} into a Set. Strings are treated as single values rather than character iterables.
+ *
+ * @param values - The value or iterable to convert.
+ * @returns A new Set containing all values.
+ */
 export declare function asSet<T>(values: IterableOrValue<T>): Set<T>;
+/**
+ * Creates a copy of the set, applies the given function to the copy, and returns it.
+ *
+ * @param set - The set to copy, or null/undefined for an empty set.
+ * @param fn - A function to mutate the copied set.
+ * @returns The modified copy of the set.
+ */
 export declare function copySetAndDo<T>(set: Maybe<Set<T>>, fn: (set: Set<T>) => void): Set<T>;
+/**
+ * Creates a copy of the set with the given values added.
+ *
+ * @param set - The set to copy, or null/undefined for an empty set.
+ * @param values - The values to add to the copy.
+ * @returns A new Set with the values added.
+ */
 export declare function addToSetCopy<T>(set: Maybe<Set<T>>, values: Maybe<IterableOrValue<T>>): Set<T>;
+/**
+ * Adds one or more values to the given set in place.
+ *
+ * @param set - The set to add values to.
+ * @param values - The value or iterable of values to add.
+ */
 export declare function addToSet<T>(set: Set<T>, values: Maybe<IterableOrValue<T>>): void;
+/**
+ * Creates a copy of the set with the given values toggled (added if absent, removed if present).
+ *
+ * @param set - The set to copy.
+ * @param values - The values to toggle.
+ * @returns A new Set with the toggles applied.
+ */
 export declare function toggleInSetCopy<T>(set: Set<T>, values: Maybe<IterableOrValue<T>>): Set<T>;
+/**
+ * Toggles values in the set in place: adds if absent, removes if present.
+ *
+ * @param set - The set to modify.
+ * @param values - The values to toggle.
+ */
 export declare function toggleInSet<T>(set: Set<T>, values: Maybe<IterableOrValue<T>>): void;
+/**
+ * Creates a copy of the set with the given values removed.
+ *
+ * @param set - The set to copy, or null/undefined for an empty set.
+ * @param values - The values to remove from the copy.
+ * @returns A new Set with the values removed.
+ */
 export declare function removeFromSetCopy<T>(set: Maybe<Set<T>>, values: Maybe<IterableOrValue<T>>): Set<T>;
+/**
+ * Removes one or more values from the given set in place.
+ *
+ * @param set - The set to remove values from.
+ * @param values - The value or iterable of values to remove.
+ */
 export declare function removeFromSet<T>(set: Set<T>, values: Maybe<IterableOrValue<T>>): void;
+/**
+ * Returns true if both iterables contain the same set of values.
+ *
+ * @param a - First iterable.
+ * @param b - Second iterable.
+ * @returns `true` if the values are identical as sets.
+ */
 export declare function hasSameValues<T>(a: Maybe<Iterable<T>>, b: Maybe<Iterable<T>>): boolean;
+/**
+ * Returns true if the two iterables contain different sets of values, or if either is null/undefined.
+ *
+ * @param a - First iterable.
+ * @param b - Second iterable.
+ * @returns `true` if the values differ.
+ */
 export declare function hasDifferentValues<T>(a: Maybe<Iterable<T>>, b: Maybe<Iterable<T>>): boolean;
+/**
+ * Returns an array of values that exist in exactly one of the two iterables (symmetric difference).
+ *
+ * @param a - First iterable.
+ * @param b - Second iterable.
+ * @returns An array of values present in only one of the inputs.
+ */
 export declare function symmetricDifferenceArray<T>(a: Maybe<Iterable<T>>, b: Maybe<Iterable<T>>): Maybe<T>[];
+/**
+ * Returns an array of the symmetric difference between two sets.
+ *
+ * @param a - First set.
+ * @param b - Second set.
+ * @returns An array of values present in only one of the sets.
+ */
 export declare function symmetricDifferenceArrayBetweenSets<T>(a: Set<Maybe<T>>, b: Set<Maybe<T>>): Maybe<T>[];
+/**
+ * Flattens a two-dimensional array into a Set of unique values.
+ *
+ * @param array - The nested array to flatten.
+ * @returns A Set containing all values from the nested arrays.
+ */
 export declare function flattenArrayToSet<T>(array: T[][]): Set<T>;
 /**
- * If the input values to keep is null or undefined, returns an empty set.
+ * Returns a new Set containing only the values from the input that also exist in the given set.
+ * If the input values are null or undefined, returns an empty set.
  *
- * @param set
- * @param values
- * @returns
+ * @param set - The reference set to check membership against.
+ * @param values - The values to filter.
+ * @returns A Set of values that exist in both inputs.
  */
 export declare function keepFromSetCopy<T>(set: Set<T>, values: Maybe<IterableOrValue<T>>): Set<T>;
+/**
+ * Filters the array to only include values that exist in the given set.
+ *
+ * @param values - The array to filter.
+ * @param set - The set to check membership against.
+ * @returns An array of values present in the set.
+ */
 export declare function keepValuesFromSet<T>(values: T[], set: Set<T>): T[];
+/**
+ * Returns values from the first array that are not present in the iterable.
+ *
+ * @param valuesToExclude - The array of values to filter.
+ * @param iterable - The iterable of values to exclude.
+ * @returns An array of values not found in the iterable.
+ */
 export declare function excludeValues<T>(valuesToExclude: T[], iterable: Maybe<Iterable<T>>): T[];
 /**
- * Excludes any values in the input array using the set.
+ * Filters the array to exclude any values present in the given set.
  *
- * @param values
- * @param set
- * @returns
+ * @param values - The array to filter.
+ * @param set - The set of values to exclude.
+ * @returns An array of values not in the set.
  */
 export declare function excludeValuesFromSet<T>(values: T[], set: Set<T>): T[];
 /**
- * Filters the values from the array using
+ * Filters the array using set membership, either including or excluding matched values.
  *
- * @param values
- * @param set
- * @param exclude
- * @returns
+ * @param values - The array to filter.
+ * @param set - The set to check against.
+ * @param exclude - If true, excludes values in the set; if false, keeps only values in the set.
+ * @returns The filtered array.
  */
 export declare function filterValuesUsingSet<T>(values: T[], set: Set<T>, exclude?: boolean): T[];
 /**
- * Filters the input iterable using a DecisionFunction and returns a Set.
+ * Filters the input iterable using a {@link DecisionFunction} and returns a Set of values for which the function returns true.
  *
- * @param values
- * @param fn
- * @returns
+ * @param values - The iterable to filter.
+ * @param fn - The decision function that determines inclusion.
+ * @returns A Set of values that passed the filter.
  */
 export declare function filterValuesToSet<T>(values: Iterable<T>, fn: DecisionFunction<T>): Set<T>;
 /**
- * SeparateValuesToSets() result
+ * Result of {@link separateValuesToSets} containing included and excluded value sets.
  */
 export interface SeparateValuesToSetsResult<T> {
     readonly included: Set<T>;
@@ -65,27 +169,29 @@ export interface SeparateValuesToSetsResult<T> {
  */
 export type SeparateValuesToSetsInput<T> = Partial<SeparateValuesToSetsResult<T>>;
 /**
- * Filters the input iterable using a DecisionFunction and returns a Set.
+ * Separates values from an iterable into two sets based on a {@link DecisionFunction}.
+ * Values for which the function returns true go into `included`, others into `excluded`.
  *
- * @param values
- * @param fn
- * @returns
+ * @param values - The iterable to partition.
+ * @param fn - The decision function that determines inclusion.
+ * @param input - Optional pre-existing sets to add results to.
+ * @returns An object with `included` and `excluded` sets.
  */
 export declare function separateValuesToSets<T>(values: Iterable<T>, fn: DecisionFunction<T>, input?: SeparateValuesToSetsInput<T>): SeparateValuesToSetsResult<T>;
 /**
- * Maps the input iterable using a MapFunction and returns a Set of the mapped values.
+ * Maps each value in the iterable through a function and collects the results into a Set.
  *
- * @param values
- * @param fn
- * @returns
+ * @param values - The iterable to map.
+ * @param mapFn - The mapping function.
+ * @returns A Set of mapped values.
  */
 export declare function mapValuesToSet<I, O>(values: Iterable<I>, mapFn: MapFunction<I, O>): Set<O>;
 /**
- * Convenience function for using setHasValueFunction with IterableOrValue input.
+ * Creates a {@link SetHasValueFunction} from an {@link IterableOrValue} by first converting it to a Set.
  *
- * @param iterable
- * @param exclude
- * @returns
+ * @param iterable - The values to create a set from.
+ * @param exclude - If true, the returned function returns true for values NOT in the set.
+ * @returns A function that tests membership.
  */
 export declare function hasValueFunction<T>(iterable: IterableOrValue<T>, exclude?: boolean): SetHasValueFunction<T>;
 /**
@@ -93,13 +199,16 @@ export declare function hasValueFunction<T>(iterable: IterableOrValue<T>, exclud
  */
 export type SetHasValueFunction<T> = (value: T) => boolean;
 /**
- * Creates a SetHasValueFunction. May create a function that returns the inverse.
+ * Creates a {@link SetHasValueFunction} for the given set. When `exclude` is true, returns the inverse (true for values not in the set).
  *
- * @param set
- * @param exclude
- * @returns
+ * @param set - The set to check against.
+ * @param exclude - If true, returns true for values NOT in the set.
+ * @returns A function that tests membership.
  */
 export declare function setHasValueFunction<T>(set: Set<T>, exclude: boolean): SetHasValueFunction<T>;
+/**
+ * Configuration for {@link findValuesFrom} that filters an array by key membership.
+ */
 export interface FindValuesFromInput<T, K extends PrimativeKey = PrimativeKey> {
     /**
      * Values to filter on.
@@ -125,10 +234,11 @@ export interface FindValuesFromInput<T, K extends PrimativeKey = PrimativeKey> {
     readonly exclude?: boolean;
 }
 /**
- * Finds values from the set based on the input.
+ * Filters an array of values based on whether their keys are found in a specified set of keys or values.
+ * Supports both inclusion and exclusion modes.
  *
- * @param config
- * @returns
+ * @param config - Configuration specifying the values, keys to find, and filtering behavior.
+ * @returns The filtered array of matching values.
  */
 export declare function findValuesFrom<T, K extends PrimativeKey = PrimativeKey>(config: FindValuesFromInput<T, K>): T[];
 /**
@@ -136,27 +246,45 @@ export declare function findValuesFrom<T, K extends PrimativeKey = PrimativeKey>
  */
 export type SetIncludesFunction<T> = (valuesToFind: IterableOrValue<T>) => boolean;
 /**
- * Creates a SetIncludesFunction using the input valuesSet and optional mode. By default the mode defaults to 'all'.
+ * Creates a {@link SetIncludesFunction} that checks whether the set includes given values using the specified mode.
  *
- * @param valuesSet
- * @param valuesToFind
- * @param mode
+ * @param valuesSet - The reference set.
+ * @param mode - Whether to require 'all' values or 'any' value to be present. Defaults to 'all'.
+ * @param emptyValuesToFindArrayResult - The result when the values to find are empty.
+ * @returns A function that tests inclusion against the set.
  */
 export declare function setIncludesFunction<T>(valuesSet: Set<T>, mode?: SetIncludesMode, emptyValuesToFindArrayResult?: boolean): SetIncludesFunction<T>;
 /**
- * Convenience function for calling setIncludesFunction() and passing the result a value, checking for includion.
+ * Checks whether the set includes the given values using the specified mode.
+ * Convenience wrapper around {@link setIncludesFunction}.
  *
- * @param valuesSet
- * @param valuesToFind
- * @param mode
- * @returns
+ * @param valuesSet - The reference set.
+ * @param valuesToFind - The values to check for.
+ * @param mode - Whether to require 'all' or 'any'. Defaults to 'all'.
+ * @returns `true` if the inclusion check passes.
  */
 export declare function setIncludes<T>(valuesSet: Set<T>, valuesToFind: IterableOrValue<T>, mode?: SetIncludesMode): boolean;
 /**
  * Returns false if the input array contains any value from the second array.
  */
 export declare function containsNoneOfValue<T>(values: IterableOrValue<T>, valuesToFind: IterableOrValue<T>, emptyValuesToFindArrayResult?: boolean): boolean;
+/**
+ * Returns true if none of the values are present in the given set.
+ *
+ * @param values - The values to check.
+ * @param valuesToFind - The set to check against.
+ * @param emptyValuesArrayResult - Result when values is empty.
+ * @returns `true` if no values are in the set.
+ */
 export declare function containsNoValueFromSet<T>(values: IterableOrValue<T>, valuesToFind: Set<T>, emptyValuesArrayResult?: boolean): boolean;
+/**
+ * Returns true if the set contains none of the given values.
+ *
+ * @param valuesSet - The set to check against.
+ * @param valuesToFind - The values to look for.
+ * @param emptyValuesToFindArrayResult - Result when valuesToFind is empty. Defaults to true.
+ * @returns `true` if none of the values are in the set.
+ */
 export declare function setContainsNoneOfValue<T>(valuesSet: Set<T>, valuesToFind: IterableOrValue<T>, emptyValuesToFindArrayResult?: boolean): boolean;
 /**
  * Returns true if the input array contains any value from the second array.

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

@@ -7,9 +7,11 @@ export type IsInSetDecisionFunction<T, V> = DecisionFunction<T> & {
     readonly _set: Set<V>;
 };
 /**
- * Creates an IsInSetDecisionFunction.
+ * Creates an {@link IsInSetDecisionFunction} that checks whether a value (or a derived value) is in the given set.
  *
- * @param set
+ * @param set - The set to check membership against.
+ * @param readValue - Optional function to extract the lookup value from the input. Defaults to identity.
+ * @returns A decision function that returns true for values found in the set.
  */
 export declare function isInSetDecisionFunction<T>(set: Set<T>): IsInSetDecisionFunction<T, T>;
 export declare function isInSetDecisionFunction<T, V>(set: Set<V>, readValue: (value: T) => V): IsInSetDecisionFunction<T, V>;

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

@@ -11,6 +11,9 @@ export declare enum SetDeltaChange {
  * Returns true if the next value has been modified compared to the past value.
  */
 export type SetValueIsModifiedFunction<T> = (past: T, next: T) => boolean;
+/**
+ * Represents the change status of a single value between two sets, including its past and next values.
+ */
 export interface SetDeltaChangePair<T, K extends PrimativeKey = PrimativeKey> {
     /**
      * Key for this pair
@@ -41,6 +44,9 @@ export interface SetDeltaChangePair<T, K extends PrimativeKey = PrimativeKey> {
  * Function that builds an array of changes based on the values in the past array to the next array.
  */
 export type SetDeltaFunction<T, K extends PrimativeKey = PrimativeKey> = (past: Iterable<T>, next: Iterable<T>) => SetDeltaChangePair<T, K>[];
+/**
+ * Configuration for creating a {@link SetDeltaFunction}.
+ */
 export interface SetDeltaFunctionConfig<T, K extends PrimativeKey = PrimativeKey> {
     /**
      * Reads the identifying key from each input value.
@@ -51,6 +57,13 @@ export interface SetDeltaFunctionConfig<T, K extends PrimativeKey = PrimativeKey
      */
     isModifiedFunction?: SetValueIsModifiedFunction<T>;
 }
+/**
+ * Creates a {@link SetDeltaFunction} that computes the differences between two iterables,
+ * identifying which items were added, removed, or unchanged.
+ *
+ * @param config - Configuration with the key reader and optional modification detector.
+ * @returns A function that compares two iterables and returns an array of change pairs.
+ */
 export declare function setDeltaFunction<T>(config: SetDeltaFunctionConfig<T>): SetDeltaFunction<T>;
 /**
  * Keys mapped by their change type.
@@ -61,10 +74,10 @@ export interface SetDeltaChangeKeys<K extends PrimativeKey = PrimativeKey> {
     readonly added: K[];
 }
 /**
- * Creates a SetDeltaChangeKeys from the input SetDeltaChangePair values.
+ * Groups the keys from an array of {@link SetDeltaChangePair} values by their change type.
  *
- * @param pairs
- * @returns
+ * @param pairs - The delta change pairs to categorize.
+ * @returns An object with `added`, `removed`, and `none` key arrays.
  */
 export declare function setDeltaChangeKeys<T, K extends PrimativeKey = PrimativeKey>(pairs: SetDeltaChangePair<T, K>[]): SetDeltaChangeKeys<K>;
 /**

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

@@ -1,6 +1,10 @@
 import { type PrimativeKey, type ReadKeyFunction } from '../key';
 import { type Maybe } from '../value/maybe.type';
+/**
+ * Configuration for a {@link HashSet}, providing the key extraction function.
+ */
 export interface HashSetConfig<K extends PrimativeKey, T> {
+    /** Extracts the unique key used for equality comparison from each value. */
     readKey: ReadKeyFunction<T, K>;
 }
 /**
@@ -11,23 +15,62 @@ export interface HashSetConfig<K extends PrimativeKey, T> {
 export declare class HashSet<K extends PrimativeKey, T> implements Set<T> {
     private readonly _map;
     private readonly _config;
+    /**
+     * @param config - Configuration with the key extraction function.
+     * @param values - Optional initial values to add.
+     */
     constructor(config: HashSetConfig<K, T>, values?: T[]);
     get config(): HashSetConfig<K, T>;
     get size(): number;
     [Symbol.iterator](): MapIterator<T>;
+    /**
+     * Adds all values from the array to the set.
+     *
+     * @param values - The values to add, or null/undefined to skip.
+     * @returns This set for chaining.
+     */
     addAll(values: Maybe<T[]>): this;
     add(value: T): this;
     clear(): void;
     delete(value: T): boolean;
     has(value: T): boolean;
+    /**
+     * Checks whether a value with the given key exists in the set.
+     *
+     * @param key - The key to check for.
+     * @returns `true` if a value with this key exists.
+     */
     hasKeyValue(key: Maybe<K>): boolean;
+    /**
+     * Returns the value associated with the given key, or undefined if not found.
+     *
+     * @param key - The key to look up.
+     * @returns The value, or undefined.
+     */
     valueForKey(key: Maybe<K>): T | undefined;
+    /**
+     * Returns key-value entry pairs for each of the given keys. Missing values appear as undefined.
+     *
+     * @param keys - The keys to look up.
+     * @returns An array of [key, value] tuples.
+     */
     valueKeyEntriesForKeys(keys: Maybe<K>[]): [Maybe<K>, Maybe<T>][];
+    /**
+     * Returns the values associated with the given keys, omitting keys that have no value.
+     *
+     * @param keys - The keys to look up.
+     * @returns An array of found values.
+     */
     valuesForKeys(keys: Maybe<K>[]): T[];
     forEach(callbackfn: (value: T, value2: T, set: Set<T>) => void, thisArg?: unknown): void;
     entries(): SetIterator<[T, T]>;
     keys(): SetIterator<T>;
     values(): SetIterator<T>;
+    /**
+     * Returns all values in the set as an array.
+     *
+     * @returns An array of all stored values.
+     */
     valuesArray(): T[];
     get [Symbol.toStringTag](): string;
 }

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

@@ -4,6 +4,9 @@ import { type DecisionFunction } from '../value';
  * Factory that creates a DecisionFunction using the input "selected" values. That function returns true if the value's key is considered to be included in the selected values.
  */
 export type IsSelectedDecisionFunctionFactory<T, K extends PrimativeKey = PrimativeKey> = (selectedValues: Iterable<K>) => DecisionFunction<T>;
+/**
+ * Configuration for {@link isSelectedDecisionFunctionFactory}.
+ */
 export interface IsSelectedDecisionFunctionConfig<T, K extends PrimativeKey = PrimativeKey> {
     /**
      * Reads the key from the input value.
@@ -17,9 +20,10 @@ export interface IsSelectedDecisionFunctionConfig<T, K extends PrimativeKey = Pr
     defaultIfKeyNull?: boolean;
 }
 /**
- * Creates a IsSelectedDecisionFunctionFactory
+ * Creates an {@link IsSelectedDecisionFunctionFactory} that produces decision functions
+ * checking whether a value's key is included in a set of selected values.
  *
- * @param config
- * @returns
+ * @param config - Configuration with the key reader and default behavior.
+ * @returns A factory that creates decision functions from a set of selected keys.
  */
 export declare function isSelectedDecisionFunctionFactory<T, K extends PrimativeKey = PrimativeKey>(config: IsSelectedDecisionFunctionConfig<T, K>): IsSelectedDecisionFunctionFactory<T, K>;

package/src/lib/sort.d.ts

@@ -50,11 +50,22 @@ export declare function reverseCompareFn<T>(compareFn: SortDescendingCompareFunc
  */
 export declare function compareFnOrder<T>(ascendingCompareFn: AscendingSortCompareFunction<T>, order?: SortingOrder): SortCompareFunction<T>;
 /**
- * Creates a new SortCompareFunction that can sort values of one type mapped to another type and sorted with a different sort function.
+ * Creates a {@link SortCompareFunction} that maps values to a different type before comparing.
+ * Useful for sorting objects by a derived property.
  *
- * @param mapValue
- * @param sortValuesFunction
- * @returns
+ * @param mapValue - Maps each value to the type used for comparison.
+ * @param comparesFunction - Compares the mapped values.
+ * @returns A sort comparison function for the original type.
+ *
+ * @example
+ * ```ts
+ * const byName = compareWithMappedValuesFunction(
+ *   (user: { name: string }) => user.name,
+ *   (a, b) => a.localeCompare(b)
+ * );
+ * [{ name: 'Bob' }, { name: 'Alice' }].sort(byName);
+ * // [{ name: 'Alice' }, { name: 'Bob' }]
+ * ```
  */
 export declare function compareWithMappedValuesFunction<T, V>(mapValue: MapFunction<T, V>, comparesFunction: SortCompareFunction<V>): SortCompareFunction<T>;
 /**
@@ -83,17 +94,18 @@ export type SortValuesInput<T> = MaybeMap<Partial<SortCompareFunctionRef<T>>> &
     readonly alwaysReturnCopy?: Maybe<boolean>;
 };
 /**
- * Sorts the input values using the input.
+ * Sorts values using the configuration in {@link SortValuesInput}. Optionally sorts on a copy to avoid mutating the original array.
  *
- * @param input
- * @returns
+ * @param input - Configuration including values, sort function, and copy behavior.
+ * @returns The sorted array (may be the original or a copy depending on configuration).
  */
 export declare function sortValues<T>(input: SortValuesInput<T>): T[];
 /**
- * Creates a SortValuesFunction using the input.
+ * Creates a {@link SortValuesFunction} from a {@link SortCompareFunctionRef}.
  *
- * @param sortRef
- * @returns
+ * @param sortRef - Reference containing the sort comparison function.
+ * @param sortOnCopyDefault - Whether to sort on a copy by default (default: true).
+ * @returns A function that sorts arrays using the configured comparison.
  */
 export declare function sortValuesFunctionWithSortRef<T>(sortRef: Maybe<Partial<SortCompareFunctionRef<T>>>, sortOnCopyDefault?: boolean): SortValuesFunction<T>;
 /**
@@ -101,11 +113,11 @@ export declare function sortValuesFunctionWithSortRef<T>(sortRef: Maybe<Partial<
  */
 export declare function sortValuesFunctionOrMapIdentityWithSortRef<T>(sortRef: Maybe<Partial<SortCompareFunctionRef<T>>>, sortOnCopyDefault?: boolean): SortValuesFunction<T>;
 /**
- * Equivalent to sortValuesFunctionOrMapIdentityWithSortRef(), but returns a SimpleSortValuesFunction instead.
+ * Equivalent to {@link sortValuesFunctionOrMapIdentityWithSortRef}, but returns a {@link SimpleSortValuesFunction} instead.
  *
- * @param sortRef
- * @param sortOnCopyDefault
- * @returns
+ * @param sortRef - Reference containing the sort comparison function.
+ * @param sortOnCopyDefault - Whether to sort on a copy by default.
+ * @returns A simple sort function or identity function.
  */
 export declare const simpleSortValuesFunctionWithSortRef: <T>(sortRef: Maybe<Partial<SortCompareFunctionRef<T>>>, sortOnCopyDefault?: boolean) => SimpleSortValuesFunction<T>;
 export interface MinAndMax<T> {
@@ -120,8 +132,16 @@ export type MinAndMaxFunctionResult<T> = MinAndMax<T> | null;
  */
 export type MinAndMaxFunction<T> = (values: Iterable<T>) => MinAndMaxFunctionResult<T>;
 /**
- * Creates a MinAndMaxFunction using the input compare.
+ * Creates a {@link MinAndMaxFunction} that finds the minimum and maximum values from an iterable using the provided comparison function.
+ *
+ * @param compareFn - Ascending sort comparison function used to determine min/max.
+ * @returns A function that returns `{ min, max }` or `null` for empty iterables.
  *
- * @param compare
+ * @example
+ * ```ts
+ * const fn = minAndMaxFunction<number>((a, b) => a - b);
+ * fn([3, 1, 4, 1, 5]); // { min: 1, max: 5 }
+ * fn([]);               // null
+ * ```
  */
 export declare function minAndMaxFunction<T>(compareFn: SortCompareFunction<T>): MinAndMaxFunction<T>;