feat(tegg): support cooperative async module loading

[gxkl]

Checklist

• npm test passes
• tests and/or benchmarks are included
• documentation is changed or added
• commit message follows commit guidelines

Affected core subsystem(s)

• @eggjs/tegg-common-util
• @eggjs/tegg-loader
• @eggjs/tegg-plugin
• AOP, Controller, and LangChain graph build hook registration

Description of change

Add an opt-in cooperative asynchronous TEgg module loading path while keeping the existing synchronous behavior as the default.

• add config.tegg.asyncLoad and asyncLoadYieldIntervalMs (default: 50ms per module)
• enumerate module files asynchronously and yield to the event loop between top-level require calls when the configured time slice is reached
• buffer global graph build hooks until asynchronous graph initialization completes
• keep a single require, including its transitive imports, synchronous and non-preemptible
• add focused loader, utility, configuration, and graph hook tests

Validation performed:

• @eggjs/tegg-loader: 5 tests passing
• EventLoopYieldUtil: 3 tests passing
• EggModuleLoader focused tests: 3 tests passing
• TypeScript --noEmit checks for common-util, loader, and tegg plugin
• ESLint on the affected TypeScript files

Summary by CodeRabbit

• New Features
  • Added opt-in asynchronous module loading to improve application responsiveness during startup.
  • Added configurable event-loop yield intervals, defaulting to 50 ms.
  • Added support for asynchronous module discovery and loading APIs.
  • Added configuration and type support for asyncLoad and asyncLoadYieldIntervalMs.
• Documentation
  • Documented asynchronous loading behavior, configuration options, defaults, and yield limitations.
• Bug Fixes
  • Improved loading coordination when multiple asynchronous load requests occur concurrently.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 4d21d2c8-9398-4892-a467-d9b1539156f5

📥 Commits

Reviewing files that changed from the base of the PR and between 8dbe37f and b28a896.

📒 Files selected for processing (21)

• core/common-util/index.ts
• core/common-util/src/EventLoopYieldUtil.ts
• core/common-util/test/EventLoopYieldUtil.test.ts
• core/loader/src/LoaderFactory.ts
• core/loader/src/impl/ModuleLoader.ts
• core/loader/test/Loader.test.ts
• core/loader/test/fixtures/modules/module-before-yield/BlockEventLoop.ts
• core/loader/test/fixtures/modules/module-before-yield/ObserveYield.ts
• core/loader/test/fixtures/modules/module-before-yield/package.json
• core/types/metadata/model/Loader.ts
• plugin/aop/app.ts
• plugin/aop/test/fixtures/apps/aop-app/config/config.default.js
• plugin/config/lib/ModuleScanner.ts
• plugin/controller/app.ts
• plugin/controller/test/fixtures/apps/middleware-graph-app/config/config.default.js
• plugin/langchain/app.ts
• plugin/tegg/README.md
• plugin/tegg/lib/EggModuleLoader.ts
• plugin/tegg/lib/ModuleHandler.ts
• plugin/tegg/test/lib/EggModuleLoader.test.ts
• plugin/tegg/typings/index.d.ts

Included review availability: Your plan includes up to 2 reviews per rolling hour; 1 remains after this review.

---

📝 Walkthrough

Walkthrough

The PR adds opt-in asynchronous module loading with configurable event-loop yields. It adds asynchronous loader contracts, deferred graph initialization, queued graph hooks, application configuration, documentation, and tests.

Changes

Asynchronous module loading

Layer / File(s)	Summary
Yield utility and loader contract core/common-util/*, core/types/metadata/model/Loader.ts	Adds EventLoopYieldUtil and the LoadAsyncOptions and Loader.loadAsync contracts.
Asynchronous class discovery core/loader/src/*, core/loader/test/*	Adds asynchronous file discovery, periodic yielding, caching, concurrent-load deduplication, synchronous fallback, and loader fixtures.
Deferred graph initialization plugin/tegg/lib/*, plugin/tegg/test/lib/EggModuleLoader.test.ts, plugin/tegg/typings/index.d.ts, plugin/config/lib/ModuleScanner.ts	Adds deferred graph creation, queued build hooks, initialization deduplication, asynchronous configuration, and related tests.
Application integration and configuration plugin/aop/*, plugin/controller/*, plugin/langchain/*, plugin/tegg/README.md	Routes graph hook registration through app.moduleHandler, enables asynchronous loading in fixtures, and documents the configuration options.

Estimated code review effort: 4 (Complex) | ~45 minutes

Merge Risk: ⚪ Minimal · up to b28a8

This change adds an opt-in asynchronous module-loading path while preserving synchronous loading by default, with focused tests and validation reported; no actionable merge-blocking risk remains.

Sequence Diagram(s)

sequenceDiagram
  participant Application
  participant ModuleHandler
  participant EggModuleLoader
  participant LoaderFactory
  participant ModuleLoader
  participant GlobalGraph
  Application->>ModuleHandler: registerGlobalGraphBuildHook(hook)
  ModuleHandler->>EggModuleLoader: forward hook
  Application->>EggModuleLoader: load()
  EggModuleLoader->>LoaderFactory: loadAppAsync(options)
  LoaderFactory->>ModuleLoader: loadAsync(options)
  ModuleLoader-->>LoaderFactory: return loaded classes
  LoaderFactory-->>EggModuleLoader: return module descriptors
  EggModuleLoader->>GlobalGraph: create and publish graph
  EggModuleLoader->>GlobalGraph: apply queued hooks

Loading

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: opt-in cooperative asynchronous module loading for TEgg.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/async-module-load-yield

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

core/common-util/index.ts

ESLint skipped: missing config or dependency (missing-dependency). The ESLint configuration references a package that is not available in the sandbox.

core/common-util/src/EventLoopYieldUtil.ts

ESLint skipped: the matched ESLint configuration already failed (missing-dependency).

core/common-util/test/EventLoopYieldUtil.test.ts

ESLint skipped: the matched ESLint configuration already failed (missing-dependency).

• 17 others

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}