/**
 * ThreadTS Universal - Array Helper Utilities
 *
 * Shared array operations reused in multiple places in the library.
 * Follows the DRY principle (Don't Repeat Yourself).
 *
 * @module utils/array-helpers
 * @author ThreadTS Universal Team
 */
/**
 * Fisher-Yates (Knuth) shuffle algorithm.
 *
 * Shuffles an array in-place with a uniform random distribution.
 * Time complexity: O(n), space complexity: O(1)
 *
 * @template T - Array element type
 * @param array - Array to shuffle (mutated)
 * @returns The same array, shuffled
 *
 * @example
 * ```typescript
 * const arr = [1, 2, 3, 4, 5];
 * fisherYatesShuffle(arr);
 * console.log(arr); // e.g. [3, 1, 5, 2, 4]
 * ```
 */
export declare function fisherYatesShuffle<T>(array: T[]): T[];
/**
 * Creates a shuffled copy of an array.
 *
 * Unlike {@link fisherYatesShuffle}, this function does not mutate the
 * original array.
 *
 * @template T - Array element type
 * @param array - Array to shuffle (not mutated)
 * @returns A new, shuffled array
 *
 * @example
 * ```typescript
 * const arr = [1, 2, 3, 4, 5];
 * const shuffled = shuffleCopy(arr);
 * console.log(arr);      // [1, 2, 3, 4, 5] - unchanged
 * console.log(shuffled); // e.g. [3, 1, 5, 2, 4]
 * ```
 */
export declare function shuffleCopy<T>(array: T[]): T[];
/**
 * Takes a random sample of n elements from an array.
 *
 * Uses Fisher-Yates shuffle for efficient random selection.
 * Returns at most array.length elements.
 *
 * @template T - Array element type
 * @param array - Array to sample from
 * @param count - Number of elements to sample
 * @returns Array of randomly selected elements
 *
 * @example
 * ```typescript
 * const arr = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
 * const sample = randomSample(arr, 3);
 * console.log(sample); // e.g. [7, 2, 9]
 * ```
 */
export declare function randomSample<T>(array: T[], count: number): T[];
/**
 * Splits an array into chunks (sub-arrays) of a given size.
 *
 * @template T - Array element type
 * @param array - Array to split
 * @param size - Size of each chunk (must be > 0)
 * @returns Array of chunks
 *
 * @example
 * ```typescript
 * const arr = [1, 2, 3, 4, 5];
 * const chunks = chunkArray(arr, 2);
 * console.log(chunks); // [[1, 2], [3, 4], [5]]
 * ```
 */
export declare function chunkArray<T>(array: T[], size: number): T[][];
/**
 * Creates sliding windows over an array.
 *
 * @template T - Array element type
 * @param array - Array to create windows over
 * @param size - Window size
 * @param step - Step between windows (default: 1)
 * @returns Array of windows
 *
 * @example
 * ```typescript
 * const arr = [1, 2, 3, 4, 5];
 * const windows = slidingWindow(arr, 3);
 * console.log(windows); // [[1, 2, 3], [2, 3, 4], [3, 4, 5]]
 *
 * const steppedWindows = slidingWindow(arr, 2, 2);
 * console.log(steppedWindows); // [[1, 2], [3, 4]]
 * ```
 */
export declare function slidingWindow<T>(array: T[], size: number, step?: number): T[][];
/**
 * Interleaves two arrays.
 *
 * @template T - Array element type
 * @param array1 - First array
 * @param array2 - Second array
 * @returns Interleaved array
 *
 * @example
 * ```typescript
 * const a = [1, 3, 5];
 * const b = [2, 4, 6];
 * console.log(interleaveArrays(a, b)); // [1, 2, 3, 4, 5, 6]
 * ```
 */
export declare function interleaveArrays<T>(array1: T[], array2: T[]): T[];
/**
 * Rotates an array by n positions.
 *
 * Positive n rotates right (end -> start),
 * negative n rotates left (start -> end).
 *
 * @template T - Array element type
 * @param array - Array to rotate
 * @param positions - Positions to rotate (positive = right, negative = left)
 * @returns New rotated array
 *
 * @example
 * ```typescript
 * const arr = [1, 2, 3, 4, 5];
 * console.log(rotateArray(arr, 2));  // [4, 5, 1, 2, 3]
 * console.log(rotateArray(arr, -2)); // [3, 4, 5, 1, 2]
 * ```
 */
export declare function rotateArray<T>(array: T[], positions: number): T[];
/**
 * Finds unique elements based on a key function.
 *
 * @template T - Array element type
 * @template K - Key type
 * @param array - Array to scan
 * @param keyFn - Function that extracts the comparison key
 * @returns Array of unique elements (keeps the first occurrence)
 *
 * @example
 * ```typescript
 * const users = [
 *   { id: 1, name: 'Alice' },
 *   { id: 2, name: 'Bob' },
 *   { id: 1, name: 'Alice Clone' }
 * ];
 * const unique = uniqueBy(users, u => u.id);
 * // [{ id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }]
 * ```
 */
export declare function uniqueBy<T, K>(array: T[], keyFn: (item: T) => K): T[];
/**
 * Finds unique elements using JSON stringification as the key.
 *
 * @template T - Array element type
 * @param array - Array to scan
 * @param keyFn - Optional function to extract the value to stringify
 * @returns Array of unique elements
 */
export declare function uniqueByJson<T>(array: T[], keyFn?: (item: T) => unknown): T[];
//# sourceMappingURL=array-helpers.d.ts.map