@simplysm/core-node 13.0.0-beta.1

package/src/worker/create-worker.ts

@@ -0,0 +1,141 @@
+import { parentPort } from "worker_threads";
+import { SdError, transferableDecode, transferableEncode } from "@simplysm/core-common";
+import type { WorkerRequest, WorkerResponse } from "./types";
+
+//#region createSdWorker
+
+/**
+ * 워커 스레드에서 사용할 워커 팩토리.
+ *
+ * @example
+ * // 이벤트 없는 워커
+ * export default createWorker({
+ *   add: (a: number, b: number) => a + b,
+ * });
+ *
+ * // 이벤트 있는 워커
+ * interface MyEvents { progress: number; }
+ * const methods = {
+ *   calc: (x: number) => { sender.send("progress", 50); return x * 2; },
+ * };
+ * const sender = createWorker<typeof methods, MyEvents>(methods);
+ * export default sender;
+ */
+export function createWorker<
+  TMethods extends Record<string, (...args: any[]) => unknown>,
+  TEvents extends Record<string, unknown> = Record<string, never>,
+>(
+  methods: TMethods,
+): {
+  send<K extends keyof TEvents & string>(event: K, data?: TEvents[K]): void;
+  __methods: TMethods;
+  __events: TEvents;
+} {
+  if (parentPort === null) {
+    throw new SdError("이 스크립트는 워커 스레드에서 실행되어야 합니다 (parentPort 필요).");
+  }
+
+  const port = parentPort;
+
+  // Worker 스레드의 stdout은 메인 스레드로 자동 전달되지 않음
+  // stdout.write를 가로채서 메시지 프로토콜을 통해 메인 스레드로 전달
+  process.stdout.write = (
+    chunk: string | Uint8Array,
+    encodingOrCallback?: BufferEncoding | ((err?: Error) => void),
+    callback?: (err?: Error) => void,
+  ): boolean => {
+    const body = typeof chunk === "string" ? chunk : new TextDecoder().decode(chunk);
+    const response: WorkerResponse = { type: "log", body };
+    const serialized = transferableEncode(response);
+    port.postMessage(serialized.result, serialized.transferList);
+
+    const cb = typeof encodingOrCallback === "function" ? encodingOrCallback : callback;
+    if (cb) {
+      queueMicrotask(() => cb());
+    }
+
+    return true;
+  };
+
+  port.on("message", async (serializedRequest: unknown) => {
+    const decoded = transferableDecode(serializedRequest);
+
+    // 요청 구조 검증
+    if (
+      decoded == null ||
+      typeof decoded !== "object" ||
+      !("id" in decoded) ||
+      !("method" in decoded) ||
+      !("params" in decoded)
+    ) {
+      let decodedStr: string;
+      try {
+        decodedStr = JSON.stringify(decoded);
+      } catch {
+        decodedStr = String(decoded);
+      }
+      const errorResponse: WorkerResponse = {
+        type: "error",
+        request: { id: "unknown", method: "unknown", params: [] },
+        body: new SdError(`형식이 잘못된 워커 요청: ${decodedStr}`),
+      };
+      const serialized = transferableEncode(errorResponse);
+      port.postMessage(serialized.result, serialized.transferList);
+      return;
+    }
+    const request = decoded as WorkerRequest;
+
+    const methodFn = methods[request.method] as ((...args: unknown[]) => unknown) | undefined;
+
+    if (methodFn == null) {
+      const response: WorkerResponse = {
+        request,
+        type: "error",
+        body: new SdError(`알 수 없는 메서드: ${request.method}`),
+      };
+
+      const serialized = transferableEncode(response);
+      port.postMessage(serialized.result, serialized.transferList);
+      return;
+    }
+
+    try {
+      const result = await methodFn(...request.params);
+
+      const response: WorkerResponse = {
+        request,
+        type: "return",
+        body: result,
+      };
+
+      const serialized = transferableEncode(response);
+      port.postMessage(serialized.result, serialized.transferList);
+    } catch (err) {
+      const response: WorkerResponse = {
+        request,
+        type: "error",
+        body: err instanceof Error ? err : new Error(String(err)),
+      };
+
+      const serialized = transferableEncode(response);
+      port.postMessage(serialized.result, serialized.transferList);
+    }
+  });
+
+  return {
+    __methods: methods,
+    __events: {} as TEvents,
+    send<K extends keyof TEvents & string>(event: K, data?: TEvents[K]) {
+      const response: WorkerResponse = {
+        type: "event",
+        event,
+        body: data,
+      };
+
+      const serialized = transferableEncode(response);
+      port.postMessage(serialized.result, serialized.transferList);
+    },
+  };
+}
+
+//#endregion

package/src/worker/types.ts

@@ -0,0 +1,86 @@
+//#region Types
+
+/**
+ * `createWorker()`가 반환하는 워커 모듈의 타입 구조.
+ * `Worker.create<typeof import("./worker")>()`에서 타입 추론에 사용된다.
+ *
+ * @see createWorker - 워커 모듈 생성
+ * @see Worker.create - 워커 프록시 생성
+ */
+export interface WorkerModule {
+  default: {
+    __methods: Record<string, (...args: any[]) => unknown>;
+    __events: Record<string, unknown>;
+  };
+}
+
+/**
+ * 메서드 타입의 반환값을 Promise로 래핑하는 매핑 타입.
+ * 워커 메서드는 postMessage 기반으로 동작하여 항상 비동기이므로,
+ * 동기 메서드 타입도 `Promise<Awaited<R>>`로 변환한다.
+ */
+export type PromisifyMethods<T> = {
+  [K in keyof T]: T[K] extends (...args: infer P) => infer R ? (...args: P) => Promise<Awaited<R>> : never;
+};
+
+/**
+ * SdWorker.create()가 반환하는 Proxy 타입.
+ * Promisified 메서드들 + on() + terminate() 제공.
+ */
+export type WorkerProxy<TModule extends WorkerModule> = PromisifyMethods<TModule["default"]["__methods"]> & {
+  /**
+   * 워커 이벤트 리스너 등록.
+   */
+  on<K extends keyof TModule["default"]["__events"] & string>(
+    event: K,
+    listener: (data: TModule["default"]["__events"][K]) => void,
+  ): void;
+
+  /**
+   * 워커 이벤트 리스너 제거.
+   */
+  off<K extends keyof TModule["default"]["__events"] & string>(
+    event: K,
+    listener: (data: TModule["default"]["__events"][K]) => void,
+  ): void;
+
+  /**
+   * 워커 종료.
+   */
+  terminate(): Promise<void>;
+};
+
+/**
+ * Worker 내부 요청 메시지.
+ */
+export interface WorkerRequest {
+  id: string;
+  method: string;
+  params: unknown[];
+}
+
+/**
+ * Worker 내부 응답 메시지.
+ */
+export type WorkerResponse =
+  | {
+      request: WorkerRequest;
+      type: "return";
+      body?: unknown;
+    }
+  | {
+      request: WorkerRequest;
+      type: "error";
+      body: Error;
+    }
+  | {
+      type: "event";
+      event: string;
+      body?: unknown;
+    }
+  | {
+      type: "log";
+      body: string;
+    };
+
+//#endregion

package/src/worker/worker.ts

@@ -0,0 +1,207 @@
+import { EventEmitter, transferableDecode, transferableEncode, Uuid } from "@simplysm/core-common";
+import { createConsola } from "consola";
+import path from "path";
+import { fileURLToPath } from "url";
+import type { WorkerOptions as WorkerRawOptions } from "worker_threads";
+import { Worker as WorkerRaw } from "worker_threads";
+import type { WorkerModule, WorkerProxy, WorkerRequest, WorkerResponse } from "./types";
+
+const logger = createConsola().withTag("sd-worker");
+
+//#region WorkerInternal
+
+/**
+ * Worker 내부 구현 클래스.
+ * Proxy를 통해 외부에 노출됨.
+ *
+ * 개발 환경(.ts)에서는 tsx를 통해 TypeScript 워커 파일을 실행하고,
+ * 프로덕션 환경(.js)에서는 직접 Worker를 생성한다.
+ */
+class WorkerInternal extends EventEmitter<Record<string, unknown>> {
+  private readonly _worker: WorkerRaw;
+  private _isTerminated = false;
+  private readonly _pendingRequests = new Map<
+    string,
+    { method: string; resolve: (value: unknown) => void; reject: (err: Error) => void }
+  >();
+
+  constructor(filePath: string, opt?: Omit<WorkerRawOptions, "stdout" | "stderr">) {
+    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") {
+      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 {
+      // 프로덕션 환경 (.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: ${code})`);
+        // 비정상 종료 시 대기 중인 모든 요청 reject
+        this._rejectAllPending(new Error(`워커가 비정상 종료됨 (code: ${code})`));
+      }
+    });
+
+    this._worker.on("error", (err) => {
+      logger.error("워커 오류:", err);
+      // 워커 에러 시 대기 중인 모든 요청 reject
+      this._rejectAllPending(err);
+    });
+
+    this._worker.on("message", (serializedResponse: unknown) => {
+      const decoded = transferableDecode(serializedResponse);
+
+      // 응답 구조 검증
+      if (decoded == null || typeof decoded !== "object" || !("type" in decoded)) {
+        logger.warn("워커에서 잘못된 형식의 응답:", decoded);
+        return;
+      }
+      const response = decoded as WorkerResponse;
+
+      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);
+        }
+      }
+    });
+  }
+
+  /**
+   * 대기 중인 모든 요청을 reject합니다.
+   */
+  private _rejectAllPending(err: Error): void {
+    for (const [_id, { method, reject }] of this._pendingRequests) {
+      reject(new Error(`${err.message} (method: ${method})`));
+    }
+    this._pendingRequests.clear();
+  }
+
+  /**
+   * 워커 메서드 호출.
+   */
+  call(method: string, params: unknown[]): Promise<unknown> {
+    return new Promise((resolve, reject) => {
+      const request: WorkerRequest = {
+        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(): Promise<void> {
+    this._isTerminated = true;
+    this._rejectAllPending(new Error("워커가 종료됨"));
+    await this._worker.terminate();
+  }
+}
+
+//#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")>("./worker.ts");
+ * const result = await worker.add(10, 20);  // 30
+ * await worker.terminate();
+ */
+export const Worker = {
+  /**
+   * 타입 안전한 Worker Proxy 생성.
+   *
+   * @param filePath - 워커 파일 경로 (file:// URL 또는 절대 경로)
+   * @param opt - Worker 옵션
+   * @returns Proxy 객체 (메서드 직접 호출, on(), terminate() 지원)
+   */
+  create<TModule extends WorkerModule>(
+    filePath: string,
+    opt?: Omit<WorkerRawOptions, "stdout" | "stderr">,
+  ): WorkerProxy<TModule> {
+    const internal = new WorkerInternal(filePath, opt);
+
+    return new Proxy({} as WorkerProxy<TModule>, {
+      get(_target, prop: string) {
+        // 예약된 메서드: on, off, terminate
+        if (prop === "on") {
+          return (event: string, listener: (data: unknown) => void) => {
+            internal.on(event, listener);
+          };
+        }
+        if (prop === "off") {
+          return (event: string, listener: (data: unknown) => void) => {
+            internal.off(event, listener);
+          };
+        }
+        if (prop === "terminate") {
+          return () => internal.terminate();
+        }
+
+        // 그 외는 워커 메서드로 처리
+        return (...args: unknown[]) => internal.call(prop, args);
+      },
+    });
+  },
+};
+
+//#endregion