@simplysm/core-node 13.0.72 → 13.0.74

package/README.md

@@ -2,33 +2,94 @@
 
 Simplysm package - Core module (node)
 
+Node.js utility library providing filesystem helpers, path utilities, a file-system watcher, and a type-safe worker thread abstraction.
+
 ## Installation
 
+```bash
 pnpm add @simplysm/core-node
+```
+
+---
+
+## Table of Contents
+
+- [Filesystem Utilities](#filesystem-utilities)
+- [Path Utilities](#path-utilities)
+- [File System Watcher](#file-system-watcher)
+- [Worker Thread Abstraction](#worker-thread-abstraction)
+
+---
+
+## Filesystem Utilities
+
+[Full documentation: docs/fs.md](docs/fs.md)
+
+Wraps the built-in `fs` module with recursive directory creation, retry logic, glob support, and consistent error wrapping via `SdError`. Both synchronous (`Sync` suffix) and asynchronous variants are provided for all operations.
+
+| Function | Description |
+|----------|-------------|
+| `fsExistsSync` / `fsExists` | Check if a path exists |
+| `fsMkdirSync` / `fsMkdir` | Create directory recursively |
+| `fsRmSync` / `fsRm` | Delete file or directory recursively (async retries on lock) |
+| `fsCopySync` / `fsCopy` | Copy file or directory with optional filter |
+| `fsReadSync` / `fsRead` | Read file as UTF-8 string |
+| `fsReadBufferSync` / `fsReadBuffer` | Read file as `Buffer` |
+| `fsReadJsonSync` / `fsReadJson` | Read and parse a JSON file |
+| `fsWriteSync` / `fsWrite` | Write string or `Uint8Array` to file (auto-creates parent dirs) |
+| `fsWriteJsonSync` / `fsWriteJson` | Serialize and write JSON to file |
+| `fsReaddirSync` / `fsReaddir` | List directory entries |
+| `fsStatSync` / `fsStat` | Get `fs.Stats` following symlinks |
+| `fsLstatSync` / `fsLstat` | Get `fs.Stats` without following symlinks |
+| `fsGlobSync` / `fsGlob` | Find files by glob pattern (returns absolute paths) |
+| `fsClearEmptyDirectory` | Recursively delete empty directories |
+| `fsFindAllParentChildPathsSync` / `fsFindAllParentChildPaths` | Find matching paths by traversing parent directories |
+
+---
+
+## Path Utilities
+
+[Full documentation: docs/path.md](docs/path.md)
+
+Complements the built-in `path` module with normalization, POSIX conversion, and filtering helpers.
+
+| Export | Description |
+|--------|-------------|
+| `NormPath` (type) | Branded string type for normalized absolute paths |
+| `pathNorm` | Resolve segments to an absolute `NormPath` |
+| `pathPosix` | Join and convert to forward-slash POSIX path |
+| `pathChangeFileDirectory` | Re-root a file path to a different base directory |
+| `pathBasenameWithoutExt` | Get filename without extension |
+| `pathIsChildPath` | Check if one path is strictly inside another |
+| `pathFilterByTargets` | Filter absolute paths by a list of relative targets |
+
+---
+
+## File System Watcher
+
+[Full documentation: docs/watcher.md](docs/watcher.md)
 
-## Source Index
+A chokidar-based watcher that debounces rapid events and delivers them as a single batched array to a callback.
 
-### Utils
+| API | Description |
+|-----|-------------|
+| `FsWatcher.watch(paths, options?)` | Start watching; returns a ready `FsWatcher` instance |
+| `watcher.onChange(opt, cb)` | Register a debounced batch-change handler |
+| `watcher.close()` | Stop watching and dispose resources |
 
-| Source | Exports | Description | Test |
-|--------|---------|-------------|------|
-| `src/utils/fs.ts` | `fsExistsSync`, `fsExists`, `fsMkdirSync`, `fsMkdir`, `fsRmSync`, `fsRm`, `fsCopySync`, `fsCopy`, `fsReadSync`, `fsRead`, `fsReadBufferSync`, `fsReadBuffer`, `fsReadJsonSync`, `fsReadJson`, `fsWriteSync`, `fsWrite`, `fsWriteJsonSync`, `fsWriteJson`, `fsReaddirSync`, `fsReaddir`, `fsStatSync`, `fsStat`, `fsLstatSync`, `fsLstat`, `fsGlobSync`, `fsGlob`, `fsClearEmptyDirectory`, `fsFindAllParentChildPathsSync`, `fsFindAllParentChildPaths` | Comprehensive file system utilities (read, write, copy, delete, glob, stat) | `fs.spec.ts` |
-| `src/utils/path.ts` | `NormPath`, `pathPosix`, `pathChangeFileDirectory`, `pathBasenameWithoutExt`, `pathIsChildPath`, `pathNorm`, `pathFilterByTargets` | Path normalization and manipulation utilities for posix-style paths | `path.spec.ts` |
+Related types: `FsWatcherEvent`, `FsWatcherChangeInfo`
 
-### Features
+---
 
-| Source | Exports | Description | Test |
-|--------|---------|-------------|------|
-| `src/features/fs-watcher.ts` | `FsWatcherEvent`, `FsWatcherChangeInfo`, `FsWatcher` | File system watcher with debounced change detection and event filtering | `fs-watcher.spec.ts` |
+## Worker Thread Abstraction
 
-### Worker
+[Full documentation: docs/worker.md](docs/worker.md)
 
-| Source | Exports | Description | Test |
-|--------|---------|-------------|------|
-| `src/worker/types.ts` | `WorkerModule`, `PromisifyMethods`, `WorkerProxy`, `WorkerRequest`, `WorkerResponse` | Type definitions for worker thread message passing and proxy pattern | - |
-| `src/worker/worker.ts` | `Worker` | Worker thread wrapper with method-based RPC and error forwarding | `sd-worker.spec.ts` |
-| `src/worker/create-worker.ts` | `createWorker` | Factory to create a type-safe worker proxy from a module path | `sd-worker.spec.ts` |
+Type-safe RPC bridge over Node.js `worker_threads`. Define methods in a worker file and call them from the main thread with full TypeScript inference.
 
-## License
+| API | Description |
+|-----|-------------|
+| `createWorker(methods)` | Register RPC methods inside a worker file |
+| `Worker.create(filePath, opt?)` | Create a typed proxy to the worker from the main thread |
 
-Apache-2.0
+Related types: `WorkerModule`, `WorkerProxy`, `PromisifyMethods`, `WorkerRequest`, `WorkerResponse`

package/package.json

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