@gesslar/actioneer 1.6.0 → 2.0.0

package/src/lib/ActionHooks.js

@@ -1,60 +1,35 @@
-import {setTimeout as timeout} from "timers/promises"
-import {Data, FileObject, Sass, Promised, Util, Valid} from "@gesslar/toolkit"
+import {FileObject, Sass} from "@gesslar/toolkit"
+import {ActionHooks as BrowserActionHooks} from "../browser/index.js"
 
 /**
  * @typedef {(message: string, level?: number, ...args: Array<unknown>) => void} DebugFn
  */
 
 /**
- * @typedef {object} ActionHooksConfig
+ * @typedef {object} NodeActionHooksConfig
  * @property {string} actionKind Action identifier shared between runner and hooks.
- * @property {FileObject} hooksFile File handle used to import the hooks module.
+ * @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
+ * Node.js-enhanced ActionHooks that extends browser version with file-based hook loading.
+ * Inherits all browser functionality and adds FileObject-based hook import capability.
  */
-
-/**
- * Generic base class for managing hooks with configurable event types.
- * Provides common functionality for hook registration, execution, and lifecycle management.
- * Designed to be extended by specific implementations.
- */
-export default class ActionHooks {
+export default class ActionHooks extends BrowserActionHooks {
   /** @type {FileObject|null} */
   #hooksFile = null
-  /** @type {HookModule|null} */
-  #hooks = null
-  /** @type {string|null} */
-  #actionKind = null
-  /** @type {number} */
-  #timeout = 1_000 // Default 1 second timeout
-  /** @type {DebugFn|null} */
-  #debug = null
 
   /**
    * Creates a new ActionHook instance.
    *
-   * @param {ActionHooksConfig} config Configuration values describing how to load the hooks.
+   * @param {NodeActionHooksConfig} config Configuration values describing how to load the hooks.
    */
   constructor({actionKind, hooksFile, hooks, hookTimeout = 1_000, debug}) {
-    this.#actionKind = actionKind
+    super({actionKind, hooks, hookTimeout, debug})
     this.#hooksFile = hooksFile
-    this.#hooks = hooks
-    this.#timeout = hookTimeout
-    this.#debug = debug
-  }
-
-  /**
-   * Gets the action identifier.
-   *
-   * @returns {string} Action identifier or instance
-   */
-  get actionKind() {
-    return this.#actionKind
   }
 
   /**
@@ -66,42 +41,6 @@ export default class ActionHooks {
     return this.#hooksFile
   }
 
-  /**
-   * Gets the loaded hooks object.
-   *
-   * @returns {object|null} Hooks object or null if not loaded
-   */
-  get hooks() {
-    return this.#hooks
-  }
-
-  /**
-   * Gets the hook execution timeout in milliseconds.
-   *
-   * @returns {number} Timeout in milliseconds
-   */
-  get timeout() {
-    return this.#timeout
-  }
-
-  /**
-   * Gets the setup hook function if available.
-   *
-   * @returns {(args: object) => unknown|null} Setup hook function or null
-   */
-  get setup() {
-    return this.hooks?.setup || null
-  }
-
-  /**
-   * Gets the cleanup hook function if available.
-   *
-   * @returns {(args: object) => unknown|null} Cleanup hook function or null
-   */
-  get cleanup() {
-    return this.hooks?.cleanup || null
-  }
-
   /**
    * Static factory method to create and initialize a hook manager.
    * Loads hooks from the specified file and returns an initialized instance.
@@ -114,125 +53,49 @@ export default class ActionHooks {
   static async new(config, debug) {
     debug("Creating new HookManager instance with args: %o", 2, config)
 
-    const instance = new ActionHooks({...config, debug})
-    if(!instance.#hooks) {
-      const hooksFile = new FileObject(instance.#hooksFile)
-
-      debug("Loading hooks from %o", 2, hooksFile.uri)
-
-      debug("Checking hooks file exists: %o", 2, hooksFile.uri)
-      if(!await hooksFile.exists)
-        throw Sass.new(`No such hooks file, ${hooksFile.uri}`)
-
-      try {
-        const hooksImport = await hooksFile.import()
-
-        if(!hooksImport)
-          return null
-
-        debug("Hooks file imported successfully as a module", 2)
-
-        const actionKind = instance.actionKind
-        if(!hooksImport[actionKind])
-          return null
-
-        const hooks = new hooksImport[actionKind]({debug})
-
-        debug(hooks.constructor.name, 4)
-
-        instance.#hooks = hooks
-        debug("Hooks %o loaded successfully for %o", 2, hooksFile.uri, instance.actionKind)
-
-        return instance
-      } catch(error) {
-        debug("Failed to load hooks %o: %o", 1, hooksFile.uri, error.message)
-
-        return null
-      }
+    // If hooks already provided, use parent class factory
+    if(config.hooks) {
+      return super.new(config, debug)
     }
 
-    return instance
-  }
+    // Load hooks from file
+    if(!config.hooksFile) {
+      debug("No hooks file provided", 2)
 
-  /**
-   * 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>}
-   */
-  async callHook(kind, activityName, context) {
-    try {
-      const debug = this.#debug
-      const hooks = this.#hooks
-
-      if(!hooks)
-        return
-
-      const stringActivityName = Data.isType(activityName, "Symbol")
-        ? activityName.description
-        : activityName
-
-      const hookName = this.#getActivityHookName(kind, stringActivityName)
+      return null
+    }
 
-      debug("Looking for hook: %o", 4, hookName)
+    const hooksFile = new FileObject(config.hooksFile)
 
-      const hook = hooks[hookName]
-      if(!hook)
-        return
+    debug("Loading hooks from %o", 2, hooksFile.uri)
+    debug("Checking hooks file exists: %o", 2, hooksFile.uri)
 
-      debug("Triggering hook: %o", 4, hookName)
-      Valid.type(hook, "Function", `Hook "${hookName}" is not a function`)
+    if(!await hooksFile.exists)
+      throw Sass.new(`No such hooks file, ${hooksFile.uri}`)
 
-      const hookFunction = async() => {
-        debug("Hook function starting execution: %o", 4, hookName)
+    try {
+      const hooksImport = await hooksFile.import()
 
-        const duration = (
-          await Util.time(() => hook.call(this.#hooks, context))
-        ).cost
+      if(!hooksImport)
+        return null
 
-        debug("Hook function completed successfully: %o, after %oms", 4, hookName, duration)
-      }
+      debug("Hooks file imported successfully as a module", 2)
 
-      const hookTimeout = this.timeout
-      const expireAsync = (async() => {
-        await timeout(hookTimeout)
-        throw Sass.new(`Hook ${hookName} execution exceeded timeout of ${hookTimeout}ms`)
-      })()
+      if(!hooksImport[config.actionKind])
+        return null
 
-      try {
-        debug("Starting Promise race for hook: %o", 4, hookName)
-        await Promised.race([
-          hookFunction(),
-          expireAsync
-        ])
-      } catch(error) {
-        throw Sass.new(`Processing hook ${kind}$${activityName}`, error)
-      }
+      const hooks = new hooksImport[config.actionKind]({debug})
 
-      debug("We made it throoough the wildernessss", 4)
+      debug(hooks.constructor.name, 4)
+      debug("Hooks loaded successfully for %o", 2, config.actionKind)
 
+      // Create instance with loaded hooks
+      return new ActionHooks({...config, hooks, debug})
     } catch(error) {
-      throw Sass.new(`Processing hook ${kind}$${activityName}`, error)
+      debug("Failed to load hooks %o: %o", 1, hooksFile.uri, error.message)
+
+      return null
     }
   }
 
-  #getActivityHookName(event, activityName) {
-    const name = activityName
-      .split(" ")
-      .map(a => a.trim())
-      .filter(Boolean)
-      .map(a => a
-        .split("")
-        .filter(b => /[\w]/.test(b))
-        .filter(Boolean)
-        .join("")
-      )
-      .map(a => a.toLowerCase())
-      .map((a, i) => i === 0 ? a : Util.capitalize(a))
-      .join("")
-
-    return `${event}$${name}`
-  }
 }

package/src/types/browser/index.d.ts

@@ -0,0 +1,7 @@
+export { default as ActionBuilder } from "./lib/ActionBuilder.js";
+export { default as ActionHooks } from "./lib/ActionHooks.js";
+export { default as ActionRunner } from "./lib/ActionRunner.js";
+export { default as ActionWrapper } from "./lib/ActionWrapper.js";
+export { default as Piper } from "./lib/Piper.js";
+export { default as Activity, ACTIVITY } from "./lib/Activity.js";
+//# sourceMappingURL=index.d.ts.map

package/src/types/browser/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../browser/index.js"],"names":[],"mappings":""}

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

@@ -0,0 +1,174 @@
+/** @typedef {import("./ActionRunner.js").default} ActionRunner */
+/** @typedef {typeof import("./Activity.js").ACTIVITY} ActivityFlags */
+/**
+ * @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.
+ */
+/**
+ * @typedef {object} ActionBuilderConfig
+ * @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.
+ */
+/**
+ * @typedef {(context: unknown) => unknown|Promise<unknown>} ActionFunction
+ */
+/**
+ * Fluent builder for describing how an action should process the context that
+ * flows through the {@link ActionRunner}. Consumers register named activities,
+ * and nested parallel pipelines before handing the builder back to the runner
+ * for execution.
+ *
+ * Typical usage:
+ *
+ * ```js
+ * const pipeline = new ActionBuilder(myAction)
+ *   .act("prepare", ACTIVITY.ONCE, ctx => ctx.initialise())
+ *   .parallel(parallel => parallel
+ *     .act("step", ACTIVITY.MANY, ctx => ctx.consume())
+ *   )
+ *   .act("finalise", ACTIVITY.ONCE, ctx => ctx.complete())
+ *   .build()
+ * ```
+ *
+ * @class ActionBuilder
+ */
+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
+     */
+    constructor(action?: ActionBuilderAction, { tag, debug }?: ActionBuilderConfig);
+    get tag(): symbol | null;
+    /**
+     * Register an activity that the runner can execute.
+     *
+     * Overloads:
+     * - do(name, op)
+     * - do(name, kind, pred, opOrWrapper)
+     * - do(name, kind, splitter, rejoiner, opOrWrapper)
+     *
+     * @overload
+     * @param {string|symbol} name Activity name
+     * @param {ActionFunction} op Operation to execute once.
+     * @returns {ActionBuilder}
+     */
+    do(name: string | symbol, op: ActionFunction): ActionBuilder;
+    /**
+     * @overload
+     * @param {string|symbol} name Activity name
+     * @param {number} kind Kind bitfield from {@link ActivityFlags}.
+     * @param {(context: unknown) => boolean|Promise<boolean>} pred Predicate executed before/after the op.
+     * @param {ActionFunction|import("./ActionWrapper.js").default} op Operation or nested wrapper to execute.
+     * @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 ACTIVITY.SPLIT flag.
+     * @param {(context: unknown) => unknown} splitter Splitter function for SPLIT mode.
+     * @param {(originalContext: unknown, splitResults: unknown) => unknown} rejoiner Rejoiner function for SPLIT mode.
+     * @param {ActionFunction|import("./ActionWrapper.js").default} op Operation or nested wrapper to execute.
+     * @returns {ActionBuilder}
+     */
+    do(name: string | symbol, kind: number, splitter: (context: unknown) => unknown, rejoiner: (originalContext: unknown, splitResults: unknown) => unknown, op: ActionFunction | import("./ActionWrapper.js").default): 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.
+     * @throws {Sass} If hooks have already been configured.
+     */
+    withHooksFile(hooksFile: string, hooksKind: string): 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.
+     * @throws {Sass} If hooks have already been configured with a different instance.
+     */
+    withHooks(hooks: import("./ActionHooks.js").default): 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.
+     * @returns {ActionBuilder} The builder instance for chaining.
+     */
+    withAction(action: ActionBuilderAction): 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.
+     */
+    build(): Promise<import("./ActionWrapper.js").default>;
+    #private;
+}
+export type ActionRunner = import("./ActionRunner.js").default;
+export type ActivityFlags = typeof import("./Activity.js").ACTIVITY;
+export type DebugFn = (message: string, level?: number, ...args: Array<unknown>) => void;
+export type ActionBuilderAction = {
+    /**
+     * Function invoked during {@link ActionBuilder#build} to register activities.
+     */
+    setup: (builder: ActionBuilder) => void;
+    /**
+     * Optional tag to reuse when reconstructing builders.
+     */
+    tag?: symbol | undefined;
+};
+export type ActionBuilderConfig = {
+    /**
+     * Optional tag for the builder instance.
+     */
+    tag?: symbol | undefined;
+    /**
+     * Logger used by the pipeline internals.
+     */
+    debug?: DebugFn | undefined;
+};
+export type ActivityDefinition = {
+    /**
+     * Parent action instance when available.
+     */
+    action: ActionBuilderAction | null;
+    /**
+     * Logger function.
+     */
+    debug: DebugFn | null;
+    /**
+     * Activity identifier.
+     */
+    name: string | symbol;
+    /**
+     * Operation to execute.
+     */
+    op: ActionFunction | import("./ActionWrapper.js").default;
+    /**
+     * Optional kind flags from {@link ActivityFlags}.
+     */
+    kind?: number | undefined;
+    /**
+     * Loop predicate.
+     */
+    pred?: ((context: unknown) => boolean | Promise<boolean>) | undefined;
+};
+export type ActionFunction = (context: unknown) => unknown | Promise<unknown>;
+//# sourceMappingURL=ActionBuilder.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ActionBuilder.d.ts","sourceRoot":"","sources":["../../../browser/lib/ActionBuilder.js"],"names":[],"mappings":"AAMA,kEAAkE;AAClE,uEAAuE;AAEvE;;GAEG;AAEH;;;;GAIG;AAEH;;;;GAIG;AAEH;;;;;;;;GAQG;AAEH;;GAEG;AAEH;;;;;;;;;;;;;;;;;;;GAmBG;AACH;IAaE;;;;;OAKG;IACH,qBAHW,mBAAmB,mBACnB,mBAAmB,EAe7B;IAED,yBAEC;;;;;;;;;;;;;;IAUE,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,OAAO,oBAAoB,EAAE,OAAO,GACjD,aAAa,CACzB;IA0DD;;;;;;;OAOG;IACH,yBALW,MAAM,aACN,MAAM,GACJ,aAAa,CAYzB;IAED;;;;;;OAMG;IACH,iBAJW,OAAO,kBAAkB,EAAE,OAAO,GAChC,aAAa,CAgBzB;IAED;;;;;;OAMG;IACH,mBAHW,mBAAmB,GACjB,aAAa,CAczB;IAeD;;;;;OAKG;IACH,SAFa,OAAO,CAAC,OAAO,oBAAoB,EAAE,OAAO,CAAC,CAmBzD;;CAqBF;2BA3Sa,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/browser/lib/ActionHooks.d.ts

@@ -0,0 +1,98 @@
+/**
+ * @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
+ */
+/**
+ * Generic base class for managing hooks with configurable event types.
+ * Provides common functionality for hook registration, execution, and lifecycle management.
+ * Designed to be extended by specific implementations.
+ *
+ * Browser version: Requires pre-instantiated hooks. File-based loading is not supported.
+ */
+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
+     */
+    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.
+     */
+    constructor({ actionKind, hooks, hookTimeout, debug }: ActionHooksConfig);
+    /**
+     * Gets the action identifier.
+     *
+     * @returns {string} Action identifier or instance
+     */
+    get actionKind(): string;
+    /**
+     * Gets the loaded hooks object.
+     *
+     * @returns {object|null} Hooks object or null if not loaded
+     */
+    get hooks(): object | null;
+    /**
+     * Gets the hook execution timeout in milliseconds.
+     *
+     * @returns {number} Timeout in milliseconds
+     */
+    get timeout(): number;
+    /**
+     * Gets the setup hook function if available.
+     *
+     * @returns {(args: object) => unknown|null} Setup hook function or null
+     */
+    get setup(): (args: object) => unknown | null;
+    /**
+     * Gets the cleanup hook function if available.
+     *
+     * @returns {(args: object) => unknown|null} Cleanup hook function or null
+     */
+    get cleanup(): (args: object) => unknown | null;
+    /**
+     * 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>}
+     */
+    callHook(kind: "before" | "after" | "setup" | "cleanup" | string, activityName: string | symbol, context: unknown): Promise<void>;
+    #private;
+}
+export type DebugFn = (message: string, level?: number, ...args: Array<unknown>) => void;
+export type ActionHooksConfig = {
+    /**
+     * Action identifier shared between runner and hooks.
+     */
+    actionKind: string;
+    /**
+     * Already-instantiated hooks implementation.
+     */
+    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>;
+//# sourceMappingURL=ActionHooks.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ActionHooks.d.ts","sourceRoot":"","sources":["../../../browser/lib/ActionHooks.js"],"names":[],"mappings":"AAEA;;GAEG;AAEH;;;;;;GAMG;AAEH;;GAEG;AAEH;;;;;;GAMG;AACH;IAmEE;;;;;;;OAOG;IACH,qBAJW,iBAAiB,SACjB,OAAO,GACL,OAAO,CAAC,WAAW,GAAC,IAAI,CAAC,CAgBrC;IA/ED;;;;OAIG;IACH,uDAFW,iBAAiB,EAO3B;IAED;;;;OAIG;IACH,kBAFa,MAAM,CAIlB;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;IA0BD;;;;;;;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;sBAlMY,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,KAAK,CAAC,OAAO,CAAC,KAAK,IAAI;;;;;gBAKjE,MAAM;;;;WACN,OAAO;;;;;;;;WAEP,OAAO;;yBAIR,MAAM,CAAC,MAAM,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,GAAC,OAAO,CAAC"}

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

@@ -0,0 +1,43 @@
+/**
+ * @typedef {(message: string, level?: number, ...args: Array<unknown>) => void} DebugFn
+ */
+/**
+ * @typedef {object} ActionRunnerOptions
+ * @property {DebugFn} [debug] Logger function.
+ */
+/**
+ * Orchestrates execution of {@link ActionBuilder}-produced pipelines.
+ *
+ * Activities run in insertion order, with support for once-off work, repeated
+ * loops, and nested parallel pipelines. Each activity receives a mutable
+ * context object under `result.value` that can be replaced or enriched.
+ */
+export default class ActionRunner extends Piper {
+    /**
+     * Instantiate a runner over an optional action wrapper.
+     *
+     * @param {import("./ActionBuilder.js").default|null} actionBuilder ActionBuilder to build.
+     * @param {ActionRunnerOptions} [options] Optional debug overrides.
+     */
+    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.
+     */
+    run(context: unknown): Promise<unknown>;
+    #private;
+}
+export type DebugFn = (message: string, level?: number, ...args: Array<unknown>) => void;
+export type ActionRunnerOptions = {
+    /**
+     * Logger function.
+     */
+    debug?: DebugFn | undefined;
+};
+import Piper from "./Piper.js";
+//# sourceMappingURL=ActionRunner.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ActionRunner.d.ts","sourceRoot":"","sources":["../../../browser/lib/ActionRunner.js"],"names":[],"mappings":"AAKA;;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,CAuG5B;;CA0FF;sBA1PY,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,KAAK,CAAC,OAAO,CAAC,KAAK,IAAI;;;;;;;kBAH7D,YAAY"}

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

@@ -0,0 +1,62 @@
+/**
+ * @typedef {object} WrappedActivityConfig
+ * @property {string|symbol} name Activity identifier used by hooks/logs.
+ * @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 {unknown} [action] Parent action instance supplied when invoking the op.
+ * @property {(message: string, level?: number, ...args: Array<unknown>) => void} [debug] Optional logger reference.
+ */
+/**
+ * @typedef {Generator<Activity, void, unknown>} ActivityIterator
+ */
+/**
+ * Thin wrapper that materialises {@link Activity} instances on demand.
+ */
+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.
+     */
+    constructor({ activities, hooks, debug }: {
+        activities: Map<string | symbol, WrappedActivityConfig>;
+        debug: (message: string, level?: number, ...args: Array<unknown>) => void;
+    });
+    /**
+     * Iterator over the registered activities.
+     *
+     * @returns {ActivityIterator} Lazy iterator yielding Activity instances.
+     */
+    get activities(): ActivityIterator;
+    #private;
+}
+export type WrappedActivityConfig = {
+    /**
+     * Activity identifier used by hooks/logs.
+     */
+    name: string | symbol;
+    /**
+     * Operation or nested wrapper to execute.
+     */
+    op: (context: unknown) => unknown | Promise<unknown> | ActionWrapper;
+    /**
+     * Optional loop semantic flags.
+     */
+    kind?: number | undefined;
+    /**
+     * Predicate tied to WHILE/UNTIL semantics.
+     */
+    pred?: ((context: unknown) => boolean | Promise<boolean>) | undefined;
+    /**
+     * Parent action instance supplied when invoking the op.
+     */
+    action?: unknown;
+    /**
+     * Optional logger reference.
+     */
+    debug?: ((message: string, level?: number, ...args: Array<unknown>) => void) | undefined;
+};
+export type ActivityIterator = Generator<Activity, void, unknown>;
+import Activity from "./Activity.js";
+//# sourceMappingURL=ActionWrapper.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ActionWrapper.d.ts","sourceRoot":"","sources":["../../../browser/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"}