xypriss 9.11.13 → 9.12.0

package/dist/src/xhsc/fs/FSHelpers.js

@@ -0,0 +1,501 @@
+import { FSCore } from "./FSCore";
+/**
+ * **Filesystem Convenience Helpers**
+ */
+export class FSHelpers extends FSCore {
+    constructor() {
+        super(...arguments);
+        /**
+         * **Deep Recursive Directory Listing**
+         *
+         * Explores a directory tree and returns a flat array of all file and
+         * subdirectory paths found. Supports optional filtering.
+         *
+         * @param {string} p - Root path to start recursion.
+         * @param {Function} [filter] - Optional callback to include/exclude paths.
+         * @returns {string[]} Flat list of matching paths.
+         *
+         * @example
+         * const tsFiles = __sys__.fs.lsRecursive("./src", (path) => path.endsWith(".ts"));
+         */
+        this.lsRecursive = (p, filter) => {
+            const files = this.ls(p, { recursive: true });
+            if (Array.isArray(files) &&
+                files.length > 0 &&
+                typeof files[0] !== "string") {
+                return [];
+            }
+            return filter
+                ? files.filter(filter)
+                : files;
+        };
+        /**
+         * **Filter Directories Only**
+         *
+         * Returns a list of directory names within the specified path.
+         *
+         * @param {string} p - Path to scan.
+         * @returns {string[]} List of directory names.
+         */
+        this.lsDirs = (p) => {
+            try {
+                const items = this.ls(p, { stats: true });
+                return items
+                    .filter((item) => item[1].is_dir)
+                    .map((item) => item[0]);
+            }
+            catch {
+                return [];
+            }
+        };
+        /**
+         * **Filter Files Only**
+         *
+         * Returns a list of file names within the specified path.
+         *
+         * @param {string} p - Path to scan.
+         * @returns {string[]} List of file names.
+         */
+        this.lsFiles = (p) => {
+            try {
+                const items = this.ls(p, { stats: true });
+                return items
+                    .filter((item) => item[1].is_file)
+                    .map((item) => item[0]);
+            }
+            catch {
+                return [];
+            }
+        };
+        /**
+         * **Read File (Asynchronous String)**
+         *
+         * Wrapper for `read()` that explicitly returns the content as a string.
+         *
+         * @param {string} p - Path to the file.
+         * @param {BufferEncoding} [encoding='utf8'] - Ignored (system uses native UTF-8).
+         * @returns {Promise<string>} File content string.
+         */
+        this.readFile = async (p, encoding = "utf8") => await this.read(p);
+        /**
+         * **Read File (Synchronous String)**
+         *
+         * Wrapper for `readSync()` that explicitly returns the content as a string.
+         *
+         * @param {string} p - Path to the file.
+         * @param {BufferEncoding} [encoding='utf8'] - Ignored (system uses native UTF-8).
+         * @returns {string} File content string.
+         */
+        this.readFileSync = (p, encoding = "utf8") => this.readSync(p);
+        /**
+         * **Read & Parse JSON (Asynchronous)**
+         *
+         * Reads a file and parses its content into a JavaScript object.
+         *
+         * @template T - Expected object structure.
+         * @param {string} p - Path to the JSON file.
+         * @returns {Promise<T>} Parsed object.
+         */
+        this.readJson = async (p) => JSON.parse(await this.read(p));
+        /**
+         * **Read & Parse JSON (Synchronous)**
+         *
+         * Synchronously reads a file and parses its content into a JavaScript object.
+         *
+         * @template T - Expected object structure.
+         * @param {string} p - Path to the JSON file.
+         * @returns {T} Parsed object.
+         *
+         * @example
+         * const config = __sys__.fs.readJsonSync("package.json");
+         */
+        this.readJsonSync = (p) => JSON.parse(this.readSync(p));
+        /**
+         * **Read File as Binary (Asynchronous)**
+         *
+         * Reads a file and returns its raw binary content as a Node.js Buffer.
+         *
+         * @param {string} p - Path to the file.
+         * @returns {Promise<Buffer>} Binary data.
+         */
+        this.readBytes = async (p) => {
+            const res = (await this.runner.runAsync("fs", "read", [p], {
+                bytes: true,
+            }));
+            const hexData = res?.data !== undefined ? res.data : res;
+            return Buffer.from(hexData, "hex");
+        };
+        /**
+         * **Read File as Binary (Synchronous)**
+         *
+         * Synchronously reads a file and returns its raw binary content as a Node.js Buffer.
+         *
+         * @param {string} p - Path to the file.
+         * @returns {Buffer} Binary data.
+         */
+        this.readBytesSync = (p) => {
+            const res = this.runner.runSync("fs", "read", [p], {
+                bytes: true,
+            });
+            const hexData = res?.data !== undefined ? res.data : res;
+            return Buffer.from(hexData, "hex");
+        };
+        /**
+         * **Write Binary Data (Asynchronous)**
+         *
+         * Writes a Node.js Buffer directly to a file.
+         *
+         * @param {string} p - Destination path.
+         * @param {Buffer} data - Binary data to write.
+         * @returns {Promise<void>}
+         */
+        this.writeBytes = async (p, data) => await this.writeFile(p, data);
+        /**
+         * **Write Binary Data (Synchronous)**
+         *
+         * Synchronously writes a Node.js Buffer directly to a file.
+         *
+         * @param {string} p - Destination path.
+         * @param {Buffer} data - Binary data to write.
+         */
+        this.writeBytesSync = (p, data) => this.writeFileSync(p, data);
+        /**
+         * **Fault-Tolerant JSON Read (Asynchronous)**
+         *
+         * Attempts to read and parse a JSON file. If the file is missing or invalid,
+         * it returns a provided default value instead of throwing.
+         *
+         * @template T - Expected object structure.
+         * @param {string} p - Path to the JSON file.
+         * @param {T} defaultValue - Value to return on failure.
+         * @returns {Promise<T>} Parsed object or default value.
+         */
+        this.readJsonSafe = async (p, defaultValue) => {
+            try {
+                return await this.readJson(p);
+            }
+            catch {
+                return defaultValue;
+            }
+        };
+        /**
+         * **Fault-Tolerant JSON Read (Synchronous)**
+         *
+         * Synchronously attempts to read and parse a JSON file, returning a default
+         * value on any error.
+         *
+         * @template T - Expected object structure.
+         * @param {string} p - Path to the JSON file.
+         * @param {T} defaultValue - Value to return on failure.
+         * @returns {T} Parsed object or default value.
+         */
+        this.readJsonSafeSync = (p, defaultValue) => {
+            try {
+                return this.readJsonSync(p);
+            }
+            catch {
+                return defaultValue;
+            }
+        };
+        /**
+         * **Write Object as JSON (Asynchronous)**
+         *
+         * Serializes an object to JSON and writes it to a file.
+         *
+         * @param {string} p - Destination path.
+         * @param {any} data - Object to serialize.
+         * @returns {Promise<void>}
+         */
+        this.writeJson = async (p, data) => await this.writeFile(p, data);
+        /**
+         * **Write Object as JSON (Synchronous)**
+         *
+         * Synchronously serializes an object to JSON and writes it to a file.
+         *
+         * @param {string} p - Destination path.
+         * @param {any} data - Object to serialize.
+         */
+        this.writeJsonSync = (p, data) => this.writeFileSync(p, data);
+        /**
+         * **Split File into Lines (Asynchronous)**
+         *
+         * Reads a file and splits its content into an array of lines based on
+         * platform-agnostic newline characters.
+         *
+         * @param {string} p - Path to the file.
+         * @returns {Promise<string[]>} Array of lines.
+         */
+        this.readLines = async (p) => {
+            return (await this.read(p)).split(/\r?\n/);
+        };
+        /**
+         * **Split File into Lines (Synchronous)**
+         *
+         * Synchronously reads a file and splits its content into an array of lines.
+         *
+         * @param {string} p - Path to the file.
+         * @returns {string[]} Array of lines.
+         */
+        this.readLinesSync = (p) => {
+            return this.readSync(p).split(/\r?\n/);
+        };
+        /**
+         * **Read Filtered Content (Asynchronous)**
+         *
+         * Reads a file and returns an array containing only non-empty, trimmed lines.
+         *
+         * @param {string} p - Path to the file.
+         * @returns {Promise<string[]>} Array of non-empty lines.
+         */
+        this.readNonEmptyLines = async (p) => {
+            return (await this.readLines(p)).filter((l) => l.trim().length > 0);
+        };
+        /**
+         * **Read Filtered Content (Synchronous)**
+         *
+         * Synchronously reads a file and returns an array of non-empty, trimmed lines.
+         *
+         * @param {string} p - Path to the file.
+         * @returns {string[]} Array of non-empty lines.
+         */
+        this.readNonEmptyLinesSync = (p) => {
+            return this.readLinesSync(p).filter((l) => l.trim().length > 0);
+        };
+        /**
+         * **Append Text to File (Asynchronous)**
+         *
+         * Adds content to the end of a file.
+         *
+         * @param {string} p - Path to the file.
+         * @param {any} data - Content to append.
+         * @returns {Promise<void>}
+         */
+        this.append = async (p, data) => {
+            await this.writeFile(p, data, { append: true });
+        };
+        /**
+         * **Append Text to File (Synchronous)**
+         *
+         * Synchronously adds content to the end of a file.
+         *
+         * @param {string} p - Path to the file.
+         * @param {any} data - Content to append.
+         */
+        this.appendSync = (p, data) => {
+            this.writeFileSync(p, data, { append: true });
+        };
+        /**
+         * **Append Single Line (Asynchronous)**
+         *
+         * Adds content followed by a newline character to the end of a file.
+         *
+         * @param {string} p - Path to the file.
+         * @param {any} line - Line content to append.
+         * @returns {Promise<void>}
+         */
+        this.appendLine = async (p, line) => {
+            await this.writeFile(p, String(line) + "\n", { append: true });
+        };
+        /**
+         * **Append Single Line (Synchronous)**
+         *
+         * Synchronously adds a line of content to the end of a file.
+         *
+         * @param {string} p - Path to the file.
+         * @param {any} line - Line content to append.
+         */
+        this.appendLineSync = (p, line) => {
+            this.writeFileSync(p, String(line) + "\n", { append: true });
+        };
+        /**
+         * **Write If New (Asynchronous)**
+         *
+         * Writes data to a file ONLY if the file does not already exist.
+         *
+         * @param {string} p - Destination path.
+         * @param {any} data - Data to write.
+         * @returns {Promise<boolean>} True if the file was written, false if it already existed.
+         */
+        this.writeIfNotExists = async (p, data) => {
+            if (this.check(p).exists)
+                return false;
+            await this.writeFile(p, data);
+            return true;
+        };
+        /**
+         * **Write If New (Synchronous)**
+         *
+         * Synchronously writes data to a file only if it does not already exist.
+         *
+         * @param {string} p - Destination path.
+         * @param {any} data - Data to write.
+         * @returns {boolean} True if written, false otherwise.
+         */
+        this.writeIfNotExistsSync = (p, data) => {
+            if (this.check(p).exists)
+                return false;
+            this.writeFileSync(p, data);
+            return true;
+        };
+        /**
+         * **Ensure Directory Existence**
+         *
+         * Guarantees that a directory (and all its parents) exists. Does nothing
+         * if the directory is already present.
+         *
+         * @param {string} p - Directory path to ensure.
+         *
+         * @example
+         * __sys__.fs.ensureDir("./data/logs/archive");
+         */
+        this.ensureDir = (p) => {
+            this.mkdir(p, { parents: true });
+        };
+        /**
+         * **Non-Blocking Directory Creation**
+         *
+         * Attempts to create a directory tree. Returns false if the path already exists.
+         *
+         * @param {string} p - Path to create.
+         * @returns {boolean} True if the directory was created.
+         */
+        this.mkdirSafe = (p) => {
+            if (this.check(p).exists)
+                return false;
+            this.mkdir(p, { parents: true });
+            return true;
+        };
+        /**
+         * **List with Absolute Paths**
+         *
+         * Lists directory contents and returns them as a flat array of absolute paths.
+         *
+         * @param {string} p - Directory to scan.
+         * @returns {string[]} List of absolute paths.
+         */
+        this.lsFullPath = (p) => {
+            const root = this.resolve(p);
+            return this.ls(p).map((f) => this.join(root, f));
+        };
+        /**
+         * **Rename Entry**
+         *
+         * Alias for `move()`. Changes the name or location of a file/directory.
+         *
+         * @param {string} oldPath - Current path.
+         * @param {string} newPath - Target path.
+         */
+        this.rename = (oldPath, newPath) => {
+            this.move(oldPath, newPath);
+        };
+        /**
+         * **Clone Entry**
+         *
+         * Creates a copy of a file or directory in the same parent folder with a new name.
+         *
+         * @param {string} p - Original path.
+         * @param {string} newName - New filename or directory name.
+         */
+        this.duplicate = (p, newName) => {
+            const dest = this.join(this.dirname(p), newName);
+            this.copy(p, dest);
+        };
+        /**
+         * **Safe Removal**
+         *
+         * Deletes a file or directory only if it currently exists on the filesystem.
+         *
+         * @param {string} p - Path to remove.
+         */
+        this.rmIfExists = (p) => {
+            if (this.check(p).exists)
+                this.rm(p, { force: true });
+        };
+        /**
+         * **Clear Directory Contents**
+         *
+         * Deletes all files and subdirectories within a directory, but keeps
+         * the empty directory itself.
+         *
+         * @param {string} p - Directory to empty.
+         */
+        this.emptyDir = (p) => {
+            if (this.check(p).exists) {
+                this.rm(p, { force: true });
+                this.mkdir(p);
+            }
+        };
+        /**
+         * **Get Formatted Size String**
+         *
+         * Returns the size of a path in a human-readable format (e.g., '12 MB', '1.2 GB').
+         *
+         * @param {string} p - Path to query.
+         * @returns {string} Human-readable size.
+         */
+        this.sizeHuman = (p) => {
+            return this.size(p, { human: true });
+        };
+        /**
+         * **Get Creation Timestamp**
+         *
+         * Retrieves the exact date and time when the file or directory was created.
+         *
+         * @param {string} p - Path to query.
+         * @returns {Date} Creation date object.
+         */
+        this.createdAt = (p) => {
+            return new Date(this.stats(p).created * 1000);
+        };
+        /**
+         * **Get Last Modification Timestamp**
+         *
+         * Retrieves the exact date and time when the file content or directory
+         * was last changed.
+         *
+         * @param {string} p - Path to query.
+         * @returns {Date} Modification date object.
+         */
+        this.modifiedAt = (p) => {
+            return new Date(this.stats(p).modified * 1000);
+        };
+        /**
+         * **Get Last Access Timestamp**
+         *
+         * Retrieves the exact date and time when the file was last accessed
+         * (read or written).
+         *
+         * @param {string} p - Path to query.
+         * @returns {Date} Access date object.
+         */
+        this.accessedAt = (p) => {
+            return new Date(this.stats(p).accessed * 1000);
+        };
+        /**
+         * **Verify Content Identity**
+         *
+         * Compares two files to see if they have identical content by comparing
+         * their cryptographic hashes.
+         *
+         * @param {string} p1 - First file path.
+         * @param {string} p2 - Second file path.
+         * @returns {boolean} True if content is identical.
+         */
+        this.isSameContent = (p1, p2) => {
+            return this.hash(p1) === this.hash(p2);
+        };
+        /**
+         * **Compare Timestamps**
+         *
+         * Checks if the first path was modified more recently than the second path.
+         *
+         * @param {string} p1 - Primary path.
+         * @param {string} p2 - Path to compare against.
+         * @returns {boolean} True if p1 is newer than p2.
+         */
+        this.isNewer = (p1, p2) => {
+            return this.modifiedAt(p1) > this.modifiedAt(p2);
+        };
+    }
+}
+//# sourceMappingURL=FSHelpers.js.map

package/dist/src/xhsc/fs/FSHelpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FSHelpers.js","sourceRoot":"","sources":["../../../../src/xhsc/fs/FSHelpers.ts"],"names":[],"mappings":"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"}

package/dist/src/xhsc/fs/FSSearch.d.ts

@@ -0,0 +1,77 @@
+import { SearchMatch, BatchRenameChange } from "../types";
+import { FSHelpers } from "./FSHelpers";
+/**
+ * **Filesystem Search & Pattern Matching**
+ */
+export declare class FSSearch extends FSHelpers {
+    /**
+     * **Content Search (Grep)**
+     *
+     * Scans all files within a directory for a specific text pattern.
+     * Extremely fast, leveraging the native engine's parallel search.
+     *
+     * @param {string} dir - Directory to search in.
+     * @param {string} pattern - Text or regex pattern to look for.
+     * @returns {SearchMatch[]} List of matches with line numbers and snippets.
+     *
+     * @example
+     * const matches = __sys__.fs.searchInFiles("./src", "TODO");
+     */
+    searchInFiles: (dir: string, pattern: string) => SearchMatch[];
+    /**
+     * **Filenames Search (Find)**
+     *
+     * Searches for files by name pattern within a directory.
+     *
+     * @param {string} dir - Directory to search in.
+     * @param {string} pattern - Glob or regex pattern for filenames.
+     * @returns {string[]} List of matching file paths.
+     *
+     * @example
+     * const tsFiles = __sys__.fs.findByPattern("./src", "*.ts");
+     */
+    findByPattern: (dir: string, pattern: string) => string[];
+    /**
+     * **Filter by File Extension**
+     *
+     * Retrieves all files within a directory that match the specified extension.
+     *
+     * @param {string} dir - Directory to search in.
+     * @param {string} ext - File extension (e.g., 'png', '.jpg').
+     * @returns {string[]} List of matching file paths.
+     *
+     * @example
+     * const images = __sys__.fs.findByExt("./assets", "png");
+     */
+    findByExt: (dir: string, ext: string) => string[];
+    /**
+     * **Pattern-Based Batch Renaming**
+     *
+     * Renames multiple files at once by replacing occurrences of a pattern
+     * in their filenames.
+     *
+     * @param {string} path - Directory to operate on.
+     * @param {string} pattern - Pattern to match in filenames.
+     * @param {string} replacement - String to replace the pattern with.
+     * @param {boolean} [dryRun=false] - If true, returns the planned changes without applying them.
+     * @returns {number | BatchRenameChange[]} Number of files renamed, or change list if dryRun is true.
+     *
+     * @example
+     * __sys__.fs.batchRename("./logs", "log-", "archive-");
+     */
+    batchRename: (path: string, pattern: string, replacement: string, dryRun?: boolean) => number | BatchRenameChange[];
+    /**
+     * **Recent Modification Discovery**
+     *
+     * Finds files that have been modified within a specific number of hours.
+     *
+     * @param {string} dir - Directory to search in.
+     * @param {number} hours - Time window in hours.
+     * @returns {string[]} List of recently modified file paths.
+     *
+     * @example
+     * const changedInLastDay = __sys__.fs.findModifiedSince("./src", 24);
+     */
+    findModifiedSince: (dir: string, hours: number) => string[];
+}
+//# sourceMappingURL=FSSearch.d.ts.map

package/dist/src/xhsc/fs/FSSearch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FSSearch.d.ts","sourceRoot":"","sources":["../../../../src/xhsc/fs/FSSearch.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAC1D,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAExC;;GAEG;AACH,qBAAa,QAAS,SAAQ,SAAS;IACnC;;;;;;;;;;;;OAYG;IACI,aAAa,GAAI,KAAK,MAAM,EAAE,SAAS,MAAM,KAAG,WAAW,EAAE,CAElE;IAEF;;;;;;;;;;;OAWG;IACI,aAAa,GAAI,KAAK,MAAM,EAAE,SAAS,MAAM,KAAG,MAAM,EAAE,CAE7D;IAEF;;;;;;;;;;;OAWG;IACI,SAAS,GAAI,KAAK,MAAM,EAAE,KAAK,MAAM,KAAG,MAAM,EAAE,CAIrD;IAEF;;;;;;;;;;;;;;OAcG;IACI,WAAW,GACd,MAAM,MAAM,EACZ,SAAS,MAAM,EACf,aAAa,MAAM,EACnB,gBAAc,KACf,MAAM,GAAG,iBAAiB,EAAE,CAM7B;IAEF;;;;;;;;;;;OAWG;IACI,iBAAiB,GAAI,KAAK,MAAM,EAAE,OAAO,MAAM,KAAG,MAAM,EAAE,CAE/D;CACL"}

package/dist/src/xhsc/fs/FSSearch.js

@@ -0,0 +1,95 @@
+import { FSHelpers } from "./FSHelpers";
+/**
+ * **Filesystem Search & Pattern Matching**
+ */
+export class FSSearch extends FSHelpers {
+    constructor() {
+        super(...arguments);
+        /**
+         * **Content Search (Grep)**
+         *
+         * Scans all files within a directory for a specific text pattern.
+         * Extremely fast, leveraging the native engine's parallel search.
+         *
+         * @param {string} dir - Directory to search in.
+         * @param {string} pattern - Text or regex pattern to look for.
+         * @returns {SearchMatch[]} List of matches with line numbers and snippets.
+         *
+         * @example
+         * const matches = __sys__.fs.searchInFiles("./src", "TODO");
+         */
+        this.searchInFiles = (dir, pattern) => {
+            return this.runner.runSync("search", "grep", [dir, pattern]);
+        };
+        /**
+         * **Filenames Search (Find)**
+         *
+         * Searches for files by name pattern within a directory.
+         *
+         * @param {string} dir - Directory to search in.
+         * @param {string} pattern - Glob or regex pattern for filenames.
+         * @returns {string[]} List of matching file paths.
+         *
+         * @example
+         * const tsFiles = __sys__.fs.findByPattern("./src", "*.ts");
+         */
+        this.findByPattern = (dir, pattern) => {
+            return this.runner.runSync("search", "find", [dir], { pattern });
+        };
+        /**
+         * **Filter by File Extension**
+         *
+         * Retrieves all files within a directory that match the specified extension.
+         *
+         * @param {string} dir - Directory to search in.
+         * @param {string} ext - File extension (e.g., 'png', '.jpg').
+         * @returns {string[]} List of matching file paths.
+         *
+         * @example
+         * const images = __sys__.fs.findByExt("./assets", "png");
+         */
+        this.findByExt = (dir, ext) => {
+            const cleanExt = ext.startsWith(".") ? ext : "." + ext;
+            const pattern = ".*\\" + cleanExt + "$";
+            return this.findByPattern(dir, pattern);
+        };
+        /**
+         * **Pattern-Based Batch Renaming**
+         *
+         * Renames multiple files at once by replacing occurrences of a pattern
+         * in their filenames.
+         *
+         * @param {string} path - Directory to operate on.
+         * @param {string} pattern - Pattern to match in filenames.
+         * @param {string} replacement - String to replace the pattern with.
+         * @param {boolean} [dryRun=false] - If true, returns the planned changes without applying them.
+         * @returns {number | BatchRenameChange[]} Number of files renamed, or change list if dryRun is true.
+         *
+         * @example
+         * __sys__.fs.batchRename("./logs", "log-", "archive-");
+         */
+        this.batchRename = (path, pattern, replacement, dryRun = false) => {
+            return this.runner.runSync("search", "rename", [path], {
+                pattern,
+                replacement,
+                dryRun,
+            });
+        };
+        /**
+         * **Recent Modification Discovery**
+         *
+         * Finds files that have been modified within a specific number of hours.
+         *
+         * @param {string} dir - Directory to search in.
+         * @param {number} hours - Time window in hours.
+         * @returns {string[]} List of recently modified file paths.
+         *
+         * @example
+         * const changedInLastDay = __sys__.fs.findModifiedSince("./src", 24);
+         */
+        this.findModifiedSince = (dir, hours) => {
+            return this.runner.runSync("search", "modified", [dir], { hours });
+        };
+    }
+}
+//# sourceMappingURL=FSSearch.js.map