@gesslar/toolkit 3.8.0 → 3.12.3

package/src/lib/TempDirectoryObject.js

@@ -4,13 +4,16 @@
  * to the OS's temporary directory tree.
  */
 
-import fs from "node:fs"
+import fs, {mkdirSync, mkdtempSync} from "node:fs"
 import os from "node:os"
 import path from "node:path"
 
-import CappedDirectoryObject from "./CappedDirectoryObject.js"
 import Data from "../browser/lib/Data.js"
+import CappedDirectoryObject from "./CappedDirectoryObject.js"
+import DirectoryObject from "./DirectoryObject.js"
+import FS from "./FS.js"
 import Sass from "./Sass.js"
+import Valid from "./Valid.js"
 
 /**
  * TempDirectoryObject extends CappedDirectoryObject with the cap set to
@@ -23,6 +26,8 @@ import Sass from "./Sass.js"
  * @augments CappedDirectoryObject
  */
 export default class TempDirectoryObject extends CappedDirectoryObject {
+  #tmpReal
+  #tmpCap
 
   /**
    * Constructs a TempDirectoryObject instance and creates the directory.
@@ -34,7 +39,7 @@ export default class TempDirectoryObject extends CappedDirectoryObject {
    * is provided without a parent, creates a new directory with a unique suffix.
    * If a parent is provided, creates a subdirectory within that parent.
    *
-   * @param {string?} [name] - Base name for the temp directory (if empty/null, uses OS temp dir)
+   * @param {string?} [directory] - Base name for the temp directory (if empty/null, uses OS temp dir)
    * @param {TempDirectoryObject?} [parent] - Optional parent temporary directory
    * @throws {Sass} If name is absolute
    * @throws {Sass} If name is empty (when parent is provided)
@@ -43,159 +48,118 @@ export default class TempDirectoryObject extends CappedDirectoryObject {
    * @throws {Sass} If parent's lineage does not trace back to the OS temp directory
    * @throws {Sass} If directory creation fails
    * @example
-   * // Use OS temp directory directly
-   * const temp = new TempDirectoryObject()
-   * console.log(temp.path) // "/tmp"
-   *
-   * @example
    * // Create with unique name
    * const temp = new TempDirectoryObject("myapp")
-   * console.log(temp.path) // "/tmp/myapp-ABC123"
-   *
-   * @example
-   * // Nested temp directories
-   * const parent = new TempDirectoryObject("parent")
-   * const child = new TempDirectoryObject("child", parent)
-   * await parent.remove() // Removes both parent and child
+   * console.log(temp.path) // "/"
+   * console.log(temp.real.path) // "/tmp/myapp-ABC123"
    */
-  constructor(name, parent=null) {
-    let dirPath
-    let cappedParent = parent
-
-    if(!parent) {
-      // No parent: need to create a capped parent at tmpdir first
-      cappedParent = new CappedDirectoryObject(os.tmpdir(), null, true)
-
-      if(name) {
-        // Check if name is a simple name (no separators, not absolute)
-        const isSimpleName = !path.isAbsolute(name) &&
-                             !name.includes("/") &&
-                             !name.includes("\\") &&
-                             !name.includes(path.sep)
-
-        if(isSimpleName) {
-          // Simple name: add unique suffix
-          const prefix = name.endsWith("-") ? name : `${name}-`
-          const uniqueSuffix =
-            Math.random()
-              .toString(36)
-              .substring(2, 8)
-              .toUpperCase()
-          dirPath = `${prefix}${uniqueSuffix}`
-        } else {
-          // Complex path: use as-is, let CappedDirectoryObject handle coercion
-          dirPath = name
-        }
-      } else {
-        // No name: use tmpdir itself (no parent)
-        dirPath = os.tmpdir()
-        cappedParent = null
-      }
-    } else {
-      // With parent: validate it's a proper temp directory parent
-      if(!Data.isType(parent, "CappedDirectoryObject")) {
-        throw Sass.new(
-          "Parent must be a CappedDirectoryObject or TempDirectoryObject."
-        )
-      }
-
-      // SECURITY: Ensure parent's cap is within tmpdir (prevent escape to other caps)
-      const tmpdir = path.resolve(os.tmpdir())
-      const parentCap = path.resolve(parent.cap)
-
-      if(!parentCap.startsWith(tmpdir)) {
-        throw Sass.new(
-          `Parent must be capped to OS temp directory (${tmpdir}) or a subdirectory thereof, ` +
-          `got cap: ${parent.cap}`
-        )
-      }
-
-      dirPath = name || ""
-      if(!dirPath) {
-        throw Sass.new("Name must not be empty when parent is provided.")
-      }
-    }
+  constructor(directory, source=null) {
+    Valid.type(source, "Null|TempDirectoryObject")
 
-    // Call parent constructor with new signature
-    super(dirPath, cappedParent, true)
+    directory ||= "temp"
+    directory = Data.append(directory, source ? "" : "-")
 
-    // Temp-specific behavior: create directory immediately
-    this.#createDirectory()
+    const parentRealPath = source?.real.path ?? os.tmpdir()
 
-    // Re-cap to the temp directory itself for consistent behavior with CappedDirectoryObject
-    // This makes temp.cap === temp.real.path and temp.parent === null
-    if(!parent) {
-      // Only re-cap if this is a root temp directory (no TempDirectoryObject parent)
-      this._recapToSelf()
+    if(source && path.isAbsolute(directory)) {
+      const {root} = FS.pathParts(directory)
+
+      directory = Data.chopLeft(directory, root)
     }
-  }
 
-  /**
-   * Creates the directory synchronously on the filesystem.
-   *
-   * @private
-   * @throws {Sass} If directory creation fails
-   */
-  #createDirectory() {
-    try {
-      // Use recursive: true to create parent directories as needed
-      fs.mkdirSync(this.realPath, {recursive: true})
-    } catch(e) {
-      // EEXIST is fine - directory already exists
-      if(e.code !== "EEXIST") {
-        throw Sass.new(
-          `Unable to create temporary directory '${this.realPath}': ${e.message}`
-        )
-      }
+    let realTempDirectoryPath, toSuper
+
+    if(source) {
+      toSuper = `/${directory}`
+      realTempDirectoryPath =
+        FS.mergeOverlappingPaths(parentRealPath, directory)
+      if(!fs.existsSync(realTempDirectoryPath))
+        mkdirSync(realTempDirectoryPath)
+    } else {
+      realTempDirectoryPath =
+        mkdtempSync(FS.mergeOverlappingPaths(os.tmpdir(), directory))
+      toSuper = path.resolve(path.sep)
     }
+
+    super(toSuper, source)
+
+    this.#tmpReal = new DirectoryObject(realTempDirectoryPath)
+    this.#tmpCap = source?.cap ?? this
+  }
+
+  get isTemporary() {
+    return true
   }
 
   /**
-   * Creates a new TempDirectoryObject by extending this directory's path.
+   * 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.
    *
-   * Validates that the resulting path remains within the temp directory tree.
-   *
-   * @param {string} newPath - The path segment to append
-   * @returns {TempDirectoryObject} A new TempDirectoryObject with the extended path
-   * @throws {Sass} If the path would escape the temp directory
-   * @throws {Sass} If the path is absolute
-   * @throws {Sass} If the path contains traversal (..)
+   * @returns {DirectoryObject} Uncapped directory object at the real filesystem path
    * @example
    * const temp = new TempDirectoryObject("myapp")
-   * const subDir = temp.getDirectory("data")
-   * console.log(subDir.path) // "/tmp/myapp-ABC123/data"
+   * 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
    */
-  getDirectory(newPath) {
-    // Delegate to base class getDirectory() which will call TempDirectoryObject constructor
-    return super.getDirectory(newPath)
+  get real() {
+    return this.#tmpReal
+  }
+
+  get cap() {
+    return this.#tmpCap
   }
 
   /**
-   * Creates a new FileObject by extending this directory's path.
+   * Recursively removes a temporary directory and all its contents.
    *
-   * Validates that the resulting path remains within the temp directory tree.
+   * This method will delete all files and subdirectories within this directory,
+   * then delete the directory itself. It only works on directories explicitly
+   * marked as temporary for safety.
    *
-   * @param {string} filename - The filename to append
-   * @returns {FileObject} A new FileObject with the extended path
-   * @throws {Sass} If the path would escape the temp directory
-   * @throws {Sass} If the path is absolute
-   * @throws {Sass} If the path contains traversal (..)
+   * @async
+   * @returns {Promise<void>}
+   * @throws {Sass} If the directory is not marked as temporary
+   * @throws {Sass} If the directory deletion fails
    * @example
-   * const temp = new TempDirectoryObject("myapp")
-   * const file = temp.getFile("config.json")
-   * console.log(file.path) // "/tmp/myapp-ABC123/config.json"
+   * const tempDir = new TempDirectoryObject("my-temp")
+   * await tempDir.assureExists()
+   * // ... use the directory ...
+   * await tempDir.remove() // Recursively deletes everything
    */
-  getFile(filename) {
-    // Delegate to base class getFile() which handles security checks
-    return super.getFile(filename)
+  async remove() {
+    await this.#recurseDelete(this.real)
+  }
+
+  async #recurseDelete(directory) {
+    const {files, directories} = await directory.read()
+
+    // files first
+    for(const file of files)
+      await file.delete()
+
+    // now dir-ty dirs
+    for(const dir of directories)
+      await this.#recurseDelete(dir)
+
+    // byebyebyeeee 🕺🏾
+    await directory.delete()
   }
 
   /**
-   * Returns a string representation of the TempDirectoryObject.
+   * TempDirectoryObject does not support fromCwd() since it is specifically
+   * designed to work within the OS temporary directory tree.
    *
-   * @returns {string} string representation of the TempDirectoryObject
+   * @throws {Sass} Always throws an error
    */
-  toString() {
-    return `[TempDirectoryObject: ${this.path}]`
+  static fromCwd() {
+    throw Sass.new("TempDirectoryObject.fromCwd() is not supported.")
   }
 }

package/src/lib/Valid.js

@@ -25,7 +25,7 @@ export default class Valid {
   static type(value, type, options) {
     Valid.assert(
       Data.isType(value, type, options),
-      `Invalid type. Expected ${type}, got ${JSON.stringify(value)}`,
+      `Invalid type. Expected ${type}, got ${Data.typeOf(value)}`,
       1,
     )
   }

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

@@ -36,7 +36,7 @@ export default class Data {
      * @param {string} append - The string to append
      * @returns {string} The appended string
      */
-    static appendString(string: string, append: string): string;
+    static append(string: string, append: string): string;
     /**
      * Prepends a string to another string if it does not already start with it.
      *
@@ -44,7 +44,51 @@ export default class Data {
      * @param {string} prepend - The string to prepend
      * @returns {string} The prepended string
      */
-    static prependString(string: string, prepend: string): string;
+    static prepend(string: string, prepend: string): string;
+    /**
+     * Remove a suffix from the end of a string if present.
+     *
+     * @param {string} string - The string to process
+     * @param {string} toChop - The suffix to remove from the end
+     * @param {boolean} [caseInsensitive=false] - Whether to perform case-insensitive matching
+     * @returns {string} The string with suffix removed, or original if suffix not found
+     * @example
+     * Data.chopRight("hello.txt", ".txt") // "hello"
+     * Data.chopRight("Hello", "o") // "Hell"
+     * Data.chopRight("HELLO", "lo", true) // "HEL"
+     */
+    static chopRight(string: string, toChop: string, caseInsensitive?: boolean): string;
+    /**
+     * Remove a prefix from the beginning of a string if present.
+     *
+     * @param {string} string - The string to process
+     * @param {string} toChop - The prefix to remove from the beginning
+     * @param {boolean} [caseInsensitive=false] - Whether to perform case-insensitive matching
+     * @returns {string} The string with prefix removed, or original if prefix not found
+     * @example
+     * Data.chopLeft("hello.txt", "hello") // ".txt"
+     * Data.chopLeft("Hello", "H") // "ello"
+     * Data.chopLeft("HELLO", "he", true) // "LLO"
+     */
+    static chopLeft(string: string, toChop: string, caseInsensitive?: boolean): string;
+    /**
+     * Chop a string after the first occurence of another string.
+     *
+     * @param {string} string - The string to search
+     * @param {string} needle - The bit to chop after
+     * @param {boolean} caseInsensitive - Whether to search insensitive to case
+     * @returns {string} The remaining string
+     */
+    static chopAfter(string: string, needle: string, caseInsensitive?: boolean): string;
+    /**
+     * Chop a string before the first occurrence of another string.
+     *
+     * @param {string} string - The string to search
+     * @param {string} needle - The bit to chop before
+     * @param {boolean} caseInsensitive - Whether to search insensitive to case
+     * @returns {string} The remaining string
+     */
+    static chopBefore(string: string, needle: string, caseInsensitive?: boolean): string;
     /**
      * Creates a type spec from a string. A type spec is an array of objects
      * defining the type of a value and whether an array is expected.

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

@@ -1 +1 @@
-{"version":3,"file":"Data.d.ts","sourceRoot":"","sources":["../../../browser/lib/Data.js"],"names":[],"mappings":"AAUA;IACA;;;;;OAKG;IACD,mBAFQ,KAAK,CAAC,MAAM,CAAC,CAgBnB;IAEF;;;;;OAKG;IACH,qBAFU,KAAK,CAAC,MAAM,CAAC,CAmBrB;IAEF;;;;;;;OAOG;IACH,kBAFU,KAAK,CAAC,MAAM,CAAC,CAKrB;IAEF;;;;;OAKG;IACH,uBAFU,KAAK,CAAC,MAAM,CAAC,CAE6C;IAEpE;;;;;;OAMG;IACH,4BAJW,MAAM,UACN,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;OAMG;IACH,6BAJW,MAAM,WACN,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;;OAOG;IACH,2BAJW,MAAM,WACN,MAAM,GACJ,KAAK,CAAC,MAAM,CAAC,CAIzB;IAED;;;;;;;OAOG;IACH,qBALW,OAAO,QACP,MAAM,GAAC,QAAQ,YACf,MAAM,GACJ,OAAO,CAQnB;IAED;;;;;OAKG;IACH,yBAHW,MAAM,GACJ,OAAO,CASnB;IAED;;;;;;;;OAQG;IACH,yBAJW,OAAO,QACP,MAAM,GACJ,OAAO,CAwBnB;IAED;;;;;OAKG;IACH,qBAHW,OAAO,GACL,MAAM,CAclB;IAED;;;;;OAKG;IACH,wBAHW,OAAO,GACL,OAAO,CAInB;IAED;;;;;;;;OAQG;IACH,sBALW,OAAO,oBACP,OAAO,GAEL,OAAO,CA2BnB;IAED;;;;;OAKG;IACH,6BAHW,MAAM,GACJ,MAAM,CAmBlB;IAED;;;;;;;OAOG;IACH,6BAJW,MAAM,QACN,KAAK,CAAC,MAAM,CAAC,GACX,MAAM,CAiBlB;IAED;;;;;;;OAOG;IACH,2BAJW,MAAM,QACN,KAAK,CAAC,MAAM,CAAC,SACb,OAAO,QAMjB;IAED;;;;;OAKG;IACH,+BAHc,MAAM,EAAA,GACP,MAAM,CAqBlB;IAED;;;;;;;OAOG;IACH,wBAJW,KAAK,CAAC,OAAO,CAAC,aACd,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,GAClC,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAMnC;IAED;;;;;;;OAOG;IACH,kBALW,MAAM,OACN,MAAM,OACN,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;;OAOG;IACH,oBALW,MAAM,OACN,MAAM,OACN,MAAM,GACJ,OAAO,CAInB;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACH,4BAbW,OAAO,GACL,OAAO,CA+BnB;IAED;;;;;;;;;;;;;;;OAeG;IACH,uBAXW,OAAO,GACL,OAAO,CAgBnB;CACF;qBA5aoB,eAAe"}
+{"version":3,"file":"Data.d.ts","sourceRoot":"","sources":["../../../browser/lib/Data.js"],"names":[],"mappings":"AAUA;IACA;;;;;OAKG;IACD,mBAFQ,KAAK,CAAC,MAAM,CAAC,CAgBnB;IAEF;;;;;OAKG;IACH,qBAFU,KAAK,CAAC,MAAM,CAAC,CAmBrB;IAEF;;;;;;;OAOG;IACH,kBAFU,KAAK,CAAC,MAAM,CAAC,CAKrB;IAEF;;;;;OAKG;IACH,uBAFU,KAAK,CAAC,MAAM,CAAC,CAE2D;IAElF;;;;;;OAMG;IACH,sBAJW,MAAM,UACN,MAAM,GACJ,MAAM,CAMlB;IAED;;;;;;OAMG;IACH,uBAJW,MAAM,WACN,MAAM,GACJ,MAAM,CAMlB;IAED;;;;;;;;;;;OAWG;IACH,yBATW,MAAM,UACN,MAAM,oBACN,OAAO,GACL,MAAM,CAWlB;IAED;;;;;;;;;;;OAWG;IACH,wBATW,MAAM,UACN,MAAM,oBACN,OAAO,GACL,MAAM,CAWlB;IAED;;;;;;;OAOG;IACH,yBALW,MAAM,UACN,MAAM,oBACN,OAAO,GACL,MAAM,CAWlB;IAED;;;;;;;OAOG;IACH,0BALW,MAAM,UACN,MAAM,oBACN,OAAO,GACL,MAAM,CAYlB;IAED;;;;;;;OAOG;IACH,2BAJW,MAAM,WACN,MAAM,GACJ,KAAK,CAAC,MAAM,CAAC,CAIzB;IAED;;;;;;;OAOG;IACH,qBALW,OAAO,QACP,MAAM,GAAC,QAAQ,YACf,MAAM,GACJ,OAAO,CAQnB;IAED;;;;;OAKG;IACH,yBAHW,MAAM,GACJ,OAAO,CASnB;IAED;;;;;;;;OAQG;IACH,yBAJW,OAAO,QACP,MAAM,GACJ,OAAO,CAwBnB;IAED;;;;;OAKG;IACH,qBAHW,OAAO,GACL,MAAM,CAclB;IAED;;;;;OAKG;IACH,wBAHW,OAAO,GACL,OAAO,CAInB;IAED;;;;;;;;OAQG;IACH,sBALW,OAAO,oBACP,OAAO,GAEL,OAAO,CA8BnB;IAED;;;;;OAKG;IACH,6BAHW,MAAM,GACJ,MAAM,CAmBlB;IAED;;;;;;;OAOG;IACH,6BAJW,MAAM,QACN,KAAK,CAAC,MAAM,CAAC,GACX,MAAM,CAiBlB;IAED;;;;;;;OAOG;IACH,2BAJW,MAAM,QACN,KAAK,CAAC,MAAM,CAAC,SACb,OAAO,QAMjB;IAED;;;;;OAKG;IACH,+BAHc,MAAM,EAAA,GACP,MAAM,CAqBlB;IAED;;;;;;;OAOG;IACH,wBAJW,KAAK,CAAC,OAAO,CAAC,aACd,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,GAClC,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAMnC;IAED;;;;;;;OAOG;IACH,kBALW,MAAM,OACN,MAAM,OACN,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;;OAOG;IACH,oBALW,MAAM,OACN,MAAM,OACN,MAAM,GACJ,OAAO,CAInB;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACH,4BAbW,OAAO,GACL,OAAO,CA+BnB;IAED;;;;;;;;;;;;;;;OAeG;IACH,uBAXW,OAAO,GACL,OAAO,CAgBnB;CACF;qBAhgBoB,eAAe"}

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

@@ -1 +1 @@
-{"version":3,"file":"TypeSpec.d.ts","sourceRoot":"","sources":["../../../browser/lib/TypeSpec.js"],"names":[],"mappings":"AAWA;;;GAGG;AACH;IAGE;;;;;OAKG;IACH,oBAHW,MAAM,WACN,OAAO,EAUjB;IAJC,aAAwB;IACxB,eAAgC;IAChC,6BAA2C;IAI7C;;;;OAIG;IACH,YAFa,MAAM,CAQlB;IAED;;;;OAIG;IACH,UAFa,OAAO,CASnB;IAED;;;;OAIG;IACH,kBAFW,CAAS,IAAO,EAAP,OAAO,KAAG,IAAI,QAIjC;IAED;;;;;OAKG;IACH,gBAHW,CAAS,IAAO,EAAP,OAAO,KAAG,OAAO,GACxB,OAAO,CAInB;IAED;;;;;OAKG;IACH,eAHW,CAAS,IAAO,EAAP,OAAO,KAAG,OAAO,GACxB,OAAO,CAInB;IAED;;;;;OAKG;IACH,iBAHW,CAAS,IAAO,EAAP,OAAO,KAAG,OAAO,GACxB,KAAK,CAAC,OAAO,CAAC,CAI1B;IAED;;;;;OAKG;IACH,cAHW,CAAS,IAAO,EAAP,OAAO,KAAG,OAAO,GACxB,KAAK,CAAC,OAAO,CAAC,CAI1B;IAED;;;;;;OAMG;IACH,iBAJW,CAAS,IAAO,EAAP,OAAO,EAAE,IAAO,EAAP,OAAO,KAAG,OAAO,gBACnC,OAAO,GACL,OAAO,CAInB;IAED;;;;;OAKG;IACH,eAHW,CAAS,IAAO,EAAP,OAAO,KAAG,OAAO,GACxB,MAAM,GAAC,SAAS,CAI5B;IAED;;;;;;;;OAQG;IACH,eALW,OAAO,WACP,OAAO,GAEL,OAAO,CAInB;IAED,2CA2DC;;CAmDF"}
+{"version":3,"file":"TypeSpec.d.ts","sourceRoot":"","sources":["../../../browser/lib/TypeSpec.js"],"names":[],"mappings":"AAWA;;;GAGG;AACH;IAGE;;;;;OAKG;IACH,oBAHW,MAAM,WACN,OAAO,EAUjB;IAJC,aAAwB;IACxB,eAAgC;IAChC,6BAA2C;IAI7C;;;;OAIG;IACH,YAFa,MAAM,CAQlB;IAED;;;;OAIG;IACH,UAFa,OAAO,CASnB;IAED;;;;OAIG;IACH,kBAFW,CAAS,IAAO,EAAP,OAAO,KAAG,IAAI,QAIjC;IAED;;;;;OAKG;IACH,gBAHW,CAAS,IAAO,EAAP,OAAO,KAAG,OAAO,GACxB,OAAO,CAInB;IAED;;;;;OAKG;IACH,eAHW,CAAS,IAAO,EAAP,OAAO,KAAG,OAAO,GACxB,OAAO,CAInB;IAED;;;;;OAKG;IACH,iBAHW,CAAS,IAAO,EAAP,OAAO,KAAG,OAAO,GACxB,KAAK,CAAC,OAAO,CAAC,CAI1B;IAED;;;;;OAKG;IACH,cAHW,CAAS,IAAO,EAAP,OAAO,KAAG,OAAO,GACxB,KAAK,CAAC,OAAO,CAAC,CAI1B;IAED;;;;;;OAMG;IACH,iBAJW,CAAS,IAAO,EAAP,OAAO,EAAE,IAAO,EAAP,OAAO,KAAG,OAAO,gBACnC,OAAO,GACL,OAAO,CAInB;IAED;;;;;OAKG;IACH,eAHW,CAAS,IAAO,EAAP,OAAO,KAAG,OAAO,GACxB,MAAM,GAAC,SAAS,CAI5B;IAED;;;;;;;;OAQG;IACH,eALW,OAAO,WACP,OAAO,GAEL,OAAO,CAInB;IAED,2CA6DC;;CAmDF"}

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

@@ -8,6 +8,19 @@
  * @augments DirectoryObject
  */
 export default class CappedDirectoryObject extends DirectoryObject {
+    /**
+     * Creates a CappedDirectoryObject from the current working directory.
+     * This is useful when working with pnpx or other tools where you need to
+     * cap at the project's root directory determined at runtime.
+     *
+     * @returns {CappedDirectoryObject} A CappedDirectoryObject capped at the current working directory
+     * @example
+     * // When using pnpx or similar tools
+     * const projectRoot = CappedDirectoryObject.fromCwd()
+     * const srcDir = projectRoot.getDirectory("src")
+     * // srcDir is capped at the project root
+     */
+    static fromCwd(): CappedDirectoryObject;
     /**
      * Constructs a CappedDirectoryObject instance.
      *
@@ -15,13 +28,16 @@ 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)
+     * @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 path is empty
      * @throws {Sass} If parent is provided but not a CappedDirectoryObject
      * @throws {Sass} If the resulting path would escape the cap
      * @example
+     * // Create new capped directory at current directory
+     * const cwd = new CappedDirectoryObject()
+     * // path: process.cwd(), cap: process.cwd()
+     *
+     * @example
      * // Create new capped directory
      * const cache = new CappedDirectoryObject("/home/user/.cache")
      * // path: /home/user/.cache, cap: /home/user/.cache
@@ -36,33 +52,34 @@ 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: string, parent?: CappedDirectoryObject | null, temporary?: boolean);
+    constructor(directory?: string, source?: any);
     /**
-     * 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.
+     * Indicates whether this directory is capped (constrained to a specific tree).
+     * Always returns true for CappedDirectoryObject instances.
      *
-     * @protected
-     */
-    protected _recapToSelf(): void;
-    /**
-     * Returns the cap path for this directory.
+     * @returns {boolean} True for all CappedDirectoryObject instances
+     * @example
+     * const capped = new TempDirectoryObject("myapp")
+     * console.log(capped.isCapped) // true
      *
-     * @returns {string} The cap directory path
+     * const regular = new DirectoryObject("/tmp")
+     * console.log(regular.isCapped) // false
      */
-    get cap(): string;
+    get isCapped(): boolean;
     /**
-     * Returns whether this directory is capped.
+     * 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 {boolean} Always true for CappedDirectoryObject instances
-     */
-    get capped(): boolean;
-    /**
-     * Returns the real filesystem path (for internal and subclass use).
+     * @returns {CappedDirectoryObject} The cap directory object (root of the capped tree)
+     * @example
+     * const temp = new TempDirectoryObject("myapp")
+     * console.log(temp.cap === temp) // true (root is its own cap)
      *
-     * @protected
-     * @returns {string} The actual filesystem path
+     * const subdir = temp.getDirectory("data")
+     * console.log(subdir.cap === temp) // true (child inherits parent's cap)
      */
-    protected get realPath(): string;
+    get cap(): CappedDirectoryObject;
     /**
      * Returns a plain DirectoryObject representing the actual filesystem location.
      * This provides an "escape hatch" from the capped environment to interact
@@ -98,50 +115,25 @@ export default class CappedDirectoryObject extends DirectoryObject {
      */
     get parent(): CappedDirectoryObject | null;
     /**
-     * Returns the URL with virtual path (cap-relative).
-     *
-     * @returns {URL} Virtual URL
-     */
-    get url(): URL;
-    /**
-     * Returns a generator that walks up to the cap.
-     *
-     * @returns {Generator<DirectoryObject>} Generator yielding parent directories
-     */
-    get walkUp(): Generator<DirectoryObject>;
-    /**
-     * 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"
+     * 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.getDirectory("/foo/bar")
-     * console.log(abs.path) // "/tmp/myapp-ABC123/foo/bar"
+     * const temp = new TempDirectoryObject("myapp")
+     * console.log(temp.parentPath) // null (at cap root)
      *
-     * @example
-     * // Excessive .. traversal clamps to cap
-     * const up = capped.getDirectory("../../../etc/passwd")
-     * console.log(up.path) // "/tmp/myapp-ABC123" (clamped to cap)
+     * const subdir = temp.getDirectory("data")
+     * console.log(subdir.parentPath) // "/data" or similar (parent's virtual path)
      */
-    getDirectory(newPath: string): CappedDirectoryObject;
+    get parentPath(): string | null;
     /**
      * 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<{
+    read(...arg: any[]): Promise<{
         files: Array<FileObject>;
         directories: any[];
     }>;

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

@@ -1 +1 @@
-{"version":3,"file":"CappedDirectoryObject.d.ts","sourceRoot":"","sources":["../../lib/CappedDirectoryObject.js"],"names":[],"mappings":"AAkBA;;;;;;;;GAQG;AACH;IAGE;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,qBArBW,MAAM,WACN,qBAAqB,OAAC,cACtB,OAAO,EA0EjB;IAqBD;;;;;OAKG;IACH,+BAEC;IAED;;;;OAIG;IACH,WAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,cAFa,OAAO,CAInB;IAED;;;;;OAKG;IACH,0BAFa,MAAM,CAIlB;IAqCD;;;;;;;;;;;;;;;;;OAiBG;IACH,YAba,eAAe,CAe3B;IAED;;;;;;;;;;;;;OAaG;IACH,cAPa,qBAAqB,GAAC,IAAI,CA0BtC;IAED;;;;OAIG;IACH,WAFa,GAAG,CAIf;IAqFD;;;;OAIG;IACH,cAFa,SAAS,CAAC,eAAe,CAAC,CAItC;IAED;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,sBAjBW,MAAM,GACJ,qBAAqB,CAiEjC;IAsID;;;;;OAKG;IACH,WAHW,MAAM,GACJ,OAAO,CAAC;QAAC,KAAK,EAAE,KAAK,CAAC,UAAU,CAAC,CAAC;QAAC,WAAW,QAAO;KAAC,CAAC,CAgBnE;;CA8DF;4BAloB2B,sBAAsB;uBAC3B,iBAAiB"}
+{"version":3,"file":"CappedDirectoryObject.d.ts","sourceRoot":"","sources":["../../lib/CappedDirectoryObject.js"],"names":[],"mappings":"AAiBA;;;;;;;;GAQG;AACH;IAoEE;;;;;;;;;;;OAWG;IACH,kBAPa,qBAAqB,CASjC;IA5ED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACH,wBAxBW,MAAM,gBAqDhB;IAkBD;;;;;;;;;;;OAWG;IACH,gBARa,OAAO,CAUnB;IAED;;;;;;;;;;;;OAYG;IACH,WARa,qBAAqB,CAUjC;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,YAba,eAAe,CAe3B;IAED;;;;;;;;;;;;;OAaG;IACH,cAPa,qBAAqB,GAAC,IAAI,CAStC;IAED;;;;;;;;;;;OAWG;IACH,kBARa,MAAM,GAAC,IAAI,CAUvB;IAkCD;;;;;OAKG;IACH,qBAFa,OAAO,CAAC;QAAC,KAAK,EAAE,KAAK,CAAC,UAAU,CAAC,CAAC;QAAC,WAAW,QAAO;KAAC,CAAC,CAUnE;;CA8BF;4BAvQ2B,sBAAsB;uBAC3B,iBAAiB"}