Actioneer

Actioneer is a small, focused action orchestration library for Node.js and browser environments. 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+ and modern browsers.

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.

Included Classes

Browser

These classes work in browsers, Node.js, and browser-like environments such as Tauri, Electron, and Deno.

Name	Description
ActionBuilder	Fluent builder for composing activities into pipelines
ActionHooks	Lifecycle hook management (requires pre-instantiated hooks in browser)
ActionRunner	Concurrent pipeline executor with configurable concurrency
ActionWrapper	Activity container and iterator
Activity	Activity definitions with WHILE, UNTIL, and SPLIT modes
Piper	Base concurrent processing with worker pools

Node.js

Includes all browser functionality plus Node.js-specific features for file-based hook loading.

Name	Description
ActionHooks	Enhanced version with file-based hook loading via `withHooksFile()`

Installation

npm install @gesslar/actioneer

Usage

Actioneer is environment-aware and automatically detects whether it is being used in a browser or Node.js. You can optionally specify the node or browser variant explicitly.

Browser

jsDelivr (runtime only)

https://cdn.jsdelivr.net/npm/@gesslar/actioneer

esm.sh (runtime with types)

https://esm.sh/@gesslar/actioneer
https://esm.sh/@gesslar/actioneer?dts  (serves .d.ts for editors)

Browser Import Example

import {ActionBuilder, ActionRunner} from "https://esm.sh/@gesslar/actioneer"

class MyAction {
  setup(builder) {
    builder
      .do("step1", ctx => { ctx.result = ctx.input * 2 })
      .do("step2", ctx => { return ctx.result })
  }
}

const builder = new ActionBuilder(new MyAction())
const runner = new ActionRunner(builder)
const results = await runner.run({input: 5})
console.log(results) // 10

Node.js

Auto-detected (recommended)

import {ActionBuilder, ActionRunner} from "@gesslar/actioneer"

Explicit variants

// Explicitly use Node.js version (with file-based hooks)
import {ActionBuilder, ActionRunner, ActionHooks} from "@gesslar/actioneer/node"

// Explicitly use browser version
import {ActionBuilder, ActionRunner} from "@gesslar/actioneer/browser"

Note: The browser version is fully functional in Node.js but lacks file-based hook loading. Use withHooks() with pre-instantiated hooks instead of withHooksFile().

Quick Start

Import the builder and runner, define an action and run it:

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 builder = new ActionBuilder(new MyAction())
const runner = new ActionRunner(builder)
const results = await runner.pipe([{}], 4) // run up to 4 contexts concurrently

// pipe() returns settled results: {status: "fulfilled", value: ...} or {status: "rejected", reason: ...}
results.forEach(result => {
  if (result.status === "fulfilled") {
    console.log("Count:", result.value)
  } else {
    console.error("Error:", result.reason)
  }
})

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:

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.

Activity Modes

Actioneer supports four distinct execution modes for activities, allowing you to control how operations are executed:

Execute Once (Default)

The simplest mode executes an activity exactly once per context:

class MyAction {
  setup(builder) {
    builder.do("processItem", ctx => {
      ctx.result = ctx.input * 2
    })
  }
}

WHILE Mode

Loops while a predicate returns true. The predicate is evaluated before each iteration:

import { ActionBuilder, ACTIVITY } from "@gesslar/actioneer"

class CounterAction {
  #shouldContinue = (ctx) => ctx.count < 10

  #increment = (ctx) => {
    ctx.count += 1
  }

  setup(builder) {
    builder
      .do("initialize", ctx => { ctx.count = 0 })
      .do("countUp", ACTIVITY.WHILE, this.#shouldContinue, this.#increment)
      .do("finish", ctx => { return ctx.count })
  }
}

The activity will continue executing as long as the predicate returns true. Once it returns false, execution moves to the next activity.

UNTIL Mode

Loops until a predicate returns true. The predicate is evaluated after each iteration:

import { ActionBuilder, ACTIVITY } from "@gesslar/actioneer"

class ProcessorAction {
  #queueIsEmpty = (ctx) => ctx.queue.length === 0

  #processItem = (ctx) => {
    const item = ctx.queue.shift()
    ctx.processed.push(item)
  }

  setup(builder) {
    builder
      .do("initialize", ctx => {
        ctx.queue = [1, 2, 3, 4, 5]
        ctx.processed = []
      })
      .do("process", ACTIVITY.UNTIL, this.#queueIsEmpty, this.#processItem)
      .do("finish", ctx => { return ctx.processed })
  }
}

The activity executes at least once, then continues while the predicate returns false. Once it returns true, execution moves to the next activity.

SPLIT Mode

Executes with a split/rejoin pattern for parallel execution. This mode requires a splitter function to divide the context and a rejoiner function to recombine results:

import { ActionBuilder, ACTIVITY } from "@gesslar/actioneer"

class ParallelProcessor {
  #split = (ctx) => {
    // Split context into multiple items for parallel processing
    return ctx.items.map(item => ({ item, processedBy: "worker" }))
  }

  #rejoin = (originalCtx, splitResults) => {
    // Recombine parallel results back into original context
    originalCtx.results = splitResults.map(r => r.item)
    return originalCtx
  }

  #processItem = (ctx) => {
    ctx.item = ctx.item.toUpperCase()
  }

  setup(builder) {
    builder
      .do("initialize", ctx => {
        ctx.items = ["apple", "banana", "cherry"]
      })
      .do("parallel", ACTIVITY.SPLIT, this.#split, this.#rejoin, this.#processItem)
      .do("finish", ctx => { return ctx.results })
  }
}

How SPLIT Mode Works:

The splitter function receives the context and returns an array of contexts (one per parallel task)
Each split context is processed in parallel through the operation function
The rejoiner function receives the original context and the array of settled results from Promise.allSettled()
The rejoiner combines the results and returns the updated context

Important: SPLIT uses Promise.allSettled()

The SPLIT mode uses Promise.allSettled() internally to execute parallel operations. This means your rejoiner function will receive an array of settlement objects, not the raw context values. Each element in the array will be either:

{ status: "fulfilled", value: <result> } for successful operations
{ status: "rejected", reason: <error> } for failed operations

Your rejoiner must handle settled results accordingly. You can process them however you need - check each status manually, or use helper utilities like those in @gesslar/toolkit:

import { Util } from "@gesslar/toolkit"

#rejoin = (originalCtx, settledResults) => {
  // settledResults is an array of settlement objects
  // Each has either { status: "fulfilled", value: ... }
  // or { status: "rejected", reason: ... }

  // Example: extract only successful results
  originalCtx.results = Util.fulfilledValues(settledResults)

  // Example: check for any failures
  if (Util.anyRejected(settledResults)) {
    originalCtx.errors = Util.rejectedReasons(
      Util.settledAndRejected(settledResults)
    )
  }

  return originalCtx
}

Nested Pipelines with SPLIT:

You can use nested ActionBuilders with SPLIT mode for complex parallel workflows:

class NestedParallel {
  #split = (ctx) => ctx.batches.map(batch => ({ batch }))

  #rejoin = (original, results) => {
    original.processed = results.flatMap(r => r.batch)
    return original
  }

  setup(builder) {
    builder
      .do("parallel", ACTIVITY.SPLIT, this.#split, this.#rejoin,
        new ActionBuilder(this)
          .do("step1", ctx => { /* ... */ })
          .do("step2", ctx => { /* ... */ })
      )
  }
}

Mode Constraints

Only one mode per activity: You cannot combine WHILE, UNTIL, and SPLIT. Attempting to use multiple modes will throw an error: "You can't combine activity kinds. Pick one: WHILE, UNTIL, or SPLIT!"
SPLIT requires both functions: The splitter and rejoiner are both mandatory for SPLIT mode
Predicates must return boolean: For WHILE and UNTIL modes, predicates should return true or false

Mode Summary Table

Mode	Signature	Predicate Timing	Use Case
Default	`.do(name, operation)`	N/A	Execute once per context
WHILE	`.do(name, ACTIVITY.WHILE, predicate, operation)`	Before iteration	Loop while condition is true
UNTIL	`.do(name, ACTIVITY.UNTIL, predicate, operation)`	After iteration	Loop until condition is true
SPLIT	`.do(name, ACTIVITY.SPLIT, splitter, rejoiner, operation)`	N/A	Parallel execution with split/rejoin

Running Actions: `run()` vs `pipe()`

ActionRunner provides two methods for executing your action pipelines:

`run(context)` - Single Context Execution

Executes the pipeline once with a single context. Returns the final context value directly, or throws if an error occurs.

const builder = new ActionBuilder(new MyAction())
const runner = new ActionRunner(builder)

try {
  const result = await runner.run({input: "data"})
  console.log(result) // Final context value
} catch (error) {
  console.error("Pipeline failed:", error)
}

Use run() when:

Processing a single context
You want errors to throw immediately
You prefer traditional try/catch error handling

`pipe(contexts, maxConcurrent)` - Concurrent Batch Execution

Executes the pipeline concurrently across multiple contexts with a configurable concurrency limit. Returns an array of settled results - never throws on individual pipeline failures.

const builder = new ActionBuilder(new MyAction())
const runner = new ActionRunner(builder)

const contexts = [{id: 1}, {id: 2}, {id: 3}]
const results = await runner.pipe(contexts, 4) // Max 4 concurrent

results.forEach((result, i) => {
  if (result.status === "fulfilled") {
    console.log(`Context ${i} succeeded:`, result.value)
  } else {
    console.error(`Context ${i} failed:`, result.reason)
  }
})

Use pipe() when:

Processing multiple contexts in parallel
You want to control concurrency (default: 10)
You need all results (both successes and failures)
Error handling should be at the call site

Important: pipe() returns settled results

The pipe() method uses Promise.allSettled() internally and returns an array of settlement objects:

{status: "fulfilled", value: <result>} for successful executions
{status: "rejected", reason: <error>} for failed executions

This design ensures error handling responsibility stays at the call site - you decide how to handle failures rather than the framework deciding for you.

ActionHooks

Actioneer supports lifecycle hooks that can execute before and after each activity in your pipeline. Hooks can be configured by file path (Node.js only) or by providing a pre-instantiated hooks object (Node.js and browser).

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

Browser: Pre-instantiated Hooks

In browser environments, you must provide pre-instantiated hooks objects:

import {ActionBuilder, ActionRunner} from "@gesslar/actioneer"

class MyActionHooks {
  constructor({debug}) {
    this.debug = debug
  }

  async before$prepare(context) {
    this.debug("About to prepare", context)
  }

  async after$prepare(context) {
    this.debug("Finished preparing", context)
  }
}

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)

Node.js: File-based or Pre-instantiated

Option 1: Load hooks from a file (Node.js only)

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)

Option 2: Provide a pre-instantiated hooks object (Node.js and browser)

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.

// 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:

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.

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 comprehensive test suite with Node's built-in test runner:

npm test

The test suite includes 150+ tests covering all core classes and behaviors:

Activity - Activity definitions, ACTIVITY flags (WHILE, UNTIL, SPLIT), and execution
ActionBuilder - Fluent builder API, activity registration, and hooks configuration
ActionWrapper - Activity iteration and integration with ActionBuilder
ActionRunner - Pipeline execution, loop semantics, nested builders, and error handling
ActionHooks - Hook lifecycle, loading from files, and timeout handling
Piper - Concurrent processing, worker pools, and lifecycle hooks

Tests are organized in tests/unit/ with one file per class. All tests use Node's native test runner and assertion library.

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!

🤗

Name		Name	Last commit message	Last commit date
Latest commit History 143 Commits
.github		.github
src		src
tests		tests
.gitignore		.gitignore
.npmignore		.npmignore
README.md		README.md
UNLICENSE.txt		UNLICENSE.txt
WIRE_UP_AND_TESTING.md		WIRE_UP_AND_TESTING.md
eslint.config.js		eslint.config.js
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
tsconfig.types.json		tsconfig.types.json

License

gesslar/Actioneer

Folders and files

Latest commit

History

Repository files navigation

Actioneer

Included Classes

Browser

Node.js

Installation

Usage

Browser

jsDelivr (runtime only)

esm.sh (runtime with types)

Browser Import Example

Node.js

Auto-detected (recommended)

Explicit variants

Quick Start

Types (TypeScript / VS Code)

Activity Modes

Execute Once (Default)

WHILE Mode

UNTIL Mode

SPLIT Mode

Mode Constraints

Mode Summary Table

Running Actions: run() vs pipe()

run(context) - Single Context Execution

pipe(contexts, maxConcurrent) - Concurrent Batch Execution

ActionHooks

Hook System Overview

Configuring Hooks

Browser: Pre-instantiated Hooks

Node.js: File-based or Pre-instantiated

Writing Hooks

Hook Naming Convention

Hook Timeout

Nested Pipelines and Hooks

Optional TypeScript (local, opt-in)

Testing

Publishing

Contributing

License

Most Portum

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 10

Packages 0

Uh oh!

Contributors 5

Uh oh!

Languages

Running Actions: `run()` vs `pipe()`

`run(context)` - Single Context Execution

`pipe(contexts, maxConcurrent)` - Concurrent Batch Execution

Packages