@simplysm/core-node 14.0.4 → 14.0.5

package/README.md

@@ -1,6 +1,6 @@
 # @simplysm/core-node
 
-Core Node.js utilities -- file system operations, path utilities, file watcher, typed worker threads.
+Node.js-specific core utilities for the Simplysm framework. Provides enhanced file system operations, path utilities, file watching, and a type-safe worker thread abstraction.
 
 ## Installation
 
@@ -8,99 +8,122 @@ Core Node.js utilities -- file system operations, path utilities, file watcher,
 npm install @simplysm/core-node
 ```
 
-## API
-
-### fsx -- File System Utilities
-
-Namespace with sync/async file system operations. See [docs/fsx.md](docs/fsx.md) for full API.
-
-| Function | Signature | Description |
-|----------|-----------|-------------|
-| `existsSync` | `(targetPath: string): boolean` | Check if path exists (sync) |
-| `exists` | `(targetPath: string): Promise<boolean>` | Check if path exists (async) |
-| `mkdirSync` | `(targetPath: string): void` | Create directory recursively (sync) |
-| `mkdir` | `(targetPath: string): Promise<void>` | Create directory recursively (async) |
-| `rmSync` | `(targetPath: string): void` | Remove file/directory (sync) |
-| `rm` | `(targetPath: string): Promise<void>` | Remove file/directory with retry (async) |
-| `copySync` | `(sourcePath, targetPath, filter?): void` | Copy file/directory (sync) |
-| `copy` | `(sourcePath, targetPath, filter?): Promise<void>` | Copy file/directory (async) |
-| `readSync` | `(targetPath: string): string` | Read file as UTF-8 string (sync) |
-| `read` | `(targetPath: string): Promise<string>` | Read file as UTF-8 string (async) |
-| `readBufferSync` | `(targetPath: string): Buffer` | Read file as Buffer (sync) |
-| `readBuffer` | `(targetPath: string): Promise<Buffer>` | Read file as Buffer (async) |
-| `readJsonSync` | `<T>(targetPath: string): T` | Read and parse JSON file (sync) |
-| `readJson` | `<T>(targetPath: string): Promise<T>` | Read and parse JSON file (async) |
-| `writeSync` | `(targetPath, data): void` | Write file with auto-mkdir (sync) |
-| `write` | `(targetPath, data): Promise<void>` | Write file with auto-mkdir (async) |
-| `writeJsonSync` | `(targetPath, data, options?): void` | Write JSON file (sync) |
-| `writeJson` | `(targetPath, data, options?): Promise<void>` | Write JSON file (async) |
-| `readdirSync` | `(targetPath: string): string[]` | List directory contents (sync) |
-| `readdir` | `(targetPath: string): Promise<string[]>` | List directory contents (async) |
-| `statSync` | `(targetPath: string): fs.Stats` | Get file info, follows symlinks (sync) |
-| `stat` | `(targetPath: string): Promise<fs.Stats>` | Get file info, follows symlinks (async) |
-| `lstatSync` | `(targetPath: string): fs.Stats` | Get file info, no symlink follow (sync) |
-| `lstat` | `(targetPath: string): Promise<fs.Stats>` | Get file info, no symlink follow (async) |
-| `globSync` | `(pattern, options?): string[]` | Glob file search (sync) |
-| `glob` | `(pattern, options?): Promise<string[]>` | Glob file search (async) |
-| `clearEmptyDirectory` | `(dirPath: string): Promise<void>` | Recursively remove empty directories |
-| `findAllParentChildPathsSync` | `(childGlob, fromPath, rootPath?): string[]` | Search parent dirs for glob matches (sync) |
-| `findAllParentChildPaths` | `(childGlob, fromPath, rootPath?): Promise<string[]>` | Search parent dirs for glob matches (async) |
-
-### pathx -- Path Utilities
-
-Namespace with path manipulation utilities. See [docs/pathx.md](docs/pathx.md) for full API.
-
-| Export | Kind | Description |
-|--------|------|-------------|
-| `NormPath` | type | Branded type for normalized absolute paths |
+## API Overview
+
+### Utilities / fsx
+
+Namespace `fsx` -- Enhanced file system functions (sync and async pairs).
+
+| API | Type | Description |
+|-----|------|-------------|
+| `exists` | function | Check if a path exists (async) |
+| `existsSync` | function | Check if a path exists (sync) |
+| `mkdir` | function | Create directory recursively (async) |
+| `mkdirSync` | function | Create directory recursively (sync) |
+| `rm` | function | Remove file/directory with retry (async) |
+| `rmSync` | function | Remove file/directory (sync) |
+| `copy` | function | Copy file/directory with filter (async) |
+| `copySync` | function | Copy file/directory with filter (sync) |
+| `read` | function | Read file as UTF-8 string (async) |
+| `readSync` | function | Read file as UTF-8 string (sync) |
+| `readBuffer` | function | Read file as Buffer (async) |
+| `readBufferSync` | function | Read file as Buffer (sync) |
+| `readJson` | function | Read and parse JSON file (async) |
+| `readJsonSync` | function | Read and parse JSON file (sync) |
+| `write` | function | Write data to file (async) |
+| `writeSync` | function | Write data to file (sync) |
+| `writeJson` | function | Write data as JSON file (async) |
+| `writeJsonSync` | function | Write data as JSON file (sync) |
+| `readdir` | function | List directory contents (async) |
+| `readdirSync` | function | List directory contents (sync) |
+| `stat` | function | Get file stats, follows symlinks (async) |
+| `statSync` | function | Get file stats, follows symlinks (sync) |
+| `lstat` | function | Get file stats, no symlink follow (async) |
+| `lstatSync` | function | Get file stats, no symlink follow (sync) |
+| `glob` | function | Search files by glob pattern (async) |
+| `globSync` | function | Search files by glob pattern (sync) |
+| `clearEmptyDirectory` | function | Recursively remove empty directories (async) |
+| `findAllParentChildPaths` | function | Search parent dirs for glob matches (async) |
+| `findAllParentChildPathsSync` | function | Search parent dirs for glob matches (sync) |
+
+> See [docs/fsx.md](./docs/fsx.md) for details.
+
+### Utilities / pathx
+
+Namespace `pathx` -- Path manipulation utilities.
+
+| API | Type | Description |
+|-----|------|-------------|
+| `NormPath` | type | Branded string type for normalized paths |
 | `posix` | function | Convert path to POSIX style (backslash to slash) |
-| `changeFileDirectory` | function | Change the directory portion of a file path |
+| `changeFileDirectory` | function | Change a file's parent directory |
 | `basenameWithoutExt` | function | Get filename without extension |
 | `isChildPath` | function | Check if a path is a child of another |
 | `norm` | function | Normalize and resolve path to `NormPath` |
 | `filterByTargets` | function | Filter file paths by target directory prefixes |
 
-### FsWatcher -- File System Watcher
+> See [docs/pathx.md](./docs/pathx.md) for details.
 
-Chokidar-based file watcher with debounced change events. See [docs/fs-watcher.md](docs/fs-watcher.md) for full API.
+### Features
 
-| Export | Kind | Description |
-|--------|------|-------------|
-| `FsWatcherEvent` | type | `"add" \| "addDir" \| "change" \| "unlink" \| "unlinkDir"` |
-| `FsWatcherChangeInfo` | interface | Change event info with path and event type |
-| `FsWatcher` | class | Debounced file system watcher |
+| API | Type | Description |
+|-----|------|-------------|
+| `FsWatcherEvent` | type | File change event type union |
+| `FsWatcherChangeInfo` | interface | File change event info |
+| `FsWatcher` | class | Debounced file system watcher (chokidar-based) |
 
-### Worker -- Typed Worker Threads
+> See [docs/fs-watcher.md](./docs/fs-watcher.md) for details.
 
-Type-safe worker thread wrapper with Proxy-based RPC. See [docs/worker.md](docs/worker.md) for full API.
+### Worker
 
-| Export | Kind | Description |
-|--------|------|-------------|
+| API | Type | Description |
+|-----|------|-------------|
 | `WorkerModule` | interface | Type structure for worker modules |
-| `PromisifyMethods` | type | Maps sync method signatures to async |
+| `PromisifyMethods` | type | Maps sync methods to async (Promise) |
 | `WorkerProxy` | type | Proxy type returned by `Worker.create()` |
 | `WorkerRequest` | interface | Internal worker request message |
-| `WorkerResponse` | type | Internal worker response message (union) |
-| `Worker` | const | Factory object with `create()` method |
-| `createWorker` | function | Define a worker module in a worker thread |
+| `WorkerResponse` | type | Internal worker response message |
+| `Worker` | object | Type-safe worker thread factory |
+| `createWorker` | function | Create a worker module in the worker thread |
 
-## Usage
+> See [docs/worker.md](./docs/worker.md) for details.
 
-```ts
-import { fsx, pathx } from "@simplysm/core-node";
+## Usage Examples
 
-// File system
-await fsx.mkdir("/tmp/mydir");
-await fsx.write("/tmp/mydir/hello.txt", "Hello, world!");
-const content = await fsx.read("/tmp/mydir/hello.txt");
-const config = await fsx.readJson<{ port: number }>("config.json");
+### File system operations
 
-// Path utilities
-const posixPath = pathx.posix("C:\\Users\\test"); // "C:/Users/test"
-const normalized = pathx.norm("/some/path");      // NormPath
+```typescript
+import { fsx } from "@simplysm/core-node";
+
+// Read/write files
+const content = await fsx.read("/path/to/file.txt");
+await fsx.write("/path/to/output.txt", "hello");
+
+// JSON
+const data = await fsx.readJson<{ name: string }>("/path/to/config.json");
+await fsx.writeJson("/path/to/out.json", data, { space: 2 });
+
+// Copy with filter
+await fsx.copy("/src", "/dest", (p) => !p.endsWith(".tmp"));
+
+// Glob
+const tsFiles = await fsx.glob("/project/src/**/*.ts");
+```
+
+### Path utilities
+
+```typescript
+import { pathx } from "@simplysm/core-node";
+
+const p = pathx.posix("C:\\Users\\test"); // "C:/Users/test"
+const name = pathx.basenameWithoutExt("file.spec.ts"); // "file.spec"
 const isChild = pathx.isChildPath("/a/b/c", "/a/b"); // true
+const norm = pathx.norm("/some/path"); // NormPath
+```
 
-// File watcher
+### File watcher
+
+```typescript
 import { FsWatcher } from "@simplysm/core-node";
 
 const watcher = await FsWatcher.watch(["src/**/*.ts"]);
@@ -109,17 +132,23 @@ watcher.onChange({ delay: 300 }, (changes) => {
     console.log(`${event}: ${path}`);
   }
 });
+
 await watcher.close();
+```
 
-// Worker threads
-import { Worker, createWorker } from "@simplysm/core-node";
+### Worker threads
 
+```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();

package/docs/fs-watcher.md

@@ -1,6 +1,6 @@
-# FsWatcher -- File System Watcher
+# FsWatcher
 
-Chokidar-based file system watcher with debounced event delivery and glob filtering.
+Chokidar-based file system watcher with debounced event merging. Short-lived events on the same file are consolidated into a single callback invocation.
 
 ```ts
 import { FsWatcher } from "@simplysm/core-node";
@@ -17,7 +17,7 @@ type FsWatcherEvent = "add" | "addDir" | "change" | "unlink" | "unlinkDir"
 
 Supported file change event types.
 
-### FsWatcherChangeInfo (interface)
+### FsWatcherChangeInfo
 
 ```ts
 interface FsWatcherChangeInfo {
@@ -31,17 +31,17 @@ interface FsWatcherChangeInfo {
 | `event` | `FsWatcherEvent` | The type of change event |
 | `path` | `NormPath` | Normalized absolute path of the changed file/directory |
 
-## FsWatcher (class)
+## FsWatcher
 
-Wraps chokidar to provide debounced file change notifications. Multiple events occurring within a short window are merged and delivered as a single batch.
-
-Event merging strategy:
+Debounced file system watcher. Events occurring within the debounce window are merged using the following strategy:
 - `add` + `change` --> `add` (modification right after creation is treated as creation)
 - `add` + `unlink` --> removed (creation then deletion cancels out)
 - `unlink` + `add` --> `add` (deletion then recreation is treated as creation)
 - Other combinations --> latest event wins
 
-**Note:** `ignoreInitial` is always set to `true` internally. Passing `ignoreInitial: false` triggers an initial callback with an empty array, but does not include the initial file listing.
+The constructor is private; use the static `watch` method.
+
+**Note:** `ignoreInitial` is always forced to `true` internally. If you pass `ignoreInitial: false`, the first `onChange` callback fires with an empty array (initial file listing is not included).
 
 ### Static Methods
 
@@ -54,14 +54,12 @@ static async watch(
 ): Promise<FsWatcher>
 ```
 
-Start watching files/directories. Resolves when the watcher is ready.
+Start watching files/directories (async). Resolves when chokidar emits the `ready` event.
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
-| `paths` | `string[]` | File paths, directory paths, or glob patterns to watch |
-| `options` | `chokidar.ChokidarOptions?` | Chokidar configuration options |
-
-Glob patterns in `paths` are automatically decomposed: the base directory is watched, and events are filtered by the glob pattern using minimatch.
+| `paths` | `string[]` | File/directory paths or glob patterns to watch |
+| `options` | `chokidar.ChokidarOptions` | Chokidar options (except `ignoreInitial`, which is forced `true`) |
 
 ### Instance Methods
 
@@ -74,14 +72,14 @@ onChange(
 ): this
 ```
 
-Register a change event handler. Events are collected for the specified delay duration and delivered as a single batch.
+Register a file change event handler. Events are collected for the specified delay, then delivered as a batch.
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
-| `opt.delay` | `number?` | Debounce delay in milliseconds |
+| `opt.delay` | `number` | Debounce delay in milliseconds |
 | `cb` | `(changeInfos: FsWatcherChangeInfo[]) => void \| Promise<void>` | Callback receiving batched change events |
 
-Returns `this` for chaining.
+**Returns:** `this` for chaining.
 
 #### close
 
@@ -89,7 +87,7 @@ Returns `this` for chaining.
 async close(): Promise<void>
 ```
 
-Stop watching and clean up all debounce queues.
+Stop the watcher and dispose all debounce queues.
 
 ## Usage
 

package/docs/fsx.md

@@ -1,12 +1,13 @@
-# fsx -- File System Utilities
+# fsx
 
-Namespace providing sync and async file system operations with automatic error wrapping, recursive directory creation, and glob support.
+Namespace of enhanced file system functions. All functions wrap Node.js `fs` with error handling (wrapping in `SdError`) and convenience features like recursive directory creation. Most functions come in sync/async pairs.
 
-```ts
+Imported as:
+```typescript
 import { fsx } from "@simplysm/core-node";
 ```
 
-## Functions
+## Existence
 
 ### existsSync
 
@@ -14,7 +15,7 @@ import { fsx } from "@simplysm/core-node";
 function existsSync(targetPath: string): boolean
 ```
 
-Check if a file or directory exists (synchronous).
+Check if a file or directory exists (sync).
 
 ### exists
 
@@ -22,7 +23,9 @@ Check if a file or directory exists (synchronous).
 async function exists(targetPath: string): Promise<boolean>
 ```
 
-Check if a file or directory exists (asynchronous).
+Check if a file or directory exists (async).
+
+## Directory Creation
 
 ### mkdirSync
 
@@ -30,7 +33,7 @@ Check if a file or directory exists (asynchronous).
 function mkdirSync(targetPath: string): void
 ```
 
-Create a directory recursively (synchronous). Equivalent to `mkdir -p`.
+Create a directory recursively (sync).
 
 ### mkdir
 
@@ -38,7 +41,9 @@ Create a directory recursively (synchronous). Equivalent to `mkdir -p`.
 async function mkdir(targetPath: string): Promise<void>
 ```
 
-Create a directory recursively (asynchronous). Equivalent to `mkdir -p`.
+Create a directory recursively (async).
+
+## Removal
 
 ### rmSync
 
@@ -46,7 +51,7 @@ Create a directory recursively (asynchronous). Equivalent to `mkdir -p`.
 function rmSync(targetPath: string): void
 ```
 
-Remove a file or directory recursively (synchronous). Does not retry on failure -- use `rm` if transient errors (e.g., file locks) are expected.
+Remove a file or directory (sync). No retry -- fails immediately on error.
 
 ### rm
 
@@ -54,7 +59,9 @@ Remove a file or directory recursively (synchronous). Does not retry on failure
 async function rm(targetPath: string): Promise<void>
 ```
 
-Remove a file or directory recursively (asynchronous). Retries up to 6 times with 500ms delay on transient errors.
+Remove a file or directory (async). Retries up to 6 times with 500ms delay for transient errors (e.g., file locks).
+
+## Copy
 
 ### copySync
 
@@ -66,12 +73,13 @@ function copySync(
 ): void
 ```
 
-Copy a file or directory recursively (synchronous).
+Copy a file or directory (sync). If `sourcePath` does not exist, returns silently. Directories are copied recursively. An optional filter function controls which children are included.
 
-- If `sourcePath` does not exist, returns silently.
-- `filter` receives the absolute path of each child entry. Return `true` to include, `false` to exclude.
-- The top-level `sourcePath` is not subject to filtering -- only its descendants are.
-- Returning `false` for a directory skips it and all its contents.
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `sourcePath` | `string` | Source path to copy |
+| `targetPath` | `string` | Destination path |
+| `filter` | `(absolutePath: string) => boolean` | Optional filter applied to all children (not the root). Return `true` to include. If a directory returns `false`, it and all contents are skipped. |
 
 ### copy
 
@@ -83,7 +91,9 @@ async function copy(
 ): Promise<void>
 ```
 
-Copy a file or directory recursively (asynchronous). Same semantics as `copySync`.
+Copy a file or directory (async). Same behavior as `copySync`.
+
+## File Reading
 
 ### readSync
 
@@ -91,7 +101,7 @@ Copy a file or directory recursively (asynchronous). Same semantics as `copySync
 function readSync(targetPath: string): string
 ```
 
-Read a file as a UTF-8 string (synchronous).
+Read a file as a UTF-8 string (sync).
 
 ### read
 
@@ -99,7 +109,7 @@ Read a file as a UTF-8 string (synchronous).
 async function read(targetPath: string): Promise<string>
 ```
 
-Read a file as a UTF-8 string (asynchronous).
+Read a file as a UTF-8 string (async).
 
 ### readBufferSync
 
@@ -107,7 +117,7 @@ Read a file as a UTF-8 string (asynchronous).
 function readBufferSync(targetPath: string): Buffer
 ```
 
-Read a file as a `Buffer` (synchronous).
+Read a file as a Buffer (sync).
 
 ### readBuffer
 
@@ -115,7 +125,7 @@ Read a file as a `Buffer` (synchronous).
 async function readBuffer(targetPath: string): Promise<Buffer>
 ```
 
-Read a file as a `Buffer` (asynchronous).
+Read a file as a Buffer (async).
 
 ### readJsonSync
 
@@ -123,7 +133,7 @@ Read a file as a `Buffer` (asynchronous).
 function readJsonSync<TData = unknown>(targetPath: string): TData
 ```
 
-Read and parse a JSON file using `json.parse` from `@simplysm/core-common` (synchronous). On parse failure, the error message includes a preview of the file contents.
+Read and parse a JSON file using `JsonConvert` (sync). On parse failure, the error message includes a preview of the file contents.
 
 ### readJson
 
@@ -131,7 +141,9 @@ Read and parse a JSON file using `json.parse` from `@simplysm/core-common` (sync
 async function readJson<TData = unknown>(targetPath: string): Promise<TData>
 ```
 
-Read and parse a JSON file using `json.parse` from `@simplysm/core-common` (asynchronous). On parse failure, the error message includes a preview of the file contents.
+Read and parse a JSON file using `JsonConvert` (async). On parse failure, the error message includes a preview of the file contents.
+
+## File Writing
 
 ### writeSync
 
@@ -139,7 +151,7 @@ Read and parse a JSON file using `json.parse` from `@simplysm/core-common` (asyn
 function writeSync(targetPath: string, data: string | Uint8Array): void
 ```
 
-Write data to a file (synchronous). Parent directories are created automatically. The file is flushed to disk.
+Write data to a file (sync). Parent directories are created automatically. Uses `flush: true`.
 
 ### write
 
@@ -147,7 +159,7 @@ Write data to a file (synchronous). Parent directories are created automatically
 async function write(targetPath: string, data: string | Uint8Array): Promise<void>
 ```
 
-Write data to a file (asynchronous). Parent directories are created automatically. The file is flushed to disk.
+Write data to a file (async). Parent directories are created automatically. Uses `flush: true`.
 
 ### writeJsonSync
 
@@ -162,12 +174,14 @@ function writeJsonSync(
 ): void
 ```
 
-Serialize data to JSON and write to a file (synchronous). Uses `json.stringify` from `@simplysm/core-common`.
+Write data as a JSON file using `JsonConvert` (sync).
 
-| Option | Type | Description |
-|--------|------|-------------|
-| `replacer` | `(this: unknown, key: string \| undefined, value: unknown) => unknown` | Custom replacer function |
-| `space` | `string \| number` | Indentation (spaces or string) |
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `targetPath` | `string` | Target file path |
+| `data` | `unknown` | Data to serialize |
+| `options.replacer` | `function` | Custom JSON replacer |
+| `options.space` | `string \| number` | Indentation |
 
 ### writeJson
 
@@ -182,7 +196,9 @@ async function writeJson(
 ): Promise<void>
 ```
 
-Serialize data to JSON and write to a file (asynchronous). Uses `json.stringify` from `@simplysm/core-common`. Same options as `writeJsonSync`.
+Write data as a JSON file using `JsonConvert` (async). Same options as `writeJsonSync`.
+
+## Directory Reading
 
 ### readdirSync
 
@@ -190,7 +206,7 @@ Serialize data to JSON and write to a file (asynchronous). Uses `json.stringify`
 function readdirSync(targetPath: string): string[]
 ```
 
-Read directory contents (synchronous). Returns an array of entry names.
+List the contents of a directory (sync). Returns entry names (not full paths).
 
 ### readdir
 
@@ -198,7 +214,9 @@ Read directory contents (synchronous). Returns an array of entry names.
 async function readdir(targetPath: string): Promise<string[]>
 ```
 
-Read directory contents (asynchronous). Returns an array of entry names.
+List the contents of a directory (async). Returns entry names (not full paths).
+
+## File Stats
 
 ### statSync
 
@@ -206,7 +224,7 @@ Read directory contents (asynchronous). Returns an array of entry names.
 function statSync(targetPath: string): fs.Stats
 ```
 
-Get file/directory info (synchronous). Follows symbolic links.
+Get file/directory stats, following symlinks (sync).
 
 ### stat
 
@@ -214,7 +232,7 @@ Get file/directory info (synchronous). Follows symbolic links.
 async function stat(targetPath: string): Promise<fs.Stats>
 ```
 
-Get file/directory info (asynchronous). Follows symbolic links.
+Get file/directory stats, following symlinks (async).
 
 ### lstatSync
 
@@ -222,7 +240,7 @@ Get file/directory info (asynchronous). Follows symbolic links.
 function lstatSync(targetPath: string): fs.Stats
 ```
 
-Get file/directory info (synchronous). Does **not** follow symbolic links.
+Get file/directory stats without following symlinks (sync).
 
 ### lstat
 
@@ -230,7 +248,9 @@ Get file/directory info (synchronous). Does **not** follow symbolic links.
 async function lstat(targetPath: string): Promise<fs.Stats>
 ```
 
-Get file/directory info (asynchronous). Does **not** follow symbolic links.
+Get file/directory stats without following symlinks (async).
+
+## Glob
 
 ### globSync
 
@@ -238,7 +258,12 @@ Get file/directory info (asynchronous). Does **not** follow symbolic links.
 function globSync(pattern: string, options?: GlobOptions): string[]
 ```
 
-Search for files matching a glob pattern (synchronous). Returns absolute paths. Backslashes in the pattern are converted to forward slashes.
+Search files by glob pattern (sync). Returns absolute paths.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `pattern` | `string` | Glob pattern (e.g., `"**/*.ts"`) |
+| `options` | `GlobOptions` | Options passed to the `glob` library |
 
 ### glob
 
@@ -246,7 +271,9 @@ Search for files matching a glob pattern (synchronous). Returns absolute paths.
 async function glob(pattern: string, options?: GlobOptions): Promise<string[]>
 ```
 
-Search for files matching a glob pattern (asynchronous). Returns absolute paths. Backslashes in the pattern are converted to forward slashes.
+Search files by glob pattern (async). Returns absolute paths.
+
+## Utilities
 
 ### clearEmptyDirectory
 
@@ -254,7 +281,7 @@ Search for files matching a glob pattern (asynchronous). Returns absolute paths.
 async function clearEmptyDirectory(dirPath: string): Promise<void>
 ```
 
-Recursively find and remove empty directories under `dirPath`. If removing children causes a parent directory to become empty, it is also removed.
+Recursively find and remove empty directories under a given path (async). When all subdirectories are removed and a parent becomes empty, it is also removed.
 
 ### findAllParentChildPathsSync
 
@@ -266,13 +293,13 @@ function findAllParentChildPathsSync(
 ): string[]
 ```
 
-Walk from `fromPath` toward the filesystem root, collecting all files matching `childGlob` in each directory (synchronous).
+Walk from `fromPath` upward toward the filesystem root, running a glob pattern at each level and collecting all matches (sync).
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
-| `childGlob` | `string` | Glob pattern to match in each directory |
-| `fromPath` | `string` | Starting path for the upward walk |
-| `rootPath` | `string?` | Stop path (defaults to filesystem root). `fromPath` must be a descendant of `rootPath`. |
+| `childGlob` | `string` | Glob pattern to search at each directory level |
+| `fromPath` | `string` | Starting path |
+| `rootPath` | `string` | Optional stop path (must be an ancestor of `fromPath`) |
 
 ### findAllParentChildPaths
 
@@ -284,4 +311,4 @@ async function findAllParentChildPaths(
 ): Promise<string[]>
 ```
 
-Walk from `fromPath` toward the filesystem root, collecting all files matching `childGlob` in each directory (asynchronous). Same parameters as `findAllParentChildPathsSync`.
+Same as `findAllParentChildPathsSync` but asynchronous.

package/docs/pathx.md

@@ -1,8 +1,9 @@
-# pathx -- Path Utilities
+# pathx
 
-Namespace providing path manipulation utilities with normalization, POSIX conversion, and filtering.
+Namespace of path manipulation utilities. Provides normalized path types, POSIX conversion, and directory-based filtering.
 
-```ts
+Imported as:
+```typescript
 import { pathx } from "@simplysm/core-node";
 ```
 
@@ -14,7 +15,7 @@ import { pathx } from "@simplysm/core-node";
 type NormPath = string & { [NORM]: never }
 ```
 
-Branded type representing a normalized absolute path. Can only be created via `norm()`. The brand prevents accidental use of raw strings where a normalized path is expected.
+Branded string type representing a normalized, resolved absolute path. Can only be created via `norm()`.
 
 ## Functions
 
@@ -24,7 +25,7 @@ Branded type representing a normalized absolute path. Can only be created via `n
 function posix(...args: string[]): string
 ```
 
-Convert a path to POSIX style by joining the arguments and replacing backslashes with forward slashes.
+Convert a path to POSIX style (backslashes replaced with forward slashes). Accepts multiple segments which are joined with `path.join`.
 
 ```ts
 pathx.posix("C:\\Users\\test");    // "C:/Users/test"
@@ -41,7 +42,15 @@ function changeFileDirectory(
 ): string
 ```
 
-Change the directory portion of a file path. The file must be inside `fromDirectory`; throws `ArgumentError` otherwise.
+Change the parent directory of a file path. The file must be inside `fromDirectory`.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `filePath` | `string` | File path to transform |
+| `fromDirectory` | `string` | Original parent directory |
+| `toDirectory` | `string` | New parent directory |
+
+**Throws:** `ArgumentError` if `filePath` is not inside `fromDirectory`.
 
 ```ts
 pathx.changeFileDirectory("/a/b/c.txt", "/a", "/x");
@@ -54,7 +63,7 @@ pathx.changeFileDirectory("/a/b/c.txt", "/a", "/x");
 function basenameWithoutExt(filePath: string): string
 ```
 
-Return the filename without its extension.
+Get the filename without its extension (last extension only).
 
 ```ts
 pathx.basenameWithoutExt("file.txt");            // "file"
@@ -81,7 +90,7 @@ pathx.isChildPath("/a/b", "/a/b");   // false (same path)
 function norm(...paths: string[]): NormPath
 ```
 
-Normalize and resolve path segments into an absolute `NormPath`. Uses the platform-specific path separator.
+Normalize and resolve path segments into a `NormPath` (absolute, platform-native separators).
 
 ```ts
 pathx.norm("/some/path");          // NormPath
@@ -98,16 +107,14 @@ function filterByTargets(
 ): string[]
 ```
 
-Filter file paths by target directory prefixes.
+Filter a list of file paths to only include those under the specified target directories. If `targets` is empty, all files are returned.
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
-| `files` | `string[]` | Absolute file paths to filter (must be under `cwd`) |
-| `targets` | `string[]` | Target directory prefixes (relative to `cwd`, POSIX style recommended) |
+| `files` | `string[]` | Absolute file paths to filter (should be under `cwd`) |
+| `targets` | `string[]` | Target directory paths relative to `cwd` (POSIX style recommended) |
 | `cwd` | `string` | Current working directory (absolute path) |
 
-Returns `files` unchanged if `targets` is empty. Otherwise returns only files whose relative path matches or is a child of a target.
-
 ```ts
 const files = ["/proj/src/a.ts", "/proj/src/b.ts", "/proj/tests/c.ts"];
 pathx.filterByTargets(files, ["src"], "/proj");

package/docs/worker.md

@@ -1,6 +1,6 @@
-# Worker -- Typed Worker Threads
+# Worker
 
-Type-safe worker thread wrapper providing Proxy-based RPC and event communication between the main thread and worker threads.
+Type-safe worker thread abstraction built on Node.js `worker_threads`. Provides a Proxy-based API where worker methods are called as if they were local async functions.
 
 ```ts
 import { Worker, createWorker } from "@simplysm/core-node";
@@ -15,7 +15,7 @@ import type {
 
 ## Types
 
-### WorkerModule (interface)
+### WorkerModule
 
 ```ts
 interface WorkerModule {
@@ -26,7 +26,7 @@ interface WorkerModule {
 }
 ```
 
-Type structure representing a worker module. Used with `Worker.create<typeof import("./worker")>()` for type inference.
+Type structure that `createWorker()` returns. Used for type inference in `Worker.create<typeof import("./worker")>()`.
 
 | Field | Type | Description |
 |-------|------|-------------|
@@ -43,7 +43,7 @@ type PromisifyMethods<TMethods> = {
 }
 ```
 
-Utility type that wraps all method return types in `Promise`. Worker methods communicate via `postMessage` and are inherently asynchronous, so even synchronous method signatures are converted to `Promise<Awaited<R>>`.
+Mapped type that wraps all method return types with `Promise<Awaited<R>>`. Worker methods always return promises because they communicate via `postMessage`.
 
 ### WorkerProxy
 
@@ -65,7 +65,7 @@ type WorkerProxy<TModule extends WorkerModule> = PromisifyMethods<
 }
 ```
 
-The proxy type returned by `Worker.create()`. Combines promisified worker methods with event handling and termination.
+The type returned by `Worker.create()`. Combines promisified methods with event subscription and termination.
 
 | Method | Description |
 |--------|-------------|
@@ -73,7 +73,7 @@ The proxy type returned by `Worker.create()`. Combines promisified worker method
 | `off(event, listener)` | Remove an event listener |
 | `terminate()` | Terminate the worker thread |
 
-### WorkerRequest (interface)
+### WorkerRequest
 
 ```ts
 interface WorkerRequest {
@@ -91,7 +91,7 @@ Internal message format sent from the main thread to the worker.
 | `method` | `string` | Name of the method to invoke |
 | `params` | `unknown[]` | Method arguments |
 
-### WorkerResponse (type)
+### WorkerResponse
 
 ```ts
 type WorkerResponse =
@@ -101,7 +101,7 @@ type WorkerResponse =
   | { type: "log"; body: string }
 ```
 
-Internal message format sent from the worker to the main thread. A discriminated union with four variants:
+Internal message format sent from the worker to the main thread. Discriminated union on `type`.
 
 | Variant | Fields | Description |
 |---------|--------|-------------|
@@ -110,9 +110,9 @@ Internal message format sent from the worker to the main thread. A discriminated
 | `event` | `event`, `body?` | Worker-emitted event |
 | `log` | `body` | Redirected stdout output |
 
-## Worker (const)
+## Worker
 
-Factory object for creating type-safe worker proxies.
+Static factory object for creating type-safe worker proxies.
 
 ### Worker.create
 
@@ -130,11 +130,11 @@ Create a type-safe worker proxy.
 | `filePath` | `string` | Worker file path (`file://` URL or absolute path) |
 | `opt` | `Omit<WorkerRawOptions, "stdout" \| "stderr">?` | Node.js `WorkerOptions` (excluding stdout/stderr which are managed internally) |
 
-In development (`.ts` files), the worker is loaded via `tsx`. In production (`.js` files), the worker is loaded directly.
+In development (`.ts` files), the worker is run through `tsx`. In production (`.js` files), the worker is created directly.
 
-Worker stdout/stderr is piped to the main process. On abnormal exit, all pending requests are rejected.
+**Returns:** `WorkerProxy<TModule>` -- Proxy object supporting direct method calls, `on()`, `off()`, and `terminate()`.
 
-## createWorker (function)
+## createWorker
 
 ```ts
 function createWorker<
@@ -152,7 +152,7 @@ function createWorker<
 }
 ```
 
-Define a worker module inside a worker thread file. Returns a sender object that can emit events to the main thread.
+Factory function used inside the worker thread file. Registers method handlers and sets up the message protocol. Returns a sender object for emitting events back to the main thread.
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
@@ -166,7 +166,7 @@ The returned object exposes:
 | `__methods` | Type-level reference to the methods map (used for type inference) |
 | `__events` | Type-level reference to the events map (used for type inference) |
 
-Throws if not running in a worker thread (`parentPort` is null).
+**Throws:** `SdError` if not running in a worker thread (no `parentPort`).
 
 ## Usage
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simplysm/core-node",
-  "version": "14.0.4",
+  "version": "14.0.5",
   "description": "심플리즘 패키지 - 코어 (node)",
   "author": "심플리즘",
   "license": "Apache-2.0",
@@ -25,7 +25,7 @@
     "glob": "^13.0.6",
     "minimatch": "^10.2.4",
     "tsx": "^4.21.0",
-    "@simplysm/core-common": "14.0.4"
+    "@simplysm/core-common": "14.0.5"
   },
   "devDependencies": {
     "@types/node": "^20.19.37"