@simplysm/core-node 13.0.100 → 14.0.1

package/docs/fs.md

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

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

@@ -1,168 +0,0 @@
-# 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();
-```