@gesslar/toolkit 0.8.0 → 1.0.0

package/README.md

@@ -7,6 +7,41 @@ but the kind that says "yumyum."
 There are file and directory abstractions, uhmm, there's also some terminal
 things and validity checkers, lots of data functions.
 
+## Usage
+
+**For Node.js projects:**
+
+```javascript
+import { Data, FileObject, Cache } from '@gesslar/toolkit'
+// or explicitly:
+import { Data, FileObject } from '@gesslar/toolkit/node'
+```
+
+**For browsers or Tauri apps:**
+
+```javascript
+import { Data, Collection, Util } from '@gesslar/toolkit/browser'
+```
+
+The browser version includes: Data, Collection, Util, Type (TypeSpec), Valid,
+Sass, and Tantrum. Node-only modules (FileObject, Cache, FS, etc.) are not
+available in the browser version.
+
+**Browser via CDN (no install):**
+
+- jsDelivr (runtime only):
+  `https://cdn.jsdelivr.net/npm/@gesslar/toolkit/browser`
+- esm.sh (runtime + optional types):
+  `https://esm.sh/@gesslar/toolkit@0.8.0/browser`
+  `https://esm.sh/@gesslar/toolkit@0.8.0/browser?dts` (serves `.d.ts` for editors)
+
+Notes:
+
+- Nothing to configure in this repo for CDN use; both URLs just work.
+- TypeScript editors do not pick up types from jsDelivr. If you want inline
+  types without installing from npm, use the esm.sh `?dts` URL or install the
+  package locally for development and use the CDN at runtime.
+
 Basically, if you want it, it is most definitely here, and working 100% and
 absolutely none of that is true. There are only a few classes here, but they're
 pretty. And if you bug-shame them, I will _come for you like_ ...

package/package.json

@@ -1,11 +1,21 @@
 {
   "name": "@gesslar/toolkit",
-  "version": "0.8.0",
+  "version": "1.0.0",
   "description": "Get in, bitches, we're going toolkitting.",
   "main": "./src/index.js",
   "type": "module",
   "exports": {
     ".": {
+      "types": "./src/types/index.d.ts",
+      "browser": "./src/browser/index.js",
+      "node": "./src/index.js",
+      "default": "./src/index.js"
+    },
+    "./browser": {
+      "types": "./src/types/index.d.ts",
+      "default": "./src/browser/index.js"
+    },
+    "./node": {
       "types": "./src/types/index.d.ts",
       "default": "./src/index.js"
     }
@@ -25,7 +35,7 @@
     "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": "node --test tests/**/*.test.js",
     "pr": "gt submit --publish --restack --ai"
   },
   "repository": {
@@ -52,16 +62,18 @@
   "dependencies": {
     "@gesslar/colours": "^0.0.1",
     "ajv": "^8.17.1",
-    "globby": "^15.0.0",
+    "globby": "^16.0.0",
     "json5": "^2.2.3",
     "yaml": "^2.8.1"
   },
   "devDependencies": {
-    "@stylistic/eslint-plugin": "^5.5.0",
-    "@types/node": "^24.10.0",
-    "@typescript-eslint/eslint-plugin": "^8.46.3",
-    "@typescript-eslint/parser": "^8.46.3",
+    "@gesslar/uglier": "^0.0.5",
+    "@stylistic/eslint-plugin": "^5.6.1",
+    "@types/node": "^24.10.1",
+    "@typescript-eslint/eslint-plugin": "^8.48.0",
+    "@typescript-eslint/parser": "^8.48.0",
     "eslint": "^9.39.1",
-    "eslint-plugin-jsdoc": "^61.1.12"
+    "eslint-plugin-jsdoc": "^61.4.1",
+    "globals": "^16.5.0"
   }
 }

package/src/browser/index.js

@@ -0,0 +1,10 @@
+// Browser-compatible utilities
+// Pure JavaScript modules that work in browsers, Tauri, and Node.js
+
+export {default as Collection} from "./lib/Collection.js"
+export {default as Data} from "./lib/Data.js"
+export {default as Sass} from "./lib/Sass.js"
+export {default as Tantrum} from "./lib/Tantrum.js"
+export {default as Type} from "./lib/TypeSpec.js"
+export {default as Util} from "./lib/Util.js"
+export {default as Valid} from "./lib/Valid.js"

package/src/browser/lib/Sass.js

@@ -0,0 +1,168 @@
+/**
+ * @file Sass.js
+ *
+ * Defines the Sass class, a custom error type for toolkit compilation
+ * errors.
+ *
+ * Supports error chaining, trace management, and formatted reporting for both
+ * user-friendly and verbose (nerd) output.
+ *
+ * Used throughout the toolkit for structured error handling and
+ * debugging.
+ */
+
+import Tantrum from "./Tantrum.js"
+
+/**
+ * Custom error class for toolkit errors.
+ * Provides error chaining, trace management, and formatted error reporting.
+ */
+export default class Sass extends Error {
+  #trace = []
+
+  /**
+   * Creates a new Sass instance.
+   *
+   * @param {string} message - The error message
+   * @param {...unknown} [arg] - Additional arguments passed to parent Error constructor
+   */
+  constructor(message, ...arg) {
+    super(message, ...arg)
+
+    this.trace = message
+  }
+
+  /**
+   * 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)
+  }
+
+  /**
+   * Adds a trace message and returns this instance for chaining.
+   *
+   * @param {string} message - The trace message to add
+   * @returns {this} This Sass instance for method chaining
+   */
+  addTrace(message) {
+    if(typeof message !== "string")
+      throw this.constructor.new(`Sass.addTrace expected string, got ${JSON.stringify(message)}`)
+
+    this.trace = message
+
+    return this
+  }
+
+  /**
+   * Reports the error to the console with formatted output.
+   * Optionally includes detailed stack trace information.
+   *
+   * @param {boolean} [nerdMode] - Whether to include detailed stack trace
+   */
+  report(nerdMode=false) {
+    console.error(
+      `[error] Something Went Wrong\n` +
+      this.trace.join("\n")
+    )
+
+    if(nerdMode) {
+      console.error(
+        "\n" +
+        `[error] Nerd Vittles\n` +
+        this.#fullBodyMassage(this.stack)
+      )
+
+      this.cause?.stack && console.error(
+        "\n" +
+        `[error] Rethrown From\n` +
+        this.#fullBodyMassage(this.cause?.stack)
+      )
+    }
+  }
+
+  /**
+   * Formats the stack trace for display, removing the first line and
+   * formatting each line with appropriate indentation.
+   *
+   * Note: Returns formatted stack trace or undefined if no stack available.
+   *
+   * @param {string} stack - The error stack to massage.
+   * @returns {string|undefined} Formatted stack trace or undefined
+   */
+  #fullBodyMassage(stack) {
+    stack = stack ?? ""
+    // Remove the first line, it's already been reported
+    const {rest} = stack.match(/^.*?\n(?<rest>[\s\S]+)$/m)?.groups ?? {}
+    const lines = []
+
+    if(rest) {
+      lines.push(
+        ...rest
+          .split("\n")
+          .map(line => {
+            const at = line.match(/^\s{4}at\s(?<at>.*)$/)?.groups?.at ?? ""
+
+            return at
+              ? `* ${at}`
+              : line
+          })
+      )
+    }
+
+    return lines.join("\n")
+  }
+
+  /**
+   * Creates an Sass from an existing Error object with additional
+   * trace message.
+   *
+   * @param {Error} error - The original error object
+   * @param {string} message - Additional trace message to add
+   * @returns {Sass} New Sass instance with trace from the original error
+   * @throws {Sass} If the first parameter is not an Error instance
+   */
+  static from(error, message) {
+    if(!(error instanceof Error))
+      throw this.new("Sass.from must take an Error object.")
+
+    const oldMessage = error.message
+    const newError = new this(oldMessage, {cause: error}).addTrace(message)
+
+    return newError
+  }
+
+  /**
+   * Factory method to create or enhance Sass instances.
+   * If error parameter is provided, enhances existing Sass or wraps
+   * other errors. Otherwise creates a new Sass instance.
+   *
+   * @param {string} message - The error message
+   * @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 this
+        ? error.addTrace(message)
+        : this.from(error, message)
+    } else {
+
+      return new this(message)
+    }
+  }
+}

package/src/browser/lib/Tantrum.js

@@ -0,0 +1,115 @@
+/**
+ * @file Tantrum.js
+ *
+ * Defines the Tantrum class, a custom AggregateError type for toolkit
+ * that collects multiple errors with Sass-style reporting.
+ *
+ * Auto-wraps plain Error objects in Sass instances while preserving
+ * existing Sass errors, providing consistent formatted output for
+ * multiple error scenarios.
+ */
+
+import Sass from "./Sass.js"
+
+/**
+ * Custom aggregate error class that extends AggregateError.
+ * Automatically wraps plain errors in Sass instances for consistent reporting.
+ */
+export default class Tantrum extends AggregateError {
+  #trace = []
+  #sass
+
+  /**
+   * Creates a new Tantrum instance.
+   *
+   * @param {string} message - The aggregate error message
+   * @param {Array<Error|Sass>} errors - Array of errors to aggregate
+   * @param {Sass} sass - Sass constructor
+   */
+  constructor(message, errors = [], sass=Sass) {
+    // Auto-wrap plain errors in Sass, keep existing Sass instances
+    const wrappedErrors = errors.map(error => {
+      if(error instanceof sass)
+        return error
+
+      if(!(error instanceof Error))
+        throw new TypeError(`All items in errors array must be Error instances, got: ${typeof error}`)
+
+      return sass.new(error.message, error)
+    })
+
+    super(wrappedErrors, message)
+
+    this.name = "Tantrum"
+    this.#sass = sass
+  }
+
+  /**
+   * 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 this.#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 console with formatted output.
+   *
+   * @param {boolean} [nerdMode] - Whether to include detailed stack traces
+   */
+  report(nerdMode = false) {
+    console.error(
+      `[error] Tantrum Incoming (${this.errors.length} errors)\n` +
+      this.message
+    )
+
+    if(this.trace)
+      console.error(this.trace.join("\n"))
+
+    console.error()
+
+    this.errors.forEach(error => {
+      error.report(nerdMode)
+    })
+  }
+
+  /**
+   * Factory method to create a Tantrum instance.
+   *
+   * @param {string} message - The aggregate error message
+   * @param {Array<Error|Sass>} errors - Array of errors to aggregate
+   * @returns {Tantrum} New Tantrum instance
+   */
+  static new(message, errors = []) {
+    if(errors instanceof this)
+      return errors.addTrace(message)
+
+    return new this(message, errors)
+  }
+}

package/src/browser/lib/Util.js

@@ -0,0 +1,257 @@
+import Sass from "./Sass.js"
+import Valid from "./Valid.js"
+import Collection from "./Collection.js"
+
+/**
+ * Utility class providing common helper functions for string manipulation,
+ * timing, 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) {
+    if(typeof text !== "string")
+      throw new TypeError("Util.capitalize expects a string")
+
+    if(text.length === 0)
+      return ""
+
+    const [first, ...rest] = Array.from(text)
+
+    return `${first.toLocaleUpperCase()}${rest.join("")}`
+  }
+
+  /**
+   * 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}`
+  }
+
+  /**
+   * Centre-align a string inside a fixed width (pad with spaces on left).
+   * 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 with text centred.
+   */
+  static centreAlignText(text, width=80) {
+    const work = String(text)
+
+    if(work.length >= width)
+      return work
+
+    const totalPadding = width - work.length
+    const leftPadding = Math.floor(totalPadding / 2)
+    const rightPadding = totalPadding - leftPadding
+
+    return `${" ".repeat(leftPadding)}${work}${" ".repeat(rightPadding)}`
+  }
+
+  /**
+   * Asynchronously awaits all promises in parallel.
+   * Wrapper around Promise.all for consistency with other utility methods.
+   *
+   * @param {Array<Promise<unknown>>} promises - Array of promises to await
+   * @returns {Promise<Array<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 {Array<Promise<unknown>>} promises - Array of promises to settle
+   * @returns {Promise<Array<object>>} Results of all settled promises with status and value/reason
+   */
+  static async settleAll(promises) {
+    return await Promise.allSettled(promises)
+  }
+
+  /**
+   * Checks if any result in the settled promise array is rejected.
+   *
+   * @param {Array<object>} result - Array of settled promise results.
+   * @returns {boolean} True if any result is rejected, false otherwise.
+   */
+  static anyRejected(result) {
+    return result.some(r => r.status === "rejected")
+  }
+
+  /**
+   * Filters and returns all rejected results from a settled promise array.
+   *
+   * @param {Array<object>} result - Array of settled promise results.
+   * @returns {Array<object>} Array of rejected results.
+   */
+  static settledAndRejected(result) {
+    return result.filter(r => r.status === "rejected")
+  }
+
+  /**
+   * Extracts the rejection reasons from an array of rejected promise results.
+   *
+   * @param {Array<object>} rejected - Array of rejected results.
+   * @returns {Array<unknown>} Array of rejection reasons.
+   */
+  static rejectedReasons(rejected) {
+    return rejected.map(r => r.reason)
+  }
+
+  /**
+   * Throws a Sass error containing all rejection reasons from settled promises.
+   *
+   * @param {string} [_message] - Optional error message. Defaults to "GIGO"
+   * @param {Array<object>} rejected - Array of rejected results.
+   * @throws {Error} Throws a Sass error with rejection reasons.
+   */
+  static throwRejected(_message="GIGO", rejected) {
+    throw Sass.new(this.rejectedReasons(rejected))
+  }
+
+  /**
+   * Filters and returns all fulfilled results from a settled promise array.
+   *
+   * @param {Array<object>} result - Array of settled promise results.
+   * @returns {Array<object>} Array of fulfilled results.
+   */
+  static settledAndFulfilled(result) {
+    return result.filter(r => r.status === "fulfilled")
+  }
+
+  /**
+   * Extracts the values from all fulfilled results in a settled promise array.
+   *
+   * @param {Array<object>} result - Array of settled promise results.
+   * @returns {Array<unknown>} Array of fulfilled values.
+   */
+  static fulfilledValues(result) {
+    return this.settledAndFulfilled(result).map(r => r.value)
+  }
+
+  /**
+   * Returns the first promise to resolve or reject from an array of promises.
+   * Wrapper around Promise.race for consistency with other utility methods.
+   *
+   * @param {Array<Promise<unknown>>} promises - Array of promises to race
+   * @returns {Promise<unknown>} Result of the first settled promise
+   */
+  static async race(promises) {
+    return await Promise.race(promises)
+  }
+
+  /**
+   * Determine the Levenshtein distance between two string values
+   *
+   * @param {string} a The first value for comparison.
+   * @param {string} b The second value for comparison.
+   * @returns {number} The Levenshtein distance
+   */
+  static levenshteinDistance(a, b) {
+    const matrix = Array.from({length: a.length + 1}, (_, i) =>
+      Array.from({length: b.length + 1}, (_, j) =>
+        (i === 0 ? j : j === 0 ? i : 0)
+      )
+    )
+
+    for(let i = 1; i <= a.length; i++) {
+      for(let j = 1; j <= b.length; j++) {
+        matrix[i][j] =
+          a[i - 1] === b[j - 1]
+            ? matrix[i - 1][j - 1]
+            : 1 + Math.min(
+              matrix[i - 1][j], matrix[i][j - 1],
+              matrix[i - 1][j - 1]
+            )
+      }
+    }
+
+    return matrix[a.length][b.length]
+  }
+
+  /**
+   * Determine the closest match between a string and allowed values
+   * from the Levenshtein distance.
+   *
+   * @param {string} input The input string to resolve
+   * @param {Array<string>} allowedValues The values which are permitted
+   * @param {number} [threshold] Max edit distance for a "close match"
+   * @returns {string} Suggested, probable match.
+   */
+  static findClosestMatch(input, allowedValues, threshold=2) {
+    let closestMatch = null
+    let closestDistance = Infinity
+    let closestLengthDiff = Infinity
+
+    for(const value of allowedValues) {
+      const distance = this.levenshteinDistance(input, value)
+      const lengthDiff = Math.abs(input.length - value.length)
+
+      if(distance < closestDistance && distance <= threshold) {
+        closestMatch = value
+        closestDistance = distance
+        closestLengthDiff = lengthDiff
+      } else if(distance === closestDistance &&
+                 distance <= threshold &&
+                 lengthDiff < closestLengthDiff) {
+        closestMatch = value
+        closestLengthDiff = lengthDiff
+      }
+    }
+
+    return closestMatch
+  }
+
+  static regexify(input, trim=true, flags=[]) {
+    Valid.type(input, "String")
+    Valid.type(trim, "Boolean")
+    Valid.type(flags, "Array")
+
+    Valid.assert(
+      flags.length === 0 ||
+      (flags.length > 0 && Collection.isArrayUniform(flags, "String")),
+      "All flags must be strings")
+
+    return new RegExp(
+      input
+        .split(/\r\n|\r|\n/)
+        .map(i => trim ? i.trim() : i)
+        .filter(i => trim ? Boolean(i) : true)
+        .join("")
+      , flags?.join(""))
+  }
+}