@gesslar/actioneer 2.1.0 → 2.3.1

package/README.md

@@ -1,6 +1,6 @@
 # Actioneer
 
-Actioneer is a small, focused action orchestration library for Node.js and browser environments. It provides a fluent builder for composing activities and a concurrent runner with lifecycle hooks and simple loop semantics (while/until). The project is written as ES modules and targets Node 20+ and modern browsers.
+Actioneer is a small, focused action orchestration library for Node.js and browser environments. It provides a fluent builder for composing activities and a concurrent runner with lifecycle hooks and control flow semantics (while/until/if/break/continue). The project is written as ES modules and targets Node 20+ and modern browsers.
 
 This repository extracts the action orchestration pieces from a larger codebase and exposes a compact API for building pipelines of work that can run concurrently with hook support and nested pipelines.
 
@@ -16,7 +16,7 @@ These classes work in browsers, Node.js, and browser-like environments such as T
 | ActionHooks | Lifecycle hook management (requires pre-instantiated hooks in browser) |
 | ActionRunner | Concurrent pipeline executor with configurable concurrency |
 | ActionWrapper | Activity container and iterator |
-| Activity | Activity definitions with WHILE, UNTIL, and SPLIT modes |
+| Activity | Activity definitions with WHILE, UNTIL, IF, BREAK, CONTINUE, and SPLIT modes |
 | Piper | Base concurrent processing with worker pools |
 
 ### Node.js
@@ -133,7 +133,7 @@ If you'd like more complete typings or additional JSDoc, open an issue or send a
 
 ## Activity Modes
 
-Actioneer supports four distinct execution modes for activities, allowing you to control how operations are executed:
+Actioneer supports six distinct execution modes for activities, allowing you to control how operations are executed:
 
 ### Execute Once (Default)
 
@@ -203,6 +203,133 @@ class ProcessorAction {
 
 The activity executes at least once, then continues while the predicate returns `false`. Once it returns `true`, execution moves to the next activity.
 
+### IF Mode
+
+Conditionally executes an activity based on a predicate. Unlike WHILE/UNTIL, IF executes at most once:
+
+```js
+import { ActionBuilder, ACTIVITY } from "@gesslar/actioneer"
+
+class ConditionalAction {
+  #shouldProcess = (ctx) => ctx.value > 10
+
+  #processLargeValue = (ctx) => {
+    ctx.processed = ctx.value * 2
+  }
+
+  setup(builder) {
+    builder
+      .do("initialize", ctx => { ctx.value = 15 })
+      .do("maybeProcess", ACTIVITY.IF, this.#shouldProcess, this.#processLargeValue)
+      .do("finish", ctx => { return ctx })
+  }
+}
+```
+
+If the predicate returns `true`, the activity executes once. If `false`, the activity is skipped entirely and execution moves to the next activity.
+
+### BREAK Mode
+
+Breaks out of a WHILE or UNTIL loop when a predicate returns `true`. BREAK must be used inside a nested ActionBuilder within a loop:
+
+```js
+import { ActionBuilder, ACTIVITY } from "@gesslar/actioneer"
+
+class BreakExample {
+  setup(builder) {
+    builder
+      .do("initialize", ctx => {
+        ctx.count = 0
+        ctx.items = []
+      })
+      .do("loop", ACTIVITY.WHILE, ctx => ctx.count < 100,
+        new ActionBuilder()
+          .do("increment", ctx => {
+            ctx.count++
+            ctx.items.push(ctx.count)
+            return ctx
+          })
+          .do("earlyExit", ACTIVITY.BREAK, ctx => ctx.count >= 5)
+      )
+      .do("finish", ctx => { return ctx.items }) // Returns [1, 2, 3, 4, 5]
+  }
+}
+```
+
+When the BREAK predicate returns `true`, the loop terminates immediately and execution continues with the next activity after the loop.
+
+**Important:** BREAK only works inside a nested ActionBuilder that is the operation of a WHILE or UNTIL activity. Using BREAK outside of a loop context will throw an error.
+
+### CONTINUE Mode
+
+Skips the remaining activities in the current loop iteration and continues to the next iteration. Like BREAK, CONTINUE must be used inside a nested ActionBuilder within a loop:
+
+```js
+import { ActionBuilder, ACTIVITY } from "@gesslar/actioneer"
+
+class ContinueExample {
+  setup(builder) {
+    builder
+      .do("initialize", ctx => {
+        ctx.count = 0
+        ctx.processed = []
+      })
+      .do("loop", ACTIVITY.WHILE, ctx => ctx.count < 5,
+        new ActionBuilder()
+          .do("increment", ctx => {
+            ctx.count++
+            return ctx
+          })
+          .do("skipEvens", ACTIVITY.CONTINUE, ctx => ctx.count % 2 === 0)
+          .do("process", ctx => {
+            ctx.processed.push(ctx.count)
+            return ctx
+          })
+      )
+      .do("finish", ctx => { return ctx.processed }) // Returns [1, 3, 5]
+  }
+}
+```
+
+When the CONTINUE predicate returns `true`, the remaining activities in that iteration are skipped, and the loop continues with its next iteration (re-evaluating the loop predicate for WHILE, or executing the operation then evaluating for UNTIL).
+
+**Important:** Like BREAK, CONTINUE only works inside a nested ActionBuilder within a WHILE or UNTIL loop.
+
+### Combining Control Flow
+
+You can combine IF, BREAK, and CONTINUE within the same loop for complex control flow:
+
+```js
+class CombinedExample {
+  setup(builder) {
+    builder
+      .do("initialize", ctx => {
+        ctx.count = 0
+        ctx.results = []
+      })
+      .do("loop", ACTIVITY.WHILE, ctx => ctx.count < 100,
+        new ActionBuilder()
+          .do("increment", ctx => { ctx.count++; return ctx })
+          .do("exitAt10", ACTIVITY.BREAK, ctx => ctx.count > 10)
+          .do("skipEvens", ACTIVITY.CONTINUE, ctx => ctx.count % 2 === 0)
+          .do("processLarge", ACTIVITY.IF, ctx => ctx.count > 5, ctx => {
+            ctx.results.push(ctx.count * 10)
+            return ctx
+          })
+          .do("processAll", ctx => {
+            ctx.results.push(ctx.count)
+            return ctx
+          })
+      )
+  }
+}
+// Results: [1, 3, 5, 70, 7, 90, 9]
+// - 1, 3, 5: odd numbers <= 5, just pushed
+// - 7, 9: odd numbers > 5, pushed with *10 first, then pushed
+// - evens skipped by CONTINUE
+// - loop exits when count > 10
+```
+
 ### 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:
@@ -301,18 +428,22 @@ class NestedParallel {
 
 ### 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!"`
+- **Only one mode per activity**: Each activity can have only one mode. Attempting to combine modes will throw an error
 - **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`
+- **Predicates must return boolean**: All predicates (WHILE, UNTIL, IF, BREAK, CONTINUE) should return `true` or `false`
+- **BREAK/CONTINUE require loop context**: These modes only work inside a nested ActionBuilder within a WHILE or UNTIL loop
 
 ### 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 |
+| 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                |
+| **IF**       | `.do(name, ACTIVITY.IF, predicate, operation)`             | Before execution | Conditional execution (once or skip)        |
+| **BREAK**    | `.do(name, ACTIVITY.BREAK, predicate)`                     | When reached     | Exit enclosing WHILE/UNTIL loop             |
+| **CONTINUE** | `.do(name, ACTIVITY.CONTINUE, predicate)`                  | When reached     | Skip to next iteration of enclosing loop    |
+| **SPLIT**    | `.do(name, ACTIVITY.SPLIT, splitter, rejoiner, operation)` | N/A              | Parallel execution with split/rejoin        |
 
 ## Running Actions: `run()` vs `pipe()`
 
@@ -376,6 +507,74 @@ The `pipe()` method uses `Promise.allSettled()` internally and returns an array
 
 This design ensures error handling responsibility stays at the call site - you decide how to handle failures rather than the framework deciding for you.
 
+## Pipeline Completion: `done()`
+
+The `done()` method registers a callback that executes after all activities in the pipeline complete, regardless of whether an error occurred. This is useful for cleanup, finalization, or returning a transformed result.
+
+```js
+import { ActionBuilder, ActionRunner } from "@gesslar/actioneer"
+
+class MyAction {
+  setup(builder) {
+    builder
+      .do("step1", ctx => { ctx.a = 1 })
+      .do("step2", ctx => { ctx.b = 2 })
+      .done(ctx => {
+        // This runs after all activities complete
+        return { total: ctx.a + ctx.b }
+      })
+  }
+}
+
+const builder = new ActionBuilder(new MyAction())
+const runner = new ActionRunner(builder)
+const result = await runner.run({})
+console.log(result) // { total: 3 }
+```
+
+### Key Behaviors
+
+- **Always executes**: The `done()` callback runs even if an earlier activity throws an error (similar to `finally` in try/catch)
+- **Top-level only**: The callback only runs for the outermost pipeline, not for nested builders inside loops (WHILE/UNTIL). However, for SPLIT activities, `done()` runs for each split context since each is an independent execution
+- **Transform the result**: Whatever you return from `done()` becomes the final pipeline result
+- **Access to action context**: The callback is bound to the action instance, so `this` refers to your action class
+- **Async support**: The callback can be async and return a Promise
+
+### Use Cases
+
+**Cleanup resources:**
+
+```js
+builder
+  .do("openConnection", ctx => { ctx.conn = openDb() })
+  .do("query", ctx => { ctx.data = ctx.conn.query("SELECT *") })
+  .done(ctx => {
+    ctx.conn.close() // Always close, even on error
+    return ctx.data
+  })
+```
+
+**Transform the final result:**
+
+```js
+builder
+  .do("gather", ctx => { ctx.items = [1, 2, 3] })
+  .do("process", ctx => { ctx.items = ctx.items.map(x => x * 2) })
+  .done(ctx => ctx.items) // Return just the items array, not the whole context
+```
+
+**Logging and metrics:**
+
+```js
+builder
+  .do("start", ctx => { ctx.startTime = Date.now() })
+  .do("work", ctx => { /* ... */ })
+  .done(ctx => {
+    console.log(`Pipeline completed in ${Date.now() - ctx.startTime}ms`)
+    return ctx
+  })
+```
+
 ## ActionHooks
 
 Actioneer supports lifecycle hooks that can execute before and after each activity in your pipeline. Hooks can be configured by file path (Node.js only) or by providing a pre-instantiated hooks object (Node.js and browser).
@@ -558,9 +757,9 @@ Run the comprehensive test suite with Node's built-in test runner:
 npm test
 ```
 
-The test suite includes 150+ tests covering all core classes and behaviors:
+The test suite includes 200+ tests covering all core classes and behaviors:
 
-- **Activity** - Activity definitions, ACTIVITY flags (WHILE, UNTIL, SPLIT), and execution
+- **Activity** - Activity definitions, ACTIVITY flags (WHILE, UNTIL, IF, BREAK, CONTINUE, 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

package/package.json

@@ -5,7 +5,7 @@
     "name": "gesslar",
     "url": "https://gesslar.dev"
   },
-  "version": "2.1.0",
+  "version": "2.3.1",
   "license": "Unlicense",
   "homepage": "https://github.com/gesslar/toolkit#readme",
   "repository": {
@@ -49,11 +49,11 @@
     "node": ">=22"
   },
   "dependencies": {
-    "@gesslar/toolkit": "^3.23.0"
+    "@gesslar/toolkit": "^3.34.0"
   },
   "devDependencies": {
-    "@gesslar/uglier": "^1.1.0",
-    "eslint": "^9.39.2",
+    "@gesslar/uglier": "^1.4.1",
+    "eslint": "^10.0.0",
     "typescript": "^5.9.3"
   },
   "scripts": {

package/src/browser/lib/ActionBuilder.js

@@ -4,36 +4,29 @@ 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 */
-
 /**
+ * Type imports and definitions.
+ *
+ * @import {default as ActionRunner} from "./ActionRunner.js"
+ *
  * @typedef {(message: string, level?: number, ...args: Array<unknown>) => void} DebugFn
- */
-
-/**
+ *
  * @typedef {object} ActionBuilderAction
- * @property {(builder: ActionBuilder) => void} setup Function invoked during {@link ActionBuilder#build} to register activities.
- * @property {symbol} [tag] Optional tag to reuse when reconstructing builders.
- */
-
-/**
+ * @property {(builder: ActionBuilder) => void} setup - Function invoked during {@link ActionBuilder} to register activities.
+ * @property {symbol} [tag] - Optional tag to reuse when reconstructing builders.
+ *
  * @typedef {object} ActionBuilderConfig
- * @property {symbol} [tag] Optional tag for the builder instance.
- * @property {DebugFn} [debug] Logger used by the pipeline internals.
- */
-
-/**
+ * @property {symbol} [tag] - Optional tag for the builder instance.
+ * @property {DebugFn} [debug] - Logger used by the pipeline internals.
+ *
  * @typedef {object} ActivityDefinition
- * @property {ActionBuilderAction|null} action Parent action instance when available.
- * @property {DebugFn|null} debug Logger function.
- * @property {string|symbol} name Activity identifier.
- * @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 {ActionBuilderAction|null} action - Parent action instance when available.
+ * @property {DebugFn|null} debug - Logger function.
+ * @property {string|symbol} name - Activity identifier.
+ * @property {ActionFunction|import("./ActionWrapper.js").default} op - Operation to execute.
+ * @property {number} [kind] - Optional kind flags from {@link ACTIVITY}.
+ * @property {(context: unknown) => boolean|Promise<boolean>} [pred] - Loop predicate.
+ *
  * @typedef {(context: unknown) => unknown|Promise<unknown>} ActionFunction
  */
 
@@ -58,24 +51,28 @@ import {ACTIVITY} from "./Activity.js"
  * @class ActionBuilder
  */
 export default class ActionBuilder {
-  /** @type {ActionBuilderAction|null} */
+  /** @type {ActionBuilderAction?} */
   #action = null
   /** @type {Map<string|symbol, ActivityDefinition>} */
   #activities = new Map([])
-  /** @type {DebugFn|null} */
+  /** @type {DebugFn?} */
   #debug = null
-  /** @type {symbol|null} */
+  /** @type {symbol?} */
   #tag = null
+  /** @type {string?} */
   #hooksFile = null
+  /** @type {string?} */
   #hooksKind = null
+  /** @type {ActionHooks?} */
   #hooks = null
+  /** @type {ActionFunction?} */
   #done = null
 
   /**
    * 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,
@@ -85,6 +82,9 @@ export default class ActionBuilder {
     this.#tag = this.#tag || tag
 
     if(action) {
+      if(action.tag)
+        throw Sass.new("Action has already been consumed by a builder and cannot be reused.")
+
       if(Data.typeOf(action.setup) !== "Function")
         throw Sass.new("Setup must be a function.")
 
@@ -100,41 +100,50 @@ export default class ActionBuilder {
    * Register an activity that the runner can execute.
    *
    * Overloads:
-   * - do(name, op)
-   * - do(name, kind, pred, opOrWrapper)
-   * - do(name, kind, splitter, rejoiner, opOrWrapper)
+   * - do(name, op) - Simple once-off activity
+   * - do(name, kind, pred) - BREAK/CONTINUE control flow (no op, just predicate)
+   * - do(name, kind, pred, opOrWrapper) - WHILE/UNTIL/IF with predicate and operation
+   * - do(name, kind, splitter, rejoiner, opOrWrapper) - SPLIT with parallel execution
    *
    * @overload
-   * @param {string|symbol} name Activity name
-   * @param {ActionFunction} op Operation to execute once.
+   * @param {string|symbol} name - Activity name
+   * @param {ActionFunction} op - Operation to execute once.
    * @returns {ActionBuilder}
    */
 
   /**
    * @overload
-   * @param {string|symbol} name Activity name
-   * @param {number} kind Kind bitfield from {@link ActivityFlags}.
-   * @param {(context: unknown) => boolean|Promise<boolean>} pred Predicate executed before/after the op.
-   * @param {ActionFunction|import("./ActionWrapper.js").default} op Operation or nested wrapper to execute.
+   * @param {string|symbol} name - Activity name
+   * @param {number} kind - ACTIVITY.BREAK or ACTIVITY.CONTINUE flag.
+   * @param {(context: unknown) => boolean|Promise<boolean>} pred - Predicate to evaluate for control flow.
    * @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.
+   * @param {string|symbol} name - Activity name
+   * @param {number} kind - Activity kind (WHILE, UNTIL, or IF) from {@link ACTIVITY}.
+   * @param {(context: unknown) => boolean|Promise<boolean>} pred - Predicate executed before/after the op.
+   * @param {ActionFunction|ActionBuilder} op - Operation or nested builder to execute.
+   * @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|ActionBuilder} op - Operation or nested builder to execute.
    * @returns {ActionBuilder}
    */
 
   /**
    * Handles runtime dispatch across the documented overloads.
    *
-   * @param {string|symbol} name Activity name
-   * @param {...unknown} args See overloads
-   * @returns {ActionBuilder} The builder instance for chaining
+   * @param {string|symbol} name - Activity name
+   * @param {...unknown} args - See overloads
+   * @returns {ActionBuilder} - The builder instance for chaining
    */
   do(name, ...args) {
     this.#dupeActivityCheck(name)
@@ -142,6 +151,7 @@ export default class ActionBuilder {
     // signatures
     // name, [function] => once
     // name, [number,function,function] => some kind of control operation (WHILE/UNTIL)
+    // name, [number,function] => some kind of control operation (BREAK/CONTINUE)
     // name, [number,function,function,function] => SPLIT operation with splitter/rejoiner
     // name, [number,function,ActionBuilder] => some kind of branch
 
@@ -155,6 +165,13 @@ export default class ActionBuilder {
       Valid.type(op, "Function")
 
       Object.assign(activityDefinition, {op, kind})
+    } else if(args.length === 2) {
+      const [kind, pred] = args
+      Valid.type(kind, "Number")
+      Valid.type(pred, "Function")
+      Valid.assert(kind === ACTIVITY.BREAK || kind === ACTIVITY.CONTINUE, "Invalid arguments for BREAK/CONTINUE.")
+
+      Object.assign(activityDefinition, {kind, pred})
     } else if(args.length === 3) {
       const [kind, pred, op] = args
 
@@ -172,7 +189,7 @@ export default class ActionBuilder {
       Valid.type(op, "Function|ActionBuilder")
 
       // Validate that kind is SPLIT
-      if((kind & ACTIVITY.SPLIT) !== ACTIVITY.SPLIT)
+      if(kind !== ACTIVITY.SPLIT)
         throw Sass.new("4-argument form of 'do' is only valid for ACTIVITY.SPLIT")
 
       Object.assign(activityDefinition, {kind, splitter, rejoiner, op})
@@ -188,9 +205,9 @@ export default class ActionBuilder {
   /**
    * Configure hooks to be loaded from a file when the action is built.
    *
-   * @param {string} hooksFile Path to the hooks module file.
-   * @param {string} hooksKind Name of the exported hooks class to instantiate.
-   * @returns {ActionBuilder} The builder instance for chaining.
+   * @param {string} hooksFile - Path to the hooks module file.
+   * @param {string} hooksKind - Name of the exported hooks class to instantiate.
+   * @returns {ActionBuilder} - The builder instance for chaining.
    * @throws {Sass} If hooks have already been configured.
    */
   withHooksFile(hooksFile, hooksKind) {
@@ -207,8 +224,8 @@ export default class ActionBuilder {
   /**
    * Configure hooks using a pre-instantiated hooks object.
    *
-   * @param {import("./ActionHooks.js").default} hooks An already-instantiated hooks instance.
-   * @returns {ActionBuilder} The builder instance for chaining.
+   * @param {ActionHooks} hooks - An already-instantiated hooks instance.
+   * @returns {ActionBuilder} - The builder instance for chaining.
    * @throws {Sass} If hooks have already been configured with a different instance.
    */
   withHooks(hooks) {
@@ -230,7 +247,7 @@ export default class ActionBuilder {
    * Configure the action instance if not already set.
    * Used to propagate parent action context to nested builders.
    *
-   * @param {ActionBuilderAction} action The action instance to inherit.
+   * @param {ActionBuilderAction} action - The action instance to inherit.
    * @returns {ActionBuilder} The builder instance for chaining.
    */
   withAction(action) {
@@ -250,7 +267,7 @@ export default class ActionBuilder {
   /**
    * Register a callback to be executed after all activities complete.
    *
-   * @param {ActionFunction} callback Function to execute at the end of the pipeline.
+   * @param {ActionFunction} callback - Function to execute at the end of the pipeline.
    * @returns {ActionBuilder} The builder instance for chaining.
    */
   done(callback) {
@@ -264,7 +281,7 @@ export default class ActionBuilder {
    * Validates that an activity name has not been reused.
    *
    * @private
-   * @param {string | symbol} name Activity identifier.
+   * @param {string|symbol} name Activity identifier.
    */
   #dupeActivityCheck(name) {
     Valid.assert(
@@ -277,9 +294,9 @@ export default class ActionBuilder {
    * Finalises the builder and returns a payload that can be consumed by the
    * runner.
    *
-   * @returns {Promise<import("./ActionWrapper.js").default>} Payload consumed by the {@link ActionRunner} constructor.
+   * @returns {Promise<ActionWrapper>} Payload consumed by the {@link ActionRunner} constructor.
    */
-  async build() {
+  async build(runner) {
     const action = this.#action
 
     if(action && !action.tag) {
@@ -288,6 +305,20 @@ export default class ActionBuilder {
       await Promise.resolve(action.setup.call(action, this))
     }
 
+    if(action) {
+    // Inject a method to the action for emission, but only if it's undefined.
+      if(Data.isType(action.emit, "Undefined"))
+        action.emit = (...args) => runner.emit(...args)
+
+      // Inject a method to the action for onission, but only if it's undefined.
+      if(Data.isType(action.on, "Undefined"))
+        action.on = (event, cb) => runner.on(event, cb)
+
+      // Inject a method to the action for offission, but only if it's undefined.
+      if(Data.isType(action.off, "Undefined"))
+        action.off = (event, cb) => runner.off(event, cb)
+    }
+
     // All children in a branch also get the same hooks.
     const hooks = await this.#getHooks()
 
@@ -296,7 +327,8 @@ export default class ActionBuilder {
       debug: this.#debug,
       hooks,
       done: this.#done,
-      action: this.#action,
+      action,
+      runner: runner,
     })
   }