feat: align some methods with the Change By Copy proposal (#9207)

BREAKING CHANGE: The `sorted` method has been renamed to `toSorted`

Author: almeidx

packages/collection/__tests__/collection.test.ts

@@ -754,14 +754,6 @@ describe('sort() tests', () => {
 		expect([...coll.values()]).toStrictEqual([1, 2, 3]);
 	});
 
-	test('sort a collection', () => {
-		const coll = createCollectionFrom(['a', 3], ['b', 2], ['c', 1]);
-		expect([...coll.values()]).toStrictEqual([3, 2, 1]);
-		const sorted = coll.sorted((a, b) => a - b);
-		expect([...coll.values()]).toStrictEqual([3, 2, 1]);
-		expect([...sorted.values()]).toStrictEqual([1, 2, 3]);
-	});
-
 	describe('defaultSort', () => {
 		test('stays the same if it is already sorted', () => {
 			const coll = createTestCollection();
@@ -855,6 +847,48 @@ describe('union() tests', () => {
 	});
 });
 
+describe('toReversed() tests', () => {
+	test('reverses a collection', () => {
+		const coll = createTestCollection();
+		const reversed = coll.toReversed();
+		expect([...reversed.entries()]).toStrictEqual([
+			['c', 3],
+			['b', 2],
+			['a', 1],
+		]);
+	});
+
+	test('does not the modify original collection', () => {
+		const coll = createTestCollection();
+		const originalEntries = [...coll.entries()];
+		const reversed = coll.toReversed();
+
+		expect(reversed).not.toBe(coll);
+		expect([...coll.entries()]).toStrictEqual(originalEntries);
+	});
+});
+
+describe('toSorted() tests', () => {
+	test('sorts a collection', () => {
+		const coll = createCollectionFrom(['a', 3], ['b', 2], ['c', 1]);
+		const sorted = coll.toSorted((a, b) => a - b);
+		expect([...sorted.entries()]).toStrictEqual([
+			['c', 1],
+			['b', 2],
+			['a', 3],
+		]);
+	});
+
+	test('does not modify the original collection', () => {
+		const coll = createCollectionFrom(['a', 3], ['b', 2], ['c', 1]);
+		const originalEntries = [...coll.entries()];
+		const sorted = coll.toSorted();
+
+		expect(sorted).not.toBe(coll);
+		expect([...coll.entries()]).toStrictEqual(originalEntries);
+	});
+});
+
 describe('random thisArg tests', () => {
 	const coll = createCollectionFrom(['a', 3], ['b', 2], ['c', 1]) as Collection<string, unknown>;
 

packages/collection/src/collection.ts

@@ -906,6 +906,14 @@ export class Collection<K, V> extends Map<K, V> {
 		return coll;
 	}
 
+	/**
+	 * Identical to {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/toReversed | Array.toReversed()}
+	 * but returns a Collection instead of an Array.
+	 */
+	public toReversed() {
+		return new this.constructor[Symbol.species](this).reverse();
+	}
+
 	/**
 	 * The sorted method sorts the items of a collection and returns it.
 	 * The sort is not necessarily stable in Node 10 or older.
@@ -919,7 +927,7 @@ export class Collection<K, V> extends Map<K, V> {
 	 * collection.sorted((userA, userB) => userA.createdTimestamp - userB.createdTimestamp);
 	 * ```
 	 */
-	public sorted(compareFunction: Comparator<K, V> = Collection.defaultSort) {
+	public toSorted(compareFunction: Comparator<K, V> = Collection.defaultSort) {
 		return new this.constructor[Symbol.species](this).sort((av, bv, ak, bk) => compareFunction(av, bv, ak, bk));
 	}