@gesslar/toolkit 3.12.3 → 3.14.0

package/src/{lib → node/lib}/FileObject.js

@@ -7,13 +7,12 @@
 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"
 
-import Data from "../browser/lib/Data.js"
+import Data from "../../browser/lib/Data.js"
 import DirectoryObject from "./DirectoryObject.js"
-import FS from "./FS.js"
+import FS from "./FileSystem.js"
 import Sass from "./Sass.js"
 import Valid from "./Valid.js"
 
@@ -28,7 +27,6 @@ import Valid from "./Valid.js"
  * @property {string} module - The file name without extension
  * @property {string} extension - The file extension
  * @property {boolean} isFile - Always true for files
- * @property {boolean} isDirectory - Always false for files
  * @property {DirectoryObject} parent - The parent directory object
  * @property {Promise<boolean>} exists - Whether the file exists (async)
  */
@@ -57,7 +55,6 @@ export default class FileObject extends FS {
    * @property {string|null} module - The file name without extension
    * @property {string|null} extension - The file extension
    * @property {boolean} isFile - Always true
-   * @property {boolean} isDirectory - Always false
    * @property {DirectoryObject|null} parent - The parent directory object
    */
   #meta = Object.seal({
@@ -68,7 +65,6 @@ export default class FileObject extends FS {
     module: null,
     extension: null,
     isFile: true,
-    isDirectory: false,
     parent: null,
     parentPath: null,
   })
@@ -76,55 +72,65 @@ export default class FileObject extends FS {
   /**
    * Constructs a FileObject instance.
    *
-   * @param {string} fileName - The file path
+   * @param {string} submitted - The file path
    * @param {DirectoryObject|string|null} [parent] - The parent directory (object or string)
    */
-  constructor(fileName, parent=null) {
+  constructor(submitted, parent=null) {
     super()
 
-    Valid.type(fileName, "String", {allowEmpty: false})
+    Valid.type(submitted, "String", {allowEmpty: false})
     Valid.type(parent, "Null|String|DirectoryObject", {allowEmpty: false})
 
-    const fixedFile = FS.fixSlashes(fileName)
-    const {dir, base, ext} = FS.pathParts(fixedFile)
+    const normalizedFile = FS.fixSlashes(submitted)
+    const absOrRel = path.isAbsolute(normalizedFile) && parent
+      ? FS.absoluteToRelative(normalizedFile, true)
+      : normalizedFile
+    const {dir, base, ext, name} = FS.pathParts(absOrRel)
+
+    const [parentObject, fullPath] = (() => {
+      if(Data.isType(parent, "String")) {
+        const joined = FS.resolvePath(parent, absOrRel)
+        const {dir} = FS.pathParts(joined)
+
+        return [
+          new DirectoryObject(dir),
+          joined,
+        ]
+      }
 
-    const parentObject = (() => {
-      if(Data.isType(parent, "String"))
-        return new DirectoryObject(parent)
+      if(Data.isType(parent, "DirectoryObject")) {
+        const joined = FS.resolvePath(parent.path, absOrRel)
+        const {dir} = FS.pathParts(joined)
 
-      if(Data.isType(parent, "DirectoryObject"))
-        return parent
+        return [
+          parent.path === dir
+            ? parent
+            : new DirectoryObject(dir),
+          joined,
+        ]
+      }
 
-      return new DirectoryObject(dir)
-    })()
+      const directory = new DirectoryObject(dir)
+      const joined = FS.resolvePath(directory.path, absOrRel)
 
-    // 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
+      return [
+        directory,
+        joined,
+      ]
+    })()
 
-    // 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 parentPath = parentObject.path
+    const resolved = FS.resolvePath(parentPath, fullPath)
     const url = new URL(FS.pathToUrl(resolved))
 
-    this.#meta.supplied = fileName
+    this.#meta.supplied = submitted
     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.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)
+    this.#meta.module = name
+    this.#meta.parentPath = parentPath
+    this.#meta.parent = parentObject
 
     Object.freeze(this.#meta)
   }
@@ -132,39 +138,12 @@ export default class FileObject extends FS {
   /**
    * Returns a string representation of the FileObject.
    *
-   * @returns {string} string representation of the FileObject
+   * @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,
-      parentPath: this.parentPath,
-      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.isVirtual
+      ?`[${this.constructor.name}: ${this.path} → ${this.real.path}]`
+      :`[${this.constructor.name}: ${this.path}]`
   }
 
   /**
@@ -186,44 +165,20 @@ 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.
-   *
-   * Use `.real.path` to always get the actual filesystem path.
+   * Returns the file path.
    *
-   * @returns {string} The file path (virtual if parent is capped, real otherwise)
+   * @returns {string} The file path
    */
   get path() {
-    const realPath = this.#meta.path
-    const parent = this.#meta.parent
-
-    // If parent is capped, return virtual path
-    if(parent?.isCapped) {
-      const cap = parent.cap.real.path
-      const capResolved = path.resolve(cap)
-      const relativeRealPath = FS.absoluteToRelative(realPath)
-      const absolute = FS.resolvePath(capResolved, relativeRealPath)
-
-      // Return with leading slash to indicate it's cap-relative
-      return FS.absoluteToRelative(absolute)
-    }
-
-    // Otherwise return real path
-    return realPath
+    return this.#meta.path
   }
 
   /**
-   * Returns the URL of the current file. If the parent is a capped directory,
-   * returns a virtual URL relative to the cap. Otherwise returns the real URL.
+   * Returns the URL of the current file.
    *
-   * @returns {URL} The file URL (virtual if parent is capped, real otherwise)
+   * @returns {URL} The file URL
    */
   get url() {
-    // If parent is capped, return virtual URL
-    if(this.parent?.isCapped)
-      return new URL(FS.pathToUrl(this.path))
-
     return this.#meta.url
   }
 
@@ -262,15 +217,6 @@ export default class FileObject extends FS {
     return this.#meta.isFile
   }
 
-  /**
-   * We're not masquerading as a directory! Nope.
-   *
-   * @returns {boolean} Always false
-   */
-  get isDirectory() {
-    return this.#meta.isDirectory
-  }
-
   /**
    * Returns the directory containing this file. This does not necessarily
    * mean that the directory exists. It could be theoretical, you will need
@@ -294,26 +240,6 @@ export default class FileObject extends FS {
     return this.#meta.parentPath
   }
 
-  /**
-   * Returns a plain FileObject representing the actual filesystem location.
-   * This provides an "escape hatch" when working with capped directories,
-   * allowing direct filesystem access when needed.
-   *
-   * @returns {FileObject} Uncapped file object at the real filesystem path
-   * @example
-   * const temp = new TempDirectoryObject("myapp")
-   * const file = temp.getFile("/config/app.json")
-   *
-   * // file.path shows virtual path
-   * console.log(file.path)       // "/config/app.json"
-   * // file.real.path shows actual filesystem path
-   * console.log(file.real.path)  // "/tmp/myapp-ABC123/config/app.json"
-   * file.real.parent.parent      // Can traverse outside the cap
-   */
-  get real() {
-    return new FileObject(this.path)
-  }
-
   /**
    * Check if a file can be read. Returns true if the file can be read, false
    *
@@ -321,7 +247,7 @@ export default class FileObject extends FS {
    */
   async canRead() {
     try {
-      await fs.access(this.#meta.path, fs.constants.R_OK)
+      await fs.access(this.real?.path ?? this.path, fs.constants.R_OK)
 
       return true
     } catch {
@@ -336,7 +262,7 @@ export default class FileObject extends FS {
    */
   async canWrite() {
     try {
-      await fs.access(this.#meta.path, fs.constants.W_OK)
+      await fs.access(this.real?.path ?? this.path, fs.constants.W_OK)
 
       return true
     } catch {
@@ -351,7 +277,7 @@ export default class FileObject extends FS {
    */
   async #fileExists() {
     try {
-      await fs.access(this.#meta.path, fs.constants.F_OK)
+      await fs.access(this.real?.path ?? this.path, fs.constants.F_OK)
 
       return true
     } catch {
@@ -366,7 +292,7 @@ export default class FileObject extends FS {
    */
   async size() {
     try {
-      const stat = await fs.stat(this.#meta.path)
+      const stat = await fs.stat(this.real?.path ?? this.path)
 
       return stat.size
     } catch {
@@ -382,7 +308,7 @@ export default class FileObject extends FS {
    */
   async modified() {
     try {
-      const stat = await fs.stat(this.#meta.path)
+      const stat = await fs.stat(this.real?.path ?? this.path)
 
       return stat.mtime
     } catch {
@@ -397,15 +323,12 @@ export default class FileObject extends FS {
    * @returns {Promise<string>} The file contents
    */
   async read(encoding="utf8") {
-    const url = this.#meta.url
-
-    if(!url)
-      throw Sass.new("No URL in file map")
+    const filePath = this.real?.path ?? this.path
 
     if(!(await this.exists))
-      throw Sass.new(`No such file '${url.href}'`)
+      throw Sass.new(`No such file '${filePath}'`)
 
-    return await fs.readFile(url, encoding)
+    return await fs.readFile(filePath, encoding)
   }
 
   /**
@@ -421,15 +344,12 @@ export default class FileObject extends FS {
    * // Use the buffer (e.g., send in HTTP response, process image, etc.)
    */
   async readBinary() {
-    const url = this.#meta.url
-
-    if(!url)
-      throw Sass.new("No URL in file map")
+    const filePath = this.real?.path ?? this.path
 
     if(!(await this.exists))
-      throw Sass.new(`No such file '${url.href}'`)
+      throw Sass.new(`No such file '${filePath}'`)
 
-    return await fs.readFile(url)
+    return await fs.readFile(filePath)
   }
 
   /**
@@ -445,29 +365,15 @@ export default class FileObject extends FS {
    * await file.write(JSON.stringify({key: 'value'}))
    */
   async write(content, encoding="utf8") {
-    const realPath = FS.virtualToRealPath(this)
-    if(!realPath)
-      throw Sass.new("No actual disk location detected.")
+    const filePath = this.real?.path ?? this.path
 
-    // 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
-      }
-    }
+    if(!filePath)
+      throw Sass.new("No actual disk location detected.")
 
     try {
-      await fs.writeFile(pathToWrite, content, encoding)
+      await fs.writeFile(filePath, content, encoding)
     } catch(error) {
-      if(error.code === "ENOENT")
-        throw Sass.new(`Invalid directory: ${path.dirname(pathToWrite)}`)
-
-      throw Sass.from(error, "Failed to write file")
+      throw Sass.new("Failed to write file.", error)
     }
   }
 
@@ -488,11 +394,10 @@ export default class FileObject extends FS {
    * await file.writeBinary(buffer)
    */
   async writeBinary(data) {
-    if(!this.url)
-      throw Sass.new("No URL in file")
+    const filePath = this.real?.path ?? this.path
 
     const exists = await this.parent.exists
-    Valid.assert(exists, `Invalid directory, ${this.parent.url.href}`)
+    Valid.assert(exists, `Invalid directory writing ${filePath}`)
 
     Valid.assert(Data.isBinary(data), "Data must be binary (ArrayBuffer, TypedArray, Blob, or Buffer)")
 
@@ -501,7 +406,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.url, bufferData)
+    return await fs.writeFile(filePath, bufferData)
   }
 
   /**
@@ -552,15 +457,12 @@ export default class FileObject extends FS {
    * @returns {Promise<object>} The file contents as a module.
    */
   async import() {
-    const url = this.url
-
-    if(!url)
-      throw Sass.new("No URL in file map")
+    const filePath = this.real?.path ?? this.path
 
     if(!(await this.exists))
-      throw Sass.new(`No such file '${url.href}'`)
+      throw Sass.new(`No such file '${filePath}'`)
 
-    return await import(url.href)
+    return await import(filePath)
   }
 
   /**
@@ -574,14 +476,11 @@ export default class FileObject extends FS {
    * await file.delete()
    */
   async delete() {
-    const url = this.url
-
-    if(!url)
-      throw Sass.new("This object does not represent a valid resource.")
+    const filePath = this.real?.path ?? this.path
 
     if(!(await this.exists))
-      throw Sass.new(`No such resource '${url.href}'`)
+      throw Sass.new(`No such resource '${filePath}'`)
 
-    return await fs.unlink(url)
+    return await fs.unlink(filePath)
   }
 }

package/src/{lib/FS.js → node/lib/FileSystem.js}

@@ -11,8 +11,8 @@
 import path from "node:path"
 import url from "node:url"
 
-import Collection from "../browser/lib/Collection.js"
-import Data from "../browser/lib/Data.js"
+import Collection from "../../browser/lib/Collection.js"
+import Data from "../../browser/lib/Data.js"
 import Valid from "./Valid.js"
 
 /** @typedef {import("./FileObject.js").default} FileObject */
@@ -27,7 +27,7 @@ const fdType = Object.freeze(
 /**
  * File system utility class for path operations and file discovery.
  */
-export default class FS {
+export default class FileSystem {
   static fdTypes = fdTypes
   static upperFdTypes = upperFdTypes
   static fdType = fdType
@@ -49,7 +49,7 @@ export default class FS {
       1
     )
 
-    return FS.relativeOrAbsolutePath(fileOrDirectoryObject, this)
+    return FileSystem.relativeOrAbsolutePath(fileOrDirectoryObject, this)
   }
 
   /**
@@ -193,7 +193,7 @@ export default class FS {
 
     // Strategy 3: Try overlap-based merging, which will default to a basic
     // join if no overlap
-    return FS.mergeOverlappingPaths(from, to)
+    return FileSystem.mergeOverlappingPaths(from, to)
   }
 
   /**
@@ -339,14 +339,14 @@ export default class FS {
     let target, cap
 
     if(fileOrDirectoryObject.isFile) {
-      if(!fileOrDirectoryObject.parent.isCapped) {
+      if(!fileOrDirectoryObject.parent.isVirtual) {
         return fileOrDirectoryObject.path
       } else {
         target = fileOrDirectoryObject.path
         cap = fileOrDirectoryObject.parent.cap.real.path
       }
     } else {
-      if(!fileOrDirectoryObject.isCapped) {
+      if(!fileOrDirectoryObject.isVirtual) {
         return fileOrDirectoryObject.path
       } else {
         target = fileOrDirectoryObject.path

package/src/{lib → node/lib}/Glog.js

@@ -13,9 +13,9 @@
 
 import c from "@gesslar/colours"
 
-import Data from "../browser/lib/Data.js"
+import Data from "../../browser/lib/Data.js"
 import Term from "./Term.js"
-import Util from "../browser/lib/Util.js"
+import Util from "../../browser/lib/Util.js"
 // ErrorStackParser will be dynamically imported when needed
 
 // Enhanced color system using @gesslar/colours

package/src/{lib → node/lib}/Logger.js

@@ -26,7 +26,7 @@
 import ErrorStackParser from "error-stack-parser"
 import console from "node:console"
 import {Environment} from "./Core.js"
-import {FileObject, Util} from "@gesslar/toolkit"
+import {FileObject, Util} from "../../../types/node/index.js"
 
 export const loggerColours = {
   debug: [

package/src/{lib → node/lib}/Sass.js

@@ -11,7 +11,7 @@
  * debugging.
  */
 
-import {Sass as BrowserSass} from "../browser/index.js"
+import {Sass as BrowserSass} from "../../browser/index.js"
 import Term from "./Term.js"
 
 /**

package/src/{lib → node/lib}/Tantrum.js

@@ -9,7 +9,7 @@
  * multiple error scenarios.
  */
 
-import {Tantrum as BrowserTantrum} from "../browser/index.js"
+import {Tantrum as BrowserTantrum} from "../../browser/index.js"
 import Sass from "./Sass.js"
 import Term from "./Term.js"
 

package/src/{lib → node/lib}/TempDirectoryObject.js

@@ -8,24 +8,24 @@ import fs, {mkdirSync, mkdtempSync} from "node:fs"
 import os from "node:os"
 import path from "node:path"
 
-import Data from "../browser/lib/Data.js"
-import CappedDirectoryObject from "./CappedDirectoryObject.js"
+import Data from "../../browser/lib/Data.js"
+import VDirectoryObject from "./VDirectoryObject.js"
 import DirectoryObject from "./DirectoryObject.js"
-import FS from "./FS.js"
+import FileSystem from "./FileSystem.js"
 import Sass from "./Sass.js"
 import Valid from "./Valid.js"
 
 /**
- * TempDirectoryObject extends CappedDirectoryObject with the cap set to
+ * TempDirectoryObject extends VDirectoryObject with the cap set to
  * the OS's temporary directory. Temporary directories are created
  * synchronously during construction and exist immediately.
  *
  * All path operations are validated to ensure they remain within the temp
  * directory hierarchy for security.
  *
- * @augments CappedDirectoryObject
+ * @augments VDirectoryObject
  */
-export default class TempDirectoryObject extends CappedDirectoryObject {
+export default class TempDirectoryObject extends VDirectoryObject {
   #tmpReal
   #tmpCap
 
@@ -62,7 +62,7 @@ export default class TempDirectoryObject extends CappedDirectoryObject {
     const parentRealPath = source?.real.path ?? os.tmpdir()
 
     if(source && path.isAbsolute(directory)) {
-      const {root} = FS.pathParts(directory)
+      const {root} = FileSystem.pathParts(directory)
 
       directory = Data.chopLeft(directory, root)
     }
@@ -72,12 +72,12 @@ export default class TempDirectoryObject extends CappedDirectoryObject {
     if(source) {
       toSuper = `/${directory}`
       realTempDirectoryPath =
-        FS.mergeOverlappingPaths(parentRealPath, directory)
+        FileSystem.mergeOverlappingPaths(parentRealPath, directory)
       if(!fs.existsSync(realTempDirectoryPath))
         mkdirSync(realTempDirectoryPath)
     } else {
       realTempDirectoryPath =
-        mkdtempSync(FS.mergeOverlappingPaths(os.tmpdir(), directory))
+        mkdtempSync(FileSystem.mergeOverlappingPaths(os.tmpdir(), directory))
       toSuper = path.resolve(path.sep)
     }
 

package/src/{lib → node/lib}/Util.js

@@ -1,6 +1,6 @@
 import {createHash} from "node:crypto"
 import {EventEmitter} from "node:events"
-import {Util as BrowserUtil} from "../browser/index.js"
+import {Util as BrowserUtil} from "../../browser/index.js"
 import Sass from "./Sass.js"
 import process from "node:process"
 import JSON5 from "json5"