@gesslar/toolkit 3.17.0 → 3.20.0

package/package.json

@@ -5,7 +5,7 @@
     "name": "gesslar",
     "url": "https://gesslar.dev"
   },
-  "version": "3.17.0",
+  "version": "3.20.0",
   "license": "Unlicense",
   "homepage": "https://github.com/gesslar/toolkit#readme",
   "repository": {
@@ -60,7 +60,7 @@
   "devDependencies": {
     "@gesslar/uglier": "^0.6.0",
     "eslint": "^9.39.2",
-    "happy-dom": "^20.0.11",
+    "happy-dom": "^20.1.0",
     "typescript": "^5.9.3"
   },
   "scripts": {

package/src/browser/lib/Promised.js

@@ -1,4 +1,5 @@
 import Tantrum from "./Tantrum.js"
+import Valid from "./Valid.js"
 
 /**
  * Utility class providing helper functions for working with Promises,
@@ -13,9 +14,24 @@ export default class Promised {
    * @returns {Promise<Array<unknown>>} Results of all promises
    */
   static async await(promises) {
+    Valid.type(promises, "Promise[]")
+
     return await Promise.all(promises)
   }
 
+  /**
+   * 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) {
+    Valid.type(promises, "Promise[]")
+
+    return await Promise.race(promises)
+  }
+
   /**
    * Settles all promises (both fulfilled and rejected) in parallel.
    * Wrapper around Promise.allSettled for consistency with other utility methods.
@@ -24,6 +40,8 @@ export default class Promised {
    * @returns {Promise<Array<{status: 'fulfilled'|'rejected', value?: unknown, reason?: unknown}>>} Results of all settled promises with status and value/reason
    */
   static async settle(promises) {
+    Valid.type(promises, "Promise[]")
+
     return await Promise.allSettled(promises)
   }
 
@@ -101,20 +119,12 @@ export default class Promised {
    * @throws {Tantrum} Throws a Tantrum error with rejection reasons
    */
   static throw(message="GIGO", settled) {
+    Valid.type(message, "String", {allowEmpty: false})
+    Valid.type(settled, "Array")
+
     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/node/index.js

@@ -17,7 +17,7 @@ export {default as Util} from "./lib/Util.js"
 export {default as Cache} from "./lib/Cache.js"
 export {default as DirectoryObject} from "./lib/DirectoryObject.js"
 export {default as FileObject} from "./lib/FileObject.js"
-export {default as FS} from "./lib/FileSystem.js"
+export {default as FileSystem} from "./lib/FileSystem.js"
 export {default as Glog} from "./lib/Glog.js"
 export {default as Notify} from "./lib/Notify.js"
 export {default as TempDirectoryObject} from "./lib/TempDirectoryObject.js"

package/src/node/lib/DirectoryObject.js

@@ -368,26 +368,29 @@ export default class DirectoryObject extends FS {
     const files = [], directories = []
     const virtual = this.isVirtual
 
-    found.forEach(e => {
+    for(const e of found) {
       if(e.isFile()) {
         const {name, parentPath} = e
         const resolved = FS.resolvePath(parentPath, name)
 
         const file = virtual
-          ? new VFileObject(resolved, this)
+          ? new VFileObject(path.relative(this.real.path, resolved), this)
           : new FileObject(resolved, this)
 
         files.push(file)
       } else if(e.isDirectory()) {
         const {name, parentPath} = e
         const resolved = FS.resolvePath(parentPath, name)
-        const directory = new this.constructor(resolved, this)
+        const relativePath = virtual
+          ? path.relative(this.real.path, resolved)
+          : resolved
+        const directory = new this.constructor(relativePath, this)
 
         directories.push(directory)
       } else {
         throw Sass.new(`wtf is this? ${e}`)
       }
-    })
+    }
 
     return {files, directories}
   }

package/src/node/lib/FileObject.js

@@ -69,6 +69,24 @@ export default class FileObject extends FS {
     parentPath: null,
   })
 
+  /**
+   * Strip root from absolute path to make it relative.
+   * Used for virtual filesystem path resolution.
+   *
+   * @private
+   * @static
+   * @param {string} pathName - The path to convert
+   * @returns {string} Path with root stripped, or original if already relative
+   */
+  static #absoluteToRelative(pathName) {
+    if(!path.isAbsolute(pathName))
+      return pathName
+
+    const {root} = FS.pathParts(pathName)
+
+    return Data.chopLeft(pathName, root)
+  }
+
   /**
    * Constructs a FileObject instance.
    *
@@ -82,40 +100,41 @@ export default class FileObject extends FS {
     Valid.type(parent, "Null|String|DirectoryObject", {allowEmpty: false})
 
     const normalizedFile = FS.fixSlashes(submitted)
-    const absOrRel = path.isAbsolute(normalizedFile) && parent
-      ? FS.absoluteToRelative(normalizedFile, true)
+    const absOrRelPath = path.isAbsolute(normalizedFile) && parent
+      ? FileObject.#absoluteToRelative(normalizedFile)
       : normalizedFile
-    const {dir, base, ext, name} = FS.pathParts(absOrRel)
+    const {dir, base, ext, name} = FS.pathParts(absOrRelPath)
 
     const [parentObject, fullPath] = (() => {
       if(Data.isType(parent, "String")) {
-        const joined = FS.resolvePath(parent, absOrRel)
-        const {dir} = FS.pathParts(joined)
+        const resolved = FS.resolvePath(parent, absOrRelPath)
+        const {dir} = FS.pathParts(resolved)
 
         return [
           new DirectoryObject(dir),
-          joined,
+          resolved,
         ]
       }
 
       if(Data.isType(parent, "DirectoryObject")) {
-        const joined = FS.resolvePath(parent.path, absOrRel)
-        const {dir} = FS.pathParts(joined)
+        const parentPath = parent.path
+        const resolved = FS.resolvePath(parentPath, absOrRelPath)
+        const parts = FS.pathParts(resolved)
 
         return [
-          parent.path === dir
+          parent.path === parts.dir
             ? parent
-            : new parent.constructor(dir, parent),
-          joined,
+            : new parent.constructor(parts.dir, parent),
+          resolved,
         ]
       }
 
       const directory = new DirectoryObject(dir)
-      const joined = FS.resolvePath(directory.path, absOrRel)
+      const resolved = FS.resolvePath(directory.path, absOrRelPath)
 
       return [
         directory,
-        joined,
+        resolved,
       ]
     })()
 
@@ -439,9 +458,8 @@ export default class FileObject extends FS {
       any: [JSON5,YAML]
     }[normalizedType]
 
-    if(!toTry) {
+    if(!toTry)
       throw Sass.new(`Unsupported data type '${type}'. Supported types: json, json5, yaml.`)
-    }
 
     for(const format of toTry) {
       try {

package/src/node/lib/FileSystem.js

@@ -49,7 +49,7 @@ export default class FileSystem {
       1
     )
 
-    return FileSystem.relativeOrAbsolutePath(fileOrDirectoryObject, this)
+    return FileSystem.relativeOrAbsolute(fileOrDirectoryObject, this)
   }
 
   /**
@@ -104,7 +104,7 @@ export default class FileSystem {
    * @param {FileObject|DirectoryObject} to - The target file or directory object
    * @returns {string} The relative path from `from` to `to`, or the absolute path if not reachable
    */
-  static relativeOrAbsolutePath(from, to) {
+  static relativeOrAbsolute(from, to) {
     const fromBasePath = from.isDirectory
       ? from.path
       : from.parent?.path ?? path.dirname(from.path)
@@ -116,6 +116,25 @@ export default class FileSystem {
       : relative
   }
 
+  /**
+   * Computes the relative path from one file or directory to another.
+   *
+   * If the target is outside the source (i.e., the relative path starts with
+   * ".."), returns the absolute path to the target instead.
+   *
+   * @static
+   * @param {string} from - The source file or directory object
+   * @param {string} to - The target file or directory object
+   * @returns {string} The relative path from `from` to `to`, or the absolute path if not reachable
+   */
+  static relativeOrAbsolutePath(from, to) {
+    const relative = path.relative(from, to)
+
+    return relative.startsWith("..")
+      ? to
+      : relative
+  }
+
   /**
    * Merge two paths by finding overlapping segments and combining them
    * efficiently
@@ -356,32 +375,4 @@ export default class FileSystem {
 
     return this.resolvePath(cap, target)
   }
-
-  /**
-   * Convert an absolute path to a relative format by removing the root component.
-   * By default, keeps a leading separator (making it "absolute-like relative").
-   * Use forceActuallyRelative to get a truly relative path without leading separator.
-   *
-   * @static
-   * @param {string} pathToCheck - The path to convert (returned unchanged if already relative)
-   * @param {boolean} [forceActuallyRelative=false] - If true, removes leading separator for truly relative path
-   * @returns {string} The relative path (with or without leading separator based on forceActuallyRelative)
-   * @example
-   * FS.absoluteToRelative("/home/user/docs") // "/home/user/docs" (with leading /)
-   * FS.absoluteToRelative("/home/user/docs", true) // "home/user/docs" (truly relative)
-   * FS.absoluteToRelative("relative/path") // "relative/path" (unchanged)
-   */
-  static absoluteToRelative(pathToCheck, forceActuallyRelative=false) {
-    if(!path.isAbsolute(pathToCheck))
-      return pathToCheck
-
-    const {root} = this.pathParts(pathToCheck)
-    const sep = path.sep
-    const chopped = Data.chopLeft(pathToCheck, root)
-    const absolute = forceActuallyRelative
-      ? chopped
-      : Data.prepend(chopped, sep)
-
-    return absolute
-  }
 }