import { type PrimativeKey, type ReadKeyFunction } from './key';
import { type IndexRef } from './value/indexed';
import { type EqualityComparatorFunction } from './value/comparator';
import { type DecisionFunction } from './value/decision';
import { type Maybe } from './value/maybe.type';
/**
 * Result of separating values into two groups based on an inclusion check.
 */
export interface SeparateResult<T> {
    included: T[];
    excluded: T[];
}
/**
 * A plain object where each key maps to an array of grouped values.
 */
export interface GroupingResult<T> {
    [key: string]: T[];
}
/**
 * A typed grouping result where keys are constrained to the keys of a known object type.
 */
export type KeyedGroupingResult<T, O> = {
    [K in keyof O]: T[];
};
/**
 * Result of pairing values by their key. Values that share a key form a pair; values with unique keys are unpaired.
 */
export interface PairsGroupingResult<T> {
    pairs: T[][];
    unpaired: T[];
}
/**
 * Configuration for comparing two arrays to determine if their contents differ.
 */
export interface ArrayContentsDifferentParams<T, K extends PrimativeKey = PrimativeKey> {
    /**
     * Extracts a unique key from each item for pairing items across arrays.
     */
    groupKeyFn: ReadKeyFunction<T, K>;
    /**
     * Compares two paired items for equality.
     */
    isEqual: EqualityComparatorFunction<T>;
}
/**
 * Configuration for RestoreOrderParams.
 */
export interface RestoreOrderParams<T, K extends number | string = number | string> {
    readKey: ReadKeyFunction<T, K>;
    /**
     * Optional function used to decide which value should be retained.
     */
    chooseRetainedValue?: (values: T[]) => T;
    /**
     * Whether or not new items should be excluded. If false, the new items are appended to the end of the result in the order they are accessed.
     *
     * By default this is false.
     */
    excludeNewItems?: boolean;
}
/**
 * An array batch that carries its zero-based batch index via {@link IndexRef}.
 */
export type IndexedBatch<T> = T[] & Readonly<IndexRef>;
/**
 * Splits the input array into batches of a maximum size. Each batch carries its zero-based index as `.i`.
 *
 * @param input - The array to split into batches.
 * @param batchSize - Maximum number of items per batch.
 * @returns An array of {@link IndexedBatch} arrays.
 *
 * @example
 * ```ts
 * const result = batch(['a', 'b', 'c', 'd'], 2);
 * // result[0] => ['a', 'b'], result[0].i => 0
 * // result[1] => ['c', 'd'], result[1].i => 1
 * ```
 */
export declare function batch<T>(input: T[], batchSize: number): IndexedBatch<T>[];
export interface BatchCount {
    /**
     * Total number of items to make.
     */
    totalItems: number;
    /**
     * Size of each batch/expected max number of items to create per make call.
     */
    itemsPerBatch: number;
}
export interface BatchCalc extends BatchCount {
    batchCount: number;
    /**
     * Total number of full batches.
     */
    fullBatchCount: number;
    /**
     * The number of items not in a full batch.
     */
    remainder: number;
}
/**
 * Calculates batch metrics (count, full batches, remainder) from a {@link BatchCount} configuration.
 *
 * @param input - The total items and items-per-batch configuration.
 * @returns A {@link BatchCalc} with computed batch counts and remainder.
 */
export declare function batchCalc(input: BatchCount): BatchCalc;
/**
 * Returns how many items are in the batch at the given index, accounting for a possible smaller remainder batch at the end.
 *
 * @param index - Zero-based batch index.
 * @param calc - Pre-computed batch calculation from {@link batchCalc}.
 * @returns The number of items in that batch.
 */
export declare function itemCountForBatchIndex(index: number, calc: BatchCalc): number;
/**
 * Convenience wrapper for {@link restoreOrder} that derives order keys from a reference array of values
 * instead of requiring a separate keys array.
 *
 * @param orderValues - Values whose keys define the desired order.
 * @param values - Values to reorder.
 * @param params - Configuration including the key-reading function.
 * @returns The reordered values array.
 */
export declare function restoreOrderWithValues<T, K extends PrimativeKey = PrimativeKey>(orderValues: T[], values: T[], params: RestoreOrderParams<T, K>): T[];
/**
 * Reorders values to match a reference key ordering. Values not present in the order keys
 * are appended at the end (unless `excludeNewItems` is true). Duplicates are resolved via
 * the `chooseRetainedValue` function (defaults to keeping the first).
 *
 * @param orderKeys - Keys defining the desired order.
 * @param values - Values to reorder.
 * @param params - Configuration including key reader, duplicate handling, and new-item behavior.
 * @param params.readKey - function that extracts the grouping key from each value
 * @param params.chooseRetainedValue - function that selects which value to keep when duplicates share the same key; defaults to keeping the first
 * @param params.excludeNewItems - when true, values whose keys are not in `orderKeys` are omitted from the result; defaults to false
 * @returns The reordered values array.
 *
 * @example
 * ```ts
 * const items = [{ key: 'a' }, { key: 'b' }, { key: 'c' }];
 * const order = ['c', 'a', 'b'];
 * restoreOrder(order, items, { readKey: (x) => x.key });
 * // [{ key: 'c' }, { key: 'a' }, { key: 'b' }]
 * ```
 */
export declare function restoreOrder<T, K extends PrimativeKey = PrimativeKey>(orderKeys: K[], values: T[], { readKey, chooseRetainedValue, excludeNewItems }: RestoreOrderParams<T, K>): T[];
/**
 * Compares two arrays by pairing items with matching keys and checking equality.
 * Returns `true` if lengths differ, any items are unpaired, or any paired items are not equal.
 *
 * @param a - First array to compare.
 * @param b - Second array to compare.
 * @param params - Key extraction and equality functions.
 * @param params.groupKeyFn - function that extracts a grouping key from each element for pairing
 * @param params.isEqual - predicate that returns true when two paired elements are considered equal
 * @returns `true` if the array contents differ.
 */
export declare function arrayContentsDiffer<T, K extends PrimativeKey = PrimativeKey>(a: T[] | undefined, b: T[] | undefined, { groupKeyFn, isEqual }: ArrayContentsDifferentParams<T, K>): boolean;
/**
 * Groups values by key, then separates them into pairs (values sharing a key) and unpaired (unique key).
 *
 * @param values - Values to group and pair.
 * @param groupKeyFn - Extracts the grouping key from each value.
 * @returns A {@link PairsGroupingResult} with paired and unpaired values.
 */
export declare function pairGroupValues<T, K extends PrimativeKey = PrimativeKey>(values: T[], groupKeyFn: ReadKeyFunction<T, K>): PairsGroupingResult<T>;
/**
 * Creates an array of `[key, value]` tuples by extracting a key from each value.
 *
 * @param values - Values to create key pairs from.
 * @param keyFn - Extracts the key from each value.
 * @returns An array of `[key, value]` tuples.
 */
export declare function makeKeyPairs<T, K extends string | number = string | number>(values: T[], keyFn: ReadKeyFunction<T, K>): [Maybe<K>, T][];
/**
 * Separates values into included and excluded groups based on a decision function.
 *
 * @param values - Values to separate.
 * @param checkInclusion - Returns `true` for values that should be included.
 * @returns A {@link SeparateResult} with included and excluded arrays.
 */
export declare function separateValues<T>(values: T[], checkInclusion: DecisionFunction<T>): SeparateResult<T>;
/**
 * Groups values by key into a plain object. Convenience wrapper around {@link makeValuesGroupMap} that returns a POJO instead of a Map.
 *
 * @param values - Values to group.
 * @param groupKeyFn - Extracts the grouping key from each value.
 * @returns A plain object mapping each key to its array of values.
 */
export declare function groupValues<T, R, K extends PrimativeKey & keyof R>(values: T[], groupKeyFn: ReadKeyFunction<T, K>): KeyedGroupingResult<T, R>;
export declare function groupValues<T, K extends PrimativeKey = PrimativeKey>(values: T[], groupKeyFn: ReadKeyFunction<T, K>): GroupingResult<T>;
export declare function groupValues<T, R, K extends PrimativeKey & keyof R>(values: Maybe<T[]>, groupKeyFn: ReadKeyFunction<T, K>): KeyedGroupingResult<T, R>;
export declare function groupValues<T, K extends PrimativeKey = PrimativeKey>(values: Maybe<T[]>, groupKeyFn: ReadKeyFunction<T, K>): GroupingResult<T>;
/**
 * Groups values by key into a Map. Each key maps to the array of values that produced that key.
 *
 * @param values - Values to group.
 * @param groupKeyFn - Extracts the grouping key from each value.
 * @returns A Map from each key to its array of values.
 *
 * @example
 * ```ts
 * const items = [{ type: 'a', v: 1 }, { type: 'b', v: 2 }, { type: 'a', v: 3 }];
 * const map = makeValuesGroupMap(items, (x) => x.type);
 * // Map { 'a' => [{ type: 'a', v: 1 }, { type: 'a', v: 3 }], 'b' => [{ type: 'b', v: 2 }] }
 * ```
 */
export declare function makeValuesGroupMap<T, K extends PrimativeKey = PrimativeKey>(values: T[], groupKeyFn: ReadKeyFunction<T, K>): Map<Maybe<K>, T[]>;
export declare function makeValuesGroupMap<T, K extends PrimativeKey = PrimativeKey>(values: Maybe<T[]>, groupKeyFn: ReadKeyFunction<T, K>): Map<Maybe<K>, T[]>;