@gesslar/toolkit 0.4.0 → 0.6.0

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

@@ -23,4 +23,4 @@ export default class TypeSpec {
   reduce<T>(callback: (acc: T, spec: TypeSpecDefinition) => T, initialValue: T): T
   find(callback: (spec: TypeSpecDefinition) => boolean): TypeSpecDefinition | undefined
   match(value: unknown, options?: { allowEmpty?: boolean }): boolean
-}
+}

package/src/types/Util.d.ts

@@ -54,6 +54,16 @@ declare class Util {
    */
   static rightAlignText(text: string | number, width?: number): string
 
+  /**
+   * Centre-align a string inside a fixed width (pad with spaces on left).
+   * If the string exceeds width it is returned unchanged.
+   *
+   * @param text - Text to align.
+   * @param width - Target field width (default 80).
+   * @returns Padded string with text centred.
+   */
+  static centreAlignText(text: string | number, width?: number): string
+
   /**
    * Compute sha256 hash (hex) of the provided string.
    *
@@ -174,7 +184,15 @@ declare class Util {
    * @param args - Arguments to pass to event listeners
    * @returns Resolves when all listeners have completed
    */
-  static asyncEmitAnon(emitter: { listeners(event: string): Function[], on(event: string, listener: Function): any, emit(event: string, ...args: unknown[]): any }, event: string, ...args: unknown[]): Promise<void>
+  static asyncEmitAnon(
+    emitter: {
+      listeners(event: string): Function[],
+      on(event: string, listener: Function): any,
+      emit(event: string, ...args: unknown[]): any
+    },
+    event: string,
+    ...args: unknown[]
+  ): Promise<void>
 
   /**
    * Determine the Levenshtein distance between two string values.
@@ -228,7 +246,7 @@ declare class Util {
    * @param trim - Whether to trim whitespace from each line (default: true)
    * @param flags - Array of regex flags to apply (default: [])
    * @returns A new RegExp object with the processed pattern
-   * 
+   *
    * @throws Will throw if input is not a string
    * @throws Will throw if trim is not a boolean
    * @throws Will throw if flags is not an array

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/ActionBuilder.js

@@ -1,144 +0,0 @@
-import Valid from "./Valid.js"
-
-/** @typedef {import("./ActionRunner.js").default} ActionRunner */
-
-/**
- * Activity bit flags recognised by {@link ActionBuilder#act}. The flag decides
- * how results are accumulated for each activity.
- *
- * @readonly
- * @enum {number}
- */
-export const ACTIVITY = Object.freeze({
-  ONCE: 1<<1,
-  MANY: 1<<2,
-  PARALLEL: 1<<3,
-})
-
-/**
- * Fluent builder for describing how an action should process the context that
- * flows through the {@link ActionRunner}. Consumers register named activities,
- * optional hook pairs, and nested parallel pipelines before handing the
- * builder back to the runner for execution.
- *
- * Typical usage:
- *
- * ```js
- * const pipeline = new ActionBuilder(myAction)
- *   .act("prepare", ACTIVITY.ONCE, ctx => ctx.initialise())
- *   .parallel(parallel => parallel
- *     .act("step", ACTIVITY.MANY, ctx => ctx.consume())
- *   )
- *   .act("finalise", ACTIVITY.ONCE, ctx => ctx.complete())
- *   .build()
- * ```
- *
- * @class ActionBuilder
- */
-export default class ActionBuilder {
-  #action = null
-  #activities = new Map([])
-
-  /**
-   * Creates a new ActionBuilder instance with the provided action callback.
-   *
-   * @param {(ctx: object) => void} action Base action invoked by the runner when a block
-   *   satisfies the configured structure.
-   */
-  constructor(action) {
-    this.#action = action
-  }
-
-  /**
-   * Returns the underlying action that will receive the extracted context.
-   *
-   * @returns {(ctx: object) => void} The action callback function that processes the extracted context.
-   */
-  get action() {
-    return this.#action
-  }
-
-  /**
-   * Returns the registered activities keyed by their name.
-   *
-   * @returns {Map<string | symbol, {op: (context: object) => unknown, kind: number, hooks: {before: ((context: object) => void)|null, after: ((context: object) => void)|null}}>} Map of registered activities and their metadata.
-   */
-  get activities() {
-    return this.#activities
-  }
-
-  /**
-   * Registers a named activity that will run for each matching block.
-   *
-   * @param {string} name Unique activity identifier.
-   * @param {number} kind Activity accumulation strategy (see {@link ACTIVITY}).
-   * @param {(context: object) => unknown} op Work function executed with the runner context.
-   * @param {{before?: (context: object) => void, after?: (context: object) => void}} [hooks] Optional hooks to run before or after the activity operation.
-   * @returns {ActionBuilder} Builder instance for chaining.
-   */
-  act(name, kind, op, hooks={}) {
-    this.#validActivityKind(kind)
-    this.#dupeActivityCheck(name)
-
-    hooks = this.#normalizeHooks(hooks)
-
-    this.#activities.set(name, {op, kind, hooks})
-
-    return this
-  }
-
-  #normalizeHooks({before=null, after=null}) {
-    return {before, after}
-  }
-
-  /**
-   * Defines a nested pipeline that will run with the {@link ACTIVITY} flag PARALLEL.
-   *
-   * The callback receives a fresh {@link ActionBuilder} scoped to the current
-   * action. The callback must return the configured builder so the runner can
-   * execute the nested pipeline.
-   *
-   * @param {(builder: ActionBuilder) => ActionBuilder} func Callback configuring a nested builder.
-   * @returns {ActionBuilder} Builder instance for chaining.
-   */
-  parallel(func) {
-    const activityName = Symbol(performance.now())
-
-    this.#activities.set(activityName, {
-      op: func.call(this.action, new ActionBuilder(this.action)),
-      kind: ACTIVITY.PARALLEL
-    })
-
-    return this
-  }
-
-  #validActivityKind(kind) {
-    Valid.assert(
-      Object.values(ACTIVITY).includes(kind),
-      "Invalid activity kind."
-    )
-  }
-
-  /**
-   * Validates that an activity name has not been reused.
-   *
-   * @private
-   * @param {string|symbol} name Activity identifier.
-   */
-  #dupeActivityCheck(name) {
-    Valid.assert(
-      !this.#activities.has(name),
-      `Activity '${String(name)}' has already been registered.`
-    )
-  }
-
-  /**
-   * Finalises the builder and returns a payload that can be consumed by the
-   * runner.
-   *
-   * @returns {{action: (context: object) => unknown, build: ActionBuilder}} Payload consumed by the {@link ActionRunner} constructor.
-   */
-  build() {
-    return {action: this.#action, build: this}
-  }
-}

package/src/lib/ActionRunner.js

@@ -1,109 +0,0 @@
-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.
- *
- * Activities run in insertion order, with support for once-off work, repeated
- * loops, and nested parallel pipelines. Each activity receives a mutable
- * context object under `result.value` that can be replaced or enriched.
- */
-export default class ActionRunner {
-  #action = null
-  #build = null
-  #logger = null
-
-  constructor({action, build, logger}) {
-    this.#action = action
-    this.#build = build
-    this.#logger = logger ?? {newDebug: () => () => {}}
-  }
-
-  /**
-   * Executes the configured action pipeline.
-   *
-   * @param {unknown} content Seed value passed to the first activity.
-   * @returns {Promise<unknown>} Final value produced by the pipeline, or null when a parallel stage reports failures.
-   * @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 {op} = activity
-
-      if(activity.kind === ACTIVITY.ONCE) {
-
-        if(Data.typeOf(activity.hooks?.before) === "Function")
-          await activity.hooks.before.call(action, result)
-
-        const activityResult = await op.call(action, result)
-
-        if(!activityResult)
-          break
-
-        if(Data.typeOf(activity.hooks?.after) === "Function")
-          await activity.hooks.after.call(action, 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)
-
-          if(!activityResult)
-            break
-
-          if(Data.typeOf(activity.hooks?.after) === "Function")
-            await activity.hooks.after.call(action, result)
-        }
-      } else if(activity.kind === ACTIVITY.PARALLEL) {
-        if(op === undefined)
-          throw Sass.new("Missing action builder. Did you return the builder?")
-
-        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))
-
-        // if(rejected.length)
-        //   return null
-
-        // result.value = settled.map(s => s.value)
-        //   .sort((a,b) => a.index-b.index)
-      }
-    }
-
-    return result.value
-  }
-}

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