From 5a3c7f799221b5ffb30952c874457f307fbb2935 Mon Sep 17 00:00:00 2001
From: jedel1043 <jedel0124@gmail.com>
Date: Tue, 6 Jun 2023 17:54:33 -0600
Subject: [PATCH 1/2] Add convenience methods to `ModuleLoader`

---
 boa_engine/src/module/mod.rs    | 36 +++++++++++++++++++++++++++++++++
 boa_examples/src/bin/modules.rs |  5 +++--
 2 files changed, 39 insertions(+), 2 deletions(-)

diff --git a/boa_engine/src/module/mod.rs b/boa_engine/src/module/mod.rs
index c9e798f6039..214f414524f 100644
--- a/boa_engine/src/module/mod.rs
+++ b/boa_engine/src/module/mod.rs
@@ -108,6 +108,26 @@ pub trait ModuleLoader {
         context: &mut Context<'_>,
     );
 
+    /// Registers a new module into the module loader.
+    ///
+    /// This is a convenience method for module loaders caching already parsed modules, since it
+    /// allows registering a new module through the `&dyn ModuleLoader` provided by
+    /// [`Context::module_loader`].
+    ///
+    /// Does nothing by default.
+    fn register_module(&self, _specifier: JsString, _module: Module) {}
+
+    /// Gets the module associated with the provided specifier.
+    ///
+    /// This is a convenience method for module loaders caching already parsed modules, since it
+    /// allows getting a cached module through the `&dyn ModuleLoader` provided by
+    /// [`Context::module_loader`].
+    ///
+    /// Returns `None` by default.
+    fn get_module(&self, _specifier: JsString) -> Option<Module> {
+        None
+    }
+
     /// Host hooks [`HostGetImportMetaProperties ( moduleRecord )`][meta] and
     /// [`HostFinalizeImportMeta ( importMeta, moduleRecord )`][final].
     ///
@@ -233,6 +253,22 @@ impl ModuleLoader for SimpleModuleLoader {
 
         finish_load(result, context);
     }
+
+    // TODO: Try to unify `ModuleLoader::register_module` with `SimpleModuleLoader::insert`.
+    fn register_module(&self, _specifier: JsString, _module: Module) {
+        panic!(
+            "`SimpleModuleLoader` uses paths to cache the modules instead of specifiers.
+        To register a module, you need to use the `SimpleModuleLoader::insert` method."
+        )
+    }
+
+    // TODO: Try to unify `ModuleLoader::get_module` with `SimpleModuleLoader::get`.
+    fn get_module(&self, _specifier: JsString) -> Option<Module> {
+        panic!(
+            "`SimpleModuleLoader` uses paths to cache the modules instead of specifiers.
+        To get a module, you need to use the `SimpleModuleLoader::get` method."
+        )
+    }
 }
 
 /// ECMAScript's [**Abstract module record**][spec].
diff --git a/boa_examples/src/bin/modules.rs b/boa_examples/src/bin/modules.rs
index f1ea129e80c..2d9435adf08 100644
--- a/boa_examples/src/bin/modules.rs
+++ b/boa_examples/src/bin/modules.rs
@@ -44,8 +44,9 @@ fn main() -> Result<(), Box<dyn Error>> {
         module.clone(),
     );
 
-    // The lifecycle of the module is tracked using promises, which can be a bit cumbersome
-    // for simple uses but that use case is better suited by the `Module::load_link_evaluate` method.
+    // The lifecycle of the module is tracked using promises which can be a bit cumbersome to use.
+    // If you just want to directly execute a module, you can use the `Module::load_link_evaluate`
+    // method to skip all the boilerplate.
     // This does the full version for demonstration purposes.
     //
     // parse -> load -> link -> evaluate

From e34edbc030bffdef94d2a390bdd0abbef546e3fc Mon Sep 17 00:00:00 2001
From: jedel1043 <jedel0124@gmail.com>
Date: Thu, 8 Jun 2023 17:58:10 -0600
Subject: [PATCH 2/2] Document special behaviour of `SimpleModuleLoader`

---
 boa_engine/src/module/mod.rs | 22 ++++++----------------
 1 file changed, 6 insertions(+), 16 deletions(-)

diff --git a/boa_engine/src/module/mod.rs b/boa_engine/src/module/mod.rs
index 214f414524f..abd610d04ea 100644
--- a/boa_engine/src/module/mod.rs
+++ b/boa_engine/src/module/mod.rs
@@ -173,6 +173,12 @@ impl ModuleLoader for IdleModuleLoader {
 }
 
 /// A simple module loader that loads modules relative to a root path.
+///
+/// # Note
+///
+/// This loader only works by using the type methods [`SimpleModuleLoader::insert`] and
+/// [`SimpleModuleLoader::get`]. The utility methods on [`ModuleLoader`] don't work at the moment,
+/// but we'll unify both APIs in the future.
 #[derive(Debug)]
 pub struct SimpleModuleLoader {
     root: PathBuf,
@@ -253,22 +259,6 @@ impl ModuleLoader for SimpleModuleLoader {
 
         finish_load(result, context);
     }
-
-    // TODO: Try to unify `ModuleLoader::register_module` with `SimpleModuleLoader::insert`.
-    fn register_module(&self, _specifier: JsString, _module: Module) {
-        panic!(
-            "`SimpleModuleLoader` uses paths to cache the modules instead of specifiers.
-        To register a module, you need to use the `SimpleModuleLoader::insert` method."
-        )
-    }
-
-    // TODO: Try to unify `ModuleLoader::get_module` with `SimpleModuleLoader::get`.
-    fn get_module(&self, _specifier: JsString) -> Option<Module> {
-        panic!(
-            "`SimpleModuleLoader` uses paths to cache the modules instead of specifiers.
-        To get a module, you need to use the `SimpleModuleLoader::get` method."
-        )
-    }
 }
 
 /// ECMAScript's [**Abstract module record**][spec].