@gesslar/actioneer 2.2.0 → 2.3.1

package/package.json

@@ -5,7 +5,7 @@
     "name": "gesslar",
     "url": "https://gesslar.dev"
   },
-  "version": "2.2.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.24.0"
+    "@gesslar/toolkit": "^3.34.0"
   },
   "devDependencies": {
-    "@gesslar/uglier": "^1.2.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,28 +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|null} */
+  /** @type {string?} */
   #hooksFile = null
-  /** @type {string|null} */
+  /** @type {string?} */
   #hooksKind = null
-  /** @type {import("./ActionHooks.js").default|null} */
+  /** @type {ActionHooks?} */
   #hooks = null
-  /** @type {ActionFunction|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,
@@ -89,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.")
 
@@ -110,44 +106,44 @@ export default class ActionBuilder {
    * - 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 ACTIVITY.BREAK or ACTIVITY.CONTINUE flag.
-   * @param {(context: unknown) => boolean|Promise<boolean>} pred Predicate to evaluate for control flow.
+   * @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 kind (WHILE, UNTIL, or IF) from {@link ActivityFlags}.
-   * @param {(context: unknown) => boolean|Promise<boolean>} pred Predicate executed before/after the op.
-   * @param {ActionFunction|ActionBuilder} op Operation or nested builder 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.
+   * @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)
@@ -209,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) {
@@ -228,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) {
@@ -251,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) {
@@ -271,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) {
@@ -285,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(
@@ -298,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) {
@@ -309,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()
 
@@ -317,7 +327,8 @@ export default class ActionBuilder {
       debug: this.#debug,
       hooks,
       done: this.#done,
-      action: this.#action,
+      action,
+      runner: runner,
     })
   }
 

package/src/browser/lib/ActionHooks.js

@@ -4,16 +4,14 @@ import {Data, Sass, Promised, Time, Util, Valid} from "@gesslar/toolkit"
  * @typedef {(message: string, level?: number, ...args: Array<unknown>) => void} DebugFn
  */
 
-/**
- * @typedef {object} ActionHooksConfig
- * @property {string} actionKind Action identifier shared between runner and hooks.
- * @property {unknown} hooks Already-instantiated hooks implementation.
- * @property {number} [hookTimeout] Timeout applied to hook execution in milliseconds.
- * @property {DebugFn} debug Logger to emit diagnostics.
- */
-
 /**
  * @typedef {Record<string, (context: unknown) => Promise<unknown>|unknown>} HookModule
+ *
+ * @typedef {object} ActionHooksConfig
+ * @property {string} actionKind - Action identifier shared between runner and hooks.
+ * @property {unknown} hooks - Already-instantiated hooks implementation.
+ * @property {number} [hookTimeout] - Timeout applied to hook execution in milliseconds.
+ * @property {DebugFn} debug - Logger to emit diagnostics.
  */
 
 /**
@@ -24,19 +22,19 @@ import {Data, Sass, Promised, Time, Util, Valid} from "@gesslar/toolkit"
  * Browser version: Requires pre-instantiated hooks. File-based loading is not supported.
  */
 export default class ActionHooks {
-  /** @type {HookModule|null} */
+  /** @type {HookModule?} */
   #hooks = null
-  /** @type {string|null} */
+  /** @type {string?} */
   #actionKind = null
   /** @type {number} */
   #timeout = 1_000 // Default 1 second timeout
-  /** @type {DebugFn|null} */
+  /** @type {DebugFn?} */
   #debug = null
 
   /**
    * Creates a new ActionHook instance.
    *
-   * @param {ActionHooksConfig} config Configuration values describing how to load the hooks.
+   * @param {ActionHooksConfig} config - Configuration values describing how to load the hooks.
    */
   constructor({actionKind, hooks, hookTimeout = 1_000, debug}) {
     this.#actionKind = actionKind
@@ -57,7 +55,7 @@ export default class ActionHooks {
   /**
    * Gets the loaded hooks object.
    *
-   * @returns {object|null} Hooks object or null if not loaded
+   * @returns {object?} Hooks object or null if not loaded
    */
   get hooks() {
     return this.#hooks
@@ -75,7 +73,7 @@ export default class ActionHooks {
   /**
    * Gets the setup hook function if available.
    *
-   * @returns {(args: object) => unknown|null} Setup hook function or null
+   * @returns {(args: object) => unknown} Setup hook function or null
    */
   get setup() {
     return this.hooks?.setup || null
@@ -84,7 +82,7 @@ export default class ActionHooks {
   /**
    * Gets the cleanup hook function if available.
    *
-   * @returns {(args: object) => unknown|null} Cleanup hook function or null
+   * @returns {(args: object) => unknown} Cleanup hook function or null
    */
   get cleanup() {
     return this.hooks?.cleanup || null
@@ -94,9 +92,9 @@ export default class ActionHooks {
    * Static factory method to create and initialize a hook manager.
    * Browser version: Only works with pre-instantiated hooks passed via config.hooks.
    *
-   * @param {ActionHooksConfig} config Configuration object with hooks property
-   * @param {DebugFn} debug The debug function.
-   * @returns {Promise<ActionHooks|null>} Initialized hook manager or null if no hooks provided
+   * @param {ActionHooksConfig} config - Configuration object with hooks property
+   * @param {DebugFn} debug - The debug function.
+   * @returns {Promise<ActionHooks?>} Initialized hook manager or null if no hooks provided
    */
   static async new(config, debug) {
     debug("Creating new HookManager instance with args: %o", 2, config)
@@ -117,9 +115,9 @@ export default class ActionHooks {
   /**
    * 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.
+   * @param {string} kind - Hook namespace.
+   * @param {string|symbol} activityName - Activity identifier.
+   * @param {unknown} context - Pipeline context supplied to the hook.
    * @returns {Promise<void>}
    */
   async callHook(kind, activityName, context) {

package/src/browser/lib/ActionRunner.js

@@ -1,17 +1,17 @@
-import {Promised, Data, Sass, Valid, Notify} from "@gesslar/toolkit"
+import {Promised, Data, Sass, Tantrum, Valid} from "@gesslar/toolkit"
 
 import {ACTIVITY} from "./Activity.js"
 import Piper from "./Piper.js"
 
 /**
- * @typedef {(message: string, level?: number, ...args: Array<unknown>) => void} DebugFn
- */
-
-/**
- * @typedef {import("./ActionBuilder.js").default} ActionBuilder
+ * Types
+ *
+ * @import {default as ActionBuilder} from "./ActionBuilder.js"
+ * @import {default as ActionWrapper} from "./ActionWrapper.js"
  */
-
 /**
+ * @typedef {(message: string, level?: number, ...args: Array<unknown>) => void} DebugFn
+ *
  * @typedef {object} ActionRunnerOptions
  * @property {DebugFn} [debug] Logger function.
  */
@@ -24,9 +24,9 @@ import Piper from "./Piper.js"
  * context object under `result.value` that can be replaced or enriched.
  */
 export default class ActionRunner extends Piper {
-  /** @type {import("./ActionBuilder.js").default|null} */
+  /** @type {ActionBuilder?} */
   #actionBuilder = null
-  /** @type {import("./ActionWrapper.js").default|null} */
+  /** @type {ActionWrapper?} */
   #actionWrapper = null
 
   /**
@@ -36,13 +36,6 @@ export default class ActionRunner extends Piper {
    */
   #debug = () => {}
 
-  /**
-   * Event emitter for cross-runner communication (BREAK/CONTINUE signals).
-   *
-   * @type {typeof Notify}
-   */
-  #notify = Notify
-
   /**
    * Instantiate a runner over an optional action wrapper.
    *
@@ -76,14 +69,17 @@ export default class ActionRunner extends Piper {
    * @param {import("./ActionWrapper.js").default|null} [parentWrapper] - Parent wrapper for BREAK/CONTINUE signaling.
    * @returns {Promise<unknown>} Final value produced by the pipeline.
    * @throws {Sass} When no activities are registered, conflicting activity kinds are used, or execution fails.
+   * @throws {Tantrum} When both an activity and the done callback fail.
    */
   async run(context, parentWrapper=null) {
     if(!this.#actionWrapper)
-      this.#actionWrapper = await this.#actionBuilder.build()
+      this.#actionWrapper = await this.#actionBuilder.build(this)
 
     const actionWrapper = this.#actionWrapper
     const activities = Array.from(actionWrapper.activities)
 
+    let caughtError = null
+
     try {
       for(
         let cursor = 0, max = activities.length;
@@ -114,7 +110,7 @@ export default class ActionRunner extends Piper {
 
               if(await this.#evalPredicate(activity, context)) {
                 if(kindBreak) {
-                  this.#notify.emit("loop.break", parentWrapper)
+                  this.emit("loop.break", parentWrapper)
                   break
                 }
 
@@ -132,7 +128,7 @@ export default class ActionRunner extends Piper {
                     break
 
                 let weWereOnABreak = false
-                const breakReceiver = this.#notify.on("loop.break", wrapper => {
+                const breakReceiver = this.on("loop.break", wrapper => {
                   if(wrapper.id === actionWrapper.id) {
                     weWereOnABreak = true
                   }
@@ -158,10 +154,7 @@ export default class ActionRunner extends Piper {
                 )
 
               const original = context
-              const splitContexts = await splitter.call(
-                activity.action,
-                context
-              )
+              const splitContexts = await splitter.call(activity.action,context)
 
               let settled
 
@@ -199,20 +192,28 @@ export default class ActionRunner extends Piper {
           throw Sass.new("ActionRunner running activity", error)
         }
       }
-    } finally {
-      // Execute done callback if registered - always runs, even on error
-      // Only run for top-level pipelines, not nested builders (inside loops)
-      if(actionWrapper.done && !parentWrapper) {
-        try {
-          context = await actionWrapper.done.call(
-            actionWrapper.action, context
-          )
-        } catch(error) {
-          throw Sass.new("ActionRunner running done callback", error)
-        }
+    } catch(err) {
+      caughtError = err
+    }
+
+    // Execute done callback if registered - always runs, even on error
+    // Only run for top-level pipelines, not nested builders (inside loops)
+    if(actionWrapper.done && !parentWrapper) {
+      try {
+        context = await actionWrapper.done.call(
+          actionWrapper.action, caughtError ?? context
+        )
+      } catch(error) {
+        if(caughtError)
+          caughtError = new Tantrum("ActionRunner running done callback", [caughtError, error])
+        else
+          caughtError = Sass.new("ActionRunner running done callback", error)
       }
     }
 
+    if(caughtError)
+      throw caughtError
+
     return context
   }
 
@@ -248,10 +249,20 @@ export default class ActionRunner extends Piper {
         debug: this.#debug, name: activity.name
       })
 
-      if(parallel) {
-        return await runner.pipe(context)
-      } else {
-        return await runner.run(context, activity.wrapper)
+      // Forward loop.break events from nested runner to this runner
+      // so that parent WHILE/UNTIL loops can receive break signals.
+      const forwarder = runner.on("loop.break",
+        wrapper => this.emit("loop.break", wrapper)
+      )
+
+      try {
+        if(parallel) {
+          return await runner.pipe(context)
+        } else {
+          return await runner.run(context, activity.wrapper)
+        }
+      } finally {
+        forwarder()
       }
     } else if(opKind === "Function") {
       try {
@@ -281,8 +292,6 @@ export default class ActionRunner extends Piper {
       }
     }
 
-    console.log(activity.opKind + " " + JSON.stringify(activity))
-
     throw Sass.new("We buy Functions and ActionBuilders. Only. Not whatever that was.")
   }
 

package/src/browser/lib/ActionWrapper.js

@@ -1,5 +1,12 @@
 import Activity from "./Activity.js"
 
+/**
+ * Type imports
+ *
+ * @import {default as ActionHooks} from "./ActionHooks.js"
+ * @import {default as ActionRunner} from "./ActionRunner.js"
+ */
+
 /**
  * @typedef {object} WrappedActivityConfig
  * @property {string|symbol} name Activity identifier used by hooks/logs.
@@ -10,10 +17,6 @@ import Activity from "./Activity.js"
  * @property {(message: string, level?: number, ...args: Array<unknown>) => void} [debug] Optional logger reference.
  */
 
-/**
- * @typedef {import("@gesslar/toolkit").Generator<Activity, void, unknown>} ActivityIterator
- */
-
 /**
  * Thin wrapper that materialises {@link Activity} instances on demand.
  */
@@ -32,7 +35,7 @@ export default class ActionWrapper {
    */
   #debug = () => {}
 
-  /** @type {import("./ActionHooks.js").default|null} */
+  /** @type {ActionHooks} */
   #hooks = null
   /** @type {((context: unknown) => unknown|Promise<unknown>)|null} */
   #done = null
@@ -40,6 +43,8 @@ export default class ActionWrapper {
   #action = null
   /** @type {symbol} */
   #id = Symbol(performance.now())
+  /** @type {ActionRunner} */
+  #runner
 
   /**
    * Create a wrapper from the builder payload.