Skip to main content
Version: Current

ActBuilder

@rotorsoft/act-root

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

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

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

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

Extends​

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

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

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/builder-base.ts:117

The registered event schemas and their reaction maps.

Inherited from​

BuilderBase.events

on​

on: <TKey>(event) => ReactionOn<ActBuilder<TSchemaReg, TEvents, TActions, TStateMap, TActor, TLanes>, TEvents, TActions, TActor, TLanes, TKey>

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

Begins defining a reaction. Chain .do(...) to run immediately, or .defer(when).do(...) to hold the reaction until a schedule is due (#1091). .to(...) follows .do(...) in both cases and, for a deferred reaction, routes it onto its own target so the hold doesn't stall the stream's other reactions.

Type Parameters​

TKey​

TKey extends string | number | symbol

Parameters​

event​

TKey

Returns​

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

Inherited from​

BuilderBase.on

withActor​

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

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

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 Readonly<{[key: string]: unknown; id: string; name: string; }>

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

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

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

Registers a standalone projection. Its events must be a subset of events already registered via .withState() (or .withSlice() on the Act builder); handlers keep their (event, stream) signature.

Type Parameters​

TNewEvents​

TNewEvents extends Schemas

Parameters​

projection​

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

Returns​

ActBuilder

Inherited from​

BuilderBase.withProjection

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

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, Readonly<{[key: string]: unknown; id: string; name: string; }>, 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 string | number | symbol]: TNewState }, TEvents & TNewEvents, TActions & TNewActions, TStateMap & { [K in string]: TNewState }, TActor, TLanes>

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

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 string | number | symbol]: TNewState }, TEvents & TNewEvents, TActions & TNewActions, TStateMap & { [K in string]: TNewState }, TActor, TLanes>

Throws​

If duplicate action or event names are detected