xypriss 9.11.13 → 9.12.0

package/dist/src/xhsc/PathApi.d.ts

@@ -0,0 +1,305 @@
+import { XyPrissRunner } from "./XyPrissRunner";
+/**
+ * **Base API Class**
+ *
+ * Serves as the foundational layer for all XyPriss domain-specific APIs.
+ * It encapsulates the `XyPrissRunner` instance, ensuring that all subclasses
+ * have unified access to the underlying XHSC bridge for high-performance system operations.
+ */
+export declare class BaseApi {
+    protected runner: XyPrissRunner;
+    /**
+     * Initializes the Base API with a shared runner instance.
+     * @param runner - The XyPrissRunner used to invoke native XHSC binaries.
+     */
+    constructor(runner: XyPrissRunner);
+}
+/**
+ * **Professional Path Manipulation API**
+ *
+ * The `PathApi` class provides a comprehensive suite of robust, platform-independent
+ * utilities for working with file and directory paths. By bridging directly to
+ * the XHSC native binary, it ensures rigorous adherence to filesystem standards
+ * across Windows, macOS, and Linux environments.
+ *
+ * **Key Benefits:**
+ * - **Cross-Platform Consistency:** Eliminates separator issues (`/` vs `\`).
+ * - **Security:** Prevents path traversal vulnerabilities via strict normalization.
+ * - **Reliability:** Handles edge cases like trailing slashes and empty segments correctly.
+ *
+ * @class PathApi
+ * @extends BaseApi
+ */
+export declare class PathApi extends BaseApi {
+    /**
+     * **Resolve to Absolute Path**
+     *
+     * Resolves a sequence of path segments into an absolute path. The resulting path
+     * is normalized, meaning all `..` (parent) and `.` (current) references are resolved.
+     *
+     * This method is critical for generating safe, unambiguous file paths relative to
+     * the project root or the current working directory.
+     *
+     * @param {...string[]} paths - A sequence of path segments to resolve.
+     * @returns {string} The resulting absolute path string.
+     *
+     * @example
+     * // Resolving a configuration file relative to the project root
+     * const configPath = __sys__.path.resolve("config", "settings.json");
+     * console.log(configPath);
+     * // Output (Linux): "/home/user/project/config/settings.json"
+     * // Output (Windows): "C:\Users\user\project\config\settings.json"
+     *
+     * @example
+     * // Handling parent directory navigation
+     * const rootPath = __sys__.path.resolve("src", "utils", "../..");
+     * // Output: "/home/user/project" (Back to root)
+     */
+    resolve: (...paths: string[]) => string;
+    /**
+     * **Join Path Segments**
+     *
+     * Joins all given path segments together using the platform-specific separator as a delimiter,
+     * then normalizes the resulting path. This is the preferred way to construct paths
+     * to ensure validity across different operating systems.
+     *
+     * @param {...string[]} paths - A sequence of path segments to join.
+     * @returns {string} The constructed path string.
+     *
+     * @example
+     * // Constructing a path for a log file
+     * const logPath = __sys__.path.join("var", "logs", "app.log");
+     * // Output (Linux): "var/logs/app.log"
+     * // Output (Windows): "var\logs\app.log"
+     */
+    join: (...paths: string[]) => string;
+    /**
+     * **Get Directory Name**
+     *
+     * Returns the directory name of a `path`. Typically used to get the parent folder
+     * of a file. It behavior follows the standard Unix `dirname` command.
+     *
+     * @param {string} p - The path to parse.
+     * @returns {string} The directory portion of the path.
+     *
+     * @example
+     * // Extracting the parent directory
+     * const parentDir = __sys__.path.dirname("/usr/local/bin/node");
+     * console.log(parentDir); // -> "/usr/local/bin"
+     */
+    dirname: (p: string) => string;
+    /**
+     * **Get Base Name**
+     *
+     * Returns the last portion of a `path`. This is commonly used to extract the
+     * filename from a full path. An optional suffix can be provided to remove
+     * the file extension effectively.
+     *
+     * @param {string} p - The path to evaluate.
+     * @param {string} [suffix] - An optional suffix to remove (e.g., ".txt").
+     * @returns {string} The base name (filename) of the path.
+     *
+     * @example
+     * // Getting a filename including extension
+     * const file = __sys__.path.basename("/src/models/user.ts");
+     * console.log(file); // -> "user.ts"
+     *
+     * @example
+     * // Getting a filename without extension
+     * const name = __sys__.path.basename("/src/models/user.ts", ".ts");
+     * console.log(name); // -> "user"
+     */
+    basename: (p: string, suffix?: string) => string;
+    /**
+     * **Get File Extension**
+     *
+     * Returns the extension of the path, including the leading dot (`.`).
+     * The extension is determined from the last portion of the path. If there
+     * is no `.` in the last portion, or if the first character is `.`, exact
+     * behavior mirrors standard library definitions (returning empty string or the dotfile name).
+     *
+     * @param {string} p - The path to evaluate.
+     * @returns {string} The extension of the file (e.g., ".ts", ".json").
+     *
+     * @example
+     * // checking file type
+     * const ext = __sys__.path.extname("data.json");
+     * if (ext === ".json") {
+     *   console.log("It's a JSON file!");
+     * }
+     */
+    extname: (p: string) => string;
+    /**
+     * **Calculate Relative Path**
+     *
+     * Solves the relative path from `from` to `to`.
+     * This is essential when you need to generate import paths or link two files
+     * relative to each other within the filesystem.
+     *
+     * @param {string} from - The source path (start point).
+     * @param {string} to - The destination path.
+     * @returns {string} The relative path string.
+     *
+     * @example
+     * // Finding relationship between two directories
+     * const relative = __sys__.path.relative("/project/src/views", "/project/src/components");
+     * console.log(relative); // -> "../components"
+     */
+    relative: (from: string, to: string) => string;
+    /**
+     * **Normalize Path**
+     *
+     * Normalizes a given path string, resolving `..` and `.` segments.
+     * It also collapses multiple sequential separators (e.g., `//` -> `/`)
+     * and ensures the path is in its simplest standard form.
+     *
+     * @param {string} p - The path to normalize.
+     * @returns {string} The clean, normalized path.
+     *
+     * @example
+     * // Cleaning up a messy path
+     * const clean = __sys__.path.normalize("/users//john/./docs/../images");
+     * console.log(clean); // -> "/users/john/images"
+     */
+    normalize: (p: string) => string;
+    /**
+     * **Check Child Path Relationship**
+     *
+     * Determines if a given `child` path is strictly contained within a `parent` directory.
+     * This is a critical security utility for verifying that file operations remain
+     * within authorized boundaries.
+     *
+     * @param {string} parent - The expected parent directory.
+     * @param {string} child - The path to check.
+     * @returns {boolean} True if child is inside parent.
+     */
+    isChild: (parent: string, child: string) => boolean;
+    /**
+     * **Secure Path Join**
+     *
+     * Joins path segments and ensures the result is strictly within the `base` path.
+     * If the resulting path attempts to escape via traversal (e.g., `../`), it
+     * throws a security error or returns a safe path.
+     *
+     * @param {string} base - The root/base directory.
+     * @param {...string[]} segments - The segments to join.
+     * @returns {string} The joined, safe path.
+     */
+    secureJoin: (base: string, ...segments: string[]) => string;
+    /**
+     * **Get Comprehensive Path Metadata**
+     *
+     * Returns a structured object containing directory, base name, extension,
+     * filename without extension, and absolute status - all in a single high-speed call.
+     *
+     * @param {string} p - The path to evaluate.
+     * @returns {object} Metadata object: { dir, base, ext, name, isAbsolute }
+     */
+    metadata: (p: string) => {
+        dir: string;
+        base: string;
+        ext: string;
+        name: string;
+        isAbsolute: boolean;
+    };
+    /**
+     * **Convert to Namespaced Path**
+     *
+     * Converts the path to a platform-specific namespaced path (e.g., UNC on Windows).
+     * This is essential for handling extremely long paths or network shares natively.
+     *
+     * @param {string} p - The path to convert.
+     * @returns {string} The namespaced path.
+     */
+    toNamespacedPath: (p: string) => string;
+    /**
+     * **Normalize Separators**
+     *
+     * Standardizes all path separators (`/` or `\`) to the current operating system's
+     * primary separator format.
+     *
+     * @param {string} p - The path to handle.
+     * @returns {string} The path with uniform separators.
+     */
+    normalizeSeparators: (p: string) => string;
+    /**
+     * **Identify Common Base Directory**
+     *
+     * Analyzes multiple paths and returns the deepest common directory shared by all.
+     *
+     * @param {...string[]} paths - Multiple paths to analyze.
+     * @returns {string} The shared parent directory.
+     */
+    commonBase: (...paths: string[]) => string;
+    /**
+     * **Check if Path is Absolute**
+     *
+     * Determines if the given path is an absolute path. This is platform-aware,
+     * correctly handling Windows drive letters and Unix root slashes.
+     *
+     * @param {string} p - The path to check.
+     * @returns {boolean} True if the path is absolute, false otherwise.
+     */
+    isAbsolute: (p: string) => boolean;
+    /**
+     * **Smart Path Correction**
+     *
+     * Attempts to fix path inconsistencies, such as doubled segments or redundant separators.
+     * Prioritizes the high-performance XHSC implementation.
+     *
+     * @param p - Path to correct.
+     * @param tentative - Maximum number of correction attempts.
+     */
+    correct(path: string, options?: {
+        tentative?: number;
+        verify?: boolean;
+    }): string;
+    /**
+     * **Get System Temp Directory**
+     */
+    tempDir: () => string;
+    /**
+     * **User-Scoped Temp Directory**
+     *
+     * Resolves and ensures a unique, ephemeral temporary directory scoped
+     * to the current user session under the XyPriss shared temp root
+     * (`<os.tmpdir>/nehonix.xypriss.data/xuser/<hex4>`).
+     *
+     * Each access generates a fresh random sub-path — suited for
+     * short-lived scratch space that must not collide across concurrent
+     * processes or requests.
+     *
+     * @returns {string} Absolute path to the isolated user temp directory.
+     *
+     * @example
+     * const scratch = __sys__.path.tmpUserDir;
+     * __sys__.fs.writeFile(scratch + "/output.json", data);
+     */
+    get tmpUserDir(): string;
+    /**
+     * **Check Existence**
+     */
+    exist: (p: string) => boolean;
+    /**
+     * **Check Existence**
+     * @deprecated use exist instead
+     */
+    exists: (p: string) => boolean;
+    /**
+     * **Check if Directory**
+     */
+    isDir: (p: string) => boolean;
+    /**
+     * **Check if File**
+     */
+    isFile: (p: string) => boolean;
+    /**
+     * **Check if Symlink**
+     */
+    isSymlink: (p: string) => boolean;
+    /**
+     * **Check if Empty**
+     */
+    isEmpty: (p: string) => boolean;
+}
+//# sourceMappingURL=PathApi.d.ts.map

package/dist/src/xhsc/PathApi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PathApi.d.ts","sourceRoot":"","sources":["../../../src/xhsc/PathApi.ts"],"names":[],"mappings":"AAkCA,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAEhD;;;;;;GAMG;AACH,qBAAa,OAAO;IAKJ,SAAS,CAAC,MAAM,EAAE,aAAa;IAJ3C;;;OAGG;gBACmB,MAAM,EAAE,aAAa;CAC9C;AAED;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,OAAQ,SAAQ,OAAO;IAChC;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACI,OAAO,GAAI,GAAG,OAAO,MAAM,EAAE,KAAG,MAAM,CACK;IAElD;;;;;;;;;;;;;;;OAeG;IACI,IAAI,GAAI,GAAG,OAAO,MAAM,EAAE,KAAG,MAAM,CACK;IAE/C;;;;;;;;;;;;;OAaG;IACI,OAAO,GAAI,GAAG,MAAM,KAAG,MAAM,CACY;IAEhD;;;;;;;;;;;;;;;;;;;;OAoBG;IACI,QAAQ,GAAI,GAAG,MAAM,EAAE,SAAS,MAAM,KAAG,MAAM,CACkB;IAExE;;;;;;;;;;;;;;;;;OAiBG;IACI,OAAO,GAAI,GAAG,MAAM,KAAG,MAAM,CACY;IAEhD;;;;;;;;;;;;;;;OAeG;IACI,QAAQ,GAAI,MAAM,MAAM,EAAE,IAAI,MAAM,KAAG,MAAM,CACI;IAExD;;;;;;;;;;;;;;OAcG;IACI,SAAS,GAAI,GAAG,MAAM,KAAG,MAAM,CACY;IAElD;;;;;;;;;;OAUG;IACI,OAAO,GAAI,QAAQ,MAAM,EAAE,OAAO,MAAM,KAAG,OAAO,CACI;IAE7D;;;;;;;;;;OAUG;IACI,UAAU,GAAI,MAAM,MAAM,EAAE,GAAG,UAAU,MAAM,EAAE,KAAG,MAAM,CACG;IAEpE;;;;;;;;OAQG;IACI,QAAQ,GACX,GAAG,MAAM,KACV;QACC,GAAG,EAAE,MAAM,CAAC;QACZ,IAAI,EAAE,MAAM,CAAC;QACb,GAAG,EAAE,MAAM,CAAC;QACZ,IAAI,EAAE,MAAM,CAAC;QACb,UAAU,EAAE,OAAO,CAAC;KACvB,CAAiD;IAElD;;;;;;;;OAQG;IACI,gBAAgB,GAAI,GAAG,MAAM,KAAG,MAAM,CACS;IAEtD;;;;;;;;OAQG;IACI,mBAAmB,GAAI,GAAG,MAAM,KAAG,MAAM,CACa;IAE7D;;;;;;;OAOG;IACI,UAAU,GAAI,GAAG,OAAO,MAAM,EAAE,KAAG,MAAM,CACM;IAEtD;;;;;;;;OAQG;IACI,UAAU,GAAI,GAAG,MAAM,KAAG,OAAO,CACY;IAEpD;;;;;;;;OAQG;IACI,OAAO,CACV,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,CAAA;KAAO,GACvD,MAAM;IAWT;;OAEG;IACI,OAAO,QAAO,MAAM,CAEzB;IAEF;;;;;;;;;;;;;;;;OAgBG;IACH,IAAW,UAAU,IAAI,MAAM,CAE9B;IAED;;OAEG;IACI,KAAK,GAAI,GAAG,MAAM,KAAG,OAAO,CAOjC;IAGF;;;OAGG;IACI,MAAM,GAAI,GAAG,MAAM,KAAG,OAAO,CAAkB;IAEtD;;OAEG;IACI,KAAK,GAAI,GAAG,MAAM,KAAG,OAAO,CAOjC;IAEF;;OAEG;IACI,MAAM,GAAI,GAAG,MAAM,KAAG,OAAO,CAOlC;IAEF;;OAEG;IACI,SAAS,GAAI,GAAG,MAAM,KAAG,OAAO,CAOrC;IAEF;;OAEG;IACI,OAAO,GAAI,GAAG,MAAM,KAAG,OAAO,CAcnC;CACL"}