15 ms·
TS to JSDoc Conversion
- antoineMoPa 3y agoWhy would anyone do this?
- rcme 3y ago> As a Svelte compiler developer, debugging without a build step greatly simplifies compiler development. Previously, debugging was complicated by the fact that we had to debug using the build step. In addition, using JSDoc does not affect compiler’s development safety because the type is almost equivalent to TS. > Of course, Svelte developers (not compiler developers) will still be provided type definition files as now, so there will be no change for Svelte developers in terms of typing. Someone who maintains the JS debugger for VS Code added this (in response to a Svelte developers saying they couldn't use a faster compiler due to debugging difficulty): > It's an aside from the main PR, but I'm not entirely sure what you mean here. This should not exclude the ability to use alternative TS compilers--in fact, the js debugger itself is built with esbuild. The debugger should also handle runtime transpilers (like tsx) just fine.
- yid 3y agots-node [1]: am i a joke to you? [1] https://www.npmjs.com/package/ts-node https://www.npmjs.com/package/ts-node
- mattwad 3y agots-node does not play well with ESM modules out of the box. I've started experimenting with tsx but it still has some edge cases of its own. Honestly, ESM has been the bane of my existence this year as packages are slowly starting to migrate, and fixing issues lays on the developer, not any one framework.
- Tade0 3y agoOverall the shift to ESM has been one hell of a dumpster fire. And introducing new extensions like .mjs or .cjs is the smoldering dead raccoon responsible for half of the smell.
- rcarr 3y agoI’ve generally found tsx to be better/less hassle than ts-node https://github.com/esbuild-kit/tsx https://github.com/esbuild-kit/tsx
- jjice 3y agoOh very cool, I'll have to look into this because ts-node can be a pain sometimes. Unfortunate name collision with the TS equivalent of JSX though.
- paiari 3y agoGreat recommendation! I gave tsx a test and found it has a 3x slower boot than my favorite one, tsm[0] (and this is using the native binary at "./node_modules/bin/tsx"). Unfortunately, tsm has much lower download numbers compared to tsx, so I can already see me jumping ship to it due to traction. I usually install tsm locally with "--save-dev" and use "node -r tsm --enable-source-maps <file>.ts" to run what I want. Here on a M1 Pro 32GB the difference between both is 0.17s for tsx and 0.06s for tsm. I urge anyone that haven't tried yet to give tsm a chance. It works great with PM2 if you create a file like "server.pm2.js" and just add at the top of it "require('tsm')" followed by "require('server.ts')". [0] https://www.npmjs.com/package/tsm https://www.npmjs.com/package/tsm
- nailer 3y agots-node is responsible for my favourite error message in all of computing. Yes better than: 'Error: success' or 'keyboard not found: press F1 to continue' > ts-node: Unknown file extension: ts. Someone will reply for a technical reason about this (mentioning .mts or package.json settings or whatever) but that doesn't change the fact that a program whose only job is to run ts files should know what a ts file is. GitHub issue: https://github.com/TypeStrong/ts-node/issues/1967 https://github.com/TypeStrong/ts-node/issues/1967 tsx or @digitak/esrun both work out of the box.
- johnfn 3y agoI'm glad you mentioned this - I had the exact same issue when using ts-node and it really blew my mind.
- maxloh 3y agoWhy don't them just use `tsc --watch`?
- djbusby 3y agoTo keep the benefits of Types w/o the burden of TS.
- merb 3y agowith the difference that typescript generates the types automatically or at least tries to and in JSDoc the user needs to write the JSDoc. Edit, btw: Most complex types in the MR are now completly broken. It's crazy that there is a serious project out there who tries to mix jsdoc and typescript interfaces in the same project. it's like getting bad things from two worlds.
- deleted 3y ago[deleted]
- mxkyb 3y agoIn general, your code is still valid JavaScript and can run in any browser or node environment. Typescript probably is not going to disappear, but if it would, your code wouldn‘t have to change. And you don’t loose your types, because the typescript compiler can interpret jsdoc as if you were using typescript directly.
- _0w8t 3y ago10 years ago I have used Closure compiler from Google, https://github.com/google/closure-compiler/wiki/Annotating-Types https://github.com/google/closure-compiler/wiki/Annotating-T... , as a type checker. We had to use for production a different minimizer, not the closure compiler, but it was extremely useful to check for types and JSDoc-style annotations were very readable with minimal distraction. Flow for JS from Facebook also supports types-as-comments, https://flow.org/en/docs/types/comments/ https://flow.org/en/docs/types/comments/ , but those are rather ugly as one has to intermix them with JS rather than using separated comment block on top.
- ajhenrydev 3y agoTwitter thread about it https://twitter.com/puruvjdev/status/1655813548495486977 https://twitter.com/puruvjdev/status/1655813548495486977
- nickreese 3y agoUsed to be really active in the svelte community and developed my own framework that got broad use. Getting Svelte and TS working together was a constant battle. This is a good decision.
- benmccann 3y agoSvelte will still provide type definitions. We're working on Svelte 4 currently and are taking the opportunity to make a few small breaking changes to the type definitions for improved TypeScript support: https://github.com/sveltejs/svelte/blob/version-4/CHANGELOG.md#unreleased-40 https://github.com/sveltejs/svelte/blob/version-4/CHANGELOG.... We'll cut a preview release soon and would love help testing and feedback from folks that have given it a try.
- ilrwbwrkhv 3y agoyes this is much better. to be able to reach the actual source code which makes a function run is something we have all lost with so many layers in the middle.
- gred 3y agoIt always makes me chuckle when a bunch of non-contributors come out of the woodwork to provide their opinion on a change which will affect them not at all.
- inglor 3y agoFunnily enough it's always stuff that's bikesheddding. I spend months trying to solicit feedback on new experimental stremaing/cancellation APIs in Node and it's silence for a year until people start using it. We say that contributors agreed to list pronouns in the readme or we mention inclusivity and oh-boy do a lot of random people from the internet cares about how the volunteers that write the software they use for free refer to each other internally.
- cjohnson318 3y ago> oh-boy do a lot of random people from the internet cares about how the volunteers that write the software they use for free refer to each other internally Oh boy. If they don't like it, then they don't have to contribute. (Spoiler: none of them are contributing anything.)
- EGreg 3y agoWe also demand that they stop working on any web3 integrations because it’s useless and we dont like it
- rcme 3y agoI think the reason is that the change just sounds so insane at face value that many can't help but comment on it.
- lucasyvas 3y agoIsn't casting with JSDoc impossibly ugly though? The inputs/outputs of a function signature are not the only times a type annotation is needed in TS.
- mirekrusin 3y agoType imports are the worst.
- dTP90pN 3y agoDo you mean native JSDoc namepaths like /** * @type {module:look/here~MyType} */ or TypeScript "JSDoc" imports like /** * @type {typeof import("./look/here").MyType} */ or both?
- mirekrusin 3y agoI meant star type imports or rather lack of it.
- eyelidlessness 3y agoType casting (type assertion, in TS parlance) is incredibly annoying to do in JS/JSDoc. In an ideal world, that would be a distinct advantage because type assertions are typically, or at least should be, considered risky: it’s a brute force way to ignore type errors. In the real world, you might find you have to correct inferred types, sometimes because they’re naively wide (eg, so many DOM interfaces devolve from HTMLElement to Element for no obvious reason!), but also often because they’re overly narrow (eg, so many dynamic collection member accesses completely ignore null safety, again for no obvious reason). In practice, what I’ve found is that the hassle of adding type assertions even if they’re correct nudges me to write worse code (“to appease the type checker”) in JS/Doc than it does in TypeScript syntax. I don’t think TypeScript syntax makes me feel more relaxed about writing unsafe type assertions, but I’m probably an outlier because I pretty much only do that when I’ve exhausted every other available/known approach.
- givemeethekeys 3y agoA bit off-topic (sorry): Is anyone using Svelte in production without SvelteKit? Hows Svelte documentation as of late?
- TehShrike 3y agoI've been using Svelte in production without SvelteKit for around 5 years now. The docs have always been pretty great in my opinion
- arzke 3y agoIs there any reason you wouldn't want to use SvelteKit now that is has reached version 1.0?
- TehShrike 3y agoThe business apps I work on don't benefit from SSR (having to write components that can render server-side is friction without payoff), and I already have a client-side router that supports nesting.
- nerdywordy 3y agoWhat router are you using? One in the svelte ecosystem or a vanilla js router? Also in the process of writing an app that has no ssr needs. There are some minor annoyances with SvelteKit and interested in other options.
- TehShrike 3y agoI'm still using https://github.com/TehShrike/abstract-state-router https://github.com/TehShrike/abstract-state-router which I wrote years ago after thinking "ui-router is great, but I need a version that can keep using no matter what component library I want to use in the future"
- wirahx 3y ago
- endisneigh 3y ago[flagged]
- rich_harris 3y agoappreciate the insightful comment
- rcarr 3y agoIf I remember right, symfony (php framework) has comments that affect how the code runs which as far as I’m concerned means they’re not comments at all but actually code masquerading as comments. Reading about JSDoc gives me the same uneasy feeling, even if it’s not quite the same thing. Edit: Here’s one example, you can define your routes in symfony using comments. Not only that, but it’s actually the officially recommended way of doing things. Absolute madness. https://symfony.com/doc/current/routing.html https://symfony.com/doc/current/routing.html
- kamikaz1k 3y agowhere does it say that JSDoc has runtime implications?
- rcarr 3y agoIt doesn’t and I say in my comment that it is not the same thing. Nevertheless it gives me the same uneasy feeling because you don’t know what features are going to creep into the language further down the road.
- madeofpalk 3y agoIt seems extremley unlikely that Javascript would ever make comments affect the runtime of the language. I'm not sure why there's a fear here why browser vendors/es standards comittees would opt to go down this road?
- masklinn 3y agoYou’re literally not making any sense. JSDoc is like 20 years old and not part of the javascript langage, it’s just a way of formatting some comments such that they’re programmatically process able.
- leoedin 3y agoAre they not using attributes, which start with a #? I thought PHP had C style // comments.
- protonimitate 3y agoFor those that didn't read the thread - this is for the Svelte compiler, not the Svelte library. Users of Svelte will be unaffected and typedefs will still be available.
- _oyks 3y agoFor anyone who is still confused - they're still gonna be using TypeScript in that they will have a tsconfig.json, `allowJS: true, checkJS: true` but they are just writing the files in JS with JSDoc type annotations, they'll still have `.d.ts` files to allow TS developers to use it without issues. Is it contrarian - yes - is it insane - no, not really. Edit: the motivation seems to be to simplify processes - running TS files can be awkward, and cross importing is awkward. fwiw created my own tool for this ([url-redacted])
- echeese 3y agoTS can generate d.ts files from JS files that use JSDoc
- skrebbel 3y agoXNR looks nice! I’m impressed that it can be faster than esbuild-runner, is there a downside?
- _oyks 3y agoI know why it's fast (it doesn't do anything it doesn't need to), but not exactly sure why it's faster than esbuild-runner; presumably it had a higher latency when tested. (and downsides not really, beyond it's pretty fresh so bug reports welcome)
- hn_throwaway_99 3y ago> but they are just writing the files in JS with JSDoc type annotations I think this is the critical piece not everyone understands. Under the covers, it's basically still Typescript (see https://www.typescriptlang.org/docs/handbook/intro-to-js-ts.html#providing-type-hints-in-js-via-jsdoc https://www.typescriptlang.org/docs/handbook/intro-to-js-ts....). The major difference is that type information is specified in comments so that the source file is still valid JS and thus doesn't need a separate compilation step. There is not an exact parity between type info that can be specified with JSDoc and Typescript, but my understanding is that it's pretty close. Any folks familiar with Flow (before Typescript essentially won out), Flow had something similar that was very nice, IMO better because it was the same Flow syntax, just wrapped in comments: https://flow.org/en/docs/types/comments/ https://flow.org/en/docs/types/comments/
- dobladov 3y agoWe do this at my current company for all projects, it does not mean you don't use typescript, you will still validate all your files with TS, but there's no build step, just a check. Very rarely we find a case that we can't cover with JSDoc annotations, and most of the time it means the code could be refactored to be simpler. I do this now for all my personal projects, in my opinion it's simpler, faster and closer to pure JS.
- makapuf 3y agoThis is great but -if I dare - wouldn't it be time to allow js to have type annotations [1] ? As in python, treat it as comments for now but with real syntax and let interesting dialects emerge from the consensus ? I like jsdoc but the syntax is urgh. [1] https://github.com/tc39/proposal-type-annotations https://github.com/tc39/proposal-type-annotations
- herpdyderp 3y agoIt will be impossibly exciting if that proposal happens. I hate build steps, one of the reasons I latched onto JS for my career, but TS is just so good that I had to go full blast with it after using it for the first time.
- Tade0 3y ago> Very rarely we find a case that we can't cover with JSDoc annotations I regret every `infer` statement I've put in application code. Grug phrased this elegantly: https://grugbrain.dev/#grug-on-type-systems https://grugbrain.dev/#grug-on-type-systems
- ripplefringe 3y agoI have never seen grug before. This is fantastic.
- Tade0 3y agoPast elder council with many wise tells: https://news.ycombinator.com/item?id=31840331 https://news.ycombinator.com/item?id=31840331
- porsager 3y agoFinally things are heading in the right direction. Can't wait for more to do this. Typescript might be good for some, but I'm glad to see the hype finally begin to fade, so the rest of up can breathe again.
- 18al 3y agoThe biggest hurdle to using TypeScript is the build step before it can actually be run. If the type annotation TC39 [0] comes to pass this would be largely taken care of; _hype_ waxes. (unfortunately the proposal has been stagnant for more than a year now) A lot of the new frontend codebases involve a build step before running. For such codebases, TypeScript's build hurdle has already been overcome. [0] https://github.com/tc39/proposal-type-annotations https://github.com/tc39/proposal-type-annotations
- joduplessis 3y agoI love pure JS over TS any day, but isn't this using JSDoc in a way it's not meant to be used? Why would you use JSDoc as a JS type framework? Or is the post title a bit misleading...?
- nepeckman 3y agoThe developers providing everyone with free tools are or course welcome to write those tools in whatever languages they want. But to me, the comment definitions are longer to type and more difficult to parse than inline type definitions. I would much rather use one of the quick TS compilers that don't actually type check when I want to make and test a small change to my source code. But to each their own!
- deleted 3y ago[deleted]
- cxr 3y agoIf a person value- TypeScript's inline syntax so much that they disagree with the developers that build steps are a nuisance, then surely they can put in a build step for themselves—one that takes TypeScript syntax as input and then "compiles" it into the equivalent JSDoc so they're never forced to type out those long, long comments. (If this is disagreeable, then your position is a lot less consistent than you think.)
- sdwvit 3y agoJSDoc and Typescript don't have feature parity: OOP that works across files, generics, inline types, etc.
- rich_harris 3y agoThis is a non-issue in practice — complex types can be expressed in .d.ts files and imported. SvelteKit (not Svelte) has been doing this for a long time and it's fine.
- zdragnar 3y agoI wish this were true. I'm currently dealing with three third-party libraries whose types are out of date with the actual code because they do this.
- rich_harris 3y agoIf those libraries were set up correctly, this would cause typechecking to fail.
- eyelidlessness 3y agoIt’s usually a non issue for most normal use cases. Some exceptions are truly maddening though, if you have good reason to use them. One off the top of my head that personally peeved me enough to ragequit one of my side projects: you cannot, as far as I’m aware, define an interface and assign its type to a class (neither its static constructor nor its instance members), without redeclaring every single member type in JSDoc. You can’t (again as far as I’m aware) even define types adjacent to their project-local implementation module and treat them the same way as @types/typeRoots. Both of these would be solvable if you could <reference …/> without polluting global scope, but again that’s a behavior only (again as far as I’m aware) available to dependencies. I’d be thrilled to make the concession to a TypeScript flavor of header/implementation file pairs and skip a build step for huge portions of my work. But I spent way too long trying to figure out how to do it and my only remaining hope that it’s even possible is to wait for the “you don’t know?!” replies. (If it’s not clear here, they’d be very very welcome!)
- Zamicol 3y agoWe are (unfortunately) already doing just JSDoc. Typescript migration was on our road map, but when we dug into it, it didn't solve the biggest issue we had with Javascript, which forces the developer to be aware of various pitfalls. Because of that, we didn't feel that TypeScript solved enough of JavaScript's faults to warrant a migration. I still think that TypeScript is great and has some of the best tooling I've had the pleasure of working with, but in our case we didn't feel that the added complexity was worth the trade off. JSDoc is "good enough", even though we've run into bugs with it on VS Code.
- rcme 3y agoWhat kind of pitfalls are you talking about?
- Zamicol 3y agoDigs through some of my Javascript Twitter rants The latest I ran into, `Object.keys(x).length` appears to recalculate length on every call. There doesn't appear to be a fast (and idiomatic) way to get top level object size in Javascript without using a secondary incrementor.
- hn_throwaway_99 3y agoThis seems like a very odd example in many ways: 1. How on Earth would you expect a type validation library to assist with this example? 2. Looking at that example, I would expect that of course it would need to do work on every call. That is, Object.keys(x) is a function call that takes an object and returns a newly constructed array. So I'm not exactly sure what you would expect to be optimized here. I guess what you are saying is that there is no native `sizeof` operator for Objects, but this doesn't seem like some crazy decision.
- Spivak 3y agoI think the argument is that JSDoc already gives them type validation. If you're going to go the effort of porting to a completely different language and add a compilation step that new language better provide some benefits beyond types like papering over warts like Kotlin does.
- progx 3y agoSveltekit, back to server side rendering. Documentation, with JSDoc back to good old comment/type documentation. Can't wait to see what clock we set the time back at next.
- bilalq 3y agoIt's immediately clear from the very first few lines of the PR that they're sacrificing safety for this. Before: import { Node } from 'acorn'; import * as code_red from 'code-red'; export const parse = (source: string): Node => code_red.parse(source, { sourceType: 'module', ecmaVersion: 13, locations: true }); After: import * as code_red from 'code-red'; /** * @param {string} source * @returns {any} */ export const parse = (source) => code_red.parse(source, { sourceType: 'module', ecmaVersion: 13, locations: true }); But I'm not a Svelte maintainer or user, so if this is their choice, I guess it is what it is. It's not something I'd ever consider. There are other approaches for making linked npm package workflows more manageable. There's the one mentioned by one of the VSCode maintainer, but the simplest setup is to just have a watch process running that recompiles on the fly.
- rich_harris 3y agoYou are making judgements based on a draft PR. There is a ton of work still to do.
- bilalq 3y agoFair enough! I'd love to read a blog post about this after you finish the work. EDIT: It'd be a great outcome in the end if this conversion spurs DX improvements in Node/TS.
- Rapzid 3y ago> There is a ton of work still to do. What's the estimated ROI?
- postalrat 3y agoThat depends on how much you value getting a bunch of developers to think about svelte, jsdoc, and typescript.
- myvoiceismypass 3y agoMaybe I am unfamiliar with jsdoc, or what the shape of Node from acorn is, but yeah if every function is returning any, that seems like a big downgrade and sacrifice.
- zoogeny 3y agoA decent expanded explanation of why in this YouTube video: https://www.youtube.com/watch?v=MJHO6FSioPI&ab_channel=SvelteSociety https://www.youtube.com/watch?v=MJHO6FSioPI&ab_channel=Svelt...
- rich_harris 3y agoLordy, I did not expect an internal refactoring PR to end up #1 on Hacker News. Let me provide some context, since a lot of people make a lot of assumptions whenever this stuff comes up! If you're rabidly anti-TypeScript and think that us doing this vindicates your position, I'm about to disappoint you. If you're rabidly pro-TypeScript and think we're a bunch of luddite numpties, I'm about to disappoint you as well. Firstly: we are not abandoning type safety or anything daft like that — we're just moving type declarations from .ts files to .js files with JSDoc annotations. As a user of Svelte, this won't affect your ability to use TypeScript with Svelte at all — functions exported from Svelte will still have all the same benefits of TypeScript that you're used to (typechecking, intellisense, inline documentation etc). Our commitment to TypeScript is stronger than ever (for an example of this, see https://svelte.dev/blog/zero-config-type-safety https://svelte.dev/blog/zero-config-type-safety). I _would_ say that this will result in no changes that are observable to users of the framework, but that's not quite true — it will result in smaller packages (no need to ship giant sourcemaps etc), and you'll be able to e.g. debug the framework by cmd-clicking on functions you import from `svelte` and its subpackages (instead of taking you to an unhelpful type declaration, it will take you to the actual source, which you'll be able to edit right inside `node_modules` to see changes happen). I expect this to lower the bar to contributing to the framework quite substantially, since you'll no longer need to a) figure out how to link the repo, b) run our build process in watch mode, and c) understand the mapping between source and dist code in order to see changes. So this will ultimately benefit our users and contributors. But it will also benefit _us_, since we're often testing changes to the source code against sandbox projects, and this workflow is drastically nicer than dealing with build steps. We also eliminate an entire class of annoying papercuts that will be familiar to anyone who has worked with the uneven landscape of TypeScript tooling. The downside is that writing types in JSDoc isn't quite as nice as writing in TypeScript. It's a relatively small price to pay (though opinions on this do differ among the team - this is a regular source of lively debate). We're doing this for practical reasons, not ideological ones — we've been building SvelteKit (as opposed to Svelte) this way for a long time and it's been miraculous for productivity.
- benmccann 3y agoI was skeptical at first when we made the change in SvelteKit. However, SvelteKit has a large integration test suite and being able to change the code and rerun the tests against the real final version of the code without waiting for any build step to complete has been a big improvement to productivity and I'm now a big fan of having made the change there. The tradeoff may be a bit different in Svelte core where we have more unit tests and fewer integration tests, so we're still investigating and considering the change, but we do have experience with both approaches and at the end of the day great software can be built using either approach.
- riogordo2go 3y agoI remember not using/trying Svelte because there was no TS support and it took quite some time before TS support emerged. With that in mind it doesn't surprise me they are not doubling down on TypeScript.
- npretto 3y agothis has nothing to do with "TS support" at all.
- brundolf 3y ago*Svelte compiler. Users of Svelte are unaffected I don't know the details of their situation, but I definitely can relate to the build step being a huge pain in the butt for Node projects. It's why I've stopped using Node whenever I can afford to, in favor of Deno (or maybe one day Bun). I used Deno to build a compiler for a personal language project recently, and it was an absolute delight not having to deal with any of Node's BS. Assuming they can't afford to migrate runtimes at this stage, I definitely get why they'd explore other options
- kabes 3y agoI don't care what svelte does, but I've maintained projects with jsdoc types and projects using ts directly and IMO using jsdoc tends to be more of a hassle to maintain, had worse ide guidance and in general felt just more cumbersome. Being able to click through to the implementation in your ide is nice though, but can be solved by the ide.
- cxr 3y agoSynthesizing the JSDoc-formatted type information into a TypeScript-like syntax for those who prefer it can also be solved by the IDE.
- jgalentine007 3y agoAs someone who has had a large project go from TypeScript -> TS/JsDoc -> back to TypeScript... I was NOT a fan of trying to use JsDoc for types.
- redbar0n 3y ago..and why was that?
- bottlepalm 3y agoWow so much overhead, but I can see why if the problem is trying to step into some npm package code - landing on a type definition file is not helpful It makes you think why can't the TS compiler produce JS code with JSDoc annotations instead of source maps. Ship the node packages with that so that debugging into the framework is seamless and easy to edit.
- POiNTx 3y agoLittle side note, I'm always in awe of the amount of crap open source developers have to take from the community vs the crazy amount of value they offer. There's a lot of backlash on something 99% of commenters will never have to interact with. A lot of knee jerk reactions without trying to understand what's going on. And in return projects like Svelte offer an insane amount of value for people and businesses. Thankless work. Nowadays it's expected that you get software for free, and if you don't like it you have the moral right to complain at insane lengths at the maintainers of this software. Even if you don't agree with certain decisions (which in this case shouldn't even be the case), there's a way of going about things, you're dealing with people, not faceless corporations.
- frankjr 3y agoWouldn't it be nice if all runtimes and browsers had native support for TS and you could just skip the entire transpiling and source mapping step? Oh, well.
- nightski 3y agoOr better yet WASM was a first class citizen and we could abandon JS once and for all.
- pjmlp 3y agoBasically this is akin to using C like coding with a C++ compiler, from the looks of it.
- ojr 3y agoI still feel vindicated, you don't need Typescript to write type definitions and also type safety on the server/api can be done with Graphql and writing gql
- ptrwis 3y agoRegardless of how it ends, it will be a very valuable experience for the entire JS community.