@fluojs/config 1.0.0-beta.1 → 1.0.0-beta.3

package/README.ko.md

@@ -80,15 +80,26 @@ class MyService {
 
 `validate` 함수는 모든 소스가 합쳐진 뒤 실행되며, 에러를 던지면 부트스트랩이 즉시 중단됩니다.
 
+### 런타임 접근과 리로드 비용 모델
+
+`ConfigService.get('a.b.c')`는 dot-path 세그먼트를 순서대로 탐색하므로 조회 비용은 path 깊이에 비례합니다. `get()`, `getOrThrow()`, `snapshot()`이 객체 형태의 값을 반환할 때는 분리된 clone을 반환합니다. 따라서 clone 비용은 반환되는 subtree 크기에 비례하며, 호출자 mutation은 활성 config snapshot에 영향을 주지 않습니다.
+
+`ConfigReloadManager.reload()`는 리로드 작업을 직렬화합니다. 현재 리로드가 listener 알림을 수행하는 동안 다른 리로드가 요청되면 후속 리로드는 큐에 들어가 활성 알림이 끝난 뒤 적용됩니다. 활성 알림이 실패하면 이전 snapshot을 복구하고 큐에 있던 리로드는 폐기합니다. 동일한 직렬화와 rollback 계약은 `createConfigReloader(...).reload()`에도 적용되며, watch로 시작된 알림 중 큐에 들어간 manual reload도 이 계약을 따릅니다.
+
 ## 공개 API
 
 | 클래스/헬퍼 | 설명 |
 |---|---|
 | `ConfigModule` | 설정을 전역 또는 지역으로 등록하기 위한 모듈입니다. |
+| `ConfigReloadModule` | 리로드 매니저를 등록하고 의존성 주입용 공유 `CONFIG_RELOADER` 토큰을 내보냅니다. |
+| `ConfigReloadManager` | 주입된 `ConfigService`의 리로드를 조정하며, 서비스 identity는 유지하고 스냅샷만 리로드 경로로 교체합니다. |
+| `CONFIG_RELOADER` | 공유 config reloader 계약을 위한 주입 토큰입니다. |
 | `ConfigService` | 설정 값에 타입 안전하게 접근하기 위한 읽기 전용 서비스입니다. 스냅샷 교체는 config reload 경로 내부에만 남습니다. |
 | `loadConfig(options)` | 설정을 수동으로 로드하기 위한 함수형 엔트리 포인트입니다. |
 | `createConfigReloader(options)` | 동적 설정 업데이트를 위한 리로더를 생성합니다. |
 
+`ConfigReloadManager.reload()`는 기존 `ConfigService` 인스턴스를 갱신하므로 소비자는 주입받은 서비스 identity를 유지하면서 새 스냅샷을 관찰합니다. 리로드 listener가 에러를 던지면 매니저는 이전 스냅샷을 복구하고 listener 에러를 다시 던집니다. `createConfigReloader(...).reload()`도 standalone reloader snapshot에 대해 동일한 listener 직렬화와 rollback 동작을 따릅니다.
+
 ## 관련 패키지
 
 - `@fluojs/runtime`: 부트스트랩 중 `loadConfig()`를 호출합니다.

package/README.md

@@ -85,15 +85,25 @@ Plain objects are deep-merged by key. Arrays and primitive values from higher-pr
 ### Validation
 The `validate` function runs after all sources are merged but before the application starts. If it throws, the application bootstrap fails immediately.
 
+### Runtime Access and Reload Cost Model
+`ConfigService.get('a.b.c')` resolves dot-path keys by walking each path segment, so lookup cost is proportional to path depth. When `get()`, `getOrThrow()`, or `snapshot()` returns an object-like value, the returned value is a detached clone; clone cost is proportional to the returned subtree size so caller mutations cannot affect the active config snapshot.
+
+`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.
+
 ## Public API
 
 | Class/Helper | Description |
 |---|---|
 | `ConfigModule` | Module for registering configuration globally or locally. |
+| `ConfigReloadModule` | Registers the reload manager and exports the shared `CONFIG_RELOADER` token for dependency injection. |
+| `ConfigReloadManager` | Coordinates reloads for the injected `ConfigService`, preserving service identity while replacing snapshots through the reload path. |
+| `CONFIG_RELOADER` | Injection token for the shared config reloader contract. |
 | `ConfigService` | Read-only service for typed access to configuration values. Snapshot replacement stays inside the config reload path. |
 | `loadConfig(options)` | Functional entry point for loading configuration manually. |
 | `createConfigReloader(options)` | Creates a reloader for dynamic configuration updates. |
 
+`ConfigReloadManager.reload()` updates the existing `ConfigService` instance so consumers keep their injected service identity while observing the new snapshot. If a reload listener throws, the manager restores the previous snapshot and rethrows the listener error. `createConfigReloader(...).reload()` follows the same listener serialization and rollback behavior for its standalone reloader snapshot.
+
 ## Related Packages
 
 - **`@fluojs/runtime`**: Calls `loadConfig` internally during application bootstrap.

package/dist/load.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"load.d.ts","sourceRoot":"","sources":["../src/load.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EACV,gBAAgB,EAChB,iBAAiB,EAEjB,cAAc,EAIf,MAAM,YAAY,CAAC;AA0MpB;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,iBAAiB,GAAG,cAAc,CA4B/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":"AASA,OAAO,KAAK,EACV,gBAAgB,EAChB,iBAAiB,EAEjB,cAAc,EAIf,MAAM,YAAY,CAAC;AAqQpB;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,iBAAiB,GAAG,cAAc,CA8B/E;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,iBAAiB,GAAG,gBAAgB,CAEvE"}

package/dist/load.js

@@ -4,6 +4,18 @@ import { FluoError } from '@fluojs/core';
 import { parse as dotenvParse } from 'dotenv';
 import { expand as dotenvExpand } from 'dotenv-expand';
 import { cloneConfigDictionary } from './clone.js';
+const reloadFailureReasons = new WeakMap();
+function markReloadFailure(error, reason) {
+  if (typeof error === 'object' && error !== null) {
+    reloadFailureReasons.set(error, reason);
+  }
+}
+function getReloadFailureReason(error) {
+  if (typeof error !== 'object' || error === null) {
+    return undefined;
+  }
+  return reloadFailureReasons.get(error);
+}
 function parseEnvContent(content, safeProcessEnv, customParser) {
   if (customParser) {
     return customParser(content);
@@ -37,27 +49,32 @@ function normalizeLoadOptions(options) {
   };
 }
 function readEnvFileValues(options) {
-  if (!existsSync(options.envFile)) {
-    return {};
+  try {
+    return parseEnvContent(readFileSync(options.envFile, 'utf8'), options.safeProcessEnv, options.parse);
+  } catch (error) {
+    if (typeof error === 'object' && error !== null && 'code' in error && error.code === 'ENOENT') {
+      return {};
+    }
+    throw error;
   }
-  return parseEnvContent(readFileSync(options.envFile, 'utf8'), options.safeProcessEnv, options.parse);
 }
 function isPlainObject(value) {
   return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
 function mergeConfigEntries(target, source) {
-  const merged = {
-    ...target
-  };
   for (const [key, sourceValue] of Object.entries(source)) {
-    const targetValue = merged[key];
+    const targetValue = target[key];
     if (isPlainObject(targetValue) && isPlainObject(sourceValue)) {
-      merged[key] = mergeConfigEntries(targetValue, sourceValue);
+      mergeConfigEntries(targetValue, sourceValue);
+      continue;
+    }
+    if (isPlainObject(sourceValue)) {
+      target[key] = mergeConfigEntries({}, sourceValue);
       continue;
     }
-    merged[key] = cloneConfigDictionary(sourceValue);
+    target[key] = cloneConfigDictionary(sourceValue);
   }
-  return merged;
+  return target;
 }
 function mergeConfigSources(...sources) {
   let merged = {};
@@ -101,7 +118,7 @@ function notifyReloadErrorListeners(listeners, error, reason) {
     listener(error, reason);
   }
 }
-function applyReload(normalized, state, listeners, reason) {
+function applyReloadNow(normalized, state, listeners, reason) {
   const previous = state.current;
   const next = resolveConfig(normalized);
   state.current = next;
@@ -113,6 +130,30 @@ function applyReload(normalized, state, listeners, reason) {
   }
   return cloneConfigDictionary(next);
 }
+function applyReload(normalized, state, listeners, reason) {
+  if (state.reloading) {
+    state.pendingReloadReason = reason;
+    return cloneConfigDictionary(state.current);
+  }
+  state.reloading = true;
+  let activeReason = reason;
+  try {
+    let latest = applyReloadNow(normalized, state, listeners, activeReason);
+    while (state.pendingReloadReason) {
+      const pendingReason = state.pendingReloadReason;
+      state.pendingReloadReason = undefined;
+      activeReason = pendingReason;
+      latest = applyReloadNow(normalized, state, listeners, pendingReason);
+    }
+    return latest;
+  } catch (error) {
+    markReloadFailure(error, activeReason);
+    throw error;
+  } finally {
+    state.pendingReloadReason = undefined;
+    state.reloading = false;
+  }
+}
 function startReloaderWatcher(normalized, options, state, listeners, errorListeners) {
   if (!options.watch || !existsSync(normalized.envFile)) {
     return undefined;
@@ -123,7 +164,7 @@ function startReloaderWatcher(normalized, options, state, listeners, errorListen
     try {
       applyReload(normalized, state, listeners, 'watch');
     } catch (error) {
-      notifyReloadErrorListeners(errorListeners, error, 'watch');
+      notifyReloadErrorListeners(errorListeners, error, getReloadFailureReason(error) ?? 'watch');
     }
   });
 }
@@ -160,6 +201,8 @@ export function createConfigReloader(options) {
   const normalized = normalizeLoadOptions(options);
   const state = {
     current: resolveConfig(normalized),
+    pendingReloadReason: undefined,
+    reloading: false,
     watcher: undefined
   };
   const listeners = new Set();

package/dist/module.js

@@ -1,6 +1,6 @@
 import { defineModuleMetadata } from '@fluojs/core/internal';
 import { loadConfig } from './load.js';
-import { ConfigService } from './service.js';
+import { ConfigService, createConfigServiceFromSnapshot } from './service.js';
 /**
  * Module facade that wires normalized configuration into the application container.
  */
@@ -31,7 +31,7 @@ export class ConfigModule {
       exports: [ConfigService],
       providers: [{
         provide: ConfigService,
-        useFactory: () => new ConfigService(loadConfig(options ?? {}))
+        useFactory: () => createConfigServiceFromSnapshot(loadConfig(options ?? {}))
       }]
     });
     return ConfigModuleImpl;

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

@@ -1 +1 @@
-{"version":3,"file":"reload-module.d.ts","sourceRoot":"","sources":["../src/reload-module.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,aAAa,EAAgC,MAAM,cAAc,CAAC;AAC3E,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":"AAKA,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"}

package/dist/reload-module.js

@@ -8,7 +8,7 @@ import { Inject } from '@fluojs/core';
 import { defineModuleMetadata } from '@fluojs/core/internal';
 import { cloneConfigDictionary } from './clone.js';
 import { createConfigReloader } from './load.js';
-import { ConfigService, replaceConfigServiceSnapshot } from './service.js';
+import { ConfigService, replaceConfigServiceSnapshotUnchecked } from './service.js';
 const CONFIG_RELOAD_OPTIONS = Symbol('fluo.config.reload-options');
 
 /**
@@ -42,7 +42,7 @@ class ConfigReloadManager {
     this.options = options;
   }
   current() {
-    return this.ensureReloader().current();
+    return this.config.snapshot();
   }
   reload() {
     return this.ensureReloader().reload();
@@ -82,12 +82,12 @@ class ConfigReloadManager {
     this.reloadForwarder = reloader.subscribe((nextConfig, reason) => {
       const previousConfig = this.config.snapshot();
       try {
-        replaceConfigServiceSnapshot(this.config, nextConfig);
+        replaceConfigServiceSnapshotUnchecked(this.config, nextConfig);
         for (const listener of this.reloadListeners) {
           listener(cloneConfigDictionary(nextConfig), reason);
         }
       } catch (error) {
-        replaceConfigServiceSnapshot(this.config, previousConfig);
+        replaceConfigServiceSnapshotUnchecked(this.config, previousConfig);
         throw error;
       }
     });

package/dist/service.d.ts

@@ -35,4 +35,18 @@ export declare class ConfigService<T extends Record<string, unknown> = ConfigDic
  * @param values The new configuration dictionary.
  */
 export declare function replaceConfigServiceSnapshot<T extends Record<string, unknown>>(service: ConfigService<T>, values: T): void;
+/**
+ * Replaces the underlying configuration snapshot with an already-detached value.
+ *
+ * @param service The `ConfigService` instance to update.
+ * @param values A trusted configuration dictionary that must not be mutated after adoption.
+ */
+export declare function replaceConfigServiceSnapshotUnchecked<T extends Record<string, unknown>>(service: ConfigService<T>, values: T): void;
+/**
+ * Creates a `ConfigService` by adopting an already-detached configuration snapshot.
+ *
+ * @param values A trusted configuration dictionary produced by the config loader.
+ * @returns A `ConfigService` backed by the provided snapshot without an additional constructor clone.
+ */
+export declare function createConfigServiceFromSnapshot<T extends Record<string, unknown>>(values: T): ConfigService<T>;
 //# sourceMappingURL=service.d.ts.map

package/dist/service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAMvE;;GAEG;AACH,qBAAa,aAAa,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,gBAAgB;IAC7E,OAAO,CAAC,MAAM,CAAI;gBAEN,MAAM,EAAE,CAAC;IAIrB;;;;;OAKG;IACH,GAAG,CAAC,CAAC,SAAS,QAAQ,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,QAAQ,CAAC,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,GAAG,SAAS;IAIvE;;;;;;OAMG;IACH,UAAU,CAAC,CAAC,SAAS,QAAQ,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,QAAQ,CAAC,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC;IAUlE;;;;OAIG;IACH,QAAQ,IAAI,gBAAgB;IAI5B,OAAO,CAAC,QAAQ;CAuBjB;AAED;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5E,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC,EACzB,MAAM,EAAE,CAAC,GACR,IAAI,CAEN"}
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAMvE;;GAEG;AACH,qBAAa,aAAa,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,gBAAgB;IAC7E,OAAO,CAAC,MAAM,CAAI;gBAEN,MAAM,EAAE,CAAC;IAIrB;;;;;OAKG;IACH,GAAG,CAAC,CAAC,SAAS,QAAQ,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,QAAQ,CAAC,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,GAAG,SAAS;IAIvE;;;;;;OAMG;IACH,UAAU,CAAC,CAAC,SAAS,QAAQ,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,QAAQ,CAAC,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC;IAUlE;;;;OAIG;IACH,QAAQ,IAAI,gBAAgB;IAI5B,OAAO,CAAC,QAAQ;CAuBjB;AAED;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5E,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC,EACzB,MAAM,EAAE,CAAC,GACR,IAAI,CAEN;AAED;;;;;GAKG;AACH,wBAAgB,qCAAqC,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACrF,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC,EACzB,MAAM,EAAE,CAAC,GACR,IAAI,CAEN;AAED;;;;;GAKG;AACH,wBAAgB,+BAA+B,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC,CAK9G"}

package/dist/service.js

@@ -78,4 +78,26 @@ export class ConfigService {
  */
 export function replaceConfigServiceSnapshot(service, values) {
   service['values'] = cloneConfigDictionary(values);
+}
+
+/**
+ * Replaces the underlying configuration snapshot with an already-detached value.
+ *
+ * @param service The `ConfigService` instance to update.
+ * @param values A trusted configuration dictionary that must not be mutated after adoption.
+ */
+export function replaceConfigServiceSnapshotUnchecked(service, values) {
+  service['values'] = values;
+}
+
+/**
+ * Creates a `ConfigService` by adopting an already-detached configuration snapshot.
+ *
+ * @param values A trusted configuration dictionary produced by the config loader.
+ * @returns A `ConfigService` backed by the provided snapshot without an additional constructor clone.
+ */
+export function createConfigServiceFromSnapshot(values) {
+  const service = Object.create(ConfigService.prototype);
+  service['values'] = values;
+  return service;
 }

package/package.json

@@ -8,7 +8,7 @@
     "environment",
     "typed-config"
   ],
-  "version": "1.0.0-beta.1",
+  "version": "1.0.0-beta.3",
   "private": false,
   "license": "MIT",
   "repository": {
@@ -37,7 +37,7 @@
   "dependencies": {
     "dotenv": "^16.0.0",
     "dotenv-expand": "^11.0.0",
-    "@fluojs/core": "^1.0.0-beta.1"
+    "@fluojs/core": "^1.0.0-beta.2"
   },
   "devDependencies": {
     "vitest": "^3.2.4"