PersistentFSM

Defined in: src/fsm/PersistentFSM.ts:201

Classic-style event-sourced actor. Subclasses override onCommand (which decides what to persist), onEvent (pure state update from the event), and optionally onRecoveryComplete. Commands are automatically stashed while persist(...) is pending, so user code can assume the state is caught up by the time its callback fires.

class AccountActor extends PersistentActor<Cmd, Event, State> { readonly persistenceId = ‘account-42’; initialState(): State { return { balance: 0 }; } onEvent(state: State, e: Event): State { if (e.kind === ‘deposited’) return { balance: state.balance + e.amount }; return state; } onCommand(state: State, cmd: Cmd): void { if (cmd.kind === ‘deposit’) { this.persist({ kind: ‘deposited’, amount: cmd.amount }, (s) => { this.sender?.tell({ ok: s.balance }); }); } } }

Extends

PersistentActor<Cmd, Event, FsmStateData<SName, Data>>

Type Parameters

Cmd

Cmd extends object

Event

Event

SName

SName extends string

Data

Data

Constructors

Constructor

new PersistentFSM<Cmd, Event, SName, Data>(): PersistentFSM<Cmd, Event, SName, Data>

Returns

PersistentFSM<Cmd, Event, SName, Data>

Inherited from

PersistentActor.constructor

Properties

persistenceId

abstract readonly persistenceId: string

Defined in: src/persistence/PersistentActor.ts:59

Inherited from

PersistentActor.persistenceId

transitions

abstract transitions: FsmTransitionMap<SName, Cmd, Event, Data>

Defined in: src/fsm/PersistentFSM.ts:227

Transition table. Implementations typically declare it as a class field so the type-narrowing in FsmTransitionMap works at the call site (transitions[state][cmdKind]).

Methods

applyEvent()

abstract applyEvent(state, data, event): FsmStateData<SName, Data>

Defined in: src/fsm/PersistentFSM.ts:218

Pure event-application — updates both state name and data. Runs at persist-time (forward) AND at recovery-time (replay), so it MUST be deterministic and free of side effects.

Parameters

state

SName

data

Data

event

Event

Returns

FsmStateData<SName, Data>

compression()

compression(): CompressionConfig | undefined

Defined in: src/persistence/PersistentActor.ts:106

Per-actor compression — overrides the plugin default for THIS actor’s snapshots. Stores that don’t compress (in-memory, SQLite, Cassandra) ignore the value. Returning undefined (the default) defers to the plugin’s resolver / configured default.

Returns

CompressionConfig | undefined

Inherited from

PersistentActor.compression

encryption()

encryption(): EncryptionConfig | undefined

Defined in: src/persistence/PersistentActor.ts:114

Per-actor encryption — overrides the plugin default for THIS actor’s snapshots. Honoured by stores that encrypt at rest (object-storage); other stores ignore it. Used on both the write path (encrypt) and the read path (derive subkey from master to decrypt).

Returns

EncryptionConfig | undefined

Inherited from

PersistentActor.encryption

eventAdapter()

eventAdapter(): EventAdapter<Event, Event> | undefined

Defined in: src/persistence/PersistentActor.ts:90

Optional event adapter for schema evolution. When defined, every persisted event is wrapped into a { _v, _t, _e } envelope on the write path and unwrapped (with up-casting through the adapter) on the read path. Recovery is strict when an adapter is set: a raw, non-envelope event in the journal will throw MigrationError. See src/persistence/migration/.

Returns

EventAdapter<Event, Event> | undefined

Inherited from

PersistentActor.eventAdapter

initialData()

abstract initialData(): Data

Defined in: src/fsm/PersistentFSM.ts:211

Starting data when no events have been replayed.

Returns

Data

initialFsmState()

abstract initialFsmState(): SName

Defined in: src/fsm/PersistentFSM.ts:208

Starting state name when no events have been replayed.

Returns

SName

initialState()

initialState(): FsmStateData<SName, Data>

Defined in: src/fsm/PersistentFSM.ts:265

Default initial state when no snapshot and no events exist.

Returns

FsmStateData<SName, Data>

Overrides

PersistentActor.initialState

onCommand()

onCommand(curr, cmd): Promise<void>

Defined in: src/fsm/PersistentFSM.ts:300

Handle an incoming command — typically calls persist(event, cb).

Parameters

curr

FsmStateData<SName, Data>

cmd

Cmd

Returns

Promise<void>

Overrides

PersistentActor.onCommand

onEvent()

onEvent(curr, event): FsmStateData<SName, Data>

Defined in: src/fsm/PersistentFSM.ts:269

Pure state-update function — MUST be deterministic.

Parameters

curr

FsmStateData<SName, Data>

event

Event

Returns

FsmStateData<SName, Data>

Overrides

PersistentActor.onEvent

onReceive()

onReceive(message): Promise<void>

Defined in: src/fsm/PersistentFSM.ts:291

Intercept the internal __fsm_state_timeout__ self-tell that the armed timer routes through the mailbox. Real user commands delegate straight to super.onReceive (which handles recovery stash + persist gating + dispatch to onCommand).

Parameters

message

Cmd

Returns

Promise<void>

Overrides

PersistentActor.onReceive

onRecoveryComplete()

onRecoveryComplete(_state): void | Promise<void>

Defined in: src/fsm/PersistentFSM.ts:273

Called once recovery finishes, with the final replayed state.

Parameters

_state

FsmStateData<SName, Data>

Returns

void | Promise<void>

Overrides

PersistentActor.onRecoveryComplete

onRecoveryFailure()

onRecoveryFailure(reason): void

Defined in: src/persistence/PersistentActor.ts:74

Called when recovery itself throws. Default = propagate to supervision.

Parameters

reason

Error

Returns

void

Inherited from

PersistentActor.onRecoveryFailure

postRestart()

postRestart(_reason): void | Promise<void>

Defined in: src/Actor.ts:55

Called on the fresh instance after a restart. Default: call preStart().

Parameters

_reason

Error

Returns

void | Promise<void>

Inherited from

PersistentActor.postRestart

postStop()

postStop(): Promise<void>

Defined in: src/fsm/PersistentFSM.ts:281

Called after the actor has been terminated. Children are already stopped.

Returns

Promise<void>

Overrides

PersistentActor.postStop

preRestart()

preRestart(_reason, _message?): void | Promise<void>

Defined in: src/Actor.ts:50

Called before a restart, on the instance about to be thrown away. The default stops children and then calls postStop().

Parameters

_reason

Error

_message?

Cmd

Returns

void | Promise<void>

Inherited from

PersistentActor.preRestart

preStart()

preStart(): Promise<void>

Defined in: src/persistence/PersistentActor.ts:138

Called after construction and before the first message is processed.

Returns

Promise<void>

Inherited from

PersistentActor.preStart

snapshotAdapter()

snapshotAdapter(): SnapshotAdapter<FsmStateData<SName, Data>, FsmStateData<SName, Data>> | undefined

Defined in: src/persistence/PersistentActor.ts:98

Optional snapshot adapter — same semantics as eventAdapter, but applied to the state blob persisted by the snapshot store. When a snapshot adapter is set and a stored snapshot is not an envelope, recovery throws.