@simplysm/core-node 13.0.100 → 14.0.4

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/tests/utils/fs-watcher.spec.ts

@@ -1,286 +0,0 @@
-import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import path from "path";
-import fs from "fs";
-import os from "os";
-import { FsWatcher } from "../../src/features/fs-watcher";
-
-describe("SdFsWatcher", () => {
-  const testDir = path.join(os.tmpdir(), "fs-watcher-test-" + Date.now());
-  let watcher: FsWatcher | undefined;
-
-  beforeEach(() => {
-    fs.mkdirSync(testDir, { recursive: true });
-  });
-
-  afterEach(async () => {
-    if (watcher != null) {
-      await watcher.close();
-      watcher = undefined;
-    }
-    fs.rmSync(testDir, { recursive: true, force: true });
-  });
-
-  //#region watch
-
-  describe("watch", () => {
-    it("starts watching files", async () => {
-      watcher = await FsWatcher.watch([path.join(testDir, "**/*")]);
-      expect(watcher).toBeDefined();
-    });
-
-  });
-
-  //#endregion
-
-  //#region close
-
-  describe("close", () => {
-    it("closes the watcher", async () => {
-      watcher = await FsWatcher.watch([path.join(testDir, "**/*")]);
-
-      // Test passes if close() completes without error
-      await expect(watcher.close()).resolves.toBeUndefined();
-
-      // Release watcher reference after closing
-      watcher = undefined;
-    });
-  });
-
-  //#endregion
-
-  //#region chaining
-
-  describe("onChange", () => {
-    it("supports onChange method chaining", async () => {
-      watcher = await FsWatcher.watch([path.join(testDir, "**/*")]);
-
-      const fn = vi.fn();
-      const result = watcher.onChange({ delay: 100 }, fn);
-
-      expect(result).toBe(watcher);
-    });
-  });
-
-  //#endregion
-
-  //#region Glob Pattern Filtering
-
-  describe("glob pattern filtering", () => {
-    const DELAY = 300;
-
-    const wait = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
-
-    const waitForChanges = (
-      watcherInstance: FsWatcher,
-      delay: number,
-    ): Promise<Array<{ event: string; path: string }>> => {
-      return new Promise((resolve) => {
-        watcherInstance.onChange({ delay }, (changeInfos) => {
-          resolve(changeInfos.map((c) => ({ event: c.event, path: c.path })));
-        });
-      });
-    };
-
-    it("receives events only for files matching glob pattern", async () => {
-      // Glob pattern that watches only .txt files
-      const globPattern = path.join(testDir, "**/*.txt");
-
-      watcher = await FsWatcher.watch([globPattern]);
-
-      const changesPromise = waitForChanges(watcher, DELAY);
-
-      // Create .txt file (matches)
-      fs.writeFileSync(path.join(testDir, "matched.txt"), "hello");
-
-      // Create .json file (does not match)
-      await wait(50);
-      fs.writeFileSync(path.join(testDir, "ignored.json"), "{}");
-
-      const changes = await changesPromise;
-
-      // Should only receive events for .txt file
-      expect(changes.length).toBe(1);
-      expect(changes[0].path).toContain("matched.txt");
-      expect(changes[0].event).toBe("add");
-    });
-  });
-
-  //#endregion
-
-  //#region Event Merging
-
-  describe("event merging", () => {
-    const DELAY = 300;
-
-    /**
-     * Helper function to wait for specified time.
-     */
-    const wait = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
-
-    /**
-     * Helper function to wait until event callback is called.
-     */
-    const waitForChanges = (
-      watcherInstance: FsWatcher,
-      delay: number,
-    ): Promise<Array<{ event: string; path: string }>> => {
-      return new Promise((resolve) => {
-        watcherInstance.onChange({ delay }, (changeInfos) => {
-          resolve(changeInfos.map((c) => ({ event: c.event, path: c.path })));
-        });
-      });
-    };
-
-    it("returns only add event when file is added then modified", async () => {
-      const testFile = path.join(testDir, "test-add-change.txt");
-
-      watcher = await FsWatcher.watch([testDir]);
-
-      const changesPromise = waitForChanges(watcher, DELAY);
-
-      // Add file
-      fs.writeFileSync(testFile, "initial");
-
-      // Modify file with short interval (must occur within delay)
-      await wait(50);
-      fs.writeFileSync(testFile, "modified");
-
-      // Wait for event callback
-      const changes = await changesPromise;
-
-      // add → change should be merged to add
-      expect(changes.length).toBe(1);
-      expect(changes[0].event).toBe("add");
-    });
-
-    it("produces no events or no changes when file is added then deleted", async () => {
-      const testFile = path.join(testDir, "test-add-unlink.txt");
-
-      watcher = await FsWatcher.watch([testDir]);
-
-      const changes: Array<{ event: string; path: string }> = [];
-      let resolved = false;
-
-      const changesPromise = new Promise<void>((resolve) => {
-        watcher!.onChange({ delay: DELAY }, (changeInfos) => {
-          changes.push(...changeInfos.map((c) => ({ event: c.event, path: c.path })));
-          if (!resolved) {
-            resolved = true;
-            resolve();
-          }
-        });
-      });
-
-      // Add file
-      fs.writeFileSync(testFile, "content");
-
-      // Delete file with short interval
-      await wait(50);
-      fs.unlinkSync(testFile);
-
-      // Wait with timeout (event may not occur)
-      await Promise.race([changesPromise, wait(DELAY + 200)]);
-
-      // add → unlink merged, no events
-      expect(changes.length).toBe(0);
-    });
-
-    it("produces no events or no changes when directory is added then deleted", async () => {
-      const testSubDir = path.join(testDir, "test-addDir-unlinkDir");
-
-      watcher = await FsWatcher.watch([testDir]);
-
-      const changes: Array<{ event: string; path: string }> = [];
-      let resolved = false;
-
-      const changesPromise = new Promise<void>((resolve) => {
-        watcher!.onChange({ delay: DELAY }, (changeInfos) => {
-          changes.push(...changeInfos.map((c) => ({ event: c.event, path: c.path })));
-          if (!resolved) {
-            resolved = true;
-            resolve();
-          }
-        });
-      });
-
-      // Add directory
-      fs.mkdirSync(testSubDir);
-
-      // Delete directory with short interval
-      await wait(50);
-      fs.rmdirSync(testSubDir);
-
-      // Wait with timeout (event may not occur)
-      await Promise.race([changesPromise, wait(DELAY + 200)]);
-
-      // addDir → unlinkDir merged, no events
-      expect(changes.length).toBe(0);
-    });
-
-    it("merges to add event when file is deleted then recreated", async () => {
-      const testFile = path.join(testDir, "test-unlink-add.txt");
-
-      // Pre-create file
-      fs.writeFileSync(testFile, "initial");
-
-      watcher = await FsWatcher.watch([testDir]);
-
-      const changesPromise = waitForChanges(watcher, DELAY);
-
-      // Delete file
-      fs.unlinkSync(testFile);
-
-      // Recreate file with short interval (must occur within delay)
-      await wait(50);
-      fs.writeFileSync(testFile, "recreated");
-
-      // Wait for event callback
-      const changes = await changesPromise;
-
-      // unlink → add/change should be merged to add (overwritten by later event)
-      // Depending on environment, chokidar may only emit change without unlink (WSL2, etc)
-      expect(changes.length).toBe(1);
-      expect(["add", "change"]).toContain(changes[0].event);
-    });
-
-    it("correctly merges events when multiple files are modified", async () => {
-      const file1 = path.join(testDir, "file1.txt");
-      const file2 = path.join(testDir, "file2.txt");
-      const file3 = path.join(testDir, "file3.txt");
-
-      // Pre-create file3 (to trigger change event)
-      fs.writeFileSync(file3, "existing");
-
-      watcher = await FsWatcher.watch([testDir]);
-
-      const changesPromise = waitForChanges(watcher, DELAY);
-
-      // file1: only add
-      fs.writeFileSync(file1, "content1");
-
-      // file2: add then delete (merged and removed)
-      await wait(50);
-      fs.writeFileSync(file2, "content2");
-      await wait(50);
-      fs.unlinkSync(file2);
-
-      // file3: modify
-      await wait(50);
-      fs.writeFileSync(file3, "modified");
-
-      // Wait for event callback
-      const changes = await changesPromise;
-
-      // file1: add, file2: removed by merge, file3: change
-      expect(changes.length).toBe(2);
-
-      const file1Change = changes.find((c) => c.path.endsWith("file1.txt"));
-      const file3Change = changes.find((c) => c.path.endsWith("file3.txt"));
-
-      expect(file1Change?.event).toBe("add");
-      expect(file3Change?.event).toBe("change");
-    });
-  });
-
-  //#endregion
-});