@fluojs/config 1.0.0-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 fluo contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.ko.md

@@ -0,0 +1,101 @@
+# @fluojs/config
+
+<p><a href="./README.md"><kbd>English</kbd></a> <strong><kbd>한국어</kbd></strong></p>
+
+fluo 애플리케이션을 위한 설정 로드, 병합, 검증, 타입 안전한 런타임 접근을 제공하는 패키지입니다.
+
+## 목차
+
+- [설치](#설치)
+- [사용 시점](#사용-시점)
+- [빠른 시작](#빠른-시작)
+- [주요 기능](#주요-기능)
+- [공개 API](#공개-api)
+- [관련 패키지](#관련-패키지)
+- [예제 소스](#예제-소스)
+
+## 설치
+
+```bash
+npm install @fluojs/config
+```
+
+## 사용 시점
+
+- `.env`와 환경 변수, 런타임 오버라이드를 하나의 설정 스냅샷으로 합쳐야 할 때
+- 여러 소스의 우선순위를 명확하게 유지한 채 설정을 병합해야 할 때
+- 애플리케이션 시작 전에 설정을 검증해서 잘못된 상태로 부팅되는 일을 막고 싶을 때
+- `ConfigService`를 통해 설정 값을 타입 안전하게 읽고 싶을 때
+
+## 빠른 시작
+
+```ts
+import { ConfigModule } from '@fluojs/config';
+import { Module } from '@fluojs/core';
+
+@Module({
+  imports: [
+    ConfigModule.forRoot({
+      envFile: '.env',
+      processEnv: {
+        DATABASE_URL: process.env.DATABASE_URL,
+      },
+      defaults: { PORT: '3000' },
+      validate: (config) => {
+        if (!config.DATABASE_URL) throw new Error('DATABASE_URL이 필요합니다');
+        return config;
+      },
+    }),
+  ],
+})
+class AppModule {}
+```
+
+등록 후에는 `ConfigService`를 주입해서 값을 읽습니다.
+
+```ts
+import { ConfigService } from '@fluojs/config';
+
+class MyService {
+  constructor(private readonly config: ConfigService) {
+    const port = this.config.get('PORT');
+    const dbUrl = this.config.getOrThrow('DATABASE_URL');
+  }
+}
+```
+
+## 주요 기능
+
+### 명확한 소스 우선순위
+
+설정은 `runtimeOverrides` → `processEnv` 옵션으로 전달한 환경 스냅샷 → env 파일 → `defaults` 순서로 병합됩니다.
+
+`@fluojs/config`는 주변 환경 변수를 자동으로 스캔하지 않습니다. 환경 기반 값을 우선순위에 포함하려면 부트스트랩 경계에서 `processEnv` 스냅샷을 명시적으로 전달하세요.
+
+### 객체 단위 딥 머지
+
+일반 객체는 키 기준으로 깊게 병합되고, 배열과 원시값은 더 높은 우선순위 소스가 전체를 덮어씁니다.
+
+### 부트스트랩 전 검증
+
+`validate` 함수는 모든 소스가 합쳐진 뒤 실행되며, 에러를 던지면 부트스트랩이 즉시 중단됩니다.
+
+## 공개 API
+
+| 클래스/헬퍼 | 설명 |
+|---|---|
+| `ConfigModule` | 설정을 전역 또는 지역으로 등록하기 위한 모듈입니다. |
+| `ConfigService` | 설정 값에 타입 안전하게 접근하기 위한 읽기 전용 서비스입니다. 스냅샷 교체는 config reload 경로 내부에만 남습니다. |
+| `loadConfig(options)` | 설정을 수동으로 로드하기 위한 함수형 엔트리 포인트입니다. |
+| `createConfigReloader(options)` | 동적 설정 업데이트를 위한 리로더를 생성합니다. |
+
+## 관련 패키지
+
+- `@fluojs/runtime`: 부트스트랩 중 `loadConfig()`를 호출합니다.
+- `@fluojs/validation`: `validate` 함수 안에서 스키마 기반 검증을 조합할 수 있습니다.
+
+## 예제 소스
+
+- `packages/config/src/load.ts`
+- `packages/config/src/service.ts`
+- `packages/config/src/load.test.ts`

package/README.md

@@ -0,0 +1,106 @@
+# @fluojs/config
+
+<p><strong><kbd>English</kbd></strong> <a href="./README.ko.md"><kbd>한국어</kbd></a></p>
+
+Configuration loading, merging, validation, and typed runtime access for fluo applications.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [When to Use](#when-to-use)
+- [Quick Start](#quick-start)
+- [Key Capabilities](#key-capabilities)
+- [Public API](#public-api)
+- [Related Packages](#related-packages)
+- [Example Sources](#example-sources)
+
+## Installation
+
+```bash
+npm install @fluojs/config
+```
+
+## When to Use
+
+Use this package when you need to:
+- Load configuration from `.env` files and environment variables.
+- Merge multiple configuration sources with strict precedence rules.
+- Validate your application configuration at startup.
+- Access configuration values through a typed `ConfigService`.
+
+## Quick Start
+
+The `ConfigModule` handles loading and validating your configuration during bootstrap.
+
+```typescript
+import { Module } from '@fluojs/core';
+import { ConfigModule } from '@fluojs/config';
+
+@Module({
+  imports: [
+    ConfigModule.forRoot({
+      envFile: '.env',
+      processEnv: {
+        DATABASE_URL: process.env.DATABASE_URL,
+      },
+      defaults: { PORT: '3000' },
+      validate: (config) => {
+        if (!config.DATABASE_URL) throw new Error('DATABASE_URL is required');
+        return config;
+      },
+    }),
+  ],
+})
+class AppModule {}
+```
+
+Once registered, you can inject `ConfigService` to access your values:
+
+```typescript
+import { Inject } from '@fluojs/core';
+import { ConfigService } from '@fluojs/config';
+
+class MyService {
+  constructor(@Inject(ConfigService) private config: ConfigService) {
+    const port = this.config.get('PORT');
+    const dbUrl = this.config.getOrThrow('DATABASE_URL');
+  }
+}
+```
+
+## Key Capabilities
+
+### Source Precedence
+Configuration is merged in the following order (highest precedence wins):
+1. **Runtime Overrides**: Values passed explicitly via `runtimeOverrides`.
+2. **Process Environment Snapshot**: Values passed via the `processEnv` option.
+3. **Environment File**: Values from the `.env` file (or custom path).
+4. **Defaults**: Values provided in the `defaults` option.
+
+`@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.
+
+### Deep Merging
+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.
+
+## Public API
+
+| Class/Helper | Description |
+|---|---|
+| `ConfigModule` | Module for registering configuration globally or locally. |
+| `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. |
+
+## Related Packages
+
+- **`@fluojs/runtime`**: Calls `loadConfig` internally during application bootstrap.
+- **`@fluojs/validation`**: Can be used within the `validate` function for schema-based validation.
+
+## Example Sources
+
+- `packages/config/src/load.ts`
+- `packages/config/src/service.ts`
+- `packages/config/src/load.test.ts`

package/dist/clone.d.ts

@@ -0,0 +1,2 @@
+export declare function cloneConfigDictionary<T>(value: T): T;
+//# sourceMappingURL=clone.d.ts.map

package/dist/clone.d.ts.map

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

package/dist/clone.js

@@ -0,0 +1,8 @@
+import { fallbackClone } from '@fluojs/core/internal';
+export function cloneConfigDictionary(value) {
+  try {
+    return structuredClone(value);
+  } catch {
+    return fallbackClone(value);
+  }
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export * from './load.js';
+export * from './module.js';
+export * from './reload-module.js';
+export { ConfigService } from './service.js';
+export * from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAC5B,cAAc,oBAAoB,CAAC;AACnC,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,cAAc,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,5 @@
+export * from './load.js';
+export * from './module.js';
+export * from './reload-module.js';
+export { ConfigService } from './service.js';
+export * from './types.js';

package/dist/load.d.ts

@@ -0,0 +1,33 @@
+import type { ConfigDictionary, ConfigLoadOptions, ConfigReloader } from './types.js';
+/**
+ * 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.
+ * @returns A reloader that exposes the current snapshot, manual reload, subscriptions, and cleanup.
+ * @throws {FluoError} When the initial config load or validation fails.
+ *
+ * @example
+ * ```ts
+ * const reloader = createConfigReloader({ envFile: '.env', watch: true });
+ *
+ * const subscription = reloader.subscribe((snapshot) => {
+ *   console.log(snapshot.PORT);
+ * });
+ *
+ * reloader.reload();
+ * subscription.unsubscribe();
+ * reloader.close();
+ * ```
+ */
+export declare function createConfigReloader(options: ConfigLoadOptions): ConfigReloader;
+/**
+ * Loads, merges, and validates one configuration snapshot without creating long-lived watcher state.
+ *
+ * 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.
+ * @returns A detached normalized configuration dictionary for the current load.
+ * @throws {FluoError} When validation throws or the config cannot be normalized.
+ */
+export declare function loadConfig(options: ConfigLoadOptions): ConfigDictionary;
+//# sourceMappingURL=load.d.ts.map

package/dist/load.d.ts.map

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

package/dist/load.js

@@ -0,0 +1,198 @@
+import { existsSync, readFileSync, watch } from 'node:fs';
+import { 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';
+function parseEnvContent(content, safeProcessEnv, customParser) {
+  if (customParser) {
+    return customParser(content);
+  }
+  const parsed = dotenvParse(content);
+  const result = dotenvExpand({
+    parsed,
+    processEnv: {
+      ...safeProcessEnv
+    }
+  });
+  return result.parsed ?? {};
+}
+function sanitizeProcessEnv(processEnv) {
+  return Object.fromEntries(Object.entries(processEnv).filter(entry => entry[1] !== undefined));
+}
+function normalizeLoadOptions(options) {
+  const cwd = options.cwd ?? process.cwd();
+  const envFile = options.envFilePath ?? options.envFile ?? join(cwd, '.env');
+  const defaults = options.defaults ?? {};
+  const processEnv = options.processEnv ?? {};
+  const safeProcessEnv = sanitizeProcessEnv(processEnv);
+  const runtimeOverrides = options.runtimeOverrides ?? {};
+  return {
+    defaults,
+    envFile,
+    parse: options.parse,
+    runtimeOverrides,
+    safeProcessEnv,
+    validate: options.validate
+  };
+}
+function readEnvFileValues(options) {
+  if (!existsSync(options.envFile)) {
+    return {};
+  }
+  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];
+    if (isPlainObject(targetValue) && isPlainObject(sourceValue)) {
+      merged[key] = mergeConfigEntries(targetValue, sourceValue);
+      continue;
+    }
+    merged[key] = cloneConfigDictionary(sourceValue);
+  }
+  return merged;
+}
+function mergeConfigSources(...sources) {
+  let merged = {};
+  for (const source of sources) {
+    merged = mergeConfigEntries(merged, source);
+  }
+  return merged;
+}
+function buildMergedConfig(options) {
+  const envFileValues = readEnvFileValues(options);
+  return mergeConfigSources(options.defaults, envFileValues, options.safeProcessEnv, options.runtimeOverrides);
+}
+function validateConfig(options, merged) {
+  try {
+    return options.validate ? options.validate(merged) : merged;
+  } catch (error) {
+    throw new FluoError('Invalid configuration.', {
+      code: 'INVALID_CONFIG',
+      cause: error
+    });
+  }
+}
+function resolveConfig(options) {
+  return validateConfig(options, buildMergedConfig(options));
+}
+function createSubscription(listeners, listener) {
+  listeners.add(listener);
+  return {
+    unsubscribe() {
+      listeners.delete(listener);
+    }
+  };
+}
+function notifyReloadListeners(listeners, snapshot, reason) {
+  for (const listener of listeners) {
+    listener(cloneConfigDictionary(snapshot), reason);
+  }
+}
+function notifyReloadErrorListeners(listeners, error, reason) {
+  for (const listener of listeners) {
+    listener(error, reason);
+  }
+}
+function applyReload(normalized, state, listeners, reason) {
+  const previous = state.current;
+  const next = resolveConfig(normalized);
+  state.current = next;
+  try {
+    notifyReloadListeners(listeners, next, reason);
+  } catch (error) {
+    state.current = previous;
+    throw error;
+  }
+  return cloneConfigDictionary(next);
+}
+function startReloaderWatcher(normalized, options, state, listeners, errorListeners) {
+  if (!options.watch || !existsSync(normalized.envFile)) {
+    return undefined;
+  }
+  return watch(normalized.envFile, {
+    persistent: false
+  }, () => {
+    try {
+      applyReload(normalized, state, listeners, 'watch');
+    } catch (error) {
+      notifyReloadErrorListeners(errorListeners, error, 'watch');
+    }
+  });
+}
+function closeReloader(state, listeners, errorListeners) {
+  if (state.watcher) {
+    state.watcher.close();
+    state.watcher = undefined;
+  }
+  listeners.clear();
+  errorListeners.clear();
+}
+
+/**
+ * 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.
+ * @returns A reloader that exposes the current snapshot, manual reload, subscriptions, and cleanup.
+ * @throws {FluoError} When the initial config load or validation fails.
+ *
+ * @example
+ * ```ts
+ * const reloader = createConfigReloader({ envFile: '.env', watch: true });
+ *
+ * const subscription = reloader.subscribe((snapshot) => {
+ *   console.log(snapshot.PORT);
+ * });
+ *
+ * reloader.reload();
+ * subscription.unsubscribe();
+ * reloader.close();
+ * ```
+ */
+export function createConfigReloader(options) {
+  const normalized = normalizeLoadOptions(options);
+  const state = {
+    current: resolveConfig(normalized),
+    watcher: undefined
+  };
+  const listeners = new Set();
+  const errorListeners = new Set();
+  state.watcher = startReloaderWatcher(normalized, options, state, listeners, errorListeners);
+  return {
+    close() {
+      closeReloader(state, listeners, errorListeners);
+    },
+    current() {
+      return cloneConfigDictionary(state.current);
+    },
+    reload() {
+      return applyReload(normalized, state, listeners, 'manual');
+    },
+    subscribe(listener) {
+      return createSubscription(listeners, listener);
+    },
+    subscribeError(listener) {
+      return createSubscription(errorListeners, listener);
+    }
+  };
+}
+
+/**
+ * Loads, merges, and validates one configuration snapshot without creating long-lived watcher state.
+ *
+ * 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.
+ * @returns A detached normalized configuration dictionary for the current load.
+ * @throws {FluoError} When validation throws or the config cannot be normalized.
+ */
+export function loadConfig(options) {
+  return cloneConfigDictionary(resolveConfig(normalizeLoadOptions(options)));
+}

package/dist/module.d.ts

@@ -0,0 +1,27 @@
+import type { ConfigModuleOptions } from './types.js';
+/**
+ * Module facade that wires normalized configuration into the application container.
+ */
+export declare class ConfigModule {
+    /**
+     * Creates a module class that registers `ConfigService` with one normalized configuration snapshot.
+     *
+     * @param options Configuration module options for env-file loading, validation, precedence, and scope.
+     * @returns A module type that can be listed in `imports` during bootstrap.
+     *
+     * @example
+     * ```ts
+     * @Module({
+     *   imports: [
+     *     ConfigModule.forRoot({
+     *       envFile: '.env',
+     *       defaults: { PORT: '3000' },
+     *     }),
+     *   ],
+     * })
+     * class AppModule {}
+     * ```
+     */
+    static forRoot(options?: ConfigModuleOptions): new () => ConfigModule;
+}
+//# sourceMappingURL=module.d.ts.map

package/dist/module.d.ts.map

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

package/dist/module.js

@@ -0,0 +1,39 @@
+import { defineModuleMetadata } from '@fluojs/core/internal';
+import { loadConfig } from './load.js';
+import { ConfigService } from './service.js';
+/**
+ * Module facade that wires normalized configuration into the application container.
+ */
+export class ConfigModule {
+  /**
+   * Creates a module class that registers `ConfigService` with one normalized configuration snapshot.
+   *
+   * @param options Configuration module options for env-file loading, validation, precedence, and scope.
+   * @returns A module type that can be listed in `imports` during bootstrap.
+   *
+   * @example
+   * ```ts
+   * @Module({
+   *   imports: [
+   *     ConfigModule.forRoot({
+   *       envFile: '.env',
+   *       defaults: { PORT: '3000' },
+   *     }),
+   *   ],
+   * })
+   * class AppModule {}
+   * ```
+   */
+  static forRoot(options) {
+    class ConfigModuleImpl extends ConfigModule {}
+    defineModuleMetadata(ConfigModuleImpl, {
+      global: options?.isGlobal ?? true,
+      exports: [ConfigService],
+      providers: [{
+        provide: ConfigService,
+        useFactory: () => new ConfigService(loadConfig(options ?? {}))
+      }]
+    });
+    return ConfigModuleImpl;
+  }
+}

package/dist/reload-module.d.ts

@@ -0,0 +1,34 @@
+import { ConfigService } from './service.js';
+import type { ConfigDictionary, ConfigLoadOptions, ConfigReloadErrorListener, ConfigReloader, ConfigReloadListener, ConfigReloadSubscription } from './types.js';
+/**
+ * Exposes the config reload manager contract for dependency injection.
+ */
+export declare const CONFIG_RELOADER: unique symbol;
+/**
+ * Lazily creates and coordinates the active config reloader instance.
+ */
+export declare class ConfigReloadManager implements ConfigReloader {
+    private readonly config;
+    private readonly options;
+    private reloader;
+    private reloadForwarder;
+    private errorForwarder;
+    private readonly reloadListeners;
+    private readonly errorListeners;
+    constructor(config: ConfigService, options: ConfigLoadOptions);
+    current(): ConfigDictionary;
+    reload(): ConfigDictionary;
+    subscribe(listener: ConfigReloadListener): ConfigReloadSubscription;
+    subscribeError(listener: ConfigReloadErrorListener): ConfigReloadSubscription;
+    close(): void;
+    onApplicationBootstrap(): void;
+    onModuleDestroy(): void;
+    private ensureReloader;
+}
+/**
+ * Registers config reload services and exports the shared reloader token.
+ */
+export declare class ConfigReloadModule {
+    static forRoot(options?: ConfigLoadOptions): new () => ConfigReloadModule;
+}
+//# sourceMappingURL=reload-module.d.ts.map

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

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

package/dist/reload-module.js

@@ -0,0 +1,127 @@
+let _initClass;
+function _applyDecs(e, t, n, r, o, i) { var a, c, u, s, f, l, p, d = Symbol.metadata || Symbol.for("Symbol.metadata"), m = Object.defineProperty, h = Object.create, y = [h(null), h(null)], v = t.length; function g(t, n, r) { return function (o, i) { n && (i = o, o = e); for (var a = 0; a < t.length; a++) i = t[a].apply(o, r ? [i] : []); return r ? i : o; }; } function b(e, t, n, r) { if ("function" != typeof e && (r || void 0 !== e)) throw new TypeError(t + " must " + (n || "be") + " a function" + (r ? "" : " or undefined")); return e; } function applyDec(e, t, n, r, o, i, u, s, f, l, p) { function d(e) { if (!p(e)) throw new TypeError("Attempted to access private element on non-instance"); } var h = [].concat(t[0]), v = t[3], w = !u, D = 1 === o, S = 3 === o, j = 4 === o, E = 2 === o; function I(t, n, r) { return function (o, i) { return n && (i = o, o = e), r && r(o), P[t].call(o, i); }; } if (!w) { var P = {}, k = [], F = S ? "get" : j || D ? "set" : "value"; if (f ? (l || D ? P = { get: _setFunctionName(function () { return v(this); }, r, "get"), set: function (e) { t[4](this, e); } } : P[F] = v, l || _setFunctionName(P[F], r, E ? "" : F)) : l || (P = Object.getOwnPropertyDescriptor(e, r)), !l && !f) { if ((c = y[+s][r]) && 7 !== (c ^ o)) throw Error("Decorating two elements with the same name (" + P[F].name + ") is not supported yet"); y[+s][r] = o < 3 ? 1 : o; } } for (var N = e, O = h.length - 1; O >= 0; O -= n ? 2 : 1) { var T = b(h[O], "A decorator", "be", !0), z = n ? h[O - 1] : void 0, A = {}, H = { kind: ["field", "accessor", "method", "getter", "setter", "class"][o], name: r, metadata: a, addInitializer: function (e, t) { if (e.v) throw new TypeError("attempted to call addInitializer after decoration was finished"); b(t, "An initializer", "be", !0), i.push(t); }.bind(null, A) }; if (w) c = T.call(z, N, H), A.v = 1, b(c, "class decorators", "return") && (N = c);else if (H.static = s, H.private = f, c = H.access = { has: f ? p.bind() : function (e) { return r in e; } }, j || (c.get = f ? E ? function (e) { return d(e), P.value; } : I("get", 0, d) : function (e) { return e[r]; }), E || S || (c.set = f ? I("set", 0, d) : function (e, t) { e[r] = t; }), N = T.call(z, D ? { get: P.get, set: P.set } : P[F], H), A.v = 1, D) { if ("object" == typeof N && N) (c = b(N.get, "accessor.get")) && (P.get = c), (c = b(N.set, "accessor.set")) && (P.set = c), (c = b(N.init, "accessor.init")) && k.unshift(c);else if (void 0 !== N) throw new TypeError("accessor decorators must return an object with get, set, or init properties or undefined"); } else b(N, (l ? "field" : "method") + " decorators", "return") && (l ? k.unshift(N) : P[F] = N); } return o < 2 && u.push(g(k, s, 1), g(i, s, 0)), l || w || (f ? D ? u.splice(-1, 0, I("get", s), I("set", s)) : u.push(E ? P[F] : b.call.bind(P[F])) : m(e, r, P)), N; } function w(e) { return m(e, d, { configurable: !0, enumerable: !0, value: a }); } return void 0 !== i && (a = i[d]), a = h(null == a ? null : a), f = [], l = function (e) { e && f.push(g(e)); }, p = function (t, r) { for (var i = 0; i < n.length; i++) { var a = n[i], c = a[1], l = 7 & c; if ((8 & c) == t && !l == r) { var p = a[2], d = !!a[3], m = 16 & c; applyDec(t ? e : e.prototype, a, m, d ? "#" + p : _toPropertyKey(p), l, l < 2 ? [] : t ? s = s || [] : u = u || [], f, !!t, d, r, t && d ? function (t) { return _checkInRHS(t) === e; } : o); } } }, p(8, 0), p(0, 0), p(8, 1), p(0, 1), l(u), l(s), c = f, v || w(e), { e: c, get c() { var n = []; return v && [w(e = applyDec(e, [t], r, e.name, 5, n)), g(n, 1)]; } }; }
+function _toPropertyKey(t) { var i = _toPrimitive(t, "string"); return "symbol" == typeof i ? i : i + ""; }
+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 { defineModuleMetadata } from '@fluojs/core/internal';
+import { cloneConfigDictionary } from './clone.js';
+import { createConfigReloader } from './load.js';
+import { ConfigService, replaceConfigServiceSnapshot } from './service.js';
+const CONFIG_RELOAD_OPTIONS = Symbol('fluo.config.reload-options');
+
+/**
+ * Exposes the config reload manager contract for dependency injection.
+ */
+export const CONFIG_RELOADER = Symbol('fluo.config.reloader');
+function createSubscription(listeners, listener) {
+  listeners.add(listener);
+  return {
+    unsubscribe() {
+      listeners.delete(listener);
+    }
+  };
+}
+
+/**
+ * Lazily creates and coordinates the active config reloader instance.
+ */
+let _ConfigReloadManager;
+class ConfigReloadManager {
+  static {
+    [_ConfigReloadManager, _initClass] = _applyDecs(this, [Inject(ConfigService, CONFIG_RELOAD_OPTIONS)], []).c;
+  }
+  reloader;
+  reloadForwarder;
+  errorForwarder;
+  reloadListeners = new Set();
+  errorListeners = new Set();
+  constructor(config, options) {
+    this.config = config;
+    this.options = options;
+  }
+  current() {
+    return this.ensureReloader().current();
+  }
+  reload() {
+    return this.ensureReloader().reload();
+  }
+  subscribe(listener) {
+    return createSubscription(this.reloadListeners, listener);
+  }
+  subscribeError(listener) {
+    return createSubscription(this.errorListeners, listener);
+  }
+  close() {
+    this.reloadForwarder?.unsubscribe();
+    this.reloadForwarder = undefined;
+    this.errorForwarder?.unsubscribe();
+    this.errorForwarder = undefined;
+    if (this.reloader) {
+      this.reloader.close();
+      this.reloader = undefined;
+    }
+    this.reloadListeners.clear();
+    this.errorListeners.clear();
+  }
+  onApplicationBootstrap() {
+    if (!this.options.watch) {
+      return;
+    }
+    this.ensureReloader();
+  }
+  onModuleDestroy() {
+    this.close();
+  }
+  ensureReloader() {
+    if (this.reloader) {
+      return this.reloader;
+    }
+    const reloader = createConfigReloader(this.options);
+    this.reloadForwarder = reloader.subscribe((nextConfig, reason) => {
+      const previousConfig = this.config.snapshot();
+      try {
+        replaceConfigServiceSnapshot(this.config, nextConfig);
+        for (const listener of this.reloadListeners) {
+          listener(cloneConfigDictionary(nextConfig), reason);
+        }
+      } catch (error) {
+        replaceConfigServiceSnapshot(this.config, previousConfig);
+        throw error;
+      }
+    });
+    this.errorForwarder = reloader.subscribeError((error, reason) => {
+      for (const listener of this.errorListeners) {
+        listener(error, reason);
+      }
+    });
+    this.reloader = reloader;
+    return reloader;
+  }
+  static {
+    _initClass();
+  }
+}
+
+/**
+ * Registers config reload services and exports the shared reloader token.
+ */
+export { _ConfigReloadManager as ConfigReloadManager };
+export class ConfigReloadModule {
+  static forRoot(options) {
+    const loadOptions = options ?? {};
+    class ConfigReloadModuleImpl extends ConfigReloadModule {}
+    defineModuleMetadata(ConfigReloadModuleImpl, {
+      exports: [CONFIG_RELOADER],
+      providers: [{
+        provide: CONFIG_RELOAD_OPTIONS,
+        useValue: loadOptions
+      }, _ConfigReloadManager, {
+        provide: CONFIG_RELOADER,
+        useExisting: _ConfigReloadManager
+      }]
+    });
+    return ConfigReloadModuleImpl;
+  }
+}

package/dist/service.d.ts

@@ -0,0 +1,38 @@
+import type { ConfigDictionary, DotPaths, DotValue } from './types.js';
+/**
+ * Typed read-only facade over the normalized runtime configuration dictionary.
+ */
+export declare class ConfigService<T extends Record<string, unknown> = ConfigDictionary> {
+    private values;
+    constructor(values: T);
+    /**
+     * Returns a config value by key (including dot-path keys) or `undefined` when missing.
+     *
+     * @param key Configuration key or dot-path key to resolve from the current snapshot.
+     * @returns The resolved value clone for object-like entries, or `undefined` when the key does not exist.
+     */
+    get<K extends DotPaths<T>>(key: K): DotValue<T, K & string> | undefined;
+    /**
+     * Returns a config value by key and throws when the key is missing.
+     *
+     * @param key Configuration key or dot-path key that must exist in the current snapshot.
+     * @returns The resolved value clone for object-like entries.
+     * @throws {FluoError} When the key is absent (`code: 'CONFIG_KEY_MISSING'`).
+     */
+    getOrThrow<K extends DotPaths<T>>(key: K): DotValue<T, K & string>;
+    /**
+     * Returns a deep-cloned snapshot of the current normalized config dictionary.
+     *
+     * @returns A detached deep clone of the current configuration snapshot.
+     */
+    snapshot(): ConfigDictionary;
+    private _resolve;
+}
+/**
+ * Replaces the underlying configuration snapshot of a `ConfigService`.
+ *
+ * @param service The `ConfigService` instance to update.
+ * @param values The new configuration dictionary.
+ */
+export declare function replaceConfigServiceSnapshot<T extends Record<string, unknown>>(service: ConfigService<T>, values: T): void;
+//# sourceMappingURL=service.d.ts.map

package/dist/service.d.ts.map

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

package/dist/service.js

@@ -0,0 +1,81 @@
+import { FluoError } from '@fluojs/core';
+import { cloneConfigDictionary } from './clone.js';
+function hasOwn(value, key) {
+  return typeof value === 'object' && value !== null && Object.hasOwn(value, key);
+}
+
+/**
+ * Typed read-only facade over the normalized runtime configuration dictionary.
+ */
+export class ConfigService {
+  values;
+  constructor(values) {
+    this.values = cloneConfigDictionary(values);
+  }
+
+  /**
+   * Returns a config value by key (including dot-path keys) or `undefined` when missing.
+   *
+   * @param key Configuration key or dot-path key to resolve from the current snapshot.
+   * @returns The resolved value clone for object-like entries, or `undefined` when the key does not exist.
+   */
+  get(key) {
+    return this._resolve(key);
+  }
+
+  /**
+   * Returns a config value by key and throws when the key is missing.
+   *
+   * @param key Configuration key or dot-path key that must exist in the current snapshot.
+   * @returns The resolved value clone for object-like entries.
+   * @throws {FluoError} When the key is absent (`code: 'CONFIG_KEY_MISSING'`).
+   */
+  getOrThrow(key) {
+    const value = this._resolve(key);
+    if (value === undefined) {
+      throw new FluoError(`Missing config key: ${String(key)}`, {
+        code: 'CONFIG_KEY_MISSING'
+      });
+    }
+    return value;
+  }
+
+  /**
+   * Returns a deep-cloned snapshot of the current normalized config dictionary.
+   *
+   * @returns A detached deep clone of the current configuration snapshot.
+   */
+  snapshot() {
+    return cloneConfigDictionary(this.values);
+  }
+  _resolve(key) {
+    let resolved;
+    if (hasOwn(this.values, key)) {
+      resolved = this.values[key];
+    } else {
+      const parts = key.split('.');
+      let current = this.values;
+      for (const part of parts) {
+        if (!hasOwn(current, part)) {
+          return undefined;
+        }
+        current = current[part];
+      }
+      resolved = current;
+    }
+    if (typeof resolved === 'object' && resolved !== null) {
+      return cloneConfigDictionary(resolved);
+    }
+    return resolved;
+  }
+}
+
+/**
+ * Replaces the underlying configuration snapshot of a `ConfigService`.
+ *
+ * @param service The `ConfigService` instance to update.
+ * @param values The new configuration dictionary.
+ */
+export function replaceConfigServiceSnapshot(service, values) {
+  service['values'] = cloneConfigDictionary(values);
+}

package/dist/types.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Plain JSON-like object used as the normalized configuration snapshot shape.
+ */
+export type ConfigDictionary = Record<string, unknown>;
+/**
+ * Nested dot-path key helper.
+ * Produces "a" | "a.b" | "a.b.c" keys from a Record type.
+ */
+export type DotPaths<T, Prefix extends string = ''> = T extends Record<string, unknown> ? {
+    [K in keyof T & string]: `${Prefix}${K}` | DotPaths<T[K], `${Prefix}${K}.`>;
+}[keyof T & string] : never;
+/**
+ * Resolves a dot-path key to its leaf value type.
+ */
+export type DotValue<T, K extends string> = K extends keyof T ? T[K] : K extends `${infer Head}.${infer Tail}` ? Head extends keyof T ? DotValue<T[Head], Tail> : never : never;
+/**
+ * Module-level configuration options for loading and validating application config.
+ */
+export interface ConfigModuleOptions {
+    envFile?: string;
+    envFilePath?: string;
+    processEnv?: NodeJS.ProcessEnv;
+    validate?: (raw: ConfigDictionary) => ConfigDictionary;
+    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. */
+    parse?: (content: string) => Record<string, string>;
+    watch?: boolean;
+    isGlobal?: boolean;
+}
+/**
+ * Extended load options for one-off config loads and reloaders outside `ConfigModule.forRoot(...)`.
+ */
+export interface ConfigLoadOptions extends ConfigModuleOptions {
+    cwd?: string;
+    runtimeOverrides?: ConfigDictionary;
+}
+/**
+ * Reason attached to config reload notifications.
+ */
+export type ConfigReloadReason = 'manual' | 'watch';
+/**
+ * Listener invoked after a config reload succeeds.
+ */
+export type ConfigReloadListener = (snapshot: ConfigDictionary, reason: ConfigReloadReason) => void;
+/**
+ * Listener invoked when a watched reload attempt fails.
+ */
+export type ConfigReloadErrorListener = (error: unknown, reason: ConfigReloadReason) => void;
+/**
+ * Disposable subscription handle returned from reloader listener registration.
+ */
+export interface ConfigReloadSubscription {
+    unsubscribe(): void;
+}
+/**
+ * Stateful config reloader contract returned by {@link createConfigReloader}.
+ */
+export interface ConfigReloader {
+    current(): ConfigDictionary;
+    reload(): ConfigDictionary;
+    subscribe(listener: ConfigReloadListener): ConfigReloadSubscription;
+    subscribeError(listener: ConfigReloadErrorListener): ConfigReloadSubscription;
+    close(): void;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@fluojs/config",
+  "description": "Configuration loading, merging, validation, and typed runtime access for Fluo applications.",
+  "keywords": [
+    "fluo",
+    "config",
+    "configuration",
+    "environment",
+    "typed-config"
+  ],
+  "version": "1.0.0-beta.1",
+  "private": false,
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/fluojs/fluo.git",
+    "directory": "packages/config"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "dotenv": "^16.0.0",
+    "dotenv-expand": "^11.0.0",
+    "@fluojs/core": "^1.0.0-beta.1"
+  },
+  "devDependencies": {
+    "vitest": "^3.2.4"
+  },
+  "scripts": {
+    "prebuild": "node ../../tooling/scripts/clean-dist.mjs",
+    "build": "pnpm exec babel src --extensions .ts --ignore 'src/**/*.test.ts' --out-dir dist --config-file ../../tooling/babel/babel.config.cjs && pnpm exec tsc -p tsconfig.build.json",
+    "typecheck": "pnpm exec tsc -p tsconfig.json --noEmit",
+    "test": "pnpm exec vitest run -c vitest.config.ts",
+    "test:watch": "pnpm exec vitest -c vitest.config.ts"
+  }
+}