immutable 5.0.2 → 5.1.0

package/dist/{immutable.d.ts → type-definitions/immutable.d.ts}

@@ -1,5 +1,4 @@
 /** @ignore we should disable this rules, but let's activate it to enable eslint first */
-/* eslint-disable @typescript-eslint/no-explicit-any, @typescript-eslint/ban-types */
 /**
  * Immutable data encourages pure functions (data-in, data-out) and lends itself
  * to much simpler application development and enabling techniques from
@@ -97,11 +96,12 @@ declare namespace Immutable {
   type OnlyObject<T> = Extract<T, object>;
 
   /** @ignore */
-  type ContainObject<T> = OnlyObject<T> extends object
-    ? OnlyObject<T> extends never
-      ? false
-      : true
-    : false;
+  type ContainObject<T> =
+    OnlyObject<T> extends object
+      ? OnlyObject<T> extends never
+        ? false
+        : true
+      : false;
 
   /**
    * @ignore
@@ -109,39 +109,46 @@ declare namespace Immutable {
    * Used to convert deeply all immutable types to a plain TS type.
    * Using `unknown` on object instead of recursive call as we have a circular reference issue
    */
-  export type DeepCopy<T> = T extends Record<infer R>
-    ? // convert Record to DeepCopy plain JS object
-      {
-        [key in keyof R]: ContainObject<R[key]> extends true ? unknown : R[key];
-      }
-    : T extends MapOf<infer R>
-    ? // convert MapOf to DeepCopy plain JS object
-      {
-        [key in keyof R]: ContainObject<R[key]> extends true ? unknown : R[key];
-      }
-    : T extends Collection.Keyed<infer KeyedKey, infer V>
-    ? // convert KeyedCollection to DeepCopy plain JS object
-      {
-        [key in KeyedKey extends string | number | symbol
-          ? KeyedKey
-          : string]: V extends object ? unknown : V;
-      }
-    : // convert IndexedCollection or Immutable.Set to DeepCopy plain JS array
-    // eslint-disable-next-line @typescript-eslint/no-unused-vars
-    T extends Collection<infer _, infer V>
-    ? Array<DeepCopy<V>>
-    : T extends string | number // Iterable scalar types : should be kept as is
-    ? T
-    : T extends Iterable<infer V> // Iterable are converted to plain JS array
-    ? Array<DeepCopy<V>>
-    : T extends object // plain JS object are converted deeply
-    ? {
-        [ObjectKey in keyof T]: ContainObject<T[ObjectKey]> extends true
-          ? unknown
-          : T[ObjectKey];
-      }
-    : // other case : should be kept as is
-      T;
+  export type DeepCopy<T> =
+    T extends Record<infer R>
+      ? // convert Record to DeepCopy plain JS object
+        {
+          [key in keyof R]: ContainObject<R[key]> extends true
+            ? unknown
+            : R[key];
+        }
+      : T extends MapOf<infer R>
+        ? // convert MapOf to DeepCopy plain JS object
+          {
+            [key in keyof R]: ContainObject<R[key]> extends true
+              ? unknown
+              : R[key];
+          }
+        : T extends Collection.Keyed<infer KeyedKey, infer V>
+          ? // convert KeyedCollection to DeepCopy plain JS object
+            {
+              [key in KeyedKey extends PropertyKey
+                ? KeyedKey
+                : string]: V extends object ? unknown : V;
+            }
+          : // convert IndexedCollection or Immutable.Set to DeepCopy plain JS array
+            // eslint-disable-next-line @typescript-eslint/no-unused-vars
+            T extends Collection<infer _, infer V>
+            ? Array<DeepCopy<V>>
+            : T extends string | number // Iterable scalar types : should be kept as is
+              ? T
+              : T extends Iterable<infer V> // Iterable are converted to plain JS array
+                ? Array<DeepCopy<V>>
+                : T extends object // plain JS object are converted deeply
+                  ? {
+                      [ObjectKey in keyof T]: ContainObject<
+                        T[ObjectKey]
+                      > extends true
+                        ? unknown
+                        : T[ObjectKey];
+                    }
+                  : // other case : should be kept as is
+                    T;
 
   /**
    * Describes which item in a pair should be placed first when sorting
@@ -164,6 +171,13 @@ declare namespace Immutable {
    */
   export type Comparator<T> = (left: T, right: T) => PairSorting | number;
 
+  /**
+   * @ignore
+   *
+   * KeyPath allowed for `xxxIn` methods
+   */
+  export type KeyPath<K> = OrderedCollection<K> | ArrayLike<K>;
+
   /**
    * Lists are ordered indexed dense collections, much like a JavaScript
    * Array.
@@ -751,6 +765,14 @@ declare namespace Immutable {
       zipper: (...values: Array<unknown>) => Z,
       ...collections: Array<Collection<unknown, unknown>>
     ): List<Z>;
+
+    /**
+     * Returns a new List with its values shuffled thanks to the
+     * [Fisher–Yates](https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle)
+     * algorithm.
+     * It uses Math.random, but you can provide your own random number generator.
+     */
+    shuffle(random?: () => number): this;
   }
 
   /**
@@ -831,9 +853,7 @@ declare namespace Immutable {
    * not altered.
    */
   function Map<K, V>(collection?: Iterable<[K, V]>): Map<K, V>;
-  function Map<R extends { [key in string | number | symbol]: unknown }>(
-    obj: R
-  ): MapOf<R>;
+  function Map<R extends { [key in PropertyKey]: unknown }>(obj: R): MapOf<R>;
   function Map<V>(obj: { [key: string]: V }): Map<string, V>;
   function Map<K extends string | symbol, V>(obj: { [P in K]?: V }): Map<K, V>;
 
@@ -842,7 +862,7 @@ declare namespace Immutable {
    *
    * @ignore
    */
-  interface MapOf<R extends { [key in string | number | symbol]: unknown }>
+  interface MapOf<R extends { [key in PropertyKey]: unknown }>
     extends Map<keyof R, R[keyof R]> {
     /**
      * Returns the value associated with the provided key, or notSetValue if
@@ -853,12 +873,12 @@ declare namespace Immutable {
      * that does not guarantee the key was not found.
      */
     get<K extends keyof R>(key: K, notSetValue?: unknown): R[K];
-    get<NSV>(key: any, notSetValue: NSV): NSV;
+    get<NSV>(key: unknown, notSetValue: NSV): NSV;
 
     // TODO `<const P extends ...>` can be used after dropping support for TypeScript 4.x
     // reference: https://www.typescriptlang.org/docs/handbook/release-notes/typescript-5-0.html#const-type-parameters
     // after this change, `as const` assertions can be remove from the type tests
-    getIn<P extends ReadonlyArray<string | number | symbol>>(
+    getIn<P extends ReadonlyArray<PropertyKey>>(
       searchKeyPath: [...P],
       notSetValue?: unknown
     ): RetrievePath<R, P>;
@@ -890,38 +910,48 @@ declare namespace Immutable {
   // Loosely based off of this work.
   // https://github.com/immutable-js/immutable-js/issues/1462#issuecomment-584123268
 
-  /** @ignore */
-  type GetMapType<S> = S extends MapOf<infer T> ? T : S;
+  /**
+   * @ignore
+   * Convert an immutable type to the equivalent plain TS type
+   * - MapOf -> object
+   * - List -> Array
+   */
+  type GetNativeType<S> =
+    S extends MapOf<infer T> ? T : S extends List<infer I> ? Array<I> : S;
 
   /** @ignore */
-  type Head<T extends ReadonlyArray<any>> = T extends [
+  type Head<T extends ReadonlyArray<unknown>> = T extends [
     infer H,
-    ...Array<unknown>
+    ...Array<unknown>,
   ]
     ? H
     : never;
-
   /** @ignore */
-  type Tail<T extends ReadonlyArray<any>> = T extends [unknown, ...infer I]
+  type Tail<T extends ReadonlyArray<unknown>> = T extends [unknown, ...infer I]
     ? I
     : Array<never>;
-
   /** @ignore */
   type RetrievePathReducer<
     T,
     C,
-    L extends ReadonlyArray<any>
-  > = C extends keyof GetMapType<T>
-    ? L extends []
-      ? GetMapType<T>[C]
-      : RetrievePathReducer<GetMapType<T>[C], Head<L>, Tail<L>>
-    : never;
+    L extends ReadonlyArray<unknown>,
+    NT = GetNativeType<T>,
+  > =
+    // we can not retrieve a path from a primitive type
+    T extends string | number | boolean | null | undefined
+      ? never
+      : C extends keyof NT
+        ? L extends [] // L extends [] means we are at the end of the path, lets return the current type
+          ? NT[C]
+          : // we are not at the end of the path, lets continue with the next key
+            RetrievePathReducer<NT[C], Head<L>, Tail<L>>
+        : // C is not a "key" of NT, so the path is invalid
+          never;
 
   /** @ignore */
-  type RetrievePath<
-    R,
-    P extends ReadonlyArray<string | number | symbol>
-  > = P extends [] ? P : RetrievePathReducer<R, Head<P>, Tail<P>>;
+  type RetrievePath<R, P extends ReadonlyArray<PropertyKey>> = P extends []
+    ? P
+    : RetrievePathReducer<R, Head<P>, Tail<P>>;
 
   interface Map<K, V> extends Collection.Keyed<K, V> {
     /**
@@ -1690,7 +1720,7 @@ declare namespace Immutable {
   function OrderedMap<K, V>(collection?: Iterable<[K, V]>): OrderedMap<K, V>;
   function OrderedMap<V>(obj: { [key: string]: V }): OrderedMap<string, V>;
 
-  interface OrderedMap<K, V> extends Map<K, V> {
+  interface OrderedMap<K, V> extends Map<K, V>, OrderedCollection<[K, V]> {
     /**
      * The number of entries in this OrderedMap.
      */
@@ -2175,7 +2205,7 @@ declare namespace Immutable {
     collection?: Iterable<T> | ArrayLike<T>
   ): OrderedSet<T>;
 
-  interface OrderedSet<T> extends Set<T> {
+  interface OrderedSet<T> extends Set<T>, OrderedCollection<T> {
     /**
      * The number of items in this OrderedSet.
      */
@@ -2765,7 +2795,7 @@ declare namespace Immutable {
     /**
      * True if `maybeRecord` is an instance of a Record.
      */
-    function isRecord(maybeRecord: unknown): maybeRecord is Record<{}>;
+    function isRecord(maybeRecord: unknown): maybeRecord is Record<object>;
 
     /**
      * Records allow passing a second parameter to supply a descriptive name
@@ -2784,7 +2814,9 @@ declare namespace Immutable {
      * Record.getDescriptiveName(me) // "Person"
      * ```
      */
-    function getDescriptiveName(record: Record<any>): string;
+    function getDescriptiveName<TProps extends object>(
+      record: RecordOf<TProps>
+    ): string;
 
     /**
      * A Record.Factory is created by the `Record()` function. Record instances
@@ -2837,11 +2869,12 @@ declare namespace Immutable {
     namespace Factory {}
 
     interface Factory<TProps extends object> {
-      (values?: Partial<TProps> | Iterable<[string, unknown]>): Record<TProps> &
-        Readonly<TProps>;
+      (
+        values?: Partial<TProps> | Iterable<[string, unknown]>
+      ): RecordOf<TProps>;
       new (
         values?: Partial<TProps> | Iterable<[string, unknown]>
-      ): Record<TProps> & Readonly<TProps>;
+      ): RecordOf<TProps>;
 
       /**
        * The name provided to `Record(values, name)` can be accessed with
@@ -2852,7 +2885,7 @@ declare namespace Immutable {
 
     function Factory<TProps extends object>(
       values?: Partial<TProps> | Iterable<[string, unknown]>
-    ): Record<TProps> & Readonly<TProps>;
+    ): RecordOf<TProps>;
   }
 
   /**
@@ -3120,14 +3153,14 @@ declare namespace Immutable {
        *
        * Converts keys to Strings.
        */
-      toJS(): { [key in string | number | symbol]: DeepCopy<V> };
+      toJS(): { [key in PropertyKey]: DeepCopy<V> };
 
       /**
        * Shallowly converts this Keyed Seq to equivalent native JavaScript Object.
        *
        * Converts keys to Strings.
        */
-      toJSON(): { [key in string | number | symbol]: V };
+      toJSON(): { [key in PropertyKey]: V };
 
       /**
        * Shallowly converts this collection to an Array.
@@ -3675,6 +3708,15 @@ declare namespace Immutable {
       predicate: (this: C, value: V, key: K, iter: this) => unknown,
       context?: C
     ): [this, this];
+
+    /**
+     * Returns a new Sequence of the same type with other values and
+     * collection-like concatenated to this one.
+     *
+     * All entries will be present in the resulting Seq, even if they
+     * have the same key.
+     */
+    concat(...valuesOrCollections: Array<unknown>): Seq<unknown, unknown>;
   }
 
   /**
@@ -3719,14 +3761,14 @@ declare namespace Immutable {
        *
        * Converts keys to Strings.
        */
-      toJS(): { [key in string | number | symbol]: DeepCopy<V> };
+      toJS(): { [key in PropertyKey]: DeepCopy<V> };
 
       /**
        * Shallowly converts this Keyed collection to equivalent native JavaScript Object.
        *
        * Converts keys to Strings.
        */
-      toJSON(): { [key in string | number | symbol]: V };
+      toJSON(): { [key in PropertyKey]: V };
 
       /**
        * Shallowly converts this collection to an Array.
@@ -3897,7 +3939,7 @@ declare namespace Immutable {
       collection?: Iterable<T> | ArrayLike<T>
     ): Collection.Indexed<T>;
 
-    interface Indexed<T> extends Collection<number, T> {
+    interface Indexed<T> extends Collection<number, T>, OrderedCollection<T> {
       /**
        * Deeply converts this Indexed collection to equivalent native JavaScript Array.
        */
@@ -4476,9 +4518,7 @@ declare namespace Immutable {
      * `Collection.Indexed`, and `Collection.Set` become `Array`, while
      * `Collection.Keyed` become `Object`, converting keys to Strings.
      */
-    toJS():
-      | Array<DeepCopy<V>>
-      | { [key in string | number | symbol]: DeepCopy<V> };
+    toJS(): Array<DeepCopy<V>> | { [key in PropertyKey]: DeepCopy<V> };
 
     /**
      * Shallowly converts this Collection to equivalent native JavaScript Array or Object.
@@ -4486,7 +4526,7 @@ declare namespace Immutable {
      * `Collection.Indexed`, and `Collection.Set` become `Array`, while
      * `Collection.Keyed` become `Object`, converting keys to Strings.
      */
-    toJSON(): Array<V> | { [key in string | number | symbol]: V };
+    toJSON(): Array<V> | { [key in PropertyKey]: V };
 
     /**
      * Shallowly converts this collection to an Array.
@@ -5322,6 +5362,20 @@ declare namespace Immutable {
     hashCode(): number;
   }
 
+  /**
+   * Interface representing all oredered collections.
+   * This includes `List`, `Stack`, `Map`, `OrderedMap`, `Set`, and `OrderedSet`.
+   * return of `isOrdered()` return true in that case.
+   */
+  interface OrderedCollection<T> {
+    /**
+     * Shallowly converts this collection to an Array.
+     */
+    toArray(): Array<T>;
+
+    [Symbol.iterator](): IterableIterator<T>;
+  }
+
   /**
    * Deeply converts plain JS objects and arrays to Immutable Maps and Lists.
    *
@@ -5407,24 +5461,23 @@ declare namespace Immutable {
 
   type FromJS<JSValue> = JSValue extends FromJSNoTransform
     ? JSValue
-    : JSValue extends Array<any>
-    ? FromJSArray<JSValue>
-    : JSValue extends {}
-    ? FromJSObject<JSValue>
-    : any;
+    : JSValue extends Array<unknown>
+      ? FromJSArray<JSValue>
+      : JSValue extends object
+        ? FromJSObject<JSValue>
+        : unknown;
 
   type FromJSNoTransform =
-    | Collection<any, any>
+    | Collection<unknown, unknown>
     | number
     | string
     | null
     | undefined;
 
-  type FromJSArray<JSValue> = JSValue extends Array<infer T>
-    ? List<FromJS<T>>
-    : never;
+  type FromJSArray<JSValue> =
+    JSValue extends Array<infer T> ? List<FromJS<T>> : never;
 
-  type FromJSObject<JSValue> = JSValue extends {}
+  type FromJSObject<JSValue> = JSValue extends object
     ? Map<keyof JSValue, FromJS<JSValue[keyof JSValue]>>
     : never;
 
@@ -5586,7 +5639,12 @@ declare namespace Immutable {
    * isOrdered(Set()); // false
    * ```
    */
-  function isOrdered(maybeOrdered: unknown): boolean;
+  function isOrdered<T>(
+    maybeOrdered: Iterable<T>
+  ): maybeOrdered is OrderedCollection<T>;
+  function isOrdered(
+    maybeOrdered: unknown
+  ): maybeOrdered is OrderedCollection<unknown>;
 
   /**
    * True if `maybeValue` is a JavaScript Object which has *both* `equals()`
@@ -5648,7 +5706,7 @@ declare namespace Immutable {
   /**
    * True if `maybeRecord` is a Record.
    */
-  function isRecord(maybeRecord: unknown): maybeRecord is Record<{}>;
+  function isRecord(maybeRecord: unknown): maybeRecord is Record<object>;
 
   /**
    * Returns the value within the provided collection associated with the
@@ -5687,9 +5745,12 @@ declare namespace Immutable {
     key: K,
     notSetValue: unknown
   ): C[K];
-  function get<V>(collection: { [key: string]: V }, key: string): V | undefined;
+  function get<V>(
+    collection: { [key: PropertyKey]: V },
+    key: string
+  ): V | undefined;
   function get<V, NSV>(
-    collection: { [key: string]: V },
+    collection: { [key: PropertyKey]: V },
     key: string,
     notSetValue: NSV
   ): V | NSV;
@@ -5737,7 +5798,7 @@ declare namespace Immutable {
   function remove<
     TProps extends object,
     C extends Record<TProps>,
-    K extends keyof TProps
+    K extends keyof TProps,
   >(collection: C, key: K): C;
   function remove<C extends Array<unknown>>(collection: C, key: number): C;
   function remove<C, K extends keyof C>(collection: C, key: K): C;
@@ -5773,7 +5834,7 @@ declare namespace Immutable {
   function set<
     TProps extends object,
     C extends Record<TProps>,
-    K extends keyof 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;
@@ -5816,13 +5877,13 @@ declare namespace Immutable {
   function update<
     TProps extends object,
     C extends Record<TProps>,
-    K extends keyof TProps
+    K extends keyof TProps,
   >(record: C, key: K, updater: (value: TProps[K]) => TProps[K]): C;
   function update<
     TProps extends object,
     C extends Record<TProps>,
     K extends keyof TProps,
-    NSV
+    NSV,
   >(
     record: C,
     key: K,
@@ -5863,6 +5924,9 @@ declare namespace Immutable {
     updater: (value: V | NSV) => V
   ): { [key: string]: V };
 
+  // TODO `<const P extends ...>` can be used after dropping support for TypeScript 4.x
+  // reference: https://www.typescriptlang.org/docs/handbook/release-notes/typescript-5-0.html#const-type-parameters
+  // after this change, `as const` assertions can be remove from the type tests
   /**
    * Returns the value at the provided key path starting at the provided
    * collection, or notSetValue if the key path is not defined.
@@ -5877,10 +5941,20 @@ declare namespace Immutable {
    * getIn({ x: { y: { z: 123 }}}, ['x', 'q', 'p'], 'ifNotSet') // 'ifNotSet'
    * ```
    */
-  function getIn(
-    collection: unknown,
-    keyPath: Iterable<unknown>,
-    notSetValue?: unknown
+  function getIn<C, P extends ReadonlyArray<PropertyKey>>(
+    object: C,
+    keyPath: [...P]
+  ): RetrievePath<C, P>;
+  function getIn<C, P extends KeyPath<unknown>>(object: C, keyPath: P): unknown;
+  function getIn<C, P extends ReadonlyArray<PropertyKey>, NSV>(
+    collection: C,
+    keyPath: [...P],
+    notSetValue: NSV
+  ): RetrievePath<C, P> extends never ? NSV : RetrievePath<C, P>;
+  function getIn<C, P extends KeyPath<unknown>, NSV>(
+    object: C,
+    keyPath: P,
+    notSetValue: NSV
   ): unknown;
 
   /**
@@ -5896,7 +5970,11 @@ declare namespace Immutable {
    * hasIn({ x: { y: { z: 123 }}}, ['x', 'q', 'p']) // false
    * ```
    */
-  function hasIn(collection: unknown, keyPath: Iterable<unknown>): boolean;
+  function hasIn(
+    collection: string | boolean | number,
+    keyPath: KeyPath<unknown>
+  ): never;
+  function hasIn<K>(collection: unknown, keyPath: KeyPath<K>): boolean;
 
   /**
    * Returns a copy of the collection with the value at the key path removed.
@@ -5950,17 +6028,83 @@ declare namespace Immutable {
    * console.log(original) // { x: { y: { z: 123 }}}
    * ```
    */
-  function updateIn<C>(
+  function updateIn<K extends PropertyKey, V, C extends Collection<K, V>>(
     collection: C,
-    keyPath: Iterable<unknown>,
-    updater: (value: unknown) => unknown
+    keyPath: KeyPath<K>,
+    updater: (
+      value: RetrievePath<C, Array<K>> | undefined
+    ) => unknown | undefined
   ): C;
-  function updateIn<C>(
+  function updateIn<K extends PropertyKey, V, C extends Collection<K, V>, NSV>(
     collection: C,
-    keyPath: Iterable<unknown>,
-    notSetValue: unknown,
-    updater: (value: unknown) => unknown
+    keyPath: KeyPath<K>,
+    notSetValue: NSV,
+    updater: (value: RetrievePath<C, Array<K>> | NSV) => unknown
+  ): C;
+  function updateIn<
+    TProps extends object,
+    C extends Record<TProps>,
+    K extends keyof TProps,
+  >(
+    record: C,
+    keyPath: KeyPath<K>,
+    updater: (value: RetrievePath<C, Array<K>>) => unknown
   ): C;
+  function updateIn<
+    TProps extends object,
+    C extends Record<TProps>,
+    K extends keyof TProps,
+    NSV,
+  >(
+    record: C,
+    keyPath: KeyPath<K>,
+    notSetValue: NSV,
+    updater: (value: RetrievePath<C, Array<K>> | NSV) => unknown
+  ): C;
+  function updateIn<K extends PropertyKey, V, C extends Array<V>>(
+    collection: Array<V>,
+    keyPath: KeyPath<string | number>,
+    updater: (
+      value: RetrievePath<C, Array<K>> | undefined
+    ) => unknown | undefined
+  ): Array<V>;
+  function updateIn<K extends PropertyKey, V, C extends Array<V>, NSV>(
+    collection: Array<V>,
+    keyPath: KeyPath<K>,
+    notSetValue: NSV,
+    updater: (value: RetrievePath<C, Array<K>> | NSV) => unknown
+  ): Array<V>;
+  function updateIn<K extends PropertyKey, C>(
+    object: C,
+    keyPath: KeyPath<K>,
+    updater: (value: RetrievePath<C, Array<K>>) => unknown
+  ): C;
+  function updateIn<K extends PropertyKey, C, NSV>(
+    object: C,
+    keyPath: KeyPath<K>,
+    notSetValue: NSV,
+    updater: (value: RetrievePath<C, Array<K>> | NSV) => unknown
+  ): C;
+  function updateIn<
+    K extends PropertyKey,
+    V,
+    C extends { [key: PropertyKey]: V },
+  >(
+    collection: C,
+    keyPath: KeyPath<K>,
+    updater: (value: RetrievePath<C, Array<K>>) => unknown
+  ): { [key: PropertyKey]: V };
+  function updateIn<
+    K extends PropertyKey,
+    V,
+    C extends { [key: PropertyKey]: V },
+    NSV,
+  >(
+    collection: C,
+    keyPath: KeyPath<K>,
+    notSetValue: NSV,
+    updater: (value: RetrievePath<C, Array<K>> | NSV) => unknown
+  ): { [key: PropertyKey]: V };
 
   /**
    * Returns a copy of the collection with the remaining collections merged in.