Cheerio: Add 1.0.0-rc.1 to History.md

Created on 28 Jun 2017 · 16Comments · Source: cheeriojs/cheerio

npm is telling me that cheerio is out of date, I'm using 0.22.0 and it's suggesting 1.0.0-rc.1. I looked at History.md but there's no indication of what changes are already in 1.0.0-rc.1 and what changes can be expected in 1.0.0, so I'm hoping this could be added to the History file so I can see what new features and breaking changes are there and evaluate whether I want to upgrade yet or wait until later.

Source

rightaway

👍13

All 16 comments

There is a v1.0.0 branch that contains an updated README.

@jugglinmike What is your impression of v1.0.0 so far? Afaict we should be good to go live with it.

fb55 on 27 Aug 2017

👍1

I think so, too. Just to be certain, though, I'd like to call on @ljharb for input.

Hi Jordan! enzyme is a highly successful project that depends on Cheerio. We've been vetting a 1.0.0 release for a few months now, and I'd love to get your input on the release candidate before we publish version 1.0. The History.md file on the v1.0.0 branch lists the details. The biggest change is probably the change in behavior to the load method, but I believe that your users don't interact with that method directly.

Enzyme (wisely) depends on Cheerio using npm's ^ operator, so publication here won't automatically change anything there. Still, I figured getting feedback earlier couldn't hurt. Would you mind taking a look and letting us know what you think?

jugglinmike on 27 Aug 2017

We're hoping to release v3 of enzyme soon, so if v1 of cheerio is coming out first, we could do the bump at the same time - can you point me to the best migration guide / summary of breaking changes, so I can review?

ljharb on 27 Aug 2017

Sure thing! You'll want to reference the History.md file on the v1.0.0 branch:

https://github.com/cheeriojs/cheerio/blob/48eae25c93702a29b8cd0d09c4a2dce2f912d1f4/History.md

jugglinmike on 27 Aug 2017

@jugglinmike thanks - the section on "load" isn't clear to me on what i'd need to look out for with existing uses of .load. It kind of looks like it's now going to always wrap my HTML string such that it produces an <html> document - how would I continue to pass HTML and have it treated like a document fragment? Am I reading it correctly that I'll want to change cheerio.load(html) to cheerio.load('')(html)? Are there any gotchas I need to look out for?

ljharb on 28 Aug 2017

Yup, that approach ought to compensate for the breaking changes. Is that feasible for Enzyme version 3?

Separately, if you have any feedback on how that changelog could be more clear/helpful, I'd be glad to incorporate it!

jugglinmike on 28 Aug 2017

Thanks! My suggestion would be:

If you have any code doing `cheerio.load(x)`, change it to `cheerio.load('')(x)` to avoid any breaking changes.

That way the straightforward codemod is explicit.

ljharb on 28 Aug 2017

See https://github.com/airbnb/enzyme/pull/1093

ljharb on 28 Aug 2017

@jugglinmike it looks like cheerio.load(x)(html).root() doesn't work in v1; what would the equivalent be?

ljharb on 29 Aug 2017

@fb55 Based on @ljharb's work in https://github.com/airbnb/enzyme/pull/1093, I think the migration guide could use some improvements (see that pull request for more details). I'm hoping to have a pull request for you to review some time this weekend.

jugglinmike on 31 Aug 2017

❤1

@jugglinmike the breaking change ended up working out in enzyme's favor; but it would be nice if there was some way to still produce the "fragment wrapper" that 0.22 does with cheerio.load('<div />'), in 1.0 - cheerio.load('')('<div />') gives me the div itself, but the prior example gives me something with 1 child which is the div itself.

ljharb on 31 Aug 2017

Great call @jugglinmike getting the enzyme team on board — thanks @ljharb, this will be incredibly helpful for other people migrating to 1.0! I'll be around for reviews this weekend, let me know if I can help in another way.

fb55 on 31 Aug 2017

❤1

@ljharb We try to help consumers write code that has parity with equivalent jQuery
code. This helps those looking to write "isomorphic" code and (maybe more
importantly) it avoids cognitive dissonance for developers who are already
familiar with jQuery (allowing for tutorial re-use and avoiding "context
switching" problems).

Unfortunately, jQuery does not expose an API for manipulating document
fragments. So while I can see how that behavior can be useful, I don't think
the need is strong enough to warrant a Cheerio-specific solution.

jugglinmike on 2 Sep 2017

What happens in jQuery if I do $([$('<div/>')])?

ljharb on 2 Sep 2017

The behavior of the jQuery function when called with an array of jQuery objects
isn't defined.

http://api.jquery.com/jQuery/#jQuery-object

And as you might expect with undocumented usage, things look a little wonky
there:

$.fn.jquery
"1.11.3"
$([$('<div/>')]).text()
""
$([$('<div/>')]).html()
undefined

jugglinmike on 2 Sep 2017

👍1

In the edge case of an input without any HTML tags a correct migration has to take this into account. Example (from https://github.com/airbnb/enzyme/pull/2221):

import cheerio from 'cheerio';
import { isHtml } from 'cheerio/lib/utils';

function loadCheerioRoot(html) {
  if (!html) {
    return cheerio.root();
  }

  if (!isHtml(html)) {
    // use isDocument=false to create fragment
    return cheerio.load(html, null, false).root();
  }

  return cheerio.load('')(html);
}