@gesslar/actioneer 0.1.3 → 0.2.1

package/README.md

@@ -28,8 +28,8 @@ class MyAction {
   }
 }
 
-const wrapper = new ActionBuilder(new MyAction()).build()
-const runner = new ActionRunner(wrapper)
+const builder = new ActionBuilder(new MyAction())
+const runner = new ActionRunner(builder)
 const result = await runner.pipe([{}], 4) // run up to 4 contexts concurrently
 console.log(result)
 ```
@@ -44,6 +44,132 @@ import { ActionBuilder, ActionRunner } from "@gesslar/actioneer"
 
 If you'd like more complete typings or additional JSDoc, open an issue or send a PR — contributions welcome.
 
+## ActionHooks
+
+Actioneer supports lifecycle hooks that can execute before and after each activity in your pipeline. Hooks are loaded from a module and can be configured either by file path or by providing a pre-instantiated hooks object.
+
+### Hook System Overview
+
+The hook system allows you to:
+
+- Execute code before and after each activity in your pipeline
+- Implement setup and cleanup logic
+- Add observability and logging to your pipelines
+- Modify or inspect the context flowing through activities
+
+### Configuring Hooks
+
+You can attach hooks to an ActionBuilder in two ways:
+
+#### 1. Load hooks from a file
+
+```js
+import { ActionBuilder, ActionRunner } from "@gesslar/actioneer"
+
+class MyAction {
+  setup(builder) {
+    builder
+      .withHooksFile("./hooks/MyActionHooks.js", "MyActionHooks")
+      .do("prepare", ctx => { ctx.count = 0 })
+      .do("work", ctx => { ctx.count += 1 })
+  }
+}
+
+const builder = new ActionBuilder(new MyAction())
+const runner = new ActionRunner(builder)
+const result = await runner.pipe([{}], 4)
+```
+
+#### 2. Provide a pre-instantiated hooks object
+
+```js
+import { ActionBuilder, ActionRunner } from "@gesslar/actioneer"
+import { MyActionHooks } from "./hooks/MyActionHooks.js"
+
+const hooks = new MyActionHooks({ debug: console.log })
+
+class MyAction {
+  setup(builder) {
+    builder
+      .withHooks(hooks)
+      .do("prepare", ctx => { ctx.count = 0 })
+      .do("work", ctx => { ctx.count += 1 })
+  }
+}
+
+const builder = new ActionBuilder(new MyAction())
+const runner = new ActionRunner(builder)
+const result = await runner.pipe([{}], 4)
+```
+
+### Writing Hooks
+
+Hooks are classes exported from a module. The hook methods follow a naming convention: `event$activityName`.
+
+```js
+// hooks/MyActionHooks.js
+export class MyActionHooks {
+  constructor({ debug }) {
+    this.debug = debug
+  }
+
+  // Hook that runs before the "prepare" activity
+  async before$prepare(context) {
+    this.debug("About to prepare", context)
+  }
+
+  // Hook that runs after the "prepare" activity
+  async after$prepare(context) {
+    this.debug("Finished preparing", context)
+  }
+
+  // Hook that runs before the "work" activity
+  async before$work(context) {
+    this.debug("Starting work", context)
+  }
+
+  // Hook that runs after the "work" activity
+  async after$work(context) {
+    this.debug("Work complete", context)
+  }
+
+  // Optional: setup hook runs once at initialization
+  async setup(args) {
+    this.debug("Hooks initialized")
+  }
+
+  // Optional: cleanup hook for teardown
+  async cleanup(args) {
+    this.debug("Hooks cleaned up")
+  }
+}
+```
+
+### Hook Naming Convention
+
+Activity names are transformed to hook method names:
+
+- Spaces are removed and words are camelCased: `"do work"` → `before$doWork` / `after$doWork`
+- Non-word characters are stripped: `"step-1"` → `before$step1` / `after$step1`
+- First word stays lowercase: `"Prepare Data"` → `before$prepareData` / `after$prepareData`
+
+### Hook Timeout
+
+By default, hooks have a 1-second (1000ms) timeout. If a hook exceeds this timeout, the pipeline will throw a `Sass` error. You can configure the timeout when creating the hooks:
+
+```js
+new ActionHooks({
+  actionKind: "MyActionHooks",
+  hooksFile: "./hooks.js",
+  hookTimeout: 5000, // 5 seconds
+  debug: console.log
+})
+```
+
+### Nested Pipelines and Hooks
+
+When you nest ActionBuilders (for branching or parallel execution), the parent's hooks are automatically passed to all children, ensuring consistent hook behavior throughout the entire pipeline hierarchy.
+
 ### Optional TypeScript (local, opt-in)
 
 This project intentionally avoids committing TypeScript tool configuration. If you'd like to use TypeScript's checker locally (for editor integration or optional JSDoc checking), you can drop a `tsconfig.json` in your working copy — `tsconfig.json` is already in the repository `.gitignore`, so feel free to typecheck yourselves into oblivion.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gesslar/actioneer",
-  "version": "0.1.3",
+  "version": "0.2.1",
   "description": "Ready? Set?? ACTION!! pew! pew! pew!",
   "main": "./src/index.js",
   "type": "module",

package/src/lib/ActionBuilder.js

@@ -1,6 +1,7 @@
 import {Data, Sass, Valid} from "@gesslar/toolkit"
 
 import ActionWrapper from "./ActionWrapper.js"
+import ActionHooks from "./ActionHooks.js"
 
 /** @typedef {import("./ActionRunner.js").default} ActionRunner */
 /** @typedef {typeof import("./Activity.js").ACTIVITY} ActivityFlags */
@@ -29,6 +30,8 @@ import ActionWrapper from "./ActionWrapper.js"
  * @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).
  */
 
 /**
@@ -38,8 +41,8 @@ import ActionWrapper from "./ActionWrapper.js"
 /**
  * Fluent builder for describing how an action should process the context that
  * flows through the {@link ActionRunner}. Consumers register named activities,
- * optional hook pairs, and nested parallel pipelines before handing the
- * builder back to the runner for execution.
+ * and nested parallel pipelines before handing the builder back to the runner
+ * for execution.
  *
  * Typical usage:
  *
@@ -64,12 +67,29 @@ export default class ActionBuilder {
   #debug = null
   /** @type {symbol|null} */
   #tag = null
+  /** @type {string|null} */
+  #hooksFile = null
+  /** @type {string|null} */
+  #hooksKind = null
+  /** @type {unknown|null} */
+  #hooks = null
+  /** @type {import("./ActionHooks.js").default|null} */
+  #actionHooks = null
+
+  /**
+   * Get the builder's tag symbol.
+   *
+   * @returns {symbol|null} The tag symbol for this builder instance
+   */
+  get tag() {
+    return this.#tag
+  }
 
   /**
    * 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,
@@ -108,6 +128,16 @@ export default class ActionBuilder {
    * @returns {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}
+   */
+
   /**
    * Handles runtime dispatch across the documented overloads.
    *
@@ -125,22 +155,32 @@ export default class ActionBuilder {
 
     const action = this.#action
     const debug = this.#debug
-    const activityDefinition = {name, action, debug}
+    const activityDefinition = {name,action,debug}
 
     if(args.length === 1) {
-      const [op, kind] = args
+      const [op,kind] = args
       Valid.type(kind, "Number|undefined")
       Valid.type(op, "Function")
 
-      Object.assign(activityDefinition, {op, kind})
+      Object.assign(activityDefinition, {op,kind})
     } else if(args.length === 3) {
-      const [kind, pred, op] = args
+      const [kind,pred,op] = args
 
       Valid.type(kind, "Number")
       Valid.type(pred, "Function")
-      Valid.type(op, "Function|ActionWrapper")
+      Valid.type(op, "Function|ActionBuilder")
+
+      Object.assign(activityDefinition, {kind,pred,op})
+    } else if(args.length === 4) {
+      const [kind,splitter,rejoiner,op] = args
+
+      Valid.type(kind, "Number")
+      Valid.type(splitter, "Function")
+      Valid.type(rejoiner, "Function")
+      Valid.type(op, "Function|ActionBuilder")
+
+      Object.assign(activityDefinition, {kind,splitter,rejoiner,op})
 
-      Object.assign(activityDefinition, {kind, pred, op})
     } else {
       throw Sass.new("Invalid number of arguments passed to 'do'")
     }
@@ -150,6 +190,65 @@ export default class ActionBuilder {
     return this
   }
 
+  /**
+   * 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, hooksKind) {
+    Valid.assert(this.#exclusiveHooksCheck(), "Hooks have already been configured.")
+
+    this.#hooksFile = hooksFile
+    this.#hooksKind = hooksKind
+
+    return this
+  }
+
+  /**
+   * 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.
+   */
+  withHooks(hooks) {
+    Valid.assert(this.#exclusiveHooksCheck(), "Hooks have already been configured.")
+
+    this.#hooks = hooks
+
+    return this
+  }
+
+  /**
+   * 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) {
+    Valid.assert(this.#exclusiveHooksCheck(), "Hooks have already been configured.")
+
+    this.#actionHooks = actionHooks
+
+    return this
+  }
+
+  /**
+   * Ensures only one hooks configuration method is used at a time.
+   *
+   * @returns {boolean} True if no hooks have been configured yet, false otherwise.
+   * @private
+   */
+  #exclusiveHooksCheck() {
+    return !!(this.#hooksFile && this.#hooksKind) +
+           !!(this.#hooks) +
+           !!(this.#actionHooks) === 0
+  }
+
   /**
    * Validates that an activity name has not been reused.
    *
@@ -167,10 +266,12 @@ export default class ActionBuilder {
    * Finalises the builder and returns a payload that can be consumed by the
    * runner.
    *
-   * @returns {import("./ActionWrapper.js").default} Payload consumed by the {@link ActionRunner} constructor.
+   * @returns {Promise<import("./ActionWrapper.js").default>} Payload consumed by the {@link ActionRunner} constructor.
    */
-  build() {
+  async build() {
     const action = this.#action
+    const activities = this.#activities
+    const debug = this.#debug
 
     if(!action.tag) {
       action.tag = this.#tag
@@ -178,9 +279,50 @@ export default class ActionBuilder {
       action.setup.call(action, this)
     }
 
-    return new ActionWrapper({
-      activities: this.#activities,
-      debug: this.#debug,
-    })
+    // All children in a branch also get the same hooks.
+    const hooks = await this.#getHooks()
+
+    return new ActionWrapper({activities,hooks,debug})
+  }
+
+  /**
+   * Check if this builder has ActionHooks configured.
+   *
+   * @returns {boolean} True if ActionHooks have been configured.
+   */
+  get hasActionHooks() {
+    return this.#actionHooks !== null
+  }
+
+  /**
+   * Internal method to retrieve or create ActionHooks instance.
+   * Caches the hooks instance to avoid redundant instantiation.
+   *
+   * @returns {Promise<import("./ActionHooks.js").default|undefined>} The ActionHooks instance if configured.
+   * @private
+   */
+  async #getHooks() {
+    if(this.#actionHooks) {
+      return this.#actionHooks
+    }
+
+    const newHooks = ActionHooks.new
+
+    const hooks = this.#hooks
+
+    if(hooks) {
+      this.#actionHooks = await newHooks({hooks}, this.#debug)
+
+      return this.#actionHooks
+    }
+
+    const hooksFile = this.#hooksFile
+    const hooksKind = this.#hooksKind
+
+    if(hooksFile && hooksKind) {
+      this.#actionHooks = await newHooks({hooksFile,hooksKind}, this.#debug)
+
+      return this.#actionHooks
+    }
   }
 }

package/src/lib/ActionHooks.js

@@ -1,5 +1,5 @@
 import {setTimeout as timeout} from "timers/promises"
-import {FileObject, Sass, Util, Valid} from "@gesslar/toolkit"
+import {Data, FileObject, Sass, Util, Valid} from "@gesslar/toolkit"
 
 /**
  * @typedef {(message: string, level?: number, ...args: Array<unknown>) => void} DebugFn
@@ -7,11 +7,10 @@ import {FileObject, Sass, Util, Valid} from "@gesslar/toolkit"
 
 /**
  * @typedef {object} ActionHooksConfig
- * @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 {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 {number} [hookTimeout] Timeout applied to hook execution in milliseconds.
- * @property {DebugFn} debug Logger to emit diagnostics.
  */
 
 /**
@@ -27,11 +26,11 @@ export default class ActionHooks {
   /** @type {FileObject|null} */
   #hooksFile = null
   /** @type {HookModule|null} */
-  #hooks = null
+  #hooksObject = null
   /** @type {string|null} */
   #actionKind = null
   /** @type {number} */
-  #timeout = 1000 // Default 1 second timeout
+  #timeout = 1_000 // Default 1 second timeout
   /** @type {DebugFn|null} */
   #debug = null
 
@@ -39,11 +38,15 @@ export default class ActionHooks {
    * 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, hooks, hookTimeout = 1000, debug}) {
+  constructor(
+    {actionKind, hooksFile, hooksObject, hookTimeout = 1_000},
+    debug,
+  ) {
     this.#actionKind = actionKind
     this.#hooksFile = hooksFile
-    this.#hooks = hooks
+    this.#hooksObject = hooksObject
     this.#timeout = hookTimeout
     this.#debug = debug
   }
@@ -51,7 +54,7 @@ export default class ActionHooks {
   /**
    * Gets the action identifier.
    *
-   * @returns {string} Action identifier or instance
+   * @returns {string|null} Action identifier or instance
    */
   get actionKind() {
     return this.#actionKind
@@ -60,7 +63,7 @@ export default class ActionHooks {
   /**
    * Gets the hooks file object.
    *
-   * @returns {FileObject} File object containing hooks
+   * @returns {FileObject|null} File object containing hooks
    */
   get hooksFile() {
     return this.#hooksFile
@@ -69,10 +72,10 @@ export default class ActionHooks {
   /**
    * Gets the loaded hooks object.
    *
-   * @returns {object|null} Hooks object or null if not loaded
+   * @returns {HookModule|null} Hooks object or null if not loaded
    */
   get hooks() {
-    return this.#hooks
+    return this.#hooksObject
   }
 
   /**
@@ -105,71 +108,80 @@ 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.
-   * Override loadHooks() in subclasses to customize hook loading logic.
+   * If a hooksObject is provided in config, it's used directly; otherwise, hooks are loaded from file.
    *
-   * @param {ActionHooksConfig} config Same configuration object as constructor
+   * @param {ActionHooksConfig} config Configuration object with hooks settings
    * @param {DebugFn} debug The debug function.
-   * @returns {Promise<ActionHooks|null>} Initialized hook manager or null if no hooks found
+   * @returns {Promise<ActionHooks>} Initialized hook manager
    */
   static async new(config, debug) {
     debug("Creating new HookManager instance with args: %o", 2, config)
 
-    const instance = new this(config, debug)
-    const hooksFile = instance.hooksFile
+    const instance = new ActionHooks(config, debug)
+    if(!instance.#hooksObject) {
+      const hooksFile = new FileObject(instance.#hooksFile)
 
-    debug("Loading hooks from %o", 2, hooksFile.uri)
+      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}`)
+      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
+      try {
+        const hooksImport = await hooksFile.import()
 
-      debug("Hooks file imported successfully as a module", 2)
+        if(!hooksImport)
+          return null
 
-      const actionKind = instance.actionKind
-      if(!hooksImport[actionKind])
-        return null
+        debug("Hooks file imported successfully as a module", 2)
 
-      const hooks = new hooksImport[actionKind]({debug})
+        const actionKind = instance.actionKind
+        if(!hooksImport[actionKind])
+          return null
 
-      debug(hooks.constructor.name, 4)
+        const hooks = new hooksImport[actionKind]({debug})
 
-      // Attach common properties to hooks
-      instance.#hooks = hooks
+        debug(hooks.constructor.name, 4)
 
-      debug("Hooks %o loaded successfully for %o", 2, hooksFile.uri, instance.actionKind)
+        instance.#hooksObject = 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 instance
+      } catch(error) {
+        debug("Failed to load hooks %o: %o", 1, hooksFile.uri, error.message)
 
-      return null
+        return null
+      }
     }
+
+    return instance
   }
 
   /**
-   * Invoke a dynamically-named hook such as `before$foo`.
+   * 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.
    *
    * @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.
    */
   async callHook(kind, activityName, context) {
-    try {
-      const debug = this.#debug
-      const hooks = this.#hooks
+    const debug = this.#debug
+    const hooks = this.#hooksObject
 
-      if(!hooks)
-        return
+    if(!hooks)
+      return
+
+    const stringActivityName = Data.isType(activityName, "Symbol")
+      ? activityName.description()
+      : activityName
 
-      const hookName = `${kind}$${activityName}`
+    const hookName = this.#getActivityHookName(kind, stringActivityName)
 
+    try {
       debug("Looking for hook: %o", 4, hookName)
 
       const hook = hooks[hookName]
@@ -183,7 +195,7 @@ export default class ActionHooks {
         debug("Hook function starting execution: %o", 4, hookName)
 
         const duration = (
-          await Util.time(() => hook.call(this.#hooks, context))
+          await Util.time(() => hook.call(this.#hooksObject, context))
         ).cost
 
         debug("Hook function completed successfully: %o, after %oms", 4, hookName, duration)
@@ -202,13 +214,41 @@ export default class ActionHooks {
           expireAsync
         ])
       } catch(error) {
-        throw Sass.new(`Processing hook ${kind}$${activityName}`, error)
+        throw Sass.new(`Processing hook ${hookName}`, error)
       }
 
       debug("We made it throoough the wildernessss", 4)
 
     } catch(error) {
-      throw Sass.new(`Processing hook ${kind}$${activityName}`, error)
+      throw Sass.new(`Processing hook ${hookName}`, error)
     }
   }
+
+  /**
+   * Transforms an activity name into a hook-compatible name.
+   * Converts "my activity name" to "myActivityName" and combines with event kind.
+   * Example: ("before", "my activity") => "before$myActivity"
+   *
+   * @param {string} event Hook event type (before, after, etc.)
+   * @param {string} activityName The raw activity name
+   * @returns {string} The formatted hook name
+   * @private
+   */
+  #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}`
+  }
 }