@gesslar/actioneer 0.2.3 → 0.2.6

package/README.md

@@ -30,8 +30,16 @@ class MyAction {
 
 const builder = new ActionBuilder(new MyAction())
 const runner = new ActionRunner(builder)
-const result = await runner.pipe([{}], 4) // run up to 4 contexts concurrently
-console.log(result)
+const results = await runner.pipe([{}], 4) // run up to 4 contexts concurrently
+
+// pipe() returns settled results: {status: "fulfilled", value: ...} or {status: "rejected", reason: ...}
+results.forEach(result => {
+  if (result.status === "fulfilled") {
+    console.log("Count:", result.value)
+  } else {
+    console.error("Error:", result.reason)
+  }
+})
 ```
 
 ## Types (TypeScript / VS Code)
@@ -154,9 +162,40 @@ class ParallelProcessor {
 
 1. The **splitter** function receives the context and returns an array of contexts (one per parallel task)
 2. Each split context is processed in parallel through the **operation** function
-3. The **rejoiner** function receives the original context and the array of processed results
+3. The **rejoiner** function receives the original context and the array of settled results from `Promise.allSettled()`
 4. The rejoiner combines the results and returns the updated context
 
+**Important: SPLIT uses `Promise.allSettled()`**
+
+The SPLIT mode uses `Promise.allSettled()` internally to execute parallel operations. This means your **rejoiner** function will receive an array of settlement objects, not the raw context values. Each element in the array will be either:
+
+- `{ status: "fulfilled", value: <result> }` for successful operations
+- `{ status: "rejected", reason: <error> }` for failed operations
+
+Your rejoiner must handle settled results accordingly. You can process them however you need - check each `status` manually, or use helper utilities like those in `@gesslar/toolkit`:
+
+```js
+import { Util } from "@gesslar/toolkit"
+
+#rejoin = (originalCtx, settledResults) => {
+  // settledResults is an array of settlement objects
+  // Each has either { status: "fulfilled", value: ... }
+  // or { status: "rejected", reason: ... }
+
+  // Example: extract only successful results
+  originalCtx.results = Util.fulfilledValues(settledResults)
+
+  // Example: check for any failures
+  if (Util.anyRejected(settledResults)) {
+    originalCtx.errors = Util.rejectedReasons(
+      Util.settledAndRejected(settledResults)
+    )
+  }
+
+  return originalCtx
+}
+```
+
 **Nested Pipelines with SPLIT:**
 
 You can use nested ActionBuilders with SPLIT mode for complex parallel workflows:
@@ -196,6 +235,68 @@ class NestedParallel {
 | **UNTIL**   | `.do(name, ACTIVITY.UNTIL, predicate, operation)`          | After iteration  | Loop until condition is true         |
 | **SPLIT**   | `.do(name, ACTIVITY.SPLIT, splitter, rejoiner, operation)` | N/A              | Parallel execution with split/rejoin |
 
+## Running Actions: `run()` vs `pipe()`
+
+ActionRunner provides two methods for executing your action pipelines:
+
+### `run(context)` - Single Context Execution
+
+Executes the pipeline once with a single context. Returns the final context value directly, or throws if an error occurs.
+
+```js
+const builder = new ActionBuilder(new MyAction())
+const runner = new ActionRunner(builder)
+
+try {
+  const result = await runner.run({input: "data"})
+  console.log(result) // Final context value
+} catch (error) {
+  console.error("Pipeline failed:", error)
+}
+```
+
+**Use `run()` when:**
+
+- Processing a single context
+- You want errors to throw immediately
+- You prefer traditional try/catch error handling
+
+### `pipe(contexts, maxConcurrent)` - Concurrent Batch Execution
+
+Executes the pipeline concurrently across multiple contexts with a configurable concurrency limit. Returns an array of **settled results** - never throws on individual pipeline failures.
+
+```js
+const builder = new ActionBuilder(new MyAction())
+const runner = new ActionRunner(builder)
+
+const contexts = [{id: 1}, {id: 2}, {id: 3}]
+const results = await runner.pipe(contexts, 4) // Max 4 concurrent
+
+results.forEach((result, i) => {
+  if (result.status === "fulfilled") {
+    console.log(`Context ${i} succeeded:`, result.value)
+  } else {
+    console.error(`Context ${i} failed:`, result.reason)
+  }
+})
+```
+
+**Use `pipe()` when:**
+
+- Processing multiple contexts in parallel
+- You want to control concurrency (default: 10)
+- You need all results (both successes and failures)
+- Error handling should be at the call site
+
+**Important: `pipe()` returns settled results**
+
+The `pipe()` method uses `Promise.allSettled()` internally and returns an array of settlement objects:
+
+- `{status: "fulfilled", value: <result>}` for successful executions
+- `{status: "rejected", reason: <error>}` for failed executions
+
+This design ensures error handling responsibility stays at the call site - you decide how to handle failures rather than the framework deciding for you.
+
 ## ActionHooks
 
 Actioneer supports lifecycle hooks that can execute before and after each activity in your pipeline. Hooks are loaded from a module and can be configured either by file path or by providing a pre-instantiated hooks object.
@@ -335,13 +436,22 @@ Examples of minimal configs and one-liners to run them are in the project discus
 
 ## Testing
 
-Run the small smoke tests with Node's built-in test runner:
+Run the comprehensive test suite with Node's built-in test runner:
 
 ```bash
 npm test
 ```
 
-The test suite is intentionally small; it verifies public exports and a few core behaviors. Add more unit tests under `tests/` if you need deeper coverage.
+The test suite includes 150+ tests covering all core classes and behaviors:
+
+- **Activity** - Activity definitions, ACTIVITY flags (WHILE, UNTIL, SPLIT), and execution
+- **ActionBuilder** - Fluent builder API, activity registration, and hooks configuration
+- **ActionWrapper** - Activity iteration and integration with ActionBuilder
+- **ActionRunner** - Pipeline execution, loop semantics, nested builders, and error handling
+- **ActionHooks** - Hook lifecycle, loading from files, and timeout handling
+- **Piper** - Concurrent processing, worker pools, and lifecycle hooks
+
+Tests are organized in `tests/unit/` with one file per class. All tests use Node's native test runner and assertion library.
 
 ## Publishing
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gesslar/actioneer",
-  "version": "0.2.3",
+  "version": "0.2.6",
   "description": "Ready? Set?? ACTION!! pew! pew! pew!",
   "main": "./src/index.js",
   "type": "module",
@@ -56,6 +56,6 @@
     "typescript": "^5.9.3"
   },
   "dependencies": {
-    "@gesslar/toolkit": "^0.7.0"
+    "@gesslar/toolkit": "^1.9.1"
   }
 }

package/src/lib/ActionBuilder.js

@@ -2,6 +2,7 @@ import {Data, Sass, Valid} from "@gesslar/toolkit"
 
 import ActionWrapper from "./ActionWrapper.js"
 import ActionHooks from "./ActionHooks.js"
+import {ACTIVITY} from "./Activity.js"
 
 /** @typedef {import("./ActionRunner.js").default} ActionRunner */
 /** @typedef {typeof import("./Activity.js").ACTIVITY} ActivityFlags */
@@ -100,6 +101,7 @@ export default class ActionBuilder {
    * Overloads:
    * - do(name, op)
    * - do(name, kind, pred, opOrWrapper)
+   * - do(name, kind, splitter, rejoiner, opOrWrapper)
    *
    * @overload
    * @param {string|symbol} name Activity name
@@ -116,6 +118,16 @@ export default class ActionBuilder {
    * @returns {ActionBuilder}
    */
 
+  /**
+   * @overload
+   * @param {string|symbol} name Activity name
+   * @param {number} kind ACTIVITY.SPLIT flag.
+   * @param {(context: unknown) => unknown} splitter Splitter function for SPLIT mode.
+   * @param {(originalContext: unknown, splitResults: unknown) => unknown} rejoiner Rejoiner function for SPLIT mode.
+   * @param {ActionFunction|import("./ActionWrapper.js").default} op Operation or nested wrapper to execute.
+   * @returns {ActionBuilder}
+   */
+
   /**
    * Handles runtime dispatch across the documented overloads.
    *
@@ -128,7 +140,8 @@ export default class ActionBuilder {
 
     // signatures
     // name, [function] => once
-    // name, [number,function,function] => some kind of control operation
+    // name, [number,function,function] => some kind of control operation (WHILE/UNTIL)
+    // name, [number,function,function,function] => SPLIT operation with splitter/rejoiner
     // name, [number,function,ActionBuilder] => some kind of branch
 
     const action = this.#action
@@ -149,6 +162,19 @@ export default class ActionBuilder {
       Valid.type(op, "Function|ActionBuilder")
 
       Object.assign(activityDefinition, {kind, pred, op})
+    } else if(args.length === 4) {
+      const [kind, splitter, rejoiner, op] = args
+
+      Valid.type(kind, "Number")
+      Valid.type(splitter, "Function")
+      Valid.type(rejoiner, "Function")
+      Valid.type(op, "Function|ActionBuilder")
+
+      // Validate that kind is SPLIT
+      if((kind & ACTIVITY.SPLIT) !== ACTIVITY.SPLIT)
+        throw Sass.new("4-argument form of 'do' is only valid for ACTIVITY.SPLIT")
+
+      Object.assign(activityDefinition, {kind, splitter, rejoiner, op})
     } else {
       throw Sass.new("Invalid number of arguments passed to 'do'")
     }
@@ -182,9 +208,14 @@ export default class ActionBuilder {
    *
    * @param {import("./ActionHooks.js").default} hooks An already-instantiated hooks instance.
    * @returns {ActionBuilder} The builder instance for chaining.
-   * @throws {Sass} If hooks have already been configured.
+   * @throws {Sass} If hooks have already been configured with a different instance.
    */
   withHooks(hooks) {
+    // If the same hooks instance is already set, this is idempotent - just return
+    if(this.#hooks === hooks) {
+      return this
+    }
+
     Valid.assert(this.#hooksFile === null, "Hooks have already been configured.")
     Valid.assert(this.#hooksKind === null, "Hooks have already been configured.")
     Valid.assert(this.#hooks === null, "Hooks have already been configured.")
@@ -236,8 +267,14 @@ export default class ActionBuilder {
     const newHooks = ActionHooks.new
 
     const hooks = this.#hooks
-    if(hooks)
+    if(hooks) {
+      // If hooks is already an ActionHooks instance, use it directly
+      if(hooks instanceof ActionHooks)
+        return hooks
+
+      // Otherwise, wrap it in a new ActionHooks instance
       return await newHooks({hooks}, this.#debug)
+    }
 
     const hooksFile = this.#hooksFile
     const hooksKind = this.#hooksKind

package/src/lib/ActionHooks.js

@@ -114,7 +114,7 @@ export default class ActionHooks {
   static async new(config, debug) {
     debug("Creating new HookManager instance with args: %o", 2, config)
 
-    const instance = new ActionHooks(config, debug)
+    const instance = new ActionHooks({...config, debug})
     if(!instance.#hooks) {
       const hooksFile = new FileObject(instance.#hooksFile)
 
@@ -151,7 +151,7 @@ export default class ActionHooks {
       }
     }
 
-    return this
+    return instance
   }
 
   /**
@@ -170,8 +170,8 @@ export default class ActionHooks {
       if(!hooks)
         return
 
-      const stringActivityName = Data.isType("Symbol")
-        ? activityName.description()
+      const stringActivityName = Data.isType(activityName, "Symbol")
+        ? activityName.description
         : activityName
 
       const hookName = this.#getActivityHookName(kind, stringActivityName)

package/src/lib/ActionRunner.js

@@ -1,4 +1,4 @@
-import {Data, Sass, Valid} from "@gesslar/toolkit"
+import {Data, Sass, Util, Valid} from "@gesslar/toolkit"
 
 import ActionBuilder from "./ActionBuilder.js"
 import {ACTIVITY} from "./Activity.js"
@@ -112,20 +112,46 @@ export default class ActionRunner extends Piper {
                 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
+          } else if(kindSplit) {
+            // SPLIT activity: parallel execution with splitter/rejoiner
+            // pattern
+            const {splitter, rejoiner} = activity
 
             if(!splitter || !rejoiner)
               throw Sass.new(
-                `SPLIT activity "${String(activity.name)}" requires both splitter and rejoiner functions.`
+                `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)
+            const splitContexts = await splitter.call(activity.action, context)
+
+            let settled
+
+            if(activity.opKind === "ActionBuilder") {
+              // Use parallel execution for ActionBuilder with concurrency control
+              // pipe() now returns settled results
+              if(activity.hooks)
+                activity.op.withHooks(activity.hooks)
+
+              const runner = new this.constructor(activity.op, {
+                debug: this.#debug, name: activity.name
+              })
+
+              // pipe() returns settled results with concurrency control
+              settled = await runner.pipe(splitContexts)
+            } else {
+              // For plain functions, process each split context
+              settled = await Util.settleAll(
+                splitContexts.map(ctx => this.#execute(activity, ctx))
+              )
+            }
+
+            const rejoined = await rejoiner.call(
+              activity.action,
+              original,
+              settled
+            )
 
             context = rejoined
           } else {
@@ -147,7 +173,7 @@ export default class ActionRunner extends Piper {
    *
    * 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}).
+   * Results from parallel execution are returned directly as an array from Piper.pipe().
    *
    * @param {import("./Activity.js").default} activity Pipeline activity descriptor.
    * @param {unknown} context Current pipeline context.
@@ -162,17 +188,15 @@ export default class ActionRunner extends Piper {
     const opKind = activity.opKind
 
     if(opKind === "ActionBuilder") {
-      if(activity.hooks && !activity.op.hasActionHooks)
-        activity.op.withActionHooks(activity.hooks)
+      if(activity.hooks)
+        activity.op.withHooks(activity.hooks)
 
       const runner = new this.constructor(activity.op, {
         debug: this.#debug, name: activity.name
       })
 
       if(parallel) {
-        const piped = await runner.pipe(context)
-
-        return piped.filter(p => p.ok).map(p => p.value)
+        return await runner.pipe(context)
       } else {
         return await runner.run(context)
       }
@@ -182,16 +206,14 @@ export default class ActionRunner extends Piper {
 
         if(Data.isType(result, "ActionBuilder")) {
           if(activity.hooks)
-            result.withActionHooks(activity.hooks)
+            result.withHooks(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)
+            return await runner.pipe(context)
           } else {
             return await runner.run(context)
           }

package/src/lib/Piper.js

@@ -79,7 +79,7 @@ export default class Piper {
    *
    * @param {Array<unknown>|unknown} items - Items to process
    * @param {number} maxConcurrent - Maximum concurrent items to process
-   * @returns {Promise<Array<unknown>>} - Collected results from steps
+   * @returns {Promise<Array<{status: string, value?: unknown, reason?: unknown}>>} - Settled results from processing
    */
   async pipe(items, maxConcurrent = 10) {
     items = Array.isArray(items)
@@ -87,20 +87,23 @@ export default class Piper {
       : [items]
 
     let itemIndex = 0
-    const allResults = []
+    const allResults = new Array(items.length)
 
     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)
+
+          allResults[currentIndex] = {status: "fulfilled", value: result}
         } catch(error) {
-          throw Sass.new("Processing pipeline item.", error)
+          allResults[currentIndex] = {status: "rejected", reason: error}
         }
       }
     }
@@ -108,6 +111,7 @@ export default class Piper {
     const setupResult = await Util.settleAll(
       [...this.#lifeCycle.get("setup")].map(e => e())
     )
+
     this.#processResult("Setting up the pipeline.", setupResult)
 
     try {
@@ -118,14 +122,14 @@ export default class Piper {
       for(let i = 0; i < workerCount; i++)
         workers.push(processWorker())
 
-      // Wait for all workers to complete
-      const processResult = await Util.settleAll(workers)
-      this.#processResult("Processing pipeline.", processResult)
+      // Wait for all workers to complete - don't throw on worker failures
+      await Promise.all(workers)
     } finally {
       // Run cleanup hooks
       const teardownResult = await Util.settleAll(
         [...this.#lifeCycle.get("teardown")].map(e => e())
       )
+
       this.#processResult("Tearing down the pipeline.", teardownResult)
     }
 

package/src/types/lib/ActionBuilder.d.ts

@@ -89,7 +89,7 @@ export default class ActionBuilder {
    *
    * @param {import("./ActionHooks.js").default} hooks An already-instantiated hooks instance.
    * @returns {ActionBuilder} The builder instance for chaining.
-   * @throws {Sass} If hooks have already been configured.
+   * @throws {Sass} If hooks have already been configured with a different instance.
    */
   withHooks(hooks: import('./ActionHooks.js').default): ActionBuilder
   /**