ActBuilder

@rotorsoft/act-root

---

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

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

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

Defined in: libs/act/src/act-builder.ts:48

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>()
• Defining event reactions via .on() → .do() → .to() or .void()
• 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

Properties

build()

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

Defined in: libs/act/src/act-builder.ts:181

Builds and returns the Act orchestrator instance.

Parameters

drainLimit?

number

Deprecated parameter, no longer used

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/act-builder.ts:187

The registered event schemas and their reaction maps.

---

on()

on: <TKey>(event) => object

Defined in: libs/act/src/act-builder.ts:156

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> & object

Parameters

handler

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

options?

Partial<ReactionOptions>

Returns

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

---

withActor()

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

Defined in: libs/act/src/act-builder.ts:138

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>

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 });

---

withProjection()

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

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

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>

---

withSlice()

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

Defined in: libs/act/src/act-builder.ts:87

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>

Parameters

slice

Slice<TNewSchemaReg, TNewEvents, TNewActions, TNewMap>

Returns

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

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>

Defined in: libs/act/src/act-builder.ts:64

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>

Throws

If duplicate action or event names are detected