@mandujs/core 0.9.46 → 0.11.0

package/src/config/watcher.ts

@@ -0,0 +1,311 @@
+/**
+ * DNA-006: Config Hot Reload
+ *
+ * 설정 파일 변경 감시 및 핫 리로드
+ * - 디바운스로 연속 변경 병합
+ * - 에러 발생 시 기존 설정 유지
+ * - 클린업 함수 반환
+ */
+
+import { watch, type FSWatcher } from "fs";
+import { loadManduConfig, type ManduConfig } from "./mandu.js";
+
+/**
+ * 설정 변경 이벤트 타입
+ */
+export type ConfigChangeEvent = {
+  /** 이전 설정 */
+  previous: ManduConfig;
+  /** 새 설정 */
+  current: ManduConfig;
+  /** 변경된 파일 경로 */
+  path: string;
+  /** 변경 시간 */
+  timestamp: Date;
+};
+
+/**
+ * 설정 감시 옵션
+ */
+export interface WatchConfigOptions {
+  /** 디바운스 딜레이 (ms, 기본: 100) */
+  debounceMs?: number;
+  /** 초기 로드 시에도 콜백 호출 (기본: false) */
+  immediate?: boolean;
+  /** 에러 핸들러 */
+  onError?: (error: Error) => void;
+}
+
+/**
+ * 설정 변경 콜백
+ */
+export type ConfigChangeCallback = (
+  newConfig: ManduConfig,
+  event: ConfigChangeEvent
+) => void;
+
+/**
+ * 설정 감시 결과
+ */
+export interface ConfigWatcher {
+  /** 감시 중지 */
+  stop: () => void;
+  /** 현재 설정 */
+  getConfig: () => ManduConfig;
+  /** 수동 리로드 */
+  reload: () => Promise<ManduConfig>;
+}
+
+/**
+ * 설정 파일 감시 및 핫 리로드
+ *
+ * @example
+ * ```ts
+ * const watcher = await watchConfig(
+ *   "/path/to/project",
+ *   (newConfig, event) => {
+ *     console.log("Config changed:", event.path);
+ *     applyConfig(newConfig);
+ *   },
+ *   { debounceMs: 200 }
+ * );
+ *
+ * // 나중에 정리
+ * watcher.stop();
+ * ```
+ */
+export async function watchConfig(
+  rootDir: string,
+  onReload: ConfigChangeCallback,
+  options: WatchConfigOptions = {}
+): Promise<ConfigWatcher> {
+  const { debounceMs = 100, immediate = false, onError } = options;
+
+  // 현재 설정 로드
+  let currentConfig = await loadManduConfig(rootDir);
+  let debounceTimer: ReturnType<typeof setTimeout> | null = null;
+  let watchers: FSWatcher[] = [];
+  let isWatching = true;
+
+  // 감시 대상 파일들
+  const configFiles = [
+    "mandu.config.ts",
+    "mandu.config.js",
+    "mandu.config.json",
+    ".mandu/guard.json",
+  ];
+
+  /**
+   * 설정 리로드 수행
+   */
+  const doReload = async (changedPath: string): Promise<void> => {
+    if (!isWatching) return;
+
+    try {
+      const previous = currentConfig;
+      const newConfig = await loadManduConfig(rootDir);
+
+      // 설정이 동일하면 무시
+      if (JSON.stringify(previous) === JSON.stringify(newConfig)) {
+        return;
+      }
+
+      // 이전에 설정이 있었는데 새 설정이 비어있으면 (파싱 에러 등)
+      // 기존 설정 유지하고 에러 핸들러 호출
+      const previousHasContent = Object.keys(previous).length > 0;
+      const newIsEmpty = Object.keys(newConfig).length === 0;
+
+      if (previousHasContent && newIsEmpty) {
+        if (onError) {
+          onError(new Error(`Failed to reload config from ${changedPath}`));
+        }
+        return; // 기존 설정 유지
+      }
+
+      currentConfig = newConfig;
+
+      const event: ConfigChangeEvent = {
+        previous,
+        current: newConfig,
+        path: changedPath,
+        timestamp: new Date(),
+      };
+
+      onReload(newConfig, event);
+    } catch (error) {
+      if (onError && error instanceof Error) {
+        onError(error);
+      }
+      // 에러 시 기존 설정 유지
+    }
+  };
+
+  /**
+   * 디바운스된 리로드
+   */
+  const scheduleReload = (changedPath: string): void => {
+    if (debounceTimer) {
+      clearTimeout(debounceTimer);
+    }
+
+    debounceTimer = setTimeout(() => {
+      debounceTimer = null;
+      doReload(changedPath);
+    }, debounceMs);
+  };
+
+  // 각 설정 파일 감시 시작
+  for (const fileName of configFiles) {
+    const filePath = `${rootDir}/${fileName}`;
+
+    try {
+      const watcher = watch(filePath, (eventType) => {
+        if (eventType === "change" && isWatching) {
+          scheduleReload(filePath);
+        }
+      });
+
+      watcher.on("error", () => {
+        // 파일이 없거나 접근 불가 - 무시
+      });
+
+      watchers.push(watcher);
+    } catch {
+      // 파일이 없으면 감시 생략
+    }
+  }
+
+  // 초기 콜백 호출
+  if (immediate) {
+    const event: ConfigChangeEvent = {
+      previous: {},
+      current: currentConfig,
+      path: rootDir,
+      timestamp: new Date(),
+    };
+    onReload(currentConfig, event);
+  }
+
+  return {
+    stop: () => {
+      isWatching = false;
+      if (debounceTimer) {
+        clearTimeout(debounceTimer);
+        debounceTimer = null;
+      }
+      for (const watcher of watchers) {
+        watcher.close();
+      }
+      watchers = [];
+    },
+
+    getConfig: () => currentConfig,
+
+    reload: async () => {
+      const previous = currentConfig;
+      currentConfig = await loadManduConfig(rootDir);
+
+      if (JSON.stringify(previous) !== JSON.stringify(currentConfig)) {
+        const event: ConfigChangeEvent = {
+          previous,
+          current: currentConfig,
+          path: rootDir,
+          timestamp: new Date(),
+        };
+        onReload(currentConfig, event);
+      }
+
+      return currentConfig;
+    },
+  };
+}
+
+/**
+ * 간단한 단일 파일 감시
+ *
+ * @example
+ * ```ts
+ * const stop = watchConfigFile(
+ *   "/path/to/mandu.config.ts",
+ *   async (path) => {
+ *     const config = await loadManduConfig(dirname(path));
+ *     applyConfig(config);
+ *   }
+ * );
+ *
+ * // 정리
+ * stop();
+ * ```
+ */
+export function watchConfigFile(
+  filePath: string,
+  onChange: (path: string) => void,
+  debounceMs = 100
+): () => void {
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  let watcher: FSWatcher | null = null;
+
+  try {
+    watcher = watch(filePath, (eventType) => {
+      if (eventType === "change") {
+        if (timer) clearTimeout(timer);
+        timer = setTimeout(() => {
+          timer = null;
+          onChange(filePath);
+        }, debounceMs);
+      }
+    });
+  } catch {
+    // 파일 없음 - 빈 함수 반환
+    return () => {};
+  }
+
+  return () => {
+    if (timer) {
+      clearTimeout(timer);
+      timer = null;
+    }
+    if (watcher) {
+      watcher.close();
+      watcher = null;
+    }
+  };
+}
+
+/**
+ * 설정 변경 감지 헬퍼
+ *
+ * 특정 설정 섹션의 변경 여부 확인
+ */
+export function hasConfigChanged(
+  previous: ManduConfig,
+  current: ManduConfig,
+  section?: keyof ManduConfig
+): boolean {
+  if (section) {
+    return JSON.stringify(previous[section]) !== JSON.stringify(current[section]);
+  }
+  return JSON.stringify(previous) !== JSON.stringify(current);
+}
+
+/**
+ * 변경된 설정 섹션 목록
+ */
+export function getChangedSections(
+  previous: ManduConfig,
+  current: ManduConfig
+): (keyof ManduConfig)[] {
+  const sections: (keyof ManduConfig)[] = [
+    "server",
+    "guard",
+    "build",
+    "dev",
+    "fsRoutes",
+    "seo",
+  ];
+
+  return sections.filter(
+    (section) =>
+      JSON.stringify(previous[section]) !== JSON.stringify(current[section])
+  );
+}

package/src/contract/index.ts

@@ -10,18 +10,19 @@
 
 export * from "./schema";
 export * from "./types";
-export * from "./validator";
-export * from "./handler";
-export * from "./client";
-export * from "./normalize";
-export * from "./registry";
-export * from "./client-safe";
-
-import type { ContractDefinition, ContractInstance, ContractSchema } from "./schema";
-import type { ContractHandlers, RouteDefinition } from "./handler";
-import { defineHandler, defineRoute } from "./handler";
-import { createClient, contractFetch, type ClientOptions } from "./client";
-import { createClientContract } from "./client-safe";
+export * from "./validator";
+export * from "./handler";
+export * from "./client";
+export * from "./normalize";
+export * from "./registry";
+export * from "./client-safe";
+export * from "./protection";
+
+import type { ContractDefinition, ContractInstance, ContractSchema } from "./schema";
+import type { ContractHandlers, RouteDefinition } from "./handler";
+import { defineHandler, defineRoute } from "./handler";
+import { createClient, contractFetch, type ClientOptions } from "./client";
+import { createClientContract } from "./client-safe";
 
 /**
  * Create a Mandu API Contract
@@ -123,7 +124,7 @@ export function createContract<T extends ContractDefinition>(definition: T): T &
  * Contract-specific Mandu functions
  * Note: Use `ManduContract` to avoid conflict with other Mandu exports
  */
-export const ManduContract = {
+export const ManduContract = {
   /**
    * Create a typed Contract
    * Contract 스키마 정의 및 타입 추론
@@ -165,9 +166,9 @@ export const ManduContract = {
    */
   route: defineRoute,
 
-  /**
-   * Create a type-safe API client from contract
-   * Contract 기반 타입 안전 클라이언트 생성
+  /**
+   * Create a type-safe API client from contract
+   * Contract 기반 타입 안전 클라이언트 생성
    *
    * @example
    * ```typescript
@@ -180,13 +181,13 @@ export const ManduContract = {
    * const newUser = await client.POST({ body: { name: "Alice" } });
    * ```
    */
-  client: createClient,
-
-  /**
-   * Create a client-safe contract
-   * Client에서 노출할 스키마만 선택
-   */
-  clientContract: createClientContract,
+  client: createClient,
+
+  /**
+   * Create a client-safe contract
+   * Client에서 노출할 스키마만 선택
+   */
+  clientContract: createClientContract,
 
   /**
    * Single type-safe fetch call
@@ -199,8 +200,8 @@ export const ManduContract = {
    * });
    * ```
    */
-  fetch: contractFetch,
-} as const;
+  fetch: contractFetch,
+} as const;
 
 /**
  * Alias for backward compatibility within contract module