immutable 5.1.1 → 5.1.3

package/README.md

@@ -73,10 +73,8 @@ bun add immutable
 
 Then require it into any module.
 
-<!-- runkit:activate -->
-
 ```js
-const { Map } = require('immutable');
+import { Map } from '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
@@ -136,10 +134,8 @@ 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');
+import { Map } from '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
@@ -187,10 +183,8 @@ 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_.
 
-<!-- runkit:activate -->
-
 ```js
-const { Map } = require('immutable');
+import { Map } from 'immutable';
 const map1 = Map({ a: 1, b: 2, c: 3 });
 const map2 = Map({ a: 1, b: 2, c: 3 });
 map1.equals(map2); // true
@@ -205,10 +199,8 @@ 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');
+import { Map } from 'immutable';
 const map1 = Map({ a: 1, b: 2, c: 3 });
 const map2 = map1.set('b', 2); // Set to same value
 map1 === map2; // true
@@ -219,10 +211,8 @@ 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).
 
-<!-- runkit:activate -->
-
 ```js
-const { Map } = require('immutable');
+import { Map } from 'immutable';
 const map = Map({ a: 1, b: 2, c: 3 });
 const mapCopy = map; // Look, "copies" are free!
 ```
@@ -230,7 +220,6 @@ const mapCopy = map; // Look, "copies" are free!
 [React]: https://reactjs.org/
 [Flux]: https://facebook.github.io/flux/docs/in-depth-overview/
 
-
 ## JavaScript-first API
 
 While Immutable.js is inspired by Clojure, Scala, Haskell and other functional
@@ -248,10 +237,8 @@ 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.
 
-<!-- runkit:activate -->
-
 ```js
-const { List } = require('immutable');
+import { List } from 'immutable';
 const list1 = List([1, 2]);
 const list2 = list1.push(3, 4, 5);
 const list3 = list2.unshift(0);
@@ -268,10 +255,8 @@ 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()`.
 
-<!-- runkit:activate -->
-
 ```js
-const { Map } = require('immutable');
+import { Map } from 'immutable';
 const alpha = Map({ a: 1, b: 2, c: 3, d: 4 });
 alpha.map((v, k) => k.toUpperCase()).join();
 // 'A,B,C,D'
@@ -283,10 +268,8 @@ Designed to inter-operate with your existing JavaScript, Immutable.js
 accepts plain JavaScript Arrays and Objects anywhere a method expects a
 `Collection`.
 
-<!-- runkit:activate -->
-
 ```js
-const { Map, List } = require('immutable');
+import { Map, List } from '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 };
@@ -305,13 +288,11 @@ 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.
 
-<!-- runkit:activate -->
-
 ```js
-const { Seq } = require('immutable');
+import { Seq } from 'immutable';
 const myObject = { a: 1, b: 2, c: 3 };
 Seq(myObject)
-  .map(x => x * x)
+  .map((x) => x * x)
   .toObject();
 // { a: 1, b: 4, c: 9 }
 ```
@@ -320,10 +301,8 @@ 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
-const { fromJS } = require('immutable');
+import { fromJS } from 'immutable';
 
 const obj = { 1: 'one' };
 console.log(Object.keys(obj)); // [ "1" ]
@@ -345,10 +324,8 @@ 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');
+import { Map, List } from '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 ] ]
@@ -369,7 +346,7 @@ browsers, they need to be translated to ES5.
 
 ```js
 // ES2015
-const mapped = foo.map(x => x * x);
+const mapped = foo.map((x) => x * x);
 // ES5
 var mapped = foo.map(function (x) {
   return x * x;
@@ -379,10 +356,8 @@ var mapped = foo.map(function (x) {
 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
-const { List } = require('immutable');
+import { List } from 'immutable';
 const aList = List([1, 2, 3]);
 const anArray = [0, ...aList, 4, 5]; // [ 0, 1, 2, 3, 4, 5 ]
 ```
@@ -395,16 +370,13 @@ not always be well defined, as is the case for the `Map` and `Set`.
 [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
 
 The collections in Immutable.js are intended to be nested, allowing for deep
 trees of data, similar to JSON.
 
-<!-- runkit:activate -->
-
 ```js
-const { fromJS } = require('immutable');
+import { fromJS } from 'immutable';
 const nested = fromJS({ a: { b: { c: [3, 4, 5] } } });
 // Map { a: Map { b: Map { c: List [ 3, 4, 5 ] } } }
 ```
@@ -413,10 +385,8 @@ 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`.
 
-<!-- runkit:activate -->
-
 ```js
-const { fromJS } = require('immutable');
+import { fromJS } from 'immutable';
 const nested = fromJS({ a: { b: { c: [3, 4, 5] } } });
 
 const nested2 = nested.mergeDeep({ a: { b: { d: 6 } } });
@@ -424,11 +394,11 @@ const nested2 = nested.mergeDeep({ a: { b: { d: 6 } } });
 
 console.log(nested2.getIn(['a', 'b', 'd'])); // 6
 
-const 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 } } }
 
-const 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 } } }
 ```
 
@@ -443,15 +413,13 @@ determines if two variables represent references to the same object instance.
 Consider the example below where two identical `Map` instances are not
 _reference equal_ but are _value equal_.
 
-<!-- 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');
+import { Map, is } from '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
@@ -462,10 +430,8 @@ is(map1, map2); // alternatively can use the is() function
 Value equality allows Immutable.js collections to be used as keys in Maps or
 values in Sets, and retrieved with different but equivalent collections:
 
-<!-- runkit:activate -->
-
 ```js
-const { Map, Set } = require('immutable');
+import { Map, Set } from 'immutable';
 const map1 = Map({ a: 1, b: 2, c: 3 });
 const map2 = Map({ a: 1, b: 2, c: 3 });
 const set = Set().add(map1);
@@ -502,10 +468,8 @@ 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.
 
-<!-- runkit:activate -->
-
 ```js
-const { Map } = require('immutable');
+import { Map } from '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.
@@ -515,10 +479,8 @@ 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');
+import { Map } from 'immutable';
 const originalMap = Map({ a: 1, b: 2, c: 3 });
 const updatedMap = originalMap.set('b', 1000);
 // New instance, leaving the original immutable.
@@ -549,10 +511,8 @@ exactly how Immutable.js applies complex mutations itself.
 As an example, building `list2` results in the creation of 1, not 3, new
 immutable Lists.
 
-<!-- runkit:activate -->
-
 ```js
-const { List } = require('immutable');
+import { List } from 'immutable';
 const list1 = List([1, 2, 3]);
 const list2 = list1.withMutations(function (list) {
   list.push(4).push(5).push(6);
@@ -590,10 +550,10 @@ For example, the following performs no work, because the resulting
 `Seq`'s values are never iterated:
 
 ```js
-const { Seq } = require('immutable');
+import { Seq } from 'immutable';
 const oddSquares = Seq([1, 2, 3, 4, 5, 6, 7, 8])
-  .filter(x => x % 2 !== 0)
-  .map(x => x * x);
+  .filter((x) => x % 2 !== 0)
+  .map((x) => x * x);
 ```
 
 Once the `Seq` is used, it performs only the work necessary. In this
@@ -606,10 +566,8 @@ oddSquares.get(1); // 9
 
 Any collection can be converted to a lazy Seq with `Seq()`.
 
-<!-- runkit:activate -->
-
 ```js
-const { Map, Seq } = require('immutable');
+import { Map, Seq } from 'immutable';
 const map = Map({ a: 1, b: 2, c: 3 });
 const lazySeq = Seq(map);
 ```
@@ -620,7 +578,7 @@ expression of logic that can otherwise be very tedious:
 ```js
 lazySeq
   .flip()
-  .map(key => key.toUpperCase())
+  .map((key) => key.toUpperCase())
   .flip();
 // Seq { A: 1, B: 2, C: 3 }
 ```
@@ -628,14 +586,12 @@ lazySeq
 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');
+import { Range } from 'immutable';
 Range(1, Infinity)
   .skip(1000)
-  .map(n => -n)
-  .filter(n => n % 2 === 0)
+  .map((n) => -n)
+  .filter((n) => n % 2 === 0)
   .take(2)
   .reduce((r, n) => r * n, 1);
 // 1006008
@@ -646,8 +602,8 @@ Range(1, Infinity)
 The `filter()`, `groupBy()`, and `partition()` methods are similar in that they
 all divide a collection into parts based on applying a function to each element.
 All three call the predicate or grouping function once for each item in the
-input collection.  All three return zero or more collections of the same type as
-their input.  The returned collections are always distinct from the input
+input collection. All three return zero or more collections of the same type as
+their input. The returned collections are always distinct from the input
 (according to `===`), even if the contents are identical.
 
 Of these methods, `filter()` is the only one that is lazy and the only one which
@@ -658,21 +614,21 @@ methods to form a pipeline of operations.
 The `partition()` method is similar to an eager version of `filter()`, but it
 returns two collections; the first contains the items that would have been
 discarded by `filter()`, and the second contains the items that would have been
-kept.  It always returns an array of exactly two collections, which can make it
-easier to use than `groupBy()`.  Compared to making two separate calls to
+kept. It always returns an array of exactly two collections, which can make it
+easier to use than `groupBy()`. Compared to making two separate calls to
 `filter()`, `partition()` makes half as many calls it the predicate passed to
 it.
 
 The `groupBy()` method is a more generalized version of `partition()` that can
-group by an arbitrary function rather than just a predicate.  It returns a map
+group by an arbitrary function rather than just a predicate. It returns a map
 with zero or more entries, where the keys are the values returned by the
 grouping function, and the values are nonempty collections of the corresponding
-arguments.  Although `groupBy()` is more powerful than `partition()`, it can be
+arguments. Although `groupBy()` is more powerful than `partition()`, it can be
 harder to use because it is not always possible predict in advance how many
 entries the returned map will have and what their keys will be.
 
 | Summary                       | `filter` | `partition` | `groupBy`      |
-|:------------------------------|:---------|:------------|:---------------|
+| :---------------------------- | :------- | :---------- | :------------- |
 | ease of use                   | easiest  | moderate    | hardest        |
 | generality                    | least    | moderate    | most           |
 | laziness                      | lazy     | eager       | eager          |
@@ -684,49 +640,63 @@ entries the returned map will have and what their keys will be.
 ## Additional Tools and Resources
 
 - [Atom-store](https://github.com/jameshopkins/atom-store/)
+
   - A Clojure-inspired atom implementation in Javascript with configurability
     for external persistance.
 
 - [Chai Immutable](https://github.com/astorije/chai-immutable)
+
   - If you are using the [Chai Assertion Library](https://chaijs.com/), this
     provides a set of assertions to use against Immutable.js collections.
 
 - [Fantasy-land](https://github.com/fantasyland/fantasy-land)
+
   - Specification for interoperability of common algebraic structures in JavaScript.
 
 - [Immutagen](https://github.com/pelotom/immutagen)
+
   - A library for simulating immutable generators in JavaScript.
 
 - [Immutable-cursor](https://github.com/redbadger/immutable-cursor)
+
   - Immutable cursors incorporating the Immutable.js interface over
-  Clojure-inspired atom.
+    Clojure-inspired atom.
 
 - [Immutable-ext](https://github.com/DrBoolean/immutable-ext)
+
   - Fantasyland extensions for immutablejs
 
 - [Immutable-js-tools](https://github.com/madeinfree/immutable-js-tools)
+
   - Util tools for immutable.js
 
 - [Immutable-Redux](https://github.com/gajus/redux-immutable)
+
   - redux-immutable is used to create an equivalent function of Redux
-  combineReducers that works with Immutable.js state.
+    combineReducers that works with Immutable.js state.
 
 - [Immutable-Treeutils](https://github.com/lukasbuenger/immutable-treeutils)
+
   - Functional tree traversal helpers for ImmutableJS data structures.
 
 - [Irecord](https://github.com/ericelliott/irecord)
+
   - An immutable store that exposes an RxJS observable. Great for React.
 
 - [Mudash](https://github.com/brianneisler/mudash)
+
   - Lodash wrapper providing Immutable.JS support.
 
 - [React-Immutable-PropTypes](https://github.com/HurricaneJames/react-immutable-proptypes)
+
   - PropType validators that work with Immutable.js.
 
 - [Redux-Immutablejs](https://github.com/indexiatech/redux-immutablejs)
+
   - Redux Immutable facilities.
 
 - [Rxstate](https://github.com/yamalight/rxstate)
+
   - Simple opinionated state management library based on RxJS and Immutable.js.
 
 - [Transit-Immutable-js](https://github.com/glenjamin/transit-immutable-js)