import { type ReadValueFunction } from './map';
import { type Maybe } from './maybe.type';
/**
 * A comparator that returns true if the two input values are considered equivalent.
 */
export type EqualityComparatorFunction<T> = (a: T, b: T) => boolean;
/**
 * Wraps an {@link EqualityComparatorFunction} to safely handle `Maybe` values.
 *
 * The wrapped function delegates to the comparator only when both values are non-nullish.
 * When both are nullish, it uses strict equality (`===`), so `null === null` is `true`
 * but `null === undefined` is `false`.
 *
 * @param compare - the comparator to wrap
 * @returns a new comparator that handles nullish values safely before delegating to the wrapped comparator
 *
 * @example
 * ```ts
 * const safeCompare = safeEqualityComparatorFunction((a: number, b: number) => a === b);
 * safeCompare(1, 1);       // true
 * safeCompare(null, null);  // true
 * safeCompare(null, undefined); // false
 * ```
 */
export declare function safeEqualityComparatorFunction<T>(compare: EqualityComparatorFunction<T>): EqualityComparatorFunction<Maybe<T>>;
/**
 * Convenience function that safely compares two `Maybe` values using the provided comparator.
 *
 * Delegates to {@link safeEqualityComparatorFunction} internally, so nullish values are handled
 * without invoking the comparator.
 *
 * @param a - first value to compare
 * @param b - second value to compare
 * @param compare - the equality comparator for non-nullish values
 * @returns `true` if the values are considered equal
 *
 * @example
 * ```ts
 * safeCompareEquality(0, 1, (a, b) => a === b);
 * // false
 *
 * safeCompareEquality(null, null, (a, b) => a === b);
 * // true (comparator is not invoked)
 * ```
 */
export declare function safeCompareEquality<T>(a: Maybe<T>, b: Maybe<T>, compare: EqualityComparatorFunction<T>): boolean;
/**
 * Function used to compare the values from the input items. Items might not be defined.
 *
 * - If the items are both null or both undefined, the function will return true.
 * - If one is defined and one is undefined, it will return false.
 * - If one is undefined and one is null the function will return false.
 */
export type CompareEqualityWithValueFromItemsFunction<I, V> = ((a: Maybe<I>, b: Maybe<I>) => boolean) & {
    /**
     * The function used to extract comparable values from each input item.
     */
    readonly _readValues: ReadValueFunction<I, V>;
    /**
     * The equality comparator applied to the extracted values.
     */
    readonly _equalityComparator: EqualityComparatorFunction<V>;
};
/**
 * Creates a {@link CompareEqualityWithValueFromItemsFunction} that extracts values from items before comparing them.
 *
 * This is a convenience wrapper around {@link compareEqualityWithValueFromItemsFunctionFactory} that
 * accepts both the value reader and comparator in a single call.
 *
 * @param readValues - extracts the comparable value from each item
 * @param equalityComparator - compares the extracted values for equality
 * @returns a function that compares two items by their extracted values
 */
export declare function compareEqualityWithValueFromItemsFunction<I, V>(readValues: ReadValueFunction<I, V>, equalityComparator: EqualityComparatorFunction<V>): CompareEqualityWithValueFromItemsFunction<I, V>;
/**
 * Function used to compare the values from the input items. Items might not be defined.
 */
export type CompareEqualityWithValueFromItemsFunctionFactory<I, V> = ((equalityComparator: EqualityComparatorFunction<V>) => CompareEqualityWithValueFromItemsFunction<I, V>) & Pick<CompareEqualityWithValueFromItemsFunction<I, V>, '_readValues'>;
/**
 * Creates a {@link CompareEqualityWithValueFromItemsFunctionFactory} that is pre-configured with a value reader.
 *
 * The returned factory accepts different equality comparators, allowing reuse of the same value extraction logic
 * with varying comparison strategies.
 *
 * @param readValues - extracts the comparable value from each item
 * @returns a factory function that accepts an equality comparator and produces a comparison function
 *
 * @example
 * ```ts
 * const factory = compareEqualityWithValueFromItemsFunctionFactory<number, number[]>((x) => [x]);
 * const fn = factory(iterablesAreSetEquivalent);
 *
 * fn(0, 0);           // true
 * fn(null, null);     // true
 * fn(undefined, undefined); // true
 * fn(0, 1);           // false
 * ```
 */
export declare function compareEqualityWithValueFromItemsFunctionFactory<I, V>(readValues: ReadValueFunction<I, V>): CompareEqualityWithValueFromItemsFunctionFactory<I, V>;