Merge pull request #592 from simov/stableSort

[FEATURE][ADD] Add stableSort function

snippets/stableSort.md

@@ -0,0 +1,21 @@
+### stableSort
+
+Performs stable sorting of an array, preserving the initial indexes of items when their values are the same. 
+Does not mutate the original array, but returns a new array instead.
+
+Use `Array.map()` to pair each element of the input array with its corresponding index. 
+Use `Array.sort()` and a `compare` function to sort the list, preserving their initial order if the items compared are equal.
+Use `Array.map()` to convert back to the initial array items.
+
+```js
+const stableSort = (arr, compare) =>
+  arr
+    .map((item, index) => ({ item, index }))
+    .sort((a, b) => compare(a.item, b.item) || a.index - b.index)
+    .map(({ item }) => item);
+```
+
+```js
+const arr = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
+const stable = stableSort(arr, () => 0); // [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
+```