feat(core): add loader fs abstraction (#5936)

## Summary
- add LoaderFS and RealLoaderFS as the loader-facing filesystem boundary
- thread loaderFS through EggLoader/FileLoader/ContextLoader paths
without changing default runtime behavior
- add targeted loader tests and wiki notes for the exported API

## Tests
- pnpm exec vitest run packages/core/test/loader/file_loader.test.ts
packages/core/test/loader/context_loader.test.ts
packages/core/test/loader/loader_fs.test.ts
packages/core/test/loader/egg_loader.test.ts --testTimeout 20000
--hookTimeout 20000
- pnpm --filter @eggjs/core run typecheck
- pnpm exec oxfmt --check packages/core/src/loader/loader_fs.ts
packages/core/src/loader/file_loader.ts
packages/core/src/loader/egg_loader.ts packages/core/src/index.ts
packages/core/test/loader/loader_fs.test.ts
packages/core/test/loader/egg_loader.test.ts wiki/packages/core.md
wiki/index.md wiki/log.md
- pnpm exec oxlint --type-aware --type-check --quiet
packages/core/src/loader/loader_fs.ts
packages/core/src/loader/file_loader.ts
packages/core/src/loader/egg_loader.ts
packages/core/test/loader/loader_fs.test.ts
packages/core/test/loader/egg_loader.test.ts (0 errors; 7 existing
warnings in egg_loader.ts)

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* Added a loader filesystem abstraction to allow custom filesystem
implementations.
* Loaders can accept an injected filesystem via options and forward it
during loading.
  * Core package now re-exports and exposes the LoaderFS boundary.

* **Documentation**
* Added Core Package docs describing the LoaderFS boundary and default
implementation.
  * Added changelog entry documenting the filesystem boundary.

* **Tests**
* Added tests for the default filesystem implementation and loader
integration with a custom filesystem.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: killagu

packages/core/src/index.ts

@@ -11,6 +11,7 @@ export * from './singleton.ts';
 export * from './loader/egg_loader.ts';
 export * from './loader/file_loader.ts';
 export * from './loader/context_loader.ts';
+export * from './loader/loader_fs.ts';
 export * from './loader/manifest.ts';
 export * from './utils/sequencify.ts';
 export * from './utils/timing.ts';

packages/core/src/loader/egg_loader.ts

@@ -24,6 +24,7 @@ import { sequencify } from '../utils/sequencify.ts';
 import { Timing } from '../utils/timing.ts';
 import { type ContextLoaderOptions, ContextLoader } from './context_loader.ts';
 import { type FileLoaderOptions, CaseStyle, FULLPATH, FileLoader } from './file_loader.ts';
+import { RealLoaderFS, type LoaderFS } from './loader_fs.ts';
 import { ManifestStore, type StartupManifest } from './manifest.ts';
 
 const debug = debuglog('egg/core/loader/egg_loader');
@@ -57,6 +58,8 @@ export interface EggLoaderOptions {
   plugins?: Record<string, EggPluginInfo>;
   /** Skip lifecycle hooks, only trigger loadMetadata for manifest generation */
   metadataOnly?: boolean;
+  /** Loader-facing filesystem abstraction */
+  loaderFS?: LoaderFS;
 }
 
 export type EggDirInfoType = 'app' | 'plugin' | 'framework';
@@ -79,6 +82,7 @@ export class EggLoader {
   dirs?: EggDirInfo[];
   /** Startup manifest — loaded from cache or collecting for generation */
   readonly manifest: ManifestStore;
+  readonly loaderFS: LoaderFS;
 
   /**
    * @class
@@ -91,6 +95,7 @@ export class EggLoader {
    */
   constructor(options: EggLoaderOptions) {
     this.options = options;
+    this.loaderFS = this.options.loaderFS ?? new RealLoaderFS();
     assert(fs.existsSync(this.options.baseDir), `${this.options.baseDir} not exists`);
     assert(this.options.app, 'options.app is required');
     assert(this.options.logger, 'options.logger is required');
@@ -1653,6 +1658,7 @@ export class EggLoader {
       target,
       inject: this.app,
       manifest: this.manifest,
+      loaderFS: options?.loaderFS ?? this.loaderFS,
     };
 
     const timingKey = `Load "${String(property)}" to Application`;
@@ -1679,6 +1685,7 @@ export class EggLoader {
       property,
       inject: this.app,
       manifest: this.manifest,
+      loaderFS: options?.loaderFS ?? this.loaderFS,
     };
 
     const timingKey = `Load "${String(property)}" to Context`;

packages/core/src/loader/file_loader.ts

@@ -1,13 +1,12 @@
 import assert from 'node:assert';
-import fs from 'node:fs';
 import path from 'node:path';
 import { debuglog } from 'node:util';
 
 import { isSupportTypeScript } from '@eggjs/utils';
-import globby from 'globby';
 import { isClass, isGeneratorFunction, isAsyncFunction, isPrimitive } from 'is-type-of';
 
-import utils, { type Fun } from '../utils/index.ts';
+import utils from '../utils/index.ts';
+import { RealLoaderFS, type LoaderFS } from './loader_fs.ts';
 import type { ManifestStore } from './manifest.ts';
 
 const debug = debuglog('egg/core/file_loader');
@@ -52,14 +51,18 @@ export interface FileLoaderOptions {
   lowercaseFirst?: boolean;
   /** Startup manifest for caching globby scans and collecting results */
   manifest?: ManifestStore;
+  /** Loader-facing filesystem abstraction */
+  loaderFS?: LoaderFS;
 }
 
 export interface FileLoaderParseItem {
   fullpath: string;
   properties: string[];
-  exports: object | Fun;
+  exports: unknown;
 }
 
+type NormalizedFileLoaderOptions = FileLoaderOptions & Required<Pick<FileLoaderOptions, 'caseStyle' | 'loaderFS'>>;
+
 function getDefaultFileLoaderMatch(): string[] {
   return isSupportTypeScript() ? ['**/*.(js|ts)', '!**/*.d.ts'] : ['**/*.js'];
 }
@@ -81,7 +84,7 @@ export class FileLoader {
     return getDefaultFileLoaderMatch();
   }
 
-  readonly options: FileLoaderOptions & Required<Pick<FileLoaderOptions, 'caseStyle'>>;
+  readonly options: NormalizedFileLoaderOptions;
 
   /**
    * @class
@@ -108,6 +111,7 @@ export class FileLoader {
       caseStyle: CaseStyle.camel,
       call: true,
       override: false,
+      loaderFS: new RealLoaderFS(),
       ...options,
     };
 
@@ -210,12 +214,12 @@ export class FileLoader {
     for (const directory of directories) {
       const manifest = this.options.manifest;
       const filepaths = manifest
-        ? manifest.globFiles(directory, () => globby.sync(files, { cwd: directory }))
-        : globby.sync(files, { cwd: directory });
+        ? manifest.globFiles(directory, () => this.options.loaderFS.glob(files, { cwd: directory }))
+        : this.options.loaderFS.glob(files, { cwd: directory });
       debug('[parse] files: %o, cwd: %o => %o', files, directory, filepaths);
       for (const filepath of filepaths) {
         const fullpath = path.join(directory, filepath);
-        if (!fs.statSync(fullpath).isFile()) continue;
+        if (!this.options.loaderFS.stat(fullpath).isFile()) continue;
         if (filepath.endsWith('.js')) {
           const filepathTs = filepath.replace(/\.js$/, '.ts');
           if (filepaths.includes(filepathTs)) {
@@ -266,8 +270,8 @@ function getProperties(filepath: string, caseStyle: CaseStyle | CaseStyleFunctio
 
 // Get exports from filepath
 // If exports is null/undefined, it will be ignored
-async function getExports(fullpath: string, options: FileLoaderOptions, pathName: string): Promise<any> {
-  let exports = await utils.loadFile(fullpath);
+async function getExports(fullpath: string, options: NormalizedFileLoaderOptions, pathName: string): Promise<unknown> {
+  let exports = await options.loaderFS.loadFile(fullpath);
   // process exports as you like
   if (options.initializer) {
     exports = options.initializer(exports, { path: fullpath, pathName });
@@ -293,7 +297,8 @@ async function getExports(fullpath: string, options: FileLoaderOptions, pathName
   //   return {};
   // }
   if (options.call && typeof exports === 'function') {
-    exports = exports(options.inject);
+    const callableExports = exports as (inject?: FileLoaderOptions['inject']) => unknown;
+    exports = callableExports(options.inject);
     if (exports !== null && exports !== undefined) {
       return exports;
     }

packages/core/src/loader/loader_fs.ts

@@ -0,0 +1,43 @@
+import fs, { type Stats } from 'node:fs';
+
+import globby from 'globby';
+import { readJSONSync } from 'utility';
+
+import utils from '../utils/index.ts';
+
+export type LoaderFSGlobOptions = globby.GlobbyOptions;
+
+export interface LoaderFS {
+  exists(filepath: string): boolean;
+  stat(filepath: string): Stats;
+  realpath(filepath: string): string;
+  readJSON<T = unknown>(filepath: string): T;
+  glob(patterns: string | string[], options?: LoaderFSGlobOptions): string[];
+  loadFile(filepath: string): Promise<unknown>;
+}
+
+export class RealLoaderFS implements LoaderFS {
+  exists(filepath: string): boolean {
+    return fs.existsSync(filepath);
+  }
+
+  stat(filepath: string): Stats {
+    return fs.statSync(filepath);
+  }
+
+  realpath(filepath: string): string {
+    return fs.realpathSync(filepath);
+  }
+
+  readJSON<T = unknown>(filepath: string): T {
+    return readJSONSync(filepath) as T;
+  }
+
+  glob(patterns: string | string[], options?: LoaderFSGlobOptions): string[] {
+    return globby.sync(patterns, options);
+  }
+
+  async loadFile(filepath: string): Promise<unknown> {
+    return utils.loadFile(filepath);
+  }
+}

packages/core/test/__snapshots__/index.test.ts.snap

@@ -19,6 +19,7 @@ exports[`should expose properties 1`] = `
   "KoaResponse",
   "Lifecycle",
   "ManifestStore",
+  "RealLoaderFS",
   "Request",
   "Response",
   "Router",

packages/core/test/loader/egg_loader.test.ts

@@ -6,7 +6,14 @@ import { getPlugins } from '@eggjs/utils';
 import { mm } from 'mm';
 import { describe, it, beforeAll, afterAll, afterEach } from 'vitest';
 
-import { EggLoader } from '../../src/index.js';
+import {
+  ContextLoader,
+  EggLoader,
+  FileLoader,
+  RealLoaderFS,
+  type EggLoaderOptions,
+  type LoaderFS,
+} from '../../src/index.js';
 import { createApp, getFilepath, type Application } from '../helper.js';
 
 describe('test/loader/egg_loader.test.ts', () => {
@@ -109,6 +116,38 @@ describe('test/loader/egg_loader.test.ts', () => {
     assert(Reflect.get(app.context, prop).user);
   });
 
+  it('should pass loaderFS to loadToApp and loadToContext', async () => {
+    const baseDir = getFilepath('load_to_app');
+    const loaderFS = new RealLoaderFS();
+    const loaderApp = { context: {} } as EggLoaderOptions['app'];
+    const loader = new EggLoader({
+      env: 'unittest',
+      baseDir,
+      app: loaderApp,
+      logger: app.logger,
+      loaderFS,
+    });
+    const passedLoaderFS: LoaderFS[] = [];
+
+    mm(FileLoader.prototype, 'load', async function (this: FileLoader) {
+      passedLoaderFS.push(this.options.loaderFS);
+      return {};
+    });
+    mm(ContextLoader.prototype, 'load', async function (this: ContextLoader) {
+      passedLoaderFS.push(this.options.loaderFS);
+      return {};
+    });
+
+    try {
+      await loader.loadToApp(path.join(baseDir, 'app/model'), 'model');
+      await loader.loadToContext(path.join(baseDir, 'app/service'), 'service');
+
+      assert.deepEqual(passedLoaderFS, [loaderFS, loaderFS]);
+    } finally {
+      mm.restore();
+    }
+  });
+
   describe('resolveModule with outDir', () => {
     afterEach(mm.restore);
 

packages/core/test/loader/file_loader.test.ts

@@ -6,10 +6,33 @@ import yaml from 'js-yaml';
 import { describe, it, expect } from 'vitest';
 
 import { FileLoader, CaseStyle } from '../../src/loader/file_loader.ts';
+import { RealLoaderFS, type LoaderFSGlobOptions } from '../../src/loader/loader_fs.ts';
+import { ManifestStore } from '../../src/loader/manifest.ts';
 import { getFilepath } from '../helper.ts';
 
 const dirBase = getFilepath('load_dirs');
 
+class RecordingLoaderFS extends RealLoaderFS {
+  readonly globCalls: Array<{ patterns: string | string[]; cwd: string | undefined }> = [];
+  readonly statCalls: string[] = [];
+  readonly loadFileCalls: string[] = [];
+
+  glob(patterns: string | string[], options?: LoaderFSGlobOptions): string[] {
+    this.globCalls.push({ patterns, cwd: options?.cwd ? String(options.cwd) : undefined });
+    return super.glob(patterns, options);
+  }
+
+  stat(filepath: string) {
+    this.statCalls.push(filepath);
+    return super.stat(filepath);
+  }
+
+  async loadFile(filepath: string): Promise<unknown> {
+    this.loadFileCalls.push(filepath);
+    return super.loadFile(filepath);
+  }
+}
+
 describe('test/loader/file_loader.test.ts', () => {
   it('should load files with package.json#exports', async () => {
     const directory = path.join(__dirname, '../../../../plugins/mock/src/app/middleware');
@@ -397,4 +420,20 @@ describe('test/loader/file_loader.test.ts', () => {
     }).load();
     assert.deepEqual(Object.keys(target), ['arr', 'class']);
   });
+
+  it('should use loaderFS for discovery, stat and loadFile', async () => {
+    const target: Record<string, unknown> = {};
+    const loaderFS = new RecordingLoaderFS();
+    await new FileLoader({
+      directory: path.join(dirBase, 'services'),
+      target,
+      loaderFS,
+      manifest: ManifestStore.createCollector(dirBase),
+    }).load();
+
+    assert(target.fooService);
+    assert(loaderFS.globCalls.some((call) => call.cwd === path.join(dirBase, 'services')));
+    assert(loaderFS.statCalls.some((filepath) => filepath.endsWith(path.join('services', 'foo_service.js'))));
+    assert(loaderFS.loadFileCalls.some((filepath) => filepath.endsWith(path.join('services', 'foo_service.js'))));
+  });
 });

packages/core/test/loader/loader_fs.test.ts

@@ -0,0 +1,36 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+
+import globby from 'globby';
+import { describe, it } from 'vitest';
+
+import { RealLoaderFS } from '../../src/loader/loader_fs.ts';
+import utils from '../../src/utils/index.ts';
+import { getFilepath } from '../helper.ts';
+
+describe('test/loader/loader_fs.test.ts', () => {
+  const loaderFS = new RealLoaderFS();
+  const baseDir = getFilepath('loadfile');
+
+  it('should wrap exists/stat/realpath with node fs behavior', () => {
+    const filepath = path.join(baseDir, 'object.js');
+
+    assert.equal(loaderFS.exists(filepath), fs.existsSync(filepath));
+    assert.equal(loaderFS.exists(path.join(baseDir, 'not-exists.js')), false);
+    assert.equal(loaderFS.stat(filepath).isFile(), fs.statSync(filepath).isFile());
+    assert.equal(loaderFS.realpath(baseDir), fs.realpathSync(baseDir));
+  });
+
+  it('should wrap readJSON/glob/loadFile with current loader behavior', async () => {
+    const packagePath = path.join(baseDir, 'package.json');
+    const patterns = ['*.js', '!null.js'];
+
+    assert.deepEqual(await loaderFS.readJSON(packagePath), JSON.parse(fs.readFileSync(packagePath, 'utf8')));
+    assert.deepEqual(loaderFS.glob(patterns, { cwd: baseDir }).sort(), globby.sync(patterns, { cwd: baseDir }).sort());
+    assert.deepEqual(
+      await loaderFS.loadFile(path.join(baseDir, 'object.js')),
+      await utils.loadFile(path.join(baseDir, 'object.js')),
+    );
+  });
+});

wiki/index.md

@@ -18,6 +18,7 @@ Read this file before exploring raw sources.
 
 ## Packages
 
+- [Core Package](./packages/core.md) - Loader, lifecycle, and application core primitives used by Egg runtime packages.
 - [Egg Bundler](./packages/egg-bundler.md) - Tooling package that bundles Egg applications and backs `egg-bin bundle`.
 - [Onerror Plugin](./packages/onerror.md) - Default Egg error-handling plugin and configurable response negotiation layer.
 - [Typings Package](./packages/typings.md) - Shared TypeScript type surface for cross-package Egg typings.

wiki/log.md

@@ -2,6 +2,12 @@
 
 Dates use the workspace-local Asia/Shanghai calendar date.
 
+## [2026-05-07] package | document core LoaderFS boundary
+
+- sources touched: `packages/core/src/index.ts`, `packages/core/src/loader/loader_fs.ts`, `packages/core/src/loader/file_loader.ts`, `packages/core/src/loader/context_loader.ts`, `packages/core/src/loader/egg_loader.ts`
+- pages updated: `wiki/index.md`, `wiki/log.md`, `wiki/packages/core.md`
+- note: Recorded `LoaderFS` as the minimal loader filesystem boundary and `RealLoaderFS` as the default implementation for existing non-bundled behavior.
+
 ## [2026-05-06] package | sync bundled runtime support changes
 
 - sources touched: `tools/egg-bundler/src/lib/ExternalsResolver.ts`, `packages/utils/src/import.ts`, `plugins/onerror/src/lib/onerror.ts`