@fluojs/config 1.0.2 → 1.0.4

package/README.ko.md

@@ -20,6 +20,8 @@ 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을 따릅니다.
+
 ## 사용 시점
 
 - `.env` 파일과 명시적인 `processEnv` 스냅샷을 하나의 설정 스냅샷으로 합쳐야 할 때
@@ -79,7 +81,9 @@ class MyService {
 
 `@fluojs/config`는 주변 환경 변수를 자동으로 스캔하지 않습니다. 환경 기반 값을 우선순위에 포함하려면 부트스트랩 경계에서 `processEnv` 스냅샷을 명시적으로 전달하세요.
 
-`envFilePath`는 `envFile`보다 우선하며, `parse`를 사용하면 flat key/value 파일을 위한 custom parser로 dotenv parsing을 대체할 수 있습니다. 누락된 env file은 load 시 빈 입력처럼 처리됩니다. watch mode에서는 parent directory도 관찰하므로 나중에 파일을 생성해도 reload를 트리거할 수 있습니다.
+`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에 포함되지 않습니다.
 
 ### 객체 단위 딥 머지
 
@@ -97,7 +101,7 @@ 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 입력은 바뀌지 않습니다. `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으로 분리합니다. `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을 교체하지 않습니다.
 
 `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`을 사용합니다.
 

package/README.md

@@ -20,6 +20,8 @@ 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.
+
 ## When to Use
 
 Use this package when you need to:
@@ -85,7 +87,9 @@ Configuration is merged in the following order (highest precedence wins):
 
 `@fluojs/config` does not scan ambient environment variables automatically. Pass an explicit `processEnv` snapshot at the bootstrap boundary when process-backed values should participate in precedence.
 
-`envFilePath` overrides `envFile`, and `parse` lets callers replace dotenv parsing with a custom parser for flat key/value files. 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.
+`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.
 
 ### Deep Merging
 Plain objects are deep-merged by key. Arrays and primitive values from higher-precedence sources completely replace lower-precedence ones.
@@ -100,7 +104,7 @@ 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`. 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.
 
 `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.
 

package/dist/load.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"load.d.ts","sourceRoot":"","sources":["../src/load.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EACV,gBAAgB,EAChB,iBAAiB,EAEjB,cAAc,EAKf,MAAM,YAAY,CAAC;AAwZpB;;;;;;;;;;;;;;;;;;;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,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"}

package/dist/load.js

@@ -1,12 +1,71 @@
-import { createHash } from 'node:crypto';
-import { existsSync, readFileSync, watch } from 'node:fs';
-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();
+const nodeBuiltinRuntimeRequirement = 'Node.js 20.16.0 or newer is required when @fluojs/config loads env files or starts watch mode.';
+let requireNodeBuiltin;
+function resolveRequireNodeBuiltin() {
+  if (requireNodeBuiltin) {
+    return requireNodeBuiltin;
+  }
+  const nodeModule = globalThis.process?.getBuiltinModule?.('node:module');
+  if (!nodeModule?.createRequire) {
+    throw new FluoError('Node.js configuration loading is unavailable in this runtime.', {
+      code: 'CONFIG_RUNTIME_UNAVAILABLE',
+      cause: new Error(`${nodeBuiltinRuntimeRequirement} The host runtime did not expose a synchronous node:module loader. Use in-memory config options or run env-file loading on Node.js.`)
+    });
+  }
+  requireNodeBuiltin = nodeModule.createRequire(import.meta.url);
+  return requireNodeBuiltin;
+}
+function requireNodeBuiltinFallback(id) {
+  try {
+    return resolveRequireNodeBuiltin()(id);
+  } catch (error) {
+    if (error instanceof FluoError) {
+      throw error;
+    }
+    throw new FluoError('Node.js configuration loading is unavailable in this runtime.', {
+      code: 'CONFIG_RUNTIME_UNAVAILABLE',
+      cause: new Error(`${nodeBuiltinRuntimeRequirement} The host runtime could not load ${id}. Use in-memory config options or run env-file loading on Node.js.`, {
+        cause: error
+      })
+    });
+  }
+}
+function resolveNodeBuiltin(id) {
+  const getBuiltinModule = globalThis.process?.getBuiltinModule;
+  if (!getBuiltinModule) {
+    return requireNodeBuiltinFallback(id);
+  }
+  const module = getBuiltinModule(id);
+  if (!module) {
+    return requireNodeBuiltinFallback(id);
+  }
+  return module;
+}
+function nodeCrypto() {
+  return resolveNodeBuiltin('node:crypto');
+}
+function nodeFs() {
+  return resolveNodeBuiltin('node:fs');
+}
+function nodePath() {
+  return resolveNodeBuiltin('node:path');
+}
+function resolveCurrentWorkingDirectory() {
+  const cwd = globalThis.process?.cwd;
+  if (!cwd) {
+    throw new FluoError('Node.js configuration loading is unavailable in this runtime.', {
+      code: 'CONFIG_RUNTIME_UNAVAILABLE',
+      cause: new Error('The host runtime did not expose process.cwd(). Pass envFilePath or avoid env-file loading outside Node.js.')
+    });
+  }
+  return cwd();
+}
+function isNodeFsError(error) {
+  return typeof error === 'object' && error !== null && 'code' in error;
+}
 function markReloadFailure(error, reason) {
   if (typeof error === 'object' && error !== null) {
     reloadFailureReasons.set(error, reason);
@@ -18,18 +77,139 @@ function getReloadFailureReason(error) {
   }
   return reloadFailureReasons.get(error);
 }
+function unquoteEnvValue(value) {
+  if (value.length < 2) {
+    return value;
+  }
+  const quote = value[0];
+  if (quote !== '"' && quote !== "'" && quote !== '`' || value[value.length - 1] !== quote) {
+    return value;
+  }
+  const unquoted = value.slice(1, -1);
+  return quote === '"' ? unquoted.replace(/\\n/g, '\n').replace(/\\r/g, '\r') : unquoted;
+}
+function stripInlineEnvComment(value) {
+  const commentIndex = value.search(/\s#/);
+  return commentIndex === -1 ? value : value.slice(0, commentIndex);
+}
+function findClosingEnvQuote(value, quote) {
+  for (let index = 1; index < value.length; index += 1) {
+    if (value[index] === quote && value[index - 1] !== '\\') {
+      return index;
+    }
+  }
+  return -1;
+}
+function collectQuotedEnvValue(lines, startIndex, valueStart, quote) {
+  let value = valueStart;
+  let currentIndex = startIndex;
+  while (currentIndex + 1 < lines.length && findClosingEnvQuote(value, quote) === -1) {
+    currentIndex += 1;
+    value += `\n${lines[currentIndex]}`;
+  }
+  const closingQuoteIndex = findClosingEnvQuote(value, quote);
+  return {
+    nextIndex: currentIndex,
+    value: closingQuoteIndex === -1 ? value : value.slice(0, closingQuoteIndex + 1)
+  };
+}
+function parseDotenvContent(content) {
+  const parsed = {};
+  const lines = content.split(/\r?\n/);
+  for (let index = 0; index < lines.length; index += 1) {
+    const rawLine = lines[index];
+    const line = rawLine.trim();
+    if (line.length === 0 || line.startsWith('#')) {
+      continue;
+    }
+    const entry = line.startsWith('export ') ? line.slice(7).trimStart() : line;
+    const separatorIndex = entry.search(/[:=]/);
+    if (separatorIndex <= 0) {
+      continue;
+    }
+    const key = entry.slice(0, separatorIndex).trim();
+    const rawValue = entry.slice(separatorIndex + 1).trim();
+    if (!/^[\w.-]+$/.test(key)) {
+      continue;
+    }
+    const quote = rawValue[0];
+    const quotedValue = quote === '"' || quote === "'" || quote === '`';
+    const collected = quotedValue ? collectQuotedEnvValue(lines, index, rawValue, quote) : {
+      nextIndex: index,
+      value: stripInlineEnvComment(rawValue).trim()
+    };
+    index = collected.nextIndex;
+    parsed[key] = unquoteEnvValue(collected.value);
+  }
+  return parsed;
+}
+function expandEnvVariables(parsed, safeProcessEnv) {
+  const expanded = {};
+  const source = {
+    ...parsed,
+    ...safeProcessEnv
+  };
+  const parseBracedExpansion = expression => {
+    if (expression in source) {
+      return {
+        variableName: expression
+      };
+    }
+    const colonDefaultIndex = expression.indexOf(':-');
+    if (colonDefaultIndex !== -1) {
+      return {
+        defaultOperator: ':-',
+        defaultValue: expression.slice(colonDefaultIndex + 2),
+        variableName: expression.slice(0, colonDefaultIndex)
+      };
+    }
+    const defaultIndex = expression.indexOf('-');
+    if (defaultIndex !== -1) {
+      return {
+        defaultOperator: '-',
+        defaultValue: expression.slice(defaultIndex + 1),
+        variableName: expression.slice(0, defaultIndex)
+      };
+    }
+    return {
+      variableName: expression
+    };
+  };
+  const expandValue = (value, visiting) => value.replace(/(^|[^\\])\$(?:\{([^}]*)\}|([\w.-]+))/g, (match, prefix, bracedExpression, bareVariableName) => {
+    const expansion = bracedExpression === undefined ? {
+      variableName: bareVariableName ?? ''
+    } : parseBracedExpansion(bracedExpression);
+    const {
+      defaultOperator,
+      defaultValue,
+      variableName
+    } = expansion;
+    if (!variableName) {
+      return match;
+    }
+    const hasSourceValue = variableName in source;
+    const sourceValue = hasSourceValue ? source[variableName] ?? '' : undefined;
+    const shouldUseDefaultValue = defaultValue !== undefined && (!hasSourceValue || defaultOperator === ':-' && sourceValue === '');
+    if (shouldUseDefaultValue) {
+      return `${prefix}${expandValue(defaultValue, visiting)}`;
+    }
+    if (!hasSourceValue || visiting.has(variableName)) {
+      return prefix;
+    }
+    const replacement = variableName in safeProcessEnv ? safeProcessEnv[variableName] : variableName in expanded ? expanded[variableName] : expandValue(sourceValue ?? '', new Set([...visiting, variableName]));
+    return `${prefix}${replacement}`;
+  }).replace(/\\\$/g, '$');
+  for (const [key, value] of Object.entries(parsed)) {
+    expanded[key] = expandValue(value, new Set([key]));
+    source[key] = expanded[key];
+  }
+  return expanded;
+}
 function parseEnvContent(content, safeProcessEnv, customParser) {
   if (customParser) {
     return customParser(content);
   }
-  const parsed = dotenvParse(content);
-  const result = dotenvExpand({
-    parsed,
-    processEnv: {
-      ...safeProcessEnv
-    }
-  });
-  return result.parsed ?? {};
+  return expandEnvVariables(parseDotenvContent(content), safeProcessEnv);
 }
 function sanitizeProcessEnv(processEnv) {
   return Object.fromEntries(Object.entries(processEnv).filter(entry => entry[1] !== undefined));
@@ -44,8 +224,11 @@ function rejectLegacyValidateOption(options) {
 }
 function normalizeLoadOptions(options) {
   rejectLegacyValidateOption(options);
-  const cwd = options.cwd ?? process.cwd();
-  const envFile = options.envFilePath ?? options.envFile ?? join(cwd, '.env');
+  const hasExplicitEnvFile = options.envFilePath !== undefined || options.envFile !== 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 defaults = options.defaults ?? {};
   const processEnv = options.processEnv ?? {};
   const safeProcessEnv = sanitizeProcessEnv(processEnv);
@@ -60,10 +243,13 @@ function normalizeLoadOptions(options) {
   };
 }
 function readEnvFileValues(options) {
+  if (options.envFile === undefined) {
+    return {};
+  }
   try {
-    return parseEnvContent(readFileSync(options.envFile, 'utf8'), options.safeProcessEnv, options.parse);
+    return parseEnvContent(nodeFs().readFileSync(options.envFile, 'utf8'), options.safeProcessEnv, options.parse);
   } catch (error) {
-    if (typeof error === 'object' && error !== null && 'code' in error && error.code === 'ENOENT') {
+    if (isNodeFsError(error) && error.code === 'ENOENT') {
       return {};
     }
     throw error;
@@ -142,7 +328,7 @@ function createInvalidConfigError(cause, issues) {
   });
 }
 function isInvalidConfigError(error) {
-  return error instanceof FluoError && error.code === 'INVALID_CONFIG';
+  return typeof error === 'object' && error !== null && 'code' in error && error.code === 'INVALID_CONFIG';
 }
 function readConfigSchemaResult(result) {
   if (isConfigSchemaFailureResult(result)) {
@@ -151,7 +337,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) {
@@ -183,9 +369,9 @@ function createSubscription(listeners, listener) {
 }
 function hashEnvFileContent(envFile) {
   try {
-    return createHash('sha256').update(readFileSync(envFile)).digest('hex');
+    return nodeCrypto().createHash('sha256').update(nodeFs().readFileSync(envFile)).digest('hex');
   } catch (error) {
-    if (typeof error === 'object' && error !== null && 'code' in error && error.code === 'ENOENT') {
+    if (isNodeFsError(error) && error.code === 'ENOENT') {
       return undefined;
     }
     throw error;
@@ -241,19 +427,25 @@ function startReloaderWatcher(normalized, options, state, listeners, errorListen
   if (!options.watch) {
     return undefined;
   }
-  const watchTarget = dirname(normalized.envFile);
-  const watchedEnvFileName = basename(normalized.envFile);
-  if (!existsSync(watchTarget)) {
+  if (normalized.envFile === undefined) {
+    return undefined;
+  }
+  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;
   }
-  return watch(watchTarget, {
+  return fs.watch(watchTarget, {
     persistent: false
   }, (_eventType, filename) => {
     if (filename !== null && filename.toString() !== watchedEnvFileName) {
       return;
     }
     try {
-      const nextEnvFileHash = hashEnvFileContent(normalized.envFile);
+      const nextEnvFileHash = hashEnvFileContent(envFile);
       if (nextEnvFileHash === state.watchedEnvFileHash) {
         return;
       }
@@ -300,7 +492,7 @@ export function createConfigReloader(options) {
     current: resolveConfig(normalized),
     pendingReloadReason: undefined,
     reloading: false,
-    watchedEnvFileHash: hashEnvFileContent(normalized.envFile),
+    watchedEnvFileHash: normalized.envFile === undefined ? undefined : hashEnvFileContent(normalized.envFile),
     watcher: undefined
   };
   const listeners = new Set();

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,EAAgB,MAAM,YAAY,CAAC;AAwCzG;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,CAAC,EAAE,mBAAmB,GAAG,mBAAmB,CAY9F;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,CAAC,EAAE,iBAAiB,GAAG,iBAAiB,CAYxF"}

package/dist/options.js

@@ -14,12 +14,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 +43,9 @@ export function snapshotConfigModuleOptions(options) {
   return Object.freeze({
     ...options,
     defaults: snapshotConfigDictionary(options.defaults),
-    processEnv: snapshotProcessEnv(options.processEnv)
+    processEnv: snapshotProcessEnv(options.processEnv),
+    runtimeOverrides: snapshotConfigDictionary(options.runtimeOverrides),
+    schema: snapshotConfigSchema(options.schema)
   });
 }
 
@@ -36,7 +53,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) {
@@ -46,6 +63,7 @@ export function snapshotConfigLoadOptions(options) {
     ...options,
     defaults: snapshotConfigDictionary(options.defaults),
     processEnv: snapshotProcessEnv(options.processEnv),
-    runtimeOverrides: snapshotConfigDictionary(options.runtimeOverrides)
+    runtimeOverrides: snapshotConfigDictionary(options.runtimeOverrides),
+    schema: snapshotConfigSchema(options.schema)
   });
 }

package/dist/types.d.ts

@@ -30,6 +30,8 @@ export interface ConfigModuleOptions {
     processEnv?: NodeJS.ProcessEnv;
     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 +46,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;;;;;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,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.2",
+  "version": "1.0.4",
   "private": false,
   "license": "MIT",
   "repository": {
@@ -17,7 +17,7 @@
     "directory": "packages/config"
   },
   "engines": {
-    "node": ">=20.0.0"
+    "node": ">=20.16.0"
   },
   "publishConfig": {
     "access": "public"
@@ -36,13 +36,11 @@
   ],
   "dependencies": {
     "@standard-schema/spec": "^1.1.0",
-    "dotenv": "^16.0.0",
-    "dotenv-expand": "^11.0.0",
-    "@fluojs/core": "^1.0.2"
+    "@fluojs/core": "^1.1.0"
   },
   "devDependencies": {
     "vitest": "^3.2.4",
-    "@fluojs/di": "^1.0.2"
+    "@fluojs/di": "^2.0.0"
   },
   "scripts": {
     "prebuild": "node ../../tooling/scripts/clean-dist.mjs",