@simplysm/core-node 13.0.0-beta.1

package/dist/worker/create-worker.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/worker/create-worker.ts"],
+  "sourcesContent": ["import { parentPort } from \"worker_threads\";\nimport { SdError, transferableDecode, transferableEncode } from \"@simplysm/core-common\";\nimport type { WorkerRequest, WorkerResponse } from \"./types\";\n\n//#region createSdWorker\n\n/**\n * \uC6CC\uCEE4 \uC2A4\uB808\uB4DC\uC5D0\uC11C \uC0AC\uC6A9\uD560 \uC6CC\uCEE4 \uD329\uD1A0\uB9AC.\n *\n * @example\n * // \uC774\uBCA4\uD2B8 \uC5C6\uB294 \uC6CC\uCEE4\n * export default createWorker({\n *   add: (a: number, b: number) => a + b,\n * });\n *\n * // \uC774\uBCA4\uD2B8 \uC788\uB294 \uC6CC\uCEE4\n * interface MyEvents { progress: number; }\n * const methods = {\n *   calc: (x: number) => { sender.send(\"progress\", 50); return x * 2; },\n * };\n * const sender = createWorker<typeof methods, MyEvents>(methods);\n * export default sender;\n */\nexport function createWorker<\n  TMethods extends Record<string, (...args: any[]) => unknown>,\n  TEvents extends Record<string, unknown> = Record<string, never>,\n>(\n  methods: TMethods,\n): {\n  send<K extends keyof TEvents & string>(event: K, data?: TEvents[K]): void;\n  __methods: TMethods;\n  __events: TEvents;\n} {\n  if (parentPort === null) {\n    throw new SdError(\"\uC774 \uC2A4\uD06C\uB9BD\uD2B8\uB294 \uC6CC\uCEE4 \uC2A4\uB808\uB4DC\uC5D0\uC11C \uC2E4\uD589\uB418\uC5B4\uC57C \uD569\uB2C8\uB2E4 (parentPort \uD544\uC694).\");\n  }\n\n  const port = parentPort;\n\n  // Worker \uC2A4\uB808\uB4DC\uC758 stdout\uC740 \uBA54\uC778 \uC2A4\uB808\uB4DC\uB85C \uC790\uB3D9 \uC804\uB2EC\uB418\uC9C0 \uC54A\uC74C\n  // stdout.write\uB97C \uAC00\uB85C\uCC44\uC11C \uBA54\uC2DC\uC9C0 \uD504\uB85C\uD1A0\uCF5C\uC744 \uD1B5\uD574 \uBA54\uC778 \uC2A4\uB808\uB4DC\uB85C \uC804\uB2EC\n  process.stdout.write = (\n    chunk: string | Uint8Array,\n    encodingOrCallback?: BufferEncoding | ((err?: Error) => void),\n    callback?: (err?: Error) => void,\n  ): boolean => {\n    const body = typeof chunk === \"string\" ? chunk : new TextDecoder().decode(chunk);\n    const response: WorkerResponse = { type: \"log\", body };\n    const serialized = transferableEncode(response);\n    port.postMessage(serialized.result, serialized.transferList);\n\n    const cb = typeof encodingOrCallback === \"function\" ? encodingOrCallback : callback;\n    if (cb) {\n      queueMicrotask(() => cb());\n    }\n\n    return true;\n  };\n\n  port.on(\"message\", async (serializedRequest: unknown) => {\n    const decoded = transferableDecode(serializedRequest);\n\n    // \uC694\uCCAD \uAD6C\uC870 \uAC80\uC99D\n    if (\n      decoded == null ||\n      typeof decoded !== \"object\" ||\n      !(\"id\" in decoded) ||\n      !(\"method\" in decoded) ||\n      !(\"params\" in decoded)\n    ) {\n      let decodedStr: string;\n      try {\n        decodedStr = JSON.stringify(decoded);\n      } catch {\n        decodedStr = String(decoded);\n      }\n      const errorResponse: WorkerResponse = {\n        type: \"error\",\n        request: { id: \"unknown\", method: \"unknown\", params: [] },\n        body: new SdError(`\uD615\uC2DD\uC774 \uC798\uBABB\uB41C \uC6CC\uCEE4 \uC694\uCCAD: ${decodedStr}`),\n      };\n      const serialized = transferableEncode(errorResponse);\n      port.postMessage(serialized.result, serialized.transferList);\n      return;\n    }\n    const request = decoded as WorkerRequest;\n\n    const methodFn = methods[request.method] as ((...args: unknown[]) => unknown) | undefined;\n\n    if (methodFn == null) {\n      const response: WorkerResponse = {\n        request,\n        type: \"error\",\n        body: new SdError(`\uC54C \uC218 \uC5C6\uB294 \uBA54\uC11C\uB4DC: ${request.method}`),\n      };\n\n      const serialized = transferableEncode(response);\n      port.postMessage(serialized.result, serialized.transferList);\n      return;\n    }\n\n    try {\n      const result = await methodFn(...request.params);\n\n      const response: WorkerResponse = {\n        request,\n        type: \"return\",\n        body: result,\n      };\n\n      const serialized = transferableEncode(response);\n      port.postMessage(serialized.result, serialized.transferList);\n    } catch (err) {\n      const response: WorkerResponse = {\n        request,\n        type: \"error\",\n        body: err instanceof Error ? err : new Error(String(err)),\n      };\n\n      const serialized = transferableEncode(response);\n      port.postMessage(serialized.result, serialized.transferList);\n    }\n  });\n\n  return {\n    __methods: methods,\n    __events: {} as TEvents,\n    send<K extends keyof TEvents & string>(event: K, data?: TEvents[K]) {\n      const response: WorkerResponse = {\n        type: \"event\",\n        event,\n        body: data,\n      };\n\n      const serialized = transferableEncode(response);\n      port.postMessage(serialized.result, serialized.transferList);\n    },\n  };\n}\n\n//#endregion\n"],
+  "mappings": "AAAA,SAAS,kBAAkB;AAC3B,SAAS,SAAS,oBAAoB,0BAA0B;AAsBzD,SAAS,aAId,SAKA;AACA,MAAI,eAAe,MAAM;AACvB,UAAM,IAAI,QAAQ,gKAA6C;AAAA,EACjE;AAEA,QAAM,OAAO;AAIb,UAAQ,OAAO,QAAQ,CACrB,OACA,oBACA,aACY;AACZ,UAAM,OAAO,OAAO,UAAU,WAAW,QAAQ,IAAI,YAAY,EAAE,OAAO,KAAK;AAC/E,UAAM,WAA2B,EAAE,MAAM,OAAO,KAAK;AACrD,UAAM,aAAa,mBAAmB,QAAQ;AAC9C,SAAK,YAAY,WAAW,QAAQ,WAAW,YAAY;AAE3D,UAAM,KAAK,OAAO,uBAAuB,aAAa,qBAAqB;AAC3E,QAAI,IAAI;AACN,qBAAe,MAAM,GAAG,CAAC;AAAA,IAC3B;AAEA,WAAO;AAAA,EACT;AAEA,OAAK,GAAG,WAAW,OAAO,sBAA+B;AACvD,UAAM,UAAU,mBAAmB,iBAAiB;AAGpD,QACE,WAAW,QACX,OAAO,YAAY,YACnB,EAAE,QAAQ,YACV,EAAE,YAAY,YACd,EAAE,YAAY,UACd;AACA,UAAI;AACJ,UAAI;AACF,qBAAa,KAAK,UAAU,OAAO;AAAA,MACrC,QAAQ;AACN,qBAAa,OAAO,OAAO;AAAA,MAC7B;AACA,YAAM,gBAAgC;AAAA,QACpC,MAAM;AAAA,QACN,SAAS,EAAE,IAAI,WAAW,QAAQ,WAAW,QAAQ,CAAC,EAAE;AAAA,QACxD,MAAM,IAAI,QAAQ,oEAAkB,UAAU,EAAE;AAAA,MAClD;AACA,YAAM,aAAa,mBAAmB,aAAa;AACnD,WAAK,YAAY,WAAW,QAAQ,WAAW,YAAY;AAC3D;AAAA,IACF;AACA,UAAM,UAAU;AAEhB,UAAM,WAAW,QAAQ,QAAQ,MAAM;AAEvC,QAAI,YAAY,MAAM;AACpB,YAAM,WAA2B;AAAA,QAC/B;AAAA,QACA,MAAM;AAAA,QACN,MAAM,IAAI,QAAQ,kDAAe,QAAQ,MAAM,EAAE;AAAA,MACnD;AAEA,YAAM,aAAa,mBAAmB,QAAQ;AAC9C,WAAK,YAAY,WAAW,QAAQ,WAAW,YAAY;AAC3D;AAAA,IACF;AAEA,QAAI;AACF,YAAM,SAAS,MAAM,SAAS,GAAG,QAAQ,MAAM;AAE/C,YAAM,WAA2B;AAAA,QAC/B;AAAA,QACA,MAAM;AAAA,QACN,MAAM;AAAA,MACR;AAEA,YAAM,aAAa,mBAAmB,QAAQ;AAC9C,WAAK,YAAY,WAAW,QAAQ,WAAW,YAAY;AAAA,IAC7D,SAAS,KAAK;AACZ,YAAM,WAA2B;AAAA,QAC/B;AAAA,QACA,MAAM;AAAA,QACN,MAAM,eAAe,QAAQ,MAAM,IAAI,MAAM,OAAO,GAAG,CAAC;AAAA,MAC1D;AAEA,YAAM,aAAa,mBAAmB,QAAQ;AAC9C,WAAK,YAAY,WAAW,QAAQ,WAAW,YAAY;AAAA,IAC7D;AAAA,EACF,CAAC;AAED,SAAO;AAAA,IACL,WAAW;AAAA,IACX,UAAU,CAAC;AAAA,IACX,KAAuC,OAAU,MAAmB;AAClE,YAAM,WAA2B;AAAA,QAC/B,MAAM;AAAA,QACN;AAAA,QACA,MAAM;AAAA,MACR;AAEA,YAAM,aAAa,mBAAmB,QAAQ;AAC9C,WAAK,YAAY,WAAW,QAAQ,WAAW,YAAY;AAAA,IAC7D;AAAA,EACF;AACF;",
+  "names": []
+}

package/dist/worker/types.js

@@ -0,0 +1 @@
+//# sourceMappingURL=types.js.map

package/dist/worker/types.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": [],
+  "sourcesContent": [],
+  "mappings": "",
+  "names": []
+}

package/dist/worker/worker.js

@@ -0,0 +1,142 @@
+import { EventEmitter, transferableDecode, transferableEncode, Uuid } from "@simplysm/core-common";
+import { createConsola } from "consola";
+import path from "path";
+import { fileURLToPath } from "url";
+import { Worker as WorkerRaw } from "worker_threads";
+const logger = createConsola().withTag("sd-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") {
+      this._worker = new WorkerRaw(path.resolve(import.meta.dirname, "../../lib/worker-dev-proxy.js"), {
+        stdout: true,
+        stderr: true,
+        ...opt,
+        env: {
+          ...process.env,
+          ...envObj
+        },
+        argv: [filePath, ...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
+        }
+      });
+    }
+    this._worker.stdout.pipe(process.stdout);
+    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})`));
+      }
+    });
+    this._worker.on("error", (err) => {
+      logger.error("\uC6CC\uCEE4 \uC624\uB958:", 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);
+        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 {
+        const pending = this._pendingRequests.get(response.request.id);
+        if (pending) {
+          this._pendingRequests.delete(response.request.id);
+          pending.reject(response.body);
+        }
+      }
+    });
+  }
+  /**
+   * 대기 중인 모든 요청을 reject합니다.
+   */
+  _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.new().toString(),
+        method,
+        params
+      };
+      this._pendingRequests.set(request.id, { method, resolve, reject });
+      const serialized = transferableEncode(request);
+      this._worker.postMessage(serialized.result, serialized.transferList);
+    });
+  }
+  /**
+   * 워커 종료.
+   */
+  async terminate() {
+    this._isTerminated = true;
+    this._rejectAllPending(new Error("\uC6CC\uCEE4\uAC00 \uC885\uB8CC\uB428"));
+    await this._worker.terminate();
+  }
+}
+const Worker = {
+  /**
+   * 타입 안전한 Worker Proxy 생성.
+   *
+   * @param filePath - 워커 파일 경로 (file:// URL 또는 절대 경로)
+   * @param opt - Worker 옵션
+   * @returns Proxy 객체 (메서드 직접 호출, on(), 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
+};
+//# sourceMappingURL=worker.js.map

package/dist/worker/worker.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/worker/worker.ts"],
+  "sourcesContent": ["import { EventEmitter, transferableDecode, transferableEncode, Uuid } from \"@simplysm/core-common\";\nimport { createConsola } from \"consola\";\nimport path from \"path\";\nimport { fileURLToPath } from \"url\";\nimport type { WorkerOptions as WorkerRawOptions } from \"worker_threads\";\nimport { Worker as WorkerRaw } from \"worker_threads\";\nimport type { WorkerModule, WorkerProxy, WorkerRequest, WorkerResponse } from \"./types\";\n\nconst logger = createConsola().withTag(\"sd-worker\");\n\n//#region WorkerInternal\n\n/**\n * Worker \uB0B4\uBD80 \uAD6C\uD604 \uD074\uB798\uC2A4.\n * Proxy\uB97C \uD1B5\uD574 \uC678\uBD80\uC5D0 \uB178\uCD9C\uB428.\n *\n * \uAC1C\uBC1C \uD658\uACBD(.ts)\uC5D0\uC11C\uB294 tsx\uB97C \uD1B5\uD574 TypeScript \uC6CC\uCEE4 \uD30C\uC77C\uC744 \uC2E4\uD589\uD558\uACE0,\n * \uD504\uB85C\uB355\uC158 \uD658\uACBD(.js)\uC5D0\uC11C\uB294 \uC9C1\uC811 Worker\uB97C \uC0DD\uC131\uD55C\uB2E4.\n */\nclass WorkerInternal extends EventEmitter<Record<string, unknown>> {\n  private readonly _worker: WorkerRaw;\n  private _isTerminated = false;\n  private readonly _pendingRequests = new Map<\n    string,\n    { method: string; resolve: (value: unknown) => void; reject: (err: Error) => void }\n  >();\n\n  constructor(filePath: string, opt?: Omit<WorkerRawOptions, \"stdout\" | \"stderr\">) {\n    super();\n\n    const ext = path.extname(import.meta.filename);\n\n    // \uD0C0\uC785 \uAC00\uB4DC\uB97C \uD1B5\uD55C env \uAC1D\uCCB4 \uCD94\uCD9C\n    const envObj = opt?.env != null && typeof opt.env === \"object\" ? opt.env : {};\n\n    // \uAC1C\uBC1C \uD658\uACBD (.ts \uD30C\uC77C)\uC778 \uACBD\uC6B0 tsx\uB97C \uD1B5\uD574 \uC2E4\uD589\n    // worker-dev-proxy.js: tsx\uB85C TypeScript \uC6CC\uCEE4 \uD30C\uC77C\uC744 \uB3D9\uC801\uC73C\uB85C \uB85C\uB4DC\uD558\uB294 \uD504\uB85D\uC2DC\n    if (ext === \".ts\") {\n      this._worker = new WorkerRaw(path.resolve(import.meta.dirname, \"../../lib/worker-dev-proxy.js\"), {\n        stdout: true,\n        stderr: true,\n        ...opt,\n        env: {\n          ...process.env,\n          ...envObj,\n        },\n        argv: [filePath, ...(opt?.argv ?? [])],\n      });\n    } else {\n      // \uD504\uB85C\uB355\uC158 \uD658\uACBD (.js \uD30C\uC77C)\n      // file:// URL\uC778 \uACBD\uC6B0 \uBCC0\uD658, \uC774\uBBF8 \uC808\uB300 \uACBD\uB85C\uC778 \uACBD\uC6B0 \uADF8\uB300\uB85C \uC0AC\uC6A9\n      const workerPath = filePath.startsWith(\"file://\") ? fileURLToPath(filePath) : filePath;\n      this._worker = new WorkerRaw(workerPath, {\n        stdout: true,\n        stderr: true,\n        ...opt,\n        env: {\n          ...process.env,\n          ...envObj,\n        },\n      });\n    }\n\n    // \uC6CC\uCEE4\uC758 stdout/stderr\uB97C \uBA54\uC778\uC5D0 \uCD9C\uB825\n    this._worker.stdout.pipe(process.stdout);\n    this._worker.stderr.pipe(process.stderr);\n\n    this._worker.on(\"exit\", (code) => {\n      if (!this._isTerminated && code !== 0) {\n        logger.error(`\uC6CC\uCEE4\uAC00 \uC624\uB958\uC640 \uD568\uAED8 \uB2EB\uD798 (code: ${code})`);\n        // \uBE44\uC815\uC0C1 \uC885\uB8CC \uC2DC \uB300\uAE30 \uC911\uC778 \uBAA8\uB4E0 \uC694\uCCAD reject\n        this._rejectAllPending(new Error(`\uC6CC\uCEE4\uAC00 \uBE44\uC815\uC0C1 \uC885\uB8CC\uB428 (code: ${code})`));\n      }\n    });\n\n    this._worker.on(\"error\", (err) => {\n      logger.error(\"\uC6CC\uCEE4 \uC624\uB958:\", err);\n      // \uC6CC\uCEE4 \uC5D0\uB7EC \uC2DC \uB300\uAE30 \uC911\uC778 \uBAA8\uB4E0 \uC694\uCCAD reject\n      this._rejectAllPending(err);\n    });\n\n    this._worker.on(\"message\", (serializedResponse: unknown) => {\n      const decoded = transferableDecode(serializedResponse);\n\n      // \uC751\uB2F5 \uAD6C\uC870 \uAC80\uC99D\n      if (decoded == null || typeof decoded !== \"object\" || !(\"type\" in decoded)) {\n        logger.warn(\"\uC6CC\uCEE4\uC5D0\uC11C \uC798\uBABB\uB41C \uD615\uC2DD\uC758 \uC751\uB2F5:\", decoded);\n        return;\n      }\n      const response = decoded as WorkerResponse;\n\n      if (response.type === \"event\") {\n        this.emit(response.event, response.body);\n      } else if (response.type === \"log\") {\n        process.stdout.write(response.body);\n      } else if (response.type === \"return\") {\n        const pending = this._pendingRequests.get(response.request.id);\n        if (pending) {\n          this._pendingRequests.delete(response.request.id);\n          pending.resolve(response.body);\n        }\n      } else {\n        // response.type === \"error\"\n        const pending = this._pendingRequests.get(response.request.id);\n        if (pending) {\n          this._pendingRequests.delete(response.request.id);\n          pending.reject(response.body);\n        }\n      }\n    });\n  }\n\n  /**\n   * \uB300\uAE30 \uC911\uC778 \uBAA8\uB4E0 \uC694\uCCAD\uC744 reject\uD569\uB2C8\uB2E4.\n   */\n  private _rejectAllPending(err: Error): void {\n    for (const [_id, { method, reject }] of this._pendingRequests) {\n      reject(new Error(`${err.message} (method: ${method})`));\n    }\n    this._pendingRequests.clear();\n  }\n\n  /**\n   * \uC6CC\uCEE4 \uBA54\uC11C\uB4DC \uD638\uCD9C.\n   */\n  call(method: string, params: unknown[]): Promise<unknown> {\n    return new Promise((resolve, reject) => {\n      const request: WorkerRequest = {\n        id: Uuid.new().toString(),\n        method,\n        params,\n      };\n\n      this._pendingRequests.set(request.id, { method, resolve, reject });\n\n      const serialized = transferableEncode(request);\n      this._worker.postMessage(serialized.result, serialized.transferList);\n    });\n  }\n\n  /**\n   * \uC6CC\uCEE4 \uC885\uB8CC.\n   */\n  async terminate(): Promise<void> {\n    this._isTerminated = true;\n    this._rejectAllPending(new Error(\"\uC6CC\uCEE4\uAC00 \uC885\uB8CC\uB428\"));\n    await this._worker.terminate();\n  }\n}\n\n//#endregion\n\n//#region Worker\n\n/**\n * \uD0C0\uC785 \uC548\uC804\uD55C Worker \uB798\uD37C.\n *\n * @example\n * // worker.ts\n * export default createWorker({\n *   add: (a: number, b: number) => a + b,\n * });\n *\n * // main.ts\n * const worker = Worker.create<typeof import(\"./worker\")>(\"./worker.ts\");\n * const result = await worker.add(10, 20);  // 30\n * await worker.terminate();\n */\nexport const Worker = {\n  /**\n   * \uD0C0\uC785 \uC548\uC804\uD55C Worker Proxy \uC0DD\uC131.\n   *\n   * @param filePath - \uC6CC\uCEE4 \uD30C\uC77C \uACBD\uB85C (file:// URL \uB610\uB294 \uC808\uB300 \uACBD\uB85C)\n   * @param opt - Worker \uC635\uC158\n   * @returns Proxy \uAC1D\uCCB4 (\uBA54\uC11C\uB4DC \uC9C1\uC811 \uD638\uCD9C, on(), terminate() \uC9C0\uC6D0)\n   */\n  create<TModule extends WorkerModule>(\n    filePath: string,\n    opt?: Omit<WorkerRawOptions, \"stdout\" | \"stderr\">,\n  ): WorkerProxy<TModule> {\n    const internal = new WorkerInternal(filePath, opt);\n\n    return new Proxy({} as WorkerProxy<TModule>, {\n      get(_target, prop: string) {\n        // \uC608\uC57D\uB41C \uBA54\uC11C\uB4DC: on, off, terminate\n        if (prop === \"on\") {\n          return (event: string, listener: (data: unknown) => void) => {\n            internal.on(event, listener);\n          };\n        }\n        if (prop === \"off\") {\n          return (event: string, listener: (data: unknown) => void) => {\n            internal.off(event, listener);\n          };\n        }\n        if (prop === \"terminate\") {\n          return () => internal.terminate();\n        }\n\n        // \uADF8 \uC678\uB294 \uC6CC\uCEE4 \uBA54\uC11C\uB4DC\uB85C \uCC98\uB9AC\n        return (...args: unknown[]) => internal.call(prop, args);\n      },\n    });\n  },\n};\n\n//#endregion\n"],
+  "mappings": "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",
+  "names": []
+}

package/lib/worker-dev-proxy.js

@@ -0,0 +1,12 @@
+import { tsImport } from "tsx/esm/api";
+import { pathToFileURL } from "url";
+
+// argv[2]에 진짜 워커 파일 경로가 들어온다고 가정
+const workerFile = process.argv[2];
+if (!workerFile) {
+  throw new Error("Worker file path is required as argument!");
+}
+
+// Windows에서 절대 경로는 file:// URL로 변환해야 ESM 로더가 처리 가능
+const workerFileUrl = pathToFileURL(workerFile).href;
+await tsImport(workerFileUrl, import.meta.url);

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@simplysm/core-node",
+  "version": "13.0.0-beta.1",
+  "description": "심플리즘 패키지 - 코어 모듈 (node)",
+  "author": "김석래",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/kslhunter/simplysm.git",
+    "directory": "packages/core-node"
+  },
+  "license": "Apache-2.0",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "dependencies": {
+    "@simplysm/core-common": "workspace:*",
+    "chokidar": "^5.0.0",
+    "consola": "^3.4.0",
+    "glob": "^13.0.0",
+    "tsx": "^4.21.0"
+  }
+}

package/src/features/fs-watcher.ts

@@ -0,0 +1,176 @@
+import { DebounceQueue } from "@simplysm/core-common";
+import * as chokidar from "chokidar";
+import { createConsola } from "consola";
+import type { EventName } from "chokidar/handler.js";
+import { type NormPath, pathNorm } from "../utils/path";
+
+//#region Types
+
+/**
+ * 지원하는 파일 변경 이벤트 타입 목록.
+ */
+const FS_WATCHER_EVENTS = ["add", "addDir", "change", "unlink", "unlinkDir"] as const;
+
+/**
+ * 파일 변경 이벤트 타입.
+ */
+export type FsWatcherEvent = (typeof FS_WATCHER_EVENTS)[number];
+
+/**
+ * 파일 변경 정보.
+ */
+export interface FsWatcherChangeInfo {
+  /** 변경 이벤트 타입 */
+  event: FsWatcherEvent;
+  /** 변경된 파일/디렉토리 경로 (정규화됨) */
+  path: NormPath;
+}
+
+//#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: string[], options?: chokidar.ChokidarOptions): Promise<FsWatcher> {
+    return new Promise<FsWatcher>((resolve, reject) => {
+      const watcher = new FsWatcher(paths, options);
+      watcher._watcher.on("ready", () => {
+        resolve(watcher);
+      });
+      watcher._watcher.on("error", reject);
+    });
+  }
+
+  private readonly _watcher: chokidar.FSWatcher;
+  private readonly _ignoreInitial: boolean = true;
+  private readonly _debounceQueues: DebounceQueue[] = [];
+
+  private readonly _logger = createConsola().withTag("sd-fs-watcher");
+
+  private constructor(paths: string[], options?: chokidar.ChokidarOptions) {
+    this._watcher = chokidar.watch(paths, {
+      persistent: true,
+      ...options,
+      ignoreInitial: true,
+    });
+    this._ignoreInitial = options?.ignoreInitial ?? this._ignoreInitial;
+
+    // 감시 중 발생하는 에러 로깅
+    this._watcher.on("error", (err) => {
+      this._logger.error("FsWatcher error:", err);
+    });
+  }
+
+  /**
+   * 파일 변경 이벤트 핸들러 등록.
+   * 지정된 delay 시간 동안 이벤트를 모아서 한 번에 콜백 호출.
+   *
+   * @param opt.delay - 이벤트 병합 대기 시간 (ms)
+   * @param cb - 변경 이벤트 콜백
+   */
+  onChange(opt: { delay?: number }, cb: (changeInfos: FsWatcherChangeInfo[]) => void | Promise<void>): this {
+    const fnQ = new DebounceQueue(opt.delay);
+    this._debounceQueues.push(fnQ);
+
+    let changeInfoMap = new Map<string, EventName>();
+
+    // ignoreInitial이 false면 초기에 빈 배열로 콜백 호출
+    if (!this._ignoreInitial) {
+      fnQ.run(async () => {
+        await cb([]);
+      });
+    }
+
+    this._watcher.on("all", (event, filePath) => {
+      // 지원하는 이벤트만 처리
+      if (!FS_WATCHER_EVENTS.includes(event as FsWatcherEvent)) 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<string, EventName>();
+
+        const changeInfos = Array.from(currChangeInfoMap.entries()).map(
+          ([path, evt]): FsWatcherChangeInfo => ({
+            path: pathNorm(path),
+            event: evt as FsWatcherEvent,
+          }),
+        );
+
+        await cb(changeInfos);
+      });
+    });
+
+    return this;
+  }
+
+  /**
+   * 파일 감시 종료.
+   */
+  async close(): Promise<void> {
+    for (const q of this._debounceQueues) {
+      q.dispose();
+    }
+    this._debounceQueues.length = 0;
+    await this._watcher.close();
+  }
+}
+
+//#endregion

package/src/index.ts

@@ -0,0 +1,11 @@
+// Utils
+export * from "./utils/fs";
+export * from "./utils/path";
+
+// Features
+export * from "./features/fs-watcher";
+
+// Worker
+export * from "./worker/types";
+export * from "./worker/worker";
+export * from "./worker/create-worker";