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

package/dist/global.d.ts

@@ -4,4 +4,26 @@ 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. It also carries
+  * a `resolve` (the underlying `createRequire(...).resolve`) so the web globals
+  * re-installer can locate `undici` through the app dependency tree.
+  */
+  var __RUNTIME_REQUIRE: (((id: string) => unknown) & {
+    resolve?: (id: string, options?: {
+      paths?: string[];
+    }) => string;
+  }) | undefined;
+  /**
+  * Re-install the web globals (`fetch`/`Headers`/.../`Blob`/`File`) that the snapshot
+  * prelude replaces with stubs at build time, as lazy accessors backed by `undici`
+  * (the fetch family) and `node:buffer` (`Blob`/`File`). Defined by the snapshot
+  * prelude and serialized into the blob; the snapshot restore main calls it once
+  * `__RUNTIME_REQUIRE` is installed, so an app that uses `globalThis.fetch` keeps
+  * working after a restore.
+  */
+  var __installWebGlobalsLazy: (() => void) | 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.19",
   "description": "Shared typings for egg projects",
   "keywords": [
     "egg",
@@ -31,17 +31,22 @@
     "./package.json": "./package.json"
   },
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "exports": {
+      ".": "./dist/index.js",
+      "./global": "./dist/global.js",
+      "./package.json": "./package.json"
+    }
+  },
+  "scripts": {
+    "typecheck": "tsgo --noEmit"
   },
   "dependencies": {},
   "devDependencies": {
-    "typescript": "^5.9.3",
-    "@eggjs/tsconfig": "3.1.2-beta.16"
+    "@eggjs/tsconfig": "3.1.2-beta.19",
+    "typescript": "^5.9.3"
   },
   "engines": {
     "node": ">=22.18.0"
-  },
-  "scripts": {
-    "typecheck": "tsgo --noEmit"
   }
-}
+}

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2017-present Alibaba Group Holding Limited and other contributors.
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.