immutable

Creates a Collection.

The type of Collection created is based on the input.

* If an Collection, that same Collection. * If an Array-like, an Collection.Indexed. * If an Object with an Iterator defined, an Collection.Indexed. * If an Object, an Collection.Keyed.

This methods forces the conversion of Objects and Strings to Collections. If you want to ensure that a Collection of one item is returned, use Seq.of.

Note: An Iterator itself will be treated as an object, becoming a Seq.Keyed, which is usually not what you want. You should turn your Iterator Object into an iterable object by defining a Symbol.iterator (or @@iterator) method which returns this.

Note: Collection is a conversion function and not a class, and does not use the new keyword during construction.

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

fromJS will convert Arrays and [array-like objects][2] to a List, and plain objects (without a custom prototype) to a Map. [Iterable objects][3] 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][1].

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

<!-- runkit:activate -->

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

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

<!-- runkit:activate -->

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}, []

Keep in mind, when using JS objects to construct Immutable Maps, that JavaScript Object properties are always strings, even if written in a quote-less shorthand, while Immutable Maps accept keys of any type.

<!-- runkit:activate -->

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" !== undefined

Property access for JavaScript Objects first converts the key to a string, but since Immutable Map keys can be of any type the argument to get() is not altered.

[1]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse#Example.3A_Using_the_reviver_parameter "Using the reviver parameter" [2]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Indexed_collections#working_with_array-like_objects "Working with array-like objects" [3]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_iterable_protocol "The iterable protocol"

Returns the value within the provided collection associated with the provided key, or notSetValue if the key is not defined in the collection.

A functional alternative to collection.get(key) which will also work on plain Objects and Arrays as an alternative for collection[key].

<!-- runkit:activate -->

const { get } = require('immutable')
get([ 'dog', 'frog', 'cat' ], 2) // 'frog'
get({ x: 123, y: 456 }, 'x') // 123
get({ x: 123, y: 456 }, 'z', 'ifNotSet') // 'ifNotSet'

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

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

<!-- runkit:activate -->

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

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

A functional alternative to collection.has(key) which will also work with plain Objects and Arrays as an alternative for collection.hasOwnProperty(key).

<!-- runkit:activate -->

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') // false

The hash() 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() will return a 31-bit integer.

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() 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() attempts to balance between speed and avoiding collisions, however it makes no attempt to produce secure hashes.

*New in Version 4.0*

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

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

<!-- runkit:activate -->

const { hasIn } = require('immutable')
hasIn({ x: { y: { z: 123 }}}, ['x', 'y', 'z']) // true
hasIn({ x: { y: { z: 123 }}}, ['x', 'q', 'p']) // false

Value equality check with semantics similar to Object.is, but treats Immutable Collections as values, equal if the second Collection includes equivalent values.

It's used throughout Immutable when checking for equality, including Map key equality and Set membership.

<!-- runkit:activate -->

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)

is() compares primitive types like strings and numbers, Immutable.js collections like Map and List, but also any custom object which implements ValueObject by providing equals() and hashCode() methods.

Note: Unlike Object.is, Immutable.is assumes 0 and -0 are the same value, matching the behavior of ES6 Map key equality.

True if maybeAssociative is either a Keyed or Indexed Collection.

<!-- runkit:activate -->

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

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

<!-- runkit:activate -->

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

True if maybeImmutable is an Immutable Collection or Record.

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

<!-- runkit:activate -->

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

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

<!-- runkit:activate -->

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

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

<!-- runkit:activate -->

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

True if maybeList is a List.

True if maybeMap is a Map.

Also true for OrderedMaps.

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

<!-- runkit:activate -->

const { isOrdered, Map, OrderedMap, List, Set } = require('immutable');
isOrdered([]); // false
isOrdered({}); // false
isOrdered(Map()); // false
isOrdered(OrderedMap()); // true
isOrdered(List()); // true
isOrdered(Set()); // false

True if maybeOrderedMap is an OrderedMap.

True if maybeOrderedSet is an OrderedSet.

True if maybeRecord is a Record.

True if maybeSeq is a Seq.

True if maybeSet is a Set.

Also true for OrderedSets.

True if maybeStack is a Stack.

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

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

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

Note: List is a factory function and not a class, and does not use the new keyword during construction.

<!-- runkit:activate -->

const { List, Set } = require('immutable')

const emptyList = List()
// List []

const plainArray = [ 1, 2, 3, 4 ]
const listFromPlainArray = List(plainArray)
// List [ 1, 2, 3, 4 ]

const plainSet = Set([ 1, 2, 3, 4 ])
const listFromPlainSet = List(plainSet)
// List [ 1, 2, 3, 4 ]

const arrayIterator = plainArray[Symbol.iterator]()
const listFromCollectionArray = List(arrayIterator)
// List [ 1, 2, 3, 4 ]

listFromPlainArray.equals(listFromCollectionArray) // true
listFromPlainSet.equals(listFromCollectionArray) // true
listFromPlainSet.equals(listFromPlainArray) // true

Creates a new Immutable Map.

Created with the same key value pairs as the provided Collection.Keyed or JavaScript Object or expects a Collection of [K, V] tuple entries.

Note: Map is a factory function and not a class, and does not use the new keyword during construction.

<!-- runkit:activate -->

const { Map } = require('immutable')
Map({ key: "value" })
Map([ [ "key", "value" ] ])

Keep in mind, when using JS objects to construct Immutable Maps, that JavaScript Object properties are always strings, even if written in a quote-less shorthand, while Immutable Maps accept keys of any type.

<!-- runkit:activate { "preamble": "const { Map } = require('immutable');" } -->

let obj = { 1: "one" }
Object.keys(obj) // [ "1" ]
assert.equal(obj["1"], obj[1]) // "one" === "one"

let map = Map(obj)
assert.notEqual(map.get("1"), map.get(1)) // "one" !== undefined

Property access for JavaScript Objects first converts the key to a string, but since Immutable Map keys can be of any type the argument to get() is not altered.

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

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

<!-- runkit:activate -->

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 }

Like 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., Maps, Records, and objects), indexed (e.g., Lists and arrays), or set-like (e.g., Sets). If they fall into separate categories, mergeDeep will replace the existing collection with the collection being merged in. This behavior can be customized by using mergeDeepWith().

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.

<!-- runkit:activate -->

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

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

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

<!-- runkit:activate -->

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

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

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

<!-- runkit:activate -->

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 }

Creates a new Immutable OrderedMap.

Created with the same key value pairs as the provided Collection.Keyed or JavaScript Object or expects a Collection of [K, V] tuple entries.

The iteration order of key-value pairs provided to this constructor will be preserved in the OrderedMap.

let newOrderedMap = OrderedMap({key: "value"}) let newOrderedMap = OrderedMap([["key", "value"]])

Note: OrderedMap is a factory function and not a class, and does not use the new keyword during construction.

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

Note: OrderedSet is a factory function and not a class, and does not use the new keyword during construction.

Returns a Seq.Indexed of numbers from start (inclusive) to end (exclusive), by step, where start defaults to 0, step to 1, and end to infinity. When start is equal to end, returns empty range.

Note: Range is a factory function and not a class, and does not use the new keyword during construction.

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

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

See above for examples of using Record().

Note: Record is a factory function and not a class, and does not use the new keyword during construction.

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

A functional alternative to collection.remove(key) which will also work with plain Objects and Arrays as an alternative for delete collectionCopy[key].

<!-- runkit:activate -->

const { remove } = require('immutable')
const originalArray = [ 'dog', 'frog', 'cat' ]
remove(originalArray, 1) // [ 'dog', 'cat' ]
console.log(originalArray) // [ 'dog', 'frog', 'cat' ]
const originalObject = { x: 123, y: 456 }
remove(originalObject, 'x') // { y: 456 }
console.log(originalObject) // { x: 123, y: 456 }

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

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

<!-- runkit:activate -->

const { removeIn } = require('immutable')
const original = { x: { y: { z: 123 }}}
removeIn(original, ['x', 'y', 'z']) // { x: { y: {}}}
console.log(original) // { x: { y: { z: 123 }}}

Returns a Seq.Indexed of value repeated times times. When times is not defined, returns an infinite Seq of value.

Note: Repeat is a factory function and not a class, and does not use the new keyword during construction.

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

Creates a Seq.

Returns a particular kind of Seq based on the input.

* If a Seq, that same Seq. * If an Collection, a Seq of the same kind (Keyed, Indexed, or Set). * If an Array-like, an Seq.Indexed. * If an Iterable Object, an Seq.Indexed. * If an Object, a Seq.Keyed.

Note: An Iterator itself will be treated as an object, becoming a Seq.Keyed, which is usually not what you want. You should turn your Iterator Object into an iterable object by defining a Symbol.iterator (or @@iterator) method which returns this.

Note: Seq is a conversion function and not a class, and does not use the new keyword during construction.

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

A functional alternative to collection.set(key, value) which will also work with plain Objects and Arrays as an alternative for collectionCopy[key] = value.

<!-- runkit:activate -->

const { set } = require('immutable')
const originalArray = [ 'dog', 'frog', 'cat' ]
set(originalArray, 1, 'cow') // [ 'dog', 'cow', 'cat' ]
console.log(originalArray) // [ 'dog', 'frog', 'cat' ]
const originalObject = { x: 123, y: 456 }
set(originalObject, 'x', 789) // { x: 789, y: 456 }
console.log(originalObject) // { x: 123, y: 456 }

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

Note: Set is a factory function and not a class, and does not use the new keyword during construction.

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

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

<!-- runkit:activate -->

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

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

The iteration order of the provided collection is preserved in the resulting Stack.

Note: Stack is a factory function and not a class, and does not use the new keyword during construction.

Returns a copy of the collection with the value at key set to the result of providing the existing value to the updating function.

A functional alternative to collection.update(key, fn) which will also work with plain Objects and Arrays as an alternative for collectionCopy[key] = fn(collection[key]).

<!-- runkit:activate -->

const { update } = require('immutable')
const originalArray = [ 'dog', 'frog', 'cat' ]
update(originalArray, 1, val => val.toUpperCase()) // [ 'dog', 'FROG', 'cat' ]
console.log(originalArray) // [ 'dog', 'frog', 'cat' ]
const originalObject = { x: 123, y: 456 }
update(originalObject, 'x', val => val * 6) // { x: 738, y: 456 }
console.log(originalObject) // { x: 123, y: 456 }

Returns a copy of the collection with the value at key path set to the result of providing the existing value to the updating function.

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

<!-- runkit:activate -->

const { updateIn } = require('immutable')
const original = { x: { y: { z: 123 }}}
updateIn(original, ['x', 'y', 'z'], val => val * 6) // { x: { y: { z: 738 }}}
console.log(original) // { x: { y: { z: 123 }}}