fix #4238: add defer and source import phases

Author: evanw

CHANGELOG.md

@@ -2,6 +2,34 @@
 
 ## Unreleased
 
+* Parse and print JavaScript imports with an explicit phase ([#4238](https://github.com/evanw/esbuild/issues/4238))
+
+    This release adds basic syntax support for the `defer` and `source` import phases in JavaScript:
+
+    * `defer`
+
+        This is a [stage 3 proposal](https://github.com/tc39/proposal-defer-import-eval) for an upcoming JavaScript feature that will provide one way to eagerly load but lazily initialize imported modules. The imported module is automatically initialized on first use. Support for this syntax will also be part of the upcoming release of [TypeScript 5.9](https://devblogs.microsoft.com/typescript/announcing-typescript-5-9-beta/#support-for-import-defer). The syntax looks like this:
+
+        ```js
+        import defer * as foo from "<specifier>";
+        const bar = await import.defer("<specifier>");
+        ```
+
+        Note that this feature deliberately cannot be used with the syntax `import defer foo from "<specifier>"` or `import defer { foo } from "<specifier>"`.
+
+    * `source`
+
+        This is a [stage 3 proposal](https://github.com/tc39/proposal-source-phase-imports) for an upcoming JavaScript feature that will provide another way to eagerly load but lazily initialize imported modules. The imported module is returned in an uninitialized state. Support for this syntax may or may not be a part of TypeScript 5.9 (see [this issue](https://github.com/microsoft/TypeScript/issues/61216) for details). The syntax looks like this:
+
+        ```js
+        import source foo from "<specifier>";
+        const bar = await import.source("<specifier>");
+        ```
+
+        Note that this feature deliberately cannot be used with the syntax `import defer * as foo from "<specifier>"` or `import defer { foo } from "<specifier>"`.
+
+    This change only adds support for this syntax. These imports cannot currently be bundled by esbuild. To use these new features with esbuild's bundler, the imported paths must be external to the bundle and the output format must be set to `esm`.
+
 * Support optionally emitting absolute paths instead of relative paths ([#338](https://github.com/evanw/esbuild/issues/338), [#2082](https://github.com/evanw/esbuild/issues/2082), [#3023](https://github.com/evanw/esbuild/issues/3023))
 
     This release introduces the `--abs-paths=` feature which takes a comma-separated list of situations where esbuild should use absolute paths instead of relative paths. There are currently three supported situations: `code` (comments and string literals), `log` (log message text and location info), and `metafile` (the JSON build metadata).

compat-table/src/index.ts

@@ -59,7 +59,9 @@ export const jsFeatures = {
   Hashbang: true,
   ImportAssertions: true,
   ImportAttributes: true,
+  ImportDefer: true,
   ImportMeta: true,
+  ImportSource: true,
   InlineScript: true,
   LogicalAssignment: true,
   NestedRestBinding: true,

internal/ast/ast.go

@@ -78,6 +78,18 @@ func (kind ImportKind) MustResolveToCSS() bool {
 	return false
 }
 
+type ImportPhase uint8
+
+const (
+	EvaluationPhase ImportPhase = iota
+
+	// See: https://github.com/tc39/proposal-defer-import-eval
+	DeferPhase
+
+	// See: https://github.com/tc39/proposal-source-phase-imports
+	SourcePhase
+)
+
 type ImportRecordFlags uint16
 
 const (
@@ -167,6 +179,7 @@ type ImportRecord struct {
 	CopySourceIndex Index32
 
 	Flags ImportRecordFlags
+	Phase ImportPhase
 	Kind  ImportKind
 }
 

internal/bundler/bundler.go

@@ -469,11 +469,18 @@ func parseFile(args parseArgs) {
 					// Special-case glob pattern imports
 					if record.GlobPattern != nil {
 						prettyPath := helpers.GlobPatternToString(record.GlobPattern.Parts)
+						phase := ""
+						switch record.Phase {
+						case ast.DeferPhase:
+							phase = ".defer"
+						case ast.SourcePhase:
+							phase = ".source"
+						}
 						switch record.GlobPattern.Kind {
 						case ast.ImportRequire:
-							prettyPath = fmt.Sprintf("require(%q)", prettyPath)
+							prettyPath = fmt.Sprintf("require%s(%q)", phase, prettyPath)
 						case ast.ImportDynamic:
-							prettyPath = fmt.Sprintf("import(%q)", prettyPath)
+							prettyPath = fmt.Sprintf("import%s(%q)", phase, prettyPath)
 						}
 						if results, msg := args.res.ResolveGlob(absResolveDir, record.GlobPattern.Parts, record.GlobPattern.Kind, prettyPath); results != nil {
 							if msg != nil {
@@ -482,7 +489,11 @@ func parseFile(args parseArgs) {
 							if result.globResolveResults == nil {
 								result.globResolveResults = make(map[uint32]globResolveResult)
 							}
+							allAreExternal := true
 							for key, result := range results {
+								if !result.PathPair.IsExternal {
+									allAreExternal = false
+								}
 								result.PathPair.Primary.ImportAttributes = attrs
 								if result.PathPair.HasSecondary() {
 									result.PathPair.Secondary.ImportAttributes = attrs
@@ -498,6 +509,12 @@ func parseFile(args parseArgs) {
 								},
 								exportAlias: record.GlobPattern.ExportAlias,
 							}
+
+							// Forbid bundling of imports with explicit phases
+							if record.Phase != ast.EvaluationPhase {
+								reportExplicitPhaseImport(args.log, &tracker, record.Range,
+									record.Phase, allAreExternal, args.options.OutputFormat)
+							}
 						} else {
 							args.log.AddError(&tracker, record.Range, fmt.Sprintf("Could not resolve %s", prettyPath))
 						}
@@ -593,6 +610,12 @@ func parseFile(args parseArgs) {
 						continue
 					}
 
+					// Forbid bundling of imports with explicit phases
+					if record.Phase != ast.EvaluationPhase {
+						reportExplicitPhaseImport(args.log, &tracker, record.Range,
+							record.Phase, entry.resolveResult.PathPair.IsExternal, args.options.OutputFormat)
+					}
+
 					result.resolveResults[importRecordIndex] = entry.resolveResult
 				}
 			}
@@ -736,6 +759,30 @@ func parseFile(args parseArgs) {
 	args.results <- result
 }
 
+func reportExplicitPhaseImport(
+	log logger.Log,
+	tracker *logger.LineColumnTracker,
+	r logger.Range,
+	phase ast.ImportPhase,
+	isExternal bool,
+	format config.Format,
+) {
+	var phaseText string
+	switch phase {
+	case ast.DeferPhase:
+		phaseText = "deferred"
+	case ast.SourcePhase:
+		phaseText = "source phase"
+	default:
+		return
+	}
+	if format != config.FormatESModule {
+		log.AddError(tracker, r, fmt.Sprintf("Bundling %s imports with the %q output format is not supported", phaseText, format.String()))
+	} else if !isExternal {
+		log.AddError(tracker, r, fmt.Sprintf("Bundling with %s imports is not supported unless they are external", phaseText))
+	}
+}
+
 func ResolveFailureErrorTextSuggestionNotes(
 	res *resolver.Resolver,
 	path string,
@@ -2144,7 +2191,7 @@ func (s *scanner) scanAllDependencies() {
 						sourceIndex := s.allocateGlobSourceIndex(result.file.inputFile.Source.Index, uint32(importRecordIndex))
 						record.SourceIndex = ast.MakeIndex32(sourceIndex)
 						s.results[sourceIndex] = s.generateResultForGlobResolve(sourceIndex, globResults.absPath,
-							&result.file.inputFile.Source, record.Range, with, record.GlobPattern.Kind, globResults, record.AssertOrWith)
+							&result.file.inputFile.Source, record.Range, with, record.GlobPattern.Kind, record.Phase, globResults, record.AssertOrWith)
 					}
 					continue
 				}
@@ -2192,6 +2239,7 @@ func (s *scanner) generateResultForGlobResolve(
 	importRange logger.Range,
 	importWith *ast.ImportAssertOrWith,
 	kind ast.ImportKind,
+	phase ast.ImportPhase,
 	result globResolveResult,
 	assertions *ast.ImportAssertOrWith,
 ) parseResult {
@@ -2245,6 +2293,7 @@ func (s *scanner) generateResultForGlobResolve(
 			SourceIndex:  sourceIndex,
 			AssertOrWith: assertions,
 			Kind:         kind,
+			Phase:        phase,
 		})
 
 		switch kind {