fix(ext/node): run register() hooks in worker thread, add --experimental-loader flag (#33906)

Two related features that together bring Node.js module loader hooks
much closer to compatibility:

### 1. Worker-thread architecture for `module.register()` 

Rearchitects `module.register()` to run async hooks in a dedicated Web
Worker thread, matching Node.js's "hooks thread" design. Previously,
hook modules were loaded on the main thread, causing deadlocks when the
hook module's own imports went through the hook infrastructure.

**How it works:**
- On first `register()` call, a Web Worker is spawned with inline
bootstrap code
- The hook module is loaded inside the worker (separate event loop, no
deadlock)
- Resolve/load requests are forwarded from the main thread to the worker
via `postMessage`
- Sync hooks from `registerHooks()` still run on the main thread (per
Node.js spec, sync before async)

### 2. `--experimental-loader` CLI flag

Adds `--experimental-loader` (with `--loader` alias) as a hidden CLI
flag for Node.js compatibility. Before the main module runs, each loader
module is eagerly imported and its resolve/load hooks are registered.

### 3. Fix sync resolve panic (#33901)

Adds a `resolve_cache` to `LoaderHookRegistry` that caches resolve
results from the async load phase. During V8's synchronous module
instantiation callback, the cache is checked first, returning a sync
result instead of panicking on an async response.

Closes #23201
Fixes #33901

Author: bartlomieju

cli/args/flags.rs

@@ -1001,6 +1001,7 @@ pub struct Flags {
   pub permission_set: Option<String>,
   pub eszip: bool,
   pub node_conditions: Vec<String>,
+  pub experimental_loaders: Vec<String>,
   pub preload: Vec<String>,
   pub require: Vec<String>,
   pub tunnel: bool,
@@ -5502,6 +5503,7 @@ fn runtime_misc_args(app: Command) -> Command {
     .arg(enable_testing_features_arg())
     .arg(trace_ops_arg())
     .arg(eszip_arg())
+    .arg(experimental_loader_arg())
     .arg(preload_arg())
     .arg(require_arg())
 }
@@ -5710,6 +5712,17 @@ fn reload_arg() -> Arg {
     .help_heading(DEPENDENCY_MANAGEMENT_HEADING)
 }
 
+fn experimental_loader_arg() -> Arg {
+  Arg::new("experimental-loader")
+    .long("experimental-loader")
+    .alias("loader")
+    .value_name("MODULE")
+    .action(ArgAction::Append)
+    .help("Use the specified module as a custom loader (Node.js compat)")
+    .hide(true)
+    .value_hint(ValueHint::FilePath)
+}
+
 fn preload_arg() -> Arg {
   Arg::new("preload")
     .long("preload")
@@ -8270,6 +8283,7 @@ fn runtime_args_parse(
   env_file_arg_parse(flags, matches);
   trace_ops_parse(flags, matches);
   eszip_arg_parse(flags, matches);
+  experimental_loader_arg_parse(flags, matches);
   preload_arg_parse(flags, matches);
   require_arg_parse(flags, matches);
   Ok(())
@@ -8320,6 +8334,12 @@ fn reload_arg_parse(
   Ok(())
 }
 
+fn experimental_loader_arg_parse(flags: &mut Flags, matches: &mut ArgMatches) {
+  if let Some(loaders) = matches.remove_many::<String>("experimental-loader") {
+    flags.experimental_loaders = loaders.collect();
+  }
+}
+
 fn preload_arg_parse(flags: &mut Flags, matches: &mut ArgMatches) {
   if let Some(preload) = matches.remove_many::<String>("preload") {
     flags.preload = preload.collect();

cli/args/mod.rs

@@ -685,6 +685,19 @@ impl CliOptions {
       .filter_map(|p| canonicalize_path(&p).ok())
   }
 
+  pub fn experimental_loaders(&self) -> Result<Vec<ModuleSpecifier>, AnyError> {
+    if self.flags.experimental_loaders.is_empty() {
+      return Ok(vec![]);
+    }
+
+    let mut modules = Vec::with_capacity(self.flags.experimental_loaders.len());
+    for loader_specifier in self.flags.experimental_loaders.iter() {
+      modules.push(resolve_url_or_path(loader_specifier, self.initial_cwd())?);
+    }
+
+    Ok(modules)
+  }
+
   pub fn preload_modules(&self) -> Result<Vec<ModuleSpecifier>, AnyError> {
     if self.flags.preload.is_empty() {
       return Ok(vec![]);

cli/factory.rs

@@ -1275,6 +1275,7 @@ impl CliFactory {
     Ok(CliMainWorkerOptions {
       needs_test_modules: cli_options.sub_command().needs_test(),
       create_hmr_runner,
+      experimental_loaders: cli_options.experimental_loaders()?,
       maybe_coverage_dir,
       maybe_cpu_prof_config,
       default_npm_caching_strategy: cli_options.default_npm_caching_strategy(),

cli/lib/worker.rs

@@ -587,12 +587,14 @@ impl<TSys: DenoLibSys> LibMainWorkerFactory<TSys> {
     mode: WorkerExecutionMode,
     permissions: PermissionsContainer,
     main_module: Url,
+    experimental_loaders: Vec<Url>,
     preload_modules: Vec<Url>,
     require_modules: Vec<Url>,
   ) -> Result<LibMainWorker, CoreError> {
     self.create_custom_worker(
       mode,
       main_module,
+      experimental_loaders,
       preload_modules,
       require_modules,
       permissions,
@@ -607,6 +609,7 @@ impl<TSys: DenoLibSys> LibMainWorkerFactory<TSys> {
     &self,
     mode: WorkerExecutionMode,
     main_module: Url,
+    experimental_loaders: Vec<Url>,
     preload_modules: Vec<Url>,
     require_modules: Vec<Url>,
     permissions: PermissionsContainer,
@@ -744,6 +747,7 @@ impl<TSys: DenoLibSys> LibMainWorkerFactory<TSys> {
 
     Ok(LibMainWorker {
       main_module,
+      experimental_loaders,
       preload_modules,
       require_modules,
       worker,
@@ -835,6 +839,7 @@ impl<TSys: DenoLibSys> LibMainWorkerFactory<TSys> {
 
 pub struct LibMainWorker {
   main_module: Url,
+  experimental_loaders: Vec<Url>,
   preload_modules: Vec<Url>,
   require_modules: Vec<Url>,
   worker: MainWorker,
@@ -927,6 +932,33 @@ impl LibMainWorker {
     Ok(())
   }
 
+  pub async fn execute_experimental_loaders(
+    &mut self,
+  ) -> Result<(), CoreError> {
+    if self.experimental_loaders.is_empty() {
+      return Ok(());
+    }
+    // Build a JS array of loader URLs using JSON serialization
+    // for robust escaping of special characters in URLs.
+    let urls_json: Vec<String> = self
+      .experimental_loaders
+      .iter()
+      .map(|u| serde_json::to_string(u.as_str()).unwrap())
+      .collect();
+    let script = format!(
+      r#"(async () => {{
+        const {{ _registerCliLoaders }} = await import("node:module");
+        await _registerCliLoaders([{}]);
+      }})()"#,
+      urls_json.join(",")
+    );
+    self
+      .worker
+      .execute_script("experimental-loader-setup", script.into())?;
+    self.worker.run_event_loop(false).await?;
+    Ok(())
+  }
+
   pub async fn execute_preload_modules(&mut self) -> Result<(), CoreError> {
     for preload_module_url in self.preload_modules.iter() {
       let id = self.worker.preload_side_module(preload_module_url).await?;
@@ -946,6 +978,9 @@ impl LibMainWorker {
   pub async fn run(&mut self) -> Result<i32, CoreError> {
     log::debug!("main_module {}", self.main_module);
 
+    // Register experimental loader hooks before anything else
+    self.execute_experimental_loaders().await?;
+
     // Run preload modules first if they were defined
     self.execute_preload_modules().await?;
 

cli/module_loader.rs

@@ -1019,6 +1019,23 @@ impl<TGraphContainer: ModuleGraphContainer> ModuleLoader
     if self.0.hook_registry.resolve_active.get()
       && !is_already_resolved_specifier(specifier)
     {
+      // Check if this specifier was already resolved by hooks during
+      // the load phase. This cache lookup is critical for V8's module
+      // instantiation callback (module_resolve_callback) which calls
+      // resolve synchronously -- we cannot return Async there.
+      let cache_key = format!("{specifier}\x00{referrer}");
+      if let Some(cached) = self
+        .0
+        .hook_registry
+        .resolve_cache
+        .borrow_mut()
+        .remove(&cache_key)
+      {
+        return deno_core::ModuleResolveResponse::Sync(
+          ModuleSpecifier::parse(&cached).map_err(JsErrorBox::from_err),
+        );
+      }
+
       let receiver = self
         .0
         .hook_registry
@@ -1039,6 +1056,12 @@ impl<TGraphContainer: ModuleGraphContainer> ModuleLoader
             Ok(Some(url)) => {
               let parsed =
                 ModuleSpecifier::parse(&url).map_err(JsErrorBox::from_err)?;
+              // Cache the resolve result so instantiation can look it up
+              // synchronously later.
+              inner.hook_registry.resolve_cache.borrow_mut().insert(
+                format!("{specifier}\x00{referrer}"),
+                parsed.to_string(),
+              );
               // Track that this specifier was hook-intercepted (virtual module)
               // so prepare_load knows to skip graph building for it.
               inner
@@ -1049,8 +1072,17 @@ impl<TGraphContainer: ModuleGraphContainer> ModuleLoader
               Ok(parsed)
             }
             Ok(None) => {
-              // Fallthrough: hooks didn't intercept, use default
-              inner.inner_resolve(&specifier, &referrer, kind, false)
+              // Fallthrough: hooks didn't intercept, use default.
+              // Cache the result so instantiation doesn't go async.
+              let result =
+                inner.inner_resolve(&specifier, &referrer, kind, false);
+              if let Ok(ref resolved) = result {
+                inner.hook_registry.resolve_cache.borrow_mut().insert(
+                  format!("{specifier}\x00{referrer}"),
+                  resolved.to_string(),
+                );
+              }
+              result
             }
             Err(err) => Err(JsErrorBox::generic(err)),
           }

cli/rt/run.rs

@@ -1397,6 +1397,7 @@ pub async fn run(
     WorkerExecutionMode::Run,
     permissions,
     main_module,
+    vec![], // no experimental loaders in standalone binaries
     preload_modules,
     require_modules,
   )?;

cli/worker.rs

@@ -43,6 +43,7 @@ pub type CreateHmrRunnerCb = Box<dyn Fn() -> HmrRunnerState + Send + Sync>;
 
 pub struct CliMainWorkerOptions {
   pub create_hmr_runner: Option<CreateHmrRunnerCb>,
+  pub experimental_loaders: Vec<ModuleSpecifier>,
   pub maybe_coverage_dir: Option<PathBuf>,
   pub maybe_cpu_prof_config: Option<CpuProfilerConfig>,
   pub default_npm_caching_strategy: NpmCachingStrategy,
@@ -131,6 +132,9 @@ impl CliMainWorker {
 
     log::debug!("main_module {}", self.worker.main_module());
 
+    // Register experimental loader hooks before anything else
+    self.worker.execute_experimental_loaders().await?;
+
     // Run preload modules first if they were defined
     self.worker.execute_preload_modules().await?;
     self.execute_main_module().await?;
@@ -358,6 +362,7 @@ pub enum CreateCustomWorkerError {
 }
 
 pub struct CliMainWorkerFactory {
+  experimental_loaders: Vec<ModuleSpecifier>,
   lib_main_worker_factory: LibMainWorkerFactory<CliSys>,
   maybe_lockfile: Option<Arc<CliLockfile>>,
   npm_installer: Option<Arc<CliNpmInstaller>>,
@@ -382,6 +387,7 @@ impl CliMainWorkerFactory {
     root_permissions: PermissionsContainer,
   ) -> Self {
     Self {
+      experimental_loaders: options.experimental_loaders,
       lib_main_worker_factory,
       maybe_lockfile,
       npm_installer,
@@ -505,6 +511,7 @@ impl CliMainWorkerFactory {
     let mut worker = self.lib_main_worker_factory.create_custom_worker(
       mode,
       main_module,
+      self.experimental_loaders.clone(),
       preload_modules,
       require_modules,
       permissions,

ext/node/ops/module_hooks.rs

@@ -49,6 +49,12 @@ pub struct LoaderHookRegistry {
   /// don't exist on disk.
   pub hook_intercepted_specifiers: Rc<RefCell<HashSet<String>>>,
 
+  /// Cache of resolve results (key: "specifier\0referrer" → resolved URL).
+  /// Populated during the async load phase so that V8's synchronous module
+  /// instantiation callback can look up previously-resolved specifiers
+  /// without going through the async hook bridge.
+  pub resolve_cache: Rc<RefCell<HashMap<String, String>>>,
+
   pending_resolves: Rc<RefCell<VecDeque<PendingResolve>>>,
   resolve_waker: Rc<RefCell<Option<Waker>>>,
   resolve_senders: Rc<RefCell<HashMap<u32, ResolveSender>>>,