@gesslar/toolkit 3.7.0 → 3.8.0

package/package.json

@@ -5,7 +5,7 @@
     "name": "gesslar",
     "url": "https://gesslar.dev"
   },
-  "version": "3.7.0",
+  "version": "3.8.0",
   "license": "Unlicense",
   "homepage": "https://github.com/gesslar/toolkit#readme",
   "repository": {

package/src/lib/CappedDirectoryObject.js

@@ -132,6 +132,16 @@ export default class CappedDirectoryObject extends DirectoryObject {
     }
   }
 
+  /**
+   * Re-caps this directory to itself, making it the new root of the capped tree.
+   * This is a protected method intended for use by subclasses like TempDirectoryObject.
+   *
+   * @protected
+   */
+  _recapToSelf() {
+    this.#cap = this.#realPath
+  }
+
   /**
    * Returns the cap path for this directory.
    *
@@ -221,14 +231,14 @@ export default class CappedDirectoryObject extends DirectoryObject {
    * Returns the parent directory of this capped directory.
    * Returns null only if this directory is at the cap (the "root" of the capped tree).
    *
-   * Note: The returned parent is a plain DirectoryObject (not capped).
-   * Use getDirectory() for creating capped subdirectories.
+   * Note: The returned parent is a CappedDirectoryObject with the same cap.
+   * This maintains the capping behavior throughout the directory hierarchy.
    *
-   * @returns {DirectoryObject|null} Parent directory or null if at cap root
+   * @returns {CappedDirectoryObject|null} Parent directory or null if at cap root
    * @example
    * const capped = new TempDirectoryObject("myapp")
    * const subdir = capped.getDirectory("data")
-   * console.log(subdir.parent.path) // Returns parent DirectoryObject
+   * console.log(subdir.parent.path) // Returns parent CappedDirectoryObject
    * console.log(capped.parent) // null (at cap root)
    */
   get parent() {
@@ -239,13 +249,17 @@ export default class CappedDirectoryObject extends DirectoryObject {
       return null
     }
 
-    // Otherwise return the parent using real path (plain DirectoryObject, not capped)
+    // Compute parent's real path
     const parentPath = path.dirname(this.#realPath)
     const isRoot = parentPath === this.#realPath
 
-    return isRoot
-      ? null
-      : new DirectoryObject(parentPath, this.temporary)
+    if(isRoot) {
+      return null
+    }
+
+    // Compute relative path from current to parent (just "..")
+    // Then use getDirectory to create the parent, which preserves the class type
+    return this.getDirectory("..")
   }
 
   /**
@@ -264,9 +278,24 @@ export default class CappedDirectoryObject extends DirectoryObject {
    */
   toJSON() {
     const capResolved = path.resolve(this.#cap)
-    const parentPath = this.#realPath === capResolved
-      ? null
-      : "/"
+    let parentPath
+
+    if(this.#realPath === capResolved) {
+      // At cap root, no parent
+      parentPath = null
+    } else {
+      // Compute parent's virtual path
+      const parentReal = path.dirname(this.#realPath)
+      const relative = path.relative(capResolved, parentReal)
+
+      // If parent is cap root or empty, return "/"
+      if(!relative || relative === ".") {
+        parentPath = "/"
+      } else {
+        // Return parent's virtual path with leading slash
+        parentPath = "/" + relative.split(path.sep).join("/")
+      }
+    }
 
     return {
       supplied: this.supplied,
@@ -278,6 +307,7 @@ export default class CappedDirectoryObject extends DirectoryObject {
       isFile: this.isFile,
       isDirectory: this.isDirectory,
       parent: parentPath,
+      root: this.root.path,
       real: this.real.toJSON()
     }
   }
@@ -436,10 +466,11 @@ export default class CappedDirectoryObject extends DirectoryObject {
     // Start at cap root
     let current = this.#createCappedAtRoot()
 
-    // Traverse each segment, creating CappedDirectoryObject instances
-    // (not subclass instances, to avoid constructor signature issues)
+    // Traverse each segment, using constructor to preserve class type
     for(const segment of segments) {
-      current = new CappedDirectoryObject(segment, current, this.temporary)
+      // Use simple name constructor to preserve subclass type
+      // Works for both CappedDirectoryObject and TempDirectoryObject
+      current = new this.constructor(segment, current, this.temporary)
     }
 
     return current

package/src/lib/DirectoryObject.js

@@ -157,7 +157,8 @@ export default class DirectoryObject extends FS {
       extension: this.extension,
       isFile: this.isFile,
       isDirectory: this.isDirectory,
-      parent: this.parent ? this.parent.path : null
+      parent: this.parent ? this.parent.path : null,
+      root: this.root.path
     }
   }
 
@@ -294,6 +295,34 @@ export default class DirectoryObject extends FS {
     return this.#parent
   }
 
+  /**
+   * Returns the root directory of the filesystem.
+   *
+   * For DirectoryObject, this walks up to the filesystem root.
+   * For CappedDirectoryObject, this returns the cap root.
+   *
+   * @returns {DirectoryObject} The root directory
+   * @example
+   * const dir = new DirectoryObject("/usr/local/bin")
+   * console.log(dir.root.path)  // "/"
+   *
+   * @example
+   * const capped = new CappedDirectoryObject("/projects/myapp")
+   * const sub = capped.getDirectory("src/lib")
+   * console.log(sub.root.path)  // "/" (virtual, cap root)
+   * console.log(sub.root.real.path)  // "/projects/myapp"
+   */
+  get root() {
+    // Walk up until we find a directory with no parent
+    let current = this
+
+    while(current.parent !== null) {
+      current = current.parent
+    }
+
+    return current
+  }
+
   /**
    * Recursively removes a temporary directory and all its contents.
    *

package/src/lib/TempDirectoryObject.js

@@ -99,11 +99,13 @@ export default class TempDirectoryObject extends CappedDirectoryObject {
         )
       }
 
-      // SECURITY: Ensure parent's cap is tmpdir (prevent escape to other caps)
-      const tmpdir = os.tmpdir()
-      if(parent.cap !== tmpdir) {
+      // 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}), ` +
+          `Parent must be capped to OS temp directory (${tmpdir}) or a subdirectory thereof, ` +
           `got cap: ${parent.cap}`
         )
       }
@@ -119,6 +121,13 @@ export default class TempDirectoryObject extends CappedDirectoryObject {
 
     // Temp-specific behavior: create directory immediately
     this.#createDirectory()
+
+    // 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()
+    }
   }
 
   /**

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

@@ -37,6 +37,13 @@ export default class CappedDirectoryObject extends DirectoryObject {
      * // path: /home/user/.cache/etc/config, cap: /home/user/.cache
      */
     constructor(dirPath: string, parent?: CappedDirectoryObject | null, temporary?: boolean);
+    /**
+     * Re-caps this directory to itself, making it the new root of the capped tree.
+     * This is a protected method intended for use by subclasses like TempDirectoryObject.
+     *
+     * @protected
+     */
+    protected _recapToSelf(): void;
     /**
      * Returns the cap path for this directory.
      *
@@ -75,6 +82,21 @@ export default class CappedDirectoryObject extends DirectoryObject {
      * subdir.real.parent              // Can traverse outside the cap
      */
     get real(): DirectoryObject;
+    /**
+     * Returns the parent directory of this capped directory.
+     * Returns null only if this directory is at the cap (the "root" of the capped tree).
+     *
+     * Note: The returned parent is a CappedDirectoryObject with the same cap.
+     * This maintains the capping behavior throughout the directory hierarchy.
+     *
+     * @returns {CappedDirectoryObject|null} Parent directory or null if at cap root
+     * @example
+     * const capped = new TempDirectoryObject("myapp")
+     * const subdir = capped.getDirectory("data")
+     * console.log(subdir.parent.path) // Returns parent CappedDirectoryObject
+     * console.log(capped.parent) // null (at cap root)
+     */
+    get parent(): CappedDirectoryObject | null;
     /**
      * Returns the URL with virtual path (cap-relative).
      *

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;;;;OAIG;IACH,WAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,cAFa,OAAO,CAInB;IAED;;;;;OAKG;IACH,0BAFa,MAAM,CAIlB;IAqCD;;;;;;;;;;;;;;;;;OAiBG;IACH,YAba,eAAe,CAe3B;IAiCD;;;;OAIG;IACH,WAFa,GAAG,CAIf;IAqED;;;;OAIG;IACH,cAFa,SAAS,CAAC,eAAe,CAAC,CAItC;IAED;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,sBAjBW,MAAM,GACJ,qBAAqB,CAiEjC;IAqID;;;;;OAKG;IACH,WAHW,MAAM,GACJ,OAAO,CAAC;QAAC,KAAK,EAAE,KAAK,CAAC,UAAU,CAAC,CAAC;QAAC,WAAW,QAAO;KAAC,CAAC,CAgBnE;;CA8DF;4BAnmB2B,sBAAsB;uBAC3B,iBAAiB"}
+{"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"}

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

@@ -139,6 +139,24 @@ export default class DirectoryObject extends FS {
      * console.log(root.parent) // null
      */
     get parent(): DirectoryObject | null;
+    /**
+     * Returns the root directory of the filesystem.
+     *
+     * For DirectoryObject, this walks up to the filesystem root.
+     * For CappedDirectoryObject, this returns the cap root.
+     *
+     * @returns {DirectoryObject} The root directory
+     * @example
+     * const dir = new DirectoryObject("/usr/local/bin")
+     * console.log(dir.root.path)  // "/"
+     *
+     * @example
+     * const capped = new CappedDirectoryObject("/projects/myapp")
+     * const sub = capped.getDirectory("src/lib")
+     * console.log(sub.root.path)  // "/" (virtual, cap root)
+     * console.log(sub.root.real.path)  // "/projects/myapp"
+     */
+    get root(): DirectoryObject;
     /**
      * Recursively removes a temporary directory and all its contents.
      *

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

@@ -1 +1 @@
-{"version":3,"file":"DirectoryObject.d.ts","sourceRoot":"","sources":["../../lib/DirectoryObject.js"],"names":[],"mappings":"AAgBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH;uBAqGe,MAAM;IAlEnB;;;;;OAKG;IACH,yCAFW,OAAO,EA6BjB;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;IAED;;;;OAIG;IACH,WAFa,MAAM,CAIlB;IAED;;;;;;;OAOG;IACH,aALa,KAAK,CAAC,MAAM,CAAC,CAOzB;IAED;;;;OAIG;IACH,iBAFa,OAAO,CAInB;IAED;;;;;;;;;;;;OAYG;IACH,cARa,eAAe,GAAC,IAAI,CAwBhC;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,UATa,OAAO,CAAC,IAAI,CAAC,CA0BzB;IAED;;;;OAIG;IACH,cAFa,OAAO,CAInB;IAED;;;;OAIG;IACH,mBAFa,OAAO,CAInB;IAiBD;;;;;;;;;;;;;;;OAeG;IACH,WAZW,MAAM,GACJ,OAAO,CAAC;QAAC,KAAK,EAAE,KAAK,CAAC,UAAU,CAAC,CAAC;QAAC,WAAW,EAAE,KAAK,CAAC,eAAe,CAAC,CAAA;KAAC,CAAC,CAoCpF;IAED;;;;;;;;;;;;OAYG;IACH,uBARW,MAAM,GACJ,OAAO,CAAC,IAAI,CAAC,CAqBzB;IA8BD;;;;;;;;;;;;;;;OAeG;IACH,cAZa,MAAM,CAclB;IAED;;;;;;;;;;;;;;OAcG;IACH,UARa,OAAO,CAAC,IAAI,CAAC,CAkBzB;IAED;;;;;OAKG;IACH,kBAHW,MAAM,GACJ,OAAO,CAAC,OAAO,CAAC,CAM5B;IAED;;;;;OAKG;IACH,sBAHW,MAAM,GACJ,OAAO,CAAC,OAAO,CAAC,CAO5B;IAED;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,sBAdW,MAAM,GACJ,eAAe,CAoB3B;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACH,kBAbW,MAAM,GACJ,UAAU,CAkBtB;;CACF;eAtkBc,SAAS;uBACD,iBAAiB"}
+{"version":3,"file":"DirectoryObject.d.ts","sourceRoot":"","sources":["../../lib/DirectoryObject.js"],"names":[],"mappings":"AAgBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH;uBAsGe,MAAM;IAnEnB;;;;;OAKG;IACH,yCAFW,OAAO,EA6BjB;IAWD;;;;OAIG;IACH,UAFa,MAAM,CAelB;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;IAED;;;;OAIG;IACH,WAFa,MAAM,CAIlB;IAED;;;;;;;OAOG;IACH,aALa,KAAK,CAAC,MAAM,CAAC,CAOzB;IAED;;;;OAIG;IACH,iBAFa,OAAO,CAInB;IAED;;;;;;;;;;;;OAYG;IACH,cARa,eAAe,GAAC,IAAI,CAwBhC;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,YAXa,eAAe,CAoB3B;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,UATa,OAAO,CAAC,IAAI,CAAC,CA0BzB;IAED;;;;OAIG;IACH,cAFa,OAAO,CAInB;IAED;;;;OAIG;IACH,mBAFa,OAAO,CAInB;IAiBD;;;;;;;;;;;;;;;OAeG;IACH,WAZW,MAAM,GACJ,OAAO,CAAC;QAAC,KAAK,EAAE,KAAK,CAAC,UAAU,CAAC,CAAC;QAAC,WAAW,EAAE,KAAK,CAAC,eAAe,CAAC,CAAA;KAAC,CAAC,CAoCpF;IAED;;;;;;;;;;;;OAYG;IACH,uBARW,MAAM,GACJ,OAAO,CAAC,IAAI,CAAC,CAqBzB;IA8BD;;;;;;;;;;;;;;;OAeG;IACH,cAZa,MAAM,CAclB;IAED;;;;;;;;;;;;;;OAcG;IACH,UARa,OAAO,CAAC,IAAI,CAAC,CAkBzB;IAED;;;;;OAKG;IACH,kBAHW,MAAM,GACJ,OAAO,CAAC,OAAO,CAAC,CAM5B;IAED;;;;;OAKG;IACH,sBAHW,MAAM,GACJ,OAAO,CAAC,OAAO,CAAC,CAO5B;IAED;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,sBAdW,MAAM,GACJ,eAAe,CAoB3B;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACH,kBAbW,MAAM,GACJ,UAAU,CAkBtB;;CACF;eAnmBc,SAAS;uBACD,iBAAiB"}

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

@@ -1 +1 @@
-{"version":3,"file":"TempDirectoryObject.d.ts","sourceRoot":"","sources":["../../lib/TempDirectoryObject.js"],"names":[],"mappings":"AAcA;;;;;;;;;GASG;AACH;IAEE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACH,mBAxBW,MAAM,OAAC,WACP,mBAAmB,OAAC,EAoF9B;IAsBD;;;;;;;;;;;;;;OAcG;IACH,sBAVW,MAAM,GACJ,mBAAmB,CAY/B;IAED;;;;;;;;;;;;;;OAcG;IACH,kBAVW,MAAM,GACJ,UAAU,CAYtB;;CAUF;kCArLiC,4BAA4B"}
+{"version":3,"file":"TempDirectoryObject.d.ts","sourceRoot":"","sources":["../../lib/TempDirectoryObject.js"],"names":[],"mappings":"AAcA;;;;;;;;;GASG;AACH;IAEE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACH,mBAxBW,MAAM,OAAC,WACP,mBAAmB,OAAC,EA6F9B;IAsBD;;;;;;;;;;;;;;OAcG;IACH,sBAVW,MAAM,GACJ,mBAAmB,CAY/B;IAED;;;;;;;;;;;;;;OAcG;IACH,kBAVW,MAAM,GACJ,UAAU,CAYtB;;CAUF;kCA9LiC,4BAA4B"}