Collection Methods

/**
 * Creates an array of values corresponding to `paths` of `object`.
 * @param object - The object to iterate over
 * @param paths - The property paths to pick
 * @returns Returns the picked values
 */
function at<T>(object: T, paths: Array<string | number>): any[];

/**
 * Creates an object composed of keys generated from the results of running
 * each element of `collection` thru `iteratee`. The corresponding value of
 * each key is the number of times the key was returned by `iteratee`.
 * @param collection - The collection to iterate over
 * @param iteratee - The iteratee to transform keys
 * @returns Returns the composed aggregate object
 */
function countBy<T>(
  collection: T[],
  iteratee?: string | ((value: T) => any)
): Record<string, number>;

/**
 * Checks if `predicate` returns truthy for **all** elements of `collection`.
 * Iteration is stopped once `predicate` returns falsey.
 * @param collection - The collection to iterate over
 * @param predicate - The function invoked per iteration
 * @returns Returns `true` if all elements pass the predicate check, else `false`
 */
function every<T>(
  collection: T[],
  predicate?: string | object | ((value: T, index: number, collection: T[]) => boolean)
): boolean;

/**
 * Iterates over elements of `collection`, returning an array of all elements
 * `predicate` returns truthy for.
 * @param collection - The collection to iterate over
 * @param predicate - The function invoked per iteration
 * @returns Returns the new filtered array
 */
function filter<T>(
  collection: T[],
  predicate?: string | object | ((value: T, index: number, collection: T[]) => boolean)
): T[];

/**
 * Iterates over elements of `collection`, returning the first element
 * `predicate` returns truthy for.
 * @param collection - The collection to inspect
 * @param predicate - The function invoked per iteration
 * @param fromIndex - The index to search from
 * @returns Returns the matched element, else `undefined`
 */
function find<T>(
  collection: T[],
  predicate?: string | object | ((value: T, index: number, collection: T[]) => boolean),
  fromIndex?: number
): T | undefined;

/**
 * This method is like `find` except that it iterates over elements of
 * `collection` from right to left.
 * @param collection - The collection to inspect
 * @param predicate - The function invoked per iteration
 * @param fromIndex - The index to search from
 * @returns Returns the matched element, else `undefined`
 */
function findLast<T>(
  collection: T[],
  predicate?: string | object | ((value: T, index: number, collection: T[]) => boolean),
  fromIndex?: number
): T | undefined;

/**
 * Creates a flattened array of values by running each element in `collection`
 * thru `iteratee` and flattening the mapped results. The iteratee is invoked
 * with three arguments: (value, index|key, collection).
 * @param collection - The collection to iterate over
 * @param iteratee - The function invoked per iteration
 * @returns Returns the new flattened array
 */
function flatMap<T, R>(
  collection: T[],
  iteratee?: string | ((value: T, index: number, collection: T[]) => R | R[])
): R[];

/**
 * This method is like `flatMap` except that it recursively flattens the
 * mapped results.
 * @param collection - The collection to iterate over
 * @param iteratee - The function invoked per iteration
 * @returns Returns the new flattened array
 */
function flatMapDeep<T, R>(
  collection: T[],
  iteratee?: string | ((value: T, index: number, collection: T[]) => R | R[])
): R[];

/**
 * This method is like `flatMap` except that it recursively flattens the
 * mapped results up to `depth` times.
 * @param collection - The collection to iterate over
 * @param iteratee - The function invoked per iteration
 * @param depth - The maximum recursion depth
 * @returns Returns the new flattened array
 */
function flatMapDepth<T, R>(
  collection: T[],
  iteratee?: string | ((value: T, index: number, collection: T[]) => R | R[]),
  depth?: number
): R[];

/**
 * Iterates over elements of `collection` and invokes `iteratee` for each element.
 * The iteratee is invoked with three arguments: (value, index|key, collection).
 * Iteratee functions may exit iteration early by explicitly returning `false`.
 * @param collection - The collection to iterate over
 * @param iteratee - The function invoked per iteration
 * @returns Returns `collection`
 */
function forEach<T>(
  collection: T[],
  iteratee?: (value: T, index: number, collection: T[]) => any
): T[];

function forEach<T>(
  collection: Record<string, T>,
  iteratee?: (value: T, key: string, collection: Record<string, T>) => any
): Record<string, T>;

/**
 * This method is like `forEach` except that it iterates over elements of
 * `collection` from right to left.
 * @param collection - The collection to iterate over
 * @param iteratee - The function invoked per iteration
 * @returns Returns `collection`
 */
function forEachRight<T>(
  collection: T[],
  iteratee?: (value: T, index: number, collection: T[]) => any
): T[];

function forEachRight<T>(
  collection: Record<string, T>,
  iteratee?: (value: T, key: string, collection: Record<string, T>) => any
): Record<string, T>;

/**
 * Creates an object composed of keys generated from the results of running
 * each element of `collection` thru `iteratee`. The order of grouped values
 * is determined by the order they occur in `collection`.
 * @param collection - The collection to iterate over
 * @param iteratee - The iteratee to transform keys
 * @returns Returns the composed aggregate object
 */
function groupBy<T>(
  collection: T[],
  iteratee?: string | ((value: T) => any)
): Record<string, T[]>;

/**
 * Checks if `value` is in `collection`. If `collection` is a string, it's
 * checked for a substring of `value`, otherwise SameValueZero is used for
 * equality comparisons.
 * @param collection - The collection to inspect
 * @param value - The value to search for
 * @param fromIndex - The index to search from
 * @returns Returns `true` if `value` is found, else `false`
 */
function includes<T>(collection: T[], value: T, fromIndex?: number): boolean;
function includes(collection: string, value: string, fromIndex?: number): boolean;
function includes<T>(collection: Record<string, T>, value: T): boolean;

/**
 * Invokes the method at `path` of each element in `collection`, returning
 * an array of the results of each invoked method.
 * @param collection - The collection to iterate over
 * @param path - The path of the method to invoke
 * @param args - The arguments to invoke each method with
 * @returns Returns the array of results
 */
function invokeMap<T>(
  collection: T[],
  path: string | ((value: T) => any),
  ...args: any[]
): any[];

/**
 * Creates an object composed of keys generated from the results of running
 * each element of `collection` thru `iteratee`. The corresponding value of
 * each key is the last element responsible for generating the key.
 * @param collection - The collection to iterate over
 * @param iteratee - The iteratee to transform keys
 * @returns Returns the composed aggregate object
 */
function keyBy<T>(
  collection: T[],
  iteratee?: string | ((value: T) => any)
): Record<string, T>;

/**
 * Creates an array of values by running each element in `collection` thru
 * `iteratee`. The iteratee is invoked with three arguments:
 * (value, index|key, collection).
 * @param collection - The collection to iterate over
 * @param iteratee - The function invoked per iteration
 * @returns Returns the new mapped array
 */
function map<T, R>(
  collection: T[],
  iteratee?: string | ((value: T, index: number, collection: T[]) => R)
): R[];

function map<T, R>(
  collection: Record<string, T>,
  iteratee?: string | ((value: T, key: string, collection: Record<string, T>) => R)
): R[];

/**
 * This method is like `sortBy` except that it allows specifying the sort
 * orders of the iteratees to sort by. If `orders` is unspecified, all values
 * are sorted in ascending order. Otherwise, specify an order of "desc" for
 * descending or "asc" for ascending sort order of corresponding values.
 * @param collection - The collection to iterate over
 * @param iteratees - The iteratees to sort by
 * @param orders - The sort orders of `iteratees`
 * @returns Returns the new sorted array
 */
function orderBy<T>(
  collection: T[],
  iteratees?: Array<string | ((value: T) => any)>,
  orders?: Array<'asc' | 'desc'>
): T[];

/**
 * Creates an array of elements split into two groups, the first of which
 * contains elements `predicate` returns truthy for, the second of which
 * contains elements `predicate` returns falsey for.
 * @param collection - The collection to iterate over
 * @param predicate - The function invoked per iteration
 * @returns Returns the array of grouped elements
 */
function partition<T>(
  collection: T[],
  predicate?: string | object | ((value: T, index: number, collection: T[]) => boolean)
): [T[], T[]];

/**
 * Reduces `collection` to a value which is the accumulated result of running
 * each element in `collection` thru `iteratee`, where each successive
 * invocation is supplied the return value of the previous.
 * @param collection - The collection to iterate over
 * @param iteratee - The function invoked per iteration
 * @param accumulator - The initial value
 * @returns Returns the accumulated value
 */
function reduce<T, R>(
  collection: T[],
  iteratee: (accumulator: R, value: T, index: number, collection: T[]) => R,
  accumulator?: R
): R;

function reduce<T, R>(
  collection: Record<string, T>,
  iteratee: (accumulator: R, value: T, key: string, collection: Record<string, T>) => R,
  accumulator?: R
): R;

/**
 * This method is like `reduce` except that it iterates over elements of
 * `collection` from right to left.
 * @param collection - The collection to iterate over
 * @param iteratee - The function invoked per iteration
 * @param accumulator - The initial value
 * @returns Returns the accumulated value
 */
function reduceRight<T, R>(
  collection: T[],
  iteratee: (accumulator: R, value: T, index: number, collection: T[]) => R,
  accumulator?: R
): R;

function reduceRight<T, R>(
  collection: Record<string, T>,
  iteratee: (accumulator: R, value: T, key: string, collection: Record<string, T>) => R,
  accumulator?: R
): R;

/**
 * The opposite of `filter`; this method returns the elements of `collection`
 * that `predicate` does **not** return truthy for.
 * @param collection - The collection to iterate over
 * @param predicate - The function invoked per iteration
 * @returns Returns the new filtered array
 */
function reject<T>(
  collection: T[],
  predicate?: string | object | ((value: T, index: number, collection: T[]) => boolean)
): T[];

/**
 * Gets a random element from `collection`.
 * @param collection - The collection to sample
 * @returns Returns the random element
 */
function sample<T>(collection: T[]): T | undefined;
function sample<T>(collection: Record<string, T>): T | undefined;

/**
 * Gets `n` random elements at unique keys from `collection` up to the
 * size of `collection`.
 * @param collection - The collection to sample
 * @param n - The number of elements to sample
 * @returns Returns the random elements
 */
function sampleSize<T>(collection: T[], n?: number): T[];
function sampleSize<T>(collection: Record<string, T>, n?: number): T[];

/**
 * Creates an array of shuffled values, using a version of the
 * [Fisher-Yates shuffle](https://en.wikipedia.org/wiki/Fisher-Yates_shuffle).
 * @param collection - The collection to shuffle
 * @returns Returns the new shuffled array
 */
function shuffle<T>(collection: T[]): T[];
function shuffle<T>(collection: Record<string, T>): T[];

/**
 * Gets the size of `collection` by returning its length for array-like
 * values or the number of own enumerable string keyed properties for objects.
 * @param collection - The collection to inspect
 * @returns Returns the collection size
 */
function size(collection: any[] | object | string): number;

/**
 * Checks if `predicate` returns truthy for **any** element of `collection`.
 * Iteration is stopped once `predicate` returns truthy.
 * @param collection - The collection to iterate over
 * @param predicate - The function invoked per iteration
 * @returns Returns `true` if any element passes the predicate check, else `false`
 */
function some<T>(
  collection: T[],
  predicate?: string | object | ((value: T, index: number, collection: T[]) => boolean)
): boolean;

/**
 * Creates an array of elements, sorted in ascending order by the results
 * of running each element in a collection thru each iteratee.
 * @param collection - The collection to iterate over
 * @param iteratees - The iteratees to sort by
 * @returns Returns the new sorted array
 */
function sortBy<T>(
  collection: T[],
  ...iteratees: Array<string | ((value: T) => any)>
): T[];