immutable 4.0.0-rc.14 → 4.0.0-rc.15

package/dist/immutable.d.ts

@@ -90,7 +90,7 @@
  * [Iterable]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols
  */
 
-declare module Immutable {
+declare namespace Immutable {
   /**
    * Lists are ordered indexed dense collections, much like a JavaScript
    * Array.
@@ -105,7 +105,7 @@ declare module Immutable {
    * "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 {
+  namespace List {
     /**
      * True if the provided value is a List
      *
@@ -171,11 +171,9 @@ declare module Immutable {
    * listFromPlainSet.equals(listFromPlainArray) // true
    * ```
    */
-  export function List<T>(collection: Iterable<T>): List<T>;
-  export function List<T>(): List<T>;
-  export function List(): List<unknown>;
+  function List<T>(collection?: Iterable<T> | ArrayLike<T>): List<T>;
 
-  export interface List<T> extends Collection.Indexed<T> {
+  interface List<T> extends Collection.Indexed<T> {
     /**
      * The number of items in this List.
      */
@@ -661,7 +659,7 @@ declare module Immutable {
       thirdCollection: Collection<unknown, V>
     ): List<Z>;
     zipWith<Z>(
-      zipper: (...any: Array<unknown>) => Z,
+      zipper: (...values: Array<unknown>) => Z,
       ...collections: Array<Collection<unknown, unknown>>
     ): List<Z>;
   }
@@ -693,7 +691,7 @@ declare module Immutable {
    *
    * Implemented by a hash-array mapped trie.
    */
-  export module Map {
+  namespace Map {
     /**
      * True if the provided value is a Map
      *
@@ -761,13 +759,11 @@ declare module Immutable {
    * but since Immutable Map keys can be of any type the argument to `get()` is
    * not altered.
    */
-  export function Map(): Map<unknown, unknown>;
-  export function Map<K, V>(): Map<K, V>;
-  export function Map<K, V>(collection: Iterable<[K, V]>): Map<K, V>;
-  export function Map<V>(obj: { [key: string]: V }): Map<string, V>;
-  export function Map<K extends string, V>(obj: { [P in K]?: V }): Map<K, V>;
+  function Map<K, V>(collection?: Iterable<[K, V]>): Map<K, V>;
+  function Map<V>(obj: { [key: string]: V }): Map<string, V>;
+  function Map<K extends string, V>(obj: { [P in K]?: V }): Map<K, V>;
 
-  export interface Map<K, V> extends Collection.Keyed<K, V> {
+  interface Map<K, V> extends Collection.Keyed<K, V> {
     /**
      * The number of entries in this Map.
      */
@@ -1019,12 +1015,18 @@ declare module Immutable {
     ): this;
 
     /**
-     * Like `merge()`, but when two Collections conflict, it merges them as well,
-     * recursing deeply through the nested data.
+     * Like `merge()`, but when two compatible collections are encountered with
+     * the same key, it merges them as well, recursing deeply through the nested
+     * data. Two collections are considered to be compatible (and thus will be
+     * merged together) if they both fall into one of three categories: keyed
+     * (e.g., `Map`s, `Record`s, and objects), indexed (e.g., `List`s and
+     * arrays), or set-like (e.g., `Set`s). If they fall into separate
+     * categories, `mergeDeep` will replace the existing collection with the
+     * collection being merged in. This behavior can be customized by using
+     * `mergeDeepWith()`.
      *
-     * Note: Values provided to `merge` are shallowly converted before being
-     * merged. No nested values are altered unless they will also be merged at
-     * a deeper level.
+     * Note: Indexed and set-like collections are merged using
+     * `concat()`/`union()` and therefore do not recurse.
      *
      * <!-- runkit:activate -->
      * ```js
@@ -1046,8 +1048,11 @@ declare module Immutable {
     ): this;
 
     /**
-     * Like `mergeDeep()`, but when two non-Collections conflict, it uses the
-     * `merger` function to determine the resulting value.
+     * Like `mergeDeep()`, but when two non-collections or incompatible
+     * collections are encountered at the same key, it uses the `merger`
+     * function to determine the resulting value. Collections are considered
+     * incompatible if they fall into separate categories between keyed,
+     * indexed, and set-like.
      *
      * <!-- runkit:activate -->
      * ```js
@@ -1061,7 +1066,7 @@ declare module Immutable {
      * //   "c": Map { "z": 3 }
      * // }
      * ```
-
+     *
      * Note: `mergeDeepWith` can be used in `withMutations`.
      */
     mergeDeepWith(
@@ -1367,7 +1372,11 @@ declare module Immutable {
      * @see Collection.Keyed.mapEntries
      */
     mapEntries<KM, VM>(
-      mapper: (entry: [K, V], index: number, iter: this) => [KM, VM] | undefined,
+      mapper: (
+        entry: [K, V],
+        index: number,
+        iter: this
+      ) => [KM, VM] | undefined,
       context?: unknown
     ): Map<KM, VM>;
 
@@ -1414,8 +1423,7 @@ declare module Immutable {
    * consume more memory. `OrderedMap#set` is amortized O(log32 N), but not
    * stable.
    */
-
-  export module OrderedMap {
+  namespace OrderedMap {
     /**
      * True if the provided value is an OrderedMap.
      */
@@ -1439,16 +1447,10 @@ declare module Immutable {
    * Note: `OrderedMap` is a factory function and not a class, and does not use
    * the `new` keyword during construction.
    */
-  export function OrderedMap(): OrderedMap<unknown, unknown>;
-  export function OrderedMap<K, V>(): OrderedMap<K, V>;
-  export function OrderedMap<K, V>(
-    collection: Iterable<[K, V]>
-  ): OrderedMap<K, V>;
-  export function OrderedMap<V>(obj: {
-    [key: string]: V;
-  }): OrderedMap<string, V>;
+  function OrderedMap<K, V>(collection?: Iterable<[K, V]>): OrderedMap<K, V>;
+  function OrderedMap<V>(obj: { [key: string]: V }): OrderedMap<string, V>;
 
-  export interface OrderedMap<K, V> extends Map<K, V> {
+  interface OrderedMap<K, V> extends Map<K, V> {
     /**
      * The number of entries in this OrderedMap.
      */
@@ -1538,7 +1540,11 @@ declare module Immutable {
      * @see Collection.Keyed.mapEntries
      */
     mapEntries<KM, VM>(
-      mapper: (entry: [K, V], index: number, iter: this) => [KM, VM] | undefined,
+      mapper: (
+        entry: [K, V],
+        index: number,
+        iter: this
+      ) => [KM, VM] | undefined,
       context?: unknown
     ): OrderedMap<KM, VM>;
 
@@ -1585,7 +1591,7 @@ declare module Immutable {
    * `Immutable.is`, enabling Sets to uniquely include other Immutable
    * collections, custom value types, and NaN.
    */
-  export module Set {
+  namespace Set {
     /**
      * True if the provided value is a Set
      */
@@ -1641,11 +1647,9 @@ declare module Immutable {
    * Note: `Set` is a factory function and not a class, and does not use the
    * `new` keyword during construction.
    */
-  export function Set<T>(collection: Iterable<T>): Set<T>;
-  export function Set<T>(): Set<T>;
-  export function Set(): Set<unknown>;
+  function Set<T>(collection?: Iterable<T> | ArrayLike<T>): Set<T>;
 
-  export interface Set<T> extends Collection.Set<T> {
+  interface Set<T> extends Collection.Set<T> {
     /**
      * The number of items in this Set.
      */
@@ -1795,7 +1799,7 @@ declare module Immutable {
    * consume more memory. `OrderedSet#add` is amortized O(log32 N), but not
    * stable.
    */
-  export module OrderedSet {
+  namespace OrderedSet {
     /**
      * True if the provided value is an OrderedSet.
      */
@@ -1821,11 +1825,11 @@ declare module Immutable {
    * Note: `OrderedSet` is a factory function and not a class, and does not use
    * the `new` keyword during construction.
    */
-  export function OrderedSet<T>(collection: Iterable<T>): OrderedSet<T>;
-  export function OrderedSet<T>(): OrderedSet<T>;
-  export function OrderedSet(): OrderedSet<unknown>;
+  function OrderedSet<T>(
+    collection?: Iterable<T> | ArrayLike<T>
+  ): OrderedSet<T>;
 
-  export interface OrderedSet<T> extends Set<T> {
+  interface OrderedSet<T> extends Set<T> {
     /**
      * The number of items in this OrderedSet.
      */
@@ -1947,7 +1951,7 @@ declare module Immutable {
       thirdCollection: Collection<unknown, V>
     ): OrderedSet<Z>;
     zipWith<Z>(
-      zipper: (...any: Array<unknown>) => Z,
+      zipper: (...values: Array<unknown>) => Z,
       ...collections: Array<Collection<unknown, unknown>>
     ): OrderedSet<Z>;
   }
@@ -1965,7 +1969,7 @@ declare module Immutable {
    *
    * Stack is implemented with a Single-Linked List.
    */
-  export module Stack {
+  namespace Stack {
     /**
      * True if the provided value is a Stack
      */
@@ -1987,11 +1991,9 @@ declare module Immutable {
    * Note: `Stack` is a factory function and not a class, and does not use the
    * `new` keyword during construction.
    */
-  export function Stack<T>(collection: Iterable<T>): Stack<T>;
-  export function Stack<T>(): Stack<T>;
-  export function Stack(): Stack<unknown>;
+  function Stack<T>(collection?: Iterable<T> | ArrayLike<T>): Stack<T>;
 
-  export interface Stack<T> extends Collection.Indexed<T> {
+  interface Stack<T> extends Collection.Indexed<T> {
     /**
      * The number of items in this Stack.
      */
@@ -2197,7 +2199,7 @@ declare module Immutable {
       thirdCollection: Collection<unknown, V>
     ): Stack<Z>;
     zipWith<Z>(
-      zipper: (...any: Array<unknown>) => Z,
+      zipper: (...values: Array<unknown>) => Z,
       ...collections: Array<Collection<unknown, unknown>>
     ): Stack<Z>;
   }
@@ -2220,7 +2222,7 @@ declare module Immutable {
    * Range(30, 30, 5) // []
    * ```
    */
-  export function Range(
+  function Range(
     start?: number,
     end?: number,
     step?: number
@@ -2239,7 +2241,7 @@ declare module Immutable {
    * Repeat('bar', 4) // [ 'bar', 'bar', 'bar', 'bar' ]
    * ```
    */
-  export function Repeat<T>(value: T, times?: number): Seq.Indexed<T>;
+  function Repeat<T>(value: T, times?: number): Seq.Indexed<T>;
 
   /**
    * A record is similar to a JS object, but enforces a specific set of allowed
@@ -2400,11 +2402,11 @@ declare module Immutable {
    *   form isn't free. If converting Records to plain objects is common,
    *   consider sticking with plain objects to begin with.
    */
-  export module Record {
+  namespace Record {
     /**
      * True if `maybeRecord` is an instance of a Record.
      */
-    export function isRecord(maybeRecord: unknown): maybeRecord is Record<{}>;
+    function isRecord(maybeRecord: unknown): maybeRecord is Record<{}>;
 
     /**
      * Records allow passing a second parameter to supply a descriptive name
@@ -2423,7 +2425,7 @@ declare module Immutable {
      * Record.getDescriptiveName(me) // "Person"
      * ```
      */
-    export function getDescriptiveName(record: Record<any>): string;
+    function getDescriptiveName(record: Record<any>): string;
 
     /**
      * A Record.Factory is created by the `Record()` function. Record instances
@@ -2473,15 +2475,14 @@ declare module Immutable {
      * const alan: Person = makePerson({ name: 'Alan' });
      * ```
      */
-    export module Factory {}
+    namespace Factory {}
 
-    export interface Factory<TProps extends Object> {
+    interface Factory<TProps extends object> {
       (values?: Partial<TProps> | Iterable<[string, unknown]>): Record<TProps> &
         Readonly<TProps>;
-      new (values?: Partial<TProps> | Iterable<[string, unknown]>): Record<
-        TProps
-      > &
-        Readonly<TProps>;
+      new (
+        values?: Partial<TProps> | Iterable<[string, unknown]>
+      ): Record<TProps> & Readonly<TProps>;
 
       /**
        * The name provided to `Record(values, name)` can be accessed with
@@ -2490,7 +2491,7 @@ declare module Immutable {
       displayName: string;
     }
 
-    export function Factory<TProps extends Object>(
+    function Factory<TProps extends object>(
       values?: Partial<TProps> | Iterable<[string, unknown]>
     ): Record<TProps> & Readonly<TProps>;
   }
@@ -2504,12 +2505,12 @@ declare module Immutable {
    * Note: `Record` is a factory function and not a class, and does not use the
    * `new` keyword during construction.
    */
-  export function Record<TProps>(
+  function Record<TProps extends object>(
     defaultValues: TProps,
     name?: string
   ): Record.Factory<TProps>;
 
-  export interface Record<TProps extends Object> {
+  interface Record<TProps extends object> {
     // Reading values
 
     has(key: string): key is keyof TProps & string;
@@ -2650,8 +2651,7 @@ declare module Immutable {
    *
    * This is equivalent to an instance of a record created by a Record Factory.
    */
-  export type RecordOf<TProps extends Object> = Record<TProps> &
-    Readonly<TProps>;
+  type RecordOf<TProps extends object> = Record<TProps> & Readonly<TProps>;
 
   /**
    * `Seq` describes a lazy operation, allowing them to efficiently chain
@@ -2728,7 +2728,7 @@ declare module Immutable {
    * ```
    */
 
-  export module Seq {
+  namespace Seq {
     /**
      * True if `maybeSeq` is a Seq, it is not backed by a concrete
      * structure such as Map, List, or Set.
@@ -2743,7 +2743,7 @@ declare module Immutable {
     /**
      * `Seq` which represents key-value pairs.
      */
-    export module Keyed {}
+    namespace Keyed {}
 
     /**
      * Always returns a Seq.Keyed, if input is not keyed, expects an
@@ -2752,12 +2752,10 @@ declare module Immutable {
      * Note: `Seq.Keyed` is a conversion function and not a class, and does not
      * use the `new` keyword during construction.
      */
-    export function Keyed<K, V>(collection: Iterable<[K, V]>): Seq.Keyed<K, V>;
-    export function Keyed<V>(obj: { [key: string]: V }): Seq.Keyed<string, V>;
-    export function Keyed<K, V>(): Seq.Keyed<K, V>;
-    export function Keyed(): Seq.Keyed<unknown, unknown>;
+    function Keyed<K, V>(collection?: Iterable<[K, V]>): Seq.Keyed<K, V>;
+    function Keyed<V>(obj: { [key: string]: V }): Seq.Keyed<string, V>;
 
-    export interface Keyed<K, V> extends Seq<K, V>, Collection.Keyed<K, V> {
+    interface Keyed<K, V> extends Seq<K, V>, Collection.Keyed<K, V> {
       /**
        * Deeply converts this Keyed Seq to equivalent native JavaScript Object.
        *
@@ -2825,7 +2823,11 @@ declare module Immutable {
        * @see Collection.Keyed.mapEntries
        */
       mapEntries<KM, VM>(
-        mapper: (entry: [K, V], index: number, iter: this) => [KM, VM] | undefined,
+        mapper: (
+          entry: [K, V],
+          index: number,
+          iter: this
+        ) => [KM, VM] | undefined,
         context?: unknown
       ): Seq.Keyed<KM, VM>;
 
@@ -2859,12 +2861,14 @@ declare module Immutable {
        * @see Collection.Keyed.flip
        */
       flip(): Seq.Keyed<V, K>;
+
+      [Symbol.iterator](): IterableIterator<[K, V]>;
     }
 
     /**
      * `Seq` which represents an ordered indexed list of values.
      */
-    module Indexed {
+    namespace Indexed {
       /**
        * Provides an Seq.Indexed of the values provided.
        */
@@ -2878,11 +2882,9 @@ declare module Immutable {
      * Note: `Seq.Indexed` is a conversion function and not a class, and does
      * not use the `new` keyword during construction.
      */
-    export function Indexed<T>(collection: Iterable<T>): Seq.Indexed<T>;
-    export function Indexed<T>(): Seq.Indexed<T>;
-    export function Indexed(): Seq.Indexed<unknown>;
+    function Indexed<T>(collection: Iterable<T> | ArrayLike<T>): Seq.Indexed<T>;
 
-    export interface Indexed<T> extends Seq<number, T>, Collection.Indexed<T> {
+    interface Indexed<T> extends Seq<number, T>, Collection.Indexed<T> {
       /**
        * Deeply converts this Indexed Seq to equivalent native JavaScript Array.
        */
@@ -3016,9 +3018,11 @@ declare module Immutable {
         thirdCollection: Collection<unknown, V>
       ): Seq.Indexed<Z>;
       zipWith<Z>(
-        zipper: (...any: Array<unknown>) => Z,
+        zipper: (...values: Array<unknown>) => Z,
         ...collections: Array<Collection<unknown, unknown>>
       ): Seq.Indexed<Z>;
+
+      [Symbol.iterator](): IterableIterator<T>;
     }
 
     /**
@@ -3027,7 +3031,7 @@ declare module Immutable {
      * Because `Seq` are often lazy, `Seq.Set` does not provide the same guarantee
      * of value uniqueness as the concrete `Set`.
      */
-    export module Set {
+    namespace Set {
       /**
        * Returns a Seq.Set of the provided values
        */
@@ -3040,11 +3044,9 @@ declare module Immutable {
      * Note: `Seq.Set` is a conversion function and not a class, and does not
      * use the `new` keyword during construction.
      */
-    export function Set<T>(collection: Iterable<T>): Seq.Set<T>;
-    export function Set<T>(): Seq.Set<T>;
-    export function Set(): Seq.Set<unknown>;
+    function Set<T>(collection: Iterable<T> | ArrayLike<T>): Seq.Set<T>;
 
-    export interface Set<T> extends Seq<T, T>, Collection.Set<T> {
+    interface Set<T> extends Seq<T, T>, Collection.Set<T> {
       /**
        * Deeply converts this Set Seq to equivalent native JavaScript Array.
        */
@@ -3115,6 +3117,8 @@ declare module Immutable {
         predicate: (value: T, key: T, iter: this) => unknown,
         context?: unknown
       ): this;
+
+      [Symbol.iterator](): IterableIterator<T>;
     }
   }
 
@@ -3137,17 +3141,16 @@ declare module Immutable {
    * Note: `Seq` is a conversion function and not a class, and does not use the
    * `new` keyword during construction.
    */
-  export function Seq<S extends Seq<unknown, unknown>>(seq: S): S;
-  export function Seq<K, V>(
-    collection: Collection.Keyed<K, V>
-  ): Seq.Keyed<K, V>;
-  export function Seq<T>(collection: Collection.Indexed<T>): Seq.Indexed<T>;
-  export function Seq<T>(collection: Collection.Set<T>): Seq.Set<T>;
-  export function Seq<T>(collection: Iterable<T>): Seq.Indexed<T>;
-  export function Seq<V>(obj: { [key: string]: V }): Seq.Keyed<string, V>;
-  export function Seq(): Seq<unknown, unknown>;
-
-  export interface Seq<K, V> extends Collection<K, V> {
+  function Seq<S extends Seq<unknown, unknown>>(seq: S): S;
+  function Seq<K, V>(collection: Collection.Keyed<K, V>): Seq.Keyed<K, V>;
+  function Seq<T>(collection: Collection.Set<T>): Seq.Set<T>;
+  function Seq<T>(
+    collection: Collection.Indexed<T> | Iterable<T> | ArrayLike<T>
+  ): Seq.Indexed<T>;
+  function Seq<V>(obj: { [key: string]: V }): Seq.Keyed<string, V>;
+  function Seq(): Seq<unknown, unknown>;
+
+  interface Seq<K, V> extends Collection<K, V> {
     /**
      * Some Seqs can describe their size lazily. When this is the case,
      * size will be an integer. Otherwise it will be undefined.
@@ -3275,7 +3278,7 @@ declare module Immutable {
    * Implementations should extend one of the subclasses, `Collection.Keyed`,
    * `Collection.Indexed`, or `Collection.Set`.
    */
-  export module Collection {
+  namespace Collection {
     /**
      * @deprecated use `const { isKeyed } = require('immutable')`
      */
@@ -3311,7 +3314,7 @@ declare module Immutable {
      * tuple, in other words, `Collection#entries` is the default iterator for
      * Keyed Collections.
      */
-    export module Keyed {}
+    namespace Keyed {}
 
     /**
      * Creates a Collection.Keyed
@@ -3322,14 +3325,10 @@ declare module Immutable {
      * Note: `Collection.Keyed` is a conversion function and not a class, and
      * does not use the `new` keyword during construction.
      */
-    export function Keyed<K, V>(
-      collection: Iterable<[K, V]>
-    ): Collection.Keyed<K, V>;
-    export function Keyed<V>(obj: {
-      [key: string]: V;
-    }): Collection.Keyed<string, V>;
+    function Keyed<K, V>(collection: Iterable<[K, V]>): Collection.Keyed<K, V>;
+    function Keyed<V>(obj: { [key: string]: V }): Collection.Keyed<string, V>;
 
-    export interface Keyed<K, V> extends Collection<K, V> {
+    interface Keyed<K, V> extends Collection<K, V> {
       /**
        * Deeply converts this Keyed collection to equivalent native JavaScript Object.
        *
@@ -3431,11 +3430,15 @@ declare module Immutable {
        *
        * Note: `mapEntries()` always returns a new instance, even if it produced
        * the same entry at every step.
-       * 
+       *
        * If the mapper function returns `undefined`, then the entry will be filtered
        */
       mapEntries<KM, VM>(
-        mapper: (entry: [K, V], index: number, iter: this) => [KM, VM] | undefined,
+        mapper: (
+          entry: [K, V],
+          index: number,
+          iter: this
+        ) => [KM, VM] | undefined,
         context?: unknown
       ): Collection.Keyed<KM, VM>;
 
@@ -3483,7 +3486,7 @@ declare module Immutable {
      * preserve indices, using them as keys, convert to a Collection.Keyed by
      * calling `toKeyedSeq`.
      */
-    export module Indexed {}
+    namespace Indexed {}
 
     /**
      * Creates a new Collection.Indexed.
@@ -3491,9 +3494,11 @@ declare module Immutable {
      * Note: `Collection.Indexed` is a conversion function and not a class, and
      * does not use the `new` keyword during construction.
      */
-    export function Indexed<T>(collection: Iterable<T>): Collection.Indexed<T>;
+    function Indexed<T>(
+      collection: Iterable<T> | ArrayLike<T>
+    ): Collection.Indexed<T>;
 
-    export interface Indexed<T> extends Collection<number, T> {
+    interface Indexed<T> extends Collection<number, T> {
       /**
        * Deeply converts this Indexed collection to equivalent native JavaScript Array.
        */
@@ -3671,7 +3676,7 @@ declare module Immutable {
         thirdCollection: Collection<unknown, V>
       ): Collection.Indexed<Z>;
       zipWith<Z>(
-        zipper: (...any: Array<unknown>) => Z,
+        zipper: (...values: Array<unknown>) => Z,
         ...collections: Array<Collection<unknown, unknown>>
       ): Collection.Indexed<Z>;
 
@@ -3780,7 +3785,7 @@ declare module Immutable {
      * )
      * ```
      */
-    export module Set {}
+    namespace Set {}
 
     /**
      * Similar to `Collection()`, but always returns a Collection.Set.
@@ -3788,9 +3793,9 @@ declare module Immutable {
      * Note: `Collection.Set` is a factory function and not a class, and does
      * not use the `new` keyword during construction.
      */
-    export function Set<T>(collection: Iterable<T>): Collection.Set<T>;
+    function Set<T>(collection: Iterable<T> | ArrayLike<T>): Collection.Set<T>;
 
-    export interface Set<T> extends Collection<T, T> {
+    interface Set<T> extends Collection<T, T> {
       /**
        * Deeply converts this Set collection to equivalent native JavaScript Array.
        */
@@ -3888,15 +3893,15 @@ declare module Immutable {
    * Note: `Collection` is a conversion function and not a class, and does not
    * use the `new` keyword during construction.
    */
-  export function Collection<I extends Collection<unknown, unknown>>(
-    collection: I
-  ): I;
-  export function Collection<T>(collection: Iterable<T>): Collection.Indexed<T>;
-  export function Collection<V>(obj: {
+  function Collection<I extends Collection<unknown, unknown>>(collection: I): I;
+  function Collection<T>(
+    collection: Iterable<T> | ArrayLike<T>
+  ): Collection.Indexed<T>;
+  function Collection<V>(obj: {
     [key: string]: V;
   }): Collection.Keyed<string, V>;
 
-  export interface Collection<K, V> extends ValueObject {
+  interface Collection<K, V> extends ValueObject {
     // Value equality
 
     /**
@@ -4200,6 +4205,8 @@ declare module Immutable {
      */
     entries(): IterableIterator<[K, V]>;
 
+    [Symbol.iterator](): IterableIterator<unknown>;
+
     // Collections (Seq)
 
     /**
@@ -4245,7 +4252,7 @@ declare module Immutable {
      *
      * @ignore
      */
-    map<M>(...args: never[]): unknown;
+    map(...args: Array<never>): unknown;
 
     /**
      * Returns a new Collection of the same type with only the entries for which
@@ -4549,6 +4556,7 @@ declare module Immutable {
      * returns Collection<K, V>
      */
     flatten(depth?: number): Collection<unknown, unknown>;
+    // tslint:disable-next-line unified-signatures
     flatten(shallow?: boolean): Collection<unknown, unknown>;
 
     /**
@@ -4825,7 +4833,7 @@ declare module Immutable {
   /**
    * The interface to fulfill to qualify as a Value Object.
    */
-  export interface ValueObject {
+  interface ValueObject {
     /**
      * True if this and the other Collection have value equality, as defined
      * by `Immutable.is()`.
@@ -4872,6 +4880,10 @@ declare module Immutable {
   /**
    * Deeply converts plain JS objects and arrays to Immutable Maps and Lists.
    *
+   * `fromJS` will convert Arrays and [array-like objects][2] to a List, and
+   * plain objects (without a custom prototype) to a Map. [Iterable objects][3]
+   * may be converted to List, Map, or Set.
+   *
    * 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
@@ -4894,10 +4906,6 @@ declare module Immutable {
    * }
    * ```
    *
-   * `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 -->
@@ -4934,15 +4942,19 @@ declare module Immutable {
    *
    * [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"
+   * [2]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Indexed_collections#working_with_array-like_objects
+   *      "Working with array-like objects"
+   * [3]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_iterable_protocol
+   *      "The iterable protocol"
    */
-  export function fromJS(
+  function fromJS(
     jsValue: unknown,
     reviver?: (
       key: string | number,
       sequence: Collection.Keyed<string, unknown> | Collection.Indexed<unknown>,
       path?: Array<string | number>
     ) => unknown
-  ): unknown;
+  ): Collection<unknown, unknown>;
 
   /**
    * Value equality check with semantics similar to `Object.is`, but treats
@@ -4969,7 +4981,7 @@ declare module Immutable {
    * 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: unknown, second: unknown): boolean;
+  function is(first: unknown, second: unknown): boolean;
 
   /**
    * The `hash()` function is an important part of how Immutable determines if
@@ -4993,7 +5005,7 @@ declare module Immutable {
    *
    * *New in Version 4.0*
    */
-  export function hash(value: unknown): number;
+  function hash(value: unknown): number;
 
   /**
    * True if `maybeImmutable` is an Immutable Collection or Record.
@@ -5011,7 +5023,7 @@ declare module Immutable {
    * isImmutable(Map().asMutable()); // true
    * ```
    */
-  export function isImmutable(
+  function isImmutable(
     maybeImmutable: unknown
   ): maybeImmutable is Collection<unknown, unknown>;
 
@@ -5028,7 +5040,7 @@ declare module Immutable {
    * isCollection(Stack()); // true
    * ```
    */
-  export function isCollection(
+  function isCollection(
     maybeCollection: unknown
   ): maybeCollection is Collection<unknown, unknown>;
 
@@ -5045,7 +5057,7 @@ declare module Immutable {
    * isKeyed(Stack()); // false
    * ```
    */
-  export function isKeyed(
+  function isKeyed(
     maybeKeyed: unknown
   ): maybeKeyed is Collection.Keyed<unknown, unknown>;
 
@@ -5063,7 +5075,7 @@ declare module Immutable {
    * isIndexed(Set()); // false
    * ```
    */
-  export function isIndexed(
+  function isIndexed(
     maybeIndexed: unknown
   ): maybeIndexed is Collection.Indexed<unknown>;
 
@@ -5081,7 +5093,7 @@ declare module Immutable {
    * isAssociative(Set()); // false
    * ```
    */
-  export function isAssociative(
+  function isAssociative(
     maybeAssociative: unknown
   ): maybeAssociative is
     | Collection.Keyed<unknown, unknown>
@@ -5102,7 +5114,7 @@ declare module Immutable {
    * isOrdered(Set()); // false
    * ```
    */
-  export function isOrdered(maybeOrdered: unknown): boolean;
+  function isOrdered(maybeOrdered: unknown): boolean;
 
   /**
    * True if `maybeValue` is a JavaScript Object which has *both* `equals()`
@@ -5111,12 +5123,12 @@ declare module Immutable {
    * 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: unknown): maybeValue is ValueObject;
+  function isValueObject(maybeValue: unknown): maybeValue is ValueObject;
 
   /**
    * True if `maybeSeq` is a Seq.
    */
-  export function isSeq(
+  function isSeq(
     maybeSeq: unknown
   ): maybeSeq is
     | Seq.Indexed<unknown>
@@ -5126,45 +5138,45 @@ declare module Immutable {
   /**
    * True if `maybeList` is a List.
    */
-  export function isList(maybeList: unknown): maybeList is List<unknown>;
+  function isList(maybeList: unknown): maybeList is List<unknown>;
 
   /**
    * True if `maybeMap` is a Map.
    *
    * Also true for OrderedMaps.
    */
-  export function isMap(maybeMap: unknown): maybeMap is Map<unknown, unknown>;
+  function isMap(maybeMap: unknown): maybeMap is Map<unknown, unknown>;
 
   /**
    * True if `maybeOrderedMap` is an OrderedMap.
    */
-  export function isOrderedMap(
+  function isOrderedMap(
     maybeOrderedMap: unknown
   ): maybeOrderedMap is OrderedMap<unknown, unknown>;
 
   /**
    * True if `maybeStack` is a Stack.
    */
-  export function isStack(maybeStack: unknown): maybeStack is Stack<unknown>;
+  function isStack(maybeStack: unknown): maybeStack is Stack<unknown>;
 
   /**
    * True if `maybeSet` is a Set.
    *
    * Also true for OrderedSets.
    */
-  export function isSet(maybeSet: unknown): maybeSet is Set<unknown>;
+  function isSet(maybeSet: unknown): maybeSet is Set<unknown>;
 
   /**
    * True if `maybeOrderedSet` is an OrderedSet.
    */
-  export function isOrderedSet(
+  function isOrderedSet(
     maybeOrderedSet: unknown
   ): maybeOrderedSet is OrderedSet<unknown>;
 
   /**
    * True if `maybeRecord` is a Record.
    */
-  export function isRecord(maybeRecord: unknown): maybeRecord is Record<{}>;
+  function isRecord(maybeRecord: unknown): maybeRecord is Record<{}>;
 
   /**
    * Returns the value within the provided collection associated with the
@@ -5181,36 +5193,30 @@ declare module Immutable {
    * 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>(
+  function get<K, V>(collection: Collection<K, V>, key: K): V | undefined;
+  function get<K, V, NSV>(
     collection: Collection<K, V>,
     key: K,
     notSetValue: NSV
   ): V | NSV;
-  export function get<TProps, K extends keyof TProps>(
+  function get<TProps extends object, K extends keyof TProps>(
     record: Record<TProps>,
     key: K,
     notSetValue: unknown
   ): TProps[K];
-  export function get<V>(collection: Array<V>, key: number): V | undefined;
-  export function get<V, NSV>(
+  function get<V>(collection: Array<V>, key: number): V | undefined;
+  function get<V, NSV>(
     collection: Array<V>,
     key: number,
     notSetValue: NSV
   ): V | NSV;
-  export function get<C extends Object, K extends keyof C>(
+  function get<C extends object, K extends keyof C>(
     object: C,
     key: K,
     notSetValue: unknown
   ): C[K];
-  export function get<V>(
-    collection: { [key: string]: V },
-    key: string
-  ): V | undefined;
-  export function get<V, NSV>(
+  function get<V>(collection: { [key: string]: V }, key: string): V | undefined;
+  function get<V, NSV>(
     collection: { [key: string]: V },
     key: string,
     notSetValue: NSV
@@ -5232,7 +5238,7 @@ declare module Immutable {
    * has({ x: 123, y: 456 }, 'z') // false
    * ```
    */
-  export function has(collection: Object, key: unknown): boolean;
+  function has(collection: object, key: unknown): boolean;
 
   /**
    * Returns a copy of the collection with the value at key removed.
@@ -5252,24 +5258,21 @@ declare module Immutable {
    * console.log(originalObject) // { x: 123, y: 456 }
    * ```
    */
-  export function remove<K, C extends Collection<K, unknown>>(
+  function remove<K, C extends Collection<K, unknown>>(
     collection: C,
     key: K
   ): C;
-  export function remove<
-    TProps,
+  function remove<
+    TProps extends object,
     C extends Record<TProps>,
     K extends keyof TProps
   >(collection: C, key: K): C;
-  export function remove<C extends Array<unknown>>(
+  function remove<C extends Array<unknown>>(collection: C, key: number): C;
+  function remove<C, K extends keyof C>(collection: C, key: K): C;
+  function remove<C extends { [key: string]: unknown }, K extends keyof C>(
     collection: C,
-    key: number
+    key: K
   ): C;
-  export function remove<C, K extends keyof C>(collection: C, key: K): C;
-  export function remove<
-    C extends { [key: string]: unknown },
-    K extends keyof C
-  >(collection: C, key: K): C;
 
   /**
    * Returns a copy of the collection with the value at key set to the provided
@@ -5290,23 +5293,19 @@ declare module Immutable {
    * console.log(originalObject) // { x: 123, y: 456 }
    * ```
    */
-  export function set<K, V, C extends Collection<K, V>>(
+  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 }>(
+  function set<
+    TProps extends object,
+    C extends Record<TProps>,
+    K extends keyof TProps
+  >(record: C, key: K, value: TProps[K]): C;
+  function set<V, C extends Array<V>>(collection: C, key: number, value: V): C;
+  function set<C, K extends keyof C>(object: C, key: K, value: C[K]): C;
+  function set<V, C extends { [key: string]: V }>(
     collection: C,
     key: string,
     value: V
@@ -5331,24 +5330,24 @@ declare module Immutable {
    * console.log(originalObject) // { x: 123, y: 456 }
    * ```
    */
-  export function update<K, V, C extends Collection<K, V>>(
+  function update<K, V, C extends Collection<K, V>>(
     collection: C,
     key: K,
     updater: (value: V | undefined) => V
   ): C;
-  export function update<K, V, C extends Collection<K, V>, NSV>(
+  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,
+  function update<
+    TProps extends object,
     C extends Record<TProps>,
     K extends keyof TProps
   >(record: C, key: K, updater: (value: TProps[K]) => TProps[K]): C;
-  export function update<
-    TProps,
+  function update<
+    TProps extends object,
     C extends Record<TProps>,
     K extends keyof TProps,
     NSV
@@ -5358,39 +5357,34 @@ declare module Immutable {
     notSetValue: NSV,
     updater: (value: TProps[K] | NSV) => TProps[K]
   ): C;
-  export function update<V>(
+  function update<V>(
     collection: Array<V>,
     key: number,
     updater: (value: V) => V
   ): Array<V>;
-  export function update<V, NSV>(
+  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>(
+  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>(
+  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>(
+  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
-  >(
+  function update<V, C extends { [key: string]: V }, K extends keyof C, NSV>(
     collection: C,
     key: K,
     notSetValue: NSV,
@@ -5411,10 +5405,10 @@ declare module Immutable {
    * getIn({ x: { y: { z: 123 }}}, ['x', 'q', 'p'], 'ifNotSet') // 'ifNotSet'
    * ```
    */
-  export function getIn(
+  function getIn(
     collection: unknown,
     keyPath: Iterable<unknown>,
-    notSetValue: unknown
+    notSetValue?: unknown
   ): unknown;
 
   /**
@@ -5430,10 +5424,7 @@ declare module Immutable {
    * hasIn({ x: { y: { z: 123 }}}, ['x', 'q', 'p']) // false
    * ```
    */
-  export function hasIn(
-    collection: unknown,
-    keyPath: Iterable<unknown>
-  ): boolean;
+  function hasIn(collection: unknown, keyPath: Iterable<unknown>): boolean;
 
   /**
    * Returns a copy of the collection with the value at the key path removed.
@@ -5449,7 +5440,7 @@ declare module Immutable {
    * console.log(original) // { x: { y: { z: 123 }}}
    * ```
    */
-  export function removeIn<C>(collection: C, keyPath: Iterable<unknown>): C;
+  function removeIn<C>(collection: C, keyPath: Iterable<unknown>): C;
 
   /**
    * Returns a copy of the collection with the value at the key path set to the
@@ -5466,7 +5457,7 @@ declare module Immutable {
    * console.log(original) // { x: { y: { z: 123 }}}
    * ```
    */
-  export function setIn<C>(
+  function setIn<C>(
     collection: C,
     keyPath: Iterable<unknown>,
     value: unknown
@@ -5487,12 +5478,12 @@ declare module Immutable {
    * console.log(original) // { x: { y: { z: 123 }}}
    * ```
    */
-  export function updateIn<C>(
+  function updateIn<C>(
     collection: C,
     keyPath: Iterable<unknown>,
     updater: (value: unknown) => unknown
   ): C;
-  export function updateIn<C>(
+  function updateIn<C>(
     collection: C,
     keyPath: Iterable<unknown>,
     notSetValue: unknown,
@@ -5513,7 +5504,7 @@ declare module Immutable {
    * console.log(original) // { x: 123, y: 456 }
    * ```
    */
-  export function merge<C>(
+  function merge<C>(
     collection: C,
     ...collections: Array<
       | Iterable<unknown>
@@ -5541,7 +5532,7 @@ declare module Immutable {
    * console.log(original) // { x: 123, y: 456 }
    * ```
    */
-  export function mergeWith<C>(
+  function mergeWith<C>(
     merger: (oldVal: unknown, newVal: unknown, key: unknown) => unknown,
     collection: C,
     ...collections: Array<
@@ -5552,8 +5543,18 @@ declare module Immutable {
   ): C;
 
   /**
-   * Returns a copy of the collection with the remaining collections merged in
-   * deeply (recursively).
+   * Like `merge()`, but when two compatible collections are encountered with
+   * the same key, it merges them as well, recursing deeply through the nested
+   * data. Two collections are considered to be compatible (and thus will be
+   * merged together) if they both fall into one of three categories: keyed
+   * (e.g., `Map`s, `Record`s, and objects), indexed (e.g., `List`s and
+   * arrays), or set-like (e.g., `Set`s). If they fall into separate
+   * categories, `mergeDeep` will replace the existing collection with the
+   * collection being merged in. This behavior can be customized by using
+   * `mergeDeepWith()`.
+   *
+   * Note: Indexed and set-like collections are merged using
+   * `concat()`/`union()` and therefore do not recurse.
    *
    * A functional alternative to `collection.mergeDeep()` which will also work
    * with plain Objects and Arrays.
@@ -5566,7 +5567,7 @@ declare module Immutable {
    * console.log(original) // { x: { y: 123 }}
    * ```
    */
-  export function mergeDeep<C>(
+  function mergeDeep<C>(
     collection: C,
     ...collections: Array<
       | Iterable<unknown>
@@ -5576,9 +5577,10 @@ declare module Immutable {
   ): 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.
+   * Like `mergeDeep()`, but when two non-collections or incompatible
+   * collections are encountered at the same key, it uses the `merger` function
+   * to determine the resulting value. Collections are considered incompatible
+   * if they fall into separate categories between keyed, indexed, and set-like.
    *
    * A functional alternative to `collection.mergeDeepWith()` which will also
    * work with plain Objects and Arrays.
@@ -5595,7 +5597,7 @@ declare module Immutable {
    * console.log(original) // { x: { y: 123 }}
    * ```
    */
-  export function mergeDeepWith<C>(
+  function mergeDeepWith<C>(
     merger: (oldVal: unknown, newVal: unknown, key: unknown) => unknown,
     collection: C,
     ...collections: Array<
@@ -5606,6 +5608,26 @@ declare module Immutable {
   ): C;
 }
 
-declare module 'immutable' {
-  export = Immutable;
-}
+/**
+ * Defines the main export of the immutable module to be the Immutable namespace
+ * This supports many common module import patterns:
+ *
+ *     const Immutable = require("immutable");
+ *     const { List } = require("immutable");
+ *     import Immutable from "immutable";
+ *     import * as Immutable from "immutable";
+ *     import { List } from "immutable";
+ *
+ */
+export = Immutable;
+
+/**
+ * A global "Immutable" namespace used by UMD modules which allows the use of
+ * the full Immutable API.
+ *
+ * If using Immutable as an imported module, prefer using:
+ *
+ *     import Immutable from 'immutable'
+ *
+ */
+export as namespace Immutable;