Add TypeScript declaration file through JSDoc

[hirasso]

Out of curiosity I gave this a try:

• installed typescript
• added an npm script types:generate:

  npx tsc --allowJs -d --emitDeclarationOnly src/index.js

• almost bit my teeth trying to get the JSDoc right for the plugin's nested options object 🤯😄

We should discuss if this is the right way to do it. The process JSDoc->tsc could become quite a big maintenance chore, I can imagine. How could we make sure it doesn't diverge from the actual code? I have the feeling that, if we want to support TS, we would have to rewrite the actual code to TypeScript. It feels like this wouldn't be more work then adding JSDoc.

[daun]

Nice work! Good to have a baseline on the workflow and quality to expect.

What's a good way of validating/checking the generated types?

It feels like this wouldn't be more work then adding JSDoc.

I haven't ported over any projects to TS lately, but that sounds wildly optimistic to me 🤠 I agree with migrating to TS if it improves the codebase in the long term, but getting it right for the core and all plugins will take us a few weeks realistically, no?

[hirasso]

I haven't ported over any projects to TS lately, but that sounds wildly optimistic to me 🤠 I agree with migrating to TS if it improves the codebase in the long term, but getting it right for the core and all plugins will take us a few weeks realistically, no?

The less I know the more optimistic I get 😁 ...I have actually never written a single line of TypeScript myself.

What's a good way of validating/checking the generated types?

That's exactly what I don't know and why I thought, well, TypeScript checks correct typings, right? Here the consumers would be on the mercy of us not making mistakes in the JSDocs...

[hirasso]

TypeScript allows plain JS, right? We could just switch to .ts for all files in swup/src and incrementally add typings. No rewrite required, just some refactoring maybe?

[daun]

What's a good way of validating/checking the generated types?

That's exactly what I don't know and why I thought, well, TypeScript checks correct typings, right? Here the consumers would be on the mercy of us not making mistakes in the JSDocs...

Exactly, with TS we know they're correct, with JSDoc conversion we'd have to also check if the TS conversion produced the correct type definitions.

[daun]

I'd opt for not merging this until we figured out which way to go with the codebase.

[hirasso]

Ok, lets do this