@gesslar/toolkit 0.4.0 → 0.6.0

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)
-    ) : []
-  }
-}

package/src/lib/Piper.js

@@ -1,181 +0,0 @@
-/**
- * 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
-  }
-}