@gesslar/toolkit 0.5.0 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gesslar/toolkit",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Get in, bitches, we're going toolkitting.",
   "main": "./src/index.js",
   "type": "module",
@@ -20,12 +20,12 @@
     "node": ">=20"
   },
   "scripts": {
+    "types:build": "tsc -p tsconfig.types.json",
     "lint": "eslint src/",
     "lint:fix": "eslint src/ --fix",
     "submit": "npm publish --access public",
     "update": "npx npm-check-updates -u && npm install",
     "test": "node --test tests/unit/*.test.js",
-    "test:unit": "node --test tests/unit/*.test.js",
     "pr": "gt submit --publish --restack --ai"
   },
   "repository": {
@@ -57,11 +57,11 @@
     "yaml": "^2.8.1"
   },
   "devDependencies": {
-    "@stylistic/eslint-plugin": "^5.4.0",
-    "@types/node": "^24.6.2",
-    "@typescript-eslint/eslint-plugin": "^8.45.0",
-    "@typescript-eslint/parser": "^8.45.0",
-    "eslint": "^9.36.0",
-    "eslint-plugin-jsdoc": "^60.7.1"
+    "@stylistic/eslint-plugin": "^5.5.0",
+    "@types/node": "^24.9.1",
+    "@typescript-eslint/eslint-plugin": "^8.46.2",
+    "@typescript-eslint/parser": "^8.46.2",
+    "eslint": "^9.38.0",
+    "eslint-plugin-jsdoc": "^61.1.8"
   }
 }

package/src/lib/Collection.js

@@ -1,9 +1,31 @@
+/**
+ * @file Collection.js
+ *
+ * Provides utility functions for working with collections (arrays, objects, sets, maps).
+ * Includes methods for iteration, transformation, validation, and manipulation of
+ * various collection types.
+ */
+
 import Data from "./Data.js"
 import Valid from "./Valid.js"
 import Sass from "./Sass.js"
 import Util from "./Util.js"
 
+/**
+ * Utility class for collection operations.
+ * Provides static methods for working with arrays, objects, sets, and maps.
+ */
 export default class Collection {
+  /**
+   * Evaluates an array with a predicate function, optionally in reverse order.
+   * Returns the first truthy result from the predicate.
+   *
+   * @param {Array<unknown>} collection - The array to evaluate
+   * @param {(value: unknown, index: number, array: Array<unknown>) => unknown} predicate - Function to evaluate each element
+   * @param {boolean} [forward] - Whether to iterate forward (true) or backward (false). Defaults to true
+   * @returns {unknown|undefined} The first truthy result from the predicate, or undefined
+   * @throws {Sass} If collection is not an array or predicate is not a function
+   */
   static evalArray(collection, predicate, forward=true) {
     const req = "Array"
     const type = Data.typeOf(collection)
@@ -24,6 +46,15 @@ export default class Collection {
     }
   }
 
+  /**
+   * Evaluates an object with a predicate function.
+   * Returns the first truthy result from the predicate.
+   *
+   * @param {object} collection - The object to evaluate
+   * @param {(value: unknown, key: string, object: object) => unknown} predicate - Function to evaluate each property
+   * @returns {unknown|undefined} The first truthy result from the predicate, or undefined
+   * @throws {Sass} If collection is not an object or predicate is not a function
+   */
   static evalObject(collection, predicate) {
     const req = "Object"
     const type = Data.typeOf(collection)
@@ -42,6 +73,15 @@ export default class Collection {
     }
   }
 
+  /**
+   * Evaluates a Set with a predicate function.
+   * Returns the first truthy result from the predicate.
+   *
+   * @param {Set<unknown>} collection - The Set to evaluate
+   * @param {(value: unknown, set: Set<unknown>) => unknown} predicate - Function to evaluate each element
+   * @returns {unknown|undefined} The first truthy result from the predicate, or undefined
+   * @throws {Sass} If collection is not a Set or predicate is not a function
+   */
   static evalSet(collection, predicate) {
     const req = "Set"
     const type = Data.typeOf(collection)
@@ -60,6 +100,16 @@ export default class Collection {
     }
   }
 
+  /**
+   * Evaluates a Map with a predicate function, optionally in reverse order.
+   * Returns the first truthy result from the predicate.
+   *
+   * @param {Map<unknown, unknown>} collection - The Map to evaluate
+   * @param {(value: unknown, key: unknown, map: Map<unknown, unknown>) => unknown} predicate - Function to evaluate each entry
+   * @param {boolean} [forward] - Whether to iterate forward (true) or backward (false). Defaults to true
+   * @returns {unknown|undefined} The first truthy result from the predicate, or undefined
+   * @throws {Sass} If collection is not a Map or predicate is not a function
+   */
   static evalMap(collection, predicate, forward=true) {
     const req = "Map"
     const type = Data.typeOf(collection)
@@ -80,12 +130,27 @@ export default class Collection {
     }
   }
 
+  /**
+   * Zips two arrays together into an array of pairs.
+   * The resulting array length equals the shorter input array.
+   *
+   * @param {Array<unknown>} array1 - The first array
+   * @param {Array<unknown>} array2 - The second array
+   * @returns {Array<[unknown, unknown]>} Array of paired elements
+   */
   static zip(array1, array2) {
     const minLength = Math.min(array1.length, array2.length)
 
     return Array.from({length: minLength}, (_, i) => [array1[i], array2[i]])
   }
 
+  /**
+   * Unzips an array of pairs into separate arrays.
+   * Transposes a 2D array structure.
+   *
+   * @param {Array<Array<unknown>>} array - Array of arrays to unzip
+   * @returns {Array<Array<unknown>>} Array of unzipped arrays, or empty array for invalid input
+   */
   static unzip(array) {
     if(!Array.isArray(array) || array.length === 0) {
       return [] // Handle empty or invalid input
@@ -108,6 +173,15 @@ export default class Collection {
     return unzipped
   }
 
+  /**
+   * Maps an array using an async function, processing items sequentially.
+   * Unlike Promise.all(array.map()), this processes one item at a time.
+   *
+   * @param {Array<unknown>} array - The array to map
+   * @param {(item: unknown) => Promise<unknown>} asyncFn - Async function to apply to each element
+   * @returns {Promise<Array<unknown>>} Promise resolving to the mapped array
+   * @throws {Sass} If array is not an Array or asyncFn is not a function
+   */
   static async asyncMap(array, asyncFn) {
     const req = "Array"
     const type = Data.typeOf(array)
@@ -128,9 +202,8 @@ export default class Collection {
   /**
    * Checks if all elements in an array are of a specified type
    *
-   * @param {Array} arr - The array to check
-   * @param {string} type - The type to check for (optional, defaults to the
-   *                        type of the first element)
+   * @param {Array<unknown>} arr - The array to check
+   * @param {string} [type] - The type to check for (optional, defaults to the type of the first element)
    * @returns {boolean} Whether all elements are of the specified type
    */
   static isArrayUniform(arr, type) {
@@ -155,8 +228,8 @@ export default class Collection {
   /**
    * Checks if an array is unique
    *
-   * @param {Array} arr - The array of which to remove duplicates
-   * @returns {Array} The unique elements of the array
+   * @param {Array<unknown>} arr - The array of which to remove duplicates
+   * @returns {Array<unknown>} The unique elements of the array
    */
   static isArrayUnique(arr) {
     const req = "Array"
@@ -170,9 +243,9 @@ export default class Collection {
   /**
    * Returns the intersection of two arrays.
    *
-   * @param {Array} arr1 - The first array.
-   * @param {Array} arr2 - The second array.
-   * @returns {Array} The intersection of the two arrays.
+   * @param {Array<unknown>} arr1 - The first array.
+   * @param {Array<unknown>} arr2 - The second array.
+   * @returns {Array<unknown>} The intersection of the two arrays.
    */
   static intersection(arr1, arr2) {
     const req = "Array"
@@ -198,8 +271,8 @@ export default class Collection {
    *   Collection.intersects([1, 2, 3], [3, 4, 5]) // returns true
    *   Collection.intersects(["a", "b"], ["c", "d"]) // returns false
    *
-   * @param {Array} arr1 - The first array to check for intersection.
-   * @param {Array} arr2 - The second array to check for intersection.
+   * @param {Array<unknown>} arr1 - The first array to check for intersection.
+   * @param {Array<unknown>} arr2 - The second array to check for intersection.
    * @returns {boolean} True if any element is shared between the arrays, false otherwise.
    */
   static intersects(arr1, arr2) {
@@ -219,11 +292,11 @@ export default class Collection {
    * Pads an array to a specified length with a value. This operation
    * occurs in-place.
    *
-   * @param {Array} arr - The array to pad.
+   * @param {Array<unknown>} arr - The array to pad.
    * @param {number} length - The length to pad the array to.
    * @param {unknown} value - The value to pad the array with.
-   * @param {number} position - The position to pad the array at.
-   * @returns {Array} The padded array.
+   * @param {number} [position] - The position to pad the array at. Defaults to 0
+   * @returns {Array<unknown>} The padded array.
    */
   static arrayPad(arr, length, value, position = 0) {
     const req = "Array"
@@ -254,9 +327,9 @@ export default class Collection {
    * Filters an array asynchronously using a predicate function.
    * Applies the predicate to all items in parallel and returns filtered results.
    *
-   * @param {Array} arr - The array to filter
-   * @param {function(unknown): Promise<boolean>} predicate - Async predicate function that returns a promise resolving to boolean
-   * @returns {Promise<Array>} Promise resolving to the filtered array
+   * @param {Array<unknown>} arr - The array to filter
+   * @param {(value: unknown, index: number, array: Array<unknown>) => Promise<boolean>} predicate - Async predicate function that returns a promise resolving to boolean
+   * @returns {Promise<Array<unknown>>} Promise resolving to the filtered array
    */
   static async asyncFilter(arr, predicate) {
     const req = "Array"
@@ -468,7 +541,7 @@ export default class Collection {
 
     if(
       !Data.isType(spec, "Array", {allowEmpty: false}) &&
-      !Data.isType(spec, "function")
+      !Data.isType(spec, "Function")
     )
       throw Sass.new("Spec must be an array or a function.")
 
@@ -498,6 +571,15 @@ export default class Collection {
     return result
   }
 
+  /**
+   * Trims falsy values from both ends of an array (in-place).
+   * Optionally preserves specific falsy values.
+   *
+   * @param {Array<unknown>} arr - The array to trim
+   * @param {Array<unknown>} [except] - Values to preserve even if falsy. Defaults to empty array
+   * @returns {Array<unknown>} The trimmed array (same reference, modified in-place)
+   * @throws {Sass} If arr is not an Array or except is not an Array
+   */
   static trimArray(arr, except=[]) {
     Valid.type(arr, "Array")
     Valid.type(except, "Array")
@@ -508,6 +590,15 @@ export default class Collection {
     return arr
   }
 
+  /**
+   * Trims falsy values from the right end of an array (in-place).
+   * Optionally preserves specific falsy values.
+   *
+   * @param {Array<unknown>} arr - The array to trim
+   * @param {Array<unknown>} [except] - Values to preserve even if falsy. Defaults to empty array
+   * @returns {Array<unknown>} The trimmed array (same reference, modified in-place)
+   * @throws {Sass} If arr is not an Array or except is not an Array
+   */
   static trimArrayRight(arr, except=[]) {
     Valid.type(arr, "Array")
     Valid.type(except, "Array")
@@ -519,6 +610,15 @@ export default class Collection {
     return arr
   }
 
+  /**
+   * Trims falsy values from the left end of an array (in-place).
+   * Optionally preserves specific falsy values.
+   *
+   * @param {Array<unknown>} arr - The array to trim
+   * @param {Array<unknown>} [except] - Values to preserve even if falsy. Defaults to empty array
+   * @returns {Array<unknown>} The trimmed array (same reference, modified in-place)
+   * @throws {Sass} If arr is not an Array or except is not an Array
+   */
   static trimArrayLeft(arr, except=[]) {
     Valid.type(arr, "Array")
     Valid.type(except, "Array")
@@ -535,6 +635,14 @@ export default class Collection {
     return arr
   }
 
+  /**
+   * Transposes an array of objects into an object of arrays.
+   * Collects values for each key across all objects into arrays.
+   *
+   * @param {Array<object>} objects - Array of plain objects to transpose
+   * @returns {object} Object with keys from input objects, values as arrays
+   * @throws {Sass} If objects is not an Array or contains non-plain objects
+   */
   static transposeObjects(objects) {
     const req = "Array"
     const type = Data.typeOf(objects)
@@ -560,6 +668,13 @@ export default class Collection {
     }, {})
   }
 
+  /**
+   * Flattens an array (or nested array) of objects and transposes them.
+   * Combines flat() and transposeObjects() operations.
+   *
+   * @param {Array<object>|Array<Array<object>>} input - Array or nested array of objects
+   * @returns {object} Transposed object with arrays of values
+   */
   static flattenObjectArray(input) {
     const flattened = Array.isArray(input) ? input.flat() : input
 

package/src/lib/Contract.js

@@ -156,7 +156,7 @@ export default class Contract {
    *
    * @param {object} providerTerms - Terms offered by provider
    * @param {object} consumerTerms - Terms expected by consumer
-   * @param {Array} stack - Stack trace for nested validation
+   * @param {Array<string>} stack - Stack trace for nested validation
    * @returns {object} Result with status and errors
    * @private
    */

package/src/lib/Data.js

@@ -17,17 +17,18 @@ export default class Data {
  */
   static primitives = Object.freeze([
   // Primitives
-    "Undefined",
-    "Null",
+    "Bigint",
     "Boolean",
+    "Class",
+    "Null",
     "Number",
-    "Bigint",
     "String",
     "Symbol",
+    "Undefined",
 
     // Object Categories from typeof
-    "Object",
     "Function",
+    "Object",
   ])
 
   /**
@@ -38,21 +39,21 @@ export default class Data {
    */
   static constructors = Object.freeze([
   // Object Constructors
-    "Object",
     "Array",
-    "Function",
     "Date",
-    "RegExp",
     "Error",
+    "Float32Array",
+    "Float64Array",
+    "Function",
+    "Int8Array",
     "Map",
+    "Object",
+    "Promise",
+    "RegExp",
     "Set",
+    "Uint8Array",
     "WeakMap",
     "WeakSet",
-    "Promise",
-    "Int8Array",
-    "Uint8Array",
-    "Float32Array",
-    "Float64Array",
   ])
 
   /**
@@ -123,7 +124,7 @@ export default class Data {
       ? type
       : Data.newTypeSpec(type, options)
 
-    return typeSpec.match(value, options)
+    return typeSpec.matches(value, options)
   }
 
   /**
@@ -134,9 +135,8 @@ export default class Data {
    */
   static isValidType(type) {
     // Allow built-in types
-    if(Data.dataTypes.includes(type)) {
+    if(Data.dataTypes.includes(type))
       return true
-    }
 
     // Allow custom classes (PascalCase starting with capital letter)
     return /^[A-Z][a-zA-Z0-9]*$/.test(type)
@@ -155,6 +155,15 @@ export default class Data {
     if(!Data.isValidType(type))
       return false
 
+    // We gotta do classes up front. Ugh.
+    if(/^[Cc]lass$/.test(type)) {
+      if(typeof value === "function" &&
+      value.prototype &&
+      value.prototype.constructor === value)
+
+        return true
+    }
+
     const valueType = Data.typeOf(value)
 
     // Special cases that need extra validation
@@ -327,9 +336,9 @@ export default class Data {
    * Filters an array asynchronously using a predicate function.
    * Applies the predicate to all items in parallel and returns filtered results.
    *
-   * @param {Array} arr - The array to filter
-   * @param {function(unknown): Promise<boolean>} predicate - Async predicate function that returns a promise resolving to boolean
-   * @returns {Promise<Array>} Promise resolving to the filtered array
+   * @param {Array<unknown>} arr - The array to filter
+   * @param {(value: unknown) => Promise<boolean>} predicate - Async predicate function that returns a promise resolving to boolean
+   * @returns {Promise<Array<unknown>>} Promise resolving to the filtered array
    */
   static async asyncFilter(arr, predicate) {
     const results = await Promise.all(arr.map(predicate))

package/src/lib/DirectoryObject.js

@@ -191,7 +191,7 @@ export default class DirectoryObject extends FS {
   /**
    * Returns the directory path split into segments.
    *
-   * @returns {string[]} Array of path segments
+   * @returns {Array<string>} Array of path segments
    * @example
    * const dir = new DirectoryObject('/path/to/directory')
    * console.log(dir.trail) // ['', 'path', 'to', 'directory']

package/src/lib/FS.js

@@ -1,3 +1,10 @@
+/**
+ * @file FS.js
+ *
+ * File system utilities for path manipulation, file discovery, and path resolution.
+ * Provides glob-based file search, URI conversion, and intelligent path merging.
+ */
+
 import {globby} from "globby"
 import path from "node:path"
 import url from "node:url"
@@ -14,6 +21,9 @@ const fdType = Object.freeze(
   await Collection.allocateObject(upperFdTypes, fdTypes)
 )
 
+/**
+ * File system utility class for path operations and file discovery.
+ */
 export default class FS {
   static fdTypes = fdTypes
   static upperFdTypes = upperFdTypes

package/src/lib/Glog.js

@@ -1,11 +1,6 @@
-import c from "@gesslar/colours"
-
-import Data from "./Data.js"
-import Term from "./Term.js"
-import Util from "./Util.js"
-// ErrorStackParser will be dynamically imported when needed
-
 /**
+ * @file Glog.js
+ *
  * Enhanced Global logging utility that combines simple logging with advanced Logger features.
  *
  * Can be used in multiple ways:
@@ -16,6 +11,13 @@ import Util from "./Util.js"
  * 5. Traditional logger: logger.debug("message", level)
  */
 
+import c from "@gesslar/colours"
+
+import Data from "./Data.js"
+import Term from "./Term.js"
+import Util from "./Util.js"
+// ErrorStackParser will be dynamically imported when needed
+
 // Enhanced color system using @gesslar/colours
 export const loggerColours = {
   debug: [
@@ -238,10 +240,24 @@ class Glog {
   }
 
   // Traditional logger methods
-  debug(message, level = 0, ...arg) {
+  /**
+   * Log a debug message with specified verbosity level.
+   * Level 0 means debug OFF - use levels 1-4 for actual debug output.
+   * Debug messages only show when logLevel > 0.
+   *
+   * @param {string} message - Debug message to log
+   * @param {number} level - Debug verbosity level (1-4, default: 1)
+   * @param {...unknown} arg - Additional arguments to log
+   * @throws {Error} If level < 1 (level 0 = debug OFF)
+   */
+  debug(message, level = 1, ...arg) {
+    if(level < 1) {
+      throw new Error("Debug level must be >= 1 (level 0 = debug OFF)")
+    }
+
     const currentLevel = this.#logLevel || Glog.logLevel
 
-    if(level <= currentLevel) {
+    if(currentLevel > 0 && level <= currentLevel) {
       Term.debug(this.#compose("debug", message, level), ...arg)
     }
   }
@@ -370,10 +386,11 @@ export default new Proxy(Glog, {
     return new target(...argumentsList)
   },
   get(target, prop) {
+    // Hide execute method from public API
     if(prop === "execute") {
       return undefined
     }
 
-    return target[prop]
+    return Reflect.get(target, prop)
   }
 })

package/src/lib/Logger.js

@@ -180,3 +180,6 @@ export default class Logger {
     this.vscodeError?.(JSON.stringify(message))
   }
 }
+
+// NOTE: This is an artifact file kept for reference during Glog development.
+// Not exported from toolkit. Has broken imports to ./Core.js (actions package).

package/src/lib/Sass.js

@@ -12,6 +12,7 @@
  */
 
 import Term from "./Term.js"
+import Tantrum from "./Tantrum.js"
 
 /**
  * Custom error class for toolkit errors.
@@ -149,15 +150,19 @@ export default class Sass extends Error {
    * other errors. Otherwise creates a new Sass instance.
    *
    * @param {string} message - The error message
-   * @param {Error|Sass} [error] - Optional existing error to wrap or enhance
+   * @param {Error|Sass|Tantrum} [error] - Optional existing error to wrap or enhance
    * @returns {Sass} New or enhanced Sass instance
    */
   static new(message, error) {
     if(error) {
+      if(error instanceof Tantrum)
+        return Tantrum.new(message, error)
+
       return error instanceof Sass
         ? error.addTrace(message)
         : Sass.from(error, message)
     } else {
+
       return new Sass(message)
     }
   }

package/src/lib/Tantrum.js

@@ -17,6 +17,8 @@ import Term from "./Term.js"
  * Automatically wraps plain errors in Sass instances for consistent reporting.
  */
 export default class Tantrum extends AggregateError {
+  #trace = []
+
   /**
    * Creates a new Tantrum instance.
    *
@@ -38,6 +40,41 @@ export default class Tantrum extends AggregateError {
     super(wrappedErrors, message)
     this.name = "Tantrum"
   }
+
+  /**
+   * Adds a trace message and returns this instance for chaining.
+   *
+   * @param {string} message - The trace message to add
+   * @param {Error|Sass} [_error] - Optional error (currently unused, reserved for future use)
+   * @returns {this} This Tantrum instance for method chaining
+   */
+  addTrace(message, _error) {
+    if(typeof message !== "string")
+      throw Sass.new(`Tantrum.addTrace expected string, got ${JSON.stringify(message)}`)
+
+    this.trace = message
+
+    return this
+  }
+
+  /**
+   * Gets the error trace array.
+   *
+   * @returns {Array<string>} Array of trace messages
+   */
+  get trace() {
+    return this.#trace
+  }
+
+  /**
+   * Adds a message to the beginning of the trace array.
+   *
+   * @param {string} message - The trace message to add
+   */
+  set trace(message) {
+    this.#trace.unshift(message)
+  }
+
   /**
    * Reports all aggregated errors to the terminal with formatted output.
    *
@@ -49,6 +86,9 @@ export default class Tantrum extends AggregateError {
       this.message
     )
 
+    if(this.trace)
+      Term.error(this.trace.join("\n"))
+
     Term.error()
 
     this.errors.forEach(error => {
@@ -64,6 +104,9 @@ export default class Tantrum extends AggregateError {
    * @returns {Tantrum} New Tantrum instance
    */
   static new(message, errors = []) {
+    if(errors instanceof Tantrum)
+      return errors.addTrace(message)
+
     return new Tantrum(message, errors)
   }
 }

package/src/lib/TypeSpec.js

@@ -138,23 +138,27 @@ export default class TypeSpec {
    * @param {boolean} options.allowEmpty - Whether empty values are allowed
    * @returns {boolean} True if the value matches any type specification
    */
+  matches(value, options) {
+    return this.match(value,options).length > 0
+  }
+
   match(value, options) {
     const allowEmpty = options?.allowEmpty ?? true
     const empty = Data.isEmpty(value)
 
-    // 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 JavaScript.
+    // 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
+    // JavaScript.
     if(this.length && !this.every(t => Data.isValidType(t.typeName)))
-      return false
+      return []
 
     // Now, let's do some checking with the types, respecting the array flag
     // with the value
     const valueType = Data.typeOf(value)
     const isArray = valueType === "Array"
 
-    // 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.
+    // 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 => {
       const {typeName: allowedType, array: allowedArray} = spec
 
@@ -187,7 +191,7 @@ export default class TypeSpec {
       return false
     })
 
-    return matchingTypeSpec.length > 0
+    return matchingTypeSpec
   }
 
   /**