Add JSDoc-based TypeScript checks + first-class types

[mourner]

This is just an experiment to see what it would take to add TypeScript checks and first-class types to a library of mine without going all the way of converting the code. The result is pretty nice — it even caught a ligitimate bug! (Fixed in f3d24b3)

JSDoc TS syntax is a little verbose for my liking, but seems like an acceptable tradeoff, and is heavily endorsed by @Rich-Harris.

[mourner]

@mfedderly does this look good to you as the author of the types on DefinitelyTyped? The first-class types would supersede your work, but would make it easier to keep the types up to date and maintained going forward.

[mfedderly]

This is the first I've actually really looked at the JSDoc TS syntax, but it looks pretty reasonable. Its a nice alternative to a handwritten index.d.ts to keep things accessible to JS devs when you don't want to go full typescript.

I think we're supposed to turn the DefinitelyTyped ones into stubs once the upstream package gets types added (https://github.com/DefinitelyTyped/DefinitelyTyped#removing-a-package). Let me know if you want me to do that after you do the next release of flatbush.

[mourner]

@mfedderly just released a new version with the first-class types, so will appreciate help with removing the package from DefinitelyTyped 🙏

[mfedderly]

Working on it now. microsoft/DefinitelyTyped-tools#682 is a prerequisite for the DefinitelyTyped PR.

[mfedderly]

DefinitelyTyped/DefinitelyTyped#65662