@gesslar/toolkit 3.23.0 → 3.24.0

package/package.json

@@ -5,7 +5,7 @@
     "name": "gesslar",
     "url": "https://gesslar.dev"
   },
-  "version": "3.23.0",
+  "version": "3.24.0",
   "license": "Unlicense",
   "homepage": "https://github.com/gesslar/toolkit#readme",
   "repository": {
@@ -62,12 +62,12 @@
     "yaml": "^2.8.2"
   },
   "devDependencies": {
-    "@gesslar/uglier": "^1.1.0",
+    "@gesslar/uglier": "^1.2.0",
     "eslint": "^9.39.2",
-    "eslint-plugin-jsdoc": "^62.0.0",
-    "happy-dom": "^20.3.1",
+    "eslint-plugin-jsdoc": "^62.3.0",
+    "happy-dom": "^20.3.4",
     "typescript": "^5.9.3",
-    "typescript-eslint": "^8.53.0"
+    "typescript-eslint": "^8.53.1"
   },
   "scripts": {
     "types": "node -e \"require('fs').rmSync('types',{recursive:true,force:true});\" && tsc -p tsconfig.types.json",

package/src/node/lib/FileObject.js

@@ -488,4 +488,49 @@ export default class FileObject extends FS {
 
     return await fs.unlink(filePath)
   }
+
+  /**
+   * Creates a FileObject representing the current working file (the file
+   * that called this method). Parses the stack trace to determine the
+   * caller's file path.
+   *
+   * @returns {FileObject} A new FileObject instance for the calling file
+   * @throws {Sass} If unable to determine caller file from stack trace
+   * @example
+   * // In /home/user/project/src/app.js:
+   * const thisFile = FileObject.fromCwf()
+   * console.log(thisFile.path) // /home/user/project/src/app.js
+   */
+  static fromCwf() {
+    const originalPrepare = Error.prepareStackTrace
+    Error.prepareStackTrace = (_, stack) => stack
+    /** @type {Array<{getFileName: () => string|null}>} */
+    const stack = (new Error().stack)
+    Error.prepareStackTrace = originalPrepare
+
+    // Find the first call site that isn't this file
+    // Stack filenames may be file:// URLs, so compare both forms
+    const thisFileUrl = import.meta.url
+    const thisFilePath = FS.urlToPath(thisFileUrl)
+    const callerSite = stack.find(site => {
+      const fileName = site.getFileName()
+
+      if(!fileName)
+        return false
+
+      return fileName !== thisFileUrl && fileName !== thisFilePath
+    })
+
+    const callerFile = callerSite?.getFileName()
+
+    if(!callerFile)
+      throw Sass.new("Unable to determine caller file from stack trace")
+
+    // Handle file:// URLs
+    const filePath = callerFile.startsWith("file://")
+      ? FS.urlToPath(callerFile)
+      : callerFile
+
+    return new this(filePath)
+  }
 }

package/src/node/lib/FileSystem.js

@@ -80,17 +80,19 @@ export default class FileSystem {
   }
 
   /**
-   * Convert a URI to a path
+   * Convert a file URL to a path.
    *
    * @static
-   * @param {string} pathName - The URI to convert
-   * @returns {string} The path
+   * @param {string} fileUrl - The file URL to convert (e.g., import.meta.url)
+   * @returns {string} The file path
+   * @example
+   * const currentFile = FileSystem.urlToPath(import.meta.url)
    */
-  static urlToPath(pathName) {
+  static urlToPath(fileUrl) {
     try {
-      return url.fileURLToPath(new URL(pathName).pathName)
+      return url.fileURLToPath(fileUrl)
     } catch {
-      return pathName
+      return fileUrl
     }
   }
 

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

@@ -22,6 +22,19 @@ export default class FileObject extends FS {
     static dataLoaderConfig: {
         [key: string]: Array<typeof JSON5 | typeof YAML>;
     };
+    /**
+     * Creates a FileObject representing the current working file (the file
+     * that called this method). Parses the stack trace to determine the
+     * caller's file path.
+     *
+     * @returns {FileObject} A new FileObject instance for the calling file
+     * @throws {Sass} If unable to determine caller file from stack trace
+     * @example
+     * // In /home/user/project/src/app.js:
+     * const thisFile = FileObject.fromCwf()
+     * console.log(thisFile.path) // /home/user/project/src/app.js
+     */
+    static fromCwf(): FileObject;
     /**
      * Constructs a FileObject instance.
      *

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

@@ -1 +1 @@
-{"version":3,"file":"FileObject.d.ts","sourceRoot":"","sources":["../../../src/node/lib/FileObject.js"],"names":[],"mappings":"AAkBA;;;;;;;;;;;;;GAaG;AAEH;IACE;;;;;OAKG;IACH,yBAFU;QAAC,CAAC,GAAG,EAAE,MAAM,GAAG,KAAK,CAAC,OAAO,KAAK,GAAG,OAAO,IAAI,CAAC,CAAA;KAAC,CAO1D;IA0BF;;;;;OAKG;IACH,uBAHW,MAAM,WACN,eAAe,GAAC,MAAM,GAAC,IAAI,EA+DrC;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;;;;;;;;;;;;;;OAcG;IACH,cAFa,eAAe,CAI3B;IAED;;;;OAIG;IACH,kBAFa,MAAM,CAIlB;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;IAED;;;;;OAKG;IACH,gBAHW,MAAM,GACJ,OAAO,CAAC,MAAM,CAAC,CAS3B;IAED;;;;;;;;;;;OAWG;IACH,cARa,OAAO,CAAC,MAAM,CAAC,CAe3B;IAED;;;;;;;;;;;OAWG;IACH,eARW,MAAM,aACN,MAAM,GACJ,OAAO,CAAC,IAAI,CAAC,CAiBzB;IAED;;;;;;;;;;;;;;;OAeG;IACH,kBAXW,WAAW,GAAC,IAAI,GAAC,MAAM,GACrB,OAAO,CAAC,IAAI,CAAC,CAwBzB;IAED;;;;;;;;;;;;;;OAcG;IACH,gBAXW,MAAM,aACN,MAAM,GACJ,OAAO,CAAC,OAAO,CAAC,CAiC5B;IAED;;;;OAIG;IACH,UAFa,OAAO,CAAC,MAAM,CAAC,CAS3B;IAED;;;;;;;;;OASG;IACH,UAPa,OAAO,CAAC,IAAI,CAAC,CAczB;;CACF;eA5dc,iBAAiB;4BADJ,sBAAsB;kBAPhC,OAAO;iBAER,MAAM"}
+{"version":3,"file":"FileObject.d.ts","sourceRoot":"","sources":["../../../src/node/lib/FileObject.js"],"names":[],"mappings":"AAkBA;;;;;;;;;;;;;GAaG;AAEH;IACE;;;;;OAKG;IACH,yBAFU;QAAC,CAAC,GAAG,EAAE,MAAM,GAAG,KAAK,CAAC,OAAO,KAAK,GAAG,OAAO,IAAI,CAAC,CAAA;KAAC,CAO1D;IA8bF;;;;;;;;;;;OAWG;IACH,kBAPa,UAAU,CAsCtB;IA/cD;;;;;OAKG;IACH,uBAHW,MAAM,WACN,eAAe,GAAC,MAAM,GAAC,IAAI,EA+DrC;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;;;;;;;;;;;;;;OAcG;IACH,cAFa,eAAe,CAI3B;IAED;;;;OAIG;IACH,kBAFa,MAAM,CAIlB;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;IAED;;;;;OAKG;IACH,gBAHW,MAAM,GACJ,OAAO,CAAC,MAAM,CAAC,CAS3B;IAED;;;;;;;;;;;OAWG;IACH,cARa,OAAO,CAAC,MAAM,CAAC,CAe3B;IAED;;;;;;;;;;;OAWG;IACH,eARW,MAAM,aACN,MAAM,GACJ,OAAO,CAAC,IAAI,CAAC,CAiBzB;IAED;;;;;;;;;;;;;;;OAeG;IACH,kBAXW,WAAW,GAAC,IAAI,GAAC,MAAM,GACrB,OAAO,CAAC,IAAI,CAAC,CAwBzB;IAED;;;;;;;;;;;;;;OAcG;IACH,gBAXW,MAAM,aACN,MAAM,GACJ,OAAO,CAAC,OAAO,CAAC,CAiC5B;IAED;;;;OAIG;IACH,UAFa,OAAO,CAAC,MAAM,CAAC,CAS3B;IAED;;;;;;;;;OASG;IACH,UAPa,OAAO,CAAC,IAAI,CAAC,CAczB;;CA8CF;eAzgBc,iBAAiB;4BADJ,sBAAsB;kBAPhC,OAAO;iBAER,MAAM"}

package/types/node/lib/FileSystem.d.ts

@@ -22,13 +22,15 @@ export default class FileSystem {
      */
     static pathToUrl(pathName: string): string;
     /**
-     * Convert a URI to a path
+     * Convert a file URL to a path.
      *
      * @static
-     * @param {string} pathName - The URI to convert
-     * @returns {string} The path
+     * @param {string} fileUrl - The file URL to convert (e.g., import.meta.url)
+     * @returns {string} The file path
+     * @example
+     * const currentFile = FileSystem.urlToPath(import.meta.url)
      */
-    static urlToPath(pathName: string): string;
+    static urlToPath(fileUrl: string): string;
     /**
      * Computes the relative path from one file or directory to another.
      *

package/types/node/lib/FileSystem.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FileSystem.d.ts","sourceRoot":"","sources":["../../../src/node/lib/FileSystem.js"],"names":[],"mappings":"AA2BA;;GAEG;AACH;IACE,kCAAwB;IACxB,uCAAkC;IAClC,mBAAsB;IAsBtB;;;;;;OAMG;IACH,4BAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;OAMG;IACH,2BAHW,MAAM,GACJ,MAAM,CAQlB;IAED;;;;;;OAMG;IACH,2BAHW,MAAM,GACJ,MAAM,CAQlB;IAED;;;;;;;;;;OAUG;IACH,gCAJW,UAAU,GAAC,eAAe,MAC1B,UAAU,GAAC,eAAe,GACxB,MAAM,CAYlB;IAED;;;;;;;;;;OAUG;IACH,oCAJW,MAAM,MACN,MAAM,GACJ,MAAM,CAQlB;IAED;;;;;;;;;OASG;IACH,oCALW,MAAM,SACN,MAAM,QACN,MAAM,GACJ,MAAM,CA0BlB;IAED;;;;;;;;OAQG;IACH,6BAJW,MAAM,UACN,MAAM,GACJ,MAAM,CAmClB;IAED;;;;;;;;;;;;OAYG;IACH,+BATW,MAAM,aACN,MAAM,GACJ,OAAO,CAcnB;IAED;;;;;;;;;;;;;;OAcG;IACH,4BATW,MAAM,MACN,MAAM,QACN,MAAM,GACJ,MAAM,GAAC,IAAI,CAwBvB;IAED;;;;;;;;;;;;;;;OAeG;IACH,+BAXW,MAAM,MACN,MAAM,QACN,MAAM,GACJ,MAAM,GAAC,IAAI,CA+BvB;IAED;;;;;;;OAOG;IAEH;;;;;;;OAOG;IACH,2BAJW,MAAM;;;;cAXH,MAAM;;;;aACN,MAAM;;;;aACN,MAAM;;;;cACN,MAAM;;;;cACN,MAAM;MAenB;IAED;;;;OAIG;IACH,kBAFa,MAAM,CAIlB;IAvTD;;;;;;;;;OASG;IACH,kCAJW,UAAU,GAAC,eAAe,GACxB,MAAM,CAWlB;CAsSF;yBAzUa,OAAO,iBAAiB,EAAE,OAAO;8BACjC,OAAO,sBAAsB,EAAE,OAAO"}
+{"version":3,"file":"FileSystem.d.ts","sourceRoot":"","sources":["../../../src/node/lib/FileSystem.js"],"names":[],"mappings":"AA2BA;;GAEG;AACH;IACE,kCAAwB;IACxB,uCAAkC;IAClC,mBAAsB;IAsBtB;;;;;;OAMG;IACH,4BAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;OAMG;IACH,2BAHW,MAAM,GACJ,MAAM,CAQlB;IAED;;;;;;;;OAQG;IACH,0BALW,MAAM,GACJ,MAAM,CAUlB;IAED;;;;;;;;;;OAUG;IACH,gCAJW,UAAU,GAAC,eAAe,MAC1B,UAAU,GAAC,eAAe,GACxB,MAAM,CAYlB;IAED;;;;;;;;;;OAUG;IACH,oCAJW,MAAM,MACN,MAAM,GACJ,MAAM,CAQlB;IAED;;;;;;;;;OASG;IACH,oCALW,MAAM,SACN,MAAM,QACN,MAAM,GACJ,MAAM,CA0BlB;IAED;;;;;;;;OAQG;IACH,6BAJW,MAAM,UACN,MAAM,GACJ,MAAM,CAmClB;IAED;;;;;;;;;;;;OAYG;IACH,+BATW,MAAM,aACN,MAAM,GACJ,OAAO,CAcnB;IAED;;;;;;;;;;;;;;OAcG;IACH,4BATW,MAAM,MACN,MAAM,QACN,MAAM,GACJ,MAAM,GAAC,IAAI,CAwBvB;IAED;;;;;;;;;;;;;;;OAeG;IACH,+BAXW,MAAM,MACN,MAAM,QACN,MAAM,GACJ,MAAM,GAAC,IAAI,CA+BvB;IAED;;;;;;;OAOG;IAEH;;;;;;;OAOG;IACH,2BAJW,MAAM;;;;cAXH,MAAM;;;;aACN,MAAM;;;;aACN,MAAM;;;;cACN,MAAM;;;;cACN,MAAM;MAenB;IAED;;;;OAIG;IACH,kBAFa,MAAM,CAIlB;IAzTD;;;;;;;;;OASG;IACH,kCAJW,UAAU,GAAC,eAAe,GACxB,MAAM,CAWlB;CAwSF;yBA3Ua,OAAO,iBAAiB,EAAE,OAAO;8BACjC,OAAO,sBAAsB,EAAE,OAAO"}