@gesslar/toolkit 0.2.8 → 0.3.0

package/src/lib/Logger.js

@@ -0,0 +1,182 @@
+/*
+  For formatting console info, see:
+  https://nodejs.org/docs/latest-v22.x/api/util.html#utilformatformat-args
+
+  * %s: String will be used to convert all values except BigInt, Object and -0.
+        BigInt values will be represented with an n and Objects that have no
+        user defined toString function are inspected using util.inspect() with
+        options { depth: 0, colors: false, compact: 3 }.
+  * %d: Number will be used to convert all values except BigInt and Symbol.
+  * %i: parseInt(value, 10) is used for all values except BigInt and Symbol.
+  * %f: parseFloat(value) is used for all values expect Symbol.
+  * %j: JSON. Replaced with the string '[Circular]' if the argument contains
+        circular references.
+  * %o: Object. A string representation of an object with generic JavaScript
+        object formatting. Similar to util.inspect() with options { showHidden:
+        true, showProxy: true }. This will show the full object including non-
+        enumerable properties and proxies.
+  * %O: Object. A string representation of an object with generic JavaScript
+        object formatting. Similar to util.inspect() without options. This will
+        show the full object not including non-enumerable properties and
+        proxies.
+  * %%: single percent sign ('%'). This does not consume an argument.
+
+*/
+
+import ErrorStackParser from "error-stack-parser"
+import console from "node:console"
+import {Environment} from "./Core.js"
+import {FileObject, Util} from "@gesslar/toolkit"
+
+export const loggerColours = {
+  debug: [
+    "\x1b[38;5;19m", // Debug level 0: Dark blue
+    "\x1b[38;5;27m", // Debug level 1: Medium blue
+    "\x1b[38;5;33m", // Debug level 2: Light blue
+    "\x1b[38;5;39m", // Debug level 3: Teal
+    "\x1b[38;5;44m", // Debug level 4: Blue-tinted cyan
+  ],
+  info: "\x1b[38;5;36m",    // Medium Spring Green
+  warn: "\x1b[38;5;214m",   // Orange1
+  error: "\x1b[38;5;196m",  // Red1
+  reset: "\x1b[0m", // Reset
+}
+
+/**
+ * Logger class
+ *
+ * Log levels:
+ * - debug: Debugging information
+ *   - Debug levels
+ *     - 0: No/critical debug information, not error level, but, should be
+ *          logged
+ *     - 1: Basic debug information, startup, shutdown, etc
+ *     - 2: Intermediate debug information, discovery, starting to get more
+ *         detailed
+ *     - 3: Detailed debug information, parsing, processing, etc
+ *     - 4: Very detailed debug information, nerd mode!
+ * - warn: Warning information
+ * - info: Informational information
+ * - error: Error information
+ */
+
+export default class Logger {
+  #name = null
+  #debugLevel = 0
+
+  constructor(options) {
+    this.#name = "BeDoc"
+    if(options) {
+      this.setOptions(options)
+      if(options.env === Environment.EXTENSION) {
+        const vscode = import("vscode")
+
+        this.vscodeError = vscode.window.showErrorMessage
+        this.vscodeWarn = vscode.window.showWarningMessage
+        this.vscodeInfo = vscode.window.showInformationMessage
+      }
+    }
+  }
+
+  get name() {
+    return this.#name
+  }
+
+  get debugLevel() {
+    return this.#debugLevel
+  }
+
+  get options() {
+    return {
+      name: this.#name,
+      debugLevel: this.#debugLevel,
+    }
+  }
+
+  setOptions(options) {
+    this.#name = options.name ?? this.#name
+    this.#debugLevel = options.debugLevel
+  }
+
+  #compose(level, message, debugLevel = 0) {
+    const tag = Util.capitalize(level)
+
+    if(level === "debug")
+      return `[${this.#name}] ${loggerColours[level][debugLevel]}${tag}${loggerColours.reset}: ${message}`
+
+    return `[${this.#name}] ${loggerColours[level]}${tag}${loggerColours.reset}: ${message}`
+  }
+
+  lastStackLine(error = new Error(), stepsRemoved = 3) {
+    const stack = ErrorStackParser.parse(error)
+
+    return stack[stepsRemoved]
+  }
+
+  extractFileFunction(level = 0) {
+    const frame = this.lastStackLine()
+    const {
+      functionName: func,
+      fileName: file,
+      lineNumber: line,
+      columnNumber: col,
+    } = frame
+
+    const tempFile = new FileObject(file)
+    const {module, uri} = tempFile
+
+    let functionName = func ?? "anonymous"
+
+    if(functionName.startsWith("#"))
+      functionName = `${module}.${functionName}`
+
+    const methodName = /\[as \w+\]$/.test(functionName)
+      ? /\[as (\w+)\]/.exec(functionName)[1]
+      : null
+
+    if(methodName) {
+      functionName = functionName.replace(/\[as \w+\]$/, "")
+      functionName = `${functionName}{${methodName}}`
+    }
+
+    if(/^async /.test(functionName))
+      functionName = functionName.replace(/^async /, "(async)")
+
+    let result = functionName
+
+    if(level >= 2)
+      result = `${result}:${line}:${col}`
+
+    if(level >= 3)
+      result = `${uri} ${result}`
+
+    return result
+  }
+
+  newDebug(tag) {
+    return function(message, level, ...arg) {
+      tag = this.extractFileFunction(this.#debugLevel)
+      this.debug(`[${tag}] ${message}`, level, ...arg)
+    }.bind(this)
+  }
+
+  debug(message, level = 0, ...arg) {
+    if(level <= (this.debugLevel ?? 4))
+      console.debug(this.#compose("debug", message, level), ...arg)
+  }
+
+  warn(message, ...arg) {
+    console.warn(this.#compose("warn", message), ...arg)
+    this.vscodeWarn?.(JSON.stringify(message))
+  }
+
+  info(message, ...arg) {
+    console.info(this.#compose("info", message), ...arg)
+    this.vscodeInfo?.(JSON.stringify(message))
+  }
+
+  error(message, ...arg) {
+    console.error(this.#compose("error", message), ...arg)
+    this.vscodeError?.(JSON.stringify(message))
+  }
+}

package/src/lib/Piper.js

@@ -0,0 +1,181 @@
+/**
+ * Generic Pipeline - Process items through a series of steps with concurrency control
+ *
+ * This abstraction handles:
+ * - Concurrent processing with configurable limits
+ * - Pipeline of processing steps
+ * - Result categorization (success/warning/error)
+ * - Setup/cleanup lifecycle hooks
+ * - Error handling and reporting
+ */
+
+export default class Piper {
+  #succeeded = []
+  #warned = []
+  #errored = []
+  #steps = []
+  #setupHooks = []
+  #cleanupHooks = []
+  #logger
+
+  constructor(options = {}) {
+    this.#logger = options.logger || {newDebug: () => () => {}}
+  }
+
+  /**
+   * Add a processing step to the pipeline
+   *
+   * @param {(context: object) => Promise<object>} stepFn - Function that processes an item: (context) => Promise<result>
+   * @param {object} options - Step options (name, required, etc.)
+   * @returns {Piper} The pipeline instance (for chaining)
+   */
+  addStep(stepFn, options = {}) {
+    this.#steps.push({
+      fn: stepFn,
+      name: options.name || `Step ${this.#steps.length + 1}`,
+      required: options.required !== false, // Default to required
+      ...options
+    })
+
+    return this
+  }
+
+  /**
+   * Add setup hook that runs before processing starts
+   *
+   * @param {() => Promise<void>} setupFn - Setup function: () => Promise<void>
+   * @returns {Piper} The pipeline instance (for chaining)
+   */
+  addSetup(setupFn) {
+    this.#setupHooks.push(setupFn)
+
+    return this
+  }
+
+  /**
+   * Add cleanup hook that runs after processing completes
+   *
+   * @param {() => Promise<void>} cleanupFn - Cleanup function: () => Promise<void>
+   * @returns {Piper} The pipeline instance (for chaining)
+   */
+  addCleanup(cleanupFn) {
+    this.#cleanupHooks.push(cleanupFn)
+
+    return this
+  }
+
+  /**
+   * Process items through the pipeline with concurrency control
+   *
+   * @param {Array} items - Items to process
+   * @param {number} maxConcurrent - Maximum concurrent items to process
+   * @returns {Promise<object>} - Results object with succeeded, warned, errored arrays
+   */
+  async pipe(items, maxConcurrent = 10) {
+    const itemQueue = [...items]
+    const activePromises = []
+
+    // Run setup hooks
+    await Promise.allSettled(this.#setupHooks.map(hook => hook()))
+
+    const processNextItem = item => {
+      return this.#processItem(item).then(result => {
+        // Categorize result
+        if(result.status === "success") {
+          this.#succeeded.push({input: item, ...result})
+        } else if(result.status === "warning") {
+          this.#warned.push({input: item, ...result})
+        } else {
+          this.#errored.push({input: item, ...result})
+        }
+
+        // Process next item if queue has items
+        if(itemQueue.length > 0) {
+          const nextItem = itemQueue.shift()
+
+          return processNextItem(nextItem)
+        }
+      })
+    }
+
+    // Fill initial concurrent slots
+    while(activePromises.length < maxConcurrent && itemQueue.length > 0) {
+      const item = itemQueue.shift()
+
+      activePromises.push(processNextItem(item))
+    }
+
+    // Wait for all processing to complete
+    await Promise.allSettled(activePromises)
+
+    // Run cleanup hooks
+    await Promise.allSettled(this.#cleanupHooks.map(hook => hook()))
+
+    return {
+      succeeded: this.#succeeded,
+      warned: this.#warned,
+      errored: this.#errored
+    }
+  }
+
+  /**
+   * Process a single item through all pipeline steps
+   *
+   * @param {object} item - The item to process
+   * @returns {Promise<object>} Result object with status and data
+   * @private
+   */
+  async #processItem(item) {
+    const debug = this.#logger.newDebug()
+    const context = {item, data: {}}
+
+    try {
+      // Execute each step in sequence
+      for(const step of this.#steps) {
+        debug(`Executing step: ${step.name}`, 2)
+
+        const result = await step.fn(context)
+
+        // Handle step result
+        if(result && typeof result === "object") {
+          if(result.status === "error") {
+            return result
+          }
+
+          if(result.status === "warning" && step.required) {
+            return result
+          }
+
+          // Merge result data into context for next steps
+          context.data = {...context.data, ...result.data}
+          context.status = result.status || context.status
+        }
+      }
+
+      return {
+        status: context.status || "success",
+        ...context.data
+      }
+
+    } catch(error) {
+      return {
+        status: "error",
+        error,
+        item
+      }
+    }
+  }
+
+  /**
+   * Clear results (useful for reusing pipeline instance)
+   *
+   * @returns {Piper} The pipeline instance (for chaining)
+   */
+  clearResults() {
+    this.#succeeded = []
+    this.#warned = []
+    this.#errored = []
+
+    return this
+  }
+}

package/src/lib/Sass.js

@@ -102,10 +102,8 @@ export default class Sass extends Error {
    * @returns {string|undefined} Formatted stack trace or undefined
    */
   #fullBodyMassage(stack) {
-    // Remove the first line, it's already been reported
-
     stack = stack ?? ""
-
+    // Remove the first line, it's already been reported
     const {rest} = stack.match(/^.*?\n(?<rest>[\s\S]+)$/m)?.groups ?? {}
     const lines = []
 
@@ -114,7 +112,7 @@ export default class Sass extends Error {
         ...rest
           .split("\n")
           .map(line => {
-            const at = line.match(/^\s{4}at\s(?<at>.*)$/)?.groups?.at ?? {}
+            const at = line.match(/^\s{4}at\s(?<at>.*)$/)?.groups?.at ?? ""
 
             return at
               ? `* ${at}`

package/src/lib/Tantrum.js

@@ -0,0 +1,69 @@
+/**
+ * @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"
+import Term from "./Term.js"
+
+/**
+ * Custom aggregate error class that extends AggregateError.
+ * Automatically wraps plain errors in Sass instances for consistent reporting.
+ */
+export default class Tantrum extends AggregateError {
+  /**
+   * Creates a new Tantrum instance.
+   *
+   * @param {string} message - The aggregate error message
+   * @param {Array<Error|Sass>} errors - Array of errors to aggregate
+   */
+  constructor(message, errors = []) {
+    // 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"
+  }
+  /**
+   * Reports all aggregated errors to the terminal with formatted output.
+   *
+   * @param {boolean} [nerdMode] - Whether to include detailed stack traces
+   */
+  report(nerdMode = false) {
+    Term.error(
+      `${Term.terminalBracket(["error", "Tantrum Incoming"])} (${this.errors.length} errors)\n` +
+      this.message
+    )
+
+    Term.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 = []) {
+    return new Tantrum(message, errors)
+  }
+}

package/src/types/Tantrum.d.ts

@@ -0,0 +1,81 @@
+// Implementation: ../lib/Tantrum.js
+// Type definitions for Tantrum aggregate error class
+
+import Sass from './Sass'
+
+/**
+ * Custom aggregate error class that extends AggregateError.
+ * 
+ * Automatically wraps plain Error objects in Sass instances while preserving
+ * existing Sass errors, providing consistent formatted reporting for
+ * multiple error scenarios.
+ * 
+ * @example
+ * ```typescript
+ * // Collect multiple errors and throw as a bundle
+ * const errors = [new Error("thing 1"), sassError, new Error("thing 3")]
+ * throw Tantrum.new("Multiple validation failures", errors)
+ * 
+ * // Later, in error handling:
+ * catch (error) {
+ *   if (error instanceof Tantrum) {
+ *     error.report() // Reports all errors with Sass formatting
+ *   }
+ * }
+ * ```
+ */
+export default class Tantrum extends AggregateError {
+  /**
+   * Creates a new Tantrum instance.
+   * Plain Error objects are automatically wrapped in Sass instances.
+   * 
+   * @param message - The aggregate error message describing the overall failure
+   * @param errors - Array of errors to aggregate (mix of Error and Sass instances allowed)
+   */
+  constructor(message: string, errors?: Array<Error | Sass>)
+
+  /** Name of the error class */
+  readonly name: 'Tantrum'
+
+  /** Array of aggregated errors (all wrapped as Sass instances) */
+  readonly errors: Array<Sass>
+
+  /**
+   * Reports all aggregated errors to the terminal with formatted output.
+   * Shows a header with error count, then delegates to each Sass instance
+   * for individual error reporting.
+   * 
+   * @param nerdMode - Whether to include detailed stack traces in output
+   * 
+   * @example
+   * ```typescript
+   * try {
+   *   throw Tantrum.new("Batch failed", [error1, error2])
+   * } catch (tantrum) {
+   *   tantrum.report() // User-friendly output
+   *   tantrum.report(true) // Includes full stack traces
+   * }
+   * ```
+   */
+  report(nerdMode?: boolean): void
+
+  /**
+   * Factory method to create a Tantrum instance.
+   * Follows the same pattern as Sass.new() for consistency.
+   * 
+   * @param message - The aggregate error message
+   * @param errors - Array of errors to aggregate
+   * @returns New Tantrum instance with all errors wrapped as Sass
+   * 
+   * @example
+   * ```typescript
+   * // Typical usage pattern
+   * throw Tantrum.new("Someone ate all my Runts!", [
+   *   emptyRuntsBoxError,
+   *   emptyRuntsBoxError, 
+   *   emptyRuntsBoxError
+   * ])
+   * ```
+   */
+  static new(message: string, errors?: Array<Error | Sass>): Tantrum
+}

package/src/types/index.d.ts

@@ -10,6 +10,7 @@ export { default as Collection } from './Collection.js'
 export { default as Data } from './Data.js'
 export { default as Glog } from './Glog.js'
 export { default as Sass } from './Sass.js'
+export { default as Tantrum } from './Tantrum.js'
 export { default as Term } from './Term.js'
 export { default as Type } from './Type.js'
 export { default as Util } from './Util.js'