feat: implements stable sorting

Fix #331

docs/pages/api.rst

@@ -2140,6 +2140,9 @@ Sort a collection using a callback. If no callback is provided, it will sort usi
 By default, it will sort by values and using a callback. If you want to sort by keys, you can pass a parameter to change
 the behaviour or use twice the flip operation. See the example below.
 
+Since version 7.4, sorting is `stable` by default. Stable sort algorithms sort equal
+elements in the same order that they appear in the input.
+
 Interface: `Sortable`_
 
 Signature: ``Collection::sort(int $type = Sortable::BY_VALUES, ?callable $callback = null): Collection;``

src/Operation/Sort.php

@@ -73,7 +73,7 @@ static function (iterable $iterable) use ($type, $callback): Generator {
                              * @param array{0:TKey|T, 1:T|TKey} $left
                              * @param array{0:TKey|T, 1:T|TKey} $right
                              */
-                            static fn (array $left, array $right): int => $callback($right[1], $left[1]);
+                            static fn (array $left, array $right): int => (0 === $return = $callback($right[1], $left[1])) ? ($right[0] <=> $left[0]) : $return;
 
                         $sortedIterator =
                             /**

tests/unit/IssuesTest.php

@@ -36,4 +36,24 @@ public function testIssue264()
         self::assertEquals('c', $subject->get(300));
         self::assertEquals('d', $subject->get(400));
     }
+
+    public function testIssue331(): void
+    {
+        $valueObjectFactory = static fn (int $id, int $weight) => new class($id, $weight) {
+            public function __construct(
+                public readonly int $id,
+                public readonly int $weight,
+            ) {}
+        };
+
+        $input = Collection::fromIterable([
+            $valueObjectFactory(id: 1, weight: 1),
+            $valueObjectFactory(id: 2, weight: 1),
+            $valueObjectFactory(id: 3, weight: 1),
+        ])
+            ->sort(callback: static fn (object $a, object $b): int => $a->weight <=> $b->weight)
+            ->map(static fn ($item): int => $item->id);
+
+        self::assertEquals([1, 2, 3], $input->all());
+    }
 }