immutable 4.0.0-rc.1 → 4.0.0-rc.14

package/README.md

@@ -1,7 +1,6 @@
-Immutable collections for JavaScript
-====================================
+# Immutable collections for JavaScript
 
-[![Build Status](https://travis-ci.org/facebook/immutable-js.svg?branch=master)](https://travis-ci.org/facebook/immutable-js)
+[![Build Status](https://github.com/immutable-js/immutable-js/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/immutable-js/immutable-js/actions/workflows/ci.yml?query=branch%3Amain) [Chat on slack](https://immutable-js.slack.com)
 
 [Immutable][] data cannot be changed once created, leading to much simpler
 application development, no defensive copying, and enabling advanced memoization
@@ -16,22 +15,20 @@ 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`.
 
 Want to hear more? Watch the presentation about Immutable.js:
 
-<a href="https://youtu.be/I7IdS-PbEgI" target="_blank" alt="Immutable Data and React"><img src="https://img.youtube.com/vi/I7IdS-PbEgI/0.jpg" /></a>
+[![Immutable Data and React](website/public/Immutable-Data-and-React-YouTube.png)](https://youtu.be/I7IdS-PbEgI)
 
-[Persistent]: http://en.wikipedia.org/wiki/Persistent_data_structure
-[Immutable]: http://en.wikipedia.org/wiki/Immutable_object
-[hash maps tries]: http://en.wikipedia.org/wiki/Hash_array_mapped_trie
-[vector tries]: http://hypirion.com/musings/understanding-persistent-vector-pt-1
+[Persistent]: https://en.wikipedia.org/wiki/Persistent_data_structure
+[Immutable]: https://en.wikipedia.org/wiki/Immutable_object
+[hash maps tries]: https://en.wikipedia.org/wiki/Hash_array_mapped_trie
+[vector tries]: https://hypirion.com/musings/understanding-persistent-vector-pt-1
 
-
-Getting started
----------------
+## Getting started
 
 Install `immutable` using npm.
 
@@ -39,70 +36,102 @@ Install `immutable` using npm.
 npm install immutable
 ```
 
+Or install using yarn.
+
+```shell
+yarn add 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](https://browserify.org/). The `immutable` npm module works
+without any additional consideration. All examples throughout the documentation
+will assume use of this kind of tool.
 
-Then, add it as a script tag to your page:
+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).
+
+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](https://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](https://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!
 
-```javascript
+#### Using TypeScript with Immutable.js v4
+
+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
 ```
 
-
-The case for Immutability
--------------------------
+## The case for Immutability
 
 Much of what makes application development difficult is tracking mutation and
 maintaining state. Developing with immutable data encourages you to think
@@ -121,23 +150,25 @@ and especially well with an application designed using the ideas of [Flux][].
 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
+Immutable collections should be treated as _values_ rather than _objects_. While
 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 a memoization function
@@ -145,48 +176,62 @@ 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/
-[Flux]: http://facebook.github.io/flux/docs/overview.html
+[React]: https://reactjs.org/
+[Flux]: https://facebook.github.io/flux/docs/in-depth-overview/
 
 
-JavaScript-first API
---------------------
+## 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
-[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
+[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 +239,51 @@ 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.js
+accepts plain JavaScript Arrays and Objects anywhere a method expects a
+`Collection`.
 
-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.
+<!-- runkit:activate -->
 
-```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);
+```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,69 +291,92 @@ 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
 since Immutable Map keys can be of any type the argument to `get()` is
 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 IE11). 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.
+
+```js
+// ES2015
+const mapped = foo.map(x => x * x);
+// ES5
+var mapped = foo.map(function (x) {
+  return x * x;
+});
+```
 
-`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.
+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.
 
-All examples are presented in ES6. To run in all browsers, they need to be
-translated to ES3.
+<!-- 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
-[Modules]: http://www.2ality.com/2014/09/es6-modules-final.html
+[Classes]: https://wiki.ecmascript.org/doku.php?id=strawman:maximally_minimal_classes
+[Modules]: https://www.2ality.com/2014/09/es6-modules-final.html
 
 
-Nested Structures
------------------
+## 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,92 +384,124 @@ 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 } } }
 
-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 } } }
 ```
 
+## Equality treats Collections as Values
 
-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.
+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.
 
-**Seq is lazy** — Seq does as little work as necessary to respond to any
-method call.
+Consider the example below where two identical `Map` instances are not
+_reference equal_ but are _value equal_.
 
-For example, the following does not perform any work, because the resulting
-Seq is never used:
+<!-- runkit:activate -->
 
-    var oddSquares = Immutable.Seq.of(1,2,3,4,5,6,7,8)
-      .filter(x => x % 2).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
+// 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
+```
 
-    console.log(oddSquares.get(1)); // 9
+Value equality allows Immutable.js collections to be used as keys in Maps or
+values in Sets, and retrieved with different but equivalent collections:
 
-Any collection can be converted to a lazy Seq with `.toSeq()`.
+<!-- runkit:activate -->
 
-    var seq = Immutable.Map({a:1, b:1, c:1}).toSeq();
+```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 allows for the efficient chaining of sequence operations, especially when
-converting to a different concrete type (such as to a JS object):
+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.
 
-    seq.flip().map(key => key.toUpperCase()).flip().toObject();
-    // { A: 1, B: 1, C: 1 }
+[object.is]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/is
 
-As well as expressing logic that would otherwise seem memory-limited:
+#### Performance tradeoffs
 
-    Immutable.Range(1, Infinity)
-      .skip(1000)
-      .map(n => -n)
-      .filter(n => n % 2 === 0)
-      .take(2)
-      .reduce((r, n) => r * n, 1);
-    // 1006008
+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.
 
-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`.
+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.
 
+#### Return self on no-op optimization
 
-Equality treats Collections as Data
------------------------------------
+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.
 
-`Immutable` provides equality which treats immutable data structures as pure
-data, performing a deep equality check if necessary.
+<!-- runkit:activate -->
 
-```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
+```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.
+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:
 
-[Object.is]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/is
+<!-- 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
-------------------
+## Batching Mutations
 
 > If a tree falls in the woods, does it make a sound?
 >
@@ -396,68 +512,139 @@ 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.
 
-*Important!*: Only a select few methods can be used in `withMutations` including
+_Important!_: Only a select few methods can be used in `withMutations` including
 `set`, `push` and `pop`. These methods can be applied directly against a
 persistent data-structure where other methods like `map`, `filter`, `sort`,
 and `splice` will always return new immutable data-structures and never mutate
 a mutable collection.
 
+## Lazy Seq
 
-Documentation
--------------
+`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.
 
-[Read the docs](http://facebook.github.io/immutable-js/docs/) and eat your vegetables.
+**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`.
 
-Docs are automatically generated from [Immutable.d.ts](https://github.com/facebook/immutable-js/blob/master/type-definitions/Immutable.d.ts).
-Please contribute!
+**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`.
 
-Also, don't miss the [Wiki](https://github.com/facebook/immutable-js/wiki) which
-contains articles on specific topics. Can't find something? Open an [issue](https://github.com/facebook/immutable-js/issues).
+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()`.
 
-Testing
--------
+<!-- runkit:activate -->
 
-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.
+```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:
 
-Contribution
-------------
+```js
+lazySeq
+  .flip()
+  .map(key => key.toUpperCase())
+  .flip();
+// Seq { A: 1, B: 2, C: 3 }
+```
 
-Use [Github issues](https://github.com/facebook/immutable-js/issues) for requests.
+As well as expressing logic that would otherwise seem memory or time
+limited, for example `Range` is a special kind of Lazy sequence.
 
-We actively welcome pull requests, learn how to [contribute](./CONTRIBUTING.md).
+<!-- 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
+```
 
-Changelog
----------
+## Documentation
 
-Changes are tracked as [Github releases](https://github.com/facebook/immutable-js/releases).
+## Documentation
 
+[Read the docs](https://immutable-js.com) and eat your vegetables.
 
-Thanks
-------
+Docs are automatically generated from [Immutable.d.ts](https://github.com/immutable-js/immutable-js/blob/main/type-definitions/Immutable.d.ts).
+Please contribute!
+
+Also, don't miss the [Wiki](https://github.com/immutable-js/immutable-js/wiki) which
+contains articles on specific topics. Can't find something? Open an [issue](https://github.com/immutable-js/immutable-js/issues).
+
+## Testing
+
+If you are using the [Chai Assertion Library](https://chaijs.com/), [Chai Immutable](https://github.com/astorije/chai-immutable) provides a set of assertions to use against Immutable.js collections.
+
+## Contribution
+
+## Contribution
+
+Use [Github issues](https://github.com/immutable-js/immutable-js/issues) for requests.
+
+We actively welcome pull requests, learn how to [contribute](https://github.com/immutable-js/immutable-js/blob/main/.github/CONTRIBUTING.md).
+
+Immutable.js is maintained within the [Contributor Covenant's Code of Conduct](https://www.contributor-covenant.org/version/2/0/code_of_conduct/).
+
+We actively welcome pull requests, learn how to [contribute](https://github.com/immutable-js/immutable-js/blob/main/.github/CONTRIBUTING.md).
+
+## Changelog
+
+Changes are tracked as [Github releases](https://github.com/immutable-js/immutable-js/releases).
+
+## Thanks
 
 [Phil Bagwell](https://www.youtube.com/watch?v=K2NYwP90bNs), for his inspiration
 and research in persistent data structures.
@@ -465,8 +652,6 @@ and research in persistent data structures.
 [Hugh Jackson](https://github.com/hughfdjackson/), for providing the npm package
 name. If you're looking for his unsupported package, see [this repository](https://github.com/hughfdjackson/immutable).
 
+## License
 
-License
--------
-
-`Immutable` is [BSD-licensed](https://github.com/facebook/immutable-js/blob/master/LICENSE). We also provide an additional [patent grant](https://github.com/facebook/immutable-js/blob/master/PATENTS).
+Immutable.js is [MIT-licensed](./LICENSE).