@gesslar/actioneer 0.2.4 → 0.2.7

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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gesslar/actioneer",
-  "version": "0.2.4",
+  "version": "0.2.7",
   "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

@@ -247,7 +247,7 @@ export default class ActionBuilder {
   async build() {
     const action = this.#action
 
-    if(!action.tag) {
+    if(action && !action.tag) {
       action.tag = this.#tag
 
       action.setup.call(action, this)

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"
@@ -113,30 +113,45 @@ export default class ActionRunner extends Piper {
                   break
             }
           } else if(kindSplit) {
-            // SPLIT activity: parallel execution with splitter/rejoiner pattern
-            const splitter = activity.splitter
-            const rejoiner = activity.rejoiner
+            // 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 splitContexts = splitter.call(activity.action,context)
+            const splitContexts = await splitter.call(activity.action, context)
+
+            let settled
 
-            let newContext
             if(activity.opKind === "ActionBuilder") {
-              // Use parallel execution for ActionBuilder
-              newContext = await this.#execute(activity,splitContexts,true)
+              // 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
-              newContext = await Promise.all(
-                splitContexts.map(ctx => this.#execute(activity,ctx))
+              settled = await Util.settleAll(
+                splitContexts.map(ctx => this.#execute(activity, ctx))
               )
             }
 
-            const rejoined = rejoiner.call(activity.action, original,newContext)
+            const rejoined = await rejoiner.call(
+              activity.action,
+              original,
+              settled
+            )
 
             context = rejoined
           } else {

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