@simplysm/core-node 13.0.100 → 14.0.4

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": "AAAA,SAAS,cAAc,UAAU,YAAY;AAC7C,OAAO,aAAa;AACpB,OAAO,UAAU;AACjB,SAAS,qBAAqB;AAE9B,SAAS,UAAU,iBAAiB;AAGpC,MAAM,SAAS,QAAQ,QAAQ,WAAW;AAW1C,MAAM,uBAAuB,aAAsC;AAAA,EAChD;AAAA,EACT,gBAAgB;AAAA,EACP,mBAAmB,oBAAI,IAGtC;AAAA,EAEF,YAAY,UAAkB,KAAmD;AAC/E,UAAM;AAEN,UAAM,MAAM,KAAK,QAAQ,YAAY,QAAQ;AAG7C,UAAM,SAAS,KAAK,OAAO,QAAQ,OAAO,IAAI,QAAQ,WAAW,IAAI,MAAM,CAAC;AAI5E,QAAI,QAAQ,OAAO;AAEjB,YAAM,aAAa,SAAS,WAAW,SAAS,IAAI,cAAc,QAAQ,IAAI;AAC9E,WAAK,UAAU,IAAI;AAAA,QACjB,KAAK,QAAQ,YAAY,SAAS,+BAA+B;AAAA,QACjE;AAAA,UACE,QAAQ;AAAA,UACR,QAAQ;AAAA,UACR,GAAG;AAAA,UACH,KAAK;AAAA,YACH,GAAG,QAAQ;AAAA,YACX,GAAG;AAAA,UACL;AAAA,UACA,MAAM,CAAC,YAAY,GAAI,KAAK,QAAQ,CAAC,CAAE;AAAA,QACzC;AAAA,MACF;AAAA,IACF,OAAO;AAGL,YAAM,aAAa,SAAS,WAAW,SAAS,IAAI,cAAc,QAAQ,IAAI;AAC9E,WAAK,UAAU,IAAI,UAAU,YAAY;AAAA,QACvC,QAAQ;AAAA,QACR,QAAQ;AAAA,QACR,GAAG;AAAA,QACH,KAAK;AAAA,UACH,GAAG,QAAQ;AAAA,UACX,GAAG;AAAA,QACL;AAAA,MACF,CAAC;AAAA,IACH;AAGA,SAAK,QAAQ,OAAO,KAAK,QAAQ,MAAM;AACvC,SAAK,QAAQ,OAAO,KAAK,QAAQ,MAAM;AAEvC,SAAK,QAAQ,GAAG,QAAQ,CAAC,SAAS;AAChC,UAAI,CAAC,KAAK,iBAAiB,SAAS,GAAG;AACrC,eAAO,MAAM,yBAAyB,IAAI,GAAG;AAE7C,aAAK,kBAAkB,IAAI,MAAM,yBAAyB,IAAI,GAAG,CAAC;AAAA,MACpE;AAAA,IACF,CAAC;AAED,SAAK,QAAQ,GAAG,SAAS,CAAC,QAAQ;AAChC,aAAO,MAAM,iBAAiB,GAAG;AAEjC,WAAK,kBAAkB,GAAG;AAAA,IAC5B,CAAC;AAED,SAAK,QAAQ,GAAG,WAAW,CAAC,uBAAgC;AAC1D,YAAM,UAAU,SAAS,OAAO,kBAAkB;AAGlD,UAAI,WAAW,QAAQ,OAAO,YAAY,YAAY,EAAE,UAAU,UAAU;AAC1E,eAAO,KAAK,wCAAwC,OAAO;AAC3D;AAAA,MACF;AACA,YAAM,WAAW;AAEjB,UAAI,SAAS,SAAS,SAAS;AAC7B,aAAK,KAAK,SAAS,OAAO,SAAS,IAAI;AAAA,MACzC,WAAW,SAAS,SAAS,OAAO;AAClC,gBAAQ,OAAO,MAAM,SAAS,IAAI;AAAA,MACpC,WAAW,SAAS,SAAS,UAAU;AACrC,cAAM,UAAU,KAAK,iBAAiB,IAAI,SAAS,QAAQ,EAAE;AAC7D,YAAI,SAAS;AACX,eAAK,iBAAiB,OAAO,SAAS,QAAQ,EAAE;AAChD,kBAAQ,QAAQ,SAAS,IAAI;AAAA,QAC/B;AAAA,MACF,OAAO;AAEL,cAAM,UAAU,KAAK,iBAAiB,IAAI,SAAS,QAAQ,EAAE;AAC7D,YAAI,SAAS;AACX,eAAK,iBAAiB,OAAO,SAAS,QAAQ,EAAE;AAChD,kBAAQ,OAAO,SAAS,IAAI;AAAA,QAC9B;AAAA,MACF;AAAA,IACF,CAAC;AAAA,EACH;AAAA;AAAA;AAAA;AAAA,EAKQ,kBAAkB,KAAkB;AAC1C,eAAW,CAAC,KAAK,EAAE,QAAQ,OAAO,CAAC,KAAK,KAAK,kBAAkB;AAC7D,aAAO,IAAI,MAAM,GAAG,IAAI,OAAO,aAAa,MAAM,GAAG,CAAC;AAAA,IACxD;AACA,SAAK,iBAAiB,MAAM;AAAA,EAC9B;AAAA;AAAA;AAAA;AAAA,EAKA,KAAK,QAAgB,QAAqC;AACxD,WAAO,IAAI,QAAQ,CAAC,SAAS,WAAW;AACtC,YAAM,UAAyB;AAAA,QAC7B,IAAI,KAAK,SAAS,EAAE,SAAS;AAAA,QAC7B;AAAA,QACA;AAAA,MACF;AAEA,WAAK,iBAAiB,IAAI,QAAQ,IAAI,EAAE,QAAQ,SAAS,OAAO,CAAC;AAEjE,YAAM,aAAa,SAAS,OAAO,OAAO;AAC1C,WAAK,QAAQ,YAAY,WAAW,QAAQ,WAAW,YAAY;AAAA,IACrE,CAAC;AAAA,EACH;AAAA;AAAA;AAAA;AAAA,EAKA,MAAM,YAA2B;AAC/B,SAAK,gBAAgB;AACrB,SAAK,kBAAkB,IAAI,MAAM,mBAAmB,CAAC;AACrD,UAAM,KAAK,QAAQ,UAAU;AAAA,EAC/B;AACF;AAoBO,MAAM,SAAS;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQpB,OACE,UACA,KACsB;AACtB,UAAM,WAAW,IAAI,eAAe,UAAU,GAAG;AAEjD,WAAO,IAAI,MAAM,CAAC,GAA2B;AAAA,MAC3C,IAAI,SAAS,MAAc;AAEzB,YAAI,SAAS,MAAM;AACjB,iBAAO,CAAC,OAAe,aAAsC;AAC3D,qBAAS,GAAG,OAAO,QAAQ;AAAA,UAC7B;AAAA,QACF;AACA,YAAI,SAAS,OAAO;AAClB,iBAAO,CAAC,OAAe,aAAsC;AAC3D,qBAAS,IAAI,OAAO,QAAQ;AAAA,UAC9B;AAAA,QACF;AACA,YAAI,SAAS,aAAa;AACxB,iBAAO,MAAM,SAAS,UAAU;AAAA,QAClC;AAGA,eAAO,IAAI,SAAoB,SAAS,KAAK,MAAM,IAAI;AAAA,MACzD;AAAA,IACF,CAAC;AAAA,EACH;AACF;",
-  "names": []
-}
+{"version":3,"file":"worker.js","sourceRoot":"","sources":["..\\..\\src\\worker\\worker.ts"],"names":[],"mappings":"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"}

package/docs/fs-watcher.md

@@ -0,0 +1,107 @@
+# FsWatcher -- File System Watcher
+
+Chokidar-based file system watcher with debounced event delivery and glob filtering.
+
+```ts
+import { FsWatcher } from "@simplysm/core-node";
+import type { FsWatcherEvent, FsWatcherChangeInfo } from "@simplysm/core-node";
+```
+
+## Types
+
+### FsWatcherEvent
+
+```ts
+type FsWatcherEvent = "add" | "addDir" | "change" | "unlink" | "unlinkDir"
+```
+
+Supported file change event types.
+
+### FsWatcherChangeInfo (interface)
+
+```ts
+interface FsWatcherChangeInfo {
+  event: FsWatcherEvent;
+  path: NormPath;
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `event` | `FsWatcherEvent` | The type of change event |
+| `path` | `NormPath` | Normalized absolute path of the changed file/directory |
+
+## FsWatcher (class)
+
+Wraps chokidar to provide debounced file change notifications. Multiple events occurring within a short window are merged and delivered as a single batch.
+
+Event merging strategy:
+- `add` + `change` --> `add` (modification right after creation is treated as creation)
+- `add` + `unlink` --> removed (creation then deletion cancels out)
+- `unlink` + `add` --> `add` (deletion then recreation is treated as creation)
+- Other combinations --> latest event wins
+
+**Note:** `ignoreInitial` is always set to `true` internally. Passing `ignoreInitial: false` triggers an initial callback with an empty array, but does not include the initial file listing.
+
+### Static Methods
+
+#### FsWatcher.watch
+
+```ts
+static async watch(
+  paths: string[],
+  options?: chokidar.ChokidarOptions,
+): Promise<FsWatcher>
+```
+
+Start watching files/directories. Resolves when the watcher is ready.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `paths` | `string[]` | File paths, directory paths, or glob patterns to watch |
+| `options` | `chokidar.ChokidarOptions?` | Chokidar configuration options |
+
+Glob patterns in `paths` are automatically decomposed: the base directory is watched, and events are filtered by the glob pattern using minimatch.
+
+### Instance Methods
+
+#### onChange
+
+```ts
+onChange(
+  opt: { delay?: number },
+  cb: (changeInfos: FsWatcherChangeInfo[]) => void | Promise<void>,
+): this
+```
+
+Register a change event handler. Events are collected for the specified delay duration and delivered as a single batch.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `opt.delay` | `number?` | Debounce delay in milliseconds |
+| `cb` | `(changeInfos: FsWatcherChangeInfo[]) => void \| Promise<void>` | Callback receiving batched change events |
+
+Returns `this` for chaining.
+
+#### close
+
+```ts
+async close(): Promise<void>
+```
+
+Stop watching and clean up all debounce queues.
+
+## Usage
+
+```ts
+const watcher = await FsWatcher.watch(["src/**/*.ts"], { depth: 3 });
+
+watcher.onChange({ delay: 300 }, (changes) => {
+  for (const { path, event } of changes) {
+    console.log(`${event}: ${path}`);
+  }
+});
+
+// Later: stop watching
+await watcher.close();
+```