@simplysm/core-node 13.0.69 → 13.0.71

package/dist/worker/worker.js

@@ -43,18 +43,18 @@ class WorkerInternal extends EventEmitter {
     this._worker.stderr.pipe(process.stderr);
     this._worker.on("exit", (code) => {
       if (!this._isTerminated && code !== 0) {
-        logger.error(`\uC6CC\uCEE4\uAC00 \uC624\uB958\uC640 \uD568\uAED8 \uB2EB\uD798 (code: ${code})`);
-        this._rejectAllPending(new Error(`\uC6CC\uCEE4\uAC00 \uBE44\uC815\uC0C1 \uC885\uB8CC\uB428 (code: ${code})`));
+        logger.error(`Worker crashed (code: ${code})`);
+        this._rejectAllPending(new Error(`Worker crashed (code: ${code})`));
       }
     });
     this._worker.on("error", (err) => {
-      logger.error("\uC6CC\uCEE4 \uC624\uB958:", err);
+      logger.error("Worker error:", err);
       this._rejectAllPending(err);
     });
     this._worker.on("message", (serializedResponse) => {
       const decoded = transferableDecode(serializedResponse);
       if (decoded == null || typeof decoded !== "object" || !("type" in decoded)) {
-        logger.warn("\uC6CC\uCEE4\uC5D0\uC11C \uC798\uBABB\uB41C \uD615\uC2DD\uC758 \uC751\uB2F5:", decoded);
+        logger.warn("Invalid response format from worker:", decoded);
         return;
       }
       const response = decoded;
@@ -78,7 +78,7 @@ class WorkerInternal extends EventEmitter {
     });
   }
   /**
-   * 대기 중인 모든 요청을 reject합니다.
+   * Rejects all pending requests.
    */
   _rejectAllPending(err) {
     for (const [_id, { method, reject }] of this._pendingRequests) {
@@ -87,7 +87,7 @@ class WorkerInternal extends EventEmitter {
     this._pendingRequests.clear();
   }
   /**
-   * 워커 메서드 호출.
+   * Calls a worker method.
    */
   call(method, params) {
     return new Promise((resolve, reject) => {
@@ -102,21 +102,21 @@ class WorkerInternal extends EventEmitter {
     });
   }
   /**
-   * 워커 종료.
+   * Terminates the worker.
    */
   async terminate() {
     this._isTerminated = true;
-    this._rejectAllPending(new Error("\uC6CC\uCEE4\uAC00 \uC885\uB8CC\uB428"));
+    this._rejectAllPending(new Error("Worker terminated"));
     await this._worker.terminate();
   }
 }
 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(filePath, opt) {
     const internal = new WorkerInternal(filePath, opt);

package/dist/worker/worker.js.map

@@ -1,6 +1,6 @@
 {
   "version": 3,
   "sources": ["../../src/worker/worker.ts"],
-  "mappings": "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",
+  "mappings": "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",
   "names": []
 }

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@simplysm/core-node",
-  "version": "13.0.69",
-  "description": "심플리즘 패키지 - 코어 모듈 (node)",
-  "author": "김석래",
+  "version": "13.0.71",
+  "description": "Simplysm package - Core module (node)",
+  "author": "simplysm",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -14,7 +14,8 @@
   "types": "./dist/index.d.ts",
   "files": [
     "dist",
-    "src"
+    "src",
+    "tests"
   ],
   "sideEffects": false,
   "dependencies": {
@@ -23,6 +24,6 @@
     "glob": "^13.0.6",
     "minimatch": "^10.2.2",
     "tsx": "^4.21.0",
-    "@simplysm/core-common": "13.0.69"
+    "@simplysm/core-common": "13.0.71"
   }
 }

package/src/features/fs-watcher.ts

@@ -8,11 +8,11 @@ import { type NormPath, pathNorm } from "../utils/path";
 
 //#region Helpers
 
-/** glob 메타문자 패턴 */
+/** Glob metacharacter pattern */
 const GLOB_CHARS_RE = /[*?{[\]]/;
 
 /**
- * glob 패턴에서 base 디렉토리 추출.
+ * Extracts the base directory from a glob pattern.
  * @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 기반 파일 시스템 감시 래퍼.
- * 짧은 시간 내 발생한 이벤트를 병합하여 콜백 호출.
+ * Chokidar-based file system watcher wrapper.
+ * Merges events that occur within a short time and calls the callback once.
  *
- * **주의**: chokidar의 `ignoreInitial` 옵션은 내부적으로 항상 `true`로 설정된다.
- * `options.ignoreInitial: false`를 전달하면 `onChange` 첫 호출 시 빈 배열로
- * 콜백이 호출되지만, 실제 초기 파일 목록은 포함되지 않는다.
- * 이는 이벤트 병합 로직과의 충돌을 방지하기 위한 의도된 동작이다.
+ * **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.
  *
  * @example
  * const watcher = await FsWatcher.watch(["src/**\/*.ts"]);
@@ -70,16 +70,16 @@ export interface FsWatcherChangeInfo {
  *   }
  * });
  *
- * // 종료
+ * // Close
  * await watcher.close();
  */
 export class FsWatcher {
   /**
-   * 파일 감시 시작 (비동기).
-   * ready 이벤트가 발생할 때까지 대기.
+   * Starts watching files (asynchronous).
+   * Waits until the ready event is emitted.
    *
-   * @param paths - 감시할 파일/디렉토리 경로 또는 glob 패턴 배열
-   * @param options - chokidar 옵션
+   * @param paths - Array of file/directory paths or glob patterns to watch
+   * @param options - chokidar options
    */
   static async watch(paths: string[], options?: chokidar.ChokidarOptions): Promise<FsWatcher> {
     return new Promise<FsWatcher>((resolve, reject) => {
@@ -111,7 +111,7 @@ export class FsWatcher {
       }
     }
 
-    // 중복 경로 제거
+    // Remove duplicate paths
     const uniquePaths = [...new Set(watchPaths)];
 
     this._watcher = chokidar.watch(uniquePaths, {
@@ -121,18 +121,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);
     });
   }
 
   /**
-   * 파일 변경 이벤트 핸들러 등록.
-   * 지정된 delay 시간 동안 이벤트를 모아서 한 번에 콜백 호출.
+   * Registers a file change event handler.
+   * Collects events for the specified delay time and calls the callback once.
    *
-   * @param opt.delay - 이벤트 병합 대기 시간 (ms)
-   * @param cb - 변경 이벤트 콜백
+   * @param opt.delay - Event merge wait time (ms)
+   * @param cb - Change event callback
    */
   onChange(
     opt: { delay?: number },
@@ -143,7 +143,7 @@ export class FsWatcher {
 
     let changeInfoMap = new Map<string, EventName>();
 
-    // ignoreInitial이 false면 초기에 빈 배열로 콜백 호출
+    // If ignoreInitial is false, call callback with empty array initially
     if (!this._ignoreInitial) {
       fnQ.run(async () => {
         await cb([]);
@@ -151,22 +151,22 @@ export class FsWatcher {
     }
 
     this._watcher.on("all", (event, filePath) => {
-      // 지원하는 이벤트만 처리
+      // Only process supported events
       if (!FS_WATCHER_EVENTS.includes(event as FsWatcherEvent)) return;
 
-      // glob 매처가 있으면 패턴 필터링 적용
+      // If glob matchers exist, apply pattern filtering
       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 (삭제 후 재생성은 생성으로 간주)
-       * - 그 외 → 최신 이벤트로 덮어씀
+       * 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
        */
       if (!changeInfoMap.has(filePath)) {
         changeInfoMap.set(filePath, event);
@@ -174,19 +174,19 @@ export class FsWatcher {
       const prevEvent = changeInfoMap.get(filePath)!;
 
       if (prevEvent === "add" && event === "change") {
-        // add 후 change → add 유지
+        // add followed by change → keep add
         changeInfoMap.set(filePath, "add");
       } else if (
         (prevEvent === "add" && event === "unlink") ||
         (prevEvent === "addDir" && event === "unlinkDir")
       ) {
-        // add 후 unlink → 변경 없음 (삭제)
+        // add followed by unlink → no change (deletion)
         changeInfoMap.delete(filePath);
       } else if (prevEvent === "unlink" && (event === "add" || event === "change")) {
-        // unlink 후 add/change → add (파일 재생성)
+        // unlink followed by add/change → add (file recreation)
         changeInfoMap.set(filePath, "add");
       } else if (prevEvent === "unlinkDir" && event === "addDir") {
-        // unlinkDir 후 addDir → addDir (디렉토리 재생성)
+        // unlinkDir followed by addDir → addDir (directory recreation)
         changeInfoMap.set(filePath, "addDir");
       } else {
         changeInfoMap.set(filePath, event);
@@ -213,7 +213,7 @@ export class FsWatcher {
   }
 
   /**
-   * 파일 감시 종료.
+   * Closes the file watcher.
    */
   async close(): Promise<void> {
     for (const q of this._debounceQueues) {