@simplysm/core-node 13.0.69 → 13.0.70

package/src/worker/types.ts

@@ -1,11 +1,11 @@
 //#region Types
 
 /**
- * `createWorker()`가 반환하는 워커 모듈의 타입 구조.
- * `Worker.create<typeof import("./worker")>()`에서 타입 추론에 사용된다.
+ * Type structure of the worker module returned by `createWorker()`.
+ * Used for type inference in `Worker.create<typeof import("./worker")>()`.
  *
- * @see createWorker - 워커 모듈 생성
- * @see Worker.create - 워커 프록시 생성
+ * @see createWorker - Create worker module
+ * @see Worker.create - Create worker proxy
  */
 export interface WorkerModule {
   default: {
@@ -15,9 +15,9 @@ export interface WorkerModule {
 }
 
 /**
- * 메서드 타입의 반환값을 Promise로 래핑하는 매핑 타입.
- * 워커 메서드는 postMessage 기반으로 동작하여 항상 비동기이므로,
- * 동기 메서드 타입도 `Promise<Awaited<R>>`로 변환한다.
+ * Mapping type that wraps method return values in Promise.
+ * Worker methods operate based on postMessage and are always asynchronous,
+ * so synchronous method types are also converted to `Promise<Awaited<R>>`.
  */
 export type PromisifyMethods<TMethods> = {
   [K in keyof TMethods]: TMethods[K] extends (...args: infer P) => infer R
@@ -26,14 +26,14 @@ export type PromisifyMethods<TMethods> = {
 };
 
 /**
- * SdWorker.create()가 반환하는 Proxy 타입.
- * Promisified 메서드들 + on() + terminate() 제공.
+ * Proxy type returned by Worker.create().
+ * Provides promisified methods + on() + terminate().
  */
 export type WorkerProxy<TModule extends WorkerModule> = PromisifyMethods<
   TModule["default"]["__methods"]
 > & {
   /**
-   * 워커 이벤트 리스너 등록.
+   * Registers a worker event listener.
    */
   on<K extends keyof TModule["default"]["__events"] & string>(
     event: K,
@@ -41,7 +41,7 @@ export type WorkerProxy<TModule extends WorkerModule> = PromisifyMethods<
   ): void;
 
   /**
-   * 워커 이벤트 리스너 제거.
+   * Unregisters a worker event listener.
    */
   off<K extends keyof TModule["default"]["__events"] & string>(
     event: K,
@@ -49,13 +49,13 @@ export type WorkerProxy<TModule extends WorkerModule> = PromisifyMethods<
   ): void;
 
   /**
-   * 워커 종료.
+   * Terminates the worker.
    */
   terminate(): Promise<void>;
 };
 
 /**
- * Worker 내부 요청 메시지.
+ * Internal worker request message.
  */
 export interface WorkerRequest {
   id: string;
@@ -64,7 +64,7 @@ export interface WorkerRequest {
 }
 
 /**
- * Worker 내부 응답 메시지.
+ * Internal worker response message.
  */
 export type WorkerResponse =
   | {

package/src/worker/worker.ts

@@ -11,11 +11,11 @@ const logger = consola.withTag("sd-worker");
 //#region WorkerInternal
 
 /**
- * Worker 내부 구현 클래스.
- * Proxy를 통해 외부에 노출됨.
+ * Internal implementation class for Worker.
+ * Exposed to the outside through a Proxy.
  *
- * 개발 환경(.ts)에서는 tsx를 통해 TypeScript 워커 파일을 실행하고,
- * 프로덕션 환경(.js)에서는 직접 Worker를 생성한다.
+ * In development (.ts files), TypeScript worker files are executed via tsx.
+ * In production (.js files), Worker is created directly.
  */
 class WorkerInternal extends EventEmitter<Record<string, unknown>> {
   private readonly _worker: WorkerRaw;
@@ -30,13 +30,13 @@ class WorkerInternal extends EventEmitter<Record<string, unknown>> {
 
     const ext = path.extname(import.meta.filename);
 
-    // 타입 가드를 통한 env 객체 추출
+    // Extract env object through type guard
     const envObj = opt?.env != null && typeof opt.env === "object" ? opt.env : {};
 
-    // 개발 환경 (.ts 파일)인 경우 tsx를 통해 실행
-    // worker-dev-proxy.js: tsx로 TypeScript 워커 파일을 동적으로 로드하는 프록시
+    // In development (.ts files), execute via tsx
+    // worker-dev-proxy.js: Proxy to dynamically load TypeScript worker files via tsx
     if (ext === ".ts") {
-      // file:// URL인 경우 절대 경로로 변환 (worker-dev-proxy.js에서 다시 pathToFileURL 적용)
+      // If file:// URL, convert to absolute path (worker-dev-proxy.js applies pathToFileURL again)
       const workerPath = filePath.startsWith("file://") ? fileURLToPath(filePath) : filePath;
       this._worker = new WorkerRaw(
         path.resolve(import.meta.dirname, "../../lib/worker-dev-proxy.js"),
@@ -52,8 +52,8 @@ class WorkerInternal extends EventEmitter<Record<string, unknown>> {
         },
       );
     } else {
-      // 프로덕션 환경 (.js 파일)
-      // file:// URL인 경우 변환, 이미 절대 경로인 경우 그대로 사용
+      // Production environment (.js files)
+      // If file:// URL, convert it; otherwise use absolute path as-is
       const workerPath = filePath.startsWith("file://") ? fileURLToPath(filePath) : filePath;
       this._worker = new WorkerRaw(workerPath, {
         stdout: true,
@@ -66,30 +66,30 @@ class WorkerInternal extends EventEmitter<Record<string, unknown>> {
       });
     }
 
-    // 워커의 stdout/stderr를 메인에 출력
+    // Pipe worker's stdout/stderr to main process
     this._worker.stdout.pipe(process.stdout);
     this._worker.stderr.pipe(process.stderr);
 
     this._worker.on("exit", (code) => {
       if (!this._isTerminated && code !== 0) {
-        logger.error(`워커가 오류와 함께 닫힘 (code: ${code})`);
-        // 비정상 종료 시 대기 중인 모든 요청 reject
-        this._rejectAllPending(new Error(`워커가 비정상 종료됨 (code: ${code})`));
+        logger.error(`Worker crashed (code: ${code})`);
+        // Reject all pending requests on abnormal exit
+        this._rejectAllPending(new Error(`Worker crashed (code: ${code})`));
       }
     });
 
     this._worker.on("error", (err) => {
-      logger.error("워커 오류:", err);
-      // 워커 에러 시 대기 중인 모든 요청 reject
+      logger.error("Worker error:", err);
+      // Reject all pending requests on worker error
       this._rejectAllPending(err);
     });
 
     this._worker.on("message", (serializedResponse: unknown) => {
       const decoded = transferableDecode(serializedResponse);
 
-      // 응답 구조 검증
+      // Validate response structure
       if (decoded == null || typeof decoded !== "object" || !("type" in decoded)) {
-        logger.warn("워커에서 잘못된 형식의 응답:", decoded);
+        logger.warn("Invalid response format from worker:", decoded);
         return;
       }
       const response = decoded as WorkerResponse;
@@ -116,7 +116,7 @@ class WorkerInternal extends EventEmitter<Record<string, unknown>> {
   }
 
   /**
-   * 대기 중인 모든 요청을 reject합니다.
+   * Rejects all pending requests.
    */
   private _rejectAllPending(err: Error): void {
     for (const [_id, { method, reject }] of this._pendingRequests) {
@@ -126,7 +126,7 @@ class WorkerInternal extends EventEmitter<Record<string, unknown>> {
   }
 
   /**
-   * 워커 메서드 호출.
+   * Calls a worker method.
    */
   call(method: string, params: unknown[]): Promise<unknown> {
     return new Promise((resolve, reject) => {
@@ -144,11 +144,11 @@ class WorkerInternal extends EventEmitter<Record<string, unknown>> {
   }
 
   /**
-   * 워커 종료.
+   * Terminates the worker.
    */
   async terminate(): Promise<void> {
     this._isTerminated = true;
-    this._rejectAllPending(new Error("워커가 종료됨"));
+    this._rejectAllPending(new Error("Worker terminated"));
     await this._worker.terminate();
   }
 }
@@ -158,7 +158,7 @@ class WorkerInternal extends EventEmitter<Record<string, unknown>> {
 //#region Worker
 
 /**
- * 타입 안전한 Worker 래퍼.
+ * Type-safe Worker wrapper.
  *
  * @example
  * // worker.ts
@@ -173,11 +173,11 @@ class WorkerInternal extends EventEmitter<Record<string, unknown>> {
  */
 export const Worker = {
   /**
-   * 타입 안전한 Worker Proxy 생성.
+   * Creates a type-safe Worker Proxy.
    *
-   * @param filePath - 워커 파일 경로 (file:// URL 또는 절대 경로)
-   * @param opt - Worker 옵션
-   * @returns Proxy 객체 (메서드 직접 호출, on(), terminate() 지원)
+   * @param filePath - Worker file path (file:// URL or absolute path)
+   * @param opt - Worker options
+   * @returns Proxy object (supports direct method calls, on(), and terminate())
    */
   create<TModule extends WorkerModule>(
     filePath: string,
@@ -187,7 +187,7 @@ export const Worker = {
 
     return new Proxy({} as WorkerProxy<TModule>, {
       get(_target, prop: string) {
-        // 예약된 메서드: on, off, terminate
+        // Reserved methods: on, off, terminate
         if (prop === "on") {
           return (event: string, listener: (data: unknown) => void) => {
             internal.on(event, listener);
@@ -202,7 +202,7 @@ export const Worker = {
           return () => internal.terminate();
         }
 
-        // 그 외는 워커 메서드로 처리
+        // Otherwise, treat as worker method
         return (...args: unknown[]) => internal.call(prop, args);
       },
     });

package/tests/utils/fs-watcher.spec.ts

@@ -0,0 +1,339 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import path from "path";
+import fs from "fs";
+import os from "os";
+import { FsWatcher } from "../../src/features/fs-watcher";
+
+describe("SdFsWatcher", () => {
+  const testDir = path.join(os.tmpdir(), "fs-watcher-test-" + Date.now());
+  let watcher: FsWatcher | undefined;
+
+  beforeEach(() => {
+    fs.mkdirSync(testDir, { recursive: true });
+  });
+
+  afterEach(async () => {
+    if (watcher != null) {
+      await watcher.close();
+      watcher = undefined;
+    }
+    fs.rmSync(testDir, { recursive: true, force: true });
+  });
+
+  //#region watch
+
+  describe("watch", () => {
+    it("starts watching files", async () => {
+      watcher = await FsWatcher.watch([path.join(testDir, "**/*")]);
+      expect(watcher).toBeDefined();
+    });
+
+    it("starts watching files with options", async () => {
+      watcher = await FsWatcher.watch([path.join(testDir, "**/*")], {
+        ignoreInitial: false,
+      });
+      expect(watcher).toBeDefined();
+    });
+
+    it("logs errors when error events occur", async () => {
+      // chokidar starts watching non-existent paths without issue
+      // Error events only occur on actual filesystem errors
+      const nonExistentPath = path.join(testDir, "non-existent-dir-" + Date.now());
+      watcher = await FsWatcher.watch([nonExistentPath]);
+
+      // Error handler is registered so it doesn't crash even if an error occurs
+      expect(watcher).toBeDefined();
+    });
+  });
+
+  //#endregion
+
+  //#region close
+
+  describe("close", () => {
+    it("closes the watcher", async () => {
+      watcher = await FsWatcher.watch([path.join(testDir, "**/*")]);
+
+      // Test passes if close() completes without error
+      await expect(watcher.close()).resolves.toBeUndefined();
+
+      // Release watcher reference after closing
+      watcher = undefined;
+    });
+  });
+
+  //#endregion
+
+  //#region chaining
+
+  describe("onChange", () => {
+    it("supports onChange method chaining", async () => {
+      watcher = await FsWatcher.watch([path.join(testDir, "**/*")]);
+
+      const fn = vi.fn();
+      const result = watcher.onChange({ delay: 100 }, fn);
+
+      expect(result).toBe(watcher);
+    });
+
+    it("can specify delay option with various values", async () => {
+      watcher = await FsWatcher.watch([path.join(testDir, "**/*")]);
+
+      const fn = vi.fn();
+      // delay option should be specifiable with various values
+      expect(() => watcher!.onChange({ delay: 0 }, fn)).not.toThrow();
+      expect(() => watcher!.onChange({ delay: 500 }, fn)).not.toThrow();
+      expect(() => watcher!.onChange({ delay: 1000 }, fn)).not.toThrow();
+    });
+  });
+
+  //#endregion
+
+  //#region Types
+
+  describe("Types", () => {
+    it("verifies FsWatcherEvent type definition", () => {
+      // Verify that event types are correctly defined
+      const validEvents = ["add", "addDir", "change", "unlink", "unlinkDir"];
+      expect(validEvents).toContain("add");
+      expect(validEvents).toContain("addDir");
+      expect(validEvents).toContain("change");
+      expect(validEvents).toContain("unlink");
+      expect(validEvents).toContain("unlinkDir");
+    });
+
+    it("verifies FsWatcherChangeInfo structure", () => {
+      // Type check to verify interface structure
+      const mockChangeInfo = {
+        event: "add" as const,
+        path: "/test/path",
+      };
+
+      expect(mockChangeInfo.event).toBe("add");
+      expect(mockChangeInfo.path).toBe("/test/path");
+    });
+  });
+
+  //#endregion
+
+  //#region Glob Pattern Filtering
+
+  describe("glob pattern filtering", () => {
+    const DELAY = 300;
+
+    const wait = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
+
+    const waitForChanges = (
+      watcherInstance: FsWatcher,
+      delay: number,
+    ): Promise<Array<{ event: string; path: string }>> => {
+      return new Promise((resolve) => {
+        watcherInstance.onChange({ delay }, (changeInfos) => {
+          resolve(changeInfos.map((c) => ({ event: c.event, path: c.path })));
+        });
+      });
+    };
+
+    it("receives events only for files matching glob pattern", async () => {
+      // Glob pattern that watches only .txt files
+      const globPattern = path.join(testDir, "**/*.txt");
+
+      watcher = await FsWatcher.watch([globPattern]);
+
+      const changesPromise = waitForChanges(watcher, DELAY);
+
+      // Create .txt file (matches)
+      fs.writeFileSync(path.join(testDir, "matched.txt"), "hello");
+
+      // Create .json file (does not match)
+      await wait(50);
+      fs.writeFileSync(path.join(testDir, "ignored.json"), "{}");
+
+      const changes = await changesPromise;
+
+      // Should only receive events for .txt file
+      expect(changes.length).toBe(1);
+      expect(changes[0].path).toContain("matched.txt");
+      expect(changes[0].event).toBe("add");
+    });
+  });
+
+  //#endregion
+
+  //#region Event Merging
+
+  describe("event merging", () => {
+    const DELAY = 300;
+
+    /**
+     * Helper function to wait for specified time.
+     */
+    const wait = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
+
+    /**
+     * Helper function to wait until event callback is called.
+     */
+    const waitForChanges = (
+      watcherInstance: FsWatcher,
+      delay: number,
+    ): Promise<Array<{ event: string; path: string }>> => {
+      return new Promise((resolve) => {
+        watcherInstance.onChange({ delay }, (changeInfos) => {
+          resolve(changeInfos.map((c) => ({ event: c.event, path: c.path })));
+        });
+      });
+    };
+
+    it("returns only add event when file is added then modified", async () => {
+      const testFile = path.join(testDir, "test-add-change.txt");
+
+      watcher = await FsWatcher.watch([testDir]);
+
+      const changesPromise = waitForChanges(watcher, DELAY);
+
+      // Add file
+      fs.writeFileSync(testFile, "initial");
+
+      // Modify file with short interval (must occur within delay)
+      await wait(50);
+      fs.writeFileSync(testFile, "modified");
+
+      // Wait for event callback
+      const changes = await changesPromise;
+
+      // add → change should be merged to add
+      expect(changes.length).toBe(1);
+      expect(changes[0].event).toBe("add");
+    });
+
+    it("produces no events or no changes when file is added then deleted", async () => {
+      const testFile = path.join(testDir, "test-add-unlink.txt");
+
+      watcher = await FsWatcher.watch([testDir]);
+
+      const changes: Array<{ event: string; path: string }> = [];
+      let resolved = false;
+
+      const changesPromise = new Promise<void>((resolve) => {
+        watcher!.onChange({ delay: DELAY }, (changeInfos) => {
+          changes.push(...changeInfos.map((c) => ({ event: c.event, path: c.path })));
+          if (!resolved) {
+            resolved = true;
+            resolve();
+          }
+        });
+      });
+
+      // Add file
+      fs.writeFileSync(testFile, "content");
+
+      // Delete file with short interval
+      await wait(50);
+      fs.unlinkSync(testFile);
+
+      // Wait with timeout (event may not occur)
+      await Promise.race([changesPromise, wait(DELAY + 200)]);
+
+      // add → unlink merged, no events
+      expect(changes.length).toBe(0);
+    });
+
+    it("produces no events or no changes when directory is added then deleted", async () => {
+      const testSubDir = path.join(testDir, "test-addDir-unlinkDir");
+
+      watcher = await FsWatcher.watch([testDir]);
+
+      const changes: Array<{ event: string; path: string }> = [];
+      let resolved = false;
+
+      const changesPromise = new Promise<void>((resolve) => {
+        watcher!.onChange({ delay: DELAY }, (changeInfos) => {
+          changes.push(...changeInfos.map((c) => ({ event: c.event, path: c.path })));
+          if (!resolved) {
+            resolved = true;
+            resolve();
+          }
+        });
+      });
+
+      // Add directory
+      fs.mkdirSync(testSubDir);
+
+      // Delete directory with short interval
+      await wait(50);
+      fs.rmdirSync(testSubDir);
+
+      // Wait with timeout (event may not occur)
+      await Promise.race([changesPromise, wait(DELAY + 200)]);
+
+      // addDir → unlinkDir merged, no events
+      expect(changes.length).toBe(0);
+    });
+
+    it("merges to add event when file is deleted then recreated", async () => {
+      const testFile = path.join(testDir, "test-unlink-add.txt");
+
+      // Pre-create file
+      fs.writeFileSync(testFile, "initial");
+
+      watcher = await FsWatcher.watch([testDir]);
+
+      const changesPromise = waitForChanges(watcher, DELAY);
+
+      // Delete file
+      fs.unlinkSync(testFile);
+
+      // Recreate file with short interval (must occur within delay)
+      await wait(50);
+      fs.writeFileSync(testFile, "recreated");
+
+      // Wait for event callback
+      const changes = await changesPromise;
+
+      // unlink → add/change should be merged to add (overwritten by later event)
+      // Depending on environment, chokidar may only emit change without unlink (WSL2, etc)
+      expect(changes.length).toBe(1);
+      expect(["add", "change"]).toContain(changes[0].event);
+    });
+
+    it("correctly merges events when multiple files are modified", async () => {
+      const file1 = path.join(testDir, "file1.txt");
+      const file2 = path.join(testDir, "file2.txt");
+      const file3 = path.join(testDir, "file3.txt");
+
+      // Pre-create file3 (to trigger change event)
+      fs.writeFileSync(file3, "existing");
+
+      watcher = await FsWatcher.watch([testDir]);
+
+      const changesPromise = waitForChanges(watcher, DELAY);
+
+      // file1: only add
+      fs.writeFileSync(file1, "content1");
+
+      // file2: add then delete (merged and removed)
+      await wait(50);
+      fs.writeFileSync(file2, "content2");
+      await wait(50);
+      fs.unlinkSync(file2);
+
+      // file3: modify
+      await wait(50);
+      fs.writeFileSync(file3, "modified");
+
+      // Wait for event callback
+      const changes = await changesPromise;
+
+      // file1: add, file2: removed by merge, file3: change
+      expect(changes.length).toBe(2);
+
+      const file1Change = changes.find((c) => c.path.endsWith("file1.txt"));
+      const file3Change = changes.find((c) => c.path.endsWith("file3.txt"));
+
+      expect(file1Change?.event).toBe("add");
+      expect(file3Change?.event).toBe("change");
+    });
+  });
+
+  //#endregion
+});