@gesslar/toolkit 0.3.0 → 0.5.0

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
+  }
+
+}

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/DirectoryObject.d.ts

@@ -40,6 +40,12 @@ export default class DirectoryObject extends FS {
   /** The directory extension (usually empty) */
   readonly extension: string
 
+  /** The platform-specific path separator (e.g., '/' on Unix, '\\' on Windows) */
+  readonly sep: string
+
+  /** Array of directory path segments split by separator */
+  readonly trail: string[]
+
   /** Always false for directories */
   readonly isFile: false
 
@@ -49,6 +55,25 @@ export default class DirectoryObject extends FS {
   /** Whether the directory exists (async) */
   readonly exists: Promise<boolean>
 
+  /**
+   * Generator that walks up the directory tree, yielding parent directories.
+   * Starts from the current directory and yields each parent until reaching the root.
+   *
+   * @example
+   * ```typescript
+   * const dir = new DirectoryObject('/path/to/deep/directory')
+   * for (const parent of dir.walkUp) {
+   *   console.log(parent.path)
+   *   // /path/to/deep/directory
+   *   // /path/to/deep
+   *   // /path/to
+   *   // /path
+   *   // /
+   * }
+   * ```
+   */
+  readonly walkUp: Generator<DirectoryObject, void, unknown>
+
   /** Returns a string representation of the DirectoryObject */
   toString(): string
 
@@ -64,9 +89,47 @@ export default class DirectoryObject extends FS {
     isDirectory: boolean
   }
 
-  /** List the contents of this directory */
+  /**
+   * Lists the contents of this directory.
+   * Returns FileObject instances for files and DirectoryObject instances for subdirectories.
+   *
+   * @returns Promise resolving to object with files and directories arrays
+   * @throws {Error} If directory cannot be read
+   *
+   * @example
+   * ```typescript
+   * const dir = new DirectoryObject('./src')
+   * const {files, directories} = await dir.read()
+   *
+   * console.log(`Found ${files.length} files`)
+   * files.forEach(file => console.log(file.name))
+   *
+   * console.log(`Found ${directories.length} subdirectories`)
+   * directories.forEach(subdir => console.log(subdir.name))
+   * ```
+   */
   read(): Promise<DirectoryListing>
 
-  /** Ensure this directory exists, creating it if necessary */
+  /**
+   * Ensures this directory exists, creating it if necessary.
+   * Gracefully handles the case where the directory already exists (EEXIST error).
+   * Pass options to control directory creation behavior (e.g., recursive, mode).
+   *
+   * @param options - Options to pass to fs.mkdir (e.g., {recursive: true, mode: 0o755})
+   * @returns Promise that resolves when directory exists or has been created
+   * @throws {Sass} If directory creation fails for reasons other than already existing
+   *
+   * @example
+   * ```typescript
+   * const dir = new DirectoryObject('./build/output')
+   *
+   * // Create directory recursively
+   * await dir.assureExists({recursive: true})
+   *
+   * // Now safe to write files
+   * const file = new FileObject('result.json', dir)
+   * await file.write(JSON.stringify(data))
+   * ```
+   */
   assureExists(options?: any): Promise<void>
 }