@gesslar/actioneer 0.2.1 → 0.2.2

package/src/lib/ActionRunner.js

@@ -1,4 +1,4 @@
-import {Data, Sass, Valid} from "@gesslar/toolkit"
+import {Sass, Valid} from "@gesslar/toolkit"
 
 import ActionBuilder from "./ActionBuilder.js"
 import {ACTIVITY} from "./Activity.js"
@@ -20,10 +20,7 @@ import Piper from "./Piper.js"
  * context object under `result.value` that can be replaced or enriched.
  */
 export default class ActionRunner extends Piper {
-  /** @type {import("./ActionBuilder.js").default|null} */
   #actionBuilder = null
-  /** @type {import("./ActionWrapper.js").default|null} */
-  #actionWrapper = null
 
   /**
    * Logger invoked for diagnostics.
@@ -51,160 +48,82 @@ export default class ActionRunner extends Piper {
 
     this.#actionBuilder = actionBuilder
 
-    this.addStep(this.run, {
-      name: `ActionRunner for ${actionBuilder.tag.description}`
-    })
+    this.addStep(this.run)
   }
 
   /**
    * 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.
-   * @throws {Sass} When no activities are registered, conflicting activity kinds are used, or execution fails.
+   * @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(context) {
-    if(!this.#actionWrapper)
-      this.#actionWrapper = await this.#actionBuilder.build()
-
-    const actionWrapper = this.#actionWrapper
+    const actionWrapper = await this.#actionBuilder.build()
     const activities = actionWrapper.activities
 
     for(const activity of activities) {
-      try {
-        // await timeout(500)
+      const kind = activity.kind
 
-        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
 
-        // 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 {
-          // 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)
+        if(kindWhile && kindUntil)
+          throw Sass.new(
+            "For Kathy Griffin's sake! You can't do something while AND " +
+            "until. Pick one!"
+          )
+
+        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
           }
+        } else {
+          context = await this.#executeActivity(activity, context)
         }
-      } catch(error) {
-        throw Sass.new("ActionRunner running activity", error)
       }
+
     }
 
     return context
   }
 
   /**
-   * 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}).
+   * Execute a single activity, recursing into nested action wrappers when needed.
    *
    * @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 #execute(activity, context, parallel=false) {
+  async #executeActivity(activity, context) {
     // What kind of op are we looking at? Is it a function?
     // Or a class instance of type ActionBuilder?
     const opKind = activity.opKind
-
     if(opKind === "ActionBuilder") {
-      if(activity.hooks && !activity.op.hasActionHooks)
-        activity.op.withActionHooks(activity.hooks)
-
-      const runner = new this.constructor(activity.op, {
-        debug: this.#debug, name: activity.name
-      })
+      const runner = new this.constructor(activity.op, {debug: this.#debug})
 
-      if(parallel) {
-        const piped = await runner.pipe(context)
-
-        return piped.filter(p => p.ok).map(p => p.value)
-      } else {
-        return await runner.run(context)
-      }
+      return await runner.run(context, true)
     } else if(opKind === "Function") {
-      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)
-      }
+      return await activity.run(context)
     }
 
-    console.log(activity.opKind + " " + JSON.stringify(activity))
-
     throw Sass.new("We buy Functions and ActionBuilders. Only. Not whatever that was.")
   }
 
@@ -217,7 +136,7 @@ export default class ActionRunner extends Piper {
    * @returns {Promise<boolean>} True when the predicate allows another iteration.
    * @private
    */
-  async #hasPredicate(activity,predicate,context) {
+  async #predicateCheck(activity,predicate,context) {
     Valid.type(predicate, "Function")
 
     return !!(await predicate.call(activity.action, context))

package/src/lib/ActionWrapper.js

@@ -3,11 +3,9 @@ import Activity from "./Activity.js"
 /**
  * @typedef {object} WrappedActivityConfig
  * @property {string|symbol} name Activity identifier used by hooks/logs.
- * @property {(context: unknown) => unknown|Promise<unknown>|import("./ActionBuilder.js").default} op Operation or nested ActionBuilder to execute.
+ * @property {(context: unknown) => unknown|Promise<unknown>|ActionWrapper} op Operation or nested wrapper 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.
  */
@@ -33,29 +31,21 @@ 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 {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
+   * @param {{activities: Map<string|symbol, WrappedActivityConfig>, debug: (message: string, level?: number, ...args: Array<unknown>) => void}} init Builder payload containing activities + logger.
    */
-  constructor(config) {
-    this.#debug = config.debug
-    this.#hooks = config.hooks
-    this.#activities = config.activities
+  constructor({activities,hooks,debug}) {
+    this.#debug = debug
+    this.#hooks = hooks
+    this.#activities = activities
     this.#debug(
       "Instantiating ActionWrapper with %o activities.",
       2,
-      this.#activities.size,
+      activities.size,
     )
   }
 

package/src/lib/Activity.js

@@ -8,58 +8,32 @@ import {Data} from "@gesslar/toolkit"
  *
  * @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
-  /** @type {((context: unknown) => boolean|Promise<boolean>)|null} */
+  #kind = null
   #pred = null
-  /** @type {((originalContext: unknown, splitResults: unknown) => unknown)|null} */
-  #rejoiner = null
-  /** @type {((context: unknown) => unknown)|null} */
-  #splitter = null
+  #hooks = null
 
   /**
    * Construct an Activity definition wrapper.
    *
-   * @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
+   * @param {{action: unknown, name: string, op: (context: unknown) => unknown|Promise<unknown>|unknown, kind?: number, pred?: (context: unknown) => boolean|Promise<boolean>, hooks?: ActionHooks}} init - Initial properties describing the activity operation, loop semantics, and predicate
    */
-  constructor({action,name,op,kind,pred,hooks,splitter,rejoiner}) {
-    this.#action = action
-    this.#hooks = hooks
-    this.#kind = kind
+  constructor({action,name,op,kind,pred,hooks}) {
     this.#name = name
     this.#op = op
+    this.#kind = kind
+    this.#action = action
     this.#pred = pred
-    this.#rejoiner = rejoiner
-    this.#splitter = splitter
+    this.#hooks = hooks
   }
 
   /**
@@ -90,16 +64,7 @@ export default class Activity {
   }
 
   /**
-   * The current context (if set).
-   *
-   * @returns {unknown} Current context value
-   */
-  get context() {
-    return this.#context
-  }
-
-  /**
-   * The operator kind name (Function or ActionBuilder).
+   * The operator kind name (Function or ActionWrapper).
    *
    * @returns {string} - Kind name extracted via Data.typeOf
    */
@@ -108,32 +73,14 @@ export default class Activity {
   }
 
   /**
-   * The operator to execute (function or nested ActionBuilder).
+   * The operator to execute (function or nested wrapper).
    *
-   * @returns {(context: unknown) => unknown|Promise<unknown>|import("./ActionBuilder.js").default} - Activity operation
+   * @returns {unknown} - 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.
    *
@@ -147,7 +94,7 @@ export default class Activity {
    * Execute the activity with before/after hooks.
    *
    * @param {unknown} context - Mutable context flowing through the pipeline
-   * @returns {Promise<unknown>} - Activity result
+   * @returns {Promise<{activityResult: unknown}>} - Activity result wrapper with new context
    */
   async run(context) {
     // before hook
@@ -165,7 +112,7 @@ export default class Activity {
   /**
    * Attach hooks to this activity instance.
    *
-   * @param {ActionHooks} hooks - Hooks instance with optional before$/after$ methods
+   * @param {unknown} hooks - Hooks instance with optional before$/after$ methods
    * @returns {this} - This activity for chaining
    */
   setActionHooks(hooks) {
@@ -174,13 +121,4 @@ 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
-  }
 }

package/src/lib/Piper.js

@@ -2,20 +2,18 @@
  * Generic Pipeline - Process items through a series of steps with concurrency control
  *
  * This abstraction handles:
- * - Concurrent processing with configurable limits using worker pool pattern
- * - Pipeline of processing steps executed sequentially per item
+ * - Concurrent processing with configurable limits
+ * - Pipeline of processing steps
+ * - Result categorization (success/warning/error)
  * - Setup/cleanup lifecycle hooks
  * - Error handling and reporting
- * - Dynamic worker spawning to maintain concurrency
  */
 
 import {Sass, Tantrum, Util} from "@gesslar/toolkit"
 
 export default class Piper {
-  /** @type {(message: string, level?: number, ...args: Array<unknown>) => void} */
   #debug
 
-  /** @type {Map<string, Set<unknown>>} */
   #lifeCycle = new Map([
     ["setup", new Set()],
     ["process", new Set()],
@@ -32,19 +30,14 @@ export default class Piper {
   }
 
   /**
-   * Add a processing step to the pipeline.
-   * Each step is executed sequentially per item.
+   * Add a processing step to the pipeline
    *
    * @param {(context: unknown) => Promise<unknown>|unknown} fn Function that processes an item
-   * @param {{name: string, required?: boolean}} options Step options (name is required)
+   * @param {{name?: string, required?: boolean}} [options] Step options
    * @param {unknown} [newThis] Optional this binding
    * @returns {Piper} The pipeline instance (for chaining)
-   * @throws {Sass} If name is not provided in options
    */
   addStep(fn, options = {}, newThis) {
-    if(options.name == null)
-      throw Sass.new("Missing name for step.")
-
     this.#lifeCycle.get("process").add({
       fn: fn.bind(newThis ?? this),
       name: options.name || `Step ${this.#lifeCycle.get("process").size + 1}`,
@@ -82,70 +75,33 @@ export default class Piper {
   }
 
   /**
-   * Process items through the pipeline with concurrency control using a worker pool pattern.
-   * Workers are spawned up to maxConcurrent limit, and as workers complete, new workers
-   * are spawned to maintain concurrency until all items are processed.
-   *
-   * This implementation uses dynamic worker spawning to maintain concurrency:
-   * - Initial workers are spawned up to maxConcurrent limit
-   * - As each worker completes (success OR failure), a replacement worker is spawned if items remain
-   * - Worker spawning occurs in finally block to ensure resilience to individual worker failures
-   * - All results are collected with {ok, value} or {ok: false, error} structure
-   * - Processing continues even if individual workers fail, collecting all errors
+   * Process items through the pipeline with concurrency control
    *
    * @param {Array<unknown>|unknown} items - Items to process
-   * @param {number} [maxConcurrent] - Maximum concurrent items to process (default: 10)
-   * @returns {Promise<Array<{ok: boolean, value?: unknown, error?: Sass}>>} - Results with success/failure status
-   * @throws {Sass} If setup or teardown fails
+   * @param {number} maxConcurrent - Maximum concurrent items to process
+   * @returns {Promise<Array<unknown>>} - Collected results from steps
    */
   async pipe(items, maxConcurrent = 10) {
     items = Array.isArray(items)
       ? items
       : [items]
 
-    const pipeResult = []
-
-    let pendingCount = 0
-    let resolveAll
-    const allDone = new Promise(resolve => {
-      resolveAll = resolve
-    })
+    let itemIndex = 0
+    const allResults = []
 
-    /**
-     * Worker function that processes one item and potentially spawns a replacement.
-     * Uses shift() to atomically retrieve items from the queue, ensuring no duplicate processing.
-     * Spawns replacement workers in the finally block to guarantee resilience to errors.
-     *
-     * @private
-     */
     const processWorker = async() => {
-      if(items.length === 0) {
-        pendingCount--
-
-        if(pendingCount === 0)
-          resolveAll()
-
-        return
-      }
-
-      const item = items.shift()
-
-      try {
-        const result = await this.#processWorker(item)
-        pipeResult.push({ok: true, value: result})
-      } catch(error) {
-        pipeResult.push({ok: false, error: Sass.new("Processing pipeline item.", error)})
-      } finally {
-        // Spawn a replacement worker if there are more items
-        if(items.length > 0) {
-          pendingCount++
-          processWorker() // Don't await - let it run in parallel
+      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)
         }
-
-        if(--pendingCount === 0)
-          resolveAll()
-
-        this.#debug("pendingCount = %o", 2, pendingCount)
       }
     }
 
@@ -156,19 +112,15 @@ export default class Piper {
 
     try {
       // Start workers up to maxConcurrent limit
+      const workers = []
       const workerCount = Math.min(maxConcurrent, items.length)
-      pendingCount = workerCount
 
-      if(workerCount === 0) {
-        resolveAll() // No items to process
-      } else {
-        for(let i = 0; i < workerCount; i++) {
-          processWorker() // Don't await - let them all run in parallel
-        }
-      }
+      for(let i = 0; i < workerCount; i++)
+        workers.push(processWorker())
 
       // Wait for all workers to complete
-      await allDone
+      const processResult = await Util.settleAll(workers)
+      this.#processResult("Processing pipeline.", processResult)
     } finally {
       // Run cleanup hooks
       const teardownResult = await Util.settleAll(
@@ -177,31 +129,7 @@ export default class Piper {
       this.#processResult("Tearing down the pipeline.", teardownResult)
     }
 
-    return pipeResult
-  }
-
-  /**
-   * Process a single item through all pipeline steps.
-   *
-   * @param {unknown} item The item to process
-   * @returns {Promise<unknown>} Result from the final step
-   * @private
-   */
-  async #processWorker(item) {
-    try {
-      // Execute each step in sequence
-      let result = item
-
-      for(const step of this.#lifeCycle.get("process")) {
-        this.#debug("Executing step: %o", 4, step.name)
-
-        result = await step.fn(result) ?? result
-      }
-
-      return result
-    } catch(error) {
-      throw Sass.new("Processing an item.", error)
-    }
+    return allResults
   }
 
   /**
@@ -218,4 +146,29 @@ export default class Piper {
         settled.filter(r => r.status==="rejected").map(r => r.reason)
       )
   }
+
+  /**
+   * Process a single item through all pipeline steps
+   *
+   * @param {unknown} item The item to process
+   * @returns {Promise<unknown>} Result from the final step
+   * @private
+   */
+  async #processItem(item) {
+    // Execute each step in sequence
+    let result = item
+
+    for(const step of this.#lifeCycle.get("process")) {
+      this.#debug("Executing step: %o", 4, step.name)
+
+      try {
+        result = await step.fn(result) ?? result
+      } catch(error) {
+        if(step.required)
+          throw Sass.new(`Processing required step "${step.name}".`, error)
+      }
+    }
+
+    return result
+  }
 }