feat(unstable): support TC39 import defer proposal (#32360)

This commit adds an experimental support for `import defer ...` syntax,
for https://github.com/tc39/proposal-defer-import-eval proposal.

Closes #30053

Author: bartlomieju

Cargo.lock

@@ -89,9 +89,9 @@ repository = "https://github.com/denoland/deno"
 [workspace.dependencies]
 deno_ast = { version = "=0.53.1", features = ["transpiling"] }
 deno_core_icudata = "0.77.0"
-deno_doc = "=0.197.0"
+deno_doc = "=0.198.0"
 deno_error = "=0.7.1"
-deno_graph = { version = "=0.107.1", default-features = false }
+deno_graph = { version = "=0.107.2", default-features = false }
 deno_lint = "=0.83.0"
 deno_media_type = { version = "=0.4.0", features = ["module_specifier"] }
 deno_native_certs = "0.3.0"

Cargo.toml

@@ -918,6 +918,7 @@ impl<TSys: SpecifierUnfurlerSys> SpecifierUnfurler<TSys> {
             match dep.kind {
               StaticDependencyKind::Export
               | StaticDependencyKind::Import
+              | StaticDependencyKind::ImportDefer
               | StaticDependencyKind::ImportSource
               | StaticDependencyKind::ExportEquals
               | StaticDependencyKind::ImportEquals => {

cli/tools/publish/unfurl.rs

@@ -1279,6 +1279,10 @@ pub static IGNORED_DIAGNOSTIC_CODES: LazyLock<HashSet<u64>> =
       // implicitly has an 'any' type.  This is due to `allowJs` being off by
       // default but importing of a JavaScript module.
       7016,
+      // TS18060: Deferred imports are only supported when the '--module' flag
+      // is set to 'esnext' or 'preserve'. Deno uses its own module resolution
+      // and supports import defer natively.
+      18060,
     ]
     .into_iter()
     .collect()

cli/tsc/mod.rs

@@ -2018,7 +2018,7 @@ impl ModuleMap {
             .unwrap()
             .clone();
           match state.phase {
-            ModuleImportPhase::Defer | ModuleImportPhase::Evaluation => {
+            ModuleImportPhase::Evaluation => {
               let module_id =
                 load.root_module_id().expect("Root module should be loaded");
               let result = self.instantiate_module(scope, module_id);
@@ -2032,6 +2032,95 @@ impl ModuleMap {
                 state,
               )?;
             }
+            ModuleImportPhase::Defer => {
+              // For defer phase imports, the module is instantiated but NOT
+              // eagerly evaluated. We call evaluate_for_import_defer which
+              // gathers and evaluates async transitive dependencies, then
+              // resolve with a deferred namespace that triggers evaluation
+              // on first property access.
+              let module_id =
+                load.root_module_id().expect("Root module should be loaded");
+              let result = self.instantiate_module(scope, module_id);
+              if let Err(exception) = result {
+                self.dynamic_import_reject(scope, dyn_import_id, exception);
+                continue;
+              }
+              let module_handle =
+                self.get_handle(module_id).expect("ModuleInfo not found");
+
+              v8::tc_scope!(let tc_scope, scope);
+
+              let cped = v8::Local::new(tc_scope, state.cped.clone());
+              tc_scope.set_continuation_preserved_embedder_data(cped);
+
+              let module = v8::Local::new(tc_scope, &module_handle);
+
+              // Gather async transitive dependencies. Returns a promise
+              // that resolves when all async deps are ready.
+              let maybe_promise = module.evaluate_for_import_defer(tc_scope);
+
+              let Some(promise_val) = maybe_promise else {
+                let exception = tc_scope.exception().unwrap();
+                let exception = v8::Global::new(tc_scope, exception);
+                self.dynamic_import_reject(tc_scope, dyn_import_id, exception);
+                continue;
+              };
+
+              // Get the deferred namespace — this triggers evaluation on
+              // first property access.
+              let module_namespace = module
+                .get_module_namespace_with_phase(v8::ModuleImportPhase::kDefer);
+
+              let promise = v8::Local::<v8::Promise>::try_from(promise_val)
+                .expect("evaluate_for_import_defer should return a promise");
+
+              match promise.state() {
+                v8::PromiseState::Fulfilled => {
+                  // All async deps are ready, resolve immediately.
+                  let resolver_handle = self
+                    .dynamic_import_map
+                    .borrow_mut()
+                    .remove(&dyn_import_id)
+                    .expect("Invalid dynamic import id")
+                    .resolver;
+                  let resolver = resolver_handle.open(tc_scope);
+                  resolver.resolve(tc_scope, module_namespace).unwrap();
+                  tc_scope.perform_microtask_checkpoint();
+                }
+                v8::PromiseState::Rejected => {
+                  let err = promise.result(tc_scope);
+                  let err = v8::Global::new(tc_scope, err);
+                  self.dynamic_import_reject(tc_scope, dyn_import_id, err);
+                }
+                v8::PromiseState::Pending => {
+                  // Async deps still loading. Store for later resolution.
+                  // The module_waker will wake us when the promise settles.
+                  fn wake_module(
+                    scope: &mut v8::PinScope<'_, '_>,
+                    _args: v8::FunctionCallbackArguments<'_>,
+                    _rv: v8::ReturnValue,
+                  ) {
+                    let module_map = JsRealm::module_map_from(scope);
+                    module_map.module_waker.wake();
+                  }
+
+                  let wake_module_cb =
+                    v8::Function::builder(wake_module).build(tc_scope);
+                  if let Some(wake_module_cb) = wake_module_cb {
+                    promise.then2(tc_scope, wake_module_cb, wake_module_cb);
+                  }
+
+                  let dyn_import_mod_evaluate = DynImportModEvaluate {
+                    load_id: dyn_import_id,
+                    module_id,
+                    promise: v8::Global::new(tc_scope, promise),
+                  };
+                  self
+                    .pending_dyn_mod_evaluations
+                    .push(dyn_import_mod_evaluate);
+                }
+              }
+            }
             ModuleImportPhase::Source => {
               let module_reference = load.root_module_reference().expect(
                 "Root module reference had to have been resolved to get here.",

libs/core/modules/map.rs

@@ -154,7 +154,8 @@ fn v8_init(
     " --harmony-temporal",
     " --js-float16array",
     " --js-explicit-resource-management",
-    " --js-source-phase-imports"
+    " --js-source-phase-imports",
+    " --js-defer-import-eval"
   );
   let snapshot_flags = "--predictable --random-seed=42";
   let expose_natives_flags = "--expose_gc --allow_natives_syntax";

libs/core/runtime/setup.rs

@@ -0,0 +1,6 @@
+// Copyright 2018-2026 the Deno authors. MIT license.
+console.log("deferred module evaluated");
+export const value = 42;
+export function add(a, b) {
+  return a + b;
+}

libs/core_testing/integration/import_defer/deferred.js

@@ -0,0 +1,3 @@
+// Copyright 2018-2026 the Deno authors. MIT license.
+console.log("deferred2 module evaluated");
+export const value = 99;

libs/core_testing/integration/import_defer/deferred2.js

@@ -0,0 +1,35 @@
+// Copyright 2018-2026 the Deno authors. MIT license.
+
+// Test for TC39 proposal: Deferred Module Evaluation
+// https://github.com/tc39/proposal-defer-import-eval
+//
+// The `import defer` syntax allows loading a module without immediately
+// executing it. The module is executed synchronously when any property
+// on the namespace is first accessed.
+//
+console.log("before import defer");
+
+// Static import defer syntax - module is loaded but not executed
+import defer * as deferred from "./deferred.js";
+
+console.log("after import defer, before access");
+
+// First property access triggers module evaluation
+console.log(`value: ${deferred.value}`);
+
+console.log("after first access");
+
+// Subsequent accesses use the already-evaluated module
+console.log(`add: ${deferred.add(1, 2)}`);
+
+console.log("after first access, before dynamic import defer");
+
+// Dynamic import.defer syntax
+const deferred2 = await import.defer("./deferred2.js");
+
+console.log("after dynamic import defer, before access");
+
+// First property access triggers evaluation
+console.log(`deferred2 value: ${deferred2.value}`);
+
+console.log("done");

libs/core_testing/integration/import_defer/import_defer.js

@@ -0,0 +1,11 @@
+before import defer
+after import defer, before access
+deferred module evaluated
+value: 42
+after first access
+add: 3
+after first access, before dynamic import defer
+after dynamic import defer, before access
+deferred2 module evaluated
+deferred2 value: 99
+done