@gesslar/toolkit 0.3.0 → 0.5.0

package/src/types/FileObject.d.ts

@@ -321,10 +321,46 @@ export default class FileObject extends FS {
   /** Read the content of a file */
   read(encoding?: string): Promise<string>
 
-  /** Write content to a file */
+  /**
+   * Write content to a file asynchronously.
+   * Validates that the parent directory exists before writing.
+   *
+   * @param content - The content to write
+   * @param encoding - The encoding in which to write (default: "utf8")
+   * @throws {Sass} If the file path is invalid or the parent directory doesn't exist
+   *
+   * @example
+   * ```typescript
+   * const file = new FileObject('./output/data.json')
+   * await file.write(JSON.stringify({key: 'value'}))
+   *
+   * // With custom encoding
+   * await file.write('content', 'utf16le')
+   * ```
+   */
   write(content: string, encoding?: string): Promise<void>
 
-  /** Load an object from JSON5 or YAML file with type specification */
+  /**
+   * Load and parse data from JSON5 or YAML file.
+   * Attempts to parse content as JSON5 first, then falls back to YAML if type is "any".
+   *
+   * @param type - The expected data format: "json", "json5", "yaml", or "any" (default: "any")
+   * @param encoding - The file encoding (default: "utf8")
+   * @returns The parsed data object
+   * @throws {Sass} If the content cannot be parsed or type is unsupported
+   *
+   * @example
+   * ```typescript
+   * // Load JSON5 config
+   * const config = await configFile.loadData('json5')
+   *
+   * // Auto-detect format (tries JSON5, then YAML)
+   * const data = await dataFile.loadData('any')
+   *
+   * // Load YAML explicitly
+   * const yaml = await yamlFile.loadData('yaml')
+   * ```
+   */
   loadData(type?: 'json' | 'json5' | 'yaml' | 'any', encoding?: string): Promise<unknown>
 
   /**

package/src/types/Schemer.d.ts

@@ -0,0 +1,179 @@
+// Implementation: ../lib/Schemer.js
+
+import type { ValidateFunction, ErrorObject } from 'ajv'
+
+/**
+ * Schemer provides utilities for compiling and validating JSON schemas using AJV.
+ * 
+ * This class serves as a convenient wrapper around AJV (Another JSON Schema Validator)
+ * with toolkit-specific enhancements for error reporting and schema compilation.
+ * 
+ * @example
+ * ```typescript
+ * // Create validator from schema object
+ * const validator = await Schemer.from({
+ *   type: "object",
+ *   properties: {
+ *     name: { type: "string" },
+ *     age: { type: "number", minimum: 0 }
+ *   },
+ *   required: ["name"]
+ * })
+ * 
+ * // Validate data
+ * const isValid = validator({ name: "John", age: 30 })
+ * ```
+ * 
+ * @example
+ * ```typescript
+ * // Create validator from file
+ * const file = new FileObject("schema.json")
+ * const validator = await Schemer.fromFile(file)
+ * ```
+ * 
+ * @example  
+ * ```typescript
+ * // Get raw AJV validator and format errors
+ * const validate = Schemer.getValidator(schema)
+ * const isValid = validate(data)
+ * if (!isValid) {
+ *   const errorReport = Schemer.reportValidationErrors(validate.errors)
+ *   console.error("Validation failed:", errorReport)
+ * }
+ * ```
+ */
+declare class Schemer {
+  /**
+   * Creates an AJV validator function from a schema file
+   * 
+   * @param file - FileObject pointing to a JSON/YAML schema file
+   * @param options - AJV configuration options
+   * @returns Promise resolving to AJV validator function
+   * 
+   * @throws {Sass} If file cannot be loaded or schema is invalid
+   * @throws {Sass} If file is not a FileObject or options are invalid
+   * 
+   * @example
+   * ```typescript
+   * const file = new FileObject("user-schema.json")
+   * const validator = await Schemer.fromFile(file, {
+   *   allErrors: true,
+   *   verbose: true
+   * })
+   * 
+   * const isValid = validator({ name: "John", age: 30 })
+   * if (!isValid) {
+   *   console.log("Errors:", validator.errors)
+   * }
+   * ```
+   */
+  static fromFile(
+    file: import('./FileObject.js').default, 
+    options?: object
+  ): Promise<ValidateFunction>
+
+  /**
+   * Creates an AJV validator function from a schema object
+   * 
+   * @param schemaData - JSON schema object to compile
+   * @param options - AJV configuration options  
+   * @returns Promise resolving to AJV validator function
+   * 
+   * @throws {Sass} If schema data or options are not plain objects
+   * @throws {Sass} If schema compilation fails
+   * 
+   * @example
+   * ```typescript
+   * const validator = await Schemer.from({
+   *   type: "object",
+   *   properties: {
+   *     id: { type: "string", format: "uuid" },
+   *     email: { type: "string", format: "email" }
+   *   },
+   *   required: ["id", "email"]
+   * }, { 
+   *   formats: true,
+   *   allErrors: true 
+   * })
+   * 
+   * const isValid = validator({ id: "123", email: "test@example.com" })
+   * if (!isValid) {
+   *   console.log("Errors:", validator.errors)
+   * }
+   * ```
+   */
+  static from(schemaData?: object, options?: object): Promise<ValidateFunction>
+
+  /**
+   * Creates a raw AJV validator function from a schema object
+   * 
+   * @param schema - The JSON schema to compile
+   * @param options - AJV configuration options (defaults to {allErrors: true, verbose: true})
+   * @returns AJV validator function with .errors property when validation fails
+   * 
+   * @example
+   * ```typescript
+   * const validate = Schemer.getValidator({
+   *   type: "string",
+   *   minLength: 1,
+   *   maxLength: 100
+   * })
+   * 
+   * const isValid = validate("Hello World")
+   * if (!isValid) {
+   *   console.log("Errors:", validate.errors)
+   * }
+   * ```
+   * 
+   * @example
+   * ```typescript
+   * // Custom AJV options
+   * const validate = Schemer.getValidator(schema, {
+   *   allErrors: false,
+   *   verbose: false,
+   *   strict: true
+   * })
+   * ```
+   */
+  static getValidator(
+    schema: object, 
+    options?: { allErrors?: boolean; verbose?: boolean; [key: string]: unknown }
+  ): ValidateFunction
+
+  /**
+   * Formats AJV validation errors into a human-readable report
+   * 
+   * @param errors - Array of AJV error objects from failed validation
+   * @returns Formatted error message with helpful details and suggestions
+   * 
+   * @example
+   * ```typescript
+   * const validate = Schemer.getValidator(schema)
+   * const isValid = validate(data)
+   * 
+   * if (!isValid) {
+   *   const report = Schemer.reportValidationErrors(validate.errors)
+   *   console.error("Validation failed:")
+   *   console.error(report)
+   *   // Output:
+   *   // - "(root)" must be object
+   *   //   ➜ Expected type: object
+   *   //   ➜ Received value: "string"
+   * }
+   * ```
+   * 
+   * @example
+   * ```typescript
+   * // The error report includes helpful details:
+   * // - Property paths and error descriptions
+   * // - Expected vs actual types
+   * // - Missing required fields
+   * // - Pattern matching failures  
+   * // - Closest matches for enum values
+   * // - Unexpected additional properties
+   * ```
+   */
+  static reportValidationErrors(errors: ErrorObject[] | null | undefined): string
+}
+
+export default Schemer

package/src/types/Terms.d.ts

@@ -0,0 +1,145 @@
+// Implementation: ../lib/Terms.js
+
+/**
+ * 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.
+ * 
+ * Terms can be created from objects, strings (YAML/JSON), or file references.
+ * File references use the format "ref://path/to/file" for loading external definitions.
+ * 
+ * @example
+ * ```typescript
+ * // Create terms from object definition
+ * const terms = new Terms({
+ *   provides: {
+ *     type: "object",
+ *     properties: {
+ *       userId: { type: "string" },
+ *       userName: { type: "string" }
+ *     },
+ *     required: ["userId"]
+ *   }
+ * })
+ * ```
+ * 
+ * @example
+ * ```typescript
+ * // Parse terms from YAML string
+ * const yamlData = `
+ * accepts:
+ *   type: object
+ *   properties:
+ *     input: 
+ *       type: string
+ *       minLength: 1
+ * `
+ * const parsedTerms = await Terms.parse(yamlData)
+ * ```
+ * 
+ * @example
+ * ```typescript
+ * // Parse terms from file reference
+ * const directory = new DirectoryObject("/path/to/schemas")
+ * const parsedTerms = await Terms.parse("ref://user-schema.json", directory)
+ * ```
+ */
+declare class Terms {
+  /**
+   * Creates a new Terms instance with the given definition
+   * 
+   * @param definition - The terms definition object describing what is provided or accepted
+   * 
+   * @example
+   * ```typescript
+   * const terms = new Terms({
+   *   provides: {
+   *     type: "object",
+   *     properties: {
+   *       data: { type: "array", items: { type: "string" } },
+   *       metadata: { 
+   *         type: "object",
+   *         properties: {
+   *           timestamp: { type: "string", format: "date-time" }
+   *         }
+   *       }
+   *     }
+   *   }
+   * })
+   * ```
+   */
+  constructor(definition: object)
+
+  /**
+   * Parses terms data from various sources, handling file references
+   * 
+   * @param termsData - Terms data as string (YAML/JSON/file reference) or object
+   * @param directoryObject - Directory context for resolving file references (required for ref:// URLs)
+   * @returns Promise resolving to parsed terms data object
+   * 
+   * @throws {Sass} If termsData is not a string or object
+   * @throws {Sass} If string data cannot be parsed as YAML or JSON  
+   * @throws {Sass} If file reference cannot be loaded (missing directory or file not found)
+   * 
+   * @example
+   * ```typescript
+   * // Parse from YAML string
+   * const yamlTerms = await Terms.parse(`
+   *   provides:
+   *     type: string
+   *     pattern: "^[A-Z][a-z]+"
+   * `)
+   * ```
+   * 
+   * @example
+   * ```typescript  
+   * // Parse from JSON string
+   * const jsonTerms = await Terms.parse(`{
+   *   "accepts": {
+   *     "type": "number",
+   *     "minimum": 0,
+   *     "maximum": 100
+   *   }
+   * }`)
+   * ```
+   * 
+   * @example
+   * ```typescript
+   * // Parse from file reference
+   * const directory = new DirectoryObject("./schemas")
+   * const fileTerms = await Terms.parse("ref://api-contract.yaml", directory)
+   * ```
+   * 
+   * @example
+   * ```typescript
+   * // Parse from object (returns as-is)
+   * const objectTerms = await Terms.parse({
+   *   provides: { type: "boolean" }
+   * })
+   * ```
+   */
+  static parse(
+    termsData: string | object, 
+    directoryObject?: import('./DirectoryObject.js').default
+  ): Promise<object>
+
+  /**
+   * Get the terms definition object
+   * 
+   * @returns The complete terms definition as provided to the constructor
+   * 
+   * @example
+   * ```typescript
+   * const terms = new Terms({
+   *   accepts: { type: "string" },
+   *   provides: { type: "number" }
+   * })
+   * 
+   * const definition = terms.definition
+   * console.log(definition.accepts)  // { type: "string" }
+   * console.log(definition.provides) // { type: "number" }
+   * ```
+   */
+  get definition(): object
+}
+
+export default Terms

package/src/types/index.d.ts

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

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"})`
-  }
-}