IAct

@rotorsoft/act-root

---

@rotorsoft/act-root / act/src / IAct

Interface: IAct<TEvents, TActions, TActor, TSchemaReg>

Defined in: libs/act/src/types/action.ts:1238

The reaction-scoped application surface — what reaction handlers receive as their third argument, and the minimal contract host integrations can depend on.

Example

Typing a reaction handler without importing the app

import type { IAct, InferActions, InferEvents } from "@rotorsoft/act";

type App = IAct<
  InferEvents<typeof StateA> & InferEvents<typeof StateB>,
  InferActions<typeof StateA> & InferActions<typeof StateB>
>;

async function myReaction(event: ..., stream: string, app: App) {
  await app.do("someAction", target, payload); // reactingTo is injected
  const snapshot = await app.load(MyState, "stream-1");
}

Type Parameters

TEvents

TEvents extends Schemas = Schemas

Event schemas

TActions

TActions extends Schemas = Schemas

Action schemas

TActor

TActor extends Actor = Actor

Actor type extending base Actor

TSchemaReg

TSchemaReg extends SchemaRegister<TActions> = SchemaRegister<TActions>

Map of action name → target state schema, threaded by Act so do returns snapshots typed to the action's state. The default collapses to Schema per action, so annotations written as IAct<TEvents, TActions> keep compiling unchanged.

Methods

do()

do<TKey>(action, target, payload, options?): Promise<Snapshot<TSchemaReg[TKey], TEvents>[]>

Defined in: libs/act/src/types/action.ts:1244

Type Parameters

TKey

TKey extends string

Parameters

action

TKey

target

Target<TActor>

payload

Readonly<TActions[TKey]>

options?

DoOptions<TEvents>

Returns

Promise<Snapshot<TSchemaReg[TKey], TEvents>[]>

---

forget()

forget(stream): Promise<{ eventCount: number; }>

Defined in: libs/act/src/types/action.ts:1316

Wipe the sensitive-data payload for every event on the stream. Delegates to the Store's forget_pii(stream), invalidates the cache entry for the stream, then emits the forgotten lifecycle event.

Throws when called if the configured Store does not implement forget_pii (its adapter declares pii_isolation: false or omits the method).

Idempotent: a second call on an already-wiped stream returns eventCount: 0 and does NOT re-emit forgotten.

Parameters

stream

string

Target stream to wipe.

Returns

Promise<{ eventCount: number; }>

Count of events whose PII column was set to NULL.

---

load()

Call Signature

load<S>(state, stream, callback?, asOf?): Promise<Snapshot<S, TEvents>>

Defined in: libs/act/src/types/action.ts:1267

Load a state snapshot for a stream. Two shapes:

Anonymous (bare stream) — load(state, stream, callback?, asOf?). The framework default-denies on every PII gate: sensitive event fields come back as [REDACTED], state fields whose names match sensitive event fields are also [REDACTED]. Use this when the caller has no authorization context (background workers, observability probes, etc.).

Auth-aware (LoadTarget) — load(state, {stream, actor, asOf?}, callback?). Symmetric with IAct.do(state, target, payload). The read runs the state's .discloses(predicate) against the supplied actor; sensitive fields come back as plaintext when the predicate returns true, [REDACTED] otherwise. Forgotten events return [SHREDDED] regardless of actor (data is gone, no auth question).

Type Parameters

S

S extends Schema

Parameters

state

State<S, any, any>

stream

string

callback?

(snapshot) => void

asOf?

AsOf

Returns

Promise<Snapshot<S, TEvents>>

Call Signature

load<S>(state, target, callback?): Promise<Snapshot<S, TEvents>>

Defined in: libs/act/src/types/action.ts:1273

Type Parameters

S

S extends Schema

Parameters

state

State<S, any, any>

target

LoadTarget<TActor>

callback?

(snapshot) => void

Returns

Promise<Snapshot<S, TEvents>>

Call Signature

load(state, stream, callback?, asOf?): Promise<Snapshot<Schema, TEvents>>

Defined in: libs/act/src/types/action.ts:1278

Parameters

state

string

stream

string

callback?

(snapshot) => void

asOf?

AsOf

Returns

Promise<Snapshot<Schema, TEvents>>

Call Signature

load(state, target, callback?): Promise<Snapshot<Schema, TEvents>>

Defined in: libs/act/src/types/action.ts:1284

Parameters

state

string

target

LoadTarget<TActor>

callback?

(snapshot) => void

Returns

Promise<Snapshot<Schema, TEvents>>

---

query()

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

Defined in: libs/act/src/types/action.ts:1290

Parameters

query

Query

callback?

(event) => void

Returns

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

---

query_array()

query_array(query): Promise<Committed<TEvents, keyof TEvents>[]>

Defined in: libs/act/src/types/action.ts:1299

Parameters

query

Query

Returns

Promise<Committed<TEvents, keyof TEvents>[]>