@gesslar/toolkit 2.8.0 → 2.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gesslar/toolkit",
-  "version": "2.8.0",
+  "version": "2.9.0",
   "description": "A collection of utilities for Node.js and browser environments.",
   "main": "./src/index.js",
   "type": "module",

package/src/lib/CappedDirectoryObject.js

@@ -13,6 +13,7 @@ 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"
 
 /**
@@ -84,7 +85,8 @@ export default class CappedDirectoryObject extends DirectoryObject {
           "Parent must have the same cap as this directory.",
         )
 
-        const parentPath = parent.path
+        // Use real path for filesystem operations
+        const parentPath = parent.realPath || parent.path
 
         // Validate parent's lineage traces back to the cap
         let found = false
@@ -128,13 +130,13 @@ export default class CappedDirectoryObject extends DirectoryObject {
    */
   #validateCapPath() {
     const cap = this.#cap
-    const resolved = path.resolve(this.path)
+    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.path}' is not within the cap directory '${cap}'`
+        `Path '${this.#realPath}' is not within the cap directory '${cap}'`
       )
     }
   }
@@ -157,6 +159,73 @@ export default class CappedDirectoryObject extends DirectoryObject {
     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 {string} Path relative to cap, or "/" if at cap root
+   * @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)
+   */
+  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("/")
+  }
+
+  /**
+   * 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 new DirectoryObject(this.#realPath)
+  }
+
   /**
    * Returns the parent directory of this capped directory.
    * Returns null only if this directory is at the cap (the "root" of the capped tree).
@@ -175,12 +244,17 @@ export default class CappedDirectoryObject extends DirectoryObject {
     const capResolved = path.resolve(this.#cap)
 
     // If we're at the cap, return null (cap is the "root")
-    if(this.path === capResolved) {
+    if(this.#realPath === capResolved) {
       return null
     }
 
-    // Otherwise return the parent (plain DirectoryObject, not capped)
-    return super.parent
+    // Otherwise return the parent using real path (plain DirectoryObject, not capped)
+    const parentPath = path.dirname(this.#realPath)
+    const isRoot = parentPath === this.#realPath
+
+    return isRoot
+      ? null
+      : new DirectoryObject(parentPath, this.temporary)
   }
 
   /**
@@ -201,19 +275,27 @@ export default class CappedDirectoryObject extends DirectoryObject {
   *#walkUpCapped() {
     const capResolved = path.resolve(this.#cap)
 
-    // Use super.walkUp but stop when we would go beyond the cap
-    for(const dir of super.walkUp) {
+    // 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(!dir.path.startsWith(capResolved)) {
+      if(!joined.startsWith(capResolved)) {
         break
       }
 
-      yield dir
+      // Yield plain DirectoryObject with real path
+      yield new DirectoryObject(joined, this.temporary)
 
       // Stop after yielding the cap
-      if(dir.path === capResolved) {
+      if(joined === capResolved) {
         break
       }
+
+      curr.pop()
     }
   }
 
@@ -229,69 +311,286 @@ export default class CappedDirectoryObject extends DirectoryObject {
   /**
    * Creates a new CappedDirectoryObject by extending this directory's path.
    *
-   * Validates that the resulting path remains within the cap directory tree.
+   * 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 segment to append
-   * @returns {CappedDirectoryObject} A new CappedDirectoryObject with the extended path
-   * @throws {Sass} If the path would escape the cap directory
-   * @throws {Sass} If the path is absolute
-   * @throws {Sass} If the path contains traversal (..)
+   * @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")
 
-    // Prevent absolute paths
+    // 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) {
+      // For CappedDirectoryObject, pass (name, cap, parent, temporary)
+      // For TempDirectoryObject subclass, it expects (name, parent) but will
+      // internally call super with the cap parameter
+      if(this.constructor === CappedDirectoryObject) {
+        return new CappedDirectoryObject(
+          newPath,
+          this.#cap,
+          this,
+          this.temporary
+        )
+      }
+
+      // For subclasses like TempDirectoryObject
+      return new this.constructor(newPath, 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(newPath)) {
-      throw Sass.new("Absolute paths are not allowed in capped directories")
+      // 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)
     }
 
-    // Prevent path traversal attacks
-    const normalized = path.normalize(newPath)
-    if(normalized.includes("..")) {
-      throw Sass.new("Path traversal (..) is not allowed in capped directories")
+    // 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()
     }
 
-    // Use the constructor of the current class (supports subclassing)
-    // Pass this as parent so the child inherits the same cap
-    return new this.constructor(newPath, this)
+    // 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(null, 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, creating CappedDirectoryObject instances
+    // (not subclass instances, to avoid constructor signature issues)
+    for(const segment of segments) {
+      current = new CappedDirectoryObject(
+        segment,
+        this.#cap,
+        current,
+        this.temporary
+      )
+    }
+
+    return current
   }
 
   /**
    * Creates a new FileObject by extending this directory's path.
    *
-   * Validates that the resulting path remains within the cap directory tree.
+   * 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 append
-   * @returns {FileObject} A new FileObject with the extended path
-   * @throws {Sass} If the path would escape the cap directory
-   * @throws {Sass} If the path is absolute
-   * @throws {Sass} If the path contains traversal (..)
+   * @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"
+   *
+   * @example
+   * // Absolute paths are relative to cap
+   * const abs = capped.getFile("/data/config.json")
+   * console.log(abs.path) // "/tmp/myapp-ABC123/data/config.json"
+   *
+   * @example
+   * // Excessive .. traversal clamps to cap
+   * const up = capped.getFile("../../../etc/passwd")
+   * console.log(up.path) // "/tmp/myapp-ABC123/passwd" (clamped to cap)
    */
   getFile(filename) {
     Valid.type(filename, "String")
 
-    // Prevent absolute paths
+    // 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)) {
-      throw Sass.new("Absolute paths are not allowed in capped directories")
+      // 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)
     }
 
-    // Prevent path traversal attacks
-    const normalized = path.normalize(filename)
-    if(normalized.includes("..")) {
-      throw Sass.new("Path traversal (..) is not allowed in capped directories")
+    // 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
     }
 
-    // Pass the filename and this directory as parent
-    // This ensures the FileObject maintains the correct parent reference
-    return new FileObject(filename, this)
+    // 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)
+  }
+
+  /**
+   * Override exists to use real filesystem path.
+   *
+   * @returns {Promise<boolean>} Whether the directory exists
+   */
+  get exists() {
+    return this.real.exists
+  }
+
+  /**
+   * Override read to use real filesystem path and return capped objects.
+   *
+   * @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)
+    })
+
+    return {files, directories: cappedDirectories}
+  }
+
+  /**
+   * Override assureExists to use real filesystem path.
+   *
+   * @param {object} [options] - Options for mkdir
+   * @returns {Promise<void>}
+   */
+  async assureExists(options = {}) {
+    return await this.real.assureExists(options)
+  }
+
+  /**
+   * Override delete to use real filesystem path.
+   *
+   * @returns {Promise<void>}
+   */
+  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()
   }
 
   /**
@@ -300,6 +599,6 @@ export default class CappedDirectoryObject extends DirectoryObject {
    * @returns {string} string representation of the CappedDirectoryObject
    */
   toString() {
-    return `[CappedDirectoryObject: ${this.path}]`
+    return `[CappedDirectoryObject: ${this.path} (real: ${this.#realPath})]`
   }
 }

package/src/lib/FileObject.js

@@ -96,6 +96,7 @@ export default class FileObject extends FS {
         case "String":
           return new DirectoryObject(parent)
         case "DirectoryObject":
+        case "CappedDirectoryObject":
         case "TempDirectoryObject":
           return parent
         default:
@@ -103,7 +104,9 @@ export default class FileObject extends FS {
       }
     })()
 
-    const final = FS.resolvePath(parentObject.path ?? ".", fixedFile)
+    // Use real path if parent is capped, otherwise use path
+    const parentPath = parentObject.realPath || parentObject.path
+    const final = FS.resolvePath(parentPath ?? ".", fixedFile)
 
     const resolved = final
     const url = new URL(FS.pathToUri(resolved))
@@ -113,7 +116,9 @@ export default class FileObject extends FS {
 
     // If the file is directly in the provided parent directory, reuse that object
     // Otherwise, create a DirectoryObject for the actual parent directory
-    const actualParent = parentObject && actualParentPath === parentObject.path
+    // Use real path for comparison if parent is capped
+    const parentRealPath = parentObject.realPath || parentObject.path
+    const actualParent = parentObject && actualParentPath === parentRealPath
       ? parentObject
       : new DirectoryObject(actualParentPath)
 
@@ -184,12 +189,28 @@ export default class FileObject extends FS {
   }
 
   /**
-   * Return the fully resolved absolute path to the file on disk.
+   * Returns the file path. If the parent is a capped directory, returns the
+   * virtual path relative to the cap. Otherwise returns the real filesystem path.
+   * Use `.real.path` to always get the actual filesystem path.
    *
-   * @returns {string} The fully resolved absolute file path
+   * @returns {string} The file path (virtual if parent is capped, real otherwise)
    */
   get path() {
-    return this.#meta.path
+    const realPath = this.#meta.path
+    const parent = this.#meta.parent
+
+    // If parent is capped, return virtual path
+    if(parent?.capped) {
+      const cap = parent.cap
+      const capResolved = path.resolve(cap)
+      const relative = path.relative(capResolved, realPath)
+
+      // Return with leading slash to indicate it's cap-relative
+      return "/" + relative.split(path.sep).join("/")
+    }
+
+    // Otherwise return real path
+    return realPath
   }
 
   /**
@@ -264,6 +285,26 @@ export default class FileObject extends FS {
     return this.#meta.parent
   }
 
+  /**
+   * Returns a plain FileObject representing the actual filesystem location.
+   * This provides an "escape hatch" when working with capped directories,
+   * allowing direct filesystem access when needed.
+   *
+   * @returns {FileObject} Uncapped file object at the real filesystem path
+   * @example
+   * const temp = new TempDirectoryObject("myapp")
+   * const file = temp.getFile("/config/app.json")
+   *
+   * // file.path shows virtual path
+   * console.log(file.path)       // "/config/app.json"
+   * // file.real.path shows actual filesystem path
+   * console.log(file.real.path)  // "/tmp/myapp-ABC123/config/app.json"
+   * file.real.parent.parent      // Can traverse outside the cap
+   */
+  get real() {
+    return new FileObject(this.#meta.path)
+  }
+
   /**
    * Check if a file can be read. Returns true if the file can be read, false
    *
@@ -271,7 +312,7 @@ export default class FileObject extends FS {
    */
   async canRead() {
     try {
-      await fs.access(this.path, fs.constants.R_OK)
+      await fs.access(this.#meta.path, fs.constants.R_OK)
 
       return true
     } catch(_) {
@@ -286,7 +327,7 @@ export default class FileObject extends FS {
    */
   async canWrite() {
     try {
-      await fs.access(this.path, fs.constants.W_OK)
+      await fs.access(this.#meta.path, fs.constants.W_OK)
 
       return true
     } catch(_) {
@@ -301,7 +342,7 @@ export default class FileObject extends FS {
    */
   async #fileExists() {
     try {
-      await fs.access(this.path, fs.constants.F_OK)
+      await fs.access(this.#meta.path, fs.constants.F_OK)
 
       return true
     } catch(_) {
@@ -316,7 +357,7 @@ export default class FileObject extends FS {
    */
   async size() {
     try {
-      const stat = await fs.stat(this.path)
+      const stat = await fs.stat(this.#meta.path)
 
       return stat.size
     } catch(_) {
@@ -332,7 +373,7 @@ export default class FileObject extends FS {
    */
   async modified() {
     try {
-      const stat = await fs.stat(this.path)
+      const stat = await fs.stat(this.#meta.path)
 
       return stat.mtime
     } catch(_) {

package/src/lib/TempDirectoryObject.js

@@ -86,12 +86,12 @@ export default class TempDirectoryObject extends CappedDirectoryObject {
    */
   #createDirectory() {
     try {
-      fs.mkdirSync(this.path)
+      fs.mkdirSync(this.realPath)
     } catch(e) {
       // EEXIST is fine - directory already exists
       if(e.code !== "EEXIST") {
         throw Sass.new(
-          `Unable to create temporary directory '${this.path}': ${e.message}`
+          `Unable to create temporary directory '${this.realPath}': ${e.message}`
         )
       }
     }

package/src/types/lib/CappedDirectoryObject.d.ts

@@ -38,6 +38,32 @@ export default class CappedDirectoryObject extends DirectoryObject {
      * @returns {boolean} Always true for CappedDirectoryObject instances
      */
     get capped(): boolean;
+    /**
+     * Returns the real filesystem path (for internal and subclass use).
+     *
+     * @protected
+     * @returns {string} The actual filesystem path
+     */
+    protected get realPath(): string;
+    /**
+     * 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 a generator that walks up to the cap.
      *
@@ -47,20 +73,41 @@ export default class CappedDirectoryObject extends DirectoryObject {
     /**
      * Creates a new CappedDirectoryObject by extending this directory's path.
      *
-     * Validates that the resulting path remains within the cap directory tree.
+     * 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 segment to append
-     * @returns {CappedDirectoryObject} A new CappedDirectoryObject with the extended path
-     * @throws {Sass} If the path would escape the cap directory
-     * @throws {Sass} If the path is absolute
-     * @throws {Sass} If the path contains traversal (..)
+     * @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: string): CappedDirectoryObject;
+    /**
+     * Override read to use real filesystem path and return capped objects.
+     *
+     * @param {string} [pat=""] - Optional glob pattern
+     * @returns {Promise<{files: Array<FileObject>, directories: Array}>} Directory contents
+     */
+    read(pat?: string): Promise<{
+        files: Array<FileObject>;
+        directories: any[];
+    }>;
     #private;
 }
 import DirectoryObject from "./DirectoryObject.js";
+import FileObject from "./FileObject.js";
 //# sourceMappingURL=CappedDirectoryObject.d.ts.map

package/src/types/lib/CappedDirectoryObject.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CappedDirectoryObject.d.ts","sourceRoot":"","sources":["../../lib/CappedDirectoryObject.js"],"names":[],"mappings":"AAiBA;;;;;;;;GAQG;AACH;IAGE;;;;;;;;;;;;;;;;OAgBG;IACH,kBAXW,MAAM,OAAC,OACP,MAAM,WACN,qBAAqB,OAAC,cACtB,OAAO,EAkFjB;IAqBD;;;;OAIG;IACH,WAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,cAFa,OAAO,CAInB;IA8DD;;;;OAIG;IACH,cAFa,SAAS,CAAC,eAAe,CAAC,CAItC;IAED;;;;;;;;;;;;;;OAcG;IACH,sBAVW,MAAM,GACJ,qBAAqB,CA0BjC;;CA4CF;4BAnS2B,sBAAsB"}
+{"version":3,"file":"CappedDirectoryObject.d.ts","sourceRoot":"","sources":["../../lib/CappedDirectoryObject.js"],"names":[],"mappings":"AAkBA;;;;;;;;GAQG;AACH;IAGE;;;;;;;;;;;;;;;;OAgBG;IACH,kBAXW,MAAM,OAAC,OACP,MAAM,WACN,qBAAqB,OAAC,cACtB,OAAO,EAmFjB;IAqBD;;;;OAIG;IACH,WAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,cAFa,OAAO,CAInB;IAED;;;;;OAKG;IACH,0BAFa,MAAM,CAIlB;IAqCD;;;;;;;;;;;;;;;;;OAiBG;IACH,YAba,eAAe,CAe3B;IA2ED;;;;OAIG;IACH,cAFa,SAAS,CAAC,eAAe,CAAC,CAItC;IAED;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,sBAjBW,MAAM,GACJ,qBAAqB,CA6EjC;IA0ID;;;;;OAKG;IACH,WAHW,MAAM,GACJ,OAAO,CAAC;QAAC,KAAK,EAAE,KAAK,CAAC,UAAU,CAAC,CAAC;QAAC,WAAW,QAAO;KAAC,CAAC,CAanE;;CAoDF;4BA9kB2B,sBAAsB;uBAC3B,iBAAiB"}

package/src/types/lib/FileObject.d.ts

@@ -50,9 +50,11 @@ export default class FileObject extends FS {
      */
     get supplied(): string;
     /**
-     * Return the fully resolved absolute path to the file on disk.
+     * Returns the file path. If the parent is a capped directory, returns the
+     * virtual path relative to the cap. Otherwise returns the real filesystem path.
+     * Use `.real.path` to always get the actual filesystem path.
      *
-     * @returns {string} The fully resolved absolute file path
+     * @returns {string} The file path (virtual if parent is capped, real otherwise)
      */
     get path(): string;
     /**
@@ -107,6 +109,23 @@ export default class FileObject extends FS {
      * @returns {DirectoryObject} The parent directory object
      */
     get parent(): DirectoryObject;
+    /**
+     * Returns a plain FileObject representing the actual filesystem location.
+     * This provides an "escape hatch" when working with capped directories,
+     * allowing direct filesystem access when needed.
+     *
+     * @returns {FileObject} Uncapped file object at the real filesystem path
+     * @example
+     * const temp = new TempDirectoryObject("myapp")
+     * const file = temp.getFile("/config/app.json")
+     *
+     * // file.path shows virtual path
+     * console.log(file.path)       // "/config/app.json"
+     * // file.real.path shows actual filesystem path
+     * console.log(file.real.path)  // "/tmp/myapp-ABC123/config/app.json"
+     * file.real.parent.parent      // Can traverse outside the cap
+     */
+    get real(): FileObject;
     /**
      * Check if a file can be read. Returns true if the file can be read, false
      *

package/src/types/lib/FileObject.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FileObject.d.ts","sourceRoot":"","sources":["../../lib/FileObject.js"],"names":[],"mappings":"AAmBA;;;;;;;;;;;;;;GAcG;AAEH;uBA8He,MAAM;IA7HnB;;;;;OAKG;IACH,yBAFU;QAAC,CAAC,GAAG,EAAE,MAAM,GAAG,KAAK,CAAC,OAAO,KAAK,GAAG,OAAO,IAAI,CAAC,CAAA;KAAC,CAO1D;IA2BF;;;;;OAKG;IACH,sBAHW,MAAM,GAAG,UAAU,WACnB,eAAe,GAAC,MAAM,GAAC,IAAI,EAkDrC;IAWD;;;;OAIG;IACH,UAFa,MAAM,CAclB;IAWD;;;;OAIG;IACH,cAFa,OAAO,CAAC,OAAO,CAAC,CAI5B;IAED;;;;OAIG;IACH,gBAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,YAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,WAFa,GAAG,CAIf;IAED;;;;OAIG;IACH,YAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,cAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,iBAFa,MAAM,CAIlB;IACD;;;;OAIG;IACH,cAFa,OAAO,CAInB;IAED;;;;OAIG;IACH,mBAFa,OAAO,CAInB;IAED;;;;;;;;;;;;;;OAcG;IACH,cAFa,eAAe,CAI3B;IAED;;;;OAIG;IACH,WAFa,OAAO,CAAC,OAAO,CAAC,CAU5B;IAED;;;;OAIG;IACH,YAFa,OAAO,CAAC,OAAO,CAAC,CAU5B;IAiBD;;;;OAIG;IACH,QAFa,OAAO,CAAC,MAAM,OAAC,CAAC,CAU5B;IAED;;;;;OAKG;IACH,YAFa,OAAO,CAAC,IAAI,OAAC,CAAC,CAU1B;IAsBD;;;;;OAKG;IACH,gBAHW,MAAM,GACJ,OAAO,CAAC,MAAM,CAAC,CAY3B;IAED;;;;;;;;;;;OAWG;IACH,cARa,OAAO,CAAC,MAAM,CAAC,CAkB3B;IAED;;;;;;;;;;;OAWG;IACH,eARW,MAAM,aACN,MAAM,GACJ,OAAO,CAAC,IAAI,CAAC,CAezB;IAED;;;;;;;;;;;;;;;OAeG;IACH,kBAXW,WAAW,GAAC,IAAI,GAAC,MAAM,GACrB,OAAO,CAAC,IAAI,CAAC,CAyBzB;IAED;;;;;;;;;;;;;;OAcG;IACH,gBAXW,MAAM,aACN,MAAM,GACJ,OAAO,CAAC,OAAO,CAAC,CAkC5B;IAED;;;;OAIG;IACH,UAFa,OAAO,CAAC,MAAM,CAAC,CAY3B;IAED;;;;;;;;;OASG;IACH,UAPa,OAAO,CAAC,IAAI,CAAC,CAiBzB;;CACF;eA7gBc,SAAS;4BADI,sBAAsB;kBARhC,OAAO;iBAIR,MAAM"}
+{"version":3,"file":"FileObject.d.ts","sourceRoot":"","sources":["../../lib/FileObject.js"],"names":[],"mappings":"AAmBA;;;;;;;;;;;;;;GAcG;AAEH;uBAmIe,MAAM;IAlInB;;;;;OAKG;IACH,yBAFU;QAAC,CAAC,GAAG,EAAE,MAAM,GAAG,KAAK,CAAC,OAAO,KAAK,GAAG,OAAO,IAAI,CAAC,CAAA;KAAC,CAO1D;IA2BF;;;;;OAKG;IACH,sBAHW,MAAM,GAAG,UAAU,WACnB,eAAe,GAAC,MAAM,GAAC,IAAI,EAuDrC;IAWD;;;;OAIG;IACH,UAFa,MAAM,CAclB;IAWD;;;;OAIG;IACH,cAFa,OAAO,CAAC,OAAO,CAAC,CAI5B;IAED;;;;OAIG;IACH,gBAFa,MAAM,CAIlB;IAED;;;;;;OAMG;IACH,YAFa,MAAM,CAkBlB;IAED;;;;OAIG;IACH,WAFa,GAAG,CAIf;IAED;;;;OAIG;IACH,YAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,cAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,iBAFa,MAAM,CAIlB;IACD;;;;OAIG;IACH,cAFa,OAAO,CAInB;IAED;;;;OAIG;IACH,mBAFa,OAAO,CAInB;IAED;;;;;;;;;;;;;;OAcG;IACH,cAFa,eAAe,CAI3B;IAED;;;;;;;;;;;;;;;OAeG;IACH,YAXa,UAAU,CAatB;IAED;;;;OAIG;IACH,WAFa,OAAO,CAAC,OAAO,CAAC,CAU5B;IAED;;;;OAIG;IACH,YAFa,OAAO,CAAC,OAAO,CAAC,CAU5B;IAiBD;;;;OAIG;IACH,QAFa,OAAO,CAAC,MAAM,OAAC,CAAC,CAU5B;IAED;;;;;OAKG;IACH,YAFa,OAAO,CAAC,IAAI,OAAC,CAAC,CAU1B;IAsBD;;;;;OAKG;IACH,gBAHW,MAAM,GACJ,OAAO,CAAC,MAAM,CAAC,CAY3B;IAED;;;;;;;;;;;OAWG;IACH,cARa,OAAO,CAAC,MAAM,CAAC,CAkB3B;IAED;;;;;;;;;;;OAWG;IACH,eARW,MAAM,aACN,MAAM,GACJ,OAAO,CAAC,IAAI,CAAC,CAezB;IAED;;;;;;;;;;;;;;;OAeG;IACH,kBAXW,WAAW,GAAC,IAAI,GAAC,MAAM,GACrB,OAAO,CAAC,IAAI,CAAC,CAyBzB;IAED;;;;;;;;;;;;;;OAcG;IACH,gBAXW,MAAM,aACN,MAAM,GACJ,OAAO,CAAC,OAAO,CAAC,CAkC5B;IAED;;;;OAIG;IACH,UAFa,OAAO,CAAC,MAAM,CAAC,CAY3B;IAED;;;;;;;;;OASG;IACH,UAPa,OAAO,CAAC,IAAI,CAAC,CAiBzB;;CACF;eAtjBc,SAAS;4BADI,sBAAsB;kBARhC,OAAO;iBAIR,MAAM"}