feat(tegg-loader): support async module importer override (__EGG_MODULE_IMPORTER__)

packages/typings/src/global.ts

@@ -1,8 +1,10 @@
-import type { BundleModuleLoader } from './index.ts';
+import type { BundleModuleLoader, ModuleImporter } from './index.ts';
 
 declare global {
   // eslint-disable-next-line no-var
   var __EGG_BUNDLE_MODULE_LOADER__: BundleModuleLoader | undefined;
+  // eslint-disable-next-line no-var
+  var __EGG_MODULE_IMPORTER__: ModuleImporter | undefined;
 }
 
 export {};

packages/typings/src/index.ts

@@ -4,3 +4,20 @@
  * standard import path.
  */
 export type BundleModuleLoader = (filepath: string) => unknown;
+
+/**
+ * Async module importer override for the tegg loader's file loading.
+ *
+ * When set, the loader delegates module loading to this importer instead of the
+ * built-in `await import(filePath)`. Its main use is testing with a bundler-based
+ * test runner (e.g. Vitest): when an app's egg modules are loaded by the loader
+ * via the native `import()` while the test file imports the same source through
+ * the runner's module graph, the two resolve to *different* module instances —
+ * so a class decorated as an egg proto by the loader is not the same class the
+ * test references, and `ctx.getEggObject(ClassRef)` fails with "can not get proto".
+ *
+ * A test runner can inject an importer that routes loading through its own module
+ * graph (e.g. `filePath => import(filePath)` evaluated inside the runner context),
+ * keeping a single module instance. Return value mirrors `await import()`.
+ */
+export type ModuleImporter = (filePath: string) => Promise<unknown>;

tegg/core/loader/src/LoaderUtil.ts

@@ -94,6 +94,16 @@ export class LoaderUtil {
     } catch (e: unknown) {
       throw createLoadError(originalFilePath, e);
     }
+    // Async module importer override (e.g. a Vitest runner that loads the module
+    // through its own module graph), so the proto class registered here is the
+    // same instance the test file imports. See `ModuleImporter` in @eggjs/typings.
+    if (exports == null && typeof globalThis.__EGG_MODULE_IMPORTER__ === 'function') {
+      try {
+        exports = await globalThis.__EGG_MODULE_IMPORTER__(originalFilePath);
+      } catch (e: unknown) {
+        throw createLoadError(originalFilePath, e);
+      }
+    }
     if (exports == null) {
       if (process.platform === 'win32') {
         // convert to file:// url

tegg/core/loader/test/Loader.test.ts

@@ -11,6 +11,7 @@ import { LoaderFactory, LoaderUtil } from '../src/index.ts';
 describe('core/loader/test/Loader.test.ts', () => {
   afterEach(() => {
     globalThis.__EGG_BUNDLE_MODULE_LOADER__ = undefined;
+    globalThis.__EGG_MODULE_IMPORTER__ = undefined;
     LoaderUtil.setConfig({});
   });
 
@@ -92,6 +93,56 @@ describe('core/loader/test/Loader.test.ts', () => {
         },
       );
     });
+
+    it('should load through the async module importer when set', async () => {
+      class ImportedService {}
+      SingletonProto()(ImportedService);
+      const importedFile = '/imported/app/manager/ImportedService.ts';
+      let importerArg: string | undefined;
+      globalThis.__EGG_MODULE_IMPORTER__ = async (filePath: string) => {
+        importerArg = filePath;
+        return { ImportedService };
+      };
+
+      const prototypes = await LoaderUtil.loadFile(importedFile);
+
+      assert.equal(importerArg, importedFile);
+      assert.deepEqual(
+        prototypes.map((proto) => proto.name),
+        ['ImportedService'],
+      );
+      assert.equal(PrototypeUtil.getFilePath(ImportedService), importedFile);
+    });
+
+    it('should fall back to dynamic import when the module importer returns null', async () => {
+      const appRepoFile = path.join(__dirname, './fixtures/modules/module-for-loader/AppRepo.ts');
+      globalThis.__EGG_MODULE_IMPORTER__ = async () => null;
+
+      const prototypes = await LoaderUtil.loadFile(appRepoFile);
+
+      assert.deepEqual(
+        prototypes.map((proto) => proto.name),
+        ['AppRepo', 'AppRepo2'],
+      );
+    });
+
+    it('should wrap module importer errors', async () => {
+      const importedFile = '/imported/app/service.ts';
+      globalThis.__EGG_MODULE_IMPORTER__ = async () => {
+        throw 'importer failed';
+      };
+
+      await assert.rejects(
+        async () => {
+          await LoaderUtil.loadFile(importedFile);
+        },
+        (err: Error & { cause?: unknown }) => {
+          assert.equal(err.message, '[tegg/loader] load /imported/app/service.ts failed: importer failed');
+          assert.equal(err.cause, 'importer failed');
+          return true;
+        },
+      );
+    });
   });
 
   describe('file has tsc error', () => {