Skip to main content

ActBuilder

@rotorsoft/act-root

@rotorsoft/act-root / act/src / ActBuilder

Type Alias: ActBuilder<TSchemaReg, TEvents, TActions, TStateMap, TActor, TLanes>

ActBuilder<TSchemaReg, TEvents, TActions, TStateMap, TActor, TLanes> = object

Defined in: libs/act/src/builders/act-builder.ts:107

Fluent builder interface for composing event-sourced applications.

Provides a chainable API for:

  • Registering states via .withState()
  • Registering slices via .withSlice()
  • Registering projections via .withProjection()
  • Locking a custom actor type via .withActor<TActor>()
  • Declaring drain lanes via .withLane({name, ...}) (ACT-1103)
  • Defining event reactions via .on() → .do() → .to()
  • Building the orchestrator via .build()

See​

  • act for usage examples
  • Act for the built orchestrator API

Type Parameters​

TSchemaReg​

TSchemaReg extends SchemaRegister<TActions>

Schema register for states (maps action names to state schemas)

TEvents​

TEvents extends Schemas

Event schemas (maps event names to event data schemas)

TActions​

TActions extends Schemas

Action schemas (maps action names to action payload schemas)

TStateMap​

TStateMap extends Record<string, Schema> = { }

Map of state names to state schemas

TActor​

TActor extends Actor = Actor

Actor type extending base Actor

TLanes​

TLanes extends string = typeof DEFAULT_LANE

Union of declared lane names (ACT-1103). Narrowed by .withLane({name}) calls so .to({lane}) and ActOptions.onlyLanes reject typos at compile time. Starts at "default".

Properties​

build​

build: (options?) => Act<TSchemaReg, TEvents, TActions, TStateMap, TActor>

Defined in: libs/act/src/builders/act-builder.ts:286

Builds and returns the Act orchestrator instance.

Parameters​

options?​

ActOptions<TLanes>

Optional runtime overrides (see ActOptions). options.onlyLanes is narrowed to the declared TLanes union, so onlyLanes: ["typo"] is a compile error when the lane wasn't declared via .withLane(...).

Returns​

Act<TSchemaReg, TEvents, TActions, TStateMap, TActor>

The Act orchestrator instance

See​

Act for available orchestrator methods

events​

readonly events: EventRegister<TEvents>

Defined in: libs/act/src/builders/act-builder.ts:292

The registered event schemas and their reaction maps.

on​

on: <TKey>(event) => object

Defined in: libs/act/src/builders/act-builder.ts:252

Begins defining a reaction to a specific event.

Reactions are event handlers that respond to state changes. They can trigger additional actions, update external systems, or perform side effects. Reactions are processed asynchronously during drain cycles.

Type Parameters​

TKey​

TKey extends keyof TEvents

Event name (must be a registered event)

Parameters​

event​

TKey

The event name to react to

Returns​

object

An object with .do() method to define the reaction handler

do​

do: (handler, options?) => ActBuilder<TSchemaReg, TEvents, TActions, TStateMap, TActor, TLanes> & object

Parameters​
handler​

(event, stream, app) => Promise<Snapshot<Schema, TEvents> | void>

options?​

Partial<ReactionOptions>

Returns​

ActBuilder<TSchemaReg, TEvents, TActions, TStateMap, TActor, TLanes> & object

withActor​

withActor: <TNewActor>() => ActBuilder<TSchemaReg, TEvents, TActions, TStateMap, TNewActor, TLanes>

Defined in: libs/act/src/builders/act-builder.ts:208

Locks a custom actor type for this application.

This is a pure type-level method — it returns the same builder at runtime but narrows the TActor generic so that app.do() and reaction dispatchers require the richer actor shape.

Type Parameters​

TNewActor​

TNewActor extends Actor

Custom actor type extending base Actor

Returns​

ActBuilder<TSchemaReg, TEvents, TActions, TStateMap, TNewActor, TLanes>

The same builder with TActor locked to TNewActor

Example​

type MyActor = { id: string; name: string; role: string; tenantId: string };

const app = act()
  .withActor<MyActor>()
  .withState(Counter)
  .build();

// Now app.do() requires MyActor in the target
await app.do("increment", {
  stream: "counter-1",
  actor: { id: "1", name: "Alice", role: "admin", tenantId: "t1" }
}, { by: 5 });

withLane​

withLane: <TConfig>(config) => ActBuilder<TSchemaReg, TEvents, TActions, TStateMap, TActor, TLanes | TConfig["name"]>

Defined in: libs/act/src/builders/act-builder.ts:231

Declares a drain lane (ACT-1103). Lane name narrows TLanes so .to({lane}) and ActOptions.onlyLanes type-check against it.

Type Parameters​

TConfig​

TConfig extends LaneConfig

Parameters​

config​

TConfig

Returns​

ActBuilder<TSchemaReg, TEvents, TActions, TStateMap, TActor, TLanes | TConfig["name"]>

Example​

const app = act()
  .withState(Counter)
  .withLane({ name: "slow", leaseMillis: 60_000, streamLimit: 5 })
  .on("OrderConfirmed")
    .do(deliverWebhook)
    .to({ target: "webhooks-out", lane: "slow" })
  .build();

withProjection​

withProjection: <TNewEvents>(projection) => ActBuilder<TSchemaReg, TEvents, TActions, TStateMap, TActor, TLanes>

Defined in: libs/act/src/builders/act-builder.ts:177

Registers a standalone projection with the builder.

The projection's events must be a subset of events already registered via .withState() or .withSlice().

Type Parameters​

TNewEvents​

TNewEvents extends Schemas

Parameters​

projection​

[Exclude<keyof TNewEvents, keyof TEvents>] extends [never] ? Projection<TNewEvents> : never

Returns​

ActBuilder<TSchemaReg, TEvents, TActions, TStateMap, TActor, TLanes>

withSlice​

withSlice: <TNewSchemaReg, TNewEvents, TNewActions, TNewMap, TNewLanes>(slice) => ActBuilder<TSchemaReg & TNewSchemaReg, TEvents & TNewEvents, TActions & TNewActions, TStateMap & TNewMap, TActor, TLanes | TNewLanes>

Defined in: libs/act/src/builders/act-builder.ts:148

Registers a slice with the builder.

Merges all the slice's states and reactions into the application. State names, action names, and event names must be unique across the application (partial states with the same name are merged automatically).

Type Parameters​

TNewSchemaReg​

TNewSchemaReg extends SchemaRegister<TNewActions>

TNewEvents​

TNewEvents extends Schemas

TNewActions​

TNewActions extends Schemas

TNewMap​

TNewMap extends Record<string, Schema>

TNewLanes​

TNewLanes extends string

Parameters​

slice​

Slice<TNewSchemaReg, TNewEvents, TNewActions, TNewMap, Actor, TNewLanes>

Returns​

ActBuilder<TSchemaReg & TNewSchemaReg, TEvents & TNewEvents, TActions & TNewActions, TStateMap & TNewMap, TActor, TLanes | TNewLanes>

Throws​

If duplicate action or event names are detected

withState​

withState: <TNewState, TNewEvents, TNewActions, TNewName>(state) => ActBuilder<TSchemaReg & { [K in keyof TNewActions]: TNewState }, TEvents & TNewEvents, TActions & TNewActions, TStateMap & { [K in TNewName]: TNewState }, TActor, TLanes>

Defined in: libs/act/src/builders/act-builder.ts:124

Registers a state definition with the builder.

State names, action names, and event names must be unique across the application (partial states with the same name are merged automatically).

Type Parameters​

TNewState​

TNewState extends Schema

TNewEvents​

TNewEvents extends Schemas

TNewActions​

TNewActions extends Schemas

TNewName​

TNewName extends string = string

Parameters​

state​

State<TNewState, TNewEvents, TNewActions, TNewName>

Returns​

ActBuilder<TSchemaReg & { [K in keyof TNewActions]: TNewState }, TEvents & TNewEvents, TActions & TNewActions, TStateMap & { [K in TNewName]: TNewState }, TActor, TLanes>

Throws​

If duplicate action or event names are detected