@fluojs/config 1.0.3 → 2.0.0

package/README.ko.md

@@ -4,6 +4,8 @@
 
 fluo 애플리케이션을 위한 설정 로드, 병합, 검증, 타입 안전한 런타임 접근을 제공하는 패키지입니다.
 
+Coordinated Node 24 릴리스를 준비한다면 패키지 업그레이드 전에 [소비자 마이그레이션 가이드](../../docs/getting-started/migrate-node24.ko.md)를 따르세요.
+
 ## 목차
 
 - [설치](#설치)
@@ -20,7 +22,7 @@ fluo 애플리케이션을 위한 설정 로드, 병합, 검증, 타입 안전
 npm install @fluojs/config
 ```
 
-패키지는 Node.js 20.16.0 이상을 지원합니다. Env-file loading, 기본 `.env` loading, watch mode는 Node filesystem, path, crypto builtin을 host runtime boundary를 통해 lazy하게 해석하며 `process.getBuiltinModule(...)`을 요구합니다. 이 API가 존재하지만 filesystem/path/crypto direct lookup이 불가능할 때는 published ESM과 호환되는 `node:module` fallback을 사용합니다. `ConfigService`와 `loadConfig({ defaults, processEnv, runtimeOverrides })`의 in-memory 사용은 env-file access를 요구하지 않지만, 배포 계약은 package-level Node.js 20.16.0 engine을 따릅니다.
+패키지는 의도적으로 package-wide `engines.node`를 선언하지 않습니다. `ConfigService`, merge/validation/clone 동작, `loadConfig({ defaults, processEnv, runtimeOverrides })`는 portable하며 `process.cwd()`, 기본 `.env` path, Node filesystem/path/crypto builtin을 해석하지 않습니다. Env-file loading, 기본 `.env` loading, watch mode는 Node 전용 기능입니다. 이 경로는 지원 범위 Node.js `>=24.0.0 <27`의 `process.getBuiltinModule(...)`을 통해 builtin을 lazy하게 해석하며 host가 해당 경계를 제공하지 않으면 in-memory option을 사용하거나 Node.js에서 실행하라는 guidance와 함께 `CONFIG_RUNTIME_UNAVAILABLE`을 던집니다. 이 guard는 feature capability를 확인하며 Node version 비교나 portable root import 차단을 추가하지 않습니다.
 
 ## 사용 시점
 
@@ -56,7 +58,7 @@ const EnvSchema = z.object({
 class AppModule {}
 ```
 
-env file이 절대 경로나 미리 해석된 경로에 있다면 `envFilePath`를 사용하고, 기본 dotenv parser 대신 다른 flat-file parser가 필요하다면 `parse`를 전달하세요.
+env file이 절대 경로나 미리 해석된 경로에 있다면 `envFilePath`를 사용하고, 여러 env file을 명시적인 순서로 계층화해야 한다면 `envFilePaths`를 사용하며, 기본 dotenv parser 대신 다른 flat-file parser가 필요하다면 `parse`를 전달하세요.
 
 등록 후에는 `ConfigService`를 주입해서 값을 읽습니다.
 
@@ -75,6 +77,19 @@ class MyService {
 
 ## 주요 기능
 
+### NestJS 등록 마이그레이션
+
+`ConfigModule`은 동기 `forRoot(...)` registration만 노출하며 `ConfigModule.forRootAsync(...)`에 대응하는 API는 없습니다. `@nestjs/config`에서 마이그레이션할 때는 다음 경계를 따르세요.
+
+- Remote secret과 다른 비동기 source는 module graph를 정의하기 전에 application-owned bootstrap boundary에서 resolve한 뒤, 최종 값을 동기 registration call에 전달합니다.
+- NestJS `load` factory는 `defaults` 또는 `runtimeOverrides`의 nested plain object로 옮깁니다. Deep merge와 dot-path `ConfigService` 접근을 위해 nesting을 그대로 유지하세요.
+- `@fluojs/config`는 ambient environment variable을 scan하지 않으므로 명시적 `processEnv` snapshot을 전달합니다.
+- NestJS `validate` callback은 `schema`에 전달하는 동기 Standard Schema로 바꿉니다. 비동기 schema 결과는 거부됩니다.
+- NestJS `isGlobal`이 아니라 `global`을 사용합니다. Visibility는 기본적으로 global이며, `global: false`로 module-local visibility를 선택합니다.
+- Call site는 single-key 형태로 재작성합니다. `ConfigService.get(key)`와 `getOrThrow(key)`는 key 하나만 받으며 NestJS default-value 또는 options overload를 노출하지 않습니다. 기본값은 `defaults` 또는 `schema` output이 소유하거나, `get(key)` 결과에 명시적인 `??` fallback을 적용합니다.
+
+공유 validated snapshot bootstrap pattern과 HTTP adapter boundary는 canonical [NestJS configuration migration guide](../../docs/getting-started/migrate-from-nestjs.ko.md)를 참고하세요.
+
 ### 명확한 소스 우선순위
 
 설정은 `runtimeOverrides` → `processEnv` 옵션으로 전달한 환경 스냅샷 → env 파일 → `defaults` 순서로 병합됩니다.
@@ -83,7 +98,34 @@ class MyService {
 
 `envFilePath`는 `envFile`보다 우선하며, `parse`를 사용하면 flat key/value 파일을 위한 custom parser로 dotenv parsing을 대체할 수 있습니다. 빈 load/module option은 `loadConfig({})`와 `ConfigModule.forRoot()`에 대해 기본 `<cwd>/.env` 동작을 보존합니다. 누락된 env file은 load 시 빈 입력처럼 처리됩니다. watch mode에서는 parent directory도 관찰하므로 나중에 파일을 생성해도 reload를 트리거할 수 있습니다.
 
-Root `@fluojs/config` 패키지를 import하는 것만으로는 Node filesystem, path, crypto builtin을 해석하지 않습니다. `ConfigService`, option type, 또는 명시적 in-memory 입력을 쓰는 `loadConfig(...)` consumer는 root import를 안전하게 사용할 수 있고, Node builtin은 env-file load 또는 watch mode가 실제로 실행될 때 lazy하게 해석됩니다. `loadConfig({ defaults, processEnv, runtimeOverrides })`는 `process.cwd()`, 기본 `.env` path, Node filesystem/path/crypto builtin을 해석하지 않습니다. Published package engine이 Node.js 20.16.0 이상이므로 Node.js 20.0.0부터 20.15.x까지와 Node.js 밖의 runtime은 env-file, 기본 `.env`, watch execution path의 지원 package contract에 포함되지 않습니다.
+### 순서가 있는 다중 env file loading
+
+`envFilePaths`는 명시적으로 순서가 정해진 env file 목록 하나를 받습니다. 목록은 낮은 우선순위에서 높은 우선순위로 병합되어 단일 env-file tier를 구성하므로, 여전히 `defaults`보다 위에 있고 `processEnv`와 `runtimeOverrides`보다 아래에 있습니다.
+
+```ts
+ConfigModule.forRoot({
+  envFilePaths: ['.env', '.env.production', '.env.production.local'],
+  processEnv: {
+    DATABASE_URL: process.env.DATABASE_URL,
+  },
+  schema: EnvSchema,
+});
+```
+
+contract는 다음과 같습니다.
+
+- 뒤쪽 entry가 앞쪽 entry를 이깁니다. plain object는 여전히 deep merge되고 array는 여전히 교체됩니다.
+- 상대 경로 entry는 `cwd`(기본값 `process.cwd()`) 기준으로 해석되고, 절대 경로 entry는 그대로 사용됩니다.
+- 누락된 파일은 아무 값도 기여하지 않으며 load를 실패시키지 않습니다.
+- `envFilePaths: []`는 기본 `<cwd>/.env` fallback을 포함해 env-file loading 자체를 명시적으로 해제합니다.
+- `envFilePaths`를 `envFile` 또는 `envFilePath`와 함께 쓰면 `INVALID_CONFIG`로 실패하며, 해석 결과가 중복된 경로나 빈 entry도 동일하게 실패합니다.
+- schema는 개별 파일이 아니라 완전히 병합된 결과를 한 번만 검증합니다.
+- watch mode에서는 서로 다른 parent directory마다 watcher를 하나씩만 시작하고, 목록에 포함된 파일이 변경되면 전체 목록을 다시 계산하며, 우선순위가 높은 파일을 삭제하면 남은 파일로 fallback합니다. 검증 실패 시에는 마지막 유효 snapshot을 유지합니다.
+- 자동 profile 탐색은 패키지 밖에 남습니다. 정확한 목록과 순서는 caller가 결정합니다.
+
+패키지는 `NODE_ENV`에서 env file 이름을 유도하지 않습니다. 환경별 계층화가 필요하다면 bootstrap boundary에서 목록을 직접 구성하세요.
+
+Root `@fluojs/config` 패키지를 import하는 것만으로는 Node filesystem, path, crypto builtin을 해석하지 않습니다. `ConfigService`, option type, 또는 명시적 in-memory 입력을 쓰는 `loadConfig(...)` consumer는 non-Node runtime에서도 지원됩니다. Env-file, 기본 `.env`, watch 실행은 Node 전용이며 `process.getBuiltinModule(...)`을 제공하는 host가 필요합니다. 지원하지 않는 host에서는 eager import failure 대신 문서화된 `CONFIG_RUNTIME_UNAVAILABLE` error가 발생합니다.
 
 ### 객체 단위 딥 머지
 
@@ -101,9 +143,9 @@ Root `@fluojs/config` 패키지를 import하는 것만으로는 Node filesystem,
 
 `ConfigReloadManager.reload()`는 리로드 작업을 직렬화합니다. 현재 리로드가 listener 알림을 수행하는 동안 다른 리로드가 요청되면 후속 리로드는 큐에 들어가 활성 알림이 끝난 뒤 적용됩니다. 활성 알림이 실패하면 직전 snapshot을 복구하고 큐에 있던 리로드는 폐기합니다. 동일한 직렬화와 rollback 계약은 `createConfigReloader(...).reload()`에도 적용되며, watch로 시작된 알림 중 큐에 들어간 manual reload도 이 계약을 따릅니다.
 
-Module registration과 reloader 생성은 caller-owned options를 저장하기 전에 snapshot으로 분리합니다. `ConfigModule.forRoot(...)`, `ConfigReloadModule.forRoot(...)`, `createConfigReloader(...)`에 넘긴 객체를 나중에 변경해도 bootstrap, manual reload, watch reload 입력은 바뀌지 않습니다. `ConfigModule.forRoot({ watch: true, ... })`를 사용하면 module은 application bootstrap 중 env-file watcher를 시작하고, 먼저 injected `ConfigService`를 watch reloader baseline과 맞춘 다음 watch reload가 성공한 뒤 같은 injected `ConfigService` instance를 갱신합니다. `ConfigModule`의 automatic watch reload 실패를 애플리케이션이 소유해야 한다면 `onReloadError`를 전달하세요. Watch mode에서는 기존 env file과 누락된 env file 모두에 대해 parent directory를 watch하므로, 나중에 env file을 생성하거나 atomic replacement로 교체해도 reload가 트리거될 수 있습니다. Watch reload는 reload 전에 최종 env file content를 마지막으로 commit된 watch baseline과 비교하므로, 내용이 바뀌지 않은 저장이나 변경 후 debounce 안에서 원래 내용으로 되돌린 burst는 인프로세스 config snapshot을 교체하지 않습니다.
+Module registration과 reloader 생성은 `schema`로 전달한 nested Standard Schema validator object를 포함해 caller-owned options를 저장하기 전에 snapshot으로 분리합니다. 이 캡처는 provider resolution이나 application bootstrap보다 앞선 `ConfigModule.forRoot(...)`, `ConfigReloadModule.forRoot(...)`, `createConfigReloader(...)` 호출 시점에 동기적으로 일어납니다. Config dictionary, `processEnv`, Standard Schema descriptor는 분리하고, `parse`, `onReloadError`, schema validator 같은 callable value는 해당 호출에서 캡처한 reference를 유지합니다. 이후 option object나 snapshot으로 분리된 nested object를 변경해도 bootstrap, manual reload, watch reload 입력은 바뀌지 않습니다. `ConfigModule.forRoot({ watch: true, ... })`를 사용하면 module은 application bootstrap 중 env-file watcher를 시작하고, 먼저 injected `ConfigService`를 watch reloader baseline과 맞춘 다음 watch reload가 성공한 뒤 같은 injected `ConfigService` instance를 갱신합니다. `ConfigModule`의 automatic watch reload 실패를 애플리케이션이 소유해야 한다면 `onReloadError`를 전달하세요. Watch mode에서는 기존 env file과 누락된 env file 모두에 대해 parent directory를 watch하므로, 나중에 env file을 생성하거나 atomic replacement로 교체해도 reload가 트리거될 수 있습니다. Watch reload는 reload 전에 최종 env file content를 마지막으로 commit된 watch baseline과 비교하므로, 내용이 바뀌지 않은 저장이나 변경 후 debounce 안에서 원래 내용으로 되돌린 burst는 인프로세스 config snapshot을 교체하지 않습니다.
 
-`ConfigReloadModule`은 명시적으로 주입 가능한 reload layer이며 standalone config source가 아닙니다. manual reload나 subscription을 위해 `CONFIG_RELOADER`가 필요한 caller는 `ConfigModule` 또는 다른 `ConfigService` provider와 함께 사용하세요. `ConfigModule` 또는 `ConfigReloadModule`이 만든 watcher는 `watch: true`일 때만 생성되며 module shutdown 중에 닫힙니다. 같은 env file에 대해서는 한 layer에서만 `watch: true`를 활성화하세요. 자동 `ConfigService` 갱신만 필요하면 `ConfigModule`을 사용하고, subscription/manual reload를 위한 injected reloader 계약이 필요하면 `ConfigReloadModule`을 사용합니다.
+`ConfigReloadModule`은 명시적으로 주입 가능한 reload layer이며 standalone config source가 아닙니다. manual reload나 subscription을 위해 `CONFIG_RELOADER`가 필요한 caller는 `ConfigModule` 또는 다른 `ConfigService` provider와 함께 사용하세요. `ConfigModule` 또는 `ConfigReloadModule`이 만든 watcher는 `watch: true`일 때만 생성되며 module shutdown 중에 닫힙니다. `ConfigReloadManager`의 종료는 최종 상태입니다. `close()` 또는 `onModuleDestroy()` 이후에는 대체 reloader나 watcher를 다시 생성하지 않고, `reload()`, `subscribe()`, `subscribeError()`는 `InvariantError`를 던지며, `current()`는 마지막으로 commit된 스냅샷을 계속 반환합니다. 같은 env file에 대해서는 한 layer에서만 `watch: true`를 활성화하세요. 자동 `ConfigService` 갱신만 필요하면 `ConfigModule`을 사용하고, subscription/manual reload를 위한 injected reloader 계약이 필요하면 `ConfigReloadModule`을 사용합니다.
 
 ## 공개 API
 
@@ -123,14 +165,17 @@ Module registration과 reloader 생성은 caller-owned options를 저장하기
 
 ## 관련 패키지
 
-- `@fluojs/runtime`: 부트스트랩 중 `loadConfig()`를 호출합니다.
+- `@fluojs/runtime`: configuration loading을 transitive하게 제공하지 않습니다. `ConfigModule.forRoot(...)`를 사용하거나 `ConfigService`를 주입하는 애플리케이션은 `@fluojs/config`를 direct dependency로 선언해야 합니다.
 - Standard Schema validator: Zod, Valibot, ArkType 및 호환 schema 라이브러리를 `schema` 옵션으로 전달할 수 있습니다.
 
 ## 예제 소스
 
 - `packages/config/src/load.ts`
+- `packages/config/src/options.ts`
+- `packages/config/src/module.ts`
 - `packages/config/src/service.ts`
 - `packages/config/src/load.test.ts`
 - `packages/config/src/reload-module.ts`
-- `docs/architecture/config-and-environments.md`
-- `docs/architecture/dev-reload-architecture.md`
+- `packages/config/src/reload-module.test.ts`
+- [구성 및 환경](../../docs/architecture/config-and-environments.ko.md)
+- [개발 리로드 아키텍처](../../docs/architecture/dev-reload-architecture.ko.md)

package/README.md

@@ -4,6 +4,8 @@
 
 Configuration loading, merging, validation, and typed runtime access for fluo applications.
 
+Preparing for the coordinated Node 24 release? Follow the [consumer migration guide](../../docs/getting-started/migrate-node24.md) before upgrading packages.
+
 ## Table of Contents
 
 - [Installation](#installation)
@@ -20,7 +22,7 @@ Configuration loading, merging, validation, and typed runtime access for fluo ap
 npm install @fluojs/config
 ```
 
-The package supports Node.js 20.16.0 or newer. Env-file loading, default `.env` loading, and watch mode resolve Node filesystem, path, and crypto builtins lazily through the host runtime boundary, requiring `process.getBuiltinModule(...)`; when that API is present but direct filesystem/path/crypto lookup is unavailable, a published-ESM-compatible `node:module` fallback is used. In-memory use of `ConfigService` and `loadConfig({ defaults, processEnv, runtimeOverrides })` does not require env-file access, but it is still distributed under the package-level Node.js 20.16.0 engine contract.
+The package intentionally declares no package-wide `engines.node`. `ConfigService`, merge/validation/clone behavior, and `loadConfig({ defaults, processEnv, runtimeOverrides })` are portable and never resolve `process.cwd()`, a default `.env` path, or Node filesystem/path/crypto builtins. Env-file loading, default `.env` loading, and watch mode are Node-only features: they lazily resolve builtins through `process.getBuiltinModule(...)` (supported on Node.js `>=24.0.0 <27`) and throw `CONFIG_RUNTIME_UNAVAILABLE` with guidance to use in-memory options or run that feature on Node.js when the host cannot provide the boundary. This guard checks feature capabilities; it does not compare Node versions or reject portable root imports.
 
 ## When to Use
 
@@ -59,7 +61,7 @@ const EnvSchema = z.object({
 class AppModule {}
 ```
 
-Use `envFilePath` when the env file lives at an absolute or pre-resolved path, or `parse` when you need a custom flat-file parser instead of the default dotenv parser.
+Use `envFilePath` when the env file lives at an absolute or pre-resolved path, `envFilePaths` when a deployment needs several env files layered in an explicit order, or `parse` when you need a custom flat-file parser instead of the default dotenv parser.
 
 Once registered, you can inject `ConfigService` to access your values:
 
@@ -78,6 +80,19 @@ class MyService {
 
 ## Key Capabilities
 
+### NestJS Registration Migration
+
+`ConfigModule` exposes only synchronous `forRoot(...)` registration and has no `ConfigModule.forRootAsync(...)` counterpart. When migrating from `@nestjs/config`:
+
+- Resolve remote secrets and other asynchronous sources at the application-owned bootstrap boundary before defining the module graph, then pass their final values to the synchronous registration call.
+- Replace NestJS `load` factories with nested plain objects in `defaults` or `runtimeOverrides`; keep the nesting intact for deep merging and dot-path `ConfigService` access.
+- Pass an explicit `processEnv` snapshot because `@fluojs/config` does not scan ambient environment variables.
+- Replace NestJS `validate` callbacks with a synchronous Standard Schema passed as `schema`; asynchronous schema results are rejected.
+- Use `global`, not NestJS `isGlobal`. Visibility is global by default, and `global: false` opts into module-local visibility.
+- Rewrite call sites to the single-key shape: `ConfigService.get(key)` and `getOrThrow(key)` take one key and expose no NestJS default-value or options overload. Own defaults in `defaults` or the `schema` output, or apply an explicit `??` fallback to the `get(key)` result.
+
+See the canonical [NestJS configuration migration guide](../../docs/getting-started/migrate-from-nestjs.md) for the shared validated-snapshot bootstrap pattern and HTTP adapter boundary.
+
 ### Source Precedence
 Configuration is merged in the following order (highest precedence wins):
 1. **Runtime Overrides**: Values passed explicitly via `runtimeOverrides`.
@@ -89,7 +104,34 @@ Configuration is merged in the following order (highest precedence wins):
 
 `envFilePath` overrides `envFile`, and `parse` lets callers replace dotenv parsing with a custom parser for flat key/value files. Empty load/module options preserve the default `<cwd>/.env` behavior for `loadConfig({})` and `ConfigModule.forRoot()`. Missing env files are treated as empty input during load; watch mode also observes the parent directory so creating the file later can trigger a reload.
 
-Importing the root `@fluojs/config` package is safe for in-memory consumers that only need `ConfigService`, option types, or `loadConfig(...)` with explicit in-memory inputs: Node filesystem, path, and crypto builtins are resolved lazily only when env-file loading or watch mode actually runs. `loadConfig({ defaults, processEnv, runtimeOverrides })` does not resolve `process.cwd()`, a default `.env` path, or Node filesystem/path/crypto builtins. Because the published package engine is Node.js 20.16.0 or newer, Node.js 20.0.0 through 20.15.x and non-Node runtimes are outside the supported package contract for env-file, default `.env`, and watch execution paths.
+### Ordered Multi-File Env Loading
+
+`envFilePaths` accepts one explicit, ordered list of env files. The list is merged from lowest to highest precedence into the single env-file tier, so it still sits above `defaults` and below `processEnv` and `runtimeOverrides`.
+
+```typescript
+ConfigModule.forRoot({
+  envFilePaths: ['.env', '.env.production', '.env.production.local'],
+  processEnv: {
+    DATABASE_URL: process.env.DATABASE_URL,
+  },
+  schema: EnvSchema,
+});
+```
+
+Contract:
+
+- Later entries win over earlier entries; plain objects still deep-merge and arrays still replace.
+- Relative entries resolve against `cwd` (defaulting to `process.cwd()`); absolute entries are used as-is.
+- Missing files contribute nothing and never fail the load.
+- `envFilePaths: []` explicitly opts out of env-file loading, including the default `<cwd>/.env` fallback.
+- Combining `envFilePaths` with `envFile` or `envFilePath` fails with `INVALID_CONFIG`, as do duplicate resolved paths and blank entries.
+- The schema validates the fully merged result once, not each file individually.
+- In watch mode every distinct parent directory is watched once, any listed-file change recomputes the entire list, and deleting a higher-precedence file falls back to the remaining files. Validation failures keep the last valid snapshot.
+- Automatic profile discovery stays outside the package: the caller decides the exact list and order.
+
+The package does not derive env-file names from `NODE_ENV`. Build the list at the bootstrap boundary when a deployment needs environment-specific layering.
+
+Importing the root `@fluojs/config` package is safe for in-memory consumers that only need `ConfigService`, option types, or `loadConfig(...)` with explicit in-memory inputs. Non-Node runtimes are supported for those portable paths. Env-file, default `.env`, and watch execution remain Node-only and require a host with `process.getBuiltinModule(...)`; unsupported hosts receive the documented `CONFIG_RUNTIME_UNAVAILABLE` error instead of an eager import failure.
 
 ### Deep Merging
 Plain objects are deep-merged by key. Arrays and primitive values from higher-precedence sources completely replace lower-precedence ones.
@@ -104,9 +146,9 @@ The `schema` option accepts a synchronous [Standard Schema](https://standardsche
 
 `ConfigReloadManager.reload()` serializes reload work. If another reload is requested while the current reload is notifying listeners, the follow-up reload is queued and applied after the active notification finishes; if the active notification fails, the previous snapshot is restored and the queued reload is discarded. The same serialization and rollback contract applies to `createConfigReloader(...).reload()`, including manual reloads queued during watch-triggered notifications.
 
-Module registration and reloader creation snapshot caller-owned options before storing them. Later mutations to objects passed to `ConfigModule.forRoot(...)`, `ConfigReloadModule.forRoot(...)`, or `createConfigReloader(...)` do not affect bootstrap, manual reloads, or watch reloads. When `ConfigModule.forRoot({ watch: true, ... })` is used, the module starts an env-file watcher during application bootstrap, first aligns the injected `ConfigService` with the watch reloader baseline, and then updates the same injected `ConfigService` instance after successful watch reloads. Pass `onReloadError` when the application needs ownership of automatic watch reload failures from `ConfigModule`. In watch mode, the parent directory is watched for both existing and missing env files, so creating or atomically replacing the env file can trigger reload. Watch reloads compare the final env file content with the last committed watch baseline before reloading, so unchanged saves and change-then-revert bursts do not replace the in-process config snapshot.
+Module registration and reloader creation snapshot caller-owned options before storing them, including nested Standard Schema validator objects supplied through `schema`. This capture happens synchronously when `ConfigModule.forRoot(...)`, `ConfigReloadModule.forRoot(...)`, or `createConfigReloader(...)` is called, before provider resolution or application bootstrap. Config dictionaries, `processEnv`, and the Standard Schema descriptor are detached, while callable values such as `parse`, `onReloadError`, and the schema validator remain the references captured at that call. Later mutations to the option object or its snapshotted nested objects do not affect bootstrap, manual reloads, or watch reloads. When `ConfigModule.forRoot({ watch: true, ... })` is used, the module starts an env-file watcher during application bootstrap, first aligns the injected `ConfigService` with the watch reloader baseline, and then updates the same injected `ConfigService` instance after successful watch reloads. Pass `onReloadError` when the application needs ownership of automatic watch reload failures from `ConfigModule`. In watch mode, the parent directory is watched for both existing and missing env files, so creating or atomically replacing the env file can trigger reload. Watch reloads compare the final env file content with the last committed watch baseline before reloading, so unchanged saves and change-then-revert bursts do not replace the in-process config snapshot.
 
-`ConfigReloadModule` is the explicit injectable reload layer, not a standalone config source. Pair it with `ConfigModule` or another `ConfigService` provider when callers need `CONFIG_RELOADER` for manual reloads or subscriptions. Watchers created by `ConfigModule` or `ConfigReloadModule` are created only when `watch: true`, and they are closed during module shutdown. Enable `watch: true` on one layer for a given env file: use `ConfigModule` for automatic `ConfigService` updates, or `ConfigReloadModule` when callers need the injected reloader contract for subscriptions/manual reloads.
+`ConfigReloadModule` is the explicit injectable reload layer, not a standalone config source. Pair it with `ConfigModule` or another `ConfigService` provider when callers need `CONFIG_RELOADER` for manual reloads or subscriptions. Watchers created by `ConfigModule` or `ConfigReloadModule` are created only when `watch: true`, and they are closed during module shutdown. `ConfigReloadManager` shutdown is terminal: after `close()` or `onModuleDestroy()`, the manager never creates another reloader or watcher, `reload()`, `subscribe()`, and `subscribeError()` throw an `InvariantError`, and `current()` keeps returning the last committed snapshot. Enable `watch: true` on one layer for a given env file: use `ConfigModule` for automatic `ConfigService` updates, or `ConfigReloadModule` when callers need the injected reloader contract for subscriptions/manual reloads.
 
 ## Public API
 
@@ -126,14 +168,17 @@ The package also exports option and subscription types such as `ConfigModuleOpti
 
 ## Related Packages
 
-- **`@fluojs/runtime`**: Calls `loadConfig` internally during application bootstrap.
+- **`@fluojs/runtime`**: Does not provide configuration loading transitively. Applications that use `ConfigModule.forRoot(...)` or inject `ConfigService` must declare `@fluojs/config` as a direct dependency.
 - **Standard Schema validators**: Zod, Valibot, ArkType, and other compatible schema libraries can be passed through the `schema` option.
 
 ## Example Sources
 
 - `packages/config/src/load.ts`
+- `packages/config/src/options.ts`
+- `packages/config/src/module.ts`
 - `packages/config/src/service.ts`
 - `packages/config/src/load.test.ts`
 - `packages/config/src/reload-module.ts`
-- `docs/architecture/config-and-environments.md`
-- `docs/architecture/dev-reload-architecture.md`
+- `packages/config/src/reload-module.test.ts`
+- [Config and Environments](../../docs/architecture/config-and-environments.md)
+- [Dev Reload Architecture](../../docs/architecture/dev-reload-architecture.md)

package/dist/load.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"load.d.ts","sourceRoot":"","sources":["../src/load.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,gBAAgB,EAChB,iBAAiB,EAEjB,cAAc,EAKf,MAAM,YAAY,CAAC;AAisBpB;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,iBAAiB,GAAG,cAAc,CAgC/E;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,iBAAiB,GAAG,gBAAgB,CAEvE"}
+{"version":3,"file":"load.d.ts","sourceRoot":"","sources":["../src/load.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,gBAAgB,EAChB,iBAAiB,EAGjB,cAAc,EAKf,MAAM,YAAY,CAAC;AA0zBpB;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,iBAAiB,GAAG,cAAc,CAiC/E;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,iBAAiB,GAAG,gBAAgB,CAEvE"}

package/dist/load.js

@@ -2,7 +2,8 @@ import { FluoError } from '@fluojs/core';
 import { cloneConfigDictionary } from './clone.js';
 import { snapshotConfigLoadOptions } from './options.js';
 const reloadFailureReasons = new WeakMap();
-const nodeBuiltinRuntimeRequirement = 'Node.js 20.16.0 or newer is required when @fluojs/config loads env files or starts watch mode.';
+const nodeBuiltinRuntimeRequirement = 'Supported env-file loading and watch mode in @fluojs/config require Node.js >=24.0.0 <27.';
+const watchEventDebounceMs = 100;
 let requireNodeBuiltin;
 function resolveRequireNodeBuiltin() {
   if (requireNodeBuiltin) {
@@ -89,7 +90,7 @@ function unquoteEnvValue(value) {
   return quote === '"' ? unquoted.replace(/\\n/g, '\n').replace(/\\r/g, '\r') : unquoted;
 }
 function stripInlineEnvComment(value) {
-  const commentIndex = value.search(/\s#/);
+  const commentIndex = value.indexOf('#');
   return commentIndex === -1 ? value : value.slice(0, commentIndex);
 }
 function findClosingEnvQuote(value, quote) {
@@ -222,20 +223,60 @@ function rejectLegacyValidateOption(options) {
     });
   }
 }
+function rejectAmbiguousEnvFileOptions(options) {
+  if (options.envFilePaths === undefined) {
+    return;
+  }
+  if (options.envFile !== undefined || options.envFilePath !== undefined) {
+    throw new FluoError('Invalid configuration.', {
+      code: 'INVALID_CONFIG',
+      cause: new Error('`envFilePaths` cannot be combined with `envFile` or `envFilePath`. Use one explicit ordered list instead of mixing singular and list env-file options.')
+    });
+  }
+}
+function resolveEnvFilePaths(envFilePaths, cwd) {
+  if (envFilePaths.length === 0) {
+    return [];
+  }
+  const path = nodePath();
+  const baseDirectory = cwd ?? resolveCurrentWorkingDirectory();
+  const resolved = [];
+  const seen = new Set();
+  for (const entry of envFilePaths) {
+    if (typeof entry !== 'string' || entry.trim().length === 0) {
+      throw new FluoError('Invalid configuration.', {
+        code: 'INVALID_CONFIG',
+        cause: new Error('`envFilePaths` entries must be non-empty file path strings.')
+      });
+    }
+    const resolvedEntry = path.resolve(baseDirectory, entry);
+    if (seen.has(resolvedEntry)) {
+      throw new FluoError('Invalid configuration.', {
+        code: 'INVALID_CONFIG',
+        cause: new Error(`\`envFilePaths\` must not repeat the same resolved file. Duplicate entry: ${resolvedEntry}.`)
+      });
+    }
+    seen.add(resolvedEntry);
+    resolved.push(resolvedEntry);
+  }
+  return resolved;
+}
 function normalizeLoadOptions(options) {
   rejectLegacyValidateOption(options);
-  const hasExplicitEnvFile = options.envFilePath !== undefined || options.envFile !== undefined;
+  rejectAmbiguousEnvFileOptions(options);
+  const hasExplicitEnvFile = options.envFilePath !== undefined || options.envFile !== undefined || options.envFilePaths !== undefined;
   const hasExplicitInMemorySource = options.defaults !== undefined || options.processEnv !== undefined || options.runtimeOverrides !== undefined;
   const shouldUseDefaultEnvFile = !hasExplicitEnvFile && (options.cwd !== undefined || options.watch === true || !hasExplicitInMemorySource);
-  const cwd = shouldUseDefaultEnvFile && options.envFilePath === undefined && options.envFile === undefined ? options.cwd ?? resolveCurrentWorkingDirectory() : options.cwd;
-  const envFile = options.envFilePath ?? options.envFile ?? (cwd ? nodePath().join(cwd, '.env') : undefined);
+  const cwd = shouldUseDefaultEnvFile ? options.cwd ?? resolveCurrentWorkingDirectory() : options.cwd;
+  const singularEnvFile = options.envFilePath ?? options.envFile ?? (shouldUseDefaultEnvFile && cwd ? nodePath().join(cwd, '.env') : undefined);
+  const envFiles = options.envFilePaths === undefined ? singularEnvFile === undefined ? [] : [singularEnvFile] : resolveEnvFilePaths(options.envFilePaths, options.cwd);
   const defaults = options.defaults ?? {};
   const processEnv = options.processEnv ?? {};
   const safeProcessEnv = sanitizeProcessEnv(processEnv);
   const runtimeOverrides = options.runtimeOverrides ?? {};
   return {
     defaults,
-    envFile,
+    envFiles,
     parse: options.parse,
     runtimeOverrides,
     safeProcessEnv,
@@ -243,17 +284,18 @@ function normalizeLoadOptions(options) {
   };
 }
 function readEnvFileValues(options) {
-  if (options.envFile === undefined) {
-    return {};
-  }
-  try {
-    return parseEnvContent(nodeFs().readFileSync(options.envFile, 'utf8'), options.safeProcessEnv, options.parse);
-  } catch (error) {
-    if (isNodeFsError(error) && error.code === 'ENOENT') {
-      return {};
+  const layers = [];
+  for (const envFile of options.envFiles) {
+    try {
+      layers.push(parseEnvContent(nodeFs().readFileSync(envFile, 'utf8'), options.safeProcessEnv, options.parse));
+    } catch (error) {
+      if (isNodeFsError(error) && error.code === 'ENOENT') {
+        continue;
+      }
+      throw error;
     }
-    throw error;
   }
+  return layers;
 }
 function isPlainObject(value) {
   return typeof value === 'object' && value !== null && !Array.isArray(value);
@@ -281,8 +323,7 @@ function mergeConfigSources(...sources) {
   return merged;
 }
 function buildMergedConfig(options) {
-  const envFileValues = readEnvFileValues(options);
-  return mergeConfigSources(options.defaults, envFileValues, options.safeProcessEnv, options.runtimeOverrides);
+  return mergeConfigSources(options.defaults, ...readEnvFileValues(options), options.safeProcessEnv, options.runtimeOverrides);
 }
 function isPromiseLike(value) {
   return (typeof value === 'object' || typeof value === 'function') && value !== null && 'then' in value && typeof value.then === 'function';
@@ -337,7 +378,7 @@ function readConfigSchemaResult(result) {
   if (!isConfigSchemaSuccessResult(result)) {
     throw createInvalidConfigError(new Error('Standard Schema config validator returned a malformed result.'));
   }
-  return result.value;
+  return cloneConfigDictionary(result.value);
 }
 function validateConfig(options, merged) {
   if (!options.schema) {
@@ -377,6 +418,21 @@ function hashEnvFileContent(envFile) {
     throw error;
   }
 }
+function hashEnvFileListContent(envFiles) {
+  if (envFiles.length === 0) {
+    return undefined;
+  }
+  const digest = nodeCrypto().createHash('sha256');
+  let hasAnyFile = false;
+  for (const envFile of envFiles) {
+    const fileHash = hashEnvFileContent(envFile);
+    if (fileHash !== undefined) {
+      hasAnyFile = true;
+    }
+    digest.update(`${envFile}\u0000${fileHash ?? ''}\u0000`);
+  }
+  return hasAnyFile ? digest.digest('hex') : undefined;
+}
 function notifyReloadListeners(listeners, snapshot, reason) {
   for (const listener of listeners) {
     listener(cloneConfigDictionary(snapshot), reason);
@@ -424,43 +480,78 @@ function applyReload(normalized, state, listeners, reason) {
   }
 }
 function startReloaderWatcher(normalized, options, state, listeners, errorListeners) {
-  if (!options.watch) {
-    return undefined;
-  }
-  if (normalized.envFile === undefined) {
-    return undefined;
+  if (!options.watch || normalized.envFiles.length === 0) {
+    return [];
   }
   const path = nodePath();
   const fs = nodeFs();
-  const envFile = normalized.envFile;
-  const watchTarget = path.dirname(envFile);
-  const watchedEnvFileName = path.basename(envFile);
-  if (!fs.existsSync(watchTarget)) {
-    return undefined;
+  const watchedNamesByDirectory = new Map();
+  for (const envFile of normalized.envFiles) {
+    const directory = path.dirname(envFile);
+    const watchedNames = watchedNamesByDirectory.get(directory);
+    if (watchedNames) {
+      watchedNames.add(path.basename(envFile));
+      continue;
+    }
+    watchedNamesByDirectory.set(directory, new Set([path.basename(envFile)]));
   }
-  return fs.watch(watchTarget, {
-    persistent: false
-  }, (_eventType, filename) => {
-    if (filename !== null && filename.toString() !== watchedEnvFileName) {
-      return;
+  const scheduleWatchReload = () => {
+    if (state.watchReloadTimer !== undefined) {
+      clearTimeout(state.watchReloadTimer);
     }
-    try {
-      const nextEnvFileHash = hashEnvFileContent(envFile);
-      if (nextEnvFileHash === state.watchedEnvFileHash) {
-        return;
+    state.watchReloadTimer = setTimeout(() => {
+      state.watchReloadTimer = undefined;
+      try {
+        const nextEnvFileHash = hashEnvFileListContent(normalized.envFiles);
+        if (nextEnvFileHash === state.watchedEnvFileHash) {
+          return;
+        }
+        applyReload(normalized, state, listeners, 'watch');
+        state.watchedEnvFileHash = nextEnvFileHash;
+      } catch (error) {
+        notifyReloadErrorListeners(errorListeners, error, getReloadFailureReason(error) ?? 'watch');
       }
-      applyReload(normalized, state, listeners, 'watch');
-      state.watchedEnvFileHash = nextEnvFileHash;
-    } catch (error) {
-      notifyReloadErrorListeners(errorListeners, error, getReloadFailureReason(error) ?? 'watch');
+    }, watchEventDebounceMs);
+  };
+  const watchers = [];
+  try {
+    for (const [directory, watchedNames] of watchedNamesByDirectory) {
+      if (!fs.existsSync(directory)) {
+        continue;
+      }
+      watchers.push(fs.watch(directory, {
+        persistent: false
+      }, (_eventType, filename) => {
+        if (filename !== null && !watchedNames.has(filename.toString())) {
+          return;
+        }
+        scheduleWatchReload();
+      }));
     }
-  });
+  } catch (error) {
+    rollBackStartedWatchers(watchers);
+    throw error;
+  }
+  return watchers;
+}
+function rollBackStartedWatchers(watchers) {
+  for (const watcher of watchers) {
+    try {
+      watcher.close();
+    } catch {
+      // A cleanup failure must never mask the watcher initialization error being rethrown.
+    }
+  }
 }
 function closeReloader(state, listeners, errorListeners) {
-  if (state.watcher) {
-    state.watcher.close();
-    state.watcher = undefined;
+  if (state.watchReloadTimer !== undefined) {
+    clearTimeout(state.watchReloadTimer);
+    state.watchReloadTimer = undefined;
+  }
+  for (const watcher of state.watchers) {
+    watcher.close();
   }
+  state.watchers = [];
   listeners.clear();
   errorListeners.clear();
 }
@@ -492,12 +583,13 @@ export function createConfigReloader(options) {
     current: resolveConfig(normalized),
     pendingReloadReason: undefined,
     reloading: false,
-    watchedEnvFileHash: normalized.envFile === undefined ? undefined : hashEnvFileContent(normalized.envFile),
-    watcher: undefined
+    watchedEnvFileHash: hashEnvFileListContent(normalized.envFiles),
+    watchReloadTimer: undefined,
+    watchers: []
   };
   const listeners = new Set();
   const errorListeners = new Set();
-  state.watcher = startReloaderWatcher(normalized, loadOptions, state, listeners, errorListeners);
+  state.watchers = startReloaderWatcher(normalized, loadOptions, state, listeners, errorListeners);
   return {
     close() {
       closeReloader(state, listeners, errorListeners);

package/dist/module.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"module.d.ts","sourceRoot":"","sources":["../src/module.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,mBAAmB,EAA4C,MAAM,YAAY,CAAC;AAmDhG;;GAEG;AACH,qBAAa,YAAY;IACvB;;;;;;;;;;;;;;;;;;OAkBG;IACH,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,mBAAmB,GAAG,UAAU,YAAY;CA4BtE"}
+{"version":3,"file":"module.d.ts","sourceRoot":"","sources":["../src/module.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,mBAAmB,EAA4C,MAAM,YAAY,CAAC;AAmDhG;;GAEG;AACH,qBAAa,YAAY;IACvB;;;;;;;;;;;;;;;;;;OAkBG;IACH,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,mBAAmB,GAAG,UAAU,YAAY;CA2BtE"}

package/dist/module.js

@@ -86,13 +86,10 @@ export class ConfigModule {
     const providers = [{
       provide: ConfigService,
       useFactory: () => createConfigServiceFromSnapshot(loadConfig(loadOptions))
-    }];
-    if (loadOptions.watch) {
-      providers.push({
-        provide: CONFIG_MODULE_WATCH_OPTIONS,
-        useValue: loadOptions
-      }, _ConfigModuleWatchMan);
-    }
+    }, ...(loadOptions.watch ? [{
+      provide: CONFIG_MODULE_WATCH_OPTIONS,
+      useValue: loadOptions
+    }, _ConfigModuleWatchMan] : [])];
     defineModuleMetadata(ConfigModuleImpl, {
       global: loadOptions.global ?? true,
       exports: [ConfigService],

package/dist/options.d.ts

@@ -3,14 +3,14 @@ import type { ConfigLoadOptions, ConfigModuleOptions } from './types.js';
  * Creates a detached snapshot of config module registration options.
  *
  * @param options Caller-owned module options captured at registration time.
- * @returns Options that cannot observe later caller mutations of config dictionaries.
+ * @returns Options that cannot observe later caller mutations of config dictionaries or schema objects.
  */
 export declare function snapshotConfigModuleOptions(options?: ConfigModuleOptions): ConfigModuleOptions;
 /**
  * Creates a detached snapshot of config load and reload options.
  *
  * @param options Caller-owned load options captured by loaders or reload modules.
- * @returns Options that preserve registration-time config dictionary inputs.
+ * @returns Options that preserve registration-time config dictionary and schema inputs.
  */
 export declare function snapshotConfigLoadOptions(options?: ConfigLoadOptions): ConfigLoadOptions;
 //# sourceMappingURL=options.d.ts.map

package/dist/options.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"options.d.ts","sourceRoot":"","sources":["../src/options.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAoB,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAsB3F;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,CAAC,EAAE,mBAAmB,GAAG,mBAAmB,CAU9F;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,CAAC,EAAE,iBAAiB,GAAG,iBAAiB,CAWxF"}
+{"version":3,"file":"options.d.ts","sourceRoot":"","sources":["../src/options.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAoB,iBAAiB,EAAE,mBAAmB,EAAkC,MAAM,YAAY,CAAC;AA4C3H;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,CAAC,EAAE,mBAAmB,GAAG,mBAAmB,CAa9F;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,CAAC,EAAE,iBAAiB,GAAG,iBAAiB,CAaxF"}

package/dist/options.js

@@ -2,6 +2,9 @@ import { cloneConfigDictionary } from './clone.js';
 function snapshotConfigDictionary(value) {
   return value === undefined ? undefined : cloneConfigDictionary(value);
 }
+function snapshotEnvFilePaths(envFilePaths) {
+  return envFilePaths === undefined ? undefined : Object.freeze([...envFilePaths]);
+}
 function snapshotProcessEnv(processEnv) {
   if (processEnv === undefined) {
     return undefined;
@@ -14,12 +17,27 @@ function snapshotProcessEnv(processEnv) {
   }
   return Object.freeze(snapshot);
 }
+function snapshotConfigSchema(schema) {
+  if (schema === undefined) {
+    return undefined;
+  }
+  const standard = schema['~standard'];
+  const snapshot = {
+    '~standard': Object.freeze({
+      types: standard.types,
+      validate: standard.validate,
+      vendor: standard.vendor,
+      version: standard.version
+    })
+  };
+  return Object.freeze(snapshot);
+}
 
 /**
  * Creates a detached snapshot of config module registration options.
  *
  * @param options Caller-owned module options captured at registration time.
- * @returns Options that cannot observe later caller mutations of config dictionaries.
+ * @returns Options that cannot observe later caller mutations of config dictionaries or schema objects.
  */
 export function snapshotConfigModuleOptions(options) {
   if (options === undefined) {
@@ -28,7 +46,10 @@ export function snapshotConfigModuleOptions(options) {
   return Object.freeze({
     ...options,
     defaults: snapshotConfigDictionary(options.defaults),
-    processEnv: snapshotProcessEnv(options.processEnv)
+    envFilePaths: snapshotEnvFilePaths(options.envFilePaths),
+    processEnv: snapshotProcessEnv(options.processEnv),
+    runtimeOverrides: snapshotConfigDictionary(options.runtimeOverrides),
+    schema: snapshotConfigSchema(options.schema)
   });
 }
 
@@ -36,7 +57,7 @@ export function snapshotConfigModuleOptions(options) {
  * Creates a detached snapshot of config load and reload options.
  *
  * @param options Caller-owned load options captured by loaders or reload modules.
- * @returns Options that preserve registration-time config dictionary inputs.
+ * @returns Options that preserve registration-time config dictionary and schema inputs.
  */
 export function snapshotConfigLoadOptions(options) {
   if (options === undefined) {
@@ -45,7 +66,9 @@ export function snapshotConfigLoadOptions(options) {
   return Object.freeze({
     ...options,
     defaults: snapshotConfigDictionary(options.defaults),
+    envFilePaths: snapshotEnvFilePaths(options.envFilePaths),
     processEnv: snapshotProcessEnv(options.processEnv),
-    runtimeOverrides: snapshotConfigDictionary(options.runtimeOverrides)
+    runtimeOverrides: snapshotConfigDictionary(options.runtimeOverrides),
+    schema: snapshotConfigSchema(options.schema)
   });
 }

package/dist/reload-module.d.ts

@@ -6,10 +6,18 @@ import type { ConfigDictionary, ConfigLoadOptions, ConfigReloadErrorListener, Co
 export declare const CONFIG_RELOADER: unique symbol;
 /**
  * Lazily creates and coordinates the active config reloader instance.
+ *
+ * @remarks
+ * `close()` and `onModuleDestroy()` are terminal. After shutdown the manager never creates another
+ * reloader or watcher, `onApplicationBootstrap()` becomes a no-op, and `current()` keeps returning the
+ * last committed `ConfigService` snapshot.
+ *
+ * @throws {InvariantError} When `reload()`, `subscribe()`, or `subscribeError()` is called after shutdown.
  */
 export declare class ConfigReloadManager implements ConfigReloader {
     private readonly config;
     private readonly options;
+    private closed;
     private reloader;
     private reloadForwarder;
     private errorForwarder;
@@ -23,6 +31,7 @@ export declare class ConfigReloadManager implements ConfigReloader {
     close(): void;
     onApplicationBootstrap(): void;
     onModuleDestroy(): void;
+    private assertNotClosed;
     private ensureReloader;
 }
 /**

package/dist/reload-module.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"reload-module.d.ts","sourceRoot":"","sources":["../src/reload-module.ts"],"names":[],"mappings":"AAMA,OAAO,EACL,aAAa,EAEd,MAAM,cAAc,CAAC;AACtB,OAAO,KAAK,EACV,gBAAgB,EAChB,iBAAiB,EACjB,yBAAyB,EACzB,cAAc,EACd,oBAAoB,EACpB,wBAAwB,EACzB,MAAM,YAAY,CAAC;AAIpB;;GAEG;AACH,eAAO,MAAM,eAAe,eAAiC,CAAC;AAY9D;;GAEG;AACH,qBACa,mBAAoB,YAAW,cAAc;IAQtD,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAR1B,OAAO,CAAC,QAAQ,CAA6B;IAC7C,OAAO,CAAC,eAAe,CAAuC;IAC9D,OAAO,CAAC,cAAc,CAAuC;IAC7D,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAmC;IACnE,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAwC;gBAGpD,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,iBAAiB;IAG7C,OAAO,IAAI,gBAAgB;IAI3B,MAAM,IAAI,gBAAgB;IAI1B,SAAS,CAAC,QAAQ,EAAE,oBAAoB,GAAG,wBAAwB;IAInE,cAAc,CAAC,QAAQ,EAAE,yBAAyB,GAAG,wBAAwB;IAI7E,KAAK,IAAI,IAAI;IAeb,sBAAsB,IAAI,IAAI;IAQ9B,eAAe,IAAI,IAAI;IAIvB,OAAO,CAAC,cAAc;CA8BvB;AAED;;GAEG;AACH,qBAAa,kBAAkB;IAC7B,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,iBAAiB,GAAG,UAAU,kBAAkB;CAsB1E"}
+{"version":3,"file":"reload-module.d.ts","sourceRoot":"","sources":["../src/reload-module.ts"],"names":[],"mappings":"AAMA,OAAO,EACL,aAAa,EAEd,MAAM,cAAc,CAAC;AACtB,OAAO,KAAK,EACV,gBAAgB,EAChB,iBAAiB,EACjB,yBAAyB,EACzB,cAAc,EACd,oBAAoB,EACpB,wBAAwB,EACzB,MAAM,YAAY,CAAC;AAIpB;;GAEG;AACH,eAAO,MAAM,eAAe,eAAiC,CAAC;AAY9D;;;;;;;;;GASG;AACH,qBACa,mBAAoB,YAAW,cAAc;IAStD,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAT1B,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,QAAQ,CAA6B;IAC7C,OAAO,CAAC,eAAe,CAAuC;IAC9D,OAAO,CAAC,cAAc,CAAuC;IAC7D,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAmC;IACnE,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAwC;gBAGpD,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,iBAAiB;IAG7C,OAAO,IAAI,gBAAgB;IAI3B,MAAM,IAAI,gBAAgB;IAM1B,SAAS,CAAC,QAAQ,EAAE,oBAAoB,GAAG,wBAAwB;IAMnE,cAAc,CAAC,QAAQ,EAAE,yBAAyB,GAAG,wBAAwB;IAM7E,KAAK,IAAI,IAAI;IAgBb,sBAAsB,IAAI,IAAI;IAQ9B,eAAe,IAAI,IAAI;IAIvB,OAAO,CAAC,eAAe;IAMvB,OAAO,CAAC,cAAc;CA8BvB;AAED;;GAEG;AACH,qBAAa,kBAAkB;IAC7B,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,iBAAiB,GAAG,UAAU,kBAAkB;CAsB1E"}

package/dist/reload-module.js

@@ -4,7 +4,7 @@ function _toPropertyKey(t) { var i = _toPrimitive(t, "string"); return "symbol"
 function _toPrimitive(t, r) { if ("object" != typeof t || !t) return t; var e = t[Symbol.toPrimitive]; if (void 0 !== e) { var i = e.call(t, r || "default"); if ("object" != typeof i) return i; throw new TypeError("@@toPrimitive must return a primitive value."); } return ("string" === r ? String : Number)(t); }
 function _setFunctionName(e, t, n) { "symbol" == typeof t && (t = (t = t.description) ? "[" + t + "]" : ""); try { Object.defineProperty(e, "name", { configurable: !0, value: n ? n + " " + t : t }); } catch (e) {} return e; }
 function _checkInRHS(e) { if (Object(e) !== e) throw TypeError("right-hand side of 'in' should be an object, got " + (null !== e ? typeof e : "null")); return e; }
-import { Inject } from '@fluojs/core';
+import { Inject, InvariantError } from '@fluojs/core';
 import { defineModuleMetadata } from '@fluojs/core/internal';
 import { cloneConfigDictionary } from './clone.js';
 import { createConfigReloader } from './load.js';
@@ -27,12 +27,20 @@ function createSubscription(listeners, listener) {
 
 /**
  * Lazily creates and coordinates the active config reloader instance.
+ *
+ * @remarks
+ * `close()` and `onModuleDestroy()` are terminal. After shutdown the manager never creates another
+ * reloader or watcher, `onApplicationBootstrap()` becomes a no-op, and `current()` keeps returning the
+ * last committed `ConfigService` snapshot.
+ *
+ * @throws {InvariantError} When `reload()`, `subscribe()`, or `subscribeError()` is called after shutdown.
  */
 let _ConfigReloadManager;
 class ConfigReloadManager {
   static {
     [_ConfigReloadManager, _initClass] = _applyDecs(this, [Inject(ConfigService, CONFIG_RELOAD_OPTIONS)], []).c;
   }
+  closed = false;
   reloader;
   reloadForwarder;
   errorForwarder;
@@ -46,15 +54,19 @@ class ConfigReloadManager {
     return this.config.snapshot();
   }
   reload() {
+    this.assertNotClosed('reload');
     return this.ensureReloader().reload();
   }
   subscribe(listener) {
+    this.assertNotClosed('subscribe');
     return createSubscription(this.reloadListeners, listener);
   }
   subscribeError(listener) {
+    this.assertNotClosed('subscribeError');
     return createSubscription(this.errorListeners, listener);
   }
   close() {
+    this.closed = true;
     this.reloadForwarder?.unsubscribe();
     this.reloadForwarder = undefined;
     this.errorForwarder?.unsubscribe();
@@ -67,7 +79,7 @@ class ConfigReloadManager {
     this.errorListeners.clear();
   }
   onApplicationBootstrap() {
-    if (!this.options.watch) {
+    if (this.closed || !this.options.watch) {
       return;
     }
     this.ensureReloader();
@@ -75,6 +87,11 @@ class ConfigReloadManager {
   onModuleDestroy() {
     this.close();
   }
+  assertNotClosed(operation) {
+    if (this.closed) {
+      throw new InvariantError(`Config reload manager cannot ${operation} after shutdown has started.`);
+    }
+  }
   ensureReloader() {
     if (this.reloader) {
       return this.reloader;

package/dist/types.d.ts

@@ -3,6 +3,14 @@ import type { StandardSchemaV1 } from '@standard-schema/spec';
  * Plain JSON-like object used as the normalized configuration snapshot shape.
  */
 export type ConfigDictionary = Record<string, unknown>;
+/**
+ * Structural process-environment snapshot accepted by `@fluojs/config`.
+ *
+ * Declared by this package instead of the ambient `NodeJS.ProcessEnv` namespace so the
+ * published declarations resolve for strict consumers without Node ambient types. A
+ * `NodeJS.ProcessEnv` value remains assignable because it has the same structure.
+ */
+export type ConfigProcessEnv = Record<string, string | undefined>;
 /**
  * Standard Schema v1-compatible config validator accepted by `@fluojs/config` loaders.
  *
@@ -27,9 +35,20 @@ export type DotValue<T, K extends string> = K extends keyof T ? T[K] : K extends
 export interface ConfigModuleOptions {
     envFile?: string;
     envFilePath?: string;
-    processEnv?: NodeJS.ProcessEnv;
+    /**
+     * Explicit ordered env-file list merged from lowest to highest precedence.
+     *
+     * Entries are resolved against `cwd` when relative, missing files contribute nothing,
+     * and the merged result stays below `processEnv` and `runtimeOverrides`. Combining this
+     * option with `envFile` or `envFilePath`, repeating a resolved path, or passing a blank
+     * entry fails with `INVALID_CONFIG`. An empty list opts out of env-file loading entirely.
+     */
+    envFilePaths?: readonly string[];
+    processEnv?: ConfigProcessEnv;
     schema?: ConfigSchema;
     defaults?: ConfigDictionary;
+    /** Highest-precedence values applied after defaults, env files, and `processEnv`. */
+    runtimeOverrides?: ConfigDictionary;
     /** Supply a custom file parser (e.g. for YAML or TOML). Receives raw file content,
      *  returns a flat key-value record. Defaults to dotenv parsing. */
     parse?: (content: string) => Record<string, string>;
@@ -44,7 +63,6 @@ export interface ConfigModuleOptions {
  */
 export interface ConfigLoadOptions extends ConfigModuleOptions {
     cwd?: string;
-    runtimeOverrides?: ConfigDictionary;
 }
 /**
  * Reason attached to config reload notifications.

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAE9D;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEvD;;;;;GAKG;AACH,MAAM,MAAM,YAAY,CAAC,KAAK,GAAG,OAAO,EAAE,MAAM,SAAS,gBAAgB,GAAG,gBAAgB,IAAI,gBAAgB,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;AAEhI;;;GAGG;AACH,MAAM,MAAM,QAAQ,CAAC,CAAC,EAAE,MAAM,SAAS,MAAM,GAAG,EAAE,IAAI,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACnF;KACG,CAAC,IAAI,MAAM,CAAC,GAAG,MAAM,GAClB,GAAG,MAAM,GAAG,CAAC,EAAE,GACf,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,MAAM,GAAG,CAAC,GAAG,CAAC;CACrC,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC,GACnB,KAAK,CAAC;AAEV;;GAEG;AACH,MAAM,MAAM,QAAQ,CAAC,CAAC,EAAE,CAAC,SAAS,MAAM,IAAI,CAAC,SAAS,MAAM,CAAC,GACzD,CAAC,CAAC,CAAC,CAAC,GACJ,CAAC,SAAS,GAAG,MAAM,IAAI,IAAI,MAAM,IAAI,EAAE,GACrC,IAAI,SAAS,MAAM,CAAC,GAClB,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,GACvB,KAAK,GACP,KAAK,CAAC;AAEZ;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IAC/B,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,QAAQ,CAAC,EAAE,gBAAgB,CAAC;IAC5B;uEACmE;IACnE,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpD,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,wEAAwE;IACxE,aAAa,CAAC,EAAE,yBAAyB,CAAC;IAC1C,qFAAqF;IACrF,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAkB,SAAQ,mBAAmB;IAC5D,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;CACrC;AAED;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG,QAAQ,GAAG,OAAO,CAAC;AAEpD;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,QAAQ,EAAE,gBAAgB,EAAE,MAAM,EAAE,kBAAkB,KAAK,IAAI,CAAC;AAEpG;;GAEG;AACH,MAAM,MAAM,yBAAyB,GAAG,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,kBAAkB,KAAK,IAAI,CAAC;AAE7F;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,WAAW,IAAI,IAAI,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,OAAO,IAAI,gBAAgB,CAAC;IAC5B,MAAM,IAAI,gBAAgB,CAAC;IAC3B,SAAS,CAAC,QAAQ,EAAE,oBAAoB,GAAG,wBAAwB,CAAC;IACpE,cAAc,CAAC,QAAQ,EAAE,yBAAyB,GAAG,wBAAwB,CAAC;IAC9E,KAAK,IAAI,IAAI,CAAC;CACf"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAE9D;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEvD;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;AAElE;;;;;GAKG;AACH,MAAM,MAAM,YAAY,CAAC,KAAK,GAAG,OAAO,EAAE,MAAM,SAAS,gBAAgB,GAAG,gBAAgB,IAAI,gBAAgB,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;AAEhI;;;GAGG;AACH,MAAM,MAAM,QAAQ,CAAC,CAAC,EAAE,MAAM,SAAS,MAAM,GAAG,EAAE,IAAI,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACnF;KACG,CAAC,IAAI,MAAM,CAAC,GAAG,MAAM,GAClB,GAAG,MAAM,GAAG,CAAC,EAAE,GACf,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,MAAM,GAAG,CAAC,GAAG,CAAC;CACrC,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC,GACnB,KAAK,CAAC;AAEV;;GAEG;AACH,MAAM,MAAM,QAAQ,CAAC,CAAC,EAAE,CAAC,SAAS,MAAM,IAAI,CAAC,SAAS,MAAM,CAAC,GACzD,CAAC,CAAC,CAAC,CAAC,GACJ,CAAC,SAAS,GAAG,MAAM,IAAI,IAAI,MAAM,IAAI,EAAE,GACrC,IAAI,SAAS,MAAM,CAAC,GAClB,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,GACvB,KAAK,GACP,KAAK,CAAC;AAEZ;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAC9B,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,QAAQ,CAAC,EAAE,gBAAgB,CAAC;IAC5B,qFAAqF;IACrF,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IACpC;uEACmE;IACnE,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpD,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,wEAAwE;IACxE,aAAa,CAAC,EAAE,yBAAyB,CAAC;IAC1C,qFAAqF;IACrF,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAkB,SAAQ,mBAAmB;IAC5D,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG,QAAQ,GAAG,OAAO,CAAC;AAEpD;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,QAAQ,EAAE,gBAAgB,EAAE,MAAM,EAAE,kBAAkB,KAAK,IAAI,CAAC;AAEpG;;GAEG;AACH,MAAM,MAAM,yBAAyB,GAAG,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,kBAAkB,KAAK,IAAI,CAAC;AAE7F;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,WAAW,IAAI,IAAI,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,OAAO,IAAI,gBAAgB,CAAC;IAC5B,MAAM,IAAI,gBAAgB,CAAC;IAC3B,SAAS,CAAC,QAAQ,EAAE,oBAAoB,GAAG,wBAAwB,CAAC;IACpE,cAAc,CAAC,QAAQ,EAAE,yBAAyB,GAAG,wBAAwB,CAAC;IAC9E,KAAK,IAAI,IAAI,CAAC;CACf"}

package/package.json

@@ -8,7 +8,7 @@
     "environment",
     "typed-config"
   ],
-  "version": "1.0.3",
+  "version": "2.0.0",
   "private": false,
   "license": "MIT",
   "repository": {
@@ -16,9 +16,6 @@
     "url": "https://github.com/fluojs/fluo.git",
     "directory": "packages/config"
   },
-  "engines": {
-    "node": ">=20.16.0"
-  },
   "publishConfig": {
     "access": "public"
   },
@@ -36,11 +33,11 @@
   ],
   "dependencies": {
     "@standard-schema/spec": "^1.1.0",
-    "@fluojs/core": "^1.0.3"
+    "@fluojs/core": "^2.0.0"
   },
   "devDependencies": {
-    "vitest": "^3.2.4",
-    "@fluojs/di": "^1.1.0"
+    "vitest": "^4.1.11",
+    "@fluojs/di": "^3.0.0"
   },
   "scripts": {
     "prebuild": "node ../../tooling/scripts/clean-dist.mjs",