@gesslar/actioneer 0.1.0

package/README.md

@@ -0,0 +1,96 @@
+# Actioneer
+
+Actioneer is a small, focused Node.js action orchestration library. It provides a fluent builder for composing activities and a concurrent runner with lifecycle hooks and simple loop semantics (while/until). The project is written as ES modules and targets Node 20+.
+
+This repository extracts the action orchestration pieces from a larger codebase and exposes a compact API for building pipelines of work that can run concurrently with hook support and nested pipelines.
+
+## Install
+
+From npm:
+
+```bash
+npm install @gesslar/actioneer
+```
+
+## Quick start
+
+Import the builder and runner, define an action and run it:
+
+```js
+import { ActionBuilder, ActionRunner } from "@gesslar/actioneer"
+
+class MyAction {
+  setup (builder) {
+    builder
+      .do("prepare", ctx => { ctx.count = 0 })
+      .do("work", ctx => { ctx.count += 1 })
+      .do("finalise", ctx => { return ctx.count })
+  }
+}
+
+const wrapper = new ActionBuilder(new MyAction()).build()
+const runner = new ActionRunner(wrapper)
+const result = await runner.pipe([{}], 4) // run up to 4 contexts concurrently
+console.log(result)
+```
+
+## Types (TypeScript / VS Code)
+
+This package ships basic TypeScript declaration files under `src/types` and exposes them via the package `types` entrypoint. VS Code users will get completions and quick help when consuming the package:
+
+```ts
+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.
+
+### 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.
+
+Two common local options:
+
+- Editor/resolve-only (no checking): set `moduleResolution`/`module` and `noEmit` so the editor resolves imports consistently without typechecking.
+- Local JSDoc checks: set `allowJs: true` and `checkJs: true` with `noEmit: true` and `strict: false` to let the TypeScript checker validate JSDoc without enforcing strict typing.
+
+Examples of minimal configs and one-liners to run them are in the project discussion; use them locally if you want an optional safety net. The repository will not require or enforce these files.
+
+## Testing
+
+Run the small smoke tests with Node's built-in test runner:
+
+```bash
+npm test
+```
+
+The test suite is intentionally small; it verifies public exports and a few core behaviors. Add more unit tests under `tests/` if you need deeper coverage.
+
+## Publishing
+
+This repository is prepared for npm publishing. The package uses ESM and targets Node 20+. The `files` field includes the `src/` folder and types. If you publish, ensure the `version` in `package.json` is updated and you have an npm token configured on the CI runner.
+
+A simple publish checklist:
+
+- Bump the package version
+- Run `npm run lint` and `npm test`
+- Build/typecheck if you add a build step
+- Tag and push a Git release
+- Run `npm publish --access public`
+
+## Contributing
+
+Contributions and issues are welcome. Please open issues for feature requests or bugs. If you're submitting a PR, include tests for new behavior where possible.
+
+## License
+
+This project is published under the Unlicense (see `UNLICENSE.txt`).
+
+## Most Portum
+
+As this is my repo, I have some opinions I would like to express and be made clear.
+
+- We use ESLint around here. I have a very opinionated and hand-rolled `eslint.config.js` that is a requirement to be observed for this repo. Prettier can fuck off. It is the worst tooling I have ever had the misfortune of experiencing (no offence to Prettier) and I will not suffer its poor conventions in my repos in any way except to be denigrated (again, no offence). If you come culting some cargo about that that product, you are reminded that this is released under the Unlicense and are invited to fork off and drown the beautiful code in your poisonous Kool-Aid. Oh, yeah!
+- TypeScript is the devil and is the antithesis of pantser coding. It is discouraged to think that I have gone through rigourous anything that isn't development by sweat. If you're a plotter, I a-plot you for your work, and if you would like to extend this project with your rulers, your abacusi, and your Kanji tattoos that definitely mean exactly what you think they do, I invite you to please do, but in your own repos.
+- Thank you, I love you. BYEBYE!
+
+🤗

package/UNLICENSE.txt

@@ -0,0 +1,24 @@
+This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or
+distribute this software, either in source code form or as a compiled
+binary, for any purpose, commercial or non-commercial, and by any
+means.
+
+In jurisdictions that recognize copyright laws, the author or authors
+of this software dedicate any and all copyright interest in the
+software to the public domain. We make this dedication for the benefit
+of the public at large and to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of
+relinquishment in perpetuity of all present and future rights to this
+software under copyright law.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+
+For more information, please refer to <https://unlicense.org>

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@gesslar/actioneer",
+  "version": "0.1.0",
+  "description": "Ready? Set?? ACTION!! pew!pew!pew!pew!",
+  "main": "./src/index.js",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/types/index.d.ts",
+      "default": "./src/index.js"
+    }
+  },
+  "files": [
+    "src/",
+    "README.md",
+    "UNLICENSE.txt"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "lint": "eslint src/",
+    "lint:fix": "eslint src/ --fix",
+    "submit": "npm publish --access public",
+    "update": "npx npm-check-updates -u && npm install",
+    "test": "node --test tests/unit/*.test.js",
+    "test:unit": "node --test tests/unit/*.test.js",
+    "pr": "gt submit --publish --restack --ai"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gesslar/actioneer.git"
+  },
+  "keywords": [
+    "actioneer",
+    "pipeline",
+    "workflow",
+    "sabrina",
+    "salem",
+    "package",
+    "composition",
+    "lasagna"
+  ],
+  "author": "gesslar",
+  "license": "Unlicense",
+  "homepage": "https://github.com/gesslar/toolkit#readme",
+  "devDependencies": {
+    "@stylistic/eslint-plugin": "^5.4.0",
+    "@types/node": "^24.6.2",
+    "@typescript-eslint/eslint-plugin": "^8.45.0",
+    "@typescript-eslint/parser": "^8.45.0",
+    "eslint": "^9.36.0",
+    "eslint-plugin-jsdoc": "^60.7.1",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "@gesslar/toolkit": "^0.6.0"
+  }
+}

package/src/index.js

@@ -0,0 +1,6 @@
+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 Activity, ACTIVITY} from "./lib/Activity.js"
+export {default as Piper} from "./lib/Piper.js"

package/src/lib/ActionBuilder.js

@@ -0,0 +1,133 @@
+import {Data, Sass, Valid} from "@gesslar/toolkit"
+
+import ActionWrapper from "./ActionWrapper.js"
+
+/** @typedef {import("./ActionRunner.js").default} ActionRunner */
+
+/**
+ * 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.
+ *
+ * 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 {
+  #action = null
+  #activities = new Map([])
+  #debug = null
+  #tag = null
+
+  /**
+   * Creates a new ActionBuilder instance with the provided action callback.
+   *
+   * @param {(ctx: unknown) => unknown} action Base action invoked by the runner when a block satisfies the configured structure.
+   * @param {{tag?: symbol, debug?: (message: string, level?: number, ...args: Array<unknown>) => void}} [config] Options
+   */
+  constructor(
+    action,
+    {tag = action?.tag ?? Symbol(performance.now()), debug = () => {}} = {},
+  ) {
+    this.#debug = debug
+    this.#tag = this.#tag || tag
+
+    if(action) {
+      if(Data.typeOf(action.setup) !== "Function")
+        throw Sass.new("Setup must be a function.")
+
+      this.#action = action
+    }
+  }
+
+  /**
+   * Register an activity.
+   *
+   * Overloads:
+   * - do(name, op)
+   * - do(name, kind, pred, opOrWrapper)
+   *
+   * @param {string|symbol} name Activity name
+   * @param {...unknown} args See overloads
+   * @returns {ActionBuilder} The builder instance for chaining
+   */
+  do(name, ...args) {
+    this.#dupeActivityCheck(name)
+
+    // signatures
+    // name, [function] => once
+    // name, [number,function,function] => some kind of control operation
+    // name, [number,function,ActionBuilder] => some kind of branch
+
+    const action = this.#action
+    const debug = this.#debug
+    const activityDefinition = {name, action, debug}
+
+    if(args.length === 1) {
+      const [op, kind] = args
+      Valid.type(kind, "Number|undefined")
+      Valid.type(op, "Function")
+
+      Object.assign(activityDefinition, {op, kind})
+    } else if(args.length === 3) {
+      const [kind, pred, op] = args
+
+      Valid.type(kind, "Number")
+      Valid.type(pred, "Function")
+      Valid.type(op, "Function|ActionWrapper")
+
+      Object.assign(activityDefinition, {kind, pred, op})
+    } else {
+      throw Sass.new("Invalid number of arguments passed to 'do'")
+    }
+
+    this.#activities.set(name, activityDefinition)
+
+    return this
+  }
+
+  /**
+   * Validates that an activity name has not been reused.
+   *
+   * @private
+   * @param {string | symbol} name Activity identifier.
+   */
+  #dupeActivityCheck(name) {
+    Valid.assert(
+      !this.#activities.has(name),
+      `Activity '${String(name)}' has already been registered.`,
+    )
+  }
+
+  /**
+   * Finalises the builder and returns a payload that can be consumed by the
+   * runner.
+   *
+   * @returns {{action: (context: unknown) => unknown, build: ActionBuilder}} Payload consumed by the {@link ActionRunner} constructor.
+   */
+  build() {
+    const action = this.#action
+
+    if(!action.tag) {
+      action.tag = this.#tag
+
+      action.setup.call(action, this)
+    }
+
+    return new ActionWrapper({
+      activities: this.#activities,
+      debug: this.#debug,
+    })
+  }
+}

package/src/lib/ActionHooks.js

@@ -0,0 +1,192 @@
+import {setTimeout as timeout} from "timers/promises"
+import {FileObject, Sass, Util, Valid} from "@gesslar/toolkit"
+
+/**
+ * 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 {
+  #hooksFile = null
+  #hooks = null
+  #actionKind = null
+  #timeout = 1000 // Default 1 second timeout
+  #debug = null
+
+  /**
+   * Creates a new ActionHook instance.
+   *
+   * @param {object} config - Configuration object
+   * @param {string} config.actionKind - Action identifier
+   * @param {FileObject} config.hooksFile - File object containing hooks with uri property
+   * @param {number} [config.hookTimeout] - Hook execution timeout in milliseconds
+   * @param {unknown} [config.hooks] - The hooks object
+   * @param {(message: string, level?: number, ...args: Array<unknown>) => void} config.debug - Debug function from Glog.
+   */
+  constructor({actionKind, hooksFile, hooks, hookTimeout = 1000, debug}) {
+    this.#actionKind = actionKind
+    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
+  }
+
+  /**
+   * Gets the hooks file object.
+   *
+   * @returns {FileObject} File object containing hooks
+   */
+  get hooksFile() {
+    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.
+   * Override loadHooks() in subclasses to customize hook loading logic.
+   *
+   * @param {object} config - Same configuration object as constructor
+   * @param {string|object} config.actionKind - Action identifier or instance
+   * @param {FileObject} config.hooksFile - File object containing hooks with uri property
+   * @param {number} [config.timeOut] - Hook execution timeout in milliseconds
+   * @param {(message: string, level?: number, ...args: Array<unknown>) => void} debug - The debug function.
+   * @returns {Promise<ActionHooks|null>} Initialized hook manager or null if no hooks found
+   */
+  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
+
+    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)
+
+      // Attach common properties to hooks
+      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
+    }
+  }
+
+  async callHook(kind, activityName, context) {
+    try {
+      const debug = this.#debug
+      const hooks = this.#hooks
+
+      if(!hooks)
+        return
+
+      const hookName = `${kind}$${activityName}`
+
+      debug("Looking for hook: %o", 4, hookName)
+
+      const hook = hooks[hookName]
+      if(!hook)
+        return
+
+      debug("Triggering hook: %o", 4, hookName)
+      Valid.type(hook, "Function", `Hook "${hookName}" is not a function`)
+
+      const hookFunction = async() => {
+        debug("Hook function starting execution: %o", 4, hookName)
+
+        const duration = (
+          await Util.time(() => hook.call(this.#hooks, context))
+        ).cost
+
+        debug("Hook function completed successfully: %o, after %oms", 4, hookName, duration)
+      }
+
+      const hookTimeout = this.timeout
+      const expireAsync = (async() => {
+        await timeout(hookTimeout)
+        throw Sass.new(`Hook ${hookName} execution exceeded timeout of ${hookTimeout}ms`)
+      })()
+
+      try {
+        debug("Starting Promise race for hook: %o", 4, hookName)
+        await Util.race([
+          hookFunction(),
+          expireAsync
+        ])
+      } catch(error) {
+        throw Sass.new(`Processing hook ${kind}$${activityName}`, error)
+      }
+
+      debug("We made it throoough the wildernessss", 4)
+
+    } catch(error) {
+      throw Sass.new(`Processing hook ${kind}$${activityName}`, error)
+    }
+  }
+}

package/src/lib/ActionRunner.js

@@ -0,0 +1,166 @@
+import {FileObject, Sass, Valid} from "@gesslar/toolkit"
+
+import ActionBuilder from "./ActionBuilder.js"
+import {ACTIVITY} from "./Activity.js"
+import Piper from "./Piper.js"
+/**
+ * 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 {
+  #actionWrapper = null
+  #debug = null
+  #hooksPath = null
+  #hooksClassName = null
+  #hooks = null
+  #tag = null
+
+  constructor(wrappedAction, {hooks,debug=(() => {})} = {}) {
+    super({debug})
+
+    this.#tag = Symbol(performance.now())
+
+    this.#debug = debug
+
+    if(!wrappedAction)
+      return this
+
+    if(wrappedAction?.constructor?.name !== "ActionWrapper")
+      throw Sass.new("ActionRunner takes an instance of an ActionWrapper")
+
+    this.#actionWrapper = wrappedAction
+
+    if(hooks)
+      this.#hooks = hooks
+    else
+      this.addSetup(this.#loadHooks)
+
+    this.addStep(this.run)
+  }
+
+  /**
+   * Executes the configured action pipeline.
+   *
+   * @param {unknown} context - Seed value passed to the first activity.
+   * @param {boolean} asIs - When true, do not wrap context in {value} (internal nested runners)
+   * @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.
+   */
+  async run(context, asIs=false) {
+    this.#debug(this.#tag.description)
+    const actionWrapper = this.#actionWrapper
+    const activities = actionWrapper.activities
+
+    if(!asIs)
+      context = {value: context}
+
+    context
+
+    for(const activity of activities) {
+      activity.setActionHooks(this.#hooks)
+
+      const kind = activity.kind
+
+      // If we have no kind, then it's just a once.
+      // Get it over and done with!
+      if(!kind) {
+        context = await this.#executeActivity(activity, context)
+      } else {
+        const {WHILE,UNTIL} = ACTIVITY
+
+        const pred = activity.pred
+        const kindWhile = kind & WHILE
+        const kindUntil = kind & UNTIL
+
+        if(kindWhile && kindUntil)
+          throw Sass.new(
+            "For Kathy Griffin's sake! You can't do something while AND " +
+            "until. Pick one!"
+          )
+
+        if(kindWhile || kindUntil) {
+          for(;;) {
+
+            if(kindWhile)
+              if(!await this.#predicateCheck(activity,pred,context))
+                break
+
+            context = await this.#executeActivity(activity,context)
+            context
+
+            if(kindUntil)
+              if(!await this.#predicateCheck(activity,pred,context))
+                break
+          }
+        } else {
+          context = await this.#executeActivity(activity, context)
+          context
+        }
+      }
+
+    }
+
+    return context
+  }
+
+  async #executeActivity(activity, context) {
+    // What kind of op are we looking at? Is it a function?
+    // Or a class instance of type ActionWrapper?
+    const opKind = activity.opKind
+    if(opKind === "ActionWrapper") {
+      const runner = new this.constructor(activity.op, {
+        debug: this.#debug,
+        hooks: this.#hooks,
+      })
+        .setHooks(this.#hooksPath, this.#hooksClassName)
+
+      return await runner.run(context, true)
+    } else if(opKind === "Function") {
+      return (await activity.run(context)).activityResult
+    }
+
+    throw Sass.new("We buy Functions and ActionWrappers. Only. Not whatever that was.")
+  }
+
+  async #predicateCheck(activity,predicate,context) {
+    Valid.type(predicate, "Function")
+
+    return !!(await predicate.call(activity.action, context))
+  }
+
+  toString() {
+    return `[object ${this.constructor.name}]`
+  }
+
+  setHooks(hooksPath, className) {
+    this.#hooksPath = hooksPath
+    this.#hooksClassName = className
+
+    this.addSetup(() => this.#loadHooks())
+
+    return this
+  }
+
+  async #loadHooks() {
+    if(!this.#hooksPath)
+      return null
+
+    const file = new FileObject(this.#hooksPath)
+    if(!await file.exists)
+      throw Sass.new(`File '${file.uri} does not exist.`)
+
+    const module = await file.import()
+    const hooksClassName = this.#hooksClassName
+
+    Valid.type(module[hooksClassName], "Function")
+
+    const loaded = new module[hooksClassName]({
+      debug: this.#debug
+    })
+
+    this.#hooks = loaded
+  }
+}

package/src/lib/ActionWrapper.js

@@ -0,0 +1,28 @@
+import Activity from "./Activity.js"
+
+export default class ActionWrapper {
+  #activities = new Map()
+  #debug = null
+
+  constructor({activities,debug}) {
+    this.#debug = debug
+    this.#activities = activities
+    this.#debug(
+      "Instantiating ActionWrapper with %o activities.",
+      2,
+      activities.size,
+    )
+  }
+
+  *#_activities() {
+    for(const [_,activity] of this.#activities) {
+      const result = new Activity(activity)
+
+      yield result
+    }
+  }
+
+  get activities() {
+    return this.#_activities()
+  }
+}

package/src/lib/Activity.js

@@ -0,0 +1,126 @@
+import {Data} from "@gesslar/toolkit"
+
+/**
+ * Activity bit flags recognised by the builder. The flag decides
+ * loop semantics for an activity.
+ *
+ * @readonly
+ * @enum {number}
+ */
+export const ACTIVITY = Object.freeze({
+  WHILE: 1<<1,
+  UNTIL: 1<<2,
+})
+
+export default class Activity {
+  #action = null
+  #name = null
+  #op = null
+  #kind = null
+  #pred = null
+  #hooks = null
+
+  /**
+   * Construct an Activity definition wrapper.
+   *
+   * @param {{action: unknown, name: string, op: (context: unknown) => unknown|Promise<unknown>|unknown, kind?: number, pred?: (context: unknown) => boolean|Promise<boolean>}} init - Initial properties describing the activity operation, loop semantics, and predicate
+   */
+  constructor({action,name,op,kind,pred}) {
+    this.#name = name
+    this.#op = op
+    this.#kind = kind
+    this.#action = action
+    this.#pred = pred
+  }
+
+  /**
+   * The activity name.
+   *
+   * @returns {string} - Activity identifier
+   */
+  get name() {
+    return this.#name
+  }
+
+  /**
+   * Bitflag kind for loop semantics.
+   *
+   * @returns {number|null} - Combined flags (e.g., WHILE or UNTIL)
+   */
+  get kind() {
+    return this.#kind
+  }
+
+  /**
+   * The predicate function for WHILE/UNTIL flows.
+   *
+   * @returns {(context: unknown) => boolean|Promise<boolean>|undefined} - Predicate used to continue/stop loops
+   */
+  get pred() {
+    return this.#pred
+  }
+
+  /**
+   * The operator kind name (Function or ActionWrapper).
+   *
+   * @returns {string} - Kind name extracted via Data.typeOf
+   */
+  get opKind() {
+    return Data.typeOf(this.#op)
+  }
+
+  /**
+   * The operator to execute (function or nested wrapper).
+   *
+   * @returns {unknown} - Activity operation
+   */
+  get op() {
+    return this.#op
+  }
+
+  /**
+   * The action instance this activity belongs to.
+   *
+   * @returns {unknown} - Bound action instance
+   */
+  get action() {
+    return this.#action
+  }
+
+  /**
+   * Execute the activity with before/after hooks.
+   *
+   * @param {unknown} context - Mutable context flowing through the pipeline
+   * @returns {Promise<{activityResult: unknown}>} - Activity result wrapper with new context
+   */
+  async run(context) {
+    const hooks = this.#hooks
+
+    // before hook
+    const before = hooks?.[`before$${this.#name}`]
+    if(Data.typeOf(before) === "Function")
+      await before.call(hooks,context)
+
+    const result = await this.#op.call(this.#action,context)
+
+    // after hook
+    const after = hooks?.[`after$${this.#name}`]
+    if(Data.typeOf(after) === "Function")
+      await after.call(hooks,context)
+
+    return {activityResult: result}
+  }
+
+  /**
+   * Attach hooks to this activity instance.
+   *
+   * @param {unknown} hooks - Hooks instance with optional before$/after$ methods
+   * @returns {this} - This activity for chaining
+   */
+  setActionHooks(hooks) {
+    if(hooks)
+      this.#hooks = hooks
+
+    return this
+  }
+}

package/src/lib/Piper.js

@@ -0,0 +1,174 @@
+/**
+ * Generic Pipeline - Process items through a series of steps with concurrency control
+ *
+ * This abstraction handles:
+ * - Concurrent processing with configurable limits
+ * - Pipeline of processing steps
+ * - Result categorization (success/warning/error)
+ * - Setup/cleanup lifecycle hooks
+ * - Error handling and reporting
+ */
+
+import {Sass, Tantrum, Util} from "@gesslar/toolkit"
+
+export default class Piper {
+  #debug
+
+  #lifeCycle = new Map([
+    ["setup", new Set()],
+    ["process", new Set()],
+    ["teardown", new Set()]
+  ])
+
+  /**
+   * Create a Piper instance.
+   *
+   * @param {{debug?: (message: string, level?: number, ...args: Array<unknown>) => void}} [config] Optional configuration with debug function
+   */
+  constructor({debug = (() => {})} = {}) {
+    this.#debug = debug
+  }
+
+  /**
+   * 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
+   * @returns {Piper} The pipeline instance (for chaining)
+   */
+  addStep(fn, options = {}, newThis) {
+    this.#lifeCycle.get("process").add({
+      fn: fn.bind(newThis ?? this),
+      name: options.name || `Step ${this.#lifeCycle.get("process").size + 1}`,
+      required: !!options.required, // Default to required
+      ...options
+    })
+
+    return this
+  }
+
+  /**
+   * Add setup hook that runs before processing starts.
+   *
+   * @param {() => Promise<void>|void} fn - Setup function executed before processing
+   * @param {unknown} [thisArg] - Optional this binding for the setup function
+   * @returns {Piper} - The pipeline instance
+   */
+  addSetup(fn, thisArg) {
+    this.#lifeCycle.get("setup").add(fn.bind(thisArg ?? this))
+
+    return this
+  }
+
+  /**
+   * Add cleanup hook that runs after processing completes
+   *
+   * @param {() => Promise<void>|void} fn - Cleanup function executed after processing
+   * @param {unknown} [thisArg] - Optional this binding for the cleanup function
+   * @returns {Piper} - The pipeline instance
+   */
+  addCleanup(fn, thisArg) {
+    this.#lifeCycle.get("teardown").add(fn.bind(thisArg ?? this))
+
+    return this
+  }
+
+  /**
+   * Process items through the pipeline with concurrency control
+   *
+   * @param {Array<unknown>|unknown} items - Items to process
+   * @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]
+
+    let itemIndex = 0
+    const allResults = []
+
+    const processWorker = async() => {
+      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)
+        }
+      }
+    }
+
+    const setupResult = await Util.settleAll(
+      [...this.#lifeCycle.get("setup")
+
+      ].map(e => e()))
+    this.#processResult("Setting up the pipeline.", setupResult)
+
+    // Start workers up to maxConcurrent limit
+    const workers = []
+    const workerCount = Math.min(maxConcurrent, items.length)
+
+    for(let i = 0; i < workerCount; i++)
+      workers.push(processWorker())
+
+    // Wait for all workers to complete
+    const processResult = await Util.settleAll(workers)
+    this.#processResult("Processing pipeline.", processResult)
+
+    // Run cleanup hooks
+    const teardownResult = await Util.settleAll(
+      [...this.#lifeCycle.get("teardown")
+
+      ].map(e => e()))
+    this.#processResult("Tearing down the pipeline.", teardownResult)
+
+    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
+   */
+  #processResult(message, settled) {
+    if(settled.some(r => r.status === "rejected"))
+      throw Tantrum.new(
+        message,
+        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) {
+    try {
+      // Execute each step in sequence
+      let result = item
+
+      for(const step of this.#lifeCycle.get("process")) {
+        if(typeof this.#debug === "function")
+          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)
+    }
+  }
+}

package/src/types/ActionBuilder.d.ts

@@ -0,0 +1,32 @@
+import type ActionWrapper from './ActionWrapper'
+
+declare type DebugFn = (message: string, level?: number, ...args: Array<unknown>) => void
+import type { ActionFunction } from './ActionWrapper'
+
+declare class ActionBuilder {
+  /**
+   * @param action An object with a `setup(builder)` method or undefined for an empty builder
+   */
+  constructor(
+    action?: { setup?: (builder: ActionBuilder) => void } | unknown,
+    config?: { tag?: symbol, debug?: DebugFn }
+  )
+
+  // Overload: once-off activity
+  do(name: string | symbol, op: ActionFunction): this
+
+  // Overload: controlled activity with kind, predicate and op (function or nested ActionWrapper)
+  do(
+    name: string | symbol,
+    kind: number,
+    pred: (context: unknown) => Promise<boolean>,
+    op: ActionFunction | ActionWrapper
+  ): this
+
+  // Generic fallback
+  do(name: string | symbol, ...args: Array<unknown>): this
+
+  build(): ActionWrapper
+}
+
+export default ActionBuilder

package/src/types/ActionHooks.d.ts

@@ -0,0 +1,24 @@
+declare type DebugFn = (message: string, level?: number, ...args: Array<unknown>) => void
+
+declare class ActionHooks {
+  constructor(config: {
+    actionKind: unknown,
+    hooksFile: unknown,
+    hooks?: unknown,
+    hookTimeout?: number,
+    debug?: DebugFn
+  })
+  static new(
+    config: { actionKind: unknown, hooksFile: unknown, timeOut?: number },
+    debug?: DebugFn
+  ): Promise<ActionHooks | null>
+  callHook(kind: string, activityName: string, context: unknown): Promise<void>
+  get actionKind(): unknown
+  get hooksFile(): unknown
+  get hooks(): unknown | null
+  get timeout(): number
+  get setup(): ((args: object) => unknown) | null
+  get cleanup(): ((args: object) => unknown) | null
+}
+
+export default ActionHooks

package/src/types/ActionRunner.d.ts

@@ -0,0 +1,18 @@
+import Piper from './Piper'
+
+declare type DebugFn = (message: string, level?: number, ...args: Array<unknown>) => void
+
+declare class ActionRunner extends Piper {
+  constructor(wrappedAction?: unknown, config?: { hooks?: unknown, debug?: DebugFn })
+
+  /**
+   * Execute the pipeline. When asIs is true, the context is not wrapped in {value}.
+   */
+  run(context: unknown, asIs?: boolean): Promise<unknown>
+
+  setHooks(hooksPath: string, className: string): this
+
+  toString(): string
+}
+
+export default ActionRunner

package/src/types/ActionWrapper.d.ts

@@ -0,0 +1,27 @@
+import type Activity from './Activity'
+
+/** Operation function signature used by activities */
+export type ActionFunction = (context: unknown) => unknown | Promise<unknown>
+
+import type { ActionFunction as _AF } from './ActionBuilder'
+
+declare type DebugFn = (message: string, level?: number, ...args: Array<unknown>) => void
+
+declare class ActionWrapper {
+  constructor(config: {
+    activities: Map<unknown, {
+      name: string,
+      /** operation: either a function(context) or a nested ActionWrapper */
+      op: ActionFunction | ActionWrapper,
+      kind?: number,
+      /** predicate used for WHILE/UNTIL, returns Promise<boolean> */
+      pred?: (context: unknown) => Promise<boolean>,
+      action?: unknown,
+      debug?: DebugFn
+    }>,
+    debug?: DebugFn
+  })
+  get activities(): IterableIterator<Activity>
+}
+
+export default ActionWrapper

package/src/types/Activity.d.ts

@@ -0,0 +1,21 @@
+export const ACTIVITY: { WHILE: number; UNTIL: number }
+
+declare class Activity {
+  constructor(init: {
+    action: unknown,
+    name: string,
+    op: (context: unknown) => unknown | Promise<unknown> | unknown,
+    kind?: number,
+    pred?: (context: unknown) => Promise<boolean>
+  })
+  get name(): string
+  get kind(): number | null
+  get pred(): ((context: unknown) => boolean | Promise<boolean>) | undefined
+  get opKind(): string
+  get op(): unknown
+  get action(): unknown
+  run(context: unknown): Promise<{ activityResult: unknown }>
+  setActionHooks(hooks: unknown): this
+}
+
+export default Activity

package/src/types/Piper.d.ts

@@ -0,0 +1,15 @@
+declare type DebugFn = (message: string, level?: number, ...args: Array<unknown>) => void
+
+declare class Piper {
+  constructor(config?: { debug?: DebugFn })
+  addStep(
+    fn: (context: unknown) => Promise<unknown> | unknown,
+    options?: { name?: string, required?: boolean },
+    newThis?: unknown
+  ): this
+  addSetup(fn: () => Promise<void> | void, thisArg?: unknown): this
+  addCleanup(fn: () => Promise<void> | void, thisArg?: unknown): this
+  pipe(items: Array<unknown> | unknown, maxConcurrent?: number): Promise<Array<unknown>>
+}
+
+export default Piper

package/src/types/index.d.ts

@@ -0,0 +1,6 @@
+export {default as ActionBuilder} from './ActionBuilder'
+export {default as ActionHooks} from './ActionHooks'
+export {default as ActionRunner} from './ActionRunner'
+export {default as ActionWrapper} from './ActionWrapper'
+export {default as Activity, ACTIVITY} from './Activity'
+export {default as Piper} from './Piper'