@simplysm/core-node 13.0.97 → 13.0.99

package/README.md

@@ -0,0 +1,112 @@
+# @simplysm/core-node
+
+Simplysm package - Core module (node). Node.js utilities for file system operations, path manipulation, file watching, and type-safe worker threads.
+
+## Installation
+
+```bash
+npm install @simplysm/core-node
+```
+
+## API Overview
+
+### File System Utils (`fsx` namespace)
+
+| API | Type | Description |
+|-----|------|-------------|
+| `existsSync` | function | Check if a file or directory exists (sync) |
+| `exists` | function | Check if a file or directory exists (async) |
+| `mkdirSync` | function | Create a directory recursively (sync) |
+| `mkdir` | function | Create a directory recursively (async) |
+| `rmSync` | function | Delete a file or directory (sync) |
+| `rm` | function | Delete a file or directory with retries (async) |
+| `copySync` | function | Copy a file or directory with optional filter (sync) |
+| `copy` | function | Copy a file or directory with optional filter (async) |
+| `readSync` | function | Read a file as UTF-8 string (sync) |
+| `read` | function | Read a file as UTF-8 string (async) |
+| `readBufferSync` | function | Read a file as Buffer (sync) |
+| `readBuffer` | function | Read a file as Buffer (async) |
+| `readJsonSync` | function | Read a JSON file using JsonConvert (sync) |
+| `readJson` | function | Read a JSON file using JsonConvert (async) |
+| `writeSync` | function | Write data to a file, auto-creates parent dirs (sync) |
+| `write` | function | Write data to a file, auto-creates parent dirs (async) |
+| `writeJsonSync` | function | Write data to a JSON file (sync) |
+| `writeJson` | function | Write data to a JSON file (async) |
+| `readdirSync` | function | Read directory contents (sync) |
+| `readdir` | function | Read directory contents (async) |
+| `statSync` | function | Get file info, follows symlinks (sync) |
+| `stat` | function | Get file info, follows symlinks (async) |
+| `lstatSync` | function | Get file info, no symlink follow (sync) |
+| `lstat` | function | Get file info, no symlink follow (async) |
+| `globSync` | function | Search files by glob pattern (sync) |
+| `glob` | function | Search files by glob pattern (async) |
+| `clearEmptyDirectory` | function | Recursively delete empty directories |
+| `findAllParentChildPathsSync` | function | Search for glob matches traversing parent dirs (sync) |
+| `findAllParentChildPaths` | function | Search for glob matches traversing parent dirs (async) |
+
+-> See [docs/fs.md](./docs/fs.md) for details.
+
+### Path Utils (`pathx` namespace)
+
+| API | Type | Description |
+|-----|------|-------------|
+| `NormPath` | type | Brand type for normalized path |
+| `posix` | function | Convert to POSIX-style path (backslash to forward slash) |
+| `changeFileDirectory` | function | Change the directory of a file path |
+| `basenameWithoutExt` | function | Get filename without extension |
+| `isChildPath` | function | Check if a path is a child of another path |
+| `norm` | function | Normalize path to absolute NormPath |
+| `filterByTargets` | function | Filter files by target path list |
+
+-> See [docs/path.md](./docs/path.md) for details.
+
+### Features
+
+| API | Type | Description |
+|-----|------|-------------|
+| `FsWatcherEvent` | type | File change event type (`add`, `addDir`, `change`, `unlink`, `unlinkDir`) |
+| `FsWatcherChangeInfo` | interface | File change information (`event`, `path`) |
+| `FsWatcher` | class | Chokidar-based file watcher with event merging |
+
+-> See [docs/features.md](./docs/features.md) for details.
+
+### Worker System
+
+| API | Type | Description |
+|-----|------|-------------|
+| `WorkerModule` | interface | Worker module type structure for type inference |
+| `PromisifyMethods` | type | Maps method return values to Promise |
+| `WorkerProxy` | type | Proxy type with promisified methods + on/off/terminate |
+| `WorkerRequest` | interface | Internal worker request message |
+| `WorkerResponse` | type | Internal worker response message |
+| `Worker` | object | Type-safe Worker wrapper with `create()` factory |
+| `createWorker` | function | Worker factory for use in worker threads |
+
+-> See [docs/worker.md](./docs/worker.md) for details.
+
+## Usage Examples
+
+```typescript
+import { fsx, pathx, FsWatcher, Worker, createWorker } from "@simplysm/core-node";
+
+// File system
+const content = await fsx.read("/path/to/file.txt");
+await fsx.write("/path/to/output.txt", content);
+
+// Path utilities
+const normalized = pathx.norm("/some/path");
+const posixPath = pathx.posix("C:\\Users\\test");
+
+// File watching
+const watcher = await FsWatcher.watch(["src/**/*.ts"]);
+watcher.onChange({ delay: 300 }, (changes) => {
+  for (const { path, event } of changes) {
+    // handle changes
+  }
+});
+
+// Workers
+const worker = Worker.create<typeof import("./worker")>("./worker.ts");
+const result = await worker.add(10, 20);
+await worker.terminate();
+```

package/docs/features.md

@@ -0,0 +1,91 @@
+# Features
+
+## FsWatcher
+
+Chokidar-based file system watcher wrapper. Merges events that occur within a short time and calls the callback once.
+
+```typescript
+import { FsWatcher } from "@simplysm/core-node";
+```
+
+### Types
+
+#### `FsWatcherEvent`
+
+File change event type.
+
+```typescript
+type FsWatcherEvent = "add" | "addDir" | "change" | "unlink" | "unlinkDir";
+```
+
+#### `FsWatcherChangeInfo`
+
+File change information.
+
+```typescript
+interface FsWatcherChangeInfo {
+  /** Change event type */
+  event: FsWatcherEvent;
+  /** Changed file/directory path (normalized) */
+  path: NormPath;
+}
+```
+
+### Class: `FsWatcher`
+
+The `ignoreInitial` option of chokidar is internally always set to `true`. If you pass `options.ignoreInitial: false`, the callback will be called with an empty array on the first `onChange` call, but the actual initial file list is not included. This is intentional behavior to prevent conflicts with the event merging logic.
+
+#### `FsWatcher.watch`
+
+Starts watching files (asynchronous). Waits until the ready event is emitted.
+
+```typescript
+static async watch(paths: string[], options?: chokidar.ChokidarOptions): Promise<FsWatcher>;
+```
+
+**Parameters:**
+- `paths` -- Array of file/directory paths or glob patterns to watch
+- `options` -- chokidar options
+
+#### `onChange`
+
+Registers a file change event handler. Collects events for the specified delay time and calls the callback once.
+
+```typescript
+onChange(
+  opt: { delay?: number },
+  cb: (changeInfos: FsWatcherChangeInfo[]) => void | Promise<void>,
+): this;
+```
+
+**Parameters:**
+- `opt.delay` -- Event merge wait time (ms)
+- `cb` -- Change event callback
+
+Event merging strategy:
+- `add` + `change` -> `add` (modification immediately after creation is considered as creation)
+- `add` + `unlink` -> no change (immediate deletion after creation is considered as no change)
+- `unlink` + `add` -> `add` (recreation after deletion is considered as creation)
+- Otherwise -> overwrite with latest event
+
+#### `close`
+
+Closes the file watcher.
+
+```typescript
+async close(): Promise<void>;
+```
+
+### Example
+
+```typescript
+const watcher = await FsWatcher.watch(["src/**/*.ts"]);
+watcher.onChange({ delay: 300 }, (changes) => {
+  for (const { path, event } of changes) {
+    console.log(`${event}: ${path}`);
+  }
+});
+
+// Close
+await watcher.close();
+```

package/docs/fs.md

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

package/docs/path.md

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

package/docs/worker.md

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

package/package.json

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