@gesslar/toolkit 0.2.9 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gesslar/toolkit",
-  "version": "0.2.9",
+  "version": "0.3.0",
   "description": "Get in, bitches, we're going toolkitting.",
   "main": "./src/index.js",
   "type": "module",
@@ -25,7 +25,8 @@
     "submit": "npm publish --access public",
     "update": "npx npm-check-updates -u && npm install",
     "test": "node --test tests/unit/*.test.js",
-    "test:unit": "node --test tests/unit/*.test.js"
+    "test:unit": "node --test tests/unit/*.test.js",
+    "pr": "gt submit --cli --publish --restack --ai --merge-when-ready"
   },
   "repository": {
     "type": "git",

package/src/lib/ActionRunner.js

@@ -19,7 +19,7 @@ export default class ActionRunner {
   constructor({action, build, logger}) {
     this.#action = action
     this.#build = build
-    this.#logger = logger ?? Glog.newDebug()
+    this.#logger = logger ?? {newDebug: () => () => {}}
   }
 
   /**

package/src/lib/BaseActionManager.js

@@ -0,0 +1,246 @@
+import Data from "./Data.js"
+import Sass from "./Sass.js"
+import ActionBuilder from "./ActionBuilder.js"
+import ActionRunner from "./ActionRunner.js"
+
+/**
+ * Generic base class for managing actions with lifecycle hooks.
+ * Provides common functionality for action setup, execution, and cleanup.
+ * Designed to be extended by specific implementations.
+ */
+export default class BaseActionManager {
+  #action = null
+  #hookManager = null
+  #contract = null
+  #log = null
+  #debug = null
+  #file = null
+  #variables = null
+  #runner = null
+  #id = null
+
+  /**
+   * @param {object} config - Configuration object
+   * @param {object} config.actionDefinition - Action definition with action, file, and contract
+   * @param {object} config.logger - Logger instance
+   * @param {object} [config.variables] - Variables to pass to action
+   */
+  constructor({actionDefinition, logger, variables}) {
+    this.#id = Symbol(performance.now())
+    this.#log = logger
+    this.#debug = this.#log.newDebug()
+    this.#variables = variables || {}
+
+    this.#initialize(actionDefinition)
+  }
+
+  get id() {
+    return this.#id
+  }
+
+  get action() {
+    return this.#action
+  }
+
+  get hookManager() {
+    return this.#hookManager
+  }
+
+  set hookManager(hookManager) {
+    if (this.hookManager)
+      throw new Error("Hook manager already set")
+
+    this.#hookManager = hookManager
+    this.#attachHooksToAction(hookManager)
+  }
+
+  get contract() {
+    return this.#contract
+  }
+
+  get meta() {
+    return this.#action?.meta
+  }
+
+  get log() {
+    return this.#log
+  }
+
+  get variables() {
+    return this.#variables
+  }
+
+  get runner() {
+    return this.#runner
+  }
+
+  get file() {
+    return this.#file
+  }
+
+  /**
+   * Initialize the action manager with the provided definition.
+   * Override in subclasses to add specific validation or setup.
+   * 
+   * @param {object} actionDefinition - Action definition
+   * @protected
+   */
+  #initialize(actionDefinition) {
+    const debug = this.#debug
+
+    debug("Setting up action", 2)
+
+    const {action, file, contract} = actionDefinition
+
+    if (!action)
+      throw new Error("Action is required")
+
+    if (!contract)
+      throw new Error("Contract is required")
+
+    this.#action = action
+    this.#contract = contract
+    this.#file = file
+
+    debug("Action initialization complete", 2)
+  }
+
+  /**
+   * Attach hooks to the action instance.
+   * Override in subclasses to customize hook attachment.
+   * 
+   * @param {object} hookManager - Hook manager instance
+   * @protected
+   */
+  #attachHooksToAction(hookManager) {
+    // Basic hook attachment - can be overridden by subclasses
+    this.action.hook = hookManager.on?.bind(hookManager)
+    this.action.hooks = hookManager.hooks
+  }
+
+  /**
+   * Setup the action by creating and configuring the runner.
+   * Override setupActionInstance() in subclasses for custom setup logic.
+   * 
+   * @returns {Promise<void>}
+   */
+  async setupAction() {
+    this.#debug("Setting up action for %s on %s", 2, this.action.meta?.kind, this.id)
+
+    await this.#setupHooks()
+    await this.#setupActionInstance()
+  }
+
+  /**
+   * Setup the action instance and create the runner.
+   * Override in subclasses to customize action setup.
+   * 
+   * @protected
+   */
+  async #setupActionInstance() {
+    const actionInstance = new this.action()
+    const setup = actionInstance?.setup
+
+    // Setup is required for actions.
+    if (Data.typeOf(setup) === "Function") {
+      const builder = new ActionBuilder(actionInstance)
+      const configuredBuilder = setup(builder)
+      const buildResult = configuredBuilder.build()
+      const runner = new ActionRunner({
+        action: buildResult.action,
+        build: buildResult.build,
+        logger: this.#log
+      })
+
+      this.#runner = runner
+    } else {
+      throw Sass.new("Action setup must be a function.")
+    }
+  }
+
+  /**
+   * Run the action with the provided input.
+   * 
+   * @param {unknown} result - Input to pass to the action
+   * @returns {Promise<unknown>} Action result
+   */
+  async runAction(result) {
+    if (!this.#runner)
+      throw new Error("Action not set up. Call setupAction() first.")
+
+    return await this.#runner.run(result)
+  }
+
+  /**
+   * Cleanup the action and hooks.
+   * 
+   * @returns {Promise<void>}
+   */
+  async cleanupAction() {
+    this.#debug("Cleaning up action for %s on %s", 2, this.action.meta?.kind, this.id)
+
+    await this.#cleanupHooks()
+    await this.#cleanupActionInstance()
+  }
+
+  /**
+   * Setup hooks if hook manager is present.
+   * Override in subclasses to customize hook setup.
+   * 
+   * @protected
+   */
+  async #setupHooks() {
+    const setup = this.#hookManager?.setup
+
+    const type = Data.typeOf(setup)
+
+    // No hooks attached.
+    if (type === "Null" || type === "Undefined")
+      return
+
+    if (type !== "Function")
+      throw Sass.new("Hook setup must be a function.")
+
+    await setup.call(
+      this.hookManager.hooks, {
+        action: this.action,
+        variables: this.#variables,
+        log: this.#log
+      }
+    )
+  }
+
+  /**
+   * Cleanup hooks if hook manager is present.
+   * Override in subclasses to customize hook cleanup.
+   * 
+   * @protected
+   */
+  async #cleanupHooks() {
+    const cleanup = this.hookManager?.cleanup
+
+    if (!cleanup)
+      return
+
+    await cleanup.call(this.hookManager.hooks)
+  }
+
+  /**
+   * Cleanup the action instance.
+   * Override in subclasses to add custom cleanup logic.
+   * 
+   * @protected
+   */
+  async #cleanupActionInstance() {
+    const cleanup = this.action?.cleanup
+
+    if (!cleanup)
+      return
+
+    await cleanup.call(this.action)
+  }
+
+  toString() {
+    return `${this.#file?.module || "UNDEFINED"} (${this.meta?.action || "UNDEFINED"})`
+  }
+}

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/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

@@ -26,13 +26,11 @@ export default class Tantrum extends AggregateError {
   constructor(message, errors = []) {
     // Auto-wrap plain errors in Sass, keep existing Sass instances
     const wrappedErrors = errors.map(error => {
-      if(error instanceof Sass) {
+      if(error instanceof Sass)
         return error
-      }
 
-      if(!(error instanceof 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)
     })
@@ -51,8 +49,9 @@ export default class Tantrum extends AggregateError {
       this.message
     )
 
+    Term.error()
+
     this.errors.forEach(error => {
-      Term.error("\n")
       error.report(nerdMode)
     })
   }