

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](https://flowtype.org/) or [TypeScript](https://www.typescriptlang.org/)). 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:

 
```
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:

 
```
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:

 
```
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:

 
```
class List<T> {
  push(value: T): this
}
```

Many methods in Immutable.js accept values which implement the JavaScript [Iterable](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols) protocol, and might appear like `[Iterable<string>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_iterable_protocol)` 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](getin()/index)` which expects an `[Iterable](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_iterable_protocol)` path:

 
```
getIn(path: Iterable<string | number>): unknown
```

To use this method, we could pass an array: `data.getIn([ "key", 2 ])`.

 Note: All examples are presented in the modern [ES2015](https://developer.mozilla.org/en-US/docs/Web/JavaScript/New_in_JavaScript/ECMAScript_6_support_in_Mozilla) version of JavaScript. Use tools like Babel to support older browsers.

 For example:

 
```
// ES2015
const mappedFoo = foo.map(x => x * x);
// ES5
var mappedFoo = foo.map(function (x) { return x * x; });
```


#### API


### [List](list/index)



Lists are ordered indexed dense collections, much like a JavaScript Array.

 
### [Map](map/index)



Immutable Map is an unordered Collection.Keyed of (key, value) pairs with `O(log32 N)` gets and `O(log32 N)` persistent sets.

 
### [OrderedMap](orderedmap/index)



A type of Map that has the additional guarantee that the iteration order of entries will be the order in which they were set().

 
### [Set](set/index)



A Collection of unique values with `O(log32 N)` adds and has.

 
### [OrderedSet](orderedset/index)



A type of Set that has the additional guarantee that the iteration order of values will be the order in which they were `[add](orderedset/index#add())`ed.

 
### [Stack](stack/index)



Stacks are indexed collections which support very efficient O(1) addition and removal from the front using `[unshift(v)](stack/index#unshift())` and `[shift()](stack/index#shift())`.

 
### [Range()](range()/index)



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.

 
### [Repeat()](repeat()/index)



Returns a Seq.Indexed of `value` repeated `times` times. When `times` is not defined, returns an infinite `[Seq](seq/index)` of `value`.

 
### [Record](record/index)



A record is similar to a JS object, but enforces a specific set of allowed string keys, and has default values.

 
### [Record.Factory](record.factory/index)



A Record.Factory is created by the `[Record()](record/index)` function. Record instances are created by passing it some of the accepted values for that Record type:

 
### [Seq](seq/index)



`[Seq](seq/index)` describes a lazy operation, allowing them to efficiently chain use of all the higher-order collection methods (such as `[map](seq/index#map())` and `[filter](seq/index#filter())`) by not creating intermediate collections.

 
### [Seq.Keyed](seq.keyed/index)



`[Seq](seq/index)` which represents key-value pairs.

 
### [Seq.Indexed](seq.indexed/index)



`[Seq](seq/index)` which represents an ordered indexed list of values.

 
### [Seq.Set](seq.set/index)



`[Seq](seq/index)` which represents a set of values.

 
### [Collection](collection/index)



The `[Collection](collection/index)` 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](collection/index#map())` and `[filter](collection/index#filter())`).

 
### [Collection.Keyed](collection.keyed/index)



Keyed Collections have discrete keys tied to each value.

 
### [Collection.Indexed](collection.indexed/index)



Indexed Collections have incrementing numeric keys. They exhibit slightly different behavior than `[Collection.Keyed](collection.keyed/index)` for some methods in order to better mirror the behavior of JavaScript's `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)`, and add methods which do not make sense on non-indexed Collections such as `[indexOf](collection.indexed/index#indexOf())`.

 
### [Collection.Set](collection.set/index)



Set Collections only represent values. They have no associated keys or indices. Duplicate values are possible in the lazy `[Seq.Set](seq.set/index)`s, however the concrete `[Set](set/index)` Collection does not allow duplicate values.

 
### [ValueObject](valueobject/index)


### [fromJS()](fromjs()/index)



Deeply converts plain JS objects and arrays to Immutable Maps and Lists.

 
### [is()](is()/index)



Value equality check with semantics similar to `[Object.is](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/is)`, but treats Immutable `[Collection](collection/index)`s as values, equal if the second `[Collection](collection/index)` includes equivalent values.

 
### [hash()](hash()/index)



The `[hash()](hash()/index)` function is an important part of how Immutable determines if two values are equivalent and is used to determine how to store those values. Provided with any value, `[hash()](hash()/index)` will return a 31-bit integer.

 
### [isImmutable()](isimmutable()/index)



True if `maybeImmutable` is an Immutable Collection or Record.

 
### [isCollection()](iscollection()/index)



True if `maybeCollection` is a Collection, or any of its subclasses.

 
### [isKeyed()](iskeyed()/index)



True if `maybeKeyed` is a Collection.Keyed, or any of its subclasses.

 
### [isIndexed()](isindexed()/index)



True if `maybeIndexed` is a Collection.Indexed, or any of its subclasses.

 
### [isAssociative()](isassociative()/index)



True if `maybeAssociative` is either a Keyed or Indexed Collection.

 
### [isOrdered()](isordered()/index)



True if `maybeOrdered` is a Collection where iteration order is well defined. True for Collection.Indexed as well as OrderedMap and OrderedSet.

 
### [isValueObject()](isvalueobject()/index)



True if `maybeValue` is a JavaScript Object which has *both* `equals()` and `hashCode()` methods.

 
### [isSeq()](isseq()/index)



True if `maybeSeq` is a Seq.

 
### [isList()](islist()/index)



True if `maybeList` is a List.

 
### [isMap()](ismap()/index)



True if `maybeMap` is a Map.

 
### [isOrderedMap()](isorderedmap()/index)



True if `maybeOrderedMap` is an OrderedMap.

 
### [isStack()](isstack()/index)



True if `maybeStack` is a Stack.

 
### [isSet()](isset()/index)



True if `maybeSet` is a Set.

 
### [isOrderedSet()](isorderedset()/index)



True if `maybeOrderedSet` is an OrderedSet.

 
### [isRecord()](isrecord()/index)



True if `maybeRecord` is a Record.

 
### [get()](get()/index)


### [has()](has()/index)



Returns true if the key is defined in the provided collection.

 
### [remove()](remove()/index)


### [set()](set()/index)


### [update()](update()/index)


### [getIn()](getin()/index)



Returns the value at the provided key path starting at the provided collection, or notSetValue if the key path is not defined.

 
### [hasIn()](hasin()/index)



Returns true if the key path is defined in the provided collection.

 
### [removeIn()](removein()/index)



Returns a copy of the collection with the value at the key path removed.

 
### [setIn()](setin()/index)



Returns a copy of the collection with the value at the key path set to the provided value.

 
### [updateIn()](updatein()/index)


### [merge()](merge()/index)



Returns a copy of the collection with the remaining collections merged in.

 
### [mergeWith()](mergewith()/index)



Returns a copy of the collection with the remaining collections merged in, calling the `merger` function whenever an existing value is encountered.

 
### [mergeDeep()](mergedeep()/index)



Like `[merge()](merge()/index)`, but when two compatible collections are encountered with the same key, it merges them as well, recursing deeply through the nested data. Two collections are considered to be compatible (and thus will be merged together) if they both fall into one of three categories: keyed (e.g., `[Map](map/index)`s, `[Record](record/index)`s, and objects), indexed (e.g., `[List](list/index)`s and arrays), or set-like (e.g., `[Set](set/index)`s). If they fall into separate categories, `[mergeDeep](mergedeep()/index)` will replace the existing collection with the collection being merged in. This behavior can be customized by using `[mergeDeepWith()](mergedeepwith()/index)`.

 
### [mergeDeepWith()](mergedeepwith()/index)



Like `[mergeDeep()](mergedeep()/index)`, but when two non-collections or incompatible collections are encountered at the same key, it uses the `merger` function to determine the resulting value. Collections are considered incompatible if they fall into separate categories between keyed, indexed, and set-like.

 

 © 2014–present, Lee Byron and other contributors  
Licensed under the 3-clause BSD License.  

<https://immutable-js.com/docs/v4.2.1/>

getIn()
=======



Returns the value at the provided key path starting at the provided collection, or notSetValue if the key path is not defined.

 

```
getIn(collection: unknown,keyPath: Iterable<unknown>,notSetValue?: unknown): unknown

```

#### Discussion



A functional alternative to `collection.getIn(keypath)` which will also work with plain Objects and Arrays.

 
```
const { getIn } = require('immutable')
getIn({ x: { y: { z: 123 }}}, ['x', 'y', 'z']) // 123
getIn({ x: { y: { z: 123 }}}, ['x', 'q', 'p'], 'ifNotSet') // 'ifNotSet'run it
```

This documentation is generated from [immutable.d.ts](https://github.com/immutable-js/immutable-js/blob/main/type-definitions/immutable.d.ts). Pull requests and [Issues](https://github.com/immutable-js/immutable-js/issues) welcome.

 © 2014–present, Lee Byron and other contributors  
Licensed under the 3-clause BSD License.  

<https://immutable-js.com/docs/v4.2.1/getIn()/>

Repeat()
========



Returns a Seq.Indexed of `value` repeated `times` times. When `times` is not defined, returns an infinite `[Seq](../seq/index)` of `value`.

 

```
Repeat<T>(value: T, times?: number): Seq.Indexed<T>

```

#### Discussion



Note: `[Repeat](index)` is a factory function and not a class, and does not use the `new` keyword during construction.

 
```
const { Repeat } = require('immutable')
Repeat('foo') // [ 'foo', 'foo', 'foo', ... ]
Repeat('bar', 4) // [ 'bar', 'bar', 'bar', 'bar' ]
```

This documentation is generated from [immutable.d.ts](https://github.com/immutable-js/immutable-js/blob/main/type-definitions/immutable.d.ts). Pull requests and [Issues](https://github.com/immutable-js/immutable-js/issues) welcome.

 © 2014–present, Lee Byron and other contributors  
Licensed under the 3-clause BSD License.  

<https://immutable-js.com/docs/v4.2.1/Repeat()/>

Range()
=======



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.

 

```
Range(start?: number, end?: number, step?: number): Seq.Indexed<number>

```

#### Discussion



Note: `[Range](index)` is a factory function and not a class, and does not use the `new` keyword during construction.

 
```
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) // []
```

This documentation is generated from [immutable.d.ts](https://github.com/immutable-js/immutable-js/blob/main/type-definitions/immutable.d.ts). Pull requests and [Issues](https://github.com/immutable-js/immutable-js/issues) welcome.

 © 2014–present, Lee Byron and other contributors  
Licensed under the 3-clause BSD License.  

<https://immutable-js.com/docs/v4.2.1/Range()/>

fromJS()
========



Deeply converts plain JS objects and arrays to Immutable Maps and Lists.

 

```
fromJS(jsValue: unknown,reviver?: (key: string | number,sequence: Collection.Keyed<string, unknown> | Collection.Indexed<unknown>,path?: Array<string | number>) => unknown): Collection<unknown, unknown>

```

#### Discussion



`[fromJS](index)` will convert Arrays and [array-like objects](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Indexed_collections#working_with_array-like_objects "Working with array-like objects") to a List, and plain objects (without a custom prototype) to a Map. [Iterable objects](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_iterable_protocol "The iterable protocol") may be converted to List, Map, or Set.

 If a `reviver` is optionally provided, it will be called with every collection as a Seq (beginning with the most nested collections and proceeding to the top-level collection itself), along with the key referring to each collection and the parent JS object provided as `this`. For the top level, object, the key will be `""`. This `reviver` is expected to return a new Immutable Collection, allowing for custom conversions from deep JS objects. Finally, a `path` is provided which is the sequence of keys to this value from the starting value.

 `reviver` acts similarly to the [same parameter in `[JSON.parse](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse)`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse#Example.3A_Using_the_reviver_parameter "Using the reviver parameter").

 If `reviver` is not provided, the default behavior will convert Objects into Maps and Arrays into Lists like so:

 
```
const { fromJS, isKeyed } = require('immutable')
function (key, value) {
  return isKeyed(value) ? value.toMap() : value.toList()
}run it
```

Accordingly, this example converts native JS data to OrderedMap and List:

 
```
const { fromJS, isKeyed } = require('immutable')
fromJS({ a: {b: [10, 20, 30]}, c: 40}, function (key, value, path) {
  console.log(key, value, path)
  return isKeyed(value) ? value.toOrderedMap() : value.toList()
})

> "b", [ 10, 20, 30 ], [ "a", "b" ]
> "a", {b: [10, 20, 30]}, [ "a" ]
> "", {a: {b: [10, 20, 30]}, c: 40}, []run it
```

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.

 
```
const { Map } = require('immutable')
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" !== undefinedrun it
```

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()](../get()/index)` is not altered.

 This documentation is generated from [immutable.d.ts](https://github.com/immutable-js/immutable-js/blob/main/type-definitions/immutable.d.ts). Pull requests and [Issues](https://github.com/immutable-js/immutable-js/issues) welcome.

 © 2014–present, Lee Byron and other contributors  
Licensed under the 3-clause BSD License.  

<https://immutable-js.com/docs/v4.2.1/fromJS()/>

Record.Factory
==============



A Record.Factory is created by the `[Record()](../record/index)` function. Record instances are created by passing it some of the accepted values for that Record type:

 

```
type Record.Factory<TProps>
```

#### Discussion


 
```
// makePerson is a Record Factory function
const makePerson = Record({ name: null, favoriteColor: 'unknown' });

// alan is a Record instance
const alan = makePerson({ name: 'Alan' });run it
```

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:

 
```
// Use the Record API
console.log('Record API: ' + alan.get('name'))

// Or direct property access (Readonly)
console.log('property access: ' + alan.name)run it
```

**Flow Typing Records:**

 Use the `RecordFactory<TProps>` Flow type to get high quality type checking of Records:

 
```
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' });
```


### Construction



#### [Record.Factory()](index#Record.Factory())



```
Record.Factory<TProps>(values?: Partial<TProps> | Iterable<[string, unknown]>): Record<TProps> & Readonly<TProps>

```


### Members



#### [displayName](index#displayName)




The name provided to `Record(values, name)` can be accessed with `[displayName](index#displayName)`.

 

```
displayName: string
```


This documentation is generated from [immutable.d.ts](https://github.com/immutable-js/immutable-js/blob/main/type-definitions/immutable.d.ts). Pull requests and [Issues](https://github.com/immutable-js/immutable-js/issues) welcome.

 © 2014–present, Lee Byron and other contributors  
Licensed under the 3-clause BSD License.  

<https://immutable-js.com/docs/v4.2.1/Record.Factory/>

ValueObject
===========



```
type ValueObject
```

### Members



#### [equals()](index#equals())




True if this and the other Collection have value equality, as defined by `[Immutable.is()](../is()/index)`.

 

```
equals(other: unknown): boolean

```

#### Discussion



Note: This is equivalent to `Immutable.is(this, other)`, but provided to allow for chained expressions.

 



#### [hashCode()](index#hashCode())




Computes and returns the hashed identity for this Collection.

 

```
hashCode(): number

```

#### Discussion



The `[hashCode](index#hashCode())` of a Collection is used to determine potential equality, and is used when adding this to a `[Set](../set/index)` or as a key in a `[Map](../map/index)`, enabling lookup via a different instance.

 
```
const { List, Set } = require('immutable');
const a = List([ 1, 2, 3 ]);
const b = List([ 1, 2, 3 ]);
assert.notStrictEqual(a, b); // different instances
const set = Set([ a ]);
assert.equal(set.has(b), true);run it
```

Note: hashCode() MUST return a Uint32 number. The easiest way to guarantee this is to return `myHash | 0` from a custom implementation.

 If two values have the same `[hashCode](index#hashCode())`, they are [not guaranteed to be equal](https://en.wikipedia.org/wiki/Collision_(computer_science)). If two values have different `[hashCode](index#hashCode())`s, they must not be equal.

 Note: `[hashCode()](index#hashCode())` is not guaranteed to always be called before `[equals()](index#equals())`. Most but not all Immutable.js collections use hash codes to organize their internal data structures, while all Immutable.js collections use equality during lookups.

 

This documentation is generated from [immutable.d.ts](https://github.com/immutable-js/immutable-js/blob/main/type-definitions/immutable.d.ts). Pull requests and [Issues](https://github.com/immutable-js/immutable-js/issues) welcome.

 © 2014–present, Lee Byron and other contributors  
Licensed under the 3-clause BSD License.  

<https://immutable-js.com/docs/v4.2.1/ValueObject/>

hash()
======



The `[hash()](index)` function is an important part of how Immutable determines if two values are equivalent and is used to determine how to store those values. Provided with any value, `[hash()](index)` will return a 31-bit integer.

 

```
hash(value: unknown): number

```

#### Discussion



When designing Objects which may be equal, it's important that when a `.equals()` method returns true, that both values `.hashCode()` method return the same value. `[hash()](index)` may be used to produce those values.

 For non-Immutable Objects that do not provide a `.hashCode()` functions (including plain Objects, plain Arrays, Date objects, etc), a unique hash value will be created for each *instance*. That is, the create hash represents referential equality, and not value equality for Objects. This ensures that if that Object is mutated over time that its hash code will remain consistent, allowing Objects to be used as keys and values in Immutable.js collections.

 Note that `[hash()](index)` attempts to balance between speed and avoiding collisions, however it makes no attempt to produce secure hashes.

 *New in Version 4.0*

 This documentation is generated from [immutable.d.ts](https://github.com/immutable-js/immutable-js/blob/main/type-definitions/immutable.d.ts). Pull requests and [Issues](https://github.com/immutable-js/immutable-js/issues) welcome.

 © 2014–present, Lee Byron and other contributors  
Licensed under the 3-clause BSD License.  

<https://immutable-js.com/docs/v4.2.1/hash()/>

Record
======



A record is similar to a JS object, but enforces a specific set of allowed string keys, and has default values.

 

```
type Record<TProps>
```

#### Discussion



The `[Record()](index)` function produces new Record Factories, which when called create Record instances.

 
```
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](../remove()/index)`ing a key from a record simply resets it to the default value for that key.

 
```
myRecord.get('a') // 1
myRecord.get('b') // 3
const myRecordWithoutB = myRecord.remove('b')
myRecordWithoutB.get('b') // 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.

 
```
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()](index#get())` when supporting IE8.

 
```
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.

 
```
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:

 
```
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()](index#getIn())` and `[setIn()](index#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()](../is()/index)` 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](../map/index)` or values in a `[Set](../set/index)`, 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.

 
### Construction



#### [Record()](index#Record())




Unlike other types in Immutable.js, the `[Record()](index)` function creates a new Record Factory, which is a function that creates Record instances.

 

```
Record<TProps>(defaultValues: TProps, name?: string): Record.Factory<TProps>

```

#### Discussion



See above for examples of using `[Record()](index)`.

 Note: `[Record](index)` is a factory function and not a class, and does not use the `new` keyword during construction.

 


### Static methods



#### [Record.isRecord()](index#isRecord())



```
Record.isRecord(maybeRecord: unknown): boolean

```



#### [Record.getDescriptiveName()](index#getDescriptiveName())



```
Record.getDescriptiveName(record: Record<any>): string

```


### Reading values



#### [has()](index#has())



```
has(key: string): boolean

```



#### [get()](index#get())



```
get<K>(key: K, notSetValue?: unknown): TProps,[K]
get<T>(key: string, notSetValue: T): T

```


### Reading deep values



#### [hasIn()](index#hasIn())



```
hasIn(keyPath: Iterable<unknown>): boolean

```



#### [getIn()](index#getIn())



```
getIn(keyPath: Iterable<unknown>): unknown

```


### Value equality



#### [equals()](index#equals())



```
equals(other: unknown): boolean

```



#### [hashCode()](index#hashCode())



```
hashCode(): number

```


### Persistent changes



#### [set()](index#set())



```
set<K>(key: K, value: TProps,[K]): this

```



#### [update()](index#update())



```
update<K>(key: K, updater: (value: TProps,[K]) => TProps,[K]): this

```



#### [merge()](index#merge())



```
merge(...collections: Array<Partial<TProps> | Iterable<[string, unknown]>>): this

```



#### [mergeDeep()](index#mergeDeep())



```
mergeDeep(...collections: Array<Partial<TProps> | Iterable<[string, unknown]>>): this

```



#### [mergeWith()](index#mergeWith())



```
mergeWith(merger: (oldVal: unknown, newVal: unknown, key: keyof TProps) => unknown,...collections: Array<Partial<TProps> | Iterable<[string, unknown]>>): this

```



#### [mergeDeepWith()](index#mergeDeepWith())



```
mergeDeepWith(merger: (oldVal: unknown, newVal: unknown, key: unknown) => unknown,...collections: Array<Partial<TProps> | Iterable<[string, unknown]>>): this

```



#### [delete()](index#delete())




Returns a new instance of this Record type with the value for the specific key set to its default value.

 

```
delete<K>(key: K): this

```

#### alias


`remove()`



#### [clear()](index#clear())




Returns a new instance of this Record type with all values set to their default values.

 

```
clear(): this

```



### Deep persistent changes



#### [setIn()](index#setIn())



```
setIn(keyPath: Iterable<unknown>, value: unknown): this

```



#### [updateIn()](index#updateIn())



```
updateIn(keyPath: Iterable<unknown>, updater: (value: unknown) => unknown): this

```



#### [mergeIn()](index#mergeIn())



```
mergeIn(keyPath: Iterable<unknown>, ...collections: Array<unknown>): this

```



#### [mergeDeepIn()](index#mergeDeepIn())



```
mergeDeepIn(keyPath: Iterable<unknown>, ...collections: Array<unknown>): this

```



#### [deleteIn()](index#deleteIn())




```
deleteIn(keyPath: Iterable<unknown>): this

```

#### alias


`removeIn()`


### Conversion to JavaScript types



#### [toJS()](index#toJS())




Deeply converts this Record to equivalent native JavaScript Object.

 

```
toJS(): DeepCopy<TProps>

```

#### Discussion



Note: This method may not be overridden. Objects with custom serialization to plain JS may override toJSON() instead.

 



#### [toJSON()](index#toJSON())




Shallowly converts this Record to equivalent native JavaScript Object.

 

```
toJSON(): TProps

```




#### [toObject()](index#toObject())




Shallowly converts this Record to equivalent JavaScript Object.

 

```
toObject(): TProps

```



### Transient changes



#### [withMutations()](index#withMutations())




Note: Not all methods can be used on a mutable collection or within `[withMutations](index#withMutations())`! Only `[set](index#set())` may be used mutatively.

 

```
withMutations(mutator: (mutable: this) => unknown): this

```

#### see



`[Map#withMutations](../map/index#withMutations())`

 



#### [asMutable()](index#asMutable())




```
asMutable(): this

```

#### see



`[Map#asMutable](../map/index#asMutable())`

 



#### [wasAltered()](index#wasAltered())




```
wasAltered(): boolean

```

#### see



`[Map#wasAltered](../map/index#wasAltered())`

 



#### [asImmutable()](index#asImmutable())




```
asImmutable(): this

```

#### see



`[Map#asImmutable](../map/index#asImmutable())`

 


### Sequence algorithms



#### [toSeq()](index#toSeq())



```
toSeq(): Seq.Keyed<keyof TProps, TProps,[keyof TProps]>

```



#### [[Symbol.iterator]()](index#%5BSymbol.iterator%5D())



```
[Symbol.iterator](): IterableIterator<[keyof TProps, TProps,[keyof TProps]]>

```

This documentation is generated from [immutable.d.ts](https://github.com/immutable-js/immutable-js/blob/main/type-definitions/immutable.d.ts). Pull requests and [Issues](https://github.com/immutable-js/immutable-js/issues) welcome.

 © 2014–present, Lee Byron and other contributors  
Licensed under the 3-clause BSD License.  

<https://immutable-js.com/docs/v4.2.1/Record/>

isKeyed()
=========



True if `maybeKeyed` is a Collection.Keyed, or any of its subclasses.

 

```
isKeyed(maybeKeyed: unknown): boolean

```

#### Discussion


 
```
const { isKeyed, Map, List, Stack } = require('immutable');
isKeyed([]); // false
isKeyed({}); // false
isKeyed(Map()); // true
isKeyed(List()); // false
isKeyed(Stack()); // falserun it
```

This documentation is generated from [immutable.d.ts](https://github.com/immutable-js/immutable-js/blob/main/type-definitions/immutable.d.ts). Pull requests and [Issues](https://github.com/immutable-js/immutable-js/issues) welcome.

 © 2014–present, Lee Byron and other contributors  
Licensed under the 3-clause BSD License.  

<https://immutable-js.com/docs/v4.2.1/isKeyed()/>

is()
====



Value equality check with semantics similar to `[Object.is](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/is)`, but treats Immutable `[Collection](../collection/index)`s as values, equal if the second `[Collection](../collection/index)` includes equivalent values.

 

```
is(first: unknown, second: unknown): boolean

```

#### Discussion



It's used throughout Immutable when checking for equality, including `[Map](../map/index)` key equality and `[Set](../set/index)` membership.

 
```
const { Map, is } = require('immutable')
const map1 = Map({ a: 1, b: 1, c: 1 })
const map2 = Map({ a: 1, b: 1, c: 1 })
assert.equal(map1 !== map2, true)
assert.equal(Object.is(map1, map2), false)
assert.equal(is(map1, map2), true)run it
```

`[is()](index)` compares primitive types like strings and numbers, Immutable.js collections like `[Map](../map/index)` and `[List](../list/index)`, but also any custom object which implements `[ValueObject](../valueobject/index)` by providing `equals()` and `hashCode()` methods.

 Note: Unlike `[Object.is](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/is)`, `[Immutable.is](index)` assumes `0` and `-0` are the same value, matching the behavior of ES6 Map key equality.

 This documentation is generated from [immutable.d.ts](https://github.com/immutable-js/immutable-js/blob/main/type-definitions/immutable.d.ts). Pull requests and [Issues](https://github.com/immutable-js/immutable-js/issues) welcome.

 © 2014–present, Lee Byron and other contributors  
Licensed under the 3-clause BSD License.  

<https://immutable-js.com/docs/v4.2.1/is()/>

isImmutable()
=============



True if `maybeImmutable` is an Immutable Collection or Record.

 

```
isImmutable(maybeImmutable: unknown): boolean

```

#### Discussion



Note: Still returns true even if the collections is within a `withMutations()`.

 
```
const { isImmutable, Map, List, Stack } = require('immutable');
isImmutable([]); // false
isImmutable({}); // false
isImmutable(Map()); // true
isImmutable(List()); // true
isImmutable(Stack()); // true
isImmutable(Map().asMutable()); // truerun it
```

This documentation is generated from [immutable.d.ts](https://github.com/immutable-js/immutable-js/blob/main/type-definitions/immutable.d.ts). Pull requests and [Issues](https://github.com/immutable-js/immutable-js/issues) welcome.

 © 2014–present, Lee Byron and other contributors  
Licensed under the 3-clause BSD License.  

<https://immutable-js.com/docs/v4.2.1/isImmutable()/>

isCollection()
==============



True if `maybeCollection` is a Collection, or any of its subclasses.

 

```
isCollection(maybeCollection: unknown): boolean

```

#### Discussion


 
```
const { isCollection, Map, List, Stack } = require('immutable');
isCollection([]); // false
isCollection({}); // false
isCollection(Map()); // true
isCollection(List()); // true
isCollection(Stack()); // truerun it
```

This documentation is generated from [immutable.d.ts](https://github.com/immutable-js/immutable-js/blob/main/type-definitions/immutable.d.ts). Pull requests and [Issues](https://github.com/immutable-js/immutable-js/issues) welcome.

 © 2014–present, Lee Byron and other contributors  
Licensed under the 3-clause BSD License.  

<https://immutable-js.com/docs/v4.2.1/isCollection()/>

isSeq()
=======



True if `maybeSeq` is a Seq.

 

```
isSeq(maybeSeq: unknown): boolean

```
This documentation is generated from [immutable.d.ts](https://github.com/immutable-js/immutable-js/blob/main/type-definitions/immutable.d.ts). Pull requests and [Issues](https://github.com/immutable-js/immutable-js/issues) welcome.

 © 2014–present, Lee Byron and other contributors  
Licensed under the 3-clause BSD License.  

<https://immutable-js.com/docs/v4.2.1/isSeq()/>

isIndexed()
===========



True if `maybeIndexed` is a Collection.Indexed, or any of its subclasses.

 

```
isIndexed(maybeIndexed: unknown): boolean

```

#### Discussion


 
```
const { isIndexed, Map, List, Stack, Set } = require('immutable');
isIndexed([]); // false
isIndexed({}); // false
isIndexed(Map()); // false
isIndexed(List()); // true
isIndexed(Stack()); // true
isIndexed(Set()); // falserun it
```

This documentation is generated from [immutable.d.ts](https://github.com/immutable-js/immutable-js/blob/main/type-definitions/immutable.d.ts). Pull requests and [Issues](https://github.com/immutable-js/immutable-js/issues) welcome.

 © 2014–present, Lee Byron and other contributors  
Licensed under the 3-clause BSD License.  

<https://immutable-js.com/docs/v4.2.1/isIndexed()/>

isValueObject()
===============



True if `maybeValue` is a JavaScript Object which has *both* `equals()` and `hashCode()` methods.

 

```
isValueObject(maybeValue: unknown): boolean

```

#### Discussion



Any two instances of *value objects* can be compared for value equality with `[Immutable.is()](../is()/index)` and can be used as keys in a `[Map](../map/index)` or members in a `[Set](../set/index)`.

 This documentation is generated from [immutable.d.ts](https://github.com/immutable-js/immutable-js/blob/main/type-definitions/immutable.d.ts). Pull requests and [Issues](https://github.com/immutable-js/immutable-js/issues) welcome.

 © 2014–present, Lee Byron and other contributors  
Licensed under the 3-clause BSD License.  

<https://immutable-js.com/docs/v4.2.1/isValueObject()/>

isList()
========



True if `maybeList` is a List.

 

```
isList(maybeList: unknown): boolean

```
This documentation is generated from [immutable.d.ts](https://github.com/immutable-js/immutable-js/blob/main/type-definitions/immutable.d.ts). Pull requests and [Issues](https://github.com/immutable-js/immutable-js/issues) welcome.

 © 2014–present, Lee Byron and other contributors  
Licensed under the 3-clause BSD License.  

<https://immutable-js.com/docs/v4.2.1/isList()/>

OrderedMap
==========



A type of Map that has the additional guarantee that the iteration order of entries will be the order in which they were set().

 

```
type OrderedMap<K, V> extends Map<K, V>
```

#### Discussion



The iteration behavior of OrderedMap is the same as native ES6 Map and JavaScript Object.

 Note that `[OrderedMap](index)` are more expensive than non-ordered `[Map](../map/index)` and may consume more memory. `[OrderedMap#set](index#set())` is amortized O(log32 N), but not stable.

 
### Construction



#### [OrderedMap()](index#OrderedMap())



```
OrderedMap<K, V>(collection?: Iterable<[K, V]>): OrderedMap<K, V>
OrderedMap<V>(obj: {[key: string]: V}): OrderedMap<string, V>

```


### Static methods



#### [OrderedMap.isOrderedMap()](index#isOrderedMap())



```
OrderedMap.isOrderedMap(maybeOrderedMap: unknown): boolean

```


### Members



#### [size](index#size)




The number of entries in this OrderedMap.

 

```
size: number
```

#### Overrides


`[Map#size](../map/index#size)`


### Persistent changes



#### [set()](index#set())




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.

 

```
set(key: K, value: V): this

```

#### Overrides


`[Map#set()](../map/index#set())`#### Discussion


 
```
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}run it
```

Note: `[set](index#set())` can be used in `[withMutations](index#withMutations())`.

 



#### [merge()](index#merge())




```
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>

```

#### Overrides


`[Map#merge()](../map/index#merge())`



#### [delete()](index#delete())




Returns a new Map which excludes this `key`.

 

```
delete(key: K): this

```

#### Inherited from


`[Map#delete()](../map/index#delete())`#### alias


`remove()`#### Discussion



Note: `[delete](../map/index#delete())` cannot be safely used in IE8, but is provided to mirror the ES6 collection API.

 
```
const { Map } = require('immutable')
const originalMap = Map({
  key: 'value',
  otherKey: 'other value'
})
// Map { "key": "value", "otherKey": "other value" }
originalMap.delete('otherKey')
// Map { "key": "value" }run it
```

Note: `[delete](../map/index#delete())` can be used in `[withMutations](../map/index#withMutations())`.

 



#### [deleteAll()](index#deleteAll())




Returns a new Map which excludes the provided `keys`.

 

```
deleteAll(keys: Iterable<K>): this

```

#### Inherited from


`[Map#deleteAll()](../map/index#deleteAll())`#### alias


`removeAll()`#### Discussion


 
```
const { Map } = require('immutable')
const names = Map({ a: "Aaron", b: "Barry", c: "Connor" })
names.deleteAll([ 'a', 'c' ])
// Map { "b": "Barry" }run it
```



Note: `[deleteAll](../map/index#deleteAll())` can be used in `[withMutations](../map/index#withMutations())`.

 



#### [clear()](index#clear())




Returns a new Map containing no keys or values.

 

```
clear(): this

```

#### Inherited from


`[Map#clear()](../map/index#clear())`#### Discussion


 
```
const { Map } = require('immutable')
Map({ key: 'value' }).clear()
// Map {}run it
```



Note: `[clear](../map/index#clear())` can be used in `[withMutations](../map/index#withMutations())`.

 



#### [update()](index#update())




```
update(key: K, notSetValue: V, updater: (value: V) => V): this
update(key: K, updater: (value: V | undefined) => V): this
update<R>(updater: (value: this) => R): R

```

#### Inherited from


`[Map#update()](../map/index#update())`



#### [mergeWith()](index#mergeWith())




Like `[merge()](../map/index#merge())`, `[mergeWith()](../map/index#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.

 

```
mergeWith(merger: (oldVal: V, newVal: V, key: K) => V,...collections: Array<Iterable<[K, V]> | {[key: string]: V}>): this

```

#### Inherited from


`[Map#mergeWith()](../map/index#mergeWith())`#### Discussion


 
```
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 }run it
```



Note: `[mergeWith](../map/index#mergeWith())` can be used in `[withMutations](../map/index#withMutations())`.

 



#### [mergeDeep()](index#mergeDeep())




Like `[merge()](../map/index#merge())`, but when two compatible collections are encountered with the same key, it merges them as well, recursing deeply through the nested data. Two collections are considered to be compatible (and thus will be merged together) if they both fall into one of three categories: keyed (e.g., `[Map](../map/index)`s, `[Record](../record/index)`s, and objects), indexed (e.g., `[List](../list/index)`s and arrays), or set-like (e.g., `[Set](../set/index)`s). If they fall into separate categories, `[mergeDeep](../map/index#mergeDeep())` will replace the existing collection with the collection being merged in. This behavior can be customized by using `[mergeDeepWith()](../map/index#mergeDeepWith())`.

 

```
mergeDeep(...collections: Array<Iterable<[K, V]> | {[key: string]: V}>): this

```

#### Inherited from


`[Map#mergeDeep()](../map/index#mergeDeep())`#### Discussion



Note: Indexed and set-like collections are merged using `[concat()](../map/index#concat())`/`union()` and therefore do not recurse.

 
```
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 }
// }run it
```

Note: `[mergeDeep](../map/index#mergeDeep())` can be used in `[withMutations](../map/index#withMutations())`.

 



#### [mergeDeepWith()](index#mergeDeepWith())




Like `[mergeDeep()](../map/index#mergeDeep())`, but when two non-collections or incompatible collections are encountered at the same key, it uses the `merger` function to determine the resulting value. Collections are considered incompatible if they fall into separate categories between keyed, indexed, and set-like.

 

```
mergeDeepWith(merger: (oldVal: unknown, newVal: unknown, key: unknown) => unknown,...collections: Array<Iterable<[K, V]> | {[key: string]: V}>): this

```

#### Inherited from


`[Map#mergeDeepWith()](../map/index#mergeDeepWith())`#### Discussion


 
```
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 }
// }run it
```



Note: `[mergeDeepWith](../map/index#mergeDeepWith())` can be used in `[withMutations](../map/index#withMutations())`.

 


### Sequence algorithms



#### [map()](index#map())




Returns a new OrderedMap with values passed through a `mapper` function.

 

```
map<M>(mapper: (value: V, key: K, iter: this) => M,context?: unknown): OrderedMap<K, M>

```

#### Overrides


`[Map#map()](../map/index#map())`#### Example




```
OrderedMap({ a: 1, b: 2 }).map(x => 10 * x)
// OrderedMap { "a": 10, "b": 20 }
```

Note: `[map()](index#map())` always returns a new instance, even if it produced the same value at every step.

 



#### [mapKeys()](index#mapKeys())




```
mapKeys<M>(mapper: (key: K, value: V, iter: this) => M,context?: unknown): OrderedMap<M, V>

```

#### Overrides


`[Map#mapKeys()](../map/index#mapKeys())`#### see



Collection.Keyed.mapKeys

 



#### [mapEntries()](index#mapEntries())




```
mapEntries<KM, VM>(mapper: (entry: [K, V], index: number, iter: this) => [KM, VM] | undefined,context?: unknown): OrderedMap<KM, VM>

```

#### Overrides


`[Map#mapEntries()](../map/index#mapEntries())`#### see



Collection.Keyed.mapEntries

 



#### [flatMap()](index#flatMap())




Flat-maps the OrderedMap, returning a new OrderedMap.

 

```
flatMap<KM, VM>(mapper: (value: V, key: K, iter: this) => Iterable<[KM, VM]>,context?: unknown): OrderedMap<KM, VM>

```

#### Overrides


`[Map#flatMap()](../map/index#flatMap())`#### Discussion



Similar to `data.map(...).flatten(true)`.

 



#### [filter()](index#filter())




```
filter<F>(predicate: (value: V, key: K, iter: this) => boolean,context?: unknown): OrderedMap<K, F>
filter(predicate: (value: V, key: K, iter: this) => unknown,context?: unknown): this

```

#### Overrides


`[Map#filter()](../map/index#filter())`



#### [partition()](index#partition())




```
partition<F, C>(predicate: (this: C, value: V, key: K, iter: this) => boolean,context?: C): [OrderedMap<K, V>, OrderedMap<K, F>]
partition<C>(predicate: (this: C, value: V, key: K, iter: this) => unknown,context?: C): [this, this]

```

#### Overrides


`[Map#partition()](../map/index#partition())`



#### [flip()](index#flip())




```
flip(): OrderedMap<V, K>

```

#### Overrides


`[Map#flip()](../map/index#flip())`#### see



Collection.Keyed.flip

 



#### [filterNot()](index#filterNot())




Returns a new Collection of the same type with only the entries for which the `predicate` function returns false.

 

```
filterNot(predicate: (value: V, key: K, iter: this) => boolean,context?: unknown): this

```

#### Inherited from


`[Collection#filterNot()](../collection/index#filterNot())`#### Discussion


 
```
const { Map } = require('immutable')
Map({ a: 1, b: 2, c: 3, d: 4}).filterNot(x => x % 2 === 0)
// Map { "a": 1, "c": 3 }run it
```



Note: `[filterNot()](../list/index#filterNot())` always returns a new instance, even if it results in not filtering out any values.

 



#### [reverse()](index#reverse())




Returns a new Collection of the same type in reverse order.

 

```
reverse(): this

```

#### Inherited from


`[Collection#reverse()](../collection/index#reverse())`



#### [sort()](index#sort())




Returns a new Collection of the same type which includes the same entries, stably sorted by using a `comparator`.

 

```
sort(comparator?: (valueA: V, valueB: V) => number): this

```

#### Inherited from


`[Collection#sort()](../collection/index#sort())`#### Discussion



If a `comparator` is not provided, a default comparator uses `<` and `>`.

 `comparator(valueA, valueB)`:

 * Returns `0` if the elements should not be swapped.
* Returns `-1` (or any negative number) if `valueA` comes before `valueB`
* Returns `1` (or any positive number) if `valueA` comes after `valueB`
* Is pure, i.e. it must always return the same value for the same pair of values.

 When sorting collections which have no defined order, their ordered equivalents will be returned. e.g. `map.sort()` returns OrderedMap.

 
```
const { Map } = require('immutable')
Map({ "c": 3, "a": 1, "b": 2 }).sort((a, b) => {
  if (a < b) { return -1; }
  if (a > b) { return 1; }
  if (a === b) { return 0; }
});
// OrderedMap { "a": 1, "b": 2, "c": 3 }run it
```

Note: `[sort()](../list/index#sort())` Always returns a new instance, even if the original was already sorted.

 Note: This is always an eager operation.

 



#### [sortBy()](index#sortBy())




Like `[sort](../list/index#sort())`, but also accepts a `comparatorValueMapper` which allows for sorting by more sophisticated means:

 

```
sortBy<C>(comparatorValueMapper: (value: V, key: K, iter: this) => C,comparator?: (valueA: C, valueB: C) => number): this

```

#### Inherited from


`[Collection#sortBy()](../collection/index#sortBy())`#### Discussion


 
```
const { Map } = require('immutable')
const beattles = Map({
  John: { name: "Lennon" },
  Paul: { name: "McCartney" },
  George: { name: "Harrison" },
  Ringo: { name: "Starr" },
});
beattles.sortBy(member => member.name);run it
```



Note: `[sortBy()](../list/index#sortBy())` Always returns a new instance, even if the original was already sorted.

 Note: This is always an eager operation.

 



#### [groupBy()](index#groupBy())




Returns a `[Collection.Keyed](../collection.keyed/index)` of `Collection.Keyeds`, grouped by the return value of the `grouper` function.

 

```
groupBy<G>(grouper: (value: V, key: K, iter: this) => G,context?: unknown): Seq.Keyed<G, Collection<K, V>>

```

#### Inherited from


`[Collection#groupBy()](../collection/index#groupBy())`#### Discussion



Note: This is always an eager operation.

 
```
const { List, Map } = require('immutable')
const listOfMaps = List([
  Map({ v: 0 }),
  Map({ v: 1 }),
  Map({ v: 1 }),
  Map({ v: 0 }),
  Map({ v: 2 })
])
const groupsOfMaps = listOfMaps.groupBy(x => x.get('v'))
// Map {
//   0: List [ Map{ "v": 0 }, Map { "v": 0 } ],
//   1: List [ Map{ "v": 1 }, Map { "v": 1 } ],
//   2: List [ Map{ "v": 2 } ],
// }run it
```




### Deep persistent changes



#### [setIn()](index#setIn())




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.

 

```
setIn(keyPath: Iterable<unknown>, value: unknown): this

```

#### Inherited from


`[Map#setIn()](../map/index#setIn())`#### Discussion


 
```
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!" } // } // }run it


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.

 
```
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" } // } // }run it


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](../map/index#setIn())` can be used in `[withMutations](../map/index#withMutations())`.

 



#### [deleteIn()](index#deleteIn())




Returns a new Map having removed the value at this `keyPath`. If any keys in `keyPath` do not exist, no change will occur.

 

```
deleteIn(keyPath: Iterable<unknown>): this

```

#### Inherited from


`[Map#deleteIn()](../map/index#deleteIn())`#### alias


`removeIn()`#### Discussion



Note: `[deleteIn](../map/index#deleteIn())` can be used in `[withMutations](../map/index#withMutations())`.

 



#### [updateIn()](index#updateIn())




```
updateIn(keyPath: Iterable<unknown>,notSetValue: unknown,updater: (value: unknown) => unknown): this
updateIn(keyPath: Iterable<unknown>, updater: (value: unknown) => unknown): this

```

#### Inherited from


`[Map#updateIn()](../map/index#updateIn())`



#### [mergeIn()](index#mergeIn())




A combination of `[updateIn](../map/index#updateIn())` and `[merge](../map/index#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:

 

```
mergeIn(keyPath: Iterable<unknown>, ...collections: Array<unknown>): this

```

#### Inherited from


`[Map#mergeIn()](../map/index#mergeIn())`#### Discussion




```
map.updateIn(['a', 'b', 'c'], abc => abc.merge(y))
map.mergeIn(['a', 'b', 'c'], y)
```



Note: `[mergeIn](../map/index#mergeIn())` can be used in `[withMutations](../map/index#withMutations())`.

 



#### [mergeDeepIn()](index#mergeDeepIn())




A combination of `[updateIn](../map/index#updateIn())` and `[mergeDeep](../map/index#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:

 

```
mergeDeepIn(keyPath: Iterable<unknown>, ...collections: Array<unknown>): this

```

#### Inherited from


`[Map#mergeDeepIn()](../map/index#mergeDeepIn())`#### Discussion




```
map.updateIn(['a', 'b', 'c'], abc => abc.mergeDeep(y))
map.mergeDeepIn(['a', 'b', 'c'], y)
```



Note: `[mergeDeepIn](../map/index#mergeDeepIn())` can be used in `[withMutations](../map/index#withMutations())`.

 


### Transient changes



#### [withMutations()](index#withMutations())




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.

 

```
withMutations(mutator: (mutable: this) => unknown): this

```

#### Inherited from


`[Map#withMutations()](../map/index#withMutations())`#### Discussion



If you need to apply a series of mutations to produce a new immutable Map, `[withMutations()](../map/index#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](../map/index#merge())` are done.

 As an example, this results in the creation of 2, not 4, new Maps:

 
```
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)run it
```

Note: Not all methods can be used on a mutable collection or within `[withMutations](../map/index#withMutations())`! Read the documentation for each method to see if it is safe to use in `[withMutations](../map/index#withMutations())`.

 



#### [asMutable()](index#asMutable())




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.

 

```
asMutable(): this

```

#### Inherited from


`[Map#asMutable()](../map/index#asMutable())`#### see



`[Map#asImmutable](../map/index#asImmutable())`

 
#### Discussion



If possible, use `[withMutations](../map/index#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](../map/index#asMutable())` returns itself.

 Note: Not all methods can be used on a mutable collection or within `[withMutations](../map/index#withMutations())`! Read the documentation for each method to see if it is safe to use in `[withMutations](../map/index#withMutations())`.

 



#### [wasAltered()](index#wasAltered())




Returns true if this is a mutable copy (see `[asMutable()](../map/index#asMutable())`) and mutative alterations have been applied.

 

```
wasAltered(): boolean

```

#### Inherited from


`[Map#wasAltered()](../map/index#wasAltered())`#### see



`[Map#asMutable](../map/index#asMutable())`

 



#### [asImmutable()](index#asImmutable())




The yin to `[asMutable](../map/index#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.

 

```
asImmutable(): this

```

#### Inherited from


`[Map#asImmutable()](../map/index#asImmutable())`#### see



`[Map#asMutable](../map/index#asMutable())`

 
#### Discussion



If possible, use `[withMutations](../map/index#withMutations())` to work with temporary mutable copies as it provides an easier to use API and considers many common optimizations.

 


### Conversion to JavaScript types



#### [toJS()](index#toJS())




Deeply converts this Keyed collection to equivalent native JavaScript Object.

 

```
toJS(): {[key: string]: DeepCopy<V>}

```

#### Inherited from


`[Collection.Keyed#toJS()](../collection.keyed/index#toJS())`#### Discussion



Converts keys to Strings.

 



#### [toJSON()](index#toJSON())




Shallowly converts this Keyed collection to equivalent native JavaScript Object.

 

```
toJSON(): {[key: string]: V}

```

#### Inherited from


`[Collection.Keyed#toJSON()](../collection.keyed/index#toJSON())`#### Discussion



Converts keys to Strings.

 



#### [toArray()](index#toArray())




Shallowly converts this collection to an Array.

 

```
toArray(): Array<[K, V]>

```

#### Inherited from


`[Collection.Keyed#toArray()](../collection.keyed/index#toArray())`



#### [toObject()](index#toObject())




Shallowly converts this Collection to an Object.

 

```
toObject(): {[key: string]: V}

```

#### Inherited from


`[Collection#toObject()](../collection/index#toObject())`#### Discussion



Converts keys to Strings.

 


### Conversion to Seq



#### [toSeq()](index#toSeq())




Returns Seq.Keyed.

 

```
toSeq(): Seq.Keyed<K, V>

```

#### Inherited from


`[Collection.Keyed#toSeq()](../collection.keyed/index#toSeq())`



#### [toKeyedSeq()](index#toKeyedSeq())




Returns a Seq.Keyed from this Collection where indices are treated as keys.

 

```
toKeyedSeq(): Seq.Keyed<K, V>

```

#### Inherited from


`[Collection#toKeyedSeq()](../collection/index#toKeyedSeq())`#### Discussion



This is useful if you want to operate on an Collection.Indexed and preserve the [index, value] pairs.

 The returned Seq will have identical iteration order as this Collection.

 
```
const { Seq } = require('immutable')
const indexedSeq = Seq([ 'A', 'B', 'C' ])
// Seq [ "A", "B", "C" ]
indexedSeq.filter(v => v === 'B')
// Seq [ "B" ]
const keyedSeq = indexedSeq.toKeyedSeq()
// Seq { 0: "A", 1: "B", 2: "C" }
keyedSeq.filter(v => v === 'B')
// Seq { 1: "B" }run it
```





#### [toIndexedSeq()](index#toIndexedSeq())




Returns an Seq.Indexed of the values of this Collection, discarding keys.

 

```
toIndexedSeq(): Seq.Indexed<V>

```

#### Inherited from


`[Collection#toIndexedSeq()](../collection/index#toIndexedSeq())`



#### [toSetSeq()](index#toSetSeq())




Returns a Seq.Set of the values of this Collection, discarding keys.

 

```
toSetSeq(): Seq.Set<V>

```

#### Inherited from


`[Collection#toSetSeq()](../collection/index#toSetSeq())`


### Sequence functions



#### [concat()](index#concat())




```
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>

```

#### Inherited from


`[Collection.Keyed#concat()](../collection.keyed/index#concat())`



#### [[Symbol.iterator]()](index#%5BSymbol.iterator%5D())




```
[Symbol.iterator](): IterableIterator<[K, V]>

```

#### Inherited from


`[Collection.Keyed#[Symbol.iterator]()](../collection.keyed/index#%5BSymbol.iterator%5D())`


### Value equality



#### [equals()](index#equals())




True if this and the other Collection have value equality, as defined by `[Immutable.is()](../is()/index)`.

 

```
equals(other: unknown): boolean

```

#### Inherited from


`[Collection#equals()](../collection/index#equals())`#### Discussion



Note: This is equivalent to `Immutable.is(this, other)`, but provided to allow for chained expressions.

 



#### [hashCode()](index#hashCode())




Computes and returns the hashed identity for this Collection.

 

```
hashCode(): number

```

#### Inherited from


`[Collection#hashCode()](../collection/index#hashCode())`#### Discussion



The `[hashCode](../list/index#hashCode())` of a Collection is used to determine potential equality, and is used when adding this to a `[Set](../set/index)` or as a key in a `[Map](../map/index)`, enabling lookup via a different instance.

 
```
const a = List([ 1, 2, 3 ]);
const b = List([ 1, 2, 3 ]);
assert.notStrictEqual(a, b); // different instances
const set = Set([ a ]);
assert.equal(set.has(b), true);run it
```

If two values have the same `[hashCode](../list/index#hashCode())`, they are [not guaranteed to be equal](https://en.wikipedia.org/wiki/Collision_(computer_science)). If two values have different `[hashCode](../list/index#hashCode())`s, they must not be equal.

 


### Reading values



#### [get()](index#get())




```
get<NSV>(key: K, notSetValue: NSV): V | NSV
get(key: K): V | undefined

```

#### Inherited from


`[Collection#get()](../collection/index#get())`



#### [has()](index#has())




True if a key exists within this `[Collection](../collection/index)`, using `[Immutable.is](../is()/index)` to determine equality

 

```
has(key: K): boolean

```

#### Inherited from


`[Collection#has()](../collection/index#has())`



#### [includes()](index#includes())




True if a value exists within this `[Collection](../collection/index)`, using `[Immutable.is](../is()/index)` to determine equality

 

```
includes(value: V): boolean

```

#### Inherited from


`[Collection#includes()](../collection/index#includes())`#### alias


`contains()`



#### [first()](index#first())




In case the `[Collection](../collection/index)` is not empty returns the first element of the `[Collection](../collection/index)`. In case the `[Collection](../collection/index)` is empty returns the optional default value if provided, if no default value is provided returns undefined.

 

```
first<NSV>(notSetValue?: NSV): V | NSV

```

#### Inherited from


`[Collection#first()](../collection/index#first())`



#### [last()](index#last())




In case the `[Collection](../collection/index)` is not empty returns the last element of the `[Collection](../collection/index)`. In case the `[Collection](../collection/index)` is empty returns the optional default value if provided, if no default value is provided returns undefined.

 

```
last<NSV>(notSetValue?: NSV): V | NSV

```

#### Inherited from


`[Collection#last()](../collection/index#last())`


### Reading deep values



#### [getIn()](index#getIn())




Returns the value found by following a path of keys or indices through nested Collections.

 

```
getIn(searchKeyPath: Iterable<unknown>, notSetValue?: unknown): unknown

```

#### Inherited from


`[Collection#getIn()](../collection/index#getIn())`#### Discussion


 
```
const { Map, List } = require('immutable')
const deepData = Map({ x: List([ Map({ y: 123 }) ]) });
deepData.getIn(['x', 0, 'y']) // 123run it
```



Plain JavaScript Object or Arrays may be nested within an Immutable.js Collection, and getIn() can access those values as well:

 
```
const { Map, List } = require('immutable')
const deepData = Map({ x: [ { y: 123 } ] });
deepData.getIn(['x', 0, 'y']) // 123run it
```


 



#### [hasIn()](index#hasIn())




True if the result of following a path of keys or indices through nested Collections results in a set value.

 

```
hasIn(searchKeyPath: Iterable<unknown>): boolean

```

#### Inherited from


`[Collection#hasIn()](../collection/index#hasIn())`


### Conversion to Collections



#### [toMap()](index#toMap())




Converts this Collection to a Map, Throws if keys are not hashable.

 

```
toMap(): Map<K, V>

```

#### Inherited from


`[Collection#toMap()](../collection/index#toMap())`#### Discussion



Note: This is equivalent to `Map(this.toKeyedSeq())`, but provided for convenience and to allow for chained expressions.

 



#### [toOrderedMap()](index#toOrderedMap())




Converts this Collection to a Map, maintaining the order of iteration.

 

```
toOrderedMap(): OrderedMap<K, V>

```

#### Inherited from


`[Collection#toOrderedMap()](../collection/index#toOrderedMap())`#### Discussion



Note: This is equivalent to `OrderedMap(this.toKeyedSeq())`, but provided for convenience and to allow for chained expressions.

 



#### [toSet()](index#toSet())




Converts this Collection to a Set, discarding keys. Throws if values are not hashable.

 

```
toSet(): Set<V>

```

#### Inherited from


`[Collection#toSet()](../collection/index#toSet())`#### Discussion



Note: This is equivalent to `[Set(this)](../set/index)`, but provided to allow for chained expressions.

 



#### [toOrderedSet()](index#toOrderedSet())




Converts this Collection to a Set, maintaining the order of iteration and discarding keys.

 

```
toOrderedSet(): OrderedSet<V>

```

#### Inherited from


`[Collection#toOrderedSet()](../collection/index#toOrderedSet())`#### Discussion



Note: This is equivalent to `OrderedSet(this.valueSeq())`, but provided for convenience and to allow for chained expressions.

 



#### [toList()](index#toList())




Converts this Collection to a List, discarding keys.

 

```
toList(): List<V>

```

#### Inherited from


`[Collection#toList()](../collection/index#toList())`#### Discussion



This is similar to `[List(collection)](../list/index)`, but provided to allow for chained expressions. However, when called on `[Map](../map/index)` or other keyed collections, `collection.toList()` discards the keys and creates a list of only the values, whereas `[List(collection)](../list/index)` creates a list of entry tuples.

 
```
const { Map, List } = require('immutable')
var myMap = Map({ a: 'Apple', b: 'Banana' })
List(myMap) // List [ [ "a", "Apple" ], [ "b", "Banana" ] ]
myMap.toList() // List [ "Apple", "Banana" ]run it
```





#### [toStack()](index#toStack())




Converts this Collection to a Stack, discarding keys. Throws if values are not hashable.

 

```
toStack(): Stack<V>

```

#### Inherited from


`[Collection#toStack()](../collection/index#toStack())`#### Discussion



Note: This is equivalent to `[Stack(this)](../stack/index)`, but provided to allow for chained expressions.

 


### Iterators



#### [keys()](index#keys())




An iterator of this `[Collection](../collection/index)`'s keys.

 

```
keys(): IterableIterator<K>

```

#### Inherited from


`[Collection#keys()](../collection/index#keys())`#### Discussion



Note: this will return an ES6 iterator which does not support Immutable.js sequence algorithms. Use `[keySeq](../list/index#keySeq())` instead, if this is what you want.

 



#### [values()](index#values())




An iterator of this `[Collection](../collection/index)`'s values.

 

```
values(): IterableIterator<V>

```

#### Inherited from


`[Collection#values()](../collection/index#values())`#### Discussion



Note: this will return an ES6 iterator which does not support Immutable.js sequence algorithms. Use `[valueSeq](../list/index#valueSeq())` instead, if this is what you want.

 



#### [entries()](index#entries())




An iterator of this `[Collection](../collection/index)`'s entries as `[ key, value ]` tuples.

 

```
entries(): IterableIterator<[K, V]>

```

#### Inherited from


`[Collection#entries()](../collection/index#entries())`#### Discussion



Note: this will return an ES6 iterator which does not support Immutable.js sequence algorithms. Use `[entrySeq](../list/index#entrySeq())` instead, if this is what you want.

 


### Collections (Seq)



#### [keySeq()](index#keySeq())




Returns a new Seq.Indexed of the keys of this Collection, discarding values.

 

```
keySeq(): Seq.Indexed<K>

```

#### Inherited from


`[Collection#keySeq()](../collection/index#keySeq())`



#### [valueSeq()](index#valueSeq())




Returns an Seq.Indexed of the values of this Collection, discarding keys.

 

```
valueSeq(): Seq.Indexed<V>

```

#### Inherited from


`[Collection#valueSeq()](../collection/index#valueSeq())`



#### [entrySeq()](index#entrySeq())




Returns a new Seq.Indexed of [key, value] tuples.

 

```
entrySeq(): Seq.Indexed<[K, V]>

```

#### Inherited from


`[Collection#entrySeq()](../collection/index#entrySeq())`


### Side effects



#### [forEach()](index#forEach())




The `sideEffect` is executed for every entry in the Collection.

 

```
forEach(sideEffect: (value: V, key: K, iter: this) => unknown,context?: unknown): number

```

#### Inherited from


`[Collection#forEach()](../collection/index#forEach())`#### Discussion



Unlike `[Array#forEach](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/forEach)`, if any call of `sideEffect` returns `false`, the iteration will stop. Returns the number of entries iterated (including the last iteration which returned false).

 


### Creating subsets



#### [slice()](index#slice())




Returns a new Collection of the same type representing a portion of this Collection from start up to but not including end.

 

```
slice(begin?: number, end?: number): this

```

#### Inherited from


`[Collection#slice()](../collection/index#slice())`#### Discussion



If begin is negative, it is offset from the end of the Collection. e.g. `slice(-2)` returns a Collection of the last two entries. If it is not provided the new Collection will begin at the beginning of this Collection.

 If end is negative, it is offset from the end of the Collection. e.g. `slice(0, -1)` returns a Collection of everything but the last entry. If it is not provided, the new Collection will continue through the end of this Collection.

 If the requested slice is equivalent to the current Collection, then it will return itself.

 



#### [rest()](index#rest())




Returns a new Collection of the same type containing all entries except the first.

 

```
rest(): this

```

#### Inherited from


`[Collection#rest()](../collection/index#rest())`



#### [butLast()](index#butLast())




Returns a new Collection of the same type containing all entries except the last.

 

```
butLast(): this

```

#### Inherited from


`[Collection#butLast()](../collection/index#butLast())`



#### [skip()](index#skip())




Returns a new Collection of the same type which excludes the first `amount` entries from this Collection.

 

```
skip(amount: number): this

```

#### Inherited from


`[Collection#skip()](../collection/index#skip())`



#### [skipLast()](index#skipLast())




Returns a new Collection of the same type which excludes the last `amount` entries from this Collection.

 

```
skipLast(amount: number): this

```

#### Inherited from


`[Collection#skipLast()](../collection/index#skipLast())`



#### [skipWhile()](index#skipWhile())




Returns a new Collection of the same type which includes entries starting from when `predicate` first returns false.

 

```
skipWhile(predicate: (value: V, key: K, iter: this) => boolean,context?: unknown): this

```

#### Inherited from


`[Collection#skipWhile()](../collection/index#skipWhile())`#### Discussion


 
```
const { List } = require('immutable')
List([ 'dog', 'frog', 'cat', 'hat', 'god' ])
  .skipWhile(x => x.match(/g/))
// List [ "cat", "hat", "god" ]run it
```


 



#### [skipUntil()](index#skipUntil())




Returns a new Collection of the same type which includes entries starting from when `predicate` first returns true.

 

```
skipUntil(predicate: (value: V, key: K, iter: this) => boolean,context?: unknown): this

```

#### Inherited from


`[Collection#skipUntil()](../collection/index#skipUntil())`#### Discussion


 
```
const { List } = require('immutable')
List([ 'dog', 'frog', 'cat', 'hat', 'god' ])
  .skipUntil(x => x.match(/hat/))
// List [ "hat", "god" ]run it
```


 



#### [take()](index#take())




Returns a new Collection of the same type which includes the first `amount` entries from this Collection.

 

```
take(amount: number): this

```

#### Inherited from


`[Collection#take()](../collection/index#take())`



#### [takeLast()](index#takeLast())




Returns a new Collection of the same type which includes the last `amount` entries from this Collection.

 

```
takeLast(amount: number): this

```

#### Inherited from


`[Collection#takeLast()](../collection/index#takeLast())`



#### [takeWhile()](index#takeWhile())




Returns a new Collection of the same type which includes entries from this Collection as long as the `predicate` returns true.

 

```
takeWhile(predicate: (value: V, key: K, iter: this) => boolean,context?: unknown): this

```

#### Inherited from


`[Collection#takeWhile()](../collection/index#takeWhile())`#### Discussion


 
```
const { List } = require('immutable')
List([ 'dog', 'frog', 'cat', 'hat', 'god' ])
  .takeWhile(x => x.match(/o/))
// List [ "dog", "frog" ]run it
```


 



#### [takeUntil()](index#takeUntil())




Returns a new Collection of the same type which includes entries from this Collection as long as the `predicate` returns false.

 

```
takeUntil(predicate: (value: V, key: K, iter: this) => boolean,context?: unknown): this

```

#### Inherited from


`[Collection#takeUntil()](../collection/index#takeUntil())`#### Discussion


 
```
const { List } = require('immutable')
List([ 'dog', 'frog', 'cat', 'hat', 'god' ])
  .takeUntil(x => x.match(/at/))
// List [ "dog", "frog" ]run it
```


 


### Combination



#### [flatten()](index#flatten())




```
flatten(depth?: number): Collection<unknown, unknown>
flatten(shallow?: boolean): Collection<unknown, unknown>

```

#### Inherited from


`[Collection#flatten()](../collection/index#flatten())`


### Reducing a value



#### [reduce()](index#reduce())




```
reduce<R>(reducer: (reduction: R, value: V, key: K, iter: this) => R,initialReduction: R,context?: unknown): R
reduce<R>(reducer: (reduction: V | R, value: V, key: K, iter: this) => R): R

```

#### Inherited from


`[Collection#reduce()](../collection/index#reduce())`



#### [reduceRight()](index#reduceRight())




```
reduceRight<R>(reducer: (reduction: R, value: V, key: K, iter: this) => R,initialReduction: R,context?: unknown): R
reduceRight<R>(reducer: (reduction: V | R, value: V, key: K, iter: this) => R): R

```

#### Inherited from


`[Collection#reduceRight()](../collection/index#reduceRight())`



#### [every()](index#every())




True if `predicate` returns true for all entries in the Collection.

 

```
every(predicate: (value: V, key: K, iter: this) => boolean,context?: unknown): boolean

```

#### Inherited from


`[Collection#every()](../collection/index#every())`



#### [some()](index#some())




True if `predicate` returns true for any entry in the Collection.

 

```
some(predicate: (value: V, key: K, iter: this) => boolean,context?: unknown): boolean

```

#### Inherited from


`[Collection#some()](../collection/index#some())`



#### [join()](index#join())




Joins values together as a string, inserting a separator between each. The default separator is `","`.

 

```
join(separator?: string): string

```

#### Inherited from


`[Collection#join()](../collection/index#join())`



#### [isEmpty()](index#isEmpty())




Returns true if this Collection includes no values.

 

```
isEmpty(): boolean

```

#### Inherited from


`[Collection#isEmpty()](../collection/index#isEmpty())`#### Discussion



For some lazy `[Seq](../seq/index)`, `[isEmpty](../list/index#isEmpty())` might need to iterate to determine emptiness. At most one iteration will occur.

 



#### [count()](index#count())




```
count(): number
count(predicate: (value: V, key: K, iter: this) => boolean,context?: unknown): number

```

#### Inherited from


`[Collection#count()](../collection/index#count())`



#### [countBy()](index#countBy())




Returns a `[Seq.Keyed](../seq.keyed/index)` of counts, grouped by the return value of the `grouper` function.

 

```
countBy<G>(grouper: (value: V, key: K, iter: this) => G,context?: unknown): Map<G, number>

```

#### Inherited from


`[Collection#countBy()](../collection/index#countBy())`#### Discussion



Note: This is not a lazy operation.

 


### Search for value



#### [find()](index#find())




Returns the first value for which the `predicate` returns true.

 

```
find(predicate: (value: V, key: K, iter: this) => boolean,context?: unknown,notSetValue?: V): V | undefined

```

#### Inherited from


`[Collection#find()](../collection/index#find())`



#### [findLast()](index#findLast())




Returns the last value for which the `predicate` returns true.

 

```
findLast(predicate: (value: V, key: K, iter: this) => boolean,context?: unknown,notSetValue?: V): V | undefined

```

#### Inherited from


`[Collection#findLast()](../collection/index#findLast())`#### Discussion



Note: `predicate` will be called for each entry in reverse.

 



#### [findEntry()](index#findEntry())




Returns the first [key, value] entry for which the `predicate` returns true.

 

```
findEntry(predicate: (value: V, key: K, iter: this) => boolean,context?: unknown,notSetValue?: V): [K, V] | undefined

```

#### Inherited from


`[Collection#findEntry()](../collection/index#findEntry())`



#### [findLastEntry()](index#findLastEntry())




Returns the last [key, value] entry for which the `predicate` returns true.

 

```
findLastEntry(predicate: (value: V, key: K, iter: this) => boolean,context?: unknown,notSetValue?: V): [K, V] | undefined

```

#### Inherited from


`[Collection#findLastEntry()](../collection/index#findLastEntry())`#### Discussion



Note: `predicate` will be called for each entry in reverse.

 



#### [findKey()](index#findKey())




Returns the key for which the `predicate` returns true.

 

```
findKey(predicate: (value: V, key: K, iter: this) => boolean,context?: unknown): K | undefined

```

#### Inherited from


`[Collection#findKey()](../collection/index#findKey())`



#### [findLastKey()](index#findLastKey())




Returns the last key for which the `predicate` returns true.

 

```
findLastKey(predicate: (value: V, key: K, iter: this) => boolean,context?: unknown): K | undefined

```

#### Inherited from


`[Collection#findLastKey()](../collection/index#findLastKey())`#### Discussion



Note: `predicate` will be called for each entry in reverse.

 



#### [keyOf()](index#keyOf())




Returns the key associated with the search value, or undefined.

 

```
keyOf(searchValue: V): K | undefined

```

#### Inherited from


`[Collection#keyOf()](../collection/index#keyOf())`



#### [lastKeyOf()](index#lastKeyOf())




Returns the last key associated with the search value, or undefined.

 

```
lastKeyOf(searchValue: V): K | undefined

```

#### Inherited from


`[Collection#lastKeyOf()](../collection/index#lastKeyOf())`



#### [max()](index#max())




Returns the maximum value in this collection. If any values are comparatively equivalent, the first one found will be returned.

 

```
max(comparator?: (valueA: V, valueB: V) => number): V | undefined

```

#### Inherited from


`[Collection#max()](../collection/index#max())`#### Discussion



The `comparator` is used in the same way as `[Collection#sort](../collection/index#sort())`. If it is not provided, the default comparator is `>`.

 When two values are considered equivalent, the first encountered will be returned. Otherwise, `[max](../list/index#max())` will operate independent of the order of input as long as the comparator is commutative. The default comparator `>` is commutative *only* when types do not differ.

 If `comparator` returns 0 and either value is NaN, undefined, or null, that value will be returned.

 



#### [maxBy()](index#maxBy())




Like `[max](../list/index#max())`, but also accepts a `comparatorValueMapper` which allows for comparing by more sophisticated means:

 

```
maxBy<C>(comparatorValueMapper: (value: V, key: K, iter: this) => C,comparator?: (valueA: C, valueB: C) => number): V | undefined

```

#### Inherited from


`[Collection#maxBy()](../collection/index#maxBy())`#### Discussion


 
```
const { List, } = require('immutable');
const l = List([
  { name: 'Bob', avgHit: 1 },
  { name: 'Max', avgHit: 3 },
  { name: 'Lili', avgHit: 2 } ,
]);
l.maxBy(i => i.avgHit); // will output { name: 'Max', avgHit: 3 }run it
```


 



#### [min()](index#min())




Returns the minimum value in this collection. If any values are comparatively equivalent, the first one found will be returned.

 

```
min(comparator?: (valueA: V, valueB: V) => number): V | undefined

```

#### Inherited from


`[Collection#min()](../collection/index#min())`#### Discussion



The `comparator` is used in the same way as `[Collection#sort](../collection/index#sort())`. If it is not provided, the default comparator is `<`.

 When two values are considered equivalent, the first encountered will be returned. Otherwise, `[min](../list/index#min())` will operate independent of the order of input as long as the comparator is commutative. The default comparator `<` is commutative *only* when types do not differ.

 If `comparator` returns 0 and either value is NaN, undefined, or null, that value will be returned.

 



#### [minBy()](index#minBy())




Like `[min](../list/index#min())`, but also accepts a `comparatorValueMapper` which allows for comparing by more sophisticated means:

 

```
minBy<C>(comparatorValueMapper: (value: V, key: K, iter: this) => C,comparator?: (valueA: C, valueB: C) => number): V | undefined

```

#### Inherited from


`[Collection#minBy()](../collection/index#minBy())`#### Discussion


 
```
const { List, } = require('immutable');
const l = List([
  { name: 'Bob', avgHit: 1 },
  { name: 'Max', avgHit: 3 },
  { name: 'Lili', avgHit: 2 } ,
]);
l.minBy(i => i.avgHit); // will output { name: 'Bob', avgHit: 1 }run it
```


 


### Comparison



#### [isSubset()](index#isSubset())




True if `iter` includes every value in this Collection.

 

```
isSubset(iter: Iterable<V>): boolean

```

#### Inherited from


`[Collection#isSubset()](../collection/index#isSubset())`



#### [isSuperset()](index#isSuperset())




True if this Collection includes every value in `iter`.

 

```
isSuperset(iter: Iterable<V>): boolean

```

#### Inherited from


`[Collection#isSuperset()](../collection/index#isSuperset())`

This documentation is generated from [immutable.d.ts](https://github.com/immutable-js/immutable-js/blob/main/type-definitions/immutable.d.ts). Pull requests and [Issues](https://github.com/immutable-js/immutable-js/issues) welcome.

 © 2014–present, Lee Byron and other contributors  
Licensed under the 3-clause BSD License.  

<https://immutable-js.com/docs/v4.2.1/OrderedMap/>

Set
===



A Collection of unique values with `O(log32 N)` adds and has.

 

```
type Set<T> extends Collection.Set<T>
```

#### Discussion



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](../is()/index)`, enabling Sets to uniquely include other Immutable collections, custom value types, and NaN.

 
### Construction



#### [Set()](index#Set())




Create a new immutable Set containing the values of the provided collection-like.

 

```
Set<T>(collection?: Iterable<T> | ArrayLike<T>): Set<T>

```

#### Discussion



Note: `[Set](index)` is a factory function and not a class, and does not use the `new` keyword during construction.

 


### Static methods



#### [Set.isSet()](index#isSet())



```
Set.isSet(maybeSet: unknown): boolean

```



#### [Set.of()](index#of())



```
Set.of<T>(...values: Array<T>): Set<T>

```



#### [Set.fromKeys()](index#fromKeys())



```
Set.fromKeys<T>(iter: Collection<T, unknown>): Set<T>
Set.fromKeys(obj: {[key: string]: unknown}): Set<string>

```



#### [Set.intersect()](index#intersect())



```
Set.intersect<T>(sets: Iterable<Iterable<T>>): Set<T>

```



#### [Set.union()](index#union())



```
Set.union<T>(sets: Iterable<Iterable<T>>): Set<T>

```


### Members



#### [size](index#size)




The number of items in this Set.

 

```
size: number
```



### Persistent changes



#### [add()](index#add())




Returns a new Set which also includes this value.

 

```
add(value: T): this

```

#### Discussion



Note: `[add](index#add())` can be used in `[withMutations](index#withMutations())`.

 



#### [delete()](index#delete())




Returns a new Set which excludes this value.

 

```
delete(value: T): this

```

#### alias


`remove()`#### Discussion



Note: `[delete](index#delete())` can be used in `[withMutations](index#withMutations())`.

 Note: `[delete](index#delete())` **cannot** be safely used in IE8, use `[remove](../remove()/index)` if supporting old browsers.

 



#### [clear()](index#clear())




Returns a new Set containing no values.

 

```
clear(): this

```

#### Discussion



Note: `[clear](index#clear())` can be used in `[withMutations](index#withMutations())`.

 



#### [union()](index#union())




Returns a Set including any value from `collections` that does not already exist in this Set.

 

```
union<C>(...collections: Array<Iterable<C>>): Set<T | C>

```

#### alias


`merge()`#### alias


`concat()`#### Discussion



Note: `[union](index#union())` can be used in `[withMutations](index#withMutations())`.

 



#### [intersect()](index#intersect())




Returns a Set which has removed any values not also contained within `collections`.

 

```
intersect(...collections: Array<Iterable<T>>): this

```

#### Discussion



Note: `[intersect](index#intersect())` can be used in `[withMutations](index#withMutations())`.

 



#### [subtract()](index#subtract())




Returns a Set excluding any values contained within `collections`.

 

```
subtract(...collections: Array<Iterable<T>>): this

```

#### Discussion


 
```
const { OrderedSet } = require('immutable')
OrderedSet([ 1, 2, 3 ]).subtract([1, 3])
// OrderedSet [2]run it
```



Note: `[subtract](index#subtract())` can be used in `[withMutations](index#withMutations())`.

 



#### [update()](index#update())




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".

 

```
update<R>(updater: (value: this) => R): R

```

#### Inherited from


`[Collection#update()](../collection/index#update())`#### Discussion



For example, to sum a Seq after mapping and filtering:

 
```
const { Seq } = require('immutable')

function sum(collection) {
  return collection.reduce((sum, x) => sum + x, 0)
}
Seq([ 1, 2, 3 ])
  .map(x => x + 1)
  .filter(x => x % 2 === 0)
  .update(sum)
// 6run it
```
 


### Transient changes



#### [withMutations()](index#withMutations())




Note: Not all methods can be used on a mutable collection or within `[withMutations](index#withMutations())`! Check the documentation for each method to see if it mentions being safe to use in `[withMutations](index#withMutations())`.

 

```
withMutations(mutator: (mutable: this) => unknown): this

```

#### see



`[Map#withMutations](../map/index#withMutations())`

 



#### [asMutable()](index#asMutable())




Note: Not all methods can be used on a mutable collection or within `[withMutations](index#withMutations())`! Check the documentation for each method to see if it mentions being safe to use in `[withMutations](index#withMutations())`.

 

```
asMutable(): this

```

#### see



`[Map#asMutable](../map/index#asMutable())`

 



#### [wasAltered()](index#wasAltered())




```
wasAltered(): boolean

```

#### see



`[Map#wasAltered](../map/index#wasAltered())`

 



#### [asImmutable()](index#asImmutable())




```
asImmutable(): this

```

#### see



`[Map#asImmutable](../map/index#asImmutable())`

 


### Sequence algorithms



#### [map()](index#map())




Returns a new Set with values passed through a `mapper` function.

 

```
map<M>(mapper: (value: T, key: T, iter: this) => M, context?: unknown): Set<M>

```

#### Overrides


`[Collection.Set#map()](../collection.set/index#map())`#### Example



```
Set([1,2]).map(x => 10 * x)
// Set [10,20]
```




#### [flatMap()](index#flatMap())




Flat-maps the Set, returning a new Set.

 

```
flatMap<M>(mapper: (value: T, key: T, iter: this) => Iterable<M>,context?: unknown): Set<M>

```

#### Overrides


`[Collection.Set#flatMap()](../collection.set/index#flatMap())`#### Discussion



Similar to `set.map(...).flatten(true)`.

 



#### [filter()](index#filter())




```
filter<F>(predicate: (value: T, key: T, iter: this) => boolean,context?: unknown): Set<F>
filter(predicate: (value: T, key: T, iter: this) => unknown,context?: unknown): this

```

#### Overrides


`[Collection.Set#filter()](../collection.set/index#filter())`



#### [partition()](index#partition())




```
partition<F, C>(predicate: (this: C, value: T, key: T, iter: this) => boolean,context?: C): [Set<T>, Set<F>]
partition<C>(predicate: (this: C, value: T, key: T, iter: this) => unknown,context?: C): [this, this]

```

#### Overrides


`[Collection.Set#partition()](../collection.set/index#partition())`



#### [concat()](index#concat())




Returns a new Collection with other collections concatenated to this one.

 

```
concat<U>(...collections: Array<Iterable<U>>): Collection.Set<T | U>

```

#### Inherited from


`[Collection.Set#concat()](../collection.set/index#concat())`



#### [[Symbol.iterator]()](index#%5BSymbol.iterator%5D())




```
[Symbol.iterator](): IterableIterator<T>

```

#### Inherited from


`[Collection.Set#[Symbol.iterator]()](../collection.set/index#%5BSymbol.iterator%5D())`



#### [filterNot()](index#filterNot())




Returns a new Collection of the same type with only the entries for which the `predicate` function returns false.

 

```
filterNot(predicate: (value: T, key: T, iter: this) => boolean,context?: unknown): this

```

#### Inherited from


`[Collection#filterNot()](../collection/index#filterNot())`#### Discussion


 
```
const { Map } = require('immutable')
Map({ a: 1, b: 2, c: 3, d: 4}).filterNot(x => x % 2 === 0)
// Map { "a": 1, "c": 3 }run it
```



Note: `[filterNot()](../list/index#filterNot())` always returns a new instance, even if it results in not filtering out any values.

 



#### [reverse()](index#reverse())




Returns a new Collection of the same type in reverse order.

 

```
reverse(): this

```

#### Inherited from


`[Collection#reverse()](../collection/index#reverse())`



#### [sort()](index#sort())




Returns a new Collection of the same type which includes the same entries, stably sorted by using a `comparator`.

 

```
sort(comparator?: (valueA: T, valueB: T) => number): this

```

#### Inherited from


`[Collection#sort()](../collection/index#sort())`#### Discussion



If a `comparator` is not provided, a default comparator uses `<` and `>`.

 `comparator(valueA, valueB)`:

 * Returns `0` if the elements should not be swapped.
* Returns `-1` (or any negative number) if `valueA` comes before `valueB`
* Returns `1` (or any positive number) if `valueA` comes after `valueB`
* Is pure, i.e. it must always return the same value for the same pair of values.

 When sorting collections which have no defined order, their ordered equivalents will be returned. e.g. `map.sort()` returns OrderedMap.

 
```
const { Map } = require('immutable')
Map({ "c": 3, "a": 1, "b": 2 }).sort((a, b) => {
  if (a < b) { return -1; }
  if (a > b) { return 1; }
  if (a === b) { return 0; }
});
// OrderedMap { "a": 1, "b": 2, "c": 3 }run it
```

Note: `[sort()](../list/index#sort())` Always returns a new instance, even if the original was already sorted.

 Note: This is always an eager operation.

 



#### [sortBy()](index#sortBy())




Like `[sort](../list/index#sort())`, but also accepts a `comparatorValueMapper` which allows for sorting by more sophisticated means:

 

```
sortBy<C>(comparatorValueMapper: (value: T, key: T, iter: this) => C,comparator?: (valueA: C, valueB: C) => number): this

```

#### Inherited from


`[Collection#sortBy()](../collection/index#sortBy())`#### Discussion


 
```
const { Map } = require('immutable')
const beattles = Map({
  John: { name: "Lennon" },
  Paul: { name: "McCartney" },
  George: { name: "Harrison" },
  Ringo: { name: "Starr" },
});
beattles.sortBy(member => member.name);run it
```



Note: `[sortBy()](../list/index#sortBy())` Always returns a new instance, even if the original was already sorted.

 Note: This is always an eager operation.

 



#### [groupBy()](index#groupBy())




Returns a `[Collection.Keyed](../collection.keyed/index)` of `Collection.Keyeds`, grouped by the return value of the `grouper` function.

 

```
groupBy<G>(grouper: (value: T, key: T, iter: this) => G,context?: unknown): Seq.Keyed<G, Collection<T, T>>

```

#### Inherited from


`[Collection#groupBy()](../collection/index#groupBy())`#### Discussion



Note: This is always an eager operation.

 
```
const { List, Map } = require('immutable')
const listOfMaps = List([
  Map({ v: 0 }),
  Map({ v: 1 }),
  Map({ v: 1 }),
  Map({ v: 0 }),
  Map({ v: 2 })
])
const groupsOfMaps = listOfMaps.groupBy(x => x.get('v'))
// Map {
//   0: List [ Map{ "v": 0 }, Map { "v": 0 } ],
//   1: List [ Map{ "v": 1 }, Map { "v": 1 } ],
//   2: List [ Map{ "v": 2 } ],
// }run it
```




### Conversion to JavaScript types



#### [toJS()](index#toJS())




Deeply converts this Set collection to equivalent native JavaScript Array.

 

```
toJS(): Array<DeepCopy<T>>

```

#### Inherited from


`[Collection.Set#toJS()](../collection.set/index#toJS())`



#### [toJSON()](index#toJSON())




Shallowly converts this Set collection to equivalent native JavaScript Array.

 

```
toJSON(): Array<T>

```

#### Inherited from


`[Collection.Set#toJSON()](../collection.set/index#toJSON())`



#### [toArray()](index#toArray())




Shallowly converts this collection to an Array.

 

```
toArray(): Array<T>

```

#### Inherited from


`[Collection.Set#toArray()](../collection.set/index#toArray())`



#### [toObject()](index#toObject())




Shallowly converts this Collection to an Object.

 

```
toObject(): {[key: string]: T}

```

#### Inherited from


`[Collection#toObject()](../collection/index#toObject())`#### Discussion



Converts keys to Strings.

 


### Conversion to Seq



#### [toSeq()](index#toSeq())




Returns Seq.Set.

 

```
toSeq(): Seq.Set<T>

```

#### Inherited from


`[Collection.Set#toSeq()](../collection.set/index#toSeq())`



#### [toKeyedSeq()](index#toKeyedSeq())




Returns a Seq.Keyed from this Collection where indices are treated as keys.

 

```
toKeyedSeq(): Seq.Keyed<T, T>

```

#### Inherited from


`[Collection#toKeyedSeq()](../collection/index#toKeyedSeq())`#### Discussion



This is useful if you want to operate on an Collection.Indexed and preserve the [index, value] pairs.

 The returned Seq will have identical iteration order as this Collection.

 
```
const { Seq } = require('immutable')
const indexedSeq = Seq([ 'A', 'B', 'C' ])
// Seq [ "A", "B", "C" ]
indexedSeq.filter(v => v === 'B')
// Seq [ "B" ]
const keyedSeq = indexedSeq.toKeyedSeq()
// Seq { 0: "A", 1: "B", 2: "C" }
keyedSeq.filter(v => v === 'B')
// Seq { 1: "B" }run it
```





#### [toIndexedSeq()](index#toIndexedSeq())




Returns an Seq.Indexed of the values of this Collection, discarding keys.

 

```
toIndexedSeq(): Seq.Indexed<T>

```

#### Inherited from


`[Collection#toIndexedSeq()](../collection/index#toIndexedSeq())`



#### [toSetSeq()](index#toSetSeq())




Returns a Seq.Set of the values of this Collection, discarding keys.

 

```
toSetSeq(): Seq.Set<T>

```

#### Inherited from


`[Collection#toSetSeq()](../collection/index#toSetSeq())`


### Value equality



#### [equals()](index#equals())




True if this and the other Collection have value equality, as defined by `[Immutable.is()](../is()/index)`.

 

```
equals(other: unknown): boolean

```

#### Inherited from


`[Collection#equals()](../collection/index#equals())`#### Discussion



Note: This is equivalent to `Immutable.is(this, other)`, but provided to allow for chained expressions.

 



#### [hashCode()](index#hashCode())




Computes and returns the hashed identity for this Collection.

 

```
hashCode(): number

```

#### Inherited from


`[Collection#hashCode()](../collection/index#hashCode())`#### Discussion



The `[hashCode](../list/index#hashCode())` of a Collection is used to determine potential equality, and is used when adding this to a `[Set](index)` or as a key in a `[Map](../map/index)`, enabling lookup via a different instance.

 
```
const a = List([ 1, 2, 3 ]);
const b = List([ 1, 2, 3 ]);
assert.notStrictEqual(a, b); // different instances
const set = Set([ a ]);
assert.equal(set.has(b), true);run it
```

If two values have the same `[hashCode](../list/index#hashCode())`, they are [not guaranteed to be equal](https://en.wikipedia.org/wiki/Collision_(computer_science)). If two values have different `[hashCode](../list/index#hashCode())`s, they must not be equal.

 


### Reading values



#### [get()](index#get())




```
get<NSV>(key: T, notSetValue: NSV): T | NSV
get(key: T): T | undefined

```

#### Inherited from


`[Collection#get()](../collection/index#get())`



#### [has()](index#has())




True if a key exists within this `[Collection](../collection/index)`, using `[Immutable.is](../is()/index)` to determine equality

 

```
has(key: T): boolean

```

#### Inherited from


`[Collection#has()](../collection/index#has())`



#### [includes()](index#includes())




True if a value exists within this `[Collection](../collection/index)`, using `[Immutable.is](../is()/index)` to determine equality

 

```
includes(value: T): boolean

```

#### Inherited from


`[Collection#includes()](../collection/index#includes())`#### alias


`contains()`



#### [first()](index#first())




In case the `[Collection](../collection/index)` is not empty returns the first element of the `[Collection](../collection/index)`. In case the `[Collection](../collection/index)` is empty returns the optional default value if provided, if no default value is provided returns undefined.

 

```
first<NSV>(notSetValue?: NSV): T | NSV

```

#### Inherited from


`[Collection#first()](../collection/index#first())`



#### [last()](index#last())




In case the `[Collection](../collection/index)` is not empty returns the last element of the `[Collection](../collection/index)`. In case the `[Collection](../collection/index)` is empty returns the optional default value if provided, if no default value is provided returns undefined.

 

```
last<NSV>(notSetValue?: NSV): T | NSV

```

#### Inherited from


`[Collection#last()](../collection/index#last())`


### Reading deep values



#### [getIn()](index#getIn())




Returns the value found by following a path of keys or indices through nested Collections.

 

```
getIn(searchKeyPath: Iterable<unknown>, notSetValue?: unknown): unknown

```

#### Inherited from


`[Collection#getIn()](../collection/index#getIn())`#### Discussion


 
```
const { Map, List } = require('immutable')
const deepData = Map({ x: List([ Map({ y: 123 }) ]) });
deepData.getIn(['x', 0, 'y']) // 123run it
```



Plain JavaScript Object or Arrays may be nested within an Immutable.js Collection, and getIn() can access those values as well:

 
```
const { Map, List } = require('immutable')
const deepData = Map({ x: [ { y: 123 } ] });
deepData.getIn(['x', 0, 'y']) // 123run it
```


 



#### [hasIn()](index#hasIn())




True if the result of following a path of keys or indices through nested Collections results in a set value.

 

```
hasIn(searchKeyPath: Iterable<unknown>): boolean

```

#### Inherited from


`[Collection#hasIn()](../collection/index#hasIn())`


### Conversion to Collections



#### [toMap()](index#toMap())




Converts this Collection to a Map, Throws if keys are not hashable.

 

```
toMap(): Map<T, T>

```

#### Inherited from


`[Collection#toMap()](../collection/index#toMap())`#### Discussion



Note: This is equivalent to `Map(this.toKeyedSeq())`, but provided for convenience and to allow for chained expressions.

 



#### [toOrderedMap()](index#toOrderedMap())




Converts this Collection to a Map, maintaining the order of iteration.

 

```
toOrderedMap(): OrderedMap<T, T>

```

#### Inherited from


`[Collection#toOrderedMap()](../collection/index#toOrderedMap())`#### Discussion



Note: This is equivalent to `OrderedMap(this.toKeyedSeq())`, but provided for convenience and to allow for chained expressions.

 



#### [toSet()](index#toSet())




Converts this Collection to a Set, discarding keys. Throws if values are not hashable.

 

```
toSet(): Set<T>

```

#### Inherited from


`[Collection#toSet()](../collection/index#toSet())`#### Discussion



Note: This is equivalent to `[Set(this)](index)`, but provided to allow for chained expressions.

 



#### [toOrderedSet()](index#toOrderedSet())




Converts this Collection to a Set, maintaining the order of iteration and discarding keys.

 

```
toOrderedSet(): OrderedSet<T>

```

#### Inherited from


`[Collection#toOrderedSet()](../collection/index#toOrderedSet())`#### Discussion



Note: This is equivalent to `OrderedSet(this.valueSeq())`, but provided for convenience and to allow for chained expressions.

 



#### [toList()](index#toList())




Converts this Collection to a List, discarding keys.

 

```
toList(): List<T>

```

#### Inherited from


`[Collection#toList()](../collection/index#toList())`#### Discussion



This is similar to `[List(collection)](../list/index)`, but provided to allow for chained expressions. However, when called on `[Map](../map/index)` or other keyed collections, `collection.toList()` discards the keys and creates a list of only the values, whereas `[List(collection)](../list/index)` creates a list of entry tuples.

 
```
const { Map, List } = require('immutable')
var myMap = Map({ a: 'Apple', b: 'Banana' })
List(myMap) // List [ [ "a", "Apple" ], [ "b", "Banana" ] ]
myMap.toList() // List [ "Apple", "Banana" ]run it
```





#### [toStack()](index#toStack())




Converts this Collection to a Stack, discarding keys. Throws if values are not hashable.

 

```
toStack(): Stack<T>

```

#### Inherited from


`[Collection#toStack()](../collection/index#toStack())`#### Discussion



Note: This is equivalent to `[Stack(this)](../stack/index)`, but provided to allow for chained expressions.

 


### Iterators



#### [keys()](index#keys())




An iterator of this `[Collection](../collection/index)`'s keys.

 

```
keys(): IterableIterator<T>

```

#### Inherited from


`[Collection#keys()](../collection/index#keys())`#### Discussion



Note: this will return an ES6 iterator which does not support Immutable.js sequence algorithms. Use `[keySeq](../list/index#keySeq())` instead, if this is what you want.

 



#### [values()](index#values())




An iterator of this `[Collection](../collection/index)`'s values.

 

```
values(): IterableIterator<T>

```

#### Inherited from


`[Collection#values()](../collection/index#values())`#### Discussion



Note: this will return an ES6 iterator which does not support Immutable.js sequence algorithms. Use `[valueSeq](../list/index#valueSeq())` instead, if this is what you want.

 



#### [entries()](index#entries())




An iterator of this `[Collection](../collection/index)`'s entries as `[ key, value ]` tuples.

 

```
entries(): IterableIterator<[T, T]>

```

#### Inherited from


`[Collection#entries()](../collection/index#entries())`#### Discussion



Note: this will return an ES6 iterator which does not support Immutable.js sequence algorithms. Use `[entrySeq](../list/index#entrySeq())` instead, if this is what you want.

 


### Collections (Seq)



#### [keySeq()](index#keySeq())




Returns a new Seq.Indexed of the keys of this Collection, discarding values.

 

```
keySeq(): Seq.Indexed<T>

```

#### Inherited from


`[Collection#keySeq()](../collection/index#keySeq())`



#### [valueSeq()](index#valueSeq())




Returns an Seq.Indexed of the values of this Collection, discarding keys.

 

```
valueSeq(): Seq.Indexed<T>

```

#### Inherited from


`[Collection#valueSeq()](../collection/index#valueSeq())`



#### [entrySeq()](index#entrySeq())




Returns a new Seq.Indexed of [key, value] tuples.

 

```
entrySeq(): Seq.Indexed<[T, T]>

```

#### Inherited from


`[Collection#entrySeq()](../collection/index#entrySeq())`


### Side effects



#### [forEach()](index#forEach())




The `sideEffect` is executed for every entry in the Collection.

 

```
forEach(sideEffect: (value: T, key: T, iter: this) => unknown,context?: unknown): number

```

#### Inherited from


`[Collection#forEach()](../collection/index#forEach())`#### Discussion



Unlike `[Array#forEach](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/forEach)`, if any call of `sideEffect` returns `false`, the iteration will stop. Returns the number of entries iterated (including the last iteration which returned false).

 


### Creating subsets



#### [slice()](index#slice())




Returns a new Collection of the same type representing a portion of this Collection from start up to but not including end.

 

```
slice(begin?: number, end?: number): this

```

#### Inherited from


`[Collection#slice()](../collection/index#slice())`#### Discussion



If begin is negative, it is offset from the end of the Collection. e.g. `slice(-2)` returns a Collection of the last two entries. If it is not provided the new Collection will begin at the beginning of this Collection.

 If end is negative, it is offset from the end of the Collection. e.g. `slice(0, -1)` returns a Collection of everything but the last entry. If it is not provided, the new Collection will continue through the end of this Collection.

 If the requested slice is equivalent to the current Collection, then it will return itself.

 



#### [rest()](index#rest())




Returns a new Collection of the same type containing all entries except the first.

 

```
rest(): this

```

#### Inherited from


`[Collection#rest()](../collection/index#rest())`



#### [butLast()](index#butLast())




Returns a new Collection of the same type containing all entries except the last.

 

```
butLast(): this

```

#### Inherited from


`[Collection#butLast()](../collection/index#butLast())`



#### [skip()](index#skip())




Returns a new Collection of the same type which excludes the first `amount` entries from this Collection.

 

```
skip(amount: number): this

```

#### Inherited from


`[Collection#skip()](../collection/index#skip())`



#### [skipLast()](index#skipLast())




Returns a new Collection of the same type which excludes the last `amount` entries from this Collection.

 

```
skipLast(amount: number): this

```

#### Inherited from


`[Collection#skipLast()](../collection/index#skipLast())`



#### [skipWhile()](index#skipWhile())




Returns a new Collection of the same type which includes entries starting from when `predicate` first returns false.

 

```
skipWhile(predicate: (value: T, key: T, iter: this) => boolean,context?: unknown): this

```

#### Inherited from


`[Collection#skipWhile()](../collection/index#skipWhile())`#### Discussion


 
```
const { List } = require('immutable')
List([ 'dog', 'frog', 'cat', 'hat', 'god' ])
  .skipWhile(x => x.match(/g/))
// List [ "cat", "hat", "god" ]run it
```


 



#### [skipUntil()](index#skipUntil())




Returns a new Collection of the same type which includes entries starting from when `predicate` first returns true.

 

```
skipUntil(predicate: (value: T, key: T, iter: this) => boolean,context?: unknown): this

```

#### Inherited from


`[Collection#skipUntil()](../collection/index#skipUntil())`#### Discussion


 
```
const { List } = require('immutable')
List([ 'dog', 'frog', 'cat', 'hat', 'god' ])
  .skipUntil(x => x.match(/hat/))
// List [ "hat", "god" ]run it
```


 



#### [take()](index#take())




Returns a new Collection of the same type which includes the first `amount` entries from this Collection.

 

```
take(amount: number): this

```

#### Inherited from


`[Collection#take()](../collection/index#take())`



#### [takeLast()](index#takeLast())




Returns a new Collection of the same type which includes the last `amount` entries from this Collection.

 

```
takeLast(amount: number): this

```

#### Inherited from


`[Collection#takeLast()](../collection/index#takeLast())`



#### [takeWhile()](index#takeWhile())




Returns a new Collection of the same type which includes entries from this Collection as long as the `predicate` returns true.

 

```
takeWhile(predicate: (value: T, key: T, iter: this) => boolean,context?: unknown): this

```

#### Inherited from


`[Collection#takeWhile()](../collection/index#takeWhile())`#### Discussion


 
```
const { List } = require('immutable')
List([ 'dog', 'frog', 'cat', 'hat', 'god' ])
  .takeWhile(x => x.match(/o/))
// List [ "dog", "frog" ]run it
```


 



#### [takeUntil()](index#takeUntil())




Returns a new Collection of the same type which includes entries from this Collection as long as the `predicate` returns false.

 

```
takeUntil(predicate: (value: T, key: T, iter: this) => boolean,context?: unknown): this

```

#### Inherited from


`[Collection#takeUntil()](../collection/index#takeUntil())`#### Discussion


 
```
const { List } = require('immutable')
List([ 'dog', 'frog', 'cat', 'hat', 'god' ])
  .takeUntil(x => x.match(/at/))
// List [ "dog", "frog" ]run it
```


 


### Combination



#### [flatten()](index#flatten())




```
flatten(depth?: number): Collection<unknown, unknown>
flatten(shallow?: boolean): Collection<unknown, unknown>

```

#### Inherited from


`[Collection#flatten()](../collection/index#flatten())`


### Reducing a value



#### [reduce()](index#reduce())




```
reduce<R>(reducer: (reduction: R, value: T, key: T, iter: this) => R,initialReduction: R,context?: unknown): R
reduce<R>(reducer: (reduction: T | R, value: T, key: T, iter: this) => R): R

```

#### Inherited from


`[Collection#reduce()](../collection/index#reduce())`



#### [reduceRight()](index#reduceRight())




```
reduceRight<R>(reducer: (reduction: R, value: T, key: T, iter: this) => R,initialReduction: R,context?: unknown): R
reduceRight<R>(reducer: (reduction: T | R, value: T, key: T, iter: this) => R): R

```

#### Inherited from


`[Collection#reduceRight()](../collection/index#reduceRight())`



#### [every()](index#every())




True if `predicate` returns true for all entries in the Collection.

 

```
every(predicate: (value: T, key: T, iter: this) => boolean,context?: unknown): boolean

```

#### Inherited from


`[Collection#every()](../collection/index#every())`



#### [some()](index#some())




True if `predicate` returns true for any entry in the Collection.

 

```
some(predicate: (value: T, key: T, iter: this) => boolean,context?: unknown): boolean

```

#### Inherited from


`[Collection#some()](../collection/index#some())`



#### [join()](index#join())




Joins values together as a string, inserting a separator between each. The default separator is `","`.

 

```
join(separator?: string): string

```

#### Inherited from


`[Collection#join()](../collection/index#join())`



#### [isEmpty()](index#isEmpty())




Returns true if this Collection includes no values.

 

```
isEmpty(): boolean

```

#### Inherited from


`[Collection#isEmpty()](../collection/index#isEmpty())`#### Discussion



For some lazy `[Seq](../seq/index)`, `[isEmpty](../list/index#isEmpty())` might need to iterate to determine emptiness. At most one iteration will occur.

 



#### [count()](index#count())




```
count(): number
count(predicate: (value: T, key: T, iter: this) => boolean,context?: unknown): number

```

#### Inherited from


`[Collection#count()](../collection/index#count())`



#### [countBy()](index#countBy())




Returns a `[Seq.Keyed](../seq.keyed/index)` of counts, grouped by the return value of the `grouper` function.

 

```
countBy<G>(grouper: (value: T, key: T, iter: this) => G,context?: unknown): Map<G, number>

```

#### Inherited from


`[Collection#countBy()](../collection/index#countBy())`#### Discussion



Note: This is not a lazy operation.

 


### Search for value



#### [find()](index#find())




Returns the first value for which the `predicate` returns true.

 

```
find(predicate: (value: T, key: T, iter: this) => boolean,context?: unknown,notSetValue?: T): T | undefined

```

#### Inherited from


`[Collection#find()](../collection/index#find())`



#### [findLast()](index#findLast())




Returns the last value for which the `predicate` returns true.

 

```
findLast(predicate: (value: T, key: T, iter: this) => boolean,context?: unknown,notSetValue?: T): T | undefined

```

#### Inherited from


`[Collection#findLast()](../collection/index#findLast())`#### Discussion



Note: `predicate` will be called for each entry in reverse.

 



#### [findEntry()](index#findEntry())




Returns the first [key, value] entry for which the `predicate` returns true.

 

```
findEntry(predicate: (value: T, key: T, iter: this) => boolean,context?: unknown,notSetValue?: T): [T, T] | undefined

```

#### Inherited from


`[Collection#findEntry()](../collection/index#findEntry())`



#### [findLastEntry()](index#findLastEntry())




Returns the last [key, value] entry for which the `predicate` returns true.

 

```
findLastEntry(predicate: (value: T, key: T, iter: this) => boolean,context?: unknown,notSetValue?: T): [T, T] | undefined

```

#### Inherited from


`[Collection#findLastEntry()](../collection/index#findLastEntry())`#### Discussion



Note: `predicate` will be called for each entry in reverse.

 



#### [findKey()](index#findKey())




Returns the key for which the `predicate` returns true.

 

```
findKey(predicate: (value: T, key: T, iter: this) => boolean,context?: unknown): T | undefined

```

#### Inherited from


`[Collection#findKey()](../collection/index#findKey())`



#### [findLastKey()](index#findLastKey())




Returns the last key for which the `predicate` returns true.

 

```
findLastKey(predicate: (value: T, key: T, iter: this) => boolean,context?: unknown): T | undefined

```

#### Inherited from


`[Collection#findLastKey()](../collection/index#findLastKey())`#### Discussion



Note: `predicate` will be called for each entry in reverse.

 



#### [keyOf()](index#keyOf())




Returns the key associated with the search value, or undefined.

 

```
keyOf(searchValue: T): T | undefined

```

#### Inherited from


`[Collection#keyOf()](../collection/index#keyOf())`



#### [lastKeyOf()](index#lastKeyOf())




Returns the last key associated with the search value, or undefined.

 

```
lastKeyOf(searchValue: T): T | undefined

```

#### Inherited from


`[Collection#lastKeyOf()](../collection/index#lastKeyOf())`



#### [max()](index#max())




Returns the maximum value in this collection. If any values are comparatively equivalent, the first one found will be returned.

 

```
max(comparator?: (valueA: T, valueB: T) => number): T | undefined

```

#### Inherited from


`[Collection#max()](../collection/index#max())`#### Discussion



The `comparator` is used in the same way as `[Collection#sort](../collection/index#sort())`. If it is not provided, the default comparator is `>`.

 When two values are considered equivalent, the first encountered will be returned. Otherwise, `[max](../list/index#max())` will operate independent of the order of input as long as the comparator is commutative. The default comparator `>` is commutative *only* when types do not differ.

 If `comparator` returns 0 and either value is NaN, undefined, or null, that value will be returned.

 



#### [maxBy()](index#maxBy())




Like `[max](../list/index#max())`, but also accepts a `comparatorValueMapper` which allows for comparing by more sophisticated means:

 

```
maxBy<C>(comparatorValueMapper: (value: T, key: T, iter: this) => C,comparator?: (valueA: C, valueB: C) => number): T | undefined

```

#### Inherited from


`[Collection#maxBy()](../collection/index#maxBy())`#### Discussion


 
```
const { List, } = require('immutable');
const l = List([
  { name: 'Bob', avgHit: 1 },
  { name: 'Max', avgHit: 3 },
  { name: 'Lili', avgHit: 2 } ,
]);
l.maxBy(i => i.avgHit); // will output { name: 'Max', avgHit: 3 }run it
```


 



#### [min()](index#min())




Returns the minimum value in this collection. If any values are comparatively equivalent, the first one found will be returned.

 

```
min(comparator?: (valueA: T, valueB: T) => number): T | undefined

```

#### Inherited from


`[Collection#min()](../collection/index#min())`#### Discussion



The `comparator` is used in the same way as `[Collection#sort](../collection/index#sort())`. If it is not provided, the default comparator is `<`.

 When two values are considered equivalent, the first encountered will be returned. Otherwise, `[min](../list/index#min())` will operate independent of the order of input as long as the comparator is commutative. The default comparator `<` is commutative *only* when types do not differ.

 If `comparator` returns 0 and either value is NaN, undefined, or null, that value will be returned.

 



#### [minBy()](index#minBy())




Like `[min](../list/index#min())`, but also accepts a `comparatorValueMapper` which allows for comparing by more sophisticated means:

 

```
minBy<C>(comparatorValueMapper: (value: T, key: T, iter: this) => C,comparator?: (valueA: C, valueB: C) => number): T | undefined

```

#### Inherited from


`[Collection#minBy()](../collection/index#minBy())`#### Discussion


 
```
const { List, } = require('immutable');
const l = List([
  { name: 'Bob', avgHit: 1 },
  { name: 'Max', avgHit: 3 },
  { name: 'Lili', avgHit: 2 } ,
]);
l.minBy(i => i.avgHit); // will output { name: 'Bob', avgHit: 1 }run it
```


 


### Comparison



#### [isSubset()](index#isSubset())




True if `iter` includes every value in this Collection.

 

```
isSubset(iter: Iterable<T>): boolean

```

#### Inherited from


`[Collection#isSubset()](../collection/index#isSubset())`



#### [isSuperset()](index#isSuperset())




True if this Collection includes every value in `iter`.

 

```
isSuperset(iter: Iterable<T>): boolean

```

#### Inherited from


`[Collection#isSuperset()](../collection/index#isSuperset())`

This documentation is generated from [immutable.d.ts](https://github.com/immutable-js/immutable-js/blob/main/type-definitions/immutable.d.ts). Pull requests and [Issues](https://github.com/immutable-js/immutable-js/issues) welcome.

 © 2014–present, Lee Byron and other contributors  
Licensed under the 3-clause BSD License.  

<https://immutable-js.com/docs/v4.2.1/Set/>

OrderedSet
==========



A type of Set that has the additional guarantee that the iteration order of values will be the order in which they were `[add](index#add())`ed.

 

```
type OrderedSet<T> extends Set<T>
```

#### Discussion



The iteration behavior of OrderedSet is the same as native ES6 Set.

 Note that `[OrderedSet](index)` are more expensive than non-ordered `[Set](../set/index)` and may consume more memory. `[OrderedSet#add](index#add())` is amortized O(log32 N), but not stable.

 
### Construction



#### [OrderedSet()](index#OrderedSet())




Create a new immutable OrderedSet containing the values of the provided collection-like.

 

```
OrderedSet<T>(collection?: Iterable<T> | ArrayLike<T>): OrderedSet<T>

```

#### Discussion



Note: `[OrderedSet](index)` is a factory function and not a class, and does not use the `new` keyword during construction.

 


### Static methods



#### [OrderedSet.isOrderedSet()](index#isOrderedSet())



```
OrderedSet.isOrderedSet(maybeOrderedSet: unknown): boolean

```



#### [OrderedSet.of()](index#of())



```
OrderedSet.of<T>(...values: Array<T>): OrderedSet<T>

```



#### [OrderedSet.fromKeys()](index#fromKeys())



```
OrderedSet.fromKeys<T>(iter: Collection<T, unknown>): OrderedSet<T>
OrderedSet.fromKeys(obj: {[key: string]: unknown}): OrderedSet<string>

```


### Members



#### [size](index#size)




The number of items in this OrderedSet.

 

```
size: number
```

#### Overrides


`[Set#size](../set/index#size)`


### Persistent changes



#### [union()](index#union())




Returns an OrderedSet including any value from `collections` that does not already exist in this OrderedSet.

 

```
union<C>(...collections: Array<Iterable<C>>): OrderedSet<T | C>

```

#### Overrides


`[Set#union()](../set/index#union())`#### alias


`merge()`#### alias


`concat()`#### Discussion



Note: `[union](index#union())` can be used in `[withMutations](index#withMutations())`.

 



#### [add()](index#add())




Returns a new Set which also includes this value.

 

```
add(value: T): this

```

#### Inherited from


`[Set#add()](../set/index#add())`#### Discussion



Note: `[add](../set/index#add())` can be used in `[withMutations](../set/index#withMutations())`.

 



#### [delete()](index#delete())




Returns a new Set which excludes this value.

 

```
delete(value: T): this

```

#### Inherited from


`[Set#delete()](../set/index#delete())`#### alias


`remove()`#### Discussion



Note: `[delete](../set/index#delete())` can be used in `[withMutations](../set/index#withMutations())`.

 Note: `[delete](../set/index#delete())` **cannot** be safely used in IE8, use `[remove](../remove()/index)` if supporting old browsers.

 



#### [clear()](index#clear())




Returns a new Set containing no values.

 

```
clear(): this

```

#### Inherited from


`[Set#clear()](../set/index#clear())`#### Discussion



Note: `[clear](../set/index#clear())` can be used in `[withMutations](../set/index#withMutations())`.

 



#### [intersect()](index#intersect())




Returns a Set which has removed any values not also contained within `collections`.

 

```
intersect(...collections: Array<Iterable<T>>): this

```

#### Inherited from


`[Set#intersect()](../set/index#intersect())`#### Discussion



Note: `[intersect](../set/index#intersect())` can be used in `[withMutations](../set/index#withMutations())`.

 



#### [subtract()](index#subtract())




Returns a Set excluding any values contained within `collections`.

 

```
subtract(...collections: Array<Iterable<T>>): this

```

#### Inherited from


`[Set#subtract()](../set/index#subtract())`#### Discussion


 
```
const { OrderedSet } = require('immutable')
OrderedSet([ 1, 2, 3 ]).subtract([1, 3])
// OrderedSet [2]run it
```



Note: `[subtract](../set/index#subtract())` can be used in `[withMutations](../set/index#withMutations())`.

 



#### [update()](index#update())




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".

 

```
update<R>(updater: (value: this) => R): R

```

#### Inherited from


`[Collection#update()](../collection/index#update())`#### Discussion



For example, to sum a Seq after mapping and filtering:

 
```
const { Seq } = require('immutable')

function sum(collection) {
  return collection.reduce((sum, x) => sum + x, 0)
}
Seq([ 1, 2, 3 ])
  .map(x => x + 1)
  .filter(x => x % 2 === 0)
  .update(sum)
// 6run it
```
 


### Sequence algorithms



#### [map()](index#map())




Returns a new Set with values passed through a `mapper` function.

 

```
map<M>(mapper: (value: T, key: T, iter: this) => M,context?: unknown): OrderedSet<M>

```

#### Overrides


`[Set#map()](../set/index#map())`#### Example



```
OrderedSet([ 1, 2 ]).map(x => 10 * x)
// OrderedSet [10, 20]
```




#### [flatMap()](index#flatMap())




Flat-maps the OrderedSet, returning a new OrderedSet.

 

```
flatMap<M>(mapper: (value: T, key: T, iter: this) => Iterable<M>,context?: unknown): OrderedSet<M>

```

#### Overrides


`[Set#flatMap()](../set/index#flatMap())`#### Discussion



Similar to `set.map(...).flatten(true)`.

 



#### [filter()](index#filter())




```
filter<F>(predicate: (value: T, key: T, iter: this) => boolean,context?: unknown): OrderedSet<F>
filter(predicate: (value: T, key: T, iter: this) => unknown,context?: unknown): this

```

#### Overrides


`[Set#filter()](../set/index#filter())`



#### [partition()](index#partition())




```
partition<F, C>(predicate: (this: C, value: T, key: T, iter: this) => boolean,context?: C): [OrderedSet<T>, OrderedSet<F>]
partition<C>(predicate: (this: C, value: T, key: T, iter: this) => unknown,context?: C): [this, this]

```

#### Overrides


`[Set#partition()](../set/index#partition())`



#### [zip()](index#zip())



```
zip<U>(other: Collection<unknown, U>): OrderedSet<[T, U]>
zip<U, V>(other1: Collection<unknown, U>,other2: Collection<unknown, V>): OrderedSet<[T, U, V]>
zip(...collections: Array<Collection<unknown, unknown>>): OrderedSet<unknown>

```



#### [zipAll()](index#zipAll())



```
zipAll<U>(other: Collection<unknown, U>): OrderedSet<[T, U]>
zipAll<U, V>(other1: Collection<unknown, U>,other2: Collection<unknown, V>): OrderedSet<[T, U, V]>
zipAll(...collections: Array<Collection<unknown, unknown>>): OrderedSet<unknown>

```



#### [zipWith()](index#zipWith())



```
zipWith<U, Z>(zipper: (value: T, otherValue: U) => Z,otherCollection: Collection<unknown, U>): OrderedSet<Z>
zipWith<U, V, Z>(zipper: (value: T, otherValue: U, thirdValue: V) => Z,otherCollection: Collection<unknown, U>,thirdCollection: Collection<unknown, V>): OrderedSet<Z>
zipWith<Z>(zipper: (...values: Array<unknown>) => Z,...collections: Array<Collection<unknown, unknown>>): OrderedSet<Z>

```



#### [concat()](index#concat())




Returns a new Collection with other collections concatenated to this one.

 

```
concat<U>(...collections: Array<Iterable<U>>): Collection.Set<T | U>

```

#### Inherited from


`[Collection.Set#concat()](../collection.set/index#concat())`



#### [[Symbol.iterator]()](index#%5BSymbol.iterator%5D())




```
[Symbol.iterator](): IterableIterator<T>

```

#### Inherited from


`[Collection.Set#[Symbol.iterator]()](../collection.set/index#%5BSymbol.iterator%5D())`



#### [filterNot()](index#filterNot())




Returns a new Collection of the same type with only the entries for which the `predicate` function returns false.

 

```
filterNot(predicate: (value: T, key: T, iter: this) => boolean,context?: unknown): this

```

#### Inherited from


`[Collection#filterNot()](../collection/index#filterNot())`#### Discussion


 
```
const { Map } = require('immutable')
Map({ a: 1, b: 2, c: 3, d: 4}).filterNot(x => x % 2 === 0)
// Map { "a": 1, "c": 3 }run it
```



Note: `[filterNot()](../list/index#filterNot())` always returns a new instance, even if it results in not filtering out any values.

 



#### [reverse()](index#reverse())




Returns a new Collection of the same type in reverse order.

 

```
reverse(): this

```

#### Inherited from


`[Collection#reverse()](../collection/index#reverse())`



#### [sort()](index#sort())




Returns a new Collection of the same type which includes the same entries, stably sorted by using a `comparator`.

 

```
sort(comparator?: (valueA: T, valueB: T) => number): this

```

#### Inherited from


`[Collection#sort()](../collection/index#sort())`#### Discussion



If a `comparator` is not provided, a default comparator uses `<` and `>`.

 `comparator(valueA, valueB)`:

 * Returns `0` if the elements should not be swapped.
* Returns `-1` (or any negative number) if `valueA` comes before `valueB`
* Returns `1` (or any positive number) if `valueA` comes after `valueB`
* Is pure, i.e. it must always return the same value for the same pair of values.

 When sorting collections which have no defined order, their ordered equivalents will be returned. e.g. `map.sort()` returns OrderedMap.

 
```
const { Map } = require('immutable')
Map({ "c": 3, "a": 1, "b": 2 }).sort((a, b) => {
  if (a < b) { return -1; }
  if (a > b) { return 1; }
  if (a === b) { return 0; }
});
// OrderedMap { "a": 1, "b": 2, "c": 3 }run it
```

Note: `[sort()](../list/index#sort())` Always returns a new instance, even if the original was already sorted.

 Note: This is always an eager operation.

 



#### [sortBy()](index#sortBy())




Like `[sort](../list/index#sort())`, but also accepts a `comparatorValueMapper` which allows for sorting by more sophisticated means:

 

```
sortBy<C>(comparatorValueMapper: (value: T, key: T, iter: this) => C,comparator?: (valueA: C, valueB: C) => number): this

```

#### Inherited from


`[Collection#sortBy()](../collection/index#sortBy())`#### Discussion


 
```
const { Map } = require('immutable')
const beattles = Map({
  John: { name: "Lennon" },
  Paul: { name: "McCartney" },
  George: { name: "Harrison" },
  Ringo: { name: "Starr" },
});
beattles.sortBy(member => member.name);run it
```



Note: `[sortBy()](../list/index#sortBy())` Always returns a new instance, even if the original was already sorted.

 Note: This is always an eager operation.

 



#### [groupBy()](index#groupBy())




Returns a `[Collection.Keyed](../collection.keyed/index)` of `Collection.Keyeds`, grouped by the return value of the `grouper` function.

 

```
groupBy<G>(grouper: (value: T, key: T, iter: this) => G,context?: unknown): Seq.Keyed<G, Collection<T, T>>

```

#### Inherited from


`[Collection#groupBy()](../collection/index#groupBy())`#### Discussion



Note: This is always an eager operation.

 
```
const { List, Map } = require('immutable')
const listOfMaps = List([
  Map({ v: 0 }),
  Map({ v: 1 }),
  Map({ v: 1 }),
  Map({ v: 0 }),
  Map({ v: 2 })
])
const groupsOfMaps = listOfMaps.groupBy(x => x.get('v'))
// Map {
//   0: List [ Map{ "v": 0 }, Map { "v": 0 } ],
//   1: List [ Map{ "v": 1 }, Map { "v": 1 } ],
//   2: List [ Map{ "v": 2 } ],
// }run it
```




### Transient changes



#### [withMutations()](index#withMutations())




Note: Not all methods can be used on a mutable collection or within `[withMutations](../set/index#withMutations())`! Check the documentation for each method to see if it mentions being safe to use in `[withMutations](../set/index#withMutations())`.

 

```
withMutations(mutator: (mutable: this) => unknown): this

```

#### Inherited from


`[Set#withMutations()](../set/index#withMutations())`#### see



`[Map#withMutations](../map/index#withMutations())`

 



#### [asMutable()](index#asMutable())




Note: Not all methods can be used on a mutable collection or within `[withMutations](../set/index#withMutations())`! Check the documentation for each method to see if it mentions being safe to use in `[withMutations](../set/index#withMutations())`.

 

```
asMutable(): this

```

#### Inherited from


`[Set#asMutable()](../set/index#asMutable())`#### see



`[Map#asMutable](../map/index#asMutable())`

 



#### [wasAltered()](index#wasAltered())




```
wasAltered(): boolean

```

#### Inherited from


`[Set#wasAltered()](../set/index#wasAltered())`#### see



`[Map#wasAltered](../map/index#wasAltered())`

 



#### [asImmutable()](index#asImmutable())




```
asImmutable(): this

```

#### Inherited from


`[Set#asImmutable()](../set/index#asImmutable())`#### see



`[Map#asImmutable](../map/index#asImmutable())`

 


### Conversion to JavaScript types



#### [toJS()](index#toJS())




Deeply converts this Set collection to equivalent native JavaScript Array.

 

```
toJS(): Array<DeepCopy<T>>

```

#### Inherited from


`[Collection.Set#toJS()](../collection.set/index#toJS())`



#### [toJSON()](index#toJSON())




Shallowly converts this Set collection to equivalent native JavaScript Array.

 

```
toJSON(): Array<T>

```

#### Inherited from


`[Collection.Set#toJSON()](../collection.set/index#toJSON())`



#### [toArray()](index#toArray())




Shallowly converts this collection to an Array.

 

```
toArray(): Array<T>

```

#### Inherited from


`[Collection.Set#toArray()](../collection.set/index#toArray())`



#### [toObject()](index#toObject())




Shallowly converts this Collection to an Object.

 

```
toObject(): {[key: string]: T}

```

#### Inherited from


`[Collection#toObject()](../collection/index#toObject())`#### Discussion



Converts keys to Strings.

 


### Conversion to Seq



#### [toSeq()](index#toSeq())




Returns Seq.Set.

 

```
toSeq(): Seq.Set<T>

```

#### Inherited from


`[Collection.Set#toSeq()](../collection.set/index#toSeq())`



#### [toKeyedSeq()](index#toKeyedSeq())




Returns a Seq.Keyed from this Collection where indices are treated as keys.

 

```
toKeyedSeq(): Seq.Keyed<T, T>

```

#### Inherited from


`[Collection#toKeyedSeq()](../collection/index#toKeyedSeq())`#### Discussion



This is useful if you want to operate on an Collection.Indexed and preserve the [index, value] pairs.

 The returned Seq will have identical iteration order as this Collection.

 
```
const { Seq } = require('immutable')
const indexedSeq = Seq([ 'A', 'B', 'C' ])
// Seq [ "A", "B", "C" ]
indexedSeq.filter(v => v === 'B')
// Seq [ "B" ]
const keyedSeq = indexedSeq.toKeyedSeq()
// Seq { 0: "A", 1: "B", 2: "C" }
keyedSeq.filter(v => v === 'B')
// Seq { 1: "B" }run it
```





#### [toIndexedSeq()](index#toIndexedSeq())




Returns an Seq.Indexed of the values of this Collection, discarding keys.

 

```
toIndexedSeq(): Seq.Indexed<T>

```

#### Inherited from


`[Collection#toIndexedSeq()](../collection/index#toIndexedSeq())`



#### [toSetSeq()](index#toSetSeq())




Returns a Seq.Set of the values of this Collection, discarding keys.

 

```
toSetSeq(): Seq.Set<T>

```

#### Inherited from


`[Collection#toSetSeq()](../collection/index#toSetSeq())`


### Value equality



#### [equals()](index#equals())




True if this and the other Collection have value equality, as defined by `[Immutable.is()](../is()/index)`.

 

```
equals(other: unknown): boolean

```

#### Inherited from


`[Collection#equals()](../collection/index#equals())`#### Discussion



Note: This is equivalent to `Immutable.is(this, other)`, but provided to allow for chained expressions.

 



#### [hashCode()](index#hashCode())




Computes and returns the hashed identity for this Collection.

 

```
hashCode(): number

```

#### Inherited from


`[Collection#hashCode()](../collection/index#hashCode())`#### Discussion



The `[hashCode](../list/index#hashCode())` of a Collection is used to determine potential equality, and is used when adding this to a `[Set](../set/index)` or as a key in a `[Map](../map/index)`, enabling lookup via a different instance.

 
```
const a = List([ 1, 2, 3 ]);
const b = List([ 1, 2, 3 ]);
assert.notStrictEqual(a, b); // different instances
const set = Set([ a ]);
assert.equal(set.has(b), true);run it
```

If two values have the same `[hashCode](../list/index#hashCode())`, they are [not guaranteed to be equal](https://en.wikipedia.org/wiki/Collision_(computer_science)). If two values have different `[hashCode](../list/index#hashCode())`s, they must not be equal.

 


### Reading values



#### [get()](index#get())




```
get<NSV>(key: T, notSetValue: NSV): T | NSV
get(key: T): T | undefined

```

#### Inherited from


`[Collection#get()](../collection/index#get())`



#### [has()](index#has())




True if a key exists within this `[Collection](../collection/index)`, using `[Immutable.is](../is()/index)` to determine equality

 

```
has(key: T): boolean

```

#### Inherited from


`[Collection#has()](../collection/index#has())`



#### [includes()](index#includes())




True if a value exists within this `[Collection](../collection/index)`, using `[Immutable.is](../is()/index)` to determine equality

 

```
includes(value: T): boolean

```

#### Inherited from


`[Collection#includes()](../collection/index#includes())`#### alias


`contains()`



#### [first()](index#first())




In case the `[Collection](../collection/index)` is not empty returns the first element of the `[Collection](../collection/index)`. In case the `[Collection](../collection/index)` is empty returns the optional default value if provided, if no default value is provided returns undefined.

 

```
first<NSV>(notSetValue?: NSV): T | NSV

```

#### Inherited from


`[Collection#first()](../collection/index#first())`



#### [last()](index#last())




In case the `[Collection](../collection/index)` is not empty returns the last element of the `[Collection](../collection/index)`. In case the `[Collection](../collection/index)` is empty returns the optional default value if provided, if no default value is provided returns undefined.

 

```
last<NSV>(notSetValue?: NSV): T | NSV

```

#### Inherited from


`[Collection#last()](../collection/index#last())`


### Reading deep values



#### [getIn()](index#getIn())




Returns the value found by following a path of keys or indices through nested Collections.

 

```
getIn(searchKeyPath: Iterable<unknown>, notSetValue?: unknown): unknown

```

#### Inherited from


`[Collection#getIn()](../collection/index#getIn())`#### Discussion


 
```
const { Map, List } = require('immutable')
const deepData = Map({ x: List([ Map({ y: 123 }) ]) });
deepData.getIn(['x', 0, 'y']) // 123run it
```



Plain JavaScript Object or Arrays may be nested within an Immutable.js Collection, and getIn() can access those values as well:

 
```
const { Map, List } = require('immutable')
const deepData = Map({ x: [ { y: 123 } ] });
deepData.getIn(['x', 0, 'y']) // 123run it
```


 



#### [hasIn()](index#hasIn())




True if the result of following a path of keys or indices through nested Collections results in a set value.

 

```
hasIn(searchKeyPath: Iterable<unknown>): boolean

```

#### Inherited from


`[Collection#hasIn()](../collection/index#hasIn())`


### Conversion to Collections



#### [toMap()](index#toMap())




Converts this Collection to a Map, Throws if keys are not hashable.

 

```
toMap(): Map<T, T>

```

#### Inherited from


`[Collection#toMap()](../collection/index#toMap())`#### Discussion



Note: This is equivalent to `Map(this.toKeyedSeq())`, but provided for convenience and to allow for chained expressions.

 



#### [toOrderedMap()](index#toOrderedMap())




Converts this Collection to a Map, maintaining the order of iteration.

 

```
toOrderedMap(): OrderedMap<T, T>

```

#### Inherited from


`[Collection#toOrderedMap()](../collection/index#toOrderedMap())`#### Discussion



Note: This is equivalent to `OrderedMap(this.toKeyedSeq())`, but provided for convenience and to allow for chained expressions.

 



#### [toSet()](index#toSet())




Converts this Collection to a Set, discarding keys. Throws if values are not hashable.

 

```
toSet(): Set<T>

```

#### Inherited from


`[Collection#toSet()](../collection/index#toSet())`#### Discussion



Note: This is equivalent to `[Set(this)](../set/index)`, but provided to allow for chained expressions.

 



#### [toOrderedSet()](index#toOrderedSet())




Converts this Collection to a Set, maintaining the order of iteration and discarding keys.

 

```
toOrderedSet(): OrderedSet<T>

```

#### Inherited from


`[Collection#toOrderedSet()](../collection/index#toOrderedSet())`#### Discussion



Note: This is equivalent to `OrderedSet(this.valueSeq())`, but provided for convenience and to allow for chained expressions.

 



#### [toList()](index#toList())




Converts this Collection to a List, discarding keys.

 

```
toList(): List<T>

```

#### Inherited from


`[Collection#toList()](../collection/index#toList())`#### Discussion



This is similar to `[List(collection)](../list/index)`, but provided to allow for chained expressions. However, when called on `[Map](../map/index)` or other keyed collections, `collection.toList()` discards the keys and creates a list of only the values, whereas `[List(collection)](../list/index)` creates a list of entry tuples.

 
```
const { Map, List } = require('immutable')
var myMap = Map({ a: 'Apple', b: 'Banana' })
List(myMap) // List [ [ "a", "Apple" ], [ "b", "Banana" ] ]
myMap.toList() // List [ "Apple", "Banana" ]run it
```





#### [toStack()](index#toStack())




Converts this Collection to a Stack, discarding keys. Throws if values are not hashable.

 

```
toStack(): Stack<T>

```

#### Inherited from


`[Collection#toStack()](../collection/index#toStack())`#### Discussion



Note: This is equivalent to `[Stack(this)](../stack/index)`, but provided to allow for chained expressions.

 


### Iterators



#### [keys()](index#keys())




An iterator of this `[Collection](../collection/index)`'s keys.

 

```
keys(): IterableIterator<T>

```

#### Inherited from


`[Collection#keys()](../collection/index#keys())`#### Discussion



Note: this will return an ES6 iterator which does not support Immutable.js sequence algorithms. Use `[keySeq](../list/index#keySeq())` instead, if this is what you want.

 



#### [values()](index#values())




An iterator of this `[Collection](../collection/index)`'s values.

 

```
values(): IterableIterator<T>

```

#### Inherited from


`[Collection#values()](../collection/index#values())`#### Discussion



Note: this will return an ES6 iterator which does not support Immutable.js sequence algorithms. Use `[valueSeq](../list/index#valueSeq())` instead, if this is what you want.

 



#### [entries()](index#entries())




An iterator of this `[Collection](../collection/index)`'s entries as `[ key, value ]` tuples.

 

```
entries(): IterableIterator<[T, T]>

```

#### Inherited from


`[Collection#entries()](../collection/index#entries())`#### Discussion



Note: this will return an ES6 iterator which does not support Immutable.js sequence algorithms. Use `[entrySeq](../list/index#entrySeq())` instead, if this is what you want.

 


### Collections (Seq)



#### [keySeq()](index#keySeq())




Returns a new Seq.Indexed of the keys of this Collection, discarding values.

 

```
keySeq(): Seq.Indexed<T>

```

#### Inherited from


`[Collection#keySeq()](../collection/index#keySeq())`



#### [valueSeq()](index#valueSeq())




Returns an Seq.Indexed of the values of this Collection, discarding keys.

 

```
valueSeq(): Seq.Indexed<T>

```

#### Inherited from


`[Collection#valueSeq()](../collection/index#valueSeq())`



#### [entrySeq()](index#entrySeq())




Returns a new Seq.Indexed of [key, value] tuples.

 

```
entrySeq(): Seq.Indexed<[T, T]>

```

#### Inherited from


`[Collection#entrySeq()](../collection/index#entrySeq())`


### Side effects



#### [forEach()](index#forEach())




The `sideEffect` is executed for every entry in the Collection.

 

```
forEach(sideEffect: (value: T, key: T, iter: this) => unknown,context?: unknown): number

```

#### Inherited from


`[Collection#forEach()](../collection/index#forEach())`#### Discussion



Unlike `[Array#forEach](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/forEach)`, if any call of `sideEffect` returns `false`, the iteration will stop. Returns the number of entries iterated (including the last iteration which returned false).

 


### Creating subsets



#### [slice()](index#slice())




Returns a new Collection of the same type representing a portion of this Collection from start up to but not including end.

 

```
slice(begin?: number, end?: number): this

```

#### Inherited from


`[Collection#slice()](../collection/index#slice())`#### Discussion



If begin is negative, it is offset from the end of the Collection. e.g. `slice(-2)` returns a Collection of the last two entries. If it is not provided the new Collection will begin at the beginning of this Collection.

 If end is negative, it is offset from the end of the Collection. e.g. `slice(0, -1)` returns a Collection of everything but the last entry. If it is not provided, the new Collection will continue through the end of this Collection.

 If the requested slice is equivalent to the current Collection, then it will return itself.

 



#### [rest()](index#rest())




Returns a new Collection of the same type containing all entries except the first.

 

```
rest(): this

```

#### Inherited from


`[Collection#rest()](../collection/index#rest())`



#### [butLast()](index#butLast())




Returns a new Collection of the same type containing all entries except the last.

 

```
butLast(): this

```

#### Inherited from


`[Collection#butLast()](../collection/index#butLast())`



#### [skip()](index#skip())




Returns a new Collection of the same type which excludes the first `amount` entries from this Collection.

 

```
skip(amount: number): this

```

#### Inherited from


`[Collection#skip()](../collection/index#skip())`



#### [skipLast()](index#skipLast())




Returns a new Collection of the same type which excludes the last `amount` entries from this Collection.

 

```
skipLast(amount: number): this

```

#### Inherited from


`[Collection#skipLast()](../collection/index#skipLast())`



#### [skipWhile()](index#skipWhile())




Returns a new Collection of the same type which includes entries starting from when `predicate` first returns false.

 

```
skipWhile(predicate: (value: T, key: T, iter: this) => boolean,context?: unknown): this

```

#### Inherited from


`[Collection#skipWhile()](../collection/index#skipWhile())`#### Discussion


 
```
const { List } = require('immutable')
List([ 'dog', 'frog', 'cat', 'hat', 'god' ])
  .skipWhile(x => x.match(/g/))
// List [ "cat", "hat", "god" ]run it
```


 



#### [skipUntil()](index#skipUntil())




Returns a new Collection of the same type which includes entries starting from when `predicate` first returns true.

 

```
skipUntil(predicate: (value: T, key: T, iter: this) => boolean,context?: unknown): this

```

#### Inherited from


`[Collection#skipUntil()](../collection/index#skipUntil())`#### Discussion


 
```
const { List } = require('immutable')
List([ 'dog', 'frog', 'cat', 'hat', 'god' ])
  .skipUntil(x => x.match(/hat/))
// List [ "hat", "god" ]run it
```


 



#### [take()](index#take())




Returns a new Collection of the same type which includes the first `amount` entries from this Collection.

 

```
take(amount: number): this

```

#### Inherited from


`[Collection#take()](../collection/index#take())`



#### [takeLast()](index#takeLast())




Returns a new Collection of the same type which includes the last `amount` entries from this Collection.

 

```
takeLast(amount: number): this

```

#### Inherited from


`[Collection#takeLast()](../collection/index#takeLast())`



#### [takeWhile()](index#takeWhile())




Returns a new Collection of the same type which includes entries from this Collection as long as the `predicate` returns true.

 

```
takeWhile(predicate: (value: T, key: T, iter: this) => boolean,context?: unknown): this

```

#### Inherited from


`[Collection#takeWhile()](../collection/index#takeWhile())`#### Discussion


 
```
const { List } = require('immutable')
List([ 'dog', 'frog', 'cat', 'hat', 'god' ])
  .takeWhile(x => x.match(/o/))
// List [ "dog", "frog" ]run it
```


 



#### [takeUntil()](index#takeUntil())




Returns a new Collection of the same type which includes entries from this Collection as long as the `predicate` returns false.

 

```
takeUntil(predicate: (value: T, key: T, iter: this) => boolean,context?: unknown): this

```

#### Inherited from


`[Collection#takeUntil()](../collection/index#takeUntil())`#### Discussion


 
```
const { List } = require('immutable')
List([ 'dog', 'frog', 'cat', 'hat', 'god' ])
  .takeUntil(x => x.match(/at/))
// List [ "dog", "frog" ]run it
```


 


### Combination



#### [flatten()](index#flatten())




```
flatten(depth?: number): Collection<unknown, unknown>
flatten(shallow?: boolean): Collection<unknown, unknown>

```

#### Inherited from


`[Collection#flatten()](../collection/index#flatten())`


### Reducing a value



#### [reduce()](index#reduce())




```
reduce<R>(reducer: (reduction: R, value: T, key: T, iter: this) => R,initialReduction: R,context?: unknown): R
reduce<R>(reducer: (reduction: T | R, value: T, key: T, iter: this) => R): R

```

#### Inherited from


`[Collection#reduce()](../collection/index#reduce())`



#### [reduceRight()](index#reduceRight())




```
reduceRight<R>(reducer: (reduction: R, value: T, key: T, iter: this) => R,initialReduction: R,context?: unknown): R
reduceRight<R>(reducer: (reduction: T | R, value: T, key: T, iter: this) => R): R

```

#### Inherited from


`[Collection#reduceRight()](../collection/index#reduceRight())`



#### [every()](index#every())




True if `predicate` returns true for all entries in the Collection.

 

```
every(predicate: (value: T, key: T, iter: this) => boolean,context?: unknown): boolean

```

#### Inherited from


`[Collection#every()](../collection/index#every())`



#### [some()](index#some())




True if `predicate` returns true for any entry in the Collection.

 

```
some(predicate: (value: T, key: T, iter: this) => boolean,context?: unknown): boolean

```

#### Inherited from


`[Collection#some()](../collection/index#some())`



#### [join()](index#join())




Joins values together as a string, inserting a separator between each. The default separator is `","`.

 

```
join(separator?: string): string

```

#### Inherited from


`[Collection#join()](../collection/index#join())`



#### [isEmpty()](index#isEmpty())




Returns true if this Collection includes no values.

 

```
isEmpty(): boolean

```

#### Inherited from


`[Collection#isEmpty()](../collection/index#isEmpty())`#### Discussion



For some lazy `[Seq](../seq/index)`, `[isEmpty](../list/index#isEmpty())` might need to iterate to determine emptiness. At most one iteration will occur.

 



#### [count()](index#count())




```
count(): number
count(predicate: (value: T, key: T, iter: this) => boolean,context?: unknown): number

```

#### Inherited from


`[Collection#count()](../collection/index#count())`



#### [countBy()](index#countBy())




Returns a `[Seq.Keyed](../seq.keyed/index)` of counts, grouped by the return value of the `grouper` function.

 

```
countBy<G>(grouper: (value: T, key: T, iter: this) => G,context?: unknown): Map<G, number>

```

#### Inherited from


`[Collection#countBy()](../collection/index#countBy())`#### Discussion



Note: This is not a lazy operation.

 


### Search for value



#### [find()](index#find())




Returns the first value for which the `predicate` returns true.

 

```
find(predicate: (value: T, key: T, iter: this) => boolean,context?: unknown,notSetValue?: T): T | undefined

```

#### Inherited from


`[Collection#find()](../collection/index#find())`



#### [findLast()](index#findLast())




Returns the last value for which the `predicate` returns true.

 

```
findLast(predicate: (value: T, key: T, iter: this) => boolean,context?: unknown,notSetValue?: T): T | undefined

```

#### Inherited from


`[Collection#findLast()](../collection/index#findLast())`#### Discussion



Note: `predicate` will be called for each entry in reverse.

 



#### [findEntry()](index#findEntry())




Returns the first [key, value] entry for which the `predicate` returns true.

 

```
findEntry(predicate: (value: T, key: T, iter: this) => boolean,context?: unknown,notSetValue?: T): [T, T] | undefined

```

#### Inherited from


`[Collection#findEntry()](../collection/index#findEntry())`



#### [findLastEntry()](index#findLastEntry())




Returns the last [key, value] entry for which the `predicate` returns true.

 

```
findLastEntry(predicate: (value: T, key: T, iter: this) => boolean,context?: unknown,notSetValue?: T): [T, T] | undefined

```

#### Inherited from


`[Collection#findLastEntry()](../collection/index#findLastEntry())`#### Discussion



Note: `predicate` will be called for each entry in reverse.

 



#### [findKey()](index#findKey())




Returns the key for which the `predicate` returns true.

 

```
findKey(predicate: (value: T, key: T, iter: this) => boolean,context?: unknown): T | undefined

```

#### Inherited from


`[Collection#findKey()](../collection/index#findKey())`



#### [findLastKey()](index#findLastKey())




Returns the last key for which the `predicate` returns true.

 

```
findLastKey(predicate: (value: T, key: T, iter: this) => boolean,context?: unknown): T | undefined

```

#### Inherited from


`[Collection#findLastKey()](../collection/index#findLastKey())`#### Discussion



Note: `predicate` will be called for each entry in reverse.

 



#### [keyOf()](index#keyOf())




Returns the key associated with the search value, or undefined.

 

```
keyOf(searchValue: T): T | undefined

```

#### Inherited from


`[Collection#keyOf()](../collection/index#keyOf())`



#### [lastKeyOf()](index#lastKeyOf())




Returns the last key associated with the search value, or undefined.

 

```
lastKeyOf(searchValue: T): T | undefined

```

#### Inherited from


`[Collection#lastKeyOf()](../collection/index#lastKeyOf())`



#### [max()](index#max())




Returns the maximum value in this collection. If any values are comparatively equivalent, the first one found will be returned.

 

```
max(comparator?: (valueA: T, valueB: T) => number): T | undefined

```

#### Inherited from


`[Collection#max()](../collection/index#max())`#### Discussion



The `comparator` is used in the same way as `[Collection#sort](../collection/index#sort())`. If it is not provided, the default comparator is `>`.

 When two values are considered equivalent, the first encountered will be returned. Otherwise, `[max](../list/index#max())` will operate independent of the order of input as long as the comparator is commutative. The default comparator `>` is commutative *only* when types do not differ.

 If `comparator` returns 0 and either value is NaN, undefined, or null, that value will be returned.

 



#### [maxBy()](index#maxBy())




Like `[max](../list/index#max())`, but also accepts a `comparatorValueMapper` which allows for comparing by more sophisticated means:

 

```
maxBy<C>(comparatorValueMapper: (value: T, key: T, iter: this) => C,comparator?: (valueA: C, valueB: C) => number): T | undefined

```

#### Inherited from


`[Collection#maxBy()](../collection/index#maxBy())`#### Discussion


 
```
const { List, } = require('immutable');
const l = List([
  { name: 'Bob', avgHit: 1 },
  { name: 'Max', avgHit: 3 },
  { name: 'Lili', avgHit: 2 } ,
]);
l.maxBy(i => i.avgHit); // will output { name: 'Max', avgHit: 3 }run it
```


 



#### [min()](index#min())




Returns the minimum value in this collection. If any values are comparatively equivalent, the first one found will be returned.

 

```
min(comparator?: (valueA: T, valueB: T) => number): T | undefined

```

#### Inherited from


`[Collection#min()](../collection/index#min())`#### Discussion



The `comparator` is used in the same way as `[Collection#sort](../collection/index#sort())`. If it is not provided, the default comparator is `<`.

 When two values are considered equivalent, the first encountered will be returned. Otherwise, `[min](../list/index#min())` will operate independent of the order of input as long as the comparator is commutative. The default comparator `<` is commutative *only* when types do not differ.

 If `comparator` returns 0 and either value is NaN, undefined, or null, that value will be returned.

 



#### [minBy()](index#minBy())




Like `[min](../list/index#min())`, but also accepts a `comparatorValueMapper` which allows for comparing by more sophisticated means:

 

```
minBy<C>(comparatorValueMapper: (value: T, key: T, iter: this) => C,comparator?: (valueA: C, valueB: C) => number): T | undefined

```

#### Inherited from


`[Collection#minBy()](../collection/index#minBy())`#### Discussion


 
```
const { List, } = require('immutable');
const l = List([
  { name: 'Bob', avgHit: 1 },
  { name: 'Max', avgHit: 3 },
  { name: 'Lili', avgHit: 2 } ,
]);
l.minBy(i => i.avgHit); // will output { name: 'Bob', avgHit: 1 }run it
```


 


### Comparison



#### [isSubset()](index#isSubset())




True if `iter` includes every value in this Collection.

 

```
isSubset(iter: Iterable<T>): boolean

```

#### Inherited from


`[Collection#isSubset()](../collection/index#isSubset())`



#### [isSuperset()](index#isSuperset())




True if this Collection includes every value in `iter`.

 

```
isSuperset(iter: Iterable<T>): boolean

```

#### Inherited from


`[Collection#isSuperset()](../collection/index#isSuperset())`

This documentation is generated from [immutable.d.ts](https://github.com/immutable-js/immutable-js/blob/main/type-definitions/immutable.d.ts). Pull requests and [Issues](https://github.com/immutable-js/immutable-js/issues) welcome.

 © 2014–present, Lee Byron and other contributors  
Licensed under the 3-clause BSD License.  

<https://immutable-js.com/docs/v4.2.1/OrderedSet/>

Stack
=====



Stacks are indexed collections which support very efficient O(1) addition and removal from the front using `[unshift(v)](index#unshift())` and `[shift()](index#shift())`.

 

```
type Stack<T> extends Collection.Indexed<T>
```

#### Discussion



For familiarity, Stack also provides `[push(v)](index#push())`, `[pop()](index#pop())`, and `[peek()](index#peek())`, but be aware that they also operate on the front of the list, unlike List or a JavaScript Array.

 Note: `[reverse()](index#reverse())` or any inherent reverse traversal (`[reduceRight](index#reduceRight())`, `[lastIndexOf](index#lastIndexOf())`, etc.) is not efficient with a Stack.

 Stack is implemented with a Single-Linked List.

 
### Construction



#### [Stack()](index#Stack())




Create a new immutable Stack containing the values of the provided collection-like.

 

```
Stack<T>(collection?: Iterable<T> | ArrayLike<T>): Stack<T>

```

#### Discussion



The iteration order of the provided collection is preserved in the resulting `[Stack](index)`.

 Note: `[Stack](index)` is a factory function and not a class, and does not use the `new` keyword during construction.

 


### Static methods



#### [Stack.isStack()](index#isStack())



```
Stack.isStack(maybeStack: unknown): boolean

```



#### [Stack.of()](index#of())



```
Stack.of<T>(...values: Array<T>): Stack<T>

```


### Members



#### [size](index#size)




The number of items in this Stack.

 

```
size: number
```



### Reading values



#### [peek()](index#peek())




Alias for `[Stack.first()](index#first())`.

 

```
peek(): T | undefined

```




#### [get()](index#get())




```
get<NSV>(index: number, notSetValue: NSV): T | NSV
get(index: number): T | undefined

```

#### Inherited from


`[Collection.Indexed#get()](../collection.indexed/index#get())`



#### [has()](index#has())




True if a key exists within this `[Collection](../collection/index)`, using `[Immutable.is](../is()/index)` to determine equality

 

```
has(key: number): boolean

```

#### Inherited from


`[Collection#has()](../collection/index#has())`



#### [includes()](index#includes())




True if a value exists within this `[Collection](../collection/index)`, using `[Immutable.is](../is()/index)` to determine equality

 

```
includes(value: T): boolean

```

#### Inherited from


`[Collection#includes()](../collection/index#includes())`#### alias


`contains()`



#### [first()](index#first())




In case the `[Collection](../collection/index)` is not empty returns the first element of the `[Collection](../collection/index)`. In case the `[Collection](../collection/index)` is empty returns the optional default value if provided, if no default value is provided returns undefined.

 

```
first<NSV>(notSetValue?: NSV): T | NSV

```

#### Inherited from


`[Collection#first()](../collection/index#first())`



#### [last()](index#last())




In case the `[Collection](../collection/index)` is not empty returns the last element of the `[Collection](../collection/index)`. In case the `[Collection](../collection/index)` is empty returns the optional default value if provided, if no default value is provided returns undefined.

 

```
last<NSV>(notSetValue?: NSV): T | NSV

```

#### Inherited from


`[Collection#last()](../collection/index#last())`


### Persistent changes



#### [clear()](index#clear())




Returns a new Stack with 0 size and no values.

 

```
clear(): Stack<T>

```

#### Discussion



Note: `[clear](index#clear())` can be used in `[withMutations](index#withMutations())`.

 



#### [unshift()](index#unshift())




Returns a new Stack with the provided `values` prepended, shifting other values ahead to higher indices.

 

```
unshift(...values: Array<T>): Stack<T>

```

#### Discussion



This is very efficient for Stack.

 Note: `[unshift](index#unshift())` can be used in `[withMutations](index#withMutations())`.

 



#### [unshiftAll()](index#unshiftAll())




Like `[Stack#unshift](index#unshift())`, but accepts a collection rather than varargs.

 

```
unshiftAll(iter: Iterable<T>): Stack<T>

```

#### Discussion



Note: `[unshiftAll](index#unshiftAll())` can be used in `[withMutations](index#withMutations())`.

 



#### [shift()](index#shift())




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.

 

```
shift(): Stack<T>

```

#### Discussion



Note: this differs from `[Array#shift](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/shift)` because it returns a new Stack rather than the removed value. Use `[first()](index#first())` or `[peek()](index#peek())` to get the first value in this Stack.

 Note: `[shift](index#shift())` can be used in `[withMutations](index#withMutations())`.

 



#### [push()](index#push())




Alias for `[Stack#unshift](index#unshift())` and is not equivalent to `[List#push](../list/index#push())`.

 

```
push(...values: Array<T>): Stack<T>

```




#### [pushAll()](index#pushAll())




Alias for `[Stack#unshiftAll](index#unshiftAll())`.

 

```
pushAll(iter: Iterable<T>): Stack<T>

```




#### [pop()](index#pop())




Alias for `[Stack#shift](index#shift())` and is not equivalent to `[List#pop](../list/index#pop())`.

 

```
pop(): Stack<T>

```




#### [update()](index#update())




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".

 

```
update<R>(updater: (value: this) => R): R

```

#### Inherited from


`[Collection#update()](../collection/index#update())`#### Discussion



For example, to sum a Seq after mapping and filtering:

 
```
const { Seq } = require('immutable')

function sum(collection) {
  return collection.reduce((sum, x) => sum + x, 0)
}
Seq([ 1, 2, 3 ])
  .map(x => x + 1)
  .filter(x => x % 2 === 0)
  .update(sum)
// 6run it
```
 


### Transient changes



#### [withMutations()](index#withMutations())




Note: Not all methods can be used on a mutable collection or within `[withMutations](index#withMutations())`! Check the documentation for each method to see if it mentions being safe to use in `[withMutations](index#withMutations())`.

 

```
withMutations(mutator: (mutable: this) => unknown): this

```

#### see



`[Map#withMutations](../map/index#withMutations())`

 



#### [asMutable()](index#asMutable())




Note: Not all methods can be used on a mutable collection or within `[withMutations](index#withMutations())`! Check the documentation for each method to see if it mentions being safe to use in `[withMutations](index#withMutations())`.

 

```
asMutable(): this

```

#### see



`[Map#asMutable](../map/index#asMutable())`

 



#### [wasAltered()](index#wasAltered())




```
wasAltered(): boolean

```

#### see



`[Map#wasAltered](../map/index#wasAltered())`

 



#### [asImmutable()](index#asImmutable())




```
asImmutable(): this

```

#### see



`[Map#asImmutable](../map/index#asImmutable())`

 


### Sequence algorithms



#### [concat()](index#concat())




Returns a new Stack with other collections concatenated to this one.

 

```
concat<C>(...valuesOrCollections: Array<Iterable<C> | C>): Stack<T | C>

```

#### Overrides


`[Collection.Indexed#concat()](../collection.indexed/index#concat())`



#### [map()](index#map())




Returns a new Stack with values passed through a `mapper` function.

 

```
map<M>(mapper: (value: T, key: number, iter: this) => M,context?: unknown): Stack<M>

```

#### Overrides


`[Collection.Indexed#map()](../collection.indexed/index#map())`#### Example




```
Stack([ 1, 2 ]).map(x => 10 * x)
// Stack [ 10, 20 ]
```

Note: `[map()](index#map())` always returns a new instance, even if it produced the same value at every step.

 



#### [flatMap()](index#flatMap())




Flat-maps the Stack, returning a new Stack.

 

```
flatMap<M>(mapper: (value: T, key: number, iter: this) => Iterable<M>,context?: unknown): Stack<M>

```

#### Overrides


`[Collection.Indexed#flatMap()](../collection.indexed/index#flatMap())`#### Discussion



Similar to `stack.map(...).flatten(true)`.

 



#### [filter()](index#filter())




```
filter<F>(predicate: (value: T, index: number, iter: this) => boolean,context?: unknown): Set<F>
filter(predicate: (value: T, index: number, iter: this) => unknown,context?: unknown): this

```

#### Overrides


`[Collection.Indexed#filter()](../collection.indexed/index#filter())`



#### [zip()](index#zip())




```
zip<U>(other: Collection<unknown, U>): Stack<[T, U]>
zip<U, V>(other: Collection<unknown, U>,other2: Collection<unknown, V>): Stack<[T, U, V]>
zip(...collections: Array<Collection<unknown, unknown>>): Stack<unknown>

```

#### Overrides


`[Collection.Indexed#zip()](../collection.indexed/index#zip())`



#### [zipAll()](index#zipAll())




```
zipAll<U>(other: Collection<unknown, U>): Stack<[T, U]>
zipAll<U, V>(other: Collection<unknown, U>,other2: Collection<unknown, V>): Stack<[T, U, V]>
zipAll(...collections: Array<Collection<unknown, unknown>>): Stack<unknown>

```

#### Overrides


`[Collection.Indexed#zipAll()](../collection.indexed/index#zipAll())`



#### [zipWith()](index#zipWith())




```
zipWith<U, Z>(zipper: (value: T, otherValue: U) => Z,otherCollection: Collection<unknown, U>): Stack<Z>
zipWith<U, V, Z>(zipper: (value: T, otherValue: U, thirdValue: V) => Z,otherCollection: Collection<unknown, U>,thirdCollection: Collection<unknown, V>): Stack<Z>
zipWith<Z>(zipper: (...values: Array<unknown>) => Z,...collections: Array<Collection<unknown, unknown>>): Stack<Z>

```

#### Overrides


`[Collection.Indexed#zipWith()](../collection.indexed/index#zipWith())`



#### [partition()](index#partition())




```
partition<F, C>(predicate: (this: C, value: T, index: number, iter: this) => boolean,context?: C): [Collection.Indexed<T>, Collection.Indexed<F>]
partition<C>(predicate: (this: C, value: T, index: number, iter: this) => unknown,context?: C): [this, this]

```

#### Inherited from


`[Collection.Indexed#partition()](../collection.indexed/index#partition())`



#### [[Symbol.iterator]()](index#%5BSymbol.iterator%5D())




```
[Symbol.iterator](): IterableIterator<T>

```

#### Inherited from


`[Collection.Indexed#[Symbol.iterator]()](../collection.indexed/index#%5BSymbol.iterator%5D())`



#### [filterNot()](index#filterNot())




Returns a new Collection of the same type with only the entries for which the `predicate` function returns false.

 

```
filterNot(predicate: (value: T, key: number, iter: this) => boolean,context?: unknown): this

```

#### Inherited from


`[Collection#filterNot()](../collection/index#filterNot())`#### Discussion


 
```
const { Map } = require('immutable')
Map({ a: 1, b: 2, c: 3, d: 4}).filterNot(x => x % 2 === 0)
// Map { "a": 1, "c": 3 }run it
```



Note: `[filterNot()](../list/index#filterNot())` always returns a new instance, even if it results in not filtering out any values.

 



#### [reverse()](index#reverse())




Returns a new Collection of the same type in reverse order.

 

```
reverse(): this

```

#### Inherited from


`[Collection#reverse()](../collection/index#reverse())`



#### [sort()](index#sort())




Returns a new Collection of the same type which includes the same entries, stably sorted by using a `comparator`.

 

```
sort(comparator?: (valueA: T, valueB: T) => number): this

```

#### Inherited from


`[Collection#sort()](../collection/index#sort())`#### Discussion



If a `comparator` is not provided, a default comparator uses `<` and `>`.

 `comparator(valueA, valueB)`:

 * Returns `0` if the elements should not be swapped.
* Returns `-1` (or any negative number) if `valueA` comes before `valueB`
* Returns `1` (or any positive number) if `valueA` comes after `valueB`
* Is pure, i.e. it must always return the same value for the same pair of values.

 When sorting collections which have no defined order, their ordered equivalents will be returned. e.g. `map.sort()` returns OrderedMap.

 
```
const { Map } = require('immutable')
Map({ "c": 3, "a": 1, "b": 2 }).sort((a, b) => {
  if (a < b) { return -1; }
  if (a > b) { return 1; }
  if (a === b) { return 0; }
});
// OrderedMap { "a": 1, "b": 2, "c": 3 }run it
```

Note: `[sort()](../list/index#sort())` Always returns a new instance, even if the original was already sorted.

 Note: This is always an eager operation.

 



#### [sortBy()](index#sortBy())




Like `[sort](../list/index#sort())`, but also accepts a `comparatorValueMapper` which allows for sorting by more sophisticated means:

 

```
sortBy<C>(comparatorValueMapper: (value: T, key: number, iter: this) => C,comparator?: (valueA: C, valueB: C) => number): this

```

#### Inherited from


`[Collection#sortBy()](../collection/index#sortBy())`#### Discussion


 
```
const { Map } = require('immutable')
const beattles = Map({
  John: { name: "Lennon" },
  Paul: { name: "McCartney" },
  George: { name: "Harrison" },
  Ringo: { name: "Starr" },
});
beattles.sortBy(member => member.name);run it
```



Note: `[sortBy()](../list/index#sortBy())` Always returns a new instance, even if the original was already sorted.

 Note: This is always an eager operation.

 



#### [groupBy()](index#groupBy())




Returns a `[Collection.Keyed](../collection.keyed/index)` of `Collection.Keyeds`, grouped by the return value of the `grouper` function.

 

```
groupBy<G>(grouper: (value: T, key: number, iter: this) => G,context?: unknown): Seq.Keyed<G, Collection<number, T>>

```

#### Inherited from


`[Collection#groupBy()](../collection/index#groupBy())`#### Discussion



Note: This is always an eager operation.

 
```
const { List, Map } = require('immutable')
const listOfMaps = List([
  Map({ v: 0 }),
  Map({ v: 1 }),
  Map({ v: 1 }),
  Map({ v: 0 }),
  Map({ v: 2 })
])
const groupsOfMaps = listOfMaps.groupBy(x => x.get('v'))
// Map {
//   0: List [ Map{ "v": 0 }, Map { "v": 0 } ],
//   1: List [ Map{ "v": 1 }, Map { "v": 1 } ],
//   2: List [ Map{ "v": 2 } ],
// }run it
```




### Conversion to JavaScript types



#### [toJS()](index#toJS())




Deeply converts this Indexed collection to equivalent native JavaScript Array.

 

```
toJS(): Array<DeepCopy<T>>

```

#### Inherited from


`[Collection.Indexed#toJS()](../collection.indexed/index#toJS())`



#### [toJSON()](index#toJSON())




Shallowly converts this Indexed collection to equivalent native JavaScript Array.

 

```
toJSON(): Array<T>

```

#### Inherited from


`[Collection.Indexed#toJSON()](../collection.indexed/index#toJSON())`



#### [toArray()](index#toArray())




Shallowly converts this collection to an Array.

 

```
toArray(): Array<T>

```

#### Inherited from


`[Collection.Indexed#toArray()](../collection.indexed/index#toArray())`



#### [toObject()](index#toObject())




Shallowly converts this Collection to an Object.

 

```
toObject(): {[key: string]: T}

```

#### Inherited from


`[Collection#toObject()](../collection/index#toObject())`#### Discussion



Converts keys to Strings.

 


### Conversion to Seq



#### [toSeq()](index#toSeq())




Returns Seq.Indexed.

 

```
toSeq(): Seq.Indexed<T>

```

#### Inherited from


`[Collection.Indexed#toSeq()](../collection.indexed/index#toSeq())`



#### [fromEntrySeq()](index#fromEntrySeq())




If this is a collection of [key, value] entry tuples, it will return a Seq.Keyed of those entries.

 

```
fromEntrySeq(): Seq.Keyed<unknown, unknown>

```

#### Inherited from


`[Collection.Indexed#fromEntrySeq()](../collection.indexed/index#fromEntrySeq())`



#### [toKeyedSeq()](index#toKeyedSeq())




Returns a Seq.Keyed from this Collection where indices are treated as keys.

 

```
toKeyedSeq(): Seq.Keyed<number, T>

```

#### Inherited from


`[Collection#toKeyedSeq()](../collection/index#toKeyedSeq())`#### Discussion



This is useful if you want to operate on an Collection.Indexed and preserve the [index, value] pairs.

 The returned Seq will have identical iteration order as this Collection.

 
```
const { Seq } = require('immutable')
const indexedSeq = Seq([ 'A', 'B', 'C' ])
// Seq [ "A", "B", "C" ]
indexedSeq.filter(v => v === 'B')
// Seq [ "B" ]
const keyedSeq = indexedSeq.toKeyedSeq()
// Seq { 0: "A", 1: "B", 2: "C" }
keyedSeq.filter(v => v === 'B')
// Seq { 1: "B" }run it
```





#### [toIndexedSeq()](index#toIndexedSeq())




Returns an Seq.Indexed of the values of this Collection, discarding keys.

 

```
toIndexedSeq(): Seq.Indexed<T>

```

#### Inherited from


`[Collection#toIndexedSeq()](../collection/index#toIndexedSeq())`



#### [toSetSeq()](index#toSetSeq())




Returns a Seq.Set of the values of this Collection, discarding keys.

 

```
toSetSeq(): Seq.Set<T>

```

#### Inherited from


`[Collection#toSetSeq()](../collection/index#toSetSeq())`


### Combination



#### [interpose()](index#interpose())




Returns a Collection of the same type with `separator` between each item in this Collection.

 

```
interpose(separator: T): this

```

#### Inherited from


`[Collection.Indexed#interpose()](../collection.indexed/index#interpose())`



#### [interleave()](index#interleave())




Returns a Collection of the same type with the provided `collections` interleaved into this collection.

 

```
interleave(...collections: Array<Collection<unknown, T>>): this

```

#### Inherited from


`[Collection.Indexed#interleave()](../collection.indexed/index#interleave())`#### Discussion



The resulting Collection includes the first item from each, then the second from each, etc.

 
```
const { List } = require('immutable')
List([ 1, 2, 3 ]).interleave(List([ 'A', 'B', 'C' ]))
// List [ 1, "A", 2, "B", 3, "C" ]run it
```

The shortest Collection stops interleave.

 
```
List([ 1, 2, 3 ]).interleave(
  List([ 'A', 'B' ]),
  List([ 'X', 'Y', 'Z' ])
)
// List [ 1, "A", "X", 2, "B", "Y" ]run it
```

Since `[interleave()](../list/index#interleave())` re-indexes values, it produces a complete copy, which has `O(N)` complexity.

 Note: `[interleave](../list/index#interleave())` *cannot* be used in `[withMutations](../list/index#withMutations())`.

 



#### [splice()](index#splice())




Splice returns a new indexed Collection by replacing a region of this Collection with new values. If values are not provided, it only skips the region to be removed.

 

```
splice(index: number, removeNum: number, ...values: Array<T>): this

```

#### Inherited from


`[Collection.Indexed#splice()](../collection.indexed/index#splice())`#### Discussion



`index` may be a negative number, which indexes back from the end of the Collection. `s.splice(-2)` splices after the second to last item.

 
```
const { List } = require('immutable')
List([ 'a', 'b', 'c', 'd' ]).splice(1, 2, 'q', 'r', 's')
// List [ "a", "q", "r", "s", "d" ]run it
```

Since `[splice()](../list/index#splice())` re-indexes values, it produces a complete copy, which has `O(N)` complexity.

 Note: `[splice](../list/index#splice())` *cannot* be used in `[withMutations](../list/index#withMutations())`.

 



#### [flatten()](index#flatten())




```
flatten(depth?: number): Collection<unknown, unknown>
flatten(shallow?: boolean): Collection<unknown, unknown>

```

#### Inherited from


`[Collection#flatten()](../collection/index#flatten())`


### Search for value



#### [indexOf()](index#indexOf())




Returns the first index at which a given value can be found in the Collection, or -1 if it is not present.

 

```
indexOf(searchValue: T): number

```

#### Inherited from


`[Collection.Indexed#indexOf()](../collection.indexed/index#indexOf())`



#### [lastIndexOf()](index#lastIndexOf())




Returns the last index at which a given value can be found in the Collection, or -1 if it is not present.

 

```
lastIndexOf(searchValue: T): number

```

#### Inherited from


`[Collection.Indexed#lastIndexOf()](../collection.indexed/index#lastIndexOf())`



#### [findIndex()](index#findIndex())




Returns the first index in the Collection where a value satisfies the provided predicate function. Otherwise -1 is returned.

 

```
findIndex(predicate: (value: T, index: number, iter: this) => boolean,context?: unknown): number

```

#### Inherited from


`[Collection.Indexed#findIndex()](../collection.indexed/index#findIndex())`



#### [findLastIndex()](index#findLastIndex())




Returns the last index in the Collection where a value satisfies the provided predicate function. Otherwise -1 is returned.

 

```
findLastIndex(predicate: (value: T, index: number, iter: this) => boolean,context?: unknown): number

```

#### Inherited from


`[Collection.Indexed#findLastIndex()](../collection.indexed/index#findLastIndex())`



#### [find()](index#find())




Returns the first value for which the `predicate` returns true.

 

```
find(predicate: (value: T, key: number, iter: this) => boolean,context?: unknown,notSetValue?: T): T | undefined

```

#### Inherited from


`[Collection#find()](../collection/index#find())`



#### [findLast()](index#findLast())




Returns the last value for which the `predicate` returns true.

 

```
findLast(predicate: (value: T, key: number, iter: this) => boolean,context?: unknown,notSetValue?: T): T | undefined

```

#### Inherited from


`[Collection#findLast()](../collection/index#findLast())`#### Discussion



Note: `predicate` will be called for each entry in reverse.

 



#### [findEntry()](index#findEntry())




Returns the first [key, value] entry for which the `predicate` returns true.

 

```
findEntry(predicate: (value: T, key: number, iter: this) => boolean,context?: unknown,notSetValue?: T): [number, T] | undefined

```

#### Inherited from


`[Collection#findEntry()](../collection/index#findEntry())`



#### [findLastEntry()](index#findLastEntry())




Returns the last [key, value] entry for which the `predicate` returns true.

 

```
findLastEntry(predicate: (value: T, key: number, iter: this) => boolean,context?: unknown,notSetValue?: T): [number, T] | undefined

```

#### Inherited from


`[Collection#findLastEntry()](../collection/index#findLastEntry())`#### Discussion



Note: `predicate` will be called for each entry in reverse.

 



#### [findKey()](index#findKey())




Returns the key for which the `predicate` returns true.

 

```
findKey(predicate: (value: T, key: number, iter: this) => boolean,context?: unknown): number | undefined

```

#### Inherited from


`[Collection#findKey()](../collection/index#findKey())`



#### [findLastKey()](index#findLastKey())




Returns the last key for which the `predicate` returns true.

 

```
findLastKey(predicate: (value: T, key: number, iter: this) => boolean,context?: unknown): number | undefined

```

#### Inherited from


`[Collection#findLastKey()](../collection/index#findLastKey())`#### Discussion



Note: `predicate` will be called for each entry in reverse.

 



#### [keyOf()](index#keyOf())




Returns the key associated with the search value, or undefined.

 

```
keyOf(searchValue: T): number | undefined

```

#### Inherited from


`[Collection#keyOf()](../collection/index#keyOf())`



#### [lastKeyOf()](index#lastKeyOf())




Returns the last key associated with the search value, or undefined.

 

```
lastKeyOf(searchValue: T): number | undefined

```

#### Inherited from


`[Collection#lastKeyOf()](../collection/index#lastKeyOf())`



#### [max()](index#max())




Returns the maximum value in this collection. If any values are comparatively equivalent, the first one found will be returned.

 

```
max(comparator?: (valueA: T, valueB: T) => number): T | undefined

```

#### Inherited from


`[Collection#max()](../collection/index#max())`#### Discussion



The `comparator` is used in the same way as `[Collection#sort](../collection/index#sort())`. If it is not provided, the default comparator is `>`.

 When two values are considered equivalent, the first encountered will be returned. Otherwise, `[max](../list/index#max())` will operate independent of the order of input as long as the comparator is commutative. The default comparator `>` is commutative *only* when types do not differ.

 If `comparator` returns 0 and either value is NaN, undefined, or null, that value will be returned.

 



#### [maxBy()](index#maxBy())




Like `[max](../list/index#max())`, but also accepts a `comparatorValueMapper` which allows for comparing by more sophisticated means:

 

```
maxBy<C>(comparatorValueMapper: (value: T, key: number, iter: this) => C,comparator?: (valueA: C, valueB: C) => number): T | undefined

```

#### Inherited from


`[Collection#maxBy()](../collection/index#maxBy())`#### Discussion


 
```
const { List, } = require('immutable');
const l = List([
  { name: 'Bob', avgHit: 1 },
  { name: 'Max', avgHit: 3 },
  { name: 'Lili', avgHit: 2 } ,
]);
l.maxBy(i => i.avgHit); // will output { name: 'Max', avgHit: 3 }run it
```


 



#### [min()](index#min())




Returns the minimum value in this collection. If any values are comparatively equivalent, the first one found will be returned.

 

```
min(comparator?: (valueA: T, valueB: T) => number): T | undefined

```

#### Inherited from


`[Collection#min()](../collection/index#min())`#### Discussion



The `comparator` is used in the same way as `[Collection#sort](../collection/index#sort())`. If it is not provided, the default comparator is `<`.

 When two values are considered equivalent, the first encountered will be returned. Otherwise, `[min](../list/index#min())` will operate independent of the order of input as long as the comparator is commutative. The default comparator `<` is commutative *only* when types do not differ.

 If `comparator` returns 0 and either value is NaN, undefined, or null, that value will be returned.

 



#### [minBy()](index#minBy())




Like `[min](../list/index#min())`, but also accepts a `comparatorValueMapper` which allows for comparing by more sophisticated means:

 

```
minBy<C>(comparatorValueMapper: (value: T, key: number, iter: this) => C,comparator?: (valueA: C, valueB: C) => number): T | undefined

```

#### Inherited from


`[Collection#minBy()](../collection/index#minBy())`#### Discussion


 
```
const { List, } = require('immutable');
const l = List([
  { name: 'Bob', avgHit: 1 },
  { name: 'Max', avgHit: 3 },
  { name: 'Lili', avgHit: 2 } ,
]);
l.minBy(i => i.avgHit); // will output { name: 'Bob', avgHit: 1 }run it
```


 


### Value equality



#### [equals()](index#equals())




True if this and the other Collection have value equality, as defined by `[Immutable.is()](../is()/index)`.

 

```
equals(other: unknown): boolean

```

#### Inherited from


`[Collection#equals()](../collection/index#equals())`#### Discussion



Note: This is equivalent to `Immutable.is(this, other)`, but provided to allow for chained expressions.

 



#### [hashCode()](index#hashCode())




Computes and returns the hashed identity for this Collection.

 

```
hashCode(): number

```

#### Inherited from


`[Collection#hashCode()](../collection/index#hashCode())`#### Discussion



The `[hashCode](../list/index#hashCode())` of a Collection is used to determine potential equality, and is used when adding this to a `[Set](../set/index)` or as a key in a `[Map](../map/index)`, enabling lookup via a different instance.

 
```
const a = List([ 1, 2, 3 ]);
const b = List([ 1, 2, 3 ]);
assert.notStrictEqual(a, b); // different instances
const set = Set([ a ]);
assert.equal(set.has(b), true);run it
```

If two values have the same `[hashCode](../list/index#hashCode())`, they are [not guaranteed to be equal](https://en.wikipedia.org/wiki/Collision_(computer_science)). If two values have different `[hashCode](../list/index#hashCode())`s, they must not be equal.

 


### Reading deep values



#### [getIn()](index#getIn())




Returns the value found by following a path of keys or indices through nested Collections.

 

```
getIn(searchKeyPath: Iterable<unknown>, notSetValue?: unknown): unknown

```

#### Inherited from


`[Collection#getIn()](../collection/index#getIn())`#### Discussion


 
```
const { Map, List } = require('immutable')
const deepData = Map({ x: List([ Map({ y: 123 }) ]) });
deepData.getIn(['x', 0, 'y']) // 123run it
```



Plain JavaScript Object or Arrays may be nested within an Immutable.js Collection, and getIn() can access those values as well:

 
```
const { Map, List } = require('immutable')
const deepData = Map({ x: [ { y: 123 } ] });
deepData.getIn(['x', 0, 'y']) // 123run it
```


 



#### [hasIn()](index#hasIn())




True if the result of following a path of keys or indices through nested Collections results in a set value.

 

```
hasIn(searchKeyPath: Iterable<unknown>): boolean

```

#### Inherited from


`[Collection#hasIn()](../collection/index#hasIn())`


### Conversion to Collections



#### [toMap()](index#toMap())




Converts this Collection to a Map, Throws if keys are not hashable.

 

```
toMap(): Map<number, T>

```

#### Inherited from


`[Collection#toMap()](../collection/index#toMap())`#### Discussion



Note: This is equivalent to `Map(this.toKeyedSeq())`, but provided for convenience and to allow for chained expressions.

 



#### [toOrderedMap()](index#toOrderedMap())




Converts this Collection to a Map, maintaining the order of iteration.

 

```
toOrderedMap(): OrderedMap<number, T>

```

#### Inherited from


`[Collection#toOrderedMap()](../collection/index#toOrderedMap())`#### Discussion



Note: This is equivalent to `OrderedMap(this.toKeyedSeq())`, but provided for convenience and to allow for chained expressions.

 



#### [toSet()](index#toSet())




Converts this Collection to a Set, discarding keys. Throws if values are not hashable.

 

```
toSet(): Set<T>

```

#### Inherited from


`[Collection#toSet()](../collection/index#toSet())`#### Discussion



Note: This is equivalent to `[Set(this)](../set/index)`, but provided to allow for chained expressions.

 



#### [toOrderedSet()](index#toOrderedSet())




Converts this Collection to a Set, maintaining the order of iteration and discarding keys.

 

```
toOrderedSet(): OrderedSet<T>

```

#### Inherited from


`[Collection#toOrderedSet()](../collection/index#toOrderedSet())`#### Discussion



Note: This is equivalent to `OrderedSet(this.valueSeq())`, but provided for convenience and to allow for chained expressions.

 



#### [toList()](index#toList())




Converts this Collection to a List, discarding keys.

 

```
toList(): List<T>

```

#### Inherited from


`[Collection#toList()](../collection/index#toList())`#### Discussion



This is similar to `[List(collection)](../list/index)`, but provided to allow for chained expressions. However, when called on `[Map](../map/index)` or other keyed collections, `collection.toList()` discards the keys and creates a list of only the values, whereas `[List(collection)](../list/index)` creates a list of entry tuples.

 
```
const { Map, List } = require('immutable')
var myMap = Map({ a: 'Apple', b: 'Banana' })
List(myMap) // List [ [ "a", "Apple" ], [ "b", "Banana" ] ]
myMap.toList() // List [ "Apple", "Banana" ]run it
```





#### [toStack()](index#toStack())




Converts this Collection to a Stack, discarding keys. Throws if values are not hashable.

 

```
toStack(): Stack<T>

```

#### Inherited from


`[Collection#toStack()](../collection/index#toStack())`#### Discussion



Note: This is equivalent to `[Stack(this)](index)`, but provided to allow for chained expressions.

 


### Iterators



#### [keys()](index#keys())




An iterator of this `[Collection](../collection/index)`'s keys.

 

```
keys(): IterableIterator<number>

```

#### Inherited from


`[Collection#keys()](../collection/index#keys())`#### Discussion



Note: this will return an ES6 iterator which does not support Immutable.js sequence algorithms. Use `[keySeq](../list/index#keySeq())` instead, if this is what you want.

 



#### [values()](index#values())




An iterator of this `[Collection](../collection/index)`'s values.

 

```
values(): IterableIterator<T>

```

#### Inherited from


`[Collection#values()](../collection/index#values())`#### Discussion



Note: this will return an ES6 iterator which does not support Immutable.js sequence algorithms. Use `[valueSeq](../list/index#valueSeq())` instead, if this is what you want.

 



#### [entries()](index#entries())




An iterator of this `[Collection](../collection/index)`'s entries as `[ key, value ]` tuples.

 

```
entries(): IterableIterator<[number, T]>

```

#### Inherited from


`[Collection#entries()](../collection/index#entries())`#### Discussion



Note: this will return an ES6 iterator which does not support Immutable.js sequence algorithms. Use `[entrySeq](../list/index#entrySeq())` instead, if this is what you want.

 


### Collections (Seq)



#### [keySeq()](index#keySeq())




Returns a new Seq.Indexed of the keys of this Collection, discarding values.

 

```
keySeq(): Seq.Indexed<number>

```

#### Inherited from


`[Collection#keySeq()](../collection/index#keySeq())`



#### [valueSeq()](index#valueSeq())




Returns an Seq.Indexed of the values of this Collection, discarding keys.

 

```
valueSeq(): Seq.Indexed<T>

```

#### Inherited from


`[Collection#valueSeq()](../collection/index#valueSeq())`



#### [entrySeq()](index#entrySeq())




Returns a new Seq.Indexed of [key, value] tuples.

 

```
entrySeq(): Seq.Indexed<[number, T]>

```

#### Inherited from


`[Collection#entrySeq()](../collection/index#entrySeq())`


### Side effects



#### [forEach()](index#forEach())




The `sideEffect` is executed for every entry in the Collection.

 

```
forEach(sideEffect: (value: T, key: number, iter: this) => unknown,context?: unknown): number

```

#### Inherited from


`[Collection#forEach()](../collection/index#forEach())`#### Discussion



Unlike `[Array#forEach](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/forEach)`, if any call of `sideEffect` returns `false`, the iteration will stop. Returns the number of entries iterated (including the last iteration which returned false).

 


### Creating subsets



#### [slice()](index#slice())




Returns a new Collection of the same type representing a portion of this Collection from start up to but not including end.

 

```
slice(begin?: number, end?: number): this

```

#### Inherited from


`[Collection#slice()](../collection/index#slice())`#### Discussion



If begin is negative, it is offset from the end of the Collection. e.g. `slice(-2)` returns a Collection of the last two entries. If it is not provided the new Collection will begin at the beginning of this Collection.

 If end is negative, it is offset from the end of the Collection. e.g. `slice(0, -1)` returns a Collection of everything but the last entry. If it is not provided, the new Collection will continue through the end of this Collection.

 If the requested slice is equivalent to the current Collection, then it will return itself.

 



#### [rest()](index#rest())




Returns a new Collection of the same type containing all entries except the first.

 

```
rest(): this

```

#### Inherited from


`[Collection#rest()](../collection/index#rest())`



#### [butLast()](index#butLast())




Returns a new Collection of the same type containing all entries except the last.

 

```
butLast(): this

```

#### Inherited from


`[Collection#butLast()](../collection/index#butLast())`



#### [skip()](index#skip())




Returns a new Collection of the same type which excludes the first `amount` entries from this Collection.

 

```
skip(amount: number): this

```

#### Inherited from


`[Collection#skip()](../collection/index#skip())`



#### [skipLast()](index#skipLast())




Returns a new Collection of the same type which excludes the last `amount` entries from this Collection.

 

```
skipLast(amount: number): this

```

#### Inherited from


`[Collection#skipLast()](../collection/index#skipLast())`



#### [skipWhile()](index#skipWhile())




Returns a new Collection of the same type which includes entries starting from when `predicate` first returns false.

 

```
skipWhile(predicate: (value: T, key: number, iter: this) => boolean,context?: unknown): this

```

#### Inherited from


`[Collection#skipWhile()](../collection/index#skipWhile())`#### Discussion


 
```
const { List } = require('immutable')
List([ 'dog', 'frog', 'cat', 'hat', 'god' ])
  .skipWhile(x => x.match(/g/))
// List [ "cat", "hat", "god" ]run it
```


 



#### [skipUntil()](index#skipUntil())




Returns a new Collection of the same type which includes entries starting from when `predicate` first returns true.

 

```
skipUntil(predicate: (value: T, key: number, iter: this) => boolean,context?: unknown): this

```

#### Inherited from


`[Collection#skipUntil()](../collection/index#skipUntil())`#### Discussion


 
```
const { List } = require('immutable')
List([ 'dog', 'frog', 'cat', 'hat', 'god' ])
  .skipUntil(x => x.match(/hat/))
// List [ "hat", "god" ]run it
```


 



#### [take()](index#take())




Returns a new Collection of the same type which includes the first `amount` entries from this Collection.

 

```
take(amount: number): this

```

#### Inherited from


`[Collection#take()](../collection/index#take())`



#### [takeLast()](index#takeLast())




Returns a new Collection of the same type which includes the last `amount` entries from this Collection.

 

```
takeLast(amount: number): this

```

#### Inherited from


`[Collection#takeLast()](../collection/index#takeLast())`



#### [takeWhile()](index#takeWhile())




Returns a new Collection of the same type which includes entries from this Collection as long as the `predicate` returns true.

 

```
takeWhile(predicate: (value: T, key: number, iter: this) => boolean,context?: unknown): this

```

#### Inherited from


`[Collection#takeWhile()](../collection/index#takeWhile())`#### Discussion


 
```
const { List } = require('immutable')
List([ 'dog', 'frog', 'cat', 'hat', 'god' ])
  .takeWhile(x => x.match(/o/))
// List [ "dog", "frog" ]run it
```


 



#### [takeUntil()](index#takeUntil())




Returns a new Collection of the same type which includes entries from this Collection as long as the `predicate` returns false.

 

```
takeUntil(predicate: (value: T, key: number, iter: this) => boolean,context?: unknown): this

```

#### Inherited from


`[Collection#takeUntil()](../collection/index#takeUntil())`#### Discussion


 
```
const { List } = require('immutable')
List([ 'dog', 'frog', 'cat', 'hat', 'god' ])
  .takeUntil(x => x.match(/at/))
// List [ "dog", "frog" ]run it
```


 


### Reducing a value



#### [reduce()](index#reduce())




```
reduce<R>(reducer: (reduction: R, value: T, key: number, iter: this) => R,initialReduction: R,context?: unknown): R
reduce<R>(reducer: (reduction: T | R, value: T, key: number, iter: this) => R): R

```

#### Inherited from


`[Collection#reduce()](../collection/index#reduce())`



#### [reduceRight()](index#reduceRight())




```
reduceRight<R>(reducer: (reduction: R, value: T, key: number, iter: this) => R,initialReduction: R,context?: unknown): R
reduceRight<R>(reducer: (reduction: T | R, value: T, key: number, iter: this) => R): R

```

#### Inherited from


`[Collection#reduceRight()](../collection/index#reduceRight())`



#### [every()](index#every())




True if `predicate` returns true for all entries in the Collection.

 

```
every(predicate: (value: T, key: number, iter: this) => boolean,context?: unknown): boolean

```

#### Inherited from


`[Collection#every()](../collection/index#every())`



#### [some()](index#some())




True if `predicate` returns true for any entry in the Collection.

 

```
some(predicate: (value: T, key: number, iter: this) => boolean,context?: unknown): boolean

```

#### Inherited from


`[Collection#some()](../collection/index#some())`



#### [join()](index#join())




Joins values together as a string, inserting a separator between each. The default separator is `","`.

 

```
join(separator?: string): string

```

#### Inherited from


`[Collection#join()](../collection/index#join())`



#### [isEmpty()](index#isEmpty())




Returns true if this Collection includes no values.

 

```
isEmpty(): boolean

```

#### Inherited from


`[Collection#isEmpty()](../collection/index#isEmpty())`#### Discussion



For some lazy `[Seq](../seq/index)`, `[isEmpty](../list/index#isEmpty())` might need to iterate to determine emptiness. At most one iteration will occur.

 



#### [count()](index#count())




```
count(): number
count(predicate: (value: T, key: number, iter: this) => boolean,context?: unknown): number

```

#### Inherited from


`[Collection#count()](../collection/index#count())`



#### [countBy()](index#countBy())




Returns a `[Seq.Keyed](../seq.keyed/index)` of counts, grouped by the return value of the `grouper` function.

 

```
countBy<G>(grouper: (value: T, key: number, iter: this) => G,context?: unknown): Map<G, number>

```

#### Inherited from


`[Collection#countBy()](../collection/index#countBy())`#### Discussion



Note: This is not a lazy operation.

 


### Comparison



#### [isSubset()](index#isSubset())




True if `iter` includes every value in this Collection.

 

```
isSubset(iter: Iterable<T>): boolean

```

#### Inherited from


`[Collection#isSubset()](../collection/index#isSubset())`



#### [isSuperset()](index#isSuperset())




True if this Collection includes every value in `iter`.

 

```
isSuperset(iter: Iterable<T>): boolean

```

#### Inherited from


`[Collection#isSuperset()](../collection/index#isSuperset())`

This documentation is generated from [immutable.d.ts](https://github.com/immutable-js/immutable-js/blob/main/type-definitions/immutable.d.ts). Pull requests and [Issues](https://github.com/immutable-js/immutable-js/issues) welcome.

 © 2014–present, Lee Byron and other contributors  
Licensed under the 3-clause BSD License.  

<https://immutable-js.com/docs/v4.2.1/Stack/>

Seq
===



`[Seq](index)` describes a lazy operation, allowing them to efficiently chain use of all the higher-order collection methods (such as `[map](index#map())` and `[filter](index#filter())`) by not creating intermediate collections.

 

```
type Seq<K, V> extends Collection<K, V>
```

#### Discussion



**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](index)` will return a new `[Seq](index)`.

 **Seq is lazy** — `[Seq](index)` 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](../list/index)` or JavaScript `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)`.

 For example, the following performs no work, because the resulting `[Seq](index)`'s values are never iterated:

 
```
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](index)` 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:

 
```
oddSquares.get(1); // 9
```

Any collection can be converted to a lazy Seq with `[Seq()](index)`.

 
```
const { Map } = require('immutable')
const map = Map({ a: 1, b: 2, c: 3 })
const lazySeq = Seq(map)run it
```

`[Seq](index)` allows for the efficient chaining of operations, allowing for the expression of logic that can otherwise be very tedious:

 
```
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](../range()/index)` is a special kind of Lazy sequence.

 
```
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)
// 1006008run it
```

Seq is often used to provide a rich collection API to JavaScript Object.

 
```
Seq({ x: 0, y: 1, z: 2 }).map(v => v * 2).toObject();
// { x: 0, y: 2, z: 4 }
```


### Construction



#### [Seq()](index#Seq())



```
Seq<S>(seq: S): S
Seq<K, V>(collection: Collection.Keyed<K, V>): Seq.Keyed<K, V>
Seq<T>(collection: Collection.Set<T>): Seq.Set<T>
Seq<T>(collection: Collection.Indexed<T> | Iterable<T> | ArrayLike<T>): Seq.Indexed<T>
Seq<V>(obj: {[key: string]: V}): Seq.Keyed<string, V>
Seq<K, V>(): Seq<K, V>

```


### Static methods



#### [Seq.isSeq()](index#isSeq())



```
Seq.isSeq(maybeSeq: unknown): boolean

```


### Members



#### [size](index#size)




Some Seqs can describe their size lazily. When this is the case, size will be an integer. Otherwise it will be undefined.

 

```
size: number | undefined
```

#### Discussion



For example, Seqs returned from `[map()](index#map())` or `[reverse()](index#reverse())` preserve the size of the original `[Seq](index)` while `[filter()](index#filter())` does not.

 Note: `[Range](../range()/index)`, `[Repeat](../repeat()/index)` and `[Seq](index)`s made from `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)`s and `[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)`s will always have a size.

 


### Force evaluation



#### [cacheResult()](index#cacheResult())




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](index#join())` iterates the Seq of three values.

 

```
cacheResult(): this

```

#### Discussion




```
var squares = Seq([ 1, 2, 3 ]).map(x => x  x)
squares.join() + squares.join()
```



If you know a `[Seq](index)` 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](index#cacheResult())`, a Seq will always have a `[size](index#size)`.

 


### Sequence algorithms



#### [map()](index#map())




Returns a new Seq with values passed through a `mapper` function.

 

```
map<M>(mapper: (value: V, key: K, iter: this) => M,context?: unknown): Seq<K, M>
map<M>(mapper: (value: V, key: K, iter: this) => M,context?: unknown): Seq<M, M>

```

#### Overrides


`[Collection#map()](../collection/index#map())`#### Example




```
const { Seq } = require('immutable')
Seq([ 1, 2 ]).map(x => 10 * x)
// Seq [ 10, 20 ]
```

Note: `[map()](index#map())` always returns a new instance, even if it produced the same value at every step. Note: used only for sets.

 



#### [flatMap()](index#flatMap())




Flat-maps the Seq, returning a Seq of the same type.

 

```
flatMap<M>(mapper: (value: V, key: K, iter: this) => Iterable<M>,context?: unknown): Seq<K, M>
flatMap<M>(mapper: (value: V, key: K, iter: this) => Iterable<M>,context?: unknown): Seq<M, M>

```

#### Overrides


`[Collection#flatMap()](../collection/index#flatMap())`#### Discussion



Similar to `seq.map(...).flatten(true)`. Note: Used only for sets.

 



#### [filter()](index#filter())




```
filter<F>(predicate: (value: V, key: K, iter: this) => boolean,context?: unknown): Seq<K, F>
filter(predicate: (value: V, key: K, iter: this) => unknown,context?: unknown): this

```

#### Overrides


`[Collection#filter()](../collection/index#filter())`



#### [partition()](index#partition())




```
partition<F, C>(predicate: (this: C, value: V, key: K, iter: this) => boolean,context?: C): [Seq<K, V>, Seq<K, F>]
partition<C>(predicate: (this: C, value: V, key: K, iter: this) => unknown,context?: C): [this, this]

```

#### Overrides


`[Collection#partition()](../collection/index#partition())`



#### [filterNot()](index#filterNot())




Returns a new Collection of the same type with only the entries for which the `predicate` function returns false.

 

```
filterNot(predicate: (value: V, key: K, iter: this) => boolean,context?: unknown): this

```

#### Inherited from


`[Collection#filterNot()](../collection/index#filterNot())`#### Discussion


 
```
const { Map } = require('immutable')
Map({ a: 1, b: 2, c: 3, d: 4}).filterNot(x => x % 2 === 0)
// Map { "a": 1, "c": 3 }run it
```



Note: `[filterNot()](../list/index#filterNot())` always returns a new instance, even if it results in not filtering out any values.

 



#### [reverse()](index#reverse())




Returns a new Collection of the same type in reverse order.

 

```
reverse(): this

```

#### Inherited from


`[Collection#reverse()](../collection/index#reverse())`



#### [sort()](index#sort())




Returns a new Collection of the same type which includes the same entries, stably sorted by using a `comparator`.

 

```
sort(comparator?: (valueA: V, valueB: V) => number): this

```

#### Inherited from


`[Collection#sort()](../collection/index#sort())`#### Discussion



If a `comparator` is not provided, a default comparator uses `<` and `>`.

 `comparator(valueA, valueB)`:

 * Returns `0` if the elements should not be swapped.
* Returns `-1` (or any negative number) if `valueA` comes before `valueB`
* Returns `1` (or any positive number) if `valueA` comes after `valueB`
* Is pure, i.e. it must always return the same value for the same pair of values.

 When sorting collections which have no defined order, their ordered equivalents will be returned. e.g. `map.sort()` returns OrderedMap.

 
```
const { Map } = require('immutable')
Map({ "c": 3, "a": 1, "b": 2 }).sort((a, b) => {
  if (a < b) { return -1; }
  if (a > b) { return 1; }
  if (a === b) { return 0; }
});
// OrderedMap { "a": 1, "b": 2, "c": 3 }run it
```

Note: `[sort()](../list/index#sort())` Always returns a new instance, even if the original was already sorted.

 Note: This is always an eager operation.

 



#### [sortBy()](index#sortBy())




Like `[sort](../list/index#sort())`, but also accepts a `comparatorValueMapper` which allows for sorting by more sophisticated means:

 

```
sortBy<C>(comparatorValueMapper: (value: V, key: K, iter: this) => C,comparator?: (valueA: C, valueB: C) => number): this

```

#### Inherited from


`[Collection#sortBy()](../collection/index#sortBy())`#### Discussion


 
```
const { Map } = require('immutable')
const beattles = Map({
  John: { name: "Lennon" },
  Paul: { name: "McCartney" },
  George: { name: "Harrison" },
  Ringo: { name: "Starr" },
});
beattles.sortBy(member => member.name);run it
```



Note: `[sortBy()](../list/index#sortBy())` Always returns a new instance, even if the original was already sorted.

 Note: This is always an eager operation.

 



#### [groupBy()](index#groupBy())




Returns a `[Collection.Keyed](../collection.keyed/index)` of `Collection.Keyeds`, grouped by the return value of the `grouper` function.

 

```
groupBy<G>(grouper: (value: V, key: K, iter: this) => G,context?: unknown): Seq.Keyed<G, Collection<K, V>>

```

#### Inherited from


`[Collection#groupBy()](../collection/index#groupBy())`#### Discussion



Note: This is always an eager operation.

 
```
const { List, Map } = require('immutable')
const listOfMaps = List([
  Map({ v: 0 }),
  Map({ v: 1 }),
  Map({ v: 1 }),
  Map({ v: 0 }),
  Map({ v: 2 })
])
const groupsOfMaps = listOfMaps.groupBy(x => x.get('v'))
// Map {
//   0: List [ Map{ "v": 0 }, Map { "v": 0 } ],
//   1: List [ Map{ "v": 1 }, Map { "v": 1 } ],
//   2: List [ Map{ "v": 2 } ],
// }run it
```




### Value equality



#### [equals()](index#equals())




True if this and the other Collection have value equality, as defined by `[Immutable.is()](../is()/index)`.

 

```
equals(other: unknown): boolean

```

#### Inherited from


`[Collection#equals()](../collection/index#equals())`#### Discussion



Note: This is equivalent to `Immutable.is(this, other)`, but provided to allow for chained expressions.

 



#### [hashCode()](index#hashCode())




Computes and returns the hashed identity for this Collection.

 

```
hashCode(): number

```

#### Inherited from


`[Collection#hashCode()](../collection/index#hashCode())`#### Discussion



The `[hashCode](../list/index#hashCode())` of a Collection is used to determine potential equality, and is used when adding this to a `[Set](../set/index)` or as a key in a `[Map](../map/index)`, enabling lookup via a different instance.

 
```
const a = List([ 1, 2, 3 ]);
const b = List([ 1, 2, 3 ]);
assert.notStrictEqual(a, b); // different instances
const set = Set([ a ]);
assert.equal(set.has(b), true);run it
```

If two values have the same `[hashCode](../list/index#hashCode())`, they are [not guaranteed to be equal](https://en.wikipedia.org/wiki/Collision_(computer_science)). If two values have different `[hashCode](../list/index#hashCode())`s, they must not be equal.

 


### Reading values



#### [get()](index#get())




```
get<NSV>(key: K, notSetValue: NSV): V | NSV
get(key: K): V | undefined

```

#### Inherited from


`[Collection#get()](../collection/index#get())`



#### [has()](index#has())




True if a key exists within this `[Collection](../collection/index)`, using `[Immutable.is](../is()/index)` to determine equality

 

```
has(key: K): boolean

```

#### Inherited from


`[Collection#has()](../collection/index#has())`



#### [includes()](index#includes())




True if a value exists within this `[Collection](../collection/index)`, using `[Immutable.is](../is()/index)` to determine equality

 

```
includes(value: V): boolean

```

#### Inherited from


`[Collection#includes()](../collection/index#includes())`#### alias


`contains()`



#### [first()](index#first())




In case the `[Collection](../collection/index)` is not empty returns the first element of the `[Collection](../collection/index)`. In case the `[Collection](../collection/index)` is empty returns the optional default value if provided, if no default value is provided returns undefined.

 

```
first<NSV>(notSetValue?: NSV): V | NSV

```

#### Inherited from


`[Collection#first()](../collection/index#first())`



#### [last()](index#last())




In case the `[Collection](../collection/index)` is not empty returns the last element of the `[Collection](../collection/index)`. In case the `[Collection](../collection/index)` is empty returns the optional default value if provided, if no default value is provided returns undefined.

 

```
last<NSV>(notSetValue?: NSV): V | NSV

```

#### Inherited from


`[Collection#last()](../collection/index#last())`


### Reading deep values



#### [getIn()](index#getIn())




Returns the value found by following a path of keys or indices through nested Collections.

 

```
getIn(searchKeyPath: Iterable<unknown>, notSetValue?: unknown): unknown

```

#### Inherited from


`[Collection#getIn()](../collection/index#getIn())`#### Discussion


 
```
const { Map, List } = require('immutable')
const deepData = Map({ x: List([ Map({ y: 123 }) ]) });
deepData.getIn(['x', 0, 'y']) // 123run it
```



Plain JavaScript Object or Arrays may be nested within an Immutable.js Collection, and getIn() can access those values as well:

 
```
const { Map, List } = require('immutable')
const deepData = Map({ x: [ { y: 123 } ] });
deepData.getIn(['x', 0, 'y']) // 123run it
```


 



#### [hasIn()](index#hasIn())




True if the result of following a path of keys or indices through nested Collections results in a set value.

 

```
hasIn(searchKeyPath: Iterable<unknown>): boolean

```

#### Inherited from


`[Collection#hasIn()](../collection/index#hasIn())`


### Persistent changes



#### [update()](index#update())




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".

 

```
update<R>(updater: (value: this) => R): R

```

#### Inherited from


`[Collection#update()](../collection/index#update())`#### Discussion



For example, to sum a Seq after mapping and filtering:

 
```
const { Seq } = require('immutable')

function sum(collection) {
  return collection.reduce((sum, x) => sum + x, 0)
}
Seq([ 1, 2, 3 ])
  .map(x => x + 1)
  .filter(x => x % 2 === 0)
  .update(sum)
// 6run it
```
 


### Conversion to JavaScript types



#### [toJS()](index#toJS())




Deeply converts this Collection to equivalent native JavaScript Array or Object.

 

```
toJS(): Array<DeepCopy<V>> | {[key: string]: DeepCopy<V>}

```

#### Inherited from


`[Collection#toJS()](../collection/index#toJS())`#### Discussion



`[Collection.Indexed](../collection.indexed/index)`, and `[Collection.Set](../collection.set/index)` become `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)`, while `[Collection.Keyed](../collection.keyed/index)` become `[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)`, converting keys to Strings.

 



#### [toJSON()](index#toJSON())




Shallowly converts this Collection to equivalent native JavaScript Array or Object.

 

```
toJSON(): Array<V> | {[key: string]: V}

```

#### Inherited from


`[Collection#toJSON()](../collection/index#toJSON())`#### Discussion



`[Collection.Indexed](../collection.indexed/index)`, and `[Collection.Set](../collection.set/index)` become `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)`, while `[Collection.Keyed](../collection.keyed/index)` become `[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)`, converting keys to Strings.

 



#### [toArray()](index#toArray())




Shallowly converts this collection to an Array.

 

```
toArray(): Array<V> | Array<[K, V]>

```

#### Inherited from


`[Collection#toArray()](../collection/index#toArray())`#### Discussion



`[Collection.Indexed](../collection.indexed/index)`, and `[Collection.Set](../collection.set/index)` produce an Array of values. `[Collection.Keyed](../collection.keyed/index)` produce an Array of [key, value] tuples.

 



#### [toObject()](index#toObject())




Shallowly converts this Collection to an Object.

 

```
toObject(): {[key: string]: V}

```

#### Inherited from


`[Collection#toObject()](../collection/index#toObject())`#### Discussion



Converts keys to Strings.

 


### Conversion to Collections



#### [toMap()](index#toMap())




Converts this Collection to a Map, Throws if keys are not hashable.

 

```
toMap(): Map<K, V>

```

#### Inherited from


`[Collection#toMap()](../collection/index#toMap())`#### Discussion



Note: This is equivalent to `Map(this.toKeyedSeq())`, but provided for convenience and to allow for chained expressions.

 



#### [toOrderedMap()](index#toOrderedMap())




Converts this Collection to a Map, maintaining the order of iteration.

 

```
toOrderedMap(): OrderedMap<K, V>

```

#### Inherited from


`[Collection#toOrderedMap()](../collection/index#toOrderedMap())`#### Discussion



Note: This is equivalent to `OrderedMap(this.toKeyedSeq())`, but provided for convenience and to allow for chained expressions.

 



#### [toSet()](index#toSet())




Converts this Collection to a Set, discarding keys. Throws if values are not hashable.

 

```
toSet(): Set<V>

```

#### Inherited from


`[Collection#toSet()](../collection/index#toSet())`#### Discussion



Note: This is equivalent to `[Set(this)](../set/index)`, but provided to allow for chained expressions.

 



#### [toOrderedSet()](index#toOrderedSet())




Converts this Collection to a Set, maintaining the order of iteration and discarding keys.

 

```
toOrderedSet(): OrderedSet<V>

```

#### Inherited from


`[Collection#toOrderedSet()](../collection/index#toOrderedSet())`#### Discussion



Note: This is equivalent to `OrderedSet(this.valueSeq())`, but provided for convenience and to allow for chained expressions.

 



#### [toList()](index#toList())




Converts this Collection to a List, discarding keys.

 

```
toList(): List<V>

```

#### Inherited from


`[Collection#toList()](../collection/index#toList())`#### Discussion



This is similar to `[List(collection)](../list/index)`, but provided to allow for chained expressions. However, when called on `[Map](../map/index)` or other keyed collections, `collection.toList()` discards the keys and creates a list of only the values, whereas `[List(collection)](../list/index)` creates a list of entry tuples.

 
```
const { Map, List } = require('immutable')
var myMap = Map({ a: 'Apple', b: 'Banana' })
List(myMap) // List [ [ "a", "Apple" ], [ "b", "Banana" ] ]
myMap.toList() // List [ "Apple", "Banana" ]run it
```





#### [toStack()](index#toStack())




Converts this Collection to a Stack, discarding keys. Throws if values are not hashable.

 

```
toStack(): Stack<V>

```

#### Inherited from


`[Collection#toStack()](../collection/index#toStack())`#### Discussion



Note: This is equivalent to `[Stack(this)](../stack/index)`, but provided to allow for chained expressions.

 


### Conversion to Seq



#### [toSeq()](index#toSeq())




Converts this Collection to a Seq of the same kind (indexed, keyed, or set).

 

```
toSeq(): Seq<K, V>

```

#### Inherited from


`[Collection#toSeq()](../collection/index#toSeq())`



#### [toKeyedSeq()](index#toKeyedSeq())




Returns a Seq.Keyed from this Collection where indices are treated as keys.

 

```
toKeyedSeq(): Seq.Keyed<K, V>

```

#### Inherited from


`[Collection#toKeyedSeq()](../collection/index#toKeyedSeq())`#### Discussion



This is useful if you want to operate on an Collection.Indexed and preserve the [index, value] pairs.

 The returned Seq will have identical iteration order as this Collection.

 
```
const { Seq } = require('immutable')
const indexedSeq = Seq([ 'A', 'B', 'C' ])
// Seq [ "A", "B", "C" ]
indexedSeq.filter(v => v === 'B')
// Seq [ "B" ]
const keyedSeq = indexedSeq.toKeyedSeq()
// Seq { 0: "A", 1: "B", 2: "C" }
keyedSeq.filter(v => v === 'B')
// Seq { 1: "B" }run it
```





#### [toIndexedSeq()](index#toIndexedSeq())




Returns an Seq.Indexed of the values of this Collection, discarding keys.

 

```
toIndexedSeq(): Seq.Indexed<V>

```

#### Inherited from


`[Collection#toIndexedSeq()](../collection/index#toIndexedSeq())`



#### [toSetSeq()](index#toSetSeq())




Returns a Seq.Set of the values of this Collection, discarding keys.

 

```
toSetSeq(): Seq.Set<V>

```

#### Inherited from


`[Collection#toSetSeq()](../collection/index#toSetSeq())`


### Iterators



#### [keys()](index#keys())




An iterator of this `[Collection](../collection/index)`'s keys.

 

```
keys(): IterableIterator<K>

```

#### Inherited from


`[Collection#keys()](../collection/index#keys())`#### Discussion



Note: this will return an ES6 iterator which does not support Immutable.js sequence algorithms. Use `[keySeq](../list/index#keySeq())` instead, if this is what you want.

 



#### [values()](index#values())




An iterator of this `[Collection](../collection/index)`'s values.

 

```
values(): IterableIterator<V>

```

#### Inherited from


`[Collection#values()](../collection/index#values())`#### Discussion



Note: this will return an ES6 iterator which does not support Immutable.js sequence algorithms. Use `[valueSeq](../list/index#valueSeq())` instead, if this is what you want.

 



#### [entries()](index#entries())




An iterator of this `[Collection](../collection/index)`'s entries as `[ key, value ]` tuples.

 

```
entries(): IterableIterator<[K, V]>

```

#### Inherited from


`[Collection#entries()](../collection/index#entries())`#### Discussion



Note: this will return an ES6 iterator which does not support Immutable.js sequence algorithms. Use `[entrySeq](../list/index#entrySeq())` instead, if this is what you want.

 



#### [[Symbol.iterator]()](index#%5BSymbol.iterator%5D())




```
[Symbol.iterator](): IterableIterator<unknown>

```

#### Inherited from


`[Collection#[Symbol.iterator]()](../collection/index#%5BSymbol.iterator%5D())`


### Collections (Seq)



#### [keySeq()](index#keySeq())




Returns a new Seq.Indexed of the keys of this Collection, discarding values.

 

```
keySeq(): Seq.Indexed<K>

```

#### Inherited from


`[Collection#keySeq()](../collection/index#keySeq())`



#### [valueSeq()](index#valueSeq())




Returns an Seq.Indexed of the values of this Collection, discarding keys.

 

```
valueSeq(): Seq.Indexed<V>

```

#### Inherited from


`[Collection#valueSeq()](../collection/index#valueSeq())`



#### [entrySeq()](index#entrySeq())




Returns a new Seq.Indexed of [key, value] tuples.

 

```
entrySeq(): Seq.Indexed<[K, V]>

```

#### Inherited from


`[Collection#entrySeq()](../collection/index#entrySeq())`


### Side effects



#### [forEach()](index#forEach())




The `sideEffect` is executed for every entry in the Collection.

 

```
forEach(sideEffect: (value: V, key: K, iter: this) => unknown,context?: unknown): number

```

#### Inherited from


`[Collection#forEach()](../collection/index#forEach())`#### Discussion



Unlike `[Array#forEach](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/forEach)`, if any call of `sideEffect` returns `false`, the iteration will stop. Returns the number of entries iterated (including the last iteration which returned false).

 


### Creating subsets



#### [slice()](index#slice())




Returns a new Collection of the same type representing a portion of this Collection from start up to but not including end.

 

```
slice(begin?: number, end?: number): this

```

#### Inherited from


`[Collection#slice()](../collection/index#slice())`#### Discussion



If begin is negative, it is offset from the end of the Collection. e.g. `slice(-2)` returns a Collection of the last two entries. If it is not provided the new Collection will begin at the beginning of this Collection.

 If end is negative, it is offset from the end of the Collection. e.g. `slice(0, -1)` returns a Collection of everything but the last entry. If it is not provided, the new Collection will continue through the end of this Collection.

 If the requested slice is equivalent to the current Collection, then it will return itself.

 



#### [rest()](index#rest())




Returns a new Collection of the same type containing all entries except the first.

 

```
rest(): this

```

#### Inherited from


`[Collection#rest()](../collection/index#rest())`



#### [butLast()](index#butLast())




Returns a new Collection of the same type containing all entries except the last.

 

```
butLast(): this

```

#### Inherited from


`[Collection#butLast()](../collection/index#butLast())`



#### [skip()](index#skip())




Returns a new Collection of the same type which excludes the first `amount` entries from this Collection.

 

```
skip(amount: number): this

```

#### Inherited from


`[Collection#skip()](../collection/index#skip())`



#### [skipLast()](index#skipLast())




Returns a new Collection of the same type which excludes the last `amount` entries from this Collection.

 

```
skipLast(amount: number): this

```

#### Inherited from


`[Collection#skipLast()](../collection/index#skipLast())`



#### [skipWhile()](index#skipWhile())




Returns a new Collection of the same type which includes entries starting from when `predicate` first returns false.

 

```
skipWhile(predicate: (value: V, key: K, iter: this) => boolean,context?: unknown): this

```

#### Inherited from


`[Collection#skipWhile()](../collection/index#skipWhile())`#### Discussion


 
```
const { List } = require('immutable')
List([ 'dog', 'frog', 'cat', 'hat', 'god' ])
  .skipWhile(x => x.match(/g/))
// List [ "cat", "hat", "god" ]run it
```


 



#### [skipUntil()](index#skipUntil())




Returns a new Collection of the same type which includes entries starting from when `predicate` first returns true.

 

```
skipUntil(predicate: (value: V, key: K, iter: this) => boolean,context?: unknown): this

```

#### Inherited from


`[Collection#skipUntil()](../collection/index#skipUntil())`#### Discussion


 
```
const { List } = require('immutable')
List([ 'dog', 'frog', 'cat', 'hat', 'god' ])
  .skipUntil(x => x.match(/hat/))
// List [ "hat", "god" ]run it
```


 



#### [take()](index#take())




Returns a new Collection of the same type which includes the first `amount` entries from this Collection.

 

```
take(amount: number): this

```

#### Inherited from


`[Collection#take()](../collection/index#take())`



#### [takeLast()](index#takeLast())




Returns a new Collection of the same type which includes the last `amount` entries from this Collection.

 

```
takeLast(amount: number): this

```

#### Inherited from


`[Collection#takeLast()](../collection/index#takeLast())`



#### [takeWhile()](index#takeWhile())




Returns a new Collection of the same type which includes entries from this Collection as long as the `predicate` returns true.

 

```
takeWhile(predicate: (value: V, key: K, iter: this) => boolean,context?: unknown): this

```

#### Inherited from


`[Collection#takeWhile()](../collection/index#takeWhile())`#### Discussion


 
```
const { List } = require('immutable')
List([ 'dog', 'frog', 'cat', 'hat', 'god' ])
  .takeWhile(x => x.match(/o/))
// List [ "dog", "frog" ]run it
```


 



#### [takeUntil()](index#takeUntil())




Returns a new Collection of the same type which includes entries from this Collection as long as the `predicate` returns false.

 

```
takeUntil(predicate: (value: V, key: K, iter: this) => boolean,context?: unknown): this

```

#### Inherited from


`[Collection#takeUntil()](../collection/index#takeUntil())`#### Discussion


 
```
const { List } = require('immutable')
List([ 'dog', 'frog', 'cat', 'hat', 'god' ])
  .takeUntil(x => x.match(/at/))
// List [ "dog", "frog" ]run it
```


 


### Combination



#### [concat()](index#concat())




Returns a new Collection of the same type with other values and collection-like concatenated to this one.

 

```
concat(...valuesOrCollections: Array<unknown>): Collection<unknown, unknown>

```

#### Inherited from


`[Collection#concat()](../collection/index#concat())`#### Discussion



For Seqs, all entries will be present in the resulting Seq, even if they have the same key.

 



#### [flatten()](index#flatten())




```
flatten(depth?: number): Collection<unknown, unknown>
flatten(shallow?: boolean): Collection<unknown, unknown>

```

#### Inherited from


`[Collection#flatten()](../collection/index#flatten())`


### Reducing a value



#### [reduce()](index#reduce())




```
reduce<R>(reducer: (reduction: R, value: V, key: K, iter: this) => R,initialReduction: R,context?: unknown): R
reduce<R>(reducer: (reduction: V | R, value: V, key: K, iter: this) => R): R

```

#### Inherited from


`[Collection#reduce()](../collection/index#reduce())`



#### [reduceRight()](index#reduceRight())




```
reduceRight<R>(reducer: (reduction: R, value: V, key: K, iter: this) => R,initialReduction: R,context?: unknown): R
reduceRight<R>(reducer: (reduction: V | R, value: V, key: K, iter: this) => R): R

```

#### Inherited from


`[Collection#reduceRight()](../collection/index#reduceRight())`



#### [every()](index#every())




True if `predicate` returns true for all entries in the Collection.

 

```
every(predicate: (value: V, key: K, iter: this) => boolean,context?: unknown): boolean

```

#### Inherited from


`[Collection#every()](../collection/index#every())`



#### [some()](index#some())




True if `predicate` returns true for any entry in the Collection.

 

```
some(predicate: (value: V, key: K, iter: this) => boolean,context?: unknown): boolean

```

#### Inherited from


`[Collection#some()](../collection/index#some())`



#### [join()](index#join())




Joins values together as a string, inserting a separator between each. The default separator is `","`.

 

```
join(separator?: string): string

```

#### Inherited from


`[Collection#join()](../collection/index#join())`



#### [isEmpty()](index#isEmpty())




Returns true if this Collection includes no values.

 

```
isEmpty(): boolean

```

#### Inherited from


`[Collection#isEmpty()](../collection/index#isEmpty())`#### Discussion



For some lazy `[Seq](index)`, `[isEmpty](../list/index#isEmpty())` might need to iterate to determine emptiness. At most one iteration will occur.

 



#### [count()](index#count())




```
count(): number
count(predicate: (value: V, key: K, iter: this) => boolean,context?: unknown): number

```

#### Inherited from


`[Collection#count()](../collection/index#count())`



#### [countBy()](index#countBy())




Returns a `[Seq.Keyed](../seq.keyed/index)` of counts, grouped by the return value of the `grouper` function.

 

```
countBy<G>(grouper: (value: V, key: K, iter: this) => G,context?: unknown): Map<G, number>

```

#### Inherited from


`[Collection#countBy()](../collection/index#countBy())`#### Discussion



Note: This is not a lazy operation.

 


### Search for value



#### [find()](index#find())




Returns the first value for which the `predicate` returns true.

 

```
find(predicate: (value: V, key: K, iter: this) => boolean,context?: unknown,notSetValue?: V): V | undefined

```

#### Inherited from


`[Collection#find()](../collection/index#find())`



#### [findLast()](index#findLast())




Returns the last value for which the `predicate` returns true.

 

```
findLast(predicate: (value: V, key: K, iter: this) => boolean,context?: unknown,notSetValue?: V): V | undefined

```

#### Inherited from


`[Collection#findLast()](../collection/index#findLast())`#### Discussion



Note: `predicate` will be called for each entry in reverse.

 



#### [findEntry()](index#findEntry())




Returns the first [key, value] entry for which the `predicate` returns true.

 

```
findEntry(predicate: (value: V, key: K, iter: this) => boolean,context?: unknown,notSetValue?: V): [K, V] | undefined

```

#### Inherited from


`[Collection#findEntry()](../collection/index#findEntry())`



#### [findLastEntry()](index#findLastEntry())




Returns the last [key, value] entry for which the `predicate` returns true.

 

```
findLastEntry(predicate: (value: V, key: K, iter: this) => boolean,context?: unknown,notSetValue?: V): [K, V] | undefined

```

#### Inherited from


`[Collection#findLastEntry()](../collection/index#findLastEntry())`#### Discussion



Note: `predicate` will be called for each entry in reverse.

 



#### [findKey()](index#findKey())




Returns the key for which the `predicate` returns true.

 

```
findKey(predicate: (value: V, key: K, iter: this) => boolean,context?: unknown): K | undefined

```

#### Inherited from


`[Collection#findKey()](../collection/index#findKey())`



#### [findLastKey()](index#findLastKey())




Returns the last key for which the `predicate` returns true.

 

```
findLastKey(predicate: (value: V, key: K, iter: this) => boolean,context?: unknown): K | undefined

```

#### Inherited from


`[Collection#findLastKey()](../collection/index#findLastKey())`#### Discussion



Note: `predicate` will be called for each entry in reverse.

 



#### [keyOf()](index#keyOf())




Returns the key associated with the search value, or undefined.

 

```
keyOf(searchValue: V): K | undefined

```

#### Inherited from


`[Collection#keyOf()](../collection/index#keyOf())`



#### [lastKeyOf()](index#lastKeyOf())




Returns the last key associated with the search value, or undefined.

 

```
lastKeyOf(searchValue: V): K | undefined

```

#### Inherited from


`[Collection#lastKeyOf()](../collection/index#lastKeyOf())`



#### [max()](index#max())




Returns the maximum value in this collection. If any values are comparatively equivalent, the first one found will be returned.

 

```
max(comparator?: (valueA: V, valueB: V) => number): V | undefined

```

#### Inherited from


`[Collection#max()](../collection/index#max())`#### Discussion



The `comparator` is used in the same way as `[Collection#sort](../collection/index#sort())`. If it is not provided, the default comparator is `>`.

 When two values are considered equivalent, the first encountered will be returned. Otherwise, `[max](../list/index#max())` will operate independent of the order of input as long as the comparator is commutative. The default comparator `>` is commutative *only* when types do not differ.

 If `comparator` returns 0 and either value is NaN, undefined, or null, that value will be returned.

 



#### [maxBy()](index#maxBy())




Like `[max](../list/index#max())`, but also accepts a `comparatorValueMapper` which allows for comparing by more sophisticated means:

 

```
maxBy<C>(comparatorValueMapper: (value: V, key: K, iter: this) => C,comparator?: (valueA: C, valueB: C) => number): V | undefined

```

#### Inherited from


`[Collection#maxBy()](../collection/index#maxBy())`#### Discussion


 
```
const { List, } = require('immutable');
const l = List([
  { name: 'Bob', avgHit: 1 },
  { name: 'Max', avgHit: 3 },
  { name: 'Lili', avgHit: 2 } ,
]);
l.maxBy(i => i.avgHit); // will output { name: 'Max', avgHit: 3 }run it
```


 



#### [min()](index#min())




Returns the minimum value in this collection. If any values are comparatively equivalent, the first one found will be returned.

 

```
min(comparator?: (valueA: V, valueB: V) => number): V | undefined

```

#### Inherited from


`[Collection#min()](../collection/index#min())`#### Discussion



The `comparator` is used in the same way as `[Collection#sort](../collection/index#sort())`. If it is not provided, the default comparator is `<`.

 When two values are considered equivalent, the first encountered will be returned. Otherwise, `[min](../list/index#min())` will operate independent of the order of input as long as the comparator is commutative. The default comparator `<` is commutative *only* when types do not differ.

 If `comparator` returns 0 and either value is NaN, undefined, or null, that value will be returned.

 



#### [minBy()](index#minBy())




Like `[min](../list/index#min())`, but also accepts a `comparatorValueMapper` which allows for comparing by more sophisticated means:

 

```
minBy<C>(comparatorValueMapper: (value: V, key: K, iter: this) => C,comparator?: (valueA: C, valueB: C) => number): V | undefined

```

#### Inherited from


`[Collection#minBy()](../collection/index#minBy())`#### Discussion


 
```
const { List, } = require('immutable');
const l = List([
  { name: 'Bob', avgHit: 1 },
  { name: 'Max', avgHit: 3 },
  { name: 'Lili', avgHit: 2 } ,
]);
l.minBy(i => i.avgHit); // will output { name: 'Bob', avgHit: 1 }run it
```


 


### Comparison



#### [isSubset()](index#isSubset())




True if `iter` includes every value in this Collection.

 

```
isSubset(iter: Iterable<V>): boolean

```

#### Inherited from


`[Collection#isSubset()](../collection/index#isSubset())`



#### [isSuperset()](index#isSuperset())




True if this Collection includes every value in `iter`.

 

```
isSuperset(iter: Iterable<V>): boolean

```

#### Inherited from


`[Collection#isSuperset()](../collection/index#isSuperset())`

This documentation is generated from [immutable.d.ts](https://github.com/immutable-js/immutable-js/blob/main/type-definitions/immutable.d.ts). Pull requests and [Issues](https://github.com/immutable-js/immutable-js/issues) welcome.

 © 2014–present, Lee Byron and other contributors  
Licensed under the 3-clause BSD License.  

<https://immutable-js.com/docs/v4.2.1/Seq/>

Seq.Keyed
=========



`[Seq](../seq/index)` which represents key-value pairs.

 

```
type Seq.Keyed<K, V> extends Seq<K, V>, Collection.Keyed<K, V>
```

### Construction



#### [Seq.Keyed()](index#Seq.Keyed())



```
Seq.Keyed<K, V>(collection?: Iterable<[K, V]>): Seq.Keyed<K, V>
Seq.Keyed<V>(obj: {[key: string]: V}): Seq.Keyed<string, V>

```


### Conversion to JavaScript types



#### [toJS()](index#toJS())




Deeply converts this Keyed Seq to equivalent native JavaScript Object.

 

```
toJS(): {[key: string]: DeepCopy<V>}

```

#### Overrides


`[Collection#toJS()](../collection/index#toJS())`#### Discussion



Converts keys to Strings.

 



#### [toJSON()](index#toJSON())




Shallowly converts this Keyed Seq to equivalent native JavaScript Object.

 

```
toJSON(): {[key: string]: V}

```

#### Overrides


`[Collection#toJSON()](../collection/index#toJSON())`#### Discussion



Converts keys to Strings.

 



#### [toArray()](index#toArray())




Shallowly converts this collection to an Array.

 

```
toArray(): Array<[K, V]>

```

#### Overrides


`[Collection#toArray()](../collection/index#toArray())`



#### [toObject()](index#toObject())




Shallowly converts this Collection to an Object.

 

```
toObject(): {[key: string]: V}

```

#### Inherited from


`[Collection#toObject()](../collection/index#toObject())`#### Discussion



Converts keys to Strings.

 


### Conversion to Seq



#### [toSeq()](index#toSeq())




Returns itself

 

```
toSeq(): this

```

#### Overrides


`[Collection#toSeq()](../collection/index#toSeq())`



#### [toKeyedSeq()](index#toKeyedSeq())




Returns a Seq.Keyed from this Collection where indices are treated as keys.

 

```
toKeyedSeq(): Seq.Keyed<K, V>

```

#### Inherited from


`[Collection#toKeyedSeq()](../collection/index#toKeyedSeq())`#### Discussion



This is useful if you want to operate on an Collection.Indexed and preserve the [index, value] pairs.

 The returned Seq will have identical iteration order as this Collection.

 
```
const { Seq } = require('immutable')
const indexedSeq = Seq([ 'A', 'B', 'C' ])
// Seq [ "A", "B", "C" ]
indexedSeq.filter(v => v === 'B')
// Seq [ "B" ]
const keyedSeq = indexedSeq.toKeyedSeq()
// Seq { 0: "A", 1: "B", 2: "C" }
keyedSeq.filter(v => v === 'B')
// Seq { 1: "B" }run it
```





#### [toIndexedSeq()](index#toIndexedSeq())




Returns an Seq.Indexed of the values of this Collection, discarding keys.

 

```
toIndexedSeq(): Seq.Indexed<V>

```

#### Inherited from


`[Collection#toIndexedSeq()](../collection/index#toIndexedSeq())`



#### [toSetSeq()](index#toSetSeq())




Returns a Seq.Set of the values of this Collection, discarding keys.

 

```
toSetSeq(): Seq.Set<V>

```

#### Inherited from


`[Collection#toSetSeq()](../collection/index#toSetSeq())`


### Combination



#### [concat()](index#concat())




```
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>

```

#### Overrides


`[Collection#concat()](../collection/index#concat())`



#### [flatten()](index#flatten())




```
flatten(depth?: number): Collection<unknown, unknown>
flatten(shallow?: boolean): Collection<unknown, unknown>

```

#### Inherited from


`[Collection#flatten()](../collection/index#flatten())`


### Sequence algorithms



#### [map()](index#map())




Returns a new Seq.Keyed with values passed through a `mapper` function.

 

```
map<M>(mapper: (value: V, key: K, iter: this) => M,context?: unknown): Seq.Keyed<K, M>

```

#### Overrides


`[Seq#map()](../seq/index#map())`#### Example




```
const { Seq } = require('immutable')
Seq.Keyed({ a: 1, b: 2 }).map(x => 10 * x)
// Seq { "a": 10, "b": 20 }
```

Note: `[map()](index#map())` always returns a new instance, even if it produced the same value at every step.

 



#### [flatMap()](index#flatMap())




Flat-maps the Seq, returning a Seq of the same type.

 

```
flatMap<KM, VM>(mapper: (value: V, key: K, iter: this) => Iterable<[KM, VM]>,context?: unknown): Seq.Keyed<KM, VM>

```

#### Overrides


`[Seq#flatMap()](../seq/index#flatMap())`#### Discussion



Similar to `seq.map(...).flatten(true)`.

 



#### [filter()](index#filter())




```
filter<F>(predicate: (value: V, key: K, iter: this) => boolean,context?: unknown): Seq.Keyed<K, F>
filter(predicate: (value: V, key: K, iter: this) => unknown,context?: unknown): this

```

#### Overrides


`[Seq#filter()](../seq/index#filter())`



#### [partition()](index#partition())




```
partition<F, C>(predicate: (this: C, value: V, key: K, iter: this) => boolean,context?: C): [Seq.Keyed<K, V>, Seq.Keyed<K, F>]
partition<C>(predicate: (this: C, value: V, key: K, iter: this) => unknown,context?: C): [this, this]

```

#### Overrides


`[Seq#partition()](../seq/index#partition())`



#### [filterNot()](index#filterNot())




Returns a new Collection of the same type with only the entries for which the `predicate` function returns false.

 

```
filterNot(predicate: (value: V, key: K, iter: this) => boolean,context?: unknown): this

```

#### Inherited from


`[Collection#filterNot()](../collection/index#filterNot())`#### Discussion


 
```
const { Map } = require('immutable')
Map({ a: 1, b: 2, c: 3, d: 4}).filterNot(x => x % 2 === 0)
// Map { "a": 1, "c": 3 }run it
```



Note: `[filterNot()](../list/index#filterNot())` always returns a new instance, even if it results in not filtering out any values.

 



#### [reverse()](index#reverse())




Returns a new Collection of the same type in reverse order.

 

```
reverse(): this

```

#### Inherited from


`[Collection#reverse()](../collection/index#reverse())`



#### [sort()](index#sort())




Returns a new Collection of the same type which includes the same entries, stably sorted by using a `comparator`.

 

```
sort(comparator?: (valueA: V, valueB: V) => number): this

```

#### Inherited from


`[Collection#sort()](../collection/index#sort())`#### Discussion



If a `comparator` is not provided, a default comparator uses `<` and `>`.

 `comparator(valueA, valueB)`:

 * Returns `0` if the elements should not be swapped.
* Returns `-1` (or any negative number) if `valueA` comes before `valueB`
* Returns `1` (or any positive number) if `valueA` comes after `valueB`
* Is pure, i.e. it must always return the same value for the same pair of values.

 When sorting collections which have no defined order, their ordered equivalents will be returned. e.g. `map.sort()` returns OrderedMap.

 
```
const { Map } = require('immutable')
Map({ "c": 3, "a": 1, "b": 2 }).sort((a, b) => {
  if (a < b) { return -1; }
  if (a > b) { return 1; }
  if (a === b) { return 0; }
});
// OrderedMap { "a": 1, "b": 2, "c": 3 }run it
```

Note: `[sort()](../list/index#sort())` Always returns a new instance, even if the original was already sorted.

 Note: This is always an eager operation.

 



#### [sortBy()](index#sortBy())




Like `[sort](../list/index#sort())`, but also accepts a `comparatorValueMapper` which allows for sorting by more sophisticated means:

 

```
sortBy<C>(comparatorValueMapper: (value: V, key: K, iter: this) => C,comparator?: (valueA: C, valueB: C) => number): this

```

#### Inherited from


`[Collection#sortBy()](../collection/index#sortBy())`#### Discussion


 
```
const { Map } = require('immutable')
const beattles = Map({
  John: { name: "Lennon" },
  Paul: { name: "McCartney" },
  George: { name: "Harrison" },
  Ringo: { name: "Starr" },
});
beattles.sortBy(member => member.name);run it
```



Note: `[sortBy()](../list/index#sortBy())` Always returns a new instance, even if the original was already sorted.

 Note: This is always an eager operation.

 



#### [groupBy()](index#groupBy())




Returns a `[Collection.Keyed](../collection.keyed/index)` of `Collection.Keyeds`, grouped by the return value of the `grouper` function.

 

```
groupBy<G>(grouper: (value: V, key: K, iter: this) => G,context?: unknown): Seq.Keyed<G, Collection<K, V>>

```

#### Inherited from


`[Collection#groupBy()](../collection/index#groupBy())`#### Discussion



Note: This is always an eager operation.

 
```
const { List, Map } = require('immutable')
const listOfMaps = List([
  Map({ v: 0 }),
  Map({ v: 1 }),
  Map({ v: 1 }),
  Map({ v: 0 }),
  Map({ v: 2 })
])
const groupsOfMaps = listOfMaps.groupBy(x => x.get('v'))
// Map {
//   0: List [ Map{ "v": 0 }, Map { "v": 0 } ],
//   1: List [ Map{ "v": 1 }, Map { "v": 1 } ],
//   2: List [ Map{ "v": 2 } ],
// }run it
```




### Sequence functions



#### [mapKeys()](index#mapKeys())




```
mapKeys<M>(mapper: (key: K, value: V, iter: this) => M,context?: unknown): Seq.Keyed<M, V>

```

#### Overrides


`[Collection.Keyed#mapKeys()](../collection.keyed/index#mapKeys())`#### see



Collection.Keyed.mapKeys

 



#### [mapEntries()](index#mapEntries())




```
mapEntries<KM, VM>(mapper: (entry: [K, V], index: number, iter: this) => [KM, VM] | undefined,context?: unknown): Seq.Keyed<KM, VM>

```

#### Overrides


`[Collection.Keyed#mapEntries()](../collection.keyed/index#mapEntries())`#### see



Collection.Keyed.mapEntries

 



#### [flip()](index#flip())




```
flip(): Seq.Keyed<V, K>

```

#### Overrides


`[Collection.Keyed#flip()](../collection.keyed/index#flip())`#### see



Collection.Keyed.flip

 


### Iterators



#### [[Symbol.iterator]()](index#%5BSymbol.iterator%5D())




```
[Symbol.iterator](): IterableIterator<[K, V]>

```

#### Overrides


`[Collection#[Symbol.iterator]()](../collection/index#%5BSymbol.iterator%5D())`



#### [keys()](index#keys())




An iterator of this `[Collection](../collection/index)`'s keys.

 

```
keys(): IterableIterator<K>

```

#### Inherited from


`[Collection#keys()](../collection/index#keys())`#### Discussion



Note: this will return an ES6 iterator which does not support Immutable.js sequence algorithms. Use `[keySeq](../list/index#keySeq())` instead, if this is what you want.

 



#### [values()](index#values())




An iterator of this `[Collection](../collection/index)`'s values.

 

```
values(): IterableIterator<V>

```

#### Inherited from


`[Collection#values()](../collection/index#values())`#### Discussion



Note: this will return an ES6 iterator which does not support Immutable.js sequence algorithms. Use `[valueSeq](../list/index#valueSeq())` instead, if this is what you want.

 



#### [entries()](index#entries())




An iterator of this `[Collection](../collection/index)`'s entries as `[ key, value ]` tuples.

 

```
entries(): IterableIterator<[K, V]>

```

#### Inherited from


`[Collection#entries()](../collection/index#entries())`#### Discussion



Note: this will return an ES6 iterator which does not support Immutable.js sequence algorithms. Use `[entrySeq](../list/index#entrySeq())` instead, if this is what you want.

 


### Members



#### [size](index#size)




Some Seqs can describe their size lazily. When this is the case, size will be an integer. Otherwise it will be undefined.

 

```
size: number | undefined
```

#### Inherited from


`[Seq#size](../seq/index#size)`#### Discussion



For example, Seqs returned from `[map()](../seq/index#map())` or `[reverse()](../seq/index#reverse())` preserve the size of the original `[Seq](../seq/index)` while `[filter()](../seq/index#filter())` does not.

 Note: `[Range](../range()/index)`, `[Repeat](../repeat()/index)` and `[Seq](../seq/index)`s made from `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)`s and `[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)`s will always have a size.

 


### Force evaluation



#### [cacheResult()](index#cacheResult())




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](../seq/index#join())` iterates the Seq of three values.

 

```
cacheResult(): this

```

#### Inherited from


`[Seq#cacheResult()](../seq/index#cacheResult())`#### Discussion




```
var squares = Seq([ 1, 2, 3 ]).map(x => x  x)
squares.join() + squares.join()
```



If you know a `[Seq](../seq/index)` 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](../seq/index#cacheResult())`, a Seq will always have a `[size](../seq/index#size)`.

 


### Value equality



#### [equals()](index#equals())




True if this and the other Collection have value equality, as defined by `[Immutable.is()](../is()/index)`.

 

```
equals(other: unknown): boolean

```

#### Inherited from


`[Collection#equals()](../collection/index#equals())`#### Discussion



Note: This is equivalent to `Immutable.is(this, other)`, but provided to allow for chained expressions.

 



#### [hashCode()](index#hashCode())




Computes and returns the hashed identity for this Collection.

 

```
hashCode(): number

```

#### Inherited from


`[Collection#hashCode()](../collection/index#hashCode())`#### Discussion



The `[hashCode](../list/index#hashCode())` of a Collection is used to determine potential equality, and is used when adding this to a `[Set](../set/index)` or as a key in a `[Map](../map/index)`, enabling lookup via a different instance.

 
```
const a = List([ 1, 2, 3 ]);
const b = List([ 1, 2, 3 ]);
assert.notStrictEqual(a, b); // different instances
const set = Set([ a ]);
assert.equal(set.has(b), true);run it
```

If two values have the same `[hashCode](../list/index#hashCode())`, they are [not guaranteed to be equal](https://en.wikipedia.org/wiki/Collision_(computer_science)). If two values have different `[hashCode](../list/index#hashCode())`s, they must not be equal.

 


### Reading values



#### [get()](index#get())




```
get<NSV>(key: K, notSetValue: NSV): V | NSV
get(key: K): V | undefined

```

#### Inherited from


`[Collection#get()](../collection/index#get())`



#### [has()](index#has())




True if a key exists within this `[Collection](../collection/index)`, using `[Immutable.is](../is()/index)` to determine equality

 

```
has(key: K): boolean

```

#### Inherited from


`[Collection#has()](../collection/index#has())`



#### [includes()](index#includes())




True if a value exists within this `[Collection](../collection/index)`, using `[Immutable.is](../is()/index)` to determine equality

 

```
includes(value: V): boolean

```

#### Inherited from


`[Collection#includes()](../collection/index#includes())`#### alias


`contains()`



#### [first()](index#first())




In case the `[Collection](../collection/index)` is not empty returns the first element of the `[Collection](../collection/index)`. In case the `[Collection](../collection/index)` is empty returns the optional default value if provided, if no default value is provided returns undefined.

 

```
first<NSV>(notSetValue?: NSV): V | NSV

```

#### Inherited from


`[Collection#first()](../collection/index#first())`



#### [last()](index#last())




In case the `[Collection](../collection/index)` is not empty returns the last element of the `[Collection](../collection/index)`. In case the `[Collection](../collection/index)` is empty returns the optional default value if provided, if no default value is provided returns undefined.

 

```
last<NSV>(notSetValue?: NSV): V | NSV

```

#### Inherited from


`[Collection#last()](../collection/index#last())`


### Reading deep values



#### [getIn()](index#getIn())




Returns the value found by following a path of keys or indices through nested Collections.

 

```
getIn(searchKeyPath: Iterable<unknown>, notSetValue?: unknown): unknown

```

#### Inherited from


`[Collection#getIn()](../collection/index#getIn())`#### Discussion


 
```
const { Map, List } = require('immutable')
const deepData = Map({ x: List([ Map({ y: 123 }) ]) });
deepData.getIn(['x', 0, 'y']) // 123run it
```



Plain JavaScript Object or Arrays may be nested within an Immutable.js Collection, and getIn() can access those values as well:

 
```
const { Map, List } = require('immutable')
const deepData = Map({ x: [ { y: 123 } ] });
deepData.getIn(['x', 0, 'y']) // 123run it
```


 



#### [hasIn()](index#hasIn())




True if the result of following a path of keys or indices through nested Collections results in a set value.

 

```
hasIn(searchKeyPath: Iterable<unknown>): boolean

```

#### Inherited from


`[Collection#hasIn()](../collection/index#hasIn())`


### Persistent changes



#### [update()](index#update())




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".

 

```
update<R>(updater: (value: this) => R): R

```

#### Inherited from


`[Collection#update()](../collection/index#update())`#### Discussion



For example, to sum a Seq after mapping and filtering:

 
```
const { Seq } = require('immutable')

function sum(collection) {
  return collection.reduce((sum, x) => sum + x, 0)
}
Seq([ 1, 2, 3 ])
  .map(x => x + 1)
  .filter(x => x % 2 === 0)
  .update(sum)
// 6run it
```
 


### Conversion to Collections



#### [toMap()](index#toMap())




Converts this Collection to a Map, Throws if keys are not hashable.

 

```
toMap(): Map<K, V>

```

#### Inherited from


`[Collection#toMap()](../collection/index#toMap())`#### Discussion



Note: This is equivalent to `Map(this.toKeyedSeq())`, but provided for convenience and to allow for chained expressions.

 



#### [toOrderedMap()](index#toOrderedMap())




Converts this Collection to a Map, maintaining the order of iteration.

 

```
toOrderedMap(): OrderedMap<K, V>

```

#### Inherited from


`[Collection#toOrderedMap()](../collection/index#toOrderedMap())`#### Discussion



Note: This is equivalent to `OrderedMap(this.toKeyedSeq())`, but provided for convenience and to allow for chained expressions.

 



#### [toSet()](index#toSet())




Converts this Collection to a Set, discarding keys. Throws if values are not hashable.

 

```
toSet(): Set<V>

```

#### Inherited from


`[Collection#toSet()](../collection/index#toSet())`#### Discussion



Note: This is equivalent to `[Set(this)](../set/index)`, but provided to allow for chained expressions.

 



#### [toOrderedSet()](index#toOrderedSet())




Converts this Collection to a Set, maintaining the order of iteration and discarding keys.

 

```
toOrderedSet(): OrderedSet<V>

```

#### Inherited from


`[Collection#toOrderedSet()](../collection/index#toOrderedSet())`#### Discussion



Note: This is equivalent to `OrderedSet(this.valueSeq())`, but provided for convenience and to allow for chained expressions.

 



#### [toList()](index#toList())




Converts this Collection to a List, discarding keys.

 

```
toList(): List<V>

```

#### Inherited from


`[Collection#toList()](../collection/index#toList())`#### Discussion



This is similar to `[List(collection)](../list/index)`, but provided to allow for chained expressions. However, when called on `[Map](../map/index)` or other keyed collections, `collection.toList()` discards the keys and creates a list of only the values, whereas `[List(collection)](../list/index)` creates a list of entry tuples.

 
```
const { Map, List } = require('immutable')
var myMap = Map({ a: 'Apple', b: 'Banana' })
List(myMap) // List [ [ "a", "Apple" ], [ "b", "Banana" ] ]
myMap.toList() // List [ "Apple", "Banana" ]run it
```





#### [toStack()](index#toStack())




Converts this Collection to a Stack, discarding keys. Throws if values are not hashable.

 

```
toStack(): Stack<V>

```

#### Inherited from


`[Collection#toStack()](../collection/index#toStack())`#### Discussion



Note: This is equivalent to `[Stack(this)](../stack/index)`, but provided to allow for chained expressions.

 


### Collections (Seq)



#### [keySeq()](index#keySeq())




Returns a new Seq.Indexed of the keys of this Collection, discarding values.

 

```
keySeq(): Seq.Indexed<K>

```

#### Inherited from


`[Collection#keySeq()](../collection/index#keySeq())`



#### [valueSeq()](index#valueSeq())




Returns an Seq.Indexed of the values of this Collection, discarding keys.

 

```
valueSeq(): Seq.Indexed<V>

```

#### Inherited from


`[Collection#valueSeq()](../collection/index#valueSeq())`



#### [entrySeq()](index#entrySeq())




Returns a new Seq.Indexed of [key, value] tuples.

 

```
entrySeq(): Seq.Indexed<[K, V]>

```

#### Inherited from


`[Collection#entrySeq()](../collection/index#entrySeq())`


### Side effects



#### [forEach()](index#forEach())




The `sideEffect` is executed for every entry in the Collection.

 

```
forEach(sideEffect: (value: V, key: K, iter: this) => unknown,context?: unknown): number

```

#### Inherited from


`[Collection#forEach()](../collection/index#forEach())`#### Discussion



Unlike `[Array#forEach](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/forEach)`, if any call of `sideEffect` returns `false`, the iteration will stop. Returns the number of entries iterated (including the last iteration which returned false).

 


### Creating subsets



#### [slice()](index#slice())




Returns a new Collection of the same type representing a portion of this Collection from start up to but not including end.

 

```
slice(begin?: number, end?: number): this

```

#### Inherited from


`[Collection#slice()](../collection/index#slice())`#### Discussion



If begin is negative, it is offset from the end of the Collection. e.g. `slice(-2)` returns a Collection of the last two entries. If it is not provided the new Collection will begin at the beginning of this Collection.

 If end is negative, it is offset from the end of the Collection. e.g. `slice(0, -1)` returns a Collection of everything but the last entry. If it is not provided, the new Collection will continue through the end of this Collection.

 If the requested slice is equivalent to the current Collection, then it will return itself.

 



#### [rest()](index#rest())




Returns a new Collection of the same type containing all entries except the first.

 

```
rest(): this

```

#### Inherited from


`[Collection#rest()](../collection/index#rest())`



#### [butLast()](index#butLast())




Returns a new Collection of the same type containing all entries except the last.

 

```
butLast(): this

```

#### Inherited from


`[Collection#butLast()](../collection/index#butLast())`



#### [skip()](index#skip())




Returns a new Collection of the same type which excludes the first `amount` entries from this Collection.

 

```
skip(amount: number): this

```

#### Inherited from


`[Collection#skip()](../collection/index#skip())`



#### [skipLast()](index#skipLast())




Returns a new Collection of the same type which excludes the last `amount` entries from this Collection.

 

```
skipLast(amount: number): this

```

#### Inherited from


`[Collection#skipLast()](../collection/index#skipLast())`



#### [skipWhile()](index#skipWhile())




Returns a new Collection of the same type which includes entries starting from when `predicate` first returns false.

 

```
skipWhile(predicate: (value: V, key: K, iter: this) => boolean,context?: unknown): this

```

#### Inherited from


`[Collection#skipWhile()](../collection/index#skipWhile())`#### Discussion


 
```
const { List } = require('immutable')
List([ 'dog', 'frog', 'cat', 'hat', 'god' ])
  .skipWhile(x => x.match(/g/))
// List [ "cat", "hat", "god" ]run it
```


 



#### [skipUntil()](index#skipUntil())




Returns a new Collection of the same type which includes entries starting from when `predicate` first returns true.

 

```
skipUntil(predicate: (value: V, key: K, iter: this) => boolean,context?: unknown): this

```

#### Inherited from


`[Collection#skipUntil()](../collection/index#skipUntil())`#### Discussion


 
```
const { List } = require('immutable')
List([ 'dog', 'frog', 'cat', 'hat', 'god' ])
  .skipUntil(x => x.match(/hat/))
// List [ "hat", "god" ]run it
```


 



#### [take()](index#take())




Returns a new Collection of the same type which includes the first `amount` entries from this Collection.

 

```
take(amount: number): this

```

#### Inherited from


`[Collection#take()](../collection/index#take())`



#### [takeLast()](index#takeLast())




Returns a new Collection of the same type which includes the last `amount` entries from this Collection.

 

```
takeLast(amount: number): this

```

#### Inherited from


`[Collection#takeLast()](../collection/index#takeLast())`



#### [takeWhile()](index#takeWhile())




Returns a new Collection of the same type which includes entries from this Collection as long as the `predicate` returns true.

 

```
takeWhile(predicate: (value: V, key: K, iter: this) => boolean,context?: unknown): this

```

#### Inherited from


`[Collection#takeWhile()](../collection/index#takeWhile())`#### Discussion


 
```
const { List } = require('immutable')
List([ 'dog', 'frog', 'cat', 'hat', 'god' ])
  .takeWhile(x => x.match(/o/))
// List [ "dog", "frog" ]run it
```


 



#### [takeUntil()](index#takeUntil())




Returns a new Collection of the same type which includes entries from this Collection as long as the `predicate` returns false.

 

```
takeUntil(predicate: (value: V, key: K, iter: this) => boolean,context?: unknown): this

```

#### Inherited from


`[Collection#takeUntil()](../collection/index#takeUntil())`#### Discussion


 
```
const { List } = require('immutable')
List([ 'dog', 'frog', 'cat', 'hat', 'god' ])
  .takeUntil(x => x.match(/at/))
// List [ "dog", "frog" ]run it
```


 


### Reducing a value



#### [reduce()](index#reduce())




```
reduce<R>(reducer: (reduction: R, value: V, key: K, iter: this) => R,initialReduction: R,context?: unknown): R
reduce<R>(reducer: (reduction: V | R, value: V, key: K, iter: this) => R): R

```

#### Inherited from


`[Collection#reduce()](../collection/index#reduce())`



#### [reduceRight()](index#reduceRight())




```
reduceRight<R>(reducer: (reduction: R, value: V, key: K, iter: this) => R,initialReduction: R,context?: unknown): R
reduceRight<R>(reducer: (reduction: V | R, value: V, key: K, iter: this) => R): R

```

#### Inherited from


`[Collection#reduceRight()](../collection/index#reduceRight())`



#### [every()](index#every())




True if `predicate` returns true for all entries in the Collection.

 

```
every(predicate: (value: V, key: K, iter: this) => boolean,context?: unknown): boolean

```

#### Inherited from


`[Collection#every()](../collection/index#every())`



#### [some()](index#some())




True if `predicate` returns true for any entry in the Collection.

 

```
some(predicate: (value: V, key: K, iter: this) => boolean,context?: unknown): boolean

```

#### Inherited from


`[Collection#some()](../collection/index#some())`



#### [join()](index#join())




Joins values together as a string, inserting a separator between each. The default separator is `","`.

 

```
join(separator?: string): string

```

#### Inherited from


`[Collection#join()](../collection/index#join())`



#### [isEmpty()](index#isEmpty())




Returns true if this Collection includes no values.

 

```
isEmpty(): boolean

```

#### Inherited from


`[Collection#isEmpty()](../collection/index#isEmpty())`#### Discussion



For some lazy `[Seq](../seq/index)`, `[isEmpty](../list/index#isEmpty())` might need to iterate to determine emptiness. At most one iteration will occur.

 



#### [count()](index#count())




```
count(): number
count(predicate: (value: V, key: K, iter: this) => boolean,context?: unknown): number

```

#### Inherited from


`[Collection#count()](../collection/index#count())`



#### [countBy()](index#countBy())




Returns a `[Seq.Keyed](index)` of counts, grouped by the return value of the `grouper` function.

 

```
countBy<G>(grouper: (value: V, key: K, iter: this) => G,context?: unknown): Map<G, number>

```

#### Inherited from


`[Collection#countBy()](../collection/index#countBy())`#### Discussion



Note: This is not a lazy operation.

 


### Search for value



#### [find()](index#find())




Returns the first value for which the `predicate` returns true.

 

```
find(predicate: (value: V, key: K, iter: this) => boolean,context?: unknown,notSetValue?: V): V | undefined

```

#### Inherited from


`[Collection#find()](../collection/index#find())`



#### [findLast()](index#findLast())




Returns the last value for which the `predicate` returns true.

 

```
findLast(predicate: (value: V, key: K, iter: this) => boolean,context?: unknown,notSetValue?: V): V | undefined

```

#### Inherited from


`[Collection#findLast()](../collection/index#findLast())`#### Discussion



Note: `predicate` will be called for each entry in reverse.

 



#### [findEntry()](index#findEntry())




Returns the first [key, value] entry for which the `predicate` returns true.

 

```
findEntry(predicate: (value: V, key: K, iter: this) => boolean,context?: unknown,notSetValue?: V): [K, V] | undefined

```

#### Inherited from


`[Collection#findEntry()](../collection/index#findEntry())`



#### [findLastEntry()](index#findLastEntry())




Returns the last [key, value] entry for which the `predicate` returns true.

 

```
findLastEntry(predicate: (value: V, key: K, iter: this) => boolean,context?: unknown,notSetValue?: V): [K, V] | undefined

```

#### Inherited from


`[Collection#findLastEntry()](../collection/index#findLastEntry())`#### Discussion



Note: `predicate` will be called for each entry in reverse.

 



#### [findKey()](index#findKey())




Returns the key for which the `predicate` returns true.

 

```
findKey(predicate: (value: V, key: K, iter: this) => boolean,context?: unknown): K | undefined

```

#### Inherited from


`[Collection#findKey()](../collection/index#findKey())`



#### [findLastKey()](index#findLastKey())




Returns the last key for which the `predicate` returns true.

 

```
findLastKey(predicate: (value: V, key: K, iter: this) => boolean,context?: unknown): K | undefined

```

#### Inherited from


`[Collection#findLastKey()](../collection/index#findLastKey())`#### Discussion



Note: `predicate` will be called for each entry in reverse.

 



#### [keyOf()](index#keyOf())




Returns the key associated with the search value, or undefined.

 

```
keyOf(searchValue: V): K | undefined

```

#### Inherited from


`[Collection#keyOf()](../collection/index#keyOf())`



#### [lastKeyOf()](index#lastKeyOf())




Returns the last key associated with the search value, or undefined.

 

```
lastKeyOf(searchValue: V): K | undefined

```

#### Inherited from


`[Collection#lastKeyOf()](../collection/index#lastKeyOf())`



#### [max()](index#max())




Returns the maximum value in this collection. If any values are comparatively equivalent, the first one found will be returned.

 

```
max(comparator?: (valueA: V, valueB: V) => number): V | undefined

```

#### Inherited from


`[Collection#max()](../collection/index#max())`#### Discussion



The `comparator` is used in the same way as `[Collection#sort](../collection/index#sort())`. If it is not provided, the default comparator is `>`.

 When two values are considered equivalent, the first encountered will be returned. Otherwise, `[max](../list/index#max())` will operate independent of the order of input as long as the comparator is commutative. The default comparator `>` is commutative *only* when types do not differ.

 If `comparator` returns 0 and either value is NaN, undefined, or null, that value will be returned.

 



#### [maxBy()](index#maxBy())




Like `[max](../list/index#max())`, but also accepts a `comparatorValueMapper` which allows for comparing by more sophisticated means:

 

```
maxBy<C>(comparatorValueMapper: (value: V, key: K, iter: this) => C,comparator?: (valueA: C, valueB: C) => number): V | undefined

```

#### Inherited from


`[Collection#maxBy()](../collection/index#maxBy())`#### Discussion


 
```
const { List, } = require('immutable');
const l = List([
  { name: 'Bob', avgHit: 1 },
  { name: 'Max', avgHit: 3 },
  { name: 'Lili', avgHit: 2 } ,
]);
l.maxBy(i => i.avgHit); // will output { name: 'Max', avgHit: 3 }run it
```


 



#### [min()](index#min())




Returns the minimum value in this collection. If any values are comparatively equivalent, the first one found will be returned.

 

```
min(comparator?: (valueA: V, valueB: V) => number): V | undefined

```

#### Inherited from


`[Collection#min()](../collection/index#min())`#### Discussion



The `comparator` is used in the same way as `[Collection#sort](../collection/index#sort())`. If it is not provided, the default comparator is `<`.

 When two values are considered equivalent, the first encountered will be returned. Otherwise, `[min](../list/index#min())` will operate independent of the order of input as long as the comparator is commutative. The default comparator `<` is commutative *only* when types do not differ.

 If `comparator` returns 0 and either value is NaN, undefined, or null, that value will be returned.

 



#### [minBy()](index#minBy())




Like `[min](../list/index#min())`, but also accepts a `comparatorValueMapper` which allows for comparing by more sophisticated means:

 

```
minBy<C>(comparatorValueMapper: (value: V, key: K, iter: this) => C,comparator?: (valueA: C, valueB: C) => number): V | undefined

```

#### Inherited from


`[Collection#minBy()](../collection/index#minBy())`#### Discussion


 
```
const { List, } = require('immutable');
const l = List([
  { name: 'Bob', avgHit: 1 },
  { name: 'Max', avgHit: 3 },
  { name: 'Lili', avgHit: 2 } ,
]);
l.minBy(i => i.avgHit); // will output { name: 'Bob', avgHit: 1 }run it
```


 


### Comparison



#### [isSubset()](index#isSubset())




True if `iter` includes every value in this Collection.

 

```
isSubset(iter: Iterable<V>): boolean

```

#### Inherited from


`[Collection#isSubset()](../collection/index#isSubset())`



#### [isSuperset()](index#isSuperset())




True if this Collection includes every value in `iter`.

 

```
isSuperset(iter: Iterable<V>): boolean

```

#### Inherited from


`[Collection#isSuperset()](../collection/index#isSuperset())`

This documentation is generated from [immutable.d.ts](https://github.com/immutable-js/immutable-js/blob/main/type-definitions/immutable.d.ts). Pull requests and [Issues](https://github.com/immutable-js/immutable-js/issues) welcome.

 © 2014–present, Lee Byron and other contributors  
Licensed under the 3-clause BSD License.  

<https://immutable-js.com/docs/v4.2.1/Seq.Keyed/>

Seq.Set
=======



`[Seq](../seq/index)` which represents a set of values.

 

```
type Seq.Set<T> extends Seq<T, T>, Collection.Set<T>
```

#### Discussion



Because `[Seq](../seq/index)` are often lazy, `[Seq.Set](index)` does not provide the same guarantee of value uniqueness as the concrete `[Set](../set/index)`.

 
### Construction



#### [Seq.Set()](index#Seq.Set())




Always returns a Seq.Set, discarding associated indices or keys.

 

```
Seq.Set<T>(collection?: Iterable<T> | ArrayLike<T>): Seq.Set<T>

```

#### Discussion



Note: `[Seq.Set](index)` is a conversion function and not a class, and does not use the `new` keyword during construction.

 


### Static methods



#### [Seq.Set.of()](index#of())



```
Seq.Set.of<T>(...values: Array<T>): Seq.Set<T>

```


### Conversion to JavaScript types



#### [toJS()](index#toJS())




Deeply converts this Set Seq to equivalent native JavaScript Array.

 

```
toJS(): Array<DeepCopy<T>>

```

#### Overrides


`[Collection#toJS()](../collection/index#toJS())`



#### [toJSON()](index#toJSON())




Shallowly converts this Set Seq to equivalent native JavaScript Array.

 

```
toJSON(): Array<T>

```

#### Overrides


`[Collection#toJSON()](../collection/index#toJSON())`



#### [toArray()](index#toArray())




Shallowly converts this collection to an Array.

 

```
toArray(): Array<T>

```

#### Overrides


`[Collection#toArray()](../collection/index#toArray())`



#### [toObject()](index#toObject())




Shallowly converts this Collection to an Object.

 

```
toObject(): {[key: string]: T}

```

#### Inherited from


`[Collection#toObject()](../collection/index#toObject())`#### Discussion



Converts keys to Strings.

 


### Conversion to Seq



#### [toSeq()](index#toSeq())




Returns itself

 

```
toSeq(): this

```

#### Overrides


`[Collection#toSeq()](../collection/index#toSeq())`



#### [toKeyedSeq()](index#toKeyedSeq())




Returns a Seq.Keyed from this Collection where indices are treated as keys.

 

```
toKeyedSeq(): Seq.Keyed<T, T>

```

#### Inherited from


`[Collection#toKeyedSeq()](../collection/index#toKeyedSeq())`#### Discussion



This is useful if you want to operate on an Collection.Indexed and preserve the [index, value] pairs.

 The returned Seq will have identical iteration order as this Collection.

 
```
const { Seq } = require('immutable')
const indexedSeq = Seq([ 'A', 'B', 'C' ])
// Seq [ "A", "B", "C" ]
indexedSeq.filter(v => v === 'B')
// Seq [ "B" ]
const keyedSeq = indexedSeq.toKeyedSeq()
// Seq { 0: "A", 1: "B", 2: "C" }
keyedSeq.filter(v => v === 'B')
// Seq { 1: "B" }run it
```





#### [toIndexedSeq()](index#toIndexedSeq())




Returns an Seq.Indexed of the values of this Collection, discarding keys.

 

```
toIndexedSeq(): Seq.Indexed<T>

```

#### Inherited from


`[Collection#toIndexedSeq()](../collection/index#toIndexedSeq())`



#### [toSetSeq()](index#toSetSeq())




Returns a Seq.Set of the values of this Collection, discarding keys.

 

```
toSetSeq(): Seq.Set<T>

```

#### Inherited from


`[Collection#toSetSeq()](../collection/index#toSetSeq())`


### Combination



#### [concat()](index#concat())




Returns a new Seq with other collections concatenated to this one.

 

```
concat<U>(...collections: Array<Iterable<U>>): Seq.Set<T | U>

```

#### Overrides


`[Collection#concat()](../collection/index#concat())`#### Discussion



All entries will be present in the resulting Seq, even if they are duplicates.

 



#### [flatten()](index#flatten())




```
flatten(depth?: number): Collection<unknown, unknown>
flatten(shallow?: boolean): Collection<unknown, unknown>

```

#### Inherited from


`[Collection#flatten()](../collection/index#flatten())`


### Sequence algorithms



#### [map()](index#map())




Returns a new Seq.Set with values passed through a `mapper` function.

 

```
map<M>(mapper: (value: T, key: T, iter: this) => M,context?: unknown): Seq.Set<M>

```

#### Overrides


`[Seq#map()](../seq/index#map())`#### Example




```
Seq.Set([ 1, 2 ]).map(x => 10 * x)
// Seq { 10, 20 }
```

Note: `[map()](index#map())` always returns a new instance, even if it produced the same value at every step.

 



#### [flatMap()](index#flatMap())




Flat-maps the Seq, returning a Seq of the same type.

 

```
flatMap<M>(mapper: (value: T, key: T, iter: this) => Iterable<M>,context?: unknown): Seq.Set<M>

```

#### Overrides


`[Seq#flatMap()](../seq/index#flatMap())`#### Discussion



Similar to `seq.map(...).flatten(true)`.

 



#### [filter()](index#filter())




```
filter<F>(predicate: (value: T, key: T, iter: this) => boolean,context?: unknown): Seq.Set<F>
filter(predicate: (value: T, key: T, iter: this) => unknown,context?: unknown): this

```

#### Overrides


`[Seq#filter()](../seq/index#filter())`



#### [partition()](index#partition())




```
partition<F, C>(predicate: (this: C, value: T, key: T, iter: this) => boolean,context?: C): [Seq.Set<T>, Seq.Set<F>]
partition<C>(predicate: (this: C, value: T, key: T, iter: this) => unknown,context?: C): [this, this]

```

#### Overrides


`[Seq#partition()](../seq/index#partition())`



#### [filterNot()](index#filterNot())




Returns a new Collection of the same type with only the entries for which the `predicate` function returns false.

 

```
filterNot(predicate: (value: T, key: T, iter: this) => boolean,context?: unknown): this

```

#### Inherited from


`[Collection#filterNot()](../collection/index#filterNot())`#### Discussion


 
```
const { Map } = require('immutable')
Map({ a: 1, b: 2, c: 3, d: 4}).filterNot(x => x % 2 === 0)
// Map { "a": 1, "c": 3 }run it
```



Note: `[filterNot()](../list/index#filterNot())` always returns a new instance, even if it results in not filtering out any values.

 



#### [reverse()](index#reverse())




Returns a new Collection of the same type in reverse order.

 

```
reverse(): this

```

#### Inherited from


`[Collection#reverse()](../collection/index#reverse())`



#### [sort()](index#sort())




Returns a new Collection of the same type which includes the same entries, stably sorted by using a `comparator`.

 

```
sort(comparator?: (valueA: T, valueB: T) => number): this

```

#### Inherited from


`[Collection#sort()](../collection/index#sort())`#### Discussion



If a `comparator` is not provided, a default comparator uses `<` and `>`.

 `comparator(valueA, valueB)`:

 * Returns `0` if the elements should not be swapped.
* Returns `-1` (or any negative number) if `valueA` comes before `valueB`
* Returns `1` (or any positive number) if `valueA` comes after `valueB`
* Is pure, i.e. it must always return the same value for the same pair of values.

 When sorting collections which have no defined order, their ordered equivalents will be returned. e.g. `map.sort()` returns OrderedMap.

 
```
const { Map } = require('immutable')
Map({ "c": 3, "a": 1, "b": 2 }).sort((a, b) => {
  if (a < b) { return -1; }
  if (a > b) { return 1; }
  if (a === b) { return 0; }
});
// OrderedMap { "a": 1, "b": 2, "c": 3 }run it
```

Note: `[sort()](../list/index#sort())` Always returns a new instance, even if the original was already sorted.

 Note: This is always an eager operation.

 



#### [sortBy()](index#sortBy())




Like `[sort](../list/index#sort())`, but also accepts a `comparatorValueMapper` which allows for sorting by more sophisticated means:

 

```
sortBy<C>(comparatorValueMapper: (value: T, key: T, iter: this) => C,comparator?: (valueA: C, valueB: C) => number): this

```

#### Inherited from


`[Collection#sortBy()](../collection/index#sortBy())`#### Discussion


 
```
const { Map } = require('immutable')
const beattles = Map({
  John: { name: "Lennon" },
  Paul: { name: "McCartney" },
  George: { name: "Harrison" },
  Ringo: { name: "Starr" },
});
beattles.sortBy(member => member.name);run it
```



Note: `[sortBy()](../list/index#sortBy())` Always returns a new instance, even if the original was already sorted.

 Note: This is always an eager operation.

 



#### [groupBy()](index#groupBy())




Returns a `[Collection.Keyed](../collection.keyed/index)` of `Collection.Keyeds`, grouped by the return value of the `grouper` function.

 

```
groupBy<G>(grouper: (value: T, key: T, iter: this) => G,context?: unknown): Seq.Keyed<G, Collection<T, T>>

```

#### Inherited from


`[Collection#groupBy()](../collection/index#groupBy())`#### Discussion



Note: This is always an eager operation.

 
```
const { List, Map } = require('immutable')
const listOfMaps = List([
  Map({ v: 0 }),
  Map({ v: 1 }),
  Map({ v: 1 }),
  Map({ v: 0 }),
  Map({ v: 2 })
])
const groupsOfMaps = listOfMaps.groupBy(x => x.get('v'))
// Map {
//   0: List [ Map{ "v": 0 }, Map { "v": 0 } ],
//   1: List [ Map{ "v": 1 }, Map { "v": 1 } ],
//   2: List [ Map{ "v": 2 } ],
// }run it
```




### Iterators



#### [[Symbol.iterator]()](index#%5BSymbol.iterator%5D())




```
[Symbol.iterator](): IterableIterator<T>

```

#### Overrides


`[Collection#[Symbol.iterator]()](../collection/index#%5BSymbol.iterator%5D())`



#### [keys()](index#keys())




An iterator of this `[Collection](../collection/index)`'s keys.

 

```
keys(): IterableIterator<T>

```

#### Inherited from


`[Collection#keys()](../collection/index#keys())`#### Discussion



Note: this will return an ES6 iterator which does not support Immutable.js sequence algorithms. Use `[keySeq](../list/index#keySeq())` instead, if this is what you want.

 



#### [values()](index#values())




An iterator of this `[Collection](../collection/index)`'s values.

 

```
values(): IterableIterator<T>

```

#### Inherited from


`[Collection#values()](../collection/index#values())`#### Discussion



Note: this will return an ES6 iterator which does not support Immutable.js sequence algorithms. Use `[valueSeq](../list/index#valueSeq())` instead, if this is what you want.

 



#### [entries()](index#entries())




An iterator of this `[Collection](../collection/index)`'s entries as `[ key, value ]` tuples.

 

```
entries(): IterableIterator<[T, T]>

```

#### Inherited from


`[Collection#entries()](../collection/index#entries())`#### Discussion



Note: this will return an ES6 iterator which does not support Immutable.js sequence algorithms. Use `[entrySeq](../list/index#entrySeq())` instead, if this is what you want.

 


### Members



#### [size](index#size)




Some Seqs can describe their size lazily. When this is the case, size will be an integer. Otherwise it will be undefined.

 

```
size: number | undefined
```

#### Inherited from


`[Seq#size](../seq/index#size)`#### Discussion



For example, Seqs returned from `[map()](../seq/index#map())` or `[reverse()](../seq/index#reverse())` preserve the size of the original `[Seq](../seq/index)` while `[filter()](../seq/index#filter())` does not.

 Note: `[Range](../range()/index)`, `[Repeat](../repeat()/index)` and `[Seq](../seq/index)`s made from `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)`s and `[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)`s will always have a size.

 


### Force evaluation



#### [cacheResult()](index#cacheResult())




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](../seq/index#join())` iterates the Seq of three values.

 

```
cacheResult(): this

```

#### Inherited from


`[Seq#cacheResult()](../seq/index#cacheResult())`#### Discussion




```
var squares = Seq([ 1, 2, 3 ]).map(x => x  x)
squares.join() + squares.join()
```



If you know a `[Seq](../seq/index)` 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](../seq/index#cacheResult())`, a Seq will always have a `[size](../seq/index#size)`.

 


### Value equality



#### [equals()](index#equals())




True if this and the other Collection have value equality, as defined by `[Immutable.is()](../is()/index)`.

 

```
equals(other: unknown): boolean

```

#### Inherited from


`[Collection#equals()](../collection/index#equals())`#### Discussion



Note: This is equivalent to `Immutable.is(this, other)`, but provided to allow for chained expressions.

 



#### [hashCode()](index#hashCode())




Computes and returns the hashed identity for this Collection.

 

```
hashCode(): number

```

#### Inherited from


`[Collection#hashCode()](../collection/index#hashCode())`#### Discussion



The `[hashCode](../list/index#hashCode())` of a Collection is used to determine potential equality, and is used when adding this to a `[Set](../set/index)` or as a key in a `[Map](../map/index)`, enabling lookup via a different instance.

 
```
const a = List([ 1, 2, 3 ]);
const b = List([ 1, 2, 3 ]);
assert.notStrictEqual(a, b); // different instances
const set = Set([ a ]);
assert.equal(set.has(b), true);run it
```

If two values have the same `[hashCode](../list/index#hashCode())`, they are [not guaranteed to be equal](https://en.wikipedia.org/wiki/Collision_(computer_science)). If two values have different `[hashCode](../list/index#hashCode())`s, they must not be equal.

 


### Reading values



#### [get()](index#get())




```
get<NSV>(key: T, notSetValue: NSV): T | NSV
get(key: T): T | undefined

```

#### Inherited from


`[Collection#get()](../collection/index#get())`



#### [has()](index#has())




True if a key exists within this `[Collection](../collection/index)`, using `[Immutable.is](../is()/index)` to determine equality

 

```
has(key: T): boolean

```

#### Inherited from


`[Collection#has()](../collection/index#has())`



#### [includes()](index#includes())




True if a value exists within this `[Collection](../collection/index)`, using `[Immutable.is](../is()/index)` to determine equality

 

```
includes(value: T): boolean

```

#### Inherited from


`[Collection#includes()](../collection/index#includes())`#### alias


`contains()`



#### [first()](index#first())




In case the `[Collection](../collection/index)` is not empty returns the first element of the `[Collection](../collection/index)`. In case the `[Collection](../collection/index)` is empty returns the optional default value if provided, if no default value is provided returns undefined.

 

```
first<NSV>(notSetValue?: NSV): T | NSV

```

#### Inherited from


`[Collection#first()](../collection/index#first())`



#### [last()](index#last())




In case the `[Collection](../collection/index)` is not empty returns the last element of the `[Collection](../collection/index)`. In case the `[Collection](../collection/index)` is empty returns the optional default value if provided, if no default value is provided returns undefined.

 

```
last<NSV>(notSetValue?: NSV): T | NSV

```

#### Inherited from


`[Collection#last()](../collection/index#last())`


### Reading deep values



#### [getIn()](index#getIn())




Returns the value found by following a path of keys or indices through nested Collections.

 

```
getIn(searchKeyPath: Iterable<unknown>, notSetValue?: unknown): unknown

```

#### Inherited from


`[Collection#getIn()](../collection/index#getIn())`#### Discussion


 
```
const { Map, List } = require('immutable')
const deepData = Map({ x: List([ Map({ y: 123 }) ]) });
deepData.getIn(['x', 0, 'y']) // 123run it
```



Plain JavaScript Object or Arrays may be nested within an Immutable.js Collection, and getIn() can access those values as well:

 
```
const { Map, List } = require('immutable')
const deepData = Map({ x: [ { y: 123 } ] });
deepData.getIn(['x', 0, 'y']) // 123run it
```


 



#### [hasIn()](index#hasIn())




True if the result of following a path of keys or indices through nested Collections results in a set value.

 

```
hasIn(searchKeyPath: Iterable<unknown>): boolean

```

#### Inherited from


`[Collection#hasIn()](../collection/index#hasIn())`


### Persistent changes



#### [update()](index#update())




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".

 

```
update<R>(updater: (value: this) => R): R

```

#### Inherited from


`[Collection#update()](../collection/index#update())`#### Discussion



For example, to sum a Seq after mapping and filtering:

 
```
const { Seq } = require('immutable')

function sum(collection) {
  return collection.reduce((sum, x) => sum + x, 0)
}
Seq([ 1, 2, 3 ])
  .map(x => x + 1)
  .filter(x => x % 2 === 0)
  .update(sum)
// 6run it
```
 


### Conversion to Collections



#### [toMap()](index#toMap())




Converts this Collection to a Map, Throws if keys are not hashable.

 

```
toMap(): Map<T, T>

```

#### Inherited from


`[Collection#toMap()](../collection/index#toMap())`#### Discussion



Note: This is equivalent to `Map(this.toKeyedSeq())`, but provided for convenience and to allow for chained expressions.

 



#### [toOrderedMap()](index#toOrderedMap())




Converts this Collection to a Map, maintaining the order of iteration.

 

```
toOrderedMap(): OrderedMap<T, T>

```

#### Inherited from


`[Collection#toOrderedMap()](../collection/index#toOrderedMap())`#### Discussion



Note: This is equivalent to `OrderedMap(this.toKeyedSeq())`, but provided for convenience and to allow for chained expressions.

 



#### [toSet()](index#toSet())




Converts this Collection to a Set, discarding keys. Throws if values are not hashable.

 

```
toSet(): Set<T>

```

#### Inherited from


`[Collection#toSet()](../collection/index#toSet())`#### Discussion



Note: This is equivalent to `[Set(this)](../set/index)`, but provided to allow for chained expressions.

 



#### [toOrderedSet()](index#toOrderedSet())




Converts this Collection to a Set, maintaining the order of iteration and discarding keys.

 

```
toOrderedSet(): OrderedSet<T>

```

#### Inherited from


`[Collection#toOrderedSet()](../collection/index#toOrderedSet())`#### Discussion



Note: This is equivalent to `OrderedSet(this.valueSeq())`, but provided for convenience and to allow for chained expressions.

 



#### [toList()](index#toList())




Converts this Collection to a List, discarding keys.

 

```
toList(): List<T>

```

#### Inherited from


`[Collection#toList()](../collection/index#toList())`#### Discussion



This is similar to `[List(collection)](../list/index)`, but provided to allow for chained expressions. However, when called on `[Map](../map/index)` or other keyed collections, `collection.toList()` discards the keys and creates a list of only the values, whereas `[List(collection)](../list/index)` creates a list of entry tuples.

 
```
const { Map, List } = require('immutable')
var myMap = Map({ a: 'Apple', b: 'Banana' })
List(myMap) // List [ [ "a", "Apple" ], [ "b", "Banana" ] ]
myMap.toList() // List [ "Apple", "Banana" ]run it
```





#### [toStack()](index#toStack())




Converts this Collection to a Stack, discarding keys. Throws if values are not hashable.

 

```
toStack(): Stack<T>

```

#### Inherited from


`[Collection#toStack()](../collection/index#toStack())`#### Discussion



Note: This is equivalent to `[Stack(this)](../stack/index)`, but provided to allow for chained expressions.

 


### Collections (Seq)



#### [keySeq()](index#keySeq())




Returns a new Seq.Indexed of the keys of this Collection, discarding values.

 

```
keySeq(): Seq.Indexed<T>

```

#### Inherited from


`[Collection#keySeq()](../collection/index#keySeq())`



#### [valueSeq()](index#valueSeq())




Returns an Seq.Indexed of the values of this Collection, discarding keys.

 

```
valueSeq(): Seq.Indexed<T>

```

#### Inherited from


`[Collection#valueSeq()](../collection/index#valueSeq())`



#### [entrySeq()](index#entrySeq())




Returns a new Seq.Indexed of [key, value] tuples.

 

```
entrySeq(): Seq.Indexed<[T, T]>

```

#### Inherited from


`[Collection#entrySeq()](../collection/index#entrySeq())`


### Side effects



#### [forEach()](index#forEach())




The `sideEffect` is executed for every entry in the Collection.

 

```
forEach(sideEffect: (value: T, key: T, iter: this) => unknown,context?: unknown): number

```

#### Inherited from


`[Collection#forEach()](../collection/index#forEach())`#### Discussion



Unlike `[Array#forEach](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/forEach)`, if any call of `sideEffect` returns `false`, the iteration will stop. Returns the number of entries iterated (including the last iteration which returned false).

 


### Creating subsets



#### [slice()](index#slice())




Returns a new Collection of the same type representing a portion of this Collection from start up to but not including end.

 

```
slice(begin?: number, end?: number): this

```

#### Inherited from


`[Collection#slice()](../collection/index#slice())`#### Discussion



If begin is negative, it is offset from the end of the Collection. e.g. `slice(-2)` returns a Collection of the last two entries. If it is not provided the new Collection will begin at the beginning of this Collection.

 If end is negative, it is offset from the end of the Collection. e.g. `slice(0, -1)` returns a Collection of everything but the last entry. If it is not provided, the new Collection will continue through the end of this Collection.

 If the requested slice is equivalent to the current Collection, then it will return itself.

 



#### [rest()](index#rest())




Returns a new Collection of the same type containing all entries except the first.

 

```
rest(): this

```

#### Inherited from


`[Collection#rest()](../collection/index#rest())`



#### [butLast()](index#butLast())




Returns a new Collection of the same type containing all entries except the last.

 

```
butLast(): this

```

#### Inherited from


`[Collection#butLast()](../collection/index#butLast())`



#### [skip()](index#skip())




Returns a new Collection of the same type which excludes the first `amount` entries from this Collection.

 

```
skip(amount: number): this

```

#### Inherited from


`[Collection#skip()](../collection/index#skip())`



#### [skipLast()](index#skipLast())




Returns a new Collection of the same type which excludes the last `amount` entries from this Collection.

 

```
skipLast(amount: number): this

```

#### Inherited from


`[Collection#skipLast()](../collection/index#skipLast())`



#### [skipWhile()](index#skipWhile())




Returns a new Collection of the same type which includes entries starting from when `predicate` first returns false.

 

```
skipWhile(predicate: (value: T, key: T, iter: this) => boolean,context?: unknown): this

```

#### Inherited from


`[Collection#skipWhile()](../collection/index#skipWhile())`#### Discussion


 
```
const { List } = require('immutable')
List([ 'dog', 'frog', 'cat', 'hat', 'god' ])
  .skipWhile(x => x.match(/g/))
// List [ "cat", "hat", "god" ]run it
```


 



#### [skipUntil()](index#skipUntil())




Returns a new Collection of the same type which includes entries starting from when `predicate` first returns true.

 

```
skipUntil(predicate: (value: T, key: T, iter: this) => boolean,context?: unknown): this

```

#### Inherited from


`[Collection#skipUntil()](../collection/index#skipUntil())`#### Discussion


 
```
const { List } = require('immutable')
List([ 'dog', 'frog', 'cat', 'hat', 'god' ])
  .skipUntil(x => x.match(/hat/))
// List [ "hat", "god" ]run it
```


 



#### [take()](index#take())




Returns a new Collection of the same type which includes the first `amount` entries from this Collection.

 

```
take(amount: number): this

```

#### Inherited from


`[Collection#take()](../collection/index#take())`



#### [takeLast()](index#takeLast())




Returns a new Collection of the same type which includes the last `amount` entries from this Collection.

 

```
takeLast(amount: number): this

```

#### Inherited from


`[Collection#takeLast()](../collection/index#takeLast())`



#### [takeWhile()](index#takeWhile())




Returns a new Collection of the same type which includes entries from this Collection as long as the `predicate` returns true.

 

```
takeWhile(predicate: (value: T, key: T, iter: this) => boolean,context?: unknown): this

```

#### Inherited from


`[Collection#takeWhile()](../collection/index#takeWhile())`#### Discussion


 
```
const { List } = require('immutable')
List([ 'dog', 'frog', 'cat', 'hat', 'god' ])
  .takeWhile(x => x.match(/o/))
// List [ "dog", "frog" ]run it
```


 



#### [takeUntil()](index#takeUntil())




Returns a new Collection of the same type which includes entries from this Collection as long as the `predicate` returns false.

 

```
takeUntil(predicate: (value: T, key: T, iter: this) => boolean,context?: unknown): this

```

#### Inherited from


`[Collection#takeUntil()](../collection/index#takeUntil())`#### Discussion


 
```
const { List } = require('immutable')
List([ 'dog', 'frog', 'cat', 'hat', 'god' ])
  .takeUntil(x => x.match(/at/))
// List [ "dog", "frog" ]run it
```


 


### Reducing a value



#### [reduce()](index#reduce())




```
reduce<R>(reducer: (reduction: R, value: T, key: T, iter: this) => R,initialReduction: R,context?: unknown): R
reduce<R>(reducer: (reduction: T | R, value: T, key: T, iter: this) => R): R

```

#### Inherited from


`[Collection#reduce()](../collection/index#reduce())`



#### [reduceRight()](index#reduceRight())




```
reduceRight<R>(reducer: (reduction: R, value: T, key: T, iter: this) => R,initialReduction: R,context?: unknown): R
reduceRight<R>(reducer: (reduction: T | R, value: T, key: T, iter: this) => R): R

```

#### Inherited from


`[Collection#reduceRight()](../collection/index#reduceRight())`



#### [every()](index#every())




True if `predicate` returns true for all entries in the Collection.

 

```
every(predicate: (value: T, key: T, iter: this) => boolean,context?: unknown): boolean

```

#### Inherited from


`[Collection#every()](../collection/index#every())`



#### [some()](index#some())




True if `predicate` returns true for any entry in the Collection.

 

```
some(predicate: (value: T, key: T, iter: this) => boolean,context?: unknown): boolean

```

#### Inherited from


`[Collection#some()](../collection/index#some())`



#### [join()](index#join())




Joins values together as a string, inserting a separator between each. The default separator is `","`.

 

```
join(separator?: string): string

```

#### Inherited from


`[Collection#join()](../collection/index#join())`



#### [isEmpty()](index#isEmpty())




Returns true if this Collection includes no values.

 

```
isEmpty(): boolean

```

#### Inherited from


`[Collection#isEmpty()](../collection/index#isEmpty())`#### Discussion



For some lazy `[Seq](../seq/index)`, `[isEmpty](../list/index#isEmpty())` might need to iterate to determine emptiness. At most one iteration will occur.

 



#### [count()](index#count())




```
count(): number
count(predicate: (value: T, key: T, iter: this) => boolean,context?: unknown): number

```

#### Inherited from


`[Collection#count()](../collection/index#count())`



#### [countBy()](index#countBy())




Returns a `[Seq.Keyed](../seq.keyed/index)` of counts, grouped by the return value of the `grouper` function.

 

```
countBy<G>(grouper: (value: T, key: T, iter: this) => G,context?: unknown): Map<G, number>

```

#### Inherited from


`[Collection#countBy()](../collection/index#countBy())`#### Discussion



Note: This is not a lazy operation.

 


### Search for value



#### [find()](index#find())




Returns the first value for which the `predicate` returns true.

 

```
find(predicate: (value: T, key: T, iter: this) => boolean,context?: unknown,notSetValue?: T): T | undefined

```

#### Inherited from


`[Collection#find()](../collection/index#find())`



#### [findLast()](index#findLast())




Returns the last value for which the `predicate` returns true.

 

```
findLast(predicate: (value: T, key: T, iter: this) => boolean,context?: unknown,notSetValue?: T): T | undefined

```

#### Inherited from


`[Collection#findLast()](../collection/index#findLast())`#### Discussion



Note: `predicate` will be called for each entry in reverse.

 



#### [findEntry()](index#findEntry())




Returns the first [key, value] entry for which the `predicate` returns true.

 

```
findEntry(predicate: (value: T, key: T, iter: this) => boolean,context?: unknown,notSetValue?: T): [T, T] | undefined

```

#### Inherited from


`[Collection#findEntry()](../collection/index#findEntry())`



#### [findLastEntry()](index#findLastEntry())




Returns the last [key, value] entry for which the `predicate` returns true.

 

```
findLastEntry(predicate: (value: T, key: T, iter: this) => boolean,context?: unknown,notSetValue?: T): [T, T] | undefined

```

#### Inherited from


`[Collection#findLastEntry()](../collection/index#findLastEntry())`#### Discussion



Note: `predicate` will be called for each entry in reverse.

 



#### [findKey()](index#findKey())




Returns the key for which the `predicate` returns true.

 

```
findKey(predicate: (value: T, key: T, iter: this) => boolean,context?: unknown): T | undefined

```

#### Inherited from


`[Collection#findKey()](../collection/index#findKey())`



#### [findLastKey()](index#findLastKey())




Returns the last key for which the `predicate` returns true.

 

```
findLastKey(predicate: (value: T, key: T, iter: this) => boolean,context?: unknown): T | undefined

```

#### Inherited from


`[Collection#findLastKey()](../collection/index#findLastKey())`#### Discussion



Note: `predicate` will be called for each entry in reverse.

 



#### [keyOf()](index#keyOf())




Returns the key associated with the search value, or undefined.

 

```
keyOf(searchValue: T): T | undefined

```

#### Inherited from


`[Collection#keyOf()](../collection/index#keyOf())`



#### [lastKeyOf()](index#lastKeyOf())




Returns the last key associated with the search value, or undefined.

 

```
lastKeyOf(searchValue: T): T | undefined

```

#### Inherited from


`[Collection#lastKeyOf()](../collection/index#lastKeyOf())`



#### [max()](index#max())




Returns the maximum value in this collection. If any values are comparatively equivalent, the first one found will be returned.

 

```
max(comparator?: (valueA: T, valueB: T) => number): T | undefined

```

#### Inherited from


`[Collection#max()](../collection/index#max())`#### Discussion



The `comparator` is used in the same way as `[Collection#sort](../collection/index#sort())`. If it is not provided, the default comparator is `>`.

 When two values are considered equivalent, the first encountered will be returned. Otherwise, `[max](../list/index#max())` will operate independent of the order of input as long as the comparator is commutative. The default comparator `>` is commutative *only* when types do not differ.

 If `comparator` returns 0 and either value is NaN, undefined, or null, that value will be returned.

 



#### [maxBy()](index#maxBy())




Like `[max](../list/index#max())`, but also accepts a `comparatorValueMapper` which allows for comparing by more sophisticated means:

 

```
maxBy<C>(comparatorValueMapper: (value: T, key: T, iter: this) => C,comparator?: (valueA: C, valueB: C) => number): T | undefined

```

#### Inherited from


`[Collection#maxBy()](../collection/index#maxBy())`#### Discussion


 
```
const { List, } = require('immutable');
const l = List([
  { name: 'Bob', avgHit: 1 },
  { name: 'Max', avgHit: 3 },
  { name: 'Lili', avgHit: 2 } ,
]);
l.maxBy(i => i.avgHit); // will output { name: 'Max', avgHit: 3 }run it
```


 



#### [min()](index#min())




Returns the minimum value in this collection. If any values are comparatively equivalent, the first one found will be returned.

 

```
min(comparator?: (valueA: T, valueB: T) => number): T | undefined

```

#### Inherited from


`[Collection#min()](../collection/index#min())`#### Discussion



The `comparator` is used in the same way as `[Collection#sort](../collection/index#sort())`. If it is not provided, the default comparator is `<`.

 When two values are considered equivalent, the first encountered will be returned. Otherwise, `[min](../list/index#min())` will operate independent of the order of input as long as the comparator is commutative. The default comparator `<` is commutative *only* when types do not differ.

 If `comparator` returns 0 and either value is NaN, undefined, or null, that value will be returned.

 



#### [minBy()](index#minBy())




Like `[min](../list/index#min())`, but also accepts a `comparatorValueMapper` which allows for comparing by more sophisticated means:

 

```
minBy<C>(comparatorValueMapper: (value: T, key: T, iter: this) => C,comparator?: (valueA: C, valueB: C) => number): T | undefined

```

#### Inherited from


`[Collection#minBy()](../collection/index#minBy())`#### Discussion


 
```
const { List, } = require('immutable');
const l = List([
  { name: 'Bob', avgHit: 1 },
  { name: 'Max', avgHit: 3 },
  { name: 'Lili', avgHit: 2 } ,
]);
l.minBy(i => i.avgHit); // will output { name: 'Bob', avgHit: 1 }run it
```


 


### Comparison



#### [isSubset()](index#isSubset())




True if `iter` includes every value in this Collection.

 

```
isSubset(iter: Iterable<T>): boolean

```

#### Inherited from


`[Collection#isSubset()](../collection/index#isSubset())`



#### [isSuperset()](index#isSuperset())




True if this Collection includes every value in `iter`.

 

```
isSuperset(iter: Iterable<T>): boolean

```

#### Inherited from


`[Collection#isSuperset()](../collection/index#isSuperset())`

This documentation is generated from [immutable.d.ts](https://github.com/immutable-js/immutable-js/blob/main/type-definitions/immutable.d.ts). Pull requests and [Issues](https://github.com/immutable-js/immutable-js/issues) welcome.

 © 2014–present, Lee Byron and other contributors  
Licensed under the 3-clause BSD License.  

<https://immutable-js.com/docs/v4.2.1/Seq.Set/>

isAssociative()
===============



True if `maybeAssociative` is either a Keyed or Indexed Collection.

 

```
isAssociative(maybeAssociative: unknown): boolean

```

#### Discussion


 
```
const { isAssociative, Map, List, Stack, Set } = require('immutable');
isAssociative([]); // false
isAssociative({}); // false
isAssociative(Map()); // true
isAssociative(List()); // true
isAssociative(Stack()); // true
isAssociative(Set()); // falserun it
```

This documentation is generated from [immutable.d.ts](https://github.com/immutable-js/immutable-js/blob/main/type-definitions/immutable.d.ts). Pull requests and [Issues](https://github.com/immutable-js/immutable-js/issues) welcome.

 © 2014–present, Lee Byron and other contributors  
Licensed under the 3-clause BSD License.  

<https://immutable-js.com/docs/v4.2.1/isAssociative()/>

isOrdered()
===========



True if `maybeOrdered` is a Collection where iteration order is well defined. True for Collection.Indexed as well as OrderedMap and OrderedSet.

 

```
isOrdered(maybeOrdered: unknown): boolean

```

#### Discussion


 
```
const { isOrdered, Map, OrderedMap, List, Set } = require('immutable');
isOrdered([]); // false
isOrdered({}); // false
isOrdered(Map()); // false
isOrdered(OrderedMap()); // true
isOrdered(List()); // true
isOrdered(Set()); // falserun it
```

This documentation is generated from [immutable.d.ts](https://github.com/immutable-js/immutable-js/blob/main/type-definitions/immutable.d.ts). Pull requests and [Issues](https://github.com/immutable-js/immutable-js/issues) welcome.

 © 2014–present, Lee Byron and other contributors  
Licensed under the 3-clause BSD License.  

<https://immutable-js.com/docs/v4.2.1/isOrdered()/>

isMap()
=======



True if `maybeMap` is a Map.

 

```
isMap(maybeMap: unknown): boolean

```

#### Discussion



Also true for OrderedMaps.

 This documentation is generated from [immutable.d.ts](https://github.com/immutable-js/immutable-js/blob/main/type-definitions/immutable.d.ts). Pull requests and [Issues](https://github.com/immutable-js/immutable-js/issues) welcome.

 © 2014–present, Lee Byron and other contributors  
Licensed under the 3-clause BSD License.  

<https://immutable-js.com/docs/v4.2.1/isMap()/>

List
====



Lists are ordered indexed dense collections, much like a JavaScript Array.

 

```
type List<T> extends Collection.Indexed<T>
```

#### Discussion



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](index#push())`, `[pop](index#pop())`) and beginning (`[unshift](index#unshift())`, `[shift](index#shift())`).

 Unlike a JavaScript Array, there is no distinction between an "unset" index and an index set to `undefined`. `[List#forEach](index#forEach())` visits all indices from 0 to size, regardless of whether they were explicitly defined.

 
### Construction



#### [List()](index#List())




Create a new immutable List containing the values of the provided collection-like.

 

```
List<T>(collection?: Iterable<T> | ArrayLike<T>): List<T>

```

#### Discussion



Note: `[List](index)` is a factory function and not a class, and does not use the `new` keyword during construction.

 
```
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) // truerun it
```




### Static methods



#### [List.isList()](index#isList())



```
List.isList(maybeList: unknown): boolean

```



#### [List.of()](index#of())



```
List.of<T>(...values: Array<T>): List<T>

```


### Members



#### [size](index#size)




The number of items in this List.

 

```
size: number
```



### Persistent changes



#### [set()](index#set())




Returns a new List which includes `value` at `index`. If `index` already exists in this List, it will be replaced.

 

```
set(index: number, value: T): List<T>

```

#### Discussion



`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](index#size)`, the returned List's `[size](index#size)` will be large enough to include the `index`.

 
```
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;
// 50001run it
```

Note: `[set](index#set())` can be used in `[withMutations](index#withMutations())`.

 



#### [delete()](index#delete())




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.

 

```
delete(index: number): List<T>

```

#### alias


`remove()`#### Discussion



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](index#delete())` cannot be safely used in IE8

 
```
List([ 0, 1, 2, 3, 4 ]).delete(0);
// List [ 1, 2, 3, 4 ]run it
```

Since `[delete()](index#delete())` re-indexes values, it produces a complete copy, which has `O(N)` complexity.

 Note: `[delete](index#delete())` *cannot* be used in `[withMutations](index#withMutations())`.

 



#### [insert()](index#insert())




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.

 

```
insert(index: number, value: T): List<T>

```

#### Discussion



This is synonymous with `list.splice(index, 0, value)`.

 
```
List([ 0, 1, 2, 3, 4 ]).insert(6, 5)
// List [ 0, 1, 2, 3, 4, 5 ]run it
```

Since `[insert()](index#insert())` re-indexes values, it produces a complete copy, which has `O(N)` complexity.

 Note: `[insert](index#insert())` *cannot* be used in `[withMutations](index#withMutations())`.

 



#### [clear()](index#clear())




Returns a new List with 0 size and no values in constant time.

 

```
clear(): List<T>

```

#### Discussion


 
```
List([ 1, 2, 3, 4 ]).clear()
// List []run it
```

Note: `[clear](index#clear())` can be used in `[withMutations](index#withMutations())`.

 



#### [push()](index#push())




Returns a new List with the provided `values` appended, starting at this List's `[size](index#size)`.

 

```
push(...values: Array<T>): List<T>

```

#### Discussion


 
```
List([ 1, 2, 3, 4 ]).push(5)
// List [ 1, 2, 3, 4, 5 ]run it
```

Note: `[push](index#push())` can be used in `[withMutations](index#withMutations())`.

 



#### [pop()](index#pop())




Returns a new List with a size ones less than this List, excluding the last index in this List.

 

```
pop(): List<T>

```

#### Discussion



Note: this differs from `[Array#pop](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/pop)` because it returns a new List rather than the removed value. Use `[last()](index#last())` to get the last value in this List.

 
```
List([ 1, 2, 3, 4 ]).pop()
// List[ 1, 2, 3 ]
```

Note: `[pop](index#pop())` can be used in `[withMutations](index#withMutations())`.

 



#### [unshift()](index#unshift())




Returns a new List with the provided `values` prepended, shifting other values ahead to higher indices.

 

```
unshift(...values: Array<T>): List<T>

```

#### Discussion


 
```
List([ 2, 3, 4]).unshift(1);
// List [ 1, 2, 3, 4 ]run it
```

Note: `[unshift](index#unshift())` can be used in `[withMutations](index#withMutations())`.

 



#### [shift()](index#shift())




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.

 

```
shift(): List<T>

```

#### Discussion



Note: this differs from `[Array#shift](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/shift)` because it returns a new List rather than the removed value. Use `[first()](index#first())` to get the first value in this List.

 
```
List([ 0, 1, 2, 3, 4 ]).shift();
// List [ 1, 2, 3, 4 ]run it
```

Note: `[shift](index#shift())` can be used in `[withMutations](index#withMutations())`.

 



#### [update()](index#update())




```
update(index: number, notSetValue: T, updater: (value: T) => T): this
update(index: number, updater: (value: T | undefined) => T): this
update<R>(updater: (value: this) => R): R

```

#### Overrides


`[Collection#update()](../collection/index#update())`



#### [setSize()](index#setSize())




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.

 

```
setSize(size: number): List<T>

```

#### Discussion



When building a new List and the final size is known up front, `[setSize](index#setSize())` used in conjunction with `[withMutations](index#withMutations())` may result in the more performant construction.

 


### Deep persistent changes



#### [setIn()](index#setIn())




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.

 

```
setIn(keyPath: Iterable<unknown>, value: unknown): this

```

#### Discussion



Index numbers are used as keys to determine the path to follow in the List.

 
```
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 ] ]run it
```

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.

 
```
const { List } = require('immutable')
const list = List([ 0, 1, 2, { plain: 'object' }])
list.setIn([3, 'plain'], 'value');
// List([ 0, 1, 2, { plain: 'value' }])run it
```

Note: `[setIn](index#setIn())` can be used in `[withMutations](index#withMutations())`.

 



#### [deleteIn()](index#deleteIn())




Returns a new List having removed the value at this `keyPath`. If any keys in `keyPath` do not exist, no change will occur.

 

```
deleteIn(keyPath: Iterable<unknown>): this

```

#### alias


`removeIn()`#### Discussion


 
```
const { List } = require('immutable')
const list = List([ 0, 1, 2, List([ 3, 4 ])])
list.deleteIn([3, 0]);
// List [ 0, 1, 2, List [ 4 ] ]run it
```

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.

 
```
const { List } = require('immutable')
const list = List([ 0, 1, 2, { plain: 'object' }])
list.removeIn([3, 'plain']);
// List([ 0, 1, 2, {}])run it
```

Note: `[deleteIn](index#deleteIn())` *cannot* be safely used in `[withMutations](index#withMutations())`.

 



#### [updateIn()](index#updateIn())



```
updateIn(keyPath: Iterable<unknown>,notSetValue: unknown,updater: (value: unknown) => unknown): this
updateIn(keyPath: Iterable<unknown>, updater: (value: unknown) => unknown): this

```



#### [mergeIn()](index#mergeIn())




Note: `[mergeIn](index#mergeIn())` can be used in `[withMutations](index#withMutations())`.

 

```
mergeIn(keyPath: Iterable<unknown>, ...collections: Array<unknown>): this

```

#### see



`[Map#mergeIn](../map/index#mergeIn())`

 



#### [mergeDeepIn()](index#mergeDeepIn())




Note: `[mergeDeepIn](index#mergeDeepIn())` can be used in `[withMutations](index#withMutations())`.

 

```
mergeDeepIn(keyPath: Iterable<unknown>, ...collections: Array<unknown>): this

```

#### see



`[Map#mergeDeepIn](../map/index#mergeDeepIn())`

 


### Transient changes



#### [withMutations()](index#withMutations())




Note: Not all methods can be safely used on a mutable collection or within `[withMutations](index#withMutations())`! Check the documentation for each method to see if it allows being used in `[withMutations](index#withMutations())`.

 

```
withMutations(mutator: (mutable: this) => unknown): this

```

#### see



`[Map#withMutations](../map/index#withMutations())`

 



#### [asMutable()](index#asMutable())




An alternative API for withMutations()

 

```
asMutable(): this

```

#### see



`[Map#asMutable](../map/index#asMutable())`

 
#### Discussion



Note: Not all methods can be safely used on a mutable collection or within `[withMutations](index#withMutations())`! Check the documentation for each method to see if it allows being used in `[withMutations](index#withMutations())`.

 



#### [wasAltered()](index#wasAltered())




```
wasAltered(): boolean

```

#### see



`[Map#wasAltered](../map/index#wasAltered())`

 



#### [asImmutable()](index#asImmutable())




```
asImmutable(): this

```

#### see



`[Map#asImmutable](../map/index#asImmutable())`

 


### Sequence algorithms



#### [concat()](index#concat())




Returns a new List with other values or collections concatenated to this one.

 

```
concat<C>(...valuesOrCollections: Array<Iterable<C> | C>): List<T | C>

```

#### Overrides


`[Collection.Indexed#concat()](../collection.indexed/index#concat())`#### alias


`merge()`#### Discussion



Note: `[concat](index#concat())` can be used in `[withMutations](index#withMutations())`.

 



#### [map()](index#map())




Returns a new List with values passed through a `mapper` function.

 

```
map<M>(mapper: (value: T, key: number, iter: this) => M,context?: unknown): List<M>

```

#### Overrides


`[Collection.Indexed#map()](../collection.indexed/index#map())`#### Discussion


 
```
List([ 1, 2 ]).map(x => 10 * x)
// List [ 10, 20 ]run it
```





#### [flatMap()](index#flatMap())




Flat-maps the List, returning a new List.

 

```
flatMap<M>(mapper: (value: T, key: number, iter: this) => Iterable<M>,context?: unknown): List<M>

```

#### Overrides


`[Collection.Indexed#flatMap()](../collection.indexed/index#flatMap())`#### Discussion



Similar to `list.map(...).flatten(true)`.

 



#### [filter()](index#filter())




```
filter<F>(predicate: (value: T, index: number, iter: this) => boolean,context?: unknown): List<F>
filter(predicate: (value: T, index: number, iter: this) => unknown,context?: unknown): this

```

#### Overrides


`[Collection.Indexed#filter()](../collection.indexed/index#filter())`



#### [partition()](index#partition())




```
partition<F, C>(predicate: (this: C, value: T, index: number, iter: this) => boolean,context?: C): [List<T>, List<F>]
partition<C>(predicate: (this: C, value: T, index: number, iter: this) => unknown,context?: C): [this, this]

```

#### Overrides


`[Collection.Indexed#partition()](../collection.indexed/index#partition())`



#### [zip()](index#zip())




```
zip<U>(other: Collection<unknown, U>): List<[T, U]>
zip<U, V>(other: Collection<unknown, U>,other2: Collection<unknown, V>): List<[T, U, V]>
zip(...collections: Array<Collection<unknown, unknown>>): List<unknown>

```

#### Overrides


`[Collection.Indexed#zip()](../collection.indexed/index#zip())`



#### [zipAll()](index#zipAll())




```
zipAll<U>(other: Collection<unknown, U>): List<[T, U]>
zipAll<U, V>(other: Collection<unknown, U>,other2: Collection<unknown, V>): List<[T, U, V]>
zipAll(...collections: Array<Collection<unknown, unknown>>): List<unknown>

```

#### Overrides


`[Collection.Indexed#zipAll()](../collection.indexed/index#zipAll())`



#### [zipWith()](index#zipWith())




```
zipWith<U, Z>(zipper: (value: T, otherValue: U) => Z,otherCollection: Collection<unknown, U>): List<Z>
zipWith<U, V, Z>(zipper: (value: T, otherValue: U, thirdValue: V) => Z,otherCollection: Collection<unknown, U>,thirdCollection: Collection<unknown, V>): List<Z>
zipWith<Z>(zipper: (...values: Array<unknown>) => Z,...collections: Array<Collection<unknown, unknown>>): List<Z>

```

#### Overrides


`[Collection.Indexed#zipWith()](../collection.indexed/index#zipWith())`



#### [[Symbol.iterator]()](index#%5BSymbol.iterator%5D())




```
[Symbol.iterator](): IterableIterator<T>

```

#### Inherited from


`[Collection.Indexed#[Symbol.iterator]()](../collection.indexed/index#%5BSymbol.iterator%5D())`



#### [filterNot()](index#filterNot())




Returns a new Collection of the same type with only the entries for which the `predicate` function returns false.

 

```
filterNot(predicate: (value: T, key: number, iter: this) => boolean,context?: unknown): this

```

#### Inherited from


`[Collection#filterNot()](../collection/index#filterNot())`#### Discussion


 
```
const { Map } = require('immutable')
Map({ a: 1, b: 2, c: 3, d: 4}).filterNot(x => x % 2 === 0)
// Map { "a": 1, "c": 3 }run it
```



Note: `[filterNot()](index#filterNot())` always returns a new instance, even if it results in not filtering out any values.

 



#### [reverse()](index#reverse())




Returns a new Collection of the same type in reverse order.

 

```
reverse(): this

```

#### Inherited from


`[Collection#reverse()](../collection/index#reverse())`



#### [sort()](index#sort())




Returns a new Collection of the same type which includes the same entries, stably sorted by using a `comparator`.

 

```
sort(comparator?: (valueA: T, valueB: T) => number): this

```

#### Inherited from


`[Collection#sort()](../collection/index#sort())`#### Discussion



If a `comparator` is not provided, a default comparator uses `<` and `>`.

 `comparator(valueA, valueB)`:

 * Returns `0` if the elements should not be swapped.
* Returns `-1` (or any negative number) if `valueA` comes before `valueB`
* Returns `1` (or any positive number) if `valueA` comes after `valueB`
* Is pure, i.e. it must always return the same value for the same pair of values.

 When sorting collections which have no defined order, their ordered equivalents will be returned. e.g. `map.sort()` returns OrderedMap.

 
```
const { Map } = require('immutable')
Map({ "c": 3, "a": 1, "b": 2 }).sort((a, b) => {
  if (a < b) { return -1; }
  if (a > b) { return 1; }
  if (a === b) { return 0; }
});
// OrderedMap { "a": 1, "b": 2, "c": 3 }run it
```

Note: `[sort()](index#sort())` Always returns a new instance, even if the original was already sorted.

 Note: This is always an eager operation.

 



#### [sortBy()](index#sortBy())




Like `[sort](index#sort())`, but also accepts a `comparatorValueMapper` which allows for sorting by more sophisticated means:

 

```
sortBy<C>(comparatorValueMapper: (value: T, key: number, iter: this) => C,comparator?: (valueA: C, valueB: C) => number): this

```

#### Inherited from


`[Collection#sortBy()](../collection/index#sortBy())`#### Discussion


 
```
const { Map } = require('immutable')
const beattles = Map({
  John: { name: "Lennon" },
  Paul: { name: "McCartney" },
  George: { name: "Harrison" },
  Ringo: { name: "Starr" },
});
beattles.sortBy(member => member.name);run it
```



Note: `[sortBy()](index#sortBy())` Always returns a new instance, even if the original was already sorted.

 Note: This is always an eager operation.

 



#### [groupBy()](index#groupBy())




Returns a `[Collection.Keyed](../collection.keyed/index)` of `Collection.Keyeds`, grouped by the return value of the `grouper` function.

 

```
groupBy<G>(grouper: (value: T, key: number, iter: this) => G,context?: unknown): Seq.Keyed<G, Collection<number, T>>

```

#### Inherited from


`[Collection#groupBy()](../collection/index#groupBy())`#### Discussion



Note: This is always an eager operation.

 
```
const { List, Map } = require('immutable')
const listOfMaps = List([
  Map({ v: 0 }),
  Map({ v: 1 }),
  Map({ v: 1 }),
  Map({ v: 0 }),
  Map({ v: 2 })
])
const groupsOfMaps = listOfMaps.groupBy(x => x.get('v'))
// Map {
//   0: List [ Map{ "v": 0 }, Map { "v": 0 } ],
//   1: List [ Map{ "v": 1 }, Map { "v": 1 } ],
//   2: List [ Map{ "v": 2 } ],
// }run it
```




### Conversion to JavaScript types



#### [toJS()](index#toJS())




Deeply converts this Indexed collection to equivalent native JavaScript Array.

 

```
toJS(): Array<DeepCopy<T>>

```

#### Inherited from


`[Collection.Indexed#toJS()](../collection.indexed/index#toJS())`



#### [toJSON()](index#toJSON())




Shallowly converts this Indexed collection to equivalent native JavaScript Array.

 

```
toJSON(): Array<T>

```

#### Inherited from


`[Collection.Indexed#toJSON()](../collection.indexed/index#toJSON())`



#### [toArray()](index#toArray())




Shallowly converts this collection to an Array.

 

```
toArray(): Array<T>

```

#### Inherited from


`[Collection.Indexed#toArray()](../collection.indexed/index#toArray())`



#### [toObject()](index#toObject())




Shallowly converts this Collection to an Object.

 

```
toObject(): {[key: string]: T}

```

#### Inherited from


`[Collection#toObject()](../collection/index#toObject())`#### Discussion



Converts keys to Strings.

 


### Reading values



#### [get()](index#get())




```
get<NSV>(index: number, notSetValue: NSV): T | NSV
get(index: number): T | undefined

```

#### Inherited from


`[Collection.Indexed#get()](../collection.indexed/index#get())`



#### [has()](index#has())




True if a key exists within this `[Collection](../collection/index)`, using `[Immutable.is](../is()/index)` to determine equality

 

```
has(key: number): boolean

```

#### Inherited from


`[Collection#has()](../collection/index#has())`



#### [includes()](index#includes())




True if a value exists within this `[Collection](../collection/index)`, using `[Immutable.is](../is()/index)` to determine equality

 

```
includes(value: T): boolean

```

#### Inherited from


`[Collection#includes()](../collection/index#includes())`#### alias


`contains()`



#### [first()](index#first())




In case the `[Collection](../collection/index)` is not empty returns the first element of the `[Collection](../collection/index)`. In case the `[Collection](../collection/index)` is empty returns the optional default value if provided, if no default value is provided returns undefined.

 

```
first<NSV>(notSetValue?: NSV): T | NSV

```

#### Inherited from


`[Collection#first()](../collection/index#first())`



#### [last()](index#last())




In case the `[Collection](../collection/index)` is not empty returns the last element of the `[Collection](../collection/index)`. In case the `[Collection](../collection/index)` is empty returns the optional default value if provided, if no default value is provided returns undefined.

 

```
last<NSV>(notSetValue?: NSV): T | NSV

```

#### Inherited from


`[Collection#last()](../collection/index#last())`


### Conversion to Seq



#### [toSeq()](index#toSeq())




Returns Seq.Indexed.

 

```
toSeq(): Seq.Indexed<T>

```

#### Inherited from


`[Collection.Indexed#toSeq()](../collection.indexed/index#toSeq())`



#### [fromEntrySeq()](index#fromEntrySeq())




If this is a collection of [key, value] entry tuples, it will return a Seq.Keyed of those entries.

 

```
fromEntrySeq(): Seq.Keyed<unknown, unknown>

```

#### Inherited from


`[Collection.Indexed#fromEntrySeq()](../collection.indexed/index#fromEntrySeq())`



#### [toKeyedSeq()](index#toKeyedSeq())




Returns a Seq.Keyed from this Collection where indices are treated as keys.

 

```
toKeyedSeq(): Seq.Keyed<number, T>

```

#### Inherited from


`[Collection#toKeyedSeq()](../collection/index#toKeyedSeq())`#### Discussion



This is useful if you want to operate on an Collection.Indexed and preserve the [index, value] pairs.

 The returned Seq will have identical iteration order as this Collection.

 
```
const { Seq } = require('immutable')
const indexedSeq = Seq([ 'A', 'B', 'C' ])
// Seq [ "A", "B", "C" ]
indexedSeq.filter(v => v === 'B')
// Seq [ "B" ]
const keyedSeq = indexedSeq.toKeyedSeq()
// Seq { 0: "A", 1: "B", 2: "C" }
keyedSeq.filter(v => v === 'B')
// Seq { 1: "B" }run it
```





#### [toIndexedSeq()](index#toIndexedSeq())




Returns an Seq.Indexed of the values of this Collection, discarding keys.

 

```
toIndexedSeq(): Seq.Indexed<T>

```

#### Inherited from


`[Collection#toIndexedSeq()](../collection/index#toIndexedSeq())`



#### [toSetSeq()](index#toSetSeq())




Returns a Seq.Set of the values of this Collection, discarding keys.

 

```
toSetSeq(): Seq.Set<T>

```

#### Inherited from


`[Collection#toSetSeq()](../collection/index#toSetSeq())`


### Combination



#### [interpose()](index#interpose())




Returns a Collection of the same type with `separator` between each item in this Collection.

 

```
interpose(separator: T): this

```

#### Inherited from


`[Collection.Indexed#interpose()](../collection.indexed/index#interpose())`



#### [interleave()](index#interleave())




Returns a Collection of the same type with the provided `collections` interleaved into this collection.

 

```
interleave(...collections: Array<Collection<unknown, T>>): this

```

#### Inherited from


`[Collection.Indexed#interleave()](../collection.indexed/index#interleave())`#### Discussion



The resulting Collection includes the first item from each, then the second from each, etc.

 
```
const { List } = require('immutable')
List([ 1, 2, 3 ]).interleave(List([ 'A', 'B', 'C' ]))
// List [ 1, "A", 2, "B", 3, "C" ]run it
```

The shortest Collection stops interleave.

 
```
List([ 1, 2, 3 ]).interleave(
  List([ 'A', 'B' ]),
  List([ 'X', 'Y', 'Z' ])
)
// List [ 1, "A", "X", 2, "B", "Y" ]run it
```

Since `[interleave()](index#interleave())` re-indexes values, it produces a complete copy, which has `O(N)` complexity.

 Note: `[interleave](index#interleave())` *cannot* be used in `[withMutations](index#withMutations())`.

 



#### [splice()](index#splice())




Splice returns a new indexed Collection by replacing a region of this Collection with new values. If values are not provided, it only skips the region to be removed.

 

```
splice(index: number, removeNum: number, ...values: Array<T>): this

```

#### Inherited from


`[Collection.Indexed#splice()](../collection.indexed/index#splice())`#### Discussion



`index` may be a negative number, which indexes back from the end of the Collection. `s.splice(-2)` splices after the second to last item.

 
```
const { List } = require('immutable')
List([ 'a', 'b', 'c', 'd' ]).splice(1, 2, 'q', 'r', 's')
// List [ "a", "q", "r", "s", "d" ]run it
```

Since `[splice()](index#splice())` re-indexes values, it produces a complete copy, which has `O(N)` complexity.

 Note: `[splice](index#splice())` *cannot* be used in `[withMutations](index#withMutations())`.

 



#### [flatten()](index#flatten())




```
flatten(depth?: number): Collection<unknown, unknown>
flatten(shallow?: boolean): Collection<unknown, unknown>

```

#### Inherited from


`[Collection#flatten()](../collection/index#flatten())`


### Search for value



#### [indexOf()](index#indexOf())




Returns the first index at which a given value can be found in the Collection, or -1 if it is not present.

 

```
indexOf(searchValue: T): number

```

#### Inherited from


`[Collection.Indexed#indexOf()](../collection.indexed/index#indexOf())`



#### [lastIndexOf()](index#lastIndexOf())




Returns the last index at which a given value can be found in the Collection, or -1 if it is not present.

 

```
lastIndexOf(searchValue: T): number

```

#### Inherited from


`[Collection.Indexed#lastIndexOf()](../collection.indexed/index#lastIndexOf())`



#### [findIndex()](index#findIndex())




Returns the first index in the Collection where a value satisfies the provided predicate function. Otherwise -1 is returned.

 

```
findIndex(predicate: (value: T, index: number, iter: this) => boolean,context?: unknown): number

```

#### Inherited from


`[Collection.Indexed#findIndex()](../collection.indexed/index#findIndex())`



#### [findLastIndex()](index#findLastIndex())




Returns the last index in the Collection where a value satisfies the provided predicate function. Otherwise -1 is returned.

 

```
findLastIndex(predicate: (value: T, index: number, iter: this) => boolean,context?: unknown): number

```

#### Inherited from


`[Collection.Indexed#findLastIndex()](../collection.indexed/index#findLastIndex())`



#### [find()](index#find())




Returns the first value for which the `predicate` returns true.

 

```
find(predicate: (value: T, key: number, iter: this) => boolean,context?: unknown,notSetValue?: T): T | undefined

```

#### Inherited from


`[Collection#find()](../collection/index#find())`



#### [findLast()](index#findLast())




Returns the last value for which the `predicate` returns true.

 

```
findLast(predicate: (value: T, key: number, iter: this) => boolean,context?: unknown,notSetValue?: T): T | undefined

```

#### Inherited from


`[Collection#findLast()](../collection/index#findLast())`#### Discussion



Note: `predicate` will be called for each entry in reverse.

 



#### [findEntry()](index#findEntry())




Returns the first [key, value] entry for which the `predicate` returns true.

 

```
findEntry(predicate: (value: T, key: number, iter: this) => boolean,context?: unknown,notSetValue?: T): [number, T] | undefined

```

#### Inherited from


`[Collection#findEntry()](../collection/index#findEntry())`



#### [findLastEntry()](index#findLastEntry())




Returns the last [key, value] entry for which the `predicate` returns true.

 

```
findLastEntry(predicate: (value: T, key: number, iter: this) => boolean,context?: unknown,notSetValue?: T): [number, T] | undefined

```

#### Inherited from


`[Collection#findLastEntry()](../collection/index#findLastEntry())`#### Discussion



Note: `predicate` will be called for each entry in reverse.

 



#### [findKey()](index#findKey())




Returns the key for which the `predicate` returns true.

 

```
findKey(predicate: (value: T, key: number, iter: this) => boolean,context?: unknown): number | undefined

```

#### Inherited from


`[Collection#findKey()](../collection/index#findKey())`



#### [findLastKey()](index#findLastKey())




Returns the last key for which the `predicate` returns true.

 

```
findLastKey(predicate: (value: T, key: number, iter: this) => boolean,context?: unknown): number | undefined

```

#### Inherited from


`[Collection#findLastKey()](../collection/index#findLastKey())`#### Discussion



Note: `predicate` will be called for each entry in reverse.

 



#### [keyOf()](index#keyOf())




Returns the key associated with the search value, or undefined.

 

```
keyOf(searchValue: T): number | undefined

```

#### Inherited from


`[Collection#keyOf()](../collection/index#keyOf())`



#### [lastKeyOf()](index#lastKeyOf())




Returns the last key associated with the search value, or undefined.

 

```
lastKeyOf(searchValue: T): number | undefined

```

#### Inherited from


`[Collection#lastKeyOf()](../collection/index#lastKeyOf())`



#### [max()](index#max())




Returns the maximum value in this collection. If any values are comparatively equivalent, the first one found will be returned.

 

```
max(comparator?: (valueA: T, valueB: T) => number): T | undefined

```

#### Inherited from


`[Collection#max()](../collection/index#max())`#### Discussion



The `comparator` is used in the same way as `[Collection#sort](../collection/index#sort())`. If it is not provided, the default comparator is `>`.

 When two values are considered equivalent, the first encountered will be returned. Otherwise, `[max](index#max())` will operate independent of the order of input as long as the comparator is commutative. The default comparator `>` is commutative *only* when types do not differ.

 If `comparator` returns 0 and either value is NaN, undefined, or null, that value will be returned.

 



#### [maxBy()](index#maxBy())




Like `[max](index#max())`, but also accepts a `comparatorValueMapper` which allows for comparing by more sophisticated means:

 

```
maxBy<C>(comparatorValueMapper: (value: T, key: number, iter: this) => C,comparator?: (valueA: C, valueB: C) => number): T | undefined

```

#### Inherited from


`[Collection#maxBy()](../collection/index#maxBy())`#### Discussion


 
```
const { List, } = require('immutable');
const l = List([
  { name: 'Bob', avgHit: 1 },
  { name: 'Max', avgHit: 3 },
  { name: 'Lili', avgHit: 2 } ,
]);
l.maxBy(i => i.avgHit); // will output { name: 'Max', avgHit: 3 }run it
```


 



#### [min()](index#min())




Returns the minimum value in this collection. If any values are comparatively equivalent, the first one found will be returned.

 

```
min(comparator?: (valueA: T, valueB: T) => number): T | undefined

```

#### Inherited from


`[Collection#min()](../collection/index#min())`#### Discussion



The `comparator` is used in the same way as `[Collection#sort](../collection/index#sort())`. If it is not provided, the default comparator is `<`.

 When two values are considered equivalent, the first encountered will be returned. Otherwise, `[min](index#min())` will operate independent of the order of input as long as the comparator is commutative. The default comparator `<` is commutative *only* when types do not differ.

 If `comparator` returns 0 and either value is NaN, undefined, or null, that value will be returned.

 



#### [minBy()](index#minBy())




Like `[min](index#min())`, but also accepts a `comparatorValueMapper` which allows for comparing by more sophisticated means:

 

```
minBy<C>(comparatorValueMapper: (value: T, key: number, iter: this) => C,comparator?: (valueA: C, valueB: C) => number): T | undefined

```

#### Inherited from


`[Collection#minBy()](../collection/index#minBy())`#### Discussion


 
```
const { List, } = require('immutable');
const l = List([
  { name: 'Bob', avgHit: 1 },
  { name: 'Max', avgHit: 3 },
  { name: 'Lili', avgHit: 2 } ,
]);
l.minBy(i => i.avgHit); // will output { name: 'Bob', avgHit: 1 }run it
```


 


### Value equality



#### [equals()](index#equals())




True if this and the other Collection have value equality, as defined by `[Immutable.is()](../is()/index)`.

 

```
equals(other: unknown): boolean

```

#### Inherited from


`[Collection#equals()](../collection/index#equals())`#### Discussion



Note: This is equivalent to `Immutable.is(this, other)`, but provided to allow for chained expressions.

 



#### [hashCode()](index#hashCode())




Computes and returns the hashed identity for this Collection.

 

```
hashCode(): number

```

#### Inherited from


`[Collection#hashCode()](../collection/index#hashCode())`#### Discussion



The `[hashCode](index#hashCode())` of a Collection is used to determine potential equality, and is used when adding this to a `[Set](../set/index)` or as a key in a `[Map](../map/index)`, enabling lookup via a different instance.

 
```
const a = List([ 1, 2, 3 ]);
const b = List([ 1, 2, 3 ]);
assert.notStrictEqual(a, b); // different instances
const set = Set([ a ]);
assert.equal(set.has(b), true);run it
```

If two values have the same `[hashCode](index#hashCode())`, they are [not guaranteed to be equal](https://en.wikipedia.org/wiki/Collision_(computer_science)). If two values have different `[hashCode](index#hashCode())`s, they must not be equal.

 


### Reading deep values



#### [getIn()](index#getIn())




Returns the value found by following a path of keys or indices through nested Collections.

 

```
getIn(searchKeyPath: Iterable<unknown>, notSetValue?: unknown): unknown

```

#### Inherited from


`[Collection#getIn()](../collection/index#getIn())`#### Discussion


 
```
const { Map, List } = require('immutable')
const deepData = Map({ x: List([ Map({ y: 123 }) ]) });
deepData.getIn(['x', 0, 'y']) // 123run it
```



Plain JavaScript Object or Arrays may be nested within an Immutable.js Collection, and getIn() can access those values as well:

 
```
const { Map, List } = require('immutable')
const deepData = Map({ x: [ { y: 123 } ] });
deepData.getIn(['x', 0, 'y']) // 123run it
```


 



#### [hasIn()](index#hasIn())




True if the result of following a path of keys or indices through nested Collections results in a set value.

 

```
hasIn(searchKeyPath: Iterable<unknown>): boolean

```

#### Inherited from


`[Collection#hasIn()](../collection/index#hasIn())`


### Conversion to Collections



#### [toMap()](index#toMap())




Converts this Collection to a Map, Throws if keys are not hashable.

 

```
toMap(): Map<number, T>

```

#### Inherited from


`[Collection#toMap()](../collection/index#toMap())`#### Discussion



Note: This is equivalent to `Map(this.toKeyedSeq())`, but provided for convenience and to allow for chained expressions.

 



#### [toOrderedMap()](index#toOrderedMap())




Converts this Collection to a Map, maintaining the order of iteration.

 

```
toOrderedMap(): OrderedMap<number, T>

```

#### Inherited from


`[Collection#toOrderedMap()](../collection/index#toOrderedMap())`#### Discussion



Note: This is equivalent to `OrderedMap(this.toKeyedSeq())`, but provided for convenience and to allow for chained expressions.

 



#### [toSet()](index#toSet())




Converts this Collection to a Set, discarding keys. Throws if values are not hashable.

 

```
toSet(): Set<T>

```

#### Inherited from


`[Collection#toSet()](../collection/index#toSet())`#### Discussion



Note: This is equivalent to `[Set(this)](../set/index)`, but provided to allow for chained expressions.

 



#### [toOrderedSet()](index#toOrderedSet())




Converts this Collection to a Set, maintaining the order of iteration and discarding keys.

 

```
toOrderedSet(): OrderedSet<T>

```

#### Inherited from


`[Collection#toOrderedSet()](../collection/index#toOrderedSet())`#### Discussion



Note: This is equivalent to `OrderedSet(this.valueSeq())`, but provided for convenience and to allow for chained expressions.

 



#### [toList()](index#toList())




Converts this Collection to a List, discarding keys.

 

```
toList(): List<T>

```

#### Inherited from


`[Collection#toList()](../collection/index#toList())`#### Discussion



This is similar to `[List(collection)](index)`, but provided to allow for chained expressions. However, when called on `[Map](../map/index)` or other keyed collections, `collection.toList()` discards the keys and creates a list of only the values, whereas `[List(collection)](index)` creates a list of entry tuples.

 
```
const { Map, List } = require('immutable')
var myMap = Map({ a: 'Apple', b: 'Banana' })
List(myMap) // List [ [ "a", "Apple" ], [ "b", "Banana" ] ]
myMap.toList() // List [ "Apple", "Banana" ]run it
```





#### [toStack()](index#toStack())




Converts this Collection to a Stack, discarding keys. Throws if values are not hashable.

 

```
toStack(): Stack<T>

```

#### Inherited from


`[Collection#toStack()](../collection/index#toStack())`#### Discussion



Note: This is equivalent to `[Stack(this)](../stack/index)`, but provided to allow for chained expressions.

 


### Iterators



#### [keys()](index#keys())




An iterator of this `[Collection](../collection/index)`'s keys.

 

```
keys(): IterableIterator<number>

```

#### Inherited from


`[Collection#keys()](../collection/index#keys())`#### Discussion



Note: this will return an ES6 iterator which does not support Immutable.js sequence algorithms. Use `[keySeq](index#keySeq())` instead, if this is what you want.

 



#### [values()](index#values())




An iterator of this `[Collection](../collection/index)`'s values.

 

```
values(): IterableIterator<T>

```

#### Inherited from


`[Collection#values()](../collection/index#values())`#### Discussion



Note: this will return an ES6 iterator which does not support Immutable.js sequence algorithms. Use `[valueSeq](index#valueSeq())` instead, if this is what you want.

 



#### [entries()](index#entries())




An iterator of this `[Collection](../collection/index)`'s entries as `[ key, value ]` tuples.

 

```
entries(): IterableIterator<[number, T]>

```

#### Inherited from


`[Collection#entries()](../collection/index#entries())`#### Discussion



Note: this will return an ES6 iterator which does not support Immutable.js sequence algorithms. Use `[entrySeq](index#entrySeq())` instead, if this is what you want.

 


### Collections (Seq)



#### [keySeq()](index#keySeq())




Returns a new Seq.Indexed of the keys of this Collection, discarding values.

 

```
keySeq(): Seq.Indexed<number>

```

#### Inherited from


`[Collection#keySeq()](../collection/index#keySeq())`



#### [valueSeq()](index#valueSeq())




Returns an Seq.Indexed of the values of this Collection, discarding keys.

 

```
valueSeq(): Seq.Indexed<T>

```

#### Inherited from


`[Collection#valueSeq()](../collection/index#valueSeq())`



#### [entrySeq()](index#entrySeq())




Returns a new Seq.Indexed of [key, value] tuples.

 

```
entrySeq(): Seq.Indexed<[number, T]>

```

#### Inherited from


`[Collection#entrySeq()](../collection/index#entrySeq())`


### Side effects



#### [forEach()](index#forEach())




The `sideEffect` is executed for every entry in the Collection.

 

```
forEach(sideEffect: (value: T, key: number, iter: this) => unknown,context?: unknown): number

```

#### Inherited from


`[Collection#forEach()](../collection/index#forEach())`#### Discussion



Unlike `[Array#forEach](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/forEach)`, if any call of `sideEffect` returns `false`, the iteration will stop. Returns the number of entries iterated (including the last iteration which returned false).

 


### Creating subsets



#### [slice()](index#slice())




Returns a new Collection of the same type representing a portion of this Collection from start up to but not including end.

 

```
slice(begin?: number, end?: number): this

```

#### Inherited from


`[Collection#slice()](../collection/index#slice())`#### Discussion



If begin is negative, it is offset from the end of the Collection. e.g. `slice(-2)` returns a Collection of the last two entries. If it is not provided the new Collection will begin at the beginning of this Collection.

 If end is negative, it is offset from the end of the Collection. e.g. `slice(0, -1)` returns a Collection of everything but the last entry. If it is not provided, the new Collection will continue through the end of this Collection.

 If the requested slice is equivalent to the current Collection, then it will return itself.

 



#### [rest()](index#rest())




Returns a new Collection of the same type containing all entries except the first.

 

```
rest(): this

```

#### Inherited from


`[Collection#rest()](../collection/index#rest())`



#### [butLast()](index#butLast())




Returns a new Collection of the same type containing all entries except the last.

 

```
butLast(): this

```

#### Inherited from


`[Collection#butLast()](../collection/index#butLast())`



#### [skip()](index#skip())




Returns a new Collection of the same type which excludes the first `amount` entries from this Collection.

 

```
skip(amount: number): this

```

#### Inherited from


`[Collection#skip()](../collection/index#skip())`



#### [skipLast()](index#skipLast())




Returns a new Collection of the same type which excludes the last `amount` entries from this Collection.

 

```
skipLast(amount: number): this

```

#### Inherited from


`[Collection#skipLast()](../collection/index#skipLast())`



#### [skipWhile()](index#skipWhile())




Returns a new Collection of the same type which includes entries starting from when `predicate` first returns false.

 

```
skipWhile(predicate: (value: T, key: number, iter: this) => boolean,context?: unknown): this

```

#### Inherited from


`[Collection#skipWhile()](../collection/index#skipWhile())`#### Discussion


 
```
const { List } = require('immutable')
List([ 'dog', 'frog', 'cat', 'hat', 'god' ])
  .skipWhile(x => x.match(/g/))
// List [ "cat", "hat", "god" ]run it
```


 



#### [skipUntil()](index#skipUntil())




Returns a new Collection of the same type which includes entries starting from when `predicate` first returns true.

 

```
skipUntil(predicate: (value: T, key: number, iter: this) => boolean,context?: unknown): this

```

#### Inherited from


`[Collection#skipUntil()](../collection/index#skipUntil())`#### Discussion


 
```
const { List } = require('immutable')
List([ 'dog', 'frog', 'cat', 'hat', 'god' ])
  .skipUntil(x => x.match(/hat/))
// List [ "hat", "god" ]run it
```


 



#### [take()](index#take())




Returns a new Collection of the same type which includes the first `amount` entries from this Collection.

 

```
take(amount: number): this

```

#### Inherited from


`[Collection#take()](../collection/index#take())`



#### [takeLast()](index#takeLast())




Returns a new Collection of the same type which includes the last `amount` entries from this Collection.

 

```
takeLast(amount: number): this

```

#### Inherited from


`[Collection#takeLast()](../collection/index#takeLast())`



#### [takeWhile()](index#takeWhile())




Returns a new Collection of the same type which includes entries from this Collection as long as the `predicate` returns true.

 

```
takeWhile(predicate: (value: T, key: number, iter: this) => boolean,context?: unknown): this

```

#### Inherited from


`[Collection#takeWhile()](../collection/index#takeWhile())`#### Discussion


 
```
const { List } = require('immutable')
List([ 'dog', 'frog', 'cat', 'hat', 'god' ])
  .takeWhile(x => x.match(/o/))
// List [ "dog", "frog" ]run it
```


 



#### [takeUntil()](index#takeUntil())




Returns a new Collection of the same type which includes entries from this Collection as long as the `predicate` returns false.

 

```
takeUntil(predicate: (value: T, key: number, iter: this) => boolean,context?: unknown): this

```

#### Inherited from


`[Collection#takeUntil()](../collection/index#takeUntil())`#### Discussion


 
```
const { List } = require('immutable')
List([ 'dog', 'frog', 'cat', 'hat', 'god' ])
  .takeUntil(x => x.match(/at/))
// List [ "dog", "frog" ]run it
```


 


### Reducing a value



#### [reduce()](index#reduce())




```
reduce<R>(reducer: (reduction: R, value: T, key: number, iter: this) => R,initialReduction: R,context?: unknown): R
reduce<R>(reducer: (reduction: T | R, value: T, key: number, iter: this) => R): R

```

#### Inherited from


`[Collection#reduce()](../collection/index#reduce())`



#### [reduceRight()](index#reduceRight())




```
reduceRight<R>(reducer: (reduction: R, value: T, key: number, iter: this) => R,initialReduction: R,context?: unknown): R
reduceRight<R>(reducer: (reduction: T | R, value: T, key: number, iter: this) => R): R

```

#### Inherited from


`[Collection#reduceRight()](../collection/index#reduceRight())`



#### [every()](index#every())




True if `predicate` returns true for all entries in the Collection.

 

```
every(predicate: (value: T, key: number, iter: this) => boolean,context?: unknown): boolean

```

#### Inherited from


`[Collection#every()](../collection/index#every())`



#### [some()](index#some())




True if `predicate` returns true for any entry in the Collection.

 

```
some(predicate: (value: T, key: number, iter: this) => boolean,context?: unknown): boolean

```

#### Inherited from


`[Collection#some()](../collection/index#some())`



#### [join()](index#join())




Joins values together as a string, inserting a separator between each. The default separator is `","`.

 

```
join(separator?: string): string

```

#### Inherited from


`[Collection#join()](../collection/index#join())`



#### [isEmpty()](index#isEmpty())




Returns true if this Collection includes no values.

 

```
isEmpty(): boolean

```

#### Inherited from


`[Collection#isEmpty()](../collection/index#isEmpty())`#### Discussion



For some lazy `[Seq](../seq/index)`, `[isEmpty](index#isEmpty())` might need to iterate to determine emptiness. At most one iteration will occur.

 



#### [count()](index#count())




```
count(): number
count(predicate: (value: T, key: number, iter: this) => boolean,context?: unknown): number

```

#### Inherited from


`[Collection#count()](../collection/index#count())`



#### [countBy()](index#countBy())




Returns a `[Seq.Keyed](../seq.keyed/index)` of counts, grouped by the return value of the `grouper` function.

 

```
countBy<G>(grouper: (value: T, key: number, iter: this) => G,context?: unknown): Map<G, number>

```

#### Inherited from


`[Collection#countBy()](../collection/index#countBy())`#### Discussion



Note: This is not a lazy operation.

 


### Comparison



#### [isSubset()](index#isSubset())




True if `iter` includes every value in this Collection.

 

```
isSubset(iter: Iterable<T>): boolean

```

#### Inherited from


`[Collection#isSubset()](../collection/index#isSubset())`



#### [isSuperset()](index#isSuperset())




True if this Collection includes every value in `iter`.

 

```
isSuperset(iter: Iterable<T>): boolean

```

#### Inherited from


`[Collection#isSuperset()](../collection/index#isSuperset())`

This documentation is generated from [immutable.d.ts](https://github.com/immutable-js/immutable-js/blob/main/type-definitions/immutable.d.ts). Pull requests and [Issues](https://github.com/immutable-js/immutable-js/issues) welcome.

 © 2014–present, Lee Byron and other contributors  
Licensed under the 3-clause BSD License.  

<https://immutable-js.com/docs/v4.2.1/List/>

Map
===



Immutable Map is an unordered Collection.Keyed of (key, value) pairs with `O(log32 N)` gets and `O(log32 N)` persistent sets.

 

```
type Map<K, V> extends Collection.Keyed<K, V>
```

#### Discussion



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](../is()/index)` to determine key equality. This allows the use of any value (including NaN) as a key.

 Because `[Immutable.is](../is()/index)` returns equality based on value semantics, and Immutable collections are treated as values, any Immutable collection may be used as a key.

 
```
const { Map, List } = require('immutable');
Map().set(List([ 1 ]), 'listofone').get(List([ 1 ]));
// 'listofone'run it
```

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.

 
### Construction



#### [Map()](index#Map())



```
Map<K, V>(collection?: Iterable<[K, V]>): Map<K, V>
Map<V>(obj: {[key: string]: V}): Map<string, V>
Map<K, V>(obj: {[key: string]: V}): Map<K, V>

```


### Static methods



#### [Map.isMap()](index#isMap())



```
Map.isMap(maybeMap: unknown): boolean

```


### Members



#### [size](index#size)




The number of entries in this Map.

 

```
size: number
```



### Persistent changes



#### [set()](index#set())




Returns a new Map also containing the new key, value pair. If an equivalent key already exists in this Map, it will be replaced.

 

```
set(key: K, value: V): this

```

#### Discussion


 
```
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" }run it
```

Note: `[set](index#set())` can be used in `[withMutations](index#withMutations())`.

 



#### [delete()](index#delete())




Returns a new Map which excludes this `key`.

 

```
delete(key: K): this

```

#### alias


`remove()`#### Discussion



Note: `[delete](index#delete())` cannot be safely used in IE8, but is provided to mirror the ES6 collection API.

 
```
const { Map } = require('immutable')
const originalMap = Map({
  key: 'value',
  otherKey: 'other value'
})
// Map { "key": "value", "otherKey": "other value" }
originalMap.delete('otherKey')
// Map { "key": "value" }run it
```

Note: `[delete](index#delete())` can be used in `[withMutations](index#withMutations())`.

 



#### [deleteAll()](index#deleteAll())




Returns a new Map which excludes the provided `keys`.

 

```
deleteAll(keys: Iterable<K>): this

```

#### alias


`removeAll()`#### Discussion


 
```
const { Map } = require('immutable')
const names = Map({ a: "Aaron", b: "Barry", c: "Connor" })
names.deleteAll([ 'a', 'c' ])
// Map { "b": "Barry" }run it
```



Note: `[deleteAll](index#deleteAll())` can be used in `[withMutations](index#withMutations())`.

 



#### [clear()](index#clear())




Returns a new Map containing no keys or values.

 

```
clear(): this

```

#### Discussion


 
```
const { Map } = require('immutable')
Map({ key: 'value' }).clear()
// Map {}run it
```



Note: `[clear](index#clear())` can be used in `[withMutations](index#withMutations())`.

 



#### [update()](index#update())




```
update(key: K, notSetValue: V, updater: (value: V) => V): this
update(key: K, updater: (value: V | undefined) => V): this
update<R>(updater: (value: this) => R): R

```

#### Overrides


`[Collection#update()](../collection/index#update())`



#### [merge()](index#merge())



```
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>

```



#### [mergeWith()](index#mergeWith())




Like `[merge()](index#merge())`, `[mergeWith()](index#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.

 

```
mergeWith(merger: (oldVal: V, newVal: V, key: K) => V,...collections: Array<Iterable<[K, V]> | {[key: string]: V}>): this

```

#### Discussion


 
```
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 }run it
```



Note: `[mergeWith](index#mergeWith())` can be used in `[withMutations](index#withMutations())`.

 



#### [mergeDeep()](index#mergeDeep())




Like `[merge()](index#merge())`, but when two compatible collections are encountered with the same key, it merges them as well, recursing deeply through the nested data. Two collections are considered to be compatible (and thus will be merged together) if they both fall into one of three categories: keyed (e.g., `[Map](index)`s, `[Record](../record/index)`s, and objects), indexed (e.g., `[List](../list/index)`s and arrays), or set-like (e.g., `[Set](../set/index)`s). If they fall into separate categories, `[mergeDeep](index#mergeDeep())` will replace the existing collection with the collection being merged in. This behavior can be customized by using `[mergeDeepWith()](index#mergeDeepWith())`.

 

```
mergeDeep(...collections: Array<Iterable<[K, V]> | {[key: string]: V}>): this

```

#### Discussion



Note: Indexed and set-like collections are merged using `[concat()](index#concat())`/`union()` and therefore do not recurse.

 
```
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 }
// }run it
```

Note: `[mergeDeep](index#mergeDeep())` can be used in `[withMutations](index#withMutations())`.

 



#### [mergeDeepWith()](index#mergeDeepWith())




Like `[mergeDeep()](index#mergeDeep())`, but when two non-collections or incompatible collections are encountered at the same key, it uses the `merger` function to determine the resulting value. Collections are considered incompatible if they fall into separate categories between keyed, indexed, and set-like.

 

```
mergeDeepWith(merger: (oldVal: unknown, newVal: unknown, key: unknown) => unknown,...collections: Array<Iterable<[K, V]> | {[key: string]: V}>): this

```

#### Discussion


 
```
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 }
// }run it
```



Note: `[mergeDeepWith](index#mergeDeepWith())` can be used in `[withMutations](index#withMutations())`.

 


### Deep persistent changes



#### [setIn()](index#setIn())




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.

 

```
setIn(keyPath: Iterable<unknown>, value: unknown): this

```

#### Discussion


 
```
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!" } // } // }run it


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.

 
```
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" } // } // }run it


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](index#setIn())` can be used in `[withMutations](index#withMutations())`.

 



#### [deleteIn()](index#deleteIn())




Returns a new Map having removed the value at this `keyPath`. If any keys in `keyPath` do not exist, no change will occur.

 

```
deleteIn(keyPath: Iterable<unknown>): this

```

#### alias


`removeIn()`#### Discussion



Note: `[deleteIn](index#deleteIn())` can be used in `[withMutations](index#withMutations())`.

 



#### [updateIn()](index#updateIn())



```
updateIn(keyPath: Iterable<unknown>,notSetValue: unknown,updater: (value: unknown) => unknown): this
updateIn(keyPath: Iterable<unknown>, updater: (value: unknown) => unknown): this

```



#### [mergeIn()](index#mergeIn())




A combination of `[updateIn](index#updateIn())` and `[merge](index#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:

 

```
mergeIn(keyPath: Iterable<unknown>, ...collections: Array<unknown>): this

```

#### Discussion




```
map.updateIn(['a', 'b', 'c'], abc => abc.merge(y))
map.mergeIn(['a', 'b', 'c'], y)
```



Note: `[mergeIn](index#mergeIn())` can be used in `[withMutations](index#withMutations())`.

 



#### [mergeDeepIn()](index#mergeDeepIn())




A combination of `[updateIn](index#updateIn())` and `[mergeDeep](index#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:

 

```
mergeDeepIn(keyPath: Iterable<unknown>, ...collections: Array<unknown>): this

```

#### Discussion




```
map.updateIn(['a', 'b', 'c'], abc => abc.mergeDeep(y))
map.mergeDeepIn(['a', 'b', 'c'], y)
```



Note: `[mergeDeepIn](index#mergeDeepIn())` can be used in `[withMutations](index#withMutations())`.

 


### Transient changes



#### [withMutations()](index#withMutations())




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.

 

```
withMutations(mutator: (mutable: this) => unknown): this

```

#### Discussion



If you need to apply a series of mutations to produce a new immutable Map, `[withMutations()](index#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](index#merge())` are done.

 As an example, this results in the creation of 2, not 4, new Maps:

 
```
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)run it
```

Note: Not all methods can be used on a mutable collection or within `[withMutations](index#withMutations())`! Read the documentation for each method to see if it is safe to use in `[withMutations](index#withMutations())`.

 



#### [asMutable()](index#asMutable())




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.

 

```
asMutable(): this

```

#### see



`[Map#asImmutable](index#asImmutable())`

 
#### Discussion



If possible, use `[withMutations](index#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](index#asMutable())` returns itself.

 Note: Not all methods can be used on a mutable collection or within `[withMutations](index#withMutations())`! Read the documentation for each method to see if it is safe to use in `[withMutations](index#withMutations())`.

 



#### [wasAltered()](index#wasAltered())




Returns true if this is a mutable copy (see `[asMutable()](index#asMutable())`) and mutative alterations have been applied.

 

```
wasAltered(): boolean

```

#### see



`[Map#asMutable](index#asMutable())`

 



#### [asImmutable()](index#asImmutable())




The yin to `[asMutable](index#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.

 

```
asImmutable(): this

```

#### see



`[Map#asMutable](index#asMutable())`

 
#### Discussion



If possible, use `[withMutations](index#withMutations())` to work with temporary mutable copies as it provides an easier to use API and considers many common optimizations.

 


### Sequence algorithms



#### [map()](index#map())




Returns a new Map with values passed through a `mapper` function.

 

```
map<M>(mapper: (value: V, key: K, iter: this) => M,context?: unknown): Map<K, M>

```

#### Overrides


`[Collection.Keyed#map()](../collection.keyed/index#map())`#### Example



```
Map({ a: 1, b: 2 }).map(x => 10 * x)
// Map { a: 10, b: 20 }
```




#### [mapKeys()](index#mapKeys())




```
mapKeys<M>(mapper: (key: K, value: V, iter: this) => M,context?: unknown): Map<M, V>

```

#### Overrides


`[Collection.Keyed#mapKeys()](../collection.keyed/index#mapKeys())`#### see



Collection.Keyed.mapKeys

 



#### [mapEntries()](index#mapEntries())




```
mapEntries<KM, VM>(mapper: (entry: [K, V], index: number, iter: this) => [KM, VM] | undefined,context?: unknown): Map<KM, VM>

```

#### Overrides


`[Collection.Keyed#mapEntries()](../collection.keyed/index#mapEntries())`#### see



Collection.Keyed.mapEntries

 



#### [flatMap()](index#flatMap())




Flat-maps the Map, returning a new Map.

 

```
flatMap<KM, VM>(mapper: (value: V, key: K, iter: this) => Iterable<[KM, VM]>,context?: unknown): Map<KM, VM>

```

#### Overrides


`[Collection.Keyed#flatMap()](../collection.keyed/index#flatMap())`#### Discussion



Similar to `data.map(...).flatten(true)`.

 



#### [filter()](index#filter())




```
filter<F>(predicate: (value: V, key: K, iter: this) => boolean,context?: unknown): Map<K, F>
filter(predicate: (value: V, key: K, iter: this) => unknown,context?: unknown): this

```

#### Overrides


`[Collection.Keyed#filter()](../collection.keyed/index#filter())`



#### [partition()](index#partition())




```
partition<F, C>(predicate: (this: C, value: V, key: K, iter: this) => boolean,context?: C): [Map<K, V>, Map<K, F>]
partition<C>(predicate: (this: C, value: V, key: K, iter: this) => unknown,context?: C): [this, this]

```

#### Overrides


`[Collection.Keyed#partition()](../collection.keyed/index#partition())`



#### [flip()](index#flip())




```
flip(): Map<V, K>

```

#### Overrides


`[Collection.Keyed#flip()](../collection.keyed/index#flip())`#### see



Collection.Keyed.flip

 



#### [filterNot()](index#filterNot())




Returns a new Collection of the same type with only the entries for which the `predicate` function returns false.

 

```
filterNot(predicate: (value: V, key: K, iter: this) => boolean,context?: unknown): this

```

#### Inherited from


`[Collection#filterNot()](../collection/index#filterNot())`#### Discussion


 
```
const { Map } = require('immutable')
Map({ a: 1, b: 2, c: 3, d: 4}).filterNot(x => x % 2 === 0)
// Map { "a": 1, "c": 3 }run it
```



Note: `[filterNot()](../list/index#filterNot())` always returns a new instance, even if it results in not filtering out any values.

 



#### [reverse()](index#reverse())




Returns a new Collection of the same type in reverse order.

 

```
reverse(): this

```

#### Inherited from


`[Collection#reverse()](../collection/index#reverse())`



#### [sort()](index#sort())




Returns a new Collection of the same type which includes the same entries, stably sorted by using a `comparator`.

 

```
sort(comparator?: (valueA: V, valueB: V) => number): this

```

#### Inherited from


`[Collection#sort()](../collection/index#sort())`#### Discussion



If a `comparator` is not provided, a default comparator uses `<` and `>`.

 `comparator(valueA, valueB)`:

 * Returns `0` if the elements should not be swapped.
* Returns `-1` (or any negative number) if `valueA` comes before `valueB`
* Returns `1` (or any positive number) if `valueA` comes after `valueB`
* Is pure, i.e. it must always return the same value for the same pair of values.

 When sorting collections which have no defined order, their ordered equivalents will be returned. e.g. `map.sort()` returns OrderedMap.

 
```
const { Map } = require('immutable')
Map({ "c": 3, "a": 1, "b": 2 }).sort((a, b) => {
  if (a < b) { return -1; }
  if (a > b) { return 1; }
  if (a === b) { return 0; }
});
// OrderedMap { "a": 1, "b": 2, "c": 3 }run it
```

Note: `[sort()](../list/index#sort())` Always returns a new instance, even if the original was already sorted.

 Note: This is always an eager operation.

 



#### [sortBy()](index#sortBy())




Like `[sort](../list/index#sort())`, but also accepts a `comparatorValueMapper` which allows for sorting by more sophisticated means:

 

```
sortBy<C>(comparatorValueMapper: (value: V, key: K, iter: this) => C,comparator?: (valueA: C, valueB: C) => number): this

```

#### Inherited from


`[Collection#sortBy()](../collection/index#sortBy())`#### Discussion


 
```
const { Map } = require('immutable')
const beattles = Map({
  John: { name: "Lennon" },
  Paul: { name: "McCartney" },
  George: { name: "Harrison" },
  Ringo: { name: "Starr" },
});
beattles.sortBy(member => member.name);run it
```



Note: `[sortBy()](../list/index#sortBy())` Always returns a new instance, even if the original was already sorted.

 Note: This is always an eager operation.

 



#### [groupBy()](index#groupBy())




Returns a `[Collection.Keyed](../collection.keyed/index)` of `Collection.Keyeds`, grouped by the return value of the `grouper` function.

 

```
groupBy<G>(grouper: (value: V, key: K, iter: this) => G,context?: unknown): Seq.Keyed<G, Collection<K, V>>

```

#### Inherited from


`[Collection#groupBy()](../collection/index#groupBy())`#### Discussion



Note: This is always an eager operation.

 
```
const { List, Map } = require('immutable')
const listOfMaps = List([
  Map({ v: 0 }),
  Map({ v: 1 }),
  Map({ v: 1 }),
  Map({ v: 0 }),
  Map({ v: 2 })
])
const groupsOfMaps = listOfMaps.groupBy(x => x.get('v'))
// Map {
//   0: List [ Map{ "v": 0 }, Map { "v": 0 } ],
//   1: List [ Map{ "v": 1 }, Map { "v": 1 } ],
//   2: List [ Map{ "v": 2 } ],
// }run it
```




### Conversion to JavaScript types



#### [toJS()](index#toJS())




Deeply converts this Keyed collection to equivalent native JavaScript Object.

 

```
toJS(): {[key: string]: DeepCopy<V>}

```

#### Inherited from


`[Collection.Keyed#toJS()](../collection.keyed/index#toJS())`#### Discussion



Converts keys to Strings.

 



#### [toJSON()](index#toJSON())




Shallowly converts this Keyed collection to equivalent native JavaScript Object.

 

```
toJSON(): {[key: string]: V}

```

#### Inherited from


`[Collection.Keyed#toJSON()](../collection.keyed/index#toJSON())`#### Discussion



Converts keys to Strings.

 



#### [toArray()](index#toArray())




Shallowly converts this collection to an Array.

 

```
toArray(): Array<[K, V]>

```

#### Inherited from


`[Collection.Keyed#toArray()](../collection.keyed/index#toArray())`



#### [toObject()](index#toObject())




Shallowly converts this Collection to an Object.

 

```
toObject(): {[key: string]: V}

```

#### Inherited from


`[Collection#toObject()](../collection/index#toObject())`#### Discussion



Converts keys to Strings.

 


### Conversion to Seq



#### [toSeq()](index#toSeq())




Returns Seq.Keyed.

 

```
toSeq(): Seq.Keyed<K, V>

```

#### Inherited from


`[Collection.Keyed#toSeq()](../collection.keyed/index#toSeq())`



#### [toKeyedSeq()](index#toKeyedSeq())




Returns a Seq.Keyed from this Collection where indices are treated as keys.

 

```
toKeyedSeq(): Seq.Keyed<K, V>

```

#### Inherited from


`[Collection#toKeyedSeq()](../collection/index#toKeyedSeq())`#### Discussion



This is useful if you want to operate on an Collection.Indexed and preserve the [index, value] pairs.

 The returned Seq will have identical iteration order as this Collection.

 
```
const { Seq } = require('immutable')
const indexedSeq = Seq([ 'A', 'B', 'C' ])
// Seq [ "A", "B", "C" ]
indexedSeq.filter(v => v === 'B')
// Seq [ "B" ]
const keyedSeq = indexedSeq.toKeyedSeq()
// Seq { 0: "A", 1: "B", 2: "C" }
keyedSeq.filter(v => v === 'B')
// Seq { 1: "B" }run it
```





#### [toIndexedSeq()](index#toIndexedSeq())




Returns an Seq.Indexed of the values of this Collection, discarding keys.

 

```
toIndexedSeq(): Seq.Indexed<V>

```

#### Inherited from


`[Collection#toIndexedSeq()](../collection/index#toIndexedSeq())`



#### [toSetSeq()](index#toSetSeq())




Returns a Seq.Set of the values of this Collection, discarding keys.

 

```
toSetSeq(): Seq.Set<V>

```

#### Inherited from


`[Collection#toSetSeq()](../collection/index#toSetSeq())`


### Sequence functions



#### [concat()](index#concat())




```
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>

```

#### Inherited from


`[Collection.Keyed#concat()](../collection.keyed/index#concat())`



#### [[Symbol.iterator]()](index#%5BSymbol.iterator%5D())




```
[Symbol.iterator](): IterableIterator<[K, V]>

```

#### Inherited from


`[Collection.Keyed#[Symbol.iterator]()](../collection.keyed/index#%5BSymbol.iterator%5D())`


### Value equality



#### [equals()](index#equals())




True if this and the other Collection have value equality, as defined by `[Immutable.is()](../is()/index)`.

 

```
equals(other: unknown): boolean

```

#### Inherited from


`[Collection#equals()](../collection/index#equals())`#### Discussion



Note: This is equivalent to `Immutable.is(this, other)`, but provided to allow for chained expressions.

 



#### [hashCode()](index#hashCode())




Computes and returns the hashed identity for this Collection.

 

```
hashCode(): number

```

#### Inherited from


`[Collection#hashCode()](../collection/index#hashCode())`#### Discussion



The `[hashCode](../list/index#hashCode())` of a Collection is used to determine potential equality, and is used when adding this to a `[Set](../set/index)` or as a key in a `[Map](index)`, enabling lookup via a different instance.

 
```
const a = List([ 1, 2, 3 ]);
const b = List([ 1, 2, 3 ]);
assert.notStrictEqual(a, b); // different instances
const set = Set([ a ]);
assert.equal(set.has(b), true);run it
```

If two values have the same `[hashCode](../list/index#hashCode())`, they are [not guaranteed to be equal](https://en.wikipedia.org/wiki/Collision_(computer_science)). If two values have different `[hashCode](../list/index#hashCode())`s, they must not be equal.

 


### Reading values



#### [get()](index#get())




```
get<NSV>(key: K, notSetValue: NSV): V | NSV
get(key: K): V | undefined

```

#### Inherited from


`[Collection#get()](../collection/index#get())`



#### [has()](index#has())




True if a key exists within this `[Collection](../collection/index)`, using `[Immutable.is](../is()/index)` to determine equality

 

```
has(key: K): boolean

```

#### Inherited from


`[Collection#has()](../collection/index#has())`



#### [includes()](index#includes())




True if a value exists within this `[Collection](../collection/index)`, using `[Immutable.is](../is()/index)` to determine equality

 

```
includes(value: V): boolean

```

#### Inherited from


`[Collection#includes()](../collection/index#includes())`#### alias


`contains()`



#### [first()](index#first())




In case the `[Collection](../collection/index)` is not empty returns the first element of the `[Collection](../collection/index)`. In case the `[Collection](../collection/index)` is empty returns the optional default value if provided, if no default value is provided returns undefined.

 

```
first<NSV>(notSetValue?: NSV): V | NSV

```

#### Inherited from


`[Collection#first()](../collection/index#first())`



#### [last()](index#last())




In case the `[Collection](../collection/index)` is not empty returns the last element of the `[Collection](../collection/index)`. In case the `[Collection](../collection/index)` is empty returns the optional default value if provided, if no default value is provided returns undefined.

 

```
last<NSV>(notSetValue?: NSV): V | NSV

```

#### Inherited from


`[Collection#last()](../collection/index#last())`


### Reading deep values



#### [getIn()](index#getIn())




Returns the value found by following a path of keys or indices through nested Collections.

 

```
getIn(searchKeyPath: Iterable<unknown>, notSetValue?: unknown): unknown

```

#### Inherited from


`[Collection#getIn()](../collection/index#getIn())`#### Discussion


 
```
const { Map, List } = require('immutable')
const deepData = Map({ x: List([ Map({ y: 123 }) ]) });
deepData.getIn(['x', 0, 'y']) // 123run it
```



Plain JavaScript Object or Arrays may be nested within an Immutable.js Collection, and getIn() can access those values as well:

 
```
const { Map, List } = require('immutable')
const deepData = Map({ x: [ { y: 123 } ] });
deepData.getIn(['x', 0, 'y']) // 123run it
```


 



#### [hasIn()](index#hasIn())




True if the result of following a path of keys or indices through nested Collections results in a set value.

 

```
hasIn(searchKeyPath: Iterable<unknown>): boolean

```

#### Inherited from


`[Collection#hasIn()](../collection/index#hasIn())`


### Conversion to Collections



#### [toMap()](index#toMap())




Converts this Collection to a Map, Throws if keys are not hashable.

 

```
toMap(): Map<K, V>

```

#### Inherited from


`[Collection#toMap()](../collection/index#toMap())`#### Discussion



Note: This is equivalent to `Map(this.toKeyedSeq())`, but provided for convenience and to allow for chained expressions.

 



#### [toOrderedMap()](index#toOrderedMap())




Converts this Collection to a Map, maintaining the order of iteration.

 

```
toOrderedMap(): OrderedMap<K, V>

```

#### Inherited from


`[Collection#toOrderedMap()](../collection/index#toOrderedMap())`#### Discussion



Note: This is equivalent to `OrderedMap(this.toKeyedSeq())`, but provided for convenience and to allow for chained expressions.

 



#### [toSet()](index#toSet())




Converts this Collection to a Set, discarding keys. Throws if values are not hashable.

 

```
toSet(): Set<V>

```

#### Inherited from


`[Collection#toSet()](../collection/index#toSet())`#### Discussion



Note: This is equivalent to `[Set(this)](../set/index)`, but provided to allow for chained expressions.

 



#### [toOrderedSet()](index#toOrderedSet())




Converts this Collection to a Set, maintaining the order of iteration and discarding keys.

 

```
toOrderedSet(): OrderedSet<V>

```

#### Inherited from


`[Collection#toOrderedSet()](../collection/index#toOrderedSet())`#### Discussion



Note: This is equivalent to `OrderedSet(this.valueSeq())`, but provided for convenience and to allow for chained expressions.

 



#### [toList()](index#toList())




Converts this Collection to a List, discarding keys.

 

```
toList(): List<V>

```

#### Inherited from


`[Collection#toList()](../collection/index#toList())`#### Discussion



This is similar to `[List(collection)](../list/index)`, but provided to allow for chained expressions. However, when called on `[Map](index)` or other keyed collections, `collection.toList()` discards the keys and creates a list of only the values, whereas `[List(collection)](../list/index)` creates a list of entry tuples.

 
```
const { Map, List } = require('immutable')
var myMap = Map({ a: 'Apple', b: 'Banana' })
List(myMap) // List [ [ "a", "Apple" ], [ "b", "Banana" ] ]
myMap.toList() // List [ "Apple", "Banana" ]run it
```





#### [toStack()](index#toStack())




Converts this Collection to a Stack, discarding keys. Throws if values are not hashable.

 

```
toStack(): Stack<V>

```

#### Inherited from


`[Collection#toStack()](../collection/index#toStack())`#### Discussion



Note: This is equivalent to `[Stack(this)](../stack/index)`, but provided to allow for chained expressions.

 


### Iterators



#### [keys()](index#keys())




An iterator of this `[Collection](../collection/index)`'s keys.

 

```
keys(): IterableIterator<K>

```

#### Inherited from


`[Collection#keys()](../collection/index#keys())`#### Discussion



Note: this will return an ES6 iterator which does not support Immutable.js sequence algorithms. Use `[keySeq](../list/index#keySeq())` instead, if this is what you want.

 



#### [values()](index#values())




An iterator of this `[Collection](../collection/index)`'s values.

 

```
values(): IterableIterator<V>

```

#### Inherited from


`[Collection#values()](../collection/index#values())`#### Discussion



Note: this will return an ES6 iterator which does not support Immutable.js sequence algorithms. Use `[valueSeq](../list/index#valueSeq())` instead, if this is what you want.

 



#### [entries()](index#entries())




An iterator of this `[Collection](../collection/index)`'s entries as `[ key, value ]` tuples.

 

```
entries(): IterableIterator<[K, V]>

```

#### Inherited from


`[Collection#entries()](../collection/index#entries())`#### Discussion



Note: this will return an ES6 iterator which does not support Immutable.js sequence algorithms. Use `[entrySeq](../list/index#entrySeq())` instead, if this is what you want.

 


### Collections (Seq)



#### [keySeq()](index#keySeq())




Returns a new Seq.Indexed of the keys of this Collection, discarding values.

 

```
keySeq(): Seq.Indexed<K>

```

#### Inherited from


`[Collection#keySeq()](../collection/index#keySeq())`



#### [valueSeq()](index#valueSeq())




Returns an Seq.Indexed of the values of this Collection, discarding keys.

 

```
valueSeq(): Seq.Indexed<V>

```

#### Inherited from


`[Collection#valueSeq()](../collection/index#valueSeq())`



#### [entrySeq()](index#entrySeq())




Returns a new Seq.Indexed of [key, value] tuples.

 

```
entrySeq(): Seq.Indexed<[K, V]>

```

#### Inherited from


`[Collection#entrySeq()](../collection/index#entrySeq())`


### Side effects



#### [forEach()](index#forEach())




The `sideEffect` is executed for every entry in the Collection.

 

```
forEach(sideEffect: (value: V, key: K, iter: this) => unknown,context?: unknown): number

```

#### Inherited from


`[Collection#forEach()](../collection/index#forEach())`#### Discussion



Unlike `[Array#forEach](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/forEach)`, if any call of `sideEffect` returns `false`, the iteration will stop. Returns the number of entries iterated (including the last iteration which returned false).

 


### Creating subsets



#### [slice()](index#slice())




Returns a new Collection of the same type representing a portion of this Collection from start up to but not including end.

 

```
slice(begin?: number, end?: number): this

```

#### Inherited from


`[Collection#slice()](../collection/index#slice())`#### Discussion



If begin is negative, it is offset from the end of the Collection. e.g. `slice(-2)` returns a Collection of the last two entries. If it is not provided the new Collection will begin at the beginning of this Collection.

 If end is negative, it is offset from the end of the Collection. e.g. `slice(0, -1)` returns a Collection of everything but the last entry. If it is not provided, the new Collection will continue through the end of this Collection.

 If the requested slice is equivalent to the current Collection, then it will return itself.

 



#### [rest()](index#rest())




Returns a new Collection of the same type containing all entries except the first.

 

```
rest(): this

```

#### Inherited from


`[Collection#rest()](../collection/index#rest())`



#### [butLast()](index#butLast())




Returns a new Collection of the same type containing all entries except the last.

 

```
butLast(): this

```

#### Inherited from


`[Collection#butLast()](../collection/index#butLast())`



#### [skip()](index#skip())




Returns a new Collection of the same type which excludes the first `amount` entries from this Collection.

 

```
skip(amount: number): this

```

#### Inherited from


`[Collection#skip()](../collection/index#skip())`



#### [skipLast()](index#skipLast())




Returns a new Collection of the same type which excludes the last `amount` entries from this Collection.

 

```
skipLast(amount: number): this

```

#### Inherited from


`[Collection#skipLast()](../collection/index#skipLast())`



#### [skipWhile()](index#skipWhile())




Returns a new Collection of the same type which includes entries starting from when `predicate` first returns false.

 

```
skipWhile(predicate: (value: V, key: K, iter: this) => boolean,context?: unknown): this

```

#### Inherited from


`[Collection#skipWhile()](../collection/index#skipWhile())`#### Discussion


 
```
const { List } = require('immutable')
List([ 'dog', 'frog', 'cat', 'hat', 'god' ])
  .skipWhile(x => x.match(/g/))
// List [ "cat", "hat", "god" ]run it
```


 



#### [skipUntil()](index#skipUntil())




Returns a new Collection of the same type which includes entries starting from when `predicate` first returns true.

 

```
skipUntil(predicate: (value: V, key: K, iter: this) => boolean,context?: unknown): this

```

#### Inherited from


`[Collection#skipUntil()](../collection/index#skipUntil())`#### Discussion


 
```
const { List } = require('immutable')
List([ 'dog', 'frog', 'cat', 'hat', 'god' ])
  .skipUntil(x => x.match(/hat/))
// List [ "hat", "god" ]run it
```


 



#### [take()](index#take())




Returns a new Collection of the same type which includes the first `amount` entries from this Collection.

 

```
take(amount: number): this

```

#### Inherited from


`[Collection#take()](../collection/index#take())`



#### [takeLast()](index#takeLast())




Returns a new Collection of the same type which includes the last `amount` entries from this Collection.

 

```
takeLast(amount: number): this

```

#### Inherited from


`[Collection#takeLast()](../collection/index#takeLast())`



#### [takeWhile()](index#takeWhile())




Returns a new Collection of the same type which includes entries from this Collection as long as the `predicate` returns true.

 

```
takeWhile(predicate: (value: V, key: K, iter: this) => boolean,context?: unknown): this

```

#### Inherited from


`[Collection#takeWhile()](../collection/index#takeWhile())`#### Discussion


 
```
const { List } = require('immutable')
List([ 'dog', 'frog', 'cat', 'hat', 'god' ])
  .takeWhile(x => x.match(/o/))
// List [ "dog", "frog" ]run it
```


 



#### [takeUntil()](index#takeUntil())




Returns a new Collection of the same type which includes entries from this Collection as long as the `predicate` returns false.

 

```
takeUntil(predicate: (value: V, key: K, iter: this) => boolean,context?: unknown): this

```

#### Inherited from


`[Collection#takeUntil()](../collection/index#takeUntil())`#### Discussion


 
```
const { List } = require('immutable')
List([ 'dog', 'frog', 'cat', 'hat', 'god' ])
  .takeUntil(x => x.match(/at/))
// List [ "dog", "frog" ]run it
```


 


### Combination



#### [flatten()](index#flatten())




```
flatten(depth?: number): Collection<unknown, unknown>
flatten(shallow?: boolean): Collection<unknown, unknown>

```

#### Inherited from


`[Collection#flatten()](../collection/index#flatten())`


### Reducing a value



#### [reduce()](index#reduce())




```
reduce<R>(reducer: (reduction: R, value: V, key: K, iter: this) => R,initialReduction: R,context?: unknown): R
reduce<R>(reducer: (reduction: V | R, value: V, key: K, iter: this) => R): R

```

#### Inherited from


`[Collection#reduce()](../collection/index#reduce())`



#### [reduceRight()](index#reduceRight())




```
reduceRight<R>(reducer: (reduction: R, value: V, key: K, iter: this) => R,initialReduction: R,context?: unknown): R
reduceRight<R>(reducer: (reduction: V | R, value: V, key: K, iter: this) => R): R

```

#### Inherited from


`[Collection#reduceRight()](../collection/index#reduceRight())`



#### [every()](index#every())




True if `predicate` returns true for all entries in the Collection.

 

```
every(predicate: (value: V, key: K, iter: this) => boolean,context?: unknown): boolean

```

#### Inherited from


`[Collection#every()](../collection/index#every())`



#### [some()](index#some())




True if `predicate` returns true for any entry in the Collection.

 

```
some(predicate: (value: V, key: K, iter: this) => boolean,context?: unknown): boolean

```

#### Inherited from


`[Collection#some()](../collection/index#some())`



#### [join()](index#join())




Joins values together as a string, inserting a separator between each. The default separator is `","`.

 

```
join(separator?: string): string

```

#### Inherited from


`[Collection#join()](../collection/index#join())`



#### [isEmpty()](index#isEmpty())




Returns true if this Collection includes no values.

 

```
isEmpty(): boolean

```

#### Inherited from


`[Collection#isEmpty()](../collection/index#isEmpty())`#### Discussion



For some lazy `[Seq](../seq/index)`, `[isEmpty](../list/index#isEmpty())` might need to iterate to determine emptiness. At most one iteration will occur.

 



#### [count()](index#count())




```
count(): number
count(predicate: (value: V, key: K, iter: this) => boolean,context?: unknown): number

```

#### Inherited from


`[Collection#count()](../collection/index#count())`



#### [countBy()](index#countBy())




Returns a `[Seq.Keyed](../seq.keyed/index)` of counts, grouped by the return value of the `grouper` function.

 

```
countBy<G>(grouper: (value: V, key: K, iter: this) => G,context?: unknown): Map<G, number>

```

#### Inherited from


`[Collection#countBy()](../collection/index#countBy())`#### Discussion



Note: This is not a lazy operation.

 


### Search for value



#### [find()](index#find())




Returns the first value for which the `predicate` returns true.

 

```
find(predicate: (value: V, key: K, iter: this) => boolean,context?: unknown,notSetValue?: V): V | undefined

```

#### Inherited from


`[Collection#find()](../collection/index#find())`



#### [findLast()](index#findLast())




Returns the last value for which the `predicate` returns true.

 

```
findLast(predicate: (value: V, key: K, iter: this) => boolean,context?: unknown,notSetValue?: V): V | undefined

```

#### Inherited from


`[Collection#findLast()](../collection/index#findLast())`#### Discussion



Note: `predicate` will be called for each entry in reverse.

 



#### [findEntry()](index#findEntry())




Returns the first [key, value] entry for which the `predicate` returns true.

 

```
findEntry(predicate: (value: V, key: K, iter: this) => boolean,context?: unknown,notSetValue?: V): [K, V] | undefined

```

#### Inherited from


`[Collection#findEntry()](../collection/index#findEntry())`



#### [findLastEntry()](index#findLastEntry())




Returns the last [key, value] entry for which the `predicate` returns true.

 

```
findLastEntry(predicate: (value: V, key: K, iter: this) => boolean,context?: unknown,notSetValue?: V): [K, V] | undefined

```

#### Inherited from


`[Collection#findLastEntry()](../collection/index#findLastEntry())`#### Discussion



Note: `predicate` will be called for each entry in reverse.

 



#### [findKey()](index#findKey())




Returns the key for which the `predicate` returns true.

 

```
findKey(predicate: (value: V, key: K, iter: this) => boolean,context?: unknown): K | undefined

```

#### Inherited from


`[Collection#findKey()](../collection/index#findKey())`



#### [findLastKey()](index#findLastKey())




Returns the last key for which the `predicate` returns true.

 

```
findLastKey(predicate: (value: V, key: K, iter: this) => boolean,context?: unknown): K | undefined

```

#### Inherited from


`[Collection#findLastKey()](../collection/index#findLastKey())`#### Discussion



Note: `predicate` will be called for each entry in reverse.

 



#### [keyOf()](index#keyOf())




Returns the key associated with the search value, or undefined.

 

```
keyOf(searchValue: V): K | undefined

```

#### Inherited from


`[Collection#keyOf()](../collection/index#keyOf())`



#### [lastKeyOf()](index#lastKeyOf())




Returns the last key associated with the search value, or undefined.

 

```
lastKeyOf(searchValue: V): K | undefined

```

#### Inherited from


`[Collection#lastKeyOf()](../collection/index#lastKeyOf())`



#### [max()](index#max())




Returns the maximum value in this collection. If any values are comparatively equivalent, the first one found will be returned.

 

```
max(comparator?: (valueA: V, valueB: V) => number): V | undefined

```

#### Inherited from


`[Collection#max()](../collection/index#max())`#### Discussion



The `comparator` is used in the same way as `[Collection#sort](../collection/index#sort())`. If it is not provided, the default comparator is `>`.

 When two values are considered equivalent, the first encountered will be returned. Otherwise, `[max](../list/index#max())` will operate independent of the order of input as long as the comparator is commutative. The default comparator `>` is commutative *only* when types do not differ.

 If `comparator` returns 0 and either value is NaN, undefined, or null, that value will be returned.

 



#### [maxBy()](index#maxBy())




Like `[max](../list/index#max())`, but also accepts a `comparatorValueMapper` which allows for comparing by more sophisticated means:

 

```
maxBy<C>(comparatorValueMapper: (value: V, key: K, iter: this) => C,comparator?: (valueA: C, valueB: C) => number): V | undefined

```

#### Inherited from


`[Collection#maxBy()](../collection/index#maxBy())`#### Discussion


 
```
const { List, } = require('immutable');
const l = List([
  { name: 'Bob', avgHit: 1 },
  { name: 'Max', avgHit: 3 },
  { name: 'Lili', avgHit: 2 } ,
]);
l.maxBy(i => i.avgHit); // will output { name: 'Max', avgHit: 3 }run it
```


 



#### [min()](index#min())




Returns the minimum value in this collection. If any values are comparatively equivalent, the first one found will be returned.

 

```
min(comparator?: (valueA: V, valueB: V) => number): V | undefined

```

#### Inherited from


`[Collection#min()](../collection/index#min())`#### Discussion



The `comparator` is used in the same way as `[Collection#sort](../collection/index#sort())`. If it is not provided, the default comparator is `<`.

 When two values are considered equivalent, the first encountered will be returned. Otherwise, `[min](../list/index#min())` will operate independent of the order of input as long as the comparator is commutative. The default comparator `<` is commutative *only* when types do not differ.

 If `comparator` returns 0 and either value is NaN, undefined, or null, that value will be returned.

 



#### [minBy()](index#minBy())




Like `[min](../list/index#min())`, but also accepts a `comparatorValueMapper` which allows for comparing by more sophisticated means:

 

```
minBy<C>(comparatorValueMapper: (value: V, key: K, iter: this) => C,comparator?: (valueA: C, valueB: C) => number): V | undefined

```

#### Inherited from


`[Collection#minBy()](../collection/index#minBy())`#### Discussion


 
```
const { List, } = require('immutable');
const l = List([
  { name: 'Bob', avgHit: 1 },
  { name: 'Max', avgHit: 3 },
  { name: 'Lili', avgHit: 2 } ,
]);
l.minBy(i => i.avgHit); // will output { name: 'Bob', avgHit: 1 }run it
```


 


### Comparison



#### [isSubset()](index#isSubset())




True if `iter` includes every value in this Collection.

 

```
isSubset(iter: Iterable<V>): boolean

```

#### Inherited from


`[Collection#isSubset()](../collection/index#isSubset())`



#### [isSuperset()](index#isSuperset())




True if this Collection includes every value in `iter`.

 

```
isSuperset(iter: Iterable<V>): boolean

```

#### Inherited from


`[Collection#isSuperset()](../collection/index#isSuperset())`

This documentation is generated from [immutable.d.ts](https://github.com/immutable-js/immutable-js/blob/main/type-definitions/immutable.d.ts). Pull requests and [Issues](https://github.com/immutable-js/immutable-js/issues) welcome.

 © 2014–present, Lee Byron and other contributors  
Licensed under the 3-clause BSD License.  

<https://immutable-js.com/docs/v4.2.1/Map/>

Seq.Indexed
===========



`[Seq](../seq/index)` which represents an ordered indexed list of values.

 

```
type Seq.Indexed<T> extends Seq<number, T>, Collection.Indexed<T>
```

### Construction



#### [Seq.Indexed()](index#Seq.Indexed())




Always returns Seq.Indexed, discarding associated keys and supplying incrementing indices.

 

```
Seq.Indexed<T>(collection?: Iterable<T> | ArrayLike<T>): Seq.Indexed<T>

```

#### Discussion



Note: `[Seq.Indexed](index)` is a conversion function and not a class, and does not use the `new` keyword during construction.

 


### Static methods



#### [Seq.Indexed.of()](index#of())



```
Seq.Indexed.of<T>(...values: Array<T>): Seq.Indexed<T>

```


### Conversion to JavaScript types



#### [toJS()](index#toJS())




Deeply converts this Indexed Seq to equivalent native JavaScript Array.

 

```
toJS(): Array<DeepCopy<T>>

```

#### Overrides


`[Collection#toJS()](../collection/index#toJS())`



#### [toJSON()](index#toJSON())




Shallowly converts this Indexed Seq to equivalent native JavaScript Array.

 

```
toJSON(): Array<T>

```

#### Overrides


`[Collection#toJSON()](../collection/index#toJSON())`



#### [toArray()](index#toArray())




Shallowly converts this collection to an Array.

 

```
toArray(): Array<T>

```

#### Overrides


`[Collection#toArray()](../collection/index#toArray())`



#### [toObject()](index#toObject())




Shallowly converts this Collection to an Object.

 

```
toObject(): {[key: string]: T}

```

#### Inherited from


`[Collection#toObject()](../collection/index#toObject())`#### Discussion



Converts keys to Strings.

 


### Conversion to Seq



#### [toSeq()](index#toSeq())




Returns itself

 

```
toSeq(): this

```

#### Overrides


`[Collection#toSeq()](../collection/index#toSeq())`



#### [toKeyedSeq()](index#toKeyedSeq())




Returns a Seq.Keyed from this Collection where indices are treated as keys.

 

```
toKeyedSeq(): Seq.Keyed<number, T>

```

#### Inherited from


`[Collection#toKeyedSeq()](../collection/index#toKeyedSeq())`#### Discussion



This is useful if you want to operate on an Collection.Indexed and preserve the [index, value] pairs.

 The returned Seq will have identical iteration order as this Collection.

 
```
const { Seq } = require('immutable')
const indexedSeq = Seq([ 'A', 'B', 'C' ])
// Seq [ "A", "B", "C" ]
indexedSeq.filter(v => v === 'B')
// Seq [ "B" ]
const keyedSeq = indexedSeq.toKeyedSeq()
// Seq { 0: "A", 1: "B", 2: "C" }
keyedSeq.filter(v => v === 'B')
// Seq { 1: "B" }run it
```





#### [toIndexedSeq()](index#toIndexedSeq())




Returns an Seq.Indexed of the values of this Collection, discarding keys.

 

```
toIndexedSeq(): Seq.Indexed<T>

```

#### Inherited from


`[Collection#toIndexedSeq()](../collection/index#toIndexedSeq())`



#### [toSetSeq()](index#toSetSeq())




Returns a Seq.Set of the values of this Collection, discarding keys.

 

```
toSetSeq(): Seq.Set<T>

```

#### Inherited from


`[Collection#toSetSeq()](../collection/index#toSetSeq())`



#### [fromEntrySeq()](index#fromEntrySeq())




If this is a collection of [key, value] entry tuples, it will return a Seq.Keyed of those entries.

 

```
fromEntrySeq(): Seq.Keyed<unknown, unknown>

```

#### Inherited from


`[Collection.Indexed#fromEntrySeq()](../collection.indexed/index#fromEntrySeq())`


### Combination



#### [concat()](index#concat())




Returns a new Seq with other collections concatenated to this one.

 

```
concat<C>(...valuesOrCollections: Array<Iterable<C> | C>): Seq.Indexed<T | C>

```

#### Overrides


`[Collection#concat()](../collection/index#concat())`



#### [zip()](index#zip())




```
zip<U>(other: Collection<unknown, U>): Seq.Indexed<[T, U]>
zip<U, V>(other: Collection<unknown, U>,other2: Collection<unknown, V>): Seq.Indexed<[T, U, V]>
zip(...collections: Array<Collection<unknown, unknown>>): Seq.Indexed<unknown>

```

#### Overrides


`[Collection.Indexed#zip()](../collection.indexed/index#zip())`



#### [zipAll()](index#zipAll())




```
zipAll<U>(other: Collection<unknown, U>): Seq.Indexed<[T, U]>
zipAll<U, V>(other: Collection<unknown, U>,other2: Collection<unknown, V>): Seq.Indexed<[T, U, V]>
zipAll(...collections: Array<Collection<unknown, unknown>>): Seq.Indexed<unknown>

```

#### Overrides


`[Collection.Indexed#zipAll()](../collection.indexed/index#zipAll())`



#### [zipWith()](index#zipWith())




```
zipWith<U, Z>(zipper: (value: T, otherValue: U) => Z,otherCollection: Collection<unknown, U>): Seq.Indexed<Z>
zipWith<U, V, Z>(zipper: (value: T, otherValue: U, thirdValue: V) => Z,otherCollection: Collection<unknown, U>,thirdCollection: Collection<unknown, V>): Seq.Indexed<Z>
zipWith<Z>(zipper: (...values: Array<unknown>) => Z,...collections: Array<Collection<unknown, unknown>>): Seq.Indexed<Z>

```

#### Overrides


`[Collection.Indexed#zipWith()](../collection.indexed/index#zipWith())`



#### [flatten()](index#flatten())




```
flatten(depth?: number): Collection<unknown, unknown>
flatten(shallow?: boolean): Collection<unknown, unknown>

```

#### Inherited from


`[Collection#flatten()](../collection/index#flatten())`



#### [interpose()](index#interpose())




Returns a Collection of the same type with `separator` between each item in this Collection.

 

```
interpose(separator: T): this

```

#### Inherited from


`[Collection.Indexed#interpose()](../collection.indexed/index#interpose())`



#### [interleave()](index#interleave())




Returns a Collection of the same type with the provided `collections` interleaved into this collection.

 

```
interleave(...collections: Array<Collection<unknown, T>>): this

```

#### Inherited from


`[Collection.Indexed#interleave()](../collection.indexed/index#interleave())`#### Discussion



The resulting Collection includes the first item from each, then the second from each, etc.

 
```
const { List } = require('immutable')
List([ 1, 2, 3 ]).interleave(List([ 'A', 'B', 'C' ]))
// List [ 1, "A", 2, "B", 3, "C" ]run it
```

The shortest Collection stops interleave.

 
```
List([ 1, 2, 3 ]).interleave(
  List([ 'A', 'B' ]),
  List([ 'X', 'Y', 'Z' ])
)
// List [ 1, "A", "X", 2, "B", "Y" ]run it
```

Since `[interleave()](../list/index#interleave())` re-indexes values, it produces a complete copy, which has `O(N)` complexity.

 Note: `[interleave](../list/index#interleave())` *cannot* be used in `[withMutations](../list/index#withMutations())`.

 



#### [splice()](index#splice())




Splice returns a new indexed Collection by replacing a region of this Collection with new values. If values are not provided, it only skips the region to be removed.

 

```
splice(index: number, removeNum: number, ...values: Array<T>): this

```

#### Inherited from


`[Collection.Indexed#splice()](../collection.indexed/index#splice())`#### Discussion



`index` may be a negative number, which indexes back from the end of the Collection. `s.splice(-2)` splices after the second to last item.

 
```
const { List } = require('immutable')
List([ 'a', 'b', 'c', 'd' ]).splice(1, 2, 'q', 'r', 's')
// List [ "a", "q", "r", "s", "d" ]run it
```

Since `[splice()](../list/index#splice())` re-indexes values, it produces a complete copy, which has `O(N)` complexity.

 Note: `[splice](../list/index#splice())` *cannot* be used in `[withMutations](../list/index#withMutations())`.

 


### Sequence algorithms



#### [map()](index#map())




Returns a new Seq.Indexed with values passed through a `mapper` function.

 

```
map<M>(mapper: (value: T, key: number, iter: this) => M,context?: unknown): Seq.Indexed<M>

```

#### Overrides


`[Seq#map()](../seq/index#map())`#### Example




```
const { Seq } = require('immutable')
Seq.Indexed([ 1, 2 ]).map(x => 10 * x)
// Seq [ 10, 20 ]
```

Note: `[map()](index#map())` always returns a new instance, even if it produced the same value at every step.

 



#### [flatMap()](index#flatMap())




Flat-maps the Seq, returning a a Seq of the same type.

 

```
flatMap<M>(mapper: (value: T, key: number, iter: this) => Iterable<M>,context?: unknown): Seq.Indexed<M>

```

#### Overrides


`[Seq#flatMap()](../seq/index#flatMap())`#### Discussion



Similar to `seq.map(...).flatten(true)`.

 



#### [filter()](index#filter())




```
filter<F>(predicate: (value: T, index: number, iter: this) => boolean,context?: unknown): Seq.Indexed<F>
filter(predicate: (value: T, index: number, iter: this) => unknown,context?: unknown): this

```

#### Overrides


`[Seq#filter()](../seq/index#filter())`



#### [partition()](index#partition())




```
partition<F, C>(predicate: (this: C, value: T, index: number, iter: this) => boolean,context?: C): [Seq.Indexed<T>, Seq.Indexed<F>]
partition<C>(predicate: (this: C, value: T, index: number, iter: this) => unknown,context?: C): [this, this]

```

#### Overrides


`[Seq#partition()](../seq/index#partition())`



#### [filterNot()](index#filterNot())




Returns a new Collection of the same type with only the entries for which the `predicate` function returns false.

 

```
filterNot(predicate: (value: T, key: number, iter: this) => boolean,context?: unknown): this

```

#### Inherited from


`[Collection#filterNot()](../collection/index#filterNot())`#### Discussion


 
```
const { Map } = require('immutable')
Map({ a: 1, b: 2, c: 3, d: 4}).filterNot(x => x % 2 === 0)
// Map { "a": 1, "c": 3 }run it
```



Note: `[filterNot()](../list/index#filterNot())` always returns a new instance, even if it results in not filtering out any values.

 



#### [reverse()](index#reverse())




Returns a new Collection of the same type in reverse order.

 

```
reverse(): this

```

#### Inherited from


`[Collection#reverse()](../collection/index#reverse())`



#### [sort()](index#sort())




Returns a new Collection of the same type which includes the same entries, stably sorted by using a `comparator`.

 

```
sort(comparator?: (valueA: T, valueB: T) => number): this

```

#### Inherited from


`[Collection#sort()](../collection/index#sort())`#### Discussion



If a `comparator` is not provided, a default comparator uses `<` and `>`.

 `comparator(valueA, valueB)`:

 * Returns `0` if the elements should not be swapped.
* Returns `-1` (or any negative number) if `valueA` comes before `valueB`
* Returns `1` (or any positive number) if `valueA` comes after `valueB`
* Is pure, i.e. it must always return the same value for the same pair of values.

 When sorting collections which have no defined order, their ordered equivalents will be returned. e.g. `map.sort()` returns OrderedMap.

 
```
const { Map } = require('immutable')
Map({ "c": 3, "a": 1, "b": 2 }).sort((a, b) => {
  if (a < b) { return -1; }
  if (a > b) { return 1; }
  if (a === b) { return 0; }
});
// OrderedMap { "a": 1, "b": 2, "c": 3 }run it
```

Note: `[sort()](../list/index#sort())` Always returns a new instance, even if the original was already sorted.

 Note: This is always an eager operation.

 



#### [sortBy()](index#sortBy())




Like `[sort](../list/index#sort())`, but also accepts a `comparatorValueMapper` which allows for sorting by more sophisticated means:

 

```
sortBy<C>(comparatorValueMapper: (value: T, key: number, iter: this) => C,comparator?: (valueA: C, valueB: C) => number): this

```

#### Inherited from


`[Collection#sortBy()](../collection/index#sortBy())`#### Discussion


 
```
const { Map } = require('immutable')
const beattles = Map({
  John: { name: "Lennon" },
  Paul: { name: "McCartney" },
  George: { name: "Harrison" },
  Ringo: { name: "Starr" },
});
beattles.sortBy(member => member.name);run it
```



Note: `[sortBy()](../list/index#sortBy())` Always returns a new instance, even if the original was already sorted.

 Note: This is always an eager operation.

 



#### [groupBy()](index#groupBy())




Returns a `[Collection.Keyed](../collection.keyed/index)` of `Collection.Keyeds`, grouped by the return value of the `grouper` function.

 

```
groupBy<G>(grouper: (value: T, key: number, iter: this) => G,context?: unknown): Seq.Keyed<G, Collection<number, T>>

```

#### Inherited from


`[Collection#groupBy()](../collection/index#groupBy())`#### Discussion



Note: This is always an eager operation.

 
```
const { List, Map } = require('immutable')
const listOfMaps = List([
  Map({ v: 0 }),
  Map({ v: 1 }),
  Map({ v: 1 }),
  Map({ v: 0 }),
  Map({ v: 2 })
])
const groupsOfMaps = listOfMaps.groupBy(x => x.get('v'))
// Map {
//   0: List [ Map{ "v": 0 }, Map { "v": 0 } ],
//   1: List [ Map{ "v": 1 }, Map { "v": 1 } ],
//   2: List [ Map{ "v": 2 } ],
// }run it
```




### Iterators



#### [[Symbol.iterator]()](index#%5BSymbol.iterator%5D())




```
[Symbol.iterator](): IterableIterator<T>

```

#### Overrides


`[Collection#[Symbol.iterator]()](../collection/index#%5BSymbol.iterator%5D())`



#### [keys()](index#keys())




An iterator of this `[Collection](../collection/index)`'s keys.

 

```
keys(): IterableIterator<number>

```

#### Inherited from


`[Collection#keys()](../collection/index#keys())`#### Discussion



Note: this will return an ES6 iterator which does not support Immutable.js sequence algorithms. Use `[keySeq](../list/index#keySeq())` instead, if this is what you want.

 



#### [values()](index#values())




An iterator of this `[Collection](../collection/index)`'s values.

 

```
values(): IterableIterator<T>

```

#### Inherited from


`[Collection#values()](../collection/index#values())`#### Discussion



Note: this will return an ES6 iterator which does not support Immutable.js sequence algorithms. Use `[valueSeq](../list/index#valueSeq())` instead, if this is what you want.

 



#### [entries()](index#entries())




An iterator of this `[Collection](../collection/index)`'s entries as `[ key, value ]` tuples.

 

```
entries(): IterableIterator<[number, T]>

```

#### Inherited from


`[Collection#entries()](../collection/index#entries())`#### Discussion



Note: this will return an ES6 iterator which does not support Immutable.js sequence algorithms. Use `[entrySeq](../list/index#entrySeq())` instead, if this is what you want.

 


### Members



#### [size](index#size)




Some Seqs can describe their size lazily. When this is the case, size will be an integer. Otherwise it will be undefined.

 

```
size: number | undefined
```

#### Inherited from


`[Seq#size](../seq/index#size)`#### Discussion



For example, Seqs returned from `[map()](../seq/index#map())` or `[reverse()](../seq/index#reverse())` preserve the size of the original `[Seq](../seq/index)` while `[filter()](../seq/index#filter())` does not.

 Note: `[Range](../range()/index)`, `[Repeat](../repeat()/index)` and `[Seq](../seq/index)`s made from `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)`s and `[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)`s will always have a size.

 


### Force evaluation



#### [cacheResult()](index#cacheResult())




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](../seq/index#join())` iterates the Seq of three values.

 

```
cacheResult(): this

```

#### Inherited from


`[Seq#cacheResult()](../seq/index#cacheResult())`#### Discussion




```
var squares = Seq([ 1, 2, 3 ]).map(x => x  x)
squares.join() + squares.join()
```



If you know a `[Seq](../seq/index)` 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](../seq/index#cacheResult())`, a Seq will always have a `[size](../seq/index#size)`.

 


### Value equality



#### [equals()](index#equals())




True if this and the other Collection have value equality, as defined by `[Immutable.is()](../is()/index)`.

 

```
equals(other: unknown): boolean

```

#### Inherited from


`[Collection#equals()](../collection/index#equals())`#### Discussion



Note: This is equivalent to `Immutable.is(this, other)`, but provided to allow for chained expressions.

 



#### [hashCode()](index#hashCode())




Computes and returns the hashed identity for this Collection.

 

```
hashCode(): number

```

#### Inherited from


`[Collection#hashCode()](../collection/index#hashCode())`#### Discussion



The `[hashCode](../list/index#hashCode())` of a Collection is used to determine potential equality, and is used when adding this to a `[Set](../set/index)` or as a key in a `[Map](../map/index)`, enabling lookup via a different instance.

 
```
const a = List([ 1, 2, 3 ]);
const b = List([ 1, 2, 3 ]);
assert.notStrictEqual(a, b); // different instances
const set = Set([ a ]);
assert.equal(set.has(b), true);run it
```

If two values have the same `[hashCode](../list/index#hashCode())`, they are [not guaranteed to be equal](https://en.wikipedia.org/wiki/Collision_(computer_science)). If two values have different `[hashCode](../list/index#hashCode())`s, they must not be equal.

 


### Reading values



#### [get()](index#get())




```
get<NSV>(key: number, notSetValue: NSV): T | NSV
get(key: number): T | undefined

```

#### Inherited from


`[Collection#get()](../collection/index#get())`



#### [has()](index#has())




True if a key exists within this `[Collection](../collection/index)`, using `[Immutable.is](../is()/index)` to determine equality

 

```
has(key: number): boolean

```

#### Inherited from


`[Collection#has()](../collection/index#has())`



#### [includes()](index#includes())




True if a value exists within this `[Collection](../collection/index)`, using `[Immutable.is](../is()/index)` to determine equality

 

```
includes(value: T): boolean

```

#### Inherited from


`[Collection#includes()](../collection/index#includes())`#### alias


`contains()`



#### [first()](index#first())




In case the `[Collection](../collection/index)` is not empty returns the first element of the `[Collection](../collection/index)`. In case the `[Collection](../collection/index)` is empty returns the optional default value if provided, if no default value is provided returns undefined.

 

```
first<NSV>(notSetValue?: NSV): T | NSV

```

#### Inherited from


`[Collection#first()](../collection/index#first())`



#### [last()](index#last())




In case the `[Collection](../collection/index)` is not empty returns the last element of the `[Collection](../collection/index)`. In case the `[Collection](../collection/index)` is empty returns the optional default value if provided, if no default value is provided returns undefined.

 

```
last<NSV>(notSetValue?: NSV): T | NSV

```

#### Inherited from


`[Collection#last()](../collection/index#last())`


### Reading deep values



#### [getIn()](index#getIn())




Returns the value found by following a path of keys or indices through nested Collections.

 

```
getIn(searchKeyPath: Iterable<unknown>, notSetValue?: unknown): unknown

```

#### Inherited from


`[Collection#getIn()](../collection/index#getIn())`#### Discussion


 
```
const { Map, List } = require('immutable')
const deepData = Map({ x: List([ Map({ y: 123 }) ]) });
deepData.getIn(['x', 0, 'y']) // 123run it
```



Plain JavaScript Object or Arrays may be nested within an Immutable.js Collection, and getIn() can access those values as well:

 
```
const { Map, List } = require('immutable')
const deepData = Map({ x: [ { y: 123 } ] });
deepData.getIn(['x', 0, 'y']) // 123run it
```


 



#### [hasIn()](index#hasIn())




True if the result of following a path of keys or indices through nested Collections results in a set value.

 

```
hasIn(searchKeyPath: Iterable<unknown>): boolean

```

#### Inherited from


`[Collection#hasIn()](../collection/index#hasIn())`


### Persistent changes



#### [update()](index#update())




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".

 

```
update<R>(updater: (value: this) => R): R

```

#### Inherited from


`[Collection#update()](../collection/index#update())`#### Discussion



For example, to sum a Seq after mapping and filtering:

 
```
const { Seq } = require('immutable')

function sum(collection) {
  return collection.reduce((sum, x) => sum + x, 0)
}
Seq([ 1, 2, 3 ])
  .map(x => x + 1)
  .filter(x => x % 2 === 0)
  .update(sum)
// 6run it
```
 


### Conversion to Collections



#### [toMap()](index#toMap())




Converts this Collection to a Map, Throws if keys are not hashable.

 

```
toMap(): Map<number, T>

```

#### Inherited from


`[Collection#toMap()](../collection/index#toMap())`#### Discussion



Note: This is equivalent to `Map(this.toKeyedSeq())`, but provided for convenience and to allow for chained expressions.

 



#### [toOrderedMap()](index#toOrderedMap())




Converts this Collection to a Map, maintaining the order of iteration.

 

```
toOrderedMap(): OrderedMap<number, T>

```

#### Inherited from


`[Collection#toOrderedMap()](../collection/index#toOrderedMap())`#### Discussion



Note: This is equivalent to `OrderedMap(this.toKeyedSeq())`, but provided for convenience and to allow for chained expressions.

 



#### [toSet()](index#toSet())




Converts this Collection to a Set, discarding keys. Throws if values are not hashable.

 

```
toSet(): Set<T>

```

#### Inherited from


`[Collection#toSet()](../collection/index#toSet())`#### Discussion



Note: This is equivalent to `[Set(this)](../set/index)`, but provided to allow for chained expressions.

 



#### [toOrderedSet()](index#toOrderedSet())




Converts this Collection to a Set, maintaining the order of iteration and discarding keys.

 

```
toOrderedSet(): OrderedSet<T>

```

#### Inherited from


`[Collection#toOrderedSet()](../collection/index#toOrderedSet())`#### Discussion



Note: This is equivalent to `OrderedSet(this.valueSeq())`, but provided for convenience and to allow for chained expressions.

 



#### [toList()](index#toList())




Converts this Collection to a List, discarding keys.

 

```
toList(): List<T>

```

#### Inherited from


`[Collection#toList()](../collection/index#toList())`#### Discussion



This is similar to `[List(collection)](../list/index)`, but provided to allow for chained expressions. However, when called on `[Map](../map/index)` or other keyed collections, `collection.toList()` discards the keys and creates a list of only the values, whereas `[List(collection)](../list/index)` creates a list of entry tuples.

 
```
const { Map, List } = require('immutable')
var myMap = Map({ a: 'Apple', b: 'Banana' })
List(myMap) // List [ [ "a", "Apple" ], [ "b", "Banana" ] ]
myMap.toList() // List [ "Apple", "Banana" ]run it
```





#### [toStack()](index#toStack())




Converts this Collection to a Stack, discarding keys. Throws if values are not hashable.

 

```
toStack(): Stack<T>

```

#### Inherited from


`[Collection#toStack()](../collection/index#toStack())`#### Discussion



Note: This is equivalent to `[Stack(this)](../stack/index)`, but provided to allow for chained expressions.

 


### Collections (Seq)



#### [keySeq()](index#keySeq())




Returns a new Seq.Indexed of the keys of this Collection, discarding values.

 

```
keySeq(): Seq.Indexed<number>

```

#### Inherited from


`[Collection#keySeq()](../collection/index#keySeq())`



#### [valueSeq()](index#valueSeq())




Returns an Seq.Indexed of the values of this Collection, discarding keys.

 

```
valueSeq(): Seq.Indexed<T>

```

#### Inherited from


`[Collection#valueSeq()](../collection/index#valueSeq())`



#### [entrySeq()](index#entrySeq())




Returns a new Seq.Indexed of [key, value] tuples.

 

```
entrySeq(): Seq.Indexed<[number, T]>

```

#### Inherited from


`[Collection#entrySeq()](../collection/index#entrySeq())`


### Side effects



#### [forEach()](index#forEach())




The `sideEffect` is executed for every entry in the Collection.

 

```
forEach(sideEffect: (value: T, key: number, iter: this) => unknown,context?: unknown): number

```

#### Inherited from


`[Collection#forEach()](../collection/index#forEach())`#### Discussion



Unlike `[Array#forEach](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/forEach)`, if any call of `sideEffect` returns `false`, the iteration will stop. Returns the number of entries iterated (including the last iteration which returned false).

 


### Creating subsets



#### [slice()](index#slice())




Returns a new Collection of the same type representing a portion of this Collection from start up to but not including end.

 

```
slice(begin?: number, end?: number): this

```

#### Inherited from


`[Collection#slice()](../collection/index#slice())`#### Discussion



If begin is negative, it is offset from the end of the Collection. e.g. `slice(-2)` returns a Collection of the last two entries. If it is not provided the new Collection will begin at the beginning of this Collection.

 If end is negative, it is offset from the end of the Collection. e.g. `slice(0, -1)` returns a Collection of everything but the last entry. If it is not provided, the new Collection will continue through the end of this Collection.

 If the requested slice is equivalent to the current Collection, then it will return itself.

 



#### [rest()](index#rest())




Returns a new Collection of the same type containing all entries except the first.

 

```
rest(): this

```

#### Inherited from


`[Collection#rest()](../collection/index#rest())`



#### [butLast()](index#butLast())




Returns a new Collection of the same type containing all entries except the last.

 

```
butLast(): this

```

#### Inherited from


`[Collection#butLast()](../collection/index#butLast())`



#### [skip()](index#skip())




Returns a new Collection of the same type which excludes the first `amount` entries from this Collection.

 

```
skip(amount: number): this

```

#### Inherited from


`[Collection#skip()](../collection/index#skip())`



#### [skipLast()](index#skipLast())




Returns a new Collection of the same type which excludes the last `amount` entries from this Collection.

 

```
skipLast(amount: number): this

```

#### Inherited from


`[Collection#skipLast()](../collection/index#skipLast())`



#### [skipWhile()](index#skipWhile())




Returns a new Collection of the same type which includes entries starting from when `predicate` first returns false.

 

```
skipWhile(predicate: (value: T, key: number, iter: this) => boolean,context?: unknown): this

```

#### Inherited from


`[Collection#skipWhile()](../collection/index#skipWhile())`#### Discussion


 
```
const { List } = require('immutable')
List([ 'dog', 'frog', 'cat', 'hat', 'god' ])
  .skipWhile(x => x.match(/g/))
// List [ "cat", "hat", "god" ]run it
```


 



#### [skipUntil()](index#skipUntil())




Returns a new Collection of the same type which includes entries starting from when `predicate` first returns true.

 

```
skipUntil(predicate: (value: T, key: number, iter: this) => boolean,context?: unknown): this

```

#### Inherited from


`[Collection#skipUntil()](../collection/index#skipUntil())`#### Discussion


 
```
const { List } = require('immutable')
List([ 'dog', 'frog', 'cat', 'hat', 'god' ])
  .skipUntil(x => x.match(/hat/))
// List [ "hat", "god" ]run it
```


 



#### [take()](index#take())




Returns a new Collection of the same type which includes the first `amount` entries from this Collection.

 

```
take(amount: number): this

```

#### Inherited from


`[Collection#take()](../collection/index#take())`



#### [takeLast()](index#takeLast())




Returns a new Collection of the same type which includes the last `amount` entries from this Collection.

 

```
takeLast(amount: number): this

```

#### Inherited from


`[Collection#takeLast()](../collection/index#takeLast())`



#### [takeWhile()](index#takeWhile())




Returns a new Collection of the same type which includes entries from this Collection as long as the `predicate` returns true.

 

```
takeWhile(predicate: (value: T, key: number, iter: this) => boolean,context?: unknown): this

```

#### Inherited from


`[Collection#takeWhile()](../collection/index#takeWhile())`#### Discussion


 
```
const { List } = require('immutable')
List([ 'dog', 'frog', 'cat', 'hat', 'god' ])
  .takeWhile(x => x.match(/o/))
// List [ "dog", "frog" ]run it
```


 



#### [takeUntil()](index#takeUntil())




Returns a new Collection of the same type which includes entries from this Collection as long as the `predicate` returns false.

 

```
takeUntil(predicate: (value: T, key: number, iter: this) => boolean,context?: unknown): this

```

#### Inherited from


`[Collection#takeUntil()](../collection/index#takeUntil())`#### Discussion


 
```
const { List } = require('immutable')
List([ 'dog', 'frog', 'cat', 'hat', 'god' ])
  .takeUntil(x => x.match(/at/))
// List [ "dog", "frog" ]run it
```


 


### Reducing a value



#### [reduce()](index#reduce())




```
reduce<R>(reducer: (reduction: R, value: T, key: number, iter: this) => R,initialReduction: R,context?: unknown): R
reduce<R>(reducer: (reduction: T | R, value: T, key: number, iter: this) => R): R

```

#### Inherited from


`[Collection#reduce()](../collection/index#reduce())`



#### [reduceRight()](index#reduceRight())




```
reduceRight<R>(reducer: (reduction: R, value: T, key: number, iter: this) => R,initialReduction: R,context?: unknown): R
reduceRight<R>(reducer: (reduction: T | R, value: T, key: number, iter: this) => R): R

```

#### Inherited from


`[Collection#reduceRight()](../collection/index#reduceRight())`



#### [every()](index#every())




True if `predicate` returns true for all entries in the Collection.

 

```
every(predicate: (value: T, key: number, iter: this) => boolean,context?: unknown): boolean

```

#### Inherited from


`[Collection#every()](../collection/index#every())`



#### [some()](index#some())




True if `predicate` returns true for any entry in the Collection.

 

```
some(predicate: (value: T, key: number, iter: this) => boolean,context?: unknown): boolean

```

#### Inherited from


`[Collection#some()](../collection/index#some())`



#### [join()](index#join())




Joins values together as a string, inserting a separator between each. The default separator is `","`.

 

```
join(separator?: string): string

```

#### Inherited from


`[Collection#join()](../collection/index#join())`



#### [isEmpty()](index#isEmpty())




Returns true if this Collection includes no values.

 

```
isEmpty(): boolean

```

#### Inherited from


`[Collection#isEmpty()](../collection/index#isEmpty())`#### Discussion



For some lazy `[Seq](../seq/index)`, `[isEmpty](../list/index#isEmpty())` might need to iterate to determine emptiness. At most one iteration will occur.

 



#### [count()](index#count())




```
count(): number
count(predicate: (value: T, key: number, iter: this) => boolean,context?: unknown): number

```

#### Inherited from


`[Collection#count()](../collection/index#count())`



#### [countBy()](index#countBy())




Returns a `[Seq.Keyed](../seq.keyed/index)` of counts, grouped by the return value of the `grouper` function.

 

```
countBy<G>(grouper: (value: T, key: number, iter: this) => G,context?: unknown): Map<G, number>

```

#### Inherited from


`[Collection#countBy()](../collection/index#countBy())`#### Discussion



Note: This is not a lazy operation.

 


### Search for value



#### [find()](index#find())




Returns the first value for which the `predicate` returns true.

 

```
find(predicate: (value: T, key: number, iter: this) => boolean,context?: unknown,notSetValue?: T): T | undefined

```

#### Inherited from


`[Collection#find()](../collection/index#find())`



#### [findLast()](index#findLast())




Returns the last value for which the `predicate` returns true.

 

```
findLast(predicate: (value: T, key: number, iter: this) => boolean,context?: unknown,notSetValue?: T): T | undefined

```

#### Inherited from


`[Collection#findLast()](../collection/index#findLast())`#### Discussion



Note: `predicate` will be called for each entry in reverse.

 



#### [findEntry()](index#findEntry())




Returns the first [key, value] entry for which the `predicate` returns true.

 

```
findEntry(predicate: (value: T, key: number, iter: this) => boolean,context?: unknown,notSetValue?: T): [number, T] | undefined

```

#### Inherited from


`[Collection#findEntry()](../collection/index#findEntry())`



#### [findLastEntry()](index#findLastEntry())




Returns the last [key, value] entry for which the `predicate` returns true.

 

```
findLastEntry(predicate: (value: T, key: number, iter: this) => boolean,context?: unknown,notSetValue?: T): [number, T] | undefined

```

#### Inherited from


`[Collection#findLastEntry()](../collection/index#findLastEntry())`#### Discussion



Note: `predicate` will be called for each entry in reverse.

 



#### [findKey()](index#findKey())




Returns the key for which the `predicate` returns true.

 

```
findKey(predicate: (value: T, key: number, iter: this) => boolean,context?: unknown): number | undefined

```

#### Inherited from


`[Collection#findKey()](../collection/index#findKey())`



#### [findLastKey()](index#findLastKey())




Returns the last key for which the `predicate` returns true.

 

```
findLastKey(predicate: (value: T, key: number, iter: this) => boolean,context?: unknown): number | undefined

```

#### Inherited from


`[Collection#findLastKey()](../collection/index#findLastKey())`#### Discussion



Note: `predicate` will be called for each entry in reverse.

 



#### [keyOf()](index#keyOf())




Returns the key associated with the search value, or undefined.

 

```
keyOf(searchValue: T): number | undefined

```

#### Inherited from


`[Collection#keyOf()](../collection/index#keyOf())`



#### [lastKeyOf()](index#lastKeyOf())




Returns the last key associated with the search value, or undefined.

 

```
lastKeyOf(searchValue: T): number | undefined

```

#### Inherited from


`[Collection#lastKeyOf()](../collection/index#lastKeyOf())`



#### [max()](index#max())




Returns the maximum value in this collection. If any values are comparatively equivalent, the first one found will be returned.

 

```
max(comparator?: (valueA: T, valueB: T) => number): T | undefined

```

#### Inherited from


`[Collection#max()](../collection/index#max())`#### Discussion



The `comparator` is used in the same way as `[Collection#sort](../collection/index#sort())`. If it is not provided, the default comparator is `>`.

 When two values are considered equivalent, the first encountered will be returned. Otherwise, `[max](../list/index#max())` will operate independent of the order of input as long as the comparator is commutative. The default comparator `>` is commutative *only* when types do not differ.

 If `comparator` returns 0 and either value is NaN, undefined, or null, that value will be returned.

 



#### [maxBy()](index#maxBy())




Like `[max](../list/index#max())`, but also accepts a `comparatorValueMapper` which allows for comparing by more sophisticated means:

 

```
maxBy<C>(comparatorValueMapper: (value: T, key: number, iter: this) => C,comparator?: (valueA: C, valueB: C) => number): T | undefined

```

#### Inherited from


`[Collection#maxBy()](../collection/index#maxBy())`#### Discussion


 
```
const { List, } = require('immutable');
const l = List([
  { name: 'Bob', avgHit: 1 },
  { name: 'Max', avgHit: 3 },
  { name: 'Lili', avgHit: 2 } ,
]);
l.maxBy(i => i.avgHit); // will output { name: 'Max', avgHit: 3 }run it
```


 



#### [min()](index#min())




Returns the minimum value in this collection. If any values are comparatively equivalent, the first one found will be returned.

 

```
min(comparator?: (valueA: T, valueB: T) => number): T | undefined

```

#### Inherited from


`[Collection#min()](../collection/index#min())`#### Discussion



The `comparator` is used in the same way as `[Collection#sort](../collection/index#sort())`. If it is not provided, the default comparator is `<`.

 When two values are considered equivalent, the first encountered will be returned. Otherwise, `[min](../list/index#min())` will operate independent of the order of input as long as the comparator is commutative. The default comparator `<` is commutative *only* when types do not differ.

 If `comparator` returns 0 and either value is NaN, undefined, or null, that value will be returned.

 



#### [minBy()](index#minBy())




Like `[min](../list/index#min())`, but also accepts a `comparatorValueMapper` which allows for comparing by more sophisticated means:

 

```
minBy<C>(comparatorValueMapper: (value: T, key: number, iter: this) => C,comparator?: (valueA: C, valueB: C) => number): T | undefined

```

#### Inherited from


`[Collection#minBy()](../collection/index#minBy())`#### Discussion


 
```
const { List, } = require('immutable');
const l = List([
  { name: 'Bob', avgHit: 1 },
  { name: 'Max', avgHit: 3 },
  { name: 'Lili', avgHit: 2 } ,
]);
l.minBy(i => i.avgHit); // will output { name: 'Bob', avgHit: 1 }run it
```


 



#### [indexOf()](index#indexOf())




Returns the first index at which a given value can be found in the Collection, or -1 if it is not present.

 

```
indexOf(searchValue: T): number

```

#### Inherited from


`[Collection.Indexed#indexOf()](../collection.indexed/index#indexOf())`



#### [lastIndexOf()](index#lastIndexOf())




Returns the last index at which a given value can be found in the Collection, or -1 if it is not present.

 

```
lastIndexOf(searchValue: T): number

```

#### Inherited from


`[Collection.Indexed#lastIndexOf()](../collection.indexed/index#lastIndexOf())`



#### [findIndex()](index#findIndex())




Returns the first index in the Collection where a value satisfies the provided predicate function. Otherwise -1 is returned.

 

```
findIndex(predicate: (value: T, index: number, iter: this) => boolean,context?: unknown): number

```

#### Inherited from


`[Collection.Indexed#findIndex()](../collection.indexed/index#findIndex())`



#### [findLastIndex()](index#findLastIndex())




Returns the last index in the Collection where a value satisfies the provided predicate function. Otherwise -1 is returned.

 

```
findLastIndex(predicate: (value: T, index: number, iter: this) => boolean,context?: unknown): number

```

#### Inherited from


`[Collection.Indexed#findLastIndex()](../collection.indexed/index#findLastIndex())`


### Comparison



#### [isSubset()](index#isSubset())




True if `iter` includes every value in this Collection.

 

```
isSubset(iter: Iterable<T>): boolean

```

#### Inherited from


`[Collection#isSubset()](../collection/index#isSubset())`



#### [isSuperset()](index#isSuperset())




True if this Collection includes every value in `iter`.

 

```
isSuperset(iter: Iterable<T>): boolean

```

#### Inherited from


`[Collection#isSuperset()](../collection/index#isSuperset())`

This documentation is generated from [immutable.d.ts](https://github.com/immutable-js/immutable-js/blob/main/type-definitions/immutable.d.ts). Pull requests and [Issues](https://github.com/immutable-js/immutable-js/issues) welcome.

 © 2014–present, Lee Byron and other contributors  
Licensed under the 3-clause BSD License.  

<https://immutable-js.com/docs/v4.2.1/Seq.Indexed/>

Collection
==========



The `[Collection](index)` 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](index#map())` and `[filter](index#filter())`).

 

```
type Collection<K, V> extends ValueObject
```

#### Discussion



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](../map/index)` and `[Set](../collection.set/index)`.

 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.keyed/index)`, `[Collection.Indexed](../collection.indexed/index)`, or `[Collection.Set](../collection.set/index)`.

 
### Construction



#### [Collection()](index#Collection())



```
Collection<I>(collection: I): I
Collection<T>(collection: Iterable<T> | ArrayLike<T>): Collection.Indexed<T>
Collection<V>(obj: {[key: string]: V}): Collection.Keyed<string, V>
Collection<K, V>(): Collection<K, V>

```


### Value equality



#### [equals()](index#equals())




True if this and the other Collection have value equality, as defined by `[Immutable.is()](../is()/index)`.

 

```
equals(other: unknown): boolean

```

#### Overrides


`[ValueObject#equals()](../valueobject/index#equals())`#### Discussion



Note: This is equivalent to `Immutable.is(this, other)`, but provided to allow for chained expressions.

 



#### [hashCode()](index#hashCode())




Computes and returns the hashed identity for this Collection.

 

```
hashCode(): number

```

#### Overrides


`[ValueObject#hashCode()](../valueobject/index#hashCode())`#### Discussion



The `[hashCode](../list/index#hashCode())` of a Collection is used to determine potential equality, and is used when adding this to a `[Set](../set/index)` or as a key in a `[Map](../map/index)`, enabling lookup via a different instance.

 
```
const a = List([ 1, 2, 3 ]);
const b = List([ 1, 2, 3 ]);
assert.notStrictEqual(a, b); // different instances
const set = Set([ a ]);
assert.equal(set.has(b), true);run it
```

If two values have the same `[hashCode](../list/index#hashCode())`, they are [not guaranteed to be equal](https://en.wikipedia.org/wiki/Collision_(computer_science)). If two values have different `[hashCode](../list/index#hashCode())`s, they must not be equal.

 


### Reading values



#### [get()](index#get())



```
get<NSV>(key: K, notSetValue: NSV): V | NSV
get(key: K): V | undefined

```



#### [has()](index#has())




True if a key exists within this `[Collection](index)`, using `[Immutable.is](../is()/index)` to determine equality

 

```
has(key: K): boolean

```




#### [includes()](index#includes())




True if a value exists within this `[Collection](index)`, using `[Immutable.is](../is()/index)` to determine equality

 

```
includes(value: V): boolean

```

#### alias


`contains()`



#### [first()](index#first())




In case the `[Collection](index)` is not empty returns the first element of the `[Collection](index)`. In case the `[Collection](index)` is empty returns the optional default value if provided, if no default value is provided returns undefined.

 

```
first<NSV>(notSetValue?: NSV): V | NSV

```




#### [last()](index#last())




In case the `[Collection](index)` is not empty returns the last element of the `[Collection](index)`. In case the `[Collection](index)` is empty returns the optional default value if provided, if no default value is provided returns undefined.

 

```
last<NSV>(notSetValue?: NSV): V | NSV

```



### Reading deep values



#### [getIn()](index#getIn())




Returns the value found by following a path of keys or indices through nested Collections.

 

```
getIn(searchKeyPath: Iterable<unknown>, notSetValue?: unknown): unknown

```

#### Discussion


 
```
const { Map, List } = require('immutable')
const deepData = Map({ x: List([ Map({ y: 123 }) ]) });
deepData.getIn(['x', 0, 'y']) // 123run it
```



Plain JavaScript Object or Arrays may be nested within an Immutable.js Collection, and getIn() can access those values as well:

 
```
const { Map, List } = require('immutable')
const deepData = Map({ x: [ { y: 123 } ] });
deepData.getIn(['x', 0, 'y']) // 123run it
```


 



#### [hasIn()](index#hasIn())




True if the result of following a path of keys or indices through nested Collections results in a set value.

 

```
hasIn(searchKeyPath: Iterable<unknown>): boolean

```



### Persistent changes



#### [update()](index#update())




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".

 

```
update<R>(updater: (value: this) => R): R

```

#### Discussion



For example, to sum a Seq after mapping and filtering:

 
```
const { Seq } = require('immutable')

function sum(collection) {
  return collection.reduce((sum, x) => sum + x, 0)
}
Seq([ 1, 2, 3 ])
  .map(x => x + 1)
  .filter(x => x % 2 === 0)
  .update(sum)
// 6run it
```
 


### Conversion to JavaScript types



#### [toJS()](index#toJS())




Deeply converts this Collection to equivalent native JavaScript Array or Object.

 

```
toJS(): Array<DeepCopy<V>> | {[key: string]: DeepCopy<V>}

```

#### Discussion



`[Collection.Indexed](../collection.indexed/index)`, and `[Collection.Set](../collection.set/index)` become `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)`, while `[Collection.Keyed](../collection.keyed/index)` become `[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)`, converting keys to Strings.

 



#### [toJSON()](index#toJSON())




Shallowly converts this Collection to equivalent native JavaScript Array or Object.

 

```
toJSON(): Array<V> | {[key: string]: V}

```

#### Discussion



`[Collection.Indexed](../collection.indexed/index)`, and `[Collection.Set](../collection.set/index)` become `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)`, while `[Collection.Keyed](../collection.keyed/index)` become `[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)`, converting keys to Strings.

 



#### [toArray()](index#toArray())




Shallowly converts this collection to an Array.

 

```
toArray(): Array<V> | Array<[K, V]>

```

#### Discussion



`[Collection.Indexed](../collection.indexed/index)`, and `[Collection.Set](../collection.set/index)` produce an Array of values. `[Collection.Keyed](../collection.keyed/index)` produce an Array of [key, value] tuples.

 



#### [toObject()](index#toObject())




Shallowly converts this Collection to an Object.

 

```
toObject(): {[key: string]: V}

```

#### Discussion



Converts keys to Strings.

 


### Conversion to Collections



#### [toMap()](index#toMap())




Converts this Collection to a Map, Throws if keys are not hashable.

 

```
toMap(): Map<K, V>

```

#### Discussion



Note: This is equivalent to `Map(this.toKeyedSeq())`, but provided for convenience and to allow for chained expressions.

 



#### [toOrderedMap()](index#toOrderedMap())




Converts this Collection to a Map, maintaining the order of iteration.

 

```
toOrderedMap(): OrderedMap<K, V>

```

#### Discussion



Note: This is equivalent to `OrderedMap(this.toKeyedSeq())`, but provided for convenience and to allow for chained expressions.

 



#### [toSet()](index#toSet())




Converts this Collection to a Set, discarding keys. Throws if values are not hashable.

 

```
toSet(): Set<V>

```

#### Discussion



Note: This is equivalent to `[Set(this)](../set/index)`, but provided to allow for chained expressions.

 



#### [toOrderedSet()](index#toOrderedSet())




Converts this Collection to a Set, maintaining the order of iteration and discarding keys.

 

```
toOrderedSet(): OrderedSet<V>

```

#### Discussion



Note: This is equivalent to `OrderedSet(this.valueSeq())`, but provided for convenience and to allow for chained expressions.

 



#### [toList()](index#toList())




Converts this Collection to a List, discarding keys.

 

```
toList(): List<V>

```

#### Discussion



This is similar to `[List(collection)](../list/index)`, but provided to allow for chained expressions. However, when called on `[Map](../map/index)` or other keyed collections, `collection.toList()` discards the keys and creates a list of only the values, whereas `[List(collection)](../list/index)` creates a list of entry tuples.

 
```
const { Map, List } = require('immutable')
var myMap = Map({ a: 'Apple', b: 'Banana' })
List(myMap) // List [ [ "a", "Apple" ], [ "b", "Banana" ] ]
myMap.toList() // List [ "Apple", "Banana" ]run it
```





#### [toStack()](index#toStack())




Converts this Collection to a Stack, discarding keys. Throws if values are not hashable.

 

```
toStack(): Stack<V>

```

#### Discussion



Note: This is equivalent to `[Stack(this)](../stack/index)`, but provided to allow for chained expressions.

 


### Conversion to Seq



#### [toSeq()](index#toSeq())




Converts this Collection to a Seq of the same kind (indexed, keyed, or set).

 

```
toSeq(): Seq<K, V>

```




#### [toKeyedSeq()](index#toKeyedSeq())




Returns a Seq.Keyed from this Collection where indices are treated as keys.

 

```
toKeyedSeq(): Seq.Keyed<K, V>

```

#### Discussion



This is useful if you want to operate on an Collection.Indexed and preserve the [index, value] pairs.

 The returned Seq will have identical iteration order as this Collection.

 
```
const { Seq } = require('immutable')
const indexedSeq = Seq([ 'A', 'B', 'C' ])
// Seq [ "A", "B", "C" ]
indexedSeq.filter(v => v === 'B')
// Seq [ "B" ]
const keyedSeq = indexedSeq.toKeyedSeq()
// Seq { 0: "A", 1: "B", 2: "C" }
keyedSeq.filter(v => v === 'B')
// Seq { 1: "B" }run it
```





#### [toIndexedSeq()](index#toIndexedSeq())




Returns an Seq.Indexed of the values of this Collection, discarding keys.

 

```
toIndexedSeq(): Seq.Indexed<V>

```




#### [toSetSeq()](index#toSetSeq())




Returns a Seq.Set of the values of this Collection, discarding keys.

 

```
toSetSeq(): Seq.Set<V>

```



### Iterators



#### [keys()](index#keys())




An iterator of this `[Collection](index)`'s keys.

 

```
keys(): IterableIterator<K>

```

#### Discussion



Note: this will return an ES6 iterator which does not support Immutable.js sequence algorithms. Use `[keySeq](../list/index#keySeq())` instead, if this is what you want.

 



#### [values()](index#values())




An iterator of this `[Collection](index)`'s values.

 

```
values(): IterableIterator<V>

```

#### Discussion



Note: this will return an ES6 iterator which does not support Immutable.js sequence algorithms. Use `[valueSeq](../list/index#valueSeq())` instead, if this is what you want.

 



#### [entries()](index#entries())




An iterator of this `[Collection](index)`'s entries as `[ key, value ]` tuples.

 

```
entries(): IterableIterator<[K, V]>

```

#### Discussion



Note: this will return an ES6 iterator which does not support Immutable.js sequence algorithms. Use `[entrySeq](../list/index#entrySeq())` instead, if this is what you want.

 



#### [[Symbol.iterator]()](index#%5BSymbol.iterator%5D())



```
[Symbol.iterator](): IterableIterator<unknown>

```


### Collections (Seq)



#### [keySeq()](index#keySeq())




Returns a new Seq.Indexed of the keys of this Collection, discarding values.

 

```
keySeq(): Seq.Indexed<K>

```




#### [valueSeq()](index#valueSeq())




Returns an Seq.Indexed of the values of this Collection, discarding keys.

 

```
valueSeq(): Seq.Indexed<V>

```




#### [entrySeq()](index#entrySeq())




Returns a new Seq.Indexed of [key, value] tuples.

 

```
entrySeq(): Seq.Indexed<[K, V]>

```



### Sequence algorithms



#### [map()](index#map())




Returns a new Collection of the same type with values passed through a `mapper` function.

 

```
map<M>(mapper: (value: V, key: K, iter: this) => M,context?: unknown): Collection<K, M>

```

#### Discussion


 
```
const { Collection } = require('immutable')
Collection({ a: 1, b: 2 }).map(x => 10 * x)
// Seq { "a": 10, "b": 20 }run it
```

Note: `[map()](index#map())` always returns a new instance, even if it produced the same value at every step.

 



#### [filter()](index#filter())



```
filter<F>(predicate: (value: V, key: K, iter: this) => boolean,context?: unknown): Collection<K, F>
filter(predicate: (value: V, key: K, iter: this) => unknown,context?: unknown): this

```



#### [filterNot()](index#filterNot())




Returns a new Collection of the same type with only the entries for which the `predicate` function returns false.

 

```
filterNot(predicate: (value: V, key: K, iter: this) => boolean,context?: unknown): this

```

#### Discussion


 
```
const { Map } = require('immutable')
Map({ a: 1, b: 2, c: 3, d: 4}).filterNot(x => x % 2 === 0)
// Map { "a": 1, "c": 3 }run it
```



Note: `[filterNot()](../list/index#filterNot())` always returns a new instance, even if it results in not filtering out any values.

 



#### [partition()](index#partition())



```
partition<F, C>(predicate: (this: C, value: V, key: K, iter: this) => boolean,context?: C): [Collection<K, V>, Collection<K, F>]
partition<C>(predicate: (this: C, value: V, key: K, iter: this) => unknown,context?: C): [this, this]

```



#### [reverse()](index#reverse())




Returns a new Collection of the same type in reverse order.

 

```
reverse(): this

```




#### [sort()](index#sort())




Returns a new Collection of the same type which includes the same entries, stably sorted by using a `comparator`.

 

```
sort(comparator?: (valueA: V, valueB: V) => number): this

```

#### Discussion



If a `comparator` is not provided, a default comparator uses `<` and `>`.

 `comparator(valueA, valueB)`:

 * Returns `0` if the elements should not be swapped.
* Returns `-1` (or any negative number) if `valueA` comes before `valueB`
* Returns `1` (or any positive number) if `valueA` comes after `valueB`
* Is pure, i.e. it must always return the same value for the same pair of values.

 When sorting collections which have no defined order, their ordered equivalents will be returned. e.g. `map.sort()` returns OrderedMap.

 
```
const { Map } = require('immutable')
Map({ "c": 3, "a": 1, "b": 2 }).sort((a, b) => {
  if (a < b) { return -1; }
  if (a > b) { return 1; }
  if (a === b) { return 0; }
});
// OrderedMap { "a": 1, "b": 2, "c": 3 }run it
```

Note: `[sort()](../list/index#sort())` Always returns a new instance, even if the original was already sorted.

 Note: This is always an eager operation.

 



#### [sortBy()](index#sortBy())




Like `[sort](../list/index#sort())`, but also accepts a `comparatorValueMapper` which allows for sorting by more sophisticated means:

 

```
sortBy<C>(comparatorValueMapper: (value: V, key: K, iter: this) => C,comparator?: (valueA: C, valueB: C) => number): this

```

#### Discussion


 
```
const { Map } = require('immutable')
const beattles = Map({
  John: { name: "Lennon" },
  Paul: { name: "McCartney" },
  George: { name: "Harrison" },
  Ringo: { name: "Starr" },
});
beattles.sortBy(member => member.name);run it
```



Note: `[sortBy()](../list/index#sortBy())` Always returns a new instance, even if the original was already sorted.

 Note: This is always an eager operation.

 



#### [groupBy()](index#groupBy())




Returns a `[Collection.Keyed](../collection.keyed/index)` of `Collection.Keyeds`, grouped by the return value of the `grouper` function.

 

```
groupBy<G>(grouper: (value: V, key: K, iter: this) => G,context?: unknown): Seq.Keyed<G, Collection<K, V>>

```

#### Discussion



Note: This is always an eager operation.

 
```
const { List, Map } = require('immutable')
const listOfMaps = List([
  Map({ v: 0 }),
  Map({ v: 1 }),
  Map({ v: 1 }),
  Map({ v: 0 }),
  Map({ v: 2 })
])
const groupsOfMaps = listOfMaps.groupBy(x => x.get('v'))
// Map {
//   0: List [ Map{ "v": 0 }, Map { "v": 0 } ],
//   1: List [ Map{ "v": 1 }, Map { "v": 1 } ],
//   2: List [ Map{ "v": 2 } ],
// }run it
```




### Side effects



#### [forEach()](index#forEach())




The `sideEffect` is executed for every entry in the Collection.

 

```
forEach(sideEffect: (value: V, key: K, iter: this) => unknown,context?: unknown): number

```

#### Discussion



Unlike `[Array#forEach](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/forEach)`, if any call of `sideEffect` returns `false`, the iteration will stop. Returns the number of entries iterated (including the last iteration which returned false).

 


### Creating subsets



#### [slice()](index#slice())




Returns a new Collection of the same type representing a portion of this Collection from start up to but not including end.

 

```
slice(begin?: number, end?: number): this

```

#### Discussion



If begin is negative, it is offset from the end of the Collection. e.g. `slice(-2)` returns a Collection of the last two entries. If it is not provided the new Collection will begin at the beginning of this Collection.

 If end is negative, it is offset from the end of the Collection. e.g. `slice(0, -1)` returns a Collection of everything but the last entry. If it is not provided, the new Collection will continue through the end of this Collection.

 If the requested slice is equivalent to the current Collection, then it will return itself.

 



#### [rest()](index#rest())




Returns a new Collection of the same type containing all entries except the first.

 

```
rest(): this

```




#### [butLast()](index#butLast())




Returns a new Collection of the same type containing all entries except the last.

 

```
butLast(): this

```




#### [skip()](index#skip())




Returns a new Collection of the same type which excludes the first `amount` entries from this Collection.

 

```
skip(amount: number): this

```




#### [skipLast()](index#skipLast())




Returns a new Collection of the same type which excludes the last `amount` entries from this Collection.

 

```
skipLast(amount: number): this

```




#### [skipWhile()](index#skipWhile())




Returns a new Collection of the same type which includes entries starting from when `predicate` first returns false.

 

```
skipWhile(predicate: (value: V, key: K, iter: this) => boolean,context?: unknown): this

```

#### Discussion


 
```
const { List } = require('immutable')
List([ 'dog', 'frog', 'cat', 'hat', 'god' ])
  .skipWhile(x => x.match(/g/))
// List [ "cat", "hat", "god" ]run it
```


 



#### [skipUntil()](index#skipUntil())




Returns a new Collection of the same type which includes entries starting from when `predicate` first returns true.

 

```
skipUntil(predicate: (value: V, key: K, iter: this) => boolean,context?: unknown): this

```

#### Discussion


 
```
const { List } = require('immutable')
List([ 'dog', 'frog', 'cat', 'hat', 'god' ])
  .skipUntil(x => x.match(/hat/))
// List [ "hat", "god" ]run it
```


 



#### [take()](index#take())




Returns a new Collection of the same type which includes the first `amount` entries from this Collection.

 

```
take(amount: number): this

```




#### [takeLast()](index#takeLast())




Returns a new Collection of the same type which includes the last `amount` entries from this Collection.

 

```
takeLast(amount: number): this

```




#### [takeWhile()](index#takeWhile())




Returns a new Collection of the same type which includes entries from this Collection as long as the `predicate` returns true.

 

```
takeWhile(predicate: (value: V, key: K, iter: this) => boolean,context?: unknown): this

```

#### Discussion


 
```
const { List } = require('immutable')
List([ 'dog', 'frog', 'cat', 'hat', 'god' ])
  .takeWhile(x => x.match(/o/))
// List [ "dog", "frog" ]run it
```


 



#### [takeUntil()](index#takeUntil())




Returns a new Collection of the same type which includes entries from this Collection as long as the `predicate` returns false.

 

```
takeUntil(predicate: (value: V, key: K, iter: this) => boolean,context?: unknown): this

```

#### Discussion


 
```
const { List } = require('immutable')
List([ 'dog', 'frog', 'cat', 'hat', 'god' ])
  .takeUntil(x => x.match(/at/))
// List [ "dog", "frog" ]run it
```


 


### Combination



#### [concat()](index#concat())




Returns a new Collection of the same type with other values and collection-like concatenated to this one.

 

```
concat(...valuesOrCollections: Array<unknown>): Collection<unknown, unknown>

```

#### Discussion



For Seqs, all entries will be present in the resulting Seq, even if they have the same key.

 



#### [flatten()](index#flatten())



```
flatten(depth?: number): Collection<unknown, unknown>
flatten(shallow?: boolean): Collection<unknown, unknown>

```



#### [flatMap()](index#flatMap())




Flat-maps the Collection, returning a Collection of the same type.

 

```
flatMap<M>(mapper: (value: V, key: K, iter: this) => Iterable<M>,context?: unknown): Collection<K, M>
flatMap<KM, VM>(mapper: (value: V, key: K, iter: this) => Iterable<[KM, VM]>,context?: unknown): Collection<KM, VM>

```

#### Discussion



Similar to `collection.map(...).flatten(true)`. Used for Dictionaries only.

 


### Reducing a value



#### [reduce()](index#reduce())



```
reduce<R>(reducer: (reduction: R, value: V, key: K, iter: this) => R,initialReduction: R,context?: unknown): R
reduce<R>(reducer: (reduction: V | R, value: V, key: K, iter: this) => R): R

```



#### [reduceRight()](index#reduceRight())



```
reduceRight<R>(reducer: (reduction: R, value: V, key: K, iter: this) => R,initialReduction: R,context?: unknown): R
reduceRight<R>(reducer: (reduction: V | R, value: V, key: K, iter: this) => R): R

```



#### [every()](index#every())




True if `predicate` returns true for all entries in the Collection.

 

```
every(predicate: (value: V, key: K, iter: this) => boolean,context?: unknown): boolean

```




#### [some()](index#some())




True if `predicate` returns true for any entry in the Collection.

 

```
some(predicate: (value: V, key: K, iter: this) => boolean,context?: unknown): boolean

```




#### [join()](index#join())




Joins values together as a string, inserting a separator between each. The default separator is `","`.

 

```
join(separator?: string): string

```




#### [isEmpty()](index#isEmpty())




Returns true if this Collection includes no values.

 

```
isEmpty(): boolean

```

#### Discussion



For some lazy `[Seq](../seq/index)`, `[isEmpty](../list/index#isEmpty())` might need to iterate to determine emptiness. At most one iteration will occur.

 



#### [count()](index#count())



```
count(): number
count(predicate: (value: V, key: K, iter: this) => boolean,context?: unknown): number

```



#### [countBy()](index#countBy())




Returns a `[Seq.Keyed](../seq.keyed/index)` of counts, grouped by the return value of the `grouper` function.

 

```
countBy<G>(grouper: (value: V, key: K, iter: this) => G,context?: unknown): Map<G, number>

```

#### Discussion



Note: This is not a lazy operation.

 


### Search for value



#### [find()](index#find())




Returns the first value for which the `predicate` returns true.

 

```
find(predicate: (value: V, key: K, iter: this) => boolean,context?: unknown,notSetValue?: V): V | undefined

```




#### [findLast()](index#findLast())




Returns the last value for which the `predicate` returns true.

 

```
findLast(predicate: (value: V, key: K, iter: this) => boolean,context?: unknown,notSetValue?: V): V | undefined

```

#### Discussion



Note: `predicate` will be called for each entry in reverse.

 



#### [findEntry()](index#findEntry())




Returns the first [key, value] entry for which the `predicate` returns true.

 

```
findEntry(predicate: (value: V, key: K, iter: this) => boolean,context?: unknown,notSetValue?: V): [K, V] | undefined

```




#### [findLastEntry()](index#findLastEntry())




Returns the last [key, value] entry for which the `predicate` returns true.

 

```
findLastEntry(predicate: (value: V, key: K, iter: this) => boolean,context?: unknown,notSetValue?: V): [K, V] | undefined

```

#### Discussion



Note: `predicate` will be called for each entry in reverse.

 



#### [findKey()](index#findKey())




Returns the key for which the `predicate` returns true.

 

```
findKey(predicate: (value: V, key: K, iter: this) => boolean,context?: unknown): K | undefined

```




#### [findLastKey()](index#findLastKey())




Returns the last key for which the `predicate` returns true.

 

```
findLastKey(predicate: (value: V, key: K, iter: this) => boolean,context?: unknown): K | undefined

```

#### Discussion



Note: `predicate` will be called for each entry in reverse.

 



#### [keyOf()](index#keyOf())




Returns the key associated with the search value, or undefined.

 

```
keyOf(searchValue: V): K | undefined

```




#### [lastKeyOf()](index#lastKeyOf())




Returns the last key associated with the search value, or undefined.

 

```
lastKeyOf(searchValue: V): K | undefined

```




#### [max()](index#max())




Returns the maximum value in this collection. If any values are comparatively equivalent, the first one found will be returned.

 

```
max(comparator?: (valueA: V, valueB: V) => number): V | undefined

```

#### Discussion



The `comparator` is used in the same way as `[Collection#sort](index#sort())`. If it is not provided, the default comparator is `>`.

 When two values are considered equivalent, the first encountered will be returned. Otherwise, `[max](../list/index#max())` will operate independent of the order of input as long as the comparator is commutative. The default comparator `>` is commutative *only* when types do not differ.

 If `comparator` returns 0 and either value is NaN, undefined, or null, that value will be returned.

 



#### [maxBy()](index#maxBy())




Like `[max](../list/index#max())`, but also accepts a `comparatorValueMapper` which allows for comparing by more sophisticated means:

 

```
maxBy<C>(comparatorValueMapper: (value: V, key: K, iter: this) => C,comparator?: (valueA: C, valueB: C) => number): V | undefined

```

#### Discussion


 
```
const { List, } = require('immutable');
const l = List([
  { name: 'Bob', avgHit: 1 },
  { name: 'Max', avgHit: 3 },
  { name: 'Lili', avgHit: 2 } ,
]);
l.maxBy(i => i.avgHit); // will output { name: 'Max', avgHit: 3 }run it
```


 



#### [min()](index#min())




Returns the minimum value in this collection. If any values are comparatively equivalent, the first one found will be returned.

 

```
min(comparator?: (valueA: V, valueB: V) => number): V | undefined

```

#### Discussion



The `comparator` is used in the same way as `[Collection#sort](index#sort())`. If it is not provided, the default comparator is `<`.

 When two values are considered equivalent, the first encountered will be returned. Otherwise, `[min](../list/index#min())` will operate independent of the order of input as long as the comparator is commutative. The default comparator `<` is commutative *only* when types do not differ.

 If `comparator` returns 0 and either value is NaN, undefined, or null, that value will be returned.

 



#### [minBy()](index#minBy())




Like `[min](../list/index#min())`, but also accepts a `comparatorValueMapper` which allows for comparing by more sophisticated means:

 

```
minBy<C>(comparatorValueMapper: (value: V, key: K, iter: this) => C,comparator?: (valueA: C, valueB: C) => number): V | undefined

```

#### Discussion


 
```
const { List, } = require('immutable');
const l = List([
  { name: 'Bob', avgHit: 1 },
  { name: 'Max', avgHit: 3 },
  { name: 'Lili', avgHit: 2 } ,
]);
l.minBy(i => i.avgHit); // will output { name: 'Bob', avgHit: 1 }run it
```


 


### Comparison



#### [isSubset()](index#isSubset())




True if `iter` includes every value in this Collection.

 

```
isSubset(iter: Iterable<V>): boolean

```




#### [isSuperset()](index#isSuperset())




True if this Collection includes every value in `iter`.

 

```
isSuperset(iter: Iterable<V>): boolean

```


This documentation is generated from [immutable.d.ts](https://github.com/immutable-js/immutable-js/blob/main/type-definitions/immutable.d.ts). Pull requests and [Issues](https://github.com/immutable-js/immutable-js/issues) welcome.

 © 2014–present, Lee Byron and other contributors  
Licensed under the 3-clause BSD License.  

<https://immutable-js.com/docs/v4.2.1/Collection/>

Collection.Keyed
================



Keyed Collections have discrete keys tied to each value.

 

```
type Collection.Keyed<K, V> extends Collection<K, V>
```

#### Discussion



When iterating `[Collection.Keyed](index)`, each iteration will yield a `[K, V]` tuple, in other words, `[Collection#entries](../collection/index#entries())` is the default iterator for Keyed Collections.

 
### Construction



#### [Collection.Keyed()](index#Collection.Keyed())



```
Collection.Keyed<K, V>(collection?: Iterable<[K, V]>): Collection.Keyed<K, V>
Collection.Keyed<V>(obj: {[key: string]: V}): Collection.Keyed<string, V>

```


### Conversion to JavaScript types



#### [toJS()](index#toJS())




Deeply converts this Keyed collection to equivalent native JavaScript Object.

 

```
toJS(): {[key: string]: DeepCopy<V>}

```

#### Overrides


`[Collection#toJS()](../collection/index#toJS())`#### Discussion



Converts keys to Strings.

 



#### [toJSON()](index#toJSON())




Shallowly converts this Keyed collection to equivalent native JavaScript Object.

 

```
toJSON(): {[key: string]: V}

```

#### Overrides


`[Collection#toJSON()](../collection/index#toJSON())`#### Discussion



Converts keys to Strings.

 



#### [toArray()](index#toArray())




Shallowly converts this collection to an Array.

 

```
toArray(): Array<[K, V]>

```

#### Overrides


`[Collection#toArray()](../collection/index#toArray())`



#### [toObject()](index#toObject())




Shallowly converts this Collection to an Object.

 

```
toObject(): {[key: string]: V}

```

#### Inherited from


`[Collection#toObject()](../collection/index#toObject())`#### Discussion



Converts keys to Strings.

 


### Conversion to Seq



#### [toSeq()](index#toSeq())




Returns Seq.Keyed.

 

```
toSeq(): Seq.Keyed<K, V>

```

#### Overrides


`[Collection#toSeq()](../collection/index#toSeq())`



#### [toKeyedSeq()](index#toKeyedSeq())




Returns a Seq.Keyed from this Collection where indices are treated as keys.

 

```
toKeyedSeq(): Seq.Keyed<K, V>

```

#### Inherited from


`[Collection#toKeyedSeq()](../collection/index#toKeyedSeq())`#### Discussion



This is useful if you want to operate on an Collection.Indexed and preserve the [index, value] pairs.

 The returned Seq will have identical iteration order as this Collection.

 
```
const { Seq } = require('immutable')
const indexedSeq = Seq([ 'A', 'B', 'C' ])
// Seq [ "A", "B", "C" ]
indexedSeq.filter(v => v === 'B')
// Seq [ "B" ]
const keyedSeq = indexedSeq.toKeyedSeq()
// Seq { 0: "A", 1: "B", 2: "C" }
keyedSeq.filter(v => v === 'B')
// Seq { 1: "B" }run it
```





#### [toIndexedSeq()](index#toIndexedSeq())




Returns an Seq.Indexed of the values of this Collection, discarding keys.

 

```
toIndexedSeq(): Seq.Indexed<V>

```

#### Inherited from


`[Collection#toIndexedSeq()](../collection/index#toIndexedSeq())`



#### [toSetSeq()](index#toSetSeq())




Returns a Seq.Set of the values of this Collection, discarding keys.

 

```
toSetSeq(): Seq.Set<V>

```

#### Inherited from


`[Collection#toSetSeq()](../collection/index#toSetSeq())`


### Sequence functions



#### [flip()](index#flip())




Returns a new Collection.Keyed of the same type where the keys and values have been flipped.

 

```
flip(): Collection.Keyed<V, K>

```

#### Discussion


 
```
const { Map } = require('immutable')
Map({ a: 'z', b: 'y' }).flip()
// Map { "z": "a", "y": "b" }run it
```





#### [concat()](index#concat())




```
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>

```

#### Overrides


`[Collection#concat()](../collection/index#concat())`



#### [map()](index#map())




Returns a new Collection.Keyed with values passed through a `mapper` function.

 

```
map<M>(mapper: (value: V, key: K, iter: this) => M,context?: unknown): Collection.Keyed<K, M>

```

#### Overrides


`[Collection#map()](../collection/index#map())`#### Example




```
const { Collection } = require('immutable')
Collection.Keyed({ a: 1, b: 2 }).map(x => 10 * x)
// Seq { "a": 10, "b": 20 }
```

Note: `[map()](index#map())` always returns a new instance, even if it produced the same value at every step.

 



#### [mapKeys()](index#mapKeys())




Returns a new Collection.Keyed of the same type with keys passed through a `mapper` function.

 

```
mapKeys<M>(mapper: (key: K, value: V, iter: this) => M,context?: unknown): Collection.Keyed<M, V>

```

#### Discussion


 
```
const { Map } = require('immutable')
Map({ a: 1, b: 2 }).mapKeys(x => x.toUpperCase())
// Map { "A": 1, "B": 2 }run it
```

Note: `[mapKeys()](index#mapKeys())` always returns a new instance, even if it produced the same key at every step.

 



#### [mapEntries()](index#mapEntries())




Returns a new Collection.Keyed of the same type with entries ([key, value] tuples) passed through a `mapper` function.

 

```
mapEntries<KM, VM>(mapper: (entry: [K, V], index: number, iter: this) => [KM, VM] | undefined,context?: unknown): Collection.Keyed<KM, VM>

```

#### Discussion


 
```
const { Map } = require('immutable')
Map({ a: 1, b: 2 })
  .mapEntries(([ k, v ]) => [ k.toUpperCase(), v * 2 ])
// Map { "A": 2, "B": 4 }run it
```

Note: `[mapEntries()](index#mapEntries())` always returns a new instance, even if it produced the same entry at every step.

 If the mapper function returns `undefined`, then the entry will be filtered

 



#### [flatMap()](index#flatMap())




Flat-maps the Collection, returning a Collection of the same type.

 

```
flatMap<KM, VM>(mapper: (value: V, key: K, iter: this) => Iterable<[KM, VM]>,context?: unknown): Collection.Keyed<KM, VM>

```

#### Overrides


`[Collection#flatMap()](../collection/index#flatMap())`#### Discussion



Similar to `collection.map(...).flatten(true)`.

 



#### [filter()](index#filter())




```
filter<F>(predicate: (value: V, key: K, iter: this) => boolean,context?: unknown): Collection.Keyed<K, F>
filter(predicate: (value: V, key: K, iter: this) => unknown,context?: unknown): this

```

#### Overrides


`[Collection#filter()](../collection/index#filter())`



#### [partition()](index#partition())




```
partition<F, C>(predicate: (this: C, value: V, key: K, iter: this) => boolean,context?: C): [Collection.Keyed<K, V>, Collection.Keyed<K, F>]
partition<C>(predicate: (this: C, value: V, key: K, iter: this) => unknown,context?: C): [this, this]

```

#### Overrides


`[Collection#partition()](../collection/index#partition())`



#### [[Symbol.iterator]()](index#%5BSymbol.iterator%5D())




```
[Symbol.iterator](): IterableIterator<[K, V]>

```

#### Overrides


`[Collection#[Symbol.iterator]()](../collection/index#%5BSymbol.iterator%5D())`


### Value equality



#### [equals()](index#equals())




True if this and the other Collection have value equality, as defined by `[Immutable.is()](../is()/index)`.

 

```
equals(other: unknown): boolean

```

#### Inherited from


`[Collection#equals()](../collection/index#equals())`#### Discussion



Note: This is equivalent to `Immutable.is(this, other)`, but provided to allow for chained expressions.

 



#### [hashCode()](index#hashCode())




Computes and returns the hashed identity for this Collection.

 

```
hashCode(): number

```

#### Inherited from


`[Collection#hashCode()](../collection/index#hashCode())`#### Discussion



The `[hashCode](../list/index#hashCode())` of a Collection is used to determine potential equality, and is used when adding this to a `[Set](../set/index)` or as a key in a `[Map](../map/index)`, enabling lookup via a different instance.

 
```
const a = List([ 1, 2, 3 ]);
const b = List([ 1, 2, 3 ]);
assert.notStrictEqual(a, b); // different instances
const set = Set([ a ]);
assert.equal(set.has(b), true);run it
```

If two values have the same `[hashCode](../list/index#hashCode())`, they are [not guaranteed to be equal](https://en.wikipedia.org/wiki/Collision_(computer_science)). If two values have different `[hashCode](../list/index#hashCode())`s, they must not be equal.

 


### Reading values



#### [get()](index#get())




```
get<NSV>(key: K, notSetValue: NSV): V | NSV
get(key: K): V | undefined

```

#### Inherited from


`[Collection#get()](../collection/index#get())`



#### [has()](index#has())




True if a key exists within this `[Collection](../collection/index)`, using `[Immutable.is](../is()/index)` to determine equality

 

```
has(key: K): boolean

```

#### Inherited from


`[Collection#has()](../collection/index#has())`



#### [includes()](index#includes())




True if a value exists within this `[Collection](../collection/index)`, using `[Immutable.is](../is()/index)` to determine equality

 

```
includes(value: V): boolean

```

#### Inherited from


`[Collection#includes()](../collection/index#includes())`#### alias


`contains()`



#### [first()](index#first())




In case the `[Collection](../collection/index)` is not empty returns the first element of the `[Collection](../collection/index)`. In case the `[Collection](../collection/index)` is empty returns the optional default value if provided, if no default value is provided returns undefined.

 

```
first<NSV>(notSetValue?: NSV): V | NSV

```

#### Inherited from


`[Collection#first()](../collection/index#first())`



#### [last()](index#last())




In case the `[Collection](../collection/index)` is not empty returns the last element of the `[Collection](../collection/index)`. In case the `[Collection](../collection/index)` is empty returns the optional default value if provided, if no default value is provided returns undefined.

 

```
last<NSV>(notSetValue?: NSV): V | NSV

```

#### Inherited from


`[Collection#last()](../collection/index#last())`


### Reading deep values



#### [getIn()](index#getIn())




Returns the value found by following a path of keys or indices through nested Collections.

 

```
getIn(searchKeyPath: Iterable<unknown>, notSetValue?: unknown): unknown

```

#### Inherited from


`[Collection#getIn()](../collection/index#getIn())`#### Discussion


 
```
const { Map, List } = require('immutable')
const deepData = Map({ x: List([ Map({ y: 123 }) ]) });
deepData.getIn(['x', 0, 'y']) // 123run it
```



Plain JavaScript Object or Arrays may be nested within an Immutable.js Collection, and getIn() can access those values as well:

 
```
const { Map, List } = require('immutable')
const deepData = Map({ x: [ { y: 123 } ] });
deepData.getIn(['x', 0, 'y']) // 123run it
```


 



#### [hasIn()](index#hasIn())




True if the result of following a path of keys or indices through nested Collections results in a set value.

 

```
hasIn(searchKeyPath: Iterable<unknown>): boolean

```

#### Inherited from


`[Collection#hasIn()](../collection/index#hasIn())`


### Persistent changes



#### [update()](index#update())




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".

 

```
update<R>(updater: (value: this) => R): R

```

#### Inherited from


`[Collection#update()](../collection/index#update())`#### Discussion



For example, to sum a Seq after mapping and filtering:

 
```
const { Seq } = require('immutable')

function sum(collection) {
  return collection.reduce((sum, x) => sum + x, 0)
}
Seq([ 1, 2, 3 ])
  .map(x => x + 1)
  .filter(x => x % 2 === 0)
  .update(sum)
// 6run it
```
 


### Conversion to Collections



#### [toMap()](index#toMap())




Converts this Collection to a Map, Throws if keys are not hashable.

 

```
toMap(): Map<K, V>

```

#### Inherited from


`[Collection#toMap()](../collection/index#toMap())`#### Discussion



Note: This is equivalent to `Map(this.toKeyedSeq())`, but provided for convenience and to allow for chained expressions.

 



#### [toOrderedMap()](index#toOrderedMap())




Converts this Collection to a Map, maintaining the order of iteration.

 

```
toOrderedMap(): OrderedMap<K, V>

```

#### Inherited from


`[Collection#toOrderedMap()](../collection/index#toOrderedMap())`#### Discussion



Note: This is equivalent to `OrderedMap(this.toKeyedSeq())`, but provided for convenience and to allow for chained expressions.

 



#### [toSet()](index#toSet())




Converts this Collection to a Set, discarding keys. Throws if values are not hashable.

 

```
toSet(): Set<V>

```

#### Inherited from


`[Collection#toSet()](../collection/index#toSet())`#### Discussion



Note: This is equivalent to `[Set(this)](../set/index)`, but provided to allow for chained expressions.

 



#### [toOrderedSet()](index#toOrderedSet())




Converts this Collection to a Set, maintaining the order of iteration and discarding keys.

 

```
toOrderedSet(): OrderedSet<V>

```

#### Inherited from


`[Collection#toOrderedSet()](../collection/index#toOrderedSet())`#### Discussion



Note: This is equivalent to `OrderedSet(this.valueSeq())`, but provided for convenience and to allow for chained expressions.

 



#### [toList()](index#toList())




Converts this Collection to a List, discarding keys.

 

```
toList(): List<V>

```

#### Inherited from


`[Collection#toList()](../collection/index#toList())`#### Discussion



This is similar to `[List(collection)](../list/index)`, but provided to allow for chained expressions. However, when called on `[Map](../map/index)` or other keyed collections, `collection.toList()` discards the keys and creates a list of only the values, whereas `[List(collection)](../list/index)` creates a list of entry tuples.

 
```
const { Map, List } = require('immutable')
var myMap = Map({ a: 'Apple', b: 'Banana' })
List(myMap) // List [ [ "a", "Apple" ], [ "b", "Banana" ] ]
myMap.toList() // List [ "Apple", "Banana" ]run it
```





#### [toStack()](index#toStack())




Converts this Collection to a Stack, discarding keys. Throws if values are not hashable.

 

```
toStack(): Stack<V>

```

#### Inherited from


`[Collection#toStack()](../collection/index#toStack())`#### Discussion



Note: This is equivalent to `[Stack(this)](../stack/index)`, but provided to allow for chained expressions.

 


### Iterators



#### [keys()](index#keys())




An iterator of this `[Collection](../collection/index)`'s keys.

 

```
keys(): IterableIterator<K>

```

#### Inherited from


`[Collection#keys()](../collection/index#keys())`#### Discussion



Note: this will return an ES6 iterator which does not support Immutable.js sequence algorithms. Use `[keySeq](../list/index#keySeq())` instead, if this is what you want.

 



#### [values()](index#values())




An iterator of this `[Collection](../collection/index)`'s values.

 

```
values(): IterableIterator<V>

```

#### Inherited from


`[Collection#values()](../collection/index#values())`#### Discussion



Note: this will return an ES6 iterator which does not support Immutable.js sequence algorithms. Use `[valueSeq](../list/index#valueSeq())` instead, if this is what you want.

 



#### [entries()](index#entries())




An iterator of this `[Collection](../collection/index)`'s entries as `[ key, value ]` tuples.

 

```
entries(): IterableIterator<[K, V]>

```

#### Inherited from


`[Collection#entries()](../collection/index#entries())`#### Discussion



Note: this will return an ES6 iterator which does not support Immutable.js sequence algorithms. Use `[entrySeq](../list/index#entrySeq())` instead, if this is what you want.

 


### Collections (Seq)



#### [keySeq()](index#keySeq())




Returns a new Seq.Indexed of the keys of this Collection, discarding values.

 

```
keySeq(): Seq.Indexed<K>

```

#### Inherited from


`[Collection#keySeq()](../collection/index#keySeq())`



#### [valueSeq()](index#valueSeq())




Returns an Seq.Indexed of the values of this Collection, discarding keys.

 

```
valueSeq(): Seq.Indexed<V>

```

#### Inherited from


`[Collection#valueSeq()](../collection/index#valueSeq())`



#### [entrySeq()](index#entrySeq())




Returns a new Seq.Indexed of [key, value] tuples.

 

```
entrySeq(): Seq.Indexed<[K, V]>

```

#### Inherited from


`[Collection#entrySeq()](../collection/index#entrySeq())`


### Sequence algorithms



#### [filterNot()](index#filterNot())




Returns a new Collection of the same type with only the entries for which the `predicate` function returns false.

 

```
filterNot(predicate: (value: V, key: K, iter: this) => boolean,context?: unknown): this

```

#### Inherited from


`[Collection#filterNot()](../collection/index#filterNot())`#### Discussion


 
```
const { Map } = require('immutable')
Map({ a: 1, b: 2, c: 3, d: 4}).filterNot(x => x % 2 === 0)
// Map { "a": 1, "c": 3 }run it
```



Note: `[filterNot()](../list/index#filterNot())` always returns a new instance, even if it results in not filtering out any values.

 



#### [reverse()](index#reverse())




Returns a new Collection of the same type in reverse order.

 

```
reverse(): this

```

#### Inherited from


`[Collection#reverse()](../collection/index#reverse())`



#### [sort()](index#sort())




Returns a new Collection of the same type which includes the same entries, stably sorted by using a `comparator`.

 

```
sort(comparator?: (valueA: V, valueB: V) => number): this

```

#### Inherited from


`[Collection#sort()](../collection/index#sort())`#### Discussion



If a `comparator` is not provided, a default comparator uses `<` and `>`.

 `comparator(valueA, valueB)`:

 * Returns `0` if the elements should not be swapped.
* Returns `-1` (or any negative number) if `valueA` comes before `valueB`
* Returns `1` (or any positive number) if `valueA` comes after `valueB`
* Is pure, i.e. it must always return the same value for the same pair of values.

 When sorting collections which have no defined order, their ordered equivalents will be returned. e.g. `map.sort()` returns OrderedMap.

 
```
const { Map } = require('immutable')
Map({ "c": 3, "a": 1, "b": 2 }).sort((a, b) => {
  if (a < b) { return -1; }
  if (a > b) { return 1; }
  if (a === b) { return 0; }
});
// OrderedMap { "a": 1, "b": 2, "c": 3 }run it
```

Note: `[sort()](../list/index#sort())` Always returns a new instance, even if the original was already sorted.

 Note: This is always an eager operation.

 



#### [sortBy()](index#sortBy())




Like `[sort](../list/index#sort())`, but also accepts a `comparatorValueMapper` which allows for sorting by more sophisticated means:

 

```
sortBy<C>(comparatorValueMapper: (value: V, key: K, iter: this) => C,comparator?: (valueA: C, valueB: C) => number): this

```

#### Inherited from


`[Collection#sortBy()](../collection/index#sortBy())`#### Discussion


 
```
const { Map } = require('immutable')
const beattles = Map({
  John: { name: "Lennon" },
  Paul: { name: "McCartney" },
  George: { name: "Harrison" },
  Ringo: { name: "Starr" },
});
beattles.sortBy(member => member.name);run it
```



Note: `[sortBy()](../list/index#sortBy())` Always returns a new instance, even if the original was already sorted.

 Note: This is always an eager operation.

 



#### [groupBy()](index#groupBy())




Returns a `[Collection.Keyed](index)` of `Collection.Keyeds`, grouped by the return value of the `grouper` function.

 

```
groupBy<G>(grouper: (value: V, key: K, iter: this) => G,context?: unknown): Seq.Keyed<G, Collection<K, V>>

```

#### Inherited from


`[Collection#groupBy()](../collection/index#groupBy())`#### Discussion



Note: This is always an eager operation.

 
```
const { List, Map } = require('immutable')
const listOfMaps = List([
  Map({ v: 0 }),
  Map({ v: 1 }),
  Map({ v: 1 }),
  Map({ v: 0 }),
  Map({ v: 2 })
])
const groupsOfMaps = listOfMaps.groupBy(x => x.get('v'))
// Map {
//   0: List [ Map{ "v": 0 }, Map { "v": 0 } ],
//   1: List [ Map{ "v": 1 }, Map { "v": 1 } ],
//   2: List [ Map{ "v": 2 } ],
// }run it
```




### Side effects



#### [forEach()](index#forEach())




The `sideEffect` is executed for every entry in the Collection.

 

```
forEach(sideEffect: (value: V, key: K, iter: this) => unknown,context?: unknown): number

```

#### Inherited from


`[Collection#forEach()](../collection/index#forEach())`#### Discussion



Unlike `[Array#forEach](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/forEach)`, if any call of `sideEffect` returns `false`, the iteration will stop. Returns the number of entries iterated (including the last iteration which returned false).

 


### Creating subsets



#### [slice()](index#slice())




Returns a new Collection of the same type representing a portion of this Collection from start up to but not including end.

 

```
slice(begin?: number, end?: number): this

```

#### Inherited from


`[Collection#slice()](../collection/index#slice())`#### Discussion



If begin is negative, it is offset from the end of the Collection. e.g. `slice(-2)` returns a Collection of the last two entries. If it is not provided the new Collection will begin at the beginning of this Collection.

 If end is negative, it is offset from the end of the Collection. e.g. `slice(0, -1)` returns a Collection of everything but the last entry. If it is not provided, the new Collection will continue through the end of this Collection.

 If the requested slice is equivalent to the current Collection, then it will return itself.

 



#### [rest()](index#rest())




Returns a new Collection of the same type containing all entries except the first.

 

```
rest(): this

```

#### Inherited from


`[Collection#rest()](../collection/index#rest())`



#### [butLast()](index#butLast())




Returns a new Collection of the same type containing all entries except the last.

 

```
butLast(): this

```

#### Inherited from


`[Collection#butLast()](../collection/index#butLast())`



#### [skip()](index#skip())




Returns a new Collection of the same type which excludes the first `amount` entries from this Collection.

 

```
skip(amount: number): this

```

#### Inherited from


`[Collection#skip()](../collection/index#skip())`



#### [skipLast()](index#skipLast())




Returns a new Collection of the same type which excludes the last `amount` entries from this Collection.

 

```
skipLast(amount: number): this

```

#### Inherited from


`[Collection#skipLast()](../collection/index#skipLast())`



#### [skipWhile()](index#skipWhile())




Returns a new Collection of the same type which includes entries starting from when `predicate` first returns false.

 

```
skipWhile(predicate: (value: V, key: K, iter: this) => boolean,context?: unknown): this

```

#### Inherited from


`[Collection#skipWhile()](../collection/index#skipWhile())`#### Discussion


 
```
const { List } = require('immutable')
List([ 'dog', 'frog', 'cat', 'hat', 'god' ])
  .skipWhile(x => x.match(/g/))
// List [ "cat", "hat", "god" ]run it
```


 



#### [skipUntil()](index#skipUntil())




Returns a new Collection of the same type which includes entries starting from when `predicate` first returns true.

 

```
skipUntil(predicate: (value: V, key: K, iter: this) => boolean,context?: unknown): this

```

#### Inherited from


`[Collection#skipUntil()](../collection/index#skipUntil())`#### Discussion


 
```
const { List } = require('immutable')
List([ 'dog', 'frog', 'cat', 'hat', 'god' ])
  .skipUntil(x => x.match(/hat/))
// List [ "hat", "god" ]run it
```


 



#### [take()](index#take())




Returns a new Collection of the same type which includes the first `amount` entries from this Collection.

 

```
take(amount: number): this

```

#### Inherited from


`[Collection#take()](../collection/index#take())`



#### [takeLast()](index#takeLast())




Returns a new Collection of the same type which includes the last `amount` entries from this Collection.

 

```
takeLast(amount: number): this

```

#### Inherited from


`[Collection#takeLast()](../collection/index#takeLast())`



#### [takeWhile()](index#takeWhile())




Returns a new Collection of the same type which includes entries from this Collection as long as the `predicate` returns true.

 

```
takeWhile(predicate: (value: V, key: K, iter: this) => boolean,context?: unknown): this

```

#### Inherited from


`[Collection#takeWhile()](../collection/index#takeWhile())`#### Discussion


 
```
const { List } = require('immutable')
List([ 'dog', 'frog', 'cat', 'hat', 'god' ])
  .takeWhile(x => x.match(/o/))
// List [ "dog", "frog" ]run it
```


 



#### [takeUntil()](index#takeUntil())




Returns a new Collection of the same type which includes entries from this Collection as long as the `predicate` returns false.

 

```
takeUntil(predicate: (value: V, key: K, iter: this) => boolean,context?: unknown): this

```

#### Inherited from


`[Collection#takeUntil()](../collection/index#takeUntil())`#### Discussion


 
```
const { List } = require('immutable')
List([ 'dog', 'frog', 'cat', 'hat', 'god' ])
  .takeUntil(x => x.match(/at/))
// List [ "dog", "frog" ]run it
```


 


### Combination



#### [flatten()](index#flatten())




```
flatten(depth?: number): Collection<unknown, unknown>
flatten(shallow?: boolean): Collection<unknown, unknown>

```

#### Inherited from


`[Collection#flatten()](../collection/index#flatten())`


### Reducing a value



#### [reduce()](index#reduce())




```
reduce<R>(reducer: (reduction: R, value: V, key: K, iter: this) => R,initialReduction: R,context?: unknown): R
reduce<R>(reducer: (reduction: V | R, value: V, key: K, iter: this) => R): R

```

#### Inherited from


`[Collection#reduce()](../collection/index#reduce())`



#### [reduceRight()](index#reduceRight())




```
reduceRight<R>(reducer: (reduction: R, value: V, key: K, iter: this) => R,initialReduction: R,context?: unknown): R
reduceRight<R>(reducer: (reduction: V | R, value: V, key: K, iter: this) => R): R

```

#### Inherited from


`[Collection#reduceRight()](../collection/index#reduceRight())`



#### [every()](index#every())




True if `predicate` returns true for all entries in the Collection.

 

```
every(predicate: (value: V, key: K, iter: this) => boolean,context?: unknown): boolean

```

#### Inherited from


`[Collection#every()](../collection/index#every())`



#### [some()](index#some())




True if `predicate` returns true for any entry in the Collection.

 

```
some(predicate: (value: V, key: K, iter: this) => boolean,context?: unknown): boolean

```

#### Inherited from


`[Collection#some()](../collection/index#some())`



#### [join()](index#join())




Joins values together as a string, inserting a separator between each. The default separator is `","`.

 

```
join(separator?: string): string

```

#### Inherited from


`[Collection#join()](../collection/index#join())`



#### [isEmpty()](index#isEmpty())




Returns true if this Collection includes no values.

 

```
isEmpty(): boolean

```

#### Inherited from


`[Collection#isEmpty()](../collection/index#isEmpty())`#### Discussion



For some lazy `[Seq](../seq/index)`, `[isEmpty](../list/index#isEmpty())` might need to iterate to determine emptiness. At most one iteration will occur.

 



#### [count()](index#count())




```
count(): number
count(predicate: (value: V, key: K, iter: this) => boolean,context?: unknown): number

```

#### Inherited from


`[Collection#count()](../collection/index#count())`



#### [countBy()](index#countBy())




Returns a `[Seq.Keyed](../seq.keyed/index)` of counts, grouped by the return value of the `grouper` function.

 

```
countBy<G>(grouper: (value: V, key: K, iter: this) => G,context?: unknown): Map<G, number>

```

#### Inherited from


`[Collection#countBy()](../collection/index#countBy())`#### Discussion



Note: This is not a lazy operation.

 


### Search for value



#### [find()](index#find())




Returns the first value for which the `predicate` returns true.

 

```
find(predicate: (value: V, key: K, iter: this) => boolean,context?: unknown,notSetValue?: V): V | undefined

```

#### Inherited from


`[Collection#find()](../collection/index#find())`



#### [findLast()](index#findLast())




Returns the last value for which the `predicate` returns true.

 

```
findLast(predicate: (value: V, key: K, iter: this) => boolean,context?: unknown,notSetValue?: V): V | undefined

```

#### Inherited from


`[Collection#findLast()](../collection/index#findLast())`#### Discussion



Note: `predicate` will be called for each entry in reverse.

 



#### [findEntry()](index#findEntry())




Returns the first [key, value] entry for which the `predicate` returns true.

 

```
findEntry(predicate: (value: V, key: K, iter: this) => boolean,context?: unknown,notSetValue?: V): [K, V] | undefined

```

#### Inherited from


`[Collection#findEntry()](../collection/index#findEntry())`



#### [findLastEntry()](index#findLastEntry())




Returns the last [key, value] entry for which the `predicate` returns true.

 

```
findLastEntry(predicate: (value: V, key: K, iter: this) => boolean,context?: unknown,notSetValue?: V): [K, V] | undefined

```

#### Inherited from


`[Collection#findLastEntry()](../collection/index#findLastEntry())`#### Discussion



Note: `predicate` will be called for each entry in reverse.

 



#### [findKey()](index#findKey())




Returns the key for which the `predicate` returns true.

 

```
findKey(predicate: (value: V, key: K, iter: this) => boolean,context?: unknown): K | undefined

```

#### Inherited from


`[Collection#findKey()](../collection/index#findKey())`



#### [findLastKey()](index#findLastKey())




Returns the last key for which the `predicate` returns true.

 

```
findLastKey(predicate: (value: V, key: K, iter: this) => boolean,context?: unknown): K | undefined

```

#### Inherited from


`[Collection#findLastKey()](../collection/index#findLastKey())`#### Discussion



Note: `predicate` will be called for each entry in reverse.

 



#### [keyOf()](index#keyOf())




Returns the key associated with the search value, or undefined.

 

```
keyOf(searchValue: V): K | undefined

```

#### Inherited from


`[Collection#keyOf()](../collection/index#keyOf())`



#### [lastKeyOf()](index#lastKeyOf())




Returns the last key associated with the search value, or undefined.

 

```
lastKeyOf(searchValue: V): K | undefined

```

#### Inherited from


`[Collection#lastKeyOf()](../collection/index#lastKeyOf())`



#### [max()](index#max())




Returns the maximum value in this collection. If any values are comparatively equivalent, the first one found will be returned.

 

```
max(comparator?: (valueA: V, valueB: V) => number): V | undefined

```

#### Inherited from


`[Collection#max()](../collection/index#max())`#### Discussion



The `comparator` is used in the same way as `[Collection#sort](../collection/index#sort())`. If it is not provided, the default comparator is `>`.

 When two values are considered equivalent, the first encountered will be returned. Otherwise, `[max](../list/index#max())` will operate independent of the order of input as long as the comparator is commutative. The default comparator `>` is commutative *only* when types do not differ.

 If `comparator` returns 0 and either value is NaN, undefined, or null, that value will be returned.

 



#### [maxBy()](index#maxBy())




Like `[max](../list/index#max())`, but also accepts a `comparatorValueMapper` which allows for comparing by more sophisticated means:

 

```
maxBy<C>(comparatorValueMapper: (value: V, key: K, iter: this) => C,comparator?: (valueA: C, valueB: C) => number): V | undefined

```

#### Inherited from


`[Collection#maxBy()](../collection/index#maxBy())`#### Discussion


 
```
const { List, } = require('immutable');
const l = List([
  { name: 'Bob', avgHit: 1 },
  { name: 'Max', avgHit: 3 },
  { name: 'Lili', avgHit: 2 } ,
]);
l.maxBy(i => i.avgHit); // will output { name: 'Max', avgHit: 3 }run it
```


 



#### [min()](index#min())




Returns the minimum value in this collection. If any values are comparatively equivalent, the first one found will be returned.

 

```
min(comparator?: (valueA: V, valueB: V) => number): V | undefined

```

#### Inherited from


`[Collection#min()](../collection/index#min())`#### Discussion



The `comparator` is used in the same way as `[Collection#sort](../collection/index#sort())`. If it is not provided, the default comparator is `<`.

 When two values are considered equivalent, the first encountered will be returned. Otherwise, `[min](../list/index#min())` will operate independent of the order of input as long as the comparator is commutative. The default comparator `<` is commutative *only* when types do not differ.

 If `comparator` returns 0 and either value is NaN, undefined, or null, that value will be returned.

 



#### [minBy()](index#minBy())




Like `[min](../list/index#min())`, but also accepts a `comparatorValueMapper` which allows for comparing by more sophisticated means:

 

```
minBy<C>(comparatorValueMapper: (value: V, key: K, iter: this) => C,comparator?: (valueA: C, valueB: C) => number): V | undefined

```

#### Inherited from


`[Collection#minBy()](../collection/index#minBy())`#### Discussion


 
```
const { List, } = require('immutable');
const l = List([
  { name: 'Bob', avgHit: 1 },
  { name: 'Max', avgHit: 3 },
  { name: 'Lili', avgHit: 2 } ,
]);
l.minBy(i => i.avgHit); // will output { name: 'Bob', avgHit: 1 }run it
```


 


### Comparison



#### [isSubset()](index#isSubset())




True if `iter` includes every value in this Collection.

 

```
isSubset(iter: Iterable<V>): boolean

```

#### Inherited from


`[Collection#isSubset()](../collection/index#isSubset())`



#### [isSuperset()](index#isSuperset())




True if this Collection includes every value in `iter`.

 

```
isSuperset(iter: Iterable<V>): boolean

```

#### Inherited from


`[Collection#isSuperset()](../collection/index#isSuperset())`

This documentation is generated from [immutable.d.ts](https://github.com/immutable-js/immutable-js/blob/main/type-definitions/immutable.d.ts). Pull requests and [Issues](https://github.com/immutable-js/immutable-js/issues) welcome.

 © 2014–present, Lee Byron and other contributors  
Licensed under the 3-clause BSD License.  

<https://immutable-js.com/docs/v4.2.1/Collection.Keyed/>

Collection.Indexed
==================



Indexed Collections have incrementing numeric keys. They exhibit slightly different behavior than `[Collection.Keyed](../collection.keyed/index)` for some methods in order to better mirror the behavior of JavaScript's `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)`, and add methods which do not make sense on non-indexed Collections such as `[indexOf](index#indexOf())`.

 

```
type Collection.Indexed<T> extends Collection<number, T>
```

#### Discussion



Unlike JavaScript arrays, `[Collection.Indexed](index)`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](index#toKeyedSeq())`.

 
### Construction



#### [Collection.Indexed()](index#Collection.Indexed())




Creates a new Collection.Indexed.

 

```
Collection.Indexed<T>(collection?: Iterable<T> | ArrayLike<T>): Collection.Indexed<T>

```

#### Discussion



Note: `[Collection.Indexed](index)` is a conversion function and not a class, and does not use the `new` keyword during construction.

 


### Conversion to JavaScript types



#### [toJS()](index#toJS())




Deeply converts this Indexed collection to equivalent native JavaScript Array.

 

```
toJS(): Array<DeepCopy<T>>

```

#### Overrides


`[Collection#toJS()](../collection/index#toJS())`



#### [toJSON()](index#toJSON())




Shallowly converts this Indexed collection to equivalent native JavaScript Array.

 

```
toJSON(): Array<T>

```

#### Overrides


`[Collection#toJSON()](../collection/index#toJSON())`



#### [toArray()](index#toArray())




Shallowly converts this collection to an Array.

 

```
toArray(): Array<T>

```

#### Overrides


`[Collection#toArray()](../collection/index#toArray())`



#### [toObject()](index#toObject())




Shallowly converts this Collection to an Object.

 

```
toObject(): {[key: string]: T}

```

#### Inherited from


`[Collection#toObject()](../collection/index#toObject())`#### Discussion



Converts keys to Strings.

 


### Reading values



#### [get()](index#get())




```
get<NSV>(index: number, notSetValue: NSV): T | NSV
get(index: number): T | undefined

```

#### Overrides


`[Collection#get()](../collection/index#get())`



#### [has()](index#has())




True if a key exists within this `[Collection](../collection/index)`, using `[Immutable.is](../is()/index)` to determine equality

 

```
has(key: number): boolean

```

#### Inherited from


`[Collection#has()](../collection/index#has())`



#### [includes()](index#includes())




True if a value exists within this `[Collection](../collection/index)`, using `[Immutable.is](../is()/index)` to determine equality

 

```
includes(value: T): boolean

```

#### Inherited from


`[Collection#includes()](../collection/index#includes())`#### alias


`contains()`



#### [first()](index#first())




In case the `[Collection](../collection/index)` is not empty returns the first element of the `[Collection](../collection/index)`. In case the `[Collection](../collection/index)` is empty returns the optional default value if provided, if no default value is provided returns undefined.

 

```
first<NSV>(notSetValue?: NSV): T | NSV

```

#### Inherited from


`[Collection#first()](../collection/index#first())`



#### [last()](index#last())




In case the `[Collection](../collection/index)` is not empty returns the last element of the `[Collection](../collection/index)`. In case the `[Collection](../collection/index)` is empty returns the optional default value if provided, if no default value is provided returns undefined.

 

```
last<NSV>(notSetValue?: NSV): T | NSV

```

#### Inherited from


`[Collection#last()](../collection/index#last())`


### Conversion to Seq



#### [toSeq()](index#toSeq())




Returns Seq.Indexed.

 

```
toSeq(): Seq.Indexed<T>

```

#### Overrides


`[Collection#toSeq()](../collection/index#toSeq())`



#### [fromEntrySeq()](index#fromEntrySeq())




If this is a collection of [key, value] entry tuples, it will return a Seq.Keyed of those entries.

 

```
fromEntrySeq(): Seq.Keyed<unknown, unknown>

```




#### [toKeyedSeq()](index#toKeyedSeq())




Returns a Seq.Keyed from this Collection where indices are treated as keys.

 

```
toKeyedSeq(): Seq.Keyed<number, T>

```

#### Inherited from


`[Collection#toKeyedSeq()](../collection/index#toKeyedSeq())`#### Discussion



This is useful if you want to operate on an Collection.Indexed and preserve the [index, value] pairs.

 The returned Seq will have identical iteration order as this Collection.

 
```
const { Seq } = require('immutable')
const indexedSeq = Seq([ 'A', 'B', 'C' ])
// Seq [ "A", "B", "C" ]
indexedSeq.filter(v => v === 'B')
// Seq [ "B" ]
const keyedSeq = indexedSeq.toKeyedSeq()
// Seq { 0: "A", 1: "B", 2: "C" }
keyedSeq.filter(v => v === 'B')
// Seq { 1: "B" }run it
```





#### [toIndexedSeq()](index#toIndexedSeq())




Returns an Seq.Indexed of the values of this Collection, discarding keys.

 

```
toIndexedSeq(): Seq.Indexed<T>

```

#### Inherited from


`[Collection#toIndexedSeq()](../collection/index#toIndexedSeq())`



#### [toSetSeq()](index#toSetSeq())




Returns a Seq.Set of the values of this Collection, discarding keys.

 

```
toSetSeq(): Seq.Set<T>

```

#### Inherited from


`[Collection#toSetSeq()](../collection/index#toSetSeq())`


### Combination



#### [interpose()](index#interpose())




Returns a Collection of the same type with `separator` between each item in this Collection.

 

```
interpose(separator: T): this

```




#### [interleave()](index#interleave())




Returns a Collection of the same type with the provided `collections` interleaved into this collection.

 

```
interleave(...collections: Array<Collection<unknown, T>>): this

```

#### Discussion



The resulting Collection includes the first item from each, then the second from each, etc.

 
```
const { List } = require('immutable')
List([ 1, 2, 3 ]).interleave(List([ 'A', 'B', 'C' ]))
// List [ 1, "A", 2, "B", 3, "C" ]run it
```

The shortest Collection stops interleave.

 
```
List([ 1, 2, 3 ]).interleave(
  List([ 'A', 'B' ]),
  List([ 'X', 'Y', 'Z' ])
)
// List [ 1, "A", "X", 2, "B", "Y" ]run it
```

Since `[interleave()](../list/index#interleave())` re-indexes values, it produces a complete copy, which has `O(N)` complexity.

 Note: `[interleave](../list/index#interleave())` *cannot* be used in `[withMutations](../list/index#withMutations())`.

 



#### [splice()](index#splice())




Splice returns a new indexed Collection by replacing a region of this Collection with new values. If values are not provided, it only skips the region to be removed.

 

```
splice(index: number, removeNum: number, ...values: Array<T>): this

```

#### Discussion



`index` may be a negative number, which indexes back from the end of the Collection. `s.splice(-2)` splices after the second to last item.

 
```
const { List } = require('immutable')
List([ 'a', 'b', 'c', 'd' ]).splice(1, 2, 'q', 'r', 's')
// List [ "a", "q", "r", "s", "d" ]run it
```

Since `[splice()](../list/index#splice())` re-indexes values, it produces a complete copy, which has `O(N)` complexity.

 Note: `[splice](../list/index#splice())` *cannot* be used in `[withMutations](../list/index#withMutations())`.

 



#### [zip()](index#zip())



```
zip<U>(other: Collection<unknown, U>): Collection.Indexed<[T, U]>
zip<U, V>(other: Collection<unknown, U>,other2: Collection<unknown, V>): Collection.Indexed<[T, U, V]>
zip(...collections: Array<Collection<unknown, unknown>>): Collection.Indexed<unknown>

```



#### [zipAll()](index#zipAll())



```
zipAll<U>(other: Collection<unknown, U>): Collection.Indexed<[T, U]>
zipAll<U, V>(other: Collection<unknown, U>,other2: Collection<unknown, V>): Collection.Indexed<[T, U, V]>
zipAll(...collections: Array<Collection<unknown, unknown>>): Collection.Indexed<unknown>

```



#### [zipWith()](index#zipWith())



```
zipWith<U, Z>(zipper: (value: T, otherValue: U) => Z,otherCollection: Collection<unknown, U>): Collection.Indexed<Z>
zipWith<U, V, Z>(zipper: (value: T, otherValue: U, thirdValue: V) => Z,otherCollection: Collection<unknown, U>,thirdCollection: Collection<unknown, V>): Collection.Indexed<Z>
zipWith<Z>(zipper: (...values: Array<unknown>) => Z,...collections: Array<Collection<unknown, unknown>>): Collection.Indexed<Z>

```



#### [flatten()](index#flatten())




```
flatten(depth?: number): Collection<unknown, unknown>
flatten(shallow?: boolean): Collection<unknown, unknown>

```

#### Inherited from


`[Collection#flatten()](../collection/index#flatten())`


### Search for value



#### [indexOf()](index#indexOf())




Returns the first index at which a given value can be found in the Collection, or -1 if it is not present.

 

```
indexOf(searchValue: T): number

```




#### [lastIndexOf()](index#lastIndexOf())




Returns the last index at which a given value can be found in the Collection, or -1 if it is not present.

 

```
lastIndexOf(searchValue: T): number

```




#### [findIndex()](index#findIndex())




Returns the first index in the Collection where a value satisfies the provided predicate function. Otherwise -1 is returned.

 

```
findIndex(predicate: (value: T, index: number, iter: this) => boolean,context?: unknown): number

```




#### [findLastIndex()](index#findLastIndex())




Returns the last index in the Collection where a value satisfies the provided predicate function. Otherwise -1 is returned.

 

```
findLastIndex(predicate: (value: T, index: number, iter: this) => boolean,context?: unknown): number

```




#### [find()](index#find())




Returns the first value for which the `predicate` returns true.

 

```
find(predicate: (value: T, key: number, iter: this) => boolean,context?: unknown,notSetValue?: T): T | undefined

```

#### Inherited from


`[Collection#find()](../collection/index#find())`



#### [findLast()](index#findLast())




Returns the last value for which the `predicate` returns true.

 

```
findLast(predicate: (value: T, key: number, iter: this) => boolean,context?: unknown,notSetValue?: T): T | undefined

```

#### Inherited from


`[Collection#findLast()](../collection/index#findLast())`#### Discussion



Note: `predicate` will be called for each entry in reverse.

 



#### [findEntry()](index#findEntry())




Returns the first [key, value] entry for which the `predicate` returns true.

 

```
findEntry(predicate: (value: T, key: number, iter: this) => boolean,context?: unknown,notSetValue?: T): [number, T] | undefined

```

#### Inherited from


`[Collection#findEntry()](../collection/index#findEntry())`



#### [findLastEntry()](index#findLastEntry())




Returns the last [key, value] entry for which the `predicate` returns true.

 

```
findLastEntry(predicate: (value: T, key: number, iter: this) => boolean,context?: unknown,notSetValue?: T): [number, T] | undefined

```

#### Inherited from


`[Collection#findLastEntry()](../collection/index#findLastEntry())`#### Discussion



Note: `predicate` will be called for each entry in reverse.

 



#### [findKey()](index#findKey())




Returns the key for which the `predicate` returns true.

 

```
findKey(predicate: (value: T, key: number, iter: this) => boolean,context?: unknown): number | undefined

```

#### Inherited from


`[Collection#findKey()](../collection/index#findKey())`



#### [findLastKey()](index#findLastKey())




Returns the last key for which the `predicate` returns true.

 

```
findLastKey(predicate: (value: T, key: number, iter: this) => boolean,context?: unknown): number | undefined

```

#### Inherited from


`[Collection#findLastKey()](../collection/index#findLastKey())`#### Discussion



Note: `predicate` will be called for each entry in reverse.

 



#### [keyOf()](index#keyOf())




Returns the key associated with the search value, or undefined.

 

```
keyOf(searchValue: T): number | undefined

```

#### Inherited from


`[Collection#keyOf()](../collection/index#keyOf())`



#### [lastKeyOf()](index#lastKeyOf())




Returns the last key associated with the search value, or undefined.

 

```
lastKeyOf(searchValue: T): number | undefined

```

#### Inherited from


`[Collection#lastKeyOf()](../collection/index#lastKeyOf())`



#### [max()](index#max())




Returns the maximum value in this collection. If any values are comparatively equivalent, the first one found will be returned.

 

```
max(comparator?: (valueA: T, valueB: T) => number): T | undefined

```

#### Inherited from


`[Collection#max()](../collection/index#max())`#### Discussion



The `comparator` is used in the same way as `[Collection#sort](../collection/index#sort())`. If it is not provided, the default comparator is `>`.

 When two values are considered equivalent, the first encountered will be returned. Otherwise, `[max](../list/index#max())` will operate independent of the order of input as long as the comparator is commutative. The default comparator `>` is commutative *only* when types do not differ.

 If `comparator` returns 0 and either value is NaN, undefined, or null, that value will be returned.

 



#### [maxBy()](index#maxBy())




Like `[max](../list/index#max())`, but also accepts a `comparatorValueMapper` which allows for comparing by more sophisticated means:

 

```
maxBy<C>(comparatorValueMapper: (value: T, key: number, iter: this) => C,comparator?: (valueA: C, valueB: C) => number): T | undefined

```

#### Inherited from


`[Collection#maxBy()](../collection/index#maxBy())`#### Discussion


 
```
const { List, } = require('immutable');
const l = List([
  { name: 'Bob', avgHit: 1 },
  { name: 'Max', avgHit: 3 },
  { name: 'Lili', avgHit: 2 } ,
]);
l.maxBy(i => i.avgHit); // will output { name: 'Max', avgHit: 3 }run it
```


 



#### [min()](index#min())




Returns the minimum value in this collection. If any values are comparatively equivalent, the first one found will be returned.

 

```
min(comparator?: (valueA: T, valueB: T) => number): T | undefined

```

#### Inherited from


`[Collection#min()](../collection/index#min())`#### Discussion



The `comparator` is used in the same way as `[Collection#sort](../collection/index#sort())`. If it is not provided, the default comparator is `<`.

 When two values are considered equivalent, the first encountered will be returned. Otherwise, `[min](../list/index#min())` will operate independent of the order of input as long as the comparator is commutative. The default comparator `<` is commutative *only* when types do not differ.

 If `comparator` returns 0 and either value is NaN, undefined, or null, that value will be returned.

 



#### [minBy()](index#minBy())




Like `[min](../list/index#min())`, but also accepts a `comparatorValueMapper` which allows for comparing by more sophisticated means:

 

```
minBy<C>(comparatorValueMapper: (value: T, key: number, iter: this) => C,comparator?: (valueA: C, valueB: C) => number): T | undefined

```

#### Inherited from


`[Collection#minBy()](../collection/index#minBy())`#### Discussion


 
```
const { List, } = require('immutable');
const l = List([
  { name: 'Bob', avgHit: 1 },
  { name: 'Max', avgHit: 3 },
  { name: 'Lili', avgHit: 2 } ,
]);
l.minBy(i => i.avgHit); // will output { name: 'Bob', avgHit: 1 }run it
```


 


### Sequence algorithms



#### [concat()](index#concat())




Returns a new Collection with other collections concatenated to this one.

 

```
concat<C>(...valuesOrCollections: Array<Iterable<C> | C>): Collection.Indexed<T | C>

```

#### Overrides


`[Collection#concat()](../collection/index#concat())`



#### [map()](index#map())




Returns a new Collection.Indexed with values passed through a `mapper` function.

 

```
map<M>(mapper: (value: T, key: number, iter: this) => M,context?: unknown): Collection.Indexed<M>

```

#### Overrides


`[Collection#map()](../collection/index#map())`#### Example




```
const { Collection } = require('immutable')
Collection.Indexed([1,2]).map(x => 10 * x)
// Seq [ 1, 2 ]
```

Note: `[map()](index#map())` always returns a new instance, even if it produced the same value at every step.

 



#### [flatMap()](index#flatMap())




Flat-maps the Collection, returning a Collection of the same type.

 

```
flatMap<M>(mapper: (value: T, key: number, iter: this) => Iterable<M>,context?: unknown): Collection.Indexed<M>

```

#### Overrides


`[Collection#flatMap()](../collection/index#flatMap())`#### Discussion



Similar to `collection.map(...).flatten(true)`.

 



#### [filter()](index#filter())




```
filter<F>(predicate: (value: T, index: number, iter: this) => boolean,context?: unknown): Collection.Indexed<F>
filter(predicate: (value: T, index: number, iter: this) => unknown,context?: unknown): this

```

#### Overrides


`[Collection#filter()](../collection/index#filter())`



#### [partition()](index#partition())




```
partition<F, C>(predicate: (this: C, value: T, index: number, iter: this) => boolean,context?: C): [Collection.Indexed<T>, Collection.Indexed<F>]
partition<C>(predicate: (this: C, value: T, index: number, iter: this) => unknown,context?: C): [this, this]

```

#### Overrides


`[Collection#partition()](../collection/index#partition())`



#### [[Symbol.iterator]()](index#%5BSymbol.iterator%5D())




```
[Symbol.iterator](): IterableIterator<T>

```

#### Overrides


`[Collection#[Symbol.iterator]()](../collection/index#%5BSymbol.iterator%5D())`



#### [filterNot()](index#filterNot())




Returns a new Collection of the same type with only the entries for which the `predicate` function returns false.

 

```
filterNot(predicate: (value: T, key: number, iter: this) => boolean,context?: unknown): this

```

#### Inherited from


`[Collection#filterNot()](../collection/index#filterNot())`#### Discussion


 
```
const { Map } = require('immutable')
Map({ a: 1, b: 2, c: 3, d: 4}).filterNot(x => x % 2 === 0)
// Map { "a": 1, "c": 3 }run it
```



Note: `[filterNot()](../list/index#filterNot())` always returns a new instance, even if it results in not filtering out any values.

 



#### [reverse()](index#reverse())




Returns a new Collection of the same type in reverse order.

 

```
reverse(): this

```

#### Inherited from


`[Collection#reverse()](../collection/index#reverse())`



#### [sort()](index#sort())




Returns a new Collection of the same type which includes the same entries, stably sorted by using a `comparator`.

 

```
sort(comparator?: (valueA: T, valueB: T) => number): this

```

#### Inherited from


`[Collection#sort()](../collection/index#sort())`#### Discussion



If a `comparator` is not provided, a default comparator uses `<` and `>`.

 `comparator(valueA, valueB)`:

 * Returns `0` if the elements should not be swapped.
* Returns `-1` (or any negative number) if `valueA` comes before `valueB`
* Returns `1` (or any positive number) if `valueA` comes after `valueB`
* Is pure, i.e. it must always return the same value for the same pair of values.

 When sorting collections which have no defined order, their ordered equivalents will be returned. e.g. `map.sort()` returns OrderedMap.

 
```
const { Map } = require('immutable')
Map({ "c": 3, "a": 1, "b": 2 }).sort((a, b) => {
  if (a < b) { return -1; }
  if (a > b) { return 1; }
  if (a === b) { return 0; }
});
// OrderedMap { "a": 1, "b": 2, "c": 3 }run it
```

Note: `[sort()](../list/index#sort())` Always returns a new instance, even if the original was already sorted.

 Note: This is always an eager operation.

 



#### [sortBy()](index#sortBy())




Like `[sort](../list/index#sort())`, but also accepts a `comparatorValueMapper` which allows for sorting by more sophisticated means:

 

```
sortBy<C>(comparatorValueMapper: (value: T, key: number, iter: this) => C,comparator?: (valueA: C, valueB: C) => number): this

```

#### Inherited from


`[Collection#sortBy()](../collection/index#sortBy())`#### Discussion


 
```
const { Map } = require('immutable')
const beattles = Map({
  John: { name: "Lennon" },
  Paul: { name: "McCartney" },
  George: { name: "Harrison" },
  Ringo: { name: "Starr" },
});
beattles.sortBy(member => member.name);run it
```



Note: `[sortBy()](../list/index#sortBy())` Always returns a new instance, even if the original was already sorted.

 Note: This is always an eager operation.

 



#### [groupBy()](index#groupBy())




Returns a `[Collection.Keyed](../collection.keyed/index)` of `Collection.Keyeds`, grouped by the return value of the `grouper` function.

 

```
groupBy<G>(grouper: (value: T, key: number, iter: this) => G,context?: unknown): Seq.Keyed<G, Collection<number, T>>

```

#### Inherited from


`[Collection#groupBy()](../collection/index#groupBy())`#### Discussion



Note: This is always an eager operation.

 
```
const { List, Map } = require('immutable')
const listOfMaps = List([
  Map({ v: 0 }),
  Map({ v: 1 }),
  Map({ v: 1 }),
  Map({ v: 0 }),
  Map({ v: 2 })
])
const groupsOfMaps = listOfMaps.groupBy(x => x.get('v'))
// Map {
//   0: List [ Map{ "v": 0 }, Map { "v": 0 } ],
//   1: List [ Map{ "v": 1 }, Map { "v": 1 } ],
//   2: List [ Map{ "v": 2 } ],
// }run it
```




### Value equality



#### [equals()](index#equals())




True if this and the other Collection have value equality, as defined by `[Immutable.is()](../is()/index)`.

 

```
equals(other: unknown): boolean

```

#### Inherited from


`[Collection#equals()](../collection/index#equals())`#### Discussion



Note: This is equivalent to `Immutable.is(this, other)`, but provided to allow for chained expressions.

 



#### [hashCode()](index#hashCode())




Computes and returns the hashed identity for this Collection.

 

```
hashCode(): number

```

#### Inherited from


`[Collection#hashCode()](../collection/index#hashCode())`#### Discussion



The `[hashCode](../list/index#hashCode())` of a Collection is used to determine potential equality, and is used when adding this to a `[Set](../set/index)` or as a key in a `[Map](../map/index)`, enabling lookup via a different instance.

 
```
const a = List([ 1, 2, 3 ]);
const b = List([ 1, 2, 3 ]);
assert.notStrictEqual(a, b); // different instances
const set = Set([ a ]);
assert.equal(set.has(b), true);run it
```

If two values have the same `[hashCode](../list/index#hashCode())`, they are [not guaranteed to be equal](https://en.wikipedia.org/wiki/Collision_(computer_science)). If two values have different `[hashCode](../list/index#hashCode())`s, they must not be equal.

 


### Reading deep values



#### [getIn()](index#getIn())




Returns the value found by following a path of keys or indices through nested Collections.

 

```
getIn(searchKeyPath: Iterable<unknown>, notSetValue?: unknown): unknown

```

#### Inherited from


`[Collection#getIn()](../collection/index#getIn())`#### Discussion


 
```
const { Map, List } = require('immutable')
const deepData = Map({ x: List([ Map({ y: 123 }) ]) });
deepData.getIn(['x', 0, 'y']) // 123run it
```



Plain JavaScript Object or Arrays may be nested within an Immutable.js Collection, and getIn() can access those values as well:

 
```
const { Map, List } = require('immutable')
const deepData = Map({ x: [ { y: 123 } ] });
deepData.getIn(['x', 0, 'y']) // 123run it
```


 



#### [hasIn()](index#hasIn())




True if the result of following a path of keys or indices through nested Collections results in a set value.

 

```
hasIn(searchKeyPath: Iterable<unknown>): boolean

```

#### Inherited from


`[Collection#hasIn()](../collection/index#hasIn())`


### Persistent changes



#### [update()](index#update())




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".

 

```
update<R>(updater: (value: this) => R): R

```

#### Inherited from


`[Collection#update()](../collection/index#update())`#### Discussion



For example, to sum a Seq after mapping and filtering:

 
```
const { Seq } = require('immutable')

function sum(collection) {
  return collection.reduce((sum, x) => sum + x, 0)
}
Seq([ 1, 2, 3 ])
  .map(x => x + 1)
  .filter(x => x % 2 === 0)
  .update(sum)
// 6run it
```
 


### Conversion to Collections



#### [toMap()](index#toMap())




Converts this Collection to a Map, Throws if keys are not hashable.

 

```
toMap(): Map<number, T>

```

#### Inherited from


`[Collection#toMap()](../collection/index#toMap())`#### Discussion



Note: This is equivalent to `Map(this.toKeyedSeq())`, but provided for convenience and to allow for chained expressions.

 



#### [toOrderedMap()](index#toOrderedMap())




Converts this Collection to a Map, maintaining the order of iteration.

 

```
toOrderedMap(): OrderedMap<number, T>

```

#### Inherited from


`[Collection#toOrderedMap()](../collection/index#toOrderedMap())`#### Discussion



Note: This is equivalent to `OrderedMap(this.toKeyedSeq())`, but provided for convenience and to allow for chained expressions.

 



#### [toSet()](index#toSet())




Converts this Collection to a Set, discarding keys. Throws if values are not hashable.

 

```
toSet(): Set<T>

```

#### Inherited from


`[Collection#toSet()](../collection/index#toSet())`#### Discussion



Note: This is equivalent to `[Set(this)](../set/index)`, but provided to allow for chained expressions.

 



#### [toOrderedSet()](index#toOrderedSet())




Converts this Collection to a Set, maintaining the order of iteration and discarding keys.

 

```
toOrderedSet(): OrderedSet<T>

```

#### Inherited from


`[Collection#toOrderedSet()](../collection/index#toOrderedSet())`#### Discussion



Note: This is equivalent to `OrderedSet(this.valueSeq())`, but provided for convenience and to allow for chained expressions.

 



#### [toList()](index#toList())




Converts this Collection to a List, discarding keys.

 

```
toList(): List<T>

```

#### Inherited from


`[Collection#toList()](../collection/index#toList())`#### Discussion



This is similar to `[List(collection)](../list/index)`, but provided to allow for chained expressions. However, when called on `[Map](../map/index)` or other keyed collections, `collection.toList()` discards the keys and creates a list of only the values, whereas `[List(collection)](../list/index)` creates a list of entry tuples.

 
```
const { Map, List } = require('immutable')
var myMap = Map({ a: 'Apple', b: 'Banana' })
List(myMap) // List [ [ "a", "Apple" ], [ "b", "Banana" ] ]
myMap.toList() // List [ "Apple", "Banana" ]run it
```





#### [toStack()](index#toStack())




Converts this Collection to a Stack, discarding keys. Throws if values are not hashable.

 

```
toStack(): Stack<T>

```

#### Inherited from


`[Collection#toStack()](../collection/index#toStack())`#### Discussion



Note: This is equivalent to `[Stack(this)](../stack/index)`, but provided to allow for chained expressions.

 


### Iterators



#### [keys()](index#keys())




An iterator of this `[Collection](../collection/index)`'s keys.

 

```
keys(): IterableIterator<number>

```

#### Inherited from


`[Collection#keys()](../collection/index#keys())`#### Discussion



Note: this will return an ES6 iterator which does not support Immutable.js sequence algorithms. Use `[keySeq](../list/index#keySeq())` instead, if this is what you want.

 



#### [values()](index#values())




An iterator of this `[Collection](../collection/index)`'s values.

 

```
values(): IterableIterator<T>

```

#### Inherited from


`[Collection#values()](../collection/index#values())`#### Discussion



Note: this will return an ES6 iterator which does not support Immutable.js sequence algorithms. Use `[valueSeq](../list/index#valueSeq())` instead, if this is what you want.

 



#### [entries()](index#entries())




An iterator of this `[Collection](../collection/index)`'s entries as `[ key, value ]` tuples.

 

```
entries(): IterableIterator<[number, T]>

```

#### Inherited from


`[Collection#entries()](../collection/index#entries())`#### Discussion



Note: this will return an ES6 iterator which does not support Immutable.js sequence algorithms. Use `[entrySeq](../list/index#entrySeq())` instead, if this is what you want.

 


### Collections (Seq)



#### [keySeq()](index#keySeq())




Returns a new Seq.Indexed of the keys of this Collection, discarding values.

 

```
keySeq(): Seq.Indexed<number>

```

#### Inherited from


`[Collection#keySeq()](../collection/index#keySeq())`



#### [valueSeq()](index#valueSeq())




Returns an Seq.Indexed of the values of this Collection, discarding keys.

 

```
valueSeq(): Seq.Indexed<T>

```

#### Inherited from


`[Collection#valueSeq()](../collection/index#valueSeq())`



#### [entrySeq()](index#entrySeq())




Returns a new Seq.Indexed of [key, value] tuples.

 

```
entrySeq(): Seq.Indexed<[number, T]>

```

#### Inherited from


`[Collection#entrySeq()](../collection/index#entrySeq())`


### Side effects



#### [forEach()](index#forEach())




The `sideEffect` is executed for every entry in the Collection.

 

```
forEach(sideEffect: (value: T, key: number, iter: this) => unknown,context?: unknown): number

```

#### Inherited from


`[Collection#forEach()](../collection/index#forEach())`#### Discussion



Unlike `[Array#forEach](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/forEach)`, if any call of `sideEffect` returns `false`, the iteration will stop. Returns the number of entries iterated (including the last iteration which returned false).

 


### Creating subsets



#### [slice()](index#slice())




Returns a new Collection of the same type representing a portion of this Collection from start up to but not including end.

 

```
slice(begin?: number, end?: number): this

```

#### Inherited from


`[Collection#slice()](../collection/index#slice())`#### Discussion



If begin is negative, it is offset from the end of the Collection. e.g. `slice(-2)` returns a Collection of the last two entries. If it is not provided the new Collection will begin at the beginning of this Collection.

 If end is negative, it is offset from the end of the Collection. e.g. `slice(0, -1)` returns a Collection of everything but the last entry. If it is not provided, the new Collection will continue through the end of this Collection.

 If the requested slice is equivalent to the current Collection, then it will return itself.

 



#### [rest()](index#rest())




Returns a new Collection of the same type containing all entries except the first.

 

```
rest(): this

```

#### Inherited from


`[Collection#rest()](../collection/index#rest())`



#### [butLast()](index#butLast())




Returns a new Collection of the same type containing all entries except the last.

 

```
butLast(): this

```

#### Inherited from


`[Collection#butLast()](../collection/index#butLast())`



#### [skip()](index#skip())




Returns a new Collection of the same type which excludes the first `amount` entries from this Collection.

 

```
skip(amount: number): this

```

#### Inherited from


`[Collection#skip()](../collection/index#skip())`



#### [skipLast()](index#skipLast())




Returns a new Collection of the same type which excludes the last `amount` entries from this Collection.

 

```
skipLast(amount: number): this

```

#### Inherited from


`[Collection#skipLast()](../collection/index#skipLast())`



#### [skipWhile()](index#skipWhile())




Returns a new Collection of the same type which includes entries starting from when `predicate` first returns false.

 

```
skipWhile(predicate: (value: T, key: number, iter: this) => boolean,context?: unknown): this

```

#### Inherited from


`[Collection#skipWhile()](../collection/index#skipWhile())`#### Discussion


 
```
const { List } = require('immutable')
List([ 'dog', 'frog', 'cat', 'hat', 'god' ])
  .skipWhile(x => x.match(/g/))
// List [ "cat", "hat", "god" ]run it
```


 



#### [skipUntil()](index#skipUntil())




Returns a new Collection of the same type which includes entries starting from when `predicate` first returns true.

 

```
skipUntil(predicate: (value: T, key: number, iter: this) => boolean,context?: unknown): this

```

#### Inherited from


`[Collection#skipUntil()](../collection/index#skipUntil())`#### Discussion


 
```
const { List } = require('immutable')
List([ 'dog', 'frog', 'cat', 'hat', 'god' ])
  .skipUntil(x => x.match(/hat/))
// List [ "hat", "god" ]run it
```


 



#### [take()](index#take())




Returns a new Collection of the same type which includes the first `amount` entries from this Collection.

 

```
take(amount: number): this

```

#### Inherited from


`[Collection#take()](../collection/index#take())`



#### [takeLast()](index#takeLast())




Returns a new Collection of the same type which includes the last `amount` entries from this Collection.

 

```
takeLast(amount: number): this

```

#### Inherited from


`[Collection#takeLast()](../collection/index#takeLast())`



#### [takeWhile()](index#takeWhile())




Returns a new Collection of the same type which includes entries from this Collection as long as the `predicate` returns true.

 

```
takeWhile(predicate: (value: T, key: number, iter: this) => boolean,context?: unknown): this

```

#### Inherited from


`[Collection#takeWhile()](../collection/index#takeWhile())`#### Discussion


 
```
const { List } = require('immutable')
List([ 'dog', 'frog', 'cat', 'hat', 'god' ])
  .takeWhile(x => x.match(/o/))
// List [ "dog", "frog" ]run it
```


 



#### [takeUntil()](index#takeUntil())




Returns a new Collection of the same type which includes entries from this Collection as long as the `predicate` returns false.

 

```
takeUntil(predicate: (value: T, key: number, iter: this) => boolean,context?: unknown): this

```

#### Inherited from


`[Collection#takeUntil()](../collection/index#takeUntil())`#### Discussion


 
```
const { List } = require('immutable')
List([ 'dog', 'frog', 'cat', 'hat', 'god' ])
  .takeUntil(x => x.match(/at/))
// List [ "dog", "frog" ]run it
```


 


### Reducing a value



#### [reduce()](index#reduce())




```
reduce<R>(reducer: (reduction: R, value: T, key: number, iter: this) => R,initialReduction: R,context?: unknown): R
reduce<R>(reducer: (reduction: T | R, value: T, key: number, iter: this) => R): R

```

#### Inherited from


`[Collection#reduce()](../collection/index#reduce())`



#### [reduceRight()](index#reduceRight())




```
reduceRight<R>(reducer: (reduction: R, value: T, key: number, iter: this) => R,initialReduction: R,context?: unknown): R
reduceRight<R>(reducer: (reduction: T | R, value: T, key: number, iter: this) => R): R

```

#### Inherited from


`[Collection#reduceRight()](../collection/index#reduceRight())`



#### [every()](index#every())




True if `predicate` returns true for all entries in the Collection.

 

```
every(predicate: (value: T, key: number, iter: this) => boolean,context?: unknown): boolean

```

#### Inherited from


`[Collection#every()](../collection/index#every())`



#### [some()](index#some())




True if `predicate` returns true for any entry in the Collection.

 

```
some(predicate: (value: T, key: number, iter: this) => boolean,context?: unknown): boolean

```

#### Inherited from


`[Collection#some()](../collection/index#some())`



#### [join()](index#join())




Joins values together as a string, inserting a separator between each. The default separator is `","`.

 

```
join(separator?: string): string

```

#### Inherited from


`[Collection#join()](../collection/index#join())`



#### [isEmpty()](index#isEmpty())




Returns true if this Collection includes no values.

 

```
isEmpty(): boolean

```

#### Inherited from


`[Collection#isEmpty()](../collection/index#isEmpty())`#### Discussion



For some lazy `[Seq](../seq/index)`, `[isEmpty](../list/index#isEmpty())` might need to iterate to determine emptiness. At most one iteration will occur.

 



#### [count()](index#count())




```
count(): number
count(predicate: (value: T, key: number, iter: this) => boolean,context?: unknown): number

```

#### Inherited from


`[Collection#count()](../collection/index#count())`



#### [countBy()](index#countBy())




Returns a `[Seq.Keyed](../seq.keyed/index)` of counts, grouped by the return value of the `grouper` function.

 

```
countBy<G>(grouper: (value: T, key: number, iter: this) => G,context?: unknown): Map<G, number>

```

#### Inherited from


`[Collection#countBy()](../collection/index#countBy())`#### Discussion



Note: This is not a lazy operation.

 


### Comparison



#### [isSubset()](index#isSubset())




True if `iter` includes every value in this Collection.

 

```
isSubset(iter: Iterable<T>): boolean

```

#### Inherited from


`[Collection#isSubset()](../collection/index#isSubset())`



#### [isSuperset()](index#isSuperset())




True if this Collection includes every value in `iter`.

 

```
isSuperset(iter: Iterable<T>): boolean

```

#### Inherited from


`[Collection#isSuperset()](../collection/index#isSuperset())`

This documentation is generated from [immutable.d.ts](https://github.com/immutable-js/immutable-js/blob/main/type-definitions/immutable.d.ts). Pull requests and [Issues](https://github.com/immutable-js/immutable-js/issues) welcome.

 © 2014–present, Lee Byron and other contributors  
Licensed under the 3-clause BSD License.  

<https://immutable-js.com/docs/v4.2.1/Collection.Indexed/>

Collection.Set
==============



Set Collections only represent values. They have no associated keys or indices. Duplicate values are possible in the lazy `[Seq.Set](../seq.set/index)`s, however the concrete `[Set](../set/index)` Collection does not allow duplicate values.

 

```
type Collection.Set<T> extends Collection<T, T>
```

#### Discussion



Collection methods on Collection.Set such as `[map](index#map())` and `[forEach](index#forEach())` will provide the value as both the first and second arguments to the provided function.

 
```
const { Collection } = require('immutable')
const seq = Collection.Set([ 'A', 'B', 'C' ])
// Seq { "A", "B", "C" }
seq.forEach((v, k) =>
 assert.equal(v, k)
)
```


### Construction



#### [Collection.Set()](index#Collection.Set())




Similar to `[Collection()](../collection/index)`, but always returns a Collection.Set.

 

```
Collection.Set<T>(collection?: Iterable<T> | ArrayLike<T>): Collection.Set<T>

```

#### Discussion



Note: `[Collection.Set](index)` is a factory function and not a class, and does not use the `new` keyword during construction.

 


### Conversion to JavaScript types



#### [toJS()](index#toJS())




Deeply converts this Set collection to equivalent native JavaScript Array.

 

```
toJS(): Array<DeepCopy<T>>

```

#### Overrides


`[Collection#toJS()](../collection/index#toJS())`



#### [toJSON()](index#toJSON())




Shallowly converts this Set collection to equivalent native JavaScript Array.

 

```
toJSON(): Array<T>

```

#### Overrides


`[Collection#toJSON()](../collection/index#toJSON())`



#### [toArray()](index#toArray())




Shallowly converts this collection to an Array.

 

```
toArray(): Array<T>

```

#### Overrides


`[Collection#toArray()](../collection/index#toArray())`



#### [toObject()](index#toObject())




Shallowly converts this Collection to an Object.

 

```
toObject(): {[key: string]: T}

```

#### Inherited from


`[Collection#toObject()](../collection/index#toObject())`#### Discussion



Converts keys to Strings.

 


### Conversion to Seq



#### [toSeq()](index#toSeq())




Returns Seq.Set.

 

```
toSeq(): Seq.Set<T>

```

#### Overrides


`[Collection#toSeq()](../collection/index#toSeq())`



#### [toKeyedSeq()](index#toKeyedSeq())




Returns a Seq.Keyed from this Collection where indices are treated as keys.

 

```
toKeyedSeq(): Seq.Keyed<T, T>

```

#### Inherited from


`[Collection#toKeyedSeq()](../collection/index#toKeyedSeq())`#### Discussion



This is useful if you want to operate on an Collection.Indexed and preserve the [index, value] pairs.

 The returned Seq will have identical iteration order as this Collection.

 
```
const { Seq } = require('immutable')
const indexedSeq = Seq([ 'A', 'B', 'C' ])
// Seq [ "A", "B", "C" ]
indexedSeq.filter(v => v === 'B')
// Seq [ "B" ]
const keyedSeq = indexedSeq.toKeyedSeq()
// Seq { 0: "A", 1: "B", 2: "C" }
keyedSeq.filter(v => v === 'B')
// Seq { 1: "B" }run it
```





#### [toIndexedSeq()](index#toIndexedSeq())




Returns an Seq.Indexed of the values of this Collection, discarding keys.

 

```
toIndexedSeq(): Seq.Indexed<T>

```

#### Inherited from


`[Collection#toIndexedSeq()](../collection/index#toIndexedSeq())`



#### [toSetSeq()](index#toSetSeq())




Returns a Seq.Set of the values of this Collection, discarding keys.

 

```
toSetSeq(): Seq.Set<T>

```

#### Inherited from


`[Collection#toSetSeq()](../collection/index#toSetSeq())`


### Sequence algorithms



#### [concat()](index#concat())




Returns a new Collection with other collections concatenated to this one.

 

```
concat<U>(...collections: Array<Iterable<U>>): Collection.Set<T | U>

```

#### Overrides


`[Collection#concat()](../collection/index#concat())`



#### [map()](index#map())




Returns a new Collection.Set with values passed through a `mapper` function.

 

```
map<M>(mapper: (value: T, key: T, iter: this) => M,context?: unknown): Collection.Set<M>

```

#### Overrides


`[Collection#map()](../collection/index#map())`#### Example




```
Collection.Set([ 1, 2 ]).map(x => 10 * x)
// Seq { 1, 2 }
```

Note: `[map()](index#map())` always returns a new instance, even if it produced the same value at every step.

 



#### [flatMap()](index#flatMap())




Flat-maps the Collection, returning a Collection of the same type.

 

```
flatMap<M>(mapper: (value: T, key: T, iter: this) => Iterable<M>,context?: unknown): Collection.Set<M>

```

#### Overrides


`[Collection#flatMap()](../collection/index#flatMap())`#### Discussion



Similar to `collection.map(...).flatten(true)`.

 



#### [filter()](index#filter())




```
filter<F>(predicate: (value: T, key: T, iter: this) => boolean,context?: unknown): Collection.Set<F>
filter(predicate: (value: T, key: T, iter: this) => unknown,context?: unknown): this

```

#### Overrides


`[Collection#filter()](../collection/index#filter())`



#### [partition()](index#partition())




```
partition<F, C>(predicate: (this: C, value: T, key: T, iter: this) => boolean,context?: C): [Collection.Set<T>, Collection.Set<F>]
partition<C>(predicate: (this: C, value: T, key: T, iter: this) => unknown,context?: C): [this, this]

```

#### Overrides


`[Collection#partition()](../collection/index#partition())`



#### [[Symbol.iterator]()](index#%5BSymbol.iterator%5D())




```
[Symbol.iterator](): IterableIterator<T>

```

#### Overrides


`[Collection#[Symbol.iterator]()](../collection/index#%5BSymbol.iterator%5D())`



#### [filterNot()](index#filterNot())




Returns a new Collection of the same type with only the entries for which the `predicate` function returns false.

 

```
filterNot(predicate: (value: T, key: T, iter: this) => boolean,context?: unknown): this

```

#### Inherited from


`[Collection#filterNot()](../collection/index#filterNot())`#### Discussion


 
```
const { Map } = require('immutable')
Map({ a: 1, b: 2, c: 3, d: 4}).filterNot(x => x % 2 === 0)
// Map { "a": 1, "c": 3 }run it
```



Note: `[filterNot()](../list/index#filterNot())` always returns a new instance, even if it results in not filtering out any values.

 



#### [reverse()](index#reverse())




Returns a new Collection of the same type in reverse order.

 

```
reverse(): this

```

#### Inherited from


`[Collection#reverse()](../collection/index#reverse())`



#### [sort()](index#sort())




Returns a new Collection of the same type which includes the same entries, stably sorted by using a `comparator`.

 

```
sort(comparator?: (valueA: T, valueB: T) => number): this

```

#### Inherited from


`[Collection#sort()](../collection/index#sort())`#### Discussion



If a `comparator` is not provided, a default comparator uses `<` and `>`.

 `comparator(valueA, valueB)`:

 * Returns `0` if the elements should not be swapped.
* Returns `-1` (or any negative number) if `valueA` comes before `valueB`
* Returns `1` (or any positive number) if `valueA` comes after `valueB`
* Is pure, i.e. it must always return the same value for the same pair of values.

 When sorting collections which have no defined order, their ordered equivalents will be returned. e.g. `map.sort()` returns OrderedMap.

 
```
const { Map } = require('immutable')
Map({ "c": 3, "a": 1, "b": 2 }).sort((a, b) => {
  if (a < b) { return -1; }
  if (a > b) { return 1; }
  if (a === b) { return 0; }
});
// OrderedMap { "a": 1, "b": 2, "c": 3 }run it
```

Note: `[sort()](../list/index#sort())` Always returns a new instance, even if the original was already sorted.

 Note: This is always an eager operation.

 



#### [sortBy()](index#sortBy())




Like `[sort](../list/index#sort())`, but also accepts a `comparatorValueMapper` which allows for sorting by more sophisticated means:

 

```
sortBy<C>(comparatorValueMapper: (value: T, key: T, iter: this) => C,comparator?: (valueA: C, valueB: C) => number): this

```

#### Inherited from


`[Collection#sortBy()](../collection/index#sortBy())`#### Discussion


 
```
const { Map } = require('immutable')
const beattles = Map({
  John: { name: "Lennon" },
  Paul: { name: "McCartney" },
  George: { name: "Harrison" },
  Ringo: { name: "Starr" },
});
beattles.sortBy(member => member.name);run it
```



Note: `[sortBy()](../list/index#sortBy())` Always returns a new instance, even if the original was already sorted.

 Note: This is always an eager operation.

 



#### [groupBy()](index#groupBy())




Returns a `[Collection.Keyed](../collection.keyed/index)` of `Collection.Keyeds`, grouped by the return value of the `grouper` function.

 

```
groupBy<G>(grouper: (value: T, key: T, iter: this) => G,context?: unknown): Seq.Keyed<G, Collection<T, T>>

```

#### Inherited from


`[Collection#groupBy()](../collection/index#groupBy())`#### Discussion



Note: This is always an eager operation.

 
```
const { List, Map } = require('immutable')
const listOfMaps = List([
  Map({ v: 0 }),
  Map({ v: 1 }),
  Map({ v: 1 }),
  Map({ v: 0 }),
  Map({ v: 2 })
])
const groupsOfMaps = listOfMaps.groupBy(x => x.get('v'))
// Map {
//   0: List [ Map{ "v": 0 }, Map { "v": 0 } ],
//   1: List [ Map{ "v": 1 }, Map { "v": 1 } ],
//   2: List [ Map{ "v": 2 } ],
// }run it
```




### Value equality



#### [equals()](index#equals())




True if this and the other Collection have value equality, as defined by `[Immutable.is()](../is()/index)`.

 

```
equals(other: unknown): boolean

```

#### Inherited from


`[Collection#equals()](../collection/index#equals())`#### Discussion



Note: This is equivalent to `Immutable.is(this, other)`, but provided to allow for chained expressions.

 



#### [hashCode()](index#hashCode())




Computes and returns the hashed identity for this Collection.

 

```
hashCode(): number

```

#### Inherited from


`[Collection#hashCode()](../collection/index#hashCode())`#### Discussion



The `[hashCode](../list/index#hashCode())` of a Collection is used to determine potential equality, and is used when adding this to a `[Set](../set/index)` or as a key in a `[Map](../map/index)`, enabling lookup via a different instance.

 
```
const a = List([ 1, 2, 3 ]);
const b = List([ 1, 2, 3 ]);
assert.notStrictEqual(a, b); // different instances
const set = Set([ a ]);
assert.equal(set.has(b), true);run it
```

If two values have the same `[hashCode](../list/index#hashCode())`, they are [not guaranteed to be equal](https://en.wikipedia.org/wiki/Collision_(computer_science)). If two values have different `[hashCode](../list/index#hashCode())`s, they must not be equal.

 


### Reading values



#### [get()](index#get())




```
get<NSV>(key: T, notSetValue: NSV): T | NSV
get(key: T): T | undefined

```

#### Inherited from


`[Collection#get()](../collection/index#get())`



#### [has()](index#has())




True if a key exists within this `[Collection](../collection/index)`, using `[Immutable.is](../is()/index)` to determine equality

 

```
has(key: T): boolean

```

#### Inherited from


`[Collection#has()](../collection/index#has())`



#### [includes()](index#includes())




True if a value exists within this `[Collection](../collection/index)`, using `[Immutable.is](../is()/index)` to determine equality

 

```
includes(value: T): boolean

```

#### Inherited from


`[Collection#includes()](../collection/index#includes())`#### alias


`contains()`



#### [first()](index#first())




In case the `[Collection](../collection/index)` is not empty returns the first element of the `[Collection](../collection/index)`. In case the `[Collection](../collection/index)` is empty returns the optional default value if provided, if no default value is provided returns undefined.

 

```
first<NSV>(notSetValue?: NSV): T | NSV

```

#### Inherited from


`[Collection#first()](../collection/index#first())`



#### [last()](index#last())




In case the `[Collection](../collection/index)` is not empty returns the last element of the `[Collection](../collection/index)`. In case the `[Collection](../collection/index)` is empty returns the optional default value if provided, if no default value is provided returns undefined.

 

```
last<NSV>(notSetValue?: NSV): T | NSV

```

#### Inherited from


`[Collection#last()](../collection/index#last())`


### Reading deep values



#### [getIn()](index#getIn())




Returns the value found by following a path of keys or indices through nested Collections.

 

```
getIn(searchKeyPath: Iterable<unknown>, notSetValue?: unknown): unknown

```

#### Inherited from


`[Collection#getIn()](../collection/index#getIn())`#### Discussion


 
```
const { Map, List } = require('immutable')
const deepData = Map({ x: List([ Map({ y: 123 }) ]) });
deepData.getIn(['x', 0, 'y']) // 123run it
```



Plain JavaScript Object or Arrays may be nested within an Immutable.js Collection, and getIn() can access those values as well:

 
```
const { Map, List } = require('immutable')
const deepData = Map({ x: [ { y: 123 } ] });
deepData.getIn(['x', 0, 'y']) // 123run it
```


 



#### [hasIn()](index#hasIn())




True if the result of following a path of keys or indices through nested Collections results in a set value.

 

```
hasIn(searchKeyPath: Iterable<unknown>): boolean

```

#### Inherited from


`[Collection#hasIn()](../collection/index#hasIn())`


### Persistent changes



#### [update()](index#update())




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".

 

```
update<R>(updater: (value: this) => R): R

```

#### Inherited from


`[Collection#update()](../collection/index#update())`#### Discussion



For example, to sum a Seq after mapping and filtering:

 
```
const { Seq } = require('immutable')

function sum(collection) {
  return collection.reduce((sum, x) => sum + x, 0)
}
Seq([ 1, 2, 3 ])
  .map(x => x + 1)
  .filter(x => x % 2 === 0)
  .update(sum)
// 6run it
```
 


### Conversion to Collections



#### [toMap()](index#toMap())




Converts this Collection to a Map, Throws if keys are not hashable.

 

```
toMap(): Map<T, T>

```

#### Inherited from


`[Collection#toMap()](../collection/index#toMap())`#### Discussion



Note: This is equivalent to `Map(this.toKeyedSeq())`, but provided for convenience and to allow for chained expressions.

 



#### [toOrderedMap()](index#toOrderedMap())




Converts this Collection to a Map, maintaining the order of iteration.

 

```
toOrderedMap(): OrderedMap<T, T>

```

#### Inherited from


`[Collection#toOrderedMap()](../collection/index#toOrderedMap())`#### Discussion



Note: This is equivalent to `OrderedMap(this.toKeyedSeq())`, but provided for convenience and to allow for chained expressions.

 



#### [toSet()](index#toSet())




Converts this Collection to a Set, discarding keys. Throws if values are not hashable.

 

```
toSet(): Set<T>

```

#### Inherited from


`[Collection#toSet()](../collection/index#toSet())`#### Discussion



Note: This is equivalent to `[Set(this)](../set/index)`, but provided to allow for chained expressions.

 



#### [toOrderedSet()](index#toOrderedSet())




Converts this Collection to a Set, maintaining the order of iteration and discarding keys.

 

```
toOrderedSet(): OrderedSet<T>

```

#### Inherited from


`[Collection#toOrderedSet()](../collection/index#toOrderedSet())`#### Discussion



Note: This is equivalent to `OrderedSet(this.valueSeq())`, but provided for convenience and to allow for chained expressions.

 



#### [toList()](index#toList())




Converts this Collection to a List, discarding keys.

 

```
toList(): List<T>

```

#### Inherited from


`[Collection#toList()](../collection/index#toList())`#### Discussion



This is similar to `[List(collection)](../list/index)`, but provided to allow for chained expressions. However, when called on `[Map](../map/index)` or other keyed collections, `collection.toList()` discards the keys and creates a list of only the values, whereas `[List(collection)](../list/index)` creates a list of entry tuples.

 
```
const { Map, List } = require('immutable')
var myMap = Map({ a: 'Apple', b: 'Banana' })
List(myMap) // List [ [ "a", "Apple" ], [ "b", "Banana" ] ]
myMap.toList() // List [ "Apple", "Banana" ]run it
```





#### [toStack()](index#toStack())




Converts this Collection to a Stack, discarding keys. Throws if values are not hashable.

 

```
toStack(): Stack<T>

```

#### Inherited from


`[Collection#toStack()](../collection/index#toStack())`#### Discussion



Note: This is equivalent to `[Stack(this)](../stack/index)`, but provided to allow for chained expressions.

 


### Iterators



#### [keys()](index#keys())




An iterator of this `[Collection](../collection/index)`'s keys.

 

```
keys(): IterableIterator<T>

```

#### Inherited from


`[Collection#keys()](../collection/index#keys())`#### Discussion



Note: this will return an ES6 iterator which does not support Immutable.js sequence algorithms. Use `[keySeq](../list/index#keySeq())` instead, if this is what you want.

 



#### [values()](index#values())




An iterator of this `[Collection](../collection/index)`'s values.

 

```
values(): IterableIterator<T>

```

#### Inherited from


`[Collection#values()](../collection/index#values())`#### Discussion



Note: this will return an ES6 iterator which does not support Immutable.js sequence algorithms. Use `[valueSeq](../list/index#valueSeq())` instead, if this is what you want.

 



#### [entries()](index#entries())




An iterator of this `[Collection](../collection/index)`'s entries as `[ key, value ]` tuples.

 

```
entries(): IterableIterator<[T, T]>

```

#### Inherited from


`[Collection#entries()](../collection/index#entries())`#### Discussion



Note: this will return an ES6 iterator which does not support Immutable.js sequence algorithms. Use `[entrySeq](../list/index#entrySeq())` instead, if this is what you want.

 


### Collections (Seq)



#### [keySeq()](index#keySeq())




Returns a new Seq.Indexed of the keys of this Collection, discarding values.

 

```
keySeq(): Seq.Indexed<T>

```

#### Inherited from


`[Collection#keySeq()](../collection/index#keySeq())`



#### [valueSeq()](index#valueSeq())




Returns an Seq.Indexed of the values of this Collection, discarding keys.

 

```
valueSeq(): Seq.Indexed<T>

```

#### Inherited from


`[Collection#valueSeq()](../collection/index#valueSeq())`



#### [entrySeq()](index#entrySeq())




Returns a new Seq.Indexed of [key, value] tuples.

 

```
entrySeq(): Seq.Indexed<[T, T]>

```

#### Inherited from


`[Collection#entrySeq()](../collection/index#entrySeq())`


### Side effects



#### [forEach()](index#forEach())




The `sideEffect` is executed for every entry in the Collection.

 

```
forEach(sideEffect: (value: T, key: T, iter: this) => unknown,context?: unknown): number

```

#### Inherited from


`[Collection#forEach()](../collection/index#forEach())`#### Discussion



Unlike `[Array#forEach](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/forEach)`, if any call of `sideEffect` returns `false`, the iteration will stop. Returns the number of entries iterated (including the last iteration which returned false).

 


### Creating subsets



#### [slice()](index#slice())




Returns a new Collection of the same type representing a portion of this Collection from start up to but not including end.

 

```
slice(begin?: number, end?: number): this

```

#### Inherited from


`[Collection#slice()](../collection/index#slice())`#### Discussion



If begin is negative, it is offset from the end of the Collection. e.g. `slice(-2)` returns a Collection of the last two entries. If it is not provided the new Collection will begin at the beginning of this Collection.

 If end is negative, it is offset from the end of the Collection. e.g. `slice(0, -1)` returns a Collection of everything but the last entry. If it is not provided, the new Collection will continue through the end of this Collection.

 If the requested slice is equivalent to the current Collection, then it will return itself.

 



#### [rest()](index#rest())




Returns a new Collection of the same type containing all entries except the first.

 

```
rest(): this

```

#### Inherited from


`[Collection#rest()](../collection/index#rest())`



#### [butLast()](index#butLast())




Returns a new Collection of the same type containing all entries except the last.

 

```
butLast(): this

```

#### Inherited from


`[Collection#butLast()](../collection/index#butLast())`



#### [skip()](index#skip())




Returns a new Collection of the same type which excludes the first `amount` entries from this Collection.

 

```
skip(amount: number): this

```

#### Inherited from


`[Collection#skip()](../collection/index#skip())`



#### [skipLast()](index#skipLast())




Returns a new Collection of the same type which excludes the last `amount` entries from this Collection.

 

```
skipLast(amount: number): this

```

#### Inherited from


`[Collection#skipLast()](../collection/index#skipLast())`



#### [skipWhile()](index#skipWhile())




Returns a new Collection of the same type which includes entries starting from when `predicate` first returns false.

 

```
skipWhile(predicate: (value: T, key: T, iter: this) => boolean,context?: unknown): this

```

#### Inherited from


`[Collection#skipWhile()](../collection/index#skipWhile())`#### Discussion


 
```
const { List } = require('immutable')
List([ 'dog', 'frog', 'cat', 'hat', 'god' ])
  .skipWhile(x => x.match(/g/))
// List [ "cat", "hat", "god" ]run it
```


 



#### [skipUntil()](index#skipUntil())




Returns a new Collection of the same type which includes entries starting from when `predicate` first returns true.

 

```
skipUntil(predicate: (value: T, key: T, iter: this) => boolean,context?: unknown): this

```

#### Inherited from


`[Collection#skipUntil()](../collection/index#skipUntil())`#### Discussion


 
```
const { List } = require('immutable')
List([ 'dog', 'frog', 'cat', 'hat', 'god' ])
  .skipUntil(x => x.match(/hat/))
// List [ "hat", "god" ]run it
```


 



#### [take()](index#take())




Returns a new Collection of the same type which includes the first `amount` entries from this Collection.

 

```
take(amount: number): this

```

#### Inherited from


`[Collection#take()](../collection/index#take())`



#### [takeLast()](index#takeLast())




Returns a new Collection of the same type which includes the last `amount` entries from this Collection.

 

```
takeLast(amount: number): this

```

#### Inherited from


`[Collection#takeLast()](../collection/index#takeLast())`



#### [takeWhile()](index#takeWhile())




Returns a new Collection of the same type which includes entries from this Collection as long as the `predicate` returns true.

 

```
takeWhile(predicate: (value: T, key: T, iter: this) => boolean,context?: unknown): this

```

#### Inherited from


`[Collection#takeWhile()](../collection/index#takeWhile())`#### Discussion


 
```
const { List } = require('immutable')
List([ 'dog', 'frog', 'cat', 'hat', 'god' ])
  .takeWhile(x => x.match(/o/))
// List [ "dog", "frog" ]run it
```


 



#### [takeUntil()](index#takeUntil())




Returns a new Collection of the same type which includes entries from this Collection as long as the `predicate` returns false.

 

```
takeUntil(predicate: (value: T, key: T, iter: this) => boolean,context?: unknown): this

```

#### Inherited from


`[Collection#takeUntil()](../collection/index#takeUntil())`#### Discussion


 
```
const { List } = require('immutable')
List([ 'dog', 'frog', 'cat', 'hat', 'god' ])
  .takeUntil(x => x.match(/at/))
// List [ "dog", "frog" ]run it
```


 


### Combination



#### [flatten()](index#flatten())




```
flatten(depth?: number): Collection<unknown, unknown>
flatten(shallow?: boolean): Collection<unknown, unknown>

```

#### Inherited from


`[Collection#flatten()](../collection/index#flatten())`


### Reducing a value



#### [reduce()](index#reduce())




```
reduce<R>(reducer: (reduction: R, value: T, key: T, iter: this) => R,initialReduction: R,context?: unknown): R
reduce<R>(reducer: (reduction: T | R, value: T, key: T, iter: this) => R): R

```

#### Inherited from


`[Collection#reduce()](../collection/index#reduce())`



#### [reduceRight()](index#reduceRight())




```
reduceRight<R>(reducer: (reduction: R, value: T, key: T, iter: this) => R,initialReduction: R,context?: unknown): R
reduceRight<R>(reducer: (reduction: T | R, value: T, key: T, iter: this) => R): R

```

#### Inherited from


`[Collection#reduceRight()](../collection/index#reduceRight())`



#### [every()](index#every())




True if `predicate` returns true for all entries in the Collection.

 

```
every(predicate: (value: T, key: T, iter: this) => boolean,context?: unknown): boolean

```

#### Inherited from


`[Collection#every()](../collection/index#every())`



#### [some()](index#some())




True if `predicate` returns true for any entry in the Collection.

 

```
some(predicate: (value: T, key: T, iter: this) => boolean,context?: unknown): boolean

```

#### Inherited from


`[Collection#some()](../collection/index#some())`



#### [join()](index#join())




Joins values together as a string, inserting a separator between each. The default separator is `","`.

 

```
join(separator?: string): string

```

#### Inherited from


`[Collection#join()](../collection/index#join())`



#### [isEmpty()](index#isEmpty())




Returns true if this Collection includes no values.

 

```
isEmpty(): boolean

```

#### Inherited from


`[Collection#isEmpty()](../collection/index#isEmpty())`#### Discussion



For some lazy `[Seq](../seq/index)`, `[isEmpty](../list/index#isEmpty())` might need to iterate to determine emptiness. At most one iteration will occur.

 



#### [count()](index#count())




```
count(): number
count(predicate: (value: T, key: T, iter: this) => boolean,context?: unknown): number

```

#### Inherited from


`[Collection#count()](../collection/index#count())`



#### [countBy()](index#countBy())




Returns a `[Seq.Keyed](../seq.keyed/index)` of counts, grouped by the return value of the `grouper` function.

 

```
countBy<G>(grouper: (value: T, key: T, iter: this) => G,context?: unknown): Map<G, number>

```

#### Inherited from


`[Collection#countBy()](../collection/index#countBy())`#### Discussion



Note: This is not a lazy operation.

 


### Search for value



#### [find()](index#find())




Returns the first value for which the `predicate` returns true.

 

```
find(predicate: (value: T, key: T, iter: this) => boolean,context?: unknown,notSetValue?: T): T | undefined

```

#### Inherited from


`[Collection#find()](../collection/index#find())`



#### [findLast()](index#findLast())




Returns the last value for which the `predicate` returns true.

 

```
findLast(predicate: (value: T, key: T, iter: this) => boolean,context?: unknown,notSetValue?: T): T | undefined

```

#### Inherited from


`[Collection#findLast()](../collection/index#findLast())`#### Discussion



Note: `predicate` will be called for each entry in reverse.

 



#### [findEntry()](index#findEntry())




Returns the first [key, value] entry for which the `predicate` returns true.

 

```
findEntry(predicate: (value: T, key: T, iter: this) => boolean,context?: unknown,notSetValue?: T): [T, T] | undefined

```

#### Inherited from


`[Collection#findEntry()](../collection/index#findEntry())`



#### [findLastEntry()](index#findLastEntry())




Returns the last [key, value] entry for which the `predicate` returns true.

 

```
findLastEntry(predicate: (value: T, key: T, iter: this) => boolean,context?: unknown,notSetValue?: T): [T, T] | undefined

```

#### Inherited from


`[Collection#findLastEntry()](../collection/index#findLastEntry())`#### Discussion



Note: `predicate` will be called for each entry in reverse.

 



#### [findKey()](index#findKey())




Returns the key for which the `predicate` returns true.

 

```
findKey(predicate: (value: T, key: T, iter: this) => boolean,context?: unknown): T | undefined

```

#### Inherited from


`[Collection#findKey()](../collection/index#findKey())`



#### [findLastKey()](index#findLastKey())




Returns the last key for which the `predicate` returns true.

 

```
findLastKey(predicate: (value: T, key: T, iter: this) => boolean,context?: unknown): T | undefined

```

#### Inherited from


`[Collection#findLastKey()](../collection/index#findLastKey())`#### Discussion



Note: `predicate` will be called for each entry in reverse.

 



#### [keyOf()](index#keyOf())




Returns the key associated with the search value, or undefined.

 

```
keyOf(searchValue: T): T | undefined

```

#### Inherited from


`[Collection#keyOf()](../collection/index#keyOf())`



#### [lastKeyOf()](index#lastKeyOf())




Returns the last key associated with the search value, or undefined.

 

```
lastKeyOf(searchValue: T): T | undefined

```

#### Inherited from


`[Collection#lastKeyOf()](../collection/index#lastKeyOf())`



#### [max()](index#max())




Returns the maximum value in this collection. If any values are comparatively equivalent, the first one found will be returned.

 

```
max(comparator?: (valueA: T, valueB: T) => number): T | undefined

```

#### Inherited from


`[Collection#max()](../collection/index#max())`#### Discussion



The `comparator` is used in the same way as `[Collection#sort](../collection/index#sort())`. If it is not provided, the default comparator is `>`.

 When two values are considered equivalent, the first encountered will be returned. Otherwise, `[max](../list/index#max())` will operate independent of the order of input as long as the comparator is commutative. The default comparator `>` is commutative *only* when types do not differ.

 If `comparator` returns 0 and either value is NaN, undefined, or null, that value will be returned.

 



#### [maxBy()](index#maxBy())




Like `[max](../list/index#max())`, but also accepts a `comparatorValueMapper` which allows for comparing by more sophisticated means:

 

```
maxBy<C>(comparatorValueMapper: (value: T, key: T, iter: this) => C,comparator?: (valueA: C, valueB: C) => number): T | undefined

```

#### Inherited from


`[Collection#maxBy()](../collection/index#maxBy())`#### Discussion


 
```
const { List, } = require('immutable');
const l = List([
  { name: 'Bob', avgHit: 1 },
  { name: 'Max', avgHit: 3 },
  { name: 'Lili', avgHit: 2 } ,
]);
l.maxBy(i => i.avgHit); // will output { name: 'Max', avgHit: 3 }run it
```


 



#### [min()](index#min())




Returns the minimum value in this collection. If any values are comparatively equivalent, the first one found will be returned.

 

```
min(comparator?: (valueA: T, valueB: T) => number): T | undefined

```

#### Inherited from


`[Collection#min()](../collection/index#min())`#### Discussion



The `comparator` is used in the same way as `[Collection#sort](../collection/index#sort())`. If it is not provided, the default comparator is `<`.

 When two values are considered equivalent, the first encountered will be returned. Otherwise, `[min](../list/index#min())` will operate independent of the order of input as long as the comparator is commutative. The default comparator `<` is commutative *only* when types do not differ.

 If `comparator` returns 0 and either value is NaN, undefined, or null, that value will be returned.

 



#### [minBy()](index#minBy())




Like `[min](../list/index#min())`, but also accepts a `comparatorValueMapper` which allows for comparing by more sophisticated means:

 

```
minBy<C>(comparatorValueMapper: (value: T, key: T, iter: this) => C,comparator?: (valueA: C, valueB: C) => number): T | undefined

```

#### Inherited from


`[Collection#minBy()](../collection/index#minBy())`#### Discussion


 
```
const { List, } = require('immutable');
const l = List([
  { name: 'Bob', avgHit: 1 },
  { name: 'Max', avgHit: 3 },
  { name: 'Lili', avgHit: 2 } ,
]);
l.minBy(i => i.avgHit); // will output { name: 'Bob', avgHit: 1 }run it
```


 


### Comparison



#### [isSubset()](index#isSubset())




True if `iter` includes every value in this Collection.

 

```
isSubset(iter: Iterable<T>): boolean

```

#### Inherited from


`[Collection#isSubset()](../collection/index#isSubset())`



#### [isSuperset()](index#isSuperset())




True if this Collection includes every value in `iter`.

 

```
isSuperset(iter: Iterable<T>): boolean

```

#### Inherited from


`[Collection#isSuperset()](../collection/index#isSuperset())`

This documentation is generated from [immutable.d.ts](https://github.com/immutable-js/immutable-js/blob/main/type-definitions/immutable.d.ts). Pull requests and [Issues](https://github.com/immutable-js/immutable-js/issues) welcome.

 © 2014–present, Lee Byron and other contributors  
Licensed under the 3-clause BSD License.  

<https://immutable-js.com/docs/v4.2.1/Collection.Set/>

isOrderedMap()
==============



True if `maybeOrderedMap` is an OrderedMap.

 

```
isOrderedMap(maybeOrderedMap: unknown): boolean

```
This documentation is generated from [immutable.d.ts](https://github.com/immutable-js/immutable-js/blob/main/type-definitions/immutable.d.ts). Pull requests and [Issues](https://github.com/immutable-js/immutable-js/issues) welcome.

 © 2014–present, Lee Byron and other contributors  
Licensed under the 3-clause BSD License.  

<https://immutable-js.com/docs/v4.2.1/isOrderedMap()/>

isStack()
=========



True if `maybeStack` is a Stack.

 

```
isStack(maybeStack: unknown): boolean

```
This documentation is generated from [immutable.d.ts](https://github.com/immutable-js/immutable-js/blob/main/type-definitions/immutable.d.ts). Pull requests and [Issues](https://github.com/immutable-js/immutable-js/issues) welcome.

 © 2014–present, Lee Byron and other contributors  
Licensed under the 3-clause BSD License.  

<https://immutable-js.com/docs/v4.2.1/isStack()/>

isSet()
=======



True if `maybeSet` is a Set.

 

```
isSet(maybeSet: unknown): boolean

```

#### Discussion



Also true for OrderedSets.

 This documentation is generated from [immutable.d.ts](https://github.com/immutable-js/immutable-js/blob/main/type-definitions/immutable.d.ts). Pull requests and [Issues](https://github.com/immutable-js/immutable-js/issues) welcome.

 © 2014–present, Lee Byron and other contributors  
Licensed under the 3-clause BSD License.  

<https://immutable-js.com/docs/v4.2.1/isSet()/>

isOrderedSet()
==============



True if `maybeOrderedSet` is an OrderedSet.

 

```
isOrderedSet(maybeOrderedSet: unknown): boolean

```
This documentation is generated from [immutable.d.ts](https://github.com/immutable-js/immutable-js/blob/main/type-definitions/immutable.d.ts). Pull requests and [Issues](https://github.com/immutable-js/immutable-js/issues) welcome.

 © 2014–present, Lee Byron and other contributors  
Licensed under the 3-clause BSD License.  

<https://immutable-js.com/docs/v4.2.1/isOrderedSet()/>

isRecord()
==========



True if `maybeRecord` is a Record.

 

```
isRecord(maybeRecord: unknown): boolean

```
This documentation is generated from [immutable.d.ts](https://github.com/immutable-js/immutable-js/blob/main/type-definitions/immutable.d.ts). Pull requests and [Issues](https://github.com/immutable-js/immutable-js/issues) welcome.

 © 2014–present, Lee Byron and other contributors  
Licensed under the 3-clause BSD License.  

<https://immutable-js.com/docs/v4.2.1/isRecord()/>

get()
=====



```
get<K, V>(collection: Collection<K, V>, key: K): V | undefined
get<K, V, NSV>(collection: Collection<K, V>, key: K, notSetValue: NSV): V | NSV
get<TProps, K>(record: Record<TProps>, key: K, notSetValue: unknown): TProps,[K]
get<V>(collection: Array<V>, key: number): V | undefined
get<V, NSV>(collection: Array<V>, key: number, notSetValue: NSV): V | NSV
get<C, K>(object: C, key: K, notSetValue: unknown): C,[K]
get<V>(collection: {[key: string]: V}, key: string): V | undefined
get<V, NSV>(collection: {[key: string]: V},key: string,notSetValue: NSV): V | NSV

```
This documentation is generated from [immutable.d.ts](https://github.com/immutable-js/immutable-js/blob/main/type-definitions/immutable.d.ts). Pull requests and [Issues](https://github.com/immutable-js/immutable-js/issues) welcome.

 © 2014–present, Lee Byron and other contributors  
Licensed under the 3-clause BSD License.  

<https://immutable-js.com/docs/v4.2.1/get()/>

has()
=====



Returns true if the key is defined in the provided collection.

 

```
has(collection: object, key: unknown): boolean

```

#### Discussion



A functional alternative to `collection.has(key)` which will also work with plain Objects and Arrays as an alternative for `collection.hasOwnProperty(key)`.

 
```
const { has } = require('immutable')
has([ 'dog', 'frog', 'cat' ], 2) // true
has([ 'dog', 'frog', 'cat' ], 5) // false
has({ x: 123, y: 456 }, 'x') // true
has({ x: 123, y: 456 }, 'z') // falserun it
```

This documentation is generated from [immutable.d.ts](https://github.com/immutable-js/immutable-js/blob/main/type-definitions/immutable.d.ts). Pull requests and [Issues](https://github.com/immutable-js/immutable-js/issues) welcome.

 © 2014–present, Lee Byron and other contributors  
Licensed under the 3-clause BSD License.  

<https://immutable-js.com/docs/v4.2.1/has()/>

remove()
========



```
remove<K, C>(collection: C, key: K): C
remove<TProps, C, K>(collection: C, key: K): C
remove<C>(collection: C, key: number): C
remove<C, K>(collection: C, key: K): C
remove<C, K>(collection: C, key: K): C

```
This documentation is generated from [immutable.d.ts](https://github.com/immutable-js/immutable-js/blob/main/type-definitions/immutable.d.ts). Pull requests and [Issues](https://github.com/immutable-js/immutable-js/issues) welcome.

 © 2014–present, Lee Byron and other contributors  
Licensed under the 3-clause BSD License.  

<https://immutable-js.com/docs/v4.2.1/remove()/>

set()
=====



```
set<K, V, C>(collection: C, key: K, value: V): C
set<TProps, C, K>(record: C, key: K, value: TProps,[K]): C
set<V, C>(collection: C, key: number, value: V): C
set<C, K>(object: C, key: K, value: C,[K]): C
set<V, C>(collection: C, key: string, value: V): C

```
This documentation is generated from [immutable.d.ts](https://github.com/immutable-js/immutable-js/blob/main/type-definitions/immutable.d.ts). Pull requests and [Issues](https://github.com/immutable-js/immutable-js/issues) welcome.

 © 2014–present, Lee Byron and other contributors  
Licensed under the 3-clause BSD License.  

<https://immutable-js.com/docs/v4.2.1/set()/>

update()
========



```
update<K, V, C>(collection: C, key: K, updater: (value: V | undefined) => V): C
update<K, V, C, NSV>(collection: C,key: K,notSetValue: NSV,updater: (value: V | NSV) => V): C
update<TProps, C, K>(record: C,key: K,updater: (value: TProps,[K]) => TProps,[K]): C
update<TProps, C, K, NSV>(record: C,key: K,notSetValue: NSV,updater: (value: TProps,[K] | NSV) => TProps,[K]): C
update<V>(collection: Array<V>, key: number, updater: (value: V) => V): Array<V>
update<V, NSV>(collection: Array<V>,key: number,notSetValue: NSV,updater: (value: V | NSV) => V): Array<V>
update<C, K>(object: C, key: K, updater: (value: C,[K]) => C,[K]): C
update<C, K, NSV>(object: C,key: K,notSetValue: NSV,updater: (value: C,[K] | NSV) => C,[K]): C
update<V, C, K>(collection: C,key: K,updater: (value: V) => V): {[key: string]: V}
update<V, C, K, NSV>(collection: C,key: K,notSetValue: NSV,updater: (value: V | NSV) => V): {[key: string]: V}

```
This documentation is generated from [immutable.d.ts](https://github.com/immutable-js/immutable-js/blob/main/type-definitions/immutable.d.ts). Pull requests and [Issues](https://github.com/immutable-js/immutable-js/issues) welcome.

 © 2014–present, Lee Byron and other contributors  
Licensed under the 3-clause BSD License.  

<https://immutable-js.com/docs/v4.2.1/update()/>

hasIn()
=======



Returns true if the key path is defined in the provided collection.

 

```
hasIn(collection: unknown, keyPath: Iterable<unknown>): boolean

```

#### Discussion



A functional alternative to `collection.hasIn(keypath)` which will also work with plain Objects and Arrays.

 
```
const { hasIn } = require('immutable')
hasIn({ x: { y: { z: 123 }}}, ['x', 'y', 'z']) // true
hasIn({ x: { y: { z: 123 }}}, ['x', 'q', 'p']) // falserun it
```

This documentation is generated from [immutable.d.ts](https://github.com/immutable-js/immutable-js/blob/main/type-definitions/immutable.d.ts). Pull requests and [Issues](https://github.com/immutable-js/immutable-js/issues) welcome.

 © 2014–present, Lee Byron and other contributors  
Licensed under the 3-clause BSD License.  

<https://immutable-js.com/docs/v4.2.1/hasIn()/>

removeIn()
==========



Returns a copy of the collection with the value at the key path removed.

 

```
removeIn<C>(collection: C, keyPath: Iterable<unknown>): C

```

#### Discussion



A functional alternative to `collection.removeIn(keypath)` which will also work with plain Objects and Arrays.

 
```
const { removeIn } = require('immutable')
const original = { x: { y: { z: 123 }}}
removeIn(original, ['x', 'y', 'z']) // { x: { y: {}}}
console.log(original) // { x: { y: { z: 123 }}}run it
```

This documentation is generated from [immutable.d.ts](https://github.com/immutable-js/immutable-js/blob/main/type-definitions/immutable.d.ts). Pull requests and [Issues](https://github.com/immutable-js/immutable-js/issues) welcome.

 © 2014–present, Lee Byron and other contributors  
Licensed under the 3-clause BSD License.  

<https://immutable-js.com/docs/v4.2.1/removeIn()/>

setIn()
=======



Returns a copy of the collection with the value at the key path set to the provided value.

 

```
setIn<C>(collection: C, keyPath: Iterable<unknown>, value: unknown): C

```

#### Discussion



A functional alternative to `collection.setIn(keypath)` which will also work with plain Objects and Arrays.

 
```
const { setIn } = require('immutable')
const original = { x: { y: { z: 123 }}}
setIn(original, ['x', 'y', 'z'], 456) // { x: { y: { z: 456 }}}
console.log(original) // { x: { y: { z: 123 }}}run it
```

This documentation is generated from [immutable.d.ts](https://github.com/immutable-js/immutable-js/blob/main/type-definitions/immutable.d.ts). Pull requests and [Issues](https://github.com/immutable-js/immutable-js/issues) welcome.

 © 2014–present, Lee Byron and other contributors  
Licensed under the 3-clause BSD License.  

<https://immutable-js.com/docs/v4.2.1/setIn()/>

updateIn()
==========



```
updateIn<C>(collection: C,keyPath: Iterable<unknown>,updater: (value: unknown) => unknown): C
updateIn<C>(collection: C,keyPath: Iterable<unknown>,notSetValue: unknown,updater: (value: unknown) => unknown): C

```
This documentation is generated from [immutable.d.ts](https://github.com/immutable-js/immutable-js/blob/main/type-definitions/immutable.d.ts). Pull requests and [Issues](https://github.com/immutable-js/immutable-js/issues) welcome.

 © 2014–present, Lee Byron and other contributors  
Licensed under the 3-clause BSD License.  

<https://immutable-js.com/docs/v4.2.1/updateIn()/>

merge()
=======



Returns a copy of the collection with the remaining collections merged in.

 

```
merge<C>(collection: C,...collections: Array<Iterable<unknown> | Iterable<[unknown, unknown]> | {[key: string]: unknown}>): C

```

#### Discussion



A functional alternative to `collection.merge()` which will also work with plain Objects and Arrays.

 
```
const { merge } = require('immutable')
const original = { x: 123, y: 456 }
merge(original, { y: 789, z: 'abc' }) // { x: 123, y: 789, z: 'abc' }
console.log(original) // { x: 123, y: 456 }run it
```

This documentation is generated from [immutable.d.ts](https://github.com/immutable-js/immutable-js/blob/main/type-definitions/immutable.d.ts). Pull requests and [Issues](https://github.com/immutable-js/immutable-js/issues) welcome.

 © 2014–present, Lee Byron and other contributors  
Licensed under the 3-clause BSD License.  

<https://immutable-js.com/docs/v4.2.1/merge()/>

mergeWith()
===========



Returns a copy of the collection with the remaining collections merged in, calling the `merger` function whenever an existing value is encountered.

 

```
mergeWith<C>(merger: (oldVal: unknown, newVal: unknown, key: unknown) => unknown,collection: C,...collections: Array<Iterable<unknown> | Iterable<[unknown, unknown]> | {[key: string]: unknown}>): C

```

#### Discussion



A functional alternative to `collection.mergeWith()` which will also work with plain Objects and Arrays.

 
```
const { mergeWith } = require('immutable')
const original = { x: 123, y: 456 }
mergeWith(
  (oldVal, newVal) => oldVal + newVal,
  original,
  { y: 789, z: 'abc' }
) // { x: 123, y: 1245, z: 'abc' }
console.log(original) // { x: 123, y: 456 }run it
```

This documentation is generated from [immutable.d.ts](https://github.com/immutable-js/immutable-js/blob/main/type-definitions/immutable.d.ts). Pull requests and [Issues](https://github.com/immutable-js/immutable-js/issues) welcome.

 © 2014–present, Lee Byron and other contributors  
Licensed under the 3-clause BSD License.  

<https://immutable-js.com/docs/v4.2.1/mergeWith()/>

mergeDeep()
===========



Like `[merge()](../merge()/index)`, but when two compatible collections are encountered with the same key, it merges them as well, recursing deeply through the nested data. Two collections are considered to be compatible (and thus will be merged together) if they both fall into one of three categories: keyed (e.g., `[Map](../map/index)`s, `[Record](../record/index)`s, and objects), indexed (e.g., `[List](../list/index)`s and arrays), or set-like (e.g., `[Set](../set/index)`s). If they fall into separate categories, `[mergeDeep](index)` will replace the existing collection with the collection being merged in. This behavior can be customized by using `[mergeDeepWith()](../mergedeepwith()/index)`.

 

```
mergeDeep<C>(collection: C,...collections: Array<Iterable<unknown> | Iterable<[unknown, unknown]> | {[key: string]: unknown}>): C

```

#### Discussion



Note: Indexed and set-like collections are merged using `concat()`/`union()` and therefore do not recurse.

 A functional alternative to `collection.mergeDeep()` which will also work with plain Objects and Arrays.

 
```
const { mergeDeep } = require('immutable')
const original = { x: { y: 123 }}
mergeDeep(original, { x: { z: 456 }}) // { x: { y: 123, z: 456 }}
console.log(original) // { x: { y: 123 }}run it
```

This documentation is generated from [immutable.d.ts](https://github.com/immutable-js/immutable-js/blob/main/type-definitions/immutable.d.ts). Pull requests and [Issues](https://github.com/immutable-js/immutable-js/issues) welcome.

 © 2014–present, Lee Byron and other contributors  
Licensed under the 3-clause BSD License.  

<https://immutable-js.com/docs/v4.2.1/mergeDeep()/>

mergeDeepWith()
===============



Like `[mergeDeep()](../mergedeep()/index)`, but when two non-collections or incompatible collections are encountered at the same key, it uses the `merger` function to determine the resulting value. Collections are considered incompatible if they fall into separate categories between keyed, indexed, and set-like.

 

```
mergeDeepWith<C>(merger: (oldVal: unknown, newVal: unknown, key: unknown) => unknown,collection: C,...collections: Array<Iterable<unknown> | Iterable<[unknown, unknown]> | {[key: string]: unknown}>): C

```

#### Discussion



A functional alternative to `collection.mergeDeepWith()` which will also work with plain Objects and Arrays.

 
```
const { mergeDeepWith } = require('immutable')
const original = { x: { y: 123 }}
mergeDeepWith(
  (oldVal, newVal) => oldVal + newVal,
  original,
  { x: { y: 456 }}
) // { x: { y: 579 }}
console.log(original) // { x: { y: 123 }}run it
```

This documentation is generated from [immutable.d.ts](https://github.com/immutable-js/immutable-js/blob/main/type-definitions/immutable.d.ts). Pull requests and [Issues](https://github.com/immutable-js/immutable-js/issues) welcome.

 © 2014–present, Lee Byron and other contributors  
Licensed under the 3-clause BSD License.  

<https://immutable-js.com/docs/v4.2.1/mergeDeepWith()/>

immutable