Port to TypeScript

[fb55]

Over the past year and a bit, I have ported all of my packages that Cheerio depends on to TypeScript. Some otherwise hard-to-diagnose bugs were fixed this way, the code style was updated to modern JS, and type definitions became more reliable.

I have been thinking about porting Cheerio for a bit now. I have recently found several issues using the TypeScript compiler in #1615, which was very promising. Some considerations for a port are:

(1) Is the exported Cheerio constructor an actual class?

The issue here is that this constructor is rarely called with new. ES6 classes throw an error in that case, leading to a breaking change.

We will target ES5 for now, in which case the TS compiler will actually allow us to create class instances without new. This could be an issue should we ever want to change our compilation target.

(2) How do we maintain the directory structure?

We can maintain the existing directory structure by extending the interface of a Cheerio class:

import * as attributes from './api/attributes';
import * as css from './api/css';
import * as forms from './api/forms';

class Cheerio {
  constructor(...args){}
}

type Attributes = typeof attributes;
type CSS = typeof css;
type Forms = typeof forms;

interface Cheerio extends Attributes, CSS, Forms {}

export default Cheerio;

---

I'd love to hear everyone's thoughts on making this change. This can be additional considerations, as well as general feedback whether this is the right move for this project.

cc'ing @matthewmueller, @5saviahv and @XhmikosR

[XhmikosR]

I'm not familiar with TypeScript myself so I can't really comment on that. But, right now the codebase is still using old syntax and is tied to Node.js 0.12, which is very unfortunate.

What I would do:

1. wrap up any PRs and release a new RC version; there have been a few nice improvements
2. finalize v1.0.0 stable
3. switch to strict mode and modern features and drop support for really ancient Node.js versions
4. after the above, the switch to TypeScript would be easier, is my guess
5. don't be afraid to bump major versions :)

[fb55]

TS would allow us to support older Node versions for longer. Particularly this makes the move attractive.

I agree that we should cut another RC before, to isolate potential issues.

Also yes in theory to not being afraid of major bumps. The long lead time to 1.0 unfortunately means that this version has a bit more meaning to it, and I would like to make the most of it. I would expect future versions to be released more regularly.

[5saviahv]

I'm also not very familiar with TypeScript and I even like pure javascript, but I also like maybe less dodgy code with TypeScript.

I think v1.0 should still be javascript (with type definitions), goal for this version was integrate parse5, but it is derailed over the years.

I do like idea for porting code to TypeScript, but maybe it should be on road map for next version.

[fb55]

I have opened #1816, implementing this change. I'd appreciate if you could have a look!

[5saviahv]

I looked briefly it looks nice. But one question - how did you solve cheerio accepting both parse5 and htmlparser2 node elements. I remember there was PR for parse5 adapter or did you use some other method.

I will come back in few days and make some tests with it, mean while nice job.

[fb55]

I've updated domhandler's types to be a superset of parse5. parse5 should still be updated to use the domhandler types directly, but this should unblock us for now.

[fb55]

Locking as this has landed.