@gesslar/toolkit 3.22.2 → 3.23.0

package/README.md

@@ -42,12 +42,10 @@ Includes all browser functionality plus Node.js-specific modules for file I/O, l
 | Notify | Event system wrapper for Node.js events |
 | Sass | Custom Error class with enhanced features |
 | Tantrum | AggregateError implementation |
-| TempDirectoryObject | Temporary directory management with automatic cleanup |
 | Term | Terminal formatting and output utilities |
 | Util | General utility functions (Node-enhanced version) |
 | Valid | Validation and assertion methods |
-| VDirectoryObject | Directory operations constrained to a specific tree |
-| VFileObject | Virtual file operations for in-memory file handling |
+
 
 ## Installation
 
@@ -100,8 +98,7 @@ import { Data, Collection, Util } from '@gesslar/toolkit/browser'
 
 The browser version includes: Collection, Data, Disposer, HTML, Notify, Sass,
 Tantrum, Type (TypeSpec), Util, and Valid. Node-only modules (Cache,
-DirectoryObject, FileObject, FileSystem, Glog, TempDirectoryObject, Term,
-VDirectoryObject, VFileObject) are not available in the browser version.
+DirectoryObject, FileObject, FileSystem, Glog, Term) are not available in the browser version.
 
 ## Post Partum
 

package/package.json

@@ -5,7 +5,7 @@
     "name": "gesslar",
     "url": "https://gesslar.dev"
   },
-  "version": "3.22.2",
+  "version": "3.23.0",
   "license": "Unlicense",
   "homepage": "https://github.com/gesslar/toolkit#readme",
   "repository": {
@@ -52,16 +52,22 @@
     "node": ">=22"
   },
   "dependencies": {
+    "@eslint/js": "^9.39.2",
     "@gesslar/colours": "^0.8.0",
+    "@stylistic/eslint-plugin": "^5.7.0",
     "ajv": "^8.17.1",
+    "globals": "^17.0.0",
     "json5": "^2.2.3",
+    "types": "^0.1.1",
     "yaml": "^2.8.2"
   },
   "devDependencies": {
-    "@gesslar/uglier": "^1.0.0",
+    "@gesslar/uglier": "^1.1.0",
     "eslint": "^9.39.2",
-    "happy-dom": "^20.1.0",
-    "typescript": "^5.9.3"
+    "eslint-plugin-jsdoc": "^62.0.0",
+    "happy-dom": "^20.3.1",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.53.0"
   },
   "scripts": {
     "types": "node -e \"require('fs').rmSync('types',{recursive:true,force:true});\" && tsc -p tsconfig.types.json",

package/src/browser/lib/Data.js

@@ -180,12 +180,26 @@ export default class Data {
     return string.slice(index + length)
   }
 
+  /**
+   * 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
+   */
+
   /**
    * Creates a type spec from a string. A type spec is an array of objects
    * defining the type of a value and whether an array is expected.
    *
    * @param {string} string - The string to parse into a type spec.
-   * @param {object} options - Additional options for parsing.
+   * @param {TypeSpecOptions} [options] - Additional options for parsing.
    * @returns {Array<object>} An array of type specs.
    */
   static newTypeSpec(string, options) {
@@ -197,7 +211,7 @@ export default class Data {
    *
    * @param {unknown} value The value to check
    * @param {string|TypeSpec} type The type to check for
-   * @param {object} options Additional options for checking
+   * @param {TypeValidationOptions} [options] Additional options for checking
    * @returns {boolean} Whether the value is of the specified type
    */
   static isType(value, type, options = {}) {

package/src/browser/lib/OObject.js

@@ -0,0 +1,196 @@
+import Data from "./Data.js"
+import Valid from "./Valid.js"
+
+/**
+ * @typedef {object} OObjectArrayInfo
+ * @property {Array<string>} path - The path array to the array element
+ * @property {string} flatPath - The dot-separated path to the array element
+ * @property {number} index - The index of the element in the array
+ */
+
+/**
+ * @typedef {object} OObjectEntry
+ * @property {string} key - The property key
+ * @property {any} value - The property value
+ * @property {string} valueString - String representation of the value
+ * @property {Array<string>} path - The path array to this property
+ * @property {string} flatPath - The dot-separated path to this property
+ * @property {OObjectArrayInfo} [array] - Array information if this entry is from an array
+ */
+
+/**
+ * @typedef {Record<string, any> | Array<any>} OObjectSource
+ */
+
+export default class OObject {
+  /** @type {Array<OObjectEntry>} */
+  #data = []
+
+  /**
+   * Constructs an OObject with optional initial data.
+   *
+   * @param {Array<OObjectEntry>} oobject
+   */
+  constructor(oobject=[]) {
+    this.#data = oobject
+  }
+
+  /**
+   * Creates an OObject from a source object or array
+   *
+   * @param {OObjectSource} source - The source object or array to decompose
+   * @returns {OObject} A new OObject instance
+   */
+  static from(source) {
+    Valid.type(source, "Object|Array")
+
+    return new this(this.#decomposeObject(source))
+  }
+
+  /**
+   * Decomposes a nested object into flat entries with path information.
+   * Recursively processes objects and arrays to create a flat structure for
+   * evaluation.
+   *
+   * @param {Record<string, any>} work - The object to decompose
+   * @param {Array<string>} objectPath - Current path array for nested properties
+   * @returns {Array<OObjectEntry>} Array of decomposed object entries with path information
+   */
+  static #decomposeObject(work, objectPath=[]) {
+    Valid.type(work, "Object|Array")
+    Valid.type(objectPath, "Array")
+
+    const result = []
+
+    for(const key in work) {
+      const currPath = [...objectPath, key]
+      const item = work[key]
+
+      if(Data.isPlainObject(item)) {
+        result.push(...this.#decomposeObject(work[key], currPath))
+      } else if(Array.isArray(work[key])) {
+        work[key].forEach((item, index) => {
+          const path = [...currPath, String(index+1)]
+
+          if(Data.isPlainObject(item)) {
+            result.push(...this.#decomposeObject(item, path))
+          } else {
+            result.push({
+              key,
+              value: item,
+              valueString: String(item),
+              path,
+              flatPath: path.join("."),
+              array: {
+                path: path.slice(0, -1),
+                flatPath: path.slice(0, -1).join("."),
+                index
+              }
+            })
+          }
+        })
+      } else {
+        result.push({key, value: item, valueString: String(item), path: currPath, flatPath: currPath.join(".")})
+      }
+    }
+
+    return result
+  }
+
+  /**
+   * Gets the internal data array
+   *
+   * @returns {Array<object>} The decomposed object entries
+   */
+  get data() {
+    return this.#data
+  }
+
+  /**
+   * Finds the first entry matching a flat path or predicate
+   *
+   * @param {string|((entry: OObjectEntry, index: number, array: Array<OObjectEntry>) => boolean)} pathOrPredicate - Flat path string or predicate function
+   * @returns {OObjectEntry|undefined} The matching entry or undefined
+   */
+  find(pathOrPredicate) {
+    if(typeof pathOrPredicate === "string") {
+      return this.#data.find(entry => entry.flatPath === pathOrPredicate)
+    }
+
+    Valid.type(pathOrPredicate, "function")
+
+    return this.#data.find(pathOrPredicate)
+  }
+
+  /**
+   * Finds all entries matching a flat path or predicate
+   *
+   * @param {string|((entry: OObjectEntry, index: number, array: Array<OObjectEntry>) => boolean)} pathOrPredicate - Flat path string or predicate function
+   * @returns {Array<object>} Array of matching entries
+   */
+  findAll(pathOrPredicate) {
+    if(typeof pathOrPredicate === "string") {
+      return this.#data.filter(entry => entry.flatPath === pathOrPredicate)
+    }
+
+    Valid.type(pathOrPredicate, "function")
+
+    return this.#data.filter(pathOrPredicate)
+  }
+
+  /**
+   * Returns an iterator over all entries in order
+   *
+   * @returns {Iterator<object>} Iterator of decomposed entries
+   */
+  entries() {
+    return this.#data[Symbol.iterator]()
+  }
+
+  /**
+   * Executes a callback for each entry in order
+   *
+   * @param {(entry: OObjectEntry, index: number, array: Array<OObjectEntry>) => void} callback - Function to call for each entry
+   * @returns {void}
+   */
+  forEach(callback) {
+    Valid.type(callback, "function")
+
+    this.#data.forEach(callback)
+  }
+
+  /**
+   * Ensures a path exists in the data, optionally setting a value
+   *
+   * @param {string} flatPath - The dot-separated path to ensure
+   * @param {*} value - Optional value to set (defaults to undefined)
+   * @returns {object} The entry at the path
+   */
+  assurePath(flatPath, value=undefined) {
+    Valid.type(flatPath, "string")
+
+    let entry = this.find(flatPath)
+
+    if(!entry) {
+      const path = flatPath.split(".")
+      const key = path[path.length - 1]
+
+      /** @type {OObjectEntry} */
+      const newEntry = {
+        key,
+        value,
+        valueString: String(value),
+        path,
+        flatPath
+      }
+
+      this.#data.push(newEntry)
+      entry = newEntry
+    } else if(value !== undefined) {
+      entry.value = value
+      entry.valueString = String(value)
+    }
+
+    return entry
+  }
+}

package/src/browser/lib/Promised.js

@@ -118,10 +118,12 @@ export default class Promised {
    * @param {Array<{status: 'fulfilled'|'rejected', value?: unknown, reason?: unknown}>} settled - Array of settled promise results
    * @throws {Tantrum} Throws a Tantrum error with rejection reasons
    */
-  static throw(message="GIGO", settled) {
-    Valid.type(message, "String", {allowEmpty: false})
+  static throw(message, settled) {
+    Valid.type(message, "Null|Undefined|String", {allowEmpty: false})
     Valid.type(settled, "Array")
 
+    message ??= "GIGO"
+
     const rejected = this.rejected(settled)
     const reasons = this.reasons(rejected)
 

package/src/browser/lib/Time.js

@@ -1,5 +1,5 @@
+import Sass from "./Sass.js"
 import Valid from "./Valid.js"
-
 /**
  * Utility class for timing operations and promise-based delays.
  * Provides methods for creating cancellable timeout promises.
@@ -30,7 +30,9 @@ export default class Time {
 
     let timerId
     const promise = new Promise(resolve => {
-      timerId = setTimeout(() => resolve(value), delay)
+      // Cap at max 32-bit signed integer to avoid Node.js timeout overflow warning
+      const safeDelay = Math.min(delay, 2147483647)
+      timerId = setTimeout(() => resolve(value), safeDelay)
     })
     promise.timerId = timerId
 

package/src/browser/lib/TypeSpec.js

@@ -9,6 +9,20 @@ 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.
@@ -20,7 +34,7 @@ export default class TypeSpec {
    * Creates a new TypeSpec instance.
    *
    * @param {string} string - The type specification string (e.g., "string|number", "object[]")
-   * @param {unknown} options - Additional parsing options
+   * @param {TypeSpecOptions} [options] - Additional parsing options
    */
   constructor(string, options) {
     this.#specs = []
@@ -134,14 +148,20 @@ 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 {unknown} options - Validation options
-   * @param {boolean} options.allowEmpty - Whether empty values are allowed
+   * @param {TypeValidationOptions} [options] - Validation options
    * @returns {boolean} True if the value matches any type specification
    */
   matches(value, options) {
     return this.match(value, options).length > 0
   }
 
+  /**
+   * Returns matching type specifications for a value.
+   *
+   * @param {unknown} value - The value to test against the type specifications
+   * @param {TypeValidationOptions} [options] - Validation options
+   * @returns {Array<object>} Array of matching type specifications
+   */
   match(value, options) {
     const allowEmpty = options?.allowEmpty ?? true
 
@@ -211,8 +231,7 @@ export default class TypeSpec {
    *
    * @private
    * @param {string} string - The type specification string to parse
-   * @param {unknown} options - Parsing options
-   * @param {string} options.delimiter - The delimiter for union types
+   * @param {TypeSpecOptions} [options] - Parsing options
    * @throws {Sass} If the type specification is invalid
    */
   #parse(string, options={delimiter: "|"}) {

package/src/node/index.js

@@ -20,7 +20,4 @@ export {default as FileObject} from "./lib/FileObject.js"
 export {default as FileSystem} from "./lib/FileSystem.js"
 export {default as Glog} from "./lib/Glog.js"
 export {default as Notify} from "./lib/Notify.js"
-export {default as TempDirectoryObject} from "./lib/TempDirectoryObject.js"
 export {default as Term} from "./lib/Term.js"
-export {default as VFileObject} from "./lib/VFileObject.js"
-export {default as VDirectoryObject} from "./lib/VDirectoryObject.js"