Add support for `import defer` proposal #60757

nicolo-ribaudo · 2024-12-13T14:59:51Z

This proposal is currently at Stage 3.

This PR only needs to add parsing support for the proposal:

it does not support downleveling it, as it's not possible to transpile it to older ESM versions
- it would be possible add support for transpiling to CommonJS, if needed.
it does not introduce any type-checking changes, as the object created by import defer * as ns is meant to "look like" the one created by import * as ns

As you'll see from the code, whether a module is deferred or not is not a boolean but an enum. That's because of the import source proposal: there is no PR for it yet, but once it will be implemented it should be done by adding one more possible "import phase" to this enum. A question I have is if that should be an enum, or just an union of undefined | DeferKeyword (which will one day become undefined | DeferKeyword | SourceKeyword).

Fixes #59391

This patch was originally written by @ryzokuken

typescript-bot · 2024-12-13T15:00:10Z

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.

nicolo-ribaudo · 2024-12-13T15:46:29Z

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.

I guess this goes in favor of using undefined | DeferKeyword, so that it avoids a breaking change in the factory method? :)

jakebailey · 2024-12-13T17:29:16Z

src/compiler/factory/nodeFactory.ts


    // @api
-    function createImportClause(isTypeOnly: boolean, name: Identifier | undefined, namedBindings: NamedImportBindings | undefined): ImportClause {
+    function createImportClause(isTypeOnly: boolean, name: Identifier | undefined, namedBindings: NamedImportBindings | undefined, phase: ImportPhase): ImportClause {


Preemptively noting that this is a breaking API change, and would require a deprecation helper in the deprecations project to tack onto our public API something that will set a default for the new parameter.

It may also be the case that phase needs to go after isTypeOnly since AST node builder parameters and properties are intended to be in source order.

I don't think we want to mix type imports with defer or source. Something like import type source foo from "foo" doesn't make sense if all source imports will have the same type, and import type defer * as foo from "foo" would essentially be the same as import type * as foo from "foo".

If we consider type, defer, and source to be mutually exclusive, then I would suggest we replace the isTypeOnly parameter with something like importModifier: SyntaxKind.TypeKeyword | SyntaxKind.DeferKeyword | SyntaxKind.SourceKeyword | boolean | undefined and have ImportClause be:

export interface ImportClause extends NamedDeclaration { readonly kind: SyntaxKind.ImportClause; readonly parent: ImportDeclaration | JSDocImportTag; /** @deprecated */ readonly isTypeOnly: boolean; readonly importModifier: SyntaxKind.TypeKeyword | SyntaxKind.DeferKeyword | SyntaxKind.SourceKeyword | undefined; readonly name?: Identifier; // Default binding readonly namedBindings?: NamedImportBindings; }

For back-compat purposes, we can set isTypeOnly to true if importModifier is SyntaxKind.TypeKeyword.

I think the issue with that scheme is that it's a little weirder to capture multiple modifiers being used in the cases of error recovery.

I was originally going with something very similar to Ron's suggestion, and consider "type" just as another phase. I ended up not doing it because of the AST breaking change, but if just keeping the old property for backwards compat is ok then I'd go for it.

I think the issue with that scheme is that it's a little weirder to capture multiple modifiers being used in the cases of error recovery.

Error recovery is going to be tricky anyway, because each modifier is a valid identifier so things like import type defer are a potentially valid start of an import declaration. I wonder how likely it is for people to accidentally write two modifiers in an import.

jakebailey · 2024-12-13T17:31:19Z

I guess this goes in favor of using undefined | DeferKeyword, so that it avoids a breaking change in the factory method? :)

I'm not an expert per se, but I would expect that these need to be modifiers so that they are nodes that can be walked, since people can stick comments between them and so on...

DanielRosenwasser · 2024-12-13T20:00:07Z

I would expect that these need to be modifiers so that they are nodes that can be walked, since people can stick comments between them and so on...

Modifiers would precede the import here, so it's a bit more iffy than that. But I guess the export @decorator class C {} thing has already made things iffy between decorators/modifiers, and @rbuckton recalls how we handled this.

But this is close syntactically to import type, which just gets an isTypeOnly property slapped on, and hasn't caused issues. When we do need to hydrate nodes in the language service, we'll end up with a synthesized defer node. So from a technical standpoint, I think it's doesn't cause issues, but it might not be the best representation long-term.

rbuckton · 2024-12-13T21:17:08Z

But this is close syntactically to import type, which just gets an isTypeOnly property slapped on, and hasn't caused issues.

We have emitTokenWithComment to handle synthetic punctuation and comments, so that's fine. IMO we should just use SyntaxKind instead of a separate enum, as I suggested above.

rbuckton · 2024-12-13T21:21:37Z

That said, ImportClause is parsed after the import keyword, so it could have modifiers and we could just make type a modifier with isTypeOnly existing purely for back-compat purposes. That would require a lot of additional complexity in how we handle modifiers, however, as we'd have to have grammar checks to disallow type, defer, and source as modifiers for most elements (though we do this for accessor, in, out, etc, so it's nothing new).

src/compiler/emitter.ts

nicolo-ribaudo · 2024-12-19T16:17:59Z

I updated the PR to go with the suggestion in #60757 (comment), which is what I found the cleanest. Happy to do differently if needed. The API change is now backwards compatible. Probably I should do the same change for exports? Even though export defer and export source don't exist, so it's only for type.

I also added a test showing that comments are properly preserved.

src/compiler/emitter.ts

nicolo-ribaudo · 2025-01-16T14:51:56Z

Marking as draft until I implement import.defer(), which has been confirmed to remain part of the proposal.

nicolo-ribaudo · 2025-01-16T15:59:14Z

Oh well, that was simpler than expected. Given that import(...) is parsed as a CallExpression whose .expression is import, I'm parsing import.defer(...) as a CallExpression whose .expression is MetaProperty(import, defer) (+ some validation to make sure that it's not used as a standalone meta property, but only in the call syntax).

rbuckton · 2025-01-16T22:00:14Z

src/compiler/checker.ts

        const file = getSourceFileOfNode(node);
-        Debug.assert(!!(file.flags & NodeFlags.PossiblyContainsImportMeta), "Containing file is missing import meta node flag.");
+        Debug.assert(node.name.escapedText === "defer" || !!(file.flags & NodeFlags.PossiblyContainsImportMeta), "Containing file is missing import meta node flag.");
        return node.name.escapedText === "meta" ? getGlobalImportMetaType() : errorType;


Should import.defer be returning errorType here? Should we also report an error here for import.defer outside of a call?

I now moved the import.defer check to the checkMetaProperty, which also already calls checkGrammarMetaProperty to check if import.defer is outside of a call. I also changes isExpressionNode() to return false for the import.defer in import.defer(...).

So now this branch is only reached if we have a "standalone" import.defer, for which checkGrammarMetaProperty reports an error, and so returning errorType is correct.

src/compiler/checker.ts

src/compiler/parser.ts

src/compiler/checker.ts

src/compiler/parser.ts

src/compiler/types.ts

nicolo-ribaudo · 2025-01-17T18:09:29Z

tests/cases/conformance/importDefer/dynamicImportDefer.ts

+  ns.foo();
+});
+
+import("./a.js"); // TODO: Without this the import.defer cannot resolve ./a


I'm going to debug this next week, but if you have any pointer as to why I would be getting an error about ./a.js not being resolved in import.defer(...) without this I'd appreciate it :)

fireairforce · 2025-01-21T09:16:54Z

Sorry for bother ,i have some quesions:

https://github.com/tc39/proposal-source-phase-imports import source proposal Is this what you mean? Now TS seems to have no issues in the repository to follow up on this.
This PR seems to support some other syntaxes like import.defer("./a.js").then()、import defer foo from "a"、 import type defer * as ns1 from "a";, but i only see import defer * as a from "b" this syntax in the original proposal: https://github.com/tc39/proposal-defer-import-eval/ , So do all these other syntaxes need to be supported?

I am currently working on supporting this syntax for the biome parser, so I would like to see if TS has any support for this syntax in its parser.

nicolo-ribaudo · 2025-01-21T10:35:41Z

Yes, and it's not supported yet by TypeScript: https://www.typescriptlang.org/play/?ts=5.8.0-dev.20250121#code/JYWwDg9gTgLgBAZwgVygYwKZwB5wGZQQhwBEAPAmBmsHsBlAHwkDcQA
import.defer("./a.js") is defined at https://tc39.es/proposal-defer-import-eval/#sec-ecmascript-language-expressions. For the others, this PR is testing that they are disallowed :)

src/compiler/utilities.ts

rbuckton · 2025-01-21T17:44:17Z

src/compiler/checker.ts


        if (node.keywordToken === SyntaxKind.ImportKeyword) {
+            if (node.name.escapedText === "defer") {
+                Debug.assert(!isCallExpression(node.parent) || node.parent.expression !== node, "Trying to get the type of `import.defer` in `import.defer(...)`");


This assertion seems like it could result in an exception in an editor as you type import.defer. I'd rather we not crash here.

I don't think this can ever cause a crash. These are two cases:

we have import.defer(...)

we have import.defer outside of a call

In the first case, we are handling it in the CallExpression visitor and we do not recourse into the import.defer node. This assertions is verifying this.

In the second case, !isCallExpression(node.parent) || node.parent.expression !== node is true so the assertion does not fail.

src/compiler/checker.ts

nicolo-ribaudo · 2025-02-23T23:36:44Z

Note: this proposal reached stage 3 at the last TC39 meeting.

nicolo-ribaudo · 2025-06-05T14:22:42Z

@weswigham Actually, reading https://www.typescriptlang.org/docs/handbook/modules/theory.html#module-resolution, should nodenext allow this at all?

nodenext: A moving target reflecting the latest Node.js versions as Node.js’s module system evolves. As of TypeScript 5.8, nodenext supports require of ECMAScript modules.

esnext: Currently identical to es2022, but will be a moving target reflecting the latest ECMAScript specifications, as well as module-related Stage 3+ proposals that are expected to be included in upcoming specification versions.

The latest Node.js version does not support this proposal yet.

nicolo-ribaudo · 2025-06-05T15:18:40Z

@weswigham All your suggestions have been applied, except for the nodenext one.

I ended up dropping support for nodenext, since according to what I read in the docs I don't think it should support syntax that Node.js does not support yet. I can restore it (fixed) if you disagree.

I also added support for the new syntax when module: preserve.

weswigham

We'll need to remember that when we add support for these to node module modes to make support format-dependent and/or downlevel it, but for now, this is probably fine.

jakebailey · 2025-06-08T22:11:42Z

Unfortunately this broke code like:

import defer = require("./defer");

nicolo-ribaudo · 2025-06-09T10:04:49Z

PR coming leter today!

typescript-bot assigned rbuckton Dec 13, 2024

typescript-bot added the For Uncommitted Bug PR for untriaged, rejected, closed or missing bug label Dec 13, 2024

nicolo-ribaudo force-pushed the import-defer branch 2 times, most recently from 942385c to de82ce7 Compare December 13, 2024 15:45

jakebailey reviewed Dec 13, 2024

View reviewed changes

Jack-Works reviewed Dec 19, 2024

View reviewed changes

src/compiler/emitter.ts Outdated Show resolved Hide resolved

nicolo-ribaudo force-pushed the import-defer branch from 4ad3ba8 to b1f506b Compare December 19, 2024 16:09

nicolo-ribaudo commented Dec 19, 2024

View reviewed changes

src/compiler/emitter.ts Outdated Show resolved Hide resolved

nicolo-ribaudo force-pushed the import-defer branch from b1f506b to bdf98f5 Compare January 16, 2025 14:17

nicolo-ribaudo marked this pull request as draft January 16, 2025 14:51

nicolo-ribaudo force-pushed the import-defer branch from 808450c to 621eee7 Compare January 16, 2025 15:59

nicolo-ribaudo marked this pull request as ready for review January 16, 2025 15:59

nicolo-ribaudo force-pushed the import-defer branch from 621eee7 to e8d76ea Compare January 16, 2025 16:57

rbuckton suggested changes Jan 16, 2025

View reviewed changes

nicolo-ribaudo commented Jan 17, 2025

View reviewed changes

fireairforce mentioned this pull request Jan 21, 2025

📎 Add support for the import source proposal biomejs/biome#4934

Closed

rbuckton suggested changes Jan 21, 2025

View reviewed changes

nicolo-ribaudo force-pushed the import-defer branch from 5d38296 to 84c71d5 Compare February 5, 2025 15:44

nicolo-ribaudo and others added 8 commits June 5, 2025 15:40

Move errorType for import.defer handling

fc0908f

Do not consider import.defer in import.defer(...) as an expression

dec1011

fmt

8d2451a

Sort tokens alphabetically

c485777

Remove unused baselines

706bb58

Properly resolve specifiers in import.defer(...)

bfbcc3f

rbuckton review

bad45a3

Add test for jsdoc (unsupported)

5f54ced

nicolo-ribaudo added 2 commits June 5, 2025 17:02

Strip defer from dts

1e445bf

Use LastKeyword for LastContextualKeyword

1886e24

nicolo-ribaudo force-pushed the import-defer branch from 84c71d5 to 1886e24 Compare June 5, 2025 15:04

nicolo-ribaudo added 2 commits June 5, 2025 17:08

Add test for typeof import.defer (unsupported)

ffcfd9a

Drop support for nodenext, and allow when preserve

b352c0d

weswigham approved these changes Jun 6, 2025

View reviewed changes

github-project-automation bot moved this from Waiting on author to Needs merge in PR Backlog Jun 6, 2025

weswigham merged commit a69c6d0 into microsoft:main Jun 6, 2025
32 checks passed

github-project-automation bot moved this to Done in lavitaconnect@MOSTAFAAMMER Jun 6, 2025

github-project-automation bot moved this from Needs merge to Done in PR Backlog Jun 6, 2025

nicolo-ribaudo deleted the import-defer branch June 6, 2025 20:52

Boshen mentioned this pull request Jun 7, 2025

[Feature Request]: import defer rolldown/rolldown#4857

Open

chenjiahan mentioned this pull request Jun 9, 2025

[Feature]: Support for Deferring Module Evaluation (import defer) web-infra-dev/rspack#10608

Closed

nicolo-ribaudo mentioned this pull request Jun 9, 2025

Restore import defer = parsing #61837

Merged

codeOwlAI mentioned this pull request Jun 30, 2025

Feature implementation from commits b86ab7d..7715955 codeOwlAI/TypeScript#3

Open

robpalme mentioned this pull request Jul 21, 2025

import defer implementation tracker tc39/proposal-defer-import-eval#73

Open

JLHwung mentioned this pull request Aug 5, 2025

Use property name importKind instead of phase for import defer / export defer estree/estree#328

Open

Andarist mentioned this pull request Oct 5, 2025

Port "Add support for import defer proposal" microsoft/typescript-go#1826

Merged

Add support for import defer proposal #60757

Add support for import defer proposal #60757

Uh oh!

Conversation

nicolo-ribaudo commented Dec 13, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

typescript-bot commented Dec 13, 2024

Uh oh!

nicolo-ribaudo commented Dec 13, 2024

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rbuckton Dec 13, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jakebailey commented Dec 13, 2024

Uh oh!

DanielRosenwasser commented Dec 13, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

rbuckton commented Dec 13, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

rbuckton commented Dec 13, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

nicolo-ribaudo commented Dec 19, 2024

Uh oh!

Uh oh!

nicolo-ribaudo commented Jan 16, 2025

Uh oh!

nicolo-ribaudo commented Jan 16, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

fireairforce commented Jan 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

nicolo-ribaudo commented Jan 21, 2025

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

nicolo-ribaudo commented Feb 23, 2025

Uh oh!

nicolo-ribaudo commented Jun 5, 2025

Uh oh!

nicolo-ribaudo commented Jun 5, 2025

Uh oh!

weswigham left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

jakebailey commented Jun 8, 2025

Uh oh!

Add support for `import defer` proposal #60757

Add support for `import defer` proposal #60757

nicolo-ribaudo commented Dec 13, 2024 •

edited

Loading

rbuckton Dec 13, 2024 •

edited

Loading

DanielRosenwasser commented Dec 13, 2024 •

edited

Loading

rbuckton commented Dec 13, 2024 •

edited

Loading

rbuckton commented Dec 13, 2024 •

edited

Loading

fireairforce commented Jan 21, 2025 •

edited

Loading