Permalink
5342 lines (4863 sloc) 170 KB
/**
* Copyright (c) 2014-present, Facebook, Inc.
*
* This source code is licensed under the MIT license found in the
* LICENSE file in the root directory of this source tree.
*/
/**
* Immutable data encourages pure functions (data-in, data-out) and lends itself
* to much simpler application development and enabling techniques from
* functional programming such as lazy evaluation.
*
* While designed to bring these powerful functional concepts to JavaScript, it
* presents an Object-Oriented API familiar to Javascript engineers and closely
* mirroring that of Array, Map, and Set. It is easy and efficient to convert to
* and from plain Javascript types.
*
* ## How to read these docs
*
* In order to better explain what kinds of values the Immutable.js API expects
* and produces, this documentation is presented in a statically typed dialect of
* JavaScript (like [Flow][] or [TypeScript][]). You *don't need* to use these
* type checking tools in order to use Immutable.js, however becoming familiar
* with their syntax will help you get a deeper understanding of this API.
*
* **A few examples and how to read them.**
*
* All methods describe the kinds of data they accept and the kinds of data
* they return. For example a function which accepts two numbers and returns
* a number would look like this:
*
* ```js
* sum(first: number, second: number): number
* ```
*
* Sometimes, methods can accept different kinds of data or return different
* kinds of data, and this is described with a *type variable*, which is
* typically in all-caps. For example, a function which always returns the same
* kind of data it was provided would look like this:
*
* ```js
* identity<T>(value: T): T
* ```
*
* Type variables are defined with classes and referred to in methods. For
* example, a class that holds onto a value for you might look like this:
*
* ```js
* class Box<T> {
* constructor(value: T)
* getValue(): T
* }
* ```
*
* In order to manipulate Immutable data, methods that we're used to affecting
* a Collection instead return a new Collection of the same type. The type
* `this` refers to the same kind of class. For example, a List which returns
* new Lists when you `push` a value onto it might look like:
*
* ```js
* class List<T> {
* push(value: T): this
* }
* ```
*
* Many methods in Immutable.js accept values which implement the JavaScript
* [Iterable][] protocol, and might appear like `Iterable<string>` for something
* which represents sequence of strings. Typically in JavaScript we use plain
* Arrays (`[]`) when an Iterable is expected, but also all of the Immutable.js
* collections are iterable themselves!
*
* For example, to get a value deep within a structure of data, we might use
* `getIn` which expects an `Iterable` path:
*
* ```
* getIn(path: Iterable<string | number>): any
* ```
*
* To use this method, we could pass an array: `data.getIn([ "key", 2 ])`.
*
*
* Note: All examples are presented in the modern [ES2015][] version of
* JavaScript. Use tools like Babel to support older browsers.
*
* For example:
*
* ```js
* // ES2015
* const mappedFoo = foo.map(x => x * x);
* // ES5
* var mappedFoo = foo.map(function (x) { return x * x; });
* ```
*
* [ES2015]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/New_in_JavaScript/ECMAScript_6_support_in_Mozilla
* [TypeScript]: http://www.typescriptlang.org/
* [Flow]: https://flowtype.org/
* [Iterable]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols
*/
declare module Immutable {
/**
* Lists are ordered indexed dense collections, much like a JavaScript
* Array.
*
* Lists are immutable and fully persistent with O(log32 N) gets and sets,
* and O(1) push and pop.
*
* Lists implement Deque, with efficient addition and removal from both the
* end (`push`, `pop`) and beginning (`unshift`, `shift`).
*
* Unlike a JavaScript Array, there is no distinction between an
* "unset" index and an index set to `undefined`. `List#forEach` visits all
* indices from 0 to size, regardless of whether they were explicitly defined.
*/
export module List {
/**
* True if the provided value is a List
*
* <!-- runkit:activate -->
* ```js
* const { List } = require('immutable');
* List.isList([]); // false
* List.isList(List()); // true
* ```
*/
function isList(maybeList: any): maybeList is List<any>;
/**
* Creates a new List containing `values`.
*
* <!-- runkit:activate -->
* ```js
* const { List } = require('immutable');
* List.of(1, 2, 3, 4)
* // List [ 1, 2, 3, 4 ]
* ```
*
* Note: Values are not altered or converted in any way.
*
* <!-- runkit:activate -->
* ```js
* const { List } = require('immutable');
* List.of({x:1}, 2, [3], 4)
* // List [ { x: 1 }, 2, [ 3 ], 4 ]
* ```
*/
function of<T>(...values: Array<T>): List<T>;
}
/**
* Create a new immutable List containing the values of the provided
* collection-like.
*
* Note: `List` is a factory function and not a class, and does not use the
* `new` keyword during construction.
*
* <!-- runkit:activate -->
* ```js
* const { List, Set } = require('immutable')
*
* const emptyList = List()
* // List []
*
* const plainArray = [ 1, 2, 3, 4 ]
* const listFromPlainArray = List(plainArray)
* // List [ 1, 2, 3, 4 ]
*
* const plainSet = Set([ 1, 2, 3, 4 ])
* const listFromPlainSet = List(plainSet)
* // List [ 1, 2, 3, 4 ]
*
* const arrayIterator = plainArray[Symbol.iterator]()
* const listFromCollectionArray = List(arrayIterator)
* // List [ 1, 2, 3, 4 ]
*
* listFromPlainArray.equals(listFromCollectionArray) // true
* listFromPlainSet.equals(listFromCollectionArray) // true
* listFromPlainSet.equals(listFromPlainArray) // true
* ```
*/
export function List(): List<any>;
export function List<T>(): List<T>;
export function List<T>(collection: Iterable<T>): List<T>;
export interface List<T> extends Collection.Indexed<T> {
/**
* The number of items in this List.
*/
readonly size: number;
// Persistent changes
/**
* Returns a new List which includes `value` at `index`. If `index` already
* exists in this List, it will be replaced.
*
* `index` may be a negative number, which indexes back from the end of the
* List. `v.set(-1, "value")` sets the last item in the List.
*
* If `index` larger than `size`, the returned List's `size` will be large
* enough to include the `index`.
*
* <!-- runkit:activate
* { "preamble": "const { List } = require('immutable');" }
* -->
* ```js
* const originalList = List([ 0 ]);
* // List [ 0 ]
* originalList.set(1, 1);
* // List [ 0, 1 ]
* originalList.set(0, 'overwritten');
* // List [ "overwritten" ]
* originalList.set(2, 2);
* // List [ 0, undefined, 2 ]
*
* List().set(50000, 'value').size;
* // 50001
* ```
*
* Note: `set` can be used in `withMutations`.
*/
set(index: number, value: T): List<T>;
/**
* Returns a new List which excludes this `index` and with a size 1 less
* than this List. Values at indices above `index` are shifted down by 1 to
* fill the position.
*
* This is synonymous with `list.splice(index, 1)`.
*
* `index` may be a negative number, which indexes back from the end of the
* List. `v.delete(-1)` deletes the last item in the List.
*
* Note: `delete` cannot be safely used in IE8
*
* <!-- runkit:activate
* { "preamble": "const { List } = require('immutable');" }
* -->
* ```js
* List([ 0, 1, 2, 3, 4 ]).delete(0);
* // List [ 1, 2, 3, 4 ]
* ```
*
* Since `delete()` re-indexes values, it produces a complete copy, which
* has `O(N)` complexity.
*
* Note: `delete` *cannot* be used in `withMutations`.
*
* @alias remove
*/
delete(index: number): List<T>;
remove(index: number): List<T>;
/**
* Returns a new List with `value` at `index` with a size 1 more than this
* List. Values at indices above `index` are shifted over by 1.
*
* This is synonymous with `list.splice(index, 0, value)`.
*
* <!-- runkit:activate
* { "preamble": "const { List } = require('immutable');" }
* -->
* ```js
* List([ 0, 1, 2, 3, 4 ]).insert(6, 5)
* // List [ 0, 1, 2, 3, 4, 5 ]
* ```
*
* Since `insert()` re-indexes values, it produces a complete copy, which
* has `O(N)` complexity.
*
* Note: `insert` *cannot* be used in `withMutations`.
*/
insert(index: number, value: T): List<T>;
/**
* Returns a new List with 0 size and no values in constant time.
*
* <!-- runkit:activate
* { "preamble": "const { List } = require('immutable');" }
* -->
* ```js
* List([ 1, 2, 3, 4 ]).clear()
* // List []
* ```
*
* Note: `clear` can be used in `withMutations`.
*/
clear(): List<T>;
/**
* Returns a new List with the provided `values` appended, starting at this
* List's `size`.
*
* <!-- runkit:activate
* { "preamble": "const { List } = require('immutable');" }
* -->
* ```js
* List([ 1, 2, 3, 4 ]).push(5)
* // List [ 1, 2, 3, 4, 5 ]
* ```
*
* Note: `push` can be used in `withMutations`.
*/
push(...values: Array<T>): List<T>;
/**
* Returns a new List with a size ones less than this List, excluding
* the last index in this List.
*
* Note: this differs from `Array#pop` because it returns a new
* List rather than the removed value. Use `last()` to get the last value
* in this List.
*
* ```js
* List([ 1, 2, 3, 4 ]).pop()
* // List[ 1, 2, 3 ]
* ```
*
* Note: `pop` can be used in `withMutations`.
*/
pop(): List<T>;
/**
* Returns a new List with the provided `values` prepended, shifting other
* values ahead to higher indices.
*
* <!-- runkit:activate
* { "preamble": "const { List } = require('immutable');" }
* -->
* ```js
* List([ 2, 3, 4]).unshift(1);
* // List [ 1, 2, 3, 4 ]
* ```
*
* Note: `unshift` can be used in `withMutations`.
*/
unshift(...values: Array<T>): List<T>;
/**
* Returns a new List with a size ones less than this List, excluding
* the first index in this List, shifting all other values to a lower index.
*
* Note: this differs from `Array#shift` because it returns a new
* List rather than the removed value. Use `first()` to get the first
* value in this List.
*
* <!-- runkit:activate
* { "preamble": "const { List } = require('immutable');" }
* -->
* ```js
* List([ 0, 1, 2, 3, 4 ]).shift();
* // List [ 1, 2, 3, 4 ]
* ```
*
* Note: `shift` can be used in `withMutations`.
*/
shift(): List<T>;
/**
* Returns a new List with an updated value at `index` with the return
* value of calling `updater` with the existing value, or `notSetValue` if
* `index` was not set. If called with a single argument, `updater` is
* called with the List itself.
*
* `index` may be a negative number, which indexes back from the end of the
* List. `v.update(-1)` updates the last item in the List.
*
* <!-- runkit:activate
* { "preamble": "const { List } = require('immutable');" }
* -->
* ```js
* const list = List([ 'a', 'b', 'c' ])
* const result = list.update(2, val => val.toUpperCase())
* // List [ "a", "b", "C" ]
* ```
*
* This can be very useful as a way to "chain" a normal function into a
* sequence of methods. RxJS calls this "let" and lodash calls it "thru".
*
* For example, to sum a List after mapping and filtering:
*
* <!-- runkit:activate
* { "preamble": "const { List } = require('immutable');" }
* -->
* ```js
* function sum(collection) {
* return collection.reduce((sum, x) => sum + x, 0)
* }
*
* List([ 1, 2, 3 ])
* .map(x => x + 1)
* .filter(x => x % 2 === 0)
* .update(sum)
* // 6
* ```
*
* Note: `update(index)` can be used in `withMutations`.
*
* @see `Map#update`
*/
update(index: number, notSetValue: T, updater: (value: T) => T): this;
update(index: number, updater: (value: T) => T): this;
update<R>(updater: (value: this) => R): R;
/**
* Returns a new List with size `size`. If `size` is less than this
* List's size, the new List will exclude values at the higher indices.
* If `size` is greater than this List's size, the new List will have
* undefined values for the newly available indices.
*
* When building a new List and the final size is known up front, `setSize`
* used in conjunction with `withMutations` may result in the more
* performant construction.
*/
setSize(size: number): List<T>;
// Deep persistent changes
/**
* Returns a new List having set `value` at this `keyPath`. If any keys in
* `keyPath` do not exist, a new immutable Map will be created at that key.
*
* Index numbers are used as keys to determine the path to follow in
* the List.
*
* <!-- runkit:activate -->
* ```js
* const { List } = require('immutable')
* const list = List([ 0, 1, 2, List([ 3, 4 ])])
* list.setIn([3, 0], 999);
* // List [ 0, 1, 2, List [ 999, 4 ] ]
* ```
*
* Plain JavaScript Object or Arrays may be nested within an Immutable.js
* Collection, and setIn() can update those values as well, treating them
* immutably by creating new copies of those values with the changes applied.
*
* <!-- runkit:activate -->
* ```js
* const { List } = require('immutable')
* const list = List([ 0, 1, 2, { plain: 'object' }])
* list.setIn([3, 'plain'], 'value');
* // List([ 0, 1, 2, { plain: 'value' }])
* ```
*
* Note: `setIn` can be used in `withMutations`.
*/
setIn(keyPath: Iterable<any>, value: any): this;
/**
* Returns a new List having removed the value at this `keyPath`. If any
* keys in `keyPath` do not exist, no change will occur.
*
* <!-- runkit:activate -->
* ```js
* const { List } = require('immutable')
* const list = List([ 0, 1, 2, List([ 3, 4 ])])
* list.deleteIn([3, 0]);
* // List [ 0, 1, 2, List [ 4 ] ]
* ```
*
* Plain JavaScript Object or Arrays may be nested within an Immutable.js
* Collection, and removeIn() can update those values as well, treating them
* immutably by creating new copies of those values with the changes applied.
*
* <!-- runkit:activate -->
* ```js
* const { List } = require('immutable')
* const list = List([ 0, 1, 2, { plain: 'object' }])
* list.removeIn([3, 'plain']);
* // List([ 0, 1, 2, {}])
* ```
*
* Note: `deleteIn` *cannot* be safely used in `withMutations`.
*
* @alias removeIn
*/
deleteIn(keyPath: Iterable<any>): this;
removeIn(keyPath: Iterable<any>): this;
/**
* Note: `updateIn` can be used in `withMutations`.
*
* @see `Map#updateIn`
*/
updateIn(keyPath: Iterable<any>, notSetValue: any, updater: (value: any) => any): this;
updateIn(keyPath: Iterable<any>, updater: (value: any) => any): this;
/**
* Note: `mergeIn` can be used in `withMutations`.
*
* @see `Map#mergeIn`
*/
mergeIn(keyPath: Iterable<any>, ...collections: Array<any>): this;
/**
* Note: `mergeDeepIn` can be used in `withMutations`.
*
* @see `Map#mergeDeepIn`
*/
mergeDeepIn(keyPath: Iterable<any>, ...collections: Array<any>): this;
// Transient changes
/**
* Note: Not all methods can be safely used on a mutable collection or within
* `withMutations`! Check the documentation for each method to see if it
* allows being used in `withMutations`.
*
* @see `Map#withMutations`
*/
withMutations(mutator: (mutable: this) => any): this;
/**
* An alternative API for withMutations()
*
* Note: Not all methods can be safely used on a mutable collection or within
* `withMutations`! Check the documentation for each method to see if it
* allows being used in `withMutations`.
*
* @see `Map#asMutable`
*/
asMutable(): this;
/**
* @see `Map#wasAltered`
*/
wasAltered(): boolean;
/**
* @see `Map#asImmutable`
*/
asImmutable(): this;
// Sequence algorithms
/**
* Returns a new List with other values or collections concatenated to this one.
*
* Note: `concat` can be used in `withMutations`.
*
* @alias merge
*/
concat<C>(...valuesOrCollections: Array<Iterable<C> | C>): List<T | C>;
merge<C>(...collections: Array<Iterable<C>>): List<T | C>;
/**
* Returns a new List with values passed through a
* `mapper` function.
*
* <!-- runkit:activate
* { "preamble": "const { List } = require('immutable');" }
* -->
* ```js
* List([ 1, 2 ]).map(x => 10 * x)
* // List [ 10, 20 ]
* ```
*/
map<M>(
mapper: (value: T, key: number, iter: this) => M,
context?: any
): List<M>;
/**
* Flat-maps the List, returning a new List.
*
* Similar to `list.map(...).flatten(true)`.
*/
flatMap<M>(
mapper: (value: T, key: number, iter: this) => Iterable<M>,
context?: any
): List<M>;
/**
* Returns a new List with only the values for which the `predicate`
* function returns true.
*
* Note: `filter()` always returns a new instance, even if it results in
* not filtering out any values.
*/
filter<F extends T>(
predicate: (value: T, index: number, iter: this) => value is F,
context?: any
): List<F>;
filter(
predicate: (value: T, index: number, iter: this) => any,
context?: any
): this;
/**
* Returns a List "zipped" with the provided collection.
*
* Like `zipWith`, but using the default `zipper`: creating an `Array`.
*
* <!-- runkit:activate
* { "preamble": "const { List } = require('immutable');" }
* -->
* ```js
* const a = List([ 1, 2, 3 ]);
* const b = List([ 4, 5, 6 ]);
* const c = a.zip(b); // List [ [ 1, 4 ], [ 2, 5 ], [ 3, 6 ] ]
* ```
*/
zip<U>(other: Collection<any, U>): List<[T,U]>;
zip<U,V>(other: Collection<any, U>, other2: Collection<any,V>): List<[T,U,V]>;
zip(...collections: Array<Collection<any, any>>): List<any>;
/**
* Returns a List "zipped" with the provided collections.
*
* Unlike `zip`, `zipAll` continues zipping until the longest collection is
* exhausted. Missing values from shorter collections are filled with `undefined`.
*
* <!-- runkit:activate
* { "preamble": "const { List } = require('immutable');" }
* -->
* ```js
* const a = List([ 1, 2 ]);
* const b = List([ 3, 4, 5 ]);
* const c = a.zipAll(b); // List [ [ 1, 3 ], [ 2, 4 ], [ undefined, 5 ] ]
* ```
*
* Note: Since zipAll will return a collection as large as the largest
* input, some results may contain undefined values. TypeScript cannot
* account for these without cases (as of v2.5).
*/
zipAll<U>(other: Collection<any, U>): List<[T,U]>;
zipAll<U,V>(other: Collection<any, U>, other2: Collection<any,V>): List<[T,U,V]>;
zipAll(...collections: Array<Collection<any, any>>): List<any>;
/**
* Returns a List "zipped" with the provided collections by using a
* custom `zipper` function.
*
* <!-- runkit:activate
* { "preamble": "const { List } = require('immutable');" }
* -->
* ```js
* const a = List([ 1, 2, 3 ]);
* const b = List([ 4, 5, 6 ]);
* const c = a.zipWith((a, b) => a + b, b);
* // List [ 5, 7, 9 ]
* ```
*/
zipWith<U, Z>(
zipper: (value: T, otherValue: U) => Z,
otherCollection: Collection<any, U>
): List<Z>;
zipWith<U, V, Z>(
zipper: (value: T, otherValue: U, thirdValue: V) => Z,
otherCollection: Collection<any, U>,
thirdCollection: Collection<any, V>
): List<Z>;
zipWith<Z>(
zipper: (...any: Array<any>) => Z,
...collections: Array<Collection<any, any>>
): List<Z>;
}
/**
* Immutable Map is an unordered Collection.Keyed of (key, value) pairs with
* `O(log32 N)` gets and `O(log32 N)` persistent sets.
*
* Iteration order of a Map is undefined, however is stable. Multiple
* iterations of the same Map will iterate in the same order.
*
* Map's keys can be of any type, and use `Immutable.is` to determine key
* equality. This allows the use of any value (including NaN) as a key.
*
* Because `Immutable.is` returns equality based on value semantics, and
* Immutable collections are treated as values, any Immutable collection may
* be used as a key.
*
* <!-- runkit:activate -->
* ```js
* const { Map, List } = require('immutable');
* Map().set(List([ 1 ]), 'listofone').get(List([ 1 ]));
* // 'listofone'
* ```
*
* Any JavaScript object may be used as a key, however strict identity is used
* to evaluate key equality. Two similar looking objects will represent two
* different keys.
*
* Implemented by a hash-array mapped trie.
*/
export module Map {
/**
* True if the provided value is a Map
*
* <!-- runkit:activate -->
* ```js
* const { Map } = require('immutable')
* Map.isMap({}) // false
* Map.isMap(Map()) // true
* ```
*/
function isMap(maybeMap: any): maybeMap is Map<any, any>;
/**
* Creates a new Map from alternating keys and values
*
* <!-- runkit:activate -->
* ```js
* const { Map } = require('immutable')
* Map.of(
* 'key', 'value',
* 'numerical value', 3,
* 0, 'numerical key'
* )
* // Map { 0: "numerical key", "key": "value", "numerical value": 3 }
* ```
*
* @deprecated Use Map([ [ 'k', 'v' ] ]) or Map({ k: 'v' })
*/
function of(...keyValues: Array<any>): Map<any, any>;
}
/**
* Creates a new Immutable Map.
*
* Created with the same key value pairs as the provided Collection.Keyed or
* JavaScript Object or expects a Collection of [K, V] tuple entries.
*
* Note: `Map` is a factory function and not a class, and does not use the
* `new` keyword during construction.
*
* <!-- runkit:activate -->
* ```js
* const { Map } = require('immutable')
* Map({ key: "value" })
* Map([ [ "key", "value" ] ])
* ```
*
* Keep in mind, when using JS objects to construct Immutable Maps, that
* JavaScript Object properties are always strings, even if written in a
* quote-less shorthand, while Immutable Maps accept keys of any type.
*
* <!-- runkit:activate
* { "preamble": "const { Map } = require('immutable');" }
* -->
* ```js
* let obj = { 1: "one" }
* Object.keys(obj) // [ "1" ]
* assert.equal(obj["1"], obj[1]) // "one" === "one"
*
* let map = Map(obj)
* assert.notEqual(map.get("1"), map.get(1)) // "one" !== undefined
* ```
*
* Property access for JavaScript Objects first converts the key to a string,
* but since Immutable Map keys can be of any type the argument to `get()` is
* not altered.
*/
export function Map<K, V>(collection: Iterable<[K, V]>): Map<K, V>;
export function Map<V>(obj: {[key: string]: V}): Map<string, V>;
export function Map<K, V>(): Map<K, V>;
export function Map(): Map<any, any>;
export interface Map<K, V> extends Collection.Keyed<K, V> {
/**
* The number of entries in this Map.
*/
readonly size: number;
// Persistent changes
/**
* Returns a new Map also containing the new key, value pair. If an equivalent
* key already exists in this Map, it will be replaced.
*
* <!-- runkit:activate -->
* ```js
* const { Map } = require('immutable')
* const originalMap = Map()
* const newerMap = originalMap.set('key', 'value')
* const newestMap = newerMap.set('key', 'newer value')
*
* originalMap
* // Map {}
* newerMap
* // Map { "key": "value" }
* newestMap
* // Map { "key": "newer value" }
* ```
*
* Note: `set` can be used in `withMutations`.
*/
set(key: K, value: V): this;
/**
* Returns a new Map which excludes this `key`.
*
* Note: `delete` cannot be safely used in IE8, but is provided to mirror
* the ES6 collection API.
*
* <!-- runkit:activate -->
* ```js
* const { Map } = require('immutable')
* const originalMap = Map({
* key: 'value',
* otherKey: 'other value'
* })
* // Map { "key": "value", "otherKey": "other value" }
* originalMap.delete('otherKey')
* // Map { "key": "value" }
* ```
*
* Note: `delete` can be used in `withMutations`.
*
* @alias remove
*/
delete(key: K): this;
remove(key: K): this;
/**
* Returns a new Map which excludes the provided `keys`.
*
* <!-- runkit:activate -->
* ```js
* const { Map } = require('immutable')
* const names = Map({ a: "Aaron", b: "Barry", c: "Connor" })
* names.deleteAll([ 'a', 'c' ])
* // Map { "b": "Barry" }
* ```
*
* Note: `deleteAll` can be used in `withMutations`.
*
* @alias removeAll
*/
deleteAll(keys: Iterable<K>): this;
removeAll(keys: Iterable<K>): this;
/**
* Returns a new Map containing no keys or values.
*
* <!-- runkit:activate -->
* ```js
* const { Map } = require('immutable')
* Map({ key: 'value' }).clear()
* // Map {}
* ```
*
* Note: `clear` can be used in `withMutations`.
*/
clear(): this;
/**
* Returns a new Map having updated the value at this `key` with the return
* value of calling `updater` with the existing value.
*
* Similar to: `map.set(key, updater(map.get(key)))`.
*
* <!-- runkit:activate -->
* ```js
* const { Map } = require('immutable')
* const aMap = Map({ key: 'value' })
* const newMap = aMap.update('key', value => value + value)
* // Map { "key": "valuevalue" }
* ```
*
* This is most commonly used to call methods on collections within a
* structure of data. For example, in order to `.push()` onto a nested `List`,
* `update` and `push` can be used together:
*
* <!-- runkit:activate
* { "preamble": "const { Map, List } = require('immutable');" }
* -->
* ```js
* const aMap = Map({ nestedList: List([ 1, 2, 3 ]) })
* const newMap = aMap.update('nestedList', list => list.push(4))
* // Map { "nestedList": List [ 1, 2, 3, 4 ] }
* ```
*
* When a `notSetValue` is provided, it is provided to the `updater`
* function when the value at the key does not exist in the Map.
*
* <!-- runkit:activate
* { "preamble": "const { Map } = require('immutable');" }
* -->
* ```js
* const aMap = Map({ key: 'value' })
* const newMap = aMap.update('noKey', 'no value', value => value + value)
* // Map { "key": "value", "noKey": "no valueno value" }
* ```
*
* However, if the `updater` function returns the same value it was called
* with, then no change will occur. This is still true if `notSetValue`
* is provided.
*
* <!-- runkit:activate
* { "preamble": "const { Map } = require('immutable');" }
* -->
* ```js
* const aMap = Map({ apples: 10 })
* const newMap = aMap.update('oranges', 0, val => val)
* // Map { "apples": 10 }
* assert.strictEqual(newMap, map);
* ```
*
* For code using ES2015 or later, using `notSetValue` is discourged in
* favor of function parameter default values. This helps to avoid any
* potential confusion with identify functions as described above.
*
* The previous example behaves differently when written with default values:
*
* <!-- runkit:activate
* { "preamble": "const { Map } = require('immutable');" }
* -->
* ```js
* const aMap = Map({ apples: 10 })
* const newMap = aMap.update('oranges', (val = 0) => val)
* // Map { "apples": 10, "oranges": 0 }
* ```
*
* If no key is provided, then the `updater` function return value is
* returned as well.
*
* <!-- runkit:activate
* { "preamble": "const { Map } = require('immutable');" }
* -->
* ```js
* const aMap = Map({ key: 'value' })
* const result = aMap.update(aMap => aMap.get('key'))
* // "value"
* ```
*
* This can be very useful as a way to "chain" a normal function into a
* sequence of methods. RxJS calls this "let" and lodash calls it "thru".
*
* For example, to sum the values in a Map
*
* <!-- runkit:activate
* { "preamble": "const { Map } = require('immutable');" }
* -->
* ```js
* function sum(collection) {
* return collection.reduce((sum, x) => sum + x, 0)
* }
*
* Map({ x: 1, y: 2, z: 3 })
* .map(x => x + 1)
* .filter(x => x % 2 === 0)
* .update(sum)
* // 6
* ```
*
* Note: `update(key)` can be used in `withMutations`.
*/
update(key: K, notSetValue: V, updater: (value: V) => V): this;
update(key: K, updater: (value: V) => V): this;
update<R>(updater: (value: this) => R): R;
/**
* Returns a new Map resulting from merging the provided Collections
* (or JS objects) into this Map. In other words, this takes each entry of
* each collection and sets it on this Map.
*
* Note: Values provided to `merge` are shallowly converted before being
* merged. No nested values are altered.
*
* <!-- runkit:activate -->
* ```js
* const { Map } = require('immutable')
* const one = Map({ a: 10, b: 20, c: 30 })
* const two = Map({ b: 40, a: 50, d: 60 })
* one.merge(two) // Map { "a": 50, "b": 40, "c": 30, "d": 60 }
* two.merge(one) // Map { "b": 20, "a": 10, "d": 60, "c": 30 }
* ```
*
* Note: `merge` can be used in `withMutations`.
*
* @alias concat
*/
merge<KC, VC>(...collections: Array<Iterable<[KC, VC]>>): Map<K | KC, V | VC>;
merge<C>(...collections: Array<{[key: string]: C}>): Map<K | string, V | C>;
concat<KC, VC>(...collections: Array<Iterable<[KC, VC]>>): Map<K | KC, V | VC>;
concat<C>(...collections: Array<{[key: string]: C}>): Map<K | string, V | C>;
/**
* Like `merge()`, `mergeWith()` returns a new Map resulting from merging
* the provided Collections (or JS objects) into this Map, but uses the
* `merger` function for dealing with conflicts.
*
* <!-- runkit:activate -->
* ```js
* const { Map } = require('immutable')
* const one = Map({ a: 10, b: 20, c: 30 })
* const two = Map({ b: 40, a: 50, d: 60 })
* one.mergeWith((oldVal, newVal) => oldVal / newVal, two)
* // { "a": 0.2, "b": 0.5, "c": 30, "d": 60 }
* two.mergeWith((oldVal, newVal) => oldVal / newVal, one)
* // { "b": 2, "a": 5, "d": 60, "c": 30 }
* ```
*
* Note: `mergeWith` can be used in `withMutations`.
*/
mergeWith(
merger: (oldVal: V, newVal: V, key: K) => V,
...collections: Array<Iterable<[K, V]> | {[key: string]: V}>
): this;
/**
* Like `merge()`, but when two Collections conflict, it merges them as well,
* recursing deeply through the nested data.
*
* Note: Values provided to `merge` are shallowly converted before being
* merged. No nested values are altered unless they will also be merged at
* a deeper level.
*
* <!-- runkit:activate -->
* ```js
* const { Map } = require('immutable')
* const one = Map({ a: Map({ x: 10, y: 10 }), b: Map({ x: 20, y: 50 }) })
* const two = Map({ a: Map({ x: 2 }), b: Map({ y: 5 }), c: Map({ z: 3 }) })
* one.mergeDeep(two)
* // Map {
* // "a": Map { "x": 2, "y": 10 },
* // "b": Map { "x": 20, "y": 5 },
* // "c": Map { "z": 3 }
* // }
* ```
*
* Note: `mergeDeep` can be used in `withMutations`.
*/
mergeDeep(...collections: Array<Iterable<[K, V]> | {[key: string]: V}>): this;
/**
* Like `mergeDeep()`, but when two non-Collections conflict, it uses the
* `merger` function to determine the resulting value.
*
* <!-- runkit:activate -->
* ```js
* const { Map } = require('immutable')
* const one = Map({ a: Map({ x: 10, y: 10 }), b: Map({ x: 20, y: 50 }) })
* const two = Map({ a: Map({ x: 2 }), b: Map({ y: 5 }), c: Map({ z: 3 }) })
* one.mergeDeepWith((oldVal, newVal) => oldVal / newVal, two)
* // Map {
* // "a": Map { "x": 5, "y": 10 },
* // "b": Map { "x": 20, "y": 10 },
* // "c": Map { "z": 3 }
* // }
* ```
* Note: `mergeDeepWith` can be used in `withMutations`.
*/
mergeDeepWith(
merger: (oldVal: any, newVal: any, key: any) => any,
...collections: Array<Iterable<[K, V]> | {[key: string]: V}>
): this;
// Deep persistent changes
/**
* Returns a new Map having set `value` at this `keyPath`. If any keys in
* `keyPath` do not exist, a new immutable Map will be created at that key.
*
* <!-- runkit:activate -->
* ```js
* const { Map } = require('immutable')
* const originalMap = Map({
* subObject: Map({
* subKey: 'subvalue',
* subSubObject: Map({
* subSubKey: 'subSubValue'
* })
* })
* })
*
* const newMap = originalMap.setIn(['subObject', 'subKey'], 'ha ha!')
* // Map {
* // "subObject": Map {
* // "subKey": "ha ha!",
* // "subSubObject": Map { "subSubKey": "subSubValue" }
* // }
* // }
*
* const newerMap = originalMap.setIn(
* ['subObject', 'subSubObject', 'subSubKey'],
* 'ha ha ha!'
* )
* // Map {
* // "subObject": Map {
* // "subKey": "subvalue",
* // "subSubObject": Map { "subSubKey": "ha ha ha!" }
* // }
* // }
* ```
*
* Plain JavaScript Object or Arrays may be nested within an Immutable.js
* Collection, and setIn() can update those values as well, treating them
* immutably by creating new copies of those values with the changes applied.
*
* <!-- runkit:activate -->
* ```js
* const { Map } = require('immutable')
* const originalMap = Map({
* subObject: {
* subKey: 'subvalue',
* subSubObject: {
* subSubKey: 'subSubValue'
* }
* }
* })
*
* originalMap.setIn(['subObject', 'subKey'], 'ha ha!')
* // Map {
* // "subObject": {
* // subKey: "ha ha!",
* // subSubObject: { subSubKey: "subSubValue" }
* // }
* // }
* ```
*
* If any key in the path exists but cannot be updated (such as a primitive
* like number or a custom Object like Date), an error will be thrown.
*
* Note: `setIn` can be used in `withMutations`.
*/
setIn(keyPath: Iterable<any>, value: any): this;
/**
* Returns a new Map having removed the value at this `keyPath`. If any keys
* in `keyPath` do not exist, no change will occur.
*
* Note: `deleteIn` can be used in `withMutations`.
*
* @alias removeIn
*/
deleteIn(keyPath: Iterable<any>): this;
removeIn(keyPath: Iterable<any>): this;
/**
* Returns a new Map having applied the `updater` to the entry found at the
* keyPath.
*
* This is most commonly used to call methods on collections nested within a
* structure of data. For example, in order to `.push()` onto a nested `List`,
* `updateIn` and `push` can be used together:
*
* <!-- runkit:activate -->
* ```js
* const { Map, List } = require('immutable')
* const map = Map({ inMap: Map({ inList: List([ 1, 2, 3 ]) }) })
* const newMap = map.updateIn(['inMap', 'inList'], list => list.push(4))
* // Map { "inMap": Map { "inList": List [ 1, 2, 3, 4 ] } }
* ```
*
* If any keys in `keyPath` do not exist, new Immutable `Map`s will
* be created at those keys. If the `keyPath` does not already contain a
* value, the `updater` function will be called with `notSetValue`, if
* provided, otherwise `undefined`.
*
* <!-- runkit:activate
* { "preamble": "const { Map } = require('immutable')" }
* -->
* ```js
* const map = Map({ a: Map({ b: Map({ c: 10 }) }) })
* const newMap = map.updateIn(['a', 'b', 'c'], val => val * 2)
* // Map { "a": Map { "b": Map { "c": 20 } } }
* ```
*
* If the `updater` function returns the same value it was called with, then
* no change will occur. This is still true if `notSetValue` is provided.
*
* <!-- runkit:activate
* { "preamble": "const { Map } = require('immutable')" }
* -->
* ```js
* const map = Map({ a: Map({ b: Map({ c: 10 }) }) })
* const newMap = map.updateIn(['a', 'b', 'x'], 100, val => val)
* // Map { "a": Map { "b": Map { "c": 10 } } }
* assert.strictEqual(newMap, aMap)
* ```
*
* For code using ES2015 or later, using `notSetValue` is discourged in
* favor of function parameter default values. This helps to avoid any
* potential confusion with identify functions as described above.
*
* The previous example behaves differently when written with default values:
*
* <!-- runkit:activate
* { "preamble": "const { Map } = require('immutable')" }
* -->
* ```js
* const map = Map({ a: Map({ b: Map({ c: 10 }) }) })
* const newMap = map.updateIn(['a', 'b', 'x'], (val = 100) => val)
* // Map { "a": Map { "b": Map { "c": 10, "x": 100 } } }
* ```
*
* Plain JavaScript Object or Arrays may be nested within an Immutable.js
* Collection, and updateIn() can update those values as well, treating them
* immutably by creating new copies of those values with the changes applied.
*
* <!-- runkit:activate
* { "preamble": "const { Map } = require('immutable')" }
* -->
* ```js
* const map = Map({ a: { b: { c: 10 } } })
* const newMap = map.updateIn(['a', 'b', 'c'], val => val * 2)
* // Map { "a": { b: { c: 20 } } }
* ```
*
* If any key in the path exists but cannot be updated (such as a primitive
* like number or a custom Object like Date), an error will be thrown.
*
* Note: `updateIn` can be used in `withMutations`.
*/
updateIn(keyPath: Iterable<any>, notSetValue: any, updater: (value: any) => any): this;
updateIn(keyPath: Iterable<any>, updater: (value: any) => any): this;
/**
* A combination of `updateIn` and `merge`, returning a new Map, but
* performing the merge at a point arrived at by following the keyPath.
* In other words, these two lines are equivalent:
*
* ```js
* map.updateIn(['a', 'b', 'c'], abc => abc.merge(y))
* map.mergeIn(['a', 'b', 'c'], y)
* ```
*
* Note: `mergeIn` can be used in `withMutations`.
*/
mergeIn(keyPath: Iterable<any>, ...collections: Array<any>): this;
/**
* A combination of `updateIn` and `mergeDeep`, returning a new Map, but
* performing the deep merge at a point arrived at by following the keyPath.
* In other words, these two lines are equivalent:
*
* ```js
* map.updateIn(['a', 'b', 'c'], abc => abc.mergeDeep(y))
* map.mergeDeepIn(['a', 'b', 'c'], y)
* ```
*
* Note: `mergeDeepIn` can be used in `withMutations`.
*/
mergeDeepIn(keyPath: Iterable<any>, ...collections: Array<any>): this;
// Transient changes
/**
* Every time you call one of the above functions, a new immutable Map is
* created. If a pure function calls a number of these to produce a final
* return value, then a penalty on performance and memory has been paid by
* creating all of the intermediate immutable Maps.
*
* If you need to apply a series of mutations to produce a new immutable
* Map, `withMutations()` creates a temporary mutable copy of the Map which
* can apply mutations in a highly performant manner. In fact, this is
* exactly how complex mutations like `merge` are done.
*
* As an example, this results in the creation of 2, not 4, new Maps:
*
* <!-- runkit:activate -->
* ```js
* const { Map } = require('immutable')
* const map1 = Map()
* const map2 = map1.withMutations(map => {
* map.set('a', 1).set('b', 2).set('c', 3)
* })
* assert.equal(map1.size, 0)
* assert.equal(map2.size, 3)
* ```
*
* Note: Not all methods can be used on a mutable collection or within
* `withMutations`! Read the documentation for each method to see if it
* is safe to use in `withMutations`.
*/
withMutations(mutator: (mutable: this) => any): this;
/**
* Another way to avoid creation of intermediate Immutable maps is to create
* a mutable copy of this collection. Mutable copies *always* return `this`,
* and thus shouldn't be used for equality. Your function should never return
* a mutable copy of a collection, only use it internally to create a new
* collection.
*
* If possible, use `withMutations` to work with temporary mutable copies as
* it provides an easier to use API and considers many common optimizations.
*
* Note: if the collection is already mutable, `asMutable` returns itself.
*
* Note: Not all methods can be used on a mutable collection or within
* `withMutations`! Read the documentation for each method to see if it
* is safe to use in `withMutations`.
*
* @see `Map#asImmutable`
*/
asMutable(): this;
/**
* Returns true if this is a mutable copy (see `asMutable()`) and mutative
* alterations have been applied.
*
* @see `Map#asMutable`
*/
wasAltered(): boolean;
/**
* The yin to `asMutable`'s yang. Because it applies to mutable collections,
* this operation is *mutable* and may return itself (though may not
* return itself, i.e. if the result is an empty collection). Once
* performed, the original mutable copy must no longer be mutated since it
* may be the immutable result.
*
* If possible, use `withMutations` to work with temporary mutable copies as
* it provides an easier to use API and considers many common optimizations.
*
* @see `Map#asMutable`
*/
asImmutable(): this;
// Sequence algorithms
/**
* Returns a new Map with values passed through a
* `mapper` function.
*
* Map({ a: 1, b: 2 }).map(x => 10 * x)
* // Map { a: 10, b: 20 }
*/
map<M>(
mapper: (value: V, key: K, iter: this) => M,
context?: any
): Map<K, M>;
/**
* @see Collection.Keyed.mapKeys
*/
mapKeys<M>(
mapper: (key: K, value: V, iter: this) => M,
context?: any
): Map<M, V>;
/**
* @see Collection.Keyed.mapEntries
*/
mapEntries<KM, VM>(
mapper: (entry: [K, V], index: number, iter: this) => [KM, VM],
context?: any
): Map<KM, VM>;
/**
* Flat-maps the Map, returning a new Map.
*
* Similar to `data.map(...).flatten(true)`.
*/
flatMap<KM, VM>(
mapper: (value: V, key: K, iter: this) => Iterable<[KM, VM]>,
context?: any
): Map<KM, VM>;
/**
* Returns a new Map with only the entries for which the `predicate`
* function returns true.
*
* Note: `filter()` always returns a new instance, even if it results in
* not filtering out any values.
*/
filter<F extends V>(
predicate: (value: V, key: K, iter: this) => value is F,
context?: any
): Map<K, F>;
filter(
predicate: (value: V, key: K, iter: this) => any,
context?: any
): this;
/**
* @see Collection.Keyed.flip
*/
flip(): Map<V, K>;
}
/**
* A type of Map that has the additional guarantee that the iteration order of
* entries will be the order in which they were set().
*
* The iteration behavior of OrderedMap is the same as native ES6 Map and
* JavaScript Object.
*
* Note that `OrderedMap` are more expensive than non-ordered `Map` and may
* consume more memory. `OrderedMap#set` is amortized O(log32 N), but not
* stable.
*/
export module OrderedMap {
/**
* True if the provided value is an OrderedMap.
*/
function isOrderedMap(maybeOrderedMap: any): maybeOrderedMap is OrderedMap<any, any>;
}
/**
* Creates a new Immutable OrderedMap.
*
* Created with the same key value pairs as the provided Collection.Keyed or
* JavaScript Object or expects a Collection of [K, V] tuple entries.
*
* The iteration order of key-value pairs provided to this constructor will
* be preserved in the OrderedMap.
*
* let newOrderedMap = OrderedMap({key: "value"})
* let newOrderedMap = OrderedMap([["key", "value"]])
*
* Note: `OrderedMap` is a factory function and not a class, and does not use
* the `new` keyword during construction.
*/
export function OrderedMap<K, V>(collection: Iterable<[K, V]>): OrderedMap<K, V>;
export function OrderedMap<V>(obj: {[key: string]: V}): OrderedMap<string, V>;
export function OrderedMap<K, V>(): OrderedMap<K, V>;
export function OrderedMap(): OrderedMap<any, any>;
export interface OrderedMap<K, V> extends Map<K, V> {
/**
* The number of entries in this OrderedMap.
*/
readonly size: number;
/**
* Returns a new OrderedMap also containing the new key, value pair. If an
* equivalent key already exists in this OrderedMap, it will be replaced
* while maintaining the existing order.
*
* <!-- runkit:activate -->
* ```js
* const { OrderedMap } = require('immutable')
* const originalMap = OrderedMap({a:1, b:1, c:1})
* const updatedMap = originalMap.set('b', 2)
*
* originalMap
* // OrderedMap {a: 1, b: 1, c: 1}
* updatedMap
* // OrderedMap {a: 1, b: 2, c: 1}
* ```
*
* Note: `set` can be used in `withMutations`.
*/
set(key: K, value: V): this;
/**
* Returns a new OrderedMap resulting from merging the provided Collections
* (or JS objects) into this OrderedMap. In other words, this takes each
* entry of each collection and sets it on this OrderedMap.
*
* Note: Values provided to `merge` are shallowly converted before being
* merged. No nested values are altered.
*
* <!-- runkit:activate -->
* ```js
* const { OrderedMap } = require('immutable')
* const one = OrderedMap({ a: 10, b: 20, c: 30 })
* const two = OrderedMap({ b: 40, a: 50, d: 60 })
* one.merge(two) // OrderedMap { "a": 50, "b": 40, "c": 30, "d": 60 }
* two.merge(one) // OrderedMap { "b": 20, "a": 10, "d": 60, "c": 30 }
* ```
*
* Note: `merge` can be used in `withMutations`.
*
* @alias concat
*/
merge<KC, VC>(...collections: Array<Iterable<[KC, VC]>>): OrderedMap<K | KC, V | VC>;
merge<C>(...collections: Array<{[key: string]: C}>): OrderedMap<K | string, V | C>;
concat<KC, VC>(...collections: Array<Iterable<[KC, VC]>>): OrderedMap<K | KC, V | VC>;
concat<C>(...collections: Array<{[key: string]: C}>): OrderedMap<K | string, V | C>;
// Sequence algorithms
/**
* Returns a new OrderedMap with values passed through a
* `mapper` function.
*
* OrderedMap({ a: 1, b: 2 }).map(x => 10 * x)
* // OrderedMap { "a": 10, "b": 20 }
*
* Note: `map()` always returns a new instance, even if it produced the same
* value at every step.
*/
map<M>(
mapper: (value: V, key: K, iter: this) => M,
context?: any
): OrderedMap<K, M>;
/**
* @see Collection.Keyed.mapKeys
*/
mapKeys<M>(
mapper: (key: K, value: V, iter: this) => M,
context?: any
): OrderedMap<M, V>;
/**
* @see Collection.Keyed.mapEntries
*/
mapEntries<KM, VM>(
mapper: (entry: [K, V], index: number, iter: this) => [KM, VM],
context?: any
): OrderedMap<KM, VM>;
/**
* Flat-maps the OrderedMap, returning a new OrderedMap.
*
* Similar to `data.map(...).flatten(true)`.
*/
flatMap<KM, VM>(
mapper: (value: V, key: K, iter: this) => Iterable<[KM, VM]>,
context?: any
): OrderedMap<KM, VM>;
/**
* Returns a new OrderedMap with only the entries for which the `predicate`
* function returns true.
*
* Note: `filter()` always returns a new instance, even if it results in
* not filtering out any values.
*/
filter<F extends V>(
predicate: (value: V, key: K, iter: this) => value is F,
context?: any
): OrderedMap<K, F>;
filter(
predicate: (value: V, key: K, iter: this) => any,
context?: any
): this;
/**
* @see Collection.Keyed.flip
*/
flip(): OrderedMap<V, K>;
}
/**
* A Collection of unique values with `O(log32 N)` adds and has.
*
* When iterating a Set, the entries will be (value, value) pairs. Iteration
* order of a Set is undefined, however is stable. Multiple iterations of the
* same Set will iterate in the same order.
*
* Set values, like Map keys, may be of any type. Equality is determined using
* `Immutable.is`, enabling Sets to uniquely include other Immutable
* collections, custom value types, and NaN.
*/
export module Set {
/**
* True if the provided value is a Set
*/
function isSet(maybeSet: any): maybeSet is Set<any>;
/**
* Creates a new Set containing `values`.
*/
function of<T>(...values: Array<T>): Set<T>;
/**
* `Set.fromKeys()` creates a new immutable Set containing the keys from
* this Collection or JavaScript Object.
*/
function fromKeys<T>(iter: Collection<T, any>): Set<T>;
function fromKeys(obj: {[key: string]: any}): Set<string>;
/**
* `Set.intersect()` creates a new immutable Set that is the intersection of
* a collection of other sets.
*
* ```js
* const { Set } = require('immutable')
* const intersected = Set.intersect([
* Set([ 'a', 'b', 'c' ])
* Set([ 'c', 'a', 't' ])
* ])
* // Set [ "a", "c"" ]
* ```
*/
function intersect<T>(sets: Iterable<Iterable<T>>): Set<T>;
/**
* `Set.union()` creates a new immutable Set that is the union of a
* collection of other sets.
*
* ```js
* const { Set } = require('immutable')
* const unioned = Set.union([
* Set([ 'a', 'b', 'c' ])
* Set([ 'c', 'a', 't' ])
* ])
* // Set [ "a", "b", "c", "t"" ]
* ```
*/
function union<T>(sets: Iterable<Iterable<T>>): Set<T>;
}
/**
* Create a new immutable Set containing the values of the provided
* collection-like.
*
* Note: `Set` is a factory function and not a class, and does not use the
* `new` keyword during construction.
*/
export function Set(): Set<any>;
export function Set<T>(): Set<T>;
export function Set<T>(collection: Iterable<T>): Set<T>;
export interface Set<T> extends Collection.Set<T> {
/**
* The number of items in this Set.
*/
readonly size: number;
// Persistent changes
/**
* Returns a new Set which also includes this value.
*
* Note: `add` can be used in `withMutations`.
*/
add(value: T): this;
/**
* Returns a new Set which excludes this value.
*
* Note: `delete` can be used in `withMutations`.
*
* Note: `delete` **cannot** be safely used in IE8, use `remove` if
* supporting old browsers.
*
* @alias remove
*/
delete(value: T): this;
remove(value: T): this;
/**
* Returns a new Set containing no values.
*
* Note: `clear` can be used in `withMutations`.
*/
clear(): this;
/**
* Returns a Set including any value from `collections` that does not already
* exist in this Set.
*
* Note: `union` can be used in `withMutations`.
* @alias merge
* @alias concat
*/
union<C>(...collections: Array<Iterable<C>>): Set<T | C>;
merge<C>(...collections: Array<Iterable<C>>): Set<T | C>;
concat<C>(...collections: Array<Iterable<C>>): Set<T | C>;
/**
* Returns a Set which has removed any values not also contained
* within `collections`.
*
* Note: `intersect` can be used in `withMutations`.
*/
intersect(...collections: Array<Iterable<T>>): this;
/**
* Returns a Set excluding any values contained within `collections`.
*
* <!-- runkit:activate -->
* ```js
* const { OrderedSet } = require('immutable')
* OrderedSet([ 1, 2, 3 ]).subtract([1, 3])
* // OrderedSet [2]
* ```
*
* Note: `subtract` can be used in `withMutations`.
*/
subtract(...collections: Array<Iterable<T>>): this;
// Transient changes
/**
* Note: Not all methods can be used on a mutable collection or within
* `withMutations`! Check the documentation for each method to see if it
* mentions being safe to use in `withMutations`.
*
* @see `Map#withMutations`
*/
withMutations(mutator: (mutable: this) => any): this;
/**
* Note: Not all methods can be used on a mutable collection or within
* `withMutations`! Check the documentation for each method to see if it
* mentions being safe to use in `withMutations`.
*
* @see `Map#asMutable`
*/
asMutable(): this;
/**
* @see `Map#wasAltered`
*/
wasAltered(): boolean;
/**
* @see `Map#asImmutable`
*/
asImmutable(): this;
// Sequence algorithms
/**
* Returns a new Set with values passed through a
* `mapper` function.
*
* Set([1,2]).map(x => 10 * x)
* // Set [10,20]
*/
map<M>(
mapper: (value: T, key: T, iter: this) => M,
context?: any
): Set<M>;
/**
* Flat-maps the Set, returning a new Set.
*
* Similar to `set.map(...).flatten(true)`.
*/
flatMap<M>(
mapper: (value: T, key: T, iter: this) => Iterable<M>,
context?: any
): Set<M>;
/**
* Returns a new Set with only the values for which the `predicate`
* function returns true.
*
* Note: `filter()` always returns a new instance, even if it results in
* not filtering out any values.
*/
filter<F extends T>(
predicate: (value: T, key: T, iter: this) => value is F,
context?: any
): Set<F>;
filter(
predicate: (value: T, key: T, iter: this) => any,
context?: any
): this;
}
/**
* A type of Set that has the additional guarantee that the iteration order of
* values will be the order in which they were `add`ed.
*
* The iteration behavior of OrderedSet is the same as native ES6 Set.
*
* Note that `OrderedSet` are more expensive than non-ordered `Set` and may
* consume more memory. `OrderedSet#add` is amortized O(log32 N), but not
* stable.
*/
export module OrderedSet {
/**
* True if the provided value is an OrderedSet.
*/
function isOrderedSet(maybeOrderedSet: any): boolean;
/**
* Creates a new OrderedSet containing `values`.
*/
function of<T>(...values: Array<T>): OrderedSet<T>;
/**
* `OrderedSet.fromKeys()` creates a new immutable OrderedSet containing
* the keys from this Collection or JavaScript Object.
*/
function fromKeys<T>(iter: Collection<T, any>): OrderedSet<T>;
function fromKeys(obj: {[key: string]: any}): OrderedSet<string>;
}
/**
* Create a new immutable OrderedSet containing the values of the provided
* collection-like.
*
* Note: `OrderedSet` is a factory function and not a class, and does not use
* the `new` keyword during construction.
*/
export function OrderedSet(): OrderedSet<any>;
export function OrderedSet<T>(): OrderedSet<T>;
export function OrderedSet<T>(collection: Iterable<T>): OrderedSet<T>;
export interface OrderedSet<T> extends Set<T> {
/**
* The number of items in this OrderedSet.
*/
readonly size: number;
/**
* Returns an OrderedSet including any value from `collections` that does
* not already exist in this OrderedSet.
*
* Note: `union` can be used in `withMutations`.
* @alias merge
* @alias concat
*/
union<C>(...collections: Array<Iterable<C>>): OrderedSet<T | C>;
merge<C>(...collections: Array<Iterable<C>>): OrderedSet<T | C>;
concat<C>(...collections: Array<Iterable<C>>): OrderedSet<T | C>;
// Sequence algorithms
/**
* Returns a new Set with values passed through a
* `mapper` function.
*
* OrderedSet([ 1, 2 ]).map(x => 10 * x)
* // OrderedSet [10, 20]
*/
map<M>(
mapper: (value: T, key: T, iter: this) => M,
context?: any
): OrderedSet<M>;
/**
* Flat-maps the OrderedSet, returning a new OrderedSet.
*
* Similar to `set.map(...).flatten(true)`.
*/
flatMap<M>(
mapper: (value: T, key: T, iter: this) => Iterable<M>,
context?: any
): OrderedSet<M>;
/**
* Returns a new OrderedSet with only the values for which the `predicate`
* function returns true.
*
* Note: `filter()` always returns a new instance, even if it results in
* not filtering out any values.
*/
filter<F extends T>(
predicate: (value: T, key: T, iter: this) => value is F,
context?: any
): OrderedSet<F>;
filter(
predicate: (value: T, key: T, iter: this) => any,
context?: any
): this;
/**
* Returns an OrderedSet of the same type "zipped" with the provided
* collections.
*
* Like `zipWith`, but using the default `zipper`: creating an `Array`.
*
* ```js
* const a = OrderedSet([ 1, 2, 3 ])
* const b = OrderedSet([ 4, 5, 6 ])
* const c = a.zip(b)
* // OrderedSet [ [ 1, 4 ], [ 2, 5 ], [ 3, 6 ] ]
* ```
*/
zip<U>(other: Collection<any, U>): OrderedSet<[T,U]>;
zip<U,V>(other1: Collection<any, U>, other2: Collection<any, V>): OrderedSet<[T,U,V]>;
zip(...collections: Array<Collection<any, any>>): OrderedSet<any>;
/**
* Returns a OrderedSet of the same type "zipped" with the provided
* collections.
*
* Unlike `zip`, `zipAll` continues zipping until the longest collection is
* exhausted. Missing values from shorter collections are filled with `undefined`.
*
* ```js
* const a = OrderedSet([ 1, 2 ]);
* const b = OrderedSet([ 3, 4, 5 ]);
* const c = a.zipAll(b); // OrderedSet [ [ 1, 3 ], [ 2, 4 ], [ undefined, 5 ] ]
* ```
*
* Note: Since zipAll will return a collection as large as the largest
* input, some results may contain undefined values. TypeScript cannot
* account for these without cases (as of v2.5).
*/
zipAll<U>(other: Collection<any, U>): OrderedSet<[T,U]>;
zipAll<U,V>(other1: Collection<any, U>, other2: Collection<any, V>): OrderedSet<[T,U,V]>;
zipAll(...collections: Array<Collection<any, any>>): OrderedSet<any>;
/**
* Returns an OrderedSet of the same type "zipped" with the provided
* collections by using a custom `zipper` function.
*
* @see Seq.Indexed.zipWith
*/
zipWith<U, Z>(
zipper: (value: T, otherValue: U) => Z,
otherCollection: Collection<any, U>
): OrderedSet<Z>;
zipWith<U, V, Z>(
zipper: (value: T, otherValue: U, thirdValue: V) => Z,
otherCollection: Collection<any, U>,
thirdCollection: Collection<any, V>
): OrderedSet<Z>;
zipWith<Z>(
zipper: (...any: Array<any>) => Z,
...collections: Array<Collection<any, any>>
): OrderedSet<Z>;
}
/**
* Stacks are indexed collections which support very efficient O(1) addition
* and removal from the front using `unshift(v)` and `shift()`.
*
* For familiarity, Stack also provides `push(v)`, `pop()`, and `peek()`, but
* be aware that they also operate on the front of the list, unlike List or
* a JavaScript Array.
*
* Note: `reverse()` or any inherent reverse traversal (`reduceRight`,
* `lastIndexOf`, etc.) is not efficient with a Stack.
*
* Stack is implemented with a Single-Linked List.
*/
export module Stack {
/**
* True if the provided value is a Stack
*/
function isStack(maybeStack: any): maybeStack is Stack<any>;
/**
* Creates a new Stack containing `values`.
*/
function of<T>(...values: Array<T>): Stack<T>;
}
/**
* Create a new immutable Stack containing the values of the provided
* collection-like.
*
* The iteration order of the provided collection is preserved in the
* resulting `Stack`.
*
* Note: `Stack` is a factory function and not a class, and does not use the
* `new` keyword during construction.
*/
export function Stack(): Stack<any>;
export function Stack<T>(): Stack<T>;
export function Stack<T>(collection: Iterable<T>): Stack<T>;
export interface Stack<T> extends Collection.Indexed<T> {
/**
* The number of items in this Stack.
*/
readonly size: number;
// Reading values
/**
* Alias for `Stack.first()`.
*/
peek(): T | undefined;
// Persistent changes
/**
* Returns a new Stack with 0 size and no values.
*
* Note: `clear` can be used in `withMutations`.
*/
clear(): Stack<T>;
/**
* Returns a new Stack with the provided `values` prepended, shifting other
* values ahead to higher indices.
*
* This is very efficient for Stack.
*
* Note: `unshift` can be used in `withMutations`.
*/
unshift(...values: Array<T>): Stack<T>;
/**
* Like `Stack#unshift`, but accepts a collection rather than varargs.
*
* Note: `unshiftAll` can be used in `withMutations`.
*/
unshiftAll(iter: Iterable<T>): Stack<T>;
/**
* Returns a new Stack with a size ones less than this Stack, excluding
* the first item in this Stack, shifting all other values to a lower index.
*
* Note: this differs from `Array#shift` because it returns a new
* Stack rather than the removed value. Use `first()` or `peek()` to get the
* first value in this Stack.
*
* Note: `shift` can be used in `withMutations`.
*/
shift(): Stack<T>;
/**
* Alias for `Stack#unshift` and is not equivalent to `List#push`.
*/
push(...values: Array<T>): Stack<T>;
/**
* Alias for `Stack#unshiftAll`.
*/
pushAll(iter: Iterable<T>): Stack<T>;
/**
* Alias for `Stack#shift` and is not equivalent to `List#pop`.
*/
pop(): Stack<T>;
// Transient changes
/**
* Note: Not all methods can be used on a mutable collection or within
* `withMutations`! Check the documentation for each method to see if it
* mentions being safe to use in `withMutations`.
*
* @see `Map#withMutations`
*/
withMutations(mutator: (mutable: this) => any): this;
/**
* Note: Not all methods can be used on a mutable collection or within
* `withMutations`! Check the documentation for each method to see if it
* mentions being safe to use in `withMutations`.
*
* @see `Map#asMutable`
*/
asMutable(): this;
/**
* @see `Map#wasAltered`
*/
wasAltered(): boolean;
/**
* @see `Map#asImmutable`
*/
asImmutable(): this;
// Sequence algorithms
/**
* Returns a new Stack with other collections concatenated to this one.
*/
concat<C>(...valuesOrCollections: Array<Iterable<C> | C>): Stack<T | C>;
/**
* Returns a new Stack with values passed through a
* `mapper` function.
*
* Stack([ 1, 2 ]).map(x => 10 * x)
* // Stack [ 10, 20 ]
*
* Note: `map()` always returns a new instance, even if it produced the same
* value at every step.
*/
map<M>(
mapper: (value: T, key: number, iter: this) => M,
context?: any
): Stack<M>;
/**
* Flat-maps the Stack, returning a new Stack.
*
* Similar to `stack.map(...).flatten(true)`.
*/
flatMap<M>(
mapper: (value: T, key: number, iter: this) => Iterable<M>,
context?: any
): Stack<M>;
/**
* Returns a new Set with only the values for which the `predicate`
* function returns true.
*
* Note: `filter()` always returns a new instance, even if it results in
* not filtering out any values.
*/
filter<F extends T>(
predicate: (value: T, index: number, iter: this) => value is F,
context?: any
): Set<F>;
filter(
predicate: (value: T, index: number, iter: this) => any,
context?: any
): this;
/**
* Returns a Stack "zipped" with the provided collections.
*
* Like `zipWith`, but using the default `zipper`: creating an `Array`.
*
* ```js
* const a = Stack([ 1, 2, 3 ]);
* const b = Stack([ 4, 5, 6 ]);
* const c = a.zip(b); // Stack [ [ 1, 4 ], [ 2, 5 ], [ 3, 6 ] ]
* ```
*/
zip<U>(other: Collection<any, U>): Stack<[T,U]>;
zip<U,V>(other: Collection<any, U>, other2: Collection<any,V>): Stack<[T,U,V]>;
zip(...collections: Array<Collection<any, any>>): Stack<any>;
/**
* Returns a Stack "zipped" with the provided collections.
*
* Unlike `zip`, `zipAll` continues zipping until the longest collection is
* exhausted. Missing values from shorter collections are filled with `undefined`.
*
* ```js
* const a = Stack([ 1, 2 ]);
* const b = Stack([ 3, 4, 5 ]);
* const c = a.zipAll(b); // Stack [ [ 1, 3 ], [ 2, 4 ], [ undefined, 5 ] ]
* ```
*
* Note: Since zipAll will return a collection as large as the largest
* input, some results may contain undefined values. TypeScript cannot
* account for these without cases (as of v2.5).
*/
zipAll<U>(other: Collection<any, U>): Stack<[T,U]>;
zipAll<U,V>(other: Collection<any, U>, other2: Collection<any,V>): Stack<[T,U,V]>;
zipAll(...collections: Array<Collection<any, any>>): Stack<any>;
/**
* Returns a Stack "zipped" with the provided collections by using a
* custom `zipper` function.
*
* ```js
* const a = Stack([ 1, 2, 3 ]);
* const b = Stack([ 4, 5, 6 ]);
* const c = a.zipWith((a, b) => a + b, b);
* // Stack [ 5, 7, 9 ]
* ```
*/
zipWith<U, Z>(
zipper: (value: T, otherValue: U) => Z,
otherCollection: Collection<any, U>
): Stack<Z>;
zipWith<U, V, Z>(
zipper: (value: T, otherValue: U, thirdValue: V) => Z,
otherCollection: Collection<any, U>,
thirdCollection: Collection<any, V>
): Stack<Z>;
zipWith<Z>(
zipper: (...any: Array<any>) => Z,
...collections: Array<Collection<any, any>>
): Stack<Z>;
}
/**
* Returns a Seq.Indexed of numbers from `start` (inclusive) to `end`
* (exclusive), by `step`, where `start` defaults to 0, `step` to 1, and `end` to
* infinity. When `start` is equal to `end`, returns empty range.
*
* Note: `Range` is a factory function and not a class, and does not use the
* `new` keyword during construction.
*
* ```js
* const { Range } = require('immutable')
* Range() // [ 0, 1, 2, 3, ... ]
* Range(10) // [ 10, 11, 12, 13, ... ]
* Range(10, 15) // [ 10, 11, 12, 13, 14 ]
* Range(10, 30, 5) // [ 10, 15, 20, 25 ]
* Range(30, 10, 5) // [ 30, 25, 20, 15 ]
* Range(30, 30, 5) // []
* ```
*/
export function Range(start?: number, end?: number, step?: number): Seq.Indexed<number>;
/**
* Returns a Seq.Indexed of `value` repeated `times` times. When `times` is
* not defined, returns an infinite `Seq` of `value`.
*
* Note: `Repeat` is a factory function and not a class, and does not use the
* `new` keyword during construction.
*
* ```js
* const { Repeat } = require('immutable')
* Repeat('foo') // [ 'foo', 'foo', 'foo', ... ]
* Repeat('bar', 4) // [ 'bar', 'bar', 'bar', 'bar' ]
* ```
*/
export function Repeat<T>(value: T, times?: number): Seq.Indexed<T>;
/**
* A record is similar to a JS object, but enforces a specific set of allowed
* string keys, and has default values.
*
* The `Record()` function produces new Record Factories, which when called
* create Record instances.
*
* ```js
* const { Record } = require('immutable')
* const ABRecord = Record({ a: 1, b: 2 })
* const myRecord = ABRecord({ b: 3 })
* ```
*
* Records always have a value for the keys they define. `remove`ing a key
* from a record simply resets it to the default value for that key.
*
* ```js
* myRecord.size // 2
* myRecord.get('a') // 1
* myRecord.get('b') // 3
* const myRecordWithoutB = myRecord.remove('b')
* myRecordWithoutB.get('b') // 2
* myRecordWithoutB.size // 2
* ```
*
* Values provided to the constructor not found in the Record type will
* be ignored. For example, in this case, ABRecord is provided a key "x" even
* though only "a" and "b" have been defined. The value for "x" will be
* ignored for this record.
*
* ```js
* const myRecord = ABRecord({ b: 3, x: 10 })
* myRecord.get('x') // undefined
* ```
*
* Because Records have a known set of string keys, property get access works
* as expected, however property sets will throw an Error.
*
* Note: IE8 does not support property access. Only use `get()` when
* supporting IE8.
*
* ```js
* myRecord.b // 3
* myRecord.b = 5 // throws Error
* ```
*
* Record Types can be extended as well, allowing for custom methods on your
* Record. This is not a common pattern in functional environments, but is in
* many JS programs.
*
* However Record Types are more restricted than typical JavaScript classes.
* They do not use a class constructor, which also means they cannot use
* class properties (since those are technically part of a constructor).
*
* While Record Types can be syntactically created with the JavaScript `class`
* form, the resulting Record function is actually a factory function, not a
* class constructor. Even though Record Types are not classes, JavaScript
* currently requires the use of `new` when creating new Record instances if
* they are defined as a `class`.
*
* ```
* class ABRecord extends Record({ a: 1, b: 2 }) {
* getAB() {
* return this.a + this.b;
* }
* }
*
* var myRecord = new ABRecord({b: 3})
* myRecord.getAB() // 4
* ```
*
*
* **Flow Typing Records:**
*
* Immutable.js exports two Flow types designed to make it easier to use
* Records with flow typed code, `RecordOf<TProps>` and `RecordFactory<TProps>`.
*
* When defining a new kind of Record factory function, use a flow type that
* describes the values the record contains along with `RecordFactory<TProps>`.
* To type instances of the Record (which the factory function returns),
* use `RecordOf<TProps>`.
*
* Typically, new Record definitions will export both the Record factory
* function as well as the Record instance type for use in other code.
*
* ```js
* import type { RecordFactory, RecordOf } from 'immutable';
*
* // Use RecordFactory<TProps> for defining new Record factory functions.
* type Point3DProps = { x: number, y: number, z: number };
* const defaultValues: Point3DProps = { x: 0, y: 0, z: 0 };
* const makePoint3D: RecordFactory<Point3DProps> = Record(defaultValues);
* export makePoint3D;
*
* // Use RecordOf<T> for defining new instances of that Record.
* export type Point3D = RecordOf<Point3DProps>;
* const some3DPoint: Point3D = makePoint3D({ x: 10, y: 20, z: 30 });
* ```
*
* **Flow Typing Record Subclasses:**
*
* Records can be subclassed as a means to add additional methods to Record
* instances. This is generally discouraged in favor of a more functional API,
* since Subclasses have some minor overhead. However the ability to create
* a rich API on Record types can be quite valuable.
*
* When using Flow to type Subclasses, do not use `RecordFactory<TProps>`,
* instead apply the props type when subclassing:
*
* ```js
* type PersonProps = {name: string, age: number};
* const defaultValues: PersonProps = {name: 'Aristotle', age: 2400};
* const PersonRecord = Record(defaultValues);
* class Person extends PersonRecord<PersonProps> {
* getName(): string {
* return this.get('name')
* }
*
* setName(name: string): this {
* return this.set('name', name);
* }
* }
* ```
*
* **Choosing Records vs plain JavaScript objects**
*
* Records offer a persistently immutable alternative to plain JavaScript
* objects, however they're not required to be used within Immutable.js
* collections. In fact, the deep-access and deep-updating functions
* like `getIn()` and `setIn()` work with plain JavaScript Objects as well.
*
* Deciding to use Records or Objects in your application should be informed
* by the tradeoffs and relative benefits of each:
*
* - *Runtime immutability*: plain JS objects may be carefully treated as
* immutable, however Record instances will *throw* if attempted to be
* mutated directly. Records provide this additional guarantee, however at
* some marginal runtime cost. While JS objects are mutable by nature, the
* use of type-checking tools like [Flow](https://medium.com/@gcanti/immutability-with-flow-faa050a1aef4)
* can help gain confidence in code written to favor immutability.
*
* - *Value equality*: Records use value equality when compared with `is()`
* or `record.equals()`. That is, two Records with the same keys and values
* are equal. Plain objects use *reference equality*. Two objects with the
* same keys and values are not equal since they are different objects.
* This is important to consider when using objects as keys in a `Map` or
* values in a `Set`, which use equality when retrieving values.
*
* - *API methods*: Records have a full featured API, with methods like
* `.getIn()`, and `.equals()`. These can make working with these values
* easier, but comes at the cost of not allowing keys with those names.
*
* - *Default values*: Records provide default values for every key, which
* can be useful when constructing Records with often unchanging values.
* However default values can make using Flow and TypeScript more laborious.
*
* - *Serialization*: Records use a custom internal representation to
* efficiently store and update their values. Converting to and from this
* form isn't free. If converting Records to plain objects is common,
* consider sticking with plain objects to begin with.
*/
export module Record {
/**
* True if `maybeRecord` is an instance of a Record.
*/
export function isRecord(maybeRecord: any): maybeRecord is Record<any>;
/**
* Records allow passing a second parameter to supply a descriptive name
* that appears when converting a Record to a string or in any error
* messages. A descriptive name for any record can be accessed by using this
* method. If one was not provided, the string "Record" is returned.
*
* ```js
* const { Record } = require('immutable')
* const Person = Record({
* name: null
* }, 'Person')
*
* var me = Person({ name: 'My Name' })
* me.toString() // "Person { "name": "My Name" }"
* Record.getDescriptiveName(me) // "Person"
* ```
*/
export function getDescriptiveName(record: Record<any>): string;
/**
* A Record.Factory is created by the `Record()` function. Record instances
* are created by passing it some of the accepted values for that Record
* type:
*
* <!-- runkit:activate
* { "preamble": "const { Record } = require('immutable')" }
* -->
* ```js
* // makePerson is a Record Factory function
* const makePerson = Record({ name: null, favoriteColor: 'unknown' });
*
* // alan is a Record instance
* const alan = makePerson({ name: 'Alan' });
* ```
*
* Note that Record Factories return `Record<TProps> & Readonly<TProps>`,
* this allows use of both the Record instance API, and direct property
* access on the resulting instances:
*
* <!-- runkit:activate
* { "preamble": "const { Record } = require('immutable');const makePerson = Record({ name: null, favoriteColor: 'unknown' });const alan = makePerson({ name: 'Alan' });" }
* -->
* ```js
* // Use the Record API
* console.log('Record API: ' + alan.get('name'))
*
* // Or direct property access (Readonly)
* console.log('property access: ' + alan.name)
* ```
*
* **Flow Typing Records:**
*
* Use the `RecordFactory<TProps>` Flow type to get high quality type checking of
* Records:
*
* ```js
* import type { RecordFactory, RecordOf } from 'immutable';
*
* // Use RecordFactory<TProps> for defining new Record factory functions.
* type PersonProps = { name: ?string, favoriteColor: string };
* const makePerson: RecordFactory<PersonProps> = Record({ name: null, favoriteColor: 'unknown' });
*
* // Use RecordOf<T> for defining new instances of that Record.
* type Person = RecordOf<PersonProps>;
* const alan: Person = makePerson({ name: 'Alan' });
* ```
*/
export module Factory {}
export interface Factory<TProps extends Object> {
(values?: Partial<TProps> | Iterable<[string, any]>): Record<TProps> & Readonly<TProps>;
new (values?: Partial<TProps> | Iterable<[string, any]>): Record<TProps> & Readonly<TProps>;
/**
* The name provided to `Record(values, name)` can be accessed with
* `displayName`.
*/
displayName: string;
}
export function Factory<TProps extends Object>(values?: Partial<TProps> | Iterable<[string, any]>): Record<TProps> & Readonly<TProps>;
}
/**
* Unlike other types in Immutable.js, the `Record()` function creates a new
* Record Factory, which is a function that creates Record instances.
*
* See above for examples of using `Record()`.
*
* Note: `Record` is a factory function and not a class, and does not use the
* `new` keyword during construction.
*/
export function Record<TProps>(defaultValues: TProps, name?: string): Record.Factory<TProps>;
export interface Record<TProps extends Object> {
// Reading values
has(key: string): key is keyof TProps & string;
/**
* Returns the value associated with the provided key, which may be the
* default value defined when creating the Record factory function.
*
* If the requested key is not defined by this Record type, then
* notSetValue will be returned if provided. Note that this scenario would
* produce an error when using Flow or TypeScript.
*/
get<K extends keyof TProps>(key: K, notSetValue?: any): TProps[K];
get<T>(key: string, notSetValue: T): T;
// Reading deep values
hasIn(keyPath: Iterable<any>): boolean;
getIn(keyPath: Iterable<any>): any;
// Value equality
equals(other: any): boolean;
hashCode(): number;
// Persistent changes
set<K extends keyof TProps>(key: K, value: TProps[K]): this;
update<K extends keyof TProps>(key: K, updater: (value: TProps[K]) => TProps[K]): this;
merge(...collections: Array<Partial<TProps> | Iterable<[string, any]>>): this;
mergeDeep(...collections: Array<Partial<TProps> | Iterable<[string, any]>>): this;
mergeWith(
merger: (oldVal: any, newVal: any, key: keyof TProps) => any,
...collections: Array<Partial<TProps> | Iterable<[string, any]>>
): this;
mergeDeepWith(
merger: (oldVal: any, newVal: any, key: any) => any,
...collections: Array<Partial<TProps> | Iterable<[string, any]>>
): this;
/**
* Returns a new instance of this Record type with the value for the
* specific key set to its default value.
*
* @alias remove
*/
delete<K extends keyof TProps>(key: K): this;
remove<K extends keyof TProps>(key: K): this;
/**
* Returns a new instance of this Record type with all values set
* to their default values.
*/
clear(): this;
// Deep persistent changes
setIn(keyPath: Iterable<any>, value: any): this;
updateIn(keyPath: Iterable<any>, updater: (value: any) => any): this;
mergeIn(keyPath: Iterable<any>, ...collections: Array<any>): this;
mergeDeepIn(keyPath: Iterable<any>, ...collections: Array<any>): this;
/**
* @alias removeIn
*/
deleteIn(keyPath: Iterable<any>): this;
removeIn(keyPath: Iterable<any>): this;
// Conversion to JavaScript types
/**
* Deeply converts this Record to equivalent native JavaScript Object.
*
* Note: This method may not be overridden. Objects with custom
* serialization to plain JS may override toJSON() instead.
*/
toJS(): { [K in keyof TProps]: any };
/**
* Shallowly converts this Record to equivalent native JavaScript Object.
*/
toJSON(): TProps;
/**
* Shallowly converts this Record to equivalent JavaScript Object.
*/
toObject(): TProps;
// Transient changes
/**
* Note: Not all methods can be used on a mutable collection or within
* `withMutations`! Only `set` may be used mutatively.
*
* @see `Map#withMutations`
*/
withMutations(mutator: (mutable: this) => any): this;
/**
* @see `Map#asMutable`
*/
asMutable(): this;
/**
* @see `Map#wasAltered`
*/
wasAltered(): boolean;
/**
* @see `Map#asImmutable`
*/
asImmutable(): this;
// Sequence algorithms
toSeq(): Seq.Keyed<keyof TProps, TProps[keyof TProps]>;
[Symbol.iterator](): IterableIterator<[keyof TProps, TProps[keyof TProps]]>;
}
/**
* RecordOf<T> is used in TypeScript to define interfaces expecting an
* instance of record with type T.
*
* This is equivalent to an instance of a record created by a Record Factory.
*/
export type RecordOf<TProps extends Object> = Record<TProps> &
Readonly<TProps>;
/**
* `Seq` describes a lazy operation, allowing them to efficiently chain
* use of all the higher-order collection methods (such as `map` and `filter`)
* by not creating intermediate collections.
*
* **Seq is immutable** — Once a Seq is created, it cannot be
* changed, appended to, rearranged or otherwise modified. Instead, any
* mutative method called on a `Seq` will return a new `Seq`.
*
* **Seq is lazy** — `Seq` does as little work as necessary to respond to any
* method call. Values are often created during iteration, including implicit
* iteration when reducing or converting to a concrete data structure such as
* a `List` or JavaScript `Array`.
*
* For example, the following performs no work, because the resulting
* `Seq`'s values are never iterated:
*
* ```js
* const { Seq } = require('immutable')
* const oddSquares = Seq([ 1, 2, 3, 4, 5, 6, 7, 8 ])
* .filter(x => x % 2 !== 0)
* .map(x => x * x)
* ```
*
* Once the `Seq` is used, it performs only the work necessary. In this
* example, no intermediate arrays are ever created, filter is called three
* times, and map is only called once:
*
* ```js
* oddSquares.get(1); // 9
* ```
*
* Any collection can be converted to a lazy Seq with `Seq()`.
*
* <!-- runkit:activate -->
* ```js
* const { Map } = require('immutable')
* const map = Map({ a: 1, b: 2, c: 3 }
* const lazySeq = Seq(map)
* ```
*
* `Seq` allows for the efficient chaining of operations, allowing for the
* expression of logic that can otherwise be very tedious:
*
* ```js
* lazySeq
* .flip()
* .map(key => key.toUpperCase())
* .flip()
* // Seq { A: 1, B: 1, C: 1 }
* ```
*
* As well as expressing logic that would otherwise seem memory or time
* limited, for example `Range` is a special kind of Lazy sequence.
*
* <!-- runkit:activate -->
* ```js
* const { Range } = require('immutable')
* Range(1, Infinity)
* .skip(1000)
* .map(n => -n)
* .filter(n => n % 2 === 0)
* .take(2)
* .reduce((r, n) => r * n, 1)
* // 1006008
* ```
*
* Seq is often used to provide a rich collection API to JavaScript Object.
*
* ```js
* Seq({ x: 0, y: 1, z: 2 }).map(v => v * 2).toObject();
* // { x: 0, y: 2, z: 4 }
* ```
*/
export module Seq {
/**
* True if `maybeSeq` is a Seq, it is not backed by a concrete
* structure such as Map, List, or Set.
*/
function isSeq(maybeSeq: any): maybeSeq is Seq.Indexed<any> | Seq.Keyed<any, any> | Seq.Set<any>;
/**
* `Seq` which represents key-value pairs.
*/
export module Keyed {}
/**
* Always returns a Seq.Keyed, if input is not keyed, expects an
* collection of [K, V] tuples.
*
* Note: `Seq.Keyed` is a conversion function and not a class, and does not
* use the `new` keyword during construction.
*/
export function Keyed<K, V>(collection: Iterable<[K, V]>): Seq.Keyed<K, V>;
export function Keyed<V>(obj: {[key: string]: V}): Seq.Keyed<string, V>;
export function Keyed<K, V>(): Seq.Keyed<K, V>;
export function Keyed(): Seq.Keyed<any, any>;
export interface Keyed<K, V> extends Seq<K, V>, Collection.Keyed<K, V> {
/**
* Deeply converts this Keyed Seq to equivalent native JavaScript Object.
*
* Converts keys to Strings.
*/
toJS(): Object;
/**
* Shallowly converts this Keyed Seq to equivalent native JavaScript Object.
*
* Converts keys to Strings.
*/
toJSON(): { [key: string]: V };
/**
* Shallowly converts this collection to an Array.
*/
toArray(): Array<[K, V]>;
/**
* Returns itself
*/
toSeq(): this;
/**
* Returns a new Seq with other collections concatenated to this one.
*
* All entries will be present in the resulting Seq, even if they
* have the same key.
*/
concat<KC, VC>(...collections: Array<Iterable<[KC, VC]>>): Seq.Keyed<K | KC, V | VC>;
concat<C>(...collections: Array<{[key: string]: C}>): Seq.Keyed<K | string, V | C>;
/**
* Returns a new Seq.Keyed with values passed through a
* `mapper` function.
*
* ```js
* const { Seq } = require('immutable')
* Seq.Keyed({ a: 1, b: 2 }).map(x => 10 * x)
* // Seq { "a": 10, "b": 20 }
* ```
*
* Note: `map()` always returns a new instance, even if it produced the
* same value at every step.
*/
map<M>(
mapper: (value: V, key: K, iter: this) => M,
context?: any
): Seq.Keyed<K, M>;
/**
* @see Collection.Keyed.mapKeys
*/
mapKeys<M>(
mapper: (key: K, value: V, iter: this) => M,
context?: any
): Seq.Keyed<M, V>;
/**
* @see Collection.Keyed.mapEntries
*/
mapEntries<KM, VM>(
mapper: (entry: [K, V], index: number, iter: this) => [KM, VM],
context?: any
): Seq.Keyed<KM, VM>;
/**
* Flat-maps the Seq, returning a Seq of the same type.
*
* Similar to `seq.map(...).flatten(true)`.
*/
flatMap<KM, VM>(
mapper: (value: V, key: K, iter: this) => Iterable<[KM, VM]>,
context?: any
): Seq.Keyed<KM, VM>;
/**
* Returns a new Seq with only the entries for which the `predicate`
* function returns true.
*
* Note: `filter()` always returns a new instance, even if it results in
* not filtering out any values.
*/
filter<F extends V>(
predicate: (value: V, key: K, iter: this) => value is F,
context?: any
): Seq.Keyed<K, F>;
filter(
predicate: (value: V, key: K, iter: this) => any,
context?: any
): this;
/**
* @see Collection.Keyed.flip
*/
flip(): Seq.Keyed<V, K>;
}
/**
* `Seq` which represents an ordered indexed list of values.
*/
module Indexed {
/**
* Provides an Seq.Indexed of the values provided.
*/
function of<T>(...values: Array<T>): Seq.Indexed<T>;
}
/**
* Always returns Seq.Indexed, discarding associated keys and
* supplying incrementing indices.
*
* Note: `Seq.Indexed` is a conversion function and not a class, and does
* not use the `new` keyword during construction.
*/
export function Indexed(): Seq.Indexed<any>;
export function Indexed<T>(): Seq.Indexed<T>;
export function Indexed<T>(collection: Iterable<T>): Seq.Indexed<T>;
export interface Indexed<T> extends Seq<number, T>, Collection.Indexed<T> {
/**
* Deeply converts this Indexed Seq to equivalent native JavaScript Array.
*/
toJS(): Array<any>;
/**
* Shallowly converts this Indexed Seq to equivalent native JavaScript Array.
*/
toJSON(): Array<T>;
/**
* Shallowly converts this collection to an Array.
*/
toArray(): Array<T>;
/**
* Returns itself
*/
toSeq(): this
/**
* Returns a new Seq with other collections concatenated to this one.
*/
concat<C>(...valuesOrCollections: Array<Iterable<C> | C>): Seq.Indexed<T | C>;
/**
* Returns a new Seq.Indexed with values passed through a
* `mapper` function.
*
* ```js
* const { Seq } = require('immutable')
* Seq.Indexed([ 1, 2 ]).map(x => 10 * x)
* // Seq [ 10, 20 ]
* ```
*
* Note: `map()` always returns a new instance, even if it produced the
* same value at every step.
*/
map<M>(
mapper: (value: T, key: number, iter: this) => M,
context?: any
): Seq.Indexed<M>;
/**
* Flat-maps the Seq, returning a a Seq of the same type.
*
* Similar to `seq.map(...).flatten(true)`.
*/
flatMap<M>(
mapper: (value: T, key: number, iter: this) => Iterable<M>,
context?: any
): Seq.Indexed<M>;
/**
* Returns a new Seq with only the values for which the `predicate`
* function returns true.
*
* Note: `filter()` always returns a new instance, even if it results in
* not filtering out any values.
*/
filter<F extends T>(
predicate: (value: T, index: number, iter: this) => value is F,
context?: any
): Seq.Indexed<F>;
filter(
predicate: (value: T, index: number, iter: this) => any,
context?: any
): this;
/**
* Returns a Seq "zipped" with the provided collections.
*
* Like `zipWith`, but using the default `zipper`: creating an `Array`.
*
* ```js
* const a = Seq([ 1, 2, 3 ]);
* const b = Seq([ 4, 5, 6 ]);
* const c = a.zip(b); // Seq [ [ 1, 4 ], [ 2, 5 ], [ 3, 6 ] ]
* ```
*/
zip<U>(other: Collection<any, U>): Seq.Indexed<[T,U]>;
zip<U,V>(other: Collection<any, U>, other2: Collection<any, V>): Seq.Indexed<[T,U,V]>;
zip(...collections: Array<Collection<any, any>>): Seq.Indexed<any>;
/**
* Returns a Seq "zipped" with the provided collections.
*
* Unlike `zip`, `zipAll` continues zipping until the longest collection is
* exhausted. Missing values from shorter collections are filled with `undefined`.
*
* ```js
* const a = Seq([ 1, 2 ]);
* const b = Seq([ 3, 4, 5 ]);
* const c = a.zipAll(b); // Seq [ [ 1, 3 ], [ 2, 4 ], [ undefined, 5 ] ]
* ```
*/
zipAll<U>(other: Collection<any, U>): Seq.Indexed<[T,U]>;
zipAll<U,V>(other: Collection<any, U>, other2: Collection<any, V>): Seq.Indexed<[T,U,V]>;
zipAll(...collections: Array<Collection<any, any>>): Seq.Indexed<any>;
/**
* Returns a Seq "zipped" with the provided collections by using a
* custom `zipper` function.
*
* ```js
* const a = Seq([ 1, 2, 3 ]);
* const b = Seq([ 4, 5, 6 ]);
* const c = a.zipWith((a, b) => a + b, b);
* // Seq [ 5, 7, 9 ]
* ```
*/
zipWith<U, Z>(
zipper: (value: T, otherValue: U) => Z,
otherCollection: Collection<any, U>
): Seq.Indexed<Z>;
zipWith<U, V, Z>(
zipper: (value: T, otherValue: U, thirdValue: V) => Z,
otherCollection: Collection<any, U>,
thirdCollection: Collection<any, V>
): Seq.Indexed<Z>;
zipWith<Z>(
zipper: (...any: Array<any>) => Z,
...collections: Array<Collection<any, any>>
): Seq.Indexed<Z>;
}
/**
* `Seq` which represents a set of values.
*
* Because `Seq` are often lazy, `Seq.Set` does not provide the same guarantee
* of value uniqueness as the concrete `Set`.
*/
export module Set {
/**
* Returns a Seq.Set of the provided values
*/
function of<T>(...values: Array<T>): Seq.Set<T>;
}
/**
* Always returns a Seq.Set, discarding associated indices or keys.
*
* Note: `Seq.Set` is a conversion function and not a class, and does not
* use the `new` keyword during construction.
*/
export function Set(): Seq.Set<any>;
export function Set<T>(): Seq.Set<T>;
export function Set<T>(collection: Iterable<T>): Seq.Set<T>;
export interface Set<T> extends Seq<T, T>, Collection.Set<T> {
/**
* Deeply converts this Set Seq to equivalent native JavaScript Array.
*/
toJS(): Array<any>;
/**
* Shallowly converts this Set Seq to equivalent native JavaScript Array.
*/
toJSON(): Array<T>;
/**
* Shallowly converts this collection to an Array.
*/
toArray(): Array<T>;
/**
* Returns itself
*/
toSeq(): this
/**
* Returns a new Seq with other collections concatenated to this one.
*
* All entries will be present in the resulting Seq, even if they
* are duplicates.
*/
concat<U>(...collections: Array<Iterable<U>>): Seq.Set<T | U>;
/**
* Returns a new Seq.Set with values passed through a
* `mapper` function.
*
* ```js
* Seq.Set([ 1, 2 ]).map(x => 10 * x)
* // Seq { 10, 20 }
* ```
*
* Note: `map()` always returns a new instance, even if it produced the
* same value at every step.
*/
map<M>(
mapper: (value: T, key: T, iter: this) => M,
context?: any
): Seq.Set<M>;
/**
* Flat-maps the Seq, returning a Seq of the same type.
*
* Similar to `seq.map(...).flatten(true)`.
*/
flatMap<M>(
mapper: (value: T, key: T, iter: this) => Iterable<M>,
context?: any
): Seq.Set<M>;
/**
* Returns a new Seq with only the values for which the `predicate`
* function returns true.
*
* Note: `filter()` always returns a new instance, even if it results in
* not filtering out any values.
*/
filter<F extends T>(
predicate: (value: T, key: T, iter: this) => value is F,
context?: any
): Seq.Set<F>;
filter(
predicate: (value: T, key: T, iter: this) => any,
context?: any
): this;
}
}
/**
* Creates a Seq.
*
* Returns a particular kind of `Seq` based on the input.
*
* * If a `Seq`, that same `Seq`.
* * If an `Collection`, a `Seq` of the same kind (Keyed, Indexed, or Set).
* * If an Array-like, an `Seq.Indexed`.
* * If an Iterable Object, an `Seq.Indexed`.
* * If an Object, a `Seq.Keyed`.
*
* Note: An Iterator itself will be treated as an object, becoming a `Seq.Keyed`,
* which is usually not what you want. You should turn your Iterator Object into
* an iterable object by defining a Symbol.iterator (or @@iterator) method which
* returns `this`.
*
* Note: `Seq` is a conversion function and not a class, and does not use the
* `new` keyword during construction.
*/
export function Seq<S extends Seq<any, any>>(seq: S): S;
export function Seq<K, V>(collection: Collection.Keyed<K, V>): Seq.Keyed<K, V>;
export function Seq<T>(collection: Collection.Indexed<T>): Seq.Indexed<T>;
export function Seq<T>(collection: Collection.Set<T>): Seq.Set<T>;
export function Seq<T>(collection: Iterable<T>): Seq.Indexed<T>;
export function Seq<V>(obj: {[key: string]: V}): Seq.Keyed<string, V>;
export function Seq(): Seq<any, any>;
export interface Seq<K, V> extends Collection<K, V> {
/**
* Some Seqs can describe their size lazily. When this is the case,
* size will be an integer. Otherwise it will be undefined.
*
* For example, Seqs returned from `map()` or `reverse()`
* preserve the size of the original `Seq` while `filter()` does not.
*
* Note: `Range`, `Repeat` and `Seq`s made from `Array`s and `Object`s will
* always have a size.
*/
readonly size: number | undefined;
// Force evaluation
/**
* Because Sequences are lazy and designed to be chained together, they do
* not cache their results. For example, this map function is called a total
* of 6 times, as each `join` iterates the Seq of three values.
*
* var squares = Seq([ 1, 2, 3 ]).map(x => x * x)
* squares.join() + squares.join()
*
* If you know a `Seq` will be used multiple times, it may be more
* efficient to first cache it in memory. Here, the map function is called
* only 3 times.
*
* var squares = Seq([ 1, 2, 3 ]).map(x => x * x).cacheResult()
* squares.join() + squares.join()
*
* Use this method judiciously, as it must fully evaluate a Seq which can be
* a burden on memory and possibly performance.
*
* Note: after calling `cacheResult`, a Seq will always have a `size`.
*/
cacheResult(): this;
// Sequence algorithms
/**
* Returns a new Seq with values passed through a
* `mapper` function.
*
* ```js
* const { Seq } = require('immutable')
* Seq([ 1, 2 ]).map(x => 10 * x)
* // Seq [ 10, 20 ]
* ```
*
* Note: `map()` always returns a new instance, even if it produced the same
* value at every step.
*/
map<M>(
mapper: (value: V, key: K, iter: this) => M,
context?: any
): Seq<K, M>;
/**
* Returns a new Seq with values passed through a
* `mapper` function.
*
* ```js
* const { Seq } = require('immutable')
* Seq([ 1, 2 ]).map(x => 10 * x)
* // Seq [ 10, 20 ]
* ```
*
* Note: `map()` always returns a new instance, even if it produced the same
* value at every step.
* Note: used only for sets.
*/
map<M>(
mapper: (value: V, key: K, iter: this) => M,
context?: any
): Seq<M, M>;
/**
* Flat-maps the Seq, returning a Seq of the same type.
*
* Similar to `seq.map(...).flatten(true)`.
*/
flatMap<M>(
mapper: (value: V, key: K, iter: this) => Iterable<M>,
context?: any
): Seq<K, M>;
/**
* Flat-maps the Seq, returning a Seq of the same type.
*
* Similar to `seq.map(...).flatten(true)`.
* Note: Used only for sets.
*/
flatMap<M>(
mapper: (value: V, key: K, iter: this) => Iterable<M>,
context?: any
): Seq<M, M>;
/**
* Returns a new Seq with only the values for which the `predicate`
* function returns true.
*
* Note: `filter()` always returns a new instance, even if it results in
* not filtering out any values.
*/
filter<F extends V>(
predicate: (value: V, key: K, iter: this) => value is F,
context?: any
): Seq<K, F>;
filter(
predicate: (value: V, key: K, iter: this) => any,
context?: any
): this;
}
/**
* The `Collection` is a set of (key, value) entries which can be iterated, and
* is the base class for all collections in `immutable`, allowing them to
* make use of all the Collection methods (such as `map` and `filter`).
*
* Note: A collection is always iterated in the same order, however that order
* may not always be well defined, as is the case for the `Map` and `Set`.
*
* Collection is the abstract base class for concrete data structures. It
* cannot be constructed directly.
*
* Implementations should extend one of the subclasses, `Collection.Keyed`,
* `Collection.Indexed`, or `Collection.Set`.
*/
export module Collection {
/**
* @deprecated use `const { isKeyed } = require('immutable')`
*/
function isKeyed(maybeKeyed: any): maybeKeyed is Collection.Keyed<any, any>;
/**
* @deprecated use `const { isIndexed } = require('immutable')`
*/
function isIndexed(maybeIndexed: any): maybeIndexed is Collection.Indexed<any>;
/**
* @deprecated use `const { isAssociative } = require('immutable')`
*/
function isAssociative(maybeAssociative: any): maybeAssociative is Collection.Keyed<any, any> | Collection.Indexed<any>;
/**
* @deprecated use `const { isOrdered } = require('immutable')`
*/
function isOrdered(maybeOrdered: any): boolean;
/**
* Keyed Collections have discrete keys tied to each value.
*
* When iterating `Collection.Keyed`, each iteration will yield a `[K, V]`
* tuple, in other words, `Collection#entries` is the default iterator for
* Keyed Collections.
*/
export module Keyed {}
/**
* Creates a Collection.Keyed
*
* Similar to `Collection()`, however it expects collection-likes of [K, V]
* tuples if not constructed from a Collection.Keyed or JS Object.
*
* Note: `Collection.Keyed` is a conversion function and not a class, and
* does not use the `new` keyword during construction.
*/
export function Keyed<K, V>(collection: Iterable<[K, V]>): Collection.Keyed<K, V>;
export function Keyed<V>(obj: {[key: string]: V}): Collection.Keyed<string, V>;
export interface Keyed<K, V> extends Collection<K, V> {
/**
* Deeply converts this Keyed collection to equivalent native JavaScript Object.
*
* Converts keys to Strings.
*/
toJS(): Object;
/**
* Shallowly converts this Keyed collection to equivalent native JavaScript Object.
*
* Converts keys to Strings.
*/
toJSON(): { [key: string]: V };
/**
* Shallowly converts this collection to an Array.
*/
toArray(): Array<[K, V]>;
/**
* Returns Seq.Keyed.
* @override
*/
toSeq(): Seq.Keyed<K, V>;
// Sequence functions
/**
* Returns a new Collection.Keyed of the same type where the keys and values
* have been flipped.
*
* <!-- runkit:activate -->
* ```js
* const { Map } = require('immutable')
* Map({ a: 'z', b: 'y' }).flip()
* // Map { "z": "a", "y": "b" }
* ```
*/
flip(): Collection.Keyed<V, K>;
/**
* Returns a new Collection with other collections concatenated to this one.
*/
concat<KC, VC>(...collections: Array<Iterable<[KC, VC]>>): Collection.Keyed<K | KC, V | VC>;
concat<C>(...collections: Array<{[key: string]: C}>): Collection.Keyed<K | string, V | C>;
/**
* Returns a new Collection.Keyed with values passed through a
* `mapper` function.
*
* ```js
* const { Collection } = require('immutable')
* Collection.Keyed({ a: 1, b: 2 }).map(x => 10 * x)
* // Seq { "a": 10, "b": 20 }
* ```
*
* Note: `map()` always returns a new instance, even if it produced the
* same value at every step.
*/
map<M>(
mapper: (value: V, key: K, iter: this) => M,
context?: any
): Collection.Keyed<K, M>;
/**
* Returns a new Collection.Keyed of the same type with keys passed through
* a `mapper` function.
*
* <!-- runkit:activate -->
* ```js
* const { Map } = require('immutable')
* Map({ a: 1, b: 2 }).mapKeys(x => x.toUpperCase())
* // Map { "A": 1, "B": 2 }
* ```
*
* Note: `mapKeys()` always returns a new instance, even if it produced
* the same key at every step.
*/
mapKeys<M>(
mapper: (key: K, value: V, iter: this) => M,
context?: any
): Collection.Keyed<M, V>;
/**
* Returns a new Collection.Keyed of the same type with entries
* ([key, value] tuples) passed through a `mapper` function.
*
* <!-- runkit:activate -->
* ```js
* const { Map } = require('immutable')
* Map({ a: 1, b: 2 })
* .mapEntries(([ k, v ]) => [ k.toUpperCase(), v * 2 ])
* // Map { "A": 2, "B": 4 }
* ```
*
* Note: `mapEntries()` always returns a new instance, even if it produced
* the same entry at every step.
*/
mapEntries<KM, VM>(
mapper: (entry: [K, V], index: number, iter: this) => [KM, VM],
context?: any
): Collection.Keyed<KM, VM>;
/**
* Flat-maps the Collection, returning a Collection of the same type.
*
* Similar to `collection.map(...).flatten(true)`.
*/
flatMap<KM, VM>(
mapper: (value: V, key: K, iter: this) => Iterable<[KM, VM]>,
context?: any
): Collection.Keyed<KM, VM>;
/**
* Returns a new Collection with only the values for which the `predicate`
* function returns true.
*
* Note: `filter()` always returns a new instance, even if it results in
* not filtering out any values.
*/
filter<F extends V>(
predicate: (value: V, key: K, iter: this) => value is F,
context?: any
): Collection.Keyed<K, F>;
filter(
predicate: (value: V, key: K, iter: this) => any,
context?: any
): this;
[Symbol.iterator](): IterableIterator<[K, V]>;
}
/**
* Indexed Collections have incrementing numeric keys. They exhibit
* slightly different behavior than `Collection.Keyed` for some methods in order
* to better mirror the behavior of JavaScript's `Array`, and add methods
* which do not make sense on non-indexed Collections such as `indexOf`.
*
* Unlike JavaScript arrays, `Collection.Indexed`s are always dense. "Unset"
* indices and `undefined` indices are indistinguishable, and all indices from
* 0 to `size` are visited when iterated.
*
* All Collection.Indexed methods return re-indexed Collections. In other words,
* indices always start at 0 and increment until size. If you wish to
* preserve indices, using them as keys, convert to a Collection.Keyed by
* calling `toKeyedSeq`.
*/
export module Indexed {}
/**
* Creates a new Collection.Indexed.
*
* Note: `Collection.Indexed` is a conversion function and not a class, and
* does not use the `new` keyword during construction.
*/
export function Indexed<T>(collection: Iterable<T>): Collection.Indexed<T>;
export interface Indexed<T> extends Collection<number, T> {
/**
* Deeply converts this Indexed collection to equivalent native JavaScript Array.
*/
toJS(): Array<any>;
/**
* Shallowly converts this Indexed collection to equivalent native JavaScript Array.