@gesslar/toolkit 0.2.8 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gesslar/toolkit",
-  "version": "0.2.8",
+  "version": "0.3.0",
   "description": "Get in, bitches, we're going toolkitting.",
   "main": "./src/index.js",
   "type": "module",
@@ -25,7 +25,8 @@
     "submit": "npm publish --access public",
     "update": "npx npm-check-updates -u && npm install",
     "test": "node --test tests/unit/*.test.js",
-    "test:unit": "node --test tests/unit/*.test.js"
+    "test:unit": "node --test tests/unit/*.test.js",
+    "pr": "gt submit --cli --publish --restack --ai --merge-when-ready"
   },
   "repository": {
     "type": "git",
@@ -49,6 +50,7 @@
   "license": "Unlicense",
   "homepage": "https://github.com/gesslar/toolkit#readme",
   "dependencies": {
+    "@gesslar/colours": "^0.0.1",
     "globby": "^15.0.0",
     "json5": "^2.2.3",
     "yaml": "^2.8.1"

package/src/index.js

@@ -9,6 +9,7 @@ export {default as Collection} from "./lib/Collection.js"
 export {default as Data} from "./lib/Data.js"
 export {default as Glog} from "./lib/Glog.js"
 export {default as Sass} from "./lib/Sass.js"
+export {default as Tantrum} from "./lib/Tantrum.js"
 export {default as Term} from "./lib/Term.js"
 export {default as Type} from "./lib/TypeSpec.js"
 export {default as Util} from "./lib/Util.js"

package/src/lib/ActionBuilder.js

@@ -0,0 +1,144 @@
+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

@@ -0,0 +1,109 @@
+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

@@ -0,0 +1,246 @@
+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"})`
+  }
+}