Implement a JSDoc @import tag

[DanielRosenwasser]

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 @from to 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 import clauses
• Could hypothetically support @from before @import and 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.)

[aozgaa]

This was previously discussed in #14377

[DanielRosenwasser]

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

/**
 * @typedef {import("express")} express
 */

[mhegazy]

closing in favor of #14844

[jkrems]

@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.

/**
 * The following works using latest typescript@next (2.9.0-dev.20180506):
 *
 * @typedef {import('http').IncomingMessage} IncomingMessage
 * @typedef {import('http').ServerResponse} ServerResponse
 *
 * But this fails:
 *
 * > Module 'http' does not refer to a type, but is used as a type here.
 *
 * @typedef {import('http')} http
 */

[mhegazy]

Use typeof:

/** @typedef {typeof import('http')} http*/

[nojvek]

Hi Typescript Magic Elves,

Do you think you'll be able to get any decisions on what the final DRY-er jsdoc import syntax will look like?

Just curious what the blocking items are?

[DanielRosenwasser]

The original motivation to not do this was to just re-use as much well-understood JSDoc as we could. If we can get more feedback, I think it will be a strong enough signal that there's interest and that we should actually invest in the feature.

[nojvek]

I hope this doesn’t get stuck in analysis paralysis fever like some of the other issues.

I am Typescript js-doccing a medium sized project and this is a pretty painful experience. It feels like a very subpar experience to TS.

[nojvek]

Kind ping to typescript authors and @DanielRosenwasser . Has any decision been regarding this?

Using tsc as a typechecker for js with a verbose syntax like this adds up quite a bit of friction.

[bmeck]

Just want to note the workaround in #22160 (comment) seems to drop the documentation of the type:

/**
 * This is documented
 * @typedef {{foo:'bar'}} Foo
 */

/**
 * @typedef {import('foo').Foo} Foo
 */
// Foo does not have a description

[ExE-Boss]

Also, #22160 (comment) doesn’t support optional type parameters.

[jeffersoneagley]

Any updates on this? I'm still importing things at the top of the file, but CRA of course complains in the preflight.

[noinkling]

I've resorted to adding export as namespace foo to my .d.ts modules. It makes the namespace globally available which isn't ideal, but it's the only way I can find (assuming we don't want to import actual code) to avoid repeated import(...) spam, since there doesn't seem to be any way to alias a namespace within JSDoc that works (which I've previously commented on in another issue: #14233 (comment)).

[RobinBlomberg]

@jeffersoneagley I had great success with approach #1, and I found a way to make it interoperable with normal .js/.ts files inside ESM modules. This approach takes advantage of how TypeScript appears to merge file extensions if the filenames are the same.

my-module.ts

export type FooString = 'foo' | 'bar' | 'baz';

export type FooObject = { foo: FooString; };

my-module.js

/**
 * @file Dummy export in order to avoid a runtime ERR_MODULE_NOT_FOUND error.
 */

export {};

index.js

import * as MyModule from './my-module.js';

/**
 * @param {MyModule.FooString} fooString
 * @return {MyModule.FooObject}
 */
export const createFooObject = (fooString) => {
  return { foo: fooString };
};

Now it seems a bit silly to have to create a dummy export file every time, but in my case, I need to define and import 100+ namespaced types, and I really haven't found any other reasonable way to do it.

[nanxiaobei]

Hope to use JSDoc syntax to import typescript definition to *.js file.

[jeffersoneagley]

@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]

@jeffersoneagley Genius! I'll have to try this.

[NemoStein]

It seems that this issue will never reach a proper conclusion, but this is blocking #46011.
We need a way of opting out of @typedef auto 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.

[jespertheend]

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]

Thanks to @a-tarasyuk, this should be in the next nightly release and in TypeScript 5.5. The syntax is based on ECMAScript imports:

/**
 * @import * as foo from "some-module-path"
 */

/**
 * @import { x, y as z, default as Default } from "another-module-path"
 */

[waynesbrain]

I can't get @import OR @typedef {import()} working in my .ts files 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#L6

If I create a .js though, this works /** @import { FileTree } from "@/FileTree" */ and I've tried all variations in .ts files including from "./FileTree".

I would bet that it's some type of eslint configuration issue but I cannot find any working advice surrounding this topic.

[waynesbrain]

@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]

@waynesbrain I believe the @import tag only works in .js files. In .ts files you can use TypeScript syntax like so:

import type { FileTree } from "@/FileTree";

[waynesbrain]

Thanks @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 .ts files is that I have to install and configure eslint-plugin-jsdoc ~ typescript-eslint/typescript-eslint#8258 ~ ok, but 🤮 I'll have to keep looking.