immutable 4.0.0-rc.5 → 4.0.0-rc.9

package/dist/immutable.d.ts

@@ -100,374 +100,95 @@
 declare module Immutable {
 
   /**
-   * 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
-   * refering to each collection and the parent JS object provided as `this`.
-   * For the top level, object, the key will be `""`. This `reviver` is expected
-   * to return a new Immutable Collection, allowing for custom conversions from
-   * deep JS objects. Finally, a `path` is provided which is the sequence of
-   * keys to this value from the starting value.
-   *
-   * `reviver` acts similarly to the [same parameter in `JSON.parse`][1].
-   *
-   * If `reviver` is not provided, the default behavior will convert Objects
-   * into Maps and Arrays into Lists like so:
-   *
-   * <!-- runkit:activate -->
-   * ```js
-   * const { fromJS, isKeyed } = require('immutable@4.0.0-rc.5')
-   * function (key, value) {
-   *   return isKeyed(value) ? value.Map() : 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:
-   *
-   * <!-- runkit:activate -->
-   * ```js
-   * const { fromJS, isKeyed } = require('immutable@4.0.0-rc.5')
-   * fromJS({ a: {b: [10, 20, 30]}, c: 40}, function (key, value, path) {
-   *   console.log(key, value, path)
-   *   return isKeyed(value) ? value.toOrderedMap() : value.toList()
-   * })
-   *
-   * > "b", [ 10, 20, 30 ], [ "a", "b" ]
-   * > "a", {b: [10, 20, 30]}, [ "a" ]
-   * > "", {a: {b: [10, 20, 30]}, c: 40}, []
-   * ```
-   *
-   * Keep in mind, when using JS objects to construct Immutable Maps, that
-   * JavaScript Object properties are always strings, even if written in a
-   * quote-less shorthand, while Immutable Maps accept keys of any type.
-   *
-   * <!-- runkit:activate -->
-   * ```js
-   * const { Map } = require('immutable@4.0.0-rc.5')
-   * let obj = { 1: "one" };
-   * Object.keys(obj); // [ "1" ]
-   * assert.equal(obj["1"], obj[1]); // "one" === "one"
+   * Lists are ordered indexed dense collections, much like a JavaScript
+   * Array.
    *
-   * let map = Map(obj);
-   * assert.notEqual(map.get("1"), map.get(1)); // "one" !== undefined
-   * ```
+   * Lists are immutable and fully persistent with O(log32 N) gets and sets,
+   * and O(1) push and pop.
    *
-   * 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.
+   * Lists implement Deque, with efficient addition and removal from both the
+   * end (`push`, `pop`) and beginning (`unshift`, `shift`).
    *
-   * [1]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse#Example.3A_Using_the_reviver_parameter
-   *      "Using the reviver parameter"
+   * Unlike a JavaScript Array, there is no distinction between an
+   * "unset" index and an index set to `undefined`. `List#forEach` visits all
+   * indices from 0 to size, regardless of whether they were explicitly defined.
    */
-  export function fromJS(
-    jsValue: any,
-    reviver?: (
-      key: string | number,
-      sequence: Collection.Keyed<string, any> | Collection.Indexed<any>,
-      path?: Array<string | number>
-    ) => any
-  ): any;
+  export module List {
+
+    /**
+     * True if the provided value is a List
+     *
+     * <!-- runkit:activate -->
+     * ```js
+     * const { List } = require('immutable@4.0.0-rc.9');
+     * List.isList([]); // false
+     * List.isList(List()); // true
+     * ```
+     */
+    function isList(maybeList: any): maybeList is List<any>;
 
+    /**
+     * Creates a new List containing `values`.
+     *
+     * <!-- runkit:activate -->
+     * ```js
+     * const { List } = require('immutable@4.0.0-rc.9');
+     * List.of(1, 2, 3, 4)
+     * // List [ 1, 2, 3, 4 ]
+     * ```
+     *
+     * Note: Values are not altered or converted in any way.
+     *
+     * <!-- runkit:activate -->
+     * ```js
+     * const { List } = require('immutable@4.0.0-rc.9');
+     * List.of({x:1}, 2, [3], 4)
+     * // List [ { x: 1 }, 2, [ 3 ], 4 ]
+     * ```
+     */
+    function of<T>(...values: Array<T>): List<T>;
+  }
 
   /**
-   * Value equality check with semantics similar to `Object.is`, but treats
-   * Immutable `Collection`s 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.
+   * Create a new immutable List containing the values of the provided
+   * collection-like.
    *
    * <!-- runkit:activate -->
    * ```js
-   * const { Map, is } = require('immutable@4.0.0-rc.5')
-   * 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.
-   */
-  export function is(first: any, second: any): boolean;
-
-
-  /**
-   * The `hash()` function is an important part of how Immutable determines if
-   * two values are equivalent and is used to determine how to store those
-   * values. Provided with any value, `hash()` will return a 31-bit integer.
-   *
-   * When designing Objects which may be equal, it's important than 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.
+   * const { List, Set } = require('immutable@4.0.0-rc.9')
    *
-   * Note that `hash()` attempts to balance between speed and avoiding
-   * collisions, however it makes no attempt to produce secure hashes.
+   * const emptyList = List()
+   * // List []
    *
-   * *New in Version 4.0*
-   */
-  export function hash(value: any): number;
-
-  /**
-   * True if `maybeImmutable` is an Immutable Collection or Record.
+   * const plainArray = [ 1, 2, 3, 4 ]
+   * const listFromPlainArray = List(plainArray)
+   * // List [ 1, 2, 3, 4 ]
    *
-   * <!-- runkit:activate -->
-   * ```js
-   * const { isImmutable, Map, List, Stack } = require('immutable@4.0.0-rc.5');
-   * isImmutable([]); // false
-   * isImmutable({}); // false
-   * isImmutable(Map()); // true
-   * isImmutable(List()); // true
-   * isImmutable(Stack()); // true
-   * isImmutable(Map().asMutable()); // false
-   * ```
-   */
-  export function isImmutable(maybeImmutable: any): maybeImmutable is Collection<any, any>;
-
-  /**
-   * True if `maybeCollection` is a Collection, or any of its subclasses.
+   * const plainSet = Set([ 1, 2, 3, 4 ])
+   * const listFromPlainSet = List(plainSet)
+   * // List [ 1, 2, 3, 4 ]
    *
-   * <!-- runkit:activate -->
-   * ```js
-   * const { isCollection, Map, List, Stack } = require('immutable@4.0.0-rc.5');
-   * isCollection([]); // false
-   * isCollection({}); // false
-   * isCollection(Map()); // true
-   * isCollection(List()); // true
-   * isCollection(Stack()); // true
-   * ```
-   */
-  export function isCollection(maybeCollection: any): maybeCollection is Collection<any, any>;
-
-  /**
-   * True if `maybeKeyed` is a Collection.Keyed, or any of its subclasses.
+   * const arrayIterator = plainArray[Symbol.iterator]()
+   * const listFromCollectionArray = List(arrayIterator)
+   * // List [ 1, 2, 3, 4 ]
    *
-   * <!-- runkit:activate -->
-   * ```js
-   * const { isKeyed, Map, List, Stack } = require('immutable@4.0.0-rc.5');
-   * isKeyed([]); // false
-   * isKeyed({}); // false
-   * isKeyed(Map()); // true
-   * isKeyed(List()); // false
-   * isKeyed(Stack()); // false
+   * listFromPlainArray.equals(listFromCollectionArray) // true
+   * listFromPlainSet.equals(listFromCollectionArray) // true
+   * listFromPlainSet.equals(listFromPlainArray) // true
    * ```
    */
-  export function isKeyed(maybeKeyed: any): maybeKeyed is Collection.Keyed<any, any>;
+  export function List(): List<any>;
+  export function List<T>(): List<T>;
+  export function List<T>(collection: Iterable<T>): List<T>;
 
-  /**
-   * True if `maybeIndexed` is a Collection.Indexed, or any of its subclasses.
-   *
-   * <!-- runkit:activate -->
-   * ```js
-   * const { isIndexed, Map, List, Stack, Set } = require('immutable@4.0.0-rc.5');
-   * isIndexed([]); // false
-   * isIndexed({}); // false
-   * isIndexed(Map()); // false
-   * isIndexed(List()); // true
-   * isIndexed(Stack()); // true
-   * isIndexed(Set()); // false
-   * ```
-   */
-  export function isIndexed(maybeIndexed: any): maybeIndexed is Collection.Indexed<any>;
+  export interface List<T> extends Collection.Indexed<T> {
 
-  /**
-   * True if `maybeAssociative` is either a Keyed or Indexed Collection.
-   *
-   * <!-- runkit:activate -->
-   * ```js
-   * const { isAssociative, Map, List, Stack, Set } = require('immutable@4.0.0-rc.5');
-   * isAssociative([]); // false
-   * isAssociative({}); // false
-   * isAssociative(Map()); // true
-   * isAssociative(List()); // true
-   * isAssociative(Stack()); // true
-   * isAssociative(Set()); // false
-   * ```
-   */
-  export function isAssociative(maybeAssociative: any): maybeAssociative is Collection.Keyed<any, any> | Collection.Indexed<any>;
+    /**
+     * The number of items in this List.
+     */
+    readonly size: number;
 
-  /**
-   * True if `maybeOrdered` is a Collection where iteration order is well
-   * defined. True for Collection.Indexed as well as OrderedMap and OrderedSet.
-   *
-   * <!-- runkit:activate -->
-   * ```js
-   * const { isOrdered, Map, OrderedMap, List, Set } = require('immutable@4.0.0-rc.5');
-   * isOrdered([]); // false
-   * isOrdered({}); // false
-   * isOrdered(Map()); // false
-   * isOrdered(OrderedMap()); // true
-   * isOrdered(List()); // true
-   * isOrdered(Set()); // false
-   * ```
-   */
-  export function isOrdered(maybeOrdered: any): boolean;
-
-  /**
-   * 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`.
-   */
-  export function isValueObject(maybeValue: any): maybeValue is ValueObject;
-
-  /**
-   * The interface to fulfill to qualify as a Value Object.
-   */
-  export interface ValueObject {
-    /**
-     * True if this and the other Collection have value equality, as defined
-     * by `Immutable.is()`.
-     *
-     * Note: This is equivalent to `Immutable.is(this, other)`, but provided to
-     * allow for chained expressions.
-     */
-    equals(other: any): boolean;
-
-    /**
-     * Computes and returns the hashed identity for this Collection.
-     *
-     * The `hashCode` of a Collection is used to determine potential equality,
-     * and is used when adding this to a `Set` or as a key in a `Map`, enabling
-     * lookup via a different instance.
-     *
-     * <!-- runkit:activate -->
-     * ```js
-     * const { List, Set } = require('immutable@4.0.0-rc.5');
-     * const a = List([ 1, 2, 3 ]);
-     * const b = List([ 1, 2, 3 ]);
-     * assert.notStrictEqual(a, b); // different instances
-     * const set = Set([ a ]);
-     * assert.equal(set.has(b), true);
-     * ```
-     *
-     * Note: hashCode() MUST return a Uint32 number. The easiest way to
-     * guarantee this is to return `myHash | 0` from a custom implementation.
-     *
-     * If two values have the same `hashCode`, they are [not guaranteed
-     * to be equal][Hash Collision]. If two values have different `hashCode`s,
-     * they must not be equal.
-     *
-     * Note: `hashCode()` is not guaranteed to always be called before
-     * `equals()`. Most but not all Immutable.js collections use hash codes to
-     * organize their internal data structures, while all Immutable.js
-     * collections use equality during lookups.
-     *
-     * [Hash Collision]: http://en.wikipedia.org/wiki/Collision_(computer_science)
-     */
-    hashCode(): number;
-  }
-
-  /**
-   * Lists are ordered indexed dense collections, much like a JavaScript
-   * Array.
-   *
-   * Lists are immutable and fully persistent with O(log32 N) gets and sets,
-   * and O(1) push and pop.
-   *
-   * Lists implement Deque, with efficient addition and removal from both the
-   * end (`push`, `pop`) and beginning (`unshift`, `shift`).
-   *
-   * Unlike a JavaScript Array, there is no distinction between an
-   * "unset" index and an index set to `undefined`. `List#forEach` visits all
-   * indices from 0 to size, regardless of whether they were explicitly defined.
-   */
-  export module List {
-
-    /**
-     * True if the provided value is a List
-     *
-     * <!-- runkit:activate -->
-     * ```js
-     * const { List } = require('immutable@4.0.0-rc.5');
-     * List.isList([]); // false
-     * List.isList(List()); // true
-     * ```
-     */
-    function isList(maybeList: any): maybeList is List<any>;
-
-    /**
-     * Creates a new List containing `values`.
-     *
-     * <!-- runkit:activate -->
-     * ```js
-     * const { List } = require('immutable@4.0.0-rc.5');
-     * List.of(1, 2, 3, 4)
-     * // List [ 1, 2, 3, 4 ]
-     * ```
-     *
-     * Note: Values are not altered or converted in any way.
-     *
-     * <!-- runkit:activate -->
-     * ```js
-     * const { List } = require('immutable@4.0.0-rc.5');
-     * List.of({x:1}, 2, [3], 4)
-     * // List [ { x: 1 }, 2, [ 3 ], 4 ]
-     * ```
-     */
-    function of<T>(...values: Array<T>): List<T>;
-  }
-
-  /**
-   * Create a new immutable List containing the values of the provided
-   * collection-like.
-   *
-   * <!-- runkit:activate -->
-   * ```js
-   * const { List, Set } = require('immutable@4.0.0-rc.5')
-   *
-   * const emptyList = List()
-   * // List []
-   *
-   * const plainArray = [ 1, 2, 3, 4 ]
-   * const listFromPlainArray = List(plainArray)
-   * // List [ 1, 2, 3, 4 ]
-   *
-   * const plainSet = Set([ 1, 2, 3, 4 ])
-   * const listFromPlainSet = List(plainSet)
-   * // List [ 1, 2, 3, 4 ]
-   *
-   * const arrayIterator = plainArray[Symbol.iterator]()
-   * const listFromCollectionArray = List(arrayIterator)
-   * // List [ 1, 2, 3, 4 ]
-   *
-   * listFromPlainArray.equals(listFromCollectionArray) // true
-   * listFromPlainSet.equals(listFromCollectionArray) // true
-   * listFromPlainSet.equals(listFromPlainArray) // true
-   * ```
-   */
-  export function List(): List<any>;
-  export function List<T>(): List<T>;
-  export function List<T>(collection: Iterable<T>): List<T>;
-
-  export interface List<T> extends Collection.Indexed<T> {
-
-    /**
-     * The number of items in this List.
-     */
-    readonly size: number;
-
-    // Persistent changes
+    // Persistent changes
 
     /**
      * Returns a new List which includes `value` at `index`. If `index` already
@@ -480,7 +201,7 @@ declare module Immutable {
      * enough to include the `index`.
      *
      * <!-- runkit:activate
-     *      { "preamble": "const { List } = require(\"immutable\");" }
+     *      { "preamble": "const { List } = require('immutable@4.0.0-rc.9');" }
      * -->
      * ```js
      * const originalList = List([ 0 ]);
@@ -513,13 +234,16 @@ declare module Immutable {
      * Note: `delete` cannot be safely used in IE8
      *
      * <!-- runkit:activate
-     *      { "preamble": "const { List } = require(\"immutable\");" }
+     *      { "preamble": "const { List } = require('immutable@4.0.0-rc.9');" }
      * -->
      * ```js
      * List([ 0, 1, 2, 3, 4 ]).delete(0);
      * // List [ 1, 2, 3, 4 ]
      * ```
      *
+     * Since `delete()` re-indexes values, it produces a complete copy, which
+     * has `O(N)` complexity.
+     *
      * Note: `delete` *cannot* be used in `withMutations`.
      *
      * @alias remove
@@ -534,22 +258,25 @@ declare module Immutable {
      * This is synonymous with `list.splice(index, 0, value)`.
      *
      * <!-- runkit:activate
-     *      { "preamble": "const { List } = require(\"immutable\");" }
+     *      { "preamble": "const { List } = require('immutable@4.0.0-rc.9');" }
      * -->
      * ```js
      * List([ 0, 1, 2, 3, 4 ]).insert(6, 5)
      * // List [ 0, 1, 2, 3, 4, 5 ]
      * ```
      *
+     * Since `insert()` re-indexes values, it produces a complete copy, which
+     * has `O(N)` complexity.
+     *
      * Note: `insert` *cannot* be used in `withMutations`.
      */
     insert(index: number, value: T): List<T>;
 
     /**
-     * Returns a new List with 0 size and no values.
+     * Returns a new List with 0 size and no values in constant time.
      *
      * <!-- runkit:activate
-     *      { "preamble": "const { List } = require(\"immutable\");" }
+     *      { "preamble": "const { List } = require('immutable@4.0.0-rc.9');" }
      * -->
      * ```js
      * List([ 1, 2, 3, 4 ]).clear()
@@ -565,7 +292,7 @@ declare module Immutable {
      * List's `size`.
      *
      * <!-- runkit:activate
-     *      { "preamble": "const { List } = require(\"immutable\");" }
+     *      { "preamble": "const { List } = require('immutable@4.0.0-rc.9');" }
      * -->
      * ```js
      * List([ 1, 2, 3, 4 ]).push(5)
@@ -598,7 +325,7 @@ declare module Immutable {
      * values ahead to higher indices.
      *
      * <!-- runkit:activate
-     *      { "preamble": "const { List } = require(\"immutable\");" }
+     *      { "preamble": "const { List } = require('immutable@4.0.0-rc.9');" }
      * -->
      * ```js
      * List([ 2, 3, 4]).unshift(1);
@@ -618,7 +345,7 @@ declare module Immutable {
      * value in this List.
      *
      * <!-- runkit:activate
-     *      { "preamble": "const { List } = require(\"immutable\");" }
+     *      { "preamble": "const { List } = require('immutable@4.0.0-rc.9');" }
      * -->
      * ```js
      * List([ 0, 1, 2, 3, 4 ]).shift();
@@ -639,7 +366,7 @@ declare module Immutable {
      * List. `v.update(-1)` updates the last item in the List.
      *
      * <!-- runkit:activate
-     *      { "preamble": "const { List } = require(\"immutable\");" }
+     *      { "preamble": "const { List } = require('immutable@4.0.0-rc.9');" }
      * -->
      * ```js
      * const list = List([ 'a', 'b', 'c' ])
@@ -653,7 +380,7 @@ declare module Immutable {
      * For example, to sum a List after mapping and filtering:
      *
      * <!-- runkit:activate
-     *      { "preamble": "const { List } = require(\"immutable\");" }
+     *      { "preamble": "const { List } = require('immutable@4.0.0-rc.9');" }
      * -->
      * ```js
      * function sum(collection) {
@@ -699,12 +426,24 @@ declare module Immutable {
      *
      * <!-- runkit:activate -->
      * ```js
-     * const { List } = require("immutable")
+     * const { List } = require('immutable@4.0.0-rc.9')
      * const list = List([ 0, 1, 2, List([ 3, 4 ])])
      * list.setIn([3, 0], 999);
      * // List [ 0, 1, 2, List [ 999, 4 ] ]
      * ```
      *
+     * Plain JavaScript Object or Arrays may be nested within an Immutable.js
+     * Collection, and setIn() can update those values as well, treating them
+     * immutably by creating new copies of those values with the changes applied.
+     *
+     * <!-- runkit:activate -->
+     * ```js
+     * const { List } = require('immutable@4.0.0-rc.9')
+     * const list = List([ 0, 1, 2, { plain: 'object' }])
+     * list.setIn([3, 'plain'], 'value');
+     * // List([ 0, 1, 2, { plain: 'value' }])
+     * ```
+     *
      * Note: `setIn` can be used in `withMutations`.
      */
     setIn(keyPath: Iterable<any>, value: any): this;
@@ -715,12 +454,24 @@ declare module Immutable {
      *
      * <!-- runkit:activate -->
      * ```js
-     * const { List } = require("immutable")
+     * const { List } = require('immutable@4.0.0-rc.9')
      * const list = List([ 0, 1, 2, List([ 3, 4 ])])
      * list.deleteIn([3, 0]);
      * // List [ 0, 1, 2, List [ 4 ] ]
      * ```
      *
+     * Plain JavaScript Object or Arrays may be nested within an Immutable.js
+     * Collection, and removeIn() can update those values as well, treating them
+     * immutably by creating new copies of those values with the changes applied.
+     *
+     * <!-- runkit:activate -->
+     * ```js
+     * const { List } = require('immutable@4.0.0-rc.9')
+     * const list = List([ 0, 1, 2, { plain: 'object' }])
+     * list.removeIn([3, 'plain']);
+     * // List([ 0, 1, 2, {}])
+     * ```
+     *
      * Note: `deleteIn` *cannot* be safely used in `withMutations`.
      *
      * @alias removeIn
@@ -787,19 +538,19 @@ declare module Immutable {
     /**
      * Returns a new List with other values or collections concatenated to this one.
      *
-     * Note: `concat` *cannot* be safely used in `withMutations`.
+     * Note: `concat` can be used in `withMutations`.
      *
      * @alias merge
      */
     concat<C>(...valuesOrCollections: Array<Iterable<C> | C>): List<T | C>;
-    merge<C>(...collections: Array<Iterable<C>): List<T | C>;
+    merge<C>(...collections: Array<Iterable<C>>): List<T | C>;
 
     /**
      * Returns a new List with values passed through a
      * `mapper` function.
      *
      * <!-- runkit:activate
-     *      { "preamble": "const { List } = require(\"immutable\");" }
+     *      { "preamble": "const { List } = require('immutable@4.0.0-rc.9');" }
      * -->
      * ```js
      * List([ 1, 2 ]).map(x => 10 * x)
@@ -846,7 +597,7 @@ declare module Immutable {
      * Like `zipWith`, but using the default `zipper`: creating an `Array`.
      *
      * <!-- runkit:activate
-     *      { "preamble": "const { List } = require(\"immutable\");" }
+     *      { "preamble": "const { List } = require('immutable@4.0.0-rc.9');" }
      * -->
      * ```js
      * const a = List([ 1, 2, 3 ]);
@@ -865,7 +616,7 @@ declare module Immutable {
      * exhausted. Missing values from shorter collections are filled with `undefined`.
      *
      * <!-- runkit:activate
-     *      { "preamble": "const { List } = require(\"immutable\");" }
+     *      { "preamble": "const { List } = require('immutable@4.0.0-rc.9');" }
      * -->
      * ```js
      * const a = List([ 1, 2 ]);
@@ -886,7 +637,7 @@ declare module Immutable {
      * custom `zipper` function.
      *
      * <!-- runkit:activate
-     *      { "preamble": "const { List } = require(\"immutable\");" }
+     *      { "preamble": "const { List } = require('immutable@4.0.0-rc.9');" }
      * -->
      * ```js
      * const a = List([ 1, 2, 3 ]);
@@ -927,7 +678,7 @@ declare module Immutable {
    *
    * <!-- runkit:activate -->
    * ```js
-   * const { Map, List } = require('immutable@4.0.0-rc.5');
+   * const { Map, List } = require('immutable@4.0.0-rc.9');
    * Map().set(List([ 1 ]), 'listofone').get(List([ 1 ]));
    * // 'listofone'
    * ```
@@ -945,7 +696,7 @@ declare module Immutable {
      *
      * <!-- runkit:activate -->
      * ```js
-     * const { Map } = require('immutable@4.0.0-rc.5')
+     * const { Map } = require('immutable@4.0.0-rc.9')
      * Map.isMap({}) // false
      * Map.isMap(Map()) // true
      * ```
@@ -957,7 +708,7 @@ declare module Immutable {
      *
      * <!-- runkit:activate -->
      * ```js
-     * const { Map } = require('immutable@4.0.0-rc.5')
+     * const { Map } = require('immutable@4.0.0-rc.9')
      * Map.of(
      *   'key', 'value',
      *   'numerical value', 3,
@@ -979,7 +730,7 @@ declare module Immutable {
    *
    * <!-- runkit:activate -->
    * ```js
-   * const { Map } = require('immutable@4.0.0-rc.5')
+   * const { Map } = require('immutable@4.0.0-rc.9')
    * Map({ key: "value" })
    * Map([ [ "key", "value" ] ])
    * ```
@@ -989,7 +740,7 @@ declare module Immutable {
    * quote-less shorthand, while Immutable Maps accept keys of any type.
    *
    * <!-- runkit:activate
-   *      { "preamble": "const { Map } = require(\"immutable\");" }
+   *      { "preamble": "const { Map } = require('immutable@4.0.0-rc.9');" }
    * -->
    * ```js
    * let obj = { 1: "one" }
@@ -1025,7 +776,7 @@ declare module Immutable {
      *
      * <!-- runkit:activate -->
      * ```js
-     * const { Map } = require('immutable@4.0.0-rc.5')
+     * const { Map } = require('immutable@4.0.0-rc.9')
      * const originalMap = Map()
      * const newerMap = originalMap.set('key', 'value')
      * const newestMap = newerMap.set('key', 'newer value')
@@ -1050,7 +801,7 @@ declare module Immutable {
      *
      * <!-- runkit:activate -->
      * ```js
-     * const { Map } = require('immutable@4.0.0-rc.5')
+     * const { Map } = require('immutable@4.0.0-rc.9')
      * const originalMap = Map({
      *   key: 'value',
      *   otherKey: 'other value'
@@ -1072,7 +823,7 @@ declare module Immutable {
      *
      * <!-- runkit:activate -->
      * ```js
-     * const { Map } = require('immutable@4.0.0-rc.5')
+     * const { Map } = require('immutable@4.0.0-rc.9')
      * const names = Map({ a: "Aaron", b: "Barry", c: "Connor" })
      * names.deleteAll([ 'a', 'c' ])
      * // Map { "b": "Barry" }
@@ -1090,7 +841,7 @@ declare module Immutable {
      *
      * <!-- runkit:activate -->
      * ```js
-     * const { Map } = require('immutable@4.0.0-rc.5')
+     * const { Map } = require('immutable@4.0.0-rc.9')
      * Map({ key: 'value' }).clear()
      * // Map {}
      * ```
@@ -1107,7 +858,7 @@ declare module Immutable {
      *
      * <!-- runkit:activate -->
      * ```js
-     * const { Map } = require('immutable@4.0.0-rc.5')
+     * const { Map } = require('immutable@4.0.0-rc.9')
      * const aMap = Map({ key: 'value' })
      * const newMap = aMap.update('key', value => value + value)
      * // Map { "key": "valuevalue" }
@@ -1118,7 +869,7 @@ declare module Immutable {
      * `update` and `push` can be used together:
      *
      * <!-- runkit:activate
-     *      { "preamble": "const { Map, List } = require(\"immutable\");" }
+     *      { "preamble": "const { Map, List } = require('immutable@4.0.0-rc.9');" }
      * -->
      * ```js
      * const aMap = Map({ nestedList: List([ 1, 2, 3 ]) })
@@ -1130,7 +881,7 @@ declare module Immutable {
      * function when the value at the key does not exist in the Map.
      *
      * <!-- runkit:activate
-     *      { "preamble": "const { Map } = require(\"immutable\");" }
+     *      { "preamble": "const { Map } = require('immutable@4.0.0-rc.9');" }
      * -->
      * ```js
      * const aMap = Map({ key: 'value' })
@@ -1143,7 +894,7 @@ declare module Immutable {
      * is provided.
      *
      * <!-- runkit:activate
-     *      { "preamble": "const { Map } = require(\"immutable\");" }
+     *      { "preamble": "const { Map } = require('immutable@4.0.0-rc.9');" }
      * -->
      * ```js
      * const aMap = Map({ apples: 10 })
@@ -1159,7 +910,7 @@ declare module Immutable {
      * The previous example behaves differently when written with default values:
      *
      * <!-- runkit:activate
-     *      { "preamble": "const { Map } = require(\"immutable\");" }
+     *      { "preamble": "const { Map } = require('immutable@4.0.0-rc.9');" }
      * -->
      * ```js
      * const aMap = Map({ apples: 10 })
@@ -1171,7 +922,7 @@ declare module Immutable {
      * returned as well.
      *
      * <!-- runkit:activate
-     *      { "preamble": "const { Map } = require(\"immutable\");" }
+     *      { "preamble": "const { Map } = require('immutable@4.0.0-rc.9');" }
      * -->
      * ```js
      * const aMap = Map({ key: 'value' })
@@ -1185,7 +936,7 @@ declare module Immutable {
      * For example, to sum the values in a Map
      *
      * <!-- runkit:activate
-     *      { "preamble": "const { Map } = require(\"immutable\");" }
+     *      { "preamble": "const { Map } = require('immutable@4.0.0-rc.9');" }
      * -->
      * ```js
      * function sum(collection) {
@@ -1215,7 +966,7 @@ declare module Immutable {
      *
      * <!-- runkit:activate -->
      * ```js
-     * const { Map } = require('immutable@4.0.0-rc.5')
+     * const { Map } = require('immutable@4.0.0-rc.9')
      * const one = Map({ a: 10, b: 20, c: 30 })
      * const two = Map({ b: 40, a: 50, d: 60 })
      * one.merge(two) // Map { "a": 50, "b": 40, "c": 30, "d": 60 }
@@ -1223,8 +974,13 @@ declare module Immutable {
      * ```
      *
      * Note: `merge` can be used in `withMutations`.
+     *
+     * @alias concat
      */
-    merge(...collections: Array<Iterable<[K, V]> | {[key: string]: V}>): this;
+    merge<KC, VC>(...collections: Array<Iterable<[KC, VC]>>): Map<K | KC, V | VC>;
+    merge<C>(...collections: Array<{[key: string]: C}>): Map<K | string, V | C>;
+    concat<KC, VC>(...collections: Array<Iterable<[KC, VC]>>): Map<K | KC, V | VC>;
+    concat<C>(...collections: Array<{[key: string]: C}>): Map<K | string, V | C>;
 
     /**
      * Like `merge()`, `mergeWith()` returns a new Map resulting from merging
@@ -1233,7 +989,7 @@ declare module Immutable {
      *
      * <!-- runkit:activate -->
      * ```js
-     * const { Map } = require('immutable@4.0.0-rc.5')
+     * const { Map } = require('immutable@4.0.0-rc.9')
      * const one = Map({ a: 10, b: 20, c: 30 })
      * const two = Map({ b: 40, a: 50, d: 60 })
      * one.mergeWith((oldVal, newVal) => oldVal / newVal, two)
@@ -1259,7 +1015,7 @@ declare module Immutable {
      *
      * <!-- runkit:activate -->
      * ```js
-     * const { Map } = require('immutable@4.0.0-rc.5')
+     * const { Map } = require('immutable@4.0.0-rc.9')
      * const one = Map({ a: Map({ x: 10, y: 10 }), b: Map({ x: 20, y: 50 }) })
      * const two = Map({ a: Map({ x: 2 }), b: Map({ y: 5 }), c: Map({ z: 3 }) })
      * one.mergeDeep(two)
@@ -1280,7 +1036,7 @@ declare module Immutable {
      *
      * <!-- runkit:activate -->
      * ```js
-     * const { Map } = require('immutable@4.0.0-rc.5')
+     * const { Map } = require('immutable@4.0.0-rc.9')
      * const one = Map({ a: Map({ x: 10, y: 10 }), b: Map({ x: 20, y: 50 }) })
      * const two = Map({ a: Map({ x: 2 }), b: Map({ y: 5 }), c: Map({ z: 3 }) })
      * one.mergeDeepWith((oldVal, newVal) => oldVal / newVal, two)
@@ -1307,7 +1063,7 @@ declare module Immutable {
      *
      * <!-- runkit:activate -->
      * ```js
-     * const { Map } = require('immutable@4.0.0-rc.5')
+     * const { Map } = require('immutable@4.0.0-rc.9')
      * const originalMap = Map({
      *   subObject: Map({
      *     subKey: 'subvalue',
@@ -1337,8 +1093,33 @@ declare module Immutable {
      * // }
      * ```
      *
-     * If any key in the path exists but does not have a `.set()` method
-     * (such as Map and List), an error will be throw.
+     * Plain JavaScript Object or Arrays may be nested within an Immutable.js
+     * Collection, and setIn() can update those values as well, treating them
+     * immutably by creating new copies of those values with the changes applied.
+     *
+     * <!-- runkit:activate -->
+     * ```js
+     * const { Map } = require('immutable@4.0.0-rc.9')
+     * const originalMap = Map({
+     *   subObject: {
+     *     subKey: 'subvalue',
+     *     subSubObject: {
+     *       subSubKey: 'subSubValue'
+     *     }
+     *   }
+     * })
+     *
+     * originalMap.setIn(['subObject', 'subKey'], 'ha ha!')
+     * // Map {
+     * //   "subObject": {
+     * //     subKey: "ha ha!",
+     * //     subSubObject: { subSubKey: "subSubValue" }
+     * //   }
+     * // }
+     * ```
+     *
+     * If any key in the path exists but cannot be updated (such as a primitive
+     * like number or a custom Object like Date), an error will be thrown.
      *
      * Note: `setIn` can be used in `withMutations`.
      */
@@ -1365,7 +1146,7 @@ declare module Immutable {
      *
      * <!-- runkit:activate -->
      * ```js
-     * const { Map, List } = require('immutable@4.0.0-rc.5')
+     * const { Map, List } = require('immutable@4.0.0-rc.9')
      * const map = Map({ inMap: Map({ inList: List([ 1, 2, 3 ]) }) })
      * const newMap = map.updateIn(['inMap', 'inList'], list => list.push(4))
      * // Map { "inMap": Map { "inList": List [ 1, 2, 3, 4 ] } }
@@ -1377,7 +1158,7 @@ declare module Immutable {
      * provided, otherwise `undefined`.
      *
      * <!-- runkit:activate
-     *      { "preamble": "const { Map } = require('immutable@4.0.0-rc.5')" }
+     *      { "preamble": "const { Map } = require('immutable@4.0.0-rc.9')" }
      * -->
      * ```js
      * const map = Map({ a: Map({ b: Map({ c: 10 }) }) })
@@ -1389,7 +1170,7 @@ declare module Immutable {
      * no change will occur. This is still true if `notSetValue` is provided.
      *
      * <!-- runkit:activate
-     *      { "preamble": "const { Map } = require('immutable@4.0.0-rc.5')" }
+     *      { "preamble": "const { Map } = require('immutable@4.0.0-rc.9')" }
      * -->
      * ```js
      * const map = Map({ a: Map({ b: Map({ c: 10 }) }) })
@@ -1405,7 +1186,7 @@ declare module Immutable {
      * The previous example behaves differently when written with default values:
      *
      * <!-- runkit:activate
-     *      { "preamble": "const { Map } = require('immutable@4.0.0-rc.5')" }
+     *      { "preamble": "const { Map } = require('immutable@4.0.0-rc.9')" }
      * -->
      * ```js
      * const map = Map({ a: Map({ b: Map({ c: 10 }) }) })
@@ -1413,8 +1194,23 @@ declare module Immutable {
      * // Map { "a": Map { "b": Map { "c": 10, "x": 100 } } }
      * ```
      *
-     * If any key in the path exists but does not have a .set() method (such as
-     * Map and List), an error will be thrown.
+     * Plain JavaScript Object or Arrays may be nested within an Immutable.js
+     * Collection, and updateIn() can update those values as well, treating them
+     * immutably by creating new copies of those values with the changes applied.
+     *
+     * <!-- runkit:activate
+     *      { "preamble": "const { Map } = require('immutable@4.0.0-rc.9')" }
+     * -->
+     * ```js
+     * const map = Map({ a: { b: { c: 10 } } })
+     * const newMap = map.updateIn(['a', 'b', 'c'], val => val * 2)
+     * // Map { "a": { b: { c: 20 } } }
+     * ```
+     *
+     * If any key in the path exists but cannot be updated (such as a primitive
+     * like number or a custom Object like Date), an error will be thrown.
+     *
+     * Note: `updateIn` can be used in `withMutations`.
      */
     updateIn(keyPath: Iterable<any>, notSetValue: any, updater: (value: any) => any): this;
     updateIn(keyPath: Iterable<any>, updater: (value: any) => any): this;
@@ -1464,7 +1260,7 @@ declare module Immutable {
      *
      * <!-- runkit:activate -->
      * ```js
-     * const { Map } = require('immutable@4.0.0-rc.5')
+     * const { Map } = require('immutable@4.0.0-rc.9')
      * const map1 = Map()
      * const map2 = map1.withMutations(map => {
      *   map.set('a', 1).set('b', 2).set('c', 3)
@@ -1512,12 +1308,6 @@ declare module Immutable {
 
     // Sequence algorithms
 
-    /**
-     * Returns a new Map with other collections concatenated to this one.
-     */
-    concat<KC, VC>(...collections: Array<Iterable<[KC, VC]>>): Map<K | KC, V | VC>;
-    concat<C>(...collections: Array<{[key: string]: C}>): Map<K | string, V | C>;
-
     /**
      * Returns a new Map with values passed through a
      * `mapper` function.
@@ -1628,14 +1418,34 @@ declare module Immutable {
      */
     readonly size: number;
 
-    // Sequence algorithms
-
     /**
-     * Returns a new OrderedMap with other collections concatenated to this one.
+     * Returns a new OrderedMap resulting from merging the provided Collections
+     * (or JS objects) into this OrderedMap. In other words, this takes each
+     * entry of each collection and sets it on this OrderedMap.
+     *
+     * Note: Values provided to `merge` are shallowly converted before being
+     * merged. No nested values are altered.
+     *
+     * <!-- runkit:activate -->
+     * ```js
+     * const { OrderedMap } = require('immutable@4.0.0-rc.9')
+     * const one = OrderedMap({ a: 10, b: 20, c: 30 })
+     * const two = OrderedMap({ b: 40, a: 50, d: 60 })
+     * one.merge(two) // OrderedMap { "a": 50, "b": 40, "c": 30, "d": 60 }
+     * two.merge(one) // OrderedMap { "b": 20, "a": 10, "d": 60, "c": 30 }
+     * ```
+     *
+     * Note: `merge` can be used in `withMutations`.
+     *
+     * @alias concat
      */
+    merge<KC, VC>(...collections: Array<Iterable<[KC, VC]>>): OrderedMap<K | KC, V | VC>;
+    merge<C>(...collections: Array<{[key: string]: C}>): OrderedMap<K | string, V | C>;
     concat<KC, VC>(...collections: Array<Iterable<[KC, VC]>>): OrderedMap<K | KC, V | VC>;
     concat<C>(...collections: Array<{[key: string]: C}>): OrderedMap<K | string, V | C>;
 
+    // Sequence algorithms
+
     /**
      * Returns a new OrderedMap with values passed through a
      * `mapper` function.
@@ -1735,7 +1545,7 @@ declare module Immutable {
      * a collection of other sets.
      *
      * ```js
-     * const { Set } = require('immutable@4.0.0-rc.5')
+     * const { Set } = require('immutable@4.0.0-rc.9')
      * const intersected = Set.intersect([
      *   Set([ 'a', 'b', 'c' ])
      *   Set([ 'c', 'a', 't' ])
@@ -1750,7 +1560,7 @@ declare module Immutable {
      * collection of other sets.
      *
      * ```js
-     * const { Set } = require('immutable@4.0.0-rc.5')
+     * const { Set } = require('immutable@4.0.0-rc.9')
      * const unioned = Set.union([
      *   Set([ 'a', 'b', 'c' ])
      *   Set([ 'c', 'a', 't' ])
@@ -1811,9 +1621,11 @@ declare module Immutable {
      *
      * Note: `union` can be used in `withMutations`.
      * @alias merge
+     * @alias concat
      */
-    union(...collections: Array<Iterable<T>>): this;
-    merge(...collections: Array<Iterable<T>>): this;
+    union<C>(...collections: Array<Iterable<C>>): Set<T | C>;
+    merge<C>(...collections: Array<Iterable<C>>): Set<T | C>;
+    concat<C>(...collections: Array<Iterable<C>>): Set<T | C>;
 
     /**
      * Returns a Set which has removed any values not also contained
@@ -1821,14 +1633,14 @@ declare module Immutable {
      *
      * Note: `intersect` can be used in `withMutations`.
      */
-    intersect(...collections: Array<Collection<any, T> | Array<T>>): this;
+    intersect(...collections: Array<Iterable<T>>): this;
 
     /**
      * Returns a Set excluding any values contained within `collections`.
      *
      * Note: `subtract` can be used in `withMutations`.
      */
-    subtract(...collections: Array<Collection<any, T> | Array<T>>): this;
+    subtract(...collections: Array<Iterable<T>>): this;
 
 
     // Transient changes
@@ -1863,11 +1675,6 @@ declare module Immutable {
 
     // Sequence algorithms
 
-    /**
-     * Returns a new Set with other collections concatenated to this one.
-     */
-    concat<C>(...valuesOrCollections: Array<Iterable<C> | C>): Set<T | C>;
-
     /**
      * Returns a new Set with values passed through a
      * `mapper` function.
@@ -1956,12 +1763,19 @@ declare module Immutable {
      */
     readonly size: number;
 
-    // Sequence algorithms
-
     /**
-     * Returns a new OrderedSet with other collections concatenated to this one.
+     * Returns an OrderedSet including any value from `collections` that does
+     * not already exist in this OrderedSet.
+     *
+     * Note: `union` can be used in `withMutations`.
+     * @alias merge
+     * @alias concat
      */
-    concat<C>(...valuesOrCollections: Array<Iterable<C> | C>): OrderedSet<T | C>;
+    union<C>(...collections: Array<Iterable<C>>): OrderedSet<T | C>;
+    merge<C>(...collections: Array<Iterable<C>>): OrderedSet<T | C>;
+    concat<C>(...collections: Array<Iterable<C>>): OrderedSet<T | C>;
+
+    // Sequence algorithms
 
     /**
      * Returns a new Set with values passed through a
@@ -2317,7 +2131,7 @@ declare module Immutable {
    * infinity. When `start` is equal to `end`, returns empty range.
    *
    * ```js
-   * const { Range } = require('immutable@4.0.0-rc.5')
+   * const { Range } = require('immutable@4.0.0-rc.9')
    * Range() // [ 0, 1, 2, 3, ... ]
    * Range(10) // [ 10, 11, 12, 13, ... ]
    * Range(10, 15) // [ 10, 11, 12, 13, 14 ]
@@ -2334,7 +2148,7 @@ declare module Immutable {
    * not defined, returns an infinite `Seq` of `value`.
    *
    * ```js
-   * const { Repeat } = require('immutable@4.0.0-rc.5')
+   * const { Repeat } = require('immutable@4.0.0-rc.9')
    * Repeat('foo') // [ 'foo', 'foo', 'foo', ... ]
    * Repeat('bar', 4) // [ 'bar', 'bar', 'bar', 'bar' ]
    * ```
@@ -2350,7 +2164,7 @@ declare module Immutable {
    * create Record instances.
    *
    * ```js
-   * const { Record } = require('immutable@4.0.0-rc.5')
+   * const { Record } = require('immutable@4.0.0-rc.9')
    * const ABRecord = Record({ a: 1, b: 2 })
    * const myRecord = new ABRecord({ b: 3 })
    * ```
@@ -2429,6 +2243,44 @@ declare module Immutable {
    * export type Point3D = RecordOf<Point3DProps>;
    * const some3DPoint: Point3D = makePoint3D({ x: 10, y: 20, z: 30 });
    * ```
+   *
+   *
+   * **Choosing Records vs plain JavaScript objects**
+   *
+   * Records ofters a persistently immutable alternative to plain JavaScript
+   * objects, however they're not required to be used within Immutable.js
+   * collections. In fact, the deep-access and deep-updating functions
+   * like `getIn()` and `setIn()` work with plain JavaScript Objects as well.
+   *
+   * Deciding to use Records or Objects in your application should be informed
+   * by the tradeoffs and relative benefits of each:
+   *
+   * - *Runtime immutability*: plain JS objects may be carefully treated as
+   *   immutable, however Record instances will *throw* if attempted to be
+   *   mutated directly. Records provide this additional guarantee, however at
+   *   some marginal runtime cost. While JS objects are mutable by nature, the
+   *   use of type-checking tools like [Flow](https://medium.com/@gcanti/immutability-with-flow-faa050a1aef4)
+   *   can help gain confidence in code written to favor immutability.
+   *
+   * - *Value equality*: Records use value equality when compared with `is()`
+   *   or `record.equals()`. That is, two Records with the same keys and values
+   *   are equal. Plain objects use *reference equality*. Two objects with the
+   *   same keys and values are not equal since they are different objects.
+   *   This is important to consider when using objects as keys in a `Map` or
+   *   values in a `Set`, which use equality when retrieving values.
+   *
+   * - *API methods*: Records have a full featured API, with methods like
+   *   `.getIn()`, and `.equals()`. These can make working with these values
+   *   easier, but comes at the cost of not allowing keys with those names.
+   *
+   * - *Default values*: Records provide default values for every key, which
+   *   can be useful when constructing Records with often unchanging values.
+   *   However default values can make using Flow and TypeScript more laborious.
+   *
+   * - *Serialization*: Records use a custom internal representation to
+   *   efficiently store and update their values. Converting to and from this
+   *   form isn't free. If converting Records to plain objects is common,
+   *   consider sticking with plain objects to begin with.
    */
   export module Record {
 
@@ -2444,7 +2296,7 @@ declare module Immutable {
      * method. If one was not provided, the string "Record" is returned.
      *
      * ```js
-     * const { Record } = require('immutable@4.0.0-rc.5')
+     * const { Record } = require('immutable@4.0.0-rc.9')
      * const Person = Record({
      *   name: null
      * }, 'Person')
@@ -2462,7 +2314,7 @@ declare module Immutable {
      * type:
      *
      * <!-- runkit:activate
-     *      { "preamble": "const { Record } = require('immutable@4.0.0-rc.5')" }
+     *      { "preamble": "const { Record } = require('immutable@4.0.0-rc.9')" }
      * -->
      * ```js
      * // makePerson is a Record Factory function
@@ -2477,7 +2329,7 @@ declare module Immutable {
      * access on the resulting instances:
      *
      * <!-- runkit:activate
-     *      { "preamble": "const { Record } = require('immutable@4.0.0-rc.5');const makePerson = Record({ name: null, favoriteColor: 'unknown' });const alan = makePerson({ name: 'Alan' });" }
+     *      { "preamble": "const { Record } = require('immutable@4.0.0-rc.9');const makePerson = Record({ name: null, favoriteColor: 'unknown' });const alan = makePerson({ name: 'Alan' });" }
      * -->
      * ```js
      * // Use the Record API
@@ -2511,7 +2363,7 @@ declare module Immutable {
       new (values?: Partial<TProps> | Iterable<[string, any]>): Record<TProps> & Readonly<TProps>;
     }
 
-    export function Factory(values?: Partial<TProps> | Iterable<[string, any]>): Record<TProps> & Readonly<TProps>;
+    export function Factory<TProps extends Object>(values?: Partial<TProps> | Iterable<[string, any]>): Record<TProps> & Readonly<TProps>;
   }
 
   /**
@@ -2527,7 +2379,16 @@ declare module Immutable {
     // Reading values
 
     has(key: string): key is keyof TProps;
-    get<K extends keyof TProps>(key: K): TProps[K];
+
+    /**
+     * Returns the value associated with the provided key, which may be the
+     * default value defined when creating the Record factory function.
+     *
+     * If the requested key is not defined by this Record type, then
+     * notSetValue will be returned if provided. Note that this scenario would
+     * produce an error when using Flow or TypeScript.
+     */
+    get<K extends keyof TProps>(key: K, notSetValue: any): TProps[K];
 
     // Reading deep values
 
@@ -2633,51 +2494,63 @@ declare module Immutable {
   }
 
   /**
-   * Represents a sequence of values, but may not be backed by a concrete data
-   * structure.
+   * `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
+   * **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:
+   * `Seq`'s values are never iterated:
    *
    * ```js
-   * const { Seq } = require('immutable@4.0.0-rc.5')
+   * const { Seq } = require('immutable@4.0.0-rc.9')
    * 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 data structures are ever created, filter is only
-   * called three times, and map is only called once:
+   * 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:
    *
-   * ```
-   * oddSquares.get(1)); // 9
+   * ```js
+   * oddSquares.get(1); // 9
    * ```
    *
-   * Seq allows for the efficient chaining of operations,
-   * allowing for the expression of logic that can otherwise be very tedious:
+   * Any collection can be converted to a lazy Seq with `Seq()`.
    *
+   * <!-- runkit:activate -->
+   * ```js
+   * const { Map } = require('immutable')
+   * const map = Map({ a: 1, b: 2, c: 3 }
+   * const lazySeq = Seq(map)
    * ```
-   * Seq({ a: 1, b: 1, c: 1})
+   *
+   * `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 be memory or time limited:
+   * 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@4.0.0-rc.5')
+   * const { Range } = require('immutable@4.0.0-rc.9')
    * Range(1, Infinity)
    *   .skip(1000)
    *   .map(n => -n)
@@ -2756,7 +2629,7 @@ declare module Immutable {
        * `mapper` function.
        *
        * ```js
-       * const { Seq } = require('immutable@4.0.0-rc.5')
+       * const { Seq } = require('immutable@4.0.0-rc.9')
        * Seq.Keyed({ a: 1, b: 2 }).map(x => 10 * x)
        * // Seq { "a": 10, "b": 20 }
        * ```
@@ -2868,7 +2741,7 @@ declare module Immutable {
        * `mapper` function.
        *
        * ```js
-       * const { Seq } = require('immutable@4.0.0-rc.5')
+       * const { Seq } = require('immutable@4.0.0-rc.9')
        * Seq.Indexed([ 1, 2 ]).map(x => 10 * x)
        * // Seq [ 10, 20 ]
        * ```
@@ -3013,7 +2886,7 @@ declare module Immutable {
        * All entries will be present in the resulting Seq, even if they
        * are duplicates.
        */
-      concat<C>(...valuesOrCollections: Array<Iterable<C> | C>): Seq.Set<T | C>;
+      concat<U>(...collections: Array<Iterable<U>>): Seq.Set<T | U>;
 
       /**
        * Returns a new Seq.Set with values passed through a
@@ -3128,7 +3001,7 @@ declare module Immutable {
      * `mapper` function.
      *
      * ```js
-     * const { Seq } = require('immutable@4.0.0-rc.5')
+     * const { Seq } = require('immutable@4.0.0-rc.9')
      * Seq([ 1, 2 ]).map(x => 10 * x)
      * // Seq [ 10, 20 ]
      * ```
@@ -3146,7 +3019,7 @@ declare module Immutable {
      * `mapper` function.
      *
      * ```js
-     * const { Seq } = require('immutable@4.0.0-rc.5')
+     * const { Seq } = require('immutable@4.0.0-rc.9')
      * Seq([ 1, 2 ]).map(x => 10 * x)
      * // Seq [ 10, 20 ]
      * ```
@@ -3215,22 +3088,22 @@ declare module Immutable {
   export module Collection {
 
     /**
-     * @deprecated use `const { isKeyed } = require('immutable@4.0.0-rc.5')`
+     * @deprecated use `const { isKeyed } = require('immutable@4.0.0-rc.9')`
      */
     function isKeyed(maybeKeyed: any): maybeKeyed is Collection.Keyed<any, any>;
 
     /**
-     * @deprecated use `const { isIndexed } = require('immutable@4.0.0-rc.5')`
+     * @deprecated use `const { isIndexed } = require('immutable@4.0.0-rc.9')`
      */
     function isIndexed(maybeIndexed: any): maybeIndexed is Collection.Indexed<any>;
 
     /**
-     * @deprecated use `const { isAssociative } = require('immutable@4.0.0-rc.5')`
+     * @deprecated use `const { isAssociative } = require('immutable@4.0.0-rc.9')`
      */
     function isAssociative(maybeAssociative: any): maybeAssociative is Collection.Keyed<any, any> | Collection.Indexed<any>;
 
     /**
-     * @deprecated use `const { isOrdered } = require('immutable@4.0.0-rc.5')`
+     * @deprecated use `const { isOrdered } = require('immutable@4.0.0-rc.9')`
      */
     function isOrdered(maybeOrdered: any): boolean;
 
@@ -3288,7 +3161,7 @@ declare module Immutable {
        *
        * <!-- runkit:activate -->
        * ```js
-       * const { Map } = require('immutable@4.0.0-rc.5')
+       * const { Map } = require('immutable@4.0.0-rc.9')
        * Map({ a: 'z', b: 'y' }).flip()
        * // Map { "z": "a", "y": "b" }
        * ```
@@ -3306,7 +3179,7 @@ declare module Immutable {
        * `mapper` function.
        *
        * ```js
-       * const { Collection } = require('immutable@4.0.0-rc.5')
+       * const { Collection } = require('immutable@4.0.0-rc.9')
        * Collection.Keyed({ a: 1, b: 2 }).map(x => 10 * x)
        * // Seq { "a": 10, "b": 20 }
        * ```
@@ -3325,7 +3198,7 @@ declare module Immutable {
        *
        * <!-- runkit:activate -->
        * ```js
-       * const { Map } = require('immutable@4.0.0-rc.5')
+       * const { Map } = require('immutable@4.0.0-rc.9')
        * Map({ a: 1, b: 2 }).mapKeys(x => x.toUpperCase())
        * // Map { "A": 1, "B": 2 }
        * ```
@@ -3344,7 +3217,7 @@ declare module Immutable {
        *
        * <!-- runkit:activate -->
        * ```js
-       * const { Map } = require('immutable@4.0.0-rc.5')
+       * const { Map } = require('immutable@4.0.0-rc.9')
        * Map({ a: 1, b: 2 })
        *   .mapEntries(([ k, v ]) => [ k.toUpperCase(), v * 2 ])
        * // Map { "A": 2, "B": 4 }
@@ -3470,10 +3343,10 @@ declare module Immutable {
        * second from each, etc.
        *
        * <!-- runkit:activate
-       *      { "preamble": "require('immutable@4.0.0-rc.5')"}
+       *      { "preamble": "require('immutable@4.0.0-rc.9')"}
        * -->
        * ```js
-       * const { List } = require('immutable@4.0.0-rc.5')
+       * const { List } = require('immutable@4.0.0-rc.9')
        * List([ 1, 2, 3 ]).interleave(List([ 'A', 'B', 'C' ]))
        * // List [ 1, "A", 2, "B", 3, "C"" ]
        * ```
@@ -3481,7 +3354,7 @@ declare module Immutable {
        * The shortest Collection stops interleave.
        *
        * <!-- runkit:activate
-       *      { "preamble": "const { List } = require('immutable@4.0.0-rc.5')" }
+       *      { "preamble": "const { List } = require('immutable@4.0.0-rc.9')" }
        * -->
        * ```js
        * List([ 1, 2, 3 ]).interleave(
@@ -3490,6 +3363,11 @@ declare module Immutable {
        * )
        * // List [ 1, "A", "X", 2, "B", "Y"" ]
        * ```
+       *
+       * Since `interleave()` re-indexes values, it produces a complete copy,
+       * which has `O(N)` complexity.
+       *
+       * Note: `interleave` *cannot* be used in `withMutations`.
        */
       interleave(...collections: Array<Collection<any, T>>): this;
 
@@ -3503,10 +3381,15 @@ declare module Immutable {
        *
        * <!-- runkit:activate -->
        * ```js
-       * const { List } = require('immutable@4.0.0-rc.5')
+       * const { List } = require('immutable@4.0.0-rc.9')
        * List([ 'a', 'b', 'c', 'd' ]).splice(1, 2, 'q', 'r', 's')
        * // List [ "a", "q", "r", "s", "d" ]
        * ```
+       *
+       * Since `splice()` re-indexes values, it produces a complete copy, which
+       * has `O(N)` complexity.
+       *
+       * Note: `splice` *cannot* be used in `withMutations`.
        */
       splice(
         index: number,
@@ -3522,7 +3405,7 @@ declare module Immutable {
        *
        *
        * <!-- runkit:activate
-       *      { "preamble": "const { List } = require('immutable@4.0.0-rc.5')" }
+       *      { "preamble": "const { List } = require('immutable@4.0.0-rc.9')" }
        * -->
        * ```js
        * const a = List([ 1, 2, 3 ]);
@@ -3555,7 +3438,7 @@ declare module Immutable {
        * collections by using a custom `zipper` function.
        *
        * <!-- runkit:activate
-       *      { "preamble": "const { List } = require('immutable@4.0.0-rc.5')" }
+       *      { "preamble": "const { List } = require('immutable@4.0.0-rc.9')" }
        * -->
        * ```js
        * const a = List([ 1, 2, 3 ]);
@@ -3623,7 +3506,7 @@ declare module Immutable {
        * `mapper` function.
        *
        * ```js
-       * const { Collection } = require('immutable@4.0.0-rc.5')
+       * const { Collection } = require('immutable@4.0.0-rc.9')
        * Collection.Indexed([1,2]).map(x => 10 * x)
        * // Seq [ 1, 2 ]
        * ```
@@ -3675,7 +3558,7 @@ declare module Immutable {
      * the value as both the first and second arguments to the provided function.
      *
      * ```js
-     * const { Collection } = require('immutable@4.0.0-rc.5')
+     * const { Collection } = require('immutable@4.0.0-rc.9')
      * const seq = Collection.Set([ 'A', 'B', 'C' ])
      * // Seq { "A", "B", "C" }
      * seq.forEach((v, k) =>
@@ -3717,7 +3600,7 @@ declare module Immutable {
       /**
        * Returns a new Collection with other collections concatenated to this one.
        */
-      concat<C>(...valuesOrCollections: Array<Iterable<C> | C>): Collection.Set<T | C>;
+      concat<U>(...collections: Array<Iterable<U>>): Collection.Set<T | U>;
 
       /**
        * Returns a new Collection.Set with values passed through a
@@ -3807,7 +3690,7 @@ declare module Immutable {
      * lookup via a different instance.
      *
      * <!-- runkit:activate
-     *      { "preamble": "const { Set,  List } = require('immutable@4.0.0-rc.5')" }
+     *      { "preamble": "const { Set,  List } = require('immutable@4.0.0-rc.9')" }
      * -->
      * ```js
      * const a = List([ 1, 2, 3 ]);
@@ -3869,6 +3752,23 @@ declare module Immutable {
     /**
      * Returns the value found by following a path of keys or indices through
      * nested Collections.
+     *
+     * <!-- runkit:activate -->
+     * ```js
+     * const { Map, List } = require('immutable@4.0.0-rc.9')
+     * const deepData = Map({ x: List([ Map({ y: 123 }) ]) });
+     * getIn(deepData, ['x', 0, 'y']) // 123
+     * ```
+     *
+     * Plain JavaScript Object or Arrays may be nested within an Immutable.js
+     * Collection, and getIn() can access those values as well:
+     *
+     * <!-- runkit:activate -->
+     * ```js
+     * const { Map, List } = require('immutable@4.0.0-rc.9')
+     * const deepData = Map({ x: [ { y: 123 } ] });
+     * getIn(deepData, ['x', 0, 'y']) // 123
+     * ```
      */
     getIn(searchKeyPath: Iterable<any>, notSetValue?: any): any;
 
@@ -3888,7 +3788,7 @@ declare module Immutable {
      *
      * <!-- runkit:activate -->
      * ```js
-     * const { Seq } = require('immutable@4.0.0-rc.5')
+     * const { Seq } = require('immutable@4.0.0-rc.9')
      *
      * function sum(collection) {
      *   return collection.reduce((sum, x) => sum + x, 0)
@@ -3984,7 +3884,7 @@ declare module Immutable {
      *
      * <!-- runkit:activate -->
      * ```js
-     * const { Map, List } = require('immutable@4.0.0-rc.5')
+     * const { Map, List } = require('immutable@4.0.0-rc.9')
      * var myMap = Map({ a: 'Apple', b: 'Banana' })
      * List(myMap) // List [ [ "a", "Apple" ], [ "b", "Banana" ] ]
      * myMap.toList() // List [ "Apple", "Banana" ]
@@ -4021,7 +3921,7 @@ declare module Immutable {
      *
      * <!-- runkit:activate -->
      * ```js
-     * const { Seq } = require('immutable@4.0.0-rc.5')
+     * const { Seq } = require('immutable@4.0.0-rc.9')
      * const indexedSeq = Seq([ 'A', 'B', 'C' ])
      * // Seq [ "A", "B", "C" ]
      * indexedSeq.filter(v => v === 'B')
@@ -4102,7 +4002,7 @@ declare module Immutable {
      *
      * <!-- runkit:activate -->
      * ```js
-     * const { Collection } = require('immutable@4.0.0-rc.5')
+     * const { Collection } = require('immutable@4.0.0-rc.9')
      * Collection({ a: 1, b: 2 }).map(x => 10 * x)
      * // Seq { "a": 10, "b": 20 }
      * ```
@@ -4129,7 +4029,7 @@ declare module Immutable {
      *
      * <!-- runkit:activate -->
      * ```js
-     * const { Map } = require('immutable@4.0.0-rc.5')
+     * const { Map } = require('immutable@4.0.0-rc.9')
      * Map({ a: 1, b: 2, c: 3, d: 4}).filter(x => x % 2 === 0)
      * // Map { "b": 2, "d": 4 }
      * ```
@@ -4152,7 +4052,7 @@ declare module Immutable {
      *
      * <!-- runkit:activate -->
      * ```js
-     * const { Map } = require('immutable@4.0.0-rc.5')
+     * const { Map } = require('immutable@4.0.0-rc.9')
      * Map({ a: 1, b: 2, c: 3, d: 4}).filterNot(x => x % 2 === 0)
      * // Map { "a": 1, "c": 3 }
      * ```
@@ -4189,7 +4089,7 @@ declare module Immutable {
      *
      * <!-- runkit:activate -->
      * ```js
-     * const { Map } = require('immutable@4.0.0-rc.5')
+     * const { Map } = require('immutable@4.0.0-rc.9')
      * Map({ "c": 3, "a": 1, "b": 2 }).sort((a, b) => {
      *   if (a < b) { return -1; }
      *   if (a > b) { return 1; }
@@ -4229,7 +4129,7 @@ declare module Immutable {
      *
      * <!-- runkit:activate -->
      * ```js
-     * const { List, Map } = require('immutable@4.0.0-rc.5')
+     * const { List, Map } = require('immutable@4.0.0-rc.9')
      * const listOfMaps = List([
      *   Map({ v: 0 }),
      *   Map({ v: 1 }),
@@ -4316,7 +4216,7 @@ declare module Immutable {
      *
      * <!-- runkit:activate -->
      * ```js
-     * const { List } = require('immutable@4.0.0-rc.5')
+     * const { List } = require('immutable@4.0.0-rc.9')
      * List([ 'dog', 'frog', 'cat', 'hat', 'god' ])
      *   .skipWhile(x => x.match(/g/))
      * // List [ "cat", "hat", "god"" ]
@@ -4333,7 +4233,7 @@ declare module Immutable {
      *
      * <!-- runkit:activate -->
      * ```js
-     * const { List } = require('immutable@4.0.0-rc.5')
+     * const { List } = require('immutable@4.0.0-rc.9')
      * List([ 'dog', 'frog', 'cat', 'hat', 'god' ])
      *   .skipUntil(x => x.match(/hat/))
      * // List [ "hat", "god"" ]
@@ -4362,7 +4262,7 @@ declare module Immutable {
      *
      * <!-- runkit:activate -->
      * ```js
-     * const { List } = require('immutable@4.0.0-rc.5')
+     * const { List } = require('immutable@4.0.0-rc.9')
      * List([ 'dog', 'frog', 'cat', 'hat', 'god' ])
      *   .takeWhile(x => x.match(/o/))
      * // List [ "dog", "frog" ]
@@ -4379,7 +4279,7 @@ declare module Immutable {
      *
      * <!-- runkit:activate -->
      * ```js
-     * const { List } = require('immutable@4.0.0-rc.5')
+     * const { List } = require('immutable@4.0.0-rc.9')
      * List([ 'dog', 'frog', 'cat', 'hat', 'god' ])
      *   .takeUntil(x => x.match(/at/))
      * // List [ "dog", "frog" ]
@@ -4674,6 +4574,578 @@ declare module Immutable {
      */
     isSuperset(iter: Iterable<V>): boolean;
   }
+
+  /**
+   * The interface to fulfill to qualify as a Value Object.
+   */
+  export interface ValueObject {
+    /**
+     * True if this and the other Collection have value equality, as defined
+     * by `Immutable.is()`.
+     *
+     * Note: This is equivalent to `Immutable.is(this, other)`, but provided to
+     * allow for chained expressions.
+     */
+    equals(other: any): boolean;
+
+    /**
+     * Computes and returns the hashed identity for this Collection.
+     *
+     * The `hashCode` of a Collection is used to determine potential equality,
+     * and is used when adding this to a `Set` or as a key in a `Map`, enabling
+     * lookup via a different instance.
+     *
+     * <!-- runkit:activate -->
+     * ```js
+     * const { List, Set } = require('immutable@4.0.0-rc.9');
+     * const a = List([ 1, 2, 3 ]);
+     * const b = List([ 1, 2, 3 ]);
+     * assert.notStrictEqual(a, b); // different instances
+     * const set = Set([ a ]);
+     * assert.equal(set.has(b), true);
+     * ```
+     *
+     * Note: hashCode() MUST return a Uint32 number. The easiest way to
+     * guarantee this is to return `myHash | 0` from a custom implementation.
+     *
+     * If two values have the same `hashCode`, they are [not guaranteed
+     * to be equal][Hash Collision]. If two values have different `hashCode`s,
+     * they must not be equal.
+     *
+     * Note: `hashCode()` is not guaranteed to always be called before
+     * `equals()`. Most but not all Immutable.js collections use hash codes to
+     * organize their internal data structures, while all Immutable.js
+     * collections use equality during lookups.
+     *
+     * [Hash Collision]: http://en.wikipedia.org/wiki/Collision_(computer_science)
+     */
+    hashCode(): number;
+  }
+
+  /**
+   * 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
+   * refering to each collection and the parent JS object provided as `this`.
+   * For the top level, object, the key will be `""`. This `reviver` is expected
+   * to return a new Immutable Collection, allowing for custom conversions from
+   * deep JS objects. Finally, a `path` is provided which is the sequence of
+   * keys to this value from the starting value.
+   *
+   * `reviver` acts similarly to the [same parameter in `JSON.parse`][1].
+   *
+   * If `reviver` is not provided, the default behavior will convert Objects
+   * into Maps and Arrays into Lists like so:
+   *
+   * <!-- runkit:activate -->
+   * ```js
+   * const { fromJS, isKeyed } = require('immutable@4.0.0-rc.9')
+   * function (key, value) {
+   *   return isKeyed(value) ? value.Map() : 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:
+   *
+   * <!-- runkit:activate -->
+   * ```js
+   * const { fromJS, isKeyed } = require('immutable@4.0.0-rc.9')
+   * fromJS({ a: {b: [10, 20, 30]}, c: 40}, function (key, value, path) {
+   *   console.log(key, value, path)
+   *   return isKeyed(value) ? value.toOrderedMap() : value.toList()
+   * })
+   *
+   * > "b", [ 10, 20, 30 ], [ "a", "b" ]
+   * > "a", {b: [10, 20, 30]}, [ "a" ]
+   * > "", {a: {b: [10, 20, 30]}, c: 40}, []
+   * ```
+   *
+   * Keep in mind, when using JS objects to construct Immutable Maps, that
+   * JavaScript Object properties are always strings, even if written in a
+   * quote-less shorthand, while Immutable Maps accept keys of any type.
+   *
+   * <!-- runkit:activate -->
+   * ```js
+   * const { Map } = require('immutable@4.0.0-rc.9')
+   * let obj = { 1: "one" };
+   * Object.keys(obj); // [ "1" ]
+   * assert.equal(obj["1"], obj[1]); // "one" === "one"
+   *
+   * let map = Map(obj);
+   * assert.notEqual(map.get("1"), map.get(1)); // "one" !== undefined
+   * ```
+   *
+   * Property access for JavaScript Objects first converts the key to a string,
+   * but since Immutable Map keys can be of any type the argument to `get()` is
+   * not altered.
+   *
+   * [1]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse#Example.3A_Using_the_reviver_parameter
+   *      "Using the reviver parameter"
+   */
+  export function fromJS(
+    jsValue: any,
+    reviver?: (
+      key: string | number,
+      sequence: Collection.Keyed<string, any> | Collection.Indexed<any>,
+      path?: Array<string | number>
+    ) => any
+  ): any;
+
+  /**
+   * Value equality check with semantics similar to `Object.is`, but treats
+   * Immutable `Collection`s as values, equal if the second `Collection` includes
+   * equivalent values.
+   *
+   * It's used throughout Immutable when checking for equality, including `Map`
+   * key equality and `Set` membership.
+   *
+   * <!-- runkit:activate -->
+   * ```js
+   * const { Map, is } = require('immutable@4.0.0-rc.9')
+   * 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.
+   */
+  export function is(first: any, second: any): boolean;
+
+  /**
+   * The `hash()` function is an important part of how Immutable determines if
+   * two values are equivalent and is used to determine how to store those
+   * values. Provided with any value, `hash()` will return a 31-bit integer.
+   *
+   * When designing Objects which may be equal, it's important than 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*
+   */
+  export function hash(value: any): number;
+
+  /**
+   * True if `maybeImmutable` is an Immutable Collection or Record.
+   *
+   * Note: Still returns true even if the collections is within a `withMutations()`.
+   *
+   * <!-- runkit:activate -->
+   * ```js
+   * const { isImmutable, Map, List, Stack } = require('immutable@4.0.0-rc.9');
+   * isImmutable([]); // false
+   * isImmutable({}); // false
+   * isImmutable(Map()); // true
+   * isImmutable(List()); // true
+   * isImmutable(Stack()); // true
+   * isImmutable(Map().asMutable()); // true
+   * ```
+   */
+  export function isImmutable(maybeImmutable: any): maybeImmutable is Collection<any, any>;
+
+  /**
+   * True if `maybeCollection` is a Collection, or any of its subclasses.
+   *
+   * <!-- runkit:activate -->
+   * ```js
+   * const { isCollection, Map, List, Stack } = require('immutable@4.0.0-rc.9');
+   * isCollection([]); // false
+   * isCollection({}); // false
+   * isCollection(Map()); // true
+   * isCollection(List()); // true
+   * isCollection(Stack()); // true
+   * ```
+   */
+  export function isCollection(maybeCollection: any): maybeCollection is Collection<any, any>;
+
+  /**
+   * True if `maybeKeyed` is a Collection.Keyed, or any of its subclasses.
+   *
+   * <!-- runkit:activate -->
+   * ```js
+   * const { isKeyed, Map, List, Stack } = require('immutable@4.0.0-rc.9');
+   * isKeyed([]); // false
+   * isKeyed({}); // false
+   * isKeyed(Map()); // true
+   * isKeyed(List()); // false
+   * isKeyed(Stack()); // false
+   * ```
+   */
+  export function isKeyed(maybeKeyed: any): maybeKeyed is Collection.Keyed<any, any>;
+
+  /**
+   * True if `maybeIndexed` is a Collection.Indexed, or any of its subclasses.
+   *
+   * <!-- runkit:activate -->
+   * ```js
+   * const { isIndexed, Map, List, Stack, Set } = require('immutable@4.0.0-rc.9');
+   * isIndexed([]); // false
+   * isIndexed({}); // false
+   * isIndexed(Map()); // false
+   * isIndexed(List()); // true
+   * isIndexed(Stack()); // true
+   * isIndexed(Set()); // false
+   * ```
+   */
+  export function isIndexed(maybeIndexed: any): maybeIndexed is Collection.Indexed<any>;
+
+  /**
+   * True if `maybeAssociative` is either a Keyed or Indexed Collection.
+   *
+   * <!-- runkit:activate -->
+   * ```js
+   * const { isAssociative, Map, List, Stack, Set } = require('immutable@4.0.0-rc.9');
+   * isAssociative([]); // false
+   * isAssociative({}); // false
+   * isAssociative(Map()); // true
+   * isAssociative(List()); // true
+   * isAssociative(Stack()); // true
+   * isAssociative(Set()); // false
+   * ```
+   */
+  export function isAssociative(maybeAssociative: any): maybeAssociative is Collection.Keyed<any, any> | Collection.Indexed<any>;
+
+  /**
+   * True if `maybeOrdered` is a Collection where iteration order is well
+   * defined. True for Collection.Indexed as well as OrderedMap and OrderedSet.
+   *
+   * <!-- runkit:activate -->
+   * ```js
+   * const { isOrdered, Map, OrderedMap, List, Set } = require('immutable@4.0.0-rc.9');
+   * isOrdered([]); // false
+   * isOrdered({}); // false
+   * isOrdered(Map()); // false
+   * isOrdered(OrderedMap()); // true
+   * isOrdered(List()); // true
+   * isOrdered(Set()); // false
+   * ```
+   */
+  export function isOrdered(maybeOrdered: any): boolean;
+
+  /**
+   * 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`.
+   */
+  export function isValueObject(maybeValue: any): maybeValue is ValueObject;
+
+  /**
+   * Returns the value within the provided collection associated with the
+   * provided key, or notSetValue if the key is not defined in the collection.
+   *
+   * A functional alternative to `collection.get(key)` which will also work on
+   * plain Objects and Arrays as an alternative for `collection[key]`.
+   *
+   * <!-- runkit:activate -->
+   * ```js
+   * const { get } = require('immutable@4.0.0-rc.9')
+   * get([ 'dog', 'frog', 'cat' ], 2) // 'frog'
+   * get({ x: 123, y: 456 }, 'x') // 123
+   * get({ x: 123, y: 456 }, 'z', 'ifNotSet') // 'ifNotSet'
+   * ```
+   */
+  export function get<K, V>(collection: Collection<K, V>, key: K): V | undefined;
+  export function get<K, V, NSV>(collection: Collection<K, V>, key: K, notSetValue: NSV): V | NSV;
+  export function get<TProps, K extends keyof TProps>(record: Record<TProps>, key: K, notSetValue: any): TProps[K];
+  export function get<V>(collection: Array<V>, key: number): V | undefined;
+  export function get<V, NSV>(collection: Array<V>, key: number, notSetValue: NSV): V | NSV;
+  export function get<C extends Object, K extends keyof C>(object: C, key: K, notSetValue: any): C[K];
+  export function get<V>(collection: {[key: string]: V}, key: string): V | undefined;
+  export function get<V, NSV>(collection: {[key: string]: V}, key: string, notSetValue: NSV): V | NSV;
+
+  /**
+   * Returns true if the key is defined in the provided collection.
+   *
+   * A functional alternative to `collection.has(key)` which will also work with
+   * plain Objects and Arrays as an alternative for
+   * `collection.hasOwnProperty(key)`.
+   *
+   * <!-- runkit:activate -->
+   * ```js
+   * const { has } = require('immutable@4.0.0-rc.9')
+   * has([ 'dog', 'frog', 'cat' ], 2) // true
+   * has([ 'dog', 'frog', 'cat' ], 5) // false
+   * has({ x: 123, y: 456 }, 'x') // true
+   * has({ x: 123, y: 456 }, 'z') // false
+   * ```
+   */
+  export function has(collection: Object, key: any): boolean;
+
+  /**
+   * Returns a copy of the collection with the value at key removed.
+   *
+   * A functional alternative to `collection.remove(key)` which will also work
+   * with plain Objects and Arrays as an alternative for
+   * `delete collectionCopy[key]`.
+   *
+   * <!-- runkit:activate -->
+   * ```js
+   * const { remove } = require('immutable@4.0.0-rc.9')
+   * 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 }
+   * ```
+   */
+  export function remove<K, C extends Collection<K, any>>(collection: C, key: K): C;
+  export function remove<TProps, C extends Record<TProps>, K extends keyof TProps>(collection: C, key: K): C;
+  export function remove<C extends Array<any>>(collection: C, key: number): C;
+  export function remove<C, K extends keyof C>(collection: C, key: K): C;
+  export function remove<C extends {[key: string]: any}, K extends keyof C>(collection: C, key: K): C;
+
+  /**
+   * Returns a copy of the collection with the value at key set to the provided
+   * value.
+   *
+   * A functional alternative to `collection.set(key, value)` which will also
+   * work with plain Objects and Arrays as an alternative for
+   * `collectionCopy[key] = value`.
+   *
+   * <!-- runkit:activate -->
+   * ```js
+   * const { set } = require('immutable@4.0.0-rc.9')
+   * 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 }
+   * ```
+   */
+  export function set<K, V, C extends Collection<K, V>>(collection: C, key: K, value: V): C;
+  export function set<TProps, C extends Record<TProps>, K extends keyof TProps>(record: C, key: K, value: TProps[K]): C;
+  export function set<V, C extends Array<V>>(collection: C, key: number, value: V): C;
+  export function set<C, K extends keyof C>(object: C, key: K, value: C[K]): C;
+  export function set<V, C extends {[key: string]: V}>(collection: C, key: string, value: V): C;
+
+  /**
+   * Returns a copy of the collection with the value at key set to the result of
+   * providing the existing value to the updating function.
+   *
+   * A functional alternative to `collection.update(key, fn)` which will also
+   * work with plain Objects and Arrays as an alternative for
+   * `collectionCopy[key] = fn(collection[key])`.
+   *
+   * <!-- runkit:activate -->
+   * ```js
+   * const { update } = require('immutable@4.0.0-rc.9')
+   * 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 }
+   * set(originalObject, 'x', val => val * 6) // { x: 738, y: 456 }
+   * console.log(originalObject) // { x: 123, y: 456 }
+   * ```
+   */
+  export function update<K, V, C extends Collection<K, V>>(collection: C, key: K, updater: (value: V) => V): C;
+  export function update<K, V, C extends Collection<K, V>, NSV>(collection: C, key: K, notSetValue: NSV, updater: (value: V | NSV) => V): C;
+  export function update<TProps, C extends Record<TProps>, K extends keyof TProps>(record: C, key: K, updater: (value: TProps[K]) => TProps[K]): C;
+  export function update<TProps, C extends Record<TProps>, K extends keyof TProps, NSV>(record: C, key: K, notSetValue: NSV, updater: (value: TProps[K] | NSV) => TProps[K]): C;
+  export function update<V>(collection: Array<V>, key: number, updater: (value: V) => V): Array<V>;
+  export function update<V, NSV>(collection: Array<V>, key: number, notSetValue: NSV, updater: (value: V | NSV) => V): Array<V>;
+  export function update<C, K extends keyof C>(object: C, key: K, updater: (value: C[K]) => C[K]): C;
+  export function update<C, K extends keyof C, NSV>(object: C, key: K, notSetValue: NSV, updater: (value: C[K] | NSV) => C[K]): C;
+  export function update<V, C extends {[key: string]: V}, K extends keyof C>(collection: C, key: K, updater: (value: V) => V): {[key: string]: V};
+  export function update<V, C extends {[key: string]: V}, K extends keyof C, NSV>(collection: C, key: K, notSetValue: NSV, updater: (value: V | NSV) => V): {[key: string]: V};
+
+  /**
+   * Returns the value at the provided key path starting at the provided
+   * collection, or notSetValue if the key path is not defined.
+   *
+   * A functional alternative to `collection.getIn(keypath)` which will also
+   * work with plain Objects and Arrays.
+   *
+   * <!-- runkit:activate -->
+   * ```js
+   * const { getIn } = require('immutable@4.0.0-rc.9')
+   * getIn({ x: { y: { z: 123 }}}, ['x', 'y', 'z']) // 123
+   * getIn({ x: { y: { z: 123 }}}, ['x', 'q', 'p'], 'ifNotSet') // 'ifNotSet'
+   * ```
+   */
+  export function getIn(collection: any, keyPath: Iterable<any>, notSetValue: any): any;
+
+  /**
+   * Returns true if the key path is defined in the provided collection.
+   *
+   * A functional alternative to `collection.hasIn(keypath)` which will also
+   * work with plain Objects and Arrays.
+   *
+   * <!-- runkit:activate -->
+   * ```js
+   * const { hasIn } = require('immutable@4.0.0-rc.9')
+   * hasIn({ x: { y: { z: 123 }}}, ['x', 'y', 'z']) // true
+   * hasIn({ x: { y: { z: 123 }}}, ['x', 'q', 'p']) // false
+   * ```
+   */
+  export function hasIn(collection: any, keyPath: Iterable<any>): boolean;
+
+  /**
+   * Returns a copy of the collection with the value at the key path removed.
+   *
+   * A functional alternative to `collection.removeIn(keypath)` which will also
+   * work with plain Objects and Arrays.
+   *
+   * <!-- runkit:activate -->
+   * ```js
+   * const { removeIn } = require('immutable@4.0.0-rc.9')
+   * const original = { x: { y: { z: 123 }}}
+   * removeIn(original, ['x', 'y', 'z']) // { x: { y: {}}}
+   * console.log(original) // { x: { y: { z: 123 }}}
+   * ```
+   */
+  export function removeIn<C>(collection: C, keyPath: Iterable<any>): C;
+
+  /**
+   * Returns a copy of the collection with the value at the key path set to the
+   * provided value.
+   *
+   * A functional alternative to `collection.setIn(keypath)` which will also
+   * work with plain Objects and Arrays.
+   *
+   * <!-- runkit:activate -->
+   * ```js
+   * const { setIn } = require('immutable@4.0.0-rc.9')
+   * const original = { x: { y: { z: 123 }}}
+   * setIn(original, ['x', 'y', 'z'], 456) // { x: { y: { z: 456 }}}
+   * console.log(original) // { x: { y: { z: 123 }}}
+   * ```
+   */
+  export function setIn<C>(collection: C, keyPath: Iterable<any>, value: any): C;
+
+  /**
+   * Returns a copy of the collection with the value at key path set to the
+   * result of providing the existing value to the updating function.
+   *
+   * A functional alternative to `collection.updateIn(keypath)` which will also
+   * work with plain Objects and Arrays.
+   *
+   * <!-- runkit:activate -->
+   * ```js
+   * const { setIn } = require('immutable@4.0.0-rc.9')
+   * const original = { x: { y: { z: 123 }}}
+   * setIn(original, ['x', 'y', 'z'], val => val * 6) // { x: { y: { z: 738 }}}
+   * console.log(original) // { x: { y: { z: 123 }}}
+   * ```
+   */
+  export function updateIn<C>(collection: C, keyPath: Iterable<any>, updater: (value: any) => any): C;
+  export function updateIn<C>(collection: C, keyPath: Iterable<any>, notSetValue: any, updater: (value: any) => any): C;
+
+  /**
+   * Returns a copy of the collection with the remaining collections merged in.
+   *
+   * A functional alternative to `collection.merge()` which will also work with
+   * plain Objects and Arrays.
+   *
+   * <!-- runkit:activate -->
+   * ```js
+   * const { merge } = require('immutable@4.0.0-rc.9')
+   * const original = { x: 123, y: 456 }
+   * merge(original, { y: 789, z: 'abc' }) // { x: 123, y: 789, z: 'abc' }
+   * console.log(original) // { x: { y: { z: 123 }}}
+   * ```
+   */
+  export function merge<C>(
+    collection: C,
+    ...collections: Array<Iterable<any> | Iterable<[any, any]> | {[key: string]: any}>
+  ): C;
+
+  /**
+   * Returns a copy of the collection with the remaining collections merged in,
+   * calling the `merger` function whenever an existing value is encountered.
+   *
+   * A functional alternative to `collection.mergeWith()` which will also work
+   * with plain Objects and Arrays.
+   *
+   * <!-- runkit:activate -->
+   * ```js
+   * const { mergeWith } = require('immutable@4.0.0-rc.9')
+   * 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: { y: { z: 123 }}}
+   * ```
+   */
+  export function mergeWith<C>(
+    merger: (oldVal: any, newVal: any, key: any) => any,
+    collection: C,
+    ...collections: Array<Iterable<any> | Iterable<[any, any]> | {[key: string]: any}>
+  ): C;
+
+  /**
+   * 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.
+   *
+   * <!-- runkit:activate -->
+   * ```js
+   * const { merge } = require('immutable@4.0.0-rc.9')
+   * const original = { x: { y: 123 }}
+   * merge(original, { x: { z: 456 }}) // { x: { y: 123, z: 456 }}
+   * console.log(original) // { x: { y: 123 }}
+   * ```
+   */
+  export function mergeDeep<C>(
+    collection: C,
+    ...collections: Array<Iterable<any> | Iterable<[any, any]> | {[key: string]: any}>
+  ): C;
+
+  /**
+   * 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.
+   *
+   * <!-- runkit:activate -->
+   * ```js
+   * const { merge } = require('immutable@4.0.0-rc.9')
+   * const original = { x: { y: 123 }}
+   * mergeDeepWith(
+   *   (oldVal, newVal) => oldVal + newVal,
+   *   original,
+   *   { x: { y: 456 }}
+   * ) // { x: { y: 579 }}
+   * console.log(original) // { x: { y: 123 }}
+   * ```
+   */
+  export function mergeDeepWith<C>(
+    merger: (oldVal: any, newVal: any, key: any) => any,
+    collection: C,
+    ...collections: Array<Iterable<any> | Iterable<[any, any]> | {[key: string]: any}>
+  ): C;
 }
 
 declare module "immutable" {