@simplysm/core-node 13.0.100 → 14.0.1

package/dist/worker/worker.d.ts

@@ -1,7 +1,7 @@
 import type { WorkerOptions as WorkerRawOptions } from "worker_threads";
 import type { WorkerModule, WorkerProxy } from "./types";
 /**
- * Type-safe Worker wrapper.
+ * 타입 안전한 Worker 래퍼.
  *
  * @example
  * // worker.ts
@@ -16,11 +16,11 @@ import type { WorkerModule, WorkerProxy } from "./types";
  */
 export declare const Worker: {
     /**
-     * Creates a type-safe Worker Proxy.
+     * 타입 안전한 Worker Proxy를 생성한다.
      *
-     * @param filePath - Worker file path (file:// URL or absolute path)
-     * @param opt - Worker options
-     * @returns Proxy object (supports direct method calls, on(), and terminate())
+     * @param filePath - 워커 파일 경로 (file:// URL 또는 절대 경로)
+     * @param opt - 워커 옵션
+     * @returns Proxy 객체 (메서드 직접 호출, on(), terminate() 지원)
      */
     create<TModule extends WorkerModule>(filePath: string, opt?: Omit<WorkerRawOptions, "stdout" | "stderr">): WorkerProxy<TModule>;
 };

package/dist/worker/worker.js

@@ -4,143 +4,179 @@ import path from "path";
 import { fileURLToPath } from "url";
 import { Worker as WorkerRaw } from "worker_threads";
 const logger = consola.withTag("sd-worker");
+//#region WorkerInternal
+/**
+ * Worker의 내부 구현 클래스.
+ * Proxy를 통해 외부에 노출된다.
+ *
+ * 개발 환경(.ts 파일)에서는 TypeScript 워커 파일을 tsx를 통해 실행한다.
+ * 프로덕션 환경(.js 파일)에서는 Worker를 직접 생성한다.
+ */
 class WorkerInternal extends EventEmitter {
-  _worker;
-  _isTerminated = false;
-  _pendingRequests = /* @__PURE__ */ new Map();
-  constructor(filePath, opt) {
-    super();
-    const ext = path.extname(import.meta.filename);
-    const envObj = opt?.env != null && typeof opt.env === "object" ? opt.env : {};
-    if (ext === ".ts") {
-      const workerPath = filePath.startsWith("file://") ? fileURLToPath(filePath) : filePath;
-      this._worker = new WorkerRaw(
-        path.resolve(import.meta.dirname, "../../lib/worker-dev-proxy.js"),
-        {
-          stdout: true,
-          stderr: true,
-          ...opt,
-          env: {
-            ...process.env,
-            ...envObj
-          },
-          argv: [workerPath, ...opt?.argv ?? []]
+    _worker;
+    _isTerminated = false;
+    _pendingRequests = new Map();
+    constructor(filePath, opt) {
+        super();
+        const ext = path.extname(import.meta.filename);
+        // 타입 가드를 통해 env 객체 추출
+        const envObj = opt?.env != null && typeof opt.env === "object" ? opt.env : {};
+        // 개발 환경(.ts 파일)에서는 tsx를 통해 실행
+        // worker-dev-proxy.js: tsx를 통해 TypeScript 워커 파일을 동적으로 로드하는 프록시
+        if (ext === ".ts") {
+            // file:// URL이면 절대 경로로 변환 (worker-dev-proxy.js가 다시 pathToFileURL을 적용)
+            const workerPath = filePath.startsWith("file://") ? fileURLToPath(filePath) : filePath;
+            this._worker = new WorkerRaw(path.resolve(import.meta.dirname, "../../lib/worker-dev-proxy.js"), {
+                stdout: true,
+                stderr: true,
+                ...opt,
+                env: {
+                    ...process.env,
+                    ...envObj,
+                },
+                argv: [workerPath, ...(opt?.argv ?? [])],
+            });
         }
-      );
-    } else {
-      const workerPath = filePath.startsWith("file://") ? fileURLToPath(filePath) : filePath;
-      this._worker = new WorkerRaw(workerPath, {
-        stdout: true,
-        stderr: true,
-        ...opt,
-        env: {
-          ...process.env,
-          ...envObj
+        else {
+            // 프로덕션 환경 (.js 파일)
+            // file:// URL이면 변환; 그렇지 않으면 절대 경로를 그대로 사용
+            const workerPath = filePath.startsWith("file://") ? fileURLToPath(filePath) : filePath;
+            this._worker = new WorkerRaw(workerPath, {
+                stdout: true,
+                stderr: true,
+                ...opt,
+                env: {
+                    ...process.env,
+                    ...envObj,
+                },
+            });
         }
-      });
+        // 워커의 stdout/stderr를 메인 프로세스로 파이프
+        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})`);
+                // 비정상 종료 시 대기 중인 모든 요청을 거부
+                this._rejectAllPending(new Error(`워커가 비정상 종료되었습니다 (코드: ${code})`));
+            }
+        });
+        this._worker.on("error", (err) => {
+            logger.error("워커 오류:", err);
+            // 워커 오류 시 대기 중인 모든 요청을 거부
+            this._rejectAllPending(err);
+        });
+        this._worker.on("message", (serializedResponse) => {
+            const decoded = transfer.decode(serializedResponse);
+            // 응답 구조 검증
+            if (decoded == null || typeof decoded !== "object" || !("type" in decoded)) {
+                logger.warn("워커로부터 잘못된 응답 형식:", decoded);
+                return;
+            }
+            const response = decoded;
+            if (response.type === "event") {
+                this.emit(response.event, response.body);
+            }
+            else if (response.type === "log") {
+                process.stdout.write(response.body);
+            }
+            else if (response.type === "return") {
+                const pending = this._pendingRequests.get(response.request.id);
+                if (pending) {
+                    this._pendingRequests.delete(response.request.id);
+                    pending.resolve(response.body);
+                }
+            }
+            else {
+                // response.type === "error"
+                const pending = this._pendingRequests.get(response.request.id);
+                if (pending) {
+                    this._pendingRequests.delete(response.request.id);
+                    pending.reject(response.body);
+                }
+            }
+        });
     }
-    this._worker.stdout.pipe(process.stdout);
-    this._worker.stderr.pipe(process.stderr);
-    this._worker.on("exit", (code) => {
-      if (!this._isTerminated && code !== 0) {
-        logger.error(`Worker crashed (code: ${code})`);
-        this._rejectAllPending(new Error(`Worker crashed (code: ${code})`));
-      }
-    });
-    this._worker.on("error", (err) => {
-      logger.error("Worker error:", err);
-      this._rejectAllPending(err);
-    });
-    this._worker.on("message", (serializedResponse) => {
-      const decoded = transfer.decode(serializedResponse);
-      if (decoded == null || typeof decoded !== "object" || !("type" in decoded)) {
-        logger.warn("Invalid response format from worker:", decoded);
-        return;
-      }
-      const response = decoded;
-      if (response.type === "event") {
-        this.emit(response.event, response.body);
-      } else if (response.type === "log") {
-        process.stdout.write(response.body);
-      } else if (response.type === "return") {
-        const pending = this._pendingRequests.get(response.request.id);
-        if (pending) {
-          this._pendingRequests.delete(response.request.id);
-          pending.resolve(response.body);
+    /**
+     * 대기 중인 모든 요청을 거부한다.
+     */
+    _rejectAllPending(err) {
+        for (const [_id, { method, reject }] of this._pendingRequests) {
+            reject(new Error(`${err.message} (method: ${method})`));
         }
-      } else {
-        const pending = this._pendingRequests.get(response.request.id);
-        if (pending) {
-          this._pendingRequests.delete(response.request.id);
-          pending.reject(response.body);
-        }
-      }
-    });
-  }
-  /**
-   * Rejects all pending requests.
-   */
-  _rejectAllPending(err) {
-    for (const [_id, { method, reject }] of this._pendingRequests) {
-      reject(new Error(`${err.message} (method: ${method})`));
+        this._pendingRequests.clear();
+    }
+    /**
+     * 워커 메서드를 호출한다.
+     */
+    call(method, params) {
+        return new Promise((resolve, reject) => {
+            const request = {
+                id: Uuid.generate().toString(),
+                method,
+                params,
+            };
+            this._pendingRequests.set(request.id, { method, resolve, reject });
+            const serialized = transfer.encode(request);
+            this._worker.postMessage(serialized.result, serialized.transferList);
+        });
+    }
+    /**
+     * 워커를 종료한다.
+     */
+    async terminate() {
+        this._isTerminated = true;
+        this._rejectAllPending(new Error("워커가 종료되었습니다"));
+        await this._worker.terminate();
     }
-    this._pendingRequests.clear();
-  }
-  /**
-   * Calls a worker method.
-   */
-  call(method, params) {
-    return new Promise((resolve, reject) => {
-      const request = {
-        id: Uuid.generate().toString(),
-        method,
-        params
-      };
-      this._pendingRequests.set(request.id, { method, resolve, reject });
-      const serialized = transfer.encode(request);
-      this._worker.postMessage(serialized.result, serialized.transferList);
-    });
-  }
-  /**
-   * Terminates the worker.
-   */
-  async terminate() {
-    this._isTerminated = true;
-    this._rejectAllPending(new Error("Worker terminated"));
-    await this._worker.terminate();
-  }
 }
-const Worker = {
-  /**
-   * Creates a type-safe Worker Proxy.
-   *
-   * @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);
-    return new Proxy({}, {
-      get(_target, prop) {
-        if (prop === "on") {
-          return (event, listener) => {
-            internal.on(event, listener);
-          };
-        }
-        if (prop === "off") {
-          return (event, listener) => {
-            internal.off(event, listener);
-          };
-        }
-        if (prop === "terminate") {
-          return () => internal.terminate();
-        }
-        return (...args) => internal.call(prop, args);
-      }
-    });
-  }
-};
-export {
-  Worker
+//#endregion
+//#region Worker
+/**
+ * 타입 안전한 Worker 래퍼.
+ *
+ * @example
+ * // worker.ts
+ * export default createWorker({
+ *   add: (a: number, b: number) => a + b,
+ * });
+ *
+ * // main.ts
+ * const worker = Worker.create<typeof import("./worker.js")>("./worker.ts");
+ * const result = await worker.add(10, 20);  // 30
+ * await worker.terminate();
+ */
+export const Worker = {
+    /**
+     * 타입 안전한 Worker Proxy를 생성한다.
+     *
+     * @param filePath - 워커 파일 경로 (file:// URL 또는 절대 경로)
+     * @param opt - 워커 옵션
+     * @returns Proxy 객체 (메서드 직접 호출, on(), terminate() 지원)
+     */
+    create(filePath, opt) {
+        const internal = new WorkerInternal(filePath, opt);
+        return new Proxy({}, {
+            get(_target, prop) {
+                // 예약된 메서드: on, off, terminate
+                if (prop === "on") {
+                    return (event, listener) => {
+                        internal.on(event, listener);
+                    };
+                }
+                if (prop === "off") {
+                    return (event, listener) => {
+                        internal.off(event, listener);
+                    };
+                }
+                if (prop === "terminate") {
+                    return () => internal.terminate();
+                }
+                // 그 외의 경우 워커 메서드로 처리
+                return (...args) => internal.call(prop, args);
+            },
+        });
+    },
 };
-//# sourceMappingURL=worker.js.map
+//#endregion
+//# sourceMappingURL=worker.js.map

package/dist/worker/worker.js.map

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

package/lib/worker-dev-proxy.js

@@ -0,0 +1,15 @@
+import process from "node:process";
+import { tsImport } from "tsx/esm/api";
+import { pathToFileURL } from "node:url";
+
+// Assume argv[2] contains the actual worker file path
+const workerFile = process.argv[2];
+if (!workerFile) {
+  throw new Error("Worker file path is required as argument!");
+}
+
+// If file:// URL is already passed, use it as-is; otherwise convert
+const workerFileUrl = workerFile.startsWith("file://")
+  ? workerFile
+  : pathToFileURL(workerFile).href;
+await tsImport(workerFileUrl, import.meta.url);

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.1",
+  "description": "심플리즘 패키지 - 코어 (node)",
+  "author": "심플리즘",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -14,9 +14,8 @@
   "types": "./dist/index.d.ts",
   "files": [
     "dist",
-    "docs",
     "src",
-    "tests"
+    "lib"
   ],
   "sideEffects": false,
   "dependencies": {
@@ -25,6 +24,9 @@
     "glob": "^13.0.6",
     "minimatch": "^10.2.4",
     "tsx": "^4.21.0",
-    "@simplysm/core-common": "13.0.100"
+    "@simplysm/core-common": "14.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.8"
   }
 }

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";