@eggjs/loader-fs 1.0.0-beta.25 → 1.0.0-beta.26

package/README.md

@@ -11,4 +11,7 @@ const loaderFS: LoaderFS = new RealLoaderFS();
 ```
 
 `LoaderFS` intentionally covers only the operations required by loader code:
-`exists`, `stat`, `realpath`, `readJSON`, `glob`, and `loadFile`.
+`exists`, `stat`, `realpath`, `readJSON`, `glob`, and `loadFile`. A source with
+an authoritative, precomputed directory view may also implement
+`getKnownFiles`; `undefined` means discovery should fall back to `glob`, while
+an empty array means the directory is authoritatively empty.

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+import { LoaderFSManifest, LoaderFSManifestData, ManifestLoaderFS } from "./manifest_loader_fs.js";
 import { Stats } from "node:fs";
 import globby from "globby";
 
@@ -8,6 +9,12 @@ interface LoaderFS {
   stat(filepath: string): Stats;
   realpath(filepath: string): string;
   readJSON<T = unknown>(filepath: string): T;
+  /**
+  * Return an authoritative, precomputed file list for a directory when one is
+  * available. `undefined` means the source has no precomputed view and callers
+  * should fall back to normal discovery; an empty array is authoritative.
+  */
+  getKnownFiles?(directory: string): readonly string[] | undefined;
   glob(patterns: string | string[], options?: LoaderFSGlobOptions): string[];
   loadFile(filepath: string): Promise<unknown>;
 }
@@ -20,4 +27,4 @@ declare class RealLoaderFS implements LoaderFS {
   loadFile(filepath: string): Promise<unknown>;
 }
 //#endregion
-export { LoaderFS, LoaderFSGlobOptions, RealLoaderFS };
+export { LoaderFS, LoaderFSGlobOptions, type LoaderFSManifest, type LoaderFSManifestData, ManifestLoaderFS, RealLoaderFS };

package/dist/index.js

@@ -1,3 +1,4 @@
+import { ManifestLoaderFS } from "./manifest_loader_fs.js";
 import BuiltinModule from "node:module";
 import fs from "node:fs";
 import path from "node:path";
@@ -63,4 +64,4 @@ var RealLoaderFS = class {
 };
 
 //#endregion
-export { RealLoaderFS };
+export { ManifestLoaderFS, RealLoaderFS };

package/dist/manifest_loader_fs.d.ts

@@ -0,0 +1,28 @@
+import { LoaderFS, LoaderFSGlobOptions } from "./index.js";
+import { Stats } from "node:fs";
+
+//#region src/manifest_loader_fs.d.ts
+interface LoaderFSManifestData {
+  /** resolveModule cache: relative filepath -> resolved relative path | null */
+  resolveCache: Record<string, string | null>;
+  /** relative directory path -> file paths relative to that directory */
+  fileDiscovery: Record<string, string[]>;
+}
+/** Host-neutral manifest view consumed by ManifestLoaderFS. */
+interface LoaderFSManifest {
+  readonly baseDir: string;
+  readonly data: LoaderFSManifestData;
+}
+declare class ManifestLoaderFS implements LoaderFS {
+  #private;
+  constructor(manifest: LoaderFSManifest, fallback?: LoaderFS);
+  exists(filepath: string): boolean;
+  stat(filepath: string): Stats;
+  realpath(filepath: string): string;
+  readJSON<T = unknown>(filepath: string): T;
+  getKnownFiles(directory: string): readonly string[] | undefined;
+  glob(patterns: string | string[], options?: LoaderFSGlobOptions): string[];
+  loadFile(filepath: string): Promise<unknown>;
+}
+//#endregion
+export { LoaderFSManifest, LoaderFSManifestData, ManifestLoaderFS };

package/dist/manifest_loader_fs.js

@@ -0,0 +1,276 @@
+import { RealLoaderFS } from "./index.js";
+import fs from "node:fs";
+import path from "node:path";
+import multimatch from "multimatch";
+
+//#region src/manifest_loader_fs.ts
+var ManifestLoaderFS = class {
+	#manifest;
+	#fallback;
+	#manifestFiles;
+	#manifestDirectories;
+	#resolveCacheTargets;
+	constructor(manifest, fallback = new RealLoaderFS()) {
+		this.#manifest = manifest;
+		this.#fallback = fallback;
+		this.#resolveCacheTargets = new Set(Object.values(manifest.data.resolveCache).filter((target) => typeof target === "string"));
+		const manifestFiles = /* @__PURE__ */ new Set();
+		const manifestDirectories = /* @__PURE__ */ new Set();
+		for (const [dir, files] of Object.entries(manifest.data.fileDiscovery)) {
+			addManifestDirectory(manifestDirectories, dir);
+			for (const file of files) {
+				const fullRel = path.posix.join(dir, file);
+				manifestFiles.add(fullRel);
+				addManifestDirectory(manifestDirectories, path.posix.dirname(fullRel));
+			}
+		}
+		for (const target of this.#resolveCacheTargets) {
+			manifestFiles.add(target);
+			addManifestDirectory(manifestDirectories, path.posix.dirname(target));
+		}
+		this.#manifestFiles = manifestFiles;
+		this.#manifestDirectories = manifestDirectories;
+	}
+	exists(filepath) {
+		const entry = this.#getManifestEntry(filepath);
+		if (entry) return entry.type !== "missing";
+		return this.#fallback.exists(filepath);
+	}
+	stat(filepath) {
+		const entry = this.#getManifestEntry(filepath);
+		if (entry?.type === "file" || entry?.type === "directory") return createVirtualStats(entry.type);
+		if (entry?.type === "missing") throw createNotFoundError("stat", filepath);
+		return this.#fallback.stat(filepath);
+	}
+	realpath(filepath) {
+		const entry = this.#getManifestEntry(filepath);
+		if (entry?.type === "file" || entry?.type === "directory") return this.#toAbsolute(entry.rel);
+		if (entry?.type === "missing") throw createNotFoundError("realpath", filepath);
+		return this.#fallback.realpath(filepath);
+	}
+	readJSON(filepath) {
+		const entry = this.#getManifestEntry(filepath);
+		if (entry?.type === "file") {
+			const bundled = this.#loadBundledModule(entry.rel);
+			if (bundled !== void 0) return unwrapDefaultExport(bundled);
+		}
+		if (entry?.type === "missing") throw createNotFoundError("open", filepath);
+		return this.#fallback.readJSON(filepath);
+	}
+	getKnownFiles(directory) {
+		const relativeDirectory = this.#toRelative(directory);
+		if (Object.hasOwn(this.#manifest.data.fileDiscovery, relativeDirectory)) return [...this.#manifest.data.fileDiscovery[relativeDirectory]].sort();
+		return this.#fallback.getKnownFiles?.(directory);
+	}
+	glob(patterns, options) {
+		const cwd = options?.cwd === void 0 ? process.cwd() : String(options.cwd);
+		const absoluteCwd = path.resolve(cwd);
+		const cwdRel = this.#toRelative(absoluteCwd);
+		const manifestFiles = this.#listManifestFilesUnder(cwdRel);
+		if (manifestFiles === void 0) return this.#fallback.glob(patterns, options);
+		const matched = filterManifestGlob(manifestFiles, patterns, options);
+		if (options?.absolute) return matched.map((file) => path.join(absoluteCwd, file));
+		return matched;
+	}
+	async loadFile(filepath) {
+		const entry = this.#getManifestEntry(filepath);
+		if (entry?.type === "file") {
+			const bundled = this.#loadBundledModule(entry.rel);
+			if (bundled !== void 0) return unwrapDefaultExport(bundled);
+		}
+		if (entry?.type === "missing") throw createNotFoundError("open", filepath);
+		return this.#fallback.loadFile(filepath);
+	}
+	#getManifestEntry(filepath) {
+		const rel = this.#toRelative(filepath);
+		const resolved = this.#resolveManifestFile(rel);
+		if (resolved?.type === "file") return {
+			type: "file",
+			rel: resolved.rel
+		};
+		if (resolved?.type === "missing") return {
+			type: "missing",
+			rel
+		};
+		if (this.#isManifestDirectory(rel)) return {
+			type: "directory",
+			rel
+		};
+	}
+	#resolveManifestFile(rel) {
+		const cache = this.#manifest.data.resolveCache;
+		if (Object.hasOwn(cache, rel)) {
+			const cached = cache[rel];
+			return cached === null ? { type: "missing" } : {
+				type: "file",
+				rel: cached
+			};
+		}
+		if (this.#isManifestFile(rel)) return {
+			type: "file",
+			rel
+		};
+		const discovered = this.#resolveFromFileDiscovery(rel);
+		if (discovered) return {
+			type: "file",
+			rel: discovered
+		};
+	}
+	#resolveFromFileDiscovery(rel) {
+		const matchedDir = this.#nearestManifestDiscoveryDir(rel);
+		if (matchedDir === void 0 || rel === matchedDir) return;
+		const request = matchedDir === "" ? rel : rel.slice(matchedDir.length + 1);
+		for (const file of this.#manifest.data.fileDiscovery[matchedDir]) {
+			if (file === request) return path.posix.join(matchedDir, file);
+			const ext = path.posix.extname(file);
+			if (!ext || ext === ".map") continue;
+			const extensionlessFile = file.slice(0, -ext.length);
+			if (extensionlessFile === request || extensionlessFile === `${request}/index`) return path.posix.join(matchedDir, file);
+		}
+	}
+	#nearestManifestDiscoveryDir(rel) {
+		let current = path.posix.dirname(rel);
+		while (true) {
+			const dir = current === "." ? "" : current;
+			if (Object.hasOwn(this.#manifest.data.fileDiscovery, dir)) return dir;
+			if (dir === "") return;
+			current = path.posix.dirname(dir);
+		}
+	}
+	#isManifestFile(rel) {
+		return this.#manifestFiles.has(rel);
+	}
+	#isManifestDirectory(rel) {
+		return this.#manifestDirectories.has(rel);
+	}
+	#listManifestFilesUnder(cwdRel) {
+		if (!this.#isManifestDirectory(cwdRel)) return;
+		const files = /* @__PURE__ */ new Set();
+		for (const [dir, entries] of Object.entries(this.#manifest.data.fileDiscovery)) {
+			const prefix = dir === cwdRel ? "" : relativePrefix(cwdRel, dir);
+			if (prefix === void 0) continue;
+			for (const entry of entries) files.add(path.posix.join(prefix, entry));
+		}
+		for (const target of Object.values(this.#manifest.data.resolveCache)) {
+			if (!target) continue;
+			const prefix = relativePrefix(cwdRel, path.posix.dirname(target));
+			if (prefix !== void 0) files.add(path.posix.join(prefix, path.posix.basename(target)));
+		}
+		return [...files].sort();
+	}
+	#loadBundledModule(rel) {
+		const loader = globalThis.__EGG_BUNDLE_MODULE_LOADER__;
+		if (!loader) return void 0;
+		for (const key of this.#bundleKeys(rel)) {
+			const loaded = loader(key);
+			if (loaded !== void 0) return loaded;
+		}
+	}
+	#bundleKeys(rel) {
+		const abs = this.#toAbsolute(rel);
+		return [...new Set([rel, normalizePath(abs)])];
+	}
+	#toRelative(filepath) {
+		return normalizePath(path.relative(this.#manifest.baseDir, path.resolve(filepath)));
+	}
+	#toAbsolute(rel) {
+		return path.isAbsolute(rel) ? rel : path.join(this.#manifest.baseDir, rel);
+	}
+};
+function normalizePath(filepath) {
+	return filepath.replaceAll(path.sep, "/");
+}
+function addManifestDirectory(directories, dir) {
+	let current = dir === "." ? "" : dir;
+	while (true) {
+		directories.add(current);
+		if (current === "") return;
+		const parent = path.posix.dirname(current);
+		current = parent === "." ? "" : parent;
+	}
+}
+function relativePrefix(cwdRel, dirRel) {
+	if (cwdRel === "") return dirRel;
+	if (dirRel === cwdRel) return "";
+	if (dirRel.startsWith(cwdRel + "/")) return dirRel.slice(cwdRel.length + 1);
+}
+function filterManifestGlob(files, patterns, options) {
+	const patternList = Array.isArray(patterns) ? patterns : [patterns];
+	if (!patternList.some((pattern) => !pattern.startsWith("!"))) return [];
+	const ignoreList = Array.isArray(options?.ignore) ? options.ignore.map(String) : options?.ignore ? [String(options.ignore)] : [];
+	return multimatch(files, patternList.map(normalizeAlternationGroups).concat(ignoreList.map((pattern) => `!${normalizeAlternationGroups(pattern)}`)), toMultimatchOptions(options));
+}
+function toMultimatchOptions(options) {
+	return {
+		...options?.dot !== void 0 ? { dot: options.dot } : {},
+		...options?.caseSensitiveMatch !== void 0 ? { nocase: !options.caseSensitiveMatch } : {},
+		...options?.braceExpansion !== void 0 ? { nobrace: !options.braceExpansion } : {},
+		...options?.extglob !== void 0 ? { noext: !options.extglob } : {},
+		...options?.globstar !== void 0 ? { noglobstar: !options.globstar } : {},
+		...options?.baseNameMatch !== void 0 ? { matchBase: options.baseNameMatch } : {}
+	};
+}
+function normalizeAlternationGroups(pattern) {
+	let normalized = "";
+	for (let index = 0; index < pattern.length; index++) {
+		const char = pattern[index];
+		if (char !== "(" || isExtglobPrefix(pattern[index - 1])) {
+			normalized += char;
+			continue;
+		}
+		const end = pattern.indexOf(")", index + 1);
+		if (end === -1) {
+			normalized += char;
+			continue;
+		}
+		const group = pattern.slice(index + 1, end);
+		if (group.includes("|")) {
+			normalized += `{${group.replaceAll("|", ",")}}`;
+			index = end;
+		} else normalized += char;
+	}
+	return normalized;
+}
+function isExtglobPrefix(char) {
+	return char === "@" || char === "!" || char === "?" || char === "+" || char === "*";
+}
+function unwrapDefaultExport(value) {
+	let unwrapped = value;
+	if (isRecord(unwrapped) && isRecord(unwrapped.default) && unwrapped.default.__esModule === true) unwrapped = unwrapped.default;
+	if (isRecord(unwrapped) && "default" in unwrapped) return unwrapped.default;
+	return unwrapped;
+}
+function isRecord(value) {
+	return value !== null && typeof value === "object";
+}
+function createVirtualStats(type) {
+	const stat = Object.create(fs.Stats.prototype);
+	const isFile = type === "file";
+	const timestamp = /* @__PURE__ */ new Date(0);
+	Object.defineProperties(stat, {
+		size: { value: 0 },
+		atimeMs: { value: 0 },
+		mtimeMs: { value: 0 },
+		ctimeMs: { value: 0 },
+		birthtimeMs: { value: 0 },
+		atime: { value: timestamp },
+		mtime: { value: timestamp },
+		ctime: { value: timestamp },
+		birthtime: { value: timestamp },
+		isFile: { value: () => isFile },
+		isDirectory: { value: () => !isFile },
+		isSymbolicLink: { value: () => false }
+	});
+	return stat;
+}
+function createNotFoundError(syscall, filepath) {
+	const err = /* @__PURE__ */ new Error(`ENOENT: no such file or directory, ${syscall} '${filepath}'`);
+	err.code = "ENOENT";
+	err.errno = -2;
+	err.syscall = syscall;
+	err.path = filepath;
+	return err;
+}
+
+//#endregion
+export { ManifestLoaderFS };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eggjs/loader-fs",
-  "version": "1.0.0-beta.25",
+  "version": "1.0.0-beta.26",
   "description": "Loader-facing filesystem abstraction for Egg",
   "keywords": [
     "egg",
@@ -41,12 +41,13 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@eggjs/utils": "5.0.2-beta.25",
+    "@eggjs/utils": "5.0.2-beta.26",
     "globby": "^11.0.2",
+    "multimatch": "^7.0.0",
     "utility": "^2.5.0"
   },
   "devDependencies": {
-    "@eggjs/tsconfig": "3.1.2-beta.25",
+    "@eggjs/tsconfig": "3.1.2-beta.26",
     "@types/node": "^24.10.2",
     "typescript": "^5.9.3",
     "vitest": "^4.0.15"