@gesslar/toolkit 3.8.0 → 3.9.0

package/package.json

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

package/src/lib/CappedDirectoryObject.js

@@ -35,13 +35,17 @@ 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} [dirPath="."] - 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
@@ -56,9 +60,8 @@ export default class CappedDirectoryObject extends DirectoryObject {
    * const config = new CappedDirectoryObject("/etc/config", cache)
    * // path: /home/user/.cache/etc/config, cap: /home/user/.cache
    */
-  constructor(dirPath, parent=null, temporary=false) {
+  constructor(dirPath=".", parent=null, temporary=false) {
     Valid.type(dirPath, "String")
-    Valid.assert(dirPath.length > 0, "Path must not be empty.")
 
     // Validate parent using inheritance-aware type checking
     if(parent !== null && !Data.isType(parent, "CappedDirectoryObject")) {
@@ -113,6 +116,22 @@ export default class CappedDirectoryObject extends DirectoryObject {
     this.#validateCapPath()
   }
 
+  /**
+   * 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() {
+    return new this(process.cwd())
+  }
+
   /**
    * Validates that the directory path is within the cap directory tree.
    *

package/src/lib/DirectoryObject.js

@@ -101,19 +101,19 @@ export default class DirectoryObject extends FS {
   /**
    * Constructs a DirectoryObject instance.
    *
-   * @param {string? | DirectoryObject?} directory - The directory path or DirectoryObject
+   * @param {string? | DirectoryObject?} [directory="."] - The directory path or DirectoryObject (defaults to current directory)
    * @param {boolean} [temporary] - Whether this is a temporary directory.
    */
-  constructor(directory=null, temporary=false) {
+  constructor(directory=".", temporary=false) {
     super()
 
-    Valid.type(directory, "String|TempDirectoryObject|DirectoryObject|Null")
+    Valid.type(directory, "String|TempDirectoryObject|DirectoryObject")
 
     // If passed a DirectoryObject, extract its path
     if(Data.isType(directory, "DirectoryObject") || Data.isType(directory, "TempDirectoryObject"))
       directory = directory.path
 
-    const fixedDir = FS.fixSlashes(directory ?? ".")
+    const fixedDir = FS.fixSlashes(directory)
     const resolved = path.resolve(fixedDir)
     const url = new URL(FS.pathToUri(resolved))
     const baseName = path.basename(resolved) || "."
@@ -133,6 +133,20 @@ export default class DirectoryObject extends FS {
     Object.freeze(this.#meta)
   }
 
+  /**
+   * Creates a DirectoryObject from the current working directory.
+   * Useful when working with pnpx or other tools where the project root
+   * needs to be determined at runtime.
+   *
+   * @returns {DirectoryObject} A DirectoryObject representing the current working directory
+   * @example
+   * const projectRoot = DirectoryObject.fromCwd()
+   * console.log(projectRoot.path) // process.cwd()
+   */
+  static fromCwd() {
+    return new this(process.cwd())
+  }
+
   /**
    * Returns a string representation of the DirectoryObject.
    *

package/src/lib/TempDirectoryObject.js

@@ -130,6 +130,19 @@ export default class TempDirectoryObject extends CappedDirectoryObject {
     }
   }
 
+  /**
+   * TempDirectoryObject does not support fromCwd() since it is specifically
+   * designed to work within the OS temporary directory tree.
+   *
+   * @throws {Sass} Always throws an error
+   */
+  static fromCwd() {
+    throw Sass.new(
+      "TempDirectoryObject.fromCwd() is not supported. " +
+      "Use CappedDirectoryObject.fromCwd() instead if you need to cap at the current working directory."
+    )
+  }
+
   /**
    * Creates the directory synchronously on the filesystem.
    *

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,17 @@ 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} [dirPath="."] - 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,7 +53,7 @@ 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(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.

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":"AAkBA;;;;;;;;GAQG;AACH;IA2FE;;;;;;;;;;;OAWG;IACH,kBAPa,qBAAqB,CASjC;IAtGD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACH,sBAzBW,MAAM,WACN,qBAAqB,OAAC,cACtB,OAAO,EA6EjB;IAqCD;;;;;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;4BArpB2B,sBAAsB;uBAC3B,iBAAiB"}

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

@@ -49,13 +49,24 @@
  */
 export default class DirectoryObject extends FS {
     [x: number]: () => object;
+    /**
+     * Creates a DirectoryObject from the current working directory.
+     * Useful when working with pnpx or other tools where the project root
+     * needs to be determined at runtime.
+     *
+     * @returns {DirectoryObject} A DirectoryObject representing the current working directory
+     * @example
+     * const projectRoot = DirectoryObject.fromCwd()
+     * console.log(projectRoot.path) // process.cwd()
+     */
+    static fromCwd(): DirectoryObject;
     /**
      * Constructs a DirectoryObject instance.
      *
-     * @param {string? | DirectoryObject?} directory - The directory path or DirectoryObject
+     * @param {string? | DirectoryObject?} [directory="."] - The directory path or DirectoryObject (defaults to current directory)
      * @param {boolean} [temporary] - Whether this is a temporary directory.
      */
-    constructor(directory?: any, temporary?: boolean);
+    constructor(directory?: string, temporary?: boolean);
     /**
      * Returns a JSON representation of the DirectoryObject.
      *

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;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"}
+{"version":3,"file":"DirectoryObject.d.ts","sourceRoot":"","sources":["../../lib/DirectoryObject.js"],"names":[],"mappings":"AAgBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH;uBAoHe,MAAM;IA9CnB;;;;;;;;;OASG;IACH,kBALa,eAAe,CAO3B;IA/CD;;;;;OAKG;IACH,4CAFW,OAAO,EA6BjB;IAyBD;;;;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;eAjnBc,SAAS;uBACD,iBAAiB"}

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

@@ -9,6 +9,13 @@
  * @augments CappedDirectoryObject
  */
 export default class TempDirectoryObject extends CappedDirectoryObject {
+    /**
+     * TempDirectoryObject does not support fromCwd() since it is specifically
+     * designed to work within the OS temporary directory tree.
+     *
+     * @throws {Sass} Always throws an error
+     */
+    static fromCwd(): void;
     /**
      * Constructs a TempDirectoryObject instance and creates the directory.
      *

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,EA6F9B;IAsBD;;;;;;;;;;;;;;OAcG;IACH,sBAVW,MAAM,GACJ,mBAAmB,CAY/B;IAED;;;;;;;;;;;;;;OAcG;IACH,kBAVW,MAAM,GACJ,UAAU,CAYtB;;CAUF;kCA9LiC,4BAA4B"}
+{"version":3,"file":"TempDirectoryObject.d.ts","sourceRoot":"","sources":["../../lib/TempDirectoryObject.js"],"names":[],"mappings":"AAcA;;;;;;;;;GASG;AACH;IA4GE;;;;;OAKG;IACH,uBAKC;IArHD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACH,mBAxBW,MAAM,OAAC,WACP,mBAAmB,OAAC,EA6F9B;IAmCD;;;;;;;;;;;;;;OAcG;IACH,sBAVW,MAAM,GACJ,mBAAmB,CAY/B;IAED;;;;;;;;;;;;;;OAcG;IACH,kBAVW,MAAM,GACJ,UAAU,CAYtB;;CAUF;kCA3MiC,4BAA4B"}