@gesslar/toolkit 0.0.13 → 0.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gesslar/toolkit",
-  "version": "0.0.13",
+  "version": "0.1.1",
   "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",
@@ -66,8 +59,6 @@
     "@typescript-eslint/eslint-plugin": "^8.44.0",
     "@typescript-eslint/parser": "^8.44.0",
     "eslint": "^9.36.0",
-    "eslint-plugin-jsdoc": "^60.1.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 FS} from "./lib/FS.js"
+export {default as FS, fdType, upperFdTypes, fdTypes} from "./lib/FS.js"
 
 // Utility classes
 export {default as Cache} from "./lib/Cache.js"
@@ -9,6 +9,6 @@ export {default as Data} from "./lib/Data.js"
 export {default as Glog} from "./lib/Glog.js"
 export {default as Sass} from "./lib/Sass.js"
 export {default as Term} from "./lib/Term.js"
-export {default as Type} from "./lib/Type.js"
+export {default as Type} from "./lib/TypeSpec.js"
 export {default as Util} from "./lib/Util.js"
 export {default as Valid} from "./lib/Valid.js"

package/src/lib/Cache.js

@@ -1,4 +1,3 @@
-import File from "./FS.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

@@ -7,7 +7,7 @@
  */
 
 import Sass from "./Sass.js"
-import TypeSpec from "./Type.js"
+import TypeSpec from "./TypeSpec.js"
 import Valid from "./Valid.js"
 
 export default class Data {
@@ -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

@@ -48,7 +48,6 @@ export default class DirectoryObject extends FS {
     extension: null,
     isFile: false,
     isDirectory: true,
-    directory: null,
   })
 
   /**
@@ -57,7 +56,7 @@ export default class DirectoryObject extends FS {
    * @param {string} directory - The directory path
    */
   constructor(directory) {
-    super(directory)
+    super()
 
     const fixedDir = FS.fixSlashes(directory ?? ".")
     const absolutePath = path.resolve(fixedDir)
@@ -214,10 +213,14 @@ export default class DirectoryObject extends FS {
    * @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 found = await fs.readdir(
+      new URL(directory.uri),
+      {withFileTypes: true}
+    )
+
     const results = await Promise.all(
       found.map(async dirent => {
-        const fullPath = path.join(directory.uri, dirent.name)
+        const fullPath = path.join(directory.path, dirent.name)
         const stat = await fs.stat(fullPath)
 
         return {dirent, stat, fullPath}

package/src/lib/FS.js

@@ -8,6 +8,12 @@ import FileObject from "./FileObject.js"
 import Sass from "./Sass.js"
 import Valid from "./Valid.js"
 
+const fdTypes = Object.freeze(["file", "directory"])
+const upperFdTypes = Object.freeze(fdTypes.map(type => type.toUpperCase()))
+const fdType = Object.freeze(await Data.allocateObject(upperFdTypes, fdTypes))
+
+export {fdType, upperFdTypes, fdTypes}
+
 export default class FS {
   /**
    * Fix slashes in a path
@@ -123,6 +129,7 @@ export default class FS {
    * @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)
 
@@ -131,18 +138,17 @@ export default class FS {
       return path1
     }
 
-    const overlapIndex = from.findLastIndex((curr, index) => {
-      const left = from.at(index)
-      const right = to.at(0)
-
-      return left === right
-    })
+    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)
 
-      return 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
@@ -159,8 +165,8 @@ export default class FS {
    */
   static resolvePath(fromPath, toPath) {
     // Normalize inputs
-    const from = fromPath.trim()
-    const to = toPath.trim()
+    const from = fromPath?.trim() ?? ""
+    const to = toPath?.trim() ?? ""
 
     // Handle empty cases
     if(!from && !to)
@@ -172,16 +178,20 @@ export default class FS {
     if(!to)
       return from
 
+    const normalizedTo = /^\.\//.test(to)
+      ? path.normalize(to)
+      : to
+
     // Strategy 1: If 'to' is absolute, it's standalone
-    if(path.isAbsolute(to))
-      return to
+    if(path.isAbsolute(normalizedTo))
+      return normalizedTo
 
-    // Strategy 2: If 'to' contains relative navigation (./ or ../)
-    if(to.includes("./") || to.includes("../") || to.startsWith(".") || to.startsWith(".."))
-      return path.resolve(from, to)
+    // 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, to)
+    return FS.mergeOverlappingPaths(from, normalizedTo)
   }
 }

package/src/lib/FileObject.js

@@ -32,6 +32,19 @@ import Valid from "./Valid.js"
  */
 
 export default class FileObject extends FS {
+  /**
+   * Configuration mapping data types to their respective parser modules for loadData method.
+   * Each parser module must have a .parse() method that accepts a string and returns parsed data.
+   *
+   * @type {{[key: string]: Array<typeof JSON5 | typeof YAML>}}
+   */
+  static dataLoaderConfig = Object.freeze({
+    json5: [JSON5],
+    json: [JSON5],
+    yaml: [YAML],
+    any: [JSON5, YAML]
+  })
+
   /**
    * @type {object}
    * @private
@@ -64,18 +77,23 @@ export default class FileObject extends FS {
    * @param {DirectoryObject|string|null} [directory] - The parent directory (object or string)
    */
   constructor(fileName, directory=null) {
-    super(fileName, directory)
+    super()
+
+    if(!fileName || typeof fileName !== "string" || fileName.length === 0) {
+      throw Sass.new("fileName must be a non-empty string")
+    }
 
     const fixedFile = FS.fixSlashes(fileName)
 
     const {dir,base,ext} = this.#deconstructFilenameToParts(fixedFile)
 
-    if(!directory)
+    if(!directory) {
       directory = new DirectoryObject(dir)
+    } else if(typeof directory === "string") {
+      directory = new DirectoryObject(directory)
+    }
 
-    const final = path.isAbsolute(fixedFile)
-      ? fixedFile
-      : path.resolve(directory?.path ?? ".", fixedFile)
+    const final = FS.resolvePath(directory?.path ?? ".", fixedFile)
 
     const resolved = final
     const fileUri = FS.pathToUri(resolved)
@@ -99,6 +117,9 @@ export default class FileObject extends FS {
    *
    * @returns {string} string representation of the FileObject
    */
+  toString() {
+    return `[FileObject: ${this.path}]`
+  }
 
   /**
    * Returns a JSON representation of the FileObject.
@@ -360,7 +381,7 @@ export default class FileObject extends FS {
    *
    * @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.
+   * @returns {Promise<unknown>} The parsed data object.
    */
   async loadData(type="any", encoding="utf8") {
     const content = await this.read(encoding)
@@ -371,7 +392,11 @@ export default class FileObject extends FS {
       any: [JSON5,YAML]
     }[type.toLowerCase()]
 
-    for(const [format] of toTry) {
+    if(!toTry) {
+      throw Sass.new(`Unsupported data type '${type}'. Supported types: json, json5, yaml, any`)
+    }
+
+    for(const format of toTry) {
       try {
         const result = format.parse(content)
 

package/src/lib/Glog.js

@@ -21,9 +21,9 @@ import console from "node:console"
  */
 class Glog {
   /** @type {number} Current log level threshold (0-5) */
-  logLevel = 0
+  static logLevel = 0
   /** @type {string} Prefix to prepend to all log messages */
-  logPrefix = ""
+  static logPrefix = ""
 
   /**
    * Sets the log prefix for all subsequent log messages.
@@ -39,7 +39,7 @@ class Glog {
   static setLogPrefix(prefix) {
     this.logPrefix = prefix
 
-    return Glog
+    return this
   }
 
   /**
@@ -57,7 +57,7 @@ class Glog {
   static setLogLevel(level) {
     this.logLevel = Data.clamp(level, 0, 5)
 
-    return Glog
+    return this
   }
 
   /**
@@ -75,11 +75,11 @@ class Glog {
     let level, rest
 
     if(args.length === 0) {
-      ;[level=0, rest=[""]] = null
+      ;[level=0, rest=[""]] = []
     } else if(args.length === 1) {
       ;[rest, level=0] = [args, 0]
     } else {
-      ;[level, ...rest] = args
+      ;[level, ...rest] = typeof args[0] === "number" ? args : [0, ...args]
     }
 
     if(level > this.logLevel)
@@ -123,10 +123,18 @@ class Glog {
 // Wrap the class in a proxy
 export default new Proxy(Glog, {
   apply(target, thisArg, argumentsList) {
-    // When called as function: MyClass(things, and, stuff)
+    // When called as function: call execute method internally
     return target.execute(...argumentsList)
   },
   construct(target, argumentsList) {
     return new target(...argumentsList)
+  },
+  get(target, prop) {
+    // Hide execute method from public API
+    if(prop === "execute") {
+      return undefined
+    }
+
+    return target[prop]
   }
 })

package/src/lib/{Type.js → TypeSpec.js}

@@ -156,20 +156,33 @@ export default class TypeSpec {
     const matchingTypeSpec = this.filter(spec => {
       const {typeName: allowedType, array: allowedArray} = spec
 
-      if(valueType === allowedType && !isArray && !allowedArray)
-        return !allowEmpty ? !empty : true
+      // Handle non-array values
+      if(!isArray && !allowedArray) {
+        if(valueType === allowedType)
+          return allowEmpty || !empty
 
+        return false
+      }
+
+      // Handle array values
       if(isArray) {
-        if(allowedType === "array")
-          if(!allowedArray)
-            return true
+        // Special case for generic "array" type
+        if(allowedType === "array" && !allowedArray)
+          return allowEmpty || !empty
+
+        // Must be an array type specification
+        if(!allowedArray)
+          return false
 
+        // Handle empty arrays
         if(empty)
-          if(allowEmpty)
-            return true
+          return allowEmpty
 
+        // Check if array elements match the required type
         return Data.isArrayUniform(value, allowedType)
       }
+
+      return false
     })
 
     return matchingTypeSpec.length > 0

package/src/lib/Util.js

@@ -98,7 +98,7 @@ export default class Util {
           .reduce((acc, curr) => acc.sign === "--" ? acc : curr, {})
           ?.option
       })
-      .filter(Boolean)
+      .filter(option => option && /^[a-zA-Z0-9]/.test(option)) // Filter out options that don't start with alphanumeric
   }
 
   /**
@@ -184,6 +184,11 @@ export default class Util {
     } catch(error) {
       const argsDesc = args.length > 0 ? `with arguments: ${args.map(String).join(", ")}` : "with no arguments"
 
+      // If it's already a Sass error, just re-throw to avoid double-wrapping
+      if(error instanceof Sass) {
+        throw error
+      }
+
       throw Sass.new(
         `Processing '${event}' event ${argsDesc}.`,
         error
@@ -214,6 +219,11 @@ export default class Util {
     } catch(error) {
       const argsDesc = args.length > 0 ? `with arguments: ${args.map(String).join(", ")}` : "with no arguments"
 
+      // If it's already a Sass error, just re-throw to avoid double-wrapping
+      if(error instanceof Sass) {
+        throw error
+      }
+
       throw Sass.new(
         `Processing '${event}' event ${argsDesc}.`,
         error

package/src/types/Cache.d.ts

@@ -24,7 +24,7 @@ declare class Cache {
    * @returns The parsed file data (JSON5 or YAML)
    * @throws If the file cannot be found or accessed
    */
-  loadCachedData(fileObject: FileObject): Promise<object>
+  loadCachedData(fileObject: FileObject): Promise<unknown>
 }
 
 export default Cache

package/src/types/FS.d.ts

@@ -29,3 +29,18 @@ export default class FS {
   /** 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
 }
+
+/**
+ * File descriptor types as lowercase strings
+ */
+export const fdTypes: readonly ["file", "directory"]
+
+/**
+ * File descriptor types as uppercase strings
+ */
+export const upperFdTypes: readonly ["FILE", "DIRECTORY"]
+
+/**
+ * Mapping from uppercase file descriptor types to lowercase
+ */
+export const fdType: Readonly<Record<"FILE" | "DIRECTORY", "file" | "directory">>

package/src/types/FileObject.d.ts

@@ -3,6 +3,14 @@
 import DirectoryObject from './DirectoryObject.js'
 import FS from './FS.js'
 
+/**
+ * Configuration for data loading parsers in loadData method.
+ * Maps supported data types to their respective parser functions.
+ */
+export interface DataLoaderConfig {
+  [type: string]: Array<{ parse: (content: string) => unknown }>
+}
+
 /**
  * FileObject encapsulates metadata and operations for a file, providing intelligent
  * path resolution, metadata extraction, and file system operations. This class serves
@@ -101,6 +109,12 @@ import FS from './FS.js'
  * file operations.
  */
 export default class FileObject extends FS {
+  /**
+   * Configuration for data parsing in the loadData method.
+   * Maps data type names to arrays of parser functions.
+   */
+  static readonly dataLoaderConfig: DataLoaderConfig
+
   /**
    * Create a new FileObject instance with intelligent path resolution.
    *
@@ -311,5 +325,5 @@ export default class FileObject extends FS {
   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>
+  loadData(type?: 'json' | 'json5' | 'yaml' | 'any', encoding?: string): Promise<unknown>
 }

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 FS } from './FS.js'
+export { default as FS, fdType, upperFdTypes, fdTypes } from './FS.js'
 
 // Utility classes
 export { default as Cache } from './Cache.js'