@gesslar/toolkit 0.0.12 → 0.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gesslar/toolkit",
-  "version": "0.0.12",
+  "version": "0.1.0",
   "description": "Get in, bitches, we're going toolkitting.",
   "main": "./src/index.js",
   "type": "module",
@@ -21,18 +21,11 @@
   },
   "scripts": {
     "lint": "eslint src/",
-    "lint:docs": "cd docs && npm run lint",
     "lint:fix": "eslint src/ --fix",
-    "lint:fix:docs": "cd docs && npm run lint:fix",
     "submit": "npm publish --access public",
     "update": "npx npm-check-updates -u && npm install",
-    "test": "node examples/FileSystem/index.js",
-    "docs:dev": "npm run docs:build && cd docs && npm run start",
-    "docs:build": "npm run docs:clean && npm run docs:generate && cd docs && npm run build",
-    "docs:serve": "cd docs && npm run serve",
-    "docs:clean": "cd docs && npm run docs:clean",
-    "docs:generate": "npx typedoc src/types/index.d.ts --out docs/docs/api --plugin typedoc-plugin-markdown --readme none --excludePrivate --excludeProtected --excludeInternal --includeVersion",
-    "docs:install": "cd docs && npm install"
+    "test": "node --test tests/unit/*.test.js",
+    "test:unit": "node --test tests/unit/*.test.js"
   },
   "repository": {
     "type": "git",
@@ -63,11 +56,9 @@
   "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",
-    "typedoc": "^0.28.13",
-    "typedoc-plugin-markdown": "^4.9.0"
+    "eslint-plugin-jsdoc": "^60.1.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,3 @@
-import File from "./File.js"
 import FileObject from "./FileObject.js"
 import Sass from "./Sass.js"
 
@@ -41,11 +40,11 @@ export default class Cache {
    * parallel processing.
    *
    * @param {FileObject} fileObject - The file object to load and cache
-   * @returns {Promise<object>} The parsed file data (JSON5 or YAML)
+   * @returns {Promise<unknown>} The parsed file data (JSON5 or YAML)
    * @throws {Sass} If the file cannot be found or accessed
    */
   async loadCachedData(fileObject) {
-    const lastModified = await File.fileModified(fileObject)
+    const lastModified = await fileObject.modified()
 
     if(lastModified === null)
       throw Sass.new(`Unable to find file '${fileObject.path}'`)
@@ -64,7 +63,7 @@ export default class Cache {
       }
     }
 
-    const data = await File.loadDataFile(fileObject)
+    const data = await fileObject.loadData()
 
     this.#modifiedTimes.set(fileObject.path, lastModified)
     this.#dataCache.set(fileObject.path, data)

package/src/lib/Data.js

@@ -20,6 +20,7 @@ export default class Data {
   static primitives = Object.freeze([
   // Primitives
     "undefined",
+    "null",
     "boolean",
     "number",
     "bigint",
@@ -196,10 +197,18 @@ export default class Data {
     const result = {}
 
     for(const [key, value] of Object.entries(obj)) {
-      if(Data.isType(value, "object"))
+      if(Data.isType(value, "array")) {
+        // Clone arrays by mapping over them
+        result[key] = value.map(item =>
+          Data.isType(item, "object") || Data.isType(item, "array")
+            ? Data.cloneObject(item)
+            : item
+        )
+      } else if(Data.isType(value, "object")) {
         result[key] = Data.cloneObject(value)
-      else
+      } else {
         result[key] = value
+      }
     }
 
     return freeze ? Object.freeze(result) : result
@@ -340,30 +349,16 @@ export default class Data {
       return false
 
     const valueType = Data.typeOf(value)
+    const normalizedType = type.toLowerCase()
 
-    switch(type.toLowerCase()) {
-      case "array":
-        return Array.isArray(value) // Native array check
-      case "string":
-        return valueType === "string"
-      case "boolean":
-        return valueType === "boolean"
+    // Special cases that need extra validation
+    switch(normalizedType) {
       case "number":
         return valueType === "number" && !isNaN(value) // Excludes NaN
       case "object":
-        return value !== null && valueType === "object" && !Array.isArray(value) // Excludes arrays and null
-      case "function":
-        return valueType === "function"
-      case "symbol":
-        return valueType === "symbol" // ES6 Symbol type
-      case "bigint":
-        return valueType === "bigint" // BigInt support
-      case "null":
-        return value === null // Explicit null check
-      case "undefined":
-        return valueType === "undefined" // Explicit undefined check
+        return valueType === "object" && value !== null && !Array.isArray(value) // Excludes arrays and null
       default:
-        return false // Unknown type
+        return valueType === normalizedType
     }
   }
 
@@ -374,7 +369,13 @@ export default class Data {
    * @returns {string} The type of the value
    */
   static typeOf(value) {
-    return Array.isArray(value) ? "array" : typeof value
+    if(value === null)
+      return "null"
+
+    if(Array.isArray(value))
+      return "array"
+
+    return typeof value
   }
 
   /**
@@ -397,11 +398,16 @@ export default class Data {
    * @returns {boolean} Whether the value is empty
    */
   static isEmpty(value, checkForNothing = true) {
-    const type = Data.typeOf(value)
-
     if(checkForNothing && Data.isNothing(value))
       return true
 
+    // When checkForNothing is false, null/undefined should not be treated as empty
+    // They should be processed like regular values
+    if(!checkForNothing && Data.isNothing(value))
+      return false
+
+    const type = Data.typeOf(value)
+
     if(!Data.emptyableTypes.includes(type))
       return false
 
@@ -409,6 +415,7 @@ export default class Data {
       case "array":
         return value.length === 0
       case "object":
+        // null was already handled above, so this should only be real objects
         return Object.keys(value).length === 0
       case "string":
         return value.trim().length === 0

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
@@ -45,7 +48,6 @@ export default class DirectoryObject {
     extension: null,
     isFile: false,
     isDirectory: true,
-    directory: null,
   })
 
   /**
@@ -54,10 +56,12 @@ export default class DirectoryObject {
    * @param {string} directory - The directory path
    */
   constructor(directory) {
-    const fixedDir = File.fixSlashes(directory ?? ".")
+    super()
+
+    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 +116,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 +190,70 @@ 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(
+      new URL(directory.uri),
+      {withFileTypes: true}
+    )
+
+    const results = await Promise.all(
+      found.map(async dirent => {
+        const fullPath = path.join(directory.path, 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,191 @@
+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 isAbsolutePath1 = path.isAbsolute(path1)
+    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 => curr === to.at(0))
+
+    // If overlap is found, slice and join
+    if(overlapIndex !== -1) {
+      const prefix = from.slice(0, overlapIndex)
+      const result = path.join(...prefix, ...to)
+
+      // If original path1 was absolute, ensure result is also absolute
+      return isAbsolutePath1 && !path.isAbsolute(result)
+        ? path.sep + result
+        : result
+    }
+
+    // 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
+
+    const normalizedTo = /^\.\//.test(to)
+      ? path.normalize(to)
+      : to
+
+    // Strategy 1: If 'to' is absolute, it's standalone
+    if(path.isAbsolute(normalizedTo))
+      return normalizedTo
+
+    // Strategy 2: If 'to' contains relative navigation
+    if(to.startsWith("../"))
+      return path.resolve(from, normalizedTo)
+
+    // Strategy 3: Try overlap-based merging, which will default to a basic
+    // join if no overlap
+    return FS.mergeOverlappingPaths(from, normalizedTo)
+  }
+}