immutable 3.8.2 → 4.0.0-rc.12

package/README.md

@@ -1,7 +1,7 @@
 Immutable collections for JavaScript
 ====================================
 
-[![Build Status](https://travis-ci.org/facebook/immutable-js.svg)](https://travis-ci.org/facebook/immutable-js)
+[![Build Status](https://travis-ci.org/facebook/immutable-js.svg?branch=master)](https://travis-ci.org/facebook/immutable-js) [![Join the chat at https://gitter.im/immutable-js/Lobby](https://badges.gitter.im/immutable-js/Lobby.svg)](https://gitter.im/immutable-js/Lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
 
 [Immutable][] data cannot be changed once created, leading to much simpler
 application development, no defensive copying, and enabling advanced memoization
@@ -16,7 +16,7 @@ These data structures are highly efficient on modern JavaScript VMs by using
 structural sharing via [hash maps tries][] and [vector tries][] as popularized
 by Clojure and Scala, minimizing the need to copy or cache data.
 
-`Immutable` also provides a lazy `Seq`, allowing efficient
+Immutable.js also provides a lazy `Seq`, allowing efficient
 chaining of collection methods like `map` and `filter` without creating
 intermediate representations. Create some `Seq` with `Range` and `Repeat`.
 
@@ -41,60 +41,86 @@ npm install immutable
 
 Then require it into any module.
 
-```javascript
-var Immutable = require('immutable');
-var map1 = Immutable.Map({a:1, b:2, c:3});
-var map2 = map1.set('b', 50);
-map1.get('b'); // 2
-map2.get('b'); // 50
+<!-- runkit:activate -->
+```js
+const { Map } = require('immutable');
+const map1 = Map({ a: 1, b: 2, c: 3 });
+const map2 = map1.set('b', 50);
+map1.get('b') + " vs. " + map2.get('b'); // 2 vs. 50
 ```
 
 ### Browser
 
-To use `immutable` from a browser, download [dist/immutable.min.js](https://github.com/facebook/immutable-js/blob/master/dist/immutable.min.js)
-or use a CDN such as [CDNJS](https://cdnjs.com/libraries/immutable)
-or [jsDelivr](http://www.jsdelivr.com/#!immutable.js).
+Immutable.js has no dependencies, which makes it predictable to include in a Browser.
+
+It's highly recommended to use a module bundler like [webpack](https://webpack.github.io/),
+[rollup](https://rollupjs.org/), or
+[browserify](http://browserify.org/). The `immutable` npm module works
+without any additional consideration. All examples throughout the documentation
+will assume use of this kind of tool.
+
+Alternatively, Immutable.js may be directly included as a script tag. Download
+or link to a CDN such as [CDNJS](https://cdnjs.com/libraries/immutable)
+or [jsDelivr](https://www.jsdelivr.com/package/npm/immutable).
 
-Then, add it as a script tag to your page:
+Use a script tag to directly add `Immutable` to the global scope:
 
 ```html
 <script src="immutable.min.js"></script>
 <script>
-    var map1 = Immutable.Map({a:1, b:2, c:3});
-    var map2 = map1.set('b', 50);
-    map1.get('b'); // 2
-    map2.get('b'); // 50
+  var map1 = Immutable.Map({ a: 1, b: 2, c: 3 });
+  var map2 = map1.set('b', 50);
+  map1.get('b'); // 2
+  map2.get('b'); // 50
 </script>
 ```
 
-Or use an AMD loader (such as [RequireJS](http://requirejs.org/)):
+Or use an AMD-style loader (such as [RequireJS](http://requirejs.org/)):
 
-```javascript
+```js
 require(['./immutable.min.js'], function (Immutable) {
-    var map1 = Immutable.Map({a:1, b:2, c:3});
-    var map2 = map1.set('b', 50);
-    map1.get('b'); // 2
-    map2.get('b'); // 50
+  var map1 = Immutable.Map({ a: 1, b: 2, c: 3 });
+  var map2 = map1.set('b', 50);
+  map1.get('b'); // 2
+  map2.get('b'); // 50
 });
 ```
 
-If you're using [browserify](http://browserify.org/), the `immutable` npm module
-also works from the browser.
-
-### TypeScript
+### Flow & TypeScript
 
 Use these Immutable collections and sequences as you would use native
-collections in your [TypeScript](http://typescriptlang.org) programs while still taking
+collections in your [Flowtype](https://flowtype.org/) or [TypeScript](http://typescriptlang.org) programs while still taking
 advantage of type generics, error detection, and auto-complete in your IDE.
 
-Just add a reference with a relative path to the type declarations at the top
-of your file.
+Installing `immutable` via npm brings with it type definitions for Flow (v0.55.0 or higher)
+and TypeScript (v2.1.0 or higher), so you shouldn't need to do anything at all!
+
+#### Using TypeScript with Immutable.js v4
 
-```javascript
+Immutable.js type definitions embrace ES2015. While Immutable.js itself supports
+legacy browsers and environments, its type definitions require TypeScript's 2015
+lib. Include either `"target": "es2015"` or `"lib": "es2015"` in your
+`tsconfig.json`, or provide `--target es2015` or `--lib es2015` to the
+`tsc` command.
+
+<!-- runkit:activate -->
+```js
+const { Map } = require("immutable");
+const map1 = Map({ a: 1, b: 2, c: 3 });
+const map2 = map1.set('b', 50);
+map1.get('b') + " vs. " + map2.get('b'); // 2 vs. 50
+```
+
+#### Using TypeScript with Immutable.js v3 and earlier:
+
+Previous versions of Immutable.js include a reference file which you can include
+via relative path to the type definitions at the top of your file.
+
+```js
 ///<reference path='./node_modules/immutable/dist/immutable.d.ts'/>
-import Immutable = require('immutable');
+import Immutable from require('immutable');
 var map1: Immutable.Map<string, number>;
-map1 = Immutable.Map({a:1, b:2, c:3});
+map1 = Immutable.Map({ a: 1, b: 2, c: 3 });
 var map2 = map1.set('b', 50);
 map1.get('b'); // 2
 map2.get('b'); // 50
@@ -122,37 +148,48 @@ When data is passed from above rather than being subscribed to, and you're only
 interested in doing work when something has changed, you can use equality.
 
 Immutable collections should be treated as *values* rather than *objects*. While
-objects represents some thing which could change over time, a value represents
+objects represent some thing which could change over time, a value represents
 the state of that thing at a particular instance of time. This principle is most
 important to understanding the appropriate use of immutable data. In order to
 treat Immutable.js collections as values, it's important to use the
-`Immutable.is()` function or `.equals()` method to determine value equality
-instead of the `===` operator which determines object reference identity.
-
-```javascript
-var map1 = Immutable.Map({a:1, b:2, c:3});
-var map2 = map1.set('b', 2);
-assert(map1.equals(map2) === true);
-var map3 = map1.set('b', 50);
-assert(map1.equals(map3) === false);
+`Immutable.is()` function or `.equals()` method to determine *value equality*
+instead of the `===` operator which determines object *reference identity*.
+
+<!-- runkit:activate -->
+```js
+const { Map } = require('immutable');
+const map1 = Map({ a: 1, b: 2, c: 3 });
+const map2 = Map({ a: 1, b: 2, c: 3 });
+map1.equals(map2); // true
+map1 === map2; // false
 ```
 
-Note: As a performance optimization `Immutable` attempts to return the existing
+Note: As a performance optimization Immutable.js attempts to return the existing
 collection when an operation would result in an identical collection, allowing
 for using `===` reference equality to determine if something definitely has not
-changed. This can be extremely useful when used within memoization function
+changed. This can be extremely useful when used within a memoization function
 which would prefer to re-run the function if a deeper equality check could
 potentially be more costly. The `===` equality check is also used internally by
 `Immutable.is` and `.equals()` as a performance optimization.
 
+<!-- runkit:activate -->
+```js
+const { Map } = require('immutable');
+const map1 = Map({ a: 1, b: 2, c: 3 });
+const map2 = map1.set('b', 2); // Set to same value
+map1 === map2; // true
+```
+
 If an object is immutable, it can be "copied" simply by making another reference
 to it instead of copying the entire object. Because a reference is much smaller
 than the object itself, this results in memory savings and a potential boost in
 execution speed for programs which rely on copies (such as an undo-stack).
 
-```javascript
-var map1 = Immutable.Map({a:1, b:2, c:3});
-var clone = map1;
+<!-- runkit:activate -->
+```js
+const { Map } = require('immutable');
+const map = Map({ a: 1, b: 2, c: 3 });
+const mapCopy = map; // Look, "copies" are free!
 ```
 
 [React]: http://facebook.github.io/react/
@@ -162,31 +199,33 @@ var clone = map1;
 JavaScript-first API
 --------------------
 
-While `immutable` is inspired by Clojure, Scala, Haskell and other functional
+While Immutable.js is inspired by Clojure, Scala, Haskell and other functional
 programming environments, it's designed to bring these powerful concepts to
 JavaScript, and therefore has an Object-Oriented API that closely mirrors that
-of [ES6][] [Array][], [Map][], and [Set][].
+of [ES2015][] [Array][], [Map][], and [Set][].
 
-[ES6]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/New_in_JavaScript/ECMAScript_6_support_in_Mozilla
+[ES2015]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/New_in_JavaScript/ECMAScript_6_support_in_Mozilla
 [Array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array
 [Map]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map
 [Set]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set
 
 The difference for the immutable collections is that methods which would mutate
-the collection, like `push`, `set`, `unshift` or `splice` instead return a new
-immutable collection. Methods which return new arrays like `slice` or `concat`
+the collection, like `push`, `set`, `unshift` or `splice`, instead return a new
+immutable collection. Methods which return new arrays, like `slice` or `concat`,
 instead return new immutable collections.
 
-```javascript
-var list1 = Immutable.List.of(1, 2);
-var list2 = list1.push(3, 4, 5);
-var list3 = list2.unshift(0);
-var list4 = list1.concat(list2, list3);
-assert(list1.size === 2);
-assert(list2.size === 5);
-assert(list3.size === 6);
-assert(list4.size === 13);
-assert(list4.get(0) === 1);
+<!-- runkit:activate -->
+```js
+const { List } = require('immutable');
+const list1 = List([ 1, 2 ]);
+const list2 = list1.push(3, 4, 5);
+const list3 = list2.unshift(0);
+const list4 = list1.concat(list2, list3);
+assert.equal(list1.size, 2);
+assert.equal(list2.size, 5);
+assert.equal(list3.size, 6);
+assert.equal(list4.size, 13);
+assert.equal(list4.get(0), 1);
 ```
 
 Almost all of the methods on [Array][] will be found in similar form on
@@ -194,35 +233,46 @@ Almost all of the methods on [Array][] will be found in similar form on
 found on `Immutable.Set`, including collection operations like `forEach()`
 and `map()`.
 
-```javascript
-var alpha = Immutable.Map({a:1, b:2, c:3, d:4});
+<!-- runkit:activate -->
+```js
+const { Map } = require('immutable');
+const alpha = Map({ a: 1, b: 2, c: 3, d: 4 });
 alpha.map((v, k) => k.toUpperCase()).join();
 // 'A,B,C,D'
 ```
 
-### Accepts raw JavaScript objects.
+### Convert from raw JavaScript objects and arrays.
 
-Designed to inter-operate with your existing JavaScript, `immutable`
-accepts plain JavaScript Arrays and Objects anywhere a method expects an
-`Iterable` with no performance penalty.
+Designed to inter-operate with your existing JavaScript, Immutable.js
+accepts plain JavaScript Arrays and Objects anywhere a method expects a
+`Collection`.
 
-```javascript
-var map1 = Immutable.Map({a:1, b:2, c:3, d:4});
-var map2 = Immutable.Map({c:10, a:20, t:30});
-var obj = {d:100, o:200, g:300};
-var map3 = map1.merge(map2, obj);
+<!-- runkit:activate -->
+```js
+const { Map, List } = require('immutable');
+const map1 = Map({ a: 1, b: 2, c: 3, d: 4 });
+const map2 = Map({ c: 10, a: 20, t: 30 });
+const obj = { d: 100, o: 200, g: 300 };
+const map3 = map1.merge(map2, obj);
 // Map { a: 20, b: 2, c: 10, d: 100, t: 30, o: 200, g: 300 }
+const list1 = List([ 1, 2, 3 ]);
+const list2 = List([ 4, 5, 6 ]);
+const array = [ 7, 8, 9 ];
+const list3 = list1.concat(list2, array);
+// List [ 1, 2, 3, 4, 5, 6, 7, 8, 9 ]
 ```
 
-This is possible because `immutable` can treat any JavaScript Array or Object
-as an Iterable. You can take advantage of this in order to get sophisticated
+This is possible because Immutable.js can treat any JavaScript Array or Object
+as a Collection. You can take advantage of this in order to get sophisticated
 collection methods on JavaScript Objects, which otherwise have a very sparse
 native API. Because Seq evaluates lazily and does not cache intermediate
 results, these operations can be extremely efficient.
 
-```javascript
-var myObject = {a:1,b:2,c:3};
-Immutable.Seq(myObject).map(x => x * x).toObject();
+<!-- runkit:activate -->
+```js
+const { Seq } = require('immutable');
+const myObject = { a: 1, b: 2, c: 3 };
+Seq(myObject).map(x => x * x).toObject();
 // { a: 1, b: 4, c: 9 }
 ```
 
@@ -230,15 +280,16 @@ 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 -->
 ```js
-var obj = { 1: "one" };
-Object.keys(obj); // [ "1" ]
-obj["1"]; // "one"
-obj[1];   // "one"
-
-var map = Immutable.fromJS(obj);
-map.get("1"); // "one"
-map.get(1);   // undefined
+const { fromJS } = require('immutable');
+
+const obj = { 1: "one" };
+console.log(Object.keys(obj)); // [ "1" ]
+console.log(obj["1"], obj[1]); // "one", "one"
+
+const map = fromJS(obj);
+console.log(map.get("1"), map.get(1)); // "one", undefined
 ```
 
 Property access for JavaScript Objects first converts the key to a string, but
@@ -248,37 +299,53 @@ not altered.
 
 ### Converts back to raw JavaScript objects.
 
-All `immutable` Iterables can be converted to plain JavaScript Arrays and
+All Immutable.js Collections can be converted to plain JavaScript Arrays and
 Objects shallowly with `toArray()` and `toObject()` or deeply with `toJS()`.
-All Immutable Iterables also implement `toJSON()` allowing them to be passed to
-`JSON.stringify` directly.
-
-```javascript
-var deep = Immutable.Map({ a: 1, b: 2, c: Immutable.List.of(3, 4, 5) });
-deep.toObject() // { a: 1, b: 2, c: List [ 3, 4, 5 ] }
-deep.toArray() // [ 1, 2, List [ 3, 4, 5 ] ]
-deep.toJS() // { a: 1, b: 2, c: [ 3, 4, 5 ] }
-JSON.stringify(deep) // '{"a":1,"b":2,"c":[3,4,5]}'
+All Immutable Collections also implement `toJSON()` allowing them to be passed
+to `JSON.stringify` directly. They also respect the custom `toJSON()` methods of
+nested objects.
+
+<!-- runkit:activate -->
+```js
+const { Map, List } = require('immutable');
+const deep = Map({ a: 1, b: 2, c: List([ 3, 4, 5 ]) });
+console.log(deep.toObject()); // { a: 1, b: 2, c: List [ 3, 4, 5 ] }
+console.log(deep.toArray()); // [ 1, 2, List [ 3, 4, 5 ] ]
+console.log(deep.toJS()); // { a: 1, b: 2, c: [ 3, 4, 5 ] }
+JSON.stringify(deep); // '{"a":1,"b":2,"c":[3,4,5]}'
 ```
 
-### Embraces ES6
+### Embraces ES2015
+
+Immutable.js supports all JavaScript environments, including legacy
+browsers (even IE8). However it also takes advantage of features added to
+JavaScript in [ES2015][], the latest standard version of JavaScript, including
+[Iterators][], [Arrow Functions][], [Classes][], and [Modules][]. It's inspired
+by the native [Map][] and [Set][] collections added to ES2015.
+
+All examples in the Documentation are presented in ES2015. To run in all
+browsers, they need to be translated to ES5.
 
-`Immutable` takes advantage of features added to JavaScript in [ES6][],
-the latest standard version of ECMAScript (JavaScript), including [Iterators][],
-[Arrow Functions][], [Classes][], and [Modules][]. It's also inspired by the
-[Map][] and [Set][] collections added to ES6. The library is "transpiled" to ES3
-in order to support all modern browsers.
+```js
+// ES2015
+const mapped = foo.map(x => x * x);
+// ES5
+var mapped = foo.map(function (x) { return x * x; });
+```
 
-All examples are presented in ES6. To run in all browsers, they need to be
-translated to ES3.
+All Immutable.js collections are [Iterable][Iterators], which allows them to be
+used anywhere an Iterable is expected, such as when spreading into an Array.
 
+<!-- runkit:activate -->
 ```js
-// ES6
-foo.map(x => x * x);
-// ES3
-foo.map(function (x) { return x * x; });
+const { List } = require('immutable');
+const aList = List([ 1, 2, 3 ]);
+const anArray = [ 0, ...aList, 4, 5 ]; // [ 0, 1, 2, 3, 4, 5 ]
 ```
 
+Note: A Collection is always iterated in the same order, however that order may
+not always be well defined, as is the case for the `Map` and `Set`.
+
 [Iterators]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/The_Iterator_protocol
 [Arrow Functions]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/Arrow_functions
 [Classes]: http://wiki.ecmascript.org/doku.php?id=strawman:maximally_minimal_classes
@@ -288,11 +355,13 @@ foo.map(function (x) { return x * x; });
 Nested Structures
 -----------------
 
-The collections in `immutable` are intended to be nested, allowing for deep
+The collections in Immutable.js are intended to be nested, allowing for deep
 trees of data, similar to JSON.
 
-```javascript
-var nested = Immutable.fromJS({a:{b:{c:[3,4,5]}}});
+<!-- runkit:activate -->
+```js
+const { fromJS } = require('immutable');
+const nested = fromJS({ a: { b: { c: [ 3, 4, 5 ] } } });
 // Map { a: Map { b: Map { c: List [ 3, 4, 5 ] } } }
 ```
 
@@ -300,91 +369,119 @@ A few power-tools allow for reading and operating on nested data. The
 most useful are `mergeDeep`, `getIn`, `setIn`, and `updateIn`, found on `List`,
 `Map` and `OrderedMap`.
 
-```javascript
-var nested2 = nested.mergeDeep({a:{b:{d:6}}});
+<!-- runkit:activate -->
+```js
+const { fromJS } = require('immutable');
+const nested = fromJS({ a: { b: { c: [ 3, 4, 5 ] } } });
+
+const nested2 = nested.mergeDeep({ a: { b: { d: 6 } } });
 // Map { a: Map { b: Map { c: List [ 3, 4, 5 ], d: 6 } } }
-```
 
-```javascript
-nested2.getIn(['a', 'b', 'd']); // 6
+console.log(nested2.getIn([ 'a', 'b', 'd' ])); // 6
 
-var nested3 = nested2.updateIn(['a', 'b', 'd'], value => value + 1);
+const nested3 = nested2.updateIn([ 'a', 'b', 'd' ], value => value + 1);
+console.log(nested3);
 // Map { a: Map { b: Map { c: List [ 3, 4, 5 ], d: 7 } } }
 
-var nested4 = nested3.updateIn(['a', 'b', 'c'], list => list.push(6));
+const nested4 = nested3.updateIn([ 'a', 'b', 'c' ], list => list.push(6));
 // Map { a: Map { b: Map { c: List [ 3, 4, 5, 6 ], d: 7 } } }
 ```
 
 
-Lazy Seq
---------
-
-`Seq` describes a lazy operation, allowing them to efficiently chain
-use of all the Iterable methods (such as `map` and `filter`).
-
-**Seq is immutable** — Once a Seq is created, it cannot be
-changed, appended to, rearranged or otherwise modified. Instead, any mutative
-method called on a Seq will return a new Seq.
-
-**Seq is lazy** — Seq does as little work as necessary to respond to any
-method call.
-
-For example, the following does not perform any work, because the resulting
-Seq is never used:
-
-    var oddSquares = Immutable.Seq.of(1,2,3,4,5,6,7,8)
-      .filter(x => x % 2).map(x => x * x);
+Equality treats Collections as Values
+-------------------------------------
 
-Once the Seq is used, it performs only the work necessary. In this
-example, no intermediate arrays are ever created, filter is called three times,
-and map is only called twice:
+Immutable.js collections are treated as pure data *values*. Two immutable
+collections are considered *value equal* (via `.equals()` or `is()`) if they
+represent the same collection of values. This differs from JavaScript's typical
+*reference equal* (via `===` or `==`) for Objects and Arrays which only
+determines if two variables represent references to the same object instance.
 
-    console.log(oddSquares.get(1)); // 9
+Consider the example below where two identical `Map` instances are not
+*reference equal* but are *value equal*.
 
-Any collection can be converted to a lazy Seq with `.toSeq()`.
+<!-- runkit:activate -->
+```js
+// First consider:
+const obj1 = { a: 1, b: 2, c: 3 };
+const obj2 = { a: 1, b: 2, c: 3 };
+obj1 !== obj2; // two different instances are always not equal with ===
+
+const { Map, is } = require('immutable');
+const map1 = Map({ a: 1, b: 2, c: 3 });
+const map2 = Map({ a: 1, b: 2, c: 3 });
+map1 !== map2; // two different instances are not reference-equal
+map1.equals(map2); // but are value-equal if they have the same values
+is(map1, map2); // alternatively can use the is() function
+```
 
-    var seq = Immutable.Map({a:1, b:1, c:1}).toSeq();
+Value equality allows Immutable.js collections to be used as keys in Maps or
+values in Sets, and retrieved with different but equivalent collections:
 
-Seq allow for the efficient chaining of sequence operations, especially when
-converting to a different concrete type (such as to a JS object):
+<!-- runkit:activate -->
+```js
+const { Map, Set } = require('immutable');
+const map1 = Map({ a: 1, b: 2, c: 3 });
+const map2 = Map({ a: 1, b: 2, c: 3 });
+const set = Set().add(map1);
+set.has(map2); // true because these are value-equal
+```
 
-    seq.flip().map(key => key.toUpperCase()).flip().toObject();
-    // Map { A: 1, B: 1, C: 1 }
+Note: `is()` uses the same measure of equality as [Object.is][] for scalar
+strings and numbers, but uses value equality for Immutable collections,
+determining if both are immutable and all keys and values are equal
+using the same measure of equality.
 
-As well as expressing logic that would otherwise seem memory-limited:
+[Object.is]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/is
 
-    Immutable.Range(1, Infinity)
-      .skip(1000)
-      .map(n => -n)
-      .filter(n => n % 2 === 0)
-      .take(2)
-      .reduce((r, n) => r * n, 1);
-    // 1006008
+#### Performance tradeoffs
 
-Note: An iterable is always iterated in the same order, however that order may
-not always be well defined, as is the case for the `Map`.
+While value equality is useful in many circumstances, it has different
+performance characteristics than reference equality. Understanding these
+tradeoffs may help you decide which to use in each case, especially when used
+to memoize some operation.
 
+When comparing two collections, value equality may require considering every
+item in each collection, on an `O(N)` time complexity. For large collections of
+values, this could become a costly operation. Though if the two are not equal
+and hardly similar, the inequality is determined very quickly. In contrast, when
+comparing two collections with reference equality, only the initial references
+to memory need to be compared which is not based on the size of the collections,
+which has an `O(1)` time complexity. Checking reference equality is always very
+fast, however just because two collections are not reference-equal does not rule
+out the possibility that they may be value-equal.
 
-Equality treats Collections as Data
------------------------------------
+#### Return self on no-op optimization
 
-`Immutable` provides equality which treats immutable data structures as pure
-data, performing a deep equality check if necessary.
+When possible, Immutable.js avoids creating new objects for updates where no
+change in *value* occurred, to allow for efficient *reference equality* checking
+to quickly determine if no change occurred.
 
-```javascript
-var map1 = Immutable.Map({a:1, b:1, c:1});
-var map2 = Immutable.Map({a:1, b:1, c:1});
-assert(map1 !== map2); // two different instances
-assert(Immutable.is(map1, map2)); // have equivalent values
-assert(map1.equals(map2)); // alternatively use the equals method
+<!-- runkit:activate -->
+```js
+const { Map } = require('immutable');
+const originalMap = Map({ a: 1, b: 2, c: 3 });
+const updatedMap = originalMap.set('b', 2);
+updatedMap === originalMap; // No-op .set() returned the original reference.
 ```
 
-`Immutable.is()` uses the same measure of equality as [Object.is][]
-including if both are immutable and all keys and values are equal
-using the same measure of equality.
-
-[Object.is]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/is
+However updates which do result in a change will return a new reference. Each
+of these operations occur independently, so two similar updates will not return
+the same reference:
 
+<!-- runkit:activate -->
+```js
+const { Map } = require('immutable');
+const originalMap = Map({ a: 1, b: 2, c: 3 });
+const updatedMap = originalMap.set('b', 1000);
+// New instance, leaving the original immutable.
+updatedMap !== originalMap;
+const anotherUpdatedMap = originalMap.set('b', 1000);
+// Despite both the results of the same operation, each created a new reference.
+anotherUpdatedMap !== updatedMap;
+// However the two are value equal.
+anotherUpdatedMap.equals(updatedMap);
+```
 
 Batching Mutations
 ------------------
@@ -398,24 +495,26 @@ Batching Mutations
 
 Applying a mutation to create a new immutable object results in some overhead,
 which can add up to a minor performance penalty. If you need to apply a series
-of mutations locally before returning, `Immutable` gives you the ability to
+of mutations locally before returning, Immutable.js gives you the ability to
 create a temporary mutable (transient) copy of a collection and apply a batch of
 mutations in a performant manner by using `withMutations`. In fact, this is
-exactly how  `Immutable` applies complex mutations itself.
+exactly how  Immutable.js applies complex mutations itself.
 
 As an example, building `list2` results in the creation of 1, not 3, new
 immutable Lists.
 
-```javascript
-var list1 = Immutable.List.of(1,2,3);
-var list2 = list1.withMutations(function (list) {
+<!-- runkit:activate -->
+```js
+const { List } = require('immutable');
+const list1 = List([ 1, 2, 3 ]);
+const list2 = list1.withMutations(function (list) {
   list.push(4).push(5).push(6);
 });
-assert(list1.size === 3);
-assert(list2.size === 6);
+assert.equal(list1.size, 3);
+assert.equal(list2.size, 6);
 ```
 
-Note: `immutable` also provides `asMutable` and `asImmutable`, but only
+Note: Immutable.js also provides `asMutable` and `asImmutable`, but only
 encourages their use when `withMutations` will not suffice. Use caution to not
 return a mutable copy, which could result in undesired behavior.
 
@@ -426,6 +525,76 @@ and `splice` will always return new immutable data-structures and never mutate
 a mutable collection.
 
 
+Lazy Seq
+--------
+
+`Seq` describes a lazy operation, allowing them to efficiently chain
+use of all the higher-order collection methods (such as `map` and `filter`)
+by not creating intermediate collections.
+
+**Seq is immutable** — Once a Seq is created, it cannot be
+changed, appended to, rearranged or otherwise modified. Instead, any mutative
+method called on a `Seq` will return a new `Seq`.
+
+**Seq is lazy** — `Seq` does as little work as necessary to respond to any
+method call. Values are often created during iteration, including implicit
+iteration when reducing or converting to a concrete data structure such as
+a `List` or JavaScript `Array`.
+
+For example, the following performs no work, because the resulting
+`Seq`'s values are never iterated:
+
+```js
+const { Seq } = require('immutable');
+const oddSquares = Seq([ 1, 2, 3, 4, 5, 6, 7, 8 ])
+  .filter(x => x % 2 !== 0)
+  .map(x => x * x);
+```
+
+Once the `Seq` is used, it performs only the work necessary. In this
+example, no intermediate arrays are ever created, filter is called three
+times, and map is only called once:
+
+```js
+oddSquares.get(1); // 9
+```
+
+Any collection can be converted to a lazy Seq with `Seq()`.
+
+<!-- runkit:activate -->
+```js
+const { Map, Seq } = require('immutable');
+const map = Map({ a: 1, b: 2, c: 3 });
+const lazySeq = Seq(map);
+```
+
+`Seq` allows for the efficient chaining of operations, allowing for the
+expression of logic that can otherwise be very tedious:
+
+```js
+lazySeq
+  .flip()
+  .map(key => key.toUpperCase())
+  .flip();
+// Seq { A: 1, B: 1, C: 1 }
+```
+
+As well as expressing logic that would otherwise seem memory or time
+limited, for example `Range` is a special kind of Lazy sequence.
+
+<!-- runkit:activate -->
+```js
+const { Range } = require('immutable');
+Range(1, Infinity)
+  .skip(1000)
+  .map(n => -n)
+  .filter(n => n % 2 === 0)
+  .take(2)
+  .reduce((r, n) => r * n, 1);
+// 1006008
+```
+
+
 Documentation
 -------------
 
@@ -441,7 +610,7 @@ contains articles on specific topics. Can't find something? Open an [issue](http
 Testing
 -------
 
-If you are using the [Chai Assertion Library](http://chaijs.com/), [Chai Immutable](https://github.com/astorije/chai-immutable) provides a set of assertions to use against `Immutable` collections.
+If you are using the [Chai Assertion Library](http://chaijs.com/), [Chai Immutable](https://github.com/astorije/chai-immutable) provides a set of assertions to use against Immutable.js collections.
 
 
 Contribution
@@ -449,7 +618,7 @@ Contribution
 
 Use [Github issues](https://github.com/facebook/immutable-js/issues) for requests.
 
-We actively welcome pull requests, learn how to [contribute](./CONTRIBUTING.md).
+We actively welcome pull requests, learn how to [contribute](https://github.com/facebook/immutable-js/blob/master/.github/CONTRIBUTING.md).
 
 
 Changelog