@gesslar/actioneer 2.1.0 → 2.3.1

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} 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
+ * Types
+ *
+ * @import {default as ActionBuilder} from "./ActionBuilder.js"
+ * @import {default as ActionWrapper} from "./ActionWrapper.js"
  */
-
-/**
- * @typedef {import("./ActionBuilder.js").default} ActionBuilder
- */
-
 /**
+ * @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
 
   /**
@@ -63,24 +63,32 @@ export default class ActionRunner extends Piper {
   /**
    * Executes the configured action pipeline.
    * Builds the ActionWrapper on first run and caches it for subsequent calls.
-   * Supports WHILE, UNTIL, and SPLIT activity kinds.
+   * Supports WHILE, UNTIL, IF, SPLIT, BREAK, and CONTINUE activity kinds.
    *
    * @param {unknown} context - Seed value passed to the first activity.
+   * @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) {
+  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 = actionWrapper.activities
+    const activities = Array.from(actionWrapper.activities)
+
+    let caughtError = null
 
     try {
-      for(const activity of activities) {
-        try {
-          // await timeout(500)
+      for(
+        let cursor = 0, max = activities.length;
+        cursor < max && cursor !== -1;
+        cursor++
+      ) {
+        const activity = activities[cursor]
 
+        try {
           const kind = activity.kind
 
           // If we have no kind, then it's just a once.
@@ -88,33 +96,50 @@ export default class ActionRunner extends Piper {
           if(!kind) {
             context = await this.#execute(activity, context)
           } else {
-            // Validate that only one activity kind bit is set
-            // (kind & (kind - 1)) !== 0 means multiple bits are set
-            const multipleBitsSet = (kind & (kind - 1)) !== 0
-            if(multipleBitsSet)
-              throw Sass.new(
-                "For Kathy Griffin's sake! You can't combine activity kinds. " +
-                "Pick one: WHILE, UNTIL, or SPLIT!"
-              )
-
-            const {WHILE,UNTIL,SPLIT} = ACTIVITY
-            const kindWhile = kind & WHILE
-            const kindUntil = kind & UNTIL
-            const kindSplit = kind & SPLIT
-
-            if(kindWhile || kindUntil) {
-              const predicate = activity.pred
-
+            const {UNTIL, WHILE, IF, SPLIT, BREAK, CONTINUE} = ACTIVITY
+            const kindUntil = kind === UNTIL
+            const kindWhile = kind === WHILE
+            const kindIf = kind === IF
+            const kindSplit = kind === SPLIT
+            const kindBreak = kind === BREAK
+            const kindContinue = kind === CONTINUE
+
+            if(kindBreak || kindContinue) {
+              if(!parentWrapper)
+                throw Sass.new(`Invalid use of control flow outside of context.`)
+
+              if(await this.#evalPredicate(activity, context)) {
+                if(kindBreak) {
+                  this.emit("loop.break", parentWrapper)
+                  break
+                }
+
+                if(kindContinue)
+                  cursor = max
+              }
+            } else if(kindIf) {
+              if(await this.#evalPredicate(activity, context))
+                context = await this.#execute(activity, context)
+            } else if(kindWhile || kindUntil) {
+              // Simple if, no loop, only gainz.
               for(;;) {
-
                 if(kindWhile)
-                  if(!await this.#hasPredicate(activity,predicate,context))
+                  if(!await this.#evalPredicate(activity, context))
                     break
 
-                context = await this.#execute(activity,context)
+                let weWereOnABreak = false
+                const breakReceiver = this.on("loop.break", wrapper => {
+                  if(wrapper.id === actionWrapper.id) {
+                    weWereOnABreak = true
+                  }
+                })
+                context = await this.#execute(activity, context)
+                breakReceiver()
+                if(weWereOnABreak)
+                  break
 
                 if(kindUntil)
-                  if(await this.#hasPredicate(activity,predicate,context))
+                  if(await this.#evalPredicate(activity, context))
                     break
               }
             } else if(kindSplit) {
@@ -129,9 +154,8 @@ 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
 
               if(activity.opKind === "ActionBuilder") {
@@ -145,7 +169,6 @@ export default class ActionRunner extends Piper {
                   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
@@ -169,19 +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
-      if(actionWrapper.done) {
-        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
   }
 
@@ -217,14 +249,24 @@ 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)
+      // 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 {
-        const result = await activity.run(context)
+        const result = await activity.run(context, activity.wrapper)
 
         if(Data.isType(result, "ActionBuilder")) {
           if(activity.action)
@@ -240,7 +282,7 @@ export default class ActionRunner extends Piper {
           if(parallel) {
             return await runner.pipe(context)
           } else {
-            return await runner.run(context)
+            return await runner.run(context, activity.wrapper)
           }
         } else {
           return result
@@ -250,24 +292,21 @@ 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.")
   }
 
   /**
-   * Evaluate the predicate for WHILE/UNTIL activity kinds.
+   * Evaluate the predicate for WHILE/UNTIL/IF/BREAK/CONTINUE activity kinds.
    *
    * @param {import("./Activity.js").default} activity Activity currently executing.
-   * @param {(context: unknown) => boolean|Promise<boolean>} predicate Predicate to evaluate.
    * @param {unknown} context Current pipeline context.
-   * @returns {Promise<boolean>} True when the predicate allows another iteration.
+   * @returns {Promise<boolean>} True when the predicate condition is met.
    * @private
    */
-  async #hasPredicate(activity,predicate,context) {
-    Valid.type(predicate, "Function")
+  async #evalPredicate(activity, context) {
+    Valid.type(activity?.pred, "Function")
 
-    return !!(await predicate.call(activity.action, context))
+    return !!(await activity.pred.call(activity.action, context))
   }
 
   toString() {

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.
  */
@@ -24,6 +27,7 @@ export default class ActionWrapper {
    * @type {Map<string|symbol, WrappedActivityConfig>}
    */
   #activities = new Map()
+
   /**
    * Logger invoked for wrapper lifecycle events.
    *
@@ -31,11 +35,16 @@ export default class ActionWrapper {
    */
   #debug = () => {}
 
+  /** @type {ActionHooks} */
   #hooks = null
-
+  /** @type {((context: unknown) => unknown|Promise<unknown>)|null} */
   #done = null
-
+  /** @type {unknown} */
   #action = null
+  /** @type {symbol} */
+  #id = Symbol(performance.now())
+  /** @type {ActionRunner} */
+  #runner
 
   /**
    * Create a wrapper from the builder payload.
@@ -47,7 +56,18 @@ export default class ActionWrapper {
     this.#hooks = hooks
     this.#done = doneCallback
     this.#action = action
-    this.#activities = activities
+
+    for(const [key, value] of activities) {
+      this.#activities.set(
+        key,
+        new Activity({
+          ...value,
+          hooks: this.#hooks,
+          wrapper: this
+        })
+      )
+    }
+
     this.#debug(
       "Instantiating ActionWrapper with %o activities.",
       2,
@@ -55,18 +75,23 @@ export default class ActionWrapper {
     )
   }
 
-  *#_activities() {
-    for(const [,activity] of this.#activities)
-      yield new Activity({...activity, hooks: this.#hooks})
+  /**
+   * Unique identifier for this wrapper instance.
+   * Used by BREAK/CONTINUE to match events to the correct loop.
+   *
+   * @returns {symbol} Unique symbol identifier
+   */
+  get id() {
+    return this.#id
   }
 
   /**
    * Iterator over the registered activities.
    *
-   * @returns {ActivityIterator} Lazy iterator yielding Activity instances.
+   * @returns {Iterator<Activity>} Iterator yielding Activity instances.
    */
   get activities() {
-    return this.#_activities()
+    return this.#activities.values()
   }
 
   /**

package/src/browser/lib/Activity.js

@@ -1,6 +1,10 @@
 import {Data} from "@gesslar/toolkit"
 
-/** @typedef {import("./ActionHooks.js").default} ActionHooks */
+/**
+ * @import {default as ActionBuilder} from "./ActionBuilder.js"
+ * @import {default as ActionHooks} from "./ActionHooks.js"
+ * @import {default as ActionWrapper} from "./ActionWrapper.js"
+ **/
 
 /**
  * Activity bit flags recognised by the builder. The flag decides
@@ -8,14 +12,20 @@ import {Data} from "@gesslar/toolkit"
  *
  * @readonly
  * @enum {number}
- * @property {number} WHILE - Execute activity while predicate returns true (2)
- * @property {number} UNTIL - Execute activity until predicate returns true (4)
- * @property {number} SPLIT - Execute activity with split/rejoin pattern for parallel execution (8)
+ * @property {number} WHILE - Execute activity while predicate returns true 1
+ * @property {number} UNTIL - Execute activity until predicate returns true 2
+ * @property {number} SPLIT - Execute activity with split/rejoin pattern for parallel execution 3
+ * @property {number} IF - Execute activity if predicate returns true 4
+ * @property {number} BREAK - Break out of a WHILE/UNTIL if predicate returns true 5
+ * @property {number} CONTINUE - Returns to the top of a WHILE/UNTIL if predicate returns true 6
  */
 export const ACTIVITY = Object.freeze({
-  WHILE: 1<<1,
-  UNTIL: 1<<2,
-  SPLIT: 1<<3,
+  WHILE: 1,
+  UNTIL: 2,
+  SPLIT: 3,
+  IF: 4,
+  BREAK: 5,
+  CONTINUE: 6,
 })
 
 export default class Activity {
@@ -23,13 +33,13 @@ export default class Activity {
   #action = null
   /** @type {unknown} */
   #context = null
-  /** @type {ActionHooks|null} */
+  /** @type {ActionHooks?} */
   #hooks = null
-  /** @type {number|null} */
+  /** @type {number?} */
   #kind = null
   /** @type {string|symbol} */
   #name = null
-  /** @type {((context: unknown) => unknown|Promise<unknown>)|import("./ActionBuilder.js").default} */
+  /** @type {((context: unknown) => unknown|Promise<unknown>)|ActionBuilder} */
   #op = null
   /** @type {((context: unknown) => boolean|Promise<boolean>)|null} */
   #pred = null
@@ -37,6 +47,10 @@ export default class Activity {
   #rejoiner = null
   /** @type {((context: unknown) => unknown)|null} */
   #splitter = null
+  /** @type {ActionWrapper?} */
+  #wrapper = null
+  /** @type {symbol} */
+  #id = Symbol(performance.now())
 
   /**
    * Construct an Activity definition wrapper.
@@ -44,14 +58,15 @@ export default class Activity {
    * @param {object} init - Initial properties describing the activity operation, loop semantics, and predicate
    * @param {unknown} init.action - Parent action instance
    * @param {string|symbol} init.name - Activity identifier
-   * @param {(context: unknown) => unknown|Promise<unknown>|import("./ActionBuilder.js").default} init.op - Operation to execute
+   * @param {(context: unknown) => unknown|Promise<unknown>|ActionBuilder} init.op - Operation to execute
    * @param {number} [init.kind] - Optional loop semantics flags
    * @param {(context: unknown) => boolean|Promise<boolean>} [init.pred] - Optional predicate for WHILE/UNTIL
    * @param {ActionHooks} [init.hooks] - Optional hooks instance
    * @param {(context: unknown) => unknown} [init.splitter] - Optional splitter function for SPLIT activities
    * @param {(originalContext: unknown, splitResults: unknown) => unknown} [init.rejoiner] - Optional rejoiner function for SPLIT activities
+   * @param {ActionWrapper} [init.wrapper] - Optional wrapper containing this activity
    */
-  constructor({action,name,op,kind,pred,hooks,splitter,rejoiner}) {
+  constructor({action,name,op,kind,pred,hooks,splitter,rejoiner,wrapper}) {
     this.#action = action
     this.#hooks = hooks
     this.#kind = kind
@@ -60,6 +75,16 @@ export default class Activity {
     this.#pred = pred
     this.#rejoiner = rejoiner
     this.#splitter = splitter
+    this.#wrapper = wrapper ?? null
+  }
+
+  /**
+   * Unique identifier for this activity instance.
+   *
+   * @returns {symbol} Unique symbol identifier
+   */
+  get id() {
+    return this.#id
   }
 
   /**
@@ -81,7 +106,7 @@ export default class Activity {
   }
 
   /**
-   * The predicate function for WHILE/UNTIL flows.
+   * The predicate function for WHILE/UNTIL/IF flows.
    *
    * @returns {(context: unknown) => boolean|Promise<boolean>|undefined} - Predicate used to continue/stop loops
    */
@@ -110,7 +135,7 @@ export default class Activity {
   /**
    * The operator to execute (function or nested ActionBuilder).
    *
-   * @returns {(context: unknown) => unknown|Promise<unknown>|import("./ActionBuilder.js").default} - Activity operation
+   * @returns {(context: unknown) => unknown|Promise<unknown>|ActionBuilder} - Activity operation
    */
   get op() {
     return this.#op
@@ -119,7 +144,7 @@ export default class Activity {
   /**
    * The splitter function for SPLIT activities.
    *
-   * @returns {((context: unknown) => unknown)|null} Splitter function or null
+   * @returns {((context: unknown) => unknown)?} Splitter function or null
    */
   get splitter() {
     return this.#splitter
@@ -128,7 +153,7 @@ export default class Activity {
   /**
    * The rejoiner function for SPLIT activities.
    *
-   * @returns {((originalContext: unknown, splitResults: unknown) => unknown)|null} Rejoiner function or null
+   * @returns {((originalContext: unknown, splitResults: unknown) => unknown)?} Rejoiner function or null
    */
   get rejoiner() {
     return this.#rejoiner
@@ -143,6 +168,16 @@ export default class Activity {
     return this.#action
   }
 
+  /**
+   * Get the ActionWrapper containing this activity.
+   * Used by BREAK/CONTINUE to signal the parent loop.
+   *
+   * @returns {ActionWrapper?} The wrapper or null
+   */
+  get wrapper() {
+    return this.#wrapper ?? null
+  }
+
   /**
    * Execute the activity with before/after hooks.
    *
@@ -178,7 +213,7 @@ export default class Activity {
   /**
    * Get the hooks instance attached to this activity.
    *
-   * @returns {ActionHooks|null} The hooks instance or null
+   * @returns {ActionHooks?} The hooks instance or null
    */
   get hooks() {
     return this.#hooks