@gesslar/toolkit 3.9.0 → 3.13.0

package/src/lib/FileObject.js

@@ -7,7 +7,6 @@
 import JSON5 from "json5"
 import fs from "node:fs/promises"
 import path from "node:path"
-import util from "node:util"
 import YAML from "yaml"
 import {URL} from "node:url"
 
@@ -70,65 +69,61 @@ export default class FileObject extends FS {
     isFile: true,
     isDirectory: false,
     parent: null,
+    parentPath: null,
   })
 
   /**
    * Constructs a FileObject instance.
    *
-   * @param {string | FileObject} fileName - The file path or FileObject
+   * @param {string} fileName - The file path
    * @param {DirectoryObject|string|null} [parent] - The parent directory (object or string)
    */
   constructor(fileName, parent=null) {
     super()
 
-    // If passed a FileObject, extract its path
-    if(Data.isType(fileName, "FileObject"))
-      fileName = fileName.path
-
-    if(!fileName || typeof fileName !== "string" || fileName.length === 0)
-      throw Sass.new("fileName must be a non-empty string")
+    Valid.type(fileName, "String", {allowEmpty: false})
+    Valid.type(parent, "Null|String|DirectoryObject", {allowEmpty: false})
 
     const fixedFile = FS.fixSlashes(fileName)
-    const {dir,base,ext} = this.#deconstructFilenameToParts(fixedFile)
+    const {dir, base, ext} = FS.pathParts(fixedFile)
 
     const parentObject = (() => {
-      switch(Data.typeOf(parent)) {
-        case "String":
-          return new DirectoryObject(parent)
-        case "DirectoryObject":
-        case "CappedDirectoryObject":
-        case "TempDirectoryObject":
-          return parent
-        default:
-          return new DirectoryObject(dir)
-      }
-    })()
+      if(Data.isType(parent, "String"))
+        return new DirectoryObject(parent)
 
-    // Use real path if parent is capped, otherwise use path
-    const parentPath = parentObject.realPath || parentObject.path
-    const final = FS.resolvePath(parentPath ?? ".", fixedFile)
+      if(Data.isType(parent, "DirectoryObject"))
+        return parent
 
-    const resolved = final
-    const url = new URL(FS.pathToUri(resolved))
+      return new DirectoryObject(dir)
+    })()
 
-    // Compute the actual parent directory from the resolved path
-    const actualParentPath = path.dirname(resolved)
+    // If the parent is passed, we need to treat the fileName as relative,
+    // regardless of what you-know-who says.
+    const resolvedFilename = parent
+      ? FS.absoluteToRelative(fixedFile, true)
+      : fixedFile
 
-    // If the file is directly in the provided parent directory, reuse that object
-    // Otherwise, create a DirectoryObject for the actual parent directory
-    // Use real path for comparison if parent is capped
-    const parentRealPath = parentObject.realPath || parentObject.path
-    const actualParent = parentObject && actualParentPath === parentRealPath
-      ? parentObject
-      : new DirectoryObject(actualParentPath)
+    // Use real path if parent is capped, otherwise use path
+    const parentPath = parentObject.real?.path || parentObject.path
+    const resolved = FS.resolvePath(parentPath ?? ".", resolvedFilename)
+    const {dir: actualParent} = FS.pathParts(resolved)
+    const url = new URL(FS.pathToUrl(resolved))
 
-    this.#meta.supplied = fixedFile
+    this.#meta.supplied = fileName
     this.#meta.path = resolved
     this.#meta.url = url
     this.#meta.name = base
     this.#meta.extension = ext
     this.#meta.module = path.basename(this.supplied, this.extension)
-    this.#meta.parent = actualParent
+    this.#meta.parentPath = actualParent
+    // Preserve capped parent or use actualParent path match
+    const useCappedParent =
+      parentObject.isCapped ||
+      FS.fixSlashes(actualParent) === FS.fixSlashes(parentObject.path)
+
+    this.#meta.parent = useCappedParent
+      ? parentObject
+      : new DirectoryObject(actualParent)
 
     Object.freeze(this.#meta)
   }
@@ -139,35 +134,9 @@ export default class FileObject extends FS {
    * @returns {string} string representation of the FileObject
    */
   toString() {
-    return `[FileObject: ${this.path}]`
-  }
-
-  /**
-   * Returns a JSON representation of the FileObject.
-   *
-   * @returns {object} JSON representation of the FileObject
-   */
-  toJSON() {
-    return {
-      supplied: this.supplied,
-      path: this.path,
-      url: this.url.toString(),
-      name: this.name,
-      module: this.module,
-      extension: this.extension,
-      isFile: this.isFile,
-      isDirectory: this.isDirectory,
-      parent: this.parent ? this.parent.path : null
-    }
-  }
-
-  /**
-   * Custom inspect method for Node.js console.
-   *
-   * @returns {object} JSON representation of this object.
-   */
-  [util.inspect.custom]() {
-    return this.toJSON()
+    return this.parent.isCapped
+      ?`[${this.constructor.name}: ${this.path} → ${this.real.path}]`
+      :`[${this.constructor.name}: ${this.path}]`
   }
 
   /**
@@ -190,7 +159,9 @@ export default class FileObject extends FS {
 
   /**
    * Returns the file path. If the parent is a capped directory, returns the
-   * virtual path relative to the cap. Otherwise returns the real filesystem path.
+   * virtual path relative to the cap. Otherwise returns the real filesystem
+   * path.
+   *
    * Use `.real.path` to always get the actual filesystem path.
    *
    * @returns {string} The file path (virtual if parent is capped, real otherwise)
@@ -200,13 +171,14 @@ export default class FileObject extends FS {
     const parent = this.#meta.parent
 
     // If parent is capped, return virtual path
-    if(parent?.capped) {
-      const cap = parent.cap
+    if(parent?.isCapped) {
+      const cap = parent.cap.real.path
       const capResolved = path.resolve(cap)
-      const relative = path.relative(capResolved, realPath)
+      const relativeRealPath = FS.absoluteToRelative(realPath)
+      const absolute = FS.resolvePath(capResolved, relativeRealPath)
 
       // Return with leading slash to indicate it's cap-relative
-      return "/" + relative.split(path.sep).join("/")
+      return FS.absoluteToRelative(absolute)
     }
 
     // Otherwise return real path
@@ -220,12 +192,9 @@ export default class FileObject extends FS {
    * @returns {URL} The file URL (virtual if parent is capped, real otherwise)
    */
   get url() {
-    const parent = this.#meta.parent
-
     // If parent is capped, return virtual URL
-    if(parent?.capped) {
-      return new URL(FS.pathToUri(this.path))
-    }
+    if(this.parent?.isCapped)
+      return new URL(FS.pathToUrl(this.path))
 
     return this.#meta.url
   }
@@ -293,6 +262,10 @@ export default class FileObject extends FS {
     return this.#meta.parent
   }
 
+  get parentPath() {
+    return this.#meta.parentPath
+  }
+
   /**
    * Returns a plain FileObject representing the actual filesystem location.
    * This provides an "escape hatch" when working with capped directories,
@@ -310,7 +283,7 @@ export default class FileObject extends FS {
    * file.real.parent.parent      // Can traverse outside the cap
    */
   get real() {
-    return new FileObject(this.#meta.path)
+    return new FileObject(this.path)
   }
 
   /**
@@ -323,7 +296,7 @@ export default class FileObject extends FS {
       await fs.access(this.#meta.path, fs.constants.R_OK)
 
       return true
-    } catch(_) {
+    } catch {
       return false
     }
   }
@@ -338,7 +311,7 @@ export default class FileObject extends FS {
       await fs.access(this.#meta.path, fs.constants.W_OK)
 
       return true
-    } catch(_) {
+    } catch {
       return false
     }
   }
@@ -353,7 +326,7 @@ export default class FileObject extends FS {
       await fs.access(this.#meta.path, fs.constants.F_OK)
 
       return true
-    } catch(_) {
+    } catch {
       return false
     }
   }
@@ -368,7 +341,7 @@ export default class FileObject extends FS {
       const stat = await fs.stat(this.#meta.path)
 
       return stat.size
-    } catch(_) {
+    } catch {
       return null
     }
   }
@@ -384,31 +357,11 @@ export default class FileObject extends FS {
       const stat = await fs.stat(this.#meta.path)
 
       return stat.mtime
-    } catch(_) {
+    } catch {
       return null
     }
   }
 
-  /**
-   * @typedef {object} FileParts
-   * @property {string} base - The file name with extension
-   * @property {string} dir - The directory path
-   * @property {string} ext - The file extension (including dot)
-   */
-
-  /**
-   * Deconstruct a filename into parts
-   *
-   * @param {string} fileName - The filename to deconstruct
-   * @returns {FileParts} The filename parts
-   */
-  #deconstructFilenameToParts(fileName) {
-    Valid.assert(typeof fileName === "string" && fileName.length > 0,
-      "file must be a non-zero length string", 1)
-
-    return path.parse(fileName)
-  }
-
   /**
    * Reads the content of a file asynchronously.
    *
@@ -464,14 +417,30 @@ export default class FileObject extends FS {
    * await file.write(JSON.stringify({key: 'value'}))
    */
   async write(content, encoding="utf8") {
-    if(!this.#meta.url)
-      throw Sass.new("No URL in file")
+    const realPath = FS.virtualToRealPath(this)
+    if(!realPath)
+      throw Sass.new("No actual disk location detected.")
 
-    if(await this.parent.exists)
-      await fs.writeFile(this.#meta.url, content, encoding)
+    // On Windows, normalize the parent directory path to handle 8.3 short names
+    let pathToWrite = realPath
+    if(process.platform === "win32") {
+      try {
+        const parentPath = path.dirname(realPath)
+        const normalizedParent = await fs.realpath(parentPath)
+        pathToWrite = path.join(normalizedParent, path.basename(realPath))
+      } catch {
+        // If normalization fails, use original path
+      }
+    }
 
-    else
-      throw Sass.new(`Invalid directory, ${this.parent.url.href}`)
+    try {
+      await fs.writeFile(pathToWrite, content, encoding)
+    } catch(error) {
+      if(error.code === "ENOENT")
+        throw Sass.new(`Invalid directory: ${path.dirname(pathToWrite)}`)
+
+      throw Sass.from(error, "Failed to write file")
+    }
   }
 
   /**
@@ -491,7 +460,7 @@ export default class FileObject extends FS {
    * await file.writeBinary(buffer)
    */
   async writeBinary(data) {
-    if(!this.#meta.url)
+    if(!this.url)
       throw Sass.new("No URL in file")
 
     const exists = await this.parent.exists
@@ -504,7 +473,7 @@ export default class FileObject extends FS {
 
     // According to the internet, if it's already binary, I don't need
     // an encoding. 🤷
-    return await fs.writeFile(this.#meta.url, bufferData)
+    return await fs.writeFile(this.url, bufferData)
   }
 
   /**
@@ -555,7 +524,7 @@ export default class FileObject extends FS {
    * @returns {Promise<object>} The file contents as a module.
    */
   async import() {
-    const url = this.#meta.url
+    const url = this.url
 
     if(!url)
       throw Sass.new("No URL in file map")
@@ -577,7 +546,7 @@ export default class FileObject extends FS {
    * await file.delete()
    */
   async delete() {
-    const url = this.#meta.url
+    const url = this.url
 
     if(!url)
       throw Sass.new("This object does not represent a valid resource.")

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,172 +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")
+
+    directory ||= "temp"
+    directory = Data.append(directory, source ? "" : "-")
 
-    // Call parent constructor with new signature
-    super(dirPath, cappedParent, true)
+    const parentRealPath = source?.real.path ?? os.tmpdir()
 
-    // Temp-specific behavior: create directory immediately
-    this.#createDirectory()
+    if(source && path.isAbsolute(directory)) {
+      const {root} = FS.pathParts(directory)
 
-    // 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()
+      directory = Data.chopLeft(directory, root)
     }
-  }
 
-  /**
-   * 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."
-    )
-  }
+    let realTempDirectoryPath, toSuper
 
-  /**
-   * 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}`
-        )
-      }
+    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,
     )
   }