@gesslar/actioneer 0.2.1 → 0.2.2

package/README.md

@@ -44,6 +44,158 @@ import { ActionBuilder, ActionRunner } from "@gesslar/actioneer"
 
 If you'd like more complete typings or additional JSDoc, open an issue or send a PR — contributions welcome.
 
+## Activity Modes
+
+Actioneer supports four distinct execution modes for activities, allowing you to control how operations are executed:
+
+### Execute Once (Default)
+
+The simplest mode executes an activity exactly once per context:
+
+```js
+class MyAction {
+  setup(builder) {
+    builder.do("processItem", ctx => {
+      ctx.result = ctx.input * 2
+    })
+  }
+}
+```
+
+### WHILE Mode
+
+Loops while a predicate returns `true`. The predicate is evaluated **before** each iteration:
+
+```js
+import { ActionBuilder, ACTIVITY } from "@gesslar/actioneer"
+
+class CounterAction {
+  #shouldContinue = (ctx) => ctx.count < 10
+
+  #increment = (ctx) => {
+    ctx.count += 1
+  }
+
+  setup(builder) {
+    builder
+      .do("initialize", ctx => { ctx.count = 0 })
+      .do("countUp", ACTIVITY.WHILE, this.#shouldContinue, this.#increment)
+      .do("finish", ctx => { return ctx.count })
+  }
+}
+```
+
+The activity will continue executing as long as the predicate returns `true`. Once it returns `false`, execution moves to the next activity.
+
+### UNTIL Mode
+
+Loops until a predicate returns `true`. The predicate is evaluated **after** each iteration:
+
+```js
+import { ActionBuilder, ACTIVITY } from "@gesslar/actioneer"
+
+class ProcessorAction {
+  #queueIsEmpty = (ctx) => ctx.queue.length === 0
+
+  #processItem = (ctx) => {
+    const item = ctx.queue.shift()
+    ctx.processed.push(item)
+  }
+
+  setup(builder) {
+    builder
+      .do("initialize", ctx => {
+        ctx.queue = [1, 2, 3, 4, 5]
+        ctx.processed = []
+      })
+      .do("process", ACTIVITY.UNTIL, this.#queueIsEmpty, this.#processItem)
+      .do("finish", ctx => { return ctx.processed })
+  }
+}
+```
+
+The activity executes at least once, then continues while the predicate returns `false`. Once it returns `true`, execution moves to the next activity.
+
+### SPLIT Mode
+
+Executes with a split/rejoin pattern for parallel execution. This mode requires a splitter function to divide the context and a rejoiner function to recombine results:
+
+```js
+import { ActionBuilder, ACTIVITY } from "@gesslar/actioneer"
+
+class ParallelProcessor {
+  #split = (ctx) => {
+    // Split context into multiple items for parallel processing
+    return ctx.items.map(item => ({ item, processedBy: "worker" }))
+  }
+
+  #rejoin = (originalCtx, splitResults) => {
+    // Recombine parallel results back into original context
+    originalCtx.results = splitResults.map(r => r.item)
+    return originalCtx
+  }
+
+  #processItem = (ctx) => {
+    ctx.item = ctx.item.toUpperCase()
+  }
+
+  setup(builder) {
+    builder
+      .do("initialize", ctx => {
+        ctx.items = ["apple", "banana", "cherry"]
+      })
+      .do("parallel", ACTIVITY.SPLIT, this.#split, this.#rejoin, this.#processItem)
+      .do("finish", ctx => { return ctx.results })
+  }
+}
+```
+
+**How SPLIT Mode Works:**
+
+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
+4. The rejoiner combines the results and returns the updated context
+
+**Nested Pipelines with SPLIT:**
+
+You can use nested ActionBuilders with SPLIT mode for complex parallel workflows:
+
+```js
+class NestedParallel {
+  #split = (ctx) => ctx.batches.map(batch => ({ batch }))
+
+  #rejoin = (original, results) => {
+    original.processed = results.flatMap(r => r.batch)
+    return original
+  }
+
+  setup(builder) {
+    builder
+      .do("parallel", ACTIVITY.SPLIT, this.#split, this.#rejoin,
+        new ActionBuilder(this)
+          .do("step1", ctx => { /* ... */ })
+          .do("step2", ctx => { /* ... */ })
+      )
+  }
+}
+```
+
+### Mode Constraints
+
+- **Only one mode per activity**: You cannot combine WHILE, UNTIL, and SPLIT. Attempting to use multiple modes will throw an error: `"You can't combine activity kinds. Pick one: WHILE, UNTIL, or SPLIT!"`
+- **SPLIT requires both functions**: The splitter and rejoiner are both mandatory for SPLIT mode
+- **Predicates must return boolean**: For WHILE and UNTIL modes, predicates should return `true` or `false`
+
+### Mode Summary Table
+
+| Mode        | Signature                                                  | Predicate Timing | Use Case                             |
+| ----------- | ---------------------------------------------------------- | ---------------- | ------------------------------------ |
+| **Default** | `.do(name, operation)`                                     | N/A              | Execute once per context             |
+| **WHILE**   | `.do(name, ACTIVITY.WHILE, predicate, operation)`          | Before iteration | Loop while condition is true         |
+| **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 |
+
 ## 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.1",
+  "version": "0.2.2",
   "description": "Ready? Set?? ACTION!! pew! pew! pew!",
   "main": "./src/index.js",
   "type": "module",

package/src/lib/ActionBuilder.js

@@ -30,8 +30,6 @@ import ActionHooks from "./ActionHooks.js"
  * @property {ActionFunction|import("./ActionWrapper.js").default} op Operation to execute.
  * @property {number} [kind] Optional kind flags from {@link ActivityFlags}.
  * @property {(context: unknown) => boolean|Promise<boolean>} [pred] Loop predicate.
- * @property {(context: unknown) => unknown} [splitter] Function to split context for parallel execution (SPLIT activities).
- * @property {(originalContext: unknown, splitResults: unknown) => unknown} [rejoiner] Function to rejoin split results (SPLIT activities).
  */
 
 /**
@@ -67,29 +65,15 @@ export default class ActionBuilder {
   #debug = null
   /** @type {symbol|null} */
   #tag = null
-  /** @type {string|null} */
   #hooksFile = null
-  /** @type {string|null} */
   #hooksKind = null
-  /** @type {unknown|null} */
   #hooks = null
-  /** @type {import("./ActionHooks.js").default|null} */
-  #actionHooks = null
-
-  /**
-   * Get the builder's tag symbol.
-   *
-   * @returns {symbol|null} The tag symbol for this builder instance
-   */
-  get tag() {
-    return this.#tag
-  }
 
   /**
    * Creates a new ActionBuilder instance with the provided action callback.
    *
-   * @param {ActionBuilderAction} [action] - Base action invoked by the runner when a block satisfies the configured structure.
-   * @param {ActionBuilderConfig} [config] - Options
+   * @param {ActionBuilderAction} [action] Base action invoked by the runner when a block satisfies the configured structure.
+   * @param {ActionBuilderConfig} [config] Options
    */
   constructor(
     action,
@@ -128,16 +112,6 @@ export default class ActionBuilder {
    * @returns {ActionBuilder}
    */
 
-  /**
-   * @overload
-   * @param {string|symbol} name Activity name
-   * @param {number} kind Kind bitfield (ACTIVITY.SPLIT).
-   * @param {(context: unknown) => unknown} splitter Function to split context for parallel execution.
-   * @param {(originalContext: unknown, splitResults: unknown) => unknown} rejoiner Function to rejoin split results with original context.
-   * @param {ActionFunction|ActionBuilder} op Operation or nested ActionBuilder to execute on split context.
-   * @returns {ActionBuilder}
-   */
-
   /**
    * Handles runtime dispatch across the documented overloads.
    *
@@ -155,32 +129,22 @@ export default class ActionBuilder {
 
     const action = this.#action
     const debug = this.#debug
-    const activityDefinition = {name,action,debug}
+    const activityDefinition = {name, action, debug}
 
     if(args.length === 1) {
-      const [op,kind] = args
+      const [op, kind] = args
       Valid.type(kind, "Number|undefined")
       Valid.type(op, "Function")
 
-      Object.assign(activityDefinition, {op,kind})
+      Object.assign(activityDefinition, {op, kind})
     } else if(args.length === 3) {
-      const [kind,pred,op] = args
+      const [kind, pred, op] = args
 
       Valid.type(kind, "Number")
       Valid.type(pred, "Function")
       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")
-
-      Object.assign(activityDefinition, {kind,splitter,rejoiner,op})
-
+      Object.assign(activityDefinition, {kind, pred, op})
     } else {
       throw Sass.new("Invalid number of arguments passed to 'do'")
     }
@@ -199,7 +163,9 @@ export default class ActionBuilder {
    * @throws {Sass} If hooks have already been configured.
    */
   withHooksFile(hooksFile, hooksKind) {
-    Valid.assert(this.#exclusiveHooksCheck(), "Hooks have already been configured.")
+    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.")
 
     this.#hooksFile = hooksFile
     this.#hooksKind = hooksKind
@@ -215,40 +181,15 @@ export default class ActionBuilder {
    * @throws {Sass} If hooks have already been configured.
    */
   withHooks(hooks) {
-    Valid.assert(this.#exclusiveHooksCheck(), "Hooks have already been configured.")
+    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.")
 
     this.#hooks = hooks
 
     return this
   }
 
-  /**
-   * Configure hooks using an ActionHooks instance directly (typically used internally).
-   *
-   * @param {import("./ActionHooks.js").default} actionHooks Pre-configured ActionHooks instance.
-   * @returns {ActionBuilder} The builder instance for chaining.
-   * @throws {Sass} If hooks have already been configured.
-   */
-  withActionHooks(actionHooks) {
-    Valid.assert(this.#exclusiveHooksCheck(), "Hooks have already been configured.")
-
-    this.#actionHooks = actionHooks
-
-    return this
-  }
-
-  /**
-   * Ensures only one hooks configuration method is used at a time.
-   *
-   * @returns {boolean} True if no hooks have been configured yet, false otherwise.
-   * @private
-   */
-  #exclusiveHooksCheck() {
-    return !!(this.#hooksFile && this.#hooksKind) +
-           !!(this.#hooks) +
-           !!(this.#actionHooks) === 0
-  }
-
   /**
    * Validates that an activity name has not been reused.
    *
@@ -270,8 +211,6 @@ export default class ActionBuilder {
    */
   async build() {
     const action = this.#action
-    const activities = this.#activities
-    const debug = this.#debug
 
     if(!action.tag) {
       action.tag = this.#tag
@@ -282,47 +221,24 @@ export default class ActionBuilder {
     // All children in a branch also get the same hooks.
     const hooks = await this.#getHooks()
 
-    return new ActionWrapper({activities,hooks,debug})
-  }
-
-  /**
-   * Check if this builder has ActionHooks configured.
-   *
-   * @returns {boolean} True if ActionHooks have been configured.
-   */
-  get hasActionHooks() {
-    return this.#actionHooks !== null
+    return new ActionWrapper({
+      activities: this.#activities,
+      debug: this.#debug,
+      hooks,
+    })
   }
 
-  /**
-   * Internal method to retrieve or create ActionHooks instance.
-   * Caches the hooks instance to avoid redundant instantiation.
-   *
-   * @returns {Promise<import("./ActionHooks.js").default|undefined>} The ActionHooks instance if configured.
-   * @private
-   */
   async #getHooks() {
-    if(this.#actionHooks) {
-      return this.#actionHooks
-    }
-
     const newHooks = ActionHooks.new
 
     const hooks = this.#hooks
-
-    if(hooks) {
-      this.#actionHooks = await newHooks({hooks}, this.#debug)
-
-      return this.#actionHooks
-    }
+    if(hooks)
+      return await newHooks({hooks}, this.#debug)
 
     const hooksFile = this.#hooksFile
     const hooksKind = this.#hooksKind
 
-    if(hooksFile && hooksKind) {
-      this.#actionHooks = await newHooks({hooksFile,hooksKind}, this.#debug)
-
-      return this.#actionHooks
-    }
+    if(hooksFile && hooksKind)
+      return await newHooks({hooksFile,hooksKind}, this.#debug)
   }
 }

package/src/lib/ActionHooks.js

@@ -7,10 +7,11 @@ import {Data, FileObject, Sass, Util, Valid} from "@gesslar/toolkit"
 
 /**
  * @typedef {object} ActionHooksConfig
- * @property {string} [actionKind] Action identifier shared between runner and hooks.
- * @property {FileObject|string} [hooksFile] File handle or path used to import the hooks module.
- * @property {unknown} [hooksObject] Already-instantiated hooks implementation (skips loading).
+ * @property {string} actionKind Action identifier shared between runner and hooks.
+ * @property {FileObject} hooksFile File handle used to import the hooks module.
+ * @property {unknown} [hooks] Already-instantiated hooks implementation (skips loading).
  * @property {number} [hookTimeout] Timeout applied to hook execution in milliseconds.
+ * @property {DebugFn} debug Logger to emit diagnostics.
  */
 
 /**
@@ -26,7 +27,7 @@ export default class ActionHooks {
   /** @type {FileObject|null} */
   #hooksFile = null
   /** @type {HookModule|null} */
-  #hooksObject = null
+  #hooks = null
   /** @type {string|null} */
   #actionKind = null
   /** @type {number} */
@@ -38,15 +39,11 @@ export default class ActionHooks {
    * Creates a new ActionHook instance.
    *
    * @param {ActionHooksConfig} config Configuration values describing how to load the hooks.
-   * @param {(message: string, level?: number, ...args: Array<unknown>) => void} debug Debug function
    */
-  constructor(
-    {actionKind, hooksFile, hooksObject, hookTimeout = 1_000},
-    debug,
-  ) {
+  constructor({actionKind, hooksFile, hooks, hookTimeout = 1_000, debug}) {
     this.#actionKind = actionKind
     this.#hooksFile = hooksFile
-    this.#hooksObject = hooksObject
+    this.#hooks = hooks
     this.#timeout = hookTimeout
     this.#debug = debug
   }
@@ -54,7 +51,7 @@ export default class ActionHooks {
   /**
    * Gets the action identifier.
    *
-   * @returns {string|null} Action identifier or instance
+   * @returns {string} Action identifier or instance
    */
   get actionKind() {
     return this.#actionKind
@@ -63,7 +60,7 @@ export default class ActionHooks {
   /**
    * Gets the hooks file object.
    *
-   * @returns {FileObject|null} File object containing hooks
+   * @returns {FileObject} File object containing hooks
    */
   get hooksFile() {
     return this.#hooksFile
@@ -72,10 +69,10 @@ export default class ActionHooks {
   /**
    * Gets the loaded hooks object.
    *
-   * @returns {HookModule|null} Hooks object or null if not loaded
+   * @returns {object|null} Hooks object or null if not loaded
    */
   get hooks() {
-    return this.#hooksObject
+    return this.#hooks
   }
 
   /**
@@ -108,17 +105,17 @@ export default class ActionHooks {
   /**
    * Static factory method to create and initialize a hook manager.
    * Loads hooks from the specified file and returns an initialized instance.
-   * If a hooksObject is provided in config, it's used directly; otherwise, hooks are loaded from file.
+   * Override loadHooks() in subclasses to customize hook loading logic.
    *
-   * @param {ActionHooksConfig} config Configuration object with hooks settings
+   * @param {ActionHooksConfig} config Same configuration object as constructor
    * @param {DebugFn} debug The debug function.
-   * @returns {Promise<ActionHooks>} Initialized hook manager
+   * @returns {Promise<ActionHooks|null>} Initialized hook manager or null if no hooks found
    */
   static async new(config, debug) {
     debug("Creating new HookManager instance with args: %o", 2, config)
 
     const instance = new ActionHooks(config, debug)
-    if(!instance.#hooksObject) {
+    if(!instance.#hooks) {
       const hooksFile = new FileObject(instance.#hooksFile)
 
       debug("Loading hooks from %o", 2, hooksFile.uri)
@@ -143,7 +140,7 @@ export default class ActionHooks {
 
         debug(hooks.constructor.name, 4)
 
-        instance.#hooksObject = hooks
+        instance.#hooks = hooks
         debug("Hooks %o loaded successfully for %o", 2, hooksFile.uri, instance.actionKind)
 
         return instance
@@ -154,34 +151,31 @@ export default class ActionHooks {
       }
     }
 
-    return instance
+    return this
   }
 
   /**
-   * Invoke a dynamically-named hook such as `before$foo` or `after$foo`.
-   * The hook name is constructed by combining the kind with the activity name.
-   * Symbols are converted to their description. Non-alphanumeric characters are filtered out.
+   * Invoke a dynamically-named hook such as `before$foo`.
    *
    * @param {'before'|'after'|'setup'|'cleanup'|string} kind Hook namespace.
    * @param {string|symbol} activityName Activity identifier.
    * @param {unknown} context Pipeline context supplied to the hook.
    * @returns {Promise<void>}
-   * @throws {Sass} If the hook execution fails or exceeds timeout.
    */
   async callHook(kind, activityName, context) {
-    const debug = this.#debug
-    const hooks = this.#hooksObject
+    try {
+      const debug = this.#debug
+      const hooks = this.#hooks
 
-    if(!hooks)
-      return
+      if(!hooks)
+        return
 
-    const stringActivityName = Data.isType(activityName, "Symbol")
-      ? activityName.description()
-      : activityName
+      const stringActivityName = Data.isType("Symbol")
+        ? activityName.description()
+        : activityName
 
-    const hookName = this.#getActivityHookName(kind, stringActivityName)
+      const hookName = this.#getActivityHookName(kind, stringActivityName)
 
-    try {
       debug("Looking for hook: %o", 4, hookName)
 
       const hook = hooks[hookName]
@@ -195,7 +189,7 @@ export default class ActionHooks {
         debug("Hook function starting execution: %o", 4, hookName)
 
         const duration = (
-          await Util.time(() => hook.call(this.#hooksObject, context))
+          await Util.time(() => hook.call(this.#hooks, context))
         ).cost
 
         debug("Hook function completed successfully: %o, after %oms", 4, hookName, duration)
@@ -214,26 +208,16 @@ export default class ActionHooks {
           expireAsync
         ])
       } catch(error) {
-        throw Sass.new(`Processing hook ${hookName}`, error)
+        throw Sass.new(`Processing hook ${kind}$${activityName}`, error)
       }
 
       debug("We made it throoough the wildernessss", 4)
 
     } catch(error) {
-      throw Sass.new(`Processing hook ${hookName}`, error)
+      throw Sass.new(`Processing hook ${kind}$${activityName}`, error)
     }
   }
 
-  /**
-   * Transforms an activity name into a hook-compatible name.
-   * Converts "my activity name" to "myActivityName" and combines with event kind.
-   * Example: ("before", "my activity") => "before$myActivity"
-   *
-   * @param {string} event Hook event type (before, after, etc.)
-   * @param {string} activityName The raw activity name
-   * @returns {string} The formatted hook name
-   * @private
-   */
   #getActivityHookName(event, activityName) {
     const name = activityName
       .split(" ")