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

package/README.ko.md

@@ -32,6 +32,12 @@ npm install @fluojs/config
 ```ts
 import { ConfigModule } from '@fluojs/config';
 import { Module } from '@fluojs/core';
+import { z } from 'zod';
+
+const EnvSchema = z.object({
+  DATABASE_URL: z.string().url(),
+  PORT: z.coerce.number().default(3000),
+});
 
 @Module({
   imports: [
@@ -41,10 +47,7 @@ import { Module } from '@fluojs/core';
         DATABASE_URL: process.env.DATABASE_URL,
       },
       defaults: { PORT: '3000' },
-      validate: (config) => {
-        if (!config.DATABASE_URL) throw new Error('DATABASE_URL이 필요합니다');
-        return config;
-      },
+      schema: EnvSchema,
     }),
   ],
 })
@@ -78,7 +81,9 @@ class MyService {
 
 ### 부트스트랩 전 검증
 
-`validate` 함수는 모든 소스가 합쳐진 뒤 실행되며, 에러를 던지면 부트스트랩이 즉시 중단됩니다.
+`schema` 옵션은 Zod, Valibot, ArkType 같은 동기식 [Standard Schema](https://standardschema.dev/schema) 호환 validator를 받습니다. 스키마는 모든 소스가 합쳐진 뒤 실행되고, 검증된 `value`가 최종 config snapshot이 됩니다. schema issue가 보고되면 bootstrap/load/reload는 `INVALID_CONFIG`로 실패합니다.
+
+`@fluojs/config`의 load와 reload API는 동기식입니다. 비동기 Standard Schema 결과는 `INVALID_CONFIG`로 거부되므로 config 검증에는 동기 스키마를 사용하세요.
 
 ### 런타임 접근과 리로드 비용 모델
 
@@ -86,6 +91,8 @@ class MyService {
 
 `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 입력은 바뀌지 않습니다. Watch mode에서 시작 시점에 env file이 없으면 빈 file snapshot처럼 취급하고 parent directory를 watch하므로, 나중에 env file을 생성해도 reload가 트리거될 수 있습니다.
+
 ## 공개 API
 
 | 클래스/헬퍼 | 설명 |
@@ -103,7 +110,7 @@ class MyService {
 ## 관련 패키지
 
 - `@fluojs/runtime`: 부트스트랩 중 `loadConfig()`를 호출합니다.
-- `@fluojs/validation`: `validate` 함수 안에서 스키마 기반 검증을 조합할 수 있습니다.
+- Standard Schema validator: Zod, Valibot, ArkType 및 호환 schema 라이브러리를 `schema` 옵션으로 전달할 수 있습니다.
 
 ## 예제 소스
 

package/README.md

@@ -35,6 +35,12 @@ The `ConfigModule` handles loading and validating your configuration during boot
 ```typescript
 import { Module } from '@fluojs/core';
 import { ConfigModule } from '@fluojs/config';
+import { z } from 'zod';
+
+const EnvSchema = z.object({
+  DATABASE_URL: z.string().url(),
+  PORT: z.coerce.number().default(3000),
+});
 
 @Module({
   imports: [
@@ -44,10 +50,7 @@ import { ConfigModule } from '@fluojs/config';
         DATABASE_URL: process.env.DATABASE_URL,
       },
       defaults: { PORT: '3000' },
-      validate: (config) => {
-        if (!config.DATABASE_URL) throw new Error('DATABASE_URL is required');
-        return config;
-      },
+      schema: EnvSchema,
     }),
   ],
 })
@@ -83,13 +86,17 @@ Configuration is merged in the following order (highest precedence wins):
 Plain objects are deep-merged by key. Arrays and primitive values from higher-precedence sources completely replace lower-precedence ones.
 
 ### Validation
-The `validate` function runs after all sources are merged but before the application starts. If it throws, the application bootstrap fails immediately.
+The `schema` option accepts a synchronous [Standard Schema](https://standardschema.dev/schema)-compatible validator such as Zod, Valibot, or ArkType. The schema runs after all sources are merged but before the application starts. Its validated `value` becomes the final config snapshot, and reported issues fail bootstrap/load/reload with `INVALID_CONFIG`.
+
+`@fluojs/config` keeps loading and reload APIs synchronous. Async Standard Schema results are rejected with `INVALID_CONFIG`; use a synchronous schema for config validation.
 
 ### 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.
 
+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. In watch mode, a missing env file at startup is treated as an empty file snapshot while the parent directory is watched so creating the env file later can still trigger reload.
+
 ## Public API
 
 | Class/Helper | Description |
@@ -107,7 +114,7 @@ The `validate` function runs after all sources are merged but before the applica
 ## Related Packages
 
 - **`@fluojs/runtime`**: Calls `loadConfig` internally during application bootstrap.
-- **`@fluojs/validation`**: Can be used within the `validate` function for schema-based validation.
+- **Standard Schema validators**: Zod, Valibot, ArkType, and other compatible schema libraries can be passed through the `schema` option.
 
 ## Example Sources
 

package/dist/clone.d.ts

@@ -1,2 +1,8 @@
+/**
+ * Clone config dictionary.
+ *
+ * @param value The value.
+ * @returns The clone config dictionary result.
+ */
 export declare function cloneConfigDictionary<T>(value: T): T;
 //# sourceMappingURL=clone.d.ts.map

package/dist/clone.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"clone.d.ts","sourceRoot":"","sources":["../src/clone.ts"],"names":[],"mappings":"AAEA,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CAMpD"}
+{"version":3,"file":"clone.d.ts","sourceRoot":"","sources":["../src/clone.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CAMpD"}

package/dist/clone.js

@@ -1,4 +1,11 @@
 import { fallbackClone } from '@fluojs/core/internal';
+
+/**
+ * Clone config dictionary.
+ *
+ * @param value The value.
+ * @returns The clone config dictionary result.
+ */
 export function cloneConfigDictionary(value) {
   try {
     return structuredClone(value);

package/dist/load.d.ts

@@ -2,7 +2,7 @@ import type { ConfigDictionary, ConfigLoadOptions, ConfigReloader } from './type
 /**
  * Creates a stateful config reloader that mirrors `loadConfig(...)` semantics and optionally watches the env file.
  *
- * @param options Configuration loading options, including optional watch mode and validation hooks.
+ * @param options Configuration loading options, including optional watch mode and a synchronous Standard Schema validator.
  * @returns A reloader that exposes the current snapshot, manual reload, subscriptions, and cleanup.
  * @throws {FluoError} When the initial config load or validation fails.
  *
@@ -25,7 +25,7 @@ export declare function createConfigReloader(options: ConfigLoadOptions): Config
  *
  * Merge precedence stays aligned with the package README contract: `defaults` < env file < `processEnv` < `runtimeOverrides`.
  *
- * @param options Configuration loading options for source precedence, parsing, and validation.
+ * @param options Configuration loading options for source precedence, parsing, and synchronous schema validation.
  * @returns A detached normalized configuration dictionary for the current load.
  * @throws {FluoError} When validation throws or the config cannot be normalized.
  */

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

package/dist/load.js

@@ -1,9 +1,10 @@
 import { existsSync, readFileSync, watch } from 'node:fs';
-import { join } from 'node:path';
+import { basename, dirname, join } from 'node:path';
 import { FluoError } from '@fluojs/core';
 import { parse as dotenvParse } from 'dotenv';
 import { expand as dotenvExpand } from 'dotenv-expand';
 import { cloneConfigDictionary } from './clone.js';
+import { snapshotConfigLoadOptions } from './options.js';
 const reloadFailureReasons = new WeakMap();
 function markReloadFailure(error, reason) {
   if (typeof error === 'object' && error !== null) {
@@ -32,7 +33,16 @@ function parseEnvContent(content, safeProcessEnv, customParser) {
 function sanitizeProcessEnv(processEnv) {
   return Object.fromEntries(Object.entries(processEnv).filter(entry => entry[1] !== undefined));
 }
+function rejectLegacyValidateOption(options) {
+  if ('validate' in options) {
+    throw new FluoError('Invalid configuration.', {
+      code: 'INVALID_CONFIG',
+      cause: new Error('The legacy `validate` option was removed. Use `schema` with a synchronous Standard Schema validator instead.')
+    });
+  }
+}
 function normalizeLoadOptions(options) {
+  rejectLegacyValidateOption(options);
   const cwd = options.cwd ?? process.cwd();
   const envFile = options.envFilePath ?? options.envFile ?? join(cwd, '.env');
   const defaults = options.defaults ?? {};
@@ -45,7 +55,7 @@ function normalizeLoadOptions(options) {
     parse: options.parse,
     runtimeOverrides,
     safeProcessEnv,
-    validate: options.validate
+    schema: options.schema
   };
 }
 function readEnvFileValues(options) {
@@ -87,14 +97,76 @@ function buildMergedConfig(options) {
   const envFileValues = readEnvFileValues(options);
   return mergeConfigSources(options.defaults, envFileValues, options.safeProcessEnv, options.runtimeOverrides);
 }
+function isPromiseLike(value) {
+  return (typeof value === 'object' || typeof value === 'function') && value !== null && 'then' in value && typeof value.then === 'function';
+}
+function isConfigSchemaIssue(value) {
+  return typeof value === 'object' && value !== null && 'message' in value && typeof value.message === 'string';
+}
+function isConfigSchemaFailureResult(value) {
+  if (typeof value !== 'object' || value === null || !('issues' in value)) {
+    return false;
+  }
+  return Array.isArray(value.issues) && value.issues.every(isConfigSchemaIssue);
+}
+function isConfigSchemaSuccessResult(value) {
+  return typeof value === 'object' && value !== null && 'value' in value && isPlainObject(value.value);
+}
+function isConfigSchemaPathKeySegment(value) {
+  if (typeof value !== 'object' || value === null || !('key' in value)) {
+    return false;
+  }
+  return typeof value.key === 'string' || typeof value.key === 'number' || typeof value.key === 'symbol';
+}
+function formatConfigSchemaPathSegment(segment) {
+  if (typeof segment === 'string' || typeof segment === 'number') {
+    return String(segment);
+  }
+  if (isConfigSchemaPathKeySegment(segment)) {
+    return String(segment.key);
+  }
+  return undefined;
+}
+function formatConfigSchemaIssue(issue) {
+  const path = issue.path?.map(formatConfigSchemaPathSegment).filter(segment => segment !== undefined).join('.');
+  return path && path.length > 0 ? `${path}: ${issue.message}` : issue.message;
+}
+function createInvalidConfigError(cause, issues) {
+  return new FluoError('Invalid configuration.', {
+    code: 'INVALID_CONFIG',
+    cause,
+    meta: issues ? {
+      issues: issues.map(formatConfigSchemaIssue)
+    } : undefined
+  });
+}
+function isInvalidConfigError(error) {
+  return error instanceof FluoError && error.code === 'INVALID_CONFIG';
+}
+function readConfigSchemaResult(result) {
+  if (isConfigSchemaFailureResult(result)) {
+    throw createInvalidConfigError(new Error('Standard Schema config validation failed.'), result.issues);
+  }
+  if (!isConfigSchemaSuccessResult(result)) {
+    throw createInvalidConfigError(new Error('Standard Schema config validator returned a malformed result.'));
+  }
+  return result.value;
+}
 function validateConfig(options, merged) {
+  if (!options.schema) {
+    return merged;
+  }
   try {
-    return options.validate ? options.validate(merged) : merged;
+    const result = options.schema['~standard'].validate(merged);
+    if (isPromiseLike(result)) {
+      throw new Error('Config schemas must validate synchronously. Async Standard Schema validation is not supported by the synchronous config API.');
+    }
+    return readConfigSchemaResult(result);
   } catch (error) {
-    throw new FluoError('Invalid configuration.', {
-      code: 'INVALID_CONFIG',
-      cause: error
-    });
+    if (isInvalidConfigError(error)) {
+      throw error;
+    }
+    throw createInvalidConfigError(error);
   }
 }
 function resolveConfig(options) {
@@ -155,12 +227,20 @@ function applyReload(normalized, state, listeners, reason) {
   }
 }
 function startReloaderWatcher(normalized, options, state, listeners, errorListeners) {
-  if (!options.watch || !existsSync(normalized.envFile)) {
+  if (!options.watch) {
     return undefined;
   }
-  return watch(normalized.envFile, {
+  const watchTarget = existsSync(normalized.envFile) ? normalized.envFile : dirname(normalized.envFile);
+  const watchedEnvFileName = basename(normalized.envFile);
+  if (!existsSync(watchTarget)) {
+    return undefined;
+  }
+  return watch(watchTarget, {
     persistent: false
-  }, () => {
+  }, (_eventType, filename) => {
+    if (watchTarget !== normalized.envFile && filename !== null && filename.toString() !== watchedEnvFileName) {
+      return;
+    }
     try {
       applyReload(normalized, state, listeners, 'watch');
     } catch (error) {
@@ -180,7 +260,7 @@ function closeReloader(state, listeners, errorListeners) {
 /**
  * Creates a stateful config reloader that mirrors `loadConfig(...)` semantics and optionally watches the env file.
  *
- * @param options Configuration loading options, including optional watch mode and validation hooks.
+ * @param options Configuration loading options, including optional watch mode and a synchronous Standard Schema validator.
  * @returns A reloader that exposes the current snapshot, manual reload, subscriptions, and cleanup.
  * @throws {FluoError} When the initial config load or validation fails.
  *
@@ -198,7 +278,8 @@ function closeReloader(state, listeners, errorListeners) {
  * ```
  */
 export function createConfigReloader(options) {
-  const normalized = normalizeLoadOptions(options);
+  const loadOptions = snapshotConfigLoadOptions(options);
+  const normalized = normalizeLoadOptions(loadOptions);
   const state = {
     current: resolveConfig(normalized),
     pendingReloadReason: undefined,
@@ -207,7 +288,7 @@ export function createConfigReloader(options) {
   };
   const listeners = new Set();
   const errorListeners = new Set();
-  state.watcher = startReloaderWatcher(normalized, options, state, listeners, errorListeners);
+  state.watcher = startReloaderWatcher(normalized, loadOptions, state, listeners, errorListeners);
   return {
     close() {
       closeReloader(state, listeners, errorListeners);
@@ -232,7 +313,7 @@ export function createConfigReloader(options) {
  *
  * Merge precedence stays aligned with the package README contract: `defaults` < env file < `processEnv` < `runtimeOverrides`.
  *
- * @param options Configuration loading options for source precedence, parsing, and validation.
+ * @param options Configuration loading options for source precedence, parsing, and synchronous schema validation.
  * @returns A detached normalized configuration dictionary for the current load.
  * @throws {FluoError} When validation throws or the config cannot be normalized.
  */

package/dist/module.d.ts.map

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

package/dist/module.js

@@ -1,5 +1,6 @@
 import { defineModuleMetadata } from '@fluojs/core/internal';
 import { loadConfig } from './load.js';
+import { snapshotConfigModuleOptions } from './options.js';
 import { ConfigService, createConfigServiceFromSnapshot } from './service.js';
 /**
  * Module facade that wires normalized configuration into the application container.
@@ -25,13 +26,14 @@ export class ConfigModule {
    * ```
    */
   static forRoot(options) {
+    const loadOptions = snapshotConfigModuleOptions(options);
     class ConfigModuleImpl extends ConfigModule {}
     defineModuleMetadata(ConfigModuleImpl, {
-      global: options?.isGlobal ?? true,
+      global: loadOptions.isGlobal ?? true,
       exports: [ConfigService],
       providers: [{
         provide: ConfigService,
-        useFactory: () => createConfigServiceFromSnapshot(loadConfig(options ?? {}))
+        useFactory: () => createConfigServiceFromSnapshot(loadConfig(loadOptions))
       }]
     });
     return ConfigModuleImpl;

package/dist/options.d.ts

@@ -0,0 +1,16 @@
+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.
+ */
+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.
+ */
+export declare function snapshotConfigLoadOptions(options?: ConfigLoadOptions): ConfigLoadOptions;
+//# sourceMappingURL=options.d.ts.map

package/dist/options.d.ts.map

@@ -0,0 +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"}

package/dist/options.js

@@ -0,0 +1,51 @@
+import { cloneConfigDictionary } from './clone.js';
+function snapshotConfigDictionary(value) {
+  return value === undefined ? undefined : cloneConfigDictionary(value);
+}
+function snapshotProcessEnv(processEnv) {
+  if (processEnv === undefined) {
+    return undefined;
+  }
+  const snapshot = {};
+  for (const [key, value] of Object.entries(processEnv)) {
+    if (value !== undefined) {
+      snapshot[key] = value;
+    }
+  }
+  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.
+ */
+export function snapshotConfigModuleOptions(options) {
+  if (options === undefined) {
+    return {};
+  }
+  return Object.freeze({
+    ...options,
+    defaults: snapshotConfigDictionary(options.defaults),
+    processEnv: snapshotProcessEnv(options.processEnv)
+  });
+}
+
+/**
+ * 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.
+ */
+export function snapshotConfigLoadOptions(options) {
+  if (options === undefined) {
+    return {};
+  }
+  return Object.freeze({
+    ...options,
+    defaults: snapshotConfigDictionary(options.defaults),
+    processEnv: snapshotProcessEnv(options.processEnv),
+    runtimeOverrides: snapshotConfigDictionary(options.runtimeOverrides)
+  });
+}

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,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;;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,6 +8,7 @@ import { Inject } from '@fluojs/core';
 import { defineModuleMetadata } from '@fluojs/core/internal';
 import { cloneConfigDictionary } from './clone.js';
 import { createConfigReloader } from './load.js';
+import { snapshotConfigLoadOptions } from './options.js';
 import { ConfigService, replaceConfigServiceSnapshotUnchecked } from './service.js';
 const CONFIG_RELOAD_OPTIONS = Symbol('fluo.config.reload-options');
 
@@ -110,7 +111,7 @@ class ConfigReloadManager {
 export { _ConfigReloadManager as ConfigReloadManager };
 export class ConfigReloadModule {
   static forRoot(options) {
-    const loadOptions = options ?? {};
+    const loadOptions = snapshotConfigLoadOptions(options);
     class ConfigReloadModuleImpl extends ConfigReloadModule {}
     defineModuleMetadata(ConfigReloadModuleImpl, {
       exports: [CONFIG_RELOADER],

package/dist/types.d.ts

@@ -1,7 +1,15 @@
+import type { StandardSchemaV1 } from '@standard-schema/spec';
 /**
  * Plain JSON-like object used as the normalized configuration snapshot shape.
  */
 export type ConfigDictionary = Record<string, unknown>;
+/**
+ * Standard Schema v1-compatible config validator accepted by `@fluojs/config` loaders.
+ *
+ * @typeParam Input Raw merged config shape consumed by the schema validator.
+ * @typeParam Output Normalized config shape produced by the schema validator.
+ */
+export type ConfigSchema<Input = unknown, Output extends ConfigDictionary = ConfigDictionary> = StandardSchemaV1<Input, Output>;
 /**
  * Nested dot-path key helper.
  * Produces "a" | "a.b" | "a.b.c" keys from a Record type.
@@ -20,7 +28,7 @@ export interface ConfigModuleOptions {
     envFile?: string;
     envFilePath?: string;
     processEnv?: NodeJS.ProcessEnv;
-    validate?: (raw: ConfigDictionary) => ConfigDictionary;
+    schema?: ConfigSchema;
     defaults?: 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. */

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEvD;;;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,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,gBAAgB,KAAK,gBAAgB,CAAC;IACvD,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,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;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;;;;;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,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;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"}

package/package.json

@@ -8,7 +8,7 @@
     "environment",
     "typed-config"
   ],
-  "version": "1.0.0-beta.3",
+  "version": "1.0.0-beta.5",
   "private": false,
   "license": "MIT",
   "repository": {
@@ -35,9 +35,10 @@
     "dist"
   ],
   "dependencies": {
+    "@standard-schema/spec": "^1.1.0",
     "dotenv": "^16.0.0",
     "dotenv-expand": "^11.0.0",
-    "@fluojs/core": "^1.0.0-beta.2"
+    "@fluojs/core": "^1.0.0-beta.3"
   },
   "devDependencies": {
     "vitest": "^3.2.4"