xypriss 9.11.13 → 9.12.0

package/dist/src/xhsc/PathApi.js

@@ -0,0 +1,389 @@
+/* *****************************************************************************
+ * Nehonix XyPriss System
+ *
+ * ACCESS RESTRICTIONS:
+ * - This software is exclusively for use by Authorized Personnel of NEHONIX
+ * - Intended for Internal Use only within NEHONIX operations
+ * - No rights granted to unauthorized individuals or entities
+ * - All modifications are works made for hire assigned to NEHONIX
+ *
+ * PROHIBITED ACTIVITIES:
+ * - Copying, distributing, or sublicensing without written permission
+ * - Reverse engineering, decompiling, or disassembling
+ * - Creating derivative works without explicit authorization
+ * - External use or commercial distribution outside NEHONIX
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ *
+ * For questions or permissions, contact:
+ * NEHONIX Legal Department
+ * Email: legal@nehonix.com
+ * Website: www.nehonix.com
+ ***************************************************************************** */
+import { createXyprissTempDir, generateXUserTmpDir, } from "../plugins/const/XyprissTempDir";
+/**
+ * **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 class BaseApi {
+    /**
+     * Initializes the Base API with a shared runner instance.
+     * @param runner - The XyPrissRunner used to invoke native XHSC binaries.
+     */
+    constructor(runner) {
+        this.runner = runner;
+    }
+}
+/**
+ * **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 class PathApi extends BaseApi {
+    constructor() {
+        super(...arguments);
+        /**
+         * **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)
+         */
+        this.resolve = (...paths) => this.runner.runSync("path", "resolve", paths);
+        /**
+         * **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"
+         */
+        this.join = (...paths) => this.runner.runSync("path", "join", paths);
+        /**
+         * **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"
+         */
+        this.dirname = (p) => this.runner.runSync("path", "dirname", [p]);
+        /**
+         * **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"
+         */
+        this.basename = (p, suffix) => this.runner.runSync("path", "basename", suffix ? [p, suffix] : [p]);
+        /**
+         * **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!");
+         * }
+         */
+        this.extname = (p) => this.runner.runSync("path", "extname", [p]);
+        /**
+         * **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"
+         */
+        this.relative = (from, to) => this.runner.runSync("path", "relative", [from, to]);
+        /**
+         * **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"
+         */
+        this.normalize = (p) => this.runner.runSync("path", "normalize", [p]);
+        /**
+         * **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.
+         */
+        this.isChild = (parent, child) => this.runner.runSync("path", "is-child", [parent, child]);
+        /**
+         * **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.
+         */
+        this.secureJoin = (base, ...segments) => this.runner.runSync("path", "secure-join", [base, ...segments]);
+        /**
+         * **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 }
+         */
+        this.metadata = (p) => this.runner.runSync("path", "metadata", [p]);
+        /**
+         * **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.
+         */
+        this.toNamespacedPath = (p) => this.runner.runSync("path", "to-namespaced", [p]);
+        /**
+         * **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.
+         */
+        this.normalizeSeparators = (p) => this.runner.runSync("path", "normalize-separators", [p]);
+        /**
+         * **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.
+         */
+        this.commonBase = (...paths) => this.runner.runSync("path", "common-base", paths);
+        /**
+         * **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.
+         */
+        this.isAbsolute = (p) => this.runner.runSync("path", "is-absolute", [p]);
+        /**
+         * **Get System Temp Directory**
+         */
+        this.tempDir = () => {
+            return require("os").tmpdir();
+        };
+        /**
+         * **Check Existence**
+         */
+        this.exist = (p) => {
+            try {
+                const res = this.runner.runSync("fs", "check", [p]);
+                return res?.exists === true;
+            }
+            catch {
+                return false;
+            }
+        };
+        // for compatibility
+        /**
+         * **Check Existence**
+         * @deprecated use exist instead
+         */
+        this.exists = (p) => this.exist(p);
+        /**
+         * **Check if Directory**
+         */
+        this.isDir = (p) => {
+            try {
+                const res = this.runner.runSync("fs", "stats", [p]);
+                return res?.is_dir === true;
+            }
+            catch {
+                return false;
+            }
+        };
+        /**
+         * **Check if File**
+         */
+        this.isFile = (p) => {
+            try {
+                const res = this.runner.runSync("fs", "stats", [p]);
+                return res?.is_file === true;
+            }
+            catch {
+                return false;
+            }
+        };
+        /**
+         * **Check if Symlink**
+         */
+        this.isSymlink = (p) => {
+            try {
+                const res = this.runner.runSync("fs", "stats", [p]);
+                return res?.is_symlink === true;
+            }
+            catch {
+                return false;
+            }
+        };
+        /**
+         * **Check if Empty**
+         */
+        this.isEmpty = (p) => {
+            try {
+                if (this.isFile(p)) {
+                    const res = this.runner.runSync("fs", "size", [p]);
+                    return res?.bytes === 0;
+                }
+                if (this.isDir(p)) {
+                    const res = this.runner.runSync("fs", "ls", [p]);
+                    return res?.length === 0;
+                }
+                return false;
+            }
+            catch {
+                return false;
+            }
+        };
+    }
+    /**
+     * **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, options = {}) {
+        const args = [path];
+        if (options.tentative !== undefined) {
+            args.push("--tentative", options.tentative.toString());
+        }
+        if (options.verify) {
+            args.push("--verify");
+        }
+        return this.runner.runSync("path", "correct", args);
+    }
+    /**
+     * **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() {
+        return createXyprissTempDir([generateXUserTmpDir()]);
+    }
+}
+//# sourceMappingURL=PathApi.js.map

package/dist/src/xhsc/PathApi.js.map

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

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

@@ -0,0 +1,126 @@
+import { OSApi } from "./OSApi";
+import { FSApi } from "./FSApi";
+import { PathApi } from "./PathApi";
+import { VarsApi } from "./VarsApi";
+import { EnvApi } from "./EnvApi";
+import { UtilsApi } from "./UtilsApi";
+/**
+ * **XyPriss System API (Aggregator)**
+ *
+ * This class serves as the **Logic Aggregator** for the entire XyPriss system interface.
+ * It sits at the top of the inheritance chain:
+ * `XyPrissFS` -> `SysApi` -> `FSApi` -> `PathApi` -> `BaseApi`
+ *
+ * **Architecture:**
+ * Instead of delegating to properties (e.g., `.fs`, `.sys`), this class **inherits**
+ * all methods directly. This creates a "Flat API" structure where all capabilities
+ * are available on the single instance.
+ *
+ * **Usage:**
+ * This class is typically not instantiated directly by the user but is the base
+ * for the global `__sys__` singleton (`__sys__`).
+ *
+ * @class XyPrissFS
+ * @extends SysApi
+ */
+export declare class XyPrissFS {
+    vars: VarsApi;
+    fs: FSApi;
+    path: PathApi;
+    os: OSApi;
+    utils: UtilsApi;
+    protected _internalRoot: string;
+    /**
+     * **Project Root Path**
+     *
+     * The absolute path to the project root directory. This is the primary
+     * resolution anchor for all system operations.
+     */
+    get __root__(): string;
+    /**
+     * **EnvApi — Environment & Security Manager**
+     *
+     * `EnvApi` is the sole authorised gateway for reading and writing environment
+     * variables inside XyPriss applications. It enforces the XyPriss
+     * **Environment Security Shield**, which prevents direct `process.env` access
+     * via a hardened runtime Proxy.
+     *
+     * ---
+     *
+     * ### Security model
+     *
+     * Four independent mechanisms work together:
+     *
+     * **1. Symbol-keyed internal store**
+     * The backing store lives at `globalThis[XY_ENV_STORE_KEY]` where
+     * `XY_ENV_STORE_KEY` is a module-scoped, unexported `Symbol`. There is no
+     * string key to guess or enumerate; external code cannot reach the store
+     * without a direct reference to the Symbol.
+     *
+     * **2. Strict store initialisation guard**
+     * Every read and write method calls `requireStore()`, which throws
+     * {@link EnvStoreError} if the store has not yet been initialised by the
+     * XyPriss bootstrap. This eliminates the silent `process.env` fallback that
+     * would otherwise leak values during the startup race window.
+     *
+     * **3. Value sanitisation**
+     * `set()` rejects values containing CR (`\r`), LF (`\n`), or NUL (`\0`).
+     * These characters can corrupt downstream log sinks, `.env` parsers, and
+     * HTTP header serialisers.
+     *
+     * **4. Shield — Proxy with enumeration hardening**
+     * `process.env` is replaced with a Proxy. Non-whitelisted reads return
+     * `undefined`. The `ownKeys` and `has` traps restrict the apparent key set to
+     * the whitelist, preventing third-party code (loggers, serialisers) from
+     * enumerating the real store through `process.env`.
+     *
+     * ---
+     *
+     * ### Usage
+     *
+     * Do not instantiate this class directly. Use the pre-configured instance
+     * exposed by the framework at `__sys__.__env__`:
+     *
+     * ```typescript
+     * // Reading with a fallback
+     * const port = __sys__.__env__.get("PORT", "3000");
+     *
+     * // Reading a required variable — throws EnvAccessError if absent
+     * const jwtSecret = __sys__.__env__.getStrict("JWT_SECRET");
+     *
+     * // Reading a required variable, also rejecting empty strings
+     * const dbPassword = __sys__.__env__.getStrict("DB_PASSWORD", { rejectEmpty: true });
+     *
+     * // Writing a variable at runtime
+     * __sys__.__env__.set("FEATURE_FLAG_BETA", "true");
+     *
+     * // Checking the execution mode
+     * if (__sys__.__env__.isProduction()) {
+     *   // Apply production hardening
+     * }
+     * ```
+     *
+     * ---
+     *
+     * @see {@link IEnvApi} for the public interface contract.
+     * @see {@link EnvAccessError} for the error thrown by `getStrict`.
+     * @see {@link EnvKeyError} for the error thrown on invalid keys or values.
+     * @see {@link EnvStoreError} for the error thrown when the store is not ready.
+     */
+    __env__: EnvApi;
+    /**
+     * **Initialize System API**
+     *
+     * Sets up the runner bridge with the specified project root.
+     *
+     * @param {Object} context - Initialization context.
+     * @param {string} context.__root__ - Absolute path to the project root directory.
+     * @param {string} [context.__mode__] - Optional execution mode (defaults to "development").
+     */
+    constructor(context: {
+        __root__: string;
+        __mode__?: string;
+        isDynamicEnv?: boolean;
+    });
+}
+//# sourceMappingURL=System.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"System.d.ts","sourceRoot":"","sources":["../../../src/xhsc/System.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAChC,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAChC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAClC,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEtC;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,SAAS;IACX,IAAI,EAAE,OAAO,CAAC;IACd,EAAE,EAAE,KAAK,CAAC;IACV,IAAI,EAAE,OAAO,CAAC;IACd,EAAE,EAAE,KAAK,CAAC;IACV,KAAK,EAAE,QAAQ,CAAC;IAEvB,SAAS,CAAC,aAAa,EAAE,MAAM,CAAC;IAEhC;;;;;OAKG;IACH,IAAW,QAAQ,IAAI,MAAM,CAE5B;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAqEG;IACI,OAAO,EAAE,MAAM,CAAC;IAEvB;;;;;;;;OAQG;gBACS,OAAO,EAAE;QACjB,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,YAAY,CAAC,EAAE,OAAO,CAAC;KAC1B;CAeJ"}

package/dist/src/xhsc/System.js

@@ -0,0 +1,58 @@
+import { XyPrissRunner } from "./XyPrissRunner";
+import { OSApi } from "./OSApi";
+import { FSApi } from "./FSApi";
+import { PathApi } from "./PathApi";
+import { VarsApi } from "./VarsApi";
+import { EnvApi } from "./EnvApi";
+import { UtilsApi } from "./UtilsApi";
+import { getCallerProjectRoot } from "../utils/ProjectDiscovery";
+/**
+ * **XyPriss System API (Aggregator)**
+ *
+ * This class serves as the **Logic Aggregator** for the entire XyPriss system interface.
+ * It sits at the top of the inheritance chain:
+ * `XyPrissFS` -> `SysApi` -> `FSApi` -> `PathApi` -> `BaseApi`
+ *
+ * **Architecture:**
+ * Instead of delegating to properties (e.g., `.fs`, `.sys`), this class **inherits**
+ * all methods directly. This creates a "Flat API" structure where all capabilities
+ * are available on the single instance.
+ *
+ * **Usage:**
+ * This class is typically not instantiated directly by the user but is the base
+ * for the global `__sys__` singleton (`__sys__`).
+ *
+ * @class XyPrissFS
+ * @extends SysApi
+ */
+export class XyPrissFS {
+    /**
+     * **Project Root Path**
+     *
+     * The absolute path to the project root directory. This is the primary
+     * resolution anchor for all system operations.
+     */
+    get __root__() {
+        return getCallerProjectRoot() || this._internalRoot;
+    }
+    /**
+     * **Initialize System API**
+     *
+     * Sets up the runner bridge with the specified project root.
+     *
+     * @param {Object} context - Initialization context.
+     * @param {string} context.__root__ - Absolute path to the project root directory.
+     * @param {string} [context.__mode__] - Optional execution mode (defaults to "development").
+     */
+    constructor(context) {
+        this._internalRoot = context.__root__;
+        const runner = new XyPrissRunner(context.__root__);
+        this.vars = new VarsApi(runner);
+        this.fs = new FSApi(runner);
+        this.path = new PathApi(runner);
+        this.os = new OSApi(runner);
+        this.utils = new UtilsApi();
+        this.__env__ = new EnvApi(runner, context.__mode__, context.isDynamicEnv || false);
+    }
+}
+//# sourceMappingURL=System.js.map

package/dist/src/xhsc/System.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"System.js","sourceRoot":"","sources":["../../../src/xhsc/System.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAChC,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAChC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAClC,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AACjE;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,OAAO,SAAS;IASlB;;;;;OAKG;IACH,IAAW,QAAQ;QACf,OAAO,oBAAoB,EAAE,IAAI,IAAI,CAAC,aAAa,CAAC;IACxD,CAAC;IA0ED;;;;;;;;OAQG;IACH,YAAY,OAIX;QACG,IAAI,CAAC,aAAa,GAAG,OAAO,CAAC,QAAQ,CAAC;QAEtC,MAAM,MAAM,GAAG,IAAI,aAAa,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QACnD,IAAI,CAAC,IAAI,GAAG,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;QAChC,IAAI,CAAC,EAAE,GAAG,IAAI,KAAK,CAAC,MAAM,CAAC,CAAC;QAC5B,IAAI,CAAC,IAAI,GAAG,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;QAChC,IAAI,CAAC,EAAE,GAAG,IAAI,KAAK,CAAC,MAAM,CAAC,CAAC;QAC5B,IAAI,CAAC,KAAK,GAAG,IAAI,QAAQ,EAAE,CAAC;QAC5B,IAAI,CAAC,OAAO,GAAG,IAAI,MAAM,CACrB,MAAM,EACN,OAAO,CAAC,QAAQ,EAChB,OAAO,CAAC,YAAY,IAAI,KAAK,CAChC,CAAC;IACN,CAAC;CACJ"}

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

@@ -0,0 +1,45 @@
+import { StringUtils } from "./utils/StringUtils";
+import { NumberUtils } from "./utils/NumberUtils";
+import { DateUtils } from "./utils/DateUtils";
+import { ObjectUtils } from "./utils/ObjectUtils";
+import { ArrayUtils } from "./utils/ArrayUtils";
+import { AsyncUtils } from "./utils/AsyncUtils";
+import { ValidationUtils } from "./utils/ValidationUtils";
+import { IdUtils } from "./utils/IdUtils";
+import { FunctionUtils } from "./utils/FunctionUtils";
+/**
+ * **UtilsApi — XyPriss System Utility Module**
+ *
+ * A comprehensive, high-performance utility class for application development.
+ * Utilities are grouped into specialized categories for better modularity.
+ *
+ * Exposed via `__sys__.utils`.
+ *
+ * @example
+ * ```ts
+ * __sys__.utils.num.formatBytes(1048576);      // "1 MB"
+ * __sys__.utils.is.email("test@example.com");  // true
+ * __sys__.utils.id.uuid();                     // "550e8400-e29b-41d4-a716-446655440000"
+ * ```
+ */
+export declare class UtilsApi {
+    /** **String Utilities** (`slugify`, `truncate`, `randomString`, etc.) */
+    readonly str: StringUtils;
+    /** **Number & Math Utilities** (`clamp`, `lerp`, `formatBytes`, etc.) */
+    readonly num: NumberUtils;
+    /** **Date & Time Utilities** (`formatDuration`, `timeAgo`, etc.) */
+    readonly date: DateUtils;
+    /** **Object Utilities** (`deepClone`, `parse`, `pick`, etc.) */
+    readonly obj: ObjectUtils;
+    /** **Array Utilities** (`chunk`, `unique`, `groupBy`, etc.) */
+    readonly arr: ArrayUtils;
+    /** **Async & Control Flow Utilities** (`sleep`, `retry`, `debounce`, etc.) */
+    readonly async: AsyncUtils;
+    /** **Validation Utilities** (`email`, `url`, `nullish`) */
+    readonly is: ValidationUtils;
+    /** **Identity Utilities** (`uuid`) */
+    readonly id: IdUtils;
+    /** **Functional Utilities** (`memo`) */
+    readonly fn: FunctionUtils;
+}
+//# sourceMappingURL=UtilsApi.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"UtilsApi.d.ts","sourceRoot":"","sources":["../../../src/xhsc/UtilsApi.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAC9C,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAChD,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAChD,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC1D,OAAO,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAEtD;;;;;;;;;;;;;;GAcG;AACH,qBAAa,QAAQ;IACjB,yEAAyE;IACzE,SAAgB,GAAG,cAAqB;IAExC,yEAAyE;IACzE,SAAgB,GAAG,cAAqB;IAExC,oEAAoE;IACpE,SAAgB,IAAI,YAAmB;IAEvC,gEAAgE;IAChE,SAAgB,GAAG,cAAqB;IAExC,+DAA+D;IAC/D,SAAgB,GAAG,aAAoB;IAEvC,8EAA8E;IAC9E,SAAgB,KAAK,aAAoB;IAEzC,2DAA2D;IAC3D,SAAgB,EAAE,kBAAyB;IAE3C,sCAAsC;IACtC,SAAgB,EAAE,UAAiB;IAEnC,wCAAwC;IACxC,SAAgB,EAAE,gBAAuB;CAC5C"}