@gesslar/toolkit 3.42.0 → 4.1.0

package/src/node/lib/FileObject.js

@@ -4,14 +4,13 @@
  * resolution and existence checks.
  */
 
-import JSON5 from "json5"
+import {Buffer} from "node:buffer"
 import fs from "node:fs/promises"
-import YAML from "yaml"
 import {URL} from "node:url"
-import {Buffer} from "node:buffer"
 import {inspect} from "node:util"
 
-import Data from "../../browser/lib/Data.js"
+import Cache from "./Cache.js"
+import Data from "./Data.js"
 import DirectoryObject from "./DirectoryObject.js"
 import FS from "./FileSystem.js"
 import Sass from "./Sass.js"
@@ -33,19 +32,6 @@ 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}
    * @property {string|null} supplied - User-supplied path
@@ -70,6 +56,8 @@ export default class FileObject extends FS {
     real: null,
   })
 
+  #cache = null
+
   /**
    * Constructs a FileObject instance.
    *
@@ -162,6 +150,7 @@ export default class FileObject extends FS {
       extension: this.extension,
       isFile: this.isFile,
       parentPath: this.parentPath,
+      cached: this.cached
     }
   }
 
@@ -377,17 +366,74 @@ export default class FileObject extends FS {
     }
   }
 
+  /**
+   * Whether this FileObject has an active cache attached.
+   *
+   * @returns {boolean} True if a Cache instance is attached
+   */
+  get cached() {
+    return Data.isType(this.#cache, "Cache")
+  }
+
+  /**
+   * Attaches a Cache instance to this FileObject for caching read and
+   * loadData results. If no cache is provided, a new Cache is created.
+   *
+   * @param {Cache} [cache] - The Cache instance to attach
+   * @returns {FileObject} This FileObject for chaining
+   * @throws {Sass} If a cache is already attached
+   */
+  withCache(cache) {
+    Valid.type(cache, "Undefined|Cache")
+    Valid.assert(!this.#cache, "Cache already set. Remove the cache before re-assigning.")
+
+    cache ??= new Cache()
+
+    this.#cache = cache
+
+    return this
+  }
+
+  /**
+   * Removes the attached cache, clearing any cached data for this file first.
+   *
+   * @returns {FileObject} This FileObject for chaining
+   */
+  removeCache() {
+    this.resetCache()
+    this.#cache = null
+
+    return this
+  }
+
+  /**
+   * Clears cached data for this file without removing the cache itself.
+   *
+   * @returns {FileObject} This FileObject for chaining
+   */
+  resetCache() {
+    this.#cache?.resetCache(this)
+
+    return this
+  }
+
   /**
    * Reads the content of a file asynchronously.
    *
-   * @param {string} [encoding] - The encoding to read the file as.
+   * @param {object} [options] - Read options
+   * @param {string} [options.encoding="utf8"] - The encoding to read the file as
+   * @param {boolean} [options.skipCache=false] - If true, bypass the cache
    * @returns {Promise<string>} The file contents
    */
-  async read(encoding="utf8") {
+  async read({encoding="utf8", skipCache=false} = {}) {
     const filePath = this.path
 
+    if(this.#cache && skipCache === false)
+      return await this.#cache.loadFromCache(
+        this, {encoding})
+
     if(!(await this.exists))
-      throw Sass.new(`No such file '${filePath}'`)
+      throw Sass.new(`No such file '${this}'`)
 
     return await fs.readFile(filePath, encoding)
   }
@@ -419,7 +465,7 @@ export default class FileObject extends FS {
    *
    * @param {string} content - The content to write
    * @param {string} [encoding] - The encoding in which to write (default: "utf8")
-   * @returns {Promise<void>}
+   * @returns {Promise<undefined>}
    * @throws {Sass} If the file URL is invalid or the parent directory doesn't exist
    * @example
    * const file = new FileObject('./output/data.json')
@@ -444,7 +490,7 @@ export default class FileObject extends FS {
    * Supports ArrayBuffer, TypedArrays (Uint8Array, etc.), Blob, and Node Buffer types.
    *
    * @param {ArrayBuffer|Blob|Buffer} data - The binary data to write
-   * @returns {Promise<void>}
+   * @returns {Promise<undefined>}
    * @throws {Sass} If the file URL is invalid
    * @throws {Sass} If the parent directory doesn't exist
    * @throws {Sass} If the data is not a valid binary type
@@ -471,44 +517,34 @@ export default class FileObject extends FS {
   }
 
   /**
-   * Loads an object from JSON or YAML file.
-   * Attempts to parse content as JSON5 first, then falls back to YAML if specified.
+   * Loads an object from JSON or YAML file. Attempts to parse content as JSON5
+   * first, then falls back to YAML if specified.
    *
-   * @param {string} [type] - The expected type of data to parse ("json", "json5", "yaml", or "any")
-   * @param {string} [encoding] - The encoding to read the file as (default: "utf8")
+   * @param {object} [options] - Load options
+   * @param {string} [options.type="any"] - The expected type of data to parse ("json", "json5", "yaml", or "any")
+   * @param {string} [options.encoding="utf8"] - The encoding to read the file as
+   * @param {boolean} [options.skipCache=false] - If true, bypass the cache
    * @returns {Promise<unknown>} The parsed data object
    * @throws {Sass} If the content cannot be parsed or type is unsupported
    * @example
    * const configFile = new FileObject('./config.json5')
-   * const config = await configFile.loadData('json5')
+   * const config = await configFile.loadData({type: 'json5'})
    *
    * // Auto-detect format
-   * const data = await configFile.loadData('any')
-   */
-  async loadData(type="any", encoding="utf8") {
-    const content = await this.read(encoding)
-    const normalizedType = type.toLowerCase()
-    const toTry = {
-      json5: [JSON5],
-      json: [JSON5],
-      yaml: [YAML],
-      any: [JSON5,YAML]
-    }[normalizedType]
-
-    if(!toTry)
-      throw Sass.new(`Unsupported data type '${type}'. Supported types: json, json5, yaml.`)
-
-    for(const format of toTry) {
-      try {
-        const result = format.parse(content)
-
-        return result
-      } catch {
-        // nothing to see here
-      }
-    }
+   * const data = await configFile.loadData()
+   */
+  async loadData({type="any", encoding="utf8", skipCache=false} = {}) {
+    if(this.#cache && skipCache === false)
+      return await this.#cache.loadDataFromCache(
+        this, {encoding, type})
+
+    if(!(await this.exists))
+      throw Sass.new(`No such file '${this}'`)
+
+    const content = await this.read({encoding, skipCache})
+    const result = Data.textAsData(content, type)
 
-    throw Sass.new(`Content is neither valid JSON5 nor valid YAML:\n'${this.path}'`)
+    return result
   }
 
   /**
@@ -610,7 +646,7 @@ export default class FileObject extends FS {
   /**
    * Deletes the file from the filesystem.
    *
-   * @returns {Promise<void>} Resolves when file is deleted
+   * @returns {Promise<undefined>} Resolves when file is deleted
    * @throws {Sass} If the file URL is invalid
    * @throws {Sass} If the file does not exist
    * @example

package/src/node/lib/FileSystem.js

@@ -11,12 +11,14 @@
 import path from "node:path"
 import url from "node:url"
 
+import Collection from "../../browser/lib/Collection.js"
 import Data from "../../browser/lib/Data.js"
+import Glog from "./Glog.js"
 import Valid from "./Valid.js"
-import Collection from "../../browser/lib/Collection.js"
+import Watcher from "./Watcher.js"
 
 /**
- * @import {Sass} from "./Sass.js"
+ * @import Sass from "./Sass.js"
  */
 
 const fdTypes = Object.freeze(["file", "directory"])
@@ -33,6 +35,8 @@ export default class FileSystem {
   static upperFdTypes = upperFdTypes
   static fdType = fdType
 
+  #watcher = null
+
   /**
    * Compute the relative path from another file or directory to this instance.
    *
@@ -53,6 +57,47 @@ export default class FileSystem {
     return FileSystem.relativeOrAbsolute(fileOrDirectoryObject, this)
   }
 
+  /**
+   * Watch this file or directory for changes.
+   *
+   * @param {object} [options] - Watch options
+   * @param {Function} [options.onChange] - Callback invoked on change
+   * @param {number} [options.debounceMs] - Debounce interval in milliseconds
+   * @param {boolean} [options.persistent] - Keep the process alive while watching
+   * @returns {Promise<undefined>}
+   */
+  async watch(options={}) {
+    Valid.type(options, "Object")
+
+    const localOptions = Collection.cloneObject(options)
+
+    const {onChange} = localOptions ?? {}
+    Valid.type(onChange, "Undefined|Function")
+
+    delete localOptions.onChange
+
+    this.stopWatching()
+
+    this.#watcher = new Watcher()
+
+    await this.#watcher.watch(this, Object.assign({},
+      localOptions,
+      {
+        onChange: onChange ?? (() => {
+          Glog(`${this} changed somehow.`)
+        })
+      }
+    ))
+  }
+
+  /**
+   * Stop watching this file or directory for changes.
+   */
+  stopWatching() {
+    this.#watcher?.stopWatching()
+    this.#watcher = null
+  }
+
   /**
    * Fix slashes in a path
    *

package/src/node/lib/Font.js

@@ -11,7 +11,7 @@ import DirectoryObject from "./DirectoryObject.js"
 import FS from "./FileSystem.js"
 
 /**
- * @import {FileObject} from "./FileObject.js"
+ * @import FileObject from "./FileObject.js"
  */
 
 const execFile = promisify(child_process.execFile)

package/src/node/lib/Glog.js

@@ -11,12 +11,24 @@
  * 5. Traditional logger: logger.debug("message", level)
  */
 
+import {createRequire} from "node:module"
+
 import c from "@gesslar/colours"
 
 import Data from "../../browser/lib/Data.js"
 import Term from "./Term.js"
 import Util from "../../browser/lib/Util.js"
 
+// Auto-detect VS Code extension environment
+let vscodeApi = null
+try {
+  const _require = createRequire(import.meta.url)
+
+  vscodeApi = _require("vscode")
+} catch {
+  // Not in a VS Code extension environment
+}
+
 /**
  * Default colour configuration for logger output using @gesslar/colours format
  *
@@ -61,16 +73,6 @@ export const logSymbols = {
   success: "✓"
 }
 
-// Set up convenient aliases for common log colours
-c.alias.set("debug", "{F033}")
-c.alias.set("info", "{F036}")
-c.alias.set("warn", "{F214}")
-c.alias.set("error", "{F196}")
-c.alias.set("success", "{F046}")
-c.alias.set("muted", "{F244}")
-c.alias.set("bold", "{<B}")
-c.alias.set("dim", "{<D}")
-
 class Glog {
   // Static properties (for global usage)
   static logLevel = 0
@@ -90,9 +92,9 @@ class Glog {
   #tagsAsStrings = false
   #displayName = true
   #symbols = null
-  #vscodeError = null
-  #vscodeWarn = null
-  #vscodeInfo = null
+  #vscodeWindow = null
+  #vscodeApi = null
+  #outputChannel = null
 
   /**
    * Create a new Glog logger instance with optional configuration
@@ -107,23 +109,18 @@ class Glog {
    * @param {boolean} [options.stackTrace=false] - Enable stack trace extraction
    * @param {boolean} [options.tagsAsStrings=false] - Use string tags instead of symbols
    * @param {boolean} [options.displayName=true] - Display logger name in output
-   * @param {string} [options.env] - Environment mode ("extension" for VSCode integration)
+   * @param {object} [options.vscode] - VS Code API object (auto-detected if not provided)
    */
   constructor(options = {}) {
     this.setOptions(options)
     this.constructor.name = "Glog"
 
-    // VSCode integration if specified
-    if(options.env === "extension") {
-      try {
-        const vscode = require("vscode")
+    // VSCode integration - prefer passed-in vscode, fall back to auto-detected
+    const vsapi = options.vscode ?? vscodeApi
 
-        this.#vscodeError = vscode.window.showErrorMessage
-        this.#vscodeWarn = vscode.window.showWarningMessage
-        this.#vscodeInfo = vscode.window.showInformationMessage
-      } catch {
-        // VSCode not available, ignore
-      }
+    if(vsapi) {
+      this.#vscodeApi = vsapi
+      this.#vscodeWindow = vsapi.window
     }
   }
 
@@ -514,6 +511,23 @@ class Glog {
     }
   }
 
+  get #channel() {
+    if(!this.#outputChannel && this.#vscodeApi) {
+      const name = this.#name || "Log"
+
+      this.#outputChannel = this.#vscodeApi.window.createOutputChannel(name)
+    }
+
+    return this.#outputChannel
+  }
+
+  #appendToChannel(level, message, ...arg) {
+    const timestamp = new Date().toISOString()
+    const parts = [timestamp, `[${level.toUpperCase()}]`, message, ...arg].join(" ")
+
+    this.#channel?.appendLine(parts)
+  }
+
   #compose(level, message, debugLevel = 0) {
     const colours = this.#colours || Glog.colours || loggerColours
     const name = this.#name || Glog.name || "Log"
@@ -603,8 +617,10 @@ class Glog {
 
     const currentLevel = this.#logLevel || Glog.logLevel
 
-    if(currentLevel > 0 && level <= currentLevel)
+    if(currentLevel > 0 && level <= currentLevel) {
       Term.debug(this.#compose("debug", message, level), ...arg)
+      this.#appendToChannel("debug", message, ...arg)
+    }
   }
 
   /**
@@ -615,7 +631,8 @@ class Glog {
    */
   info(message, ...arg) {
     Term.info(this.#compose("info", message), ...arg)
-    this.#vscodeInfo?.(JSON.stringify(message))
+    this.#appendToChannel("info", message, ...arg)
+    this.#vscodeWindow?.showInformationMessage(message)
   }
 
   /**
@@ -626,7 +643,8 @@ class Glog {
    */
   warn(message, ...arg) {
     Term.warn(this.#compose("warn", message), ...arg)
-    this.#vscodeWarn?.(JSON.stringify(message))
+    this.#appendToChannel("warn", message, ...arg)
+    this.#vscodeWindow?.showWarningMessage(message)
   }
 
   /**
@@ -637,7 +655,8 @@ class Glog {
    */
   error(message, ...arg) {
     Term.error(this.#compose("error", message), ...arg)
-    this.#vscodeError?.(JSON.stringify(message))
+    this.#appendToChannel("error", message, ...arg)
+    this.#vscodeWindow?.showErrorMessage(message)
   }
 
   /**

package/src/node/lib/Notify.js

@@ -31,7 +31,7 @@ export class Notify {
    *
    * @param {string} type - Event name to dispatch.
    * @param {unknown} [payload] - Data to send with the event.
-   * @returns {void}
+   * @returns {undefined}
    */
   emit(type, payload=undefined) {
     Valid.type(type, "String", {allowEmpty: false})
@@ -46,7 +46,7 @@ export class Notify {
    *
    * @param {string} type - Event name to dispatch.
    * @param {unknown} [payload] - Data to send with the event.
-   * @returns {Promise<void>} Resolves when all listeners have completed.
+   * @returns {Promise<undefined>} Resolves when all listeners have completed.
    */
   async asyncEmit(type, payload) {
     Valid.type(type, "String", {allowEmpty: false})
@@ -74,10 +74,10 @@ export class Notify {
    * Registers a listener for the given event type.
    *
    * @param {string} type - Event name to listen for.
-   * @param {(payload: unknown) => void} handler - Listener callback.
+   * @param {(payload: unknown) => undefined} handler - Listener callback.
    * @param {EventEmitter} [emitter] - The EventEmitter to attach to. Default is internal emitter.
    * @param {NotifyEventOptions} [options] - Options for the listener.
-   * @returns {() => void} Dispose function to unregister the handler.
+   * @returns {() => undefined} Dispose function to unregister the handler.
    */
   on(type, handler, emitter=this.#emitter, options=undefined) {
     Valid.type(type, "String", {allowEmpty: false})
@@ -96,9 +96,9 @@ export class Notify {
    * Removes a previously registered listener for the given event type.
    *
    * @param {string} type - Event name to remove.
-   * @param {(payload: unknown) => void} handler - Listener callback to detach.
+   * @param {(payload: unknown) => undefined} handler - Listener callback to detach.
    * @param {EventEmitter} [emitter] - The EventEmitter from which to remove. Default is internal emitter.
-   * @returns {void}
+   * @returns {undefined}
    */
   off(type, handler, emitter=this.#emitter) {
     Valid.type(type, "String", {allowEmpty: false})

package/src/node/lib/Sass.js

@@ -24,20 +24,17 @@ export default class Sass extends BrowserSass {
    * Optionally includes detailed stack trace information.
    *
    * @param {boolean} [nerdMode] - Whether to include detailed stack trace
-   * @param {boolean} [isNested] - Whether this is a nested error report
    */
-  report(nerdMode=false, isNested=false) {
-    if(isNested)
-      Term.error()
-
+  report(nerdMode=false) {
     Term.group(
+      "\r\n" +
       `${Term.terminalBracket(["error", "Something Went Wrong"])}\n` +
       this.trace.join("\n")
     )
 
     if(nerdMode) {
       Term.error(
-        "\n" +
+        "\r\n" +
         `${Term.terminalBracket(["error", "Nerd Victuals"])}\n` +
         this.#fullBodyMassage(this.stack)
       )

package/src/node/lib/Term.js

@@ -12,22 +12,22 @@ import Sass from "./Sass.js"
 
 c.alias.set("success", "{F035}")
 c.alias.set("info", "{F033}")
-c.alias.set("warn", "{F208}")
-c.alias.set("error", "{F032}")
-c.alias.set("modified", "{F147}")
+c.alias.set("warn", "{F214}")
+c.alias.set("error", "{F124}")
+
+c.alias.set("debug", "{F033}")
+
+c.alias.set("modified", "{F099}")
+
+c.alias.set("muted", "{F244}")
+c.alias.set("bold", "{<B}")
+c.alias.set("dim", "{<D}")
 
 /**
  * Terminal output utilities with ANSI colour support.
  *
  * Provides console logging wrappers, cursor control, and formatted message
  * output with colour styling via `@gesslar/colours`.
- *
- * Predefined colour aliases:
- * - `success` - green (F035)
- * - `info` - blue (F033)
- * - `warn` - orange (F208)
- * - `error` - red (F032)
- * - `modified` - purple (F147)
  */
 export default class Term {
   static #cache = new Map()
@@ -230,7 +230,7 @@ export default class Term {
    * @param {string | Array<string | [string, string]>} args - Message or segments.
    * @param {object} [options] - Behaviour flags.
    * @param {boolean} options.silent - When true, suppress output.
-   * @returns {void}
+   * @returns {undefined}
    */
   static status(args, {silent=false} = {}) {
     if(silent)

package/src/node/lib/Util.js

@@ -65,7 +65,7 @@ export default class Util extends BrowserUtil {
    * @param {object} emitter - The emitter object (already validated)
    * @param {string} event - The event name to emit
    * @param {...unknown} args - Arguments to pass to event listeners
-   * @returns {Promise<void>} Resolves when all listeners have completed
+   * @returns {Promise<undefined>} Resolves when all listeners have completed
    */
   static async #performAsyncEmit(emitter, event, ...args) {
     const listeners = emitter.listeners(event)
@@ -97,7 +97,7 @@ export default class Util extends BrowserUtil {
    * @param {EventEmitter} emitter - The EventEmitter instance to emit on
    * @param {string} event - The event name to emit
    * @param {...unknown} args - Arguments to pass to event listeners
-   * @returns {Promise<void>} Resolves when all listeners have completed
+   * @returns {Promise<undefined>} Resolves when all listeners have completed
    */
   static async asyncEmit(emitter, event, ...args) {
     try {
@@ -124,7 +124,7 @@ export default class Util extends BrowserUtil {
    * @param {object} emitter - Any object with EventEmitter-like interface
    * @param {string} event - The event name to emit
    * @param {...unknown} args - Arguments to pass to event listeners
-   * @returns {Promise<void>} Resolves when all listeners have completed, but no grapes.
+   * @returns {Promise<undefined>} Resolves when all listeners have completed, but no grapes.
    */
   static async asyncEmitQuack(emitter, event, ...args) {
     try {

package/src/node/lib/Valid.js

@@ -51,17 +51,14 @@ export default class Valid {
    *                         met (optional)
    */
   static assert(condition, message, arg = null) {
-    if(!Data.isType(condition, "boolean")) {
+    if(!Data.isType(condition, "boolean"))
       throw Sass.new(`Condition must be a boolean, got ${condition}`)
-    }
 
-    if(!Data.isType(message, "string")) {
+    if(!Data.isType(message, "string"))
       throw Sass.new(`Message must be a string, got ${message}`)
-    }
 
-    if(!(arg === null || arg === undefined || typeof arg === "number")) {
+    if(!(arg === null || arg === undefined || typeof arg === "number"))
       throw Sass.new(`Arg must be a number, got ${arg}`)
-    }
 
     if(!condition)
       throw Sass.new(`${message}${arg ? `: ${arg}` : ""}`)