/**
 * Array-focused utility helpers.
 *
 * @module bquery/core/utils/array
 */
/**
 * Ensures the input is always returned as an array.
 *
 * @template T - The item type
 * @param value - A single value, array, or nullish value
 * @returns An array (empty if nullish)
 *
 * @example
 * ```ts
 * ensureArray('a'); // ['a']
 * ensureArray(['a', 'b']); // ['a', 'b']
 * ensureArray(null); // []
 * ```
 */
export declare function ensureArray<T>(value: T | T[] | null | undefined): T[];
/**
 * Removes duplicate entries from an array.
 *
 * @template T - The item type
 * @param items - The array to deduplicate
 * @returns A new array with unique items
 *
 * @example
 * ```ts
 * unique([1, 2, 2, 3]); // [1, 2, 3]
 * ```
 */
export declare function unique<T>(items: T[]): T[];
/**
 * Splits an array into chunks of a given size.
 *
 * @template T - The item type
 * @param items - The array to chunk
 * @param size - The maximum size of each chunk
 * @returns An array of chunks
 *
 * @example
 * ```ts
 * chunk([1, 2, 3, 4, 5], 2); // [[1,2],[3,4],[5]]
 * ```
 */
export declare function chunk<T>(items: T[], size: number): T[][];
/**
 * Removes falsy values from an array.
 *
 * @template T - The item type
 * @param items - The array to compact
 * @returns A new array without falsy values
 *
 * @example
 * ```ts
 * compact([0, 1, '', 'ok', null]); // [1, 'ok']
 * ```
 */
export declare function compact<T>(items: Array<T | null | undefined | false | 0 | ''>): T[];
/**
 * Flattens a single level of nested arrays.
 *
 * @template T - The item type
 * @param items - The array to flatten
 * @returns A new flattened array
 *
 * @example
 * ```ts
 * flatten([1, [2, 3], 4]); // [1, 2, 3, 4]
 * ```
 */
export declare function flatten<T>(items: Array<T | T[]>): T[];
/** Iteratee that resolves a string key or function selector. */
/**
 * Groups items by a key derived from either a property name or a selector function.
 *
 * @example
 * ```ts
 * groupBy([{ k: 'a' }, { k: 'b' }, { k: 'a' }], 'k');
 * // { a: [{k:'a'},{k:'a'}], b: [{k:'b'}] }
 * groupBy([1, 2, 3, 4], (n) => (n % 2 === 0 ? 'even' : 'odd'));
 * // { odd: [1, 3], even: [2, 4] }
 * ```
 */
export declare function groupBy<T, K extends keyof T>(items: readonly T[], key: K): Record<string, T[]>;
export declare function groupBy<T, R extends PropertyKey>(items: readonly T[], key: (item: T) => R): Record<R, T[]>;
/**
 * Indexes items by a key derived from either a property name or a selector
 * function. Later items with the same key override earlier ones.
 *
 * @example
 * ```ts
 * keyBy([{ id: 1 }, { id: 2 }], 'id'); // { 1: { id: 1 }, 2: { id: 2 } }
 * ```
 */
export declare function keyBy<T, K extends keyof T>(items: readonly T[], key: K): Record<string, T>;
export declare function keyBy<T, R extends PropertyKey>(items: readonly T[], key: (item: T) => R): Record<R, T>;
/**
 * Partitions items into `[matching, nonMatching]` based on a predicate.
 */
export declare function partition<T>(items: readonly T[], predicate: (item: T, index: number) => boolean): [T[], T[]];
/**
 * Combines parallel arrays into tuples (truncated to the shortest input).
 *
 * @example
 * ```ts
 * zip([1, 2, 3], ['a', 'b', 'c']); // [[1, 'a'], [2, 'b'], [3, 'c']]
 * ```
 */
export declare function zip<T extends unknown[][]>(...arrays: T): Array<{
    [K in keyof T]: T[K] extends Array<infer U> ? U : never;
}>;
/**
 * Generates a numeric range `[start, end)` with the given step.
 *
 * @example
 * ```ts
 * range(0, 5);        // [0, 1, 2, 3, 4]
 * range(2, 10, 2);    // [2, 4, 6, 8]
 * range(5, 0, -1);    // [5, 4, 3, 2, 1]
 * ```
 */
export declare function range(start: number, end: number, step?: number): number[];
/** Returns the first element of an array, or `undefined` if empty. */
export declare function first<T>(items: readonly T[]): T | undefined;
/** Returns the last element of an array, or `undefined` if empty. */
export declare function last<T>(items: readonly T[]): T | undefined;
/** Returns a new array containing the first `n` elements. */
export declare function take<T>(items: readonly T[], n: number): T[];
/** Returns a new array with the first `n` elements removed. */
export declare function drop<T>(items: readonly T[], n: number): T[];
/**
 * Returns a single random element from the array, or `undefined` if empty.
 * Uses `Math.random()` — not suitable for cryptographic randomness.
 */
export declare function sample<T>(items: readonly T[]): T | undefined;
/**
 * Returns a new array with the items shuffled using the Fisher–Yates
 * algorithm. Uses `Math.random()` — not suitable for cryptographic use.
 */
export declare function shuffle<T>(items: readonly T[]): T[];
/**
 * Returns a new array with duplicates removed based on a selector. Preserves
 * the first occurrence of each key.
 */
export declare function uniqueBy<T, K>(items: readonly T[], selector: (item: T) => K): T[];
/**
 * Returns a sorted copy ordered by one or more selectors. Each
 * selector should return a comparable primitive (number, string, boolean,
 * Date).
 *
 * @example
 * ```ts
 * sortBy(users, (u) => u.lastName);
 * sortBy(users, [(u) => u.lastName, (u) => u.firstName]);
 * ```
 */
export declare function sortBy<T, K extends string | number | boolean | bigint | Date>(items: readonly T[], selector: ((item: T) => K) | Array<(item: T) => K>): T[];
/**
 * Returns the intersection of two arrays. Element order follows `a`.
 * Uses strict equality via `Set` membership.
 */
export declare function intersection<T>(a: readonly T[], b: readonly T[]): T[];
/**
 * Returns the items in `a` that are not in `b`.
 */
export declare function difference<T>(a: readonly T[], b: readonly T[]): T[];
/**
 * Recursively flattens nested arrays of arbitrary depth.
 */
export declare function flattenDeep<T>(items: ReadonlyArray<T | readonly unknown[]>): T[];
/**
 * Returns a new array with the element at `from` moved to `to`. Out-of-range
 * indices are clamped to `[0, items.length - 1]`.
 */
export declare function move<T>(items: readonly T[], from: number, to: number): T[];
/**
 * Splits an array into consecutive chunks at each point where the predicate
 * returns true for an item relative to the previous one in the chunk.
 *
 * @example
 * ```ts
 * chunkBy([1, 1, 2, 2, 3], (a, b) => a === b);
 * // [[1, 1], [2, 2], [3]]
 * ```
 */
export declare function chunkBy<T>(items: readonly T[], predicate: (current: T, previous: T) => boolean): T[][];
//# sourceMappingURL=array.d.ts.map