@gesslar/toolkit 0.2.7 → 0.2.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gesslar/toolkit",
-  "version": "0.2.7",
+  "version": "0.2.9",
   "description": "Get in, bitches, we're going toolkitting.",
   "main": "./src/index.js",
   "type": "module",
@@ -49,6 +49,7 @@
   "license": "Unlicense",
   "homepage": "https://github.com/gesslar/toolkit#readme",
   "dependencies": {
+    "@gesslar/colours": "^0.0.1",
     "globby": "^15.0.0",
     "json5": "^2.2.3",
     "yaml": "^2.8.1"

package/src/index.js

@@ -9,6 +9,7 @@ export {default as Collection} from "./lib/Collection.js"
 export {default as Data} from "./lib/Data.js"
 export {default as Glog} from "./lib/Glog.js"
 export {default as Sass} from "./lib/Sass.js"
+export {default as Tantrum} from "./lib/Tantrum.js"
 export {default as Term} from "./lib/Term.js"
 export {default as Type} from "./lib/TypeSpec.js"
 export {default as Util} from "./lib/Util.js"

package/src/lib/ActionBuilder.js

@@ -0,0 +1,144 @@
+import Valid from "./Valid.js"
+
+/** @typedef {import("./ActionRunner.js").default} ActionRunner */
+
+/**
+ * Activity bit flags recognised by {@link ActionBuilder#act}. The flag decides
+ * how results are accumulated for each activity.
+ *
+ * @readonly
+ * @enum {number}
+ */
+export const ACTIVITY = Object.freeze({
+  ONCE: 1<<1,
+  MANY: 1<<2,
+  PARALLEL: 1<<3,
+})
+
+/**
+ * Fluent builder for describing how an action should process the context that
+ * flows through the {@link ActionRunner}. Consumers register named activities,
+ * optional hook pairs, and nested parallel pipelines before handing the
+ * builder back to the runner for execution.
+ *
+ * Typical usage:
+ *
+ * ```js
+ * const pipeline = new ActionBuilder(myAction)
+ *   .act("prepare", ACTIVITY.ONCE, ctx => ctx.initialise())
+ *   .parallel(parallel => parallel
+ *     .act("step", ACTIVITY.MANY, ctx => ctx.consume())
+ *   )
+ *   .act("finalise", ACTIVITY.ONCE, ctx => ctx.complete())
+ *   .build()
+ * ```
+ *
+ * @class ActionBuilder
+ */
+export default class ActionBuilder {
+  #action = null
+  #activities = new Map([])
+
+  /**
+   * Creates a new ActionBuilder instance with the provided action callback.
+   *
+   * @param {(ctx: object) => void} action Base action invoked by the runner when a block
+   *   satisfies the configured structure.
+   */
+  constructor(action) {
+    this.#action = action
+  }
+
+  /**
+   * Returns the underlying action that will receive the extracted context.
+   *
+   * @returns {(ctx: object) => void} The action callback function that processes the extracted context.
+   */
+  get action() {
+    return this.#action
+  }
+
+  /**
+   * Returns the registered activities keyed by their name.
+   *
+   * @returns {Map<string | symbol, {op: (context: object) => unknown, kind: number, hooks: {before: ((context: object) => void)|null, after: ((context: object) => void)|null}}>} Map of registered activities and their metadata.
+   */
+  get activities() {
+    return this.#activities
+  }
+
+  /**
+   * Registers a named activity that will run for each matching block.
+   *
+   * @param {string} name Unique activity identifier.
+   * @param {number} kind Activity accumulation strategy (see {@link ACTIVITY}).
+   * @param {(context: object) => unknown} op Work function executed with the runner context.
+   * @param {{before?: (context: object) => void, after?: (context: object) => void}} [hooks] Optional hooks to run before or after the activity operation.
+   * @returns {ActionBuilder} Builder instance for chaining.
+   */
+  act(name, kind, op, hooks={}) {
+    this.#validActivityKind(kind)
+    this.#dupeActivityCheck(name)
+
+    hooks = this.#normalizeHooks(hooks)
+
+    this.#activities.set(name, {op, kind, hooks})
+
+    return this
+  }
+
+  #normalizeHooks({before=null, after=null}) {
+    return {before, after}
+  }
+
+  /**
+   * Defines a nested pipeline that will run with the {@link ACTIVITY} flag PARALLEL.
+   *
+   * The callback receives a fresh {@link ActionBuilder} scoped to the current
+   * action. The callback must return the configured builder so the runner can
+   * execute the nested pipeline.
+   *
+   * @param {(builder: ActionBuilder) => ActionBuilder} func Callback configuring a nested builder.
+   * @returns {ActionBuilder} Builder instance for chaining.
+   */
+  parallel(func) {
+    const activityName = Symbol(performance.now())
+
+    this.#activities.set(activityName, {
+      op: func.call(this.action, new ActionBuilder(this.action)),
+      kind: ACTIVITY.PARALLEL
+    })
+
+    return this
+  }
+
+  #validActivityKind(kind) {
+    Valid.assert(
+      Object.values(ACTIVITY).includes(kind),
+      "Invalid activity kind."
+    )
+  }
+
+  /**
+   * Validates that an activity name has not been reused.
+   *
+   * @private
+   * @param {string|symbol} name Activity identifier.
+   */
+  #dupeActivityCheck(name) {
+    Valid.assert(
+      !this.#activities.has(name),
+      `Activity '${String(name)}' has already been registered.`
+    )
+  }
+
+  /**
+   * Finalises the builder and returns a payload that can be consumed by the
+   * runner.
+   *
+   * @returns {{action: (context: object) => unknown, build: ActionBuilder}} Payload consumed by the {@link ActionRunner} constructor.
+   */
+  build() {
+    return {action: this.#action, build: this}
+  }
+}

package/src/lib/ActionRunner.js

@@ -0,0 +1,109 @@
+import ActionBuilder, {ACTIVITY} from "./ActionBuilder.js"
+import Data from "./Data.js"
+import Piper from "./Piper.js"
+import Sass from "./Sass.js"
+import Glog from "./Glog.js"
+
+/**
+ * Orchestrates execution of {@link ActionBuilder}-produced pipelines.
+ *
+ * Activities run in insertion order, with support for once-off work, repeated
+ * loops, and nested parallel pipelines. Each activity receives a mutable
+ * context object under `result.value` that can be replaced or enriched.
+ */
+export default class ActionRunner {
+  #action = null
+  #build = null
+  #logger = null
+
+  constructor({action, build, logger}) {
+    this.#action = action
+    this.#build = build
+    this.#logger = logger ?? Glog.newDebug()
+  }
+
+  /**
+   * Executes the configured action pipeline.
+   *
+   * @param {unknown} content Seed value passed to the first activity.
+   * @returns {Promise<unknown>} Final value produced by the pipeline, or null when a parallel stage reports failures.
+   * @throws {Sass} When no activities are registered or required parallel builders are missing.
+   */
+  async run(content) {
+    const AR = ActionRunner
+    const result = {value: content}
+    const action = this.#action
+    const activities = this.#build.activities
+
+    if(!activities.size)
+      throw Sass.new("No activities defined in action.")
+
+    for(const [_,activity] of activities) {
+      const {op} = activity
+
+      if(activity.kind === ACTIVITY.ONCE) {
+
+        if(Data.typeOf(activity.hooks?.before) === "Function")
+          await activity.hooks.before.call(action, result)
+
+        const activityResult = await op.call(action, result)
+
+        if(!activityResult)
+          break
+
+        if(Data.typeOf(activity.hooks?.after) === "Function")
+          await activity.hooks.after.call(action, result)
+
+      } else if(activity.kind == ACTIVITY.MANY) {
+        for(;;) {
+
+          if(Data.typeOf(activity.hooks?.before) === "Function")
+            await activity.hooks.before.call(action, result)
+
+          const activityResult = await op.call(action, result)
+
+          if(!activityResult)
+            break
+
+          if(Data.typeOf(activity.hooks?.after) === "Function")
+            await activity.hooks.after.call(action, result)
+        }
+      } else if(activity.kind === ACTIVITY.PARALLEL) {
+        if(op === undefined)
+          throw Sass.new("Missing action builder. Did you return the builder?")
+
+        if(!op)
+          throw Sass.new("Okay, cheeky monkey, you need to return the builder for this to work.")
+
+        const piper = new Piper({logger: this.#logger})
+          .addStep(c => new AR(op.build()).run(c))
+
+        result.value = await piper.pipe()
+        Glog(result)
+        throw Sass.new("Nope")
+
+        // // wheeeeeeeeeeeeee! ZOOMZOOM!
+        // const settled = await Util.settleAll(
+        //   result.value.map()
+        // )
+
+        // const rejected = settled
+        //   .filter(r => r.status === "rejected")
+        //   .map(r => {
+        //     return r.reason instanceof Sass
+        //       ? r.reason
+        //       : Sass.new("Running structured parsing.", r.reason)
+        //   })
+        //   .map(r => r.report(true))
+
+        // if(rejected.length)
+        //   return null
+
+        // result.value = settled.map(s => s.value)
+        //   .sort((a,b) => a.index-b.index)
+      }
+    }
+
+    return result.value
+  }
+}

package/src/lib/FileObject.js

@@ -353,12 +353,12 @@ export default class FileObject extends FS {
   async read(encoding="utf8") {
     const filePath = this.path
 
-    if(!(await this.exists))
-      throw Sass.new(`No such file '${filePath}'`)
-
     if(!filePath)
       throw Sass.new("No absolute path in file map")
 
+    if(!(await this.exists))
+      throw Sass.new(`No such file '${filePath}'`)
+
     return await fs.readFile(filePath, encoding)
   }
 
@@ -409,4 +409,21 @@ export default class FileObject extends FS {
 
     throw Sass.new(`Content is neither valid JSON5 nor valid YAML:\n'${this.path}'`)
   }
+
+  /**
+   * Loads a file as a module and returns it.
+   *
+   * @returns {Promise<object>} The file contents as a module.
+   */
+  async import() {
+    const fileUri = this.uri
+
+    if(!fileUri)
+      throw Sass.new("No URI in file map")
+
+    if(!(await this.exists))
+      throw Sass.new(`No such file '${fileUri}'`)
+
+    return await import(fileUri)
+  }
 }

package/src/lib/Glog.js

@@ -1,136 +1,374 @@
 import Data from "./Data.js"
-import console from "node:console"
+import Util from "./Util.js"
+import c from "@gesslar/colours"
+import Term from "./Term.js"
+// ErrorStackParser will be dynamically imported when needed
 
 /**
- * Global logging utility with configurable log levels and prefixes.
- * Provides a flexible logging system that can be used as both a class and
- * a callable function, with support for log level filtering and custom
- * prefixes for better log organization.
+ * Enhanced Global logging utility that combines simple logging with advanced Logger features.
  *
- * The Glog class uses a proxy to enable both class-style and function-style
- * usage patterns, making it convenient for different coding preferences.
- *
- * @example
- * // Set up logging configuration
- * Glog.setLogLevel(3).setLogPrefix('[MyApp]')
- *
- * // Log messages with different levels
- * Glog(0, 'Critical error')  // Always shown
- * Glog(2, 'Debug info')      // Shown if logLevel >= 2
- * Glog('Simple message')     // Level 0 by default
+ * Can be used in multiple ways:
+ * 1. Simple function call: Glog(data)
+ * 2. With levels: Glog(2, "debug message")
+ * 3. Configured instance: new Glog(options)
+ * 4. Fluent setup: Glog.create().withName("App").withColors()
+ * 5. Traditional logger: logger.debug("message", level)
  */
+
+// Enhanced color system using @gesslar/colours
+export const loggerColours = {
+  debug: [
+    "{F019}", // Debug level 0: Dark blue
+    "{F027}", // Debug level 1: Medium blue
+    "{F033}", // Debug level 2: Light blue
+    "{F039}", // Debug level 3: Teal
+    "{F044}", // Debug level 4: Blue-tinted cyan
+  ],
+  info: "{F036}",    // Medium Spring Green
+  warn: "{F214}",    // Orange1
+  error: "{F196}",   // Red1
+  reset: "{/}",      // Reset
+}
+
+// Set up convenient aliases for common log colors
+c.alias.set("debug", "{F033}")
+c.alias.set("info", "{F036}")
+c.alias.set("warn", "{F214}")
+c.alias.set("error", "{F196}")
+c.alias.set("success", "{F046}")
+c.alias.set("muted", "{F244}")
+c.alias.set("bold", "{<B}")
+c.alias.set("dim", "{<D}")
+
 class Glog {
-  /** @type {number} Current log level threshold (0-5) */
+  // Static properties (for global usage)
   static logLevel = 0
-  /** @type {string} Prefix to prepend to all log messages */
   static logPrefix = ""
+  static colors = null
+  static stackTrace = false
+  static name = ""
+
+  // Instance properties (for configured loggers)
+  #logLevel = 0
+  #logPrefix = ""
+  #colors = null
+  #stackTrace = false
+  #name = ""
+  #vscodeError = null
+  #vscodeWarn = null
+  #vscodeInfo = null
+
+  constructor(options = {}) {
+    this.setOptions(options)
+
+    // VSCode integration if specified
+    if(options.env === "extension") {
+      try {
+        const vscode = require("vscode")
+
+        this.#vscodeError = vscode.window.showErrorMessage
+        this.#vscodeWarn = vscode.window.showWarningMessage
+        this.#vscodeInfo = vscode.window.showInformationMessage
+      } catch {
+        // VSCode not available, ignore
+      }
+    }
+  }
+
+  // === CONFIGURATION METHODS ===
+
+  setOptions(options) {
+    this.#name = options.name ?? this.#name
+    this.#logLevel = options.debugLevel ?? options.logLevel ?? this.#logLevel
+    this.#logPrefix = options.prefix ?? this.#logPrefix
+    this.#colors = options.colors ?? this.#colors
+    this.#stackTrace = options.stackTrace ?? this.#stackTrace
+
+    return this
+  }
+
+  // === STATIC CONFIGURATION (for global usage) ===
 
-  /**
-   * Sets the log prefix for all subsequent log messages.
-   * The prefix helps identify the source of log messages in complex
-   * applications with multiple components.
-   *
-   * @param {string} prefix - The prefix string to prepend to log messages
-   * @returns {typeof Glog} Returns the Glog class for method chaining
-   * @example
-   * Glog.setLogPrefix('[Database]')
-   * Glog('Connection established') // Output: [Database] Connection established
-   */
   static setLogPrefix(prefix) {
     this.logPrefix = prefix
 
     return this
   }
 
-  /**
-   * Sets the minimum log level for messages to be displayed.
-   * Messages with a level higher than this threshold will be filtered out.
-   * Log levels range from 0 (critical) to 5 (verbose debug).
-   *
-   * @param {number} level - The minimum log level (0-5, clamped to range)
-   * @returns {typeof Glog} Returns the Glog class for method chaining
-   * @example
-   * Glog.setLogLevel(2) // Only show messages with level 0, 1, or 2
-   * Glog(1, 'Important') // Shown
-   * Glog(3, 'Verbose')   // Hidden
-   */
   static setLogLevel(level) {
     this.logLevel = Data.clamp(level, 0, 5)
 
     return this
   }
 
-  /**
-   * Internal logging method that handles message formatting and level
-   * filtering.
-   *
-   * Parses arguments to determine log level and message content, then outputs
-   * the message if it meets the current log level threshold.
-   *
-   * @private
-   * @param {...unknown} args - Variable arguments: either (level, ...messages) or (...messages)
-   * @returns {void}
-   */
-  static #log(...args) {
+  static withName(name) {
+    this.name = name
+
+    return this
+  }
+
+  static withColors(colors = loggerColours) {
+    this.colors = colors
+
+    return this
+  }
+
+  static withStackTrace(enabled = true) {
+    this.stackTrace = enabled
+
+    return this
+  }
+
+  // === FLUENT INSTANCE CREATION ===
+
+  static create(options = {}) {
+    return new Glog(options)
+  }
+
+  withName(name) {
+    this.#name = name
+
+    return this
+  }
+
+  withLogLevel(level) {
+    this.#logLevel = level
+
+    return this
+  }
+
+  withPrefix(prefix) {
+    this.#logPrefix = prefix
+
+    return this
+  }
+
+  withColors(colors = loggerColours) {
+    this.#colors = colors
+
+    return this
+  }
+
+  withStackTrace(enabled = true) {
+    this.#stackTrace = enabled
+
+    return this
+  }
+
+  // === UTILITY METHODS ===
+
+  get name() {
+    return this.#name
+  }
+
+  get debugLevel() {
+    return this.#logLevel
+  }
+
+  get options() {
+    return {
+      name: this.#name,
+      debugLevel: this.#logLevel,
+      prefix: this.#logPrefix,
+      colors: this.#colors,
+      stackTrace: this.#stackTrace
+    }
+  }
+
+  #compose(level, message, debugLevel = 0) {
+    const colors = this.#colors || Glog.colors || loggerColours
+    const name = this.#name || Glog.name || "Log"
+    const tag = Util.capitalize(level)
+
+    if(!colors) {
+      return `[${name}] ${tag}: ${message}`
+    }
+
+    if(level === "debug") {
+      const colorCode = colors[level][debugLevel] || colors[level][0]
+
+      return c`[${name}] ${colorCode}${tag}{/}: ${message}`
+    }
+
+    return c`[${name}] ${colors[level]}${tag}{/}: ${message}`
+  }
+
+  // Stack trace functionality - simplified for now
+  extractFileFunction() {
+    // Simple fallback - just return a basic tag
+    return "caller"
+  }
+
+  newDebug(tag) {
+    return function(message, level, ...arg) {
+      if(this.#stackTrace || Glog.stackTrace) {
+        tag = this.extractFileFunction()
+      }
+
+      this.debug(`[${tag}] ${message}`, level, ...arg)
+    }.bind(this)
+  }
+
+  // === LOGGING METHODS ===
+
+  #log(...args) {
+    let level, rest
+
+    if(args.length === 0) {
+      [level = 0, rest = [""]] = []
+    } else if(args.length === 1) {
+      [rest, level = 0] = [args, 0]
+    } else {
+      [level, ...rest] = typeof args[0] === "number" ? args : [0, ...args]
+    }
+
+    const currentLevel = this.#logLevel || Glog.logLevel
+
+    if(level > currentLevel)
+      return
+
+    const prefix = this.#logPrefix || Glog.logPrefix
+
+    if(prefix) {
+      Term.log(prefix, ...rest)
+    } else {
+      Term.log(...rest)
+    }
+  }
+
+  // Traditional logger methods
+  debug(message, level = 0, ...arg) {
+    const currentLevel = this.#logLevel || Glog.logLevel
+
+    if(level <= currentLevel) {
+      Term.debug(this.#compose("debug", message, level), ...arg)
+    }
+  }
+
+  info(message, ...arg) {
+    Term.info(this.#compose("info", message), ...arg)
+    this.#vscodeInfo?.(JSON.stringify(message))
+  }
+
+  warn(message, ...arg) {
+    Term.warn(this.#compose("warn", message), ...arg)
+    this.#vscodeWarn?.(JSON.stringify(message))
+  }
+
+  error(message, ...arg) {
+    Term.error(this.#compose("error", message), ...arg)
+    this.#vscodeError?.(JSON.stringify(message))
+  }
+
+  // Core execute method for simple usage
+  static execute(...args) {
+    // Use static properties for global calls
     let level, rest
 
     if(args.length === 0) {
-      ;[level=0, rest=[""]] = []
+      [level = 0, rest = [""]] = []
     } else if(args.length === 1) {
-      ;[rest, level=0] = [args, 0]
+      [rest, level = 0] = [args, 0]
     } else {
-      ;[level, ...rest] = typeof args[0] === "number" ? args : [0, ...args]
+      [level, ...rest] = typeof args[0] === "number" ? args : [0, ...args]
     }
 
     if(level > this.logLevel)
       return
 
-    if(this.logPrefix)
-      console.log(this.logPrefix, ...rest)
-    else
-      console.log(...rest)
+    if(this.logPrefix) {
+      Term.log(this.logPrefix, ...rest)
+    } else {
+      Term.log(...rest)
+    }
+  }
+
+  // Instance execute for configured loggers
+  execute(...args) {
+    this.#log(...args)
   }
 
+  // === ENHANCED METHODS WITH @gesslar/colours ===
+
   /**
-   * Executes a log operation with the provided arguments.
-   * This method serves as the entry point for all logging operations,
-   * delegating to the private #log method for actual processing.
+   * Log a colorized message using template literals
    *
-   * @param {...unknown} args - Log level (optional) followed by message arguments
-   * @returns {void}
-   * @example
-   * Glog.execute(0, 'Error:', error.message)
-   * Glog.execute('Simple message') // Level 0 assumed
+   * @param {Array<string>} strings - Template strings
+   * @param {...unknown} values - Template values
+   * @example logger.colorize`{success}Operation completed{/} in {bold}${time}ms{/}`
    */
-  static execute(...args) {
-    this.#log(...args)
+  colorize(strings, ...values) {
+    const message = c(strings, ...values)
+    const name = this.#name || Glog.name || "Log"
+
+    Term.log(`[${name}] ${message}`)
+  }
+
+  /**
+   * Static version of colorize for global usage
+   *
+   * @param {Array<string>} strings - Template strings
+   * @param {...unknown} values - Template values
+   */
+  static colorize(strings, ...values) {
+    const message = c(strings, ...values)
+    const name = this.name || "Log"
+
+    Term.log(`[${name}] ${message}`)
+  }
+
+  /**
+   * Log a success message with green color
+   *
+   * @param {string} message - Success message
+   * @param {...unknown} args - Additional arguments
+   */
+  success(message, ...args) {
+    Term.log(c`[${this.#name || Glog.name || "Log"}] {success}Success{/}: ${message}`, ...args)
+  }
+
+  /**
+   * Static success method
+   *
+   * @param {string} message - Success message to log
+   * @param {...unknown} args - Additional arguments to log
+   */
+  static success(message, ...args) {
+    Term.log(c`[${this.name || "Log"}] {success}Success{/}: ${message}`, ...args)
+  }
+
+  /**
+   * Set a color alias for convenient usage
+   *
+   * @param {string} alias - Alias name
+   * @param {string} colorCode - Color code (e.g., "{F196}" or "{<B}")
+   * @returns {Glog} The Glog class for chaining.
+   */
+  static setAlias(alias, colorCode) {
+    c.alias.set(alias, colorCode)
+
+    return this
+  }
+
+  /**
+   * Get access to the colours template function for instance usage
+   *
+   * @returns {import('@gesslar/colours')} The colours template function from \@gesslar/colours
+   */
+  get colours() {
+    return c
   }
 }
 
-/**
- * Global logging utility with proxy-based dual interface.
- * Can be used as both a class and a function for maximum flexibility.
- *
- * @class Glog
- * @example
- * // Use as function
- * Glog('Hello world')
- * Glog(2, 'Debug message')
- *
- * // Use class methods
- * Glog.setLogLevel(3).setLogPrefix('[App]')
- */
-// Wrap the class in a proxy
+// Wrap in proxy for dual usage
 export default new Proxy(Glog, {
   apply(target, thisArg, argumentsList) {
-    // When called as function: call execute method internally
     return target.execute(...argumentsList)
   },
   construct(target, argumentsList) {
     return new target(...argumentsList)
   },
   get(target, prop) {
-    // Hide execute method from public API
     if(prop === "execute") {
       return undefined
     }

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/Tantrum.js

@@ -0,0 +1,70 @@
+/**
+ * @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
+    )
+
+    this.errors.forEach(error => {
+      Term.error("\n")
+      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/FileObject.d.ts

@@ -326,4 +326,27 @@ export default class FileObject extends FS {
 
   /** Load an object from JSON5 or YAML file with type specification */
   loadData(type?: 'json' | 'json5' | 'yaml' | 'any', encoding?: string): Promise<unknown>
+
+  /**
+   * Dynamically import the file using the resolved file URI.
+   *
+   * Uses Node.js' native dynamic `import()` under the hood, allowing consumers to load
+   * ESM modules from disk with full path resolution handled by FileObject. The method
+   * verifies the file exists before attempting the import to provide clearer error
+   * messaging and prevent low-level loader failures.
+   *
+   * @typeParam TModule - Expected module shape. Defaults to a loose record to help with
+   * module namespace typing.
+   *
+   * @returns The imported module namespace object.
+   *
+   * @throws {Error} When the file does not exist or the path cannot be converted to a URI.
+   *
+   * @example
+   * ```typescript
+   * const configModule = await file.import<{ default: Config }>()
+   * const config = configModule.default
+   * ```
+   */
+  import<TModule = Record<string, unknown>>(): Promise<TModule>
 }

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'