@gesslar/actioneer 2.2.0 → 2.4.0

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.
    *
@@ -62,9 +55,45 @@ export default class ActionRunner extends Piper {
 
     this.#actionBuilder = actionBuilder
 
+    this.addSetup(this.#setupHooks)
     this.addStep(this.run, {
       name: `ActionRunner for ${actionBuilder.tag.description}`
     })
+    this.addCleanup(this.#cleanupHooks)
+  }
+
+  /**
+   * Invokes the `setup` lifecycle hook on the raw hooks object, if defined.
+   * Registered as a Piper setup step so it fires before any items are processed.
+   *
+   * @param {unknown} ctx - Value passed by {@link Piper#pipe} (the items array).
+   * @returns {Promise<void>}
+   * @private
+   */
+  async #setupHooks(ctx) {
+    const ab = this.#actionBuilder
+    const ah = ab?.hooks
+    const setup = ah?.setup
+
+    if(setup)
+      await setup.call(ah, ctx)
+  }
+
+  /**
+   * Invokes the `cleanup` lifecycle hook on the raw hooks object, if defined.
+   * Registered as a Piper teardown step so it fires after all items are processed.
+   *
+   * @param {unknown} ctx - Value passed by {@link Piper#pipe} (the items array).
+   * @returns {Promise<void>}
+   * @private
+   */
+  async #cleanupHooks(ctx) {
+    const ab = this.#actionBuilder
+    const ah = ab?.hooks
+    const cleanup = ah?.cleanup
+
+    if(cleanup)
+      await cleanup.call(ah, ctx)
   }
 
   /**
@@ -76,14 +105,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 +146,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 +164,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 +190,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 +228,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 +285,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 +328,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,11 @@
 import Activity from "./Activity.js"
 
+/**
+ * Type imports
+ *
+ * @import {default as ActionHooks} from "./ActionHooks.js"
+ */
+
 /**
  * @typedef {object} WrappedActivityConfig
  * @property {string|symbol} name Activity identifier used by hooks/logs.
@@ -10,10 +16,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 +34,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
@@ -44,7 +46,12 @@ export default class ActionWrapper {
   /**
    * Create a wrapper from the builder payload.
    *
-   * @param {{activities: Map<string|symbol, WrappedActivityConfig>, debug: (message: string, level?: number, ...args: Array<unknown>) => void}} init Builder payload containing activities + logger.
+   * @param {object} init - Builder payload.
+   * @param {Map<string|symbol, WrappedActivityConfig>} init.activities - Registered activities.
+   * @param {(message: string, level?: number, ...args: Array<unknown>) => void} init.debug - Logger.
+   * @param {import("./ActionHooks.js").default?} init.hooks - Optional hooks instance.
+   * @param {((context: unknown) => unknown|Promise<unknown>)|null} [init.done] - Optional done callback.
+   * @param {unknown} [init.action] - Optional parent action instance.
    */
   constructor({activities,hooks,debug,done: doneCallback,action}) {
     this.#debug = debug

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
@@ -29,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
@@ -43,7 +47,7 @@ export default class Activity {
   #rejoiner = null
   /** @type {((context: unknown) => unknown)|null} */
   #splitter = null
-  /** @type {import("./ActionWrapper.js").default|null} */
+  /** @type {ActionWrapper?} */
   #wrapper = null
   /** @type {symbol} */
   #id = Symbol(performance.now())
@@ -54,13 +58,13 @@ 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 {import("./ActionWrapper.js").default} [init.wrapper] - Optional wrapper containing this activity
+   * @param {ActionWrapper} [init.wrapper] - Optional wrapper containing this activity
    */
   constructor({action,name,op,kind,pred,hooks,splitter,rejoiner,wrapper}) {
     this.#action = action
@@ -131,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
@@ -140,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
@@ -149,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
@@ -168,7 +172,7 @@ export default class Activity {
    * Get the ActionWrapper containing this activity.
    * Used by BREAK/CONTINUE to signal the parent loop.
    *
-   * @returns {import("./ActionWrapper.js").default|null} The wrapper or null
+   * @returns {ActionWrapper?} The wrapper or null
    */
   get wrapper() {
     return this.#wrapper ?? null
@@ -188,7 +192,7 @@ export default class Activity {
     const result = await this.#op.call(this.#action, context)
 
     // after hook
-    await this.#hooks?.callHook("after", this.#name, context)
+    await this.#hooks?.callHook("after", this.#name, result, context)
 
     return result
   }
@@ -209,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

package/src/browser/lib/Piper.js

@@ -9,10 +9,16 @@
  * - Error handling and reporting
  */
 
-import {Promised, Sass, Tantrum} from "@gesslar/toolkit"
+import {Data, Disposer, NotifyClass, Promised, Sass} from "@gesslar/toolkit"
 
-export default class Piper {
+/**
+ * @import {Tantrum} from "@gesslar/toolkit"
+ */
+
+export default class Piper extends NotifyClass {
   #debug
+  #disposer = Disposer
+  #abortedReason
 
   #lifeCycle = new Map([
     ["setup", new Set()],
@@ -23,18 +29,32 @@ export default class Piper {
   /**
    * Create a Piper instance.
    *
-   * @param {{debug?: (message: string, level?: number, ...args: Array<unknown>) => void}} [config] Optional configuration with debug function
+   * @param {{debug?: (message: string, level?: number, ...args: Array<unknown>) => void}} [config] - Optional configuration with debug function
    */
   constructor({debug = (() => {})} = {}) {
+    super()
+
     this.#debug = debug
+
+    this.#disposer.register(
+      this.on("abort", this.#abortCalled.bind(this))
+    )
+  }
+
+  #abortCalled(reason) {
+    this.#abortedReason = reason
+  }
+
+  get reason() {
+    return this.#abortedReason
   }
 
   /**
    * Add a processing step to the pipeline
    *
-   * @param {(context: unknown) => Promise<unknown>|unknown} fn Function that processes an item
-   * @param {{name?: string, required?: boolean}} [options] Step options
-   * @param {unknown} [newThis] Optional this binding
+   * @param {(context: unknown) => Promise<unknown>|unknown} fn - Function that processes an item
+   * @param {{name?: string, required?: boolean}} [options] - Step options
+   * @param {unknown} [newThis] - Optional this binding
    * @returns {Piper} The pipeline instance (for chaining)
    */
   addStep(fn, options = {}, newThis) {
@@ -51,7 +71,7 @@ export default class Piper {
   /**
    * Add setup hook that runs before processing starts.
    *
-   * @param {() => Promise<void>|void} fn - Setup function executed before processing
+   * @param {(items: Array<unknown>) => Promise<void>|void} fn - Setup function executed before processing; receives the full items array.
    * @param {unknown} [thisArg] - Optional this binding for the setup function
    * @returns {Piper} - The pipeline instance
    */
@@ -64,7 +84,7 @@ export default class Piper {
   /**
    * Add cleanup hook that runs after processing completes
    *
-   * @param {() => Promise<void>|void} fn - Cleanup function executed after processing
+   * @param {(items: Array<unknown>) => Promise<void>|void} fn - Cleanup function executed after processing; receives the full items array.
    * @param {unknown} [thisArg] - Optional this binding for the cleanup function
    * @returns {Piper} - The pipeline instance
    */
@@ -90,7 +110,7 @@ export default class Piper {
     const allResults = new Array(items.length)
 
     const processWorker = async() => {
-      while(true) {
+      while(true && !this.reason) {
         const currentIndex = itemIndex++
 
         if(currentIndex >= items.length)
@@ -101,7 +121,10 @@ export default class Piper {
         try {
           const result = await this.#processItem(item)
 
-          allResults[currentIndex] = {status: "fulfilled", value: result}
+          if(Data.isType(result, "Error"))
+            allResults[currentIndex] = {status: "rejected", reason: result}
+          else
+            allResults[currentIndex] = {status: "fulfilled", value: result}
         } catch(error) {
           allResults[currentIndex] = {status: "rejected", reason: error}
         }
@@ -109,7 +132,7 @@ export default class Piper {
     }
 
     const setupResult = await Promised.settle(
-      [...this.#lifeCycle.get("setup")].map(e => Promise.resolve(e()))
+      [...this.#lifeCycle.get("setup")].map(e => Promise.resolve(e(items)))
     )
 
     this.#processResult("Setting up the pipeline.", setupResult)
@@ -127,36 +150,37 @@ export default class Piper {
     } finally {
       // Run cleanup hooks
       const teardownResult = await Promised.settle(
-        [...this.#lifeCycle.get("teardown")].map(e => Promise.resolve(e()))
+        [...this.#lifeCycle.get("teardown")].map(e => Promise.resolve(e(items)))
       )
 
       this.#processResult("Tearing down the pipeline.", teardownResult)
     }
 
+    if(this.reason)
+      this.emit("aborted", this.reason)
+
     return allResults
   }
 
   /**
    * Validate settleAll results and throw a combined error when rejected.
    *
-   * @param {string} message Context message
-   * @param {Array<unknown>} settled Results from settleAll
    * @private
+   * @param {string} message - Context message
+   * @param {Array<unknown>} settled - Results from settleAll
+   * @throws {Tantrum} - If any settled result was rejected
    */
-  #processResult(message, settled) {
-    if(settled.some(r => r.status === "rejected"))
-      throw Tantrum.new(
-        message,
-        settled.filter(r => r.status==="rejected").map(r => r.reason)
-      )
+  #processResult(_message, settled) {
+    if(Promised.hasRejected(settled))
+      Promised.throw(settled)
   }
 
   /**
    * Process a single item through all pipeline steps
    *
-   * @param {unknown} item The item to process
-   * @returns {Promise<unknown>} Result from the final step
    * @private
+   * @param {unknown} item - The item to process
+   * @returns {Promise<unknown>} Result from the final step
    */
   async #processItem(item) {
     // Execute each step in sequence