Repository navigation
Implement a JSDoc @import tag #22160
Description
Background
#22158 tracks referencing types from a given module using JSDoc-style namepaths. Given that the syntax is somewhat unintuitive and predates the concept of ECMAScript modules, we would like to support a more ergonomic form if we feel it would be helpful.
Options
Bikeshedding time. 🚲 🏠
@from @import
/**
* @from "express"
* @import { Request, Response as CoolResponse } from
* @import Default
* @import * as ns
*/Pros
- Allowing
@fromto precede named import clauses would be easier for completions (this is one of our oldest-duped requests Request for alternative import syntax to improve auto-complete experience #2371) - Can have multiple
importclauses - Could hypothetically support
@frombefore@importand vice versa.
Cons
- Doesn't totally look like ESModule syntax which is just extra cognitive overhead.
ECMAScript Import-based
/**
* @import { x, y as z, default as Default } from "express"
*/Pros
- Nothing to learn if you already know ECMAScript syntax.
Cons
- Less optimal for completions
Issues with the Above
The options above don't make it explicit that only types are being imported. We could play around with keyword/tag placement (e.g. @importtype, @import type, etc.)
Reacted by Robert Knight, Saturn, Andrei Kazakou, ClementVidal, stephen, Jesse Niininen, igor-sky, Jan Stoots, Esteban Echeverry, Noj Vek and 86 more
Reacted by stephen, Noj Vek, Nicu Chiciuc, majo44, Gabriel Lima and Robin Röper
Reacted by stephen, Noj Vek, Nicu Chiciuc, majo44, SebastianMC, Marek Krajčovič, Gabriel Lima, ExE Boss, Robin Röper, Jake Verbaten and 5 more
Reacted by Nicu Chiciuc, Robin Röper, Michał Drobniak and Matteo Ronchi
Reacted by Jayden Seric and Christian Rondeau
Activity
aozgaa commentedon Feb 26, 2018
This was previously discussed in #14377
DanielRosenwasser commentedon Mar 9, 2018
We're going to hold off on any new JSDoc syntax, and wait for more feedback here. As per #22445, our current recommendation is to wait on #14844 and then use
mhegazy commentedon Mar 9, 2018
closing in favor of #14844
hybrist commentedon May 7, 2018
Daniel Rosenwasser (@DanielRosenwasser) Did the syntax for module namespaces change? I tried scanning through the linked issues but since none of them are showing the JSDoc equivalent, it's somewhat hard to follow.
mhegazy commentedon May 7, 2018
Use
typeof:/** @typedef {typeof import('http')} http*/30 remaining items
nanxiaobei commentedon Feb 28, 2021
Hope to use JSDoc syntax to import typescript definition to *.js file.
jeffersoneagley commentedon Apr 14, 2021
Robin Blomberg (@RobinBlomberg) I actually define mine in types.d.ts files around the app now and they basically give every js file in the directory the ability to access types defined in pure TS (don't use any import statements other than inline though, top-of-file imports will turn the type file into a module and then you can't easily import it into js)
RobinBlomberg commentedon Apr 24, 2021
Jefferson Eagley (@jeffersoneagley) Genius! I'll have to try this.
Fix Viewer API definitions and include in CI
NemoStein commentedon Jul 11, 2022
It seems that this issue will never reach a proper conclusion, but this is blocking #46011.
We need a way of opting out of
@typedefauto exporting the type!/** @import { Type } from './path/to/module.js' */would be, IMO, the perfect solution, but something else is needed if this isn't possible.Fix Viewer API definitions and include in CI
jespertheend commentedon Jan 26, 2023
These are snippets of some of my real world code 🥲
What can I say, it is what it is. I still prefer this rather than having to deal with a build step and import maps though.
DanielRosenwasser commentedon Mar 26, 2024
Thanks to Oleksandr Tarasiuk (@a-tarasyuk), this should be in the next nightly release and in TypeScript 5.5. The syntax is based on ECMAScript imports:
waynesbrain commentedon Oct 16, 2024
I can't get
@importOR@typedef {import()}working in my.tsfiles here in my project which I just upgraded to TS 5.6.3 - https://github.com/jrfso/jrfs/blob/7297019eee352bece45e3df5aac1c7bc4a257e03/packages/core/src/types.ts#L6If I create a
.jsthough, this works/** @import { FileTree } from "@/FileTree" */and I've tried all variations in.tsfiles includingfrom "./FileTree".I would bet that it's some type of eslint configuration issue but I cannot find any working advice surrounding this topic.
waynesbrain commentedon Oct 17, 2024
Turadg Aleahmad (@turadg) Any advice? Am I doing it wrong? (Sorry!) EDIT: Maybe you were reacting to my commenting here at all... Idk, the tag said "Awaiting feedback". However, I wish they would enable discussions here because StackOverflow isn't a great option anymore IMO.
jespertheend commentedon Oct 17, 2024
Wayne Sbrain (@waynesbrain) I believe the
@importtag only works in.jsfiles. In.tsfiles you can use TypeScript syntax like so:waynesbrain commentedon Oct 17, 2024
Thanks Jesper van den Ende (@jespertheend) - I see now that the docs aren’t explicit that you can only do this in a JavaScript file, but it’s the only type of file that’s mentioned.
I wish they would have implemented it in TS because if I import this type just for documentation using the TS syntax then I get errors for having an unused import.
UPDATE: So, I guess the answer for intermodule-y documenting TypeScript
.tsfiles is that I have to install and configure eslint-plugin-jsdoc ~ typescript-eslint/typescript-eslint#8258 ~ ok, but 🤮 I'll have to keep looking.