@eggjs/typings 4.1.2-beta.16 → 4.1.2-beta.17

package/dist/global.d.ts

@@ -4,4 +4,11 @@ import { BundleModuleLoader, ModuleImporter } from "./index.js";
 declare global {
   var __EGG_BUNDLE_MODULE_LOADER__: BundleModuleLoader | undefined;
   var __EGG_MODULE_IMPORTER__: ModuleImporter | undefined;
+  /**
+  * Synchronous require bound to the bundle output directory, installed by the
+  * snapshot restore main function. The snapshot prelude / lazy mechanism uses it
+  * to pull in modules through `require()` (Node 22+ can `require()` ESM) because a
+  * deserialized snapshot process has no dynamic `import()` callback.
+  */
+  var __RUNTIME_REQUIRE: ((id: string) => unknown) | undefined;
 }

package/dist/index.d.ts

@@ -1,24 +1,56 @@
 //#region src/index.d.ts
 /**
-* Module loader for bundled Egg apps. Called with the `importModule()` filepath
-* after POSIX path normalization. Return `undefined` to fall through to the
-* standard import path.
+* Module loader for bundled Egg apps, registered on `globalThis` as
+* `__EGG_BUNDLE_MODULE_LOADER__` (use `setBundleModuleLoader()` from
+* `@eggjs/utils`). This is the highest-priority hook: it runs before on-disk
+* resolution in both `importModule()` / `importResolve()` (`@eggjs/utils`) and
+* the loaders in `@eggjs/core` and the tegg loader.
+*
+* It is called with the `importModule()` filepath (or a virtual specifier)
+* after POSIX path normalization, and is meant to return a module already
+* inlined into the bundle — typically a lookup into a static bundle map emitted
+* by `egg-bundler`. Return `undefined` to fall through to the next hook (the
+* snapshot loader registered via `setSnapshotModuleLoader()`, then
+* `__EGG_MODULE_IMPORTER__`) or the standard `import()` / `require()` path.
+*
+* The non-undefined return value follows the same default-export unwrapping
+* rules as a native import (double-default `__esModule` compatibility plus the
+* caller's `importDefaultOnly` option).
 */
 type BundleModuleLoader = (filepath: string) => unknown;
 /**
-* Async module importer override for the tegg loader's file loading.
+* Async module importer override, registered on `globalThis` as
+* `__EGG_MODULE_IMPORTER__`. When set (and neither the bundle loader nor a
+* snapshot loader registered via `setSnapshotModuleLoader()` already resolved
+* the path), `importModule()` / the loaders delegate module loading to this
+* importer instead of the built-in `await import(filePath)`. The return value
+* is awaited and mirrors `await import()` (default unwrapping and
+* `importDefaultOnly` apply); because it is awaited, a synchronous return value
+* such as the result of `require()` is also valid.
+*
+* The path passed in depends on the caller: `@eggjs/utils` `importModule()`
+* passes the resolved module path from `importResolve()` (OS-native separators,
+* not normalized), while the tegg loader passes the original loader filepath
+* with separators normalized to POSIX. Importers that care about separators
+* should normalize defensively.
+*
+* Two main uses:
 *
-* 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".
+* 1. 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
+*    injects 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.
 *
-* 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()`.
+* 2. V8 startup-snapshot restore: the deserialized main function runs without a
+*    host dynamic-import callback, so native `import()` throws. The snapshot
+*    entry generated by `egg-bundler` 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.
 */
 type ModuleImporter = (filePath: string) => Promise<unknown>;
 //#endregion

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eggjs/typings",
-  "version": "4.1.2-beta.16",
+  "version": "4.1.2-beta.17",
   "description": "Shared typings for egg projects",
   "keywords": [
     "egg",
@@ -36,7 +36,7 @@
   "dependencies": {},
   "devDependencies": {
     "typescript": "^5.9.3",
-    "@eggjs/tsconfig": "3.1.2-beta.16"
+    "@eggjs/tsconfig": "3.1.2-beta.17"
   },
   "engines": {
     "node": ">=22.18.0"