@gesslar/actioneer 0.2.1 → 0.2.3

package/src/lib/Piper.js

@@ -2,20 +2,18 @@
  * Generic Pipeline - Process items through a series of steps with concurrency control
  *
  * This abstraction handles:
- * - Concurrent processing with configurable limits using worker pool pattern
- * - Pipeline of processing steps executed sequentially per item
+ * - Concurrent processing with configurable limits
+ * - Pipeline of processing steps
+ * - Result categorization (success/warning/error)
  * - Setup/cleanup lifecycle hooks
  * - Error handling and reporting
- * - Dynamic worker spawning to maintain concurrency
  */
 
 import {Sass, Tantrum, Util} from "@gesslar/toolkit"
 
 export default class Piper {
-  /** @type {(message: string, level?: number, ...args: Array<unknown>) => void} */
   #debug
 
-  /** @type {Map<string, Set<unknown>>} */
   #lifeCycle = new Map([
     ["setup", new Set()],
     ["process", new Set()],
@@ -32,19 +30,14 @@ export default class Piper {
   }
 
   /**
-   * Add a processing step to the pipeline.
-   * Each step is executed sequentially per item.
+   * 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 (name is required)
+   * @param {{name?: string, required?: boolean}} [options] Step options
    * @param {unknown} [newThis] Optional this binding
    * @returns {Piper} The pipeline instance (for chaining)
-   * @throws {Sass} If name is not provided in options
    */
   addStep(fn, options = {}, newThis) {
-    if(options.name == null)
-      throw Sass.new("Missing name for step.")
-
     this.#lifeCycle.get("process").add({
       fn: fn.bind(newThis ?? this),
       name: options.name || `Step ${this.#lifeCycle.get("process").size + 1}`,
@@ -82,70 +75,33 @@ export default class Piper {
   }
 
   /**
-   * Process items through the pipeline with concurrency control using a worker pool pattern.
-   * Workers are spawned up to maxConcurrent limit, and as workers complete, new workers
-   * are spawned to maintain concurrency until all items are processed.
-   *
-   * This implementation uses dynamic worker spawning to maintain concurrency:
-   * - Initial workers are spawned up to maxConcurrent limit
-   * - As each worker completes (success OR failure), a replacement worker is spawned if items remain
-   * - Worker spawning occurs in finally block to ensure resilience to individual worker failures
-   * - All results are collected with {ok, value} or {ok: false, error} structure
-   * - Processing continues even if individual workers fail, collecting all errors
+   * Process items through the pipeline with concurrency control
    *
    * @param {Array<unknown>|unknown} items - Items to process
-   * @param {number} [maxConcurrent] - Maximum concurrent items to process (default: 10)
-   * @returns {Promise<Array<{ok: boolean, value?: unknown, error?: Sass}>>} - Results with success/failure status
-   * @throws {Sass} If setup or teardown fails
+   * @param {number} maxConcurrent - Maximum concurrent items to process
+   * @returns {Promise<Array<unknown>>} - Collected results from steps
    */
   async pipe(items, maxConcurrent = 10) {
     items = Array.isArray(items)
       ? items
       : [items]
 
-    const pipeResult = []
-
-    let pendingCount = 0
-    let resolveAll
-    const allDone = new Promise(resolve => {
-      resolveAll = resolve
-    })
+    let itemIndex = 0
+    const allResults = []
 
-    /**
-     * Worker function that processes one item and potentially spawns a replacement.
-     * Uses shift() to atomically retrieve items from the queue, ensuring no duplicate processing.
-     * Spawns replacement workers in the finally block to guarantee resilience to errors.
-     *
-     * @private
-     */
     const processWorker = async() => {
-      if(items.length === 0) {
-        pendingCount--
-
-        if(pendingCount === 0)
-          resolveAll()
-
-        return
-      }
-
-      const item = items.shift()
-
-      try {
-        const result = await this.#processWorker(item)
-        pipeResult.push({ok: true, value: result})
-      } catch(error) {
-        pipeResult.push({ok: false, error: Sass.new("Processing pipeline item.", error)})
-      } finally {
-        // Spawn a replacement worker if there are more items
-        if(items.length > 0) {
-          pendingCount++
-          processWorker() // Don't await - let it run in parallel
+      while(true) {
+        const currentIndex = itemIndex++
+        if(currentIndex >= items.length)
+          break
+
+        const item = items[currentIndex]
+        try {
+          const result = await this.#processItem(item)
+          allResults.push(result)
+        } catch(error) {
+          throw Sass.new("Processing pipeline item.", error)
         }
-
-        if(--pendingCount === 0)
-          resolveAll()
-
-        this.#debug("pendingCount = %o", 2, pendingCount)
       }
     }
 
@@ -156,19 +112,15 @@ export default class Piper {
 
     try {
       // Start workers up to maxConcurrent limit
+      const workers = []
       const workerCount = Math.min(maxConcurrent, items.length)
-      pendingCount = workerCount
 
-      if(workerCount === 0) {
-        resolveAll() // No items to process
-      } else {
-        for(let i = 0; i < workerCount; i++) {
-          processWorker() // Don't await - let them all run in parallel
-        }
-      }
+      for(let i = 0; i < workerCount; i++)
+        workers.push(processWorker())
 
       // Wait for all workers to complete
-      await allDone
+      const processResult = await Util.settleAll(workers)
+      this.#processResult("Processing pipeline.", processResult)
     } finally {
       // Run cleanup hooks
       const teardownResult = await Util.settleAll(
@@ -177,31 +129,7 @@ export default class Piper {
       this.#processResult("Tearing down the pipeline.", teardownResult)
     }
 
-    return pipeResult
-  }
-
-  /**
-   * Process a single item through all pipeline steps.
-   *
-   * @param {unknown} item The item to process
-   * @returns {Promise<unknown>} Result from the final step
-   * @private
-   */
-  async #processWorker(item) {
-    try {
-      // Execute each step in sequence
-      let result = item
-
-      for(const step of this.#lifeCycle.get("process")) {
-        this.#debug("Executing step: %o", 4, step.name)
-
-        result = await step.fn(result) ?? result
-      }
-
-      return result
-    } catch(error) {
-      throw Sass.new("Processing an item.", error)
-    }
+    return allResults
   }
 
   /**
@@ -218,4 +146,29 @@ export default class Piper {
         settled.filter(r => r.status==="rejected").map(r => r.reason)
       )
   }
+
+  /**
+   * Process a single item through all pipeline steps
+   *
+   * @param {unknown} item The item to process
+   * @returns {Promise<unknown>} Result from the final step
+   * @private
+   */
+  async #processItem(item) {
+    // Execute each step in sequence
+    let result = item
+
+    for(const step of this.#lifeCycle.get("process")) {
+      this.#debug("Executing step: %o", 4, step.name)
+
+      try {
+        result = await step.fn(result) ?? result
+      } catch(error) {
+        if(step.required)
+          throw Sass.new(`Processing required step "${step.name}".`, error)
+      }
+    }
+
+    return result
+  }
 }

package/src/types/lib/ActionBuilder.d.ts

@@ -21,8 +21,6 @@
  * @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).
  */
 /**
  * @typedef {(context: unknown) => unknown|Promise<unknown>} ActionFunction
@@ -51,16 +49,10 @@ export default class ActionBuilder {
   /**
    * 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?: ActionBuilderAction, { tag, debug }?: ActionBuilderConfig)
-  /**
-   * Get the builder's tag symbol.
-   *
-   * @returns {symbol|null} The tag symbol for this builder instance
-   */
-  get tag(): symbol | null
   /**
    * Register an activity that the runner can execute.
    *
@@ -83,16 +75,6 @@ export default class ActionBuilder {
    * @returns {ActionBuilder}
    */
   do(name: string | symbol, kind: number, pred: (context: unknown) => boolean | Promise<boolean>, op: ActionFunction | import('./ActionWrapper.js').default): 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}
-   */
-  do(name: string | symbol, kind: number, splitter: (context: unknown) => unknown, rejoiner: (originalContext: unknown, splitResults: unknown) => unknown, op: ActionFunction | ActionBuilder): ActionBuilder
   /**
    * Configure hooks to be loaded from a file when the action is built.
    *
@@ -110,14 +92,6 @@ export default class ActionBuilder {
    * @throws {Sass} If hooks have already been configured.
    */
   withHooks(hooks: import('./ActionHooks.js').default): ActionBuilder
-  /**
-   * 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: import('./ActionHooks.js').default): ActionBuilder
   /**
    * Finalises the builder and returns a payload that can be consumed by the
    * runner.
@@ -125,12 +99,6 @@ export default class ActionBuilder {
    * @returns {Promise<import("./ActionWrapper.js").default>} Payload consumed by the {@link ActionRunner} constructor.
    */
   build(): Promise<import('./ActionWrapper.js').default>
-  /**
-   * Check if this builder has ActionHooks configured.
-   *
-   * @returns {boolean} True if ActionHooks have been configured.
-   */
-  get hasActionHooks(): boolean
   #private
 }
 export type ActionRunner = import('./ActionRunner.js').default
@@ -181,14 +149,6 @@ export type ActivityDefinition = {
    * Loop predicate.
    */
   pred?: ((context: unknown) => boolean | Promise<boolean>) | undefined;
-  /**
-   * Function to split context for parallel execution (SPLIT activities).
-   */
-  splitter?: ((context: unknown) => unknown) | undefined;
-  /**
-   * Function to rejoin split results (SPLIT activities).
-   */
-  rejoiner?: ((originalContext: unknown, splitResults: unknown) => unknown) | undefined;
 }
 export type ActionFunction = (context: unknown) => unknown | Promise<unknown>
 //# sourceMappingURL=ActionBuilder.d.ts.map

package/src/types/lib/ActionBuilder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ActionBuilder.d.ts","sourceRoot":"","sources":["../../lib/ActionBuilder.js"],"names":[],"mappings":"AAKA,kEAAkE;AAClE,uEAAuE;AAEvE;;GAEG;AAEH;;;;GAIG;AAEH;;;;GAIG;AAEH;;;;;;;;;;GAUG;AAEH;;GAEG;AAEH;;;;;;;;;;;;;;;;;;;GAmBG;AACH;IA2BE;;;;;OAKG;IACH,qBAHW,mBAAmB,mBACnB,mBAAmB,EAe7B;IA5BD;;;;OAIG;IACH,WAFa,MAAM,GAAC,IAAI,CAIvB;;;;;;;;;;;;;IA8BE,SACQ,MAAM,GAAC,MAAM,MACb,cAAc,GACZ,aAAa,CACzB;;;;;;;;;IAGE,SACQ,MAAM,GAAC,MAAM,QACb,MAAM,QACN,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,GAAC,OAAO,CAAC,OAAO,CAAC,MAC9C,cAAc,GAAC,OAAO,oBAAoB,EAAE,OAAO,GACjD,aAAa,CACzB;;;;;;;;;;IAGE,SACQ,MAAM,GAAC,MAAM,QACb,MAAM,YACN,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,YAC7B,CAAC,eAAe,EAAE,OAAO,EAAE,YAAY,EAAE,OAAO,KAAK,OAAO,MAC5D,cAAc,GAAC,aAAa,GAC1B,aAAa,CACzB;IAsDD;;;;;;;OAOG;IACH,yBALW,MAAM,aACN,MAAM,GACJ,aAAa,CAUzB;IAED;;;;;;OAMG;IACH,iBAJW,OAAO,kBAAkB,EAAE,OAAO,GAChC,aAAa,CASzB;IAED;;;;;;OAMG;IACH,6BAJW,OAAO,kBAAkB,EAAE,OAAO,GAChC,aAAa,CASzB;IA2BD;;;;;OAKG;IACH,SAFa,OAAO,CAAC,OAAO,oBAAoB,EAAE,OAAO,CAAC,CAiBzD;IAED;;;;OAIG;IACH,sBAFa,OAAO,CAInB;;CAiCF;2BAlUa,OAAO,mBAAmB,EAAE,OAAO;4BACnC,cAAc,eAAe,EAAE,QAAQ;sBAGxC,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,KAAK,CAAC,OAAO,CAAC,KAAK,IAAI;;;;;WAKjE,CAAC,OAAO,EAAE,aAAa,KAAK,IAAI;;;;;;;;;;;;;;;;;;;;YAYhC,mBAAmB,GAAC,IAAI;;;;WACxB,OAAO,GAAC,IAAI;;;;UACZ,MAAM,GAAC,MAAM;;;;QACb,cAAc,GAAC,OAAO,oBAAoB,EAAE,OAAO;;;;;;;;sBAEzC,OAAO,KAAK,OAAO,GAAC,OAAO,CAAC,OAAO,CAAC;;;;0BACpC,OAAO,KAAK,OAAO;;;;kCACX,OAAO,gBAAgB,OAAO,KAAK,OAAO;;6BAI7D,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,GAAC,OAAO,CAAC,OAAO,CAAC"}
+{"version":3,"file":"ActionBuilder.d.ts","sourceRoot":"","sources":["../../lib/ActionBuilder.js"],"names":[],"mappings":"AAKA,kEAAkE;AAClE,uEAAuE;AAEvE;;GAEG;AAEH;;;;GAIG;AAEH;;;;GAIG;AAEH;;;;;;;;GAQG;AAEH;;GAEG;AAEH;;;;;;;;;;;;;;;;;;;GAmBG;AACH;IAaE;;;;;OAKG;IACH,qBAHW,mBAAmB,mBACnB,mBAAmB,EAe7B;;;;;;;;;;;;;IASE,SACQ,MAAM,GAAC,MAAM,MACb,cAAc,GACZ,aAAa,CACzB;;;;;;;;;IAGE,SACQ,MAAM,GAAC,MAAM,QACb,MAAM,QACN,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,GAAC,OAAO,CAAC,OAAO,CAAC,MAC9C,cAAc,GAAC,OAAO,oBAAoB,EAAE,OAAO,GACjD,aAAa,CACzB;IA4CD;;;;;;;OAOG;IACH,yBALW,MAAM,aACN,MAAM,GACJ,aAAa,CAYzB;IAED;;;;;;OAMG;IACH,iBAJW,OAAO,kBAAkB,EAAE,OAAO,GAChC,aAAa,CAWzB;IAeD;;;;;OAKG;IACH,SAFa,OAAO,CAAC,OAAO,oBAAoB,EAAE,OAAO,CAAC,CAmBzD;;CAeF;2BA9Oa,OAAO,mBAAmB,EAAE,OAAO;4BACnC,cAAc,eAAe,EAAE,QAAQ;sBAGxC,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,KAAK,CAAC,OAAO,CAAC,KAAK,IAAI;;;;;WAKjE,CAAC,OAAO,EAAE,aAAa,KAAK,IAAI;;;;;;;;;;;;;;;;;;;;YAYhC,mBAAmB,GAAC,IAAI;;;;WACxB,OAAO,GAAC,IAAI;;;;UACZ,MAAM,GAAC,MAAM;;;;QACb,cAAc,GAAC,OAAO,oBAAoB,EAAE,OAAO;;;;;;;;sBAEzC,OAAO,KAAK,OAAO,GAAC,OAAO,CAAC,OAAO,CAAC;;6BAI/C,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,GAAC,OAAO,CAAC,OAAO,CAAC"}

package/src/types/lib/ActionHooks.d.ts

@@ -3,10 +3,11 @@
  */
 /**
  * @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.
  */
 /**
  * @typedef {Record<string, (context: unknown) => Promise<unknown>|unknown>} HookModule
@@ -20,38 +21,37 @@ 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 'new'(config: ActionHooksConfig, debug: DebugFn): Promise<ActionHooks>
+  static 'new'(config: ActionHooksConfig, debug: DebugFn): Promise<ActionHooks | null>
   /**
    * 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 }: ActionHooksConfig, debug: (message: string, level?: number, ...args: Array<unknown>) => void)
+  constructor({ actionKind, hooksFile, hooks, hookTimeout, debug }: ActionHooksConfig)
   /**
    * Gets the action identifier.
    *
-   * @returns {string|null} Action identifier or instance
+   * @returns {string} Action identifier or instance
    */
-  get actionKind(): string | null
+  get actionKind(): string
   /**
    * Gets the hooks file object.
    *
-   * @returns {FileObject|null} File object containing hooks
+   * @returns {FileObject} File object containing hooks
    */
-  get hooksFile(): FileObject | null
+  get hooksFile(): FileObject
   /**
    * 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(): HookModule | null
+  get hooks(): object | null
   /**
    * Gets the hook execution timeout in milliseconds.
    *
@@ -71,15 +71,12 @@ export default class ActionHooks {
    */
   get cleanup(): (args: object) => unknown | null
   /**
-   * 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.
    */
   callHook(kind: 'before' | 'after' | 'setup' | 'cleanup' | string, activityName: string | symbol, context: unknown): Promise<void>
   #private
@@ -89,19 +86,23 @@ export type ActionHooksConfig = {
   /**
    * Action identifier shared between runner and hooks.
    */
-  actionKind?: string | undefined;
+  actionKind: string;
   /**
-   * File handle or path used to import the hooks module.
+   * File handle used to import the hooks module.
    */
-  hooksFile?: string | FileObject | undefined;
+  hooksFile: FileObject;
   /**
    * Already-instantiated hooks implementation (skips loading).
    */
-  hooksObject?: unknown;
+  hooks?: unknown;
   /**
    * Timeout applied to hook execution in milliseconds.
    */
   hookTimeout?: number | undefined;
+  /**
+   * Logger to emit diagnostics.
+   */
+  debug: DebugFn;
 }
 export type HookModule = Record<string, (context: unknown) => Promise<unknown> | unknown>
 import { FileObject } from '@gesslar/toolkit'

package/src/types/lib/ActionHooks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ActionHooks.d.ts","sourceRoot":"","sources":["../../lib/ActionHooks.js"],"names":[],"mappings":"AAGA;;GAEG;AAEH;;;;;;GAMG;AAEH;;GAEG;AAEH;;;;GAIG;AACH;IAmFE;;;;;;;;OAQG;IACH,qBAJW,iBAAiB,SACjB,OAAO,GACL,OAAO,CAAC,WAAW,CAAC,CA2ChC;IAzHD;;;;;OAKG;IACH,iEAHW,iBAAiB,SACjB,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,KAAK,CAAC,OAAO,CAAC,KAAK,IAAI,EAW5E;IAED;;;;OAIG;IACH,kBAFa,MAAM,GAAC,IAAI,CAIvB;IAED;;;;OAIG;IACH,iBAFa,UAAU,GAAC,IAAI,CAI3B;IAED;;;;OAIG;IACH,aAFa,UAAU,GAAC,IAAI,CAI3B;IAED;;;;OAIG;IACH,eAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,aAFa,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,GAAC,IAAI,CAI1C;IAED;;;;OAIG;IACH,eAFa,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,GAAC,IAAI,CAI1C;IAsDD;;;;;;;;;;OAUG;IACH,eANW,QAAQ,GAAC,OAAO,GAAC,OAAO,GAAC,SAAS,GAAC,MAAM,gBACzC,MAAM,GAAC,MAAM,WACb,OAAO,GACL,OAAO,CAAC,IAAI,CAAC,CAyDzB;;CA6BF;sBAzPY,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,KAAK,CAAC,OAAO,CAAC,KAAK,IAAI;;;;;;;;;;;;;kBAOjE,OAAO;;;;;;yBAKR,MAAM,CAAC,MAAM,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,GAAC,OAAO,CAAC;2BAfzB,kBAAkB"}
+{"version":3,"file":"ActionHooks.d.ts","sourceRoot":"","sources":["../../lib/ActionHooks.js"],"names":[],"mappings":"AAGA;;GAEG;AAEH;;;;;;;GAOG;AAEH;;GAEG;AAEH;;;;GAIG;AACH;IA+EE;;;;;;;;OAQG;IACH,qBAJW,iBAAiB,SACjB,OAAO,GACL,OAAO,CAAC,WAAW,GAAC,IAAI,CAAC,CA2CrC;IArHD;;;;OAIG;IACH,kEAFW,iBAAiB,EAQ3B;IAED;;;;OAIG;IACH,kBAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,iBAFa,UAAU,CAItB;IAED;;;;OAIG;IACH,aAFa,MAAM,GAAC,IAAI,CAIvB;IAED;;;;OAIG;IACH,eAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,aAFa,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,GAAC,IAAI,CAI1C;IAED;;;;OAIG;IACH,eAFa,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,GAAC,IAAI,CAI1C;IAsDD;;;;;;;OAOG;IACH,eALW,QAAQ,GAAC,OAAO,GAAC,OAAO,GAAC,SAAS,GAAC,MAAM,gBACzC,MAAM,GAAC,MAAM,WACb,OAAO,GACL,OAAO,CAAC,IAAI,CAAC,CAwDzB;;CAmBF;sBAzOY,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,KAAK,CAAC,OAAO,CAAC,KAAK,IAAI;;;;;gBAKjE,MAAM;;;;eACN,UAAU;;;;YACV,OAAO;;;;;;;;WAEP,OAAO;;yBAIR,MAAM,CAAC,MAAM,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,GAAC,OAAO,CAAC;2BAhBzB,kBAAkB"}

package/src/types/lib/ActionRunner.d.ts

@@ -22,12 +22,10 @@ export default class ActionRunner extends Piper {
   constructor(actionBuilder: import('./ActionBuilder.js').default | null, { debug }?: ActionRunnerOptions)
   /**
    * Executes the configured action pipeline.
-   * Builds the ActionWrapper on first run and caches it for subsequent calls.
-   * Supports WHILE, UNTIL, and SPLIT activity kinds.
    *
    * @param {unknown} context - Seed value passed to the first activity.
-   * @returns {Promise<unknown>} Final value produced by the pipeline.
-   * @throws {Sass} When no activities are registered, conflicting activity kinds are used, or execution fails.
+   * @returns {Promise<unknown>} Final value produced by the pipeline, or null when a parallel stage reports failures.
+   * @throws {Sass} When no activities are registered or required parallel builders are missing.
    */
   run(context: unknown): Promise<unknown>
   #private

package/src/types/lib/ActionRunner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ActionRunner.d.ts","sourceRoot":"","sources":["../../lib/ActionRunner.js"],"names":[],"mappings":"AAMA;;GAEG;AAEH;;;GAGG;AACH;;;;;;GAMG;AACH;IAaE;;;;;OAKG;IACH,2BAHW,OAAO,oBAAoB,EAAE,OAAO,GAAC,IAAI,cACzC,mBAAmB,EAkB7B;IAED;;;;;;;;OAQG;IACH,aAJW,OAAO,GACL,OAAO,CAAC,OAAO,CAAC,CA4E5B;;CAwFF;sBA7NY,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,KAAK,CAAC,OAAO,CAAC,KAAK,IAAI;;;;;;;kBAH7D,YAAY"}
+{"version":3,"file":"ActionRunner.d.ts","sourceRoot":"","sources":["../../lib/ActionRunner.js"],"names":[],"mappings":"AAMA;;GAEG;AAEH;;;GAGG;AACH;;;;;;GAMG;AACH;IAUE;;;;;OAKG;IACH,2BAHW,OAAO,oBAAoB,EAAE,OAAO,GAAC,IAAI,cACzC,mBAAmB,EAgB7B;IAED;;;;;;OAMG;IACH,aAJW,OAAO,GACL,OAAO,CAAC,OAAO,CAAC,CA+C5B;;CA2CF;sBA5IY,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,KAAK,CAAC,OAAO,CAAC,KAAK,IAAI;;;;;;;kBAH7D,YAAY"}

package/src/types/lib/ActionWrapper.d.ts

@@ -1,11 +1,9 @@
 /**
  * @typedef {object} WrappedActivityConfig
  * @property {string|symbol} name Activity identifier used by hooks/logs.
- * @property {(context: unknown) => unknown|Promise<unknown>|import("./ActionBuilder.js").default} op Operation or nested ActionBuilder to execute.
+ * @property {(context: unknown) => unknown|Promise<unknown>|ActionWrapper} op Operation or nested wrapper to execute.
  * @property {number} [kind] Optional loop semantic flags.
  * @property {(context: unknown) => boolean|Promise<boolean>} [pred] Predicate tied to WHILE/UNTIL semantics.
- * @property {(context: unknown) => unknown} [splitter] Splitter function for SPLIT activities.
- * @property {(originalContext: unknown, splitResults: unknown) => unknown} [rejoiner] Rejoiner function for SPLIT activities.
  * @property {unknown} [action] Parent action instance supplied when invoking the op.
  * @property {(message: string, level?: number, ...args: Array<unknown>) => void} [debug] Optional logger reference.
  */
@@ -19,15 +17,11 @@ export default class ActionWrapper {
   /**
    * Create a wrapper from the builder payload.
    *
-   * @param {object} config Builder payload containing activities + logger
-   * @param {Map<string|symbol, WrappedActivityConfig>} config.activities Activities map
-   * @param {(message: string, level?: number, ...args: Array<unknown>) => void} config.debug Debug function
-   * @param {object} config.hooks Hooks object
+   * @param {{activities: Map<string|symbol, WrappedActivityConfig>, debug: (message: string, level?: number, ...args: Array<unknown>) => void}} init Builder payload containing activities + logger.
    */
-  constructor(config: {
+  constructor({ activities, hooks, debug }: {
     activities: Map<string | symbol, WrappedActivityConfig>;
     debug: (message: string, level?: number, ...args: Array<unknown>) => void;
-    hooks: object;
   })
   /**
    * Iterator over the registered activities.
@@ -43,9 +37,9 @@ export type WrappedActivityConfig = {
    */
   name: string | symbol;
   /**
-   * Operation or nested ActionBuilder to execute.
+   * Operation or nested wrapper to execute.
    */
-  op: (context: unknown) => unknown | Promise<unknown> | import('./ActionBuilder.js').default;
+  op: (context: unknown) => unknown | Promise<unknown> | ActionWrapper;
   /**
    * Optional loop semantic flags.
    */
@@ -54,14 +48,6 @@ export type WrappedActivityConfig = {
    * Predicate tied to WHILE/UNTIL semantics.
    */
   pred?: ((context: unknown) => boolean | Promise<boolean>) | undefined;
-  /**
-   * Splitter function for SPLIT activities.
-   */
-  splitter?: ((context: unknown) => unknown) | undefined;
-  /**
-   * Rejoiner function for SPLIT activities.
-   */
-  rejoiner?: ((originalContext: unknown, splitResults: unknown) => unknown) | undefined;
   /**
    * Parent action instance supplied when invoking the op.
    */

package/src/types/lib/ActionWrapper.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ActionWrapper.d.ts","sourceRoot":"","sources":["../../lib/ActionWrapper.js"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AAEH;;GAEG;AAEH;;GAEG;AACH;IAqBE;;;;;;;OAOG;IACH,oBAJG;QAA0D,UAAU,EAA5D,GAAG,CAAC,MAAM,GAAC,MAAM,EAAE,qBAAqB,CAAC;QACkC,KAAK,EAAhF,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,KAAK,CAAC,OAAO,CAAC,KAAK,IAAI;QACnD,KAAK,EAApB,MAAM;KAChB,EAUA;IAOD;;;;OAIG;IACH,kBAFa,gBAAgB,CAI5B;;CACF;;;;;UAtEa,MAAM,GAAC,MAAM;;;;QACb,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,GAAC,OAAO,CAAC,OAAO,CAAC,GAAC,OAAO,oBAAoB,EAAE,OAAO;;;;;;;;sBAEzE,OAAO,KAAK,OAAO,GAAC,OAAO,CAAC,OAAO,CAAC;;;;0BACpC,OAAO,KAAK,OAAO;;;;kCACX,OAAO,gBAAgB,OAAO,KAAK,OAAO;;;;aAC5D,OAAO;;;;uBACG,MAAM,UAAU,MAAM,WAAW,KAAK,CAAC,OAAO,CAAC,KAAK,IAAI;;+BAInE,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,OAAO,CAAC;qBAf1B,eAAe"}
+{"version":3,"file":"ActionWrapper.d.ts","sourceRoot":"","sources":["../../lib/ActionWrapper.js"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AAEH;;GAEG;AAEH;;GAEG;AACH;IAgBE;;;;OAIG;IACH,0CAFW;QAAC,UAAU,EAAE,GAAG,CAAC,MAAM,GAAC,MAAM,EAAE,qBAAqB,CAAC,CAAC;QAAC,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,KAAK,CAAC,OAAO,CAAC,KAAK,IAAI,CAAA;KAAC,EAW5I;IAOD;;;;OAIG;IACH,kBAFa,gBAAgB,CAI5B;;CACF;;;;;UA5Da,MAAM,GAAC,MAAM;;;;QACb,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,GAAC,OAAO,CAAC,OAAO,CAAC,GAAC,aAAa;;;;;;;;sBAElD,OAAO,KAAK,OAAO,GAAC,OAAO,CAAC,OAAO,CAAC;;;;aAC9C,OAAO;;;;uBACG,MAAM,UAAU,MAAM,WAAW,KAAK,CAAC,OAAO,CAAC,KAAK,IAAI;;+BAInE,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,OAAO,CAAC;qBAb1B,eAAe"}

package/src/types/lib/Activity.d.ts

@@ -1,5 +1,6 @@
 /**
- *
+ * Activity bit flags recognised by the builder. The flag decides
+ * loop semantics for an activity.
  */
 export type ACTIVITY = number
 /** @typedef {import("./ActionHooks.js").default} ActionHooks */
@@ -9,38 +10,24 @@ export type ACTIVITY = number
  *
  * @readonly
  * @enum {number}
- * @property {number} WHILE - Execute activity while predicate returns true (2)
- * @property {number} UNTIL - Execute activity until predicate returns false (4)
- * @property {number} SPLIT - Execute activity with split/rejoin pattern for parallel execution (8)
  */
 export const ACTIVITY: Readonly<{
   WHILE: number;
   UNTIL: number;
-  SPLIT: number;
 }>
 export default class Activity {
   /**
    * Construct an Activity definition wrapper.
    *
-   * @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 {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 {{action: unknown, name: string, op: (context: unknown) => unknown|Promise<unknown>|unknown, kind?: number, pred?: (context: unknown) => boolean|Promise<boolean>, hooks?: ActionHooks}} init - Initial properties describing the activity operation, loop semantics, and predicate
    */
-  constructor({ action, name, op, kind, pred, hooks, splitter, rejoiner }: {
+  constructor({ action, name, op, kind, pred, hooks }: {
     action: unknown;
-    name: string | symbol;
-    op: (context: unknown) => unknown | Promise<unknown> | import('./ActionBuilder.js').default;
-    kind?: number | undefined;
-    pred?: ((context: unknown) => boolean | Promise<boolean>) | undefined;
-    hooks?: import('./ActionHooks.js').default | undefined;
-    splitter?: ((context: unknown) => unknown) | undefined;
-    rejoiner?: ((originalContext: unknown, splitResults: unknown) => unknown) | undefined;
+    name: string;
+    op: (context: unknown) => unknown | Promise<unknown> | unknown;
+    kind?: number;
+    pred?: (context: unknown) => boolean | Promise<boolean>;
+    hooks?: ActionHooks;
   })
   /**
    * The activity name.
@@ -61,35 +48,17 @@ export default class Activity {
    */
   get pred(): (context: unknown) => boolean | Promise<boolean> | undefined
   /**
-   * The current context (if set).
-   *
-   * @returns {unknown} Current context value
-   */
-  get context(): unknown
-  /**
-   * The operator kind name (Function or ActionBuilder).
+   * The operator kind name (Function or ActionWrapper).
    *
    * @returns {string} - Kind name extracted via Data.typeOf
    */
   get opKind(): string
   /**
-   * The operator to execute (function or nested ActionBuilder).
+   * The operator to execute (function or nested wrapper).
    *
-   * @returns {(context: unknown) => unknown|Promise<unknown>|import("./ActionBuilder.js").default} - Activity operation
+   * @returns {unknown} - Activity operation
    */
-  get op(): (context: unknown) => unknown | Promise<unknown> | import('./ActionBuilder.js').default
-  /**
-   * The splitter function for SPLIT activities.
-   *
-   * @returns {((context: unknown) => unknown)|null} Splitter function or null
-   */
-  get splitter(): ((context: unknown) => unknown) | null
-  /**
-   * The rejoiner function for SPLIT activities.
-   *
-   * @returns {((originalContext: unknown, splitResults: unknown) => unknown)|null} Rejoiner function or null
-   */
-  get rejoiner(): ((originalContext: unknown, splitResults: unknown) => unknown) | null
+  get op(): unknown
   /**
    * The action instance this activity belongs to.
    *
@@ -100,22 +69,18 @@ export default class Activity {
    * Execute the activity with before/after hooks.
    *
    * @param {unknown} context - Mutable context flowing through the pipeline
-   * @returns {Promise<unknown>} - Activity result
+   * @returns {Promise<{activityResult: unknown}>} - Activity result wrapper with new context
    */
-  run(context: unknown): Promise<unknown>
+  run(context: unknown): Promise<{
+    activityResult: unknown;
+  }>
   /**
    * Attach hooks to this activity instance.
    *
-   * @param {ActionHooks} hooks - Hooks instance with optional before$/after$ methods
+   * @param {unknown} hooks - Hooks instance with optional before$/after$ methods
    * @returns {this} - This activity for chaining
    */
-  setActionHooks(hooks: ActionHooks): this
-  /**
-   * Get the hooks instance attached to this activity.
-   *
-   * @returns {ActionHooks|null} The hooks instance or null
-   */
-  get hooks(): ActionHooks | null
+  setActionHooks(hooks: unknown): this
   #private
 }
 export type ActionHooks = import('./ActionHooks.js').default

package/src/types/lib/Activity.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Activity.d.ts","sourceRoot":"","sources":["../../lib/Activity.js"],"names":[],"mappings":";;;uBASU,MAAM;AAPhB,gEAAgE;AAEhE;;;;;;;;;GASG;AACH;;;;GAIE;AAEF;IAoBE;;;;;;;;;;;;OAYG;IACH,yEATG;QAAsB,MAAM,EAApB,OAAO;QACa,IAAI,EAAxB,MAAM,GAAC,MAAM;QAC6E,EAAE,EAA5F,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,GAAC,OAAO,CAAC,OAAO,CAAC,GAAC,OAAO,oBAAoB,EAAE,OAAO;QACrE,IAAI;QACoC,IAAI,cAAhD,OAAO,KAAK,OAAO,GAAC,OAAO,CAAC,OAAO,CAAC;QAC3B,KAAK;QACa,QAAQ,cAAnC,OAAO,KAAK,OAAO;QACuC,QAAQ,sBAA1D,OAAO,gBAAgB,OAAO,KAAK,OAAO;KACtE,EAUA;IAED;;;;OAIG;IACH,YAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,YAFa,MAAM,GAAC,IAAI,CAIvB;IAED;;;;OAIG;IACH,YAFa,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,GAAC,OAAO,CAAC,OAAO,CAAC,GAAC,SAAS,CAIpE;IAED;;;;OAIG;IACH,eAFa,OAAO,CAInB;IAED;;;;OAIG;IACH,cAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,UAFa,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,GAAC,OAAO,CAAC,OAAO,CAAC,GAAC,OAAO,oBAAoB,EAAE,OAAO,CAI/F;IAED;;;;OAIG;IACH,gBAFa,CAAC,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,GAAC,IAAI,CAIhD;IAED;;;;OAIG;IACH,gBAFa,CAAC,CAAC,eAAe,EAAE,OAAO,EAAE,YAAY,EAAE,OAAO,KAAK,OAAO,CAAC,GAAC,IAAI,CAI/E;IAED;;;;OAIG;IACH,cAFa,OAAO,CAInB;IAED;;;;;OAKG;IACH,aAHW,OAAO,GACL,OAAO,CAAC,OAAO,CAAC,CAa5B;IAED;;;;;OAKG;IACH,sBAHW,WAAW,GACT,IAAI,CAOhB;IAED;;;;OAIG;IACH,aAFa,WAAW,GAAC,IAAI,CAI5B;;CACF;0BAvLa,OAAO,kBAAkB,EAAE,OAAO"}
+{"version":3,"file":"Activity.d.ts","sourceRoot":"","sources":["../../lib/Activity.js"],"names":[],"mappings":";;;;uBASU,MAAM;AAPhB,gEAAgE;AAEhE;;;;;;GAMG;AACH;;;GAGE;AAEF;IAQE;;;;OAIG;IACH,qDAFW;QAAC,MAAM,EAAE,OAAO,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,GAAC,OAAO,CAAC,OAAO,CAAC,GAAC,OAAO,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,GAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QAAC,KAAK,CAAC,EAAE,WAAW,CAAA;KAAC,EAShM;IAED;;;;OAIG;IACH,YAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,YAFa,MAAM,GAAC,IAAI,CAIvB;IAED;;;;OAIG;IACH,YAFa,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,GAAC,OAAO,CAAC,OAAO,CAAC,GAAC,SAAS,CAIpE;IAED;;;;OAIG;IACH,cAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,UAFa,OAAO,CAInB;IAED;;;;OAIG;IACH,cAFa,OAAO,CAInB;IAED;;;;;OAKG;IACH,aAHW,OAAO,GACL,OAAO,CAAC;QAAC,cAAc,EAAE,OAAO,CAAA;KAAC,CAAC,CAa9C;IAED;;;;;OAKG;IACH,sBAHW,OAAO,GACL,IAAI,CAOhB;;CACF;0BAzHa,OAAO,kBAAkB,EAAE,OAAO"}