@gesslar/toolkit 0.0.2 → 0.0.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gesslar/toolkit",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "description": "Get in, bitches, we're going toolkitting.",
   "main": "./src/index.js",
   "type": "module",

package/src/index.js

@@ -4,8 +4,10 @@ export {default as DirectoryObject} from "./lib/DirectoryObject.js"
 export {default as File} from "./lib/File.js"
 
 // Utility classes
+export {default as Cache} from "./lib/Cache.js"
 export {default as Data} from "./lib/Data.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 Util} from "./lib/Util.js"
 export {default as Valid} from "./lib/Valid.js"

package/src/lib/Cache.js

@@ -0,0 +1,74 @@
+import File from "./File.js"
+import FileObject from "./FileObject.js"
+import Sass from "./Sass.js"
+
+/**
+ * File system cache with automatic invalidation based on modification time.
+ * Provides intelligent caching of parsed JSON5/YAML files with mtime-based
+ * cache invalidation to optimize performance for repeated file access.
+ *
+ * The cache eliminates redundant file reads and parsing when multiple processes
+ * access the same dependency files, while ensuring data freshness through
+ * modification time checking.
+ */
+export default class Cache {
+  /** @type {Map<string, Date>} Map of file paths to last modification times */
+  #modifiedTimes = new Map()
+  /** @type {Map<string, object>} Map of file paths to parsed file data */
+  #dataCache = new Map()
+
+  /**
+   * Removes cached data for a specific file from both time and data maps.
+   * Used when files are modified or when cache consistency needs to be
+   * maintained.
+   *
+   * @private
+   * @param {FileObject} file - The file object to remove from cache
+   * @returns {void}
+   */
+  #cleanup(file) {
+    this.#modifiedTimes.delete(file.path)
+    this.#dataCache.delete(file.path)
+  }
+
+  /**
+   * Loads and caches parsed file data with automatic invalidation based on
+   * modification time.
+   *
+   * Implements a sophisticated caching strategy that checks file modification
+   * times to determine whether cached data is still valid, ensuring data
+   * freshness while optimizing performance for repeated file access during
+   * parallel processing.
+   *
+   * @param {FileObject} fileObject - The file object to load and cache
+   * @returns {Promise<object>} 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)
+
+    if(lastModified === null)
+      throw Sass.new(`Unable to find file '${fileObject.path}'`)
+
+    if(this.#modifiedTimes.has(fileObject.path)) {
+      const lastCached = this.#modifiedTimes.get(fileObject.path)
+
+      if(lastModified > lastCached) {
+        this.#cleanup(fileObject)
+      } else {
+        if(!(this.#dataCache.has(fileObject.path)))
+          this.#cleanup(fileObject)
+        else {
+          return this.#dataCache.get(fileObject.path)
+        }
+      }
+    }
+
+    const data = await File.loadDataFile(fileObject)
+
+    this.#modifiedTimes.set(fileObject.path, lastModified)
+    this.#dataCache.set(fileObject.path, data)
+
+    return data
+  }
+}

package/src/lib/Data.js

@@ -3,8 +3,8 @@
  * Provides comprehensive utilities for working with JavaScript data types and structures.
  */
 
-import TypeSpec from "./Type.js"
 import Sass from "./Sass.js"
+import TypeSpec from "./Type.js"
 import Valid from "./Valid.js"
 
 export default class Data {

package/src/lib/File.js

@@ -11,10 +11,10 @@ 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 Sass from "./Sass.js"
 import Valid from "./Valid.js"
 
 export default class File {
@@ -37,7 +37,7 @@ export default class File {
   static pathToUri(pathName) {
     try {
       return url.pathToFileURL(pathName).href
-    } catch (e) {
+    } catch(e) {
       void e // stfu linter
 
       return pathName
@@ -55,7 +55,7 @@ export default class File {
       await fs.access(file.path, fs.constants.R_OK)
 
       return true
-    } catch (_) {
+    } catch(_) {
       return false
     }
   }
@@ -71,7 +71,7 @@ export default class File {
       await fs.access(file.path, fs.constants.W_OK)
 
       return true
-    } catch (_error) {
+    } catch(_) {
       return false
     }
   }
@@ -84,10 +84,10 @@ export default class File {
    */
   static async fileExists(file) {
     try {
-      await fs.access(file.path, fs.constants.R_OK)
+      await fs.access(file.path, fs.constants.F_OK)
 
       return true
-    } catch (_) {
+    } catch(_) {
       return false
     }
   }
@@ -103,7 +103,7 @@ export default class File {
       const stat = await fs.stat(file.path)
 
       return stat.size
-    } catch (_) {
+    } catch(_) {
       return null
     }
   }
@@ -120,7 +120,7 @@ export default class File {
       const stat = await fs.stat(file.path)
 
       return stat.mtime
-    } catch (_) {
+    } catch(_) {
       return null
     }
   }
@@ -136,7 +136,7 @@ export default class File {
       (await fs.opendir(dirObject.path)).close()
 
       return true
-    } catch (_) {
+    } catch(_) {
       return false
     }
   }
@@ -150,7 +150,7 @@ export default class File {
   static uriToPath(pathName) {
     try {
       return url.fileURLToPath(pathName)
-    } catch (_) {
+    } catch(_) {
       return pathName
     }
   }
@@ -211,11 +211,10 @@ export default class File {
       !globbyArray.length
     )
       throw Sass.new(
-        `Invalid glob pattern: Array must contain only strings. Got ${JSON.stringify(glob)}`,
+        `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))
 
@@ -310,20 +309,18 @@ export default class File {
    * @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
+   * @returns {Promise<void>}
    * @throws {Sass} If directory creation fails
    */
   static async assureDirectory(dirObject, options = {}) {
     if(await dirObject.exists)
-      return true
+      return
 
     try {
       await fs.mkdir(dirObject.path, options)
-    } catch (e) {
+    } catch(e) {
       throw Sass.new(`Unable to create directory '${dirObject.path}': ${e.message}`)
     }
-
-    return dirObject.exists
   }
 
   /**

package/src/lib/FileObject.js

@@ -66,13 +66,9 @@ export default class FileObject {
     if(!directory)
       directory = new DirectoryObject(dir)
 
-    let final
-
-    if(path.isAbsolute(fixedFile)) {
-      final = fixedFile
-    } else {
-      final = path.resolve(directory.path, fixedFile)
-    }
+    const final = path.isAbsolute(fixedFile)
+      ? fixedFile
+      : path.resolve(directory.path, fixedFile)
 
     const resolved = final
     const fileUri = File.pathToUri(resolved)

package/src/lib/Util.js

@@ -0,0 +1,134 @@
+import {createHash} from "node:crypto"
+import {performance} from "node:perf_hooks"
+
+/**
+ * Utility class providing common helper functions for string manipulation,
+ * timing, hashing, and option parsing.
+ */
+export default class Util {
+  /**
+   * Capitalizes the first letter of a string.
+   *
+   * @param {string} text - The text to capitalize
+   * @returns {string} Text with first letter capitalized
+   */
+  static capitalize(text) {
+    return typeof text === "string"
+      && `${text.slice(0,1).toUpperCase()}${text.slice(1)}`
+      || text
+  }
+
+  /**
+   * Measure wall-clock time for an async function.
+   *
+   * @template T
+   * @param {() => Promise<T>} fn - Thunk returning a promise.
+   * @returns {Promise<{result: T, cost: number}>} Object containing result and elapsed ms (number, 1 decimal).
+   */
+  static async time(fn) {
+    const t0 = performance.now()
+    const result = await fn()
+    const cost = Math.round((performance.now() - t0) * 10) / 10
+
+    return {result, cost}
+  }
+
+  /**
+   * Right-align a string inside a fixed width (left pad with spaces).
+   * If the string exceeds width it is returned unchanged.
+   *
+   * @param {string|number} text - Text to align.
+   * @param {number} width - Target field width (default 80).
+   * @returns {string} Padded string.
+   */
+  static rightAlignText(text, width=80) {
+    const work = String(text)
+
+    if(work.length > width)
+      return work
+
+    const diff = width-work.length
+
+    return `${" ".repeat(diff)}${work}`
+  }
+
+  /**
+   * Compute sha256 hash (hex) of the provided string.
+   *
+   * @param {string} s - Input string.
+   * @returns {string} 64-char hexadecimal digest.
+   */
+  static hashOf(s) {
+    return createHash("sha256").update(s).digest("hex")
+  }
+
+  /**
+   * Extracts canonical option names from a Commander-style options object.
+   *
+   * Each key in the input object is a string containing one or more option
+   * forms, separated by commas (e.g. "-w, --watch"). This function splits each
+   * key, trims whitespace, and parses out the long option name (e.g. "watch")
+   * for each entry. If no long option ("--") is present, the short option (e.g.
+   * "v" from "-v") will be included in the result array. If both are present,
+   * the long option is preferred.
+   *
+   * Example:
+   *   generateOptionNames({"-w, --watch": "desc", "-v": "desc"})
+   *   → ["watch", "v"]
+   *
+   * Edge cases:
+   *   - If a key contains only a short option ("-v"), that short name will be
+   *     included in the result.
+   *   - If multiple long options are present, only the first is used.
+   *   - If the option string is malformed, may return undefined for that entry
+   *     (filtered out).
+   *
+   * @param {object} object - Mapping of option strings to descriptions.
+   * @returns {string[]} Array of canonical option names (long preferred, short if no long present).
+   */
+  static generateOptionNames(object) {
+    return Object.keys(object)
+      .map(key => {
+        return key
+          .split(",")
+          .map(o => o.trim())
+          .map(o => o.match(/^(?<sign>--?)(?<option>[\w-]+)/)?.groups ?? {})
+          .reduce((acc, curr) => acc.sign === "--" ? acc : curr, {})
+          ?.option
+      })
+      .filter(Boolean)
+  }
+
+  /**
+   * Asynchronously awaits all promises in parallel.
+   * Wrapper around Promise.all for consistency with other utility methods.
+   *
+   * @param {Promise[]} promises - Array of promises to await
+   * @returns {Promise<unknown[]>} Results of all promises
+   */
+  static async awaitAll(promises) {
+    return await Promise.all(promises)
+  }
+
+  /**
+   * Settles all promises (both fulfilled and rejected) in parallel.
+   * Wrapper around Promise.allSettled for consistency with other utility methods.
+   *
+   * @param {Promise[]} promises - Array of promises to settle
+   * @returns {Promise<Array>} Results of all settled promises with status and value/reason
+   */
+  static async settleAll(promises) {
+    return await Promise.allSettled(promises)
+  }
+
+  /**
+   * Returns the first promise to resolve or reject from an array of promises.
+   * Wrapper around Promise.race for consistency with other utility methods.
+   *
+   * @param {Promise[]} promises - Array of promises to race
+   * @returns {Promise<unknown>} Result of the first settled promise
+   */
+  static async race(promises) {
+    return await Promise.race(promises)
+  }
+}

package/src/types/Cache.d.ts

@@ -0,0 +1,29 @@
+import FileObject from '../lib/FileObject.js'
+
+/**
+ * File system cache for theme compilation data with automatic invalidation.
+ * Provides intelligent caching of parsed JSON5/YAML files with mtime-based
+ * cache invalidation to optimize parallel theme compilation performance.
+ *
+ * The cache eliminates redundant file reads and parsing when multiple themes
+ * import the same dependency files, while ensuring data freshness through
+ * modification time checking.
+ */
+declare class Cache {
+  /**
+   * Loads and caches parsed file data with automatic invalidation based on
+   * modification time.
+   *
+   * Implements a sophisticated caching strategy that checks file modification
+   * times to determine whether cached data is still valid, ensuring data
+   * freshness while optimizing performance for repeated file access during
+   * parallel theme compilation.
+   *
+   * @param fileObject - The file object to load and cache
+   * @returns The parsed file data (JSON5 or YAML)
+   * @throws If the file cannot be found or accessed
+   */
+  loadCachedData(fileObject: FileObject): Promise<object>
+}
+
+export default Cache

package/src/types/Util.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Utility class providing common helper functions for string manipulation,
+ * timing, hashing, and option parsing.
+ */
+declare class Util {
+  /**
+   * Capitalizes the first letter of a string.
+   *
+   * @param text - The text to capitalize
+   * @returns Text with first letter capitalized
+   */
+  static capitalize(text: string): string
+
+  /**
+   * Measure wall-clock time for an async function.
+   *
+   * @template T
+   * @param fn - Thunk returning a promise.
+   * @returns Object containing result and elapsed ms (number, 1 decimal).
+   */
+  static time<T>(fn: () => Promise<T>): Promise<{result: T, cost: number}>
+
+  /**
+   * Right-align a string inside a fixed width (left pad with spaces).
+   * If the string exceeds width it is returned unchanged.
+   *
+   * @param text - Text to align.
+   * @param width - Target field width (default 80).
+   * @returns Padded string.
+   */
+  static rightAlignText(text: string | number, width?: number): string
+
+  /**
+   * Compute sha256 hash (hex) of the provided string.
+   *
+   * @param s - Input string.
+   * @returns 64-char hexadecimal digest.
+   */
+  static hashOf(s: string): string
+
+  /**
+   * Extracts canonical option names from a Commander-style options object.
+   *
+   * Each key in the input object is a string containing one or more option
+   * forms, separated by commas (e.g. "-w, --watch"). This function splits each
+   * key, trims whitespace, and parses out the long option name (e.g. "watch")
+   * for each entry. If no long option ("--") is present, the short option (e.g.
+   * "v" from "-v") will be included in the result array. If both are present,
+   * the long option is preferred.
+   *
+   * @param object - Mapping of option strings to descriptions.
+   * @returns Array of canonical option names (long preferred, short if no long present).
+   */
+  static generateOptionNames(object: Record<string, any>): string[]
+
+  /**
+   * Asynchronously awaits all promises in parallel.
+   * Wrapper around Promise.all for consistency with other utility methods.
+   *
+   * @param promises - Array of promises to await
+   * @returns Results of all promises
+   */
+  static awaitAll<T>(promises: Promise<T>[]): Promise<T[]>
+
+  /**
+   * Settles all promises (both fulfilled and rejected) in parallel.
+   * Wrapper around Promise.allSettled for consistency with other utility methods.
+   *
+   * @param promises - Array of promises to settle
+   * @returns Results of all settled promises with status and value/reason
+   */
+  static settleAll<T>(promises: Promise<T>[]): Promise<PromiseSettledResult<T>[]>
+
+  /**
+   * Returns the first promise to resolve or reject from an array of promises.
+   * Wrapper around Promise.race for consistency with other utility methods.
+   *
+   * @param promises - Array of promises to race
+   * @returns Result of the first settled promise
+   */
+  static race<T>(promises: Promise<T>[]): Promise<T>
+}
+
+export default Util

package/src/types/index.d.ts

@@ -4,10 +4,12 @@ export { default as DirectoryObject } from './DirectoryObject.js'
 export { default as File } from './File.js'
 
 // Utility classes
+export { default as Cache } from './Cache.js'
 export { default as Data } from './Data.js'
 export { default as Sass } from './Sass.js'
 export { default as Term } from './Term.js'
 export { default as Type } from './Type.js'
+export { default as Util } from './Util.js'
 export { default as Valid } from './Valid.js'
 
 // Type exports