@gesslar/toolkit 2.7.1 → 2.9.0

package/README.md

@@ -16,6 +16,7 @@ a Tauri app.
 | Disposer | Lifecycle management for disposable resources |
 | HTML | HTML loading and sanitization utilities |
 | Notify | Event system wrapper for DOM events |
+| Promised | Promise utilities for settling, filtering, and extracting values from promise results |
 | Sass | Custom Error class with enhanced features |
 | Tantrum | AggregateError implementation |
 | Type | String-based type management (exported as TypeSpec in browser) |
@@ -93,3 +94,11 @@ import { Data, Collection, Util } from '@gesslar/toolkit/browser'
 ```
 
 The browser version includes: Collection, Data, Disposer, HTML, Notify, Sass, Tantrum, Type (TypeSpec), Util, and Valid. Node-only modules (Cache, CappedDirectoryObject, Contract, DirectoryObject, FileObject, FS, Glog, Schemer, TempDirectoryObject, Term, Terms) are not available in the browser version.
+
+## Post Partum
+
+If you made it this far, please understand that I have absolutely zero scruples when it comes to breaking changes. Primarily, the audience for this library is myself. Consequently, anything that relies on the contents of this library will dutifully crash and I'll have to refactor those things then. It's like leaving playing nicky nicky nine doors. But with myself. And there's a lazy bomb waiting for me. That I planted. For me. And the bomb just explodes poop.
+
+You're of course welcome to use my library! It's pretty robust. Uhhh, but maybe lock in the version until you see if something is gonna poop all over you. I make robots make my PR notifications and generally they're very good at firing off klaxons about my fetish for breaking changes, so you should be all right if you're paying attention. 🤷🏻
+
+Sincerely, Senator Yabba of the Dabba (Doo)

package/package.json

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

package/src/browser/index.js

@@ -8,6 +8,7 @@ export {Disposer as DisposerClass} from "./lib/Disposer.js"
 export {default as HTML} from "./lib/HTML.js"
 export {HTML as HTMLClass} from "./lib/HTML.js"
 export {default as Notify} from "./lib/Notify.js"
+export {default as Promised} from "./lib/Promised.js"
 export {default as Sass} from "./lib/Sass.js"
 export {default as Tantrum} from "./lib/Tantrum.js"
 export {default as Type} from "./lib/TypeSpec.js"

package/src/browser/lib/Promised.js

@@ -0,0 +1,120 @@
+import Tantrum from "./Tantrum.js"
+
+/**
+ * Utility class providing helper functions for working with Promises,
+ * including settling, filtering, and extracting values from promise results.
+ */
+export default class Promised {
+  /**
+   * Asynchronously awaits all promises in parallel.
+   * Wrapper around Promise.all for consistency with other utility methods.
+   *
+   * @param {Array<Promise<unknown>>} promises - Array of promises to await
+   * @returns {Promise<Array<unknown>>} Results of all promises
+   */
+  static async await(promises) {
+    return await Promise.all(promises)
+  }
+
+  /**
+   * Settles all promises (both fulfilled and rejected) in parallel.
+   * Wrapper around Promise.allSettled for consistency with other utility methods.
+   *
+   * @param {Array<Promise<unknown>>} promises - Array of promises to settle
+   * @returns {Promise<Array<{status: 'fulfilled'|'rejected', value?: unknown, reason?: unknown}>>} Results of all settled promises with status and value/reason
+   */
+  static async settle(promises) {
+    return await Promise.allSettled(promises)
+  }
+
+  /**
+   * Checks if any result in the settled promise array is rejected.
+   *
+   * @param {Array<{status: 'fulfilled'|'rejected', value?: unknown, reason?: unknown}>} settled - Array of settled promise results
+   * @returns {boolean} True if any result is rejected, false otherwise
+   */
+  static hasRejected(settled) {
+    return settled.some(r => r.status === "rejected")
+  }
+
+  /**
+   * Checks if any result in the settled promise array is fulfilled.
+   *
+   * @param {Array<{status: 'fulfilled'|'rejected', value?: unknown, reason?: unknown}>} settled - Array of settled promise results
+   * @returns {boolean} True if any result is fulfilled, false otherwise
+   */
+  static hasFulfilled(settled) {
+    return settled.some(r => r.status === "fulfilled")
+  }
+
+  /**
+   * Filters and returns all rejected results from a settled promise array.
+   *
+   * @param {Array<{status: 'fulfilled'|'rejected', value?: unknown, reason?: unknown}>} settled - Array of settled promise results
+   * @returns {Array<{status: 'rejected', reason: unknown}>} Array of rejected results
+   */
+  static rejected(settled) {
+    return settled.filter(r => r.status === "rejected")
+  }
+
+  /**
+   * Filters and returns all fulfilled results from a settled promise array.
+   *
+   * @param {Array<{status: 'fulfilled'|'rejected', value?: unknown, reason?: unknown}>} result - Array of settled promise results
+   * @returns {Array<{status: 'fulfilled', value: unknown}>} Array of fulfilled results
+   */
+  static fulfilled(result) {
+    return result.filter(r => r.status === "fulfilled")
+  }
+
+  /**
+   * Extracts the rejection reasons from a settled promise array.
+   *
+   * @param {Array<{status: 'fulfilled'|'rejected', value?: unknown, reason?: unknown}>} settled - Array of settled promise results
+   * @returns {Array<unknown>} Array of rejection reasons
+   */
+  static reasons(settled) {
+    const rejected = this.rejected(settled)
+    const reasons = rejected.map(e => e.reason)
+
+    return reasons
+  }
+
+  /**
+   * Extracts the values from fulfilled results in a settled promise array.
+   *
+   * @param {Array<{status: 'fulfilled'|'rejected', value?: unknown, reason?: unknown}>} settled - Array of settled promise results
+   * @returns {Array<unknown>} Array of fulfilled values
+   */
+  static values(settled) {
+    const fulfilled = this.fulfilled(settled)
+    const values = fulfilled.map(e => e.value)
+
+    return values
+  }
+
+  /**
+   * Throws a Tantrum containing all rejection reasons from settled promises.
+   *
+   * @param {string} message - Error message. Defaults to "GIGO"
+   * @param {Array<{status: 'fulfilled'|'rejected', value?: unknown, reason?: unknown}>} settled - Array of settled promise results
+   * @throws {Tantrum} Throws a Tantrum error with rejection reasons
+   */
+  static throw(message="GIGO", settled) {
+    const rejected = this.rejected(settled)
+    const reasons = this.reasons(rejected)
+
+    throw Tantrum.new(message, reasons)
+  }
+
+  /**
+   * Returns the first promise to resolve or reject from an array of promises.
+   * Wrapper around Promise.race for consistency with other utility methods.
+   *
+   * @param {Array<Promise<unknown>>} promises - Array of promises to race
+   * @returns {Promise<unknown>} Result of the first settled promise
+   */
+  static async race(promises) {
+    return await Promise.race(promises)
+  }
+}

package/src/browser/lib/Util.js

@@ -1,4 +1,3 @@
-import Tantrum from "./Tantrum.js"
 import Valid from "./Valid.js"
 import Collection from "./Collection.js"
 
@@ -80,103 +79,6 @@ export default class Util {
     return `${" ".repeat(leftPadding)}${work}${" ".repeat(rightPadding)}`
   }
 
-  /**
-   * Asynchronously awaits all promises in parallel.
-   * Wrapper around Promise.all for consistency with other utility methods.
-   *
-   * @param {Array<Promise<unknown>>} promises - Array of promises to await
-   * @returns {Promise<Array<unknown>>} Results of all promises
-   */
-  static async awaitAll(promises) {
-    return await Promise.all(promises)
-  }
-
-  /**
-   * Settles all promises (both fulfilled and rejected) in parallel.
-   * Wrapper around Promise.allSettled for consistency with other utility methods.
-   *
-   * @param {Array<Promise<unknown>>} promises - Array of promises to settle
-   * @returns {Promise<Array<object>>} Results of all settled promises with status and value/reason
-   */
-  static async settleAll(promises) {
-    return await Promise.allSettled(promises)
-  }
-
-  /**
-   * Checks if any result in the settled promise array is rejected.
-   *
-   * @param {Array<object>} result - Array of settled promise results.
-   * @returns {boolean} True if any result is rejected, false otherwise.
-   */
-  static anyRejected(result) {
-    return result.some(r => r.status === "rejected")
-  }
-
-  /**
-   * Filters and returns all rejected results from a settled promise array.
-   *
-   * @param {Array<object>} result - Array of settled promise results.
-   * @returns {Array<object>} Array of rejected results.
-   */
-  static settledAndRejected(result) {
-    return result.filter(r => r.status === "rejected")
-  }
-
-  /**
-   * Extracts the rejection reasons from an array of rejected promise results.
-   *
-   * @param {Array<object>} rejected - Array of rejected results.
-   * @returns {Array<unknown>} Array of rejection reasons.
-   */
-  static rejectedReasons(rejected) {
-    return rejected.map(r => r.reason)
-  }
-
-  /**
-   * Throws a Sass error containing all rejection reasons from settled promises.
-   *
-   * @param {string} [_message] - Optional error message. Defaults to "GIGO"
-   * @param {Array<object>} rejected - Array of rejected results.
-   * @throws {Error} Throws a Tantrum error with rejection reasons.
-   */
-  static throwRejected(message="GIGO", settled) {
-    throw Tantrum.new(
-      message,
-      this.rejectedReasons(this.settledAndRejected(settled))
-    )
-  }
-
-  /**
-   * Filters and returns all fulfilled results from a settled promise array.
-   *
-   * @param {Array<object>} result - Array of settled promise results.
-   * @returns {Array<object>} Array of fulfilled results.
-   */
-  static settledAndFulfilled(result) {
-    return result.filter(r => r.status === "fulfilled")
-  }
-
-  /**
-   * Extracts the values from all fulfilled results in a settled promise array.
-   *
-   * @param {Array<object>} result - Array of settled promise results.
-   * @returns {Array<unknown>} Array of fulfilled values.
-   */
-  static fulfilledValues(result) {
-    return this.settledAndFulfilled(result).map(r => r.value)
-  }
-
-  /**
-   * Returns the first promise to resolve or reject from an array of promises.
-   * Wrapper around Promise.race for consistency with other utility methods.
-   *
-   * @param {Array<Promise<unknown>>} promises - Array of promises to race
-   * @returns {Promise<unknown>} Result of the first settled promise
-   */
-  static async race(promises) {
-    return await Promise.race(promises)
-  }
-
   /**
    * Determine the Levenshtein distance between two string values
    *

package/src/index.js

@@ -3,6 +3,7 @@ export {default as Collection} from "./browser/lib/Collection.js"
 export {default as Data} from "./browser/lib/Data.js"
 export {default as Disposer} from "./browser/lib/Disposer.js"
 export {Disposer as DisposerClass} from "./browser/lib/Disposer.js"
+export {default as Promised} from "./browser/lib/Promised.js"
 export {default as Type} from "./browser/lib/TypeSpec.js"
 export {default as Valid} from "./lib/Valid.js"
 

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

@@ -85,12 +85,10 @@ export default class FileObject extends FS {
     if(Data.isType(fileName, "FileObject"))
       fileName = fileName.path
 
-    if(!fileName || typeof fileName !== "string" || fileName.length === 0) {
+    if(!fileName || typeof fileName !== "string" || fileName.length === 0)
       throw Sass.new("fileName must be a non-empty string")
-    }
 
     const fixedFile = FS.fixSlashes(fileName)
-
     const {dir,base,ext} = this.#deconstructFilenameToParts(fixedFile)
 
     const parentObject = (() => {
@@ -98,6 +96,7 @@ export default class FileObject extends FS {
         case "String":
           return new DirectoryObject(parent)
         case "DirectoryObject":
+        case "CappedDirectoryObject":
         case "TempDirectoryObject":
           return parent
         default:
@@ -105,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))
@@ -115,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)
 
@@ -186,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
   }
 
   /**
@@ -266,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
    *
@@ -273,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(_) {
@@ -288,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(_) {
@@ -303,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(_) {
@@ -318,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(_) {
@@ -334,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/browser/index.d.ts

@@ -1,6 +1,7 @@
 export { default as Collection } from "./lib/Collection.js";
 export { default as Data } from "./lib/Data.js";
 export { default as Notify } from "./lib/Notify.js";
+export { default as Promised } from "./lib/Promised.js";
 export { default as Sass } from "./lib/Sass.js";
 export { default as Tantrum } from "./lib/Tantrum.js";
 export { default as Type } from "./lib/TypeSpec.js";

package/src/types/browser/lib/Promised.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Utility class providing helper functions for working with Promises,
+ * including settling, filtering, and extracting values from promise results.
+ */
+export default class Promised {
+    /**
+     * Asynchronously awaits all promises in parallel.
+     * Wrapper around Promise.all for consistency with other utility methods.
+     *
+     * @param {Array<Promise<unknown>>} promises - Array of promises to await
+     * @returns {Promise<Array<unknown>>} Results of all promises
+     */
+    static await(promises: Array<Promise<unknown>>): Promise<Array<unknown>>;
+    /**
+     * Settles all promises (both fulfilled and rejected) in parallel.
+     * Wrapper around Promise.allSettled for consistency with other utility methods.
+     *
+     * @param {Array<Promise<unknown>>} promises - Array of promises to settle
+     * @returns {Promise<Array<{status: 'fulfilled'|'rejected', value?: unknown, reason?: unknown}>>} Results of all settled promises with status and value/reason
+     */
+    static settle(promises: Array<Promise<unknown>>): Promise<Array<{
+        status: "fulfilled" | "rejected";
+        value?: unknown;
+        reason?: unknown;
+    }>>;
+    /**
+     * Checks if any result in the settled promise array is rejected.
+     *
+     * @param {Array<{status: 'fulfilled'|'rejected', value?: unknown, reason?: unknown}>} settled - Array of settled promise results
+     * @returns {boolean} True if any result is rejected, false otherwise
+     */
+    static hasRejected(settled: Array<{
+        status: "fulfilled" | "rejected";
+        value?: unknown;
+        reason?: unknown;
+    }>): boolean;
+    /**
+     * Checks if any result in the settled promise array is fulfilled.
+     *
+     * @param {Array<{status: 'fulfilled'|'rejected', value?: unknown, reason?: unknown}>} settled - Array of settled promise results
+     * @returns {boolean} True if any result is fulfilled, false otherwise
+     */
+    static hasFulfilled(settled: Array<{
+        status: "fulfilled" | "rejected";
+        value?: unknown;
+        reason?: unknown;
+    }>): boolean;
+    /**
+     * Filters and returns all rejected results from a settled promise array.
+     *
+     * @param {Array<{status: 'fulfilled'|'rejected', value?: unknown, reason?: unknown}>} settled - Array of settled promise results
+     * @returns {Array<{status: 'rejected', reason: unknown}>} Array of rejected results
+     */
+    static rejected(settled: Array<{
+        status: "fulfilled" | "rejected";
+        value?: unknown;
+        reason?: unknown;
+    }>): Array<{
+        status: "rejected";
+        reason: unknown;
+    }>;
+    /**
+     * Filters and returns all fulfilled results from a settled promise array.
+     *
+     * @param {Array<{status: 'fulfilled'|'rejected', value?: unknown, reason?: unknown}>} result - Array of settled promise results
+     * @returns {Array<{status: 'fulfilled', value: unknown}>} Array of fulfilled results
+     */
+    static fulfilled(result: Array<{
+        status: "fulfilled" | "rejected";
+        value?: unknown;
+        reason?: unknown;
+    }>): Array<{
+        status: "fulfilled";
+        value: unknown;
+    }>;
+    /**
+     * Extracts the rejection reasons from a settled promise array.
+     *
+     * @param {Array<{status: 'fulfilled'|'rejected', value?: unknown, reason?: unknown}>} settled - Array of settled promise results
+     * @returns {Array<unknown>} Array of rejection reasons
+     */
+    static reasons(settled: Array<{
+        status: "fulfilled" | "rejected";
+        value?: unknown;
+        reason?: unknown;
+    }>): Array<unknown>;
+    /**
+     * Extracts the values from fulfilled results in a settled promise array.
+     *
+     * @param {Array<{status: 'fulfilled'|'rejected', value?: unknown, reason?: unknown}>} settled - Array of settled promise results
+     * @returns {Array<unknown>} Array of fulfilled values
+     */
+    static values(settled: Array<{
+        status: "fulfilled" | "rejected";
+        value?: unknown;
+        reason?: unknown;
+    }>): Array<unknown>;
+    /**
+     * Throws a Tantrum containing all rejection reasons from settled promises.
+     *
+     * @param {string} message - Error message. Defaults to "GIGO"
+     * @param {Array<{status: 'fulfilled'|'rejected', value?: unknown, reason?: unknown}>} settled - Array of settled promise results
+     * @throws {Tantrum} Throws a Tantrum error with rejection reasons
+     */
+    static throw(message: string, settled: Array<{
+        status: "fulfilled" | "rejected";
+        value?: unknown;
+        reason?: unknown;
+    }>): void;
+    /**
+     * Returns the first promise to resolve or reject from an array of promises.
+     * Wrapper around Promise.race for consistency with other utility methods.
+     *
+     * @param {Array<Promise<unknown>>} promises - Array of promises to race
+     * @returns {Promise<unknown>} Result of the first settled promise
+     */
+    static race(promises: Array<Promise<unknown>>): Promise<unknown>;
+}
+//# sourceMappingURL=Promised.d.ts.map

package/src/types/browser/lib/Promised.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Promised.d.ts","sourceRoot":"","sources":["../../../browser/lib/Promised.js"],"names":[],"mappings":"AAEA;;;GAGG;AACH;IACE;;;;;;OAMG;IACH,uBAHW,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,GACrB,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAInC;IAED;;;;;;OAMG;IACH,wBAHW,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,GACrB,OAAO,CAAC,KAAK,CAAC;QAAC,MAAM,EAAE,WAAW,GAAC,UAAU,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,CAAA;KAAC,CAAC,CAAC,CAI/F;IAED;;;;;OAKG;IACH,4BAHW,KAAK,CAAC;QAAC,MAAM,EAAE,WAAW,GAAC,UAAU,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,CAAA;KAAC,CAAC,GACxE,OAAO,CAInB;IAED;;;;;OAKG;IACH,6BAHW,KAAK,CAAC;QAAC,MAAM,EAAE,WAAW,GAAC,UAAU,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,CAAA;KAAC,CAAC,GACxE,OAAO,CAInB;IAED;;;;;OAKG;IACH,yBAHW,KAAK,CAAC;QAAC,MAAM,EAAE,WAAW,GAAC,UAAU,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,CAAA;KAAC,CAAC,GACxE,KAAK,CAAC;QAAC,MAAM,EAAE,UAAU,CAAC;QAAC,MAAM,EAAE,OAAO,CAAA;KAAC,CAAC,CAIxD;IAED;;;;;OAKG;IACH,yBAHW,KAAK,CAAC;QAAC,MAAM,EAAE,WAAW,GAAC,UAAU,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,CAAA;KAAC,CAAC,GACxE,KAAK,CAAC;QAAC,MAAM,EAAE,WAAW,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAC,CAAC,CAIxD;IAED;;;;;OAKG;IACH,wBAHW,KAAK,CAAC;QAAC,MAAM,EAAE,WAAW,GAAC,UAAU,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,CAAA;KAAC,CAAC,GACxE,KAAK,CAAC,OAAO,CAAC,CAO1B;IAED;;;;;OAKG;IACH,uBAHW,KAAK,CAAC;QAAC,MAAM,EAAE,WAAW,GAAC,UAAU,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,CAAA;KAAC,CAAC,GACxE,KAAK,CAAC,OAAO,CAAC,CAO1B;IAED;;;;;;OAMG;IACH,sBAJW,MAAM,WACN,KAAK,CAAC;QAAC,MAAM,EAAE,WAAW,GAAC,UAAU,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,CAAA;KAAC,CAAC,QAQpF;IAED;;;;;;OAMG;IACH,sBAHW,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,GACrB,OAAO,CAAC,OAAO,CAAC,CAI5B;CACF"}

package/src/types/browser/lib/Util.d.ts

@@ -39,73 +39,6 @@ export default class Util {
      * @returns {string} Padded string with text centred.
      */
     static centreAlignText(text: string | number, width?: number): string;
-    /**
-     * Asynchronously awaits all promises in parallel.
-     * Wrapper around Promise.all for consistency with other utility methods.
-     *
-     * @param {Array<Promise<unknown>>} promises - Array of promises to await
-     * @returns {Promise<Array<unknown>>} Results of all promises
-     */
-    static awaitAll(promises: Array<Promise<unknown>>): Promise<Array<unknown>>;
-    /**
-     * Settles all promises (both fulfilled and rejected) in parallel.
-     * Wrapper around Promise.allSettled for consistency with other utility methods.
-     *
-     * @param {Array<Promise<unknown>>} promises - Array of promises to settle
-     * @returns {Promise<Array<object>>} Results of all settled promises with status and value/reason
-     */
-    static settleAll(promises: Array<Promise<unknown>>): Promise<Array<object>>;
-    /**
-     * Checks if any result in the settled promise array is rejected.
-     *
-     * @param {Array<object>} result - Array of settled promise results.
-     * @returns {boolean} True if any result is rejected, false otherwise.
-     */
-    static anyRejected(result: Array<object>): boolean;
-    /**
-     * Filters and returns all rejected results from a settled promise array.
-     *
-     * @param {Array<object>} result - Array of settled promise results.
-     * @returns {Array<object>} Array of rejected results.
-     */
-    static settledAndRejected(result: Array<object>): Array<object>;
-    /**
-     * Extracts the rejection reasons from an array of rejected promise results.
-     *
-     * @param {Array<object>} rejected - Array of rejected results.
-     * @returns {Array<unknown>} Array of rejection reasons.
-     */
-    static rejectedReasons(rejected: Array<object>): Array<unknown>;
-    /**
-     * Throws a Sass error containing all rejection reasons from settled promises.
-     *
-     * @param {string} [_message] - Optional error message. Defaults to "GIGO"
-     * @param {Array<object>} rejected - Array of rejected results.
-     * @throws {Error} Throws a Tantrum error with rejection reasons.
-     */
-    static throwRejected(message: string, settled: any): void;
-    /**
-     * Filters and returns all fulfilled results from a settled promise array.
-     *
-     * @param {Array<object>} result - Array of settled promise results.
-     * @returns {Array<object>} Array of fulfilled results.
-     */
-    static settledAndFulfilled(result: Array<object>): Array<object>;
-    /**
-     * Extracts the values from all fulfilled results in a settled promise array.
-     *
-     * @param {Array<object>} result - Array of settled promise results.
-     * @returns {Array<unknown>} Array of fulfilled values.
-     */
-    static fulfilledValues(result: Array<object>): Array<unknown>;
-    /**
-     * Returns the first promise to resolve or reject from an array of promises.
-     * Wrapper around Promise.race for consistency with other utility methods.
-     *
-     * @param {Array<Promise<unknown>>} promises - Array of promises to race
-     * @returns {Promise<unknown>} Result of the first settled promise
-     */
-    static race(promises: Array<Promise<unknown>>): Promise<unknown>;
     /**
      * Determine the Levenshtein distance between two string values
      *

package/src/types/browser/lib/Util.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Util.d.ts","sourceRoot":"","sources":["../../../browser/lib/Util.js"],"names":[],"mappings":"AAIA;;;GAGG;AACH;IACE;;;;;OAKG;IACH,wBAHW,MAAM,GACJ,MAAM,CAYlB;IAED;;;;;;OAMG;IACH,YAJa,CAAC,MACH,MAAM,OAAO,CAAC,CAAC,CAAC,GACd,OAAO,CAAC;QAAC,MAAM,EAAE,CAAC,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAC,CAAC,CAQ9C;IAED;;;;;;;OAOG;IACH,4BAJW,MAAM,GAAC,MAAM,UACb,MAAM,GACJ,MAAM,CAWlB;IAED;;;;;;;OAOG;IACH,6BAJW,MAAM,GAAC,MAAM,UACb,MAAM,GACJ,MAAM,CAalB;IAED;;;;;;OAMG;IACH,0BAHW,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,GACrB,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAInC;IAED;;;;;;OAMG;IACH,2BAHW,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,GACrB,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAIlC;IAED;;;;;OAKG;IACH,2BAHW,KAAK,CAAC,MAAM,CAAC,GACX,OAAO,CAInB;IAED;;;;;OAKG;IACH,kCAHW,KAAK,CAAC,MAAM,CAAC,GACX,KAAK,CAAC,MAAM,CAAC,CAIzB;IAED;;;;;OAKG;IACH,iCAHW,KAAK,CAAC,MAAM,CAAC,GACX,KAAK,CAAC,OAAO,CAAC,CAI1B;IAED;;;;;;OAMG;IACH,0DAKC;IAED;;;;;OAKG;IACH,mCAHW,KAAK,CAAC,MAAM,CAAC,GACX,KAAK,CAAC,MAAM,CAAC,CAIzB;IAED;;;;;OAKG;IACH,+BAHW,KAAK,CAAC,MAAM,CAAC,GACX,KAAK,CAAC,OAAO,CAAC,CAI1B;IAED;;;;;;OAMG;IACH,sBAHW,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,GACrB,OAAO,CAAC,OAAO,CAAC,CAI5B;IAED;;;;;;OAMG;IACH,8BAJW,MAAM,KACN,MAAM,GACJ,MAAM,CAsBlB;IAED;;;;;;;;OAQG;IACH,+BALW,MAAM,iBACN,KAAK,CAAC,MAAM,CAAC,cACb,MAAM,GACJ,MAAM,CAwBlB;IAED,mEAiBC;CACF"}
+{"version":3,"file":"Util.d.ts","sourceRoot":"","sources":["../../../browser/lib/Util.js"],"names":[],"mappings":"AAGA;;;GAGG;AACH;IACE;;;;;OAKG;IACH,wBAHW,MAAM,GACJ,MAAM,CAYlB;IAED;;;;;;OAMG;IACH,YAJa,CAAC,MACH,MAAM,OAAO,CAAC,CAAC,CAAC,GACd,OAAO,CAAC;QAAC,MAAM,EAAE,CAAC,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAC,CAAC,CAQ9C;IAED;;;;;;;OAOG;IACH,4BAJW,MAAM,GAAC,MAAM,UACb,MAAM,GACJ,MAAM,CAWlB;IAED;;;;;;;OAOG;IACH,6BAJW,MAAM,GAAC,MAAM,UACb,MAAM,GACJ,MAAM,CAalB;IAED;;;;;;OAMG;IACH,8BAJW,MAAM,KACN,MAAM,GACJ,MAAM,CAsBlB;IAED;;;;;;;;OAQG;IACH,+BALW,MAAM,iBACN,KAAK,CAAC,MAAM,CAAC,cACb,MAAM,GACJ,MAAM,CAwBlB;IAED,mEAiBC;CACF"}

package/src/types/index.d.ts

@@ -1,5 +1,6 @@
 export { default as Collection } from "./browser/lib/Collection.js";
 export { default as Data } from "./browser/lib/Data.js";
+export { default as Promised } from "./browser/lib/Promised.js";
 export { default as Type } from "./browser/lib/TypeSpec.js";
 export { default as Valid } from "./lib/Valid.js";
 export { default as Sass } from "./lib/Sass.js";

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;uBAgIe,MAAM;IA/HnB;;;;;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,EAoDrC;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;eA/gBc,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"}