@gesslar/actioneer 0.1.3 → 0.2.1

package/src/lib/ActionRunner.js

@@ -1,18 +1,15 @@
-import {FileObject, Sass, Valid} from "@gesslar/toolkit"
+import {Data, Sass, Valid} from "@gesslar/toolkit"
 
 import ActionBuilder from "./ActionBuilder.js"
 import {ACTIVITY} from "./Activity.js"
 import Piper from "./Piper.js"
 
-/** @typedef {import("./ActionHooks.js").default} ActionHooks */
-
 /**
  * @typedef {(message: string, level?: number, ...args: Array<unknown>) => void} DebugFn
  */
 
 /**
  * @typedef {object} ActionRunnerOptions
- * @property {ActionHooks} [hooks] Pre-configured hooks.
  * @property {DebugFn} [debug] Logger function.
  */
 /**
@@ -23,154 +20,192 @@ import Piper from "./Piper.js"
  * context object under `result.value` that can be replaced or enriched.
  */
 export default class ActionRunner extends Piper {
-  /**
-   * Pipeline produced by the builder.
-   *
-   * @type {import("./ActionWrapper.js").default|null}
-   */
+  /** @type {import("./ActionBuilder.js").default|null} */
+  #actionBuilder = null
+  /** @type {import("./ActionWrapper.js").default|null} */
   #actionWrapper = null
+
   /**
    * Logger invoked for diagnostics.
    *
    * @type {DebugFn}
    */
   #debug = () => {}
-  /**
-   * Filesystem path to a hooks module.
-   *
-   * @type {string|null}
-   */
-  #hooksPath = null
-  /**
-   * Constructor name exported by the hooks module.
-   *
-   * @type {string|null}
-   */
-  #hooksClassName = null
-  /**
-   * Lazily instantiated hooks implementation.
-   *
-   * @type {ActionHooks|null}
-   */
-  #hooks = null
-  /**
-   * Unique tag for log correlation.
-   *
-   * @type {symbol|null}
-   */
-  #tag = null
 
   /**
    * Instantiate a runner over an optional action wrapper.
    *
-   * @param {import("./ActionWrapper.js").default|null} wrappedAction Output of {@link ActionBuilder#build}.
-   * @param {ActionRunnerOptions} [options] Optional hooks/debug overrides.
+   * @param {import("./ActionBuilder.js").default|null} actionBuilder ActionBuilder to build.
+   * @param {ActionRunnerOptions} [options] Optional debug overrides.
    */
-  constructor(wrappedAction, {hooks,debug=(() => {})} = {}) {
+  constructor(actionBuilder, {debug=(() => {})} = {}) {
     super({debug})
 
-    this.#tag = Symbol(performance.now())
-
     this.#debug = debug
 
-    if(!wrappedAction)
+    if(!actionBuilder)
       return this
 
-    if(wrappedAction?.constructor?.name !== "ActionWrapper")
-      throw Sass.new("ActionRunner takes an instance of an ActionWrapper")
-
-    this.#actionWrapper = wrappedAction
+    if(actionBuilder?.constructor?.name !== "ActionBuilder")
+      throw Sass.new("ActionRunner takes an instance of an ActionBuilder")
 
-    if(hooks)
-      this.#hooks = hooks
-    else
-      this.addSetup(this.#loadHooks)
+    this.#actionBuilder = actionBuilder
 
-    this.addStep(this.run)
+    this.addStep(this.run, {
+      name: `ActionRunner for ${actionBuilder.tag.description}`
+    })
   }
 
   /**
    * Executes the configured action pipeline.
+   * Builds the ActionWrapper on first run and caches it for subsequent calls.
+   * Supports WHILE, UNTIL, and SPLIT activity kinds.
    *
    * @param {unknown} context - 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.
+   * @returns {Promise<unknown>} Final value produced by the pipeline.
+   * @throws {Sass} When no activities are registered, conflicting activity kinds are used, or execution fails.
    */
   async run(context) {
-    this.#debug(this.#tag.description)
+    if(!this.#actionWrapper)
+      this.#actionWrapper = await this.#actionBuilder.build()
+
     const actionWrapper = this.#actionWrapper
     const activities = actionWrapper.activities
 
     for(const activity of activities) {
-      activity.setActionHooks(this.#hooks)
-
-      const kind = activity.kind
-
-      // If we have no kind, then it's just a once.
-      // Get it over and done with!
-      if(!kind) {
-        context = await this.#executeActivity(activity, context)
-      } else {
-        const {WHILE,UNTIL} = ACTIVITY
-
-        const pred = activity.pred
-        const kindWhile = kind & WHILE
-        const kindUntil = kind & UNTIL
+      try {
+        // await timeout(500)
 
-        if(kindWhile && kindUntil)
-          throw Sass.new(
-            "For Kathy Griffin's sake! You can't do something while AND " +
-            "until. Pick one!"
-          )
+        const kind = activity.kind
 
-        if(kindWhile || kindUntil) {
-          for(;;) {
-
-            if(kindWhile)
-              if(!await this.#predicateCheck(activity,pred,context))
-                break
-
-            context = await this.#executeActivity(activity,context)
-
-            if(kindUntil)
-              if(!await this.#predicateCheck(activity,pred,context))
-                break
-          }
+        // If we have no kind, then it's just a once.
+        // Get it over and done with!
+        if(!kind) {
+          context = await this.#execute(activity, context)
         } else {
-          context = await this.#executeActivity(activity, context)
+          // Validate that only one activity kind bit is set
+          // (kind & (kind - 1)) !== 0 means multiple bits are set
+          const multipleBitsSet = (kind & (kind - 1)) !== 0
+          if(multipleBitsSet)
+            throw Sass.new(
+              "For Kathy Griffin's sake! You can't combine activity kinds. " +
+              "Pick one: WHILE, UNTIL, or SPLIT!"
+            )
+
+          const {WHILE,UNTIL,SPLIT} = ACTIVITY
+          const kindWhile = kind & WHILE
+          const kindUntil = kind & UNTIL
+          const kindSplit = kind & SPLIT
+
+          if(kindWhile || kindUntil) {
+            const predicate = activity.pred
+
+            for(;;) {
+
+              if(kindWhile)
+                if(!await this.#hasPredicate(activity,predicate,context))
+                  break
+
+              context = await this.#execute(activity,context)
+
+              if(kindUntil)
+                if(!await this.#hasPredicate(activity,predicate,context))
+                  break
+            }
+          } else if(kindSplit && activity.opKind === "ActionBuilder") {
+            // SPLIT activity: parallel execution with splitter/rejoiner pattern
+            const splitter = activity.splitter
+            const rejoiner = activity.rejoiner
+
+            if(!splitter || !rejoiner)
+              throw Sass.new(
+                `SPLIT activity "${String(activity.name)}" requires both splitter and rejoiner functions.`
+              )
+
+            const original = context
+            const splitContext = splitter.call(activity.action,context)
+            const newContext = await this.#execute(activity,splitContext,true)
+            const rejoined = rejoiner.call(activity.action, original,newContext)
+
+            context = rejoined
+          } else {
+            context = await this.#execute(activity, context)
+          }
         }
+      } catch(error) {
+        throw Sass.new("ActionRunner running activity", error)
       }
-
     }
 
     return context
   }
 
   /**
-   * Execute a single activity, recursing into nested action wrappers when needed.
+   * Execute a single activity, recursing into nested ActionBuilders when needed.
+   * Handles both function-based activities and ActionBuilder-based nested pipelines.
+   * Automatically propagates hooks to nested builders and handles dynamic ActionBuilder returns.
+   *
+   * When parallel=true, uses Piper.pipe() for concurrent execution with worker pool pattern.
+   * This is triggered by SPLIT activities where context is divided for parallel processing.
+   * Results from parallel execution are filtered to only include successful outcomes ({ok: true}).
    *
    * @param {import("./Activity.js").default} activity Pipeline activity descriptor.
    * @param {unknown} context Current pipeline context.
+   * @param {boolean} [parallel] Whether to use parallel execution (via pipe() instead of run()). Default: false.
    * @returns {Promise<unknown>} Resolved activity result.
+   * @throws {Sass} If the operation kind is invalid, or if SPLIT activity lacks splitter/rejoiner.
    * @private
    */
-  async #executeActivity(activity, context) {
+  async #execute(activity, context, parallel=false) {
     // What kind of op are we looking at? Is it a function?
-    // Or a class instance of type ActionWrapper?
+    // Or a class instance of type ActionBuilder?
     const opKind = activity.opKind
-    if(opKind === "ActionWrapper") {
+
+    if(opKind === "ActionBuilder") {
+      if(activity.hooks && !activity.op.hasActionHooks)
+        activity.op.withActionHooks(activity.hooks)
+
       const runner = new this.constructor(activity.op, {
-        debug: this.#debug,
-        hooks: this.#hooks,
+        debug: this.#debug, name: activity.name
       })
-        .setHooks(this.#hooksPath, this.#hooksClassName)
 
-      return await runner.run(context, true)
+      if(parallel) {
+        const piped = await runner.pipe(context)
+
+        return piped.filter(p => p.ok).map(p => p.value)
+      } else {
+        return await runner.run(context)
+      }
     } else if(opKind === "Function") {
-      return await activity.run(context)
+      try {
+        const result = await activity.run(context)
+
+        if(Data.isType(result, "ActionBuilder")) {
+          if(activity.hooks)
+            result.withActionHooks(activity.hooks)
+
+          const runner = new this.constructor(result, {
+            debug: this.#debug, name: result.name
+          })
+
+          if(parallel) {
+            const piped = await runner.pipe(context)
+
+            return piped.filter(p => p.ok).map(p => p.value)
+          } else {
+            return await runner.run(context)
+          }
+        } else {
+          return result
+        }
+      } catch(error) {
+        throw Sass.new("Executing activity", error)
+      }
     }
 
-    throw Sass.new("We buy Functions and ActionWrappers. Only. Not whatever that was.")
+    console.log(activity.opKind + " " + JSON.stringify(activity))
+
+    throw Sass.new("We buy Functions and ActionBuilders. Only. Not whatever that was.")
   }
 
   /**
@@ -182,7 +217,7 @@ export default class ActionRunner extends Piper {
    * @returns {Promise<boolean>} True when the predicate allows another iteration.
    * @private
    */
-  async #predicateCheck(activity,predicate,context) {
+  async #hasPredicate(activity,predicate,context) {
     Valid.type(predicate, "Function")
 
     return !!(await predicate.call(activity.action, context))
@@ -191,46 +226,4 @@ export default class ActionRunner extends Piper {
   toString() {
     return `[object ${this.constructor.name}]`
   }
-
-  /**
-   * Configure hooks to be lazily loaded when the pipeline runs.
-   *
-   * @param {string} hooksPath Absolute path to the module exporting the hooks class.
-   * @param {string} className Constructor to instantiate from the hooks module.
-   * @returns {this} Runner instance for chaining.
-   */
-  setHooks(hooksPath, className) {
-    this.#hooksPath = hooksPath
-    this.#hooksClassName = className
-
-    this.addSetup(() => this.#loadHooks())
-
-    return this
-  }
-
-  /**
-   * Import and instantiate the configured hooks module.
-   *
-   * @returns {Promise<null|void>} Null when hooks are disabled, otherwise void.
-   * @private
-   */
-  async #loadHooks() {
-    if(!this.#hooksPath)
-      return null
-
-    const file = new FileObject(this.#hooksPath)
-    if(!await file.exists)
-      throw Sass.new(`File '${file.uri} does not exist.`)
-
-    const module = await file.import()
-    const hooksClassName = this.#hooksClassName
-
-    Valid.type(module[hooksClassName], "Function")
-
-    const loaded = new module[hooksClassName]({
-      debug: this.#debug
-    })
-
-    this.#hooks = loaded
-  }
 }

package/src/lib/ActionWrapper.js

@@ -3,9 +3,11 @@ import Activity from "./Activity.js"
 /**
  * @typedef {object} WrappedActivityConfig
  * @property {string|symbol} name Activity identifier used by hooks/logs.
- * @property {(context: unknown) => unknown|Promise<unknown>|ActionWrapper} op Operation or nested wrapper to execute.
+ * @property {(context: unknown) => unknown|Promise<unknown>|import("./ActionBuilder.js").default} op Operation or nested ActionBuilder to execute.
  * @property {number} [kind] Optional loop semantic flags.
  * @property {(context: unknown) => boolean|Promise<boolean>} [pred] Predicate tied to WHILE/UNTIL semantics.
+ * @property {(context: unknown) => unknown} [splitter] Splitter function for SPLIT activities.
+ * @property {(originalContext: unknown, splitResults: unknown) => unknown} [rejoiner] Rejoiner function for SPLIT activities.
  * @property {unknown} [action] Parent action instance supplied when invoking the op.
  * @property {(message: string, level?: number, ...args: Array<unknown>) => void} [debug] Optional logger reference.
  */
@@ -31,24 +33,35 @@ export default class ActionWrapper {
    */
   #debug = () => {}
 
+  /**
+   * ActionHooks instance shared across all activities.
+   *
+   * @type {import("./ActionHooks.js").default|null}
+   */
+  #hooks = null
+
   /**
    * Create a wrapper from the builder payload.
    *
-   * @param {{activities: Map<string|symbol, WrappedActivityConfig>, debug: (message: string, level?: number, ...args: Array<unknown>) => void}} init Builder payload containing activities + logger.
+   * @param {object} config Builder payload containing activities + logger
+   * @param {Map<string|symbol, WrappedActivityConfig>} config.activities Activities map
+   * @param {(message: string, level?: number, ...args: Array<unknown>) => void} config.debug Debug function
+   * @param {object} config.hooks Hooks object
    */
-  constructor({activities,debug}) {
-    this.#debug = debug
-    this.#activities = activities
+  constructor(config) {
+    this.#debug = config.debug
+    this.#hooks = config.hooks
+    this.#activities = config.activities
     this.#debug(
       "Instantiating ActionWrapper with %o activities.",
       2,
-      activities.size,
+      this.#activities.size,
     )
   }
 
   *#_activities() {
     for(const [,activity] of this.#activities)
-      yield new Activity(activity)
+      yield new Activity({...activity, hooks: this.#hooks})
   }
 
   /**

package/src/lib/Activity.js

@@ -1,36 +1,65 @@
 import {Data} from "@gesslar/toolkit"
 
+/** @typedef {import("./ActionHooks.js").default} ActionHooks */
+
 /**
  * Activity bit flags recognised by the builder. The flag decides
  * loop semantics for an activity.
  *
  * @readonly
  * @enum {number}
+ * @property {number} WHILE - Execute activity while predicate returns true (2)
+ * @property {number} UNTIL - Execute activity until predicate returns false (4)
+ * @property {number} SPLIT - Execute activity with split/rejoin pattern for parallel execution (8)
  */
 export const ACTIVITY = Object.freeze({
   WHILE: 1<<1,
   UNTIL: 1<<2,
+  SPLIT: 1<<3,
 })
 
 export default class Activity {
+  /** @type {unknown} */
   #action = null
+  /** @type {unknown} */
+  #context = null
+  /** @type {ActionHooks|null} */
+  #hooks = null
+  /** @type {number|null} */
+  #kind = null
+  /** @type {string|symbol} */
   #name = null
+  /** @type {((context: unknown) => unknown|Promise<unknown>)|import("./ActionBuilder.js").default} */
   #op = null
-  #kind = null
+  /** @type {((context: unknown) => boolean|Promise<boolean>)|null} */
   #pred = null
-  #hooks = null
+  /** @type {((originalContext: unknown, splitResults: unknown) => unknown)|null} */
+  #rejoiner = null
+  /** @type {((context: unknown) => unknown)|null} */
+  #splitter = null
 
   /**
    * Construct an Activity definition wrapper.
    *
-   * @param {{action: unknown, name: string, op: (context: unknown) => unknown|Promise<unknown>|unknown, kind?: number, pred?: (context: unknown) => boolean|Promise<boolean>}} init - Initial properties describing the activity operation, loop semantics, and predicate
+   * @param {object} init - Initial properties describing the activity operation, loop semantics, and predicate
+   * @param {unknown} init.action - Parent action instance
+   * @param {string|symbol} init.name - Activity identifier
+   * @param {(context: unknown) => unknown|Promise<unknown>|import("./ActionBuilder.js").default} init.op - Operation to execute
+   * @param {number} [init.kind] - Optional loop semantics flags
+   * @param {(context: unknown) => boolean|Promise<boolean>} [init.pred] - Optional predicate for WHILE/UNTIL
+   * @param {ActionHooks} [init.hooks] - Optional hooks instance
+   * @param {(context: unknown) => unknown} [init.splitter] - Optional splitter function for SPLIT activities
+   * @param {(originalContext: unknown, splitResults: unknown) => unknown} [init.rejoiner] - Optional rejoiner function for SPLIT activities
    */
-  constructor({action,name,op,kind,pred}) {
+  constructor({action,name,op,kind,pred,hooks,splitter,rejoiner}) {
+    this.#action = action
+    this.#hooks = hooks
+    this.#kind = kind
     this.#name = name
     this.#op = op
-    this.#kind = kind
-    this.#action = action
     this.#pred = pred
+    this.#rejoiner = rejoiner
+    this.#splitter = splitter
   }
 
   /**
@@ -61,7 +90,16 @@ export default class Activity {
   }
 
   /**
-   * The operator kind name (Function or ActionWrapper).
+   * The current context (if set).
+   *
+   * @returns {unknown} Current context value
+   */
+  get context() {
+    return this.#context
+  }
+
+  /**
+   * The operator kind name (Function or ActionBuilder).
    *
    * @returns {string} - Kind name extracted via Data.typeOf
    */
@@ -70,14 +108,32 @@ export default class Activity {
   }
 
   /**
-   * The operator to execute (function or nested wrapper).
+   * The operator to execute (function or nested ActionBuilder).
    *
-   * @returns {unknown} - Activity operation
+   * @returns {(context: unknown) => unknown|Promise<unknown>|import("./ActionBuilder.js").default} - Activity operation
    */
   get op() {
     return this.#op
   }
 
+  /**
+   * The splitter function for SPLIT activities.
+   *
+   * @returns {((context: unknown) => unknown)|null} Splitter function or null
+   */
+  get splitter() {
+    return this.#splitter
+  }
+
+  /**
+   * The rejoiner function for SPLIT activities.
+   *
+   * @returns {((originalContext: unknown, splitResults: unknown) => unknown)|null} Rejoiner function or null
+   */
+  get rejoiner() {
+    return this.#rejoiner
+  }
+
   /**
    * The action instance this activity belongs to.
    *
@@ -91,22 +147,17 @@ export default class Activity {
    * Execute the activity with before/after hooks.
    *
    * @param {unknown} context - Mutable context flowing through the pipeline
-   * @returns {Promise<{activityResult: unknown}>} - Activity result wrapper with new context
+   * @returns {Promise<unknown>} - Activity result
    */
   async run(context) {
-    const hooks = this.#hooks
-
     // before hook
-    const before = hooks?.[`before$${this.#name}`]
-    if(Data.typeOf(before) === "Function")
-      await before.call(hooks,context)
+    await this.#hooks?.callHook("before", this.#name, context)
 
+    // not a hook
     const result = await this.#op.call(this.#action,context)
 
     // after hook
-    const after = hooks?.[`after$${this.#name}`]
-    if(Data.typeOf(after) === "Function")
-      await after.call(hooks,context)
+    await this.#hooks?.callHook("after", this.#name, context)
 
     return result
   }
@@ -114,7 +165,7 @@ export default class Activity {
   /**
    * Attach hooks to this activity instance.
    *
-   * @param {unknown} hooks - Hooks instance with optional before$/after$ methods
+   * @param {ActionHooks} hooks - Hooks instance with optional before$/after$ methods
    * @returns {this} - This activity for chaining
    */
   setActionHooks(hooks) {
@@ -123,4 +174,13 @@ export default class Activity {
 
     return this
   }
+
+  /**
+   * Get the hooks instance attached to this activity.
+   *
+   * @returns {ActionHooks|null} The hooks instance or null
+   */
+  get hooks() {
+    return this.#hooks
+  }
 }