@gesslar/toolkit 0.4.0 → 0.6.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/Data.d.ts

@@ -21,33 +21,33 @@ export default class Data {
 
   /**
    * Append a suffix string to the end of a string if it doesn't already end with it.
-   * 
-   * Useful for ensuring strings have consistent endings like file extensions, 
+   *
+   * Useful for ensuring strings have consistent endings like file extensions,
    * URL paths, or punctuation. Performs case-sensitive comparison and only appends
    * if the string doesn't already end with the specified suffix.
    *
    * @param string - The base string to potentially append to. Can be empty string.
    * @param append - The suffix to append if not already present. Cannot be empty.
    * @returns The string with the suffix appended, or the original string if suffix already present
-   * 
+   *
    * @throws {Error} When append parameter is empty or undefined
    *
    * @example
    * ```typescript
    * import { Data } from '@gesslar/toolkit'
-   * 
+   *
    * // Basic usage with file extensions
    * const filename = Data.appendString('config', '.json')
    * console.log(filename) // 'config.json'
-   * 
+   *
    * // No double-appending
-   * const alreadyHasExt = Data.appendString('package.json', '.json')  
+   * const alreadyHasExt = Data.appendString('package.json', '.json')
    * console.log(alreadyHasExt) // 'package.json' (unchanged)
-   * 
+   *
    * // URL path handling
    * const apiPath = Data.appendString('/api/users', '/')
    * console.log(apiPath) // '/api/users/'
-   * 
+   *
    * // Works with empty strings
    * const fromEmpty = Data.appendString('', '.txt')
    * console.log(fromEmpty) // '.txt'
@@ -57,33 +57,33 @@ export default class Data {
 
   /**
    * Prepend a prefix string to the beginning of a string if it doesn't already start with it.
-   * 
+   *
    * Useful for ensuring strings have consistent beginnings like protocol prefixes,
-   * path separators, or formatting markers. Performs case-sensitive comparison and 
+   * path separators, or formatting markers. Performs case-sensitive comparison and
    * only prepends if the string doesn't already start with the specified prefix.
    *
    * @param string - The base string to potentially prepend to. Can be empty string.
    * @param prepend - The prefix to prepend if not already present. Cannot be empty.
    * @returns The string with the prefix prepended, or the original string if prefix already present
-   * 
+   *
    * @throws {Error} When prepend parameter is empty or undefined
    *
    * @example
    * ```typescript
    * import { Data } from '@gesslar/toolkit'
-   * 
+   *
    * // Basic usage with protocols
    * const url = Data.prependString('example.com', 'https://')
    * console.log(url) // 'https://example.com'
-   * 
+   *
    * // No double-prepending
    * const alreadyHasProtocol = Data.prependString('https://api.example.com', 'https://')
    * console.log(alreadyHasProtocol) // 'https://api.example.com' (unchanged)
-   * 
+   *
    * // File path handling
    * const absolutePath = Data.prependString('home/user/docs', '/')
    * console.log(absolutePath) // '/home/user/docs'
-   * 
+   *
    * // CSS class prefixing
    * const className = Data.prependString('button-primary', 'css-')
    * console.log(className) // 'css-button-primary'
@@ -135,32 +135,32 @@ export default class Data {
   static clamped(val: number, min: number, max: number): boolean
 
   /**
-   * Checks if a value is a plain object - created with object literals {}, 
+   * Checks if a value is a plain object - created with object literals {},
    * new Object(), or Object.create(null).
-   * 
-   * Distinguishes plain objects from objects created by custom constructors, built-ins, 
+   *
+   * Distinguishes plain objects from objects created by custom constructors, built-ins,
    * or primitives. Plain objects only have Object.prototype or null in their prototype chain.
    * Useful for validating configuration objects or data structures that should be plain objects.
    *
    * @param value - The value to check for plain object status
    * @returns True if the value is a plain object, false otherwise
-   * 
+   *
    * @example
    * ```typescript
    * import { Data } from '@gesslar/toolkit'
-   * 
+   *
    * // Plain objects return true
    * console.log(Data.isPlainObject({})) // true
-   * console.log(Data.isPlainObject(new Object())) // true 
+   * console.log(Data.isPlainObject(new Object())) // true
    * console.log(Data.isPlainObject(Object.create(null))) // true
-   * 
+   *
    * // Non-plain objects return false
    * console.log(Data.isPlainObject([])) // false
    * console.log(Data.isPlainObject(new Date())) // false
    * console.log(Data.isPlainObject(/regex/)) // false
    * console.log(Data.isPlainObject(null)) // false
    * console.log(Data.isPlainObject('string')) // false
-   * 
+   *
    * // Useful for validating config objects
    * function processConfig(config: unknown) {
    *   if (!Data.isPlainObject(config)) {

package/src/types/FS.d.ts

@@ -9,13 +9,13 @@ import DirectoryObject from './DirectoryObject.js'
  */
 export default class FS {
   /** Array of lowercase file descriptor types */
-  static readonly fdTypes: readonly ["file", "directory"]
+  static readonly fdTypes: readonly ['file', 'directory']
 
   /** Array of uppercase file descriptor types */
-  static readonly upperFdTypes: readonly ["FILE", "DIRECTORY"]
+  static readonly upperFdTypes: readonly ['FILE', 'DIRECTORY']
 
   /** Mapping from uppercase to lowercase file descriptor types */
-  static readonly fdType: Readonly<Record<"FILE" | "DIRECTORY", "file" | "directory">>
+  static readonly fdType: Readonly<Record<'FILE' | 'DIRECTORY', 'file' | 'directory'>>
 
   /** Fix slashes in a path */
   static fixSlashes(pathName: string): string