Array Operations

/**
 * Transform each array element using iterator function
 * @param array - Array to transform
 * @param iterate - Iterator function receiving (item, index, array)
 * @param context - Optional context for iterator
 * @returns New array with transformed elements
 */
function map<T, U, C = any>(
  array: T[], 
  iterate: (this: C, item: T, index: number, array: T[]) => U, 
  context?: C
): U[];

/**
 * Filter array elements based on predicate function
 * @param array - Array to filter
 * @param iterate - Predicate function returning boolean
 * @param context - Optional context for predicate
 * @returns New array with filtered elements
 */
function filter<T, C = any>(
  array: T[], 
  iterate: (this: C, item: T, index: number, array: T[]) => boolean, 
  context?: C
): T[];

/**
 * Find first element matching predicate
 * @param array - Array to search
 * @param iterate - Predicate function
 * @param context - Optional context for predicate
 * @returns First matching element or undefined
 */
function find<T, C = any>(
  array: T[], 
  iterate: (this: C, item: T, index: number, array: T[]) => boolean, 
  context?: C
): T | undefined;

/**
 * Find last element matching predicate
 * @param array - Array to search
 * @param iterate - Predicate function
 * @param context - Optional context for predicate
 * @returns Last matching element or undefined
 */
function findLast<T, C = any>(
  array: T[], 
  iterate: (this: C, item: T, index: number, array: T[]) => boolean, 
  context?: C
): T | undefined;

/**
 * Remove duplicate elements from array
 * @param array - Array to process
 * @returns New array with unique elements
 */
function uniq<T>(array: T[]): T[];

/**
 * Create union of multiple arrays (unique elements from all)
 * @param arrays - Arrays to union
 * @returns New array with unique elements from all input arrays
 */
function union<T>(...arrays: T[][]): T[];

/**
 * Extract slice of array
 * @param array - Array to slice
 * @param startIndex - Start index (inclusive)
 * @param endIndex - End index (exclusive)
 * @returns New array slice
 */
function slice<T>(array: T[], startIndex?: number, endIndex?: number): T[];

/**
 * Split array into chunks of specified size
 * @param array - Array to chunk
 * @param size - Size of each chunk
 * @returns Array of chunks
 */
function chunk<T>(array: T[], size: number): T[][];

/**
 * Flatten nested arrays (optimized for arrays of arrays)
 * @param array - Array of arrays to flatten
 * @param deep - Whether to deeply flatten (default: shallow)
 * @returns Flattened array
 */
function flatten<T>(array: T[][], deep?: boolean): T[];

/**
 * Flatten nested arrays (general purpose)
 * @param array - Any nested array structure to flatten
 * @param deep - Whether to deeply flatten (default: shallow)
 * @returns Flattened array
 */
function flatten<T>(array: any[], deep?: boolean): T[];

/**
 * Zip multiple arrays together
 * @param arrays - Arrays to zip
 * @returns Array of arrays where each sub-array contains elements at same index
 */
function zip<T>(...arrays: T[][]): T[][];

/**
 * Unzip array of arrays
 * @param array - Array of arrays to unzip
 * @returns Multiple arrays with elements grouped by position
 */
function unzip<T>(array: T[][]): T[][];

/**
 * Create object from key and value arrays
 * @param keys - Array of keys
 * @param values - Array of values
 * @returns Object with keys mapped to values
 */
function zipObject<T>(keys: string[], values: T[]): { [key: string]: T };

/**
 * Convert value to array
 * @param value - Value to convert
 * @returns Array representation of value
 */
function toArray<T>(value: T | T[]): T[];

/**
 * Copy array elements within array
 * @param array - Array to modify
 * @param target - Target index to copy to
 * @param start - Start index to copy from
 * @param end - End index to copy from
 * @returns Modified array
 */
function copyWithin<T>(array: T[], target: number, start: number, end?: number): T[];

/**
 * Sort array by computed values
 * @param array - Array to sort
 * @param iterate - Function to compute sort values
 * @param context - Optional context for iterator
 * @returns New sorted array
 */
function sortBy<T, C = any>(
  array: T[], 
  iterate: (this: C, item: T) => any, 
  context?: C
): T[];

/**
 * Sort array by multiple criteria
 * @param array - Array to sort
 * @param iterates - Array of functions to compute sort values
 * @param orders - Array of sort orders ('asc' or 'desc')
 * @returns New sorted array
 */
function orderBy<T>(
  array: T[], 
  iterates: Array<(item: T) => any>, 
  orders?: Array<'asc' | 'desc'>
): T[];

/**
 * Randomly shuffle array elements
 * @param array - Array to shuffle
 * @returns New shuffled array
 */
function shuffle<T>(array: T[]): T[];

/**
 * Get random sample from array
 * @param array - Array to sample from
 * @param count - Number of elements to sample
 * @returns Array of sampled elements
 */
function sample<T>(array: T[], count?: number): T[];

/**
 * Iterate over array elements
 * @param array - Array to iterate
 * @param iterate - Iterator function receiving (item, index, array)
 * @param context - Optional context for iterator
 */
function arrayEach<T, C = any>(
  array: T[], 
  iterate: (this: C, item: T, index: number, array: T[]) => void, 
  context?: C
): void;

/**
 * Iterate over array elements in reverse order
 * @param array - Array to iterate
 * @param iterate - Iterator function receiving (item, index, array)
 * @param context - Optional context for iterator
 */
function lastArrayEach<T, C = any>(
  array: T[], 
  iterate: (this: C, item: T, index: number, array: T[]) => void, 
  context?: C
): void;

/**
 * Find index of element using custom comparison
 * @param array - Array to search
 * @param searchElement - Element to find
 * @param fromIndex - Starting index for search
 * @returns Index of element or -1 if not found
 */
function arrayIndexOf<T>(array: T[], searchElement: T, fromIndex?: number): number;

/**
 * Find last index of element
 * @param array - Array to search
 * @param searchElement - Element to find
 * @param fromIndex - Starting index for reverse search
 * @returns Last index of element or -1 if not found
 */
function arrayLastIndexOf<T>(array: T[], searchElement: T, fromIndex?: number): number;

/**
 * Check if array includes element
 * @param array - Array to check
 * @param searchElement - Element to find
 * @param fromIndex - Starting index for search
 * @returns True if element is found
 */
function includes<T>(array: T[], searchElement: T, fromIndex?: number): boolean;

/**
 * Find key of first matching property in object
 * @param obj - Object to search
 * @param iterate - Predicate function
 * @param context - Optional context
 * @returns Key of matching property or undefined
 */
function findKey<T, C = any>(
  obj: T, 
  iterate: (this: C, value: any, key: string, obj: T) => boolean, 
  context?: C
): string | undefined;

/**
 * Check if array includes any of the specified values
 * @param array - Array to check
 * @param values - Values to search for
 * @returns True if any value is found
 */
function includeArrays<T>(array: T[], values: T[]): boolean;

/**
 * Reduce array to single value
 * @param array - Array to reduce
 * @param iterate - Reducer function
 * @param initialValue - Initial accumulator value
 * @returns Reduced value
 */
function reduce<T, U>(
  array: T[], 
  iterate: (accumulator: U, currentValue: T, index: number, array: T[]) => U, 
  initialValue: U
): U;

/**
 * Extract property values from array of objects
 * @param array - Array of objects
 * @param property - Property name to extract
 * @returns Array of property values
 */
function pluck<T, K extends keyof T>(array: T[], property: K): T[K][];

/**
 * Invoke method on each array element
 * @param array - Array of objects
 * @param methodName - Method name to invoke
 * @param args - Arguments to pass to method
 * @returns Array of method results
 */
function invoke<T>(array: T[], methodName: string, ...args: any[]): any[];

/**
 * Test if some elements pass predicate test
 * @param array - Array to test
 * @param iterate - Predicate function
 * @param context - Optional context
 * @returns True if any element passes test
 */
function some<T, C = any>(
  array: T[], 
  iterate: (this: C, item: T, index: number, array: T[]) => boolean, 
  context?: C
): boolean;

/**
 * Test if all elements pass predicate test
 * @param array - Array to test
 * @param iterate - Predicate function
 * @param context - Optional context
 * @returns True if all elements pass test
 */
function every<T, C = any>(
  array: T[], 
  iterate: (this: C, item: T, index: number, array: T[]) => boolean, 
  context?: C
): boolean;

/**
 * Convert flat array to tree structure
 * @param array - Flat array with hierarchical data
 * @param options - Tree conversion options
 * @returns Tree structure
 */
function toArrayTree<T>(array: T[], options?: TreeOptions): T[];

/**
 * Convert tree structure to flat array
 * @param tree - Tree structure
 * @param options - Flattening options
 * @returns Flat array
 */
function toTreeArray<T>(tree: T[], options?: TreeOptions): T[];

/**
 * Find nodes in tree structure
 * @param tree - Tree structure to search
 * @param iterate - Predicate function
 * @param options - Tree traversal options
 * @param context - Optional context
 * @returns Found nodes
 */
function findTree<T, C = any>(
  tree: T[], 
  iterate: (this: C, item: T, index: number, items: T[], path: number[], parent: T) => boolean, 
  options?: TreeOptions, 
  context?: C
): T[];

/**
 * Iterate over tree nodes
 * @param tree - Tree structure
 * @param iterate - Iterator function
 * @param options - Tree traversal options
 * @param context - Optional context
 */
function eachTree<T, C = any>(
  tree: T[], 
  iterate: (this: C, item: T, index: number, items: T[], path: number[], parent: T) => void, 
  options?: TreeOptions, 
  context?: C
): void;

interface TreeOptions {
  /** Property name for child nodes (default: 'children') */
  children?: string;
  /** Property name for parent reference (default: 'parentId') */
  parentKey?: string;
  /** Property name for node ID (default: 'id') */
  key?: string;
  /** Property name for mapping parent relationships */
  mapChildren?: string;
  /** Whether to strictly match parent-child relationships */
  strict?: boolean;
}

import { map, filter, sortBy, uniq, chunk, pluck } from 'xe-utils';

// Transform array
const numbers = [1, 2, 3, 4, 5];
const doubled = map(numbers, x => x * 2); // [2, 4, 6, 8, 10]

// Filter and sort
const users = [
  { name: 'Alice', age: 25, active: true },
  { name: 'Bob', age: 30, active: false },
  { name: 'Charlie', age: 35, active: true }
];

const activeUsers = filter(users, user => user.active);
const sortedByAge = sortBy(users, user => user.age);
const names = pluck(users, 'name'); // ['Alice', 'Bob', 'Charlie']

// Array utilities
const duplicates = [1, 2, 2, 3, 3, 3];
const unique = uniq(duplicates); // [1, 2, 3]

const items = [1, 2, 3, 4, 5, 6, 7, 8];
const chunks = chunk(items, 3); // [[1, 2, 3], [4, 5, 6], [7, 8]]