Normalizing the public API

The project has two notions of “static methods”:

1. Methods defined on the Cheerio constructor function. There are six in total:
   • 3 mimic methods defined on the global function defined by the jQuery project: .contains(), .merge(), and .parseHTML()
   • 3 are specific to Cheerio, exposed to address concerns that are not relevant in the browser context .html() and .xml(), .root()
2. Methods defined on the module’s exported value (e.g. the value returned from require('cheerio')). There are two of these: .load() and .text().

As of today, however, the source does not reflect this distinction. All eight methods are defined in both places.

The exported value is itself the constructor for the Cheerio object. We have never documented the direct use of this constructor. As far as I remember, we have always instructed folks to use it indirectly, after being “bound” by the load method (as trying to use it directly would involve re-implementing the load method).

These details make the API difficult to document, and they may cause confusion for developers who are new to the project. (The methods in the first set don’t make sense in the context of the Cheerio module itself, and the methods in the second set don’t apply to a Cheerio function that has been “bound” to a document.) Because we are preparing for a major release, I would like to discuss taking the opportunity to make a breaking change:

1. Export an ordinary object value (not a function)
2. Re-implement exports.html() and exports.xml() to operate in this context (rendering the “outer” markup of a “selection” defined by a provided Cheerio object)
3. Persist the following exported values: exports.load(), exports.text(), and exports.version
4. Remove the Cheerio.load() and Cheerio.text() methods from the Cheerio constructor function

#2 directly contradicts the documentation on rendering, but the upgrade path is fairly straightforward:

• $.html('.pear') becomes cheerio.html($('.pear'))
• $.html($('.pear')) becomes cheerio.html($('.pear'))
• $.html() becomes cheerio.html($.root())

I think this is warranted because it makes the API easier to understand/document and because it further reduces disparities between “Cheerio objects” and “jQuery objects”.

@fb55 @matthewmueller does this sound good to you? And are there any consumers out there that can share a use case which would be prevented by the change I’m proposing?

[matthewmueller]

Would it be possible to upgrade this without breaking anything? I agree with these changes and given that we’re still in 0.x, I’m open to this change.

I do think it’d be better if we can avoid breaking anything, alias these functions and update the docs with the improved API.

Lots of users these days – over 5 million downloads per month (!!). For better or for worse, there’s going to be some package.json’s with { "cheerio": "*" } 🙃

[jugglinmike]

We just completed step 3 via gh-1232, so it’s safe to call this issue resolved 😃