import { type PrimativeKey, type ReadKeyFunction } from '../key';
import { type DecisionFunction } from '../value/decision';
import { type Maybe } from '../value/maybe.type';
/**
 * An Iterable or a value.
 *
 * Note that strings are a valid Iterable, allowing iteration over characters.
 */
export type IterableOrValue<T> = T | Iterable<T>;
/**
 * Converts an IterableOrValue to an Iterable. Non-iterable values are wrapped in an array.
 *
 * @param values - The value or iterable to convert
 * @param treatStringAsIterable - Whether to treat strings as iterable (defaults to false)
 * @returns An Iterable containing the value(s)
 */
export declare function asIterable<T = unknown>(values: IterableOrValue<T>, treatStringAsIterable?: boolean): Iterable<T>;
/**
 * Converts an IterableOrValue to an array.
 *
 * By default treats strings as a non-iterable value, using the string as a single value.
 *
 * @param values - The value or iterable to convert
 * @param treatStringAsIterable - Whether to treat strings as iterable (defaults to false)
 * @returns An array containing the value(s)
 */
export declare function iterableToArray<T = unknown>(values: IterableOrValue<T>, treatStringAsIterable?: boolean): T[];
/**
 * Converts an IterableOrValue to a Set.
 *
 * By default treats strings as a non-iterable value, using the string as a single value.
 *
 * @param values - The value or iterable to convert
 * @param treatStringAsIterable - Whether to treat strings as iterable (defaults to false)
 * @returns A Set containing the value(s)
 */
export declare function iterableToSet<T = unknown>(values: IterableOrValue<T>, treatStringAsIterable?: boolean): Set<T>;
/**
 * Converts an IterableOrValue to a Map using a key extraction function.
 *
 * @param values - The value or iterable to convert
 * @param readKey - Function to extract the key from each value
 * @returns A Map with the extracted keys and their corresponding values
 */
export declare function iterableToMap<T, K extends PrimativeKey = PrimativeKey>(values: IterableOrValue<T>, readKey: ReadKeyFunction<T, K>): Map<Maybe<K>, T>;
/**
 * Type guard that returns true if the input is an Iterable.
 * By default, strings are not treated as iterable.
 *
 * @param values - The value to check
 * @param treatStringAsIterable - Whether to treat strings as iterable (defaults to false)
 * @returns True if the value is iterable
 */
export declare function isIterable<T = unknown>(values: unknown, treatStringAsIterable?: boolean): values is Iterable<T>;
/**
 * Returns true if the iterable has no values.
 *
 * @param values - The iterable to check
 * @returns True if the iterable is empty
 */
export declare function isEmptyIterable<T = unknown>(values: Iterable<T>): boolean;
/**
 * Returns the first value from the Iterable, or undefined if empty. Order is not guaranteed.
 *
 * @param values - The iterable to read from
 * @returns The first value, or undefined if empty
 */
export declare function firstValueFromIterable<T>(values: Iterable<T>): Maybe<T>;
/**
 * Takes up to `count` items from the iterable. Order is not guaranteed.
 *
 * @param values - The iterable to take from
 * @param count - Maximum number of items to take
 * @returns An array of taken values
 */
export declare function takeValuesFromIterable<T>(values: Iterable<T>, count: number): T[];
/**
 * Iterates over iterable values, calling the function for each one.
 *
 * @param values - The iterable to iterate over
 * @param fn - The function to call for each value
 */
export declare function forEachInIterable<T>(values: Iterable<T>, fn: (value: T) => void): void;
/**
 * Calls the function for each value if the input is iterable, or once with the value if it's a single value.
 * Does nothing if the input is null/undefined.
 *
 * @param values - The value or iterable to process
 * @param fn - The function to call for each value
 * @param treatStringAsIterable - Whether to treat strings as iterable (defaults to false)
 */
export declare function useIterableOrValue<T>(values: Maybe<IterableOrValue<T>>, fn: (value: T) => void, treatStringAsIterable?: boolean): void;
/**
 * Finds and returns the first value in the iterable that matches the decision function.
 *
 * @param values - The iterable to search
 * @param fn - Decision function that returns true for the desired value
 * @returns The first matching value, or undefined
 */
export declare function findInIterable<T>(values: Iterable<T>, fn: DecisionFunction<T>): Maybe<T>;
/**
 * Returns true if any value in the iterable matches the decision function.
 *
 * @param values - The iterable to search
 * @param fn - Decision function to test each value
 * @returns True if at least one value matches
 */
export declare function existsInIterable<T>(values: Iterable<T>, fn: DecisionFunction<T>): boolean;
/**
 * Filters values from the iterable, keeping those that pass the decision function.
 *
 * @param values - The iterable to filter
 * @param fn - Decision function that returns true for values to keep
 * @returns An array of matching values
 */
export declare function filterFromIterable<T>(values: Iterable<T>, fn: DecisionFunction<T>): T[];
/**
 * Wraps a single tuple value into an array. Distinguishes between a single tuple and an array of tuples
 * by checking whether nested array elements have uniform length.
 *
 * Used to prevent functions from incorrectly treating a tuple as an array of values.
 *
 * @param input - The tuple or array of tuples to wrap
 * @returns An array containing the tuple(s)
 * @throws Error if input is not an array
 */
export declare function wrapTuples<T>(input: IterableOrValue<T>): T[];