import { type PrimativeKey, type ReadKeyFunction, type ReadMultipleKeysFunction } from '../key';
import { type IterableOrValue } from '../iterable/iterable';
import { type Maybe } from '../value/maybe.type';
/**
 * Creates a map by reading keys from the input values.
 *
 * Values without a key (null/undefined) are ignored.
 */
export type KeyValueMapFactory<T, K extends PrimativeKey = PrimativeKey> = (values: T[]) => Map<K, T>;
/**
 * Creates a KeyValueMapFactory that maps values by their key using a ReadKeyFunction.
 *
 * @param read - Function that extracts a key from each value
 * @returns A factory that creates Maps from arrays of values
 */
export declare function keyValueMapFactory<T, K extends PrimativeKey = PrimativeKey>(read: ReadKeyFunction<T, K>): KeyValueMapFactory<T, K>;
/**
 * Reads keys off the input values and places them in a Map using a ReadKeyFunction.
 *
 * @param values - The array of values to map
 * @param read - Function that extracts a key from each value
 * @returns A Map keyed by the extracted keys
 */
export declare function readKeysToMap<T, K extends PrimativeKey = PrimativeKey>(values: T[], read: ReadKeyFunction<T, K>): Map<K, T>;
/**
 * Creates a KeyValueMapFactory that maps values by multiple keys using a ReadMultipleKeysFunction.
 * Each value can appear under multiple keys.
 *
 * @param read - Function that extracts multiple keys from each value
 * @returns A factory that creates Maps from arrays of values
 */
export declare function multiKeyValueMapFactory<T, K extends PrimativeKey = PrimativeKey>(read: ReadMultipleKeysFunction<T, K>): KeyValueMapFactory<T, K>;
/**
 * Reads multiple keys off the input values and places them in a Map using a ReadMultipleKeysFunction.
 *
 * @param values - The array of values to map
 * @param read - Function that extracts multiple keys from each value
 * @returns A Map keyed by the extracted keys
 */
export declare function readMultipleKeysToMap<T, K extends PrimativeKey = PrimativeKey>(values: T[], read: ReadMultipleKeysFunction<T, K>): Map<K, T>;
/**
 * Map with an array of values for a key.
 */
export type MultiValueMap<T, K extends PrimativeKey = PrimativeKey> = Map<Maybe<K>, T[]>;
/**
 * Interface for adding key/value pairs to a map that contains an array of values.
 */
export interface MultiValueMapBuilder<T, K extends PrimativeKey = PrimativeKey> {
    map(): MultiValueMap<T, K>;
    entries(): [Maybe<K>, T[]][];
    tuples(): [Maybe<K>, T][];
    /**
     * Deletes all values from the map with the input key.
     *
     * Returns true if a value was deleted.
     *
     * @param key
     */
    delete(key: Maybe<K>): boolean;
    /**
     * Adds the input key/value pair to the map. Use for inserting all Tuple values.
     *
     * @param key
     * @param value
     */
    addTuples(key: Maybe<K>, value: IterableOrValue<T>): void;
    /**
     * Adds the input key/value(s) pair to the map.
     *
     * Use the addTuple() function if adding a single tuple value to the array.
     *
     * @param key
     * @param value
     */
    add(key: Maybe<K>, value: IterableOrValue<T>): void;
    /**
     * Adds all input values with all the input key pairs to the map. Use for inserting multiple Tuple values.
     *
     * @param keys
     * @param value
     */
    addTuplesToKeys(keys: Maybe<IterableOrValue<K>>, value: IterableOrValue<T>): void;
    /**
     * Adds the input keys and value pairs to the map.
     *
     * Use the addTuple() function if adding a single tuple value to the array.
     *
     * @param keys
     * @param value
     */
    addToKeys(keys: Maybe<IterableOrValue<K>>, value: IterableOrValue<T>): void;
    /**
     * Returns true if the map contains the input key.
     *
     * @param key
     */
    has(key: Maybe<K>): boolean;
    /**
     * Returns all current values for the input key. If no values are found,
     *
     * @param key
     */
    get(key: Maybe<K>): T[];
}
/**
 * Creates a new MultiValueMapBuilder for building Maps where each key maps to an array of values.
 *
 * @returns A new MultiValueMapBuilder instance
 */
export declare function multiValueMapBuilder<T, K extends PrimativeKey = PrimativeKey>(): MultiValueMapBuilder<T, K>;
/**
 * Determines if two maps have the same keys.
 *
 * @param a - The first map
 * @param b - The second map
 * @returns true if the maps have the same keys, false otherwise
 */
export declare function mapsHaveSameKeys<K>(a: Map<K, unknown>, b: Map<K, unknown>): boolean;