@gesslar/toolkit 0.4.0 → 0.5.0

package/src/lib/BaseActionManager.js

@@ -1,246 +0,0 @@
-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

@@ -1,209 +0,0 @@
-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] - 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)
-    ) : []
-  }
-}