@gesslar/toolkit 3.9.0 → 3.13.0

package/src/lib/CappedDirectoryObject.js

@@ -10,11 +10,10 @@
 
 import path from "node:path"
 
-import {Data, Valid} from "../browser/index.js"
 import DirectoryObject from "./DirectoryObject.js"
 import FileObject from "./FileObject.js"
 import FS from "./FS.js"
-import Sass from "./Sass.js"
+import Valid from "./Valid.js"
 
 /**
  * CappedDirectoryObject extends DirectoryObject with constraints that ensure
@@ -26,7 +25,10 @@ import Sass from "./Sass.js"
  * @augments DirectoryObject
  */
 export default class CappedDirectoryObject extends DirectoryObject {
+  #real
   #cap
+  #cappedParentPath
+  #cappedParent
 
   /**
    * Constructs a CappedDirectoryObject instance.
@@ -35,9 +37,8 @@ export default class CappedDirectoryObject extends DirectoryObject {
    * (virtual root). With a parent, the path is resolved relative to the parent's
    * cap using virtual path semantics (absolute paths treated as cap-relative).
    *
-   * @param {string} [dirPath="."] - Directory path (becomes cap if no parent, else relative to parent's cap, defaults to current directory)
+   * @param {string} [directory="."] - Directory path (becomes cap if no parent, else relative to parent's cap, defaults to current directory)
    * @param {CappedDirectoryObject?} [parent] - Optional parent capped directory
-   * @param {boolean} [temporary=false] - Whether this is a temporary directory
    * @throws {Sass} If parent is provided but not a CappedDirectoryObject
    * @throws {Sass} If the resulting path would escape the cap
    * @example
@@ -60,60 +61,35 @@ export default class CappedDirectoryObject extends DirectoryObject {
    * const config = new CappedDirectoryObject("/etc/config", cache)
    * // path: /home/user/.cache/etc/config, cap: /home/user/.cache
    */
-  constructor(dirPath=".", parent=null, temporary=false) {
-    Valid.type(dirPath, "String")
+  constructor(directory, source=null) {
+    Valid.type(source, "Null|CappedDirectoryObject")
 
-    // Validate parent using inheritance-aware type checking
-    if(parent !== null && !Data.isType(parent, "CappedDirectoryObject")) {
-      throw Sass.new(`Parent must be null or a CappedDirectoryObject instance, got ${Data.typeOf(parent)}`)
-    }
-
-    let cap
-    let resolvedPath
+    directory ||= "."
 
-    if(!parent) {
-      // No parent: dirPath becomes both the directory and the cap
-      cap = path.resolve(dirPath)
-      resolvedPath = cap
-    } else {
-      // With parent: inherit cap and resolve dirPath relative to it
-      cap = parent.#cap
+    const baseLocalPath = source?.path ?? "/"
+    const baseRealPath = source?.real.path ?? directory
 
-      // Use real path for filesystem operations
-      const parentPath = parent.realPath || parent.path
-      const capResolved = path.resolve(cap)
+    if(source && directory.startsWith("/"))
+      directory = directory.slice(1)
 
-      let targetPath
+    // Find out what directory means to the basePath
+    const realResolved = FS.resolvePath(baseRealPath, directory)
+    const localResolved = source
+      ? FS.resolvePath(baseLocalPath, directory)
+      : path.parse(path.resolve("")).root
 
-      // If absolute, treat as virtual path relative to cap (strip leading /)
-      if(path.isAbsolute(dirPath)) {
-        const relative = dirPath.replace(/^[/\\]+/, "")
-        targetPath = relative ? path.join(capResolved, relative) : capResolved
-      } else {
-        // Relative path - resolve from parent directory
-        targetPath = FS.resolvePath(parentPath, dirPath)
-      }
+    super(localResolved)
 
-      // Resolve to absolute path (handles .. and .)
-      const resolved = path.resolve(targetPath)
+    this.#real = new DirectoryObject(realResolved)
+    this.#cap = source?.cap ?? this
 
-      // Clamp to cap boundary - cannot escape above cap
-      if(!resolved.startsWith(capResolved)) {
-        // Path tried to escape - clamp to cap root
-        resolvedPath = capResolved
-      } else {
-        resolvedPath = resolved
-      }
+    if(source) {
+      this.#cappedParent = source
+      this.#cappedParentPath = source.path
+    } else {
+      this.#cappedParent = null
+      this.#cappedParentPath = null
     }
-
-    // Call parent constructor with the path
-    super(resolvedPath, temporary)
-
-    // Store the cap AFTER calling super()
-    this.#cap = cap
-
-    // Validate that this path is within the cap
-    this.#validateCapPath()
   }
 
   /**
@@ -133,95 +109,36 @@ export default class CappedDirectoryObject extends DirectoryObject {
   }
 
   /**
-   * Validates that the directory path is within the cap directory tree.
+   * Indicates whether this directory is capped (constrained to a specific tree).
+   * Always returns true for CappedDirectoryObject instances.
    *
-   * @private
-   * @throws {Sass} If the path is not within the cap directory
-   */
-  #validateCapPath() {
-    const cap = this.#cap
-    const resolved = path.resolve(this.#realPath)
-    const capResolved = path.resolve(cap)
-
-    // Check if the resolved path starts with the cap directory
-    if(!resolved.startsWith(capResolved)) {
-      throw Sass.new(
-        `Path '${this.#realPath}' is not within the cap directory '${cap}'`
-      )
-    }
-  }
-
-  /**
-   * Re-caps this directory to itself, making it the new root of the capped tree.
-   * This is a protected method intended for use by subclasses like TempDirectoryObject.
-   *
-   * @protected
-   */
-  _recapToSelf() {
-    this.#cap = this.#realPath
-  }
-
-  /**
-   * Returns the cap path for this directory.
-   *
-   * @returns {string} The cap directory path
-   */
-  get cap() {
-    return this.#cap
-  }
-
-  /**
-   * Returns whether this directory is capped.
+   * @returns {boolean} True for all CappedDirectoryObject instances
+   * @example
+   * const capped = new TempDirectoryObject("myapp")
+   * console.log(capped.isCapped) // true
    *
-   * @returns {boolean} Always true for CappedDirectoryObject instances
+   * const regular = new DirectoryObject("/tmp")
+   * console.log(regular.isCapped) // false
    */
-  get capped() {
+  get isCapped() {
     return true
   }
 
   /**
-   * Returns the real filesystem path (for internal and subclass use).
-   *
-   * @protected
-   * @returns {string} The actual filesystem path
-   */
-  get realPath() {
-    return super.path
-  }
-
-  /**
-   * Private alias for realPath (for use in private methods).
-   *
-   * @private
-   * @returns {string} The actual filesystem path
-   */
-  get #realPath() {
-    return this.realPath
-  }
-
-  /**
-   * Returns the virtual path relative to the cap.
-   * This is the default path representation in the capped environment.
-   * Use `.real.path` to access the actual filesystem path.
+   * Returns the cap (root) of the capped directory tree.
+   * For root CappedDirectoryObject instances, returns itself.
+   * For children, returns the inherited cap from the parent chain.
    *
-   * @returns {string} Path relative to cap, or "/" if at cap root
+   * @returns {CappedDirectoryObject} The cap directory object (root of the capped tree)
    * @example
    * const temp = new TempDirectoryObject("myapp")
-   * const subdir = temp.getDirectory("data/cache")
-   * console.log(subdir.path)       // "/data/cache" (virtual, relative to cap)
-   * console.log(subdir.real.path)  // "/tmp/myapp-ABC123/data/cache" (actual filesystem)
+   * 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 path() {
-    const capResolved = path.resolve(this.#cap)
-    const relative = path.relative(capResolved, this.#realPath)
-
-    // If at cap root or empty, return "/"
-    if(!relative || relative === ".") {
-      return "/"
-    }
-
-    // Return with leading slash to indicate it's cap-relative
-    return "/" + relative.split(path.sep).join("/")
+  get cap() {
+    return this.#cap
   }
 
   /**
@@ -243,7 +160,7 @@ export default class CappedDirectoryObject extends DirectoryObject {
    * subdir.real.parent              // Can traverse outside the cap
    */
   get real() {
-    return new DirectoryObject(this.#realPath)
+    return this.#real
   }
 
   /**
@@ -261,324 +178,23 @@ export default class CappedDirectoryObject extends DirectoryObject {
    * console.log(capped.parent) // null (at cap root)
    */
   get parent() {
-    const capResolved = path.resolve(this.#cap)
-
-    // If we're at the cap, return null (cap is the "root")
-    if(this.#realPath === capResolved) {
-      return null
-    }
-
-    // Compute parent's real path
-    const parentPath = path.dirname(this.#realPath)
-    const isRoot = parentPath === this.#realPath
-
-    if(isRoot) {
-      return null
-    }
-
-    // Compute relative path from current to parent (just "..")
-    // Then use getDirectory to create the parent, which preserves the class type
-    return this.getDirectory("..")
-  }
-
-  /**
-   * Returns the URL with virtual path (cap-relative).
-   *
-   * @returns {URL} Virtual URL
-   */
-  get url() {
-    return new URL(FS.pathToUri(this.path))
-  }
-
-  /**
-   * Returns JSON representation with virtual paths and .real escape hatch.
-   *
-   * @returns {object} JSON representation
-   */
-  toJSON() {
-    const capResolved = path.resolve(this.#cap)
-    let parentPath
-
-    if(this.#realPath === capResolved) {
-      // At cap root, no parent
-      parentPath = null
-    } else {
-      // Compute parent's virtual path
-      const parentReal = path.dirname(this.#realPath)
-      const relative = path.relative(capResolved, parentReal)
-
-      // If parent is cap root or empty, return "/"
-      if(!relative || relative === ".") {
-        parentPath = "/"
-      } else {
-        // Return parent's virtual path with leading slash
-        parentPath = "/" + relative.split(path.sep).join("/")
-      }
-    }
-
-    return {
-      supplied: this.supplied,
-      path: this.path,
-      url: this.url.toString(),
-      name: this.name,
-      module: this.module,
-      extension: this.extension,
-      isFile: this.isFile,
-      isDirectory: this.isDirectory,
-      parent: parentPath,
-      root: this.root.path,
-      real: this.real.toJSON()
-    }
-  }
-
-  /**
-   * Generator that walks up the directory tree, stopping at the cap.
-   * Yields parent directories from current up to (and including) the cap root.
-   *
-   * @returns {Generator<DirectoryObject>} Generator yielding parent DirectoryObject instances
-   * @example
-   * const capped = new TempDirectoryObject("myapp")
-   * const deep = capped.getDirectory("data").getDirectory("files")
-   * for(const parent of deep.walkUp) {
-   *   console.log(parent.path)
-   *   // .../myapp-ABC123/data/files
-   *   // .../myapp-ABC123/data
-   *   // .../myapp-ABC123 (stops at cap)
-   * }
-   */
-  *#walkUpCapped() {
-    const capResolved = path.resolve(this.#cap)
-
-    // Build trail from real path
-    const trail = this.#realPath.split(path.sep).filter(Boolean)
-    const curr = [...trail]
-
-    while(curr.length > 0) {
-      const joined = path.sep + curr.join(path.sep)
-
-      // Don't yield anything beyond the cap
-      if(!joined.startsWith(capResolved)) {
-        break
-      }
-
-      // Yield plain DirectoryObject with real path
-      yield new DirectoryObject(joined, this.temporary)
-
-      // Stop after yielding the cap
-      if(joined === capResolved) {
-        break
-      }
-
-      curr.pop()
-    }
-  }
-
-  /**
-   * Returns a generator that walks up to the cap.
-   *
-   * @returns {Generator<DirectoryObject>} Generator yielding parent directories
-   */
-  get walkUp() {
-    return this.#walkUpCapped()
-  }
-
-  /**
-   * Creates a new CappedDirectoryObject by extending this directory's path.
-   *
-   * All paths are coerced to remain within the cap directory tree:
-   * - Absolute paths (e.g., "/foo") are treated as relative to the cap
-   * - Parent traversal ("..") is allowed but clamped at the cap boundary
-   * - The cap acts as the virtual root directory
-   *
-   * @param {string} newPath - The path to resolve (can be absolute or contain ..)
-   * @returns {CappedDirectoryObject} A new CappedDirectoryObject with the coerced path
-   * @example
-   * const capped = new TempDirectoryObject("myapp")
-   * const subDir = capped.getDirectory("data")
-   * console.log(subDir.path) // "/tmp/myapp-ABC123/data"
-   *
-   * @example
-   * // Absolute paths are relative to cap
-   * const abs = capped.getDirectory("/foo/bar")
-   * console.log(abs.path) // "/tmp/myapp-ABC123/foo/bar"
-   *
-   * @example
-   * // Excessive .. traversal clamps to cap
-   * const up = capped.getDirectory("../../../etc/passwd")
-   * console.log(up.path) // "/tmp/myapp-ABC123" (clamped to cap)
-   */
-  getDirectory(newPath) {
-    Valid.type(newPath, "String")
-
-    // Fast path: if it's a simple name (no separators, not absolute, no ..)
-    // use the subclass constructor directly to preserve type
-    const isSimpleName = !path.isAbsolute(newPath) &&
-                         !newPath.includes("/") &&
-                         !newPath.includes("\\") &&
-                         !newPath.includes("..")
-
-    if(isSimpleName) {
-      // Both CappedDirectoryObject and subclasses use same signature now
-      return new this.constructor(newPath, this, this.temporary)
-    }
-
-    // Complex path - handle coercion
-    const capResolved = path.resolve(this.#cap)
-    let targetPath
-
-    // If absolute, treat as relative to cap (virtual root)
-    if(path.isAbsolute(newPath)) {
-      // Strip leading slashes to make relative
-      const relative = newPath.replace(/^[/\\]+/, "")
-
-      // Join with cap (unless empty, which means cap root)
-      targetPath = relative ? path.join(capResolved, relative) : capResolved
-    } else {
-      // Relative path - resolve from current directory
-      targetPath = FS.resolvePath(this.#realPath, newPath)
-    }
-
-    // Resolve to absolute path (handles .. and .)
-    const resolved = path.resolve(targetPath)
-
-    // Coerce: if path escaped cap, clamp to cap boundary
-    const coerced = resolved.startsWith(capResolved)
-      ? resolved
-      : capResolved
-
-    // Compute path relative to cap for reconstruction
-    const relativeToCap = path.relative(capResolved, coerced)
-
-    // If we're at the cap root, return cap root directory
-    if(!relativeToCap || relativeToCap === ".") {
-      return this.#createCappedAtRoot()
-    }
-
-    // Build directory by traversing segments from cap
-    return this.#buildDirectoryFromRelativePath(relativeToCap)
-  }
-
-  /**
-   * Creates a CappedDirectoryObject at the cap root.
-   * Can be overridden by subclasses that have different root semantics.
-   *
-   * @private
-   * @returns {CappedDirectoryObject} Directory object at cap root
-   */
-  #createCappedAtRoot() {
-    // Create a base CappedDirectoryObject at the cap path
-    // This works for direct usage of CappedDirectoryObject
-    // Subclasses may need to override if they have special semantics
-    return new CappedDirectoryObject(this.#cap, null, this.temporary)
-  }
-
-  /**
-   * Builds a directory by traversing path segments from cap.
-   *
-   * @private
-   * @param {string} relativePath - Path relative to cap
-   * @returns {CappedDirectoryObject} The directory at the final path
-   */
-  #buildDirectoryFromRelativePath(relativePath) {
-    const segments = relativePath.split(path.sep).filter(Boolean)
-
-    // Start at cap root
-    let current = this.#createCappedAtRoot()
-
-    // Traverse each segment, using constructor to preserve class type
-    for(const segment of segments) {
-      // Use simple name constructor to preserve subclass type
-      // Works for both CappedDirectoryObject and TempDirectoryObject
-      current = new this.constructor(segment, current, this.temporary)
-    }
-
-    return current
+    return this.#cappedParent
   }
 
   /**
-   * Creates a new FileObject by extending this directory's path.
-   *
-   * All paths are coerced to remain within the cap directory tree:
-   * - Absolute paths (e.g., "/config.json") are treated as relative to the cap
-   * - Parent traversal ("..") is allowed but clamped at the cap boundary
-   * - The cap acts as the virtual root directory
-   *
-   * @param {string} filename - The filename to resolve (can be absolute or contain ..)
-   * @returns {FileObject} A new FileObject with the coerced path
-   * @example
-   * const capped = new TempDirectoryObject("myapp")
-   * const file = capped.getFile("config.json")
-   * console.log(file.path) // "/tmp/myapp-ABC123/config.json"
+   * 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
-   * // Absolute paths are relative to cap
-   * const abs = capped.getFile("/data/config.json")
-   * console.log(abs.path) // "/tmp/myapp-ABC123/data/config.json"
+   * const temp = new TempDirectoryObject("myapp")
+   * console.log(temp.parentPath) // null (at cap root)
    *
-   * @example
-   * // Excessive .. traversal clamps to cap
-   * const up = capped.getFile("../../../etc/passwd")
-   * console.log(up.path) // "/tmp/myapp-ABC123/passwd" (clamped to cap)
+   * const subdir = temp.getDirectory("data")
+   * console.log(subdir.parentPath) // "/data" or similar (parent's virtual path)
    */
-  getFile(filename) {
-    Valid.type(filename, "String")
-
-    // Fast path: if it's a simple filename (no separators, not absolute, no ..)
-    // use this as the parent directly
-    const isSimpleName = !path.isAbsolute(filename) &&
-                         !filename.includes("/") &&
-                         !filename.includes("\\") &&
-                         !filename.includes("..")
-
-    if(isSimpleName) {
-      // Simple filename - create directly with this as parent
-      return new FileObject(filename, this)
-    }
-
-    // Complex path - handle coercion
-    const capResolved = path.resolve(this.#cap)
-    let targetPath
-
-    // If absolute, treat as relative to cap (virtual root)
-    if(path.isAbsolute(filename)) {
-      // Strip leading slashes to make relative
-      const relative = filename.replace(/^[/\\]+/, "")
-
-      // Join with cap
-      targetPath = path.join(capResolved, relative)
-    } else {
-      // Relative path - resolve from current directory
-      targetPath = FS.resolvePath(this.#realPath, filename)
-    }
-
-    // Resolve to absolute path (handles .. and .)
-    const resolved = path.resolve(targetPath)
-
-    // Coerce: if path escaped cap, clamp to cap boundary
-    const coerced = resolved.startsWith(capResolved)
-      ? resolved
-      : capResolved
-
-    // Extract directory and filename parts
-    let fileDir = path.dirname(coerced)
-    let fileBasename = path.basename(coerced)
-
-    // Special case: if coerced is exactly the cap (file tried to escape),
-    // the file should be placed at the cap root with just the filename
-    if(coerced === capResolved) {
-      // Extract just the filename from the original path
-      fileBasename = path.basename(resolved)
-      fileDir = capResolved
-    }
-
-    // Get or create the parent directory
-    const relativeToCap = path.relative(capResolved, fileDir)
-    const parentDir = !relativeToCap || relativeToCap === "."
-      ? this.#createCappedAtRoot()
-      : this.#buildDirectoryFromRelativePath(relativeToCap)
-
-    // Create FileObject with parent directory
-    return new FileObject(fileBasename, parentDir)
+  get parentPath() {
+    return this.#cappedParentPath
   }
 
   /**
@@ -596,20 +212,14 @@ export default class CappedDirectoryObject extends DirectoryObject {
    * @param {string} [pat=""] - Optional glob pattern
    * @returns {Promise<{files: Array<FileObject>, directories: Array}>} Directory contents
    */
-  async read(pat="") {
-    const {files, directories} = await this.real.read(pat)
-
-    // Convert plain DirectoryObjects to CappedDirectoryObjects with same cap
-    const cappedDirectories = directories.map(dir => {
-      const name = dir.name
-
-      return new this.constructor(name, this)
-    })
+  async read(...arg) {
+    const {files, directories} = await this.real.read(...arg)
 
-    // Recreate FileObjects with capped parent so they return virtual paths
-    const cappedFiles = files.map(file => new FileObject(file.name, this))
+    // we need to re-cast
+    const recastDirs = directories.map(e => this.getDirectory(e.name))
+    const recastFiles = files.map(f => new FileObject(f.name, this))
 
-    return {files: cappedFiles, directories: cappedDirectories}
+    return {files: recastFiles, directories: recastDirs}
   }
 
   /**
@@ -640,36 +250,4 @@ export default class CappedDirectoryObject extends DirectoryObject {
   async delete() {
     return await this.real.delete()
   }
-
-  /**
-   * Override remove to preserve temporary flag check.
-   *
-   * @returns {Promise<void>}
-   */
-  async remove() {
-    if(!this.temporary)
-      throw Sass.new("This is not a temporary directory.")
-
-    const {files, directories} = await this.read()
-
-    // Remove subdirectories recursively
-    for(const dir of directories)
-      await dir.remove()
-
-    // Remove files
-    for(const file of files)
-      await file.delete()
-
-    // Delete the now-empty directory
-    await this.delete()
-  }
-
-  /**
-   * Returns a string representation of the CappedDirectoryObject.
-   *
-   * @returns {string} string representation of the CappedDirectoryObject
-   */
-  toString() {
-    return `[CappedDirectoryObject: ${this.path} (real: ${this.#realPath})]`
-  }
 }