@simplysm/core-node 13.0.81 → 13.0.83

package/README.md

@@ -0,0 +1,48 @@
+# @simplysm/core-node
+
+> Simplysm package - Core module (node)
+
+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
+
+| 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) |
+
+## Quick Example
+
+```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}`);
+  }
+});
+
+// Worker
+const worker = Worker.create<typeof import("./my-worker")>("./my-worker.ts");
+const result = await worker.add(1, 2);
+await worker.terminate();
+```

package/docs/filesystem.md

@@ -0,0 +1,254 @@
+# 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

@@ -0,0 +1,145 @@
+# 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

@@ -0,0 +1,154 @@
+# 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

@@ -0,0 +1,209 @@
+# 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"],
+  },
+);
+```

package/package.json

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