@gesslar/toolkit 0.2.8 → 0.3.0

package/src/lib/BaseHookManager.js

@@ -0,0 +1,206 @@
+import { setTimeout as timeoutPromise } from "timers/promises"
+import Collection from "./Collection.js"
+import Data from "./Data.js"
+import Sass from "./Sass.js"
+import Valid from "./Valid.js"
+
+/**
+ * Generic base class for managing hooks with configurable event types.
+ * Provides common functionality for hook registration, execution, and lifecycle management.
+ * Designed to be extended by specific implementations.
+ */
+export default class BaseHookManager {
+  #hooksFile = null
+  #log = null
+  #hooks = null
+  #action = null
+  #timeout = 1000 // Default 1 second timeout
+  #allowedEvents = []
+
+  /**
+   * @param {object} config - Configuration object
+   * @param {string|object} config.action - Action identifier or instance
+   * @param {object} config.hooksFile - File object containing hooks
+   * @param {object} config.logger - Logger instance
+   * @param {number} [config.timeOut=1000] - Hook execution timeout in milliseconds
+   * @param {string[]} [config.allowedEvents=[]] - Array of allowed event types for validation
+   */
+  constructor({action, hooksFile, logger, timeOut = 1000, allowedEvents = []}) {
+    this.#action = action
+    this.#hooksFile = hooksFile
+    this.#log = logger
+    this.#timeout = timeOut
+    this.#allowedEvents = allowedEvents
+  }
+
+  get action() {
+    return this.#action
+  }
+
+  get hooksFile() {
+    return this.#hooksFile
+  }
+
+  get hooks() {
+    return this.#hooks
+  }
+
+  get log() {
+    return this.#log
+  }
+
+  get timeout() {
+    return this.#timeout
+  }
+
+  get allowedEvents() {
+    return this.#allowedEvents
+  }
+
+  get setup() {
+    return this.hooks?.setup || null
+  }
+
+  get cleanup() {
+    return this.hooks?.cleanup || null
+  }
+
+  /**
+   * Static factory method to create and initialize a hook manager.
+   * Override loadHooks() in subclasses to customize hook loading logic.
+   * 
+   * @param {object} config - Same as constructor config
+   * @returns {Promise<BaseHookManager|null>} Initialized hook manager or null if no hooks found
+   */
+  static async new(config) {
+    const instance = new this(config)
+    const debug = instance.log.newDebug()
+
+    debug("Creating new HookManager instance with args: `%o`", 2, config)
+
+    const hooksFile = instance.hooksFile
+
+    debug("Loading hooks from `%s`", 2, hooksFile.uri)
+
+    debug("Checking hooks file exists: %j", 2, hooksFile)
+    
+    try {
+      const hooksFileContent = await import(hooksFile.uri)
+      debug("Hooks file loaded successfully", 2)
+
+      if (!hooksFileContent)
+        throw new Error(`Hooks file is empty: ${hooksFile.uri}`)
+
+      const hooks = await instance.loadHooks(hooksFileContent)
+      
+      if (Data.isEmpty(hooks))
+        return null
+
+      debug("Hooks found for action: `%s`", 2, instance.action)
+
+      if (!hooks)
+        return null
+
+      // Attach common properties to hooks
+      hooks.log = instance.log
+      hooks.timeout = instance.timeout
+      instance.#hooks = hooks
+
+      debug("Hooks loaded successfully for `%s`", 2, instance.action)
+
+      return instance
+    } catch (error) {
+      debug("Failed to load hooks: %s", 1, error.message)
+      return null
+    }
+  }
+
+  /**
+   * Load hooks from the imported hooks file content.
+   * Override in subclasses to customize hook loading logic.
+   * 
+   * @param {object} hooksFileContent - Imported hooks file content
+   * @returns {Promise<object|null>} Loaded hooks object or null if no hooks found
+   * @protected
+   */
+  async loadHooks(hooksFileContent) {
+    const hooks = hooksFileContent.default || hooksFileContent.Hooks
+
+    if (!hooks)
+      throw new Error(`\`${this.hooksFile.uri}\` contains no hooks.`)
+
+    // Default implementation: look for hooks by action name
+    const hooksObj = hooks[this.action]
+
+    return hooksObj || null
+  }
+
+  /**
+   * Trigger a hook by event name.
+   * 
+   * @param {string} event - The type of hook to trigger
+   * @param {object} args - The hook arguments as an object
+   * @returns {Promise<unknown>} The result of the hook
+   */
+  async on(event, args) {
+    const debug = this.log.newDebug()
+
+    debug("Triggering hook for event `%s`", 4, event)
+
+    if (!event)
+      throw new Error("Event type is required for hook invocation")
+
+    // Validate event type if allowed events are configured
+    if (this.#allowedEvents.length > 0 && !this.#allowedEvents.includes(event))
+      throw new Error(`Invalid event type: ${event}. Allowed events: ${this.#allowedEvents.join(", ")}`)
+
+    const hook = this.hooks?.[event]
+
+    if (hook) {
+      Valid.type(hook, "function", `Hook "${event}" is not a function`)
+
+      const hookExecution = hook.call(this.hooks, args)
+      const hookTimeout = this.timeout
+      
+      const expireAsync = () =>
+        timeoutPromise(
+          hookTimeout,
+          new Error(`Hook execution exceeded timeout of ${hookTimeout}ms`)
+        )
+
+      const result = await Promise.race([hookExecution, expireAsync()])
+
+      if (result?.status === "error")
+        throw Sass.new(result.error)
+
+      debug("Hook executed successfully for event: `%s`", 4, event)
+
+      return result
+    } else {
+      debug("No hook found for event: `%s`", 4, event)
+      return null
+    }
+  }
+
+  /**
+   * Check if a hook exists for the given event.
+   * 
+   * @param {string} event - Event name to check
+   * @returns {boolean} True if hook exists
+   */
+  hasHook(event) {
+    return !!(this.hooks?.[event])
+  }
+
+  /**
+   * Get all available hook events.
+   * 
+   * @returns {string[]} Array of available hook event names
+   */
+  getAvailableEvents() {
+    return this.hooks ? Object.keys(this.hooks).filter(key => 
+      typeof this.hooks[key] === 'function' && 
+      !['setup', 'cleanup', 'log', 'timeout'].includes(key)
+    ) : []
+  }
+}

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
     }