@eggjs/core 7.0.2-beta.2 → 7.0.2-beta.22

package/dist/egg.d.ts

@@ -4,6 +4,7 @@ import { Timing } from "./utils/timing.js";
 import { Lifecycle } from "./lifecycle.js";
 import { EggAppConfig } from "./types.js";
 import { EggLoader } from "./loader/egg_loader.js";
+import { LoaderFS } from "./loader/loader_fs.js";
 import { SingletonCreateMethod } from "./singleton.js";
 import { Application as KoaApplication, Context as KoaContext, MiddlewareFunc as KoaMiddlewareFunc, Next, Request as KoaRequest, Response as KoaResponse } from "@eggjs/koa";
 import { EggRouter as Router, RegisterOptions, ResourcesController } from "@eggjs/router";
@@ -18,6 +19,18 @@ interface EggCoreOptions {
   plugins?: any;
   serverScope?: string;
   env?: string;
+  /** Skip lifecycle hooks, only trigger loadMetadata for manifest generation */
+  metadataOnly?: boolean;
+  /** Loader-facing filesystem abstraction */
+  loaderFS?: LoaderFS;
+  /**
+  * When true, lifecycle stops after the `configWillLoad` phase.
+  * `configDidLoad`, `didLoad`, `willReady`, `didReady`, and `serverDidReady`
+  * are skipped. Used for V8 startup snapshot construction — SDKs typically
+  * execute during `configDidLoad`, opening connections and starting timers
+  * which are not serializable. Analogous to `metadataOnly` mode.
+  */
+  snapshot?: boolean;
 }
 type EggCoreInitOptions = Partial<EggCoreOptions>;
 declare class Request$1 extends KoaRequest {
@@ -197,6 +210,18 @@ declare class EggCore extends KoaApplication {
   */
   beforeClose(fn: Fun, name?: string): void;
   /**
+  * Trigger snapshotWillSerialize lifecycle hooks on all boots in reverse order.
+  * Called by the build script before V8 serializes the heap.
+  * Cleans up non-serializable resources: file handles, timers, listeners, connections.
+  */
+  triggerSnapshotWillSerialize(): Promise<void>;
+  /**
+  * Trigger snapshotDidDeserialize lifecycle hooks on all boots in forward order.
+  * Called by the restore entry after V8 deserializes the heap.
+  * Restores non-serializable resources and resumes the lifecycle from configDidLoad.
+  */
+  triggerSnapshotDidDeserialize(): Promise<void>;
+  /**
   * Close all, it will close
   * - callbacks registered by beforeClose
   * - emit `close` event

package/dist/egg.js

@@ -107,7 +107,8 @@ var EggCore = class EggCore extends KoaApplication {
 		this.lifecycle = new Lifecycle({
 			baseDir: options.baseDir,
 			app: this,
-			logger: this.console
+			logger: this.console,
+			snapshot: options.snapshot
 		});
 		this.lifecycle.on("error", (err) => this.emit("error", err));
 		this.lifecycle.on("ready_timeout", (id) => this.emit("ready_timeout", id));
@@ -130,7 +131,9 @@ var EggCore = class EggCore extends KoaApplication {
 			logger: this.console,
 			serverScope: options.serverScope,
 			env: options.env ?? "",
-			EggCoreClass: EggCore
+			EggCoreClass: EggCore,
+			metadataOnly: options.metadataOnly,
+			loaderFS: options.loaderFS
 		});
 	}
 	get logger() {
@@ -274,6 +277,22 @@ var EggCore = class EggCore extends KoaApplication {
 		this.lifecycle.registerBeforeClose(fn, name);
 	}
 	/**
+	* Trigger snapshotWillSerialize lifecycle hooks on all boots in reverse order.
+	* Called by the build script before V8 serializes the heap.
+	* Cleans up non-serializable resources: file handles, timers, listeners, connections.
+	*/
+	async triggerSnapshotWillSerialize() {
+		return this.lifecycle.triggerSnapshotWillSerialize();
+	}
+	/**
+	* Trigger snapshotDidDeserialize lifecycle hooks on all boots in forward order.
+	* Called by the restore entry after V8 deserializes the heap.
+	* Restores non-serializable resources and resumes the lifecycle from configDidLoad.
+	*/
+	async triggerSnapshotDidDeserialize() {
+		return this.lifecycle.triggerSnapshotDidDeserialize();
+	}
+	/**
 	* Close all, it will close
 	* - callbacks registered by beforeClose
 	* - emit `close` event

package/dist/index.d.ts

@@ -3,10 +3,14 @@ import { BaseContextClass } from "./base_context_class.js";
 import { Timing, TimingItem } from "./utils/timing.js";
 import { BootImplClass, FunWithFullPath, ILifecycleBoot, Lifecycle, LifecycleOptions } from "./lifecycle.js";
 import { CustomLoaderConfigItem, EggAppConfig, EggAppInfo, EggPluginInfo } from "./types.js";
+import { ManifestGenerateOptions, ManifestInvalidation, ManifestStore, StartupManifest } from "./loader/manifest.js";
 import { CaseStyle, CaseStyleFunction, EXPORTS, FULLPATH, FileLoader, FileLoaderFilter, FileLoaderInitializer, FileLoaderOptions, FileLoaderParseItem } from "./loader/file_loader.js";
 import { ClassLoader, ClassLoaderOptions, ContextLoader, ContextLoaderOptions } from "./loader/context_loader.js";
 import { EggDirInfo, EggDirInfoType, EggLoader, EggLoaderOptions } from "./loader/egg_loader.js";
+import { ManifestLoaderFS } from "./loader/loader_fs.js";
 import { Singleton, SingletonCreateMethod, SingletonOptions } from "./singleton.js";
 import { Context, EGG_LOADER, EggCore, EggCoreInitOptions, EggCoreOptions, KoaApplication, KoaContext, KoaMiddlewareFunc, KoaRequest, KoaResponse, MiddlewareFunc, Next, Request, Response, Router } from "./egg.js";
 import { SequencifyResult, SequencifyTask, sequencify } from "./utils/sequencify.js";
-export { BaseContextClass, BootImplClass, CaseStyle, CaseStyleFunction, ClassLoader, ClassLoaderOptions, Context, ContextLoader, ContextLoaderOptions, CustomLoaderConfigItem, EGG_LOADER, EXPORTS, EggAppConfig, EggAppInfo, EggCore, EggCoreInitOptions, EggCoreOptions, EggDirInfo, EggDirInfoType, EggLoader, EggLoaderOptions, EggPluginInfo, FULLPATH, FileLoader, FileLoaderFilter, FileLoaderInitializer, FileLoaderOptions, FileLoaderParseItem, FunWithFullPath, ILifecycleBoot, KoaApplication, KoaContext, KoaMiddlewareFunc, KoaRequest, KoaResponse, Lifecycle, LifecycleOptions, MiddlewareFunc, Next, Request, Response, Router, SequencifyResult, SequencifyTask, Singleton, SingletonCreateMethod, SingletonOptions, Timing, TimingItem, sequencify, utils };
+import "@eggjs/typings/global";
+export * from "@eggjs/loader-fs";
+export { BaseContextClass, BootImplClass, CaseStyle, CaseStyleFunction, ClassLoader, ClassLoaderOptions, Context, ContextLoader, ContextLoaderOptions, CustomLoaderConfigItem, EGG_LOADER, EXPORTS, EggAppConfig, EggAppInfo, EggCore, EggCoreInitOptions, EggCoreOptions, EggDirInfo, EggDirInfoType, EggLoader, EggLoaderOptions, EggPluginInfo, FULLPATH, FileLoader, FileLoaderFilter, FileLoaderInitializer, FileLoaderOptions, FileLoaderParseItem, FunWithFullPath, ILifecycleBoot, KoaApplication, KoaContext, KoaMiddlewareFunc, KoaRequest, KoaResponse, Lifecycle, LifecycleOptions, ManifestGenerateOptions, ManifestInvalidation, ManifestLoaderFS, ManifestStore, MiddlewareFunc, Next, Request, Response, Router, SequencifyResult, SequencifyTask, Singleton, SingletonCreateMethod, SingletonOptions, StartupManifest, Timing, TimingItem, sequencify, utils };

package/dist/index.js

@@ -5,8 +5,13 @@ import { sequencify } from "./utils/sequencify.js";
 import { Timing } from "./utils/timing.js";
 import { CaseStyle, EXPORTS, FULLPATH, FileLoader } from "./loader/file_loader.js";
 import { ClassLoader, ContextLoader } from "./loader/context_loader.js";
+import { ManifestStore } from "./loader/manifest.js";
 import { EggLoader } from "./loader/egg_loader.js";
 import { Singleton } from "./singleton.js";
 import { Context, EGG_LOADER, EggCore, KoaApplication, KoaContext, KoaRequest, KoaResponse, Request, Response, Router } from "./egg.js";
+import { ManifestLoaderFS } from "./loader/loader_fs.js";
+import "@eggjs/typings/global";
 
-export { BaseContextClass, CaseStyle, ClassLoader, Context, ContextLoader, EGG_LOADER, EXPORTS, EggCore, EggLoader, FULLPATH, FileLoader, KoaApplication, KoaContext, KoaRequest, KoaResponse, Lifecycle, Request, Response, Router, Singleton, Timing, sequencify, utils_default as utils };
+export * from "@eggjs/loader-fs"
+
+export { BaseContextClass, CaseStyle, ClassLoader, Context, ContextLoader, EGG_LOADER, EXPORTS, EggCore, EggLoader, FULLPATH, FileLoader, KoaApplication, KoaContext, KoaRequest, KoaResponse, Lifecycle, ManifestLoaderFS, ManifestStore, Request, Response, Router, Singleton, Timing, sequencify, utils_default as utils };

package/dist/lifecycle.d.ts

@@ -40,12 +40,42 @@ interface ILifecycleBoot {
   * Do some thing before app close
   */
   beforeClose?(): Promise<void>;
+  /**
+  * Collect metadata for manifest generation (metadataOnly mode).
+  * Called instead of configWillLoad/configDidLoad/didLoad/willReady
+  * when the application is started with metadataOnly: true.
+  */
+  loadMetadata?(): Promise<void> | void;
+  /**
+  * Called before V8 serializes the heap for startup snapshot.
+  * Clean up non-serializable resources: close file handles, clear timers,
+  * remove process listeners, close network connections.
+  * Executed in REVERSE registration order (like beforeClose).
+  */
+  snapshotWillSerialize?(): Promise<void> | void;
+  /**
+  * Called after V8 deserializes the heap from a startup snapshot.
+  * Restore non-serializable resources: reopen file handles, recreate timers,
+  * re-register process listeners, reinitialize connections.
+  * Executed in FORWARD registration order (like configWillLoad).
+  * After all hooks complete, the normal lifecycle resumes from configDidLoad.
+  */
+  snapshotDidDeserialize?(): Promise<void> | void;
 }
 type BootImplClass<T = ILifecycleBoot> = new (...args: any[]) => T;
 interface LifecycleOptions {
   baseDir: string;
   app: EggCore;
   logger: EggConsoleLogger;
+  /**
+  * When true, the lifecycle stops after configWillLoad phase completes.
+  * configDidLoad, didLoad, willReady, didReady, and serverDidReady hooks
+  * are NOT called. Used for V8 startup snapshot construction — SDKs
+  * typically execute during configDidLoad, opening connections and starting
+  * timers which are not serializable. The handling is analogous to
+  * metadataOnly mode: both short-circuit the lifecycle chain early.
+  */
+  snapshot?: boolean;
 }
 type FunWithFullPath = Fun & {
   fullPath?: string;
@@ -60,6 +90,18 @@ declare class Lifecycle extends EventEmitter {
   ready(): Promise<void>;
   ready(flagOrFunction: ReadyFunctionArg): void;
   get app(): EggCore;
+  /**
+  * Whether `close()` has finished. Useful to guard lazy work (logger creation,
+  * close-hook registration) that may run after the app/agent was torn down.
+  */
+  get isClosed(): boolean;
+  /**
+  * Whether `close()` is currently running (started but not yet finished). A
+  * close hook registered during this window would be added after the close
+  * callback snapshot is taken and would never run, so `registerBeforeClose()`
+  * also refuses registration while closing.
+  */
+  get isClosing(): boolean;
   get logger(): EggConsoleLogger;
   get timing(): Timing;
   legacyReadyCallback(name: string, opt?: object): (...args: unknown[]) => void;
@@ -70,7 +112,12 @@ declare class Lifecycle extends EventEmitter {
   */
   init(): void;
   registerBeforeStart(scope: Fun, name: string): void;
-  registerBeforeClose(fn: FunWithFullPath, fullPath?: string): void;
+  /**
+  * Register a function to run during `close()`. Returns `false` when the
+  * registration is refused because the app/agent is already closing or closed
+  * (the hook would never run); `true` otherwise.
+  */
+  registerBeforeClose(fn: FunWithFullPath, fullPath?: string): boolean;
   close(): Promise<void>;
   triggerConfigWillLoad(): void;
   triggerConfigDidLoad(): void;
@@ -78,6 +125,20 @@ declare class Lifecycle extends EventEmitter {
   triggerWillReady(): void;
   triggerDidReady(err?: Error): Promise<void>;
   triggerServerDidReady(): Promise<void>;
+  triggerLoadMetadata(): Promise<void>;
+  /**
+  * Trigger snapshotWillSerialize on all boots in REVERSE order.
+  * Called by the build script before V8 serializes the heap.
+  */
+  triggerSnapshotWillSerialize(): Promise<void>;
+  /**
+  * Trigger snapshotDidDeserialize on all boots in FORWARD order.
+  * Called by the restore entry after V8 deserializes the heap.
+  * After all hooks complete, resets the ready state and resumes the normal
+  * lifecycle from configDidLoad. The returned promise resolves when the
+  * full lifecycle (configDidLoad → didLoad → willReady) has completed.
+  */
+  triggerSnapshotDidDeserialize(): Promise<void>;
 }
 //#endregion
 export { BootImplClass, FunWithFullPath, ILifecycleBoot, Lifecycle, LifecycleOptions };

package/dist/lifecycle.js

@@ -15,6 +15,9 @@ var Lifecycle = class extends EventEmitter {
 	#bootHooks;
 	#boots;
 	#isClosed;
+	#isClosing;
+	#metadataOnly;
+	#snapshotBuilding;
 	#closeFunctionSet;
 	loadReady;
 	bootReady;
@@ -29,6 +32,9 @@ var Lifecycle = class extends EventEmitter {
 		this.#boots = [];
 		this.#closeFunctionSet = /* @__PURE__ */ new Set();
 		this.#isClosed = false;
+		this.#isClosing = false;
+		this.#metadataOnly = false;
+		this.#snapshotBuilding = false;
 		this.#init = false;
 		this.timing.start(`${this.options.app.type} Start`);
 		const eggReadyTimeoutEnv = Number.parseInt(process.env.EGG_READY_TIMEOUT_ENV || "10000");
@@ -41,7 +47,7 @@ var Lifecycle = class extends EventEmitter {
 			this.logger.warn("[egg/core/lifecycle:ready_timeout] %s seconds later %s was still unable to finish.", this.readyTimeout / 1e3, id);
 		});
 		this.ready((err) => {
-			this.triggerDidReady(err);
+			if (!this.#metadataOnly && !this.options.snapshot) this.triggerDidReady(err);
 			debug("app ready");
 			this.timing.end(`${this.options.app.type} Start`);
 		});
@@ -53,6 +59,22 @@ var Lifecycle = class extends EventEmitter {
 	get app() {
 		return this.options.app;
 	}
+	/**
+	* Whether `close()` has finished. Useful to guard lazy work (logger creation,
+	* close-hook registration) that may run after the app/agent was torn down.
+	*/
+	get isClosed() {
+		return this.#isClosed;
+	}
+	/**
+	* Whether `close()` is currently running (started but not yet finished). A
+	* close hook registered during this window would be added after the close
+	* callback snapshot is taken and would never run, so `registerBeforeClose()`
+	* also refuses registration while closing.
+	*/
+	get isClosing() {
+		return this.#isClosing;
+	}
 	get logger() {
 		return this.options.logger;
 	}
@@ -117,20 +139,35 @@ var Lifecycle = class extends EventEmitter {
 			scopeFullName: name
 		});
 	}
+	/**
+	* Register a function to run during `close()`. Returns `false` when the
+	* registration is refused because the app/agent is already closing or closed
+	* (the hook would never run); `true` otherwise.
+	*/
 	registerBeforeClose(fn, fullPath) {
 		assert(typeof fn === "function", "argument should be function");
-		assert(this.#isClosed === false, "app has been closed");
+		if (this.#isClosing || this.#isClosed) {
+			debug("%s skip registerBeforeClose at %o, app is closing or has been closed", this.app.type, fullPath);
+			return false;
+		}
 		if (fullPath) fn.fullPath = fullPath;
 		this.#closeFunctionSet.add(fn);
 		debug("%s register beforeClose at %o, count: %d", this.app.type, fullPath, this.#closeFunctionSet.size);
+		return true;
 	}
 	async close() {
-		const closeFns = Array.from(this.#closeFunctionSet);
-		debug("%s start trigger %d beforeClose functions", this.app.type, closeFns.length);
-		for (const fn of closeFns.reverse()) {
-			debug("%s trigger beforeClose at %o", this.app.type, fn.fullPath);
-			await utils_default.callFn(fn);
-			this.#closeFunctionSet.delete(fn);
+		this.#isClosing = true;
+		if (this.#metadataOnly || this.#snapshotBuilding) {
+			debug("%s skip beforeClose functions in early-exit lifecycle mode", this.app.type);
+			this.#closeFunctionSet.clear();
+		} else {
+			const closeFns = Array.from(this.#closeFunctionSet);
+			debug("%s start trigger %d beforeClose functions", this.app.type, closeFns.length);
+			for (const fn of closeFns.reverse()) {
+				debug("%s trigger beforeClose at %o", this.app.type, fn.fullPath);
+				await utils_default.callFn(fn);
+				this.#closeFunctionSet.delete(fn);
+			}
 		}
 		this.app.emit("close");
 		this.removeAllListeners();
@@ -145,6 +182,12 @@ var Lifecycle = class extends EventEmitter {
 			boot.configWillLoad();
 		}
 		debug("trigger configWillLoad end");
+		if (this.options.snapshot) {
+			debug("snapshot mode: stopping after configWillLoad, skipping configDidLoad and later phases");
+			this.#snapshotBuilding = true;
+			this.loadReady.start();
+			return;
+		}
 		this.triggerConfigDidLoad();
 	}
 	triggerConfigDidLoad() {
@@ -221,6 +264,85 @@ var Lifecycle = class extends EventEmitter {
 			debug("trigger serverDidReady end");
 		})();
 	}
+	async triggerLoadMetadata() {
+		this.#metadataOnly = true;
+		debug("trigger loadMetadata start");
+		let firstError;
+		for (const boot of this.#boots) if (typeof boot.loadMetadata === "function") {
+			debug("trigger loadMetadata at %o", boot.fullPath);
+			try {
+				await boot.loadMetadata();
+			} catch (err) {
+				const error = err instanceof Error ? err : new Error(String(err));
+				if (!firstError) firstError = error;
+				debug("trigger loadMetadata error at %o, error: %s", boot.fullPath, error);
+				this.emit("error", error);
+			}
+		}
+		debug("trigger loadMetadata end");
+		this.ready(firstError ?? true);
+	}
+	/**
+	* Trigger snapshotWillSerialize on all boots in REVERSE order.
+	* Called by the build script before V8 serializes the heap.
+	*/
+	async triggerSnapshotWillSerialize() {
+		if (!this.options.snapshot) throw new Error("triggerSnapshotWillSerialize() can only be called on a snapshot-mode lifecycle");
+		debug("trigger snapshotWillSerialize start");
+		const boots = [...this.#boots].reverse();
+		for (const boot of boots) {
+			if (typeof boot.snapshotWillSerialize !== "function") continue;
+			const fullPath = boot.fullPath ?? "unknown";
+			debug("trigger snapshotWillSerialize at %o", fullPath);
+			const timingKey = `Snapshot Will Serialize in ${utils_default.getResolvedFilename(fullPath, this.app.baseDir)}`;
+			this.timing.start(timingKey);
+			try {
+				await utils_default.callFn(boot.snapshotWillSerialize.bind(boot));
+			} catch (err) {
+				debug("trigger snapshotWillSerialize error at %o, error: %s", fullPath, err);
+				this.timing.end(timingKey);
+				throw err;
+			}
+			this.timing.end(timingKey);
+		}
+		debug("trigger snapshotWillSerialize end");
+	}
+	/**
+	* Trigger snapshotDidDeserialize on all boots in FORWARD order.
+	* Called by the restore entry after V8 deserializes the heap.
+	* After all hooks complete, resets the ready state and resumes the normal
+	* lifecycle from configDidLoad. The returned promise resolves when the
+	* full lifecycle (configDidLoad → didLoad → willReady) has completed.
+	*/
+	async triggerSnapshotDidDeserialize() {
+		if (!this.options.snapshot) throw new Error("triggerSnapshotDidDeserialize() can only be called on a snapshot-mode lifecycle");
+		debug("trigger snapshotDidDeserialize start");
+		for (const boot of this.#boots) {
+			if (typeof boot.snapshotDidDeserialize !== "function") continue;
+			const fullPath = boot.fullPath ?? "unknown";
+			debug("trigger snapshotDidDeserialize at %o", fullPath);
+			const timingKey = `Snapshot Did Deserialize in ${utils_default.getResolvedFilename(fullPath, this.app.baseDir)}`;
+			this.timing.start(timingKey);
+			try {
+				await utils_default.callFn(boot.snapshotDidDeserialize.bind(boot));
+			} catch (err) {
+				debug("trigger snapshotDidDeserialize error at %o, error: %s", fullPath, err);
+				this.timing.end(timingKey);
+				throw err;
+			}
+			this.timing.end(timingKey);
+		}
+		debug("trigger snapshotDidDeserialize end");
+		this.#snapshotBuilding = false;
+		this.#readyObject = new Ready();
+		this.#initReady();
+		this.ready((err) => {
+			this.triggerDidReady(err);
+			debug("app ready after snapshot deserialize");
+		});
+		this.triggerConfigDidLoad();
+		await this.ready();
+	}
 	#initReady() {
 		debug("loadReady init");
 		this.loadReady = new Ready$1({
@@ -232,6 +354,7 @@ var Lifecycle = class extends EventEmitter {
 			debug("loadReady end, err: %o", err);
 			debug("trigger didLoad end");
 			if (err) this.ready(err);
+			else if (this.#snapshotBuilding) this.ready(true);
 			else this.triggerWillReady();
 		});
 		debug("bootReady init");

package/dist/loader/egg_loader.d.ts

@@ -1,10 +1,12 @@
 import { Timing } from "../utils/timing.js";
 import { Lifecycle } from "../lifecycle.js";
 import { EggAppConfig, EggAppInfo, EggPluginInfo } from "../types.js";
+import { ManifestStore, StartupManifest } from "./manifest.js";
 import { FileLoader, FileLoaderOptions } from "./file_loader.js";
 import { ContextLoader, ContextLoaderOptions } from "./context_loader.js";
 import { EggCore } from "../egg.js";
 import { Logger } from "egg-logger";
+import { LoaderFS } from "@eggjs/loader-fs";
 
 //#region src/loader/egg_loader.d.ts
 interface EggLoaderOptions {
@@ -21,6 +23,10 @@ interface EggLoaderOptions {
   serverScope?: string;
   /** custom plugins */
   plugins?: Record<string, EggPluginInfo>;
+  /** Skip lifecycle hooks, only trigger loadMetadata for manifest generation */
+  metadataOnly?: boolean;
+  /** Loader-facing filesystem abstraction */
+  loaderFS?: LoaderFS;
 }
 type EggDirInfoType = "app" | "plugin" | "framework";
 interface EggDirInfo {
@@ -36,7 +42,11 @@ declare class EggLoader {
   readonly serverEnv: string;
   readonly serverScope: string;
   readonly appInfo: EggAppInfo;
+  readonly outDir?: string;
   dirs?: EggDirInfo[];
+  /** Startup manifest — loaded from cache or collecting for generation */
+  readonly manifest: ManifestStore;
+  readonly loaderFS: LoaderFS;
   /**
   * @class
   * @param {Object} options - options
@@ -368,6 +378,11 @@ declare class EggLoader {
   get ContextLoader(): typeof ContextLoader;
   getTypeFiles(filename: string): string[];
   resolveModule(filepath: string): string | undefined;
+  /**
+  * Generate startup manifest from collected data.
+  * Should be called after all loading phases complete.
+  */
+  generateManifest(): StartupManifest;
 }
 //#endregion
 export { EggDirInfo, EggDirInfoType, EggLoader, EggLoaderOptions };