Comment by _gruntled
2 years ago
> It's also a really contrarian viewpoint about typescript which is really popular.
I really, really don't get the controversy here. JSDoc _is_ TypeScript, just with a syntax that's valid JavaScript (on account of it living in comments). This means it doesn't have to be built to run, but still gets all of the typing goodies regular TypeScript does. The end-user code authoring experience is the same or better.
> To completely switch over to js and then set types that way seems regressive.
"It's regressive to use a fully-JS TypeScript syntax instead of using dozens of tools on top of regular TypeScript to achieve the same outcome" is quite a spicy take.
> "It's regressive to use a fully-JS TypeScript syntax instead of using dozens of tools on top of regular TypeScript to achieve the same outcome" is quite a spicy take.
To be fair, "We are so invested in TypeScript we're dropping it!" is an equally astonishing take. It's language I'd expect from Google about any of their projects.
But that's the thing, it's _not astonishing_. It _would_ be astonishing if we were abandoning typing Svelte. We're not. We're not even abandoning TypeScript -- the whole project will still run `tsc` and enforce complete type-safety, it just won't use the compiled output. This is _abandoning one syntax for another_ because one syntax doesn't require a build step and a huge toolchain to run and debug.
> JSDoc _is_ TypeScript
This is surprisingly true in a way. TypeScript is not a language(1), it's primarily a linter-assisting overlay atop of an actual language, JavaScript. Also, there's a linter that outputs and bundles JS, shedding the alien type annotations and also injecting its own, very partial runtime.
So, JSDoc is just a linter/documenter aid. And so is TypeScript.
(1) TS is not a language: it has no spec, no reference documentation. It defines no behaviors, in particular, no runtime behaviors. It sits atop of various JS versions, layering over them in unspecified ways. TS is a linting layer, and also is a hack.
> JSDoc _is_ TypeScript
No. At least, it didn't used to be. JSDoc had its own syntax, but now you can piggyback its format and put TypeScript inside. So now you can write `@type {Record<string, number>}` instead of the "classic" `@type {Object.<string, number>}`, and use some more TypeScript goodies.
You can even kind of use generics with JSDoc, still thanks to TypeScript, but then again... you're not really leaving TypeScript, you'll still have to deal with TS versions, and probably with some of the not-clearly-explained "papercuts" from above.
And finally, I'm not sure that JSDoc+TypeScript is perfectly equivalent to TypeScript. I have a hunch that some of the advanced strategies, e.g. involving `infer` or `extends`, aren't really replicable in JSDoc - or at least I have no clue how to do that in JSDoc - so we'll have to settle for weaker definitions in some cases. So, I'll have to see if it's actually "the same outcome".
I admit I'm no JSDoc guru, so maybe if somebody is compelled to try harder they might actually find a solution for a transition from TypeScript to a completely equivalent alternative. I'm all ears... but surely, if you try too hard the point will be lost.
All of this just to help the Svelte community to contribute - I'll have to take Rich' word for it. For now, it's the only community I've heard that switched from TypeScript in favor of JSDoc. They'll have to deal with a more verbose and less readable codebase for sure, I think there's no doubt about it. Is it really helping the contributors?
It may work for an open source project with a strong governance, maybe. I have a very different experience with projects that decided to use JS instead of TS. Unless we're talking about a very small project, it always turned out to be an ungodly mess.
> it doesn't have to be built to run
If this is a problem, then you have other problems...
Late to this party, wanted to add something here. Wholly agree with your perspective.
The counter-trend to this is the structural-first approach to TS, which eschews return types, and uses mechanisms like the 'satisfies' keyword to ensure that the type evaluates against known symbols, while maintaining the language-server inferred type product in all contexts. The tl;dr goal of this method is to make code that presses compiler-safety at every edge.†
Inversely, the JSDoc method sees you explicitly define everything, and what you save is writing a d.ts file (sometimes). You can pass the TS compiler over it, but it's not going to give you the incremental typing benefit. What you get are a bunch of black boxes with a published contract and a pretend-really-hard approach to typing.
That is frequently fine in cases like libraries. What I worry about is your average dev†† assuming this objectively traction-control-off approach to writing JavaScript approach is good, or rigorous. I don't doubt the svelte team is perfectly capable of writing code in this mode of delivery, and has an armada of tests to back up the proposition. The average dev always opts for easy, and therefore will take to this approach with gusto, but balk at the testing that is necessary to make up for some of the blackbox behavior (blind calls, function internal any, implicit unknown passing that TS would reject, et al) that may not be fully consistent with the behavior the purported type signatures suggest.
†for the sake of argument, I'll define "average dev" as people with a few years of experience still feeling out their place in the industry, and the 9-5 contingent who may or may not own a computer at home and like that paycheck.
††I don't necessarily rep this approach, it's just the other extreme*
JSDoc TS is well documented: https://www.typescriptlang.org/docs/handbook/jsdoc-supported...
It's not 1:1 in features though, but because you can import definitions https://www.typescriptlang.org/docs/handbook/jsdoc-supported... you can use a file a part whenever you encounter any of those advanced features / edge cases current JSDoc does not support.
Like other said, it's still TS after all, and there are escape hatches when needed.
In so many projects I use JSDoc TS, the amount of projects that ended up needing a manual .d.ts file not utomatically generated via `tsc` can be counted in half hand.
Maybe people could give it a try, after all if you comment a method, beside its signature and return types, you can as well just move types in there ;-)
That's an interesting hybrid approach, thanks Andrea.
Is this what Svelte will use? (Asking anybody that knows, of course.)
Anyway, to me the main problem in using TS with libraries is that we have 3-4 major releases per year, and they're just too many. Unless one takes a very restrained approach, releasing very generic (and thus less helpful) types that won't (presumably) break future (or past) versions of TypeScript, we need to release with `typesVersions` targetting n different versions of TypeScript. That's an ever-growing bother indeed for maintainers as time passes.
And I fear the hybrid approach above won't escape this issue. So using "pure" JSDoc or JSDoc with just a sprinkle of TypeScript actually makes sense... But I'd expect this workflow to be winning with smaller projects, and that's why this announcement for Svelte has been surprising to me.