immutable-js · jdeniau · Oct 17, 2024 · Aug 18, 2024 · Aug 19, 2024
diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -127,7 +127,7 @@
     "rollup": "3.28.1",
     "size-limit": "^8.2.6",
     "transducers-js": "0.4.174",
-    "tstyche": "^2.0.0",
+    "tstyche": "^2.1.1",
     "typescript": "5.1"
   },
   "size-limit": [

diff --git a/type-definitions/immutable.d.ts b/type-definitions/immutable.d.ts
@@ -1591,6 +1591,65 @@ declare namespace Immutable {
      * @see Collection.Keyed.flip
      */
     flip(): Map<V, K>;
+
+    /**
+     * Returns an OrderedMap of the same type which includes the same entries,
+     * stably sorted by using a `comparator`.
+     *
+     * If a `comparator` is not provided, a default comparator uses `<` and `>`.
+     *
+     * `comparator(valueA, valueB)`:
+     *
+     *   * Returns `0` if the elements should not be swapped.
+     *   * Returns `-1` (or any negative number) if `valueA` comes before `valueB`
+     *   * Returns `1` (or any positive number) if `valueA` comes after `valueB`
+     *   * Alternatively, can return a value of the `PairSorting` enum type
+     *   * Is pure, i.e. it must always return the same value for the same pair
+     *     of values.
+     *
+     * <!-- runkit:activate -->
+     * ```js
+     * const { Map } = require('immutable')
+     * Map({ "c": 3, "a": 1, "b": 2 }).sort((a, b) => {
+     *   if (a < b) { return -1; }
+     *   if (a > b) { return 1; }
+     *   if (a === b) { return 0; }
+     * });
+     * // OrderedMap { "a": 1, "b": 2, "c": 3 }
+     * ```
+     *
+     * Note: `sort()` Always returns a new instance, even if the original was
+     * already sorted.
+     *
+     * Note: This is always an eager operation.
+     */
+    sort(comparator?: Comparator<V>): this & OrderedMap<K, V>;
+
+    /**
+     * Like `sort`, but also accepts a `comparatorValueMapper` which allows for
+     * sorting by more sophisticated means:
+     *
+     * <!-- runkit:activate -->
+     * ```js
+     * const { Map } = require('immutable')
+     * const beattles = Map({
+     *   John: { name: "Lennon" },
+     *   Paul: { name: "McCartney" },
+     *   George: { name: "Harrison" },
+     *   Ringo: { name: "Starr" },
+     * });
+     * beattles.sortBy(member => member.name);
+     * ```
+     *
+     * Note: `sortBy()` Always returns a new instance, even if the original was
+     * already sorted.
+     *
+     * Note: This is always an eager operation.
+     */
+    sortBy<C>(
+      comparatorValueMapper: (value: V, key: K, iter: this) => C,
+      comparator?: (valueA: C, valueB: C) => number
+    ): this & OrderedMap<K, V>;
   }
 
   /**
@@ -2012,6 +2071,65 @@ declare namespace Immutable {
       predicate: (this: C, value: T, key: T, iter: this) => unknown,
       context?: C
     ): [this, this];
+
+    /**
+     * Returns an OrderedSet of the same type which includes the same entries,
+     * stably sorted by using a `comparator`.
+     *
+     * If a `comparator` is not provided, a default comparator uses `<` and `>`.
+     *
+     * `comparator(valueA, valueB)`:
+     *
+     *   * Returns `0` if the elements should not be swapped.
+     *   * Returns `-1` (or any negative number) if `valueA` comes before `valueB`
+     *   * Returns `1` (or any positive number) if `valueA` comes after `valueB`
+     *   * Alternatively, can return a value of the `PairSorting` enum type
+     *   * Is pure, i.e. it must always return the same value for the same pair
+     *     of values.
+     *
+     * <!-- runkit:activate -->
+     * ```js
+     * const { Set } = require('immutable')
+     * Set(['b', 'a', 'c']).sort((a, b) => {
+     *   if (a < b) { return -1; }
+     *   if (a > b) { return 1; }
+     *   if (a === b) { return 0; }
+     * });
+     * // OrderedSet { "a":, "b", "c" }
+     * ```
+     *
+     * Note: `sort()` Always returns a new instance, even if the original was
+     * already sorted.
+     *
+     * Note: This is always an eager operation.
+     */
+    sort(comparator?: Comparator<T>): this & OrderedSet<T>;
+
+    /**
+     * Like `sort`, but also accepts a `comparatorValueMapper` which allows for
+     * sorting by more sophisticated means:
+     *
+     * <!-- runkit:activate -->
+     * ```js
+     * const { Set } = require('immutable')
+     * const beattles = Set([
+     *   { name: "Lennon" },
+     *   { name: "McCartney" },
+     *   { name: "Harrison" },
+     *   { name: "Starr" },
+     * ]);
+     * beattles.sortBy(member => member.name);
+     * ```
+     *
+     * Note: `sortBy()` Always returns a new instance, even if the original was
+     * already sorted.
+     *
+     * Note: This is always an eager operation.
+     */
+    sortBy<C>(
+      comparatorValueMapper: (value: T, key: T, iter: this) => C,
+      comparator?: (valueA: C, valueB: C) => number
+    ): this & OrderedSet<T>;
   }
 
   /**

diff --git a/type-definitions/ts-tests/map.ts b/type-definitions/ts-tests/map.ts
@@ -1,5 +1,5 @@
 import { expect, test } from 'tstyche';
-import { Map, List, MapOf } from 'immutable';
+import { Map, List, MapOf, OrderedMap } from 'immutable';
 
 test('#constructor', () => {
   expect(Map()).type.toBe<Map<unknown, unknown>>();
@@ -602,6 +602,35 @@ test('#flip', () => {
   expect(Map<number, string>().flip()).type.toBe<Map<string, number>>();
 });
 
+test('#sort', () => {
+  expect(Map<string, string>().sort()).type.toBe<
+    Map<string, string> & OrderedMap<string, string>
+  >();
+  expect(Map<string, string>().sort((a, b) => 1)).type.toBe<
+    Map<string, string> & OrderedMap<string, string>
+  >();
+
+  expect(Map({ a: 'a' }).sort()).type.toBe<
+    MapOf<{ a: string }> & OrderedMap<'a', string>
+  >();
+});
+
+test('#sortBy', () => {
+  expect(Map<string, string>().sortBy(v => v)).type.toBe<
+    Map<string, string> & OrderedMap<string, string>
+  >();
+
+  expect(
+    Map<string, string>().sortBy(
+      v => v,
+      (a, b) => 1
+    )
+  ).type.toBe<Map<string, string> & OrderedMap<string, string>>();
+  expect(Map({ a: 'a' }).sortBy(v => v)).type.toBe<
+    MapOf<{ a: string }> & OrderedMap<'a', string>
+  >();
+});
+
 test('#withMutations', () => {
   expect(Map<number, number>().withMutations(mutable => mutable)).type.toBe<
     Map<number, number>

diff --git a/type-definitions/ts-tests/set.ts b/type-definitions/ts-tests/set.ts
@@ -1,5 +1,5 @@
 import { expect, test } from 'tstyche';
-import { Set, Map, Collection } from 'immutable';
+import { Set, Map, Collection, OrderedSet } from 'immutable';
 
 test('#constructor', () => {
   expect(Set()).type.toBe<Set<unknown>>();
@@ -229,6 +229,26 @@ test('#flatten', () => {
   expect(Set<number>().flatten('a')).type.toRaiseError();
 });
 
+test('#sort', () => {
+  expect(Set<string>().sort()).type.toBe<Set<string> & OrderedSet<string>>();
+  expect(Set<string>().sort((a, b) => 1)).type.toBe<
+    Set<string> & OrderedSet<string>
+  >();
+});
+
+test('#sortBy', () => {
+  expect(Set<string>().sortBy(v => v)).type.toBe<
+    Set<string> & OrderedSet<string>
+  >();
+
+  expect(
+    Set<string>().sortBy(
+      v => v,
+      (a, b) => 1
+    )
+  ).type.toBe<Set<string> & OrderedSet<string>>();
+});
+
 test('#withMutations', () => {
   expect(Set<number>().withMutations(mutable => mutable)).type.toBe<
     Set<number>