Export JSDoc types

[Theaninova]

Fixes #312 and #214.

Since most of the packages are typed nicely using JSDoc it's possible to make them visible to TypeScript consumers via a single index.d.ts containing export * from './src/index.js' (allowJs might need to be true in the consumer's tsconfig.json).

[lojjic]

Thanks for this! It's an intriguing approach. I'm not very knowledgeable about the TS-JS interop... Is there a way to see what types this is "generating" into the TS system when a user consumes the library this way? My concern is if the JSDocs are incomplete (or incorrect), this would put extra burden on the user to add workarounds like "as any" casts in their code. But without seeing what TS is creating, we can't catch these prior to publishing...?

[Theaninova]

It really isn't "generating" any types as much as it's just exposing the already existing types, so what you get is exactly what you put in the JSDoc, plus inferred types like you would have in a .ts file.

In fact, you can have a fully type-checked JS project without a single TypeScript file through JS syntax, and many projects are using this approach because it makes consuming libraries a lot more pleasant and you don't need a build step, Svelte as an example does this.

While JSDoc is generally a lot less at risk of becoming outdated compared to separately maintained .d.ts files, without migrating to a fully type-checked JSDoc TypeScript project you can't really catch wrong types... Although most editors nowadays will automatically use JSDoc as type hints, and thus highlight any type errors, it's just not enforced.

TL;DR

• no need to check
• JS + JSDoc has the same capabilities as TS
• some types are inferred just like they are in TS
• it's like publishing a TypeScript project without running a type checker, but afaik usually libraries don't get type-checked from the consumer side and won't produce type errors