@simplysm/core-node 13.0.100 → 14.0.4

package/docs/fsx.md

@@ -0,0 +1,287 @@
+# fsx -- File System Utilities
+
+Namespace providing sync and async file system operations with automatic error wrapping, recursive directory creation, and glob support.
+
+```ts
+import { fsx } from "@simplysm/core-node";
+```
+
+## Functions
+
+### existsSync
+
+```ts
+function existsSync(targetPath: string): boolean
+```
+
+Check if a file or directory exists (synchronous).
+
+### exists
+
+```ts
+async function exists(targetPath: string): Promise<boolean>
+```
+
+Check if a file or directory exists (asynchronous).
+
+### mkdirSync
+
+```ts
+function mkdirSync(targetPath: string): void
+```
+
+Create a directory recursively (synchronous). Equivalent to `mkdir -p`.
+
+### mkdir
+
+```ts
+async function mkdir(targetPath: string): Promise<void>
+```
+
+Create a directory recursively (asynchronous). Equivalent to `mkdir -p`.
+
+### rmSync
+
+```ts
+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.
+
+### rm
+
+```ts
+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.
+
+### copySync
+
+```ts
+function copySync(
+  sourcePath: string,
+  targetPath: string,
+  filter?: (absolutePath: string) => boolean,
+): void
+```
+
+Copy a file or directory recursively (synchronous).
+
+- 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.
+
+### copy
+
+```ts
+async function copy(
+  sourcePath: string,
+  targetPath: string,
+  filter?: (absolutePath: string) => boolean,
+): Promise<void>
+```
+
+Copy a file or directory recursively (asynchronous). Same semantics as `copySync`.
+
+### readSync
+
+```ts
+function readSync(targetPath: string): string
+```
+
+Read a file as a UTF-8 string (synchronous).
+
+### read
+
+```ts
+async function read(targetPath: string): Promise<string>
+```
+
+Read a file as a UTF-8 string (asynchronous).
+
+### readBufferSync
+
+```ts
+function readBufferSync(targetPath: string): Buffer
+```
+
+Read a file as a `Buffer` (synchronous).
+
+### readBuffer
+
+```ts
+async function readBuffer(targetPath: string): Promise<Buffer>
+```
+
+Read a file as a `Buffer` (asynchronous).
+
+### readJsonSync
+
+```ts
+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.
+
+### readJson
+
+```ts
+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.
+
+### writeSync
+
+```ts
+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
+
+```ts
+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.
+
+### writeJsonSync
+
+```ts
+function writeJsonSync(
+  targetPath: string,
+  data: unknown,
+  options?: {
+    replacer?: (this: unknown, key: string | undefined, value: unknown) => unknown;
+    space?: string | number;
+  },
+): void
+```
+
+Serialize data to JSON and write to a file (synchronous). Uses `json.stringify` from `@simplysm/core-common`.
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `replacer` | `(this: unknown, key: string \| undefined, value: unknown) => unknown` | Custom replacer function |
+| `space` | `string \| number` | Indentation (spaces or string) |
+
+### writeJson
+
+```ts
+async function writeJson(
+  targetPath: string,
+  data: unknown,
+  options?: {
+    replacer?: (this: unknown, key: string | undefined, value: unknown) => unknown;
+    space?: string | number;
+  },
+): Promise<void>
+```
+
+Serialize data to JSON and write to a file (asynchronous). Uses `json.stringify` from `@simplysm/core-common`. Same options as `writeJsonSync`.
+
+### readdirSync
+
+```ts
+function readdirSync(targetPath: string): string[]
+```
+
+Read directory contents (synchronous). Returns an array of entry names.
+
+### readdir
+
+```ts
+async function readdir(targetPath: string): Promise<string[]>
+```
+
+Read directory contents (asynchronous). Returns an array of entry names.
+
+### statSync
+
+```ts
+function statSync(targetPath: string): fs.Stats
+```
+
+Get file/directory info (synchronous). Follows symbolic links.
+
+### stat
+
+```ts
+async function stat(targetPath: string): Promise<fs.Stats>
+```
+
+Get file/directory info (asynchronous). Follows symbolic links.
+
+### lstatSync
+
+```ts
+function lstatSync(targetPath: string): fs.Stats
+```
+
+Get file/directory info (synchronous). Does **not** follow symbolic links.
+
+### lstat
+
+```ts
+async function lstat(targetPath: string): Promise<fs.Stats>
+```
+
+Get file/directory info (asynchronous). Does **not** follow symbolic links.
+
+### globSync
+
+```ts
+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.
+
+### glob
+
+```ts
+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.
+
+### clearEmptyDirectory
+
+```ts
+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.
+
+### findAllParentChildPathsSync
+
+```ts
+function findAllParentChildPathsSync(
+  childGlob: string,
+  fromPath: string,
+  rootPath?: string,
+): string[]
+```
+
+Walk from `fromPath` toward the filesystem root, collecting all files matching `childGlob` in each directory (synchronous).
+
+| 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`. |
+
+### findAllParentChildPaths
+
+```ts
+async function findAllParentChildPaths(
+  childGlob: string,
+  fromPath: string,
+  rootPath?: string,
+): Promise<string[]>
+```
+
+Walk from `fromPath` toward the filesystem root, collecting all files matching `childGlob` in each directory (asynchronous). Same parameters as `findAllParentChildPathsSync`.

package/docs/pathx.md

@@ -0,0 +1,115 @@
+# pathx -- Path Utilities
+
+Namespace providing path manipulation utilities with normalization, POSIX conversion, and filtering.
+
+```ts
+import { pathx } from "@simplysm/core-node";
+```
+
+## Types
+
+### NormPath
+
+```ts
+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.
+
+## Functions
+
+### posix
+
+```ts
+function posix(...args: string[]): string
+```
+
+Convert a path to POSIX style by joining the arguments and replacing backslashes with forward slashes.
+
+```ts
+pathx.posix("C:\\Users\\test");    // "C:/Users/test"
+pathx.posix("src", "index.ts");   // "src/index.ts"
+```
+
+### changeFileDirectory
+
+```ts
+function changeFileDirectory(
+  filePath: string,
+  fromDirectory: string,
+  toDirectory: string,
+): string
+```
+
+Change the directory portion of a file path. The file must be inside `fromDirectory`; throws `ArgumentError` otherwise.
+
+```ts
+pathx.changeFileDirectory("/a/b/c.txt", "/a", "/x");
+// "/x/b/c.txt"
+```
+
+### basenameWithoutExt
+
+```ts
+function basenameWithoutExt(filePath: string): string
+```
+
+Return the filename without its extension.
+
+```ts
+pathx.basenameWithoutExt("file.txt");            // "file"
+pathx.basenameWithoutExt("/path/to/file.spec.ts"); // "file.spec"
+```
+
+### isChildPath
+
+```ts
+function isChildPath(childPath: string, parentPath: string): boolean
+```
+
+Check if `childPath` is a descendant of `parentPath`. Returns `false` for identical paths. Paths are normalized internally via `norm()`.
+
+```ts
+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
+
+```ts
+function norm(...paths: string[]): NormPath
+```
+
+Normalize and resolve path segments into an absolute `NormPath`. Uses the platform-specific path separator.
+
+```ts
+pathx.norm("/some/path");          // NormPath
+pathx.norm("relative", "path");   // NormPath (resolved to absolute)
+```
+
+### filterByTargets
+
+```ts
+function filterByTargets(
+  files: string[],
+  targets: string[],
+  cwd: string,
+): string[]
+```
+
+Filter file paths by target directory prefixes.
+
+| 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) |
+| `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");
+// ["/proj/src/a.ts", "/proj/src/b.ts"]
+```

package/docs/worker.md

@@ -1,18 +1,23 @@
-# Worker
+# Worker -- Typed Worker Threads
 
-Type-safe `worker_threads` wrapper providing a proxy-based RPC interface for worker threads.
+Type-safe worker thread wrapper providing Proxy-based RPC and event communication between the main thread and worker threads.
 
-```typescript
+```ts
 import { Worker, createWorker } from "@simplysm/core-node";
+import type {
+  WorkerModule,
+  PromisifyMethods,
+  WorkerProxy,
+  WorkerRequest,
+  WorkerResponse,
+} from "@simplysm/core-node";
 ```
 
 ## Types
 
-### `WorkerModule`
+### WorkerModule (interface)
 
-Type structure of the worker module returned by `createWorker()`. Used for type inference in `Worker.create<typeof import("./worker")>()`.
-
-```typescript
+```ts
 interface WorkerModule {
   default: {
     __methods: Record<string, (...args: any[]) => unknown>;
@@ -21,48 +26,56 @@ interface WorkerModule {
 }
 ```
 
-### `PromisifyMethods<TMethods>`
+Type structure representing a worker module. Used with `Worker.create<typeof import("./worker")>()` for type inference.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `default.__methods` | `Record<string, (...args: any[]) => unknown>` | Map of callable worker methods |
+| `default.__events` | `Record<string, unknown>` | Map of event names to event data types |
 
-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>>`.
+### PromisifyMethods
 
-```typescript
+```ts
 type PromisifyMethods<TMethods> = {
   [K in keyof TMethods]: TMethods[K] extends (...args: infer P) => infer R
     ? (...args: P) => Promise<Awaited<R>>
     : never;
-};
+}
 ```
 
-### `WorkerProxy<TModule>`
+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>>`.
 
-Proxy type returned by `Worker.create()`. Provides promisified methods + `on()` + `off()` + `terminate()`.
+### WorkerProxy
 
-```typescript
+```ts
 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`
+The proxy type returned by `Worker.create()`. Combines promisified worker methods with event handling and termination.
+
+| Method | Description |
+|--------|-------------|
+| `on(event, listener)` | Register an event listener |
+| `off(event, listener)` | Remove an event listener |
+| `terminate()` | Terminate the worker thread |
 
-Internal worker request message.
+### WorkerRequest (interface)
 
-```typescript
+```ts
 interface WorkerRequest {
   id: string;
   method: string;
@@ -70,99 +83,141 @@ interface WorkerRequest {
 }
 ```
 
-### `WorkerResponse`
+Internal message format sent from the main thread to the worker.
 
-Internal worker response message.
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | `string` | Unique request identifier (UUID) |
+| `method` | `string` | Name of the method to invoke |
+| `params` | `unknown[]` | Method arguments |
 
-```typescript
+### WorkerResponse (type)
+
+```ts
 type WorkerResponse =
   | { request: WorkerRequest; type: "return"; body?: unknown }
   | { request: WorkerRequest; type: "error"; body: Error }
   | { type: "event"; event: string; body?: unknown }
-  | { type: "log"; body: string };
+  | { type: "log"; body: string }
 ```
 
-## `Worker.create`
+Internal message format sent from the worker to the main thread. A discriminated union with four variants:
 
-Creates a type-safe Worker Proxy.
+| Variant | Fields | Description |
+|---------|--------|-------------|
+| `return` | `request`, `body?` | Successful method return value |
+| `error` | `request`, `body` | Method threw an error |
+| `event` | `event`, `body?` | Worker-emitted event |
+| `log` | `body` | Redirected stdout output |
 
-```typescript
-const Worker = {
-  create<TModule extends WorkerModule>(
-    filePath: string,
-    opt?: Omit<WorkerOptions, "stdout" | "stderr">,
-  ): WorkerProxy<TModule>;
-};
+## Worker (const)
+
+Factory object for creating type-safe worker proxies.
+
+### Worker.create
+
+```ts
+Worker.create<TModule extends WorkerModule>(
+  filePath: string,
+  opt?: Omit<WorkerRawOptions, "stdout" | "stderr">,
+): WorkerProxy<TModule>
 ```
 
-**Parameters:**
-- `filePath` -- Worker file path (file:// URL or absolute path)
-- `opt` -- Worker options
+Create a type-safe worker proxy.
 
-**Returns:** Proxy object (supports direct method calls, `on()`, `off()`, and `terminate()`)
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `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), TypeScript worker files are executed via tsx. In production (`.js` files), Worker is created directly.
+In development (`.ts` files), the worker is loaded via `tsx`. In production (`.js` files), the worker is loaded directly.
 
-## `createWorker`
+Worker stdout/stderr is piped to the main process. On abnormal exit, all pending requests are rejected.
 
-Worker factory for use in worker threads. This is the function called inside the worker file.
+## createWorker (function)
 
-```typescript
+```ts
 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;
+  send<TEventName extends keyof TEvents & string>(
+    event: TEventName,
+    data?: TEvents[TEventName],
+  ): void;
   __methods: TMethods;
   __events: TEvents;
-};
+}
 ```
 
-## Example
+Define a worker module inside a worker thread file. Returns a sender object that can emit events to the main thread.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `methods` | `TMethods` | Object mapping method names to handler functions |
+
+The returned object exposes:
+
+| Property/Method | Description |
+|-----------------|-------------|
+| `send(event, data?)` | Emit a typed event to the main thread |
+| `__methods` | Type-level reference to the methods map (used for type inference) |
+| `__events` | Type-level reference to the events map (used for type inference) |
 
-```typescript
-// worker.ts
+Throws if not running in a worker thread (`parentPort` is null).
+
+## Usage
+
+### Basic worker (no events)
+
+```ts
+// 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,
 });
 
 // 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
+const worker = Worker.create<typeof import("./math-worker")>("./math-worker.ts");
+const sum = await worker.add(10, 20);       // 30
+const product = await worker.multiply(3, 7); // 21
 await worker.terminate();
 ```
 
-### Worker with Events
+### Worker with events
 
-```typescript
-// worker.ts
+```ts
+// process-worker.ts
 import { createWorker } from "@simplysm/core-node";
 
-interface MyEvents {
+interface Events {
   progress: number;
 }
 
 const methods = {
-  calc: (x: number) => {
-    sender.send("progress", 50);
-    return x * 2;
+  processData: (items: string[]) => {
+    for (let i = 0; i < items.length; i++) {
+      // ... process item ...
+      sender.send("progress", ((i + 1) / items.length) * 100);
+    }
+    return items.length;
   },
 };
 
-const sender = createWorker<typeof methods, MyEvents>(methods);
+const sender = createWorker<typeof methods, Events>(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
+import { Worker } from "@simplysm/core-node";
+
+const worker = Worker.create<typeof import("./process-worker")>("./process-worker.ts");
+worker.on("progress", (pct) => console.log(`${pct}% done`));
+const count = await worker.processData(["a", "b", "c"]);
 await worker.terminate();
 ```

package/lib/worker-dev-proxy.js

@@ -0,0 +1,15 @@
+import process from "node:process";
+import { tsImport } from "tsx/esm/api";
+import { pathToFileURL } from "node:url";
+
+// Assume argv[2] contains the actual worker file path
+const workerFile = process.argv[2];
+if (!workerFile) {
+  throw new Error("Worker file path is required as argument!");
+}
+
+// If file:// URL is already passed, use it as-is; otherwise convert
+const workerFileUrl = workerFile.startsWith("file://")
+  ? workerFile
+  : pathToFileURL(workerFile).href;
+await tsImport(workerFileUrl, import.meta.url);