@gesslar/toolkit 0.0.12 → 0.1.0

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,20 @@ import File from "./File.js"
  * @property {Promise<boolean>} exists - Whether the file exists (async)
  */
 
-export default class FileObject {
+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
@@ -59,19 +77,26 @@ 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()
 
-    const {dir,base,ext} = File.deconstructFilenameToParts(fixedFile)
+    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 = File.pathToUri(resolved)
+    const fileUri = FS.pathToUri(resolved)
 
     this.#meta.supplied = fixedFile
     this.#meta.path = resolved
@@ -80,7 +105,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)
 
@@ -92,6 +117,9 @@ export default class FileObject {
    *
    * @returns {string} string representation of the FileObject
    */
+  toString() {
+    return `[FileObject: ${this.path}]`
+  }
 
   /**
    * Returns a JSON representation of the FileObject.
@@ -127,7 +155,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 +247,165 @@ 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 {Promise<unknown>} 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()]
+
+    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)
+
+        return result
+      } catch {
+        // nothing to see here
+      }
+    }
+
+    throw Sass.new(`Content is neither valid JSON5 nor valid YAML:\n'${this.path}'`)
+  }
 }

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

@@ -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/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,15 @@
 // Implementation: ../lib/FileObject.js
 
 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
@@ -60,7 +69,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 +108,13 @@ 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 {
+  /**
+   * 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.
    *
@@ -142,8 +157,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 +166,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 +175,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 +185,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 +196,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 +204,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 +216,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 +224,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 +236,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 +244,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 +253,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 +262,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 +277,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 +286,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 +305,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<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 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'