// Type definitions for Underscore 1.7.0
// Project: http://underscorejs.org/
// Definitions by: Boris Yankov , Josh Baldwin
// Definitions: https://github.com/borisyankov/DefinitelyTyped
declare module _ {
/**
* underscore.js _.throttle options.
**/
interface ThrottleSettings {
/**
* If you'd like to disable the leading-edge call, pass this as false.
**/
leading?: boolean;
/**
* If you'd like to disable the execution on the trailing-edge, pass false.
**/
trailing?: boolean;
}
/**
* underscore.js template settings, set templateSettings or pass as an argument
* to 'template()' to override defaults.
**/
interface TemplateSettings {
/**
* Default value is '/<%([\s\S]+?)%>/g'.
**/
evaluate?: RegExp;
/**
* Default value is '/<%=([\s\S]+?)%>/g'.
**/
interpolate?: RegExp;
/**
* Default value is '/<%-([\s\S]+?)%>/g'.
**/
escape?: RegExp;
/**
* By default, 'template()' places the values from your data in the local scope via the 'with' statement.
* However, you can specify a single variable name with this setting.
**/
variable?: string;
}
interface Collection { }
// Common interface between Arrays and jQuery objects
interface List extends Collection {
[index: number]: T;
length: number;
}
interface Dictionary extends Collection {
[index: string]: T;
}
interface ListIterator {
(value: T, index: number, list: List): TResult;
}
interface ObjectIterator {
(element: T, key: string, list: Dictionary): TResult;
}
interface MemoIterator {
(prev: TResult, curr: T, index: number, list: List): TResult;
}
interface MemoObjectIterator {
(prev: TResult, curr: T, key: string, list: Dictionary): TResult;
}
}
interface UnderscoreStatic {
/**
* Underscore OOP Wrapper, all Underscore functions that take an object
* as the first parameter can be invoked through this function.
* @param key First argument to Underscore object functions.
**/
(value: _.Dictionary): Underscore;
(value: Array): Underscore;
(value: T): Underscore;
/* *************
* Collections *
************* */
/**
* Iterates over a list of elements, yielding each in turn to an iterator function. The iterator is
* bound to the context object, if one is passed. Each invocation of iterator is called with three
* arguments: (element, index, list). If list is a JavaScript object, iterator's arguments will be
* (value, key, object). Delegates to the native forEach function if it exists.
* @param list Iterates over this list of elements.
* @param iterator Iterator function for each element `list`.
* @param context 'this' object in `iterator`, optional.
**/
each(
list: _.List,
iterator: _.ListIterator,
context?: any): _.List;
/**
* @see _.each
* @param object Iterates over properties of this object.
* @param iterator Iterator function for each property on `object`.
* @param context 'this' object in `iterator`, optional.
**/
each(
object: _.Dictionary,
iterator: _.ObjectIterator,
context?: any): _.Dictionary;
/**
* @see _.each
**/
forEach(
list: _.List,
iterator: _.ListIterator,
context?: any): _.List;
/**
* @see _.each
**/
forEach(
object: _.Dictionary,
iterator: _.ObjectIterator,
context?: any): _.Dictionary;
/**
* Produces a new array of values by mapping each value in list through a transformation function
* (iterator). If the native map method exists, it will be used instead. If list is a JavaScript
* object, iterator's arguments will be (value, key, object).
* @param list Maps the elements of this array.
* @param iterator Map iterator function for each element in `list`.
* @param context `this` object in `iterator`, optional.
* @return The mapped array result.
**/
map(
list: _.List,
iterator: _.ListIterator,
context?: any): TResult[];
/**
* @see _.map
* @param object Maps the properties of this object.
* @param iterator Map iterator function for each property on `object`.
* @param context `this` object in `iterator`, optional.
* @return The mapped object result.
**/
map(
object: _.Dictionary,
iterator: _.ObjectIterator,
context?: any): TResult[];
/**
* @see _.map
**/
collect(
list: _.List,
iterator: _.ListIterator,
context?: any): TResult[];
/**
* @see _.map
**/
collect(
object: _.Dictionary,
iterator: _.ObjectIterator,
context?: any): TResult[];
/**
* Also known as inject and foldl, reduce boils down a list of values into a single value.
* Memo is the initial state of the reduction, and each successive step of it should be
* returned by iterator. The iterator is passed four arguments: the memo, then the value
* and index (or key) of the iteration, and finally a reference to the entire list.
* @param list Reduces the elements of this array.
* @param iterator Reduce iterator function for each element in `list`.
* @param memo Initial reduce state.
* @param context `this` object in `iterator`, optional.
* @return Reduced object result.
**/
reduce(
list: _.Collection,
iterator: _.MemoIterator,
memo?: TResult,
context?: any): TResult;
reduce(
list: _.Dictionary,
iterator: _.MemoObjectIterator,
memo?: TResult,
context?: any): TResult;
/**
* @see _.reduce
**/
inject(
list: _.Collection,
iterator: _.MemoIterator,
memo?: TResult,
context?: any): TResult;
/**
* @see _.reduce
**/
foldl(
list: _.Collection,
iterator: _.MemoIterator,
memo?: TResult,
context?: any): TResult;
/**
* The right-associative version of reduce. Delegates to the JavaScript 1.8 version of
* reduceRight, if it exists. `foldr` is not as useful in JavaScript as it would be in a
* language with lazy evaluation.
* @param list Reduces the elements of this array.
* @param iterator Reduce iterator function for each element in `list`.
* @param memo Initial reduce state.
* @param context `this` object in `iterator`, optional.
* @return Reduced object result.
**/
reduceRight(
list: _.Collection,
iterator: _.MemoIterator,
memo?: TResult,
context?: any): TResult;
/**
* @see _.reduceRight
**/
foldr(
list: _.Collection,
iterator: _.MemoIterator,
memo?: TResult,
context?: any): TResult;
/**
* Looks through each value in the list, returning the first one that passes a truth
* test (iterator). The function returns as soon as it finds an acceptable element,
* and doesn't traverse the entire list.
* @param list Searches for a value in this list.
* @param iterator Search iterator function for each element in `list`.
* @param context `this` object in `iterator`, optional.
* @return The first acceptable found element in `list`, if nothing is found undefined/null is returned.
**/
find(
list: _.List,
iterator: _.ListIterator,
context?: any): T;
/**
* @see _.find
**/
find(
object: _.Dictionary,
iterator: _.ObjectIterator,
context?: any): T;
/**
* @see _.find
**/
find(
object: _.List|_.Dictionary,
iterator: U): T;
/**
* @see _.find
**/
find(
object: _.List|_.Dictionary,
iterator: string): T;
/**
* @see _.find
**/
detect(
list: _.List,
iterator: _.ListIterator,
context?: any): T;
/**
* @see _.find
**/
detect(
object: _.Dictionary,
iterator: _.ObjectIterator,
context?: any): T;
/**
* @see _.find
**/
detect(
object: _.List|_.Dictionary,
iterator: U): T;
/**
* @see _.find
**/
detect(
object: _.List|_.Dictionary,
iterator: string): T;
/**
* Looks through each value in the list, returning the index of the first one that passes a truth
* test (iterator). The function returns as soon as it finds an acceptable element,
* and doesn't traverse the entire list.
* @param list Searches for a value in this list.
* @param iterator Search iterator function for each element in `list`.
* @param context `this` object in `iterator`, optional.
* @return The index of the first acceptable found element in `list`, if nothing is found -1 is returned.
**/
findIndex(
list: _.List,
iterator: _.ListIterator,
context?: any): number;
/**
* Looks through each value in the list, returning an array of all the values that pass a truth
* test (iterator). Delegates to the native filter method, if it exists.
* @param list Filter elements out of this list.
* @param iterator Filter iterator function for each element in `list`.
* @param context `this` object in `iterator`, optional.
* @return The filtered list of elements.
**/
filter(
list: _.List,
iterator: _.ListIterator,
context?: any): T[];
/**
* @see _.filter
**/
filter(
object: _.Dictionary,
iterator: _.ObjectIterator,
context?: any): T[];
/**
* @see _.filter
**/
select(
list: _.List,
iterator: _.ListIterator,
context?: any): T[];
/**
* @see _.filter
**/
select(
object: _.Dictionary,
iterator: _.ObjectIterator,
context?: any): T[];
/**
* Looks through each value in the list, returning an array of all the values that contain all
* of the key-value pairs listed in properties.
* @param list List to match elements again `properties`.
* @param properties The properties to check for on each element within `list`.
* @return The elements within `list` that contain the required `properties`.
**/
where(
list: _.List,
properties: U): T[];
/**
* Looks through the list and returns the first value that matches all of the key-value pairs listed in properties.
* @param list Search through this list's elements for the first object with all `properties`.
* @param properties Properties to look for on the elements within `list`.
* @return The first element in `list` that has all `properties`.
**/
findWhere(
list: _.List,
properties: U): T;
/**
* Returns the values in list without the elements that the truth test (iterator) passes.
* The opposite of filter.
* Return all the elements for which a truth test fails.
* @param list Reject elements within this list.
* @param iterator Reject iterator function for each element in `list`.
* @param context `this` object in `iterator`, optional.
* @return The rejected list of elements.
**/
reject(
list: _.List,
iterator: _.ListIterator,
context?: any): T[];
/**
* @see _.reject
**/
reject(
object: _.Dictionary,
iterator: _.ObjectIterator,
context?: any): T[];
/**
* Returns true if all of the values in the list pass the iterator truth test. Delegates to the
* native method every, if present.
* @param list Truth test against all elements within this list.
* @param iterator Trust test iterator function for each element in `list`.
* @param context `this` object in `iterator`, optional.
* @return True if all elements passed the truth test, otherwise false.
**/
every(
list: _.List,
iterator?: _.ListIterator,
context?: any): boolean;
/**
* @see _.every
**/
every(
list: _.Dictionary,
iterator?: _.ObjectIterator,
context?: any): boolean;
/**
* @see _.every
**/
all(
list: _.List,
iterator?: _.ListIterator,
context?: any): boolean;
/**
* @see _.every
**/
all(
list: _.Dictionary,
iterator?: _.ObjectIterator,
context?: any): boolean;
/**
* Returns true if any of the values in the list pass the iterator truth test. Short-circuits and
* stops traversing the list if a true element is found. Delegates to the native method some, if present.
* @param list Truth test against all elements within this list.
* @param iterator Trust test iterator function for each element in `list`.
* @param context `this` object in `iterator`, optional.
* @return True if any elements passed the truth test, otherwise false.
**/
some(
list: _.List,
iterator?: _.ListIterator,
context?: any): boolean;
/**
* @see _.some
**/
some(
object: _.Dictionary,
iterator?: _.ObjectIterator,
context?: any): boolean;
/**
* @see _.some
**/
any(
list: _.List,
iterator?: _.ListIterator,
context?: any): boolean;
/**
* @see _.some
**/
any(
object: _.Dictionary,
iterator?: _.ObjectIterator,
context?: any): boolean;
/**
* Returns true if the value is present in the list. Uses indexOf internally,
* if list is an Array.
* @param list Checks each element to see if `value` is present.
* @param value The value to check for within `list`.
* @return True if `value` is present in `list`, otherwise false.
**/
contains(
list: _.List,
value: T): boolean;
/**
* @see _.contains
**/
contains(
object: _.Dictionary,
value: T): boolean;
/**
* @see _.contains
**/
include(
list: _.Collection,
value: T): boolean;
/**
* @see _.contains
**/
include(
object: _.Dictionary,
value: T): boolean;
/**
* Calls the method named by methodName on each value in the list. Any extra arguments passed to
* invoke will be forwarded on to the method invocation.
* @param list The element's in this list will each have the method `methodName` invoked.
* @param methodName The method's name to call on each element within `list`.
* @param arguments Additional arguments to pass to the method `methodName`.
**/
invoke(
list: _.List,
methodName: string,
...arguments: any[]): any;
/**
* A convenient version of what is perhaps the most common use-case for map: extracting a list of
* property values.
* @param list The list to pluck elements out of that have the property `propertyName`.
* @param propertyName The property to look for on each element within `list`.
* @return The list of elements within `list` that have the property `propertyName`.
**/
pluck(
list: _.List,
propertyName: string): any[];
/**
* Returns the maximum value in list.
* @param list Finds the maximum value in this list.
* @return Maximum value in `list`.
**/
max(list: _.List): number;
/**
* Returns the maximum value in list. If iterator is passed, it will be used on each value to generate
* the criterion by which the value is ranked.
* @param list Finds the maximum value in this list.
* @param iterator Compares each element in `list` to find the maximum value.
* @param context `this` object in `iterator`, optional.
* @return The maximum element within `list`.
**/
max(
list: _.List,
iterator?: _.ListIterator,
context?: any): T;
/**
* Returns the minimum value in list.
* @param list Finds the minimum value in this list.
* @return Minimum value in `list`.
**/
min(list: _.List): number;
/**
* Returns the minimum value in list. If iterator is passed, it will be used on each value to generate
* the criterion by which the value is ranked.
* @param list Finds the minimum value in this list.
* @param iterator Compares each element in `list` to find the minimum value.
* @param context `this` object in `iterator`, optional.
* @return The minimum element within `list`.
**/
min(
list: _.List,
iterator?: _.ListIterator,
context?: any): T;
/**
* Returns a sorted copy of list, ranked in ascending order by the results of running each value
* through iterator. Iterator may also be the string name of the property to sort by (eg. length).
* @param list Sorts this list.
* @param iterator Sort iterator for each element within `list`.
* @param context `this` object in `iterator`, optional.
* @return A sorted copy of `list`.
**/
sortBy(
list: _.List,
iterator?: _.ListIterator,
context?: any): T[];
/**
* @see _.sortBy
* @param iterator Sort iterator for each element within `list`.
**/
sortBy(
list: _.List,
iterator: string,
context?: any): T[];
/**
* Splits a collection into sets, grouped by the result of running each value through iterator.
* If iterator is a string instead of a function, groups by the property named by iterator on
* each of the values.
* @param list Groups this list.
* @param iterator Group iterator for each element within `list`, return the key to group the element by.
* @param context `this` object in `iterator`, optional.
* @return An object with the group names as properties where each property contains the grouped elements from `list`.
**/
groupBy(
list: _.List,
iterator?: _.ListIterator,
context?: any): _.Dictionary;
/**
* @see _.groupBy
* @param iterator Property on each object to group them by.
**/
groupBy(
list: _.List,
iterator: string,
context?: any): _.Dictionary;
/**
* Given a `list`, and an `iterator` function that returns a key for each element in the list (or a property name),
* returns an object with an index of each item. Just like _.groupBy, but for when you know your keys are unique.
**/
indexBy(
list: _.List,
iterator: _.ListIterator,
context?: any): _.Dictionary;
/**
* @see _.indexBy
* @param iterator Property on each object to index them by.
**/
indexBy(
list: _.List,
iterator: string,
context?: any): _.Dictionary;
/**
* Sorts a list into groups and returns a count for the number of objects in each group. Similar
* to groupBy, but instead of returning a list of values, returns a count for the number of values
* in that group.
* @param list Group elements in this list and then count the number of elements in each group.
* @param iterator Group iterator for each element within `list`, return the key to group the element by.
* @param context `this` object in `iterator`, optional.
* @return An object with the group names as properties where each property contains the number of elements in that group.
**/
countBy(
list: _.List,
iterator?: _.ListIterator,
context?: any): _.Dictionary;
/**
* @see _.countBy
* @param iterator Function name
**/
countBy(
list: _.List,
iterator: string,
context?: any): _.Dictionary;
/**
* Returns a shuffled copy of the list, using a version of the Fisher-Yates shuffle.
* @param list List to shuffle.
* @return Shuffled copy of `list`.
**/
shuffle(list: _.Collection): T[];
/**
* Produce a random sample from the `list`. Pass a number to return `n` random elements from the list. Otherwise a single random item will be returned.
* @param list List to sample.
* @return Random sample of `n` elements in `list`.
**/
sample(list: _.Collection, n: number): T[];
/**
* @see _.sample
**/
sample(list: _.Collection): T;
/**
* Converts the list (anything that can be iterated over), into a real Array. Useful for transmuting
* the arguments object.
* @param list object to transform into an array.
* @return `list` as an array.
**/
toArray(list: _.Collection): T[];
/**
* Return the number of values in the list.
* @param list Count the number of values/elements in this list.
* @return Number of values in `list`.
**/
size(list: _.Collection): number;
/**
* Split array into two arrays:
* one whose elements all satisfy predicate and one whose elements all do not satisfy predicate.
* @param array Array to split in two.
* @param iterator Filter iterator function for each element in `array`.
* @param context `this` object in `iterator`, optional.
* @return Array where Array[0] are the elements in `array` that satisfies the predicate, and Array[1] the elements that did not.
**/
partition(
array: Array,
iterator: _.ListIterator,
context?: any): T[][];
/*********
* Arrays *
**********/
/**
* Returns the first element of an array. Passing n will return the first n elements of the array.
* @param array Retrieves the first element of this array.
* @return Returns the first element of `array`.
**/
first(array: _.List): T;
/**
* @see _.first
* @param n Return more than one element from `array`.
**/
first(
array: _.List,
n: number): T[];
/**
* @see _.first
**/
head(array: _.List): T;
/**
* @see _.first
**/
head(
array: _.List,
n: number): T[];
/**
* @see _.first
**/
take(array: _.List): T;
/**
* @see _.first
**/
take(
array: _.List,
n: number): T[];
/**
* Returns everything but the last entry of the array. Especially useful on the arguments object.
* Pass n to exclude the last n elements from the result.
* @param array Retrieve all elements except the last `n`.
* @param n Leaves this many elements behind, optional.
* @return Returns everything but the last `n` elements of `array`.
**/
initial(
array: _.List,
n?: number): T[];
/**
* Returns the last element of an array. Passing n will return the last n elements of the array.
* @param array Retrieves the last element of this array.
* @return Returns the last element of `array`.
**/
last(array: _.List): T;
/**
* @see _.last
* @param n Return more than one element from `array`.
**/
last(
array: _.List,
n: number): T[];
/**
* Returns the rest of the elements in an array. Pass an index to return the values of the array
* from that index onward.
* @param array The array to retrieve all but the first `index` elements.
* @param n The index to start retrieving elements forward from, optional, default = 1.
* @return Returns the elements of `array` from `index` to the end of `array`.
**/
rest(
array: _.List,
n?: number): T[];
/**
* @see _.rest
**/
tail(
array: _.List,
n?: number): T[];
/**
* @see _.rest
**/
drop(
array: _.List,
n?: number): T[];
/**
* Returns a copy of the array with all falsy values removed. In JavaScript, false, null, 0, "",
* undefined and NaN are all falsy.
* @param array Array to compact.
* @return Copy of `array` without false values.
**/
compact(array: _.List): T[];
/**
* Flattens a nested array (the nesting can be to any depth). If you pass shallow, the array will
* only be flattened a single level.
* @param array The array to flatten.
* @param shallow If true then only flatten one level, optional, default = false.
* @return `array` flattened.
**/
flatten(
array: _.List,
shallow?: boolean): any[];
/**
* Returns a copy of the array with all instances of the values removed.
* @param array The array to remove `values` from.
* @param values The values to remove from `array`.
* @return Copy of `array` without `values`.
**/
without(
array: _.List,
...values: T[]): T[];
/**
* Computes the union of the passed-in arrays: the list of unique items, in order, that are
* present in one or more of the arrays.
* @param arrays Array of arrays to compute the union of.
* @return The union of elements within `arrays`.
**/
union(...arrays: _.List[]): T[];
/**
* Computes the list of values that are the intersection of all the arrays. Each value in the result
* is present in each of the arrays.
* @param arrays Array of arrays to compute the intersection of.
* @return The intersection of elements within `arrays`.
**/
intersection(...arrays: _.List[]): T[];
/**
* Similar to without, but returns the values from array that are not present in the other arrays.
* @param array Keeps values that are within `others`.
* @param others The values to keep within `array`.
* @return Copy of `array` with only `others` values.
**/
difference(
array: _.List,
...others: _.List[]): T[];
/**
* Produces a duplicate-free version of the array, using === to test object equality. If you know in
* advance that the array is sorted, passing true for isSorted will run a much faster algorithm. If
* you want to compute unique items based on a transformation, pass an iterator function.
* @param array Array to remove duplicates from.
* @param isSorted True if `array` is already sorted, optional, default = false.
* @param iterator Transform the elements of `array` before comparisons for uniqueness.
* @param context 'this' object in `iterator`, optional.
* @return Copy of `array` where all elements are unique.
**/
uniq(
array: _.List,
isSorted?: boolean,
iterator?: _.ListIterator,
context?: any): T[];
/**
* @see _.uniq
**/
uniq(
array: _.List,
iterator?: _.ListIterator,
context?: any): T[];
/**
* @see _.uniq
**/
unique(
array: _.List,
iterator?: _.ListIterator,
context?: any): T[];
/**
* @see _.uniq
**/
unique(
array: _.List,
isSorted?: boolean,
iterator?: _.ListIterator,
context?: any): T[];
/**
* Merges together the values of each of the arrays with the values at the corresponding position.
* Useful when you have separate data sources that are coordinated through matching array indexes.
* If you're working with a matrix of nested arrays, zip.apply can transpose the matrix in a similar fashion.
* @param arrays The arrays to merge/zip.
* @return Zipped version of `arrays`.
**/
zip(...arrays: any[][]): any[][];
/**
* @see _.zip
**/
zip(...arrays: any[]): any[];
/**
* The opposite of zip. Given a number of arrays, returns a series of new arrays, the first
* of which contains all of the first elements in the input arrays, the second of which
* contains all of the second elements, and so on. Use with apply to pass in an array
* of arrays
* @param arrays The arrays to unzip.
* @return Unzipped version of `arrays`.
**/
unzip(...arrays: any[][]): any[][];
/**
* Converts arrays into objects. Pass either a single list of [key, value] pairs, or a
* list of keys, and a list of values.
* @param keys Key array.
* @param values Value array.
* @return An object containing the `keys` as properties and `values` as the property values.
**/
object(
keys: _.List,
values: _.List): TResult;
/**
* Converts arrays into objects. Pass either a single list of [key, value] pairs, or a
* list of keys, and a list of values.
* @param keyValuePairs Array of [key, value] pairs.
* @return An object containing the `keys` as properties and `values` as the property values.
**/
object(...keyValuePairs: any[][]): TResult;
/**
* @see _.object
**/
object(
list: _.List,
values?: any): TResult;
/**
* Returns the index at which value can be found in the array, or -1 if value is not present in the array.
* Uses the native indexOf function unless it's missing. If you're working with a large array, and you know
* that the array is already sorted, pass true for isSorted to use a faster binary search ... or, pass a number
* as the third argument in order to look for the first matching value in the array after the given index.
* @param array The array to search for the index of `value`.
* @param value The value to search for within `array`.
* @param isSorted True if the array is already sorted, optional, default = false.
* @return The index of `value` within `array`.
**/
indexOf