@gesslar/toolkit 3.14.0 → 3.14.1

package/types/node/lib/VDirectoryObject.d.ts

@@ -0,0 +1,132 @@
+/**
+ * VDirectoryObject extends DirectoryObject with constraints that ensure
+ * all operations are restricted to a specific directory tree (the "cap").
+ *
+ * All path operations are validated to ensure they remain within the
+ * cap directory hierarchy for security.
+ *
+ * @augments DirectoryObject
+ */
+export default class VDirectoryObject extends DirectoryObject {
+    /**
+     * Creates a VDirectoryObject from the current working directory.
+     * This is useful when working with pnpx or other tools where you need to
+     * cap at the project's root directory determined at runtime.
+     *
+     * @returns {VDirectoryObject} A VDirectoryObject capped at the current working directory
+     * @example
+     * // When using pnpx or similar tools
+     * const projectRoot = VDirectoryObject.fromCwd()
+     * const srcDir = projectRoot.getDirectory("src")
+     * // srcDir is capped at the project root
+     */
+    static fromCwd(): VDirectoryObject;
+    /**
+     * Constructs a VDirectoryObject instance.
+     *
+     * Without a parent, creates a new cap at the specified real directory location
+     * with virtual path "/". With a parent, the path is resolved relative to the
+     * parent's virtual path (absolute paths treated as cap-relative).
+     *
+     * @param {string} [directory="."] - Real directory path when no parent (becomes cap), or relative/absolute virtual path when parent provided
+     * @param {VDirectoryObject?} [parent] - Optional parent capped directory
+     * @throws {Sass} If parent is provided but not a VDirectoryObject
+     * @example
+     * // Create new capped directory at current directory
+     * const cwd = new VDirectoryObject()
+     * // Virtual path: "/", Real path: process.cwd(), Cap: itself
+     *
+     * @example
+     * // Create new capped directory
+     * const cache = new VDirectoryObject("/home/user/.cache")
+     * // Virtual path: "/", Real path: /home/user/.cache, Cap: itself
+     *
+     * @example
+     * // Create subdirectory with parent
+     * const data = new VDirectoryObject("data", cache)
+     * // Virtual path: /data, Real path: /home/user/.cache/data, Cap: cache
+     *
+     * @example
+     * // Virtual absolute path with parent (treated as cap-relative)
+     * const config = new VDirectoryObject("/etc/config", cache)
+     * // Virtual path: /etc/config, Real path: /home/user/.cache/etc/config, Cap: cache
+     */
+    constructor(directory?: string, source?: any);
+    /**
+     * Indicates whether this directory is capped (constrained to a specific tree).
+     * Always returns true for VDirectoryObject instances.
+     *
+     * @returns {boolean} True for all VDirectoryObject instances
+     * @example
+     * const capped = new TempDirectoryObject("myapp")
+     * console.log(capped.isVirtual) // true
+     *
+     * const regular = new DirectoryObject("/tmp")
+     * console.log(regular.isVirtual) // false
+     */
+    get isVirtual(): boolean;
+    /**
+     * Returns the cap (root) of the capped directory tree.
+     * For root VDirectoryObject instances, returns itself.
+     * For children, returns the inherited cap from the parent chain.
+     *
+     * @returns {VDirectoryObject} The cap directory object (root of the capped tree)
+     * @example
+     * const temp = new TempDirectoryObject("myapp")
+     * console.log(temp.cap === temp) // true (root is its own cap)
+     *
+     * const subdir = temp.getDirectory("data")
+     * console.log(subdir.cap === temp) // true (child inherits parent's cap)
+     */
+    get cap(): VDirectoryObject;
+    /**
+     * Returns a plain DirectoryObject representing the actual filesystem location.
+     * This provides an "escape hatch" from the capped environment to interact
+     * with the real filesystem when needed.
+     *
+     * @returns {DirectoryObject} Uncapped directory object at the real filesystem path
+     * @example
+     * const temp = new TempDirectoryObject("myapp")
+     * const subdir = temp.getDirectory("data")
+     *
+     * // Work within the capped environment (virtual paths)
+     * console.log(subdir.path)        // "/data" (virtual)
+     * subdir.getFile("config.json")   // Stays within cap
+     *
+     * // Break out to real filesystem when needed
+     * console.log(subdir.real.path)   // "/tmp/myapp-ABC123/data" (real)
+     * subdir.real.parent              // Can traverse outside the cap
+     */
+    get real(): DirectoryObject;
+    /**
+     * Returns the parent directory of this capped directory.
+     * Returns null only if this directory is at the cap (the "root" of the capped tree).
+     *
+     * Note: The returned parent is a VDirectoryObject with the same cap.
+     * This maintains the capping behavior throughout the directory hierarchy.
+     *
+     * @returns {VDirectoryObject|null} Parent directory or null if at cap root
+     * @example
+     * const capped = new TempDirectoryObject("myapp")
+     * const subdir = capped.getDirectory("data")
+     * console.log(subdir.parent.path) // Returns parent VDirectoryObject
+     * console.log(capped.parent) // null (at cap root)
+     */
+    get parent(): VDirectoryObject | null;
+    /**
+     * Returns the path of the parent directory.
+     * Returns null if this directory is at the cap root (no parent).
+     *
+     * @returns {string|null} The parent directory path, or null if at cap root
+     * @example
+     * const temp = new TempDirectoryObject("myapp")
+     * console.log(temp.parentPath) // null (at cap root)
+     *
+     * const subdir = temp.getDirectory("data")
+     * console.log(subdir.parentPath) // "/" (parent's virtual path)
+     */
+    get parentPath(): string | null;
+    #private;
+}
+import DirectoryObject from "./DirectoryObject.js";
+//# sourceMappingURL=VDirectoryObject.d.ts.map

package/types/node/lib/VDirectoryObject.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"VDirectoryObject.d.ts","sourceRoot":"","sources":["../../../src/node/lib/VDirectoryObject.js"],"names":[],"mappings":"AAgBA;;;;;;;;GAQG;AACH;IAmEE;;;;;;;;;;;OAWG;IACH,kBAPa,gBAAgB,CAS5B;IA3ED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACH,wBAvBW,MAAM,gBAoDhB;IAkBD;;;;;;;;;;;OAWG;IACH,iBARa,OAAO,CAUnB;IAED;;;;;;;;;;;;OAYG;IACH,WARa,gBAAgB,CAU5B;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,YAba,eAAe,CAe3B;IAED;;;;;;;;;;;;;OAaG;IACH,cAPa,gBAAgB,GAAC,IAAI,CASjC;IAED;;;;;;;;;;;OAWG;IACH,kBARa,MAAM,GAAC,IAAI,CAUvB;;CAEF;4BAzL2B,sBAAsB"}

package/types/node/lib/VFileObject.d.ts

@@ -0,0 +1,33 @@
+/**
+ * VFileObject extends FileObject with virtual path support, maintaining both
+ * a virtual path (relative to cap) and a real filesystem path.
+ *
+ * Virtual files must have a VDirectoryObject parent and cannot exist independently.
+ * All file operations use the real filesystem path while exposing clean virtual paths.
+ *
+ * @property {string} supplied - User-supplied path
+ * @property {string} path - The virtual file path (relative to cap)
+ * @property {URL} url - The file URL
+ * @property {string} name - The file name
+ * @property {string} module - The file name without extension
+ * @property {string} extension - The file extension
+ * @property {boolean} isFile - Always true for files
+ * @property {boolean} isVirtual - Always true for VFileObject instances
+ * @property {VDirectoryObject} parent - The parent virtual directory object
+ * @property {FileObject} real - The real filesystem FileObject
+ * @property {Promise<boolean>} exists - Whether the file exists (async)
+ */
+export default class VFileObject extends FileObject {
+    /**
+     * Constructs a VFileObject instance.
+     *
+     * @param {string} fileName - The file path
+     * @param {VDirectoryObject} parent - The parent virtual directory (required)
+     */
+    constructor(fileName: string, parent: VDirectoryObject);
+    get isVirtual(): boolean;
+    get real(): FileObject;
+    #private;
+}
+import FileObject from "./FileObject.js";
+//# sourceMappingURL=VFileObject.d.ts.map

package/types/node/lib/VFileObject.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"VFileObject.d.ts","sourceRoot":"","sources":["../../../src/node/lib/VFileObject.js"],"names":[],"mappings":"AAUA;;;;;;;;;;;;;;;;;;GAkBG;AAEH;IAGE;;;;;OAKG;IACH,sBAHW,MAAM,UACN,gBAAgB,EAc1B;IAED,yBAEC;IAED,uBAEC;;CACF;uBAtDsB,iBAAiB"}

package/types/node/lib/Valid.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Validation utility class providing type checking and assertion methods.
+ */
+export default class Valid {
+    static "__#private@#restrictedProto": string[];
+    /**
+     * Validates a value against a type. Uses Data.isType.
+     *
+     * @param {unknown} value - The value to validate
+     * @param {string} type - The expected type in the form of "object", "object[]", "object|object[]"
+     * @param {object} [options] - Additional options for validation.
+     */
+    static type(value: unknown, type: string, options?: object): void;
+    /**
+     * Asserts a condition
+     *
+     * @param {boolean} condition - The condition to assert
+     * @param {string} message - The message to display if the condition is not
+     *                           met
+     * @param {number} [arg] - The argument to display if the condition is not
+     *                         met (optional)
+     */
+    static assert(condition: boolean, message: string, arg?: number): void;
+    /**
+     * Protects against prototype pollution by checking keys for dangerous
+     * property names.
+     *
+     * Throws if any restricted prototype properties are found in the keys array.
+     *
+     * @param {Array<string>} keys - Array of property keys to validate
+     * @throws {Sass} If any key matches restricted prototype properties (__proto__, constructor, prototype)
+     */
+    static prototypePollutionProtection(keys: Array<string>): void;
+}
+//# sourceMappingURL=Valid.d.ts.map

package/types/node/lib/Valid.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Valid.d.ts","sourceRoot":"","sources":["../../../src/node/lib/Valid.js"],"names":[],"mappings":"AAWA;;GAEG;AACH;IACE,+CAAmE;IAEnE;;;;;;OAMG;IACH,mBAJW,OAAO,QACP,MAAM,YACN,MAAM,QAYhB;IAED;;;;;;;;OAQG;IACH,yBANW,OAAO,WACP,MAAM,QAEN,MAAM,QAkBhB;IAED;;;;;;;;OAQG;IACH,0CAHW,KAAK,CAAC,MAAM,CAAC,QAYvB;CACF"}