@simplysm/core-node 13.0.100 → 14.0.4

package/README.md

@@ -1,6 +1,6 @@
 # @simplysm/core-node
 
-Simplysm package - Core module (node). Node.js utilities for file system operations, path manipulation, file watching, and type-safe worker threads.
+Core Node.js utilities -- file system operations, path utilities, file watcher, typed worker threads.
 
 ## Installation
 
@@ -8,105 +8,119 @@ Simplysm package - Core module (node). Node.js utilities for file system operati
 npm install @simplysm/core-node
 ```
 
-## API Overview
-
-### File System Utils (`fsx` namespace)
-
-| API | Type | Description |
-|-----|------|-------------|
-| `existsSync` | function | Check if a file or directory exists (sync) |
-| `exists` | function | Check if a file or directory exists (async) |
-| `mkdirSync` | function | Create a directory recursively (sync) |
-| `mkdir` | function | Create a directory recursively (async) |
-| `rmSync` | function | Delete a file or directory (sync) |
-| `rm` | function | Delete a file or directory with retries (async) |
-| `copySync` | function | Copy a file or directory with optional filter (sync) |
-| `copy` | function | Copy a file or directory with optional filter (async) |
-| `readSync` | function | Read a file as UTF-8 string (sync) |
-| `read` | function | Read a file as UTF-8 string (async) |
-| `readBufferSync` | function | Read a file as Buffer (sync) |
-| `readBuffer` | function | Read a file as Buffer (async) |
-| `readJsonSync` | function | Read a JSON file using JsonConvert (sync) |
-| `readJson` | function | Read a JSON file using JsonConvert (async) |
-| `writeSync` | function | Write data to a file, auto-creates parent dirs (sync) |
-| `write` | function | Write data to a file, auto-creates parent dirs (async) |
-| `writeJsonSync` | function | Write data to a JSON file (sync) |
-| `writeJson` | function | Write data to a JSON file (async) |
-| `readdirSync` | function | Read directory contents (sync) |
-| `readdir` | function | Read directory contents (async) |
-| `statSync` | function | Get file info, follows symlinks (sync) |
-| `stat` | function | Get file info, follows symlinks (async) |
-| `lstatSync` | function | Get file info, no symlink follow (sync) |
-| `lstat` | function | Get file info, no symlink follow (async) |
-| `globSync` | function | Search files by glob pattern (sync) |
-| `glob` | function | Search files by glob pattern (async) |
-| `clearEmptyDirectory` | function | Recursively delete empty directories |
-| `findAllParentChildPathsSync` | function | Search for glob matches traversing parent dirs (sync) |
-| `findAllParentChildPaths` | function | Search for glob matches traversing parent dirs (async) |
-
--> See [docs/fs.md](./docs/fs.md) for details.
-
-### Path Utils (`pathx` namespace)
-
-| API | Type | Description |
-|-----|------|-------------|
-| `NormPath` | type | Brand type for normalized path |
-| `posix` | function | Convert to POSIX-style path (backslash to forward slash) |
-| `changeFileDirectory` | function | Change the directory of a file path |
+## API
+
+### fsx -- File System Utilities
+
+Namespace with sync/async file system operations. See [docs/fsx.md](docs/fsx.md) for full API.
+
+| Function | Signature | Description |
+|----------|-----------|-------------|
+| `existsSync` | `(targetPath: string): boolean` | Check if path exists (sync) |
+| `exists` | `(targetPath: string): Promise<boolean>` | Check if path exists (async) |
+| `mkdirSync` | `(targetPath: string): void` | Create directory recursively (sync) |
+| `mkdir` | `(targetPath: string): Promise<void>` | Create directory recursively (async) |
+| `rmSync` | `(targetPath: string): void` | Remove file/directory (sync) |
+| `rm` | `(targetPath: string): Promise<void>` | Remove file/directory with retry (async) |
+| `copySync` | `(sourcePath, targetPath, filter?): void` | Copy file/directory (sync) |
+| `copy` | `(sourcePath, targetPath, filter?): Promise<void>` | Copy file/directory (async) |
+| `readSync` | `(targetPath: string): string` | Read file as UTF-8 string (sync) |
+| `read` | `(targetPath: string): Promise<string>` | Read file as UTF-8 string (async) |
+| `readBufferSync` | `(targetPath: string): Buffer` | Read file as Buffer (sync) |
+| `readBuffer` | `(targetPath: string): Promise<Buffer>` | Read file as Buffer (async) |
+| `readJsonSync` | `<T>(targetPath: string): T` | Read and parse JSON file (sync) |
+| `readJson` | `<T>(targetPath: string): Promise<T>` | Read and parse JSON file (async) |
+| `writeSync` | `(targetPath, data): void` | Write file with auto-mkdir (sync) |
+| `write` | `(targetPath, data): Promise<void>` | Write file with auto-mkdir (async) |
+| `writeJsonSync` | `(targetPath, data, options?): void` | Write JSON file (sync) |
+| `writeJson` | `(targetPath, data, options?): Promise<void>` | Write JSON file (async) |
+| `readdirSync` | `(targetPath: string): string[]` | List directory contents (sync) |
+| `readdir` | `(targetPath: string): Promise<string[]>` | List directory contents (async) |
+| `statSync` | `(targetPath: string): fs.Stats` | Get file info, follows symlinks (sync) |
+| `stat` | `(targetPath: string): Promise<fs.Stats>` | Get file info, follows symlinks (async) |
+| `lstatSync` | `(targetPath: string): fs.Stats` | Get file info, no symlink follow (sync) |
+| `lstat` | `(targetPath: string): Promise<fs.Stats>` | Get file info, no symlink follow (async) |
+| `globSync` | `(pattern, options?): string[]` | Glob file search (sync) |
+| `glob` | `(pattern, options?): Promise<string[]>` | Glob file search (async) |
+| `clearEmptyDirectory` | `(dirPath: string): Promise<void>` | Recursively remove empty directories |
+| `findAllParentChildPathsSync` | `(childGlob, fromPath, rootPath?): string[]` | Search parent dirs for glob matches (sync) |
+| `findAllParentChildPaths` | `(childGlob, fromPath, rootPath?): Promise<string[]>` | Search parent dirs for glob matches (async) |
+
+### pathx -- Path Utilities
+
+Namespace with path manipulation utilities. See [docs/pathx.md](docs/pathx.md) for full API.
+
+| Export | Kind | Description |
+|--------|------|-------------|
+| `NormPath` | type | Branded type for normalized absolute paths |
+| `posix` | function | Convert path to POSIX style (backslash to slash) |
+| `changeFileDirectory` | function | Change the directory portion of a file path |
 | `basenameWithoutExt` | function | Get filename without extension |
-| `isChildPath` | function | Check if a path is a child of another path |
-| `norm` | function | Normalize path to absolute NormPath |
-| `filterByTargets` | function | Filter files by target path list |
+| `isChildPath` | function | Check if a path is a child of another |
+| `norm` | function | Normalize and resolve path to `NormPath` |
+| `filterByTargets` | function | Filter file paths by target directory prefixes |
 
--> See [docs/path.md](./docs/path.md) for details.
+### FsWatcher -- File System Watcher
 
-### Features
+Chokidar-based file watcher with debounced change events. See [docs/fs-watcher.md](docs/fs-watcher.md) for full API.
 
-| API | Type | Description |
-|-----|------|-------------|
-| `FsWatcherEvent` | type | File change event type (`add`, `addDir`, `change`, `unlink`, `unlinkDir`) |
-| `FsWatcherChangeInfo` | interface | File change information (`event`, `path`) |
-| `FsWatcher` | class | Chokidar-based file watcher with event merging |
+| Export | Kind | Description |
+|--------|------|-------------|
+| `FsWatcherEvent` | type | `"add" \| "addDir" \| "change" \| "unlink" \| "unlinkDir"` |
+| `FsWatcherChangeInfo` | interface | Change event info with path and event type |
+| `FsWatcher` | class | Debounced file system watcher |
 
--> See [docs/features.md](./docs/features.md) for details.
+### Worker -- Typed Worker Threads
 
-### Worker System
+Type-safe worker thread wrapper with Proxy-based RPC. See [docs/worker.md](docs/worker.md) for full API.
 
-| API | Type | Description |
-|-----|------|-------------|
-| `WorkerModule` | interface | Worker module type structure for type inference |
-| `PromisifyMethods` | type | Maps method return values to Promise |
-| `WorkerProxy` | type | Proxy type with promisified methods + on/off/terminate |
+| Export | Kind | Description |
+|--------|------|-------------|
+| `WorkerModule` | interface | Type structure for worker modules |
+| `PromisifyMethods` | type | Maps sync method signatures to async |
+| `WorkerProxy` | type | Proxy type returned by `Worker.create()` |
 | `WorkerRequest` | interface | Internal worker request message |
-| `WorkerResponse` | type | Internal worker response message |
-| `Worker` | object | Type-safe Worker wrapper with `create()` factory |
-| `createWorker` | function | Worker factory for use in worker threads |
+| `WorkerResponse` | type | Internal worker response message (union) |
+| `Worker` | const | Factory object with `create()` method |
+| `createWorker` | function | Define a worker module in a worker thread |
 
--> See [docs/worker.md](./docs/worker.md) for details.
+## Usage
 
-## Usage Examples
-
-```typescript
-import { fsx, pathx, FsWatcher, Worker, createWorker } from "@simplysm/core-node";
+```ts
+import { fsx, pathx } from "@simplysm/core-node";
 
 // File system
-const content = await fsx.read("/path/to/file.txt");
-await fsx.write("/path/to/output.txt", content);
+await fsx.mkdir("/tmp/mydir");
+await fsx.write("/tmp/mydir/hello.txt", "Hello, world!");
+const content = await fsx.read("/tmp/mydir/hello.txt");
+const config = await fsx.readJson<{ port: number }>("config.json");
 
 // Path utilities
-const normalized = pathx.norm("/some/path");
-const posixPath = pathx.posix("C:\\Users\\test");
+const posixPath = pathx.posix("C:\\Users\\test"); // "C:/Users/test"
+const normalized = pathx.norm("/some/path");      // NormPath
+const isChild = pathx.isChildPath("/a/b/c", "/a/b"); // true
+
+// File watcher
+import { FsWatcher } from "@simplysm/core-node";
 
-// File watching
 const watcher = await FsWatcher.watch(["src/**/*.ts"]);
 watcher.onChange({ delay: 300 }, (changes) => {
   for (const { path, event } of changes) {
-    // handle changes
+    console.log(`${event}: ${path}`);
   }
 });
+await watcher.close();
+
+// Worker threads
+import { Worker, createWorker } from "@simplysm/core-node";
+
+// worker.ts
+export default createWorker({
+  add: (a: number, b: number) => a + b,
+});
 
-// Workers
+// main.ts
 const worker = Worker.create<typeof import("./worker")>("./worker.ts");
-const result = await worker.add(10, 20);
+const result = await worker.add(10, 20); // 30
 await worker.terminate();
 ```

package/dist/features/fs-watcher.d.ts

@@ -1,30 +1,30 @@
 import * as chokidar from "chokidar";
 import { type NormPath } from "../utils/path";
 /**
- * List of supported file change event types.
+ * 지원되는 파일 변경 이벤트 타입 목록.
  */
 declare const FS_WATCHER_EVENTS: readonly ["add", "addDir", "change", "unlink", "unlinkDir"];
 /**
- * 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;
 }
 /**
- * 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"]);
@@ -34,16 +34,16 @@ export interface FsWatcherChangeInfo {
  *   }
  * });
  *
- * // Close
+ * // 종료
  * await watcher.close();
  */
 export declare 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 watch(paths: string[], options?: chokidar.ChokidarOptions): Promise<FsWatcher>;
     private readonly _watcher;
@@ -53,17 +53,17 @@ export declare class FsWatcher {
     private readonly _logger;
     private constructor();
     /**
-     * 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;
     }, cb: (changeInfos: FsWatcherChangeInfo[]) => void | Promise<void>): this;
     /**
-     * Closes the file watcher.
+     * 파일 감시자를 종료한다.
      */
     close(): Promise<void>;
 }

package/dist/features/fs-watcher.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fs-watcher.d.ts","sourceRoot":"","sources":["..\\..\\src\\features\\fs-watcher.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,QAAQ,MAAM,UAAU,CAAC;AAKrC,OAAO,EAAE,KAAK,QAAQ,EAAQ,MAAM,eAAe,CAAC;AAyBpD;;GAEG;AACH,QAAA,MAAM,iBAAiB,6DAA8D,CAAC;AAEtF;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEhE;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,wBAAwB;IACxB,KAAK,EAAE,cAAc,CAAC;IACtB,+CAA+C;IAC/C,IAAI,EAAE,QAAQ,CAAC;CAChB;AAMD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,SAAS;IACpB;;;;;;OAMG;WACU,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,OAAO,CAAC,EAAE,QAAQ,CAAC,eAAe,GAAG,OAAO,CAAC,SAAS,CAAC;IAU3F,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAqB;IAC9C,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAiB;IAChD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAuB;IACvD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAmB;IAEjD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoC;IAE5D,OAAO;IA6BP;;;;;;OAMG;IACH,QAAQ,CACN,GAAG,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,EACvB,EAAE,EAAE,CAAC,WAAW,EAAE,mBAAmB,EAAE,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GAC/D,IAAI;IA2EP;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAO7B"}
+{"version":3,"file":"fs-watcher.d.ts","sourceRoot":"","sources":["..\\..\\src\\features\\fs-watcher.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,QAAQ,MAAM,UAAU,CAAC;AAKrC,OAAO,EAAE,KAAK,QAAQ,EAAQ,MAAM,eAAe,CAAC;AAyBpD;;GAEG;AACH,QAAA,MAAM,iBAAiB,6DAA8D,CAAC;AAEtF;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEhE;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,gBAAgB;IAChB,KAAK,EAAE,cAAc,CAAC;IACtB,4BAA4B;IAC5B,IAAI,EAAE,QAAQ,CAAC;CAChB;AAMD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,SAAS;IACpB;;;;;;OAMG;WACU,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,OAAO,CAAC,EAAE,QAAQ,CAAC,eAAe,GAAG,OAAO,CAAC,SAAS,CAAC;IAqB3F,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAqB;IAC9C,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAiB;IAChD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAuB;IACvD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAmB;IAEjD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoC;IAE5D,OAAO;IA6BP;;;;;;OAMG;IACH,QAAQ,CACN,GAAG,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,EACvB,EAAE,EAAE,CAAC,WAAW,EAAE,mBAAmB,EAAE,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GAC/D,IAAI;IA2EP;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAO7B"}

package/dist/features/fs-watcher.js

@@ -4,125 +4,187 @@ import consola from "consola";
 import { Minimatch } from "minimatch";
 import path from "path";
 import { norm } from "../utils/path.js";
+//#region Helpers
+/** Glob 메타문자 패턴 */
 const GLOB_CHARS_RE = /[*?{[\]]/;
+/**
+ * Glob 패턴에서 기본 디렉토리를 추출한다.
+ * @example extractGlobBase("/home/user/src/**\/*.ts") → "/home/user/src"
+ */
 function extractGlobBase(globPath) {
-  const segments = globPath.split(/[/\\]/);
-  const baseSegments = [];
-  for (const seg of segments) {
-    if (GLOB_CHARS_RE.test(seg)) break;
-    baseSegments.push(seg);
-  }
-  return baseSegments.join(path.sep) || path.sep;
+    const segments = globPath.split(/[/\\]/);
+    const baseSegments = [];
+    for (const seg of segments) {
+        if (GLOB_CHARS_RE.test(seg))
+            break;
+        baseSegments.push(seg);
+    }
+    return baseSegments.join(path.sep) || path.sep;
 }
+//#endregion
+//#region Types
+/**
+ * 지원되는 파일 변경 이벤트 타입 목록.
+ */
 const FS_WATCHER_EVENTS = ["add", "addDir", "change", "unlink", "unlinkDir"];
-class FsWatcher {
-  /**
-   * Starts watching files (asynchronous).
-   * Waits until the ready event is emitted.
-   *
-   * @param paths - Array of file/directory paths or glob patterns to watch
-   * @param options - chokidar options
-   */
-  static async watch(paths, options) {
-    return new Promise((resolve, reject) => {
-      const watcher = new FsWatcher(paths, options);
-      watcher._watcher.on("ready", () => {
-        resolve(watcher);
-      });
-      watcher._watcher.on("error", reject);
-    });
-  }
-  _watcher;
-  _ignoreInitial = true;
-  _debounceQueues = [];
-  _globMatchers = [];
-  _logger = consola.withTag("sd-fs-watcher");
-  constructor(paths, options) {
-    const watchPaths = [];
-    for (const p of paths) {
-      const posixPath = p.replace(/\\/g, "/");
-      if (GLOB_CHARS_RE.test(posixPath)) {
-        this._globMatchers.push(new Minimatch(posixPath, { dot: true }));
-        watchPaths.push(extractGlobBase(p));
-      } else {
-        watchPaths.push(p);
-      }
+//#endregion
+//#region FsWatcher
+/**
+ * Chokidar 기반 파일 시스템 감시 래퍼.
+ * 짧은 시간 내에 발생하는 이벤트를 병합하여 콜백을 한 번만 호출한다.
+ *
+ * **주의**: chokidar의 `ignoreInitial` 옵션은 내부적으로 항상 `true`로 설정된다.
+ * `options.ignoreInitial: false`를 전달하면 첫 번째 `onChange` 호출 시 빈 배열로 콜백이 호출되지만,
+ * 실제 초기 파일 목록은 포함되지 않는다.
+ * 이는 이벤트 병합 로직과의 충돌을 방지하기 위한 의도적인 동작이다.
+ *
+ * @example
+ * const watcher = await FsWatcher.watch(["src/**\/*.ts"]);
+ * watcher.onChange({ delay: 300 }, (changes) => {
+ *   for (const { path, event } of changes) {
+ *     console.log(`${event}: ${path}`);
+ *   }
+ * });
+ *
+ * // 종료
+ * await watcher.close();
+ */
+export class FsWatcher {
+    /**
+     * 파일 감시를 시작한다 (비동기).
+     * ready 이벤트가 발생할 때까지 대기한다.
+     *
+     * @param paths - 감시할 파일/디렉토리 경로 또는 glob 패턴 배열
+     * @param options - chokidar 옵션
+     */
+    static async watch(paths, options) {
+        return new Promise((resolve, reject) => {
+            const watcher = new FsWatcher(paths, options);
+            const onReady = () => {
+                watcher._watcher.removeListener("error", onError);
+                resolve(watcher);
+            };
+            const onError = (err) => {
+                watcher._watcher.removeListener("ready", onReady);
+                watcher.close().then(() => reject(err), () => reject(err));
+            };
+            watcher._watcher.once("ready", onReady);
+            watcher._watcher.once("error", onError);
+        });
+    }
+    _watcher;
+    _ignoreInitial = true;
+    _debounceQueues = [];
+    _globMatchers = [];
+    _logger = consola.withTag("sd-fs-watcher");
+    constructor(paths, options) {
+        const watchPaths = [];
+        for (const p of paths) {
+            const posixPath = p.replace(/\\/g, "/");
+            if (GLOB_CHARS_RE.test(posixPath)) {
+                this._globMatchers.push(new Minimatch(posixPath, { dot: true }));
+                watchPaths.push(extractGlobBase(p));
+            }
+            else {
+                watchPaths.push(p);
+            }
+        }
+        // 중복 경로 제거
+        const uniquePaths = [...new Set(watchPaths)];
+        this._watcher = chokidar.watch(uniquePaths, {
+            persistent: true,
+            ...options,
+            ignoreInitial: true,
+        });
+        this._ignoreInitial = options?.ignoreInitial ?? this._ignoreInitial;
+        // 감시 중 발생하는 오류를 로깅
+        this._watcher.on("error", (err) => {
+            this._logger.error("FsWatcher 오류:", err);
+        });
     }
-    const uniquePaths = [...new Set(watchPaths)];
-    this._watcher = chokidar.watch(uniquePaths, {
-      persistent: true,
-      ...options,
-      ignoreInitial: true
-    });
-    this._ignoreInitial = options?.ignoreInitial ?? this._ignoreInitial;
-    this._watcher.on("error", (err) => {
-      this._logger.error("FsWatcher error:", 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
-   */
-  onChange(opt, cb) {
-    const fnQ = new DebounceQueue(opt.delay);
-    this._debounceQueues.push(fnQ);
-    let changeInfoMap = /* @__PURE__ */ new Map();
-    if (!this._ignoreInitial) {
-      fnQ.run(async () => {
-        await cb([]);
-      });
+    /**
+     * 파일 변경 이벤트 핸들러를 등록한다.
+     * 지정된 지연 시간 동안 이벤트를 수집하여 콜백을 한 번 호출한다.
+     *
+     * @param opt.delay - 이벤트 병합 대기 시간 (ms)
+     * @param cb - 변경 이벤트 콜백
+     */
+    onChange(opt, cb) {
+        const fnQ = new DebounceQueue(opt.delay);
+        this._debounceQueues.push(fnQ);
+        let changeInfoMap = new Map();
+        // ignoreInitial이 false이면 초기에 빈 배열로 콜백 호출
+        if (!this._ignoreInitial) {
+            fnQ.run(async () => {
+                await cb([]);
+            });
+        }
+        this._watcher.on("all", (event, filePath) => {
+            // 지원되는 이벤트만 처리
+            if (!FS_WATCHER_EVENTS.includes(event))
+                return;
+            // glob matcher가 존재하면 패턴 필터링 적용
+            if (this._globMatchers.length > 0) {
+                const posixFilePath = filePath.replace(/\\/g, "/");
+                if (!this._globMatchers.some((m) => m.match(posixFilePath)))
+                    return;
+            }
+            /*
+             * 이벤트 병합 전략:
+             * 같은 파일에 대해 짧은 시간 내에 여러 이벤트가 발생하면, 최종 상태만 전달한다.
+             * - add + change → add (생성 직후 수정은 생성으로 간주)
+             * - add + unlink → 변경 없음 (생성 직후 삭제는 변경 없음으로 간주)
+             * - unlink + add → add (삭제 후 재생성은 생성으로 간주)
+             * - 그 외 → 최신 이벤트로 덮어쓰기
+             */
+            if (!changeInfoMap.has(filePath)) {
+                changeInfoMap.set(filePath, event);
+            }
+            const prevEvent = changeInfoMap.get(filePath);
+            if (prevEvent === "add" && event === "change") {
+                // add 후 change → add 유지
+                changeInfoMap.set(filePath, "add");
+            }
+            else if ((prevEvent === "add" && event === "unlink") ||
+                (prevEvent === "addDir" && event === "unlinkDir")) {
+                // add 후 unlink → 변경 없음 (삭제)
+                changeInfoMap.delete(filePath);
+            }
+            else if (prevEvent === "unlink" && (event === "add" || event === "change")) {
+                // unlink 후 add/change → add (파일 재생성)
+                changeInfoMap.set(filePath, "add");
+            }
+            else if (prevEvent === "unlinkDir" && event === "addDir") {
+                // unlinkDir 후 addDir → addDir (디렉토리 재생성)
+                changeInfoMap.set(filePath, "addDir");
+            }
+            else {
+                changeInfoMap.set(filePath, event);
+            }
+            fnQ.run(async () => {
+                if (changeInfoMap.size === 0)
+                    return;
+                const currChangeInfoMap = changeInfoMap;
+                changeInfoMap = new Map();
+                const changeInfos = Array.from(currChangeInfoMap.entries()).map(([changedPath, evt]) => ({
+                    path: norm(changedPath),
+                    event: evt,
+                }));
+                await cb(changeInfos);
+            });
+        });
+        return this;
     }
-    this._watcher.on("all", (event, filePath) => {
-      if (!FS_WATCHER_EVENTS.includes(event)) return;
-      if (this._globMatchers.length > 0) {
-        const posixFilePath = filePath.replace(/\\/g, "/");
-        if (!this._globMatchers.some((m) => m.match(posixFilePath))) return;
-      }
-      if (!changeInfoMap.has(filePath)) {
-        changeInfoMap.set(filePath, event);
-      }
-      const prevEvent = changeInfoMap.get(filePath);
-      if (prevEvent === "add" && event === "change") {
-        changeInfoMap.set(filePath, "add");
-      } else if (prevEvent === "add" && event === "unlink" || prevEvent === "addDir" && event === "unlinkDir") {
-        changeInfoMap.delete(filePath);
-      } else if (prevEvent === "unlink" && (event === "add" || event === "change")) {
-        changeInfoMap.set(filePath, "add");
-      } else if (prevEvent === "unlinkDir" && event === "addDir") {
-        changeInfoMap.set(filePath, "addDir");
-      } else {
-        changeInfoMap.set(filePath, event);
-      }
-      fnQ.run(async () => {
-        if (changeInfoMap.size === 0) return;
-        const currChangeInfoMap = changeInfoMap;
-        changeInfoMap = /* @__PURE__ */ new Map();
-        const changeInfos = Array.from(currChangeInfoMap.entries()).map(
-          ([changedPath, evt]) => ({
-            path: norm(changedPath),
-            event: evt
-          })
-        );
-        await cb(changeInfos);
-      });
-    });
-    return this;
-  }
-  /**
-   * Closes the file watcher.
-   */
-  async close() {
-    for (const q of this._debounceQueues) {
-      q.dispose();
+    /**
+     * 파일 감시자를 종료한다.
+     */
+    async close() {
+        for (const q of this._debounceQueues) {
+            q.dispose();
+        }
+        this._debounceQueues.length = 0;
+        await this._watcher.close();
     }
-    this._debounceQueues.length = 0;
-    await this._watcher.close();
-  }
 }
-export {
-  FsWatcher
-};
-//# sourceMappingURL=fs-watcher.js.map
+//#endregion
+//# sourceMappingURL=fs-watcher.js.map

package/dist/features/fs-watcher.js.map

@@ -1,6 +1 @@
-{
-  "version": 3,
-  "sources": ["../../src/features/fs-watcher.ts"],
-  "mappings": "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",
-  "names": []
-}
+{"version":3,"file":"fs-watcher.js","sourceRoot":"","sources":["..\\..\\src\\features\\fs-watcher.ts"],"names":[],"mappings":"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"}