implement jQuery's .has()

Author: cvrebert

Readme.md

@@ -448,6 +448,24 @@ $('li').filter(function(i, el) {
 //=> 2
 ```
 
+#### .has( selector ) <br /> .has( element )
+
+Filters the set of matched elements to only those which have the given DOM element as a descendant or which have a descendant that matches the given selector. Equivalent to `.filter(':has(selector)')`.
+
+Selector:
+
+```js
+$('ul').has('.pear').attr('id');
+//=> fruits
+```
+
+Element:
+
+```js
+$('ul').has($('.pear')[0]).attr('id');
+//=> fruits
+```
+
 #### .first()
 Will select the first element of a cheerio object
 

lib/api/traversing.js

@@ -328,6 +328,13 @@ var makeFilterMethod = function(filterFn) {
 exports.filter = makeFilterMethod(_.filter);
 exports.not = makeFilterMethod(_.reject);
 
+exports.has = function(selectorOrHaystack) {
+  var that = this;
+  return exports.filter.call(this, function() {
+    return that._make(this).find(selectorOrHaystack).length > 0;
+  });
+};
+
 exports.first = function() {
   return this.length > 1 ? this._make(this[0]) : this;
 };

test/api.traversing.js

@@ -825,6 +825,38 @@ describe('$(...)', function() {
     });
   });
 
+  describe('.has', function() {
+
+    beforeEach(function() {
+      $ = cheerio.load(food);
+    });
+
+    it('(selector) : should reduce the set of matched elements to those with descendants that match the selector', function() {
+      var $fruits = $('#fruits,#vegetables').has('.pear');
+      expect($fruits).to.have.length(1);
+      expect($fruits[0]).to.be($('#fruits')[0]);
+    });
+
+    it('(selector) : should only consider nested elements', function() {
+      var $empty = $('#fruits').has('#fruits');
+      expect($empty).to.have.length(0);
+    });
+
+    it('(element) : should reduce the set of matched elements to those that are ancestors of the provided element', function() {
+      var $fruits = $('#fruits,#vegetables').has($('.pear')[0]);
+      expect($fruits).to.have.length(1);
+      expect($fruits[0]).to.be($('#fruits')[0]);
+    });
+
+    it('(element) : should only consider nested elements', function() {
+      var $fruits = $('#fruits');
+      var fruits = $fruits[0];
+      var $empty = $fruits.has(fruits);
+
+      expect($empty).to.have.length(0);
+    });
+  });
+
   describe('.first', function() {
 
     it('() : should return the first item', function() {