@simplysm/core-node 13.0.96 → 13.0.98

package/README.md

@@ -1,315 +1,56 @@
 # @simplysm/core-node
 
-Node.js 환경 전용 유틸리티. 파일시스템, 경로, 파일 감시, Worker 스레드를 제공한다.
+Core module (node) -- Node.js utilities for file system, path, watching, and workers.
 
-## 설치
+## Installation
 
 ```bash
 npm install @simplysm/core-node
 ```
 
-**의존성:** `@simplysm/core-common`, `chokidar`, `consola`, `glob`, `minimatch`, `tsx`
+## Exports
 
-## 모듈 구조
-
-```
-@simplysm/core-node
-├── fsx           # 파일시스템 유틸리티 (namespace)
-├── pathx         # 경로 유틸리티 (namespace)
-├── FsWatcher     # 파일 감시 (class)
-├── Worker        # 타입 안전한 Worker 스레드 (object)
-├── createWorker  # Worker 팩토리 (function)
-└── types         # NormPath, WorkerModule, WorkerProxy, ...
-```
-
----
-
-## 주요 사용법
-
-### fsx -- 파일시스템 유틸리티
-
-모든 함수는 async/sync 쌍으로 제공된다 (예: `read` / `readSync`).
+All utilities are re-exported from the package entry point:
 
 ```typescript
-import { fsx } from "@simplysm/core-node";
-
-// 존재 확인
-await fsx.exists("/path/to/file");
-fsx.existsSync("/path/to/file");
-
-// 디렉토리 생성 (재귀)
-await fsx.mkdir("/path/to/dir");
-fsx.mkdirSync("/path/to/dir");
-
-// 삭제
-// async: 6회 재시도, 500ms 간격 (파일 잠금 등 일시적 오류 대응)
-// sync: 재시도 없이 즉시 실패
-await fsx.rm("/path/to/target");
-fsx.rmSync("/path/to/target");
-
-// 복사 (필터 지원)
-// 필터는 자식 경로에만 적용, 최상위 sourcePath는 필터링 대상이 아님
-// 디렉토리에 false를 반환하면 해당 디렉토리와 모든 하위 내용을 건너뜀
-// sourcePath가 존재하지 않으면 아무 동작 없이 반환
-await fsx.copy(src, dst, (absPath) => !absPath.includes("node_modules"));
-fsx.copySync(src, dst);
-
-// 읽기
-const text = await fsx.read("/path/to/file.txt");           // UTF-8 문자열
-const buf = await fsx.readBuffer("/path/to/file.bin");      // Buffer
-const config = await fsx.readJson<Config>("/path/config.json"); // JSON 파싱 (core-common의 json.parse 사용)
-
-// 쓰기 (부모 디렉토리 자동 생성)
-await fsx.write("/path/to/file.txt", content);              // string | Uint8Array
-await fsx.writeJson("/path/to/config.json", data, { space: 2 });
-// writeJson의 options: { replacer?, space? }
-
-// 디렉토리 읽기
-const entries = await fsx.readdir("/path/to/dir");          // string[]
-
-// 파일 정보
-const stats = await fsx.stat("/path/to/file");              // 심볼릭 링크 따라감
-const lstats = await fsx.lstat("/path/to/symlink");         // 심볼릭 링크 자체 정보
-
-// Glob 패턴 검색 (절대 경로 반환)
-const files = await fsx.glob("**/*.ts", { cwd: "/project" });
-const filesSync = fsx.globSync("**/*.ts", { cwd: "/project" });
-
-// 빈 디렉토리 정리 (재귀적으로 빈 디렉토리 삭제)
-await fsx.clearEmptyDirectory("/path/to/dir");
-
-// 상위 디렉토리 탐색
-// fromPath에서 루트까지 각 디렉토리에서 childGlob 패턴에 매칭되는 파일 검색
-const paths = await fsx.findAllParentChildPaths("package.json", "/project/src/deep");
-const pathsSync = fsx.findAllParentChildPathsSync("package.json", "/project/src/deep", "/project"); // rootPath 지정 가능
-```
-
-### pathx -- 경로 유틸리티
-
-```typescript
-import { pathx } from "@simplysm/core-node";
-import type { NormPath } from "@simplysm/core-node";
-
-// POSIX 변환 (여러 인자를 path.join 후 변환)
-pathx.posix("C:\\Users\\test");              // "C:/Users/test"
-pathx.posix("src", "index.ts");              // "src/index.ts"
-
-// 정규화 (절대 경로, 브랜드 타입 NormPath 반환)
-const norm: NormPath = pathx.norm("relative/path");
-const norm2: NormPath = pathx.norm("base", "relative"); // 여러 경로 조합 가능
-
-// 디렉토리 변경
-pathx.changeFileDirectory("/a/b/c.txt", "/a", "/x"); // "/x/b/c.txt"
-// filePath가 fromDirectory 하위가 아니면 ArgumentError 발생
-
-// 확장자 없는 파일명
-pathx.basenameWithoutExt("/path/file.spec.ts");       // "file.spec"
-
-// 자식 경로 확인
-pathx.isChildPath("/a/b/c", "/a/b");                  // true
-pathx.isChildPath("/a/b", "/a/b");                    // false (동일 경로)
-
-// 대상 경로 필터링
-pathx.filterByTargets(
-  ["/proj/src/a.ts", "/proj/tests/c.ts"],
-  ["src"],
-  "/proj"
-);
-// ["/proj/src/a.ts"]
-// targets가 빈 배열이면 files를 그대로 반환
+import { fsx, pathx, FsWatcher, Worker, createWorker } from "@simplysm/core-node";
 ```
 
-### FsWatcher -- 파일 감시
+- **`fsx`** -- File system utilities (namespace). See [docs/fs.md](docs/fs.md)
+- **`pathx`** -- Path utilities (namespace). See [docs/path.md](docs/path.md)
+- **`FsWatcher`** -- Chokidar-based file system watcher. See [docs/features.md](docs/features.md)
+- **Worker / createWorker** -- Type-safe worker_threads wrapper. See [docs/worker.md](docs/worker.md)
 
-Chokidar 기반, 이벤트 디바운싱 및 glob 패턴 지원.
+## Quick Start
 
 ```typescript
-import { FsWatcher } from "@simplysm/core-node";
-import type { FsWatcherEvent, FsWatcherChangeInfo } from "@simplysm/core-node";
+import { fsx, pathx, FsWatcher, Worker, createWorker } from "@simplysm/core-node";
 
-// 감시 시작 (ready 이벤트까지 대기)
-// 경로 또는 glob 패턴 모두 사용 가능
-const watcher = await FsWatcher.watch([
-  "/project/src",         // 디렉토리 경로
-  "/project/lib/**/*.js", // glob 패턴
-]);
+// File system
+const content = await fsx.read("/path/to/file.txt");
+await fsx.write("/path/to/output.txt", content);
 
-// chokidar 옵션 전달 가능 (ignoreInitial은 내부적으로 항상 true로 설정됨)
-const watcher2 = await FsWatcher.watch(["/project/src"], {
-  depth: 2,
-  ignored: /node_modules/,
-});
+// Path utilities
+const normalized = pathx.norm("/some/path");
+const posixPath = pathx.posix("C:\\Users\\test");
 
-// 변경 이벤트 핸들러 등록
-// delay ms 동안 이벤트를 모아 한 번에 콜백 호출
-watcher.onChange({ delay: 300 }, (changes: FsWatcherChangeInfo[]) => {
-  for (const { event, path } of changes) {
-    // event: "add" | "addDir" | "change" | "unlink" | "unlinkDir"
-    // path: NormPath (정규화된 절대 경로)
+// File watching
+const watcher = await FsWatcher.watch(["src/**/*.ts"]);
+watcher.onChange({ delay: 300 }, (changes) => {
+  for (const { path, event } of changes) {
+    // handle changes
   }
 });
 
-// 종료
-await watcher.close();
-```
-
-**이벤트 병합 전략** (같은 파일에 대해 짧은 시간 내 여러 이벤트 발생 시):
-- `add` + `change` -> `add` (생성 직후 수정은 생성으로 처리)
-- `add` + `unlink` -> 제거 (생성 후 즉시 삭제는 무변경)
-- `unlink` + `add` -> `add` (삭제 후 재생성은 생성으로 처리)
-- `unlink` + `change` -> `add` (삭제 후 변경은 생성으로 처리)
-- `unlinkDir` + `addDir` -> `addDir`
-- 그 외 -> 마지막 이벤트로 덮어쓰기
-
-### Worker -- 타입 안전한 Worker 스레드
-
-#### Worker 파일 작성 (worker.ts)
-
-```typescript
-import { createWorker } from "@simplysm/core-node";
-
-// 이벤트 없는 Worker
-export default createWorker({
-  add: (a: number, b: number) => a + b,
-});
-
-// 이벤트가 있는 Worker
-interface MyEvents {
-  progress: number;
-}
-
-const methods = {
-  processFile: async (path: string) => {
-    sender.send("progress", 50);
-    // ... 처리 ...
-    sender.send("progress", 100);
-    return "done";
-  },
-};
-
-const sender = createWorker<typeof methods, MyEvents>(methods);
-export default sender;
-```
-
-#### 메인 스레드에서 사용
-
-```typescript
-import { Worker } from "@simplysm/core-node";
-
-// Worker 생성 (타입 추론을 위해 typeof import 사용)
+// Workers
 const worker = Worker.create<typeof import("./worker")>("./worker.ts");
-
-// 옵션 전달 (WorkerOptions에서 stdout/stderr 제외)
-const worker2 = Worker.create<typeof import("./worker")>("./worker.ts", {
-  env: { NODE_ENV: "production" },
-  argv: ["--verbose"],
-});
-
-// 메서드 호출 (자동 Promise 래핑)
-const result = await worker.add(10, 20); // 30
-
-// 이벤트 수신
-const handler = (value: number) => { /* ... */ };
-worker.on("progress", handler);
-worker.off("progress", handler); // 이벤트 해제
-
-// 종료
+const result = await worker.add(10, 20);
 await worker.terminate();
 ```
 
-**특징:**
-- `.ts` 파일은 tsx를 통해 자동 실행 (개발 환경), `.js` 파일은 직접 Worker 생성 (프로덕션)
-- UUID 기반 요청 추적으로 동시 요청 지원
-- Worker 크래시 시 대기 중인 모든 요청 자동 reject
-- Worker 내 `process.stdout.write`는 메인 스레드로 자동 전달
-- `@simplysm/core-common`의 `transfer`를 사용하여 메시지 직렬화
-- `file://` URL 경로와 절대 경로 모두 지원
-
----
-
-## API 레퍼런스
-
-### fsx (namespace)
-
-| 함수 | 시그니처 | 설명 |
-|------|----------|------|
-| `exists` | `(targetPath: string) => Promise<boolean>` | 파일/디렉토리 존재 확인 |
-| `existsSync` | `(targetPath: string) => boolean` | 동기 버전 |
-| `mkdir` | `(targetPath: string) => Promise<void>` | 디렉토리 재귀 생성 |
-| `mkdirSync` | `(targetPath: string) => void` | 동기 버전 |
-| `rm` | `(targetPath: string) => Promise<void>` | 삭제 (6회 재시도, 500ms 간격) |
-| `rmSync` | `(targetPath: string) => void` | 동기 버전 (재시도 없음) |
-| `copy` | `(src, dst, filter?) => Promise<void>` | 파일/디렉토리 복사 (async 시 병렬 처리) |
-| `copySync` | `(src, dst, filter?) => void` | 동기 버전 |
-| `read` | `(targetPath: string) => Promise<string>` | UTF-8 텍스트 읽기 |
-| `readSync` | `(targetPath: string) => string` | 동기 버전 |
-| `readBuffer` | `(targetPath: string) => Promise<Buffer>` | 바이너리 읽기 |
-| `readBufferSync` | `(targetPath: string) => Buffer` | 동기 버전 |
-| `readJson` | `<T>(targetPath: string) => Promise<T>` | JSON 파일 읽기 |
-| `readJsonSync` | `<T>(targetPath: string) => T` | 동기 버전 |
-| `write` | `(targetPath, data: string \| Uint8Array) => Promise<void>` | 파일 쓰기 (부모 디렉토리 자동 생성) |
-| `writeSync` | `(targetPath, data: string \| Uint8Array) => void` | 동기 버전 |
-| `writeJson` | `(targetPath, data, options?) => Promise<void>` | JSON 파일 쓰기 |
-| `writeJsonSync` | `(targetPath, data, options?) => void` | 동기 버전 |
-| `readdir` | `(targetPath: string) => Promise<string[]>` | 디렉토리 내용 읽기 |
-| `readdirSync` | `(targetPath: string) => string[]` | 동기 버전 |
-| `stat` | `(targetPath: string) => Promise<fs.Stats>` | 파일 정보 (심링크 따라감) |
-| `statSync` | `(targetPath: string) => fs.Stats` | 동기 버전 |
-| `lstat` | `(targetPath: string) => Promise<fs.Stats>` | 파일 정보 (심링크 자체) |
-| `lstatSync` | `(targetPath: string) => fs.Stats` | 동기 버전 |
-| `glob` | `(pattern, options?: GlobOptions) => Promise<string[]>` | Glob 패턴 검색 (절대 경로 반환) |
-| `globSync` | `(pattern, options?: GlobOptions) => string[]` | 동기 버전 |
-| `clearEmptyDirectory` | `(dirPath: string) => Promise<void>` | 빈 디렉토리 재귀 삭제 |
-| `findAllParentChildPaths` | `(childGlob, fromPath, rootPath?) => Promise<string[]>` | 상위 디렉토리 탐색 |
-| `findAllParentChildPathsSync` | `(childGlob, fromPath, rootPath?) => string[]` | 동기 버전 |
-
-### pathx (namespace)
-
-| 함수 | 시그니처 | 설명 |
-|------|----------|------|
-| `posix` | `(...args: string[]) => string` | POSIX 경로 변환 (path.join 후 `\` -> `/`) |
-| `norm` | `(...paths: string[]) => NormPath` | 절대 경로 정규화 (브랜드 타입) |
-| `changeFileDirectory` | `(filePath, fromDir, toDir) => string` | 파일의 기준 디렉토리 변경 |
-| `basenameWithoutExt` | `(filePath: string) => string` | 확장자 제외한 파일명 |
-| `isChildPath` | `(childPath, parentPath) => boolean` | 자식 경로 여부 확인 |
-| `filterByTargets` | `(files, targets, cwd) => string[]` | 대상 경로 기준 파일 필터링 |
-
-### FsWatcher (class)
-
-| 멤버 | 시그니처 | 설명 |
-|------|----------|------|
-| `static watch` | `(paths: string[], options?: ChokidarOptions) => Promise<FsWatcher>` | 감시 시작 (ready까지 대기) |
-| `onChange` | `(opt: { delay?: number }, cb) => this` | 변경 이벤트 핸들러 등록 (체이닝 가능) |
-| `close` | `() => Promise<void>` | 감시 종료 |
-
-### Worker (object)
-
-| 멤버 | 시그니처 | 설명 |
-|------|----------|------|
-| `create` | `<TModule>(filePath, opt?) => WorkerProxy<TModule>` | 타입 안전한 Worker 프록시 생성 |
-
-### createWorker (function)
-
-```typescript
-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;
-}
-```
-
-### 타입
+## Documentation
 
-| 타입 | 설명 |
-|------|------|
-| `NormPath` | 정규화된 경로 브랜드 타입 (`string & { [NORM]: never }`) |
-| `FsWatcherEvent` | `"add" \| "addDir" \| "change" \| "unlink" \| "unlinkDir"` |
-| `FsWatcherChangeInfo` | `{ event: FsWatcherEvent; path: NormPath }` |
-| `WorkerModule` | Worker 모듈 타입 구조 (타입 추론용) |
-| `WorkerProxy<TModule>` | Worker 프록시 타입 (메서드 + `on`/`off`/`terminate`) |
-| `PromisifyMethods<T>` | 메서드 반환값을 Promise로 래핑하는 매핑 타입 |
-| `WorkerRequest` | 내부 Worker 요청 메시지 타입 |
-| `WorkerResponse` | 내부 Worker 응답 메시지 타입 (return/error/event/log) |
+- [File System Utilities](docs/fs.md)
+- [Path Utilities](docs/path.md)
+- [Features (FsWatcher)](docs/features.md)
+- [Worker](docs/worker.md)

package/docs/features.md

@@ -0,0 +1,91 @@
+# 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();
+```

package/docs/fs.md

@@ -0,0 +1,309 @@
+# File System Utilities
+
+File system utilities exported as the `fsx` namespace.
+
+```typescript
+import { fsx } from "@simplysm/core-node";
+```
+
+## Existence Check
+
+### `existsSync`
+
+Checks if a file or directory exists (synchronous).
+
+```typescript
+function existsSync(targetPath: string): boolean;
+```
+
+### `exists`
+
+Checks if a file or directory exists (asynchronous).
+
+```typescript
+function exists(targetPath: string): Promise<boolean>;
+```
+
+## Create Directory
+
+### `mkdirSync`
+
+Creates a directory (recursive).
+
+```typescript
+function mkdirSync(targetPath: string): void;
+```
+
+### `mkdir`
+
+Creates a directory (recursive, asynchronous).
+
+```typescript
+function mkdir(targetPath: string): Promise<void>;
+```
+
+## Delete
+
+### `rmSync`
+
+Deletes a file or directory.
+
+The synchronous version fails immediately without retries. Use `rm` for cases with potential transient errors like file locks.
+
+```typescript
+function rmSync(targetPath: string): void;
+```
+
+### `rm`
+
+Deletes a file or directory (asynchronous).
+
+The asynchronous version retries up to 6 times (500ms interval) for transient errors like file locks.
+
+```typescript
+function rm(targetPath: string): Promise<void>;
+```
+
+## Copy
+
+### `copySync`
+
+Copies a file or directory.
+
+If `sourcePath` does not exist, no action is performed and the function returns.
+
+```typescript
+function copySync(
+  sourcePath: string,
+  targetPath: string,
+  filter?: (absolutePath: string) => boolean,
+): void;
+```
+
+**Parameters:**
+- `sourcePath` -- Path of the source to copy
+- `targetPath` -- Destination path for the copy
+- `filter` -- A filter function that determines whether to copy. The **absolute path** of each file/directory is passed. Returns `true` to copy, `false` to exclude. The top-level `sourcePath` is not subject to filtering; the filter function is applied recursively to all children. Returning `false` for a directory skips that directory and all its contents.
+
+### `copy`
+
+Copies a file or directory (asynchronous). Same behavior as `copySync`.
+
+```typescript
+function copy(
+  sourcePath: string,
+  targetPath: string,
+  filter?: (absolutePath: string) => boolean,
+): Promise<void>;
+```
+
+## Read File
+
+### `readSync`
+
+Reads a file as a UTF-8 string.
+
+```typescript
+function readSync(targetPath: string): string;
+```
+
+### `read`
+
+Reads a file as a UTF-8 string (asynchronous).
+
+```typescript
+function read(targetPath: string): Promise<string>;
+```
+
+### `readBufferSync`
+
+Reads a file as a Buffer.
+
+```typescript
+function readBufferSync(targetPath: string): Buffer;
+```
+
+### `readBuffer`
+
+Reads a file as a Buffer (asynchronous).
+
+```typescript
+function readBuffer(targetPath: string): Promise<Buffer>;
+```
+
+### `readJsonSync`
+
+Reads a JSON file (using JsonConvert).
+
+```typescript
+function readJsonSync<TData = unknown>(targetPath: string): TData;
+```
+
+### `readJson`
+
+Reads a JSON file (using JsonConvert, asynchronous).
+
+```typescript
+function readJson<TData = unknown>(targetPath: string): Promise<TData>;
+```
+
+## Write File
+
+### `writeSync`
+
+Writes data to a file (auto-creates parent directories).
+
+```typescript
+function writeSync(targetPath: string, data: string | Uint8Array): void;
+```
+
+### `write`
+
+Writes data to a file (auto-creates parent directories, asynchronous).
+
+```typescript
+function write(targetPath: string, data: string | Uint8Array): Promise<void>;
+```
+
+### `writeJsonSync`
+
+Writes data to a JSON file (using JsonConvert).
+
+```typescript
+function writeJsonSync(
+  targetPath: string,
+  data: unknown,
+  options?: {
+    replacer?: (this: unknown, key: string | undefined, value: unknown) => unknown;
+    space?: string | number;
+  },
+): void;
+```
+
+### `writeJson`
+
+Writes data to a JSON file (using JsonConvert, asynchronous).
+
+```typescript
+function writeJson(
+  targetPath: string,
+  data: unknown,
+  options?: {
+    replacer?: (this: unknown, key: string | undefined, value: unknown) => unknown;
+    space?: string | number;
+  },
+): Promise<void>;
+```
+
+## Read Directory
+
+### `readdirSync`
+
+Reads the contents of a directory.
+
+```typescript
+function readdirSync(targetPath: string): string[];
+```
+
+### `readdir`
+
+Reads the contents of a directory (asynchronous).
+
+```typescript
+function readdir(targetPath: string): Promise<string[]>;
+```
+
+## File Information
+
+### `statSync`
+
+Gets file/directory information (follows symbolic links).
+
+```typescript
+function statSync(targetPath: string): fs.Stats;
+```
+
+### `stat`
+
+Gets file/directory information (follows symbolic links, asynchronous).
+
+```typescript
+function stat(targetPath: string): Promise<fs.Stats>;
+```
+
+### `lstatSync`
+
+Gets file/directory information (does not follow symbolic links).
+
+```typescript
+function lstatSync(targetPath: string): fs.Stats;
+```
+
+### `lstat`
+
+Gets file/directory information (does not follow symbolic links, asynchronous).
+
+```typescript
+function lstat(targetPath: string): Promise<fs.Stats>;
+```
+
+## Glob
+
+### `globSync`
+
+Searches for files using a glob pattern.
+
+```typescript
+function globSync(pattern: string, options?: GlobOptions): string[];
+```
+
+Returns an array of absolute paths for matched files.
+
+### `glob`
+
+Searches for files using a glob pattern (asynchronous).
+
+```typescript
+function glob(pattern: string, options?: GlobOptions): Promise<string[]>;
+```
+
+Returns an array of absolute paths for matched files.
+
+## Utilities
+
+### `clearEmptyDirectory`
+
+Recursively searches and deletes empty directories under a specified directory. If all child directories are deleted and a parent becomes empty, it will also be deleted.
+
+```typescript
+function clearEmptyDirectory(dirPath: string): Promise<void>;
+```
+
+### `findAllParentChildPathsSync`
+
+Searches for files matching a glob pattern by traversing parent directories from a start path towards the root. Collects all file paths matching the `childGlob` pattern in each directory.
+
+```typescript
+function findAllParentChildPathsSync(
+  childGlob: string,
+  fromPath: string,
+  rootPath?: string,
+): string[];
+```
+
+**Parameters:**
+- `childGlob` -- Glob pattern to search for in each directory
+- `fromPath` -- Path to start searching from
+- `rootPath` -- Path to stop searching at (if not specified, searches to filesystem root). `fromPath` must be a child path of `rootPath`. Otherwise, searches to the filesystem root.
+
+### `findAllParentChildPaths`
+
+Asynchronous version of `findAllParentChildPathsSync`.
+
+```typescript
+function findAllParentChildPaths(
+  childGlob: string,
+  fromPath: string,
+  rootPath?: string,
+): Promise<string[]>;
+```

package/docs/path.md

@@ -0,0 +1,120 @@
+# Path Utilities
+
+Path utilities exported as the `pathx` namespace.
+
+```typescript
+import { pathx } from "@simplysm/core-node";
+```
+
+## Types
+
+### `NormPath`
+
+Brand type representing a normalized path. Can only be created through `norm()`.
+
+```typescript
+type NormPath = string & { [NORM]: never };
+```
+
+## Functions
+
+### `posix`
+
+Converts to POSIX-style path (backslash to forward slash).
+
+```typescript
+function posix(...args: string[]): string;
+```
+
+**Examples:**
+```typescript
+posix("C:\\Users\\test"); // "C:/Users/test"
+posix("src", "index.ts"); // "src/index.ts"
+```
+
+### `changeFileDirectory`
+
+Changes the directory of a file path.
+
+```typescript
+function changeFileDirectory(
+  filePath: string,
+  fromDirectory: string,
+  toDirectory: string,
+): string;
+```
+
+Throws an error if the file is not inside `fromDirectory`.
+
+**Example:**
+```typescript
+changeFileDirectory("/a/b/c.txt", "/a", "/x");
+// "/x/b/c.txt"
+```
+
+### `basenameWithoutExt`
+
+Returns the filename (basename) without extension.
+
+```typescript
+function basenameWithoutExt(filePath: string): string;
+```
+
+**Examples:**
+```typescript
+basenameWithoutExt("file.txt"); // "file"
+basenameWithoutExt("/path/to/file.spec.ts"); // "file.spec"
+```
+
+### `isChildPath`
+
+Checks if `childPath` is a child path of `parentPath`. Returns `false` if the paths are the same.
+
+Paths are internally normalized using `norm()` and compared using platform-specific path separators.
+
+```typescript
+function isChildPath(childPath: string, parentPath: string): boolean;
+```
+
+**Examples:**
+```typescript
+isChildPath("/a/b/c", "/a/b"); // true
+isChildPath("/a/b", "/a/b/c"); // false
+isChildPath("/a/b", "/a/b");   // false (same path)
+```
+
+### `norm`
+
+Normalizes the path and returns it as `NormPath`. Converts to absolute path and normalizes using platform-specific separators.
+
+```typescript
+function norm(...paths: string[]): NormPath;
+```
+
+**Examples:**
+```typescript
+norm("/some/path");        // NormPath
+norm("relative", "path");  // NormPath (converted to absolute path)
+```
+
+### `filterByTargets`
+
+Filters files based on a list of target paths. Includes files that match or are children of a target path.
+
+```typescript
+function filterByTargets(files: string[], targets: string[], cwd: string): string[];
+```
+
+**Parameters:**
+- `files` -- File paths to filter. Must be absolute paths under `cwd`.
+- `targets` -- Target paths (relative to `cwd`, POSIX style recommended)
+- `cwd` -- Current working directory (absolute path)
+
+If `targets` is empty, returns `files` as-is; otherwise returns only files under target paths.
+
+**Example:**
+```typescript
+const files = ["/proj/src/a.ts", "/proj/src/b.ts", "/proj/tests/c.ts"];
+filterByTargets(files, ["src"], "/proj");
+// ["/proj/src/a.ts", "/proj/src/b.ts"]
+```

package/docs/worker.md

@@ -0,0 +1,168 @@
+# Worker
+
+Type-safe `worker_threads` wrapper providing a proxy-based RPC interface for worker threads.
+
+```typescript
+import { Worker, createWorker } from "@simplysm/core-node";
+```
+
+## Types
+
+### `WorkerModule`
+
+Type structure of the worker module returned by `createWorker()`. Used for type inference in `Worker.create<typeof import("./worker")>()`.
+
+```typescript
+interface WorkerModule {
+  default: {
+    __methods: Record<string, (...args: any[]) => unknown>;
+    __events: Record<string, unknown>;
+  };
+}
+```
+
+### `PromisifyMethods<TMethods>`
+
+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>>`.
+
+```typescript
+type PromisifyMethods<TMethods> = {
+  [K in keyof TMethods]: TMethods[K] extends (...args: infer P) => infer R
+    ? (...args: P) => Promise<Awaited<R>>
+    : never;
+};
+```
+
+### `WorkerProxy<TModule>`
+
+Proxy type returned by `Worker.create()`. Provides promisified methods + `on()` + `off()` + `terminate()`.
+
+```typescript
+type WorkerProxy<TModule extends WorkerModule> = PromisifyMethods<
+  TModule["default"]["__methods"]
+> & {
+  /** Registers a worker event listener. */
+  on<TEventName extends keyof TModule["default"]["__events"] & string>(
+    event: TEventName,
+    listener: (data: TModule["default"]["__events"][TEventName]) => void,
+  ): void;
+
+  /** Unregisters a worker event listener. */
+  off<TEventName extends keyof TModule["default"]["__events"] & string>(
+    event: TEventName,
+    listener: (data: TModule["default"]["__events"][TEventName]) => void,
+  ): void;
+
+  /** Terminates the worker. */
+  terminate(): Promise<void>;
+};
+```
+
+### `WorkerRequest`
+
+Internal worker request message.
+
+```typescript
+interface WorkerRequest {
+  id: string;
+  method: string;
+  params: unknown[];
+}
+```
+
+### `WorkerResponse`
+
+Internal worker response message.
+
+```typescript
+type WorkerResponse =
+  | { request: WorkerRequest; type: "return"; body?: unknown }
+  | { request: WorkerRequest; type: "error"; body: Error }
+  | { type: "event"; event: string; body?: unknown }
+  | { type: "log"; body: string };
+```
+
+## `Worker.create`
+
+Creates a type-safe Worker Proxy.
+
+```typescript
+const Worker = {
+  create<TModule extends WorkerModule>(
+    filePath: string,
+    opt?: Omit<WorkerOptions, "stdout" | "stderr">,
+  ): WorkerProxy<TModule>;
+};
+```
+
+**Parameters:**
+- `filePath` -- Worker file path (file:// URL or absolute path)
+- `opt` -- Worker options
+
+**Returns:** Proxy object (supports direct method calls, `on()`, `off()`, and `terminate()`)
+
+In development (`.ts` files), TypeScript worker files are executed via tsx. In production (`.js` files), Worker is created directly.
+
+## `createWorker`
+
+Worker factory for use in worker threads. This is the function called inside the worker file.
+
+```typescript
+function createWorker<
+  TMethods extends Record<string, (...args: any[]) => unknown>,
+  TEvents extends Record<string, unknown> = Record<string, never>,
+>(
+  methods: TMethods,
+): {
+  send<TEventName extends keyof TEvents & string>(event: TEventName, data?: TEvents[TEventName]): void;
+  __methods: TMethods;
+  __events: TEvents;
+};
+```
+
+## Example
+
+```typescript
+// worker.ts
+import { createWorker } from "@simplysm/core-node";
+
+export default createWorker({
+  add: (a: number, b: number) => a + b,
+});
+
+// main.ts
+import { Worker } from "@simplysm/core-node";
+
+const worker = Worker.create<typeof import("./worker")>("./worker.ts");
+const result = await worker.add(10, 20); // 30
+await worker.terminate();
+```
+
+### Worker with Events
+
+```typescript
+// worker.ts
+import { createWorker } from "@simplysm/core-node";
+
+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;
+
+// main.ts
+const worker = Worker.create<typeof import("./worker")>("./worker.ts");
+worker.on("progress", (value) => {
+  console.log(`Progress: ${value}%`);
+});
+const result = await worker.calc(5); // 10
+await worker.terminate();
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simplysm/core-node",
-  "version": "13.0.96",
+  "version": "13.0.98",
   "description": "Simplysm package - Core module (node)",
   "author": "simplysm",
   "license": "Apache-2.0",
@@ -25,6 +25,6 @@
     "glob": "^13.0.6",
     "minimatch": "^10.2.4",
     "tsx": "^4.21.0",
-    "@simplysm/core-common": "13.0.96"
+    "@simplysm/core-common": "13.0.98"
   }
 }