Array Operations

/**
 * Array constructor with enhanced static methods
 */
interface ArrayConstructor {
  /**
   * Creates an array from an array-like or iterable object
   * @param arrayLike - Array-like or iterable object to convert
   * @param mapfn - Optional mapping function to call on every element
   * @param thisArg - Value to use as this when executing mapfn
   */
  from<T>(arrayLike: ArrayLike<T> | Iterable<T>): T[];
  from<T, U>(arrayLike: ArrayLike<T> | Iterable<T>, mapfn: (v: T, k: number) => U, thisArg?: any): U[];
  
  /**
   * Creates an array from an async iterable
   * @param asyncIterable - Async iterable to convert to array
   * @param mapfn - Optional async mapping function
   * @param thisArg - Value to use as this when executing mapfn
   */
  fromAsync<T>(asyncIterable: AsyncIterable<T> | Iterable<T | Promise<T>>): Promise<T[]>;
  fromAsync<T, U>(asyncIterable: AsyncIterable<T> | Iterable<T | Promise<T>>, mapfn: (v: T, k: number) => U | Promise<U>, thisArg?: any): Promise<U[]>;
  
  /**
   * Creates an array from the given arguments
   * @param items - Items to include in the array
   */
  of<T>(...items: T[]): T[];
  
  /**
   * Determines whether the passed value is an array
   * @param arg - Value to test
   */
  isArray(arg: any): arg is any[];
}

import Array from 'core-js-pure/stable/array';

// Convert string to array of characters
const chars = Array.from('hello'); // ['h', 'e', 'l', 'l', 'o']

// Convert with mapping function
const numbers = Array.from([1, 2, 3], x => x * 2); // [2, 4, 6]

// Create array from arguments
const arr = Array.of(1, 2, 3); // [1, 2, 3]

// Async array creation
const asyncArray = await Array.fromAsync([
  Promise.resolve(1),
  Promise.resolve(2),
  Promise.resolve(3)
]); // [1, 2, 3]

// Type checking
Array.isArray([1, 2, 3]); // true
Array.isArray('hello'); // false

interface Array<T> {
  /**
   * Access element at the given index, supporting negative indices
   * @param index - Index to access (can be negative)
   */
  at(index: number): T | undefined;
  
  /**
   * Copies array elements within the array to another location
   * @param target - Index to copy elements to
   * @param start - Index to start copying from
   * @param end - Index to end copying at
   */
  copyWithin(target: number, start?: number, end?: number): this;
  
  /**
   * Tests whether all elements pass the provided test function
   * @param predicate - Function to test each element
   * @param thisArg - Value to use as this when executing predicate
   */
  every<S extends T>(predicate: (value: T, index: number, array: T[]) => value is S, thisArg?: any): this is S[];
  every(predicate: (value: T, index: number, array: T[]) => unknown, thisArg?: any): boolean;
  
  /**
   * Fills array elements with a static value
   * @param value - Value to fill array with
   * @param start - Start index
   * @param end - End index
   */
  fill(value: T, start?: number, end?: number): this;
  
  /**
   * Creates array with elements that pass the test function
   * @param predicate - Function to test each element
   * @param thisArg - Value to use as this when executing predicate
   */
  filter<S extends T>(predicate: (value: T, index: number, array: T[]) => value is S, thisArg?: any): S[];
  filter(predicate: (value: T, index: number, array: T[]) => unknown, thisArg?: any): T[];
  
  /**
   * Returns the first element that satisfies the test function
   * @param predicate - Function to test each element
   * @param thisArg - Value to use as this when executing predicate
   */
  find<S extends T>(predicate: (value: T, index: number, obj: T[]) => value is S, thisArg?: any): S | undefined;
  find(predicate: (value: T, index: number, obj: T[]) => unknown, thisArg?: any): T | undefined;
  
  /**
   * Returns the index of the first element that satisfies the test function
   * @param predicate - Function to test each element
   * @param thisArg - Value to use as this when executing predicate
   */
  findIndex(predicate: (value: T, index: number, obj: T[]) => unknown, thisArg?: any): number;
  
  /**
   * Returns the last element that satisfies the test function
   * @param predicate - Function to test each element
   * @param thisArg - Value to use as this when executing predicate
   */
  findLast<S extends T>(predicate: (value: T, index: number, array: T[]) => value is S, thisArg?: any): S | undefined;
  findLast(predicate: (value: T, index: number, array: T[]) => unknown, thisArg?: any): T | undefined;
  
  /**
   * Returns the index of the last element that satisfies the test function
   * @param predicate - Function to test each element
   * @param thisArg - Value to use as this when executing predicate
   */
  findLastIndex(predicate: (value: T, index: number, array: T[]) => unknown, thisArg?: any): number;
  
  /**
   * Creates new array with all sub-array elements flattened
   * @param depth - Depth level to flatten
   */
  flat<D = 1>(depth?: D): FlatArray<T, D>[];
  
  /**
   * Maps each element using mapping function, then flattens result
   * @param callback - Function that produces element for new array
   * @param thisArg - Value to use as this when executing callback
   */
  flatMap<U, This = undefined>(callback: (value: T, index: number, array: T[]) => U | ReadonlyArray<U>, thisArg?: This): U[];
  
  /**
   * Executes provided function once for each array element
   * @param callbackfn - Function to execute for each element
   * @param thisArg - Value to use as this when executing callbackfn
   */
  forEach(callbackfn: (value: T, index: number, array: T[]) => void, thisArg?: any): void;
  
  /**
   * Determines whether array includes certain element
   * @param searchElement - Element to search for
   * @param fromIndex - Index to start search from
   */
  includes(searchElement: T, fromIndex?: number): boolean;
  
  /**
   * Returns first index of element, or -1 if not found
   * @param searchElement - Element to search for
   * @param fromIndex - Index to start search from
   */
  indexOf(searchElement: T, fromIndex?: number): number;
  
  /**
   * Joins array elements into string
   * @param separator - String to separate elements
   */
  join(separator?: string): string;
  
  /**
   * Returns last index of element, or -1 if not found
   * @param searchElement - Element to search for
   * @param fromIndex - Index to start search from
   */
  lastIndexOf(searchElement: T, fromIndex?: number): number;
  
  /**
   * Creates new array with results of calling function on every element
   * @param callbackfn - Function that produces element for new array
   * @param thisArg - Value to use as this when executing callbackfn
   */
  map<U>(callbackfn: (value: T, index: number, array: T[]) => U, thisArg?: any): U[];
  
  /**
   * Adds elements to end of array and returns new length
   * @param items - Elements to add
   */
  push(...items: T[]): number;
  
  /**
   * Executes reducer function on each element, resulting in single value
   * @param callbackfn - Reducer function
   * @param initialValue - Initial value for accumulator
   */
  reduce(callbackfn: (previousValue: T, currentValue: T, currentIndex: number, array: T[]) => T): T;
  reduce(callbackfn: (previousValue: T, currentValue: T, currentIndex: number, array: T[]) => T, initialValue: T): T;
  reduce<U>(callbackfn: (previousValue: U, currentValue: T, currentIndex: number, array: T[]) => U, initialValue: U): U;
  
  /**
   * Executes reducer function on each element from right to left
   * @param callbackfn - Reducer function
   * @param initialValue - Initial value for accumulator
   */
  reduceRight(callbackfn: (previousValue: T, currentValue: T, currentIndex: number, array: T[]) => T): T;
  reduceRight(callbackfn: (previousValue: T, currentValue: T, currentIndex: number, array: T[]) => T, initialValue: T): T;
  reduceRight<U>(callbackfn: (previousValue: U, currentValue: T, currentIndex: number, array: T[]) => U, initialValue: U): U;
  
  /**
   * Reverses array in place
   */
  reverse(): T[];
  
  /**
   * Returns shallow copy of portion of array
   * @param start - Start index
   * @param end - End index
   */
  slice(start?: number, end?: number): T[];
  
  /**
   * Tests whether at least one element passes the test function
   * @param predicate - Function to test each element
   * @param thisArg - Value to use as this when executing predicate
   */
  some(predicate: (value: T, index: number, array: T[]) => unknown, thisArg?: any): boolean;
  
  /**
   * Sorts elements in place
   * @param compareFn - Function to determine sort order
   */
  sort(compareFn?: (a: T, b: T) => number): this;
  
  /**
   * Changes array by removing/replacing existing elements and/or adding new elements
   * @param start - Start index
   * @param deleteCount - Number of elements to remove
   * @param items - Elements to add
   */
  splice(start: number, deleteCount?: number, ...items: T[]): T[];
  
  /**
   * Creates new array with elements reversed (immutable)
   */
  toReversed(): T[];
  
  /**
   * Creates new array with elements sorted (immutable)
   * @param compareFn - Function to determine sort order
   */
  toSorted(compareFn?: (a: T, b: T) => number): T[];
  
  /**
   * Creates new array with some elements removed/replaced (immutable)
   * @param start - Start index
   * @param deleteCount - Number of elements to remove
   * @param items - Elements to add
   */
  toSpliced(start: number, deleteCount?: number, ...items: T[]): T[];
  
  /**
   * Adds elements to beginning of array and returns new length
   * @param items - Elements to add
   */
  unshift(...items: T[]): number;
  
  /**
   * Groups array elements by key returned by grouping function
   * @param callbackfn - Function that returns grouping key
   * @param thisArg - Value to use as this when executing callbackfn
   */
  group<K extends PropertyKey>(callbackfn: (value: T, index: number, array: T[]) => K, thisArg?: any): Partial<Record<K, T[]>>;
  
  /**
   * Groups array elements by key into a Map
   * @param callbackfn - Function that returns grouping key
   * @param thisArg - Value to use as this when executing callbackfn
   */
  groupToMap<K>(callbackfn: (value: T, index: number, array: T[]) => K, thisArg?: any): Map<K, T[]>;
  
  /**
   * Creates new array with element at index replaced (immutable)
   * @param index - Index to replace
   * @param value - New value
   */
  with(index: number, value: T): T[];
  
  /**
   * Returns iterator for array entries [index, value]
   */
  entries(): IterableIterator<[number, T]>;
  
  /**
   * Returns iterator for array indices
   */
  keys(): IterableIterator<number>;
  
  /**
   * Returns iterator for array values
   */
  values(): IterableIterator<T>;
  
  /**
   * Returns iterator for array values (same as values())
   */
  [Symbol.iterator](): IterableIterator<T>;
}

import Array from 'core-js-pure/stable/array';

// Modern array access
const arr = [1, 2, 3, 4, 5];
console.log(arr.at(-1)); // 5 (last element)
console.log(arr.at(-2)); // 4 (second to last)

// Flattening arrays
const nested = [1, [2, 3], [4, [5, 6]]];
console.log(nested.flat()); // [1, 2, 3, 4, [5, 6]]
console.log(nested.flat(2)); // [1, 2, 3, 4, 5, 6]

// Immutable operations
const original = [3, 1, 4, 1, 5];
const sorted = original.toSorted(); // [1, 1, 3, 4, 5]
const reversed = original.toReversed(); // [5, 1, 4, 1, 3]
const replaced = original.with(2, 9); // [3, 1, 9, 1, 5]
console.log(original); // [3, 1, 4, 1, 5] (unchanged)

// Find methods
const users = [
  { name: 'Alice', age: 25 },
  { name: 'Bob', age: 30 },
  { name: 'Charlie', age: 35 }
];

const lastAdult = users.findLast(user => user.age >= 30); // { name: 'Charlie', age: 35 }
const lastAdultIndex = users.findLastIndex(user => user.age >= 30); // 2

/**
 * Virtual array methods - pure functions that don't modify prototypes
 * Available via: core-js-pure/array/virtual/{method-name}
 */

// Example virtual method signatures
declare function map<T, U>(array: T[], callbackfn: (value: T, index: number, array: T[]) => U, thisArg?: any): U[];
declare function filter<T>(array: T[], predicate: (value: T, index: number, array: T[]) => unknown, thisArg?: any): T[];
declare function find<T>(array: T[], predicate: (value: T, index: number, array: T[]) => unknown, thisArg?: any): T | undefined;
declare function reduce<T>(array: T[], callbackfn: (previousValue: T, currentValue: T, currentIndex: number, array: T[]) => T): T;
declare function reduce<T, U>(array: T[], callbackfn: (previousValue: U, currentValue: T, currentIndex: number, array: T[]) => U, initialValue: U): U;

import map from 'core-js-pure/array/virtual/map';
import filter from 'core-js-pure/array/virtual/filter';
import reduce from 'core-js-pure/array/virtual/reduce';

// Use as pure functions without modifying prototypes
const numbers = [1, 2, 3, 4, 5];
const doubled = map(numbers, x => x * 2); // [2, 4, 6, 8, 10]
const evens = filter(numbers, x => x % 2 === 0); // [2, 4]
const sum = reduce(numbers, (acc, val) => acc + val, 0); // 15

// Chain operations functionally
const result = reduce(
  filter(
    map(numbers, x => x * 2),
    x => x > 5
  ),
  (acc, val) => acc + val,
  0
); // 30 (6 + 8 + 10)

import Array from 'core-js-pure/stable/array';

// Create arrays from various sources
const fromString = Array.from('hello'); // ['h', 'e', 'l', 'l', 'o']
const fromSet = Array.from(new Set([1, 2, 2, 3])); // [1, 2, 3]
const fromNodeList = Array.from(document.querySelectorAll('div'));

// With transformation
const squares = Array.from({ length: 5 }, (_, i) => i * i); // [0, 1, 4, 9, 16]
const doubled = Array.from([1, 2, 3], x => x * 2); // [2, 4, 6]

// Modern immutable methods avoid mutation
const original = [1, 2, 3, 4, 5];

// All these return new arrays
const operations = {
  reversed: original.toReversed(),
  sorted: original.toSorted((a, b) => b - a),
  withReplacement: original.with(2, 99),
  spliced: original.toSpliced(1, 2, 'a', 'b')
};

console.log(original); // [1, 2, 3, 4, 5] - unchanged

const data = [
  { id: 1, name: 'Alice', active: true },
  { id: 2, name: 'Bob', active: false },
  { id: 3, name: 'Charlie', active: true }
];

// Modern find methods
const lastActive = data.findLast(user => user.active); // Charlie
const firstInactiveIndex = data.findIndex(user => !user.active); // 1

// Complex filtering with type guards
function isActive<T extends { active: boolean }>(item: T): item is T & { active: true } {
  return item.active;
}

const activeUsers = data.filter(isActive); // Type is narrowed to active users