RecordOf
This is equivalent to an instance of a record created by a Record Factory.
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) // []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' ]Deeply converts plain JS objects and arrays to Immutable Maps and Lists.
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.
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()
}fromJS is conservative in its conversion. It will only convert
arrays which pass Array.isArray to Lists, and only raw objects (no custom
prototype) to Map.
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}, []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" !== undefinedProperty 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 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].
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.
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).
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') // falseReturns 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.
const { hasIn } = require('immutable')
hasIn({ x: { y: { z: 123 }}}, ['x', 'y', 'z']) // true
hasIn({ x: { y: { z: 123 }}}, ['x', 'q', 'p']) // falseThe 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
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.
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.
const { isAssociative, Map, List, Stack, Set } = require('immutable');
isAssociative([]); // false
isAssociative({}); // false
isAssociative(Map()); // true
isAssociative(List()); // true
isAssociative(Stack()); // true
isAssociative(Set()); // falseTrue if maybeCollection is a Collection, or any of its subclasses.
const { isCollection, Map, List, Stack } = require('immutable');
isCollection([]); // false
isCollection({}); // false
isCollection(Map()); // true
isCollection(List()); // true
isCollection(Stack()); // trueTrue if maybeImmutable is an Immutable Collection or Record.
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()); // trueTrue if maybeIndexed is a Collection.Indexed, or any of its subclasses.
const { isIndexed, Map, List, Stack, Set } = require('immutable');
isIndexed([]); // false
isIndexed({}); // false
isIndexed(Map()); // false
isIndexed(List()); // true
isIndexed(Stack()); // true
isIndexed(Set()); // falseTrue if maybeKeyed is a Collection.Keyed, or any of its subclasses.
const { isKeyed, Map, List, Stack } = require('immutable');
isKeyed([]); // false
isKeyed({}); // false
isKeyed(Map()); // true
isKeyed(List()); // false
isKeyed(Stack()); // falseTrue 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.
const { isOrdered, Map, OrderedMap, List, Set } = require('immutable');
isOrdered([]); // false
isOrdered({}); // false
isOrdered(Map()); // false
isOrdered(OrderedMap()); // true
isOrdered(List()); // true
isOrdered(Set()); // falseTrue 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.
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.
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 }Returns a copy of the collection with the remaining collections merged in deeply (recursively).
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 }}Returns a copy of the collection with the remaining collections merged in
deeply (recursively), calling the merger function whenever an existing
value is encountered.
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 }}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.
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 }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].
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.
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 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.
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 }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.
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 }}}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]).
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.
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 }}}Generated using TypeDoc
Copyright (c) 2014-present, Facebook, Inc.
This source code is licensed under the MIT license found in the LICENSE file in the root directory of this source tree.