Act

@rotorsoft/act-root

---

@rotorsoft/act-root / act/src / Act

Class: Act<S, E, A>

Defined in: libs/act/src/act.ts:46

See

Store

Main orchestrator for event-sourced state machines and workflows.

It manages the lifecycle of actions, reactions, and event streams, providing APIs for loading state, executing actions, querying events, and draining reactions.

Usage

const app = new Act(registry, 100);
await app.do("increment", { stream: "counter1", actor }, { by: 1 });
const snapshot = await app.load(Counter, "counter1");
await app.drain();

• Register event listeners with .on("committed", ...) and .on("drained", ...) to react to lifecycle events.
• Use .query() to analyze event streams for analytics or debugging.

Type Parameters

S

S extends SchemaRegister<A>

SchemaRegister for state

E

E extends Schemas

Schemas for events

A

A extends Schemas

Schemas for actions

Constructors

Constructor

new Act<S, E, A>(registry, drainLimit): Act<S, E, A>

Defined in: libs/act/src/act.ts:100

Create a new Act orchestrator.

Parameters

registry

Registry<S, E, A>

The registry of state, event, and action schemas

drainLimit

number

The maximum number of events to drain per cycle

Returns

Act<S, E, A>

Properties

drainLimit

readonly drainLimit: number

Defined in: libs/act/src/act.ts:102

The maximum number of events to drain per cycle

---

registry

readonly registry: Registry<S, E, A>

Defined in: libs/act/src/act.ts:101

The registry of state, event, and action schemas

Methods

do()

do<K>(action, target, payload, reactingTo?, skipValidation?): Promise<Snapshot<S[K], E>>

Defined in: libs/act/src/act.ts:119

Executes an action (command) against a state machine, emitting and committing the resulting event(s).

Type Parameters

K

K extends string | number | symbol

The type of action to execute

Parameters

action

K

The action name (key of the action schema)

target

Target

The target (stream and actor) for the action

payload

Readonly<A[K]>

The action payload (validated against the schema)

reactingTo?

Committed<E, keyof E>

(Optional) The event this action is reacting to

skipValidation?

boolean = false

(Optional) If true, skips schema validation (not recommended)

Returns

Promise<Snapshot<S[K], E>>

The snapshot of the committed event

Example

await app.do("increment", { stream: "counter1", actor }, { by: 1 });

---

drain()

drain(): Promise<number>

Defined in: libs/act/src/act.ts:239

Drains and processes events from the store, triggering reactions and updating state.

This is typically called in a background loop or after committing new events.

Returns

Promise<number>

The number of events drained and processed

Example

await app.drain();

---

emit()

Call Signature

emit(event, args): boolean

Defined in: libs/act/src/act.ts:60

Emit a lifecycle event (internal use, but can be used for custom listeners).

Parameters

event

"committed"

The event name ("committed" or "drained")

args

SnapshotArgs

The event payload

Returns

boolean

true if the event had listeners, false otherwise

Call Signature

emit(event, args): boolean

Defined in: libs/act/src/act.ts:61

Emit a lifecycle event (internal use, but can be used for custom listeners).

Parameters

event

"drained"

The event name ("committed" or "drained")

args

Lease[]

The event payload

Returns

boolean

true if the event had listeners, false otherwise

---

load()

load<SX, EX, AX>(state, stream, callback?): Promise<Snapshot<SX, EX>>

Defined in: libs/act/src/act.ts:152

Loads the current state snapshot for a given state machine and stream.

Type Parameters

SX

SX extends Schema

The type of state

EX

EX extends Schemas

The type of events

AX

AX extends Schemas

The type of actions

Parameters

state

State<SX, EX, AX>

The state machine definition

stream

string

The stream (instance) to load

callback?

(snapshot) => void

(Optional) Callback to receive the loaded snapshot

Returns

Promise<Snapshot<SX, EX>>

The snapshot of the loaded state

Example

const snapshot = await app.load(Counter, "counter1");

---

off()

Call Signature

off(event, listener): this

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

Remove a listener for a lifecycle event.

Parameters

event

"committed"

The event name

listener

(args) => void

The callback function

Returns

this

this (for chaining)

Call Signature

off(event, listener): this

Defined in: libs/act/src/act.ts:88

Remove a listener for a lifecycle event.

Parameters

event

"drained"

The event name

listener

(args) => void

The callback function

Returns

this

this (for chaining)

---

on()

Call Signature

on(event, listener): this

Defined in: libs/act/src/act.ts:73

Register a listener for a lifecycle event ("committed" or "drained").

Parameters

event

"committed"

The event name

listener

(args) => void

The callback function

Returns

this

this (for chaining)

Call Signature

on(event, listener): this

Defined in: libs/act/src/act.ts:74

Register a listener for a lifecycle event ("committed" or "drained").

Parameters

event

"drained"

The event name

listener

(args) => void

The callback function

Returns

this

this (for chaining)

---

query()

query(query, callback?): Promise<{ count: number; first?: Committed<E, keyof E>; last?: Committed<E, keyof E>; }>

Defined in: libs/act/src/act.ts:170

Query the event store for events matching a filter.

Parameters

query

The query filter (e.g., by stream, event name, or time range)

after?

number = ...

backward?

boolean = ...

before?

number = ...

correlation?

string = ...

created_after?

Date = ...

created_before?

Date = ...

limit?

number = ...

names?

string[] = ...

stream?

string = ...

callback?

(event) => void

(Optional) Callback for each event found

Returns

Promise<{ count: number; first?: Committed<E, keyof E>; last?: Committed<E, keyof E>; }>

An object with the first and last event found, and the total count

Example

const { count } = await app.query({ stream: "counter1" }, (event) => console.log(event));