@gesslar/toolkit 0.4.0 → 0.5.0

package/src/lib/Glog.js

@@ -1,7 +1,8 @@
-import Data from "./Data.js"
-import Util from "./Util.js"
 import c from "@gesslar/colours"
+
+import Data from "./Data.js"
 import Term from "./Term.js"
+import Util from "./Util.js"
 // ErrorStackParser will be dynamically imported when needed
 
 /**

package/src/lib/Hooks.js

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

@@ -9,31 +9,36 @@
  * - 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 {
-  #succeeded = []
-  #warned = []
-  #errored = []
-  #steps = []
-  #setupHooks = []
-  #cleanupHooks = []
-  #logger
-
-  constructor(options = {}) {
-    this.#logger = options.logger || {newDebug: () => () => {}}
+  #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>} stepFn - Function that processes an item: (context) => Promise<result>
+   * @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(stepFn, options = {}) {
-    this.#steps.push({
-      fn: stepFn,
-      name: options.name || `Step ${this.#steps.length + 1}`,
-      required: options.required !== false, // Default to required
+  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
     })
 
@@ -43,11 +48,11 @@ export default class Piper {
   /**
    * Add setup hook that runs before processing starts
    *
-   * @param {() => Promise<void>} setupFn - Setup function: () => Promise<void>
+   * @param {() => Promise<void>} fn - Setup function: () => Promise<void>
    * @returns {Piper} The pipeline instance (for chaining)
    */
-  addSetup(setupFn) {
-    this.#setupHooks.push(setupFn)
+  addSetup(fn) {
+    this.#lifeCycle.get("setup").add(fn)
 
     return this
   }
@@ -55,11 +60,11 @@ export default class Piper {
   /**
    * Add cleanup hook that runs after processing completes
    *
-   * @param {() => Promise<void>} cleanupFn - Cleanup function: () => Promise<void>
+   * @param {() => Promise<void>} fn - Cleanup function: () => Promise<void>
    * @returns {Piper} The pipeline instance (for chaining)
    */
-  addCleanup(cleanupFn) {
-    this.#cleanupHooks.push(cleanupFn)
+  addCleanup(fn) {
+    this.#lifeCycle.get("teardown").add(fn)
 
     return this
   }
@@ -72,50 +77,54 @@ export default class Piper {
    * @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})
+    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)
         }
-
-        // 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()
+    const setupResult = await Util.settleAll([...this.#lifeCycle.get("setup")].map(e => e()))
+    this.#processResult("Setting up the pipeline.", setupResult)
 
-      activePromises.push(processNextItem(item))
-    }
+    // 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 processing to complete
-    await Promise.allSettled(activePromises)
+    // Wait for all workers to complete
+    const processResult = await Util.settleAll(workers)
+    this.#processResult("Processing pipeline.", processResult)
 
     // Run cleanup hooks
-    await Promise.allSettled(this.#cleanupHooks.map(hook => hook()))
+    const teardownResult = await Util.settleAll([...this.#lifeCycle.get("teardown")].map(e => e()))
+    this.#processResult("Tearing down the pipeline.", teardownResult)
 
-    return {
-      succeeded: this.#succeeded,
-      warned: this.#warned,
-      errored: this.#errored
-    }
+    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)
+      )
   }
 
   /**
@@ -126,56 +135,21 @@ export default class Piper {
    * @private
    */
   async #processItem(item) {
-    const debug = this.#logger.newDebug()
-    const context = {item, data: {}}
+    const debug = this.#debug
 
     try {
       // Execute each step in sequence
-      for(const step of this.#steps) {
-        debug(`Executing step: ${step.name}`, 2)
-
-        const result = await step.fn(context)
+      let result = item
 
-        // Handle step result
-        if(result && typeof result === "object") {
-          if(result.status === "error") {
-            return result
-          }
+      for(const step of this.#lifeCycle.get("process")) {
+        debug("Executing step: %o", 2, step.name)
 
-          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
+        result = await step.fn(result) ?? result
       }
 
+      return result
     } catch(error) {
-      return {
-        status: "error",
-        error,
-        item
-      }
+      throw Sass.new("Processing an item.", error)
     }
   }
-
-  /**
-   * Clear results (useful for reusing pipeline instance)
-   *
-   * @returns {Piper} The pipeline instance (for chaining)
-   */
-  clearResults() {
-    this.#succeeded = []
-    this.#warned = []
-    this.#errored = []
-
-    return this
-  }
 }

package/src/lib/Schemer.js

@@ -0,0 +1,89 @@
+import Ajv from "ajv"
+
+import Data from "./Data.js"
+import Util from "./Util.js"
+import Valid from "./Valid.js"
+
+/**
+ * Schemer provides utilities for compiling and validating JSON schemas using AJV.
+ *
+ * Usage:
+ *   - Use Schemer.fromFile(file, options) to create a validator from a file.
+ *   - Use Schemer.from(schemaData, options) to create a validator from a schema object.
+ *   - Use Schemer.getValidator(schema, options) to get a raw AJV validator function.
+ *   - Use Schemer.reportValidationErrors(errors) to format AJV validation errors.
+ */
+export default class Schemer {
+  static async fromFile(file, options={}) {
+    Valid.type(file, "FileObject")
+    Valid.assert(Data.isPlainObject(options), "Options must be a plain object.")
+
+    const schemaData = await file.loadData()
+
+    return Schemer.getValidator(schemaData, options)
+  }
+
+  static async from(schemaData={}, options={}) {
+    Valid.assert(Data.isPlainObject(schemaData), "Schema data must be a plain object.")
+    Valid.assert(Data.isPlainObject(options), "Options must be a plain object.")
+
+    return Schemer.getValidator(schemaData, options)
+  }
+
+  /**
+   * Creates a validator function from a schema object
+   *
+   * @param {object} schema - The schema to compile
+   * @param {object} [options] - AJV options
+   * @returns {(data: unknown) => boolean} The AJV validator function, which may have additional properties (e.g., `.errors`)
+   */
+  static getValidator(schema, options = {allErrors: true, verbose: true}) {
+    const ajv = new Ajv(options)
+
+    return ajv.compile(schema)
+  }
+
+  static reportValidationErrors(errors) {
+    if(!errors) {
+      return ""
+    }
+
+    return errors.reduce((errorMessages, error) => {
+      let msg = `- "${error.instancePath || "(root)"}" ${error.message}`
+
+      if(error.params) {
+        const details = []
+
+        if(error.params.type)
+          details.push(`  ➜ Expected type: ${error.params.type}`)
+
+        if(error.params.missingProperty)
+          details.push(`  ➜ Missing required field: ${error.params.missingProperty}`)
+
+        if(error.params.allowedValues) {
+          details.push(`  ➜ Allowed values: "${error.params.allowedValues.join('", "')}"`)
+          details.push(`  ➜ Received value: "${error.data}"`)
+          const closestMatch =
+            Util.findClosestMatch(error.data, error.params.allowedValues)
+
+          if(closestMatch)
+            details.push(`  ➜ Did you mean: "${closestMatch}"?`)
+        }
+
+        if(error.params.pattern)
+          details.push(`  ➜ Expected pattern: ${error.params.pattern}`)
+
+        if(error.params.format)
+          details.push(`  ➜ Expected format: ${error.params.format}`)
+
+        if(error.params.additionalProperty)
+          details.push(`  ➜ Unexpected property: ${error.params.additionalProperty}`)
+
+        if(details.length)
+          msg += `\n${details.join("\n")}`
+      }
+
+      return errorMessages ? `${errorMessages}\n${msg}` : msg
+    }, "")
+  }
+}

package/src/lib/Terms.js

@@ -0,0 +1,74 @@
+import JSON5 from "json5"
+import yaml from "yaml"
+
+import Data from "./Data.js"
+import DirectoryObject from "./DirectoryObject.js"
+import FileObject from "./FileObject.js"
+import Sass from "./Sass.js"
+import Valid from "./Valid.js"
+
+const refex = /^ref:\/\/(?<file>.*)$/
+
+/**
+ * Terms represents an interface definition - what an action promises to provide or accept.
+ * It's just the specification, not the negotiation. Contract handles the negotiation.
+ */
+export default class Terms {
+  #definition = null
+
+  constructor(definition) {
+    this.#definition = definition
+  }
+
+  /**
+   * Parses terms data, handling file references
+   *
+   * @param {string|object} termsData - Terms data or reference
+   * @param {DirectoryObject?} directoryObject - Directory context for file resolution
+   * @returns {object} Parsed terms data
+   */
+  static async parse(termsData, directoryObject) {
+    if(Data.isBaseType(termsData, "String")) {
+      const match = refex.exec(termsData)
+
+      if(match?.groups?.file) {
+        Valid.type(directoryObject, "DirectoryObject")
+
+        const file = new FileObject(match.groups.file, directoryObject)
+
+        return await file.loadData()
+      }
+
+      // Try parsing as YAML/JSON
+      try {
+        const result = JSON5.parse(termsData)
+
+        return result
+      } catch {
+        try {
+          const result = yaml.parse(termsData)
+
+          return result
+        } catch {
+          throw Sass.new(`Could not parse terms data as YAML or JSON: ${termsData}`)
+        }
+      }
+    }
+
+    if(Data.isBaseType(termsData, "Object")) {
+      return termsData
+    }
+
+    throw Sass.new(`Invalid terms data type: ${typeof termsData}`)
+  }
+
+  /**
+   * Get the terms definition
+   *
+   * @returns {object} The terms definition
+   */
+  get definition() {
+    return this.#definition
+  }
+
+}