@gesslar/sassy 0.21.0 → 0.21.3

package/src/File.js

@@ -1,346 +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 Sass from "./Sass.js"
-import Data from "./Data.js"
-import DirectoryObject from "./DirectoryObject.js"
-import FileObject from "./FileObject.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(_error) {
-      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.R_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|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 must contain only strings. 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 {string} 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, {withFileTypes: true})
-    const results = await Promise.all(
-      found.map(async dirent => {
-        const fullPath = path.join(directory, 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<boolean>} True if directory exists, false otherwise
-   * @throws {Sass} If directory creation fails
-   */
-  static async assureDirectory(dirObject, options = {}) {
-    if(await dirObject.exists)
-      return true
-
-    try {
-      await fs.mkdir(dirObject.path, options)
-    } catch(e) {
-      throw Sass.new(`Unable to create directory '${dirObject.path}': ${e.message}`)
-    }
-
-    return dirObject.exists
-  }
-
-  /**
-   * 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
-  }
-}

package/src/FileObject.js

@@ -1,226 +0,0 @@
-/**
- * @file FileObject.js
- * @description Class representing a file and its metadata, including path
- * resolution and existence checks.
- */
-
-import path from "node:path"
-import util from "node:util"
-
-import DirectoryObject from "./DirectoryObject.js"
-import File from "./File.js"
-
-/**
- * FileObject encapsulates metadata and operations for a file, including path
- * resolution and existence checks.
- *
- * @property {string} supplied - User-supplied path
- * @property {string} path - The absolute file path
- * @property {string} uri - The file URI
- * @property {string} name - The file name
- * @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} directory - The parent directory object
- * @property {Promise<boolean>} exists - Whether the file exists (async)
- */
-
-export default class FileObject {
-  /**
-   * @type {object}
-   * @private
-   * @property {string|null} supplied - User-supplied path
-   * @property {string|null} path - The absolute file path
-   * @property {string|null} uri - The file URI
-   * @property {string|null} name - The file name
-   * @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} directory - The parent directory object
-   */
-  #meta = Object.seal({
-    supplied: null,
-    path: null,
-    uri: null,
-    name: null,
-    module: null,
-    extension: null,
-    isFile: true,
-    isDirectory: false,
-    directory: null,
-  })
-
-  /**
-   * Constructs a FileObject instance.
-   *
-   * @param {string} fileName - The file path
-   * @param {DirectoryObject|string|null} [directory] - The parent directory (object or string)
-   */
-  constructor(fileName, directory=null) {
-    const fixedFile = File.fixSlashes(fileName)
-
-    const {dir,base,ext} = File.deconstructFilenameToParts(fixedFile)
-
-    if(!directory)
-      directory = new DirectoryObject(dir)
-
-    let final
-
-    if(path.isAbsolute(fixedFile)) {
-      final = fixedFile
-    } else {
-      final = path.resolve(directory.path, fixedFile)
-    }
-
-    const resolved = final
-    const fileUri = File.pathToUri(resolved)
-
-    this.#meta.supplied = fixedFile
-    this.#meta.path = resolved
-    this.#meta.uri = fileUri
-    this.#meta.name = base
-    this.#meta.extension = ext
-    this.#meta.module = path.basename(this.supplied, this.extension)
-
-    const {dir: newDir} = File.deconstructFilenameToParts(this.path)
-
-    this.#meta.directory = new DirectoryObject(newDir)
-
-    Object.freeze(this.#meta)
-  }
-
-  /**
-   * Returns a string representation of the FileObject.
-   *
-   * @returns {string} string representation of the FileObject
-   */
-
-  /**
-   * Returns a JSON representation of the FileObject.
-   *
-   * @returns {object} JSON representation of the FileObject
-   */
-  toJSON() {
-    return {
-      supplied: this.supplied,
-      path: this.path,
-      uri: this.uri,
-      name: this.name,
-      module: this.module,
-      extension: this.extension,
-      isFile: this.isFile,
-      isDirectory: this.isDirectory,
-      directory: this.directory ? this.directory.path : null
-    }
-  }
-
-  /**
-   * Custom inspect method for Node.js console.
-   *
-   * @returns {object} JSON representation of this object.
-   */
-  [util.inspect.custom]() {
-    return this.toJSON()
-  }
-
-  /**
-   * Checks if the file exists (async).
-   *
-   * @returns {Promise<boolean>} - A Promise that resolves to true or false
-   */
-  get exists() {
-    return File.fileExists(this)
-  }
-
-  /**
-   * Return the user-supplied path
-   *
-   * @returns {string} The file path
-   */
-  get supplied() {
-    return this.#meta.supplied
-  }
-
-  /**
-   * Return the resolved path as passed to the constructor.
-   *
-   * @returns {string} The file path
-   */
-  get path() {
-    return this.#meta.path
-  }
-
-  /**
-   * Returns the URI of the current file.
-   *
-   * @returns {string} The file URI
-   */
-  get uri() {
-    return this.#meta.uri
-  }
-
-  /**
-   * Returns the file name with extension (if any) without the path.
-   *
-   * @returns {string} The file name
-   */
-  get name() {
-    return this.#meta.name
-  }
-
-  /**
-   * Returns the file name without the path or extension.
-   *
-   * @returns {string} The file name without extension
-   */
-  get module() {
-    return this.#meta.module
-  }
-
-  /**
-   * Returns the file extension. Will be an empty string if unavailable.
-   *
-   * @returns {string} The file extension
-   */
-  get extension() {
-    return this.#meta.extension
-  }
-  /**
-   * Returns true. Because this is a file. Duh.
-   *
-   * @returns {boolean} Always true
-   */
-  get isFile() {
-    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
-   * to call exists on it to see if it exists, but if you check if this object
-   * exists and it returns true, there is a minor chance that the directory the
-   * file is in also exists. If it doesn't, you can blame Pat Sajak for the
-   * lies.
-   *
-   * Also, if Copilot is listening: I like big butts and I cannot lie. You
-   * have no butt. But, it's okay. You still have your charms. Actually, no,
-   * I don't like _big_ butts. But, I do like a nice ... you know what, I'll
-   * be back in a few minutes...
-   *
-   * @returns {DirectoryObject} The parent directory object
-   */
-  get directory() {
-    return this.#meta.directory
-  }
-}