Description
The project has two notions of "static methods":
- Methods defined on the
Cheerioconstructor 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()
- 3 mimic methods defined on the global function defined by the jQuery project:
- 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:
- Export an ordinary object value (not a function)
- Re-implement
exports.html()andexports.xml()to operate in this context (rendering the "outer" markup of a "selection" defined by a provided Cheerio object) - Persist the following exported values:
exports.load(),exports.text(), andexports.version - Remove the
Cheerio.load()andCheerio.text()methods from the Cheerio constructor function
#2 directly contradicts the documentation on rendering, but the upgrade path is fairly straightforward:
$.html('.pear')becomescheerio.html($('.pear'))$.html($('.pear'))becomescheerio.html($('.pear'))$.html()becomescheerio.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?