ActionBuilder

ActionBuilder is the fluent API for composing a pipeline. You add activities with .do(), configure hooks, and register a done() finalizer, then hand the builder to an ActionRunner.

import {ActionBuilder} from "@gesslar/actioneer"

Constructor

new ActionBuilder(action?, config?)

Parameter	Type	Description
action	object (optional)	An action instance with a setup(builder) method. If provided, its setup(builder) runs when the pipeline is built — lazily, on the first run()/pipe() — to populate the pipeline.
config	object (optional)	Options: {tag?, debug?}.

// With an action
const builder = new ActionBuilder(new MyAction())

// Empty — add activities directly (common for nested builders)
const nested = new ActionBuilder()

Caution

An action can only be consumed by one builder. Reusing an action instance throws "Action has already been consumed by a builder and cannot be reused." setup must be a function.

do(name, ...args)

Appends an activity to the pipeline. The arguments after name determine the mode. Returns the builder for chaining.

Overload	Mode
.do(name, operation)	Default — run once
.do(name, ACTIVITY.WHILE, predicate, operation)	WHILE
.do(name, ACTIVITY.UNTIL, predicate, operation)	UNTIL
.do(name, ACTIVITY.IF, predicate, operation)	IF
.do(name, ACTIVITY.BREAK, predicate)	BREAK
.do(name, ACTIVITY.CONTINUE, predicate)	CONTINUE
.do(name, ACTIVITY.SPLIT, splitter, rejoiner, operation)	SPLIT

The operation may be a function (context) => unknown or a nested ActionBuilder.

Names must be unique

Each activity name must be unique within a builder. Reusing a name throws "Activity '<name>' has already been registered." Names are also used to wire up hooks.

withHooks(hooks)

Configures the pipeline with a pre-instantiated hooks object. Works in both Node.js and the browser. Returns the builder.

builder.withHooks(new MyActionHooks({debug: console.log}))

Calling withHooks() with the same instance again is idempotent. Configuring hooks more than once with a different source throws "Hooks have already been configured."

withHooksFile(hooksFile, hooksKind)

Node.js only. Loads hooks from a module file when the action is built. Returns the builder.

Parameter	Type	Description
hooksFile	string	Path to the hooks module file.
hooksKind	string	Name of the exported hooks class to instantiate.

builder.withHooksFile("./hooks/MyActionHooks.js", "MyActionHooks")

See Lifecycle Hooks for the hook authoring conventions.

withAction(action)

Sets the action instance if not already set, propagating it to any existing activity definitions that lack one. Primarily used to pass parent action context to nested builders. Returns the builder.

new ActionBuilder().withAction(this)

done(callback)

Registers a finalizer that runs after every activity completes — even on error. Whatever it returns becomes the pipeline’s final result. The callback is bound to the action instance and may be async. Returns the builder.

builder.done(ctx => ({total: ctx.a + ctx.b}))

See Finalizing with done() for behavior details.

Related

• ActionRunner — executes the built pipeline.
• Activity & ACTIVITY — the mode flags.
• Core Concepts — how builders fit into the whole.