Projects can choose to do as they please but the pros of "not compiling" don't outweigh the problem being introduced here.
When you write TypeScript using it's type declarations IT IS your source of truth.
When you write JSDoc and implement alongside the declaration you now have two sources of truth.
This for me far outweighs any gain. Introducing multiple sources of truth like this for a large codebase just makes them prone to bugs and fragile for new developers to get started.
I think you've missed the point, you can quite easily abuse what the JSDoc states and what is actually written by the engineer.
JSDoc
vs
TypeScript
By the time you add some form of pipeline w/ linting on top of the JSDoc approach you are already reliant upon a toolchain, you may as well just compile from source 🤷🏼♀️
Each to their own though, hand craft it if it makes the engineer feel like they have more control and have reduced headaches. But from experience working on multi million LoC web apps now, across multiple teams, enforcing engineers to write JSDoc always and maintain it would have been a nightmare.
I'm not sure what this is trying to show? You are running TypeScript here, you're dependant on tsc without relishing any of the benefits like type declarations that are transformative but removed after compilation e.g. Omit.
The entire point of this whole article is that both approaches use TypeScript Compiler to do typechecking and that the type safety and IntelliSense is 100% equivalent. It is literally beyond me how people can miss that when it's repeatedly stated in the article, with massive emphasis.
Because there is literally 0 requirement to run tsc for any reason, whatsoever, from the standpoint of the author of the code...
You now have a necessary build step to catch the errors that the developer made in JSDoc, but you have to do it in a post dev process, if you aren't going to run a live recompilation step... and if you are going to run a live recompilation step, then you are just adding more headaches because you are inventing more ways of writing your type incorrectly, without being caught by the editor (and instead requiring debugging via the terminal, or debugging via a precommit hook, or via a PR process). You went through the whole trouble of setting up the whole buildchain (at least from dev to origin) but completely skipped out on the benefits of great type inference and advanced type algebra being vetted in real-time, with immediate dev feedback. So you are still doing 100% of the work but getting ~40% of the benefit, with the added danger of being confidently incorrect about your types, and the added frustration of getting your feedback in a different place than your text buffer, and you are even adding the extra timebomb of allowing untested JSDoc through, given that it doesn't need any part of the build step to function.
I am going to repeat this 3 times in the hopes that it lands, because people keep missing this despite the author emphasizing this point multiple times:
Real time type inference, editor feedback, Intellisense, is completely equivalent to using TS files.
Real time type inference, editor feedback, Intellisense, is completely equivalent to using TS files.
Real time type inference, editor feedback, Intellisense, is completely equivalent to using TS files.
There is no need to run TSC to see the type errors, in VSCode and Jetbrains editors, Typescript Language Server works with both TS files and JSDocs in JS files, in the EXACT same way, to provide this live feedback, all you need it to set allowJs and checkJs to true in your tsconfig for that to happen. There is 0 difference. ZERO. There is no need to run tsc --noEmit during dev to lint, because you get the feedback immediately in your editor just like you would if you were using TS files.
Projects can choose to do as they please but the pros of "not compiling" don't outweigh the problem being introduced here.
When you write TypeScript using it's type declarations IT IS your source of truth.
When you write JSDoc and implement alongside the declaration you now have two sources of truth.
This for me far outweighs any gain. Introducing multiple sources of truth like this for a large codebase just makes them prone to bugs and fragile for new developers to get started.
This is wrong. Your types are still the source of truth.
I think you've missed the point, you can quite easily abuse what the JSDoc states and what is actually written by the engineer.
JSDoc
vs
TypeScript
By the time you add some form of pipeline w/ linting on top of the JSDoc approach you are already reliant upon a toolchain, you may as well just compile from source 🤷🏼♀️
Each to their own though, hand craft it if it makes the engineer feel like they have more control and have reduced headaches. But from experience working on multi million LoC web apps now, across multiple teams, enforcing engineers to write JSDoc always and maintain it would have been a nightmare.
I'm not sure what this is trying to show? You are running TypeScript here, you're dependant on
tscwithout relishing any of the benefits like type declarations that are transformative but removed after compilation e.g.Omit.Have you actually read the article? The point that is repeatedly made is that you're still using tsc
The entire point of this whole article is that both approaches use TypeScript Compiler to do typechecking and that the type safety and IntelliSense is 100% equivalent. It is literally beyond me how people can miss that when it's repeatedly stated in the article, with massive emphasis.
Because there is literally 0 requirement to run
tscfor any reason, whatsoever, from the standpoint of the author of the code...You now have a necessary build step to catch the errors that the developer made in JSDoc, but you have to do it in a post dev process, if you aren't going to run a live recompilation step... and if you are going to run a live recompilation step, then you are just adding more headaches because you are inventing more ways of writing your type incorrectly, without being caught by the editor (and instead requiring debugging via the terminal, or debugging via a precommit hook, or via a PR process). You went through the whole trouble of setting up the whole buildchain (at least from dev to origin) but completely skipped out on the benefits of great type inference and advanced type algebra being vetted in real-time, with immediate dev feedback. So you are still doing 100% of the work but getting ~40% of the benefit, with the added danger of being confidently incorrect about your types, and the added frustration of getting your feedback in a different place than your text buffer, and you are even adding the extra timebomb of allowing untested JSDoc through, given that it doesn't need any part of the build step to function.
I am going to repeat this 3 times in the hopes that it lands, because people keep missing this despite the author emphasizing this point multiple times:
Real time type inference, editor feedback, Intellisense, is completely equivalent to using TS files.
Real time type inference, editor feedback, Intellisense, is completely equivalent to using TS files.
Real time type inference, editor feedback, Intellisense, is completely equivalent to using TS files.
There is no need to run TSC to see the type errors, in VSCode and Jetbrains editors, Typescript Language Server works with both TS files and JSDocs in JS files, in the EXACT same way, to provide this live feedback, all you need it to set allowJs and checkJs to true in your tsconfig for that to happen. There is 0 difference. ZERO. There is no need to run tsc --noEmit during dev to lint, because you get the feedback immediately in your editor just like you would if you were using TS files.
You run tsc as a linter.