Selector: Implement the `uniqueSort` chainable method

Some APIs, like `.prevAll()`, return elements in the reversed order, causing
confusing behavior when used with wrapping methods (see gh-5149 for more info)
 To provide an easy workaround, this commit implements a chainable `uniqueSort`
method on jQuery objects, an equivalent of `jQuery.uniqueSort`.

Fixes gh-5166
Closes gh-5168

2 files changed, 61 insertions, 22 deletions

diff --git a/src/selector/uniqueSort.js b/src/selector/uniqueSort.js
index e9438485c..91c7193e9 100644
--- a/src/selector/uniqueSort.js
+++ b/src/selector/uniqueSort.js
@@ -2,6 +2,7 @@ import jQuery from "../core.js";
 import document from "../var/document.js";
 import sort from "../var/sort.js";
 import splice from "../var/splice.js";
+import slice from "../var/slice.js";
 
 var hasDuplicate;
 
@@ -87,3 +88,7 @@ jQuery.uniqueSort = function( results ) {
 
 	return results;
 };
+
+jQuery.fn.uniqueSort = function() {
+	return this.pushStack( jQuery.uniqueSort( slice.apply( this ) ) );
+};
diff --git a/test/unit/selector.js b/test/unit/selector.js
index 4f50412e7..720d2ddf5 100644
--- a/test/unit/selector.js
+++ b/test/unit/selector.js
@@ -1923,20 +1923,8 @@ QUnit.test( "find in document fragments", function( assert ) {
 	assert.strictEqual( elem.length, 1, "Selection works" );
 } );
 
-QUnit.test( "jQuery.uniqueSort", function( assert ) {
-	assert.expect( 14 );
-
-	function Arrayish( arr ) {
-		var i = this.length = arr.length;
-		while ( i-- ) {
-			this[ i ] = arr[ i ];
-		}
-	}
-	Arrayish.prototype = {
-		sliceForTestOnly: [].slice
-	};
-
-	var i, tests,
+function getUniqueSortFixtures() {
+	var i,
 		detached = [],
 		body = document.body,
 		fixture = document.getElementById( "qunit-fixture" ),
@@ -1951,7 +1939,7 @@ QUnit.test( "jQuery.uniqueSort", function( assert ) {
 		detached2.appendChild( document.createElement( "li" ) ).id = "detachedChild" + i;
 	}
 
-	tests = {
+	return {
 		"Empty": {
 			input: [],
 			expected: []
@@ -1992,15 +1980,61 @@ QUnit.test( "jQuery.uniqueSort", function( assert ) {
 			length: 3
 		}
 	};
+}
+
+QUnit.test( "jQuery.uniqueSort", function( assert ) {
+	assert.expect( 14 );
 
-	jQuery.each( tests, function( label, test ) {
-		var length = test.length || test.input.length;
-		// We duplicate `test.input` because otherwise it is modified by `uniqueSort`
+	var fixtures = getUniqueSortFixtures();
+
+	function Arrayish( arr ) {
+		var i = this.length = arr.length;
+		while ( i-- ) {
+			this[ i ] = arr[ i ];
+		}
+	}
+	Arrayish.prototype = {
+		sliceForTestOnly: [].slice
+	};
+
+	jQuery.each( fixtures, function( label, fixture ) {
+		var length = fixture.length || fixture.input.length;
+
+		// We duplicate `fixture.input` because otherwise it is modified by `uniqueSort`
 		// and the second test becomes worthless.
-		assert.deepEqual( jQuery.uniqueSort( test.input.slice( 0 ) ).slice( 0, length ),
-			test.expected, label + " (array)" );
-		assert.deepEqual( jQuery.uniqueSort( new Arrayish( test.input ) ).sliceForTestOnly( 0, length ),
-			test.expected, label + " (quasi-array)" );
+		assert.deepEqual(
+			jQuery.uniqueSort( fixture.input.slice( 0 ) )
+				.slice( 0, length ),
+			fixture.expected,
+			label + " (array)"
+		);
+
+		assert.deepEqual(
+			jQuery.uniqueSort( new Arrayish( fixture.input ) )
+				.sliceForTestOnly( 0, length ),
+			fixture.expected,
+			label + " (quasi-array)"
+		);
+	} );
+} );
+
+QUnit.test( "uniqueSort()", function( assert ) {
+	assert.expect( 28 );
+
+	var fixtures = getUniqueSortFixtures();
+
+	jQuery.each( fixtures, function( label, fixture ) {
+		var length = fixture.length || fixture.input.length,
+			fixtureInputCopy = fixture.input.slice( 0 ),
+			sortedElem = jQuery( fixture.input ).uniqueSort();
+
+		assert.deepEqual( fixture.input, fixtureInputCopy, "Fixture not modified (" + label + ")" );
+
+		assert.deepEqual( sortedElem.slice( 0, length ).toArray(), fixture.expected, label );
+
+		// Chaining
+		assert.ok( sortedElem instanceof jQuery, "chaining" );
+		assert.deepEqual( sortedElem.end().toArray(), fixture.input, label );
 	} );
 } );