@gesslar/toolkit 4.0.0 → 4.1.0

package/README.md

@@ -45,6 +45,7 @@ Includes all browser functionality plus Node.js-specific modules for file I/O, l
 | Term | Terminal formatting and output utilities |
 | Util | General utility functions (Node-enhanced version) |
 | Valid | Validation and assertion methods |
+| Watcher | File and directory change watcher with debounce protection |
 
 
 ## Installation

package/package.json

@@ -5,7 +5,7 @@
     "name": "gesslar",
     "url": "https://gesslar.dev"
   },
-  "version": "4.0.0",
+  "version": "4.1.0",
   "license": "Unlicense",
   "homepage": "https://github.com/gesslar/toolkit#readme",
   "repository": {

package/src/browser/lib/Data.js

@@ -199,11 +199,10 @@ export default class Data {
    * defining the type of a value and whether an array is expected.
    *
    * @param {string} string - The string to parse into a type spec.
-   * @param {TypeSpecOptions} [options] - Additional options for parsing.
-   * @returns {Array<object>} An array of type specs.
+   * @returns {TypeSpec} A new TypeSpec instance.
    */
-  static newTypeSpec(string, options) {
-    return new TypeSpec(string, options)
+  static newTypeSpec(string) {
+    return new TypeSpec(string)
   }
 
   /**
@@ -530,4 +529,5 @@ export default class Data {
              Data.isType(value, "ArrayBuffer|Blob|Buffer")
            )
   }
+
 }

package/src/browser/lib/TypeSpec.js

@@ -9,20 +9,6 @@ import Data from "./Data.js"
 import Sass from "./Sass.js"
 import Util from "./Util.js"
 
-/**
- * Options for creating a new TypeSpec.
- *
- * @typedef {object} TypeSpecOptions
- * @property {string} [delimiter="|"] - The delimiter for union types
- */
-
-/**
- * Options for type validation methods.
- *
- * @typedef {object} TypeValidationOptions
- * @property {boolean} [allowEmpty=true] - Whether empty values are allowed
- */
-
 /**
  * Type specification class for parsing and validating complex type definitions.
  * Supports union types, array types, and validation options.
@@ -34,11 +20,10 @@ export default class TypeSpec {
    * Creates a new TypeSpec instance.
    *
    * @param {string} string - The type specification string (e.g., "string|number", "object[]")
-   * @param {TypeSpecOptions} [options] - Additional parsing options
    */
-  constructor(string, options) {
+  constructor(string) {
     this.#specs = []
-    this.#parse(string, options)
+    this.#parse(string)
     Object.freeze(this.#specs)
     this.specs = this.#specs
     this.length = this.#specs.length
@@ -52,11 +37,21 @@ export default class TypeSpec {
    * @returns {string} The type specification as a string (e.g., "string|number[]")
    */
   toString() {
-    return this.#specs
-      .map(spec => {
-        return `${spec.typeName}${spec.array ? "[]" : ""}`
-      })
-      .join("|")
+    // Reconstruct in parse order, grouping consecutive mixed specs
+    const parts = []
+    const emittedGroups = new Set()
+
+    for(const spec of this.#specs) {
+      if(spec.mixed === false) {
+        parts.push(`${spec.typeName}${spec.array ? "[]" : ""}`)
+      } else if(!emittedGroups.has(spec.mixed)) {
+        emittedGroups.add(spec.mixed)
+        const group = this.#specs.filter(s => s.mixed === spec.mixed)
+        parts.push(`(${group.map(s => s.typeName).join("|")})[]`)
+      }
+    }
+
+    return parts.join("|")
   }
 
   /**
@@ -148,22 +143,30 @@ export default class TypeSpec {
    * Handles array types, union types, and empty value validation.
    *
    * @param {unknown} value - The value to test against the type specifications
-   * @param {TypeValidationOptions} [options] - Validation options
+   * @param {TypeMatchOptions} [options] - Validation options
    * @returns {boolean} True if the value matches any type specification
    */
   matches(value, options) {
     return this.match(value, options).length > 0
   }
 
+  /**
+   * Options that can be passed to {@link TypeSpec.match}
+   *
+   * @typedef {object} TypeMatchOptions
+   * @property {boolean} [allowEmpty=true] - Permit a spec of {@link Data.emptyableTypes} to be empty
+   */
+
   /**
    * Returns matching type specifications for a value.
    *
    * @param {unknown} value - The value to test against the type specifications
-   * @param {TypeValidationOptions} [options] - Validation options
+   * @param {TypeMatchOptions} [options] - Validation options
    * @returns {Array<object>} Array of matching type specifications
    */
-  match(value, options) {
-    const allowEmpty = options?.allowEmpty ?? true
+  match(value, {
+    allowEmpty = true,
+  } = {}) {
 
     // If we have a list of types, because the string was validly parsed, we
     // need to ensure that all of the types that were parsed are valid types in
@@ -179,10 +182,13 @@ export default class TypeSpec {
     // We need to ensure that we match the type and the consistency of the
     // types in an array, if it is an array and an array is allowed.
     const matchingTypeSpec = this.filter(spec => {
+      // Skip mixed specs — they are handled in the grouped-array check below
+      if(spec.mixed !== false)
+        return false
+
       const {typeName: allowedType, array: allowedArray} = spec
-      const empty =
-        Data.emptyableTypes.includes(allowedType) &&
-        Data.isEmpty(value)
+      const empty = Data.emptyableTypes.includes(allowedType)
+        && Data.isEmpty(value)
 
       // Handle non-array values
       if(!isArray && !allowedArray) {
@@ -222,6 +228,41 @@ export default class TypeSpec {
       return false
     })
 
+    // Check mixed-array groups independently. Each group (e.g.,
+    // (String|Number)[] vs (Boolean|Bigint)[]) is validated separately
+    // so that multiple groups don't merge into one.
+    if(isArray) {
+      const mixedSpecs = this.filter(spec => spec.mixed !== false)
+
+      if(mixedSpecs.length) {
+        const empty = Data.isEmpty(value)
+
+        if(empty)
+          return allowEmpty ? [...matchingTypeSpec, ...mixedSpecs] : []
+
+        // Collect unique group IDs
+        const groups = [...new Set(mixedSpecs.map(s => s.mixed))]
+
+        for(const gid of groups) {
+          const groupSpecs = mixedSpecs.filter(s => s.mixed === gid)
+
+          const allMatch = value.every(element => {
+            const elType = Data.typeOf(element)
+
+            return groupSpecs.some(spec => {
+              if(spec.typeName === "Object")
+                return Data.isPlainObject(element)
+
+              return elType === spec.typeName
+            })
+          })
+
+          if(allMatch)
+            return [...matchingTypeSpec, ...groupSpecs]
+        }
+      }
+    }
+
     return matchingTypeSpec
   }
 
@@ -231,29 +272,64 @@ export default class TypeSpec {
    *
    * @private
    * @param {string} string - The type specification string to parse
-   * @param {TypeSpecOptions} [options] - Parsing options
    * @throws {Sass} If the type specification is invalid
    */
-  #parse(string, options={delimiter: "|"}) {
-    const delimiter = options?.delimiter ?? "|"
-    const parts = string.split(delimiter)
+  #parse(string) {
+    const specs = []
+    const groupPattern = /\((\w+(?:\|\w+)*)\)\[\]/g
+
+    // Replace groups with placeholder X to validate structure and
+    // determine parse order
+    const groups = []
+    const stripped = string.replace(groupPattern, (_, inner) => {
+      groups.push(inner)
+
+      return "X"
+    })
+
+    // Validate for malformed delimiters and missing boundaries
+    if(/\|\||^\||\|$/.test(stripped) || /[^|]X|X[^|]/.test(stripped))
+      throw Sass.new(`Invalid type: ${string}`)
+
+    // Parse in order using the stripped template
+    const segments = stripped.split("|")
+    let groupId = 0
+
+    for(const segment of segments) {
+      if(segment === "X") {
+        const currentGroup = groupId++
+        const inner = groups[currentGroup]
 
-    this.#specs = parts.map(part => {
-      const typeMatches = /^(\w+)(\[\])?$/.exec(part)
+        for(const raw of inner.split("|")) {
+          const typeName = Util.capitalize(raw)
+
+          if(!Data.isValidType(typeName))
+            throw Sass.new(`Invalid type: ${raw}`)
+
+          specs.push({typeName, array: true, mixed: currentGroup})
+        }
+
+        continue
+      }
+
+      const typeMatches = /^(\w+)(\[\])?$/.exec(segment)
 
       if(!typeMatches || typeMatches.length !== 3)
-        throw Sass.new(`Invalid type: ${part}`)
+        throw Sass.new(`Invalid type: ${segment}`)
 
       const typeName = Util.capitalize(typeMatches[1])
 
       if(!Data.isValidType(typeName))
         throw Sass.new(`Invalid type: ${typeMatches[1]}`)
 
-      return {
+      specs.push({
         typeName,
         array: typeMatches[2] === "[]",
-      }
-    })
+        mixed: false,
+      })
+    }
+
+    this.#specs = specs
   }
 
   #getTypeLineage(value) {

package/src/node/index.js

@@ -1,6 +1,6 @@
 // Browser-compatible utilities (pure JS)
 export {default as Collection} from "../browser/lib/Collection.js"
-export {default as Data} from "../browser/lib/Data.js"
+export {default as Data} from "./lib/Data.js"
 export {default as Disposer} from "../browser/lib/Disposer.js"
 export {Disposer as DisposerClass} from "../browser/lib/Disposer.js"
 export {default as Promised} from "../browser/lib/Promised.js"
@@ -23,3 +23,4 @@ export {default as Glog} from "./lib/Glog.js"
 export {default as Notify} from "./lib/Notify.js"
 export {Notify as NotifyClass} from "./lib/Notify.js"
 export {default as Term} from "./lib/Term.js"
+export {default as Watcher, OverFlowBehaviour} from "./lib/Watcher.js"

package/src/node/lib/Cache.js

@@ -1,32 +1,97 @@
+import Valid from "../../browser/lib/Valid.js"
+import Data from "./Data.js"
 import Sass from "./Sass.js"
 
+/**
+ * @import FileObject from "./FileObject.js"
+ */
+
+/**
+ * @typedef {"raw" | "structured"} CacheDataType
+ */
+
+/**
+ * @typedef {{modified: Date, raw: string|null, structured: unknown}} CacheData
+ */
+
 /**
  * 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.
+ * 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()
+  /** @type {Map<string, CacheData>} Map of file paths to cached data */
+  #cache = new Map()
 
   /**
-   * Removes cached data for a specific file from both time and data maps.
+   * Removes cached data for a specific file from the #cache map.
    * Used when files are modified or when cache consistency needs to be
    * maintained.
    *
    * @private
-   * @param {import("./FileObject.js").FileObject} file - The file object to remove from cache
-   * @returns {void}
+   * @param {FileObject} file - The file object to remove from cache
+   * @returns {undefined}
    */
   #cleanup(file) {
-    this.#modifiedTimes.delete(file.path)
-    this.#dataCache.delete(file.path)
+    this.#cache.delete(file.path)
+  }
+
+  /**
+   * Internal cache loader that reads raw content via FileObject and
+   * optionally parses it, using mtime-based invalidation to serve cached
+   * results when possible.
+   *
+   * @private
+   * @param {FileObject} fileObject - The file object to load
+   * @param {CacheDataType} kind - Whether to return "raw" text or
+   *   "structured" parsed data
+   * @param {object} [options] - Options forwarded to read/parse
+   * @param {string} [options.encoding="utf8"] - File encoding
+   * @param {string} [options.type="any"] - Data format for parsing
+   * @returns {Promise<unknown>} The cached or freshly loaded data
+   * @throws {Sass} If the file does not exist
+   */
+  async #loadFromCache(fileObject, kind, options={}) {
+    Valid.assert(kind === "raw" || kind === "structured",
+      "Cache data type must be 'raw' or 'structured'.")
+
+    const lastModified = await fileObject.modified()
+
+    if(lastModified === null)
+      throw Sass.new(`No such file '${fileObject}'`)
+
+    const rec = this.#cache.get(fileObject.path) ?? Object.seal({
+      modified: new Date(0),
+      raw: null,
+      structured: null,
+    })
+
+    if(lastModified.getTime() === rec.modified.getTime()) {
+      if(kind === "raw" && rec.raw !== null)
+        return rec.raw
+
+      if(kind === "structured" && rec.structured !== null)
+        return rec.structured
+    }
+
+    this.#cache.set(fileObject.path, rec)
+    rec.modified = lastModified
+    rec.raw = await fileObject.read({
+      encoding: options.encoding,
+      skipCache: true,
+    })
+    rec.structured = null
+
+    if(kind === "raw")
+      return rec.raw
+
+    rec.structured = Data.textAsData(rec.raw, options.type)
+
+    return rec.structured
   }
 
   /**
@@ -38,35 +103,40 @@ export default class Cache {
    * freshness while optimizing performance for repeated file access during
    * parallel processing.
    *
-   * @param {import("./FileObject.js").FileObject} fileObject - The file object to load and cache
+   * @param {FileObject} fileObject - The file object to load and cache
    * @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 fileObject.modified()
+  async loadDataFromCache(fileObject, options={}) {
+    Valid.type(fileObject, "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)
-        }
-      }
-    }
+    return await this.#loadFromCache(
+      fileObject, "structured", options)
+  }
+
+  /**
+   * Loads and caches raw file content with automatic mtime-based
+   * invalidation.
+   *
+   * @param {FileObject} fileObject - The file object to read and cache
+   * @returns {Promise<string>} The raw file content
+   * @throws {Sass} If the file cannot be found or accessed
+   */
+  async loadFromCache(fileObject, options={}) {
+    Valid.type(fileObject, "FileObject")
 
-    const data = await fileObject.loadData()
+    return await this.#loadFromCache(
+      fileObject, "raw", options)
+  }
 
-    this.#modifiedTimes.set(fileObject.path, lastModified)
-    this.#dataCache.set(fileObject.path, data)
+  /**
+   * Clears cached data for a specific file from both time and data maps.
+   *
+   * @param {import("./FileObject.js").default} file - The file object to clear from cache
+   */
+  resetCache(file) {
+    Valid.type(file, "FileObject")
 
-    return data
+    this.#cleanup(file)
   }
 }

package/src/node/lib/Data.js

@@ -0,0 +1,49 @@
+import JSON5 from "json5"
+import YAML from "yaml"
+import BrowserData from "../../browser/lib/Data.js"
+import Sass from "./Sass.js"
+
+/**
+ * Node-side extension of Data with parsing utilities that require
+ * node-specific dependencies.
+ */
+export default class Data extends BrowserData {
+  /**
+   * Parses text content as structured data (JSON5 or YAML).
+   *
+   * @param {string} source - The text content to parse
+   * @param {string} [type="any"] - The expected format ("json",
+   *   "json5", "yaml", or "any")
+   * @returns {unknown} The parsed data
+   * @throws {Sass} If content cannot be parsed or type is
+   *   unsupported
+   */
+  static textAsData(source, type="any") {
+    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(source)
+
+        return result
+      } catch {
+        // nothing to see here
+      }
+    }
+
+    throw Sass.new(
+      `Content is neither valid JSON5 nor valid YAML.`)
+  }
+}

package/src/node/lib/DirectoryObject.js

@@ -37,7 +37,8 @@ import Valid from "./Valid.js"
  * @property {URL|null} url - The directory URL
  */
 
-/** * DirectoryObject encapsulates metadata and operations for a directory,
+/**
+ * DirectoryObject encapsulates metadata and operations for a directory,
  * providing immutable path resolution, existence checks, and content enumeration.
  *
  * Features:
@@ -480,7 +481,7 @@ export default class DirectoryObject extends FS {
    *
    * @async
    * @param {object} [options] - Options to pass to fs.mkdir (e.g., {recursive: true, mode: 0o755})
-   * @returns {Promise<void>}
+   * @returns {Promise<undefined>}
    * @throws {Sass} If directory creation fails for reasons other than already existing
    * @example
    * // Create directory recursively
@@ -555,7 +556,7 @@ export default class DirectoryObject extends FS {
    * a directory with contents, you must imperatively decide your deletion
    * strategy and handle it explicitly.
    *
-   * @returns {Promise<void>} Resolves when directory is deleted
+   * @returns {Promise<undefined>} Resolves when directory is deleted
    * @throws {Sass} If the directory URL is invalid
    * @throws {Sass} If the directory does not exist
    * @throws {Error} If the directory is not empty (from fs.rmdir)
@@ -629,8 +630,6 @@ export default class DirectoryObject extends FS {
   getDirectory(newPath) {
     Valid.type(newPath, "String", {allowEmpty: false})
 
-    // New direction: every path is relative to THIS path. Absolute?
-    //  ../../../..? up to this path and then down again if required.
     const thisPath = this.path
     const merged = FS.mergeOverlappingPaths(thisPath, newPath)
     const resolved = FS.resolvePath(thisPath, merged)
@@ -679,8 +678,6 @@ export default class DirectoryObject extends FS {
   getFile(filename) {
     Valid.type(filename, "String", {allowEmpty: false})
 
-    // Every path is relative to THIS path. Absolute or .. paths
-    // are constrained to this directory.
     const thisPath = this.path
     const merged = FS.mergeOverlappingPaths(thisPath, filename)
     const resolved = FS.resolvePath(thisPath, merged)