@simplysm/core-node 13.0.84 → 13.0.86

package/README.md

@@ -1,48 +1,305 @@
 # @simplysm/core-node
 
-> Simplysm package - Core module (node)
+Node.js 환경 전용 유틸리티. 파일시스템, 경로, 파일 감시, Worker 스레드를 제공한다.
 
-Node.js utility library providing enhanced filesystem operations, path manipulation, file watching, and a type-safe worker thread wrapper. All filesystem functions include automatic error wrapping with `SdError` for better stack traces.
-
-## Installation
+## 설치
 
 ```bash
 npm install @simplysm/core-node
 ```
 
-## Documentation
+**의존성:** `@simplysm/core-common`, `chokidar`, `consola`, `glob`, `minimatch`, `tsx`
+
+## 모듈 구조
+
+```
+@simplysm/core-node
+├── fsx           # 파일시스템 유틸리티 (namespace)
+├── pathx         # 경로 유틸리티 (namespace)
+├── FsWatcher     # 파일 감시 (class)
+├── Worker        # 타입 안전한 Worker 스레드 (object)
+├── createWorker  # Worker 팩토리 (function)
+└── types         # NormPath, WorkerModule, WorkerProxy, ...
+```
+
+---
+
+## 주요 사용법
 
-| Category | Description | File |
-|---|---|---|
-| Filesystem Utilities | File/directory CRUD, glob, JSON read/write | [docs/filesystem.md](docs/filesystem.md) |
-| Path Utilities | Path normalization, POSIX conversion, child path checks | [docs/path.md](docs/path.md) |
-| File Watcher | Chokidar-based watcher with event debouncing and merging | [docs/fs-watcher.md](docs/fs-watcher.md) |
-| Worker | Type-safe worker thread wrapper with RPC and events | [docs/worker.md](docs/worker.md) |
+### fsx -- 파일시스템 유틸리티
 
-## Quick Example
+모든 함수는 async/sync 쌍으로 제공된다 (예: `read` / `readSync`).
 
 ```typescript
-import { fsx, pathx, FsWatcher, Worker } from "@simplysm/core-node";
-
-// Filesystem
-const content = await fsx.read("config.json");
-await fsx.write("output.txt", "hello");
-const files = await fsx.glob("src/**/*.ts");
-
-// Path
-const normalized = pathx.norm("/some/path");
-const posixPath = pathx.posix("C:\\Users\\test"); // "C:/Users/test"
-
-// File watcher
-const watcher = await FsWatcher.watch(["src/**/*.ts"]);
-watcher.onChange({ delay: 300 }, (changes) => {
-  for (const { path, event } of changes) {
-    console.log(`${event}: ${path}`);
+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를 반환하면 해당 디렉토리와 모든 하위 내용을 건너뜀
+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 });
+
+// 디렉토리 읽기
+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를 그대로 반환
+```
+
+### FsWatcher -- 파일 감시
+
+Chokidar 기반, 이벤트 디바운싱 및 glob 패턴 지원.
+
+```typescript
+import { FsWatcher } from "@simplysm/core-node";
+import type { FsWatcherEvent, FsWatcherChangeInfo } from "@simplysm/core-node";
+
+// 감시 시작 (ready 이벤트까지 대기)
+// 경로 또는 glob 패턴 모두 사용 가능
+const watcher = await FsWatcher.watch([
+  "/project/src",         // 디렉토리 경로
+  "/project/lib/**/*.js", // glob 패턴
+]);
+
+// 변경 이벤트 핸들러 등록
+// delay ms 동안 이벤트를 모아 한 번에 콜백 호출
+watcher.onChange({ delay: 300 }, (changes: FsWatcherChangeInfo[]) => {
+  for (const { event, path } of changes) {
+    // event: "add" | "addDir" | "change" | "unlink" | "unlinkDir"
+    // path: NormPath (정규화된 절대 경로)
   }
 });
 
-// Worker
-const worker = Worker.create<typeof import("./my-worker")>("./my-worker.ts");
-const result = await worker.add(1, 2);
+// 종료
+await watcher.close();
+```
+
+**이벤트 병합 전략** (같은 파일에 대해 짧은 시간 내 여러 이벤트 발생 시):
+- `add` + `change` -> `add` (생성 직후 수정은 생성으로 처리)
+- `add` + `unlink` -> 제거 (생성 후 즉시 삭제는 무변경)
+- `unlink` + `add` -> `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 사용)
+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); // 이벤트 해제
+
+// 종료
 await worker.terminate();
 ```
+
+**특징:**
+- `.ts` 파일은 tsx를 통해 자동 실행 (개발 환경)
+- UUID 기반 요청 추적으로 동시 요청 지원
+- Worker 크래시 시 대기 중인 모든 요청 자동 reject
+- Worker 내 `process.stdout.write`는 메인 스레드로 자동 전달
+- `@simplysm/core-common`의 `transfer`를 사용하여 메시지 직렬화
+
+---
+
+## 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>` | 삭제 (재시도 포함) |
+| `rmSync` | `(targetPath: string) => void` | 동기 버전 (재시도 없음) |
+| `copy` | `(src, dst, filter?) => Promise<void>` | 파일/디렉토리 복사 |
+| `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?) => Promise<string[]>` | Glob 패턴 검색 (절대 경로 반환) |
+| `globSync` | `(pattern, options?) => 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?) => 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;
+}
+```
+
+### 타입
+
+| 타입 | 설명 |
+|------|------|
+| `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) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simplysm/core-node",
-  "version": "13.0.84",
+  "version": "13.0.86",
   "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.84"
+    "@simplysm/core-common": "13.0.86"
   }
 }

package/docs/filesystem.md

@@ -1,254 +0,0 @@
-# Filesystem Utilities (`fsx`)
-
-Imported as a namespace:
-
-```typescript
-import { fsx } from "@simplysm/core-node";
-```
-
-All functions wrap Node.js `fs` operations with automatic `SdError` wrapping for improved stack traces. Most functions come in sync and async pairs.
-
----
-
-## API Reference
-
-### exists / existsSync
-
-```typescript
-function exists(targetPath: string): Promise<boolean>;
-function existsSync(targetPath: string): boolean;
-```
-
-Checks if a file or directory exists.
-
----
-
-### mkdir / mkdirSync
-
-```typescript
-function mkdir(targetPath: string): Promise<void>;
-function mkdirSync(targetPath: string): void;
-```
-
-Creates a directory recursively (like `mkdir -p`).
-
----
-
-### rm / rmSync
-
-```typescript
-function rm(targetPath: string): Promise<void>;
-function rmSync(targetPath: string): void;
-```
-
-Deletes a file or directory recursively with `force: true`.
-
-- **`rm`** (async): Retries up to 6 times with a 500ms interval for transient errors (e.g., file locks).
-- **`rmSync`**: Fails immediately without retries.
-
----
-
-### copy / copySync
-
-```typescript
-function copy(
-  sourcePath: string,
-  targetPath: string,
-  filter?: (absolutePath: string) => boolean,
-): Promise<void>;
-
-function copySync(
-  sourcePath: string,
-  targetPath: string,
-  filter?: (absolutePath: string) => boolean,
-): void;
-```
-
-Copies a file or directory. If `sourcePath` does not exist, returns silently.
-
-**Parameters:**
-- `sourcePath` -- Source path to copy from.
-- `targetPath` -- Destination path.
-- `filter` -- Optional filter receiving the absolute path of each child. Return `true` to include, `false` to exclude. The top-level `sourcePath` itself is not filtered; only its children (recursively) are subject to the filter. Returning `false` for a directory skips it and all its contents.
-
----
-
-### read / readSync
-
-```typescript
-function read(targetPath: string): Promise<string>;
-function readSync(targetPath: string): string;
-```
-
-Reads a file as a UTF-8 string.
-
----
-
-### readBuffer / readBufferSync
-
-```typescript
-function readBuffer(targetPath: string): Promise<Buffer>;
-function readBufferSync(targetPath: string): Buffer;
-```
-
-Reads a file as a Buffer.
-
----
-
-### readJson / readJsonSync
-
-```typescript
-function readJson<TData = unknown>(targetPath: string): Promise<TData>;
-function readJsonSync<TData = unknown>(targetPath: string): TData;
-```
-
-Reads and parses a JSON file using `JsonConvert` from `@simplysm/core-common`. On parse failure, the error includes a truncated preview of the file contents (up to 500 characters).
-
----
-
-### write / writeSync
-
-```typescript
-function write(targetPath: string, data: string | Uint8Array): Promise<void>;
-function writeSync(targetPath: string, data: string | Uint8Array): void;
-```
-
-Writes data to a file. Automatically creates parent directories if they do not exist. Uses `flush: true` for immediate disk write.
-
----
-
-### writeJson / writeJsonSync
-
-```typescript
-function writeJson(
-  targetPath: string,
-  data: unknown,
-  options?: {
-    replacer?: (this: unknown, key: string | undefined, value: unknown) => unknown;
-    space?: string | number;
-  },
-): Promise<void>;
-
-function writeJsonSync(
-  targetPath: string,
-  data: unknown,
-  options?: {
-    replacer?: (this: unknown, key: string | undefined, value: unknown) => unknown;
-    space?: string | number;
-  },
-): void;
-```
-
-Writes data to a JSON file using `JsonConvert`.
-
-**Parameters:**
-- `data` -- Data to serialize.
-- `options.replacer` -- Custom JSON replacer function.
-- `options.space` -- Indentation (number of spaces or string).
-
----
-
-### readdir / readdirSync
-
-```typescript
-function readdir(targetPath: string): Promise<string[]>;
-function readdirSync(targetPath: string): string[];
-```
-
-Reads the contents of a directory (file and directory names only, not full paths).
-
----
-
-### stat / statSync
-
-```typescript
-function stat(targetPath: string): Promise<fs.Stats>;
-function statSync(targetPath: string): fs.Stats;
-```
-
-Gets file/directory information. Follows symbolic links.
-
----
-
-### lstat / lstatSync
-
-```typescript
-function lstat(targetPath: string): Promise<fs.Stats>;
-function lstatSync(targetPath: string): fs.Stats;
-```
-
-Gets file/directory information. Does **not** follow symbolic links.
-
----
-
-### glob / globSync
-
-```typescript
-function glob(pattern: string, options?: GlobOptions): Promise<string[]>;
-function globSync(pattern: string, options?: GlobOptions): string[];
-```
-
-Searches for files using a glob pattern. Backslashes in the pattern are automatically converted to forward slashes. Returns an array of **absolute paths**.
-
----
-
-### clearEmptyDirectory
-
-```typescript
-function clearEmptyDirectory(dirPath: string): Promise<void>;
-```
-
-Recursively searches and deletes empty directories under the specified path. If all children of a directory are deleted and it becomes empty, it is also removed.
-
----
-
-### findAllParentChildPaths / findAllParentChildPathsSync
-
-```typescript
-function findAllParentChildPaths(
-  childGlob: string,
-  fromPath: string,
-  rootPath?: string,
-): Promise<string[]>;
-
-function findAllParentChildPathsSync(
-  childGlob: string,
-  fromPath: string,
-  rootPath?: string,
-): string[];
-```
-
-Traverses parent directories from `fromPath` toward the root, collecting all file paths matching `childGlob` in each directory.
-
-**Parameters:**
-- `childGlob` -- Glob pattern to match in each directory.
-- `fromPath` -- Starting directory.
-- `rootPath` -- Optional boundary; stops searching at this directory. Must be a parent of `fromPath`.
-
----
-
-## Usage Examples
-
-```typescript
-import { fsx } from "@simplysm/core-node";
-
-// Read and write JSON
-const config = await fsx.readJson<{ port: number }>("config.json");
-await fsx.writeJson("output.json", { port: 3000 }, { space: 2 });
-
-// Copy with filter (skip node_modules)
-await fsx.copy("src", "dist", (absPath) => !absPath.includes("node_modules"));
-
-// Find all package.json files from a subdirectory up to the project root
-const packageFiles = fsx.findAllParentChildPathsSync(
-  "package.json",
-  "/project/packages/my-lib/src",
-  "/project",
-);
-
-// Clean up empty directories after a build
-await fsx.clearEmptyDirectory("dist");
-
-// Glob search
-const tsFiles = await fsx.glob("src/**/*.ts");
-```

package/docs/fs-watcher.md

@@ -1,145 +0,0 @@
-# File Watcher (`FsWatcher`)
-
-```typescript
-import { FsWatcher } from "@simplysm/core-node";
-```
-
-A chokidar-based file system watcher that debounces and merges rapid file change events, delivering a single consolidated callback.
-
----
-
-## API Reference
-
-### FsWatcherEvent
-
-```typescript
-type FsWatcherEvent = "add" | "addDir" | "change" | "unlink" | "unlinkDir";
-```
-
-Supported file change event types.
-
----
-
-### FsWatcherChangeInfo
-
-```typescript
-interface FsWatcherChangeInfo {
-  event: FsWatcherEvent;
-  path: NormPath;
-}
-```
-
-Describes a single file change with its event type and normalized path.
-
----
-
-### FsWatcher
-
-#### FsWatcher.watch
-
-```typescript
-static async watch(
-  paths: string[],
-  options?: chokidar.ChokidarOptions,
-): Promise<FsWatcher>;
-```
-
-Starts watching files and resolves once the watcher is ready.
-
-**Parameters:**
-- `paths` -- Array of file paths, directory paths, or glob patterns to watch.
-- `options` -- Chokidar options. Note: `ignoreInitial` is internally forced to `true`.
-
----
-
-#### FsWatcher#onChange
-
-```typescript
-onChange(
-  opt: { delay?: number },
-  cb: (changeInfos: FsWatcherChangeInfo[]) => void | Promise<void>,
-): this;
-```
-
-Registers a change event handler. Events occurring within the `delay` window are merged and delivered in a single callback.
-
-**Parameters:**
-- `opt.delay` -- Debounce delay in milliseconds.
-- `cb` -- Callback receiving an array of merged change events.
-
-**Event merging strategy:**
-
-When multiple events occur for the same file within the debounce window:
-
-| Previous Event | New Event | Result |
-|---|---|---|
-| `add` | `change` | `add` (modification right after creation) |
-| `add` | `unlink` | removed (created then deleted = no change) |
-| `unlink` | `add`/`change` | `add` (recreated after deletion) |
-| `addDir` | `unlinkDir` | removed (no change) |
-| `unlinkDir` | `addDir` | `addDir` (recreated) |
-| any | any (other) | latest event wins |
-
----
-
-#### FsWatcher#close
-
-```typescript
-async close(): Promise<void>;
-```
-
-Closes the file watcher and disposes all debounce queues.
-
----
-
-## Usage Examples
-
-```typescript
-import { FsWatcher } from "@simplysm/core-node";
-
-// Watch TypeScript files with 300ms debounce
-const watcher = await FsWatcher.watch(["src/**/*.ts"]);
-
-watcher.onChange({ delay: 300 }, (changes) => {
-  for (const { path, event } of changes) {
-    console.log(`${event}: ${path}`);
-  }
-});
-
-// Watch multiple patterns
-const multiWatcher = await FsWatcher.watch([
-  "src/**/*.ts",
-  "config/**/*.json",
-]);
-
-multiWatcher.onChange({ delay: 500 }, async (changes) => {
-  const tsChanges = changes.filter((c) => c.path.endsWith(".ts"));
-  const configChanges = changes.filter((c) => c.path.endsWith(".json"));
-
-  if (tsChanges.length > 0) {
-    // Rebuild TypeScript
-  }
-  if (configChanges.length > 0) {
-    // Reload configuration
-  }
-});
-
-// Clean up
-await watcher.close();
-await multiWatcher.close();
-```
-
-### ignoreInitial behavior
-
-By default, `ignoreInitial` is `true` and the callback is not invoked until an actual change occurs. If set to `false` in options, the callback is called once immediately with an empty array (the actual initial file list is not included -- this is intentional to avoid conflicts with event merging).
-
-```typescript
-const watcher = await FsWatcher.watch(["src/**/*.ts"], {
-  ignoreInitial: false,
-});
-
-watcher.onChange({ delay: 300 }, (changes) => {
-  // First call: changes = [] (initial trigger)
-  // Subsequent calls: actual file changes
-});
-```

package/docs/path.md

@@ -1,154 +0,0 @@
-# Path Utilities (`pathx`)
-
-Imported as a namespace:
-
-```typescript
-import { pathx } from "@simplysm/core-node";
-```
-
-Provides path normalization, POSIX conversion, child path detection, and target-based filtering utilities.
-
----
-
-## API Reference
-
-### NormPath
-
-```typescript
-type NormPath = string & { [NORM]: never };
-```
-
-A branded string type representing a normalized absolute path. Can only be created through `norm()`. Useful for ensuring path consistency throughout an application.
-
----
-
-### posix
-
-```typescript
-function posix(...args: string[]): string;
-```
-
-Converts path segments to a POSIX-style path (backslashes replaced with forward slashes). Segments are joined using `path.join()` before conversion.
-
-```typescript
-pathx.posix("C:\\Users\\test");       // "C:/Users/test"
-pathx.posix("src", "index.ts");       // "src/index.ts"
-```
-
----
-
-### changeFileDirectory
-
-```typescript
-function changeFileDirectory(
-  filePath: string,
-  fromDirectory: string,
-  toDirectory: string,
-): string;
-```
-
-Changes the base directory of a file path. Throws `ArgumentError` if `filePath` is not inside `fromDirectory`.
-
-```typescript
-pathx.changeFileDirectory("/a/b/c.txt", "/a", "/x");
-// "/x/b/c.txt"
-```
-
----
-
-### basenameWithoutExt
-
-```typescript
-function basenameWithoutExt(filePath: string): string;
-```
-
-Returns the filename without extension.
-
-```typescript
-pathx.basenameWithoutExt("file.txt");              // "file"
-pathx.basenameWithoutExt("/path/to/file.spec.ts"); // "file.spec"
-```
-
----
-
-### isChildPath
-
-```typescript
-function isChildPath(childPath: string, parentPath: string): boolean;
-```
-
-Checks if `childPath` is a child of `parentPath`. Returns `false` if the paths are identical. Paths are normalized internally.
-
-```typescript
-pathx.isChildPath("/a/b/c", "/a/b"); // true
-pathx.isChildPath("/a/b", "/a/b/c"); // false
-pathx.isChildPath("/a/b", "/a/b");   // false (same path)
-```
-
----
-
-### norm
-
-```typescript
-function norm(...paths: string[]): NormPath;
-```
-
-Normalizes and resolves path segments to an absolute `NormPath`. Uses platform-specific separators.
-
-```typescript
-const p = pathx.norm("/some/path");          // NormPath
-const q = pathx.norm("relative", "path");    // NormPath (resolved to absolute)
-```
-
----
-
-### filterByTargets
-
-```typescript
-function filterByTargets(
-  files: string[],
-  targets: string[],
-  cwd: string,
-): string[];
-```
-
-Filters an array of absolute file paths to only include those that match or are children of the given target paths.
-
-**Parameters:**
-- `files` -- Absolute file paths to filter.
-- `targets` -- Target paths relative to `cwd` (POSIX style recommended).
-- `cwd` -- Current working directory (absolute path).
-
-Returns `files` unmodified if `targets` is empty.
-
-```typescript
-const files = ["/proj/src/a.ts", "/proj/src/b.ts", "/proj/tests/c.ts"];
-pathx.filterByTargets(files, ["src"], "/proj");
-// ["/proj/src/a.ts", "/proj/src/b.ts"]
-```
-
----
-
-## Usage Examples
-
-```typescript
-import { pathx } from "@simplysm/core-node";
-
-// Normalize paths for consistent comparison
-const a = pathx.norm("/project/src/../lib");
-const b = pathx.norm("/project/lib");
-console.log(a === b); // true
-
-// Remap file paths from one directory to another
-const newPath = pathx.changeFileDirectory(
-  "/build/src/utils/helper.ts",
-  "/build/src",
-  "/dist",
-);
-// "/dist/utils/helper.ts"
-
-// Filter files by target directories
-const allFiles = ["/proj/src/a.ts", "/proj/docs/b.md", "/proj/tests/c.ts"];
-const srcOnly = pathx.filterByTargets(allFiles, ["src", "tests"], "/proj");
-// ["/proj/src/a.ts", "/proj/tests/c.ts"]
-```

package/docs/worker.md

@@ -1,209 +0,0 @@
-# Worker
-
-```typescript
-import { createWorker, Worker } from "@simplysm/core-node";
-```
-
-Type-safe wrapper around Node.js `worker_threads`. Define methods in a worker file with `createWorker`, then call them from the main thread via `Worker.create` with full type inference.
-
----
-
-## API Reference
-
-### createWorker
-
-```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;
-};
-```
-
-Factory function for defining a worker module. Must be the default export of the worker file.
-
-**Parameters:**
-- `methods` -- Object mapping method names to handler functions.
-
-**Returns** an object with:
-- `send(event, data?)` -- Sends a custom event from the worker to the main thread.
-- `__methods` / `__events` -- Type-only markers used for inference (not accessed at runtime).
-
----
-
-### Worker.create
-
-```typescript
-const Worker: {
-  create<TModule extends WorkerModule>(
-    filePath: string,
-    opt?: Omit<WorkerOptions, "stdout" | "stderr">,
-  ): WorkerProxy<TModule>;
-};
-```
-
-Creates a type-safe worker proxy. In development (`.ts` files), the worker is executed via `tsx` automatically. In production (`.js` files), the Worker is created directly.
-
-**Parameters:**
-- `filePath` -- Worker file path (absolute path or `file://` URL).
-- `opt` -- Standard `WorkerOptions` (except `stdout`/`stderr`, which are managed internally).
-
-**Returns** a `WorkerProxy` with:
-- All worker methods available as async functions.
-- `on(event, listener)` -- Subscribe to worker events.
-- `off(event, listener)` -- Unsubscribe from worker events.
-- `terminate()` -- Terminates the worker thread.
-
----
-
-### WorkerModule
-
-```typescript
-interface WorkerModule {
-  default: {
-    __methods: Record<string, (...args: any[]) => unknown>;
-    __events: Record<string, unknown>;
-  };
-}
-```
-
-Type structure of a worker module. Used for type inference with `Worker.create<typeof import("./worker")>()`.
-
----
-
-### WorkerProxy
-
-```typescript
-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>;
-};
-```
-
-The proxy type returned by `Worker.create()`. All worker methods are promisified (return `Promise<Awaited<R>>`).
-
----
-
-### PromisifyMethods
-
-```typescript
-type PromisifyMethods<TMethods> = {
-  [K in keyof TMethods]: TMethods[K] extends (...args: infer P) => infer R
-    ? (...args: P) => Promise<Awaited<R>>
-    : never;
-};
-```
-
-Utility type that wraps all method return values in `Promise`. Worker communication is always asynchronous via `postMessage`.
-
----
-
-## Usage Examples
-
-### Basic worker
-
-```typescript
-// math-worker.ts
-import { createWorker } from "@simplysm/core-node";
-
-export default createWorker({
-  add: (a: number, b: number) => a + b,
-  multiply: (a: number, b: number) => a * b,
-});
-```
-
-```typescript
-// main.ts
-import { Worker } from "@simplysm/core-node";
-
-const worker = Worker.create<typeof import("./math-worker")>(
-  new URL("./math-worker.ts", import.meta.url).href,
-);
-
-const sum = await worker.add(10, 20);       // 30
-const product = await worker.multiply(3, 4); // 12
-
-await worker.terminate();
-```
-
-### Worker with events
-
-```typescript
-// process-worker.ts
-import { createWorker } from "@simplysm/core-node";
-
-interface ProcessEvents {
-  progress: number;
-  status: string;
-}
-
-const methods = {
-  processData: async (items: string[]) => {
-    const results: string[] = [];
-    for (let i = 0; i < items.length; i++) {
-      sender.send("progress", ((i + 1) / items.length) * 100);
-      sender.send("status", `Processing ${items[i]}`);
-      results.push(items[i].toUpperCase());
-    }
-    return results;
-  },
-};
-
-const sender = createWorker<typeof methods, ProcessEvents>(methods);
-export default sender;
-```
-
-```typescript
-// main.ts
-import { Worker } from "@simplysm/core-node";
-
-const worker = Worker.create<typeof import("./process-worker")>(
-  new URL("./process-worker.ts", import.meta.url).href,
-);
-
-worker.on("progress", (pct) => {
-  console.log(`Progress: ${pct}%`);
-});
-
-worker.on("status", (msg) => {
-  console.log(`Status: ${msg}`);
-});
-
-const results = await worker.processData(["hello", "world"]);
-// Progress: 50%
-// Status: Processing hello
-// Progress: 100%
-// Status: Processing world
-// results: ["HELLO", "WORLD"]
-
-await worker.terminate();
-```
-
-### Worker with options
-
-```typescript
-const worker = Worker.create<typeof import("./my-worker")>(
-  new URL("./my-worker.ts", import.meta.url).href,
-  {
-    env: { NODE_ENV: "production" },
-    argv: ["--verbose"],
-  },
-);
-```