@gesslar/toolkit 0.4.0 → 0.5.0

package/src/types/Contract.d.ts

@@ -0,0 +1,162 @@
+// Implementation: ../lib/Contract.js
+
+import type { ValidateFunction } from 'ajv'
+
+/**
+ * Debug function type for Contract operations
+ */
+export type DebugFunction = (message: string, level?: number, ...args: unknown[]) => void
+
+/**
+ * Contract represents a successful negotiation between Terms.
+ * It handles validation and compatibility checking between what
+ * one action provides and what another accepts.
+ * 
+ * @example
+ * ```typescript
+ * // Two-party contract between provider and consumer
+ * const provider = new Terms(providerDefinition)
+ * const consumer = new Terms(consumerDefinition)
+ * const contract = new Contract(provider, consumer, { debug: console.log })
+ * 
+ * // Validate data against the contract
+ * const isValid = contract.validate(someData)
+ * ```
+ * 
+ * @example
+ * ```typescript
+ * // Single-party contract from terms definition
+ * const contract = Contract.fromTerms("parser", {
+ *   provides: {
+ *     type: "object",
+ *     properties: {
+ *       name: { type: "string" },
+ *       age: { type: "number" }
+ *     }
+ *   }
+ * })
+ * 
+ * contract.validate({ name: "John", age: 30 }) // true
+ * ```
+ */
+declare class Contract {
+  /**
+   * Creates a contract by negotiating between provider and consumer terms
+   * 
+   * @param providerTerms - What the provider offers
+   * @param consumerTerms - What the consumer expects  
+   * @param options - Configuration options
+   * @param options.debug - Debug function for logging negotiation details
+   * 
+   * @throws {Sass} If contract negotiation fails due to incompatible terms
+   */
+  constructor(
+    providerTerms: import('./Terms.js').default | null, 
+    consumerTerms: import('./Terms.js').default | null, 
+    options?: { debug?: DebugFunction }
+  )
+
+  /**
+   * Creates a contract from terms with schema validation
+   * 
+   * @param name - Contract identifier for error reporting
+   * @param termsDefinition - The terms definition object
+   * @param validator - Optional AJV schema validator function with .errors property
+   * @param debug - Debug function for logging validation details
+   * @returns New contract instance ready for data validation
+   * 
+   * @throws {Sass} If terms definition is invalid according to the validator
+   * 
+   * @example
+   * ```typescript
+   * const contract = Contract.fromTerms("user-parser", {
+   *   provides: {
+   *     type: "object", 
+   *     properties: {
+   *       id: { type: "string" },
+   *       name: { type: "string" }
+   *     },
+   *     required: ["id", "name"]
+   *   }
+   * })
+   * ```
+   */
+  static fromTerms(
+    name: string, 
+    termsDefinition: object, 
+    validator?: ValidateFunction | null, 
+    debug?: DebugFunction
+  ): Contract
+
+  /**
+   * Validates data against this contract's schema
+   * 
+   * @param data - Data object to validate against the contract
+   * @returns True if validation passes
+   * 
+   * @throws {Sass} If validation fails with detailed error messages
+   * @throws {Sass} If contract has not been successfully negotiated
+   * @throws {Sass} If no validator is available for this contract
+   * 
+   * @example
+   * ```typescript
+   * try {
+   *   contract.validate({ id: "123", name: "John" })
+   *   console.log("Data is valid!")
+   * } catch (error) {
+   *   console.error("Validation failed:", error.message)
+   * }
+   * ```
+   */
+  validate(data: object): boolean
+
+  /**
+   * Check if contract negotiation was successful
+   * 
+   * @returns True if the contract has been successfully negotiated
+   * 
+   * @example
+   * ```typescript
+   * if (contract.isNegotiated) {
+   *   contract.validate(data)
+   * } else {
+   *   console.error("Contract negotiation failed")
+   * }
+   * ```
+   */
+  get isNegotiated(): boolean
+
+  /**
+   * Get the provider terms (if any)
+   * 
+   * @returns Provider terms or null for single-party contracts
+   */
+  get providerTerms(): import('./Terms.js').default | null
+
+  /**
+   * Get the consumer terms (if any)
+   * 
+   * @returns Consumer terms or null for single-party contracts  
+   */
+  get consumerTerms(): import('./Terms.js').default | null
+
+  /**
+   * Get the contract validator function
+   * 
+   * @returns The AJV validator function used by this contract, or null if none available
+   * 
+   * @example
+   * ```typescript
+   * const validator = contract.validator
+   * if (validator) {
+   *   const isValid = validator(someData)
+   *   if (!isValid) {
+   *     console.log("Validation errors:", validator.errors)
+   *   }
+   * }
+   * ```
+   */
+  get validator(): ((data: object) => boolean) | null
+}
+
+export default Contract

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'