feat(41825): JSDoc equivalent of import * #57207

a-tarasyuk · 2024-01-28T22:39:09Z

Fixes #22160
Fixes #41825
Fixes #41825 (comment)

typescript-bot · 2024-01-28T22:39:20Z

Looks like you're introducing a change to the public API surface area. If this includes breaking changes, please document them on our wiki's API Breaking Changes page.

Also, please make sure @DanielRosenwasser and @RyanCavanaugh are aware of the changes, just as a heads up.

src/compiler/parser.ts

DanielRosenwasser · 2024-01-31T21:41:13Z

@typescript-bot pack this

typescript-bot · 2024-01-31T21:41:16Z

Heya @DanielRosenwasser, I've started to run the tarball bundle task on this PR at 0a20ad3. You can monitor the build here.

typescript-bot · 2024-01-31T21:42:54Z

Hey @DanielRosenwasser, I've packed this into an installable tgz. You can install it for testing by referencing it in your package.json like so:

{
    "devDependencies": {
        "typescript": "https://typescript.visualstudio.com/cf7ac146-d525-443c-b23c-0d58337efebc/_apis/build/builds/159723/artifacts?artifactName=tgz&fileId=D02528D51446E4533EE8387E4D86BA71B3A7D3FC035CD42935DA2197A5F1290D02&fileName=/typescript-5.4.0-insiders.20240131.tgz"
    }
}

and then running npm install.

There is also a playground for this build and an npm module you can use via "typescript": "npm:@typescript-deploys/pr-build@5.4.0-pr-57207-3".;

DanielRosenwasser · 2024-01-31T22:23:50Z

Something we should test

/**
 * @importType
 * as Foo from "foo"
 */

and

/**
 * @importType {
 *   A,
 *   B,
 *   C,
 * } from "foo"
 */

DanielRosenwasser · 2024-01-31T23:14:03Z

In our design meeting, I brought up some of the discussion on Twitter around the tag name.

I think the team is up for just calling it @import.

Something that came up was the use of type modifiers on import specifiers.

/**
 * @import { type Foo } from "foo"
 */

The preference was to disallow them for now, even though it might make copy/pasting from TS to JS easier. The idea was can always relax that restriction.

Another two things that I do want us to test:

Auto-imports - whether it works, where they get inserted in an import list, etc.
Declaration file generation - precisely how a /** @import */ comment translates into a TS import within a .d.ts file.

As raised above, multi-line should just work:

/**
 * @import {
 *   A,
 *   B,
 *   C,
 * } from "foo"
 */

However, I don't know exactly how this should be handled, and I am curious to hear thoughts from @sandersn (who can also help out with where the leading * logic lives in our JSDoc implementation).

/**
 * @import
 * as Foo from "foo"
 ^
 what is this?
 */

As I write this up, it really makes me realize like the devil is in the details. 😅

a-tarasyuk · 2024-02-01T00:09:32Z

As raised above, multi-line should just work:

/**
 * @import {
 *   A,
 *   B,
 *   C,
 * } from "foo"
 */

@DanielRosenwasser I think the scanner can handle this case. However, I think we need to change the naming for this option :).

TypeScript/src/compiler/scanner.ts

Line 1062 in 821b1d8

setInJSDocType,

TypeScript/src/compiler/scanner.ts

Lines 1922 to 1926 in 821b1d8

    
           if (inJSDocType && !asteriskSeen && (tokenFlags & TokenFlags.PrecedingLineBreak)) { 
        
               // decoration at the start of a JSDoc comment line 
        
               asteriskSeen = true; 
        
               continue; 
        
           }

a-tarasyuk · 2024-02-02T20:48:47Z

Auto-imports - whether it works, where they get inserted in an import list, etc.

@DanielRosenwasser The existing auto-import logic will add @param { import("./a").A } for the following case., Should we consider changing this logic to use @import?

// @Filename: /a.ts
export default interface A { }

// @Filename: /test.js
/**
 * @param { A/**/ } a
 */
export function f(a) { }

a-tarasyuk · 2024-02-06T01:04:41Z

/**
 * @import
 * as Foo from "foo"
 ^
 what is this?
 */

@DanielRosenwasser It's a tricky case because the first * in the JSDoc is a decoration. So, if we handle import tag like other tags, the correct way to use multiline import * should be...

/**
 * @import
 * * as Foo from "foo"
 */

DanielRosenwasser · 2024-02-06T23:24:42Z

Should we consider changing this logic to use @import?

I would say so - however, in the interest of keeping this PR smaller, you might want to do a follow-up PR instead. @andrewbranch might have thoughts here.

Regarding the ambiguity with *, I am okay with either decision. My suggestion is to say that the next token following a JSDoc import has to occur on the same line. @sandersn might have thoughts here.

a-tarasyuk · 2024-02-07T15:57:31Z

Declaration file generation - precisely how a /** @import */ comment translates into a TS import within a .d.ts file.

@DanielRosenwasser These imports are currently transformed into ImportTypeNode ({import("./types").A}). Is it better to translate import tags as top-level declarations within the checker?

TypeScript/src/compiler/transformers/declarations.ts

Line 440 in c790dc1

    
           const result = resolver.getDeclarationStatementsForSourceFile(sourceFile, declarationEmitNodeBuilderFlags, symbolTracker, bundled);

andrewbranch · 2024-02-07T18:39:27Z

Since these have type-only import semantics in JSDoc, I would have assumed they would translate to type-only import declarations in the .d.ts file. I’m not sure it actually matters though.

We have to remember that JS-based declaration emit works completely differently from TS-based declaration emit—instead of walking the source file, it walks the symbol table and just synthesizes types for stuff. So as far as the declaration emitter is concerned, this feature really changes nothing. It’s just one more way to give visible symbols a type, but the declaration emitter already doesn’t know or care how anything got its type when working from JS.

sandersn

Not done reviewing, but I found that I wrote some requests for tests last time I looked at this and forgot to post them.

src/compiler/parser.ts

src/compiler/transformers/declarations.ts

src/services/completions.ts

src/services/refactors/convertImport.ts

src/services/stringCompletions.ts

sandersn · 2024-02-07T23:13:20Z

Regarding the ambiguity with *, I am okay with either decision. My suggestion is to say that the next token following a JSDoc import has to occur on the same line. @sandersn might have thoughts here.

I'm also OK with any decision, and I think strict no-newline one is a good place to start except that it would require special-casing parseTag, which currently uses

const tagName = parseJSDocIdentifierName(/*message*/ undefined);
const indentText = skipWhitespaceOrAsterisk();

So I'd personally leave it as interpreting a leading asterisk as decoration:

/**
 * @import
 * { foo, bar }
 * from "multiline.js"
 */

equivalent to import { foo, bar } from 'multiline.js'. I don't think it's worth any additional code. Just test that

/**
 * @import
 * * as multiline from 'multiline.js'
 */

works.

…eat/41825

weswigham

I think this is fine? @andrewbranch should give the type-only behavior a once-over, though.

andrewbranch · 2024-03-26T18:12:02Z

I was skimming for a test like this and I didn’t see one, so let me know if I missed it:

// @declaration: true
// @emitDeclarationOnly: true
// @checkJs: true
// @allowJs: true

// @filename: 0.ts
export default interface Foo {}
export interface I {}

// @filename: 1.js
/** @import Foo, { I } from './0' */

/**
 * @param {Foo} a
 * @param {I} b
 */
export function foo(a, b) {}

Is this input syntax valid, and does it emit valid declaration file syntax? The input syntax should be valid in my opinion, but if it wasn’t handled specifically, it may emit invalid syntax on the output:

import type Foo, { I } from './0';
//     ^^^^^^^^^^^^^^^
// A type-only import can specify a default import or named bindings, but not both.(1363)

…eat/41825

See microsoft/TypeScript#57207

bcomnes · 2024-06-04T23:02:52Z

I love this feature! I've noticed though, that if you import a type with the new syntax, and then only use that type inside of another typedef (used or unused in the js file), you get a ts6133 "is declared but its value is never read." warning, despite the imported type resolving and the new typedef being declared properly. It only counts read state when something is assigned the type directly.

andrewbranch · 2024-06-05T16:15:33Z

@bcomnes I can't reproduce that behavior; here's my attempt in the playground: https://www.typescriptlang.org/play/?noUnusedLocals=true&ts=5.6.0-dev.20240605&filetype=js#code/PTAEAEDsHsFVIK4GcCmATAMtAxgQwDZIBcoALgE4IoCwAUHQJYC2ADtOaaAEQBmSXAbjp1gAKlERmbDqADeoAOrkGpFADEG+FAHkWpBtEhJQAX1A9y0Jtz5dQo4MNohQ8bFaYpI+yAHNzDAAeKMakABYooCjkluQiYGIS4KQAnizoKDxySirqmjp6BkZmCmra9sBAA

If you can show an example, could you open a new issue? Thanks!

bcomnes · 2024-06-05T22:20:36Z

Hrmmm you are right. I'm having a hard time coming up with a minimal reproducible example. I think it may be related to cycles in the type import, but also related to usage of the cycling type. I'll report back if I can pin it down.

acidoxee · 2024-06-21T07:17:24Z

My apologies if this has already been discussed, but it seems the new @import syntax doesn't support import attributes, especially the resolution-mode one that enables @typedef to resolve imports correctly regardless of the type of module being used.

For additional details, my codebase is mostly ESM, but some parts still have to be CJS for compatibility reasons with "old" tools. In those CJS parts, I previously imported types from the ESM part like this:

/** @typedef {import('../path/to/some/ESModule.js', { with: { 'resolution-mode': 'import' } }).MyType} MyType */

I have tried migrating to the new @import tag with an equivalent syntax, but it seems the import attribute is being ignored:

/** @import {MyType} from '../path/to/some/ESModule.js' with { 'resolution-mode': 'import' } */

Using the above syntax yields this error message:

The current file is a CommonJS module whose imports will produce 'require' calls; however, the referenced file is an ECMAScript module and cannot be imported with 'require'. Consider writing a dynamic 'import("../path/to/some/ESModule.js")' call instead.
To convert this file to an ECMAScript module, change its file extension to '.mjs', or add the field "type": "module" to '/CJSpart/package.json'. ts(1479)

Am I wrong, or is this simply not available yet for @import? Thanks 🙏

a-tarasyuk · 2024-06-21T08:01:24Z

@acidoxee Can you create a new issue? I'll take a look at it.

acidoxee · 2024-06-21T10:01:58Z

Sure @a-tarasyuk, here you go! #58955
I hope the format of the issue is OK, I couldn't create a TS playground with several files because of #52666.

zheung · 2024-06-22T10:42:38Z

@bcomnes I can't reproduce that behavior; here's my attempt in the playground: https://www.typescriptlang.org/play/?noUnusedLocals=true&ts=5.6.0-dev.20240605&filetype=js#code/PTAEAEDsHsFVIK4GcCmATAMtAxgQwDZIBcoALgE4IoCwAUHQJYC2ADtOaaAEQBmSXAbjp1gAKlERmbDqADeoAOrkGpFADEG+FAHkWpBtEhJQAX1A9y0Jtz5dQo4MNohQ8bFaYpI+yAHNzDAAeKMakABYooCjkluQiYGIS4KQAnizoKDxySirqmjp6BkZmCmra9sBAA

If you can show an example, could you open a new issue? Thanks!

@andrewbranch maybe i can reproduce this with my case:

Version: 1.91.0-insider
Commit: 4bbebd8
Date: 2024-06-21T03:34:42.273Z
Browser: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Code-Insiders/1.91.0-insider Chrome/122.0.6261.156 Electron/29.4.0 Safari/537.36

types.d.ts

export type TestType = {
	route: string;
	method?: string | undefined;
	handle: Function;
	upload?: boolean | undefined;
	option?: Object | undefined;
};

test1.js

/** @import { TestType } from './types.d.ts' */

export default async function doSomething() {
	/** @type {TestType[]} */
	const types = [];

	return types;
}

test2.js

/** @import { TestType } from './types.d.ts' */

export default {
	/** @type {TestType[]} */
	types: []
};

update1: reproduce on playground:
https://www.typescriptlang.org/play/?noUnusedLocals=true&ts=5.6.0-dev.20240605&filetype=js#code/PTAEAEDsHsFVIK4GcCmATAMtAxgQwDZIBcoALgE4IoCwAUHQJYC2ADtOaaAEQBmSXAbjp1gAKlERmbDqADeoAOrkGpFADEG+FAHkWpBtEhJQAX1A9y0Jtz5dQo4MNohQ8bFaYpI+yAHNzDAAeKMakABYooCjkluQiYCiB0pxoKDy4CPicsvGgAJBiEuCkAJ4skbJKKuqaOnoGRgDaALpmDrl5peXEoC25JkL0tInJoKnpmZy4SCWQ2OYIc-qGY9AAylYo4Qx+ABQAlHJ0BeIQXRVVqhpaustNrfaOtHnuRpznxgC8vc2Dx+RbBDkSBkMohQYmIA

update2:
i fount it only work when @import before true import, nah after true import or without true import

zheung · 2024-06-23T03:42:16Z

For the same project as above, I found another problem: tsc doesn't seem to recognize types imported via @import correctly.

jbeaudoin11 · 2024-07-03T18:56:24Z

Hi guys, not sure if i should simply open an issue instead of writing here but is it me or it's not possible to just import all ?

/** @import * from "./types.ts" */

DanielRosenwasser · 2024-07-03T19:49:28Z

In general it's not best practice to comment on a closed PR or issue since people stop following as often, and creates noise in the conversation.

To answer your question, you have to create a name for the import:

/** @import * as myTypes from "./types.ts" */
//            ^^^^^^^^^^

JavaScript/TypeScript doesn't support an "import all the things from this module into the current scope" sort of import statement.

jbeaudoin11 · 2024-07-03T20:58:05Z

Alright, i'm really confused, i swear i used to do this all the time before ESM was a thing but maybe i'm wrong...
Maybe i assumed we could do it since we can do it with export 🤷‍♂️
Thanks !

feat(41825): add importType jsdoc tag

953e54b

add jsdocImportTypeTag parsing tests

b67cba6

jakebailey mentioned this pull request Jan 29, 2024

enable @typescript-eslint/no-unused-vars #57123

Merged

a-tarasyuk added 2 commits January 29, 2024 19:57

update baseline

fc4ac15

add jsdoc import type tag go to definition tests

df23ce3

DanielRosenwasser reviewed Jan 29, 2024

View reviewed changes

src/compiler/parser.ts Show resolved Hide resolved

jsdoc import type completions

0b0029d

a-tarasyuk force-pushed the feat/41825 branch from db6bd73 to 0b0029d Compare January 30, 2024 15:35

jsdoc import type find-all-refs/rename

0a20ad3

a-tarasyuk added 2 commits February 1, 2024 01:58

rename importType to import

386120f

add tests

08806b6

a-tarasyuk added 2 commits February 1, 2024 23:45

auto import fix to existing jsdoc imports

d629693

cleanup

6ec3b27

a-tarasyuk added 2 commits February 4, 2024 00:42

handle multiline import clause

ad24624

add tests

26f633f

cleanup

82f79be

sandersn reviewed Feb 7, 2024

View reviewed changes

a-tarasyuk requested a review from weswigham March 18, 2024 22:20

a-tarasyuk added 3 commits March 19, 2024 01:16

Merge branch 'main' of https://github.com/microsoft/TypeScript into f…

aa9600d

…eat/41825

Merge branch 'main' of https://github.com/microsoft/TypeScript into f…

32bbf4c

…eat/41825

Merge branch 'main' of https://github.com/microsoft/TypeScript into f…

0da4e23

…eat/41825

weswigham approved these changes Mar 22, 2024

View reviewed changes

a-tarasyuk added 2 commits March 26, 2024 22:10

Merge branch 'main' of https://github.com/microsoft/TypeScript into f…

51f902e

…eat/41825

add tests

653955e

sandersn approved these changes Mar 26, 2024

View reviewed changes

andrewbranch approved these changes Mar 26, 2024

View reviewed changes

sandersn merged commit 2de69b0 into microsoft:main Mar 26, 2024
25 checks passed

turadg mentioned this pull request Mar 27, 2024

support @import from TypeScript 5.5 gajus/eslint-plugin-jsdoc#1218

Closed

timocov added a commit to timocov/dts-bundle-generator that referenced this pull request Apr 1, 2024

Make it compile-able with latest typescript version (again)

34a18af

See microsoft/TypeScript#57207

lishaduck mentioned this pull request Jun 22, 2024

@imports marked as unused #58969

Closed

DanielRosenwasser mentioned this pull request Jul 11, 2024

TypeScript 5.6 Iteration Plan #59250

Open

pokey mentioned this pull request Jul 18, 2024

Switch to docstring imports for things we import only for docstrings cursorless-dev/cursorless#2531

Open

natsuki-engr mentioned this pull request Oct 17, 2024

TS starts to supporting @import statement alexharri/website#9

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(41825): JSDoc equivalent of import * #57207

feat(41825): JSDoc equivalent of import * #57207

a-tarasyuk commented Jan 28, 2024 •

edited by DanielRosenwasser

Loading

typescript-bot commented Jan 28, 2024

DanielRosenwasser commented Jan 31, 2024

typescript-bot commented Jan 31, 2024 •

edited

Loading

typescript-bot commented Jan 31, 2024 •

edited

Loading

DanielRosenwasser commented Jan 31, 2024 •

edited

Loading

DanielRosenwasser commented Jan 31, 2024 •

edited

Loading

a-tarasyuk commented Feb 1, 2024 •

edited

Loading

a-tarasyuk commented Feb 2, 2024

a-tarasyuk commented Feb 6, 2024 •

edited

Loading

DanielRosenwasser commented Feb 6, 2024 •

edited

Loading

a-tarasyuk commented Feb 7, 2024

andrewbranch commented Feb 7, 2024 •

edited

Loading

sandersn left a comment

sandersn commented Feb 7, 2024

weswigham left a comment

andrewbranch commented Mar 26, 2024

bcomnes commented Jun 4, 2024

andrewbranch commented Jun 5, 2024

bcomnes commented Jun 5, 2024 •

edited

Loading

acidoxee commented Jun 21, 2024

a-tarasyuk commented Jun 21, 2024

acidoxee commented Jun 21, 2024

zheung commented Jun 22, 2024 •

edited

Loading

zheung commented Jun 23, 2024

jbeaudoin11 commented Jul 3, 2024

DanielRosenwasser commented Jul 3, 2024

jbeaudoin11 commented Jul 3, 2024

feat(41825): JSDoc equivalent of import * #57207

feat(41825): JSDoc equivalent of import * #57207

Conversation

a-tarasyuk commented Jan 28, 2024 • edited by DanielRosenwasser Loading

typescript-bot commented Jan 28, 2024

DanielRosenwasser commented Jan 31, 2024

typescript-bot commented Jan 31, 2024 • edited Loading

typescript-bot commented Jan 31, 2024 • edited Loading

DanielRosenwasser commented Jan 31, 2024 • edited Loading

DanielRosenwasser commented Jan 31, 2024 • edited Loading

a-tarasyuk commented Feb 1, 2024 • edited Loading

a-tarasyuk commented Feb 2, 2024

a-tarasyuk commented Feb 6, 2024 • edited Loading

DanielRosenwasser commented Feb 6, 2024 • edited Loading

a-tarasyuk commented Feb 7, 2024

andrewbranch commented Feb 7, 2024 • edited Loading

sandersn left a comment

Choose a reason for hiding this comment

sandersn commented Feb 7, 2024

weswigham left a comment

Choose a reason for hiding this comment

andrewbranch commented Mar 26, 2024

bcomnes commented Jun 4, 2024

andrewbranch commented Jun 5, 2024

bcomnes commented Jun 5, 2024 • edited Loading

acidoxee commented Jun 21, 2024

a-tarasyuk commented Jun 21, 2024

acidoxee commented Jun 21, 2024

zheung commented Jun 22, 2024 • edited Loading

zheung commented Jun 23, 2024

jbeaudoin11 commented Jul 3, 2024

DanielRosenwasser commented Jul 3, 2024

jbeaudoin11 commented Jul 3, 2024

a-tarasyuk commented Jan 28, 2024 •

edited by DanielRosenwasser

Loading

typescript-bot commented Jan 31, 2024 •

edited

Loading

typescript-bot commented Jan 31, 2024 •

edited

Loading

DanielRosenwasser commented Jan 31, 2024 •

edited

Loading

DanielRosenwasser commented Jan 31, 2024 •

edited

Loading

a-tarasyuk commented Feb 1, 2024 •

edited

Loading

a-tarasyuk commented Feb 6, 2024 •

edited

Loading

DanielRosenwasser commented Feb 6, 2024 •

edited

Loading

andrewbranch commented Feb 7, 2024 •

edited

Loading

bcomnes commented Jun 5, 2024 •

edited

Loading

zheung commented Jun 22, 2024 •

edited

Loading