@simplysm/core-node 13.0.100 → 14.0.4

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@simplysm/core-node",
-  "version": "13.0.100",
-  "description": "Simplysm package - Core module (node)",
-  "author": "simplysm",
+  "version": "14.0.4",
+  "description": "심플리즘 패키지 - 코어 (node)",
+  "author": "심플리즘",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -14,9 +14,9 @@
   "types": "./dist/index.d.ts",
   "files": [
     "dist",
-    "docs",
     "src",
-    "tests"
+    "lib",
+    "docs"
   ],
   "sideEffects": false,
   "dependencies": {
@@ -25,6 +25,9 @@
     "glob": "^13.0.6",
     "minimatch": "^10.2.4",
     "tsx": "^4.21.0",
-    "@simplysm/core-common": "13.0.100"
+    "@simplysm/core-common": "14.0.4"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.37"
   }
 }

package/src/features/fs-watcher.ts

@@ -8,11 +8,11 @@ import { type NormPath, norm } from "../utils/path";
 
 //#region Helpers
 
-/** Glob metacharacter pattern */
+/** Glob 메타문자 패턴 */
 const GLOB_CHARS_RE = /[*?{[\]]/;
 
 /**
- * Extracts the base directory from a glob pattern.
+ * Glob 패턴에서 기본 디렉토리를 추출한다.
  * @example extractGlobBase("/home/user/src/**\/*.ts") → "/home/user/src"
  */
 function extractGlobBase(globPath: string): string {
@@ -30,22 +30,22 @@ function extractGlobBase(globPath: string): string {
 //#region Types
 
 /**
- * List of supported file change event types.
+ * 지원되는 파일 변경 이벤트 타입 목록.
  */
 const FS_WATCHER_EVENTS = ["add", "addDir", "change", "unlink", "unlinkDir"] as const;
 
 /**
- * File change event type.
+ * 파일 변경 이벤트 타입.
  */
 export type FsWatcherEvent = (typeof FS_WATCHER_EVENTS)[number];
 
 /**
- * File change information.
+ * 파일 변경 정보.
  */
 export interface FsWatcherChangeInfo {
-  /** Change event type */
+  /** 변경 이벤트 타입 */
   event: FsWatcherEvent;
-  /** Changed file/directory path (normalized) */
+  /** 변경된 파일/디렉토리 경로 (정규화됨) */
   path: NormPath;
 }
 
@@ -54,13 +54,13 @@ export interface FsWatcherChangeInfo {
 //#region FsWatcher
 
 /**
- * Chokidar-based file system watcher wrapper.
- * Merges events that occur within a short time and calls the callback once.
+ * Chokidar 기반 파일 시스템 감시 래퍼.
+ * 짧은 시간 내에 발생하는 이벤트를 병합하여 콜백을 한 번만 호출한다.
  *
- * **Note**: The `ignoreInitial` option of chokidar is internally always set to `true`.
- * If you pass `options.ignoreInitial: false`, the callback will be called with an empty array on the first `onChange` call,
- * but the actual initial file list is not included.
- * This is intentional behavior to prevent conflicts with the event merging logic.
+ * **주의**: chokidar의 `ignoreInitial` 옵션은 내부적으로 항상 `true`로 설정된다.
+ * `options.ignoreInitial: false`를 전달하면 첫 번째 `onChange` 호출 시 빈 배열로 콜백이 호출되지만,
+ * 실제 초기 파일 목록은 포함되지 않는다.
+ * 이는 이벤트 병합 로직과의 충돌을 방지하기 위한 의도적인 동작이다.
  *
  * @example
  * const watcher = await FsWatcher.watch(["src/**\/*.ts"]);
@@ -70,24 +70,35 @@ export interface FsWatcherChangeInfo {
  *   }
  * });
  *
- * // Close
+ * // 종료
  * await watcher.close();
  */
 export class FsWatcher {
   /**
-   * Starts watching files (asynchronous).
-   * Waits until the ready event is emitted.
+   * 파일 감시를 시작한다 (비동기).
+   * ready 이벤트가 발생할 때까지 대기한다.
    *
-   * @param paths - Array of file/directory paths or glob patterns to watch
-   * @param options - chokidar options
+   * @param paths - 감시할 파일/디렉토리 경로 또는 glob 패턴 배열
+   * @param options - chokidar 옵션
    */
   static async watch(paths: string[], options?: chokidar.ChokidarOptions): Promise<FsWatcher> {
     return new Promise<FsWatcher>((resolve, reject) => {
       const watcher = new FsWatcher(paths, options);
-      watcher._watcher.on("ready", () => {
+
+      const onReady = () => {
+        watcher._watcher.removeListener("error", onError);
         resolve(watcher);
-      });
-      watcher._watcher.on("error", reject);
+      };
+      const onError = (err: unknown) => {
+        watcher._watcher.removeListener("ready", onReady);
+        watcher.close().then(
+          () => reject(err),
+          () => reject(err),
+        );
+      };
+
+      watcher._watcher.once("ready", onReady);
+      watcher._watcher.once("error", onError);
     });
   }
 
@@ -111,7 +122,7 @@ export class FsWatcher {
       }
     }
 
-    // Remove duplicate paths
+    // 중복 경로 제거
     const uniquePaths = [...new Set(watchPaths)];
 
     this._watcher = chokidar.watch(uniquePaths, {
@@ -121,18 +132,18 @@ export class FsWatcher {
     });
     this._ignoreInitial = options?.ignoreInitial ?? this._ignoreInitial;
 
-    // Log errors that occur during watching
+    // 감시 중 발생하는 오류를 로깅
     this._watcher.on("error", (err) => {
-      this._logger.error("FsWatcher error:", err);
+      this._logger.error("FsWatcher 오류:", err);
     });
   }
 
   /**
-   * Registers a file change event handler.
-   * Collects events for the specified delay time and calls the callback once.
+   * 파일 변경 이벤트 핸들러를 등록한다.
+   * 지정된 지연 시간 동안 이벤트를 수집하여 콜백을 한 번 호출한다.
    *
-   * @param opt.delay - Event merge wait time (ms)
-   * @param cb - Change event callback
+   * @param opt.delay - 이벤트 병합 대기 시간 (ms)
+   * @param cb - 변경 이벤트 콜백
    */
   onChange(
     opt: { delay?: number },
@@ -143,7 +154,7 @@ export class FsWatcher {
 
     let changeInfoMap = new Map<string, EventName>();
 
-    // If ignoreInitial is false, call callback with empty array initially
+    // ignoreInitial이 false이면 초기에 빈 배열로 콜백 호출
     if (!this._ignoreInitial) {
       fnQ.run(async () => {
         await cb([]);
@@ -151,22 +162,22 @@ export class FsWatcher {
     }
 
     this._watcher.on("all", (event, filePath) => {
-      // Only process supported events
+      // 지원되는 이벤트만 처리
       if (!FS_WATCHER_EVENTS.includes(event as FsWatcherEvent)) return;
 
-      // If glob matchers exist, apply pattern filtering
+      // glob matcher가 존재하면 패턴 필터링 적용
       if (this._globMatchers.length > 0) {
         const posixFilePath = filePath.replace(/\\/g, "/");
         if (!this._globMatchers.some((m) => m.match(posixFilePath))) return;
       }
 
       /*
-       * Event merging strategy:
-       * If multiple events occur for the same file within a short time, only the final state is passed.
-       * - add + change → add (modification immediately after creation is considered as creation)
-       * - add + unlink → no change (immediate deletion after creation is considered as no change)
-       * - unlink + add → add (recreation after deletion is considered as creation)
-       * - otherwise → overwrite with latest event
+       * 이벤트 병합 전략:
+       * 같은 파일에 대해 짧은 시간 내에 여러 이벤트가 발생하면, 최종 상태만 전달한다.
+       * - add + change → add (생성 직후 수정은 생성으로 간주)
+       * - add + unlink → 변경 없음 (생성 직후 삭제는 변경 없음으로 간주)
+       * - unlink + add → add (삭제 후 재생성은 생성으로 간주)
+       * - 그 외 → 최신 이벤트로 덮어쓰기
        */
       if (!changeInfoMap.has(filePath)) {
         changeInfoMap.set(filePath, event);
@@ -174,19 +185,19 @@ export class FsWatcher {
       const prevEvent = changeInfoMap.get(filePath)!;
 
       if (prevEvent === "add" && event === "change") {
-        // add followed by change → keep add
+        // add 후 change → add 유지
         changeInfoMap.set(filePath, "add");
       } else if (
         (prevEvent === "add" && event === "unlink") ||
         (prevEvent === "addDir" && event === "unlinkDir")
       ) {
-        // add followed by unlink → no change (deletion)
+        // add 후 unlink → 변경 없음 (삭제)
         changeInfoMap.delete(filePath);
       } else if (prevEvent === "unlink" && (event === "add" || event === "change")) {
-        // unlink followed by add/change → add (file recreation)
+        // unlink 후 add/change → add (파일 재생성)
         changeInfoMap.set(filePath, "add");
       } else if (prevEvent === "unlinkDir" && event === "addDir") {
-        // unlinkDir followed by addDir → addDir (directory recreation)
+        // unlinkDir 후 addDir → addDir (디렉토리 재생성)
         changeInfoMap.set(filePath, "addDir");
       } else {
         changeInfoMap.set(filePath, event);
@@ -213,7 +224,7 @@ export class FsWatcher {
   }
 
   /**
-   * Closes the file watcher.
+   * 파일 감시자를 종료한다.
    */
   async close(): Promise<void> {
     for (const q of this._debounceQueues) {

package/src/index.ts

@@ -1,11 +1,11 @@
-// Utils
+// 유틸리티
 export * as fsx from "./utils/fs";
 export * as pathx from "./utils/path";
 
-// Features
+// 기능
 export * from "./features/fs-watcher";
 
-// Worker
+// 워커
 export * from "./worker/types";
 export * from "./worker/worker";
 export * from "./worker/create-worker";