@gesslar/actioneer 0.2.3 → 0.2.4

package/README.md

@@ -335,13 +335,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.4",
   "description": "Ready? Set?? ACTION!! pew! pew! pew!",
   "main": "./src/index.js",
   "type": "module",

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

@@ -112,7 +112,7 @@ export default class ActionRunner extends Piper {
                 if(await this.#hasPredicate(activity,predicate,context))
                   break
             }
-          } else if(kindSplit && activity.opKind === "ActionBuilder") {
+          } else if(kindSplit) {
             // SPLIT activity: parallel execution with splitter/rejoiner pattern
             const splitter = activity.splitter
             const rejoiner = activity.rejoiner
@@ -123,8 +123,19 @@ export default class ActionRunner extends Piper {
               )
 
             const original = context
-            const splitContext = splitter.call(activity.action,context)
-            const newContext = await this.#execute(activity,splitContext,true)
+            const splitContexts = splitter.call(activity.action,context)
+
+            let newContext
+            if(activity.opKind === "ActionBuilder") {
+              // Use parallel execution for ActionBuilder
+              newContext = await this.#execute(activity,splitContexts,true)
+            } else {
+              // For plain functions, process each split context
+              newContext = await Promise.all(
+                splitContexts.map(ctx => this.#execute(activity,ctx))
+              )
+            }
+
             const rejoined = rejoiner.call(activity.action, original,newContext)
 
             context = rejoined
@@ -147,7 +158,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 +173,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 +191,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/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
   /**