@gesslar/toolkit 0.0.12 → 0.0.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gesslar/toolkit",
-  "version": "0.0.12",
+  "version": "0.0.13",
   "description": "Get in, bitches, we're going toolkitting.",
   "main": "./src/index.js",
   "type": "module",
@@ -63,10 +63,10 @@
   "devDependencies": {
     "@stylistic/eslint-plugin": "^5.4.0",
     "@types/node": "^24.5.2",
-    "@typescript-eslint/eslint-plugin": "^8.44.1",
-    "@typescript-eslint/parser": "^8.44.1",
+    "@typescript-eslint/eslint-plugin": "^8.44.0",
+    "@typescript-eslint/parser": "^8.44.0",
     "eslint": "^9.36.0",
-    "eslint-plugin-jsdoc": "^60.3.0",
+    "eslint-plugin-jsdoc": "^60.1.0",
     "typedoc": "^0.28.13",
     "typedoc-plugin-markdown": "^4.9.0"
   }

package/src/index.js

@@ -1,7 +1,7 @@
 // Core file system abstractions
 export {default as FileObject} from "./lib/FileObject.js"
 export {default as DirectoryObject} from "./lib/DirectoryObject.js"
-export {default as File} from "./lib/File.js"
+export {default as FS} from "./lib/FS.js"
 
 // Utility classes
 export {default as Cache} from "./lib/Cache.js"

package/src/lib/Cache.js

@@ -1,4 +1,4 @@
-import File from "./File.js"
+import File from "./FS.js"
 import FileObject from "./FileObject.js"
 import Sass from "./Sass.js"
 

package/src/lib/DirectoryObject.js

@@ -4,10 +4,13 @@
  * resolution and existence checks.
  */
 
+import fs from "node:fs/promises"
 import path from "node:path"
 import util from "node:util"
 
-import File from "./File.js"
+import FS from "./FS.js"
+import FileObject from "./FileObject.js"
+import Sass from "./Sass.js"
 
 /**
  * DirectoryObject encapsulates metadata and operations for a directory,
@@ -23,7 +26,7 @@ import File from "./File.js"
  * @property {boolean} isDirectory - Always true
  * @property {Promise<boolean>} exists - Whether the directory exists (async)
  */
-export default class DirectoryObject {
+export default class DirectoryObject extends FS {
   /**
    * @type {object}
    * @private
@@ -54,10 +57,12 @@ export default class DirectoryObject {
    * @param {string} directory - The directory path
    */
   constructor(directory) {
-    const fixedDir = File.fixSlashes(directory ?? ".")
+    super(directory)
+
+    const fixedDir = FS.fixSlashes(directory ?? ".")
     const absolutePath = path.resolve(fixedDir)
-    const fileUri = File.pathToUri(absolutePath)
-    const filePath = File.uriToPath(fileUri)
+    const fileUri = FS.pathToUri(absolutePath)
+    const filePath = FS.uriToPath(fileUri)
     const baseName = path.basename(absolutePath) || "."
 
     this.#meta.supplied = fixedDir
@@ -112,7 +117,7 @@ export default class DirectoryObject {
    * @returns {Promise<boolean>} - A Promise that resolves to true or false
    */
   get exists() {
-    return File.directoryExists(this)
+    return this.#directoryExists()
   }
 
   /**
@@ -186,4 +191,66 @@ export default class DirectoryObject {
   get isDirectory() {
     return this.#meta.isDirectory
   }
+
+  /**
+   * Check if a directory exists
+   *
+   * @returns {Promise<boolean>} Whether the directory exists
+   */
+  async #directoryExists() {
+    try {
+      (await fs.opendir(this.path)).close()
+
+      return true
+    } catch(_) {
+      return false
+    }
+  }
+
+  /**
+   * Lists the contents of a directory.
+   *
+   * @param {DirectoryObject} directory - The directory to list.
+   * @returns {Promise<{files: Array<FileObject>, directories: Array<DirectoryObject>}>} The files and directories in the directory.
+   */
+  async read(directory) {
+    const found = await fs.readdir(directory.uri, {withFileTypes: true})
+    const results = await Promise.all(
+      found.map(async dirent => {
+        const fullPath = path.join(directory.uri, dirent.name)
+        const stat = await fs.stat(fullPath)
+
+        return {dirent, stat, fullPath}
+      }),
+    )
+
+    const files = results
+      .filter(({stat}) => stat.isFile())
+      .map(({fullPath}) => new FileObject(fullPath))
+
+    const directories = results
+      .filter(({stat}) => stat.isDirectory())
+      .map(({fullPath}) => new DirectoryObject(fullPath))
+
+    return {files, directories}
+  }
+
+  /**
+   * Ensures a directory exists, creating it if necessary
+   *
+   * @async
+   * @param {object} [options] - Any options to pass to mkdir
+   * @returns {Promise<void>}
+   * @throws {Sass} If directory creation fails
+   */
+  async assureExists(options = {}) {
+    if(await this.exists)
+      return
+
+    try {
+      await fs.mkdir(this.path, options)
+    } catch(e) {
+      throw Sass.new(`Unable to create directory '${this.path}': ${e.message}`)
+    }
+  }
 }

package/src/lib/FS.js

@@ -0,0 +1,187 @@
+import {globby} from "globby"
+import path from "node:path"
+import url from "node:url"
+
+import Data from "./Data.js"
+import DirectoryObject from "./DirectoryObject.js"
+import FileObject from "./FileObject.js"
+import Sass from "./Sass.js"
+import Valid from "./Valid.js"
+
+export default class FS {
+  /**
+   * Fix slashes in a path
+   *
+   * @param {string} pathName - The path to fix
+   * @returns {string} The fixed path
+   */
+  static fixSlashes(pathName) {
+    return pathName.replace(/\\/g, "/")
+  }
+
+  /**
+   * Convert a path to a URI
+   *
+   * @param {string} pathName - The path to convert
+   * @returns {string} The URI
+   */
+  static pathToUri(pathName) {
+    try {
+      return url.pathToFileURL(pathName).href
+    } catch(e) {
+      void e // stfu linter
+
+      return pathName
+    }
+  }
+
+  /**
+   * Convert a URI to a path
+   *
+   * @param {string} pathName - The URI to convert
+   * @returns {string} The path
+   */
+  static uriToPath(pathName) {
+    try {
+      return url.fileURLToPath(pathName)
+    } catch(_) {
+      return pathName
+    }
+  }
+
+  /**
+   * Retrieve all files matching a specific glob pattern.
+   *
+   * @param {string|Array<string>} glob - The glob pattern(s) to search.
+   * @returns {Promise<Array<FileObject>>} A promise that resolves to an array of file objects
+   * @throws {Sass} If the input is not a string or array of strings.
+   * @throws {Sass} If the glob pattern array is empty or for other search failures.
+   */
+  static async getFiles(glob) {
+    Valid.assert(
+      (
+        (typeof glob === "string" && glob.length > 0) ||
+        (
+          Array.isArray(glob) && Data.uniformStringArray(glob) &&
+          glob.length > 0
+        )
+      ),
+      "glob must be a non-empty string or array of strings.",
+      1
+    )
+
+    const globbyArray = (
+      typeof glob === "string"
+        ? glob
+          .split("|")
+          .map(g => g.trim())
+          .filter(Boolean)
+        : glob
+    ).map(g => FS.fixSlashes(g))
+
+    if(
+      Array.isArray(globbyArray) &&
+      Data.uniformStringArray(globbyArray) &&
+      !globbyArray.length
+    )
+      throw Sass.new(
+        `Invalid glob pattern: Array cannot be empty. Got ${JSON.stringify(glob)}`,
+      )
+
+    // Use Globby to fetch matching files
+    const filesArray = await globby(globbyArray)
+    const files = filesArray.map(file => new FileObject(file))
+
+    // Flatten the result and remove duplicates
+    return files
+  }
+
+  /**
+   * 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.
+   *
+   * @param {FileObject|DirectoryObject} from - The source file or directory object
+   * @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) {
+    const relative = path.relative(from.path, to.path)
+
+    return relative.startsWith("..")
+      ? to.path
+      : relative
+  }
+
+  /**
+   * Merge two paths by finding overlapping segments and combining them efficiently
+   *
+   * @param {string} path1 - The first path
+   * @param {string} path2 - The second path to merge with the first
+   * @param {string} [sep] - The path separator to use (defaults to system separator)
+   * @returns {string} The merged path
+   */
+  static mergeOverlappingPaths(path1, path2, sep=path.sep) {
+    const from = path1.split(sep).filter(Boolean)
+    const to = path2.split(sep).filter(Boolean)
+
+    // If they're the same, just return path1
+    if(to.length === from.length && from.every((f, i) => to[i] === f)) {
+      return path1
+    }
+
+    const overlapIndex = from.findLastIndex((curr, index) => {
+      const left = from.at(index)
+      const right = to.at(0)
+
+      return left === right
+    })
+
+    // If overlap is found, slice and join
+    if(overlapIndex !== -1) {
+      const prefix = from.slice(0, overlapIndex)
+
+      return path.join(...prefix, ...to)
+    }
+
+    // If no overlap, just join the paths
+    return path.join(path1, path2)
+  }
+
+  /**
+   * Resolve a path relative to another path using various strategies
+   * Handles absolute paths, relative navigation, and overlap-based merging
+   *
+   * @param {string} fromPath - The base path to resolve from
+   * @param {string} toPath - The target path to resolve
+   * @returns {string} The resolved path
+   */
+  static resolvePath(fromPath, toPath) {
+    // Normalize inputs
+    const from = fromPath.trim()
+    const to = toPath.trim()
+
+    // Handle empty cases
+    if(!from && !to)
+      return ""
+
+    if(!from)
+      return to
+
+    if(!to)
+      return from
+
+    // Strategy 1: If 'to' is absolute, it's standalone
+    if(path.isAbsolute(to))
+      return to
+
+    // Strategy 2: If 'to' contains relative navigation (./ or ../)
+    if(to.includes("./") || to.includes("../") || to.startsWith(".") || to.startsWith(".."))
+      return path.resolve(from, to)
+
+    // Strategy 3: Try overlap-based merging, which will default to a basic
+    // join if no overlap
+    return FS.mergeOverlappingPaths(from, to)
+  }
+}

package/src/lib/FileObject.js

@@ -4,11 +4,16 @@
  * resolution and existence checks.
  */
 
+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 DirectoryObject from "./DirectoryObject.js"
-import File from "./File.js"
+import FS from "./FS.js"
+import Sass from "./Sass.js"
+import Valid from "./Valid.js"
 
 /**
  * FileObject encapsulates metadata and operations for a file, including path
@@ -26,7 +31,7 @@ import File from "./File.js"
  * @property {Promise<boolean>} exists - Whether the file exists (async)
  */
 
-export default class FileObject {
+export default class FileObject extends FS {
   /**
    * @type {object}
    * @private
@@ -59,9 +64,11 @@ export default class FileObject {
    * @param {DirectoryObject|string|null} [directory] - The parent directory (object or string)
    */
   constructor(fileName, directory=null) {
-    const fixedFile = File.fixSlashes(fileName)
+    super(fileName, directory)
 
-    const {dir,base,ext} = File.deconstructFilenameToParts(fixedFile)
+    const fixedFile = FS.fixSlashes(fileName)
+
+    const {dir,base,ext} = this.#deconstructFilenameToParts(fixedFile)
 
     if(!directory)
       directory = new DirectoryObject(dir)
@@ -71,7 +78,7 @@ export default class FileObject {
       : path.resolve(directory?.path ?? ".", fixedFile)
 
     const resolved = final
-    const fileUri = File.pathToUri(resolved)
+    const fileUri = FS.pathToUri(resolved)
 
     this.#meta.supplied = fixedFile
     this.#meta.path = resolved
@@ -80,7 +87,7 @@ export default class FileObject {
     this.#meta.extension = ext
     this.#meta.module = path.basename(this.supplied, this.extension)
 
-    const {dir: newDir} = File.deconstructFilenameToParts(this.path)
+    const {dir: newDir} = this.#deconstructFilenameToParts(this.path)
 
     this.#meta.directory = new DirectoryObject(newDir)
 
@@ -127,7 +134,7 @@ export default class FileObject {
    * @returns {Promise<boolean>} - A Promise that resolves to true or false
    */
   get exists() {
-    return File.fileExists(this)
+    return this.#fileExists()
   }
 
   /**
@@ -219,4 +226,161 @@ export default class FileObject {
   get directory() {
     return this.#meta.directory
   }
+
+  /**
+   * Check if a file can be read. Returns true if the file can be read, false
+   *
+   * @returns {Promise<boolean>} Whether the file can be read
+   */
+  async canRead() {
+    try {
+      await fs.access(this.path, fs.constants.R_OK)
+
+      return true
+    } catch(_) {
+      return false
+    }
+  }
+
+  /**
+   * Check if a file can be written. Returns true if the file can be written,
+   *
+   * @returns {Promise<boolean>} Whether the file can be written
+   */
+  async canWrite() {
+    try {
+      await fs.access(this.path, fs.constants.W_OK)
+
+      return true
+    } catch(_) {
+      return false
+    }
+  }
+
+  /**
+   * Check if a file exists
+   *
+   * @returns {Promise<boolean>} Whether the file exists
+   */
+  async #fileExists() {
+    try {
+      await fs.access(this.path, fs.constants.F_OK)
+
+      return true
+    } catch(_) {
+      return false
+    }
+  }
+
+  /**
+   * Determines the size of a file.
+   *
+   * @returns {Promise<number?>} - The size of the file or null, if it doesn't exist.
+   */
+  async size() {
+    try {
+      const stat = await fs.stat(this.path)
+
+      return stat.size
+    } catch(_) {
+      return null
+    }
+  }
+
+  /**
+   * Gets the last modification time of a file.
+   * Used by the caching system to determine if cached data is still valid.
+   *
+   * @returns {Promise<Date?>} The last modification time, or null if file doesn't exist
+   */
+  async modified() {
+    try {
+      const stat = await fs.stat(this.path)
+
+      return stat.mtime
+    } 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.
+   *
+   * @param {string} [encoding] - The encoding to read the file as.
+   * @returns {Promise<string>} The file contents
+   */
+  async read(encoding="utf8") {
+    const filePath = this.path
+
+    if(!(await this.exists))
+      throw Sass.new(`No such file '${filePath}'`)
+
+    if(!filePath)
+      throw Sass.new("No absolute path in file map")
+
+    return await fs.readFile(filePath, encoding)
+  }
+
+  /**
+   * Writes content to a file synchronously.
+   *
+   * @param {string} content - The content to write
+   * @param {string} encoding - The encoding in which to write.
+   * @returns {Promise<void>}
+   */
+  async write(content, encoding="utf8") {
+    if(!this.path)
+      throw Sass.new("No absolute path in file")
+
+    await fs.writeFile(this.path, content, encoding)
+  }
+
+  /**
+   * Loads an object from JSON or YAML provided a fileMap
+   *
+   * @param {string} [type] - The expected type of data to parse.
+   * @param {string} [encoding] - The encoding to read the file as.
+   * @returns {object} The parsed data object.
+   */
+  async loadData(type="any", encoding="utf8") {
+    const content = await this.read(encoding)
+    const toTry = {
+      json5: [JSON5],
+      json: [JSON5],
+      yaml: [YAML],
+      any: [JSON5,YAML]
+    }[type.toLowerCase()]
+
+    for(const [format] of toTry) {
+      try {
+        const result = format.parse(content)
+
+        return result
+      } catch {
+        // nothing to see here
+      }
+    }
+
+    throw Sass.new(`Content is neither valid JSON5 nor valid YAML:\n'${this.path}'`)
+  }
 }

package/src/types/DirectoryObject.d.ts

@@ -1,11 +1,21 @@
 // Implementation: ../lib/DirectoryObject.js
 // Type definitions for DirectoryObject
 
+import FS from './FS.js'
+import FileObject from './FileObject.js'
+
+export interface DirectoryListing {
+  /** Array of FileObject instances */
+  files: Array<FileObject>
+  /** Array of DirectoryObject instances */
+  directories: Array<DirectoryObject>
+}
+
 /**
  * DirectoryObject encapsulates metadata and operations for a directory,
  * including path resolution and existence checks.
  */
-export default class DirectoryObject {
+export default class DirectoryObject extends FS {
   /**
    * Create a new DirectoryObject instance.
    * @param directory - The directory path
@@ -53,4 +63,10 @@ export default class DirectoryObject {
     isFile: boolean
     isDirectory: boolean
   }
-}
+
+  /** List the contents of this directory */
+  read(): Promise<DirectoryListing>
+
+  /** Ensure this directory exists, creating it if necessary */
+  assureExists(options?: any): Promise<void>
+}

package/src/types/FS.d.ts

@@ -0,0 +1,31 @@
+// Implementation: ../lib/FS.js
+// Type definitions for FS utilities
+
+import FileObject from './FileObject.js'
+import DirectoryObject from './DirectoryObject.js'
+
+/**
+ * Base filesystem utilities class. FileObject and DirectoryObject extend this class.
+ */
+export default class FS {
+  /** Fix slashes in a path */
+  static fixSlashes(pathName: string): string
+
+  /** Convert a path to a URI */
+  static pathToUri(pathName: string): string
+
+  /** Convert a URI to a path */
+  static uriToPath(pathName: string): string
+
+  /** Retrieve files matching glob pattern(s) */
+  static getFiles(glob: string | Array<string>): Promise<Array<FileObject>>
+
+  /** Compute relative path between two file system objects */
+  static relativeOrAbsolutePath(from: FileObject | DirectoryObject, to: FileObject | DirectoryObject): string
+
+  /** Merge two paths by finding overlapping segments and combining them efficiently */
+  static mergeOverlappingPaths(path1: string, path2: string, sep?: string): string
+
+  /** Resolve a path relative to another path using various strategies. Handles absolute paths, relative navigation, and overlap-based merging */
+  static resolvePath(fromPath: string, toPath: string): string
+}

package/src/types/FileObject.d.ts

@@ -1,6 +1,7 @@
 // Implementation: ../lib/FileObject.js
 
 import DirectoryObject from './DirectoryObject.js'
+import FS from './FS.js'
 
 /**
  * FileObject encapsulates metadata and operations for a file, providing intelligent
@@ -60,7 +61,7 @@ import DirectoryObject from './DirectoryObject.js'
  *
  * for (const fileItem of files) {
  *   console.log(`${fileItem.module}${fileItem.extension} -> ${fileItem.path}`)
- *   
+ *
  *   // Type-based processing
  *   switch (fileItem.extension) {
  *     case '.json':
@@ -99,7 +100,7 @@ import DirectoryObject from './DirectoryObject.js'
  * inherits the directory's resolved path, ensuring consistency in hierarchical
  * file operations.
  */
-export default class FileObject {
+export default class FileObject extends FS {
   /**
    * Create a new FileObject instance with intelligent path resolution.
    *
@@ -142,8 +143,8 @@ export default class FileObject {
    * // Complex directory structures and nested files
    * const projectRoot = new DirectoryObject('./my-project')
    * const srcDir = new DirectoryObject('src', projectRoot)
-   * 
-   * // Create files within nested directory structure  
+   *
+   * // Create files within nested directory structure
    * const mainApp = new FileObject('App.tsx', srcDir)
    * const stylesheet = new FileObject('styles/main.css', srcDir)
    * const testFile = new FileObject('__tests__/App.test.tsx', srcDir)
@@ -151,7 +152,7 @@ export default class FileObject {
    * console.log('Main app:', mainApp.path)     // /absolute/path/my-project/src/App.tsx
    * console.log('Stylesheet:', stylesheet.path) // /absolute/path/my-project/src/styles/main.css
    * console.log('Test file:', testFile.path)   // /absolute/path/my-project/src/__tests__/App.test.tsx
-   * 
+   *
    * // All files share the same parent directory reference
    * console.log('Same parent?', mainApp.directory === srcDir) // true
    * ```
@@ -160,7 +161,7 @@ export default class FileObject {
 
   /**
    * The original user-supplied path string used during construction.
-   * 
+   *
    * Preserves the exact path string passed to the constructor, including
    * any relative path indicators (./, ../) or path separators. Useful
    * for debugging, logging, or when you need to recreate the original
@@ -170,7 +171,7 @@ export default class FileObject {
    * ```typescript
    * const file1 = new FileObject('./config.json')
    * const file2 = new FileObject('../package.json')
-   * 
+   *
    * console.log(file1.supplied) // './config.json'
    * console.log(file2.supplied) // '../package.json'
    * console.log(file1.path)     // '/absolute/path/to/config.json'
@@ -181,7 +182,7 @@ export default class FileObject {
 
   /**
    * The fully resolved absolute file path with normalized separators.
-   * 
+   *
    * Automatically resolved during construction using Node.js path utilities.
    * Always uses forward slashes on Unix systems and backslashes on Windows.
    * This is the canonical path that should be used for all file operations.
@@ -189,9 +190,9 @@ export default class FileObject {
    * @example
    * ```typescript
    * // Different inputs, same resolved path
-   * const file1 = new FileObject('./src/../config.json')  
+   * const file1 = new FileObject('./src/../config.json')
    * const file2 = new FileObject('config.json')
-   * 
+   *
    * console.log(file1.path) // '/absolute/path/config.json'
    * console.log(file2.path) // '/absolute/path/config.json'
    * console.log(file1.path === file2.path) // true
@@ -201,7 +202,7 @@ export default class FileObject {
 
   /**
    * The file URI representation following RFC 3986 standard.
-   * 
+   *
    * Converts the absolute file path to a proper file:// URI scheme,
    * handling URL encoding for special characters and proper formatting
    * for cross-platform file URI access.
@@ -209,9 +210,9 @@ export default class FileObject {
    * @example
    * ```typescript
    * const file = new FileObject('./my project/config file.json')
-   * console.log(file.uri) 
+   * console.log(file.uri)
    * // 'file:///absolute/path/my%20project/config%20file.json'
-   * 
+   *
    * // Can be used with URL constructor or file:// handlers
    * const url = new URL(file.uri)
    * console.log(url.pathname) // '/absolute/path/my project/config file.json'
@@ -221,7 +222,7 @@ export default class FileObject {
 
   /**
    * The complete filename including extension.
-   * 
+   *
    * Extracted from the resolved path using Node.js path utilities.
    * Includes the file extension but excludes any directory components.
    *
@@ -229,7 +230,7 @@ export default class FileObject {
    * ```typescript
    * const jsFile = new FileObject('./src/components/Button.tsx')
    * const configFile = new FileObject('../.env.production')
-   * 
+   *
    * console.log(jsFile.name)    // 'Button.tsx'
    * console.log(configFile.name) // '.env.production'
    * ```
@@ -238,7 +239,7 @@ export default class FileObject {
 
   /**
    * The filename without its extension, suitable for module identification.
-   * 
+   *
    * Useful for generating module names, import statements, or when you need
    * the base name without file type information. Handles complex extensions
    * and dotfiles appropriately.
@@ -247,7 +248,7 @@ export default class FileObject {
 
   /**
    * The file extension including the leading dot.
-   * 
+   *
    * Extracted using Node.js path utilities, always includes the dot prefix.
    * Returns an empty string for files without extensions. Handles multiple
    * extensions by returning only the last one.
@@ -262,7 +263,7 @@ export default class FileObject {
 
   /**
    * The parent DirectoryObject containing this file.
-   * 
+   *
    * Automatically created during FileObject construction based on the resolved
    * file path. Provides access to parent directory operations and maintains
    * the hierarchical relationship between files and directories.
@@ -271,7 +272,7 @@ export default class FileObject {
 
   /**
    * Promise that resolves to whether the file exists on the filesystem.
-   * 
+   *
    * Performs an asynchronous filesystem check to determine file existence.
    * The Promise will resolve to true if the file exists and is accessible,
    * false otherwise. Always await this property before using the result.
@@ -290,4 +291,25 @@ export default class FileObject {
     isDirectory: boolean
     directory: string | null
   }
+
+  /** Check if a file can be read */
+  canRead(): Promise<boolean>
+
+  /** Check if a file can be written */
+  canWrite(): Promise<boolean>
+
+  /** Get the size of a file */
+  size(): Promise<number | null>
+
+  /** Get the last modification time of a file */
+  modified(): Promise<Date | null>
+
+  /** Read the content of a file */
+  read(encoding?: string): Promise<string>
+
+  /** Write content to a file */
+  write(content: string, encoding?: string): Promise<void>
+
+  /** Load an object from JSON5 or YAML file with type specification */
+  loadData(type?: 'json' | 'json5' | 'yaml' | 'any', encoding?: string): Promise<any>
 }

package/src/types/index.d.ts

@@ -2,7 +2,7 @@
 // Core file system abstractions
 export { default as FileObject } from './FileObject.js'
 export { default as DirectoryObject } from './DirectoryObject.js'
-export { default as File } from './File.js'
+export { default as FS } from './FS.js'
 
 // Utility classes
 export { default as Cache } from './Cache.js'
@@ -15,4 +15,4 @@ export { default as Util } from './Util.js'
 export { default as Valid } from './Valid.js'
 
 // Type exports
-export type { FileParts } from './File.js'
+export type { FileParts } from './FS.js'

package/src/lib/File.js

@@ -1,414 +0,0 @@
-/**
- * @file File system utilities for reading, writing, and manipulating files and directories.
- * Provides comprehensive file operations including data file loading (JSON5/YAML),
- * path resolution, and file system navigation with support for both files and directories.
- */
-
-import {globby} from "globby"
-import JSON5 from "json5"
-import fs from "node:fs/promises"
-import path from "node:path"
-import url from "node:url"
-import YAML from "yaml"
-
-import Data from "./Data.js"
-import DirectoryObject from "./DirectoryObject.js"
-import FileObject from "./FileObject.js"
-import Sass from "./Sass.js"
-import Valid from "./Valid.js"
-
-export default class File {
-/**
- * Fix slashes in a path
- *
- * @param {string} pathName - The path to fix
- * @returns {string} The fixed path
- */
-  static fixSlashes(pathName) {
-    return pathName.replace(/\\/g, "/")
-  }
-
-  /**
-   * Convert a path to a URI
-   *
-   * @param {string} pathName - The path to convert
-   * @returns {string} The URI
-   */
-  static pathToUri(pathName) {
-    try {
-      return url.pathToFileURL(pathName).href
-    } catch(e) {
-      void e // stfu linter
-
-      return pathName
-    }
-  }
-
-  /**
-   * Check if a file can be read. Returns true if the file can be read, false
-   *
-   * @param {FileObject} file - The file map to check
-   * @returns {Promise<boolean>} Whether the file can be read
-   */
-  static async canReadFile(file) {
-    try {
-      await fs.access(file.path, fs.constants.R_OK)
-
-      return true
-    } catch(_) {
-      return false
-    }
-  }
-
-  /**
-   * Check if a file can be written. Returns true if the file can be written,
-   *
-   * @param {FileObject} file - The file map to check
-   * @returns {Promise<boolean>} Whether the file can be written
-   */
-  static async canWriteFile(file) {
-    try {
-      await fs.access(file.path, fs.constants.W_OK)
-
-      return true
-    } catch(_) {
-      return false
-    }
-  }
-
-  /**
-   * Check if a file exists
-   *
-   * @param {FileObject} file - The file map to check
-   * @returns {Promise<boolean>} Whether the file exists
-   */
-  static async fileExists(file) {
-    try {
-      await fs.access(file.path, fs.constants.F_OK)
-
-      return true
-    } catch(_) {
-      return false
-    }
-  }
-
-  /**
-   * Determines the size of a file.
-   *
-   * @param {FileObject} file - The file object to test
-   * @returns {Promise<number?>} - The size of the file or null, if it doesn't exist.
-   */
-  static async fileSize(file) {
-    try {
-      const stat = await fs.stat(file.path)
-
-      return stat.size
-    } catch(_) {
-      return null
-    }
-  }
-
-  /**
-   * Gets the last modification time of a file.
-   * Used by the caching system to determine if cached data is still valid.
-   *
-   * @param {FileObject} file - The file object to check
-   * @returns {Promise<Date|null>} The last modification time, or null if file doesn't exist
-   */
-  static async fileModified(file) {
-    try {
-      const stat = await fs.stat(file.path)
-
-      return stat.mtime
-    } catch(_) {
-      return null
-    }
-  }
-
-  /**
-   * Check if a directory exists
-   *
-   * @param {DirectoryObject} dirObject - The directory map to check
-   * @returns {Promise<boolean>} Whether the directory exists
-   */
-  static async directoryExists(dirObject) {
-    try {
-      (await fs.opendir(dirObject.path)).close()
-
-      return true
-    } catch(_) {
-      return false
-    }
-  }
-
-  /**
-   * Convert a URI to a path
-   *
-   * @param {string} pathName - The URI to convert
-   * @returns {string} The path
-   */
-  static uriToPath(pathName) {
-    try {
-      return url.fileURLToPath(pathName)
-    } catch(_) {
-      return pathName
-    }
-  }
-
-  /**
-   * @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
-   */
-  static deconstructFilenameToParts(fileName) {
-    Valid.assert(typeof fileName === "string" && fileName.length > 0,
-      "file must be a non-zero length string", 1)
-
-    return path.parse(fileName)
-  }
-
-  /**
-   * Retrieve all files matching a specific glob pattern.
-   *
-   * @param {string|Array<string>} glob - The glob pattern(s) to search.
-   * @returns {Promise<Array<FileObject>>} A promise that resolves to an array of file objects
-   * @throws {Sass} If the input is not a string or array of strings.
-   * @throws {Sass} If the glob pattern array is empty or for other search failures.
-   */
-  static async getFiles(glob) {
-    Valid.assert(
-      (
-        (typeof glob === "string" && glob.length > 0) ||
-        (
-          Array.isArray(glob) && Data.uniformStringArray(glob) &&
-          glob.length > 0
-        )
-      ),
-      "glob must be a non-empty string or array of strings.",
-      1
-    )
-
-    const globbyArray = (
-      typeof glob === "string"
-        ? glob
-          .split("|")
-          .map(g => g.trim())
-          .filter(Boolean)
-        : glob
-    ).map(g => File.fixSlashes(g))
-
-    if(
-      Array.isArray(globbyArray) &&
-      Data.uniformStringArray(globbyArray) &&
-      !globbyArray.length
-    )
-      throw Sass.new(
-        `Invalid glob pattern: Array cannot be empty. Got ${JSON.stringify(glob)}`,
-      )
-
-    // Use Globby to fetch matching files
-    const filesArray = await globby(globbyArray)
-    const files = filesArray.map(file => new FileObject(file))
-
-    // Flatten the result and remove duplicates
-    return files
-  }
-
-  /**
-   * Lists the contents of a directory.
-   *
-   * @param {DirectoryObject} directory - The directory to list.
-   * @returns {Promise<{files: Array<FileObject>, directories: Array<DirectoryObject>}>} The files and
-   * directories in the directory.
-   */
-  static async ls(directory) {
-    const found = await fs.readdir(directory.uri, {withFileTypes: true})
-    const results = await Promise.all(
-      found.map(async dirent => {
-        const fullPath = path.join(directory.uri, dirent.name)
-        const stat = await fs.stat(fullPath)
-
-        return {dirent, stat, fullPath}
-      }),
-    )
-
-    const files = results
-      .filter(({stat}) => stat.isFile())
-      .map(({fullPath}) => new FileObject(fullPath))
-
-    const directories = results
-      .filter(({stat}) => stat.isDirectory())
-      .map(({fullPath}) => new DirectoryObject(fullPath))
-
-    return {files, directories}
-  }
-
-  /**
-   * Reads the content of a file asynchronously.
-   *
-   * @param {FileObject} fileObject - The file map containing the file path
-   * @returns {Promise<string>} The file contents
-   */
-  static async readFile(fileObject) {
-    const filePath = fileObject.path
-
-    if(!(await fileObject.exists))
-      throw Sass.new(`No such file '${filePath}'`)
-
-    if(!filePath)
-      throw Sass.new("No absolute path in file map")
-
-    return await fs.readFile(filePath, "utf8")
-  }
-
-  /**
-   * Writes content to a file synchronously.
-   *
-   * @param {FileObject} fileObject - The file map containing the file path
-   * @param {string} content - The content to write
-   */
-  static async writeFile(fileObject, content) {
-    if(!fileObject.path)
-      throw Sass.new("No absolute path in file")
-
-    await fs.writeFile(fileObject.path, content, "utf8")
-  }
-
-  /**
-   * Loads an object from JSON or YAML provided a fileMap
-   *
-   * @param {FileObject} fileObject - The FileObj file to load containing
-   *  JSON or YAML text.
-   * @returns {object} The parsed data object.
-   */
-  static async loadDataFile(fileObject) {
-    const content = await File.readFile(fileObject)
-
-    try {
-      return JSON5.parse(content)
-    } catch {
-      try {
-        return YAML.parse(content)
-      } catch {
-        throw Sass.new(`Content is neither valid JSON nor valid YAML:\n'${fileObject.path}'`)
-      }
-    }
-  }
-
-  /**
-   * Ensures a directory exists, creating it if necessary
-   *
-   * @async
-   * @param {DirectoryObject} dirObject - The path or DirMap of the directory to assure exists
-   * @param {object} [options] - Any options to pass to mkdir
-   * @returns {Promise<void>}
-   * @throws {Sass} If directory creation fails
-   */
-  static async assureDirectory(dirObject, options = {}) {
-    if(await dirObject.exists)
-      return
-
-    try {
-      await fs.mkdir(dirObject.path, options)
-    } catch(e) {
-      throw Sass.new(`Unable to create directory '${dirObject.path}': ${e.message}`)
-    }
-  }
-
-  /**
-   * 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.
-   *
-   * @param {FileObject|DirectoryObject} from - The source file or directory object
-   * @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) {
-    const relative = path.relative(from.path, to.path)
-
-    return relative.startsWith("..")
-      ? to.path
-      : relative
-  }
-
-  /**
-   * Merge two paths by finding overlapping segments and combining them efficiently
-   *
-   * @param {string} path1 - The first path
-   * @param {string} path2 - The second path to merge with the first
-   * @param {string} [sep] - The path separator to use (defaults to system separator)
-   * @returns {string} The merged path
-   */
-  static mergeOverlappingPaths(path1, path2, sep=path.sep) {
-    const from = path1.split(sep).filter(Boolean)
-    const to = path2.split(sep).filter(Boolean)
-
-    // If they're the same, just return path1
-    if(to.length === from.length && from.every((f, i) => to[i] === f)) {
-      return path1
-    }
-
-    const overlapIndex = from.findLastIndex((curr, index) => {
-      const left = from.at(index)
-      const right = to.at(0)
-
-      return left === right
-    })
-
-    // If overlap is found, slice and join
-    if(overlapIndex !== -1) {
-      const prefix = from.slice(0, overlapIndex)
-
-      return path.join(...prefix, ...to)
-    }
-
-    // If no overlap, just join the paths
-    return path.join(path1, path2)
-  }
-
-  /**
-   * Resolve a path relative to another path using various strategies
-   * Handles absolute paths, relative navigation, and overlap-based merging
-   *
-   * @param {string} fromPath - The base path to resolve from
-   * @param {string} toPath - The target path to resolve
-   * @returns {string} The resolved path
-   */
-  static resolvePath(fromPath, toPath) {
-    // Normalize inputs
-    const from = fromPath.trim()
-    const to = toPath.trim()
-
-    // Handle empty cases
-    if(!from && !to)
-      return ""
-
-    if(!from)
-      return to
-
-    if(!to)
-      return from
-
-    // Strategy 1: If 'to' is absolute, it's standalone
-    if(path.isAbsolute(to))
-      return to
-
-    // Strategy 2: If 'to' contains relative navigation (./ or ../)
-    if(to.includes("./") || to.includes("../") || to.startsWith(".") || to.startsWith(".."))
-      return path.resolve(from, to)
-
-    // Strategy 3: Try overlap-based merging, which will default to a basic
-    // join if no overlap
-    return File.mergeOverlappingPaths(from, to)
-  }
-}

package/src/types/File.d.ts

@@ -1,83 +0,0 @@
-// Implementation: ../lib/File.js
-// Type definitions for File utilities
-
-import FileObject from './FileObject.js'
-import DirectoryObject from './DirectoryObject.js'
-
-export interface FileParts {
-  /** The file name with extension */
-  base: string
-  /** The directory path */
-  dir: string
-  /** The file extension (including dot) */
-  ext: string
-}
-
-export interface DirectoryListing {
-  /** Array of FileObject instances */
-  files: Array<FileObject>
-  /** Array of DirectoryObject instances */
-  directories: Array<DirectoryObject>
-}
-
-/**
- * File system utilities for reading, writing, and manipulating files and directories.
- */
-export default class File {
-  /** Fix slashes in a path */
-  static fixSlashes(pathName: string): string
-
-  /** Convert a path to a URI */
-  static pathToUri(pathName: string): string
-
-  /** Convert a URI to a path */
-  static uriToPath(pathName: string): string
-
-  /** Check if a file can be read */
-  static canReadFile(file: FileObject): Promise<boolean>
-
-  /** Check if a file can be written */
-  static canWriteFile(file: FileObject): Promise<boolean>
-
-  /** Check if a file exists */
-  static fileExists(file: FileObject): Promise<boolean>
-
-  /** Get the size of a file */
-  static fileSize(file: FileObject): Promise<number | null>
-
-  /** Get the last modification time of a file */
-  static fileModified(file: FileObject): Promise<Date | null>
-
-  /** Check if a directory exists */
-  static directoryExists(dirObject: DirectoryObject): Promise<boolean>
-
-  /** Deconstruct a filename into parts */
-  static deconstructFilenameToParts(fileName: string): FileParts
-
-  /** Retrieve files matching glob pattern(s) */
-  static getFiles(glob: string | Array<string>): Promise<Array<FileObject>>
-
-  /** List the contents of a directory */
-  static ls(directory: DirectoryObject): Promise<DirectoryListing>
-
-  /** Read the content of a file */
-  static readFile(fileObject: FileObject): Promise<string>
-
-  /** Write content to a file */
-  static writeFile(fileObject: FileObject, content: string): Promise<void>
-
-  /** Load an object from JSON or YAML file */
-  static loadDataFile(fileObject: FileObject): Promise<any>
-
-  /** Ensure a directory exists, creating it if necessary */
-  static assureDirectory(dirObject: DirectoryObject, options?: any): Promise<boolean>
-
-  /** Compute relative path between two file system objects */
-  static relativeOrAbsolutePath(from: FileObject | DirectoryObject, to: FileObject | DirectoryObject): string
-
-  /** Merge two paths by finding overlapping segments and combining them efficiently */
-  static mergeOverlappingPaths(path1: string, path2: string, sep?: string): string
-
-  /** Resolve a path relative to another path using various strategies. Handles absolute paths, relative navigation, and overlap-based merging */
-  static resolvePath(fromPath: string, toPath: string): string
-}