@simplysm/core-node 13.0.100 → 14.0.1

package/src/worker/create-worker.ts

@@ -5,15 +5,15 @@ import type { WorkerRequest, WorkerResponse } from "./types";
 //#region createWorker
 
 /**
- * Worker factory for use in worker threads.
+ * Worker thread에서 사용하기 위한 워커 팩토리.
  *
  * @example
- * // Worker without events
+ * // 이벤트 없는 워커
  * export default createWorker({
  *   add: (a: number, b: number) => a + b,
  * });
  *
- * // Worker with events
+ * // 이벤트가 있는 워커
  * interface MyEvents { progress: number; }
  * const methods = {
  *   calc: (x: number) => { sender.send("progress", 50); return x * 2; },
@@ -32,13 +32,13 @@ export function createWorker<
   __events: TEvents;
 } {
   if (parentPort === null) {
-    throw new SdError("This script must be executed in a worker thread (parentPort required).");
+    throw new SdError("이 스크립트는 worker thread에서 실행되어야 합니다 (parentPort 필요).");
   }
 
   const port = parentPort;
 
-  // Worker thread's stdout is not automatically forwarded to the main thread
-  // Intercept stdout.write and forward it to the main thread via message protocol
+  // Worker thread의 stdout은 메인 스레드로 자동 전달되지 않음
+  // stdout.write를 가로채서 메시지 프로토콜을 통해 메인 스레드로 전달
   process.stdout.write = (
     chunk: string | Uint8Array,
     encodingOrCallback?: BufferEncoding | ((err?: Error) => void),
@@ -50,7 +50,7 @@ export function createWorker<
     port.postMessage(serialized.result, serialized.transferList);
 
     const cb = typeof encodingOrCallback === "function" ? encodingOrCallback : callback;
-    if (cb) {
+    if (cb != null) {
       queueMicrotask(() => cb());
     }
 
@@ -60,7 +60,7 @@ export function createWorker<
   port.on("message", async (serializedRequest: unknown) => {
     const decoded = transfer.decode(serializedRequest);
 
-    // Validate request structure
+    // 요청 구조 검증
     if (
       decoded == null ||
       typeof decoded !== "object" ||
@@ -77,7 +77,7 @@ export function createWorker<
       const errorResponse: WorkerResponse = {
         type: "error",
         request: { id: "unknown", method: "unknown", params: [] },
-        body: new SdError(`Invalid worker request format: ${decodedStr}`),
+        body: new SdError(`잘못된 워커 요청 형식: ${decodedStr}`),
       };
       const serialized = transfer.encode(errorResponse);
       port.postMessage(serialized.result, serialized.transferList);
@@ -91,7 +91,7 @@ export function createWorker<
       const response: WorkerResponse = {
         request,
         type: "error",
-        body: new SdError(`Unknown method: ${request.method}`),
+        body: new SdError(`알 수 없는 메서드: ${request.method}`),
       };
 
       const serialized = transfer.encode(response);

package/src/worker/types.ts

@@ -1,11 +1,11 @@
 //#region Types
 
 /**
- * Type structure of the worker module returned by `createWorker()`.
- * Used for type inference in `Worker.create<typeof import("./worker")>()`.
+ * `createWorker()`가 반환하는 워커 모듈의 타입 구조.
+ * `Worker.create<typeof import("./worker")>()`에서 타입 추론에 사용된다.
  *
- * @see createWorker - Create worker module
- * @see Worker.create - Create worker proxy
+ * @see createWorker - 워커 모듈 생성
+ * @see Worker.create - 워커 프록시 생성
  */
 export interface WorkerModule {
   default: {
@@ -15,9 +15,9 @@ export interface WorkerModule {
 }
 
 /**
- * Mapping type that wraps method return values in Promise.
- * Worker methods operate based on postMessage and are always asynchronous,
- * so synchronous method types are also converted to `Promise<Awaited<R>>`.
+ * 메서드 반환값을 Promise로 감싸는 매핑 타입.
+ * 워커 메서드는 postMessage 기반으로 동작하여 항상 비동기이므로,
+ * 동기 메서드 타입도 `Promise<Awaited<R>>`로 변환된다.
  */
 export type PromisifyMethods<TMethods> = {
   [K in keyof TMethods]: TMethods[K] extends (...args: infer P) => infer R
@@ -26,14 +26,14 @@ export type PromisifyMethods<TMethods> = {
 };
 
 /**
- * Proxy type returned by Worker.create().
- * Provides promisified methods + on() + terminate().
+ * Worker.create()가 반환하는 프록시 타입.
+ * Promise화된 메서드 + on() + terminate()을 제공한다.
  */
 export type WorkerProxy<TModule extends WorkerModule> = PromisifyMethods<
   TModule["default"]["__methods"]
 > & {
   /**
-   * Registers a worker event listener.
+   * 워커 이벤트 리스너를 등록한다.
    */
   on<TEventName extends keyof TModule["default"]["__events"] & string>(
     event: TEventName,
@@ -41,7 +41,7 @@ export type WorkerProxy<TModule extends WorkerModule> = PromisifyMethods<
   ): void;
 
   /**
-   * Unregisters a worker event listener.
+   * 워커 이벤트 리스너를 해제한다.
    */
   off<TEventName extends keyof TModule["default"]["__events"] & string>(
     event: TEventName,
@@ -49,13 +49,13 @@ export type WorkerProxy<TModule extends WorkerModule> = PromisifyMethods<
   ): void;
 
   /**
-   * Terminates the worker.
+   * 워커를 종료한다.
    */
   terminate(): Promise<void>;
 };
 
 /**
- * Internal worker request message.
+ * 내부 워커 요청 메시지.
  */
 export interface WorkerRequest {
   id: string;
@@ -64,7 +64,7 @@ export interface WorkerRequest {
 }
 
 /**
- * Internal worker response message.
+ * 내부 워커 응답 메시지.
  */
 export type WorkerResponse =
   | {

package/src/worker/worker.ts

@@ -11,11 +11,11 @@ const logger = consola.withTag("sd-worker");
 //#region WorkerInternal
 
 /**
- * Internal implementation class for Worker.
- * Exposed to the outside through a Proxy.
+ * Worker의 내부 구현 클래스.
+ * Proxy를 통해 외부에 노출된다.
  *
- * In development (.ts files), TypeScript worker files are executed via tsx.
- * In production (.js files), Worker is created directly.
+ * 개발 환경(.ts 파일)에서는 TypeScript 워커 파일을 tsx를 통해 실행한다.
+ * 프로덕션 환경(.js 파일)에서는 Worker를 직접 생성한다.
  */
 class WorkerInternal extends EventEmitter<Record<string, unknown>> {
   private readonly _worker: WorkerRaw;
@@ -30,13 +30,13 @@ class WorkerInternal extends EventEmitter<Record<string, unknown>> {
 
     const ext = path.extname(import.meta.filename);
 
-    // Extract env object through type guard
+    // 타입 가드를 통해 env 객체 추출
     const envObj = opt?.env != null && typeof opt.env === "object" ? opt.env : {};
 
-    // In development (.ts files), execute via tsx
-    // worker-dev-proxy.js: Proxy to dynamically load TypeScript worker files via tsx
+    // 개발 환경(.ts 파일)에서는 tsx를 통해 실행
+    // worker-dev-proxy.js: tsx를 통해 TypeScript 워커 파일을 동적으로 로드하는 프록시
     if (ext === ".ts") {
-      // If file:// URL, convert to absolute path (worker-dev-proxy.js applies pathToFileURL again)
+      // 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"),
@@ -52,8 +52,8 @@ class WorkerInternal extends EventEmitter<Record<string, unknown>> {
         },
       );
     } else {
-      // Production environment (.js files)
-      // If file:// URL, convert it; otherwise use absolute path as-is
+      // 프로덕션 환경 (.js 파일)
+      // file:// URL이면 변환; 그렇지 않으면 절대 경로를 그대로 사용
       const workerPath = filePath.startsWith("file://") ? fileURLToPath(filePath) : filePath;
       this._worker = new WorkerRaw(workerPath, {
         stdout: true,
@@ -66,30 +66,30 @@ class WorkerInternal extends EventEmitter<Record<string, unknown>> {
       });
     }
 
-    // Pipe worker's stdout/stderr to main process
+    // 워커의 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(`Worker crashed (code: ${code})`);
-        // Reject all pending requests on abnormal exit
-        this._rejectAllPending(new Error(`Worker crashed (code: ${code})`));
+        logger.error(`워커가 비정상 종료되었습니다 (코드: ${code})`);
+        // 비정상 종료 시 대기 중인 모든 요청을 거부
+        this._rejectAllPending(new Error(`워커가 비정상 종료되었습니다 (코드: ${code})`));
       }
     });
 
     this._worker.on("error", (err) => {
-      logger.error("Worker error:", err);
-      // Reject all pending requests on worker error
+      logger.error("워커 오류:", err);
+      // 워커 오류 시 대기 중인 모든 요청을 거부
       this._rejectAllPending(err);
     });
 
     this._worker.on("message", (serializedResponse: unknown) => {
       const decoded = transfer.decode(serializedResponse);
 
-      // Validate response structure
+      // 응답 구조 검증
       if (decoded == null || typeof decoded !== "object" || !("type" in decoded)) {
-        logger.warn("Invalid response format from worker:", decoded);
+        logger.warn("워커로부터 잘못된 응답 형식:", decoded);
         return;
       }
       const response = decoded as WorkerResponse;
@@ -116,7 +116,7 @@ class WorkerInternal extends EventEmitter<Record<string, unknown>> {
   }
 
   /**
-   * Rejects all pending requests.
+   * 대기 중인 모든 요청을 거부한다.
    */
   private _rejectAllPending(err: Error): void {
     for (const [_id, { method, reject }] of this._pendingRequests) {
@@ -126,7 +126,7 @@ class WorkerInternal extends EventEmitter<Record<string, unknown>> {
   }
 
   /**
-   * Calls a worker method.
+   * 워커 메서드를 호출한다.
    */
   call(method: string, params: unknown[]): Promise<unknown> {
     return new Promise((resolve, reject) => {
@@ -144,11 +144,11 @@ class WorkerInternal extends EventEmitter<Record<string, unknown>> {
   }
 
   /**
-   * Terminates the worker.
+   * 워커를 종료한다.
    */
   async terminate(): Promise<void> {
     this._isTerminated = true;
-    this._rejectAllPending(new Error("Worker terminated"));
+    this._rejectAllPending(new Error("워커가 종료되었습니다"));
     await this._worker.terminate();
   }
 }
@@ -158,7 +158,7 @@ class WorkerInternal extends EventEmitter<Record<string, unknown>> {
 //#region Worker
 
 /**
- * Type-safe Worker wrapper.
+ * 타입 안전한 Worker 래퍼.
  *
  * @example
  * // worker.ts
@@ -173,11 +173,11 @@ class WorkerInternal extends EventEmitter<Record<string, unknown>> {
  */
 export 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,
@@ -187,7 +187,7 @@ export const Worker = {
 
     return new Proxy({} as WorkerProxy<TModule>, {
       get(_target, prop: string) {
-        // Reserved methods: on, off, terminate
+        // 예약된 메서드: on, off, terminate
         if (prop === "on") {
           return (event: string, listener: (data: unknown) => void) => {
             internal.on(event, listener);
@@ -202,7 +202,7 @@ export const Worker = {
           return () => internal.terminate();
         }
 
-        // Otherwise, treat as worker method
+        // 그 외의 경우 워커 메서드로 처리
         return (...args: unknown[]) => internal.call(prop, args);
       },
     });

package/README.md

@@ -1,112 +0,0 @@
-# @simplysm/core-node
-
-Simplysm package - Core module (node). Node.js utilities for file system operations, path manipulation, file watching, and type-safe worker threads.
-
-## Installation
-
-```bash
-npm install @simplysm/core-node
-```
-
-## API Overview
-
-### File System Utils (`fsx` namespace)
-
-| API | Type | Description |
-|-----|------|-------------|
-| `existsSync` | function | Check if a file or directory exists (sync) |
-| `exists` | function | Check if a file or directory exists (async) |
-| `mkdirSync` | function | Create a directory recursively (sync) |
-| `mkdir` | function | Create a directory recursively (async) |
-| `rmSync` | function | Delete a file or directory (sync) |
-| `rm` | function | Delete a file or directory with retries (async) |
-| `copySync` | function | Copy a file or directory with optional filter (sync) |
-| `copy` | function | Copy a file or directory with optional filter (async) |
-| `readSync` | function | Read a file as UTF-8 string (sync) |
-| `read` | function | Read a file as UTF-8 string (async) |
-| `readBufferSync` | function | Read a file as Buffer (sync) |
-| `readBuffer` | function | Read a file as Buffer (async) |
-| `readJsonSync` | function | Read a JSON file using JsonConvert (sync) |
-| `readJson` | function | Read a JSON file using JsonConvert (async) |
-| `writeSync` | function | Write data to a file, auto-creates parent dirs (sync) |
-| `write` | function | Write data to a file, auto-creates parent dirs (async) |
-| `writeJsonSync` | function | Write data to a JSON file (sync) |
-| `writeJson` | function | Write data to a JSON file (async) |
-| `readdirSync` | function | Read directory contents (sync) |
-| `readdir` | function | Read directory contents (async) |
-| `statSync` | function | Get file info, follows symlinks (sync) |
-| `stat` | function | Get file info, follows symlinks (async) |
-| `lstatSync` | function | Get file info, no symlink follow (sync) |
-| `lstat` | function | Get file info, no symlink follow (async) |
-| `globSync` | function | Search files by glob pattern (sync) |
-| `glob` | function | Search files by glob pattern (async) |
-| `clearEmptyDirectory` | function | Recursively delete empty directories |
-| `findAllParentChildPathsSync` | function | Search for glob matches traversing parent dirs (sync) |
-| `findAllParentChildPaths` | function | Search for glob matches traversing parent dirs (async) |
-
--> See [docs/fs.md](./docs/fs.md) for details.
-
-### Path Utils (`pathx` namespace)
-
-| API | Type | Description |
-|-----|------|-------------|
-| `NormPath` | type | Brand type for normalized path |
-| `posix` | function | Convert to POSIX-style path (backslash to forward slash) |
-| `changeFileDirectory` | function | Change the directory of a file path |
-| `basenameWithoutExt` | function | Get filename without extension |
-| `isChildPath` | function | Check if a path is a child of another path |
-| `norm` | function | Normalize path to absolute NormPath |
-| `filterByTargets` | function | Filter files by target path list |
-
--> See [docs/path.md](./docs/path.md) for details.
-
-### Features
-
-| API | Type | Description |
-|-----|------|-------------|
-| `FsWatcherEvent` | type | File change event type (`add`, `addDir`, `change`, `unlink`, `unlinkDir`) |
-| `FsWatcherChangeInfo` | interface | File change information (`event`, `path`) |
-| `FsWatcher` | class | Chokidar-based file watcher with event merging |
-
--> See [docs/features.md](./docs/features.md) for details.
-
-### Worker System
-
-| API | Type | Description |
-|-----|------|-------------|
-| `WorkerModule` | interface | Worker module type structure for type inference |
-| `PromisifyMethods` | type | Maps method return values to Promise |
-| `WorkerProxy` | type | Proxy type with promisified methods + on/off/terminate |
-| `WorkerRequest` | interface | Internal worker request message |
-| `WorkerResponse` | type | Internal worker response message |
-| `Worker` | object | Type-safe Worker wrapper with `create()` factory |
-| `createWorker` | function | Worker factory for use in worker threads |
-
--> See [docs/worker.md](./docs/worker.md) for details.
-
-## Usage Examples
-
-```typescript
-import { fsx, pathx, FsWatcher, Worker, createWorker } from "@simplysm/core-node";
-
-// File system
-const content = await fsx.read("/path/to/file.txt");
-await fsx.write("/path/to/output.txt", content);
-
-// Path utilities
-const normalized = pathx.norm("/some/path");
-const posixPath = pathx.posix("C:\\Users\\test");
-
-// File watching
-const watcher = await FsWatcher.watch(["src/**/*.ts"]);
-watcher.onChange({ delay: 300 }, (changes) => {
-  for (const { path, event } of changes) {
-    // handle changes
-  }
-});
-
-// Workers
-const worker = Worker.create<typeof import("./worker")>("./worker.ts");
-const result = await worker.add(10, 20);
-await worker.terminate();
-```

package/docs/features.md

@@ -1,91 +0,0 @@
-# Features
-
-## FsWatcher
-
-Chokidar-based file system watcher wrapper. Merges events that occur within a short time and calls the callback once.
-
-```typescript
-import { FsWatcher } from "@simplysm/core-node";
-```
-
-### Types
-
-#### `FsWatcherEvent`
-
-File change event type.
-
-```typescript
-type FsWatcherEvent = "add" | "addDir" | "change" | "unlink" | "unlinkDir";
-```
-
-#### `FsWatcherChangeInfo`
-
-File change information.
-
-```typescript
-interface FsWatcherChangeInfo {
-  /** Change event type */
-  event: FsWatcherEvent;
-  /** Changed file/directory path (normalized) */
-  path: NormPath;
-}
-```
-
-### Class: `FsWatcher`
-
-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.
-
-#### `FsWatcher.watch`
-
-Starts watching files (asynchronous). Waits until the ready event is emitted.
-
-```typescript
-static async watch(paths: string[], options?: chokidar.ChokidarOptions): Promise<FsWatcher>;
-```
-
-**Parameters:**
-- `paths` -- Array of file/directory paths or glob patterns to watch
-- `options` -- chokidar options
-
-#### `onChange`
-
-Registers a file change event handler. Collects events for the specified delay time and calls the callback once.
-
-```typescript
-onChange(
-  opt: { delay?: number },
-  cb: (changeInfos: FsWatcherChangeInfo[]) => void | Promise<void>,
-): this;
-```
-
-**Parameters:**
-- `opt.delay` -- Event merge wait time (ms)
-- `cb` -- Change event callback
-
-Event merging strategy:
-- `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
-
-#### `close`
-
-Closes the file watcher.
-
-```typescript
-async close(): Promise<void>;
-```
-
-### Example
-
-```typescript
-const watcher = await FsWatcher.watch(["src/**/*.ts"]);
-watcher.onChange({ delay: 300 }, (changes) => {
-  for (const { path, event } of changes) {
-    console.log(`${event}: ${path}`);
-  }
-});
-
-// Close
-await watcher.close();
-```