Validate existing JavaScript implementation with TypeScript

[EzraBrooks]

Public API Changes

• The internals of some class constructors no longer protect against users passing undefined or no argument for options. However, this was never actually supported, so this should not affect the great majority of users.

Description

Using the TypeScript compiler to statically type-check the existing JavaScript in this repository (and hopefully also auto-generate some typescript typings, that would be nice)

TODO:

• get it building without errors
• add the typescript step to the grunt build
• Tweak some build settings, probably, to reduce compiled size (removing unnecessary polyfills)

[EzraBrooks]

Refactored prototypes to classes in 98ab37c due to TypeScript lacking support for JSDoc @extends for prototypes.

[EzraBrooks]

The tsc build is passing! I had to scatter more ts-expect-error directives around than I would've liked, but that's why it's there - to allow slow conversion from untyped to typed code.

[EzraBrooks]

When reviewing this I highly recommend checking the "hide whitespace" box because there's a ton of indentation changes because of the prototype->class migration.

[EzraBrooks]

I've been progressively rolling back any "fixes" that I made in the name of making red squiggles go away, in favor of instead marking them with // @ts-expect-error so we can have the build pass but have a to-do list of fixes to make by just searching for that marker in the codebase.

This PR is a substantial enough improvement just from having syntactically-correct JSDoc that is validated by tsc and having ES6+ classes.

[EzraBrooks]

getting very close but still wrestling with some JSDoc details.

[EzraBrooks]

I've been playing with the typescript compiler settings and I don't think I can make the bundle smaller, if we're going to continue supporting ES5 (which I think we should for now).

In my opinion we should take the size hit, then switch to a more optimal bundler that may help, then over time incrementally raise our target ECMAScript version to reduce the number of polyfills TypeScript is including.

[sea-bass]

We got to a point where these changes work in our dev environment, so I'm approving this.

Of course, let's cut this v1/v2 boundary first before merging here.

[EzraBrooks]

I think we should get rid of the built content in the repo a la #643 before merging this - but yeah, need v2 cut.

[EzraBrooks]

consensus between me and @sea-bass: this is:

• a release delineating change
• too big to review well
• and I really did try pretty damn hard not to break API which was quite difficult

so we're gonna merge this and fix any other problems as they arise in our usage or in Issues.

[sea-bass]

We also are actively using this branch in our project, so that gives us confidence that it does, in fact, work.

[MatthijsBurgh]

Why are we bumping to 1.4.1? Why not already bump it to 2.0.0, so people know this isn't 1.X anymore. Doesn't mean we need to release it.

[MatthijsBurgh]

Or this isn't breaking yet?

[sea-bass]

Why are we bumping to 1.4.1? Why not already bump it to 2.0.0, so people know this isn't 1.X anymore. Doesn't mean we need to release it.

We probably should bump it to 2.0.0. I can do it in #645, or we can do it as a standalone PR.

[EzraBrooks]

this shouldn't be breaking yet - but anyway, sorry, the 1.4.1 came in as a merge conflict and I should've reconciled it as 2.0.0!