@gesslar/toolkit 0.3.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gesslar/toolkit",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Get in, bitches, we're going toolkitting.",
   "main": "./src/index.js",
   "type": "module",
@@ -26,7 +26,7 @@
     "update": "npx npm-check-updates -u && npm install",
     "test": "node --test tests/unit/*.test.js",
     "test:unit": "node --test tests/unit/*.test.js",
-    "pr": "gt submit --cli --publish --restack --ai --merge-when-ready"
+    "pr": "gt submit --publish --restack --ai"
   },
   "repository": {
     "type": "git",
@@ -51,6 +51,7 @@
   "homepage": "https://github.com/gesslar/toolkit#readme",
   "dependencies": {
     "@gesslar/colours": "^0.0.1",
+    "ajv": "^8.17.1",
     "globby": "^15.0.0",
     "json5": "^2.2.3",
     "yaml": "^2.8.1"

package/src/index.js

@@ -6,11 +6,14 @@ export {default as FS} from "./lib/FS.js"
 // Utility classes
 export {default as Cache} from "./lib/Cache.js"
 export {default as Collection} from "./lib/Collection.js"
+export {default as Contract} from "./lib/Contract.js"
 export {default as Data} from "./lib/Data.js"
 export {default as Glog} from "./lib/Glog.js"
 export {default as Sass} from "./lib/Sass.js"
+export {default as Schemer} from "./lib/Schemer.js"
 export {default as Tantrum} from "./lib/Tantrum.js"
 export {default as Term} from "./lib/Term.js"
+export {default as Terms} from "./lib/Terms.js"
 export {default as Type} from "./lib/TypeSpec.js"
 export {default as Util} from "./lib/Util.js"
 export {default as Valid} from "./lib/Valid.js"

package/src/lib/Action.js

@@ -0,0 +1,283 @@
+import ActionBuilder from "./ActionBuilder.js"
+import ActionRunner from "./ActionRunner.js"
+import Data from "./Data.js"
+import FileObject from "./FileObject.js"
+import Hooks from "./Hooks.js"
+import Sass from "./Sass.js"
+import Terms from "./Terms.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 Action {
+  #action = null
+  #hooks = null
+  #file = null
+  #variables = null
+  #runner = null
+  #id = null
+  #debug
+
+  /**
+   * Creates a new BaseActionManager instance.
+   *
+   * @param {object} config - Configuration object
+   * @param {object} config.actionDefinition - Action definition containing action class and file info
+   * @param {object} [config.variables] - Variables to pass to action during setup
+   * @param {import('../types.js').DebugFunction} config.debug - The logger's debug function
+   */
+  constructor({actionDefinition, variables, debug}) {
+    this.#id = Symbol(performance.now())
+    this.#variables = variables || {}
+    this.#debug = debug
+
+    const {action,file} = actionDefinition
+    this.#action = action
+    this.#file = file
+  }
+  /**
+   * Gets the unique identifier for this action manager instance.
+   *
+   * @returns {symbol} Unique symbol identifier
+   */
+  get id() {
+    return this.#id
+  }
+
+  /**
+   * Gets the action class constructor.
+   *
+   * @returns {new () => object} Action class constructor
+   */
+  get action() {
+    return this.#action
+  }
+
+  /**
+   * Gets the current hook manager instance.
+   *
+   * @returns {Hooks|null} Hook manager instance or null if not set
+   */
+  get hooks() {
+    return this.#hooks
+  }
+
+  /**
+   * Sets the hook manager and attaches hooks to the action.
+   *
+   * @param {Hooks} hooks - Hook manager instance with hooks and on method.
+   * @returns {Promise<this>} Promise of this instance.
+   * @throws {Sass} If hook manager is already set.
+   */
+  setHooks(hooks) {
+    if(this.#hooks)
+      throw Sass.new("Hook manager already set")
+
+    this.#hooks = hooks
+
+    return this
+  }
+
+  // async callHook(kind, activity, action, context) {
+  //   const hooks = this.#hooks
+
+  // }
+
+  /**
+   * Gets the action metadata.
+   *
+   * @returns {object|undefined} Action metadata object
+   */
+  get meta() {
+    return this.#action?.meta
+  }
+
+  /**
+   * Gets the variables passed to the action.
+   *
+   * @returns {object} Variables object
+   */
+  get variables() {
+    return this.#variables
+  }
+
+  /**
+   * Gets the action runner instance.
+   *
+   * @returns {ActionRunner?} ActionRunner instance or null if not set up
+   */
+  get runner() {
+    return this.#runner
+  }
+
+  /**
+   * Gets the file information object.
+   *
+   * @returns {FileObject?} File information object
+   */
+  get file() {
+    return this.#file
+  }
+
+  /**
+   * Setup the action by creating and configuring the runner.
+   * This is the main public method to initialize the action for use.
+   *
+   * @returns {Promise<this>} Promise of this instance.
+   * @throws {Sass} If action setup fails
+   */
+  async setupAction() {
+    this.#debug("Setting up action for %o on %o", 2, this.#action.meta?.kind, this.id)
+
+    await this.#setupHooks()
+    await this.#setupAction()
+
+    return this
+  }
+
+  /**
+   * Setup the action instance and create the runner.
+   * Creates a new action instance, calls its setup method with an
+   * ActionBuilder, and creates an ActionRunner from the result.
+   *
+   * Can be overridden in subclasses to customize action setup.
+   *
+   * @returns {Promise<void>}
+   * @throws {Sass} If action setup method is not a function
+   * @protected
+   */
+  async #setupAction() {
+    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
+      }, this.#hooks)
+
+      this.#runner = runner
+    } else {
+      throw Sass.new("Action setup must be a function.")
+    }
+  }
+
+  /**
+   * Run the action with the provided input.
+   * The action must be set up via setupAction() before calling this method.
+   *
+   * @param {unknown} context - Input data to pass to the action runner
+   * @returns {Promise<unknown>} Result from the action execution
+   * @throws {Sass} If action is not set up
+   */
+  async runAction(context) {
+    if(!this.#runner)
+      throw Sass.new("Action not set up. Call setupAction() first.")
+
+    return await this.#runner.run(context)
+  }
+
+  /**
+   * Cleanup the action and hooks.
+   * This should be called when the action is no longer needed to free
+   * resources.
+   *
+   * Calls cleanupHooks() and cleanupActionInstance() which can be overridden.
+   *
+   * @returns {Promise<this>} Promise of this instance.
+   */
+  async cleanupAction() {
+    this.#debug("Cleaning up action for %o on %o", 2, this.#action.meta?.kind, this.id)
+
+    await this.#cleanupHooks()
+    await this.#cleanupAction()
+
+    return this
+  }
+
+  /**
+   * Setup hooks if hook manager is present.
+   * Calls the hook manager's setup function with action context.
+   * Override in subclasses to customize hook setup.
+   *
+   * @returns {Promise<void>}
+   * @throws {Sass} If hook setup is not a function
+   * @private
+   */
+  async #setupHooks() {
+    const setup = this.#hooks?.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.hooks.hooks, {
+        action: this.#action,
+        variables: this.#variables,
+      }
+    )
+  }
+
+  /**
+   * Cleanup hooks if hook manager is present.
+   * Calls the hook manager's cleanup function.
+   * Override in subclasses to customize hook cleanup.
+   *
+   * @returns {Promise<void>}
+   * @protected
+   */
+  async #cleanupHooks() {
+    const cleanup = this.hooks?.cleanup
+
+    if(!cleanup)
+      return
+
+    await cleanup.call(this.hooks.hooks)
+  }
+
+  /**
+   * Cleanup the action instance.
+   * Calls the action's cleanup method if it exists.
+   * Override in subclasses to add custom cleanup logic.
+   *
+   * @returns {Promise<void>}
+   * @protected
+   */
+  async #cleanupAction() {
+    const cleanup = this.#action?.cleanup
+
+    if(!cleanup)
+      return
+
+    await cleanup.call(this.#action)
+  }
+
+  /**
+   * Returns a string representation of this action manager.
+   *
+   * @returns {string} String representation with module and action info
+   */
+  toString() {
+    return `${this.#file?.module || "UNDEFINED"} (${this.meta?.action || "UNDEFINED"})`
+  }
+
+  /**
+   * Get contract/terms for this action (override in subclasses)
+   *
+   * @returns {Terms?} Contract terms or null if not implemented
+   */
+  get terms() {
+    return null
+  }
+}

package/src/lib/ActionRunner.js

@@ -1,9 +1,6 @@
 import ActionBuilder, {ACTIVITY} from "./ActionBuilder.js"
-import Data from "./Data.js"
 import Piper from "./Piper.js"
 import Sass from "./Sass.js"
-import Glog from "./Glog.js"
-
 /**
  * Orchestrates execution of {@link ActionBuilder}-produced pipelines.
  *
@@ -14,12 +11,12 @@ import Glog from "./Glog.js"
 export default class ActionRunner {
   #action = null
   #build = null
-  #logger = null
+  #hooks = null
 
-  constructor({action, build, logger}) {
+  constructor({action, build}, hooks) {
     this.#action = action
     this.#build = build
-    this.#logger = logger ?? {newDebug: () => () => {}}
+    this.#hooks = hooks
   }
 
   /**
@@ -30,43 +27,33 @@ export default class ActionRunner {
    * @throws {Sass} When no activities are registered or required parallel builders are missing.
    */
   async run(content) {
-    const AR = ActionRunner
-    const result = {value: content}
-    const action = this.#action
     const activities = this.#build.activities
 
     if(!activities.size)
       throw Sass.new("No activities defined in action.")
 
-    for(const [_,activity] of activities) {
+    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(Data.typeOf(activity.hooks?.before) === "Function")
-          await activity.hooks.before.call(action, result)
-
-        const activityResult = await op.call(action, result)
-
-        if(!activityResult)
+        if(!await op.call(action, result))
           break
 
-        if(Data.typeOf(activity.hooks?.after) === "Function")
-          await activity.hooks.after.call(action, result)
-
+        this.#hooks && await this.#hooks.callHook("after", name, result)
       } else if(activity.kind == ACTIVITY.MANY) {
         for(;;) {
 
-          if(Data.typeOf(activity.hooks?.before) === "Function")
-            await activity.hooks.before.call(action, result)
-
-          const activityResult = await op.call(action, result)
+          this.#hooks && await this.#hooks.callHook("before", name, result)
 
-          if(!activityResult)
+          if(!await op.call(action, result))
             break
 
-          if(Data.typeOf(activity.hooks?.after) === "Function")
-            await activity.hooks.after.call(action, result)
+          this.#hooks && await this.#hooks.callHook("after", name, result)
         }
       } else if(activity.kind === ACTIVITY.PARALLEL) {
         if(op === undefined)
@@ -75,35 +62,18 @@ export default class ActionRunner {
         if(!op)
           throw Sass.new("Okay, cheeky monkey, you need to return the builder for this to work.")
 
-        const piper = new Piper({logger: this.#logger})
-          .addStep(c => new AR(op.build()).run(c))
-
-        result.value = await piper.pipe()
-        Glog(result)
-        throw Sass.new("Nope")
-
-        // // wheeeeeeeeeeeeee! ZOOMZOOM!
-        // const settled = await Util.settleAll(
-        //   result.value.map()
-        // )
-
-        // const rejected = settled
-        //   .filter(r => r.status === "rejected")
-        //   .map(r => {
-        //     return r.reason instanceof Sass
-        //       ? r.reason
-        //       : Sass.new("Running structured parsing.", r.reason)
-        //   })
-        //   .map(r => r.report(true))
+        const builder = op.build()
+        const piper = new Piper()
+          .addStep(item => {
+            const runner = new ActionRunner(builder, this.#hooks)
 
-        // if(rejected.length)
-        //   return null
+            return runner.run(item)
+          }, {name: `Process Parallel ActionRunner Activity`,})
 
-        // result.value = settled.map(s => s.value)
-        //   .sort((a,b) => a.index-b.index)
+        await piper.pipe(result.value)
       }
     }
 
-    return result.value
+    return result
   }
 }

package/src/lib/Contract.js

@@ -0,0 +1,257 @@
+import Sass from "./Sass.js"
+import Schemer from "./Schemer.js"
+import Terms from "./Terms.js"
+import Data from "./Data.js"
+
+/**
+ * Contract represents a successful negotiation between Terms.
+ * It handles validation and compatibility checking between what
+ * one action provides and what another accepts.
+ */
+export default class Contract {
+  #providerTerms = null
+  #consumerTerms = null
+  #validator = null
+  #debug = null
+  #isNegotiated = false
+
+  /**
+   * Creates a contract by negotiating between provider and consumer terms
+   *
+   * @param {Terms} providerTerms - What the provider offers
+   * @param {Terms} consumerTerms - What the consumer expects
+   * @param {object} options - Configuration options
+   * @param {import('../types.js').DebugFunction} [options.debug] - Debug function
+   */
+  constructor(providerTerms, consumerTerms, {debug = null} = {}) {
+    this.#providerTerms = providerTerms
+    this.#consumerTerms = consumerTerms
+    this.#debug = debug
+
+    // Perform the negotiation
+    this.#negotiate()
+  }
+
+  /**
+   * Extracts the actual schema from a terms definition
+   *
+   * @param {object} definition - Terms definition with TLD descriptor
+   * @returns {object} Extracted schema content
+   * @throws {Sass} If definition structure is invalid
+   * @private
+   */
+  static #extractSchemaFromTerms(definition) {
+    // Must be a plain object
+    if(!Data.isPlainObject(definition)) {
+      throw Sass.new("Terms definition must be a plain object")
+    }
+
+    // Must have exactly one key (the TLD/descriptor)
+    const keys = Object.keys(definition)
+    if(keys.length !== 1) {
+      throw Sass.new("Terms definition must have exactly one top-level key (descriptor)")
+    }
+
+    // Extract the content under the TLD
+    const [key] = keys
+
+    return definition[key]
+  }
+
+  /**
+   * Creates a contract from terms with schema validation
+   *
+   * @param {string} name - Contract identifier
+   * @param {object} termsDefinition - The terms definition
+   * @param {import('ajv').ValidateFunction|null} [validator] - Optional AJV schema validator function with .errors property
+   * @param {import('../types.js').DebugFunction} [debug] - Debug function
+   * @returns {Contract} New contract instance
+   */
+  static fromTerms(name, termsDefinition, validator = null, debug = null) {
+    // Validate the terms definition if validator provided
+    if(validator) {
+      const valid = validator(termsDefinition)
+
+      if(!valid) {
+        const error = Schemer.reportValidationErrors(validator.errors)
+        throw Sass.new(`Invalid terms definition for ${name}:\n${error}`)
+      }
+    }
+
+    // Extract schema from terms definition for validation
+    const schemaDefinition = Contract.#extractSchemaFromTerms(termsDefinition)
+    const termsSchemaValidator = Schemer.getValidator(schemaDefinition)
+
+    const contract = new Contract(null, null, {debug})
+    contract.#validator = termsSchemaValidator
+    contract.#isNegotiated = true // Single-party contract is automatically negotiated
+
+    return contract
+  }
+
+  /**
+   * Performs negotiation between provider and consumer terms
+   *
+   * @private
+   */
+  #negotiate() {
+    if(!this.#providerTerms || !this.#consumerTerms) {
+      // Single-party contract scenario
+      this.#isNegotiated = true
+
+      return
+    }
+
+    // Extract content for comparison (ignore TLD metadata)
+    const providerContent = Contract.#extractSchemaFromTerms(
+      this.#providerTerms.definition
+    )
+    const consumerContent = Contract.#extractSchemaFromTerms(
+      this.#consumerTerms.definition
+    )
+
+    // Compare terms for compatibility
+    const compatibility = this.#compareTerms(providerContent, consumerContent)
+
+    if(compatibility.status === "error") {
+      throw Sass.new(
+        `Contract negotiation failed: ${compatibility.errors.map(e => e.message).join(", ")}`
+      )
+    }
+
+    this.#isNegotiated = true
+    this.#debug?.(`Contract negotiated successfully`, 3)
+  }
+
+  /**
+   * Validates data against this contract
+   *
+   * @param {object} data - Data to validate
+   * @returns {boolean} True if valid
+   * @throws {Sass} If validation fails or contract not negotiated
+   */
+  validate(data) {
+    const debug = this.#debug
+
+    if(!this.#isNegotiated)
+      throw Sass.new("Cannot validate against unnegotiated contract")
+
+    if(!this.#validator)
+      throw Sass.new("No validator available for this contract")
+
+    debug?.("Validating data %o", 4, data)
+
+    const valid = this.#validator(data)
+
+    if(!valid) {
+      const error = Schemer.reportValidationErrors(this.#validator.errors)
+      throw Sass.new(`Contract validation failed:\n${error}`)
+    }
+
+    return true
+  }
+
+  /**
+   * Compares terms for compatibility
+   *
+   * @param {object} providerTerms - Terms offered by provider
+   * @param {object} consumerTerms - Terms expected by consumer
+   * @param {Array} stack - Stack trace for nested validation
+   * @returns {object} Result with status and errors
+   * @private
+   */
+  #compareTerms(providerTerms, consumerTerms, stack = []) {
+    const debug = this.#debug
+    const breadcrumb = key => (stack.length ? `@${stack.join(".")}` : key)
+    const errors = []
+
+    if(!providerTerms || !consumerTerms) {
+      return {
+        status: "error",
+        errors: [Sass.new("Both provider and consumer terms are required")]
+      }
+    }
+
+    debug?.("Comparing provider keys:%o with consumer keys:%o", 3,
+      Object.keys(providerTerms), Object.keys(consumerTerms))
+
+    // Check that consumer requirements are met by provider
+    for(const [key, consumerRequirement] of Object.entries(consumerTerms)) {
+      debug?.("Checking consumer requirement: %o [required = %o]", 3,
+        key, consumerRequirement.required ?? false)
+
+      if(consumerRequirement.required && !(key in providerTerms)) {
+        debug?.("Provider missing required capability: %o", 2, key)
+        errors.push(
+          Sass.new(`Provider missing required capability: ${key} ${breadcrumb(key)}`)
+        )
+        continue
+      }
+
+      if(key in providerTerms) {
+        const expectedType = consumerRequirement.dataType
+        const providedType = providerTerms[key]?.dataType
+
+        if(expectedType && providedType && expectedType !== providedType) {
+          errors.push(
+            Sass.new(
+              `Type mismatch for ${key}: Consumer expects ${expectedType}, provider offers ${providedType} ${breadcrumb(key)}`
+            )
+          )
+        }
+
+        // Recursive validation for nested requirements
+        if(consumerRequirement.contains) {
+          debug?.("Recursing into nested requirement: %o", 3, key)
+          const nestedResult = this.#compareTerms(
+            providerTerms[key]?.contains,
+            consumerRequirement.contains,
+            [...stack, key]
+          )
+
+          if(nestedResult.errors.length) {
+            errors.push(...nestedResult.errors)
+          }
+        }
+      }
+    }
+
+    return {status: errors.length === 0 ? "success" : "error", errors}
+  }
+
+  /**
+   * Check if contract negotiation was successful
+   *
+   * @returns {boolean} True if negotiated
+   */
+  get isNegotiated() {
+    return this.#isNegotiated
+  }
+
+  /**
+   * Get the provider terms (if any)
+   *
+   * @returns {Terms|null} Provider terms
+   */
+  get providerTerms() {
+    return this.#providerTerms
+  }
+
+  /**
+   * Get the consumer terms (if any)
+   *
+   * @returns {Terms|null} Consumer terms
+   */
+  get consumerTerms() {
+    return this.#consumerTerms
+  }
+
+  /**
+   * Get the contract validator
+   *
+   * @returns {(data: object) => boolean|null} The contract validator function
+   */
+  get validator() {
+    return this.#validator
+  }
+}