@gesslar/toolkit 0.5.0 → 0.7.0

package/src/lib/ActionRunner.js

@@ -1,79 +0,0 @@
-import ActionBuilder, {ACTIVITY} from "./ActionBuilder.js"
-import Piper from "./Piper.js"
-import Sass from "./Sass.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
-  #hooks = null
-
-  constructor({action, build}, hooks) {
-    this.#action = action
-    this.#build = build
-    this.#hooks = hooks
-  }
-
-  /**
-   * 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 activities = this.#build.activities
-
-    if(!activities.size)
-      throw Sass.new("No activities defined in action.")
-
-    const result = content
-    const action = this.#action
-
-    for(const [name,activity] of activities) {
-      const {op} = activity
-
-      if(activity.kind === ACTIVITY.ONCE) {
-        this.#hooks && await this.#hooks.callHook("before", name, result)
-
-        if(!await op.call(action, result))
-          break
-
-        this.#hooks && await this.#hooks.callHook("after", name, result)
-      } else if(activity.kind == ACTIVITY.MANY) {
-        for(;;) {
-
-          this.#hooks && await this.#hooks.callHook("before", name, result)
-
-          if(!await op.call(action, result))
-            break
-
-          this.#hooks && await this.#hooks.callHook("after", name, 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 builder = op.build()
-        const piper = new Piper()
-          .addStep(item => {
-            const runner = new ActionRunner(builder, this.#hooks)
-
-            return runner.run(item)
-          }, {name: `Process Parallel ActionRunner Activity`,})
-
-        await piper.pipe(result.value)
-      }
-    }
-
-    return result
-  }
-}

package/src/lib/Hooks.js

@@ -1,194 +0,0 @@
-import {setTimeout as timeout} from "timers/promises"
-
-import FileObject from "./FileObject.js"
-import Sass from "./Sass.js"
-import Util from "./Util.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 Hooks {
-  #hooksFile = null
-  #hooks = null
-  #actionKind = null
-  #timeout = 1000 // Default 1 second timeout
-  #debug = null
-
-  /**
-   * Creates a new BaseHookManager instance.
-   *
-   * @param {object} config - Configuration object
-   * @param {string} config.actionKind - Action identifier
-   * @param {FileObject} config.hooksFile - File object containing hooks with uri property
-   * @param {number} [config.hookTimeout] - Hook execution timeout in milliseconds
-   * @param {unknown} [config.hooks] - The hooks object
-   * @param {import('../types.js').DebugFunction} debug - Debug function from Glog.
-   */
-  constructor({actionKind, hooksFile, hooks, hookTimeout = 1000}, debug) {
-    this.#actionKind = actionKind
-    this.#hooksFile = hooksFile
-    this.#hooks = hooks
-    this.#timeout = hookTimeout
-    this.#debug = debug
-  }
-
-  /**
-   * Gets the action identifier.
-   *
-   * @returns {string} Action identifier or instance
-   */
-  get actionKind() {
-    return this.#actionKind
-  }
-
-  /**
-   * Gets the hooks file object.
-   *
-   * @returns {FileObject} File object containing hooks
-   */
-  get hooksFile() {
-    return this.#hooksFile
-  }
-
-  /**
-   * Gets the loaded hooks object.
-   *
-   * @returns {object|null} Hooks object or null if not loaded
-   */
-  get hooks() {
-    return this.#hooks
-  }
-
-  /**
-   * Gets the hook execution timeout in milliseconds.
-   *
-   * @returns {number} Timeout in milliseconds
-   */
-  get timeout() {
-    return this.#timeout
-  }
-
-  /**
-   * Gets the setup hook function if available.
-   *
-   * @returns {(args: object) => unknown|null} Setup hook function or null
-   */
-  get setup() {
-    return this.hooks?.setup || null
-  }
-
-  /**
-   * Gets the cleanup hook function if available.
-   *
-   * @returns {(args: object) => unknown|null} Cleanup hook function or null
-   */
-  get cleanup() {
-    return this.hooks?.cleanup || null
-  }
-
-  /**
-   * Static factory method to create and initialize a hook manager.
-   * Loads hooks from the specified file and returns an initialized instance.
-   * Override loadHooks() in subclasses to customize hook loading logic.
-   *
-   * @param {object} config - Same configuration object as constructor
-   * @param {string|object} config.actionKind - Action identifier or instance
-   * @param {FileObject} config.hooksFile - File object containing hooks with uri property
-   * @param {number} [config.timeOut] - Hook execution timeout in milliseconds
-   * @param {import('../types.js').DebugFunction} debug - The debug function.
-   * @returns {Promise<Hooks|null>} Initialized hook manager or null if no hooks found
-   */
-  static async new(config, debug) {
-    debug("Creating new HookManager instance with args: %o", 2, config)
-
-    const instance = new this(config, debug)
-    const hooksFile = instance.hooksFile
-
-    debug("Loading hooks from %o", 2, hooksFile.uri)
-
-    debug("Checking hooks file exists: %o", 2, hooksFile.uri)
-    if(!await hooksFile.exists)
-      throw Sass.new(`No such hooks file, ${hooksFile.uri}`)
-
-    try {
-      const hooksImport = await hooksFile.import()
-
-      if(!hooksImport)
-        return null
-
-      debug("Hooks file imported successfully as a module", 2)
-
-      const actionKind = instance.actionKind
-      if(!hooksImport[actionKind])
-        return null
-
-      const hooks = new hooksImport[actionKind]({debug})
-
-      debug(hooks.constructor.name, 4)
-
-      // Attach common properties to hooks
-      instance.#hooks = hooks
-
-      debug("Hooks %o loaded successfully for %o", 2, hooksFile.uri, instance.actionKind)
-
-      return instance
-    } catch(error) {
-      debug("Failed to load hooks %o: %o", 1, hooksFile.uri, error.message)
-
-      return null
-    }
-  }
-
-  async callHook(kind, activityName, context) {
-    try {
-      const debug = this.#debug
-      const hooks = this.#hooks
-
-      if(!hooks)
-        return
-
-      const hookName = `${kind}$${activityName}`
-
-      debug("Looking for hook: %o", 4, hookName)
-
-      const hook = hooks[hookName]
-      if(!hook)
-        return
-
-      debug("Triggering hook: %o", 4, hookName)
-      Valid.type(hook, "Function", `Hook "${hookName}" is not a function`)
-
-      const hookFunction = async() => {
-        debug("Hook function starting execution: %o", 4, hookName)
-
-        const duration = (await Util.time(() => hook.call(this.#hooks, context))).cost
-
-        debug("Hook function completed successfully: %o, after %oms", 4, hookName, duration)
-      }
-
-      const hookTimeout = this.timeout
-      const expireAsync = (async() => {
-        await timeout(hookTimeout)
-        throw Sass.new(`Hook ${hookName} execution exceeded timeout of ${hookTimeout}ms`)
-      })()
-
-      try {
-        debug("Starting Promise race for hook: %o", 4, hookName)
-        await Util.race([
-          hookFunction(),
-          expireAsync
-        ])
-      } catch(error) {
-        throw Sass.new(`Processing hook ${kind}$${activityName}`, error)
-      }
-
-      debug("We made it throoough the wildernessss", 4)
-
-    } catch(error) {
-      throw Sass.new(`Processing hook ${kind}$${activityName}`, error)
-    }
-  }
-}

package/src/lib/Piper.js

@@ -1,155 +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
- */
-
-import Glog from "./Glog.js"
-import Sass from "./Sass.js"
-import Tantrum from "./Tantrum.js"
-import Util from "./Util.js"
-
-export default class Piper {
-  #debug
-
-  #lifeCycle = new Map([
-    ["setup", new Set()],
-    ["process", new Set()],
-    ["teardown", new Set()]
-  ])
-
-  constructor(arg) {
-    this.#debug = arg?.debug ?? new Glog().newDebug("[PIPER]")
-  }
-
-  /**
-   * Add a processing step to the pipeline
-   *
-   * @param {(context: object) => Promise<object>} fn - Function that processes an item: (context) => Promise<result>
-   * @param {object} options - Step options (name, required, etc.)
-   * @returns {Piper} The pipeline instance (for chaining)
-   */
-  addStep(fn, options = {}) {
-    this.#lifeCycle.get("process").add({
-      fn,
-      name: options.name || `Step ${this.#lifeCycle.get("process").size + 1}`,
-      required: !!options.required, // Default to required
-      ...options
-    })
-
-    return this
-  }
-
-  /**
-   * Add setup hook that runs before processing starts
-   *
-   * @param {() => Promise<void>} fn - Setup function: () => Promise<void>
-   * @returns {Piper} The pipeline instance (for chaining)
-   */
-  addSetup(fn) {
-    this.#lifeCycle.get("setup").add(fn)
-
-    return this
-  }
-
-  /**
-   * Add cleanup hook that runs after processing completes
-   *
-   * @param {() => Promise<void>} fn - Cleanup function: () => Promise<void>
-   * @returns {Piper} The pipeline instance (for chaining)
-   */
-  addCleanup(fn) {
-    this.#lifeCycle.get("teardown").add(fn)
-
-    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) {
-    items.forEach(item => item.pipeStamp = Symbol(performance.now()))
-
-    let itemIndex = 0
-    const allResults = []
-
-    const processWorker = async() => {
-      while(true) {
-        const currentIndex = itemIndex++
-        if(currentIndex >= items.length)
-          break
-
-        const item = items[currentIndex]
-        try {
-          const result = await this.#processItem(item)
-          allResults.push(result)
-        } catch(error) {
-          throw Sass.new("Processing pipeline item.", error)
-        }
-      }
-    }
-
-    const setupResult = await Util.settleAll([...this.#lifeCycle.get("setup")].map(e => e()))
-    this.#processResult("Setting up the pipeline.", setupResult)
-
-    // Start workers up to maxConcurrent limit
-    const workers = []
-    const workerCount = Math.min(maxConcurrent, items.length)
-
-    for(let i = 0; i < workerCount; i++)
-      workers.push(processWorker())
-
-    // Wait for all workers to complete
-    const processResult = await Util.settleAll(workers)
-    this.#processResult("Processing pipeline.", processResult)
-
-    // Run cleanup hooks
-    const teardownResult = await Util.settleAll([...this.#lifeCycle.get("teardown")].map(e => e()))
-    this.#processResult("Tearing down the pipeline.", teardownResult)
-
-    return allResults
-  }
-
-  #processResult(message, settled) {
-    if(settled.some(r => r.status === "rejected"))
-      throw Tantrum.new(
-        message,
-        settled.filter(r => r.status==="rejected").map(r => r.reason)
-      )
-  }
-
-  /**
-   * 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.#debug
-
-    try {
-      // Execute each step in sequence
-      let result = item
-
-      for(const step of this.#lifeCycle.get("process")) {
-        debug("Executing step: %o", 2, step.name)
-
-        result = await step.fn(result) ?? result
-      }
-
-      return result
-    } catch(error) {
-      throw Sass.new("Processing an item.", error)
-    }
-  }
-}