@gesslar/toolkit 3.22.2 → 3.24.0

package/src/node/lib/VDirectoryObject.js

@@ -1,198 +0,0 @@
-/**
- * @file VDirectoryObject.js
- * @description Abstract base class for directory objects that are constrained
- * to a specific directory tree (the "cap"). This provides security by ensuring
- * all operations remain within the capped directory hierarchy.
- *
- * This class is not intended to be instantiated directly. Use subclasses like
- * TempDirectoryObject that define specific caps.
- */
-
-import path from "node:path"
-
-import DirectoryObject from "./DirectoryObject.js"
-import FileSystem from "./FileSystem.js"
-import Valid from "./Valid.js"
-
-/**
- * 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 {
-  #real
-  #cap
-  #cappedParentPath
-  #cappedParent
-
-  /**
-   * 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, source=null) {
-    Valid.type(source, "Null|VDirectoryObject")
-
-    directory ||= "."
-
-    const baseLocalPath = source?.path ?? "/"
-    const baseRealPath = source?.real.path ?? directory
-
-    if(source && directory.startsWith("/"))
-      directory = directory.slice(1)
-
-    // Find out what directory means to the basePath
-    const realResolved = FileSystem.resolvePath(baseRealPath, directory)
-    const localResolved = source
-      ? FileSystem.resolvePath(baseLocalPath, directory)
-      : path.parse(path.resolve("")).root
-
-    super(localResolved)
-
-    this.#real = new DirectoryObject(realResolved)
-    this.#cap = source?.cap ?? this
-
-    if(source) {
-      this.#cappedParent = source
-      this.#cappedParentPath = source.path
-    } else {
-      this.#cappedParent = null
-      this.#cappedParentPath = null
-    }
-  }
-
-  /**
-   * 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() {
-    return new this(process.cwd())
-  }
-
-  /**
-   * 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() {
-    return true
-  }
-
-  /**
-   * 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() {
-    return this.#cap
-  }
-
-  /**
-   * 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() {
-    return this.#real
-  }
-
-  /**
-   * 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() {
-    return this.#cappedParent
-  }
-
-  /**
-   * 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() {
-    return this.#cappedParentPath
-  }
-
-}

package/src/node/lib/VFileObject.js

@@ -1,110 +0,0 @@
-/**
- * @file VFileObject.js
- * @description Class representing a virtual file within a capped directory tree.
- * Extends FileObject with virtual path support and real filesystem mapping.
- */
-
-import DirectoryObject from "./DirectoryObject.js"
-import FileObject from "./FileObject.js"
-import FS from "./FileSystem.js"
-import Valid from "./Valid.js"
-
-/**
- * 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 {
-  #real
-
-  /**
-   * Constructs a VFileObject instance.
-   *
-   * @param {string} virtualPath - The virtual file path (can be absolute like "/path/to/file.ext" or relative like "file.txt")
-   * @param {VDirectoryObject} parent - The parent virtual directory (required, used for cap reference)
-   */
-  constructor(virtualPath, parent) {
-    Valid.type(virtualPath, "String", {allowEmpty: false})
-    Valid.type(parent, "VDirectoryObject")
-
-    // Normalize the virtual path
-    const normalizedVirtual = FS.fixSlashes(virtualPath)
-    const isAbsolute = normalizedVirtual.startsWith("/")
-
-    // If absolute path, it's already resolved from cap root (from getFile())
-    // If relative path, resolve from parent directory (from hasFile(), read(), etc.)
-    let resolvedVirtualPath
-    if(isAbsolute) {
-      // Absolute path is already resolved - use as-is
-      resolvedVirtualPath = normalizedVirtual
-    } else {
-      // Relative path: resolve from parent directory (not cap root!)
-      resolvedVirtualPath = FS.resolvePath(parent.path, normalizedVirtual)
-    }
-
-    const normalized = FS.fixSlashes(resolvedVirtualPath)
-
-    // Extract the directory and filename from the resolved virtual path
-    const {dir: virtualDir, base} = FS.pathParts(normalized)
-
-    // Determine the virtual parent directory
-    // If virtualDir is "/" or empty or equals cap path, use the cap root
-    // Otherwise, construct the parent directory path relative to cap
-    let virtualParent
-    if(!virtualDir || virtualDir === "/" || virtualDir === parent.cap.path) {
-      virtualParent = parent.cap
-    } else {
-      // virtualDir is something like "/path/to" - we need to create a VDirectoryObject for it
-      // Strip leading "/" if present to make it relative to cap
-      const dirRelativeToCap = virtualDir.startsWith("/") ? virtualDir.slice(1) : virtualDir
-      // Use the VDirectoryObject constructor to create the parent directory
-      virtualParent = new parent.constructor(dirRelativeToCap, parent.cap)
-    }
-
-    // Call super with just the filename and the virtual parent
-    // This ensures FileObject sets up the virtual path correctly
-    super(base, virtualParent)
-
-    // Convert virtual path to real path
-    // The resolved virtual path is relative to the cap root, so we resolve it relative to cap's real path
-    const capRealPath = parent.cap.real.path
-
-    // Strip leading "/" from resolved virtual path if present to make it relative
-    const relativeFromCap = normalized.startsWith("/")
-      ? normalized.slice(1)
-      : normalized
-
-    // Resolve the real filesystem path
-    const realPath = FS.resolvePath(capRealPath, relativeFromCap)
-
-    // Create FileObject with the full real path
-    // Extract directory and filename parts
-    const {dir: realDir, base: realBase} = FS.pathParts(realPath)
-    const realParentDir = new DirectoryObject(realDir)
-
-    this.#real = new FileObject(realBase, realParentDir)
-  }
-
-  get isVirtual() {
-    return true
-  }
-
-  get real() {
-    return this.#real
-  }
-}

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

@@ -1,42 +0,0 @@
-/**
- * TempDirectoryObject extends VDirectoryObject with the cap set to
- * the OS's temporary directory. Temporary directories are created
- * synchronously during construction and exist immediately.
- *
- * All path operations are validated to ensure they remain within the temp
- * directory hierarchy for security.
- *
- * @augments VDirectoryObject
- */
-export default class TempDirectoryObject extends VDirectoryObject {
-    /**
-     * TempDirectoryObject does not support fromCwd() since it is specifically
-     * designed to work within the OS temporary directory tree.
-     *
-     * @throws {Sass} Always throws an error
-     */
-    static fromCwd(): void;
-    get isTemporary(): boolean;
-    get cap(): any;
-    /**
-     * Recursively removes a temporary directory and all its contents.
-     *
-     * This method will delete all files and subdirectories within this directory,
-     * then delete the directory itself. It only works on directories explicitly
-     * marked as temporary for safety.
-     *
-     * @async
-     * @returns {Promise<void>}
-     * @throws {Sass} If the directory is not marked as temporary
-     * @throws {Sass} If the directory deletion fails
-     * @example
-     * const tempDir = new TempDirectoryObject("my-temp")
-     * await tempDir.assureExists()
-     * // ... use the directory ...
-     * await tempDir.remove() // Recursively deletes everything
-     */
-    remove(): Promise<void>;
-    #private;
-}
-import VDirectoryObject from "./VDirectoryObject.js";
-//# sourceMappingURL=TempDirectoryObject.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"TempDirectoryObject.d.ts","sourceRoot":"","sources":["../../../src/node/lib/TempDirectoryObject.js"],"names":[],"mappings":"AAiBA;;;;;;;;;GASG;AACH;IAgIE;;;;;OAKG;IACH,uBAEC;IA1ED,2BAEC;IAwBD,eAEC;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,UATa,OAAO,CAAC,IAAI,CAAC,CAWzB;;CA0BF;6BAzJ4B,uBAAuB"}

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

@@ -1,132 +0,0 @@
-/**
- * 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

@@ -1 +0,0 @@
-{"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

@@ -1,33 +0,0 @@
-/**
- * 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} virtualPath - The virtual file path (can be absolute like "/path/to/file.ext" or relative like "file.txt")
-     * @param {VDirectoryObject} parent - The parent virtual directory (required, used for cap reference)
-     */
-    constructor(virtualPath: 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

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