@eggjs/utils 5.0.2-beta.2 → 5.0.2-beta.22

package/README.md

@@ -42,6 +42,65 @@ npm i @eggjs/utils
 - {String} baseDir - the current directory of application
 - {String} framework - the directory of framework
 
+### `setBundleModuleLoader(loader)`
+
+Register a module loader hook for bundled Egg apps. The hook runs before the
+normal `importModule()` resolution path.
+
+- {Function | undefined} loader - a synchronous function that receives the
+  original `filepath` argument passed to `importModule()` after POSIX separator
+  normalization, or a virtual specifier. It does not receive the resolved
+  absolute file path from `importResolve()`. Return `undefined` to fall back to
+  the normal import path.
+
+The bundle loader is stored on `globalThis`, so bundled and external copies of
+`@eggjs/utils` share the same loader. Non-`undefined` results follow the same
+default export unwrapping rules as `importModule()`, including
+`importDefaultOnly`.
+
+### Bundle / snapshot module-loading hooks
+
+`importModule()` resolves a module through the following hooks, in order. The
+first one that produces a value wins; otherwise it falls back to the native
+`import()` / `require()` path:
+
+1. **`globalThis.__EGG_BUNDLE_MODULE_LOADER__`** — set via
+   `setBundleModuleLoader()`. Looks up a module already inlined into the bundle
+   (typically a static bundle map emitted by `egg-bundler`). Runs before on-disk
+   resolution and receives the POSIX-normalized `importModule()` filepath or a
+   virtual specifier. Return `undefined` to fall through.
+2. **Snapshot module loader** — set via `setSnapshotModuleLoader()`. This is a
+   module-local hook (not a `globalThis` global) used by the V8 snapshot entry
+   generator to serve pre-bundled modules synchronously, keyed by the resolved
+   path. Once registered it handles every load that reaches it, so the importer
+   below is not consulted while it is active.
+3. **`globalThis.__EGG_MODULE_IMPORTER__`** — an async (or sync, since the value
+   is awaited) importer that receives the resolved file path (the
+   `importResolve()` result, with OS-native separators — not normalized). When
+   set, and the two hooks above did not resolve the module, it replaces the
+   native `await import(filePath)`.
+
+The bundle loader and importer globals are typed in `@eggjs/typings`
+(`BundleModuleLoader` / `ModuleImporter`); import `@eggjs/typings/global` to pick
+up the `declare global` augmentation. These hooks are the contract that
+`egg-bundler`'s generated entry relies on. `@eggjs/core`'s `ManifestLoaderFS`
+consults `__EGG_BUNDLE_MODULE_LOADER__` directly; its importer/native fallback is
+reached through `@eggjs/loader-fs`, which calls back into `importModule()`. The
+tegg loader (`LoaderUtil.loadFile`) consults both globals directly, passing the
+loader filepath with separators normalized to POSIX.
+
+`__EGG_MODULE_IMPORTER__` has two main uses:
+
+- **Bundler-based test runners (e.g. Vitest):** route module loading through the
+  runner's own module graph so the loader and the test file share a single
+  module instance (otherwise `ctx.getEggObject(ClassRef)` fails with
+  "can not get proto").
+- **V8 startup-snapshot restore:** the deserialized main function runs without a
+  host dynamic-import callback, so native `import()` throws. The snapshot entry
+  installs a synchronous `require()`-based importer (`createRequire()` over the
+  bundle output dir); `require()` can load ESM on Node >= 22, so modules resolve
+  without dynamic import.
+
 ## License
 
 [MIT](LICENSE)

package/dist/import.d.ts

@@ -1,3 +1,5 @@
+import { BundleModuleLoader, BundleModuleLoader as BundleModuleLoader$1 } from "@eggjs/typings";
+
 //#region src/import.d.ts
 interface ImportResolveOptions {
   paths?: string[];
@@ -10,6 +12,39 @@ declare function getRequire(): NodeRequire;
 declare function getExtensions(): NodeJS.RequireExtensions;
 declare function isSupportTypeScript(): boolean;
 declare function importResolve(filepath: string, options?: ImportResolveOptions): string;
+/**
+* Module loader function type for V8 snapshot support.
+* Called with the resolved absolute file path, returns the module exports.
+*/
+type SnapshotModuleLoader = (resolvedPath: string) => any;
+/**
+* Register a snapshot module loader that intercepts `importModule()` calls.
+*
+* When set, `importModule()` delegates to this loader instead of calling
+* `import()` or `require()`. This is used by the V8 snapshot entry generator
+* to provide pre-bundled modules — the bundler generates a static module map
+* from the egg manifest and registers it via this API.
+*
+* Also sets `isESM = false` because the snapshot bundle is CJS and
+* esbuild's `import.meta` polyfill causes incorrect ESM detection.
+*
+* Pass `undefined` to clear the loader and restore the auto-detected `isESM`
+* value. Always clear it once snapshot mode is no longer needed (e.g. in test
+* teardown) so the module-level state does not leak into other files when
+* vitest runs with `isolate: false`.
+*/
+declare function setSnapshotModuleLoader(loader: SnapshotModuleLoader | undefined): void;
+/**
+* Register a bundle module loader. Uses globalThis so that bundled and
+* external copies of @eggjs/utils share the same loader.
+*
+* The loader receives a POSIX-normalized filepath or virtual specifier before
+* normal resolution runs. Return `undefined` to fall through to the default
+* import path. Non-undefined hits use the same default unwrapping semantics as
+* normal imports, including `importDefaultOnly` and double-default `__esModule`
+* compatibility.
+*/
+declare function setBundleModuleLoader(loader: BundleModuleLoader | undefined): void;
 declare function importModule(filepath: string, options?: ImportModuleOptions): Promise<any>;
 //#endregion
-export { ImportModuleOptions, ImportResolveOptions, getExtensions, getRequire, importModule, importResolve, isESM, isSupportTypeScript };
+export { type BundleModuleLoader$1 as BundleModuleLoader, ImportModuleOptions, ImportResolveOptions, SnapshotModuleLoader, getExtensions, getRequire, importModule, importResolve, isESM, isSupportTypeScript, setBundleModuleLoader, setSnapshotModuleLoader };

package/dist/import.js

@@ -8,17 +8,30 @@ import { debuglog } from "node:util";
 
 //#region src/import.ts
 const debug = debuglog("egg/utils/import");
+let nativeDynamicImport;
+/* v8 ignore next -- covered by the spawned Node fixture; Vitest cannot instrument this opaque import. */
+function getNativeDynamicImport() {
+	if (!nativeDynamicImport) try {
+		nativeDynamicImport = new Function("specifier", "return import(specifier);");
+	} catch (err) {
+		const error = /* @__PURE__ */ new Error("Native dynamic import fallback for bundled module loader misses requires code generation from strings.");
+		error.cause = err;
+		throw error;
+	}
+	return nativeDynamicImport;
+}
 let isESM = true;
 try {
 	if (typeof import.meta !== "undefined") isESM = true;
 } catch {
 	isESM = false;
 }
+const detectedIsESM = isESM;
 const nodeMajorVersion = parseInt(process.versions.node.split(".", 1)[0], 10);
-const supportImportMetaResolve = nodeMajorVersion >= 18;
+const supportImportMetaResolve = nodeMajorVersion >= 18 && typeof import.meta !== "undefined" && typeof import.meta.resolve === "function";
 let _customRequire;
 function getRequire() {
-	if (!_customRequire) if (typeof __require !== "undefined") _customRequire = __require;
+	if (!_customRequire) if (typeof __require !== "undefined" && __require.extensions) _customRequire = __require;
 	else _customRequire = createRequire(process.cwd());
 	return _customRequire;
 }
@@ -193,6 +206,11 @@ function importResolve(filepath, options) {
 			}
 		}
 	}
+	const bundleModuleLoader = globalThis.__EGG_BUNDLE_MODULE_LOADER__;
+	if (bundleModuleLoader && bundleModuleLoader(normalizeBundleModulePath(filepath)) !== void 0) {
+		debug("[importResolve:bundle] %o => %o", filepath, filepath);
+		return filepath;
+	}
 	const extname = path.extname(filepath);
 	if (!isAbsolute && extname === ".json" || !isESM) moduleFilePath = getRequire().resolve(filepath, { paths });
 	else if (supportImportMetaResolve) {
@@ -205,19 +223,95 @@ function importResolve(filepath, options) {
 		if (moduleFilePath.startsWith("file://")) moduleFilePath = fileURLToPath(moduleFilePath);
 		debug("[importResolve] import.meta.resolve %o => %o", filepath, moduleFilePath);
 		if (!fs.statSync(moduleFilePath, { throwIfNoEntry: false })?.isFile()) throw new TypeError(`Cannot find module ${filepath}, because ${moduleFilePath} does not exists`);
-	} else moduleFilePath = getRequire().resolve(filepath);
+	} else moduleFilePath = getRequire().resolve(filepath, paths ? { paths } : void 0);
 	debug("[importResolve:success] %o, options: %o => %o, isESM: %s", filepath, options, moduleFilePath, isESM);
 	return moduleFilePath;
 }
+let _snapshotModuleLoader;
+/**
+* Register a snapshot module loader that intercepts `importModule()` calls.
+*
+* When set, `importModule()` delegates to this loader instead of calling
+* `import()` or `require()`. This is used by the V8 snapshot entry generator
+* to provide pre-bundled modules — the bundler generates a static module map
+* from the egg manifest and registers it via this API.
+*
+* Also sets `isESM = false` because the snapshot bundle is CJS and
+* esbuild's `import.meta` polyfill causes incorrect ESM detection.
+*
+* Pass `undefined` to clear the loader and restore the auto-detected `isESM`
+* value. Always clear it once snapshot mode is no longer needed (e.g. in test
+* teardown) so the module-level state does not leak into other files when
+* vitest runs with `isolate: false`.
+*/
+function setSnapshotModuleLoader(loader) {
+	_snapshotModuleLoader = loader;
+	isESM = loader ? false : detectedIsESM;
+}
+function normalizeBundleModulePath(filepath) {
+	return filepath.split(path.win32.sep).join(path.posix.sep);
+}
+/**
+* Register a bundle module loader. Uses globalThis so that bundled and
+* external copies of @eggjs/utils share the same loader.
+*
+* The loader receives a POSIX-normalized filepath or virtual specifier before
+* normal resolution runs. Return `undefined` to fall through to the default
+* import path. Non-undefined hits use the same default unwrapping semantics as
+* normal imports, including `importDefaultOnly` and double-default `__esModule`
+* compatibility.
+*/
+function setBundleModuleLoader(loader) {
+	globalThis.__EGG_BUNDLE_MODULE_LOADER__ = loader;
+}
+const _inflightImports = /* @__PURE__ */ new Map();
 async function importModule(filepath, options) {
+	const _bundleModuleLoader = globalThis.__EGG_BUNDLE_MODULE_LOADER__;
+	if (_bundleModuleLoader) {
+		const hit = _bundleModuleLoader(normalizeBundleModulePath(filepath));
+		if (hit !== void 0) {
+			let obj$1 = hit;
+			if (obj$1?.default?.__esModule === true && "default" in obj$1.default) obj$1 = obj$1.default;
+			if (options?.importDefaultOnly && obj$1 && typeof obj$1 === "object" && "default" in obj$1) obj$1 = obj$1.default;
+			return obj$1;
+		}
+	}
 	const moduleFilePath = importResolve(filepath, options);
+	if (_snapshotModuleLoader) {
+		let obj$1 = _snapshotModuleLoader(moduleFilePath);
+		if (obj$1 && typeof obj$1 === "object" && obj$1.default?.__esModule === true && obj$1.default && "default" in obj$1.default) obj$1 = obj$1.default;
+		if (options?.importDefaultOnly) {
+			if (obj$1 && typeof obj$1 === "object" && "default" in obj$1) obj$1 = obj$1.default;
+		}
+		return obj$1;
+	}
+	const _moduleImporter = globalThis.__EGG_MODULE_IMPORTER__;
+	if (_moduleImporter) {
+		let obj$1 = await _moduleImporter(moduleFilePath);
+		if (obj$1 && typeof obj$1 === "object" && obj$1.default?.__esModule === true && obj$1.default && "default" in obj$1.default) obj$1 = obj$1.default;
+		if (options?.importDefaultOnly && obj$1 && typeof obj$1 === "object" && "default" in obj$1) obj$1 = obj$1.default;
+		return obj$1;
+	}
 	let obj;
 	if (isESM) {
 		const fileUrl = pathToFileURL(moduleFilePath).toString();
 		debug("[importModule:start] await import fileUrl: %s, isESM: %s", fileUrl, isESM);
-		obj = await import(fileUrl);
+		/* v8 ignore if -- covered by the spawned Node fixture; Vitest cannot instrument this opaque import. */
+		if (_bundleModuleLoader) obj = await getNativeDynamicImport()(fileUrl);
+		else {
+			let pending = _inflightImports.get(fileUrl);
+			if (pending === void 0) {
+				pending = import(fileUrl);
+				_inflightImports.set(fileUrl, pending);
+				const clearInflight = () => {
+					if (_inflightImports.get(fileUrl) === pending) _inflightImports.delete(fileUrl);
+				};
+				pending.then(clearInflight, clearInflight);
+			}
+			obj = await pending;
+		}
 		debug("[importModule:success] await import %o", fileUrl);
-		if (obj?.default?.__esModule === true && "default" in obj?.default) obj = obj.default;
+		if (obj?.default?.__esModule === true && obj.default && "default" in obj.default) obj = obj.default;
 		if (options?.importDefaultOnly) {
 			if ("default" in obj) obj = obj.default;
 		}
@@ -231,4 +325,4 @@ async function importModule(filepath, options) {
 }
 
 //#endregion
-export { getExtensions, getRequire, importModule, importResolve, isESM, isSupportTypeScript };
+export { getExtensions, getRequire, importModule, importResolve, isESM, isSupportTypeScript, setBundleModuleLoader, setSnapshotModuleLoader };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { getFrameworkOrEggPath } from "./deprecated.js";
 import { getFrameworkPath } from "./framework.js";
 import { findEggCore, getConfig, getLoadUnits, getLoader, getPlugins } from "./plugin.js";
-import { ImportModuleOptions, ImportResolveOptions, getExtensions, getRequire, importModule, importResolve, isESM, isSupportTypeScript } from "./import.js";
+import { BundleModuleLoader, ImportModuleOptions, ImportResolveOptions, SnapshotModuleLoader, getExtensions, getRequire, importModule, importResolve, isESM, isSupportTypeScript, setBundleModuleLoader, setSnapshotModuleLoader } from "./import.js";
 import { ImportResolveError } from "./error/ImportResolveError.js";
 
 //#region src/index.d.ts
@@ -25,4 +25,4 @@ type EggType = (typeof EggType)[keyof typeof EggType];
 */
 declare function detectType(baseDir: string): Promise<keyof typeof EggType>;
 //#endregion
-export { EggType, ImportModuleOptions, ImportResolveError, ImportResolveOptions, _default as default, detectType, findEggCore, getConfig, getExtensions, getFrameworkOrEggPath, getFrameworkPath, getLoadUnits, getLoader, getPlugins, getRequire, importModule, importResolve, isESM, isSupportTypeScript };
+export { BundleModuleLoader, EggType, ImportModuleOptions, ImportResolveError, ImportResolveOptions, SnapshotModuleLoader, _default as default, detectType, findEggCore, getConfig, getExtensions, getFrameworkOrEggPath, getFrameworkPath, getLoadUnits, getLoader, getPlugins, getRequire, importModule, importResolve, isESM, isSupportTypeScript, setBundleModuleLoader, setSnapshotModuleLoader };

package/dist/index.js

@@ -1,6 +1,6 @@
 import { getFrameworkOrEggPath } from "./deprecated.js";
 import { ImportResolveError } from "./error/ImportResolveError.js";
-import { getExtensions, getRequire, importModule, importResolve, isESM, isSupportTypeScript } from "./import.js";
+import { getExtensions, getRequire, importModule, importResolve, isESM, isSupportTypeScript, setBundleModuleLoader, setSnapshotModuleLoader } from "./import.js";
 import { getFrameworkPath } from "./framework.js";
 import { findEggCore, getConfig, getLoadUnits, getLoader, getPlugins } from "./plugin.js";
 import fs from "node:fs/promises";
@@ -42,4 +42,4 @@ async function detectType(baseDir) {
 }
 
 //#endregion
-export { EggType, ImportResolveError, src_default as default, detectType, findEggCore, getConfig, getExtensions, getFrameworkOrEggPath, getFrameworkPath, getLoadUnits, getLoader, getPlugins, getRequire, importModule, importResolve, isESM, isSupportTypeScript };
+export { EggType, ImportResolveError, src_default as default, detectType, findEggCore, getConfig, getExtensions, getFrameworkOrEggPath, getFrameworkPath, getLoadUnits, getLoader, getPlugins, getRequire, importModule, importResolve, isESM, isSupportTypeScript, setBundleModuleLoader, setSnapshotModuleLoader };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eggjs/utils",
-  "version": "5.0.2-beta.2",
+  "version": "5.0.2-beta.22",
   "description": "Utils for all egg projects",
   "keywords": [
     "egg",
@@ -26,9 +26,18 @@
     "./package.json": "./package.json"
   },
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "exports": {
+      ".": "./dist/index.js",
+      "./package.json": "./package.json"
+    }
+  },
+  "scripts": {
+    "typecheck": "tsgo --noEmit"
+  },
+  "dependencies": {
+    "@eggjs/typings": "4.1.2-beta.22"
   },
-  "dependencies": {},
   "devDependencies": {
     "coffee": "5",
     "mm": "^4.0.2",
@@ -37,8 +46,5 @@
   },
   "engines": {
     "node": ">=22.18.0"
-  },
-  "scripts": {
-    "typecheck": "tsgo --noEmit"
   }
-}
+}